feat(plugin-auth): a JIT sign-in reads the IdP locale claim into the user language preference

.changeset/25261-jit-idp-locale-claim.md

@@ -0,0 +1,17 @@
+---
+'@objectstack/plugin-auth': patch
+---
+
+feat(plugin-auth): a JIT sign-in reads the IdP `locale` claim into the user's language preference, so a hosted environment follows the cloud account language
+
+Clause-②: no
+Metadata-protocol: none
+
+When an external IdP sign-in creates or refreshes a user just-in-time (the cloud as IdP on a hosted environment through `oidcProviders`, any generic-OAuth or social provider, or a `@better-auth/sso` OIDC provider), the standard OIDC `locale` claim now becomes `sys_user.locale`, the column the console reads as the signed-in user's language and messaging reads per recipient.
+
+- **First creation:** the claim sets the preference.
+- **A later sign-in:** the claim updates it only while the user has not picked a language in the environment itself. A local choice wins and is never overwritten; clearing it hands the column back to the IdP.
+- **An unknown or unsupported claim:** nothing is stored (an IdP-written value is cleared), so the deployment default applies. The claim is closed against the locales the i18n service reports (`i18n.supportedLocales` when the app declares them), matched exact, then case-insensitive, then by base language (`en-US` → `en`, `ja` → `ja-JP`), and the supported spelling is stored. The underscore spelling (`zh_CN`) reads as the tag it stands for.
+- **No claim:** nothing changes.
+
+What the IdP last wrote is recorded per user in `sys_verification` (identifier `idp-locale:` plus the user id), so an IdP-written value can be told apart from a local choice; no schema changes. Applying the claim never fails a sign-in: a store that refuses the write is reported at `warn` and the user keeps the language they had.

content/docs/permissions/tenant-audit-census.mdx

@@ -132,7 +132,7 @@ are reported as `undecidable` rather than assumed either way.
 
 The same holds twice over for the context. An options argument spelled as a
 literal can be read; one spelled `options`, `{ ...opts }`, or handed through a
-forwarding shim cannot, and **51 of the 236 sites are spelled that way**. A
+forwarding shim cannot, and **51 of the 237 sites are spelled that way**. A
 context resolved from an inline literal or a local `const` can be tested for
 `isSystem`; one arriving from a helper call cannot.
 
@@ -197,10 +197,10 @@ reproduce them. Where it disagrees, it disagrees on the page:
 
 | carried figure | where it survives | this census |
 | :--- | :--- | ---: |
-| 175 write call sites | quoted in the merged changeset | **236** |
+| 175 write call sites | quoted in the merged changeset | **237** |
 | 24 carrying no tenant context | quoted in the merged changeset | **2** provable and tenancy-enabled; **29** more whose options argument is unreadable |
-| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **160 of 236** decidable, **76** undecidable |
-| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 134 decidably elevated, 0 decidably not, 94 undecidable |
+| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **161 of 237** decidable, **76** undecidable |
+| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 135 decidably elevated, 0 decidably not, 94 undecidable |
 | 141 and 132, two independent re-derivations | the card that filed this work | — |
 
 **The differences are not reconciled, and deliberately so.** The old census's
@@ -217,11 +217,11 @@ would report a smaller number and would not say so.
 
 The fourth row is the one worth flagging to anyone citing it. **The 135 / 77%
 figure has no surviving corroboration anywhere in the tree.** This census reads
-134 of 236 (57%) as decidably elevated, with 94 more whose elevation is a
+135 of 237 (57%) as decidably elevated, with 94 more whose elevation is a
 run-time fact — so the claim is neither confirmed nor refuted, and the honest
 answer is that a static reading cannot settle it.
 
-⇒ **Cite `2 / 236`, and say what it is**: the sites whose options argument was
+⇒ **Cite `2 / 237`, and say what it is**: the sites whose options argument was
 READ and holds no tenant context, against a decidably tenancy-enabled object.
 That is the control's provable yield surface. ⛔ Do not cite it as "the sites
 without tenant context" — **29 further sites** have an options argument this
@@ -233,28 +233,28 @@ cannot read, and they are neither in nor out.
 
 | what | count |
 | :--- | ---: |
-| write call sites on the application surface | **236** |
-| …whose object name is statically decidable | 160 |
+| write call sites on the application surface | **237** |
+| …whose object name is statically decidable | 161 |
 | …whose object name is chosen at run time | 76 |
-| …against an object with tenancy ENABLED | 159 |
+| …against an object with tenancy ENABLED | 160 |
 | …against an object that declares tenancy off | 1 |
-| threading a tenant context | 177 |
+| threading a tenant context | 178 |
 | PROVABLY carrying none (options read, no context key) | **8** |
 | …of those, against a decidably tenancy-enabled object | **2** |
 | options argument UNREADABLE — may or may not carry one | 51 |
 | …of those, against a decidably tenancy-enabled object | 29 |
-| threading a decidably ELEVATED (`isSystem`) context | 134 |
+| threading a decidably ELEVATED (`isSystem`) context | 135 |
 | threading a context that is decidably NOT elevated | 0 |
 | threading a context whose elevation is a run-time fact | 94 |
 
 | how the instrument reached the site | count |
 | :--- | ---: |
-| receiver carried a readable engine type | 195 |
+| receiver carried a readable engine type | 196 |
 | receiver erased, placed by the object NAME | 31 |
 | receiver erased, placed by an `object: string` PARAMETER | 5 |
 | receiver erased, placed by an `UNTYPED_RECEIVERS` row | 5 |
 
-| object name spelled inline | 109 |
+| object name spelled inline | 110 |
 | object name spelled through a `const` | 51 |
 | object name is an `object: string` parameter | 7 |
 | object name is some other run-time expression | 69 |
@@ -307,13 +307,13 @@ holds still. They are required to be HERE and to say WHEN they were true;
 their values are not compared. The reasoning, and the measurement behind it,
 are in `scripts/check-tenant-audit-census.mjs`.
 
-Measured on 2026-10-22 at `78b1ed16a`.
+Measured on 2026-10-22 at `4d4e2390c`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 700 |
-| engine-shaped types recognised | 86 |
+| tracked non-test sources scanned | 706 |
+| engine-shaped types recognised | 87 |
 | declared objects in the registry | 117 |
-| same-named calls subtracted as non-engine | 169 |
+| same-named calls subtracted as non-engine | 171 |
 
 {/* END GENERATED: tenant-audit-census */}

docs/audits/2026-08-tenant-audit-write-call-sites.counts.md

@@ -33,17 +33,17 @@ silent, and `node scripts/tenant-audit-census.mjs --write` is the resolution.
 
 | Measure | Value |
 |---|---:|
-| Write call sites | 236 |
-| Object name statically decidable | 160 |
+| Write call sites | 237 |
+| Object name statically decidable | 161 |
 | Object name chosen at run time | 76 |
-| Against a tenancy-enabled object | 159 |
+| Against a tenancy-enabled object | 160 |
 | Against an object declaring tenancy off | 1 |
-| Threading a tenant context | 177 |
+| Threading a tenant context | 178 |
 | Provably carrying none | 8 |
 | …and decidably tenancy-enabled | 2 |
 | Options argument unreadable | 51 |
 | …and decidably tenancy-enabled | 29 |
-| Threading a decidably elevated context | 134 |
+| Threading a decidably elevated context | 135 |
 | Threading a decidably non-elevated context | 0 |
 | Threading a context of undecidable elevation | 94 |
 
@@ -90,14 +90,14 @@ holds still. They are required to be HERE and to say WHEN they were true;
 their values are not compared. The reasoning, and the measurement behind it,
 are in `scripts/check-tenant-audit-census.mjs`.
 
-Measured on 2026-10-22 at `78b1ed16a`.
+Measured on 2026-10-22 at `4d4e2390c`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 700 |
-| engine-shaped types recognised | 86 |
+| tracked non-test sources scanned | 706 |
+| engine-shaped types recognised | 87 |
 | declared objects in the registry | 117 |
-| same-named calls subtracted as non-engine | 169 |
+| same-named calls subtracted as non-engine | 171 |
 
 ## Every site
 
@@ -145,6 +145,7 @@ Measured on 2026-10-22 at `78b1ed16a`.
 | `packages/plugins/plugin-auth/src/ensure-default-organization.ts` | `update` | `sys_member` | enabled | elevated | 1 |
 | `packages/plugins/plugin-auth/src/forced-reset-revocation.ts` | `update` | `SystemObjectName.API_KEY` | undecidable | elevated | 1 |
 | `packages/plugins/plugin-auth/src/forced-reset-revocation.ts` | `update` | `SystemObjectName.SESSION` | undecidable | elevated | 1 |
+| `packages/plugins/plugin-auth/src/idp-locale-claim.ts` | `update` | `sys_user` | enabled | elevated | 1 |
 | `packages/plugins/plugin-auth/src/member-role-canonical.ts` | `update` | `MEMBER_OBJECT` | undecidable | elevated | 1 |
 | `packages/plugins/plugin-auth/src/membership-backfill-ledger.ts` | `insert` | `DATA_MIGRATION_FLAG_OBJECT` | undecidable | elevated | 1 |
 | `packages/plugins/plugin-auth/src/membership-ended-session.ts` | `update` | `SystemObjectName.SESSION` | undecidable | elevated | 2 |

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -39,6 +39,7 @@ import {
   type LinkingAuthContext,
   refuseImplicitAccountLink,
 } from './implicit-account-linking.js';
+import { IdpLocaleSync } from './idp-locale-claim.js';
 import type { IDataEngine } from '@objectstack/core';
 import {
   API_KEY_DEFAULT_EXPIRY_DAYS,
@@ -1885,12 +1886,18 @@ export class AuthManager {
         // implicit link is written — see `implicit-account-linking.ts`. The
         // audience gate judges only `create-user`, so the two never answer
         // the same call.
-        validateUserInfo: async (data: any, ctx: any) =>
-          (await refuseImplicitAccountLink(data, ctx, {
+        //
+        // It is also where better-auth hands over the IdP's raw profile, so
+        // the profile's `locale` claim is STAGED here, refusing nothing; the
+        // session the sign-in mints settles it (`idp-locale-claim.ts`).
+        validateUserInfo: async (data: any, ctx: any) => {
+          this.idpLocale.stage(data, ctx);
+          return (await refuseImplicitAccountLink(data, ctx, {
             requireLocalEmailVerified: this.implicitLinkRequiresLocalEmailVerified(),
             resolveContext: () => this.linkingContext(),
             logInfo: (m, meta) => this.config.logger?.info?.(m, meta),
-          })) ?? this.validateAudienceAdmission(data, ctx),
+          })) ?? this.validateAudienceAdmission(data, ctx);
+        },
       },
       account: {
         ...AUTH_ACCOUNT_CONFIG,
@@ -5050,6 +5057,25 @@ export class AuthManager {
     }
   }
 
+  /**
+   * An external sign-in's `locale` claim → `sys_user.locale`, staged by the
+   * `validateUserInfo` seam and settled on the session the sign-in mints.
+   * The rule and its record: `idp-locale-claim.ts`.
+   */
+  private readonly idpLocale = new IdpLocaleSync({
+    getEngine: () => this.getDataEngine() as never,
+    getSupportedLocales: () => {
+      try {
+        const locales = this.config.getI18n?.()?.getLocales?.();
+        return Array.isArray(locales) ? locales : undefined;
+      } catch {
+        return undefined;
+      }
+    },
+    resolveAuth: () => this.linkingContext(),
+    warn: (message, meta) => this.config.logger?.warn?.(message, meta),
+  });
+
   /**
    * [ADR-0093 D7] The users created in each in-flight better-auth request,
    * keyed by that request's endpoint context — the object better-auth hands
@@ -8448,6 +8474,7 @@ export class AuthManager {
     const userDeleteAfter = async (user: any, ctx: any) => {
       const result = hostUserDeleteAfter ? await hostUserDeleteAfter(user, ctx) : undefined;
       await clearUserUnlinks(user, ctx);
+      await this.idpLocale.forget(user, ctx);
       return result;
     };
 
@@ -8589,6 +8616,9 @@ export class AuthManager {
         this.config.getAuditSink?.(),
         loginEventFor(session, typeof ctx?.path === 'string' ? ctx.path : undefined),
       );
+      // An external sign-in's staged `locale` claim lands on the user the
+      // session names, new or returning (`idp-locale-claim.ts`). Never throws.
+      await this.idpLocale.settle(session, ctx);
       return result;
     };
     // [#23772] A minted principal session is NEVER renewed. better-auth's