fix(platform-objects): drop the dead mapId param from register_sso_provider (#8222) (#8800)

The OIDC subject claim is not configurable in @better-auth/sso@1.7.0-rc.2:
oidcConfig.mapping is a z.strictObject with no `id` member, the subject is
hard-wired to the `sub` claim, and extraFields is spread before `id` so it is
not an escape hatch either. The form field's only accepted values were empty
and the `sub` it already defaulted to; anything else has answered
INVALID_REQUEST since #8221. Removing it restores declared = enforced.

Translation bundles regenerated via scripts/check-i18n-bundles.mjs --write,
not hand-edited. The plugin-auth bridge guard is kept as belt-and-braces for
non-form callers; only its doc comment changed.


Claude-Session: https://claude.ai/code/session_01XeQRiAa7vYRVX5Fog7Zby8

Co-authored-by: Claude <noreply@anthropic.com>

Author: hotlong

.changeset/sso-provider-map-id-param-retired.md

@@ -0,0 +1,58 @@
+---
+"@objectstack/platform-objects": patch
+"@objectstack/plugin-auth": patch
+---
+
+fix(platform-objects): drop the dead `mapId` ("Map: User ID claim") param from `register_sso_provider` — the OIDC subject claim is not configurable (#8222)
+
+<!-- adr-0087: not-required (no-migration-prescription) One action PARAM is
+removed from a UI action declaration, plus the generated i18n entries that
+carried its label/helpText. `params` are the form fields an `type: 'api'` action
+collects for its request body — not an authorable metadata property, not a field,
+not a stored column, so there is nothing to tombstone and no conversion to
+register. No stored `sys_sso_provider` row changes shape: the param was only ever
+a transient form input, and since #8193/#8221 the bridge has not forwarded it to
+better-auth at all. The runtime accept set does not move. -->
+
+The `register_sso_provider` action on `sys_sso_provider` offered an optional
+**"Map: User ID claim"** text field (`mapId`), with helpText reading *"Optional.
+ID-token claim mapped to the user ID. Defaults to `sub`."*
+
+**That capability no longer exists.** It was retired upstream in
+`@better-auth/sso@1.7.0-rc.2`:
+
+- `oidcConfig.mapping` is a `z.strictObject` whose members are
+  `{ email, emailVerified?, name, image?, extraFields? }` — there is no `id`;
+- the federated subject is hard-wired to the OIDC `sub` claim
+  (`id: readStringClaim(rawUserInfo, "sub")` and `id: idToken.sub`), then
+  cross-checked (`id_token_subject_missing`,
+  `id_token_userinfo_subject_mismatch`);
+- `extraFields` is not an escape hatch — it is spread **before** `id` in the
+  profile literal, so an `extraFields.id` is overwritten by `sub` before anything
+  reads it.
+
+`1.6.20` did honour `mapping.id` (`id: rawUserInfo[mapping.id || "sub"]`); the
+version bump deleted the member.
+
+So the field's only accepted values were "empty" and the `sub` it already
+defaulted to. #8193 (PR #8221) stopped the bridge emitting the retired key and —
+rather than accept a value it would silently discard — made a non-`sub` value
+answer `INVALID_REQUEST`. That left the last half of the problem: **the form
+still advertised a free-form optional field that 400s on anything meaningful.**
+Removing it restores declared = enforced. Nothing else about registration moves:
+the runtime accept set is unchanged, and a registration that never sent `mapId`
+behaves exactly as before.
+
+`mapEmail` and `mapName` are untouched — they map to live `oidcMappingSchema`
+members and are still honoured.
+
+**The bridge-side guard in `plugin-auth`'s `register-sso-provider.ts` is kept**,
+and its refusal test with it. The admin form was only one caller: a direct API
+client, a script, or a stale cached console bundle can still put `mapId` on the
+wire, and telling those callers plainly still beats discarding the value in
+silence. Only the guard's doc comment changed, to stop describing `mapId` as a
+field the form sends.
+
+The generated translation bundles (`*.objects.generated.ts`, all four locales)
+were **regenerated**, not hand-edited, so the retired label disappears from every
+locale rather than lingering as a stale entry.

packages/platform-objects/src/apps/translations/en.objects.generated.ts

@@ -1804,11 +1804,6 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
             helpText: "Optional. Space- or comma-separated OAuth scopes. Defaults to \"openid email profile\".",
             placeholder: "openid email profile"
           },
-          mapId: {
-            label: "Map: User ID claim",
-            helpText: "Optional. ID-token claim mapped to the user ID. Defaults to \"sub\".",
-            placeholder: "sub"
-          },
           mapEmail: {
             label: "Map: Email claim",
             helpText: "Optional. Claim mapped to email. Defaults to \"email\".",

packages/platform-objects/src/apps/translations/es-ES.objects.generated.ts

@@ -1804,11 +1804,6 @@ export const esESObjects: NonNullable<TranslationData['objects']> = {
             helpText: "Opcional. Ámbitos OAuth separados por espacios o comas. Valor predeterminado: «openid email profile».",
             placeholder: "openid email profile"
           },
-          mapId: {
-            label: "Mapeo: reclamo de ID de usuario",
-            helpText: "Opcional. Reclamo del token de ID asignado al ID de usuario. Valor predeterminado: «sub».",
-            placeholder: "sub"
-          },
           mapEmail: {
             label: "Mapeo: reclamo de correo",
             helpText: "Opcional. Reclamo asignado al correo. Valor predeterminado: «email».",

packages/platform-objects/src/apps/translations/ja-JP.objects.generated.ts

@@ -1804,11 +1804,6 @@ export const jaJPObjects: NonNullable<TranslationData['objects']> = {
             helpText: "任意。スペースまたはカンマ区切りの OAuth スコープ。既定値は「openid email profile」。",
             placeholder: "openid email profile"
           },
-          mapId: {
-            label: "マッピング: ユーザー ID クレーム",
-            helpText: "任意。ユーザー ID にマッピングする ID トークンのクレーム。既定値は「sub」。",
-            placeholder: "sub"
-          },
           mapEmail: {
             label: "マッピング: メールクレーム",
             helpText: "任意。メールにマッピングするクレーム。既定値は「email」。",

packages/platform-objects/src/apps/translations/zh-CN.objects.generated.ts

@@ -1804,11 +1804,6 @@ export const zhCNObjects: NonNullable<TranslationData['objects']> = {
             helpText: "可选。以空格或逗号分隔的 OAuth 授权范围（scopes）。默认为 “openid email profile”。",
             placeholder: "openid email profile"
           },
-          mapId: {
-            label: "映射：用户 ID claim",
-            helpText: "可选。映射到用户 ID 的 ID-token claim。默认为 “sub”。",
-            placeholder: "sub"
-          },
           mapEmail: {
             label: "映射：邮箱 claim",
             helpText: "可选。映射到邮箱的 claim。默认为 “email”。",

packages/platform-objects/src/identity/sys-sso-provider.object.ts

@@ -99,7 +99,16 @@ export const SysSsoProvider = ObjectSchema.create({
         { name: 'clientSecret', label: 'Client Secret', type: 'text', required: true, helpText: 'OAuth client secret (stored encrypted by better-auth).' },
         { name: 'discoveryEndpoint', label: 'Discovery URL', type: 'text', required: false, helpText: 'Optional. OIDC discovery document URL. Leave blank to derive `<issuer>/.well-known/openid-configuration`.' },
         { name: 'scopes', label: 'Scopes', type: 'text', required: false, placeholder: 'openid email profile', helpText: 'Optional. Space- or comma-separated OAuth scopes. Defaults to "openid email profile".' },
-        { name: 'mapId', label: 'Map: User ID claim', type: 'text', required: false, placeholder: 'sub', helpText: 'Optional. ID-token claim mapped to the user ID. Defaults to "sub".' },
+        // No "Map: User ID claim" param here on purpose. `@better-auth/sso@1.7.0-rc.2`
+        // retired the capability: `oidcConfig.mapping` is a `z.strictObject` with no
+        // `id` member, the federated subject is hard-wired to the OIDC `sub` claim
+        // (`id: readStringClaim(rawUserInfo, "sub")` / `id: idToken.sub`), and
+        // `extraFields` is spread BEFORE `id` in the profile literal, so it is not an
+        // escape hatch either. Offering the field made the form promise a choice the
+        // runtime does not have — its only accepted values were "empty" and the `sub`
+        // it already defaults to, and anything else answers 400 (see the guard in
+        // plugin-auth `register-sso-provider.ts`, which stays as belt-and-braces for
+        // non-form callers). Removing it restores declared = enforced.
         { name: 'mapEmail', label: 'Map: Email claim', type: 'text', required: false, placeholder: 'email', helpText: 'Optional. Claim mapped to email. Defaults to "email".' },
         { name: 'mapName', label: 'Map: Name claim', type: 'text', required: false, placeholder: 'name', helpText: 'Optional. Claim mapped to display name. Defaults to "name".' },
       ],

packages/platform-objects/src/identity/sys-sso-provider.subject-claim-not-authorable.test.ts

@@ -0,0 +1,104 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * #8222 — the OIDC subject claim is not authorable, so the form must not offer it.
+ *
+ * `register_sso_provider` used to collect a `mapId` ("Map: User ID claim") param.
+ * The capability behind it was retired UPSTREAM in `@better-auth/sso@1.7.0-rc.2`:
+ * `oidcConfig.mapping` is a `z.strictObject` whose members are
+ * `{ email, emailVerified?, name, image?, extraFields? }` — no `id` — and the
+ * federated subject is hard-wired to the OIDC `sub` claim
+ * (`id: readStringClaim(rawUserInfo, "sub")` / `id: idToken.sub`, then
+ * cross-checked). `extraFields` is not an escape hatch: it is spread BEFORE `id`
+ * in the profile literal, so an `extraFields.id` is overwritten by `sub` before
+ * anything reads it. 1.6.20 did honour `mapping.id`; the version bump deleted it.
+ *
+ * The field therefore promised a choice the runtime does not have: its only
+ * accepted values were "empty" and the `sub` it already defaulted to, and #8193
+ * (PR #8221) made anything else answer `INVALID_REQUEST` — a 400 from a field the
+ * UI presented as optional and free-form. Removing it restores declared = enforced.
+ *
+ * **What this file pins is the admin-visible affordance, in both directions.**
+ * The risk is not that the identifier `mapId` reappears somewhere — a grep sees
+ * that. It is (a) that the param comes back under some other spelling while every
+ * `mapId` grep stays green, and (b) that a future sweep over-applies and takes the
+ * mapping params that ARE still real down with it. `mapEmail` and `mapName` map to
+ * live `oidcMappingSchema` members and must survive.
+ *
+ * The bridge-side guard in plugin-auth `register-sso-provider.ts` is deliberately
+ * NOT removed and is NOT this file's subject: the form is only one caller, and a
+ * direct API client can still put `mapId` on the wire. Its refusal is pinned where
+ * it lives, in `register-sso-provider.test.ts`.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { SysSsoProvider } from './sys-sso-provider.object.js';
+import { enObjects } from '../apps/translations/en.objects.generated.js';
+import { zhCNObjects } from '../apps/translations/zh-CN.objects.generated.js';
+import { jaJPObjects } from '../apps/translations/ja-JP.objects.generated.js';
+import { esESObjects } from '../apps/translations/es-ES.objects.generated.js';
+
+const registerAction = (): any => {
+  const action = ((SysSsoProvider as any).actions ?? []).find(
+    (a: any) => a.name === 'register_sso_provider',
+  );
+  if (!action) throw new Error('sys_sso_provider declares no `register_sso_provider` action');
+  return action;
+};
+
+const paramNames = (): string[] => (registerAction().params ?? []).map((p: any) => p.name);
+
+describe('#8222 — `register_sso_provider` does not offer a user-ID claim mapping', () => {
+  it('declares no `mapId` param', () => {
+    expect(
+      paramNames(),
+      'the OIDC subject is read from `sub` and is not configurable in '
+        + '@better-auth/sso@1.7.0-rc.2 — offering the field makes the form promise '
+        + 'a choice the runtime does not have',
+    ).not.toContain('mapId');
+  });
+
+  it('offers no param that collects a user-ID / subject claim under ANY spelling', () => {
+    // The half a `mapId` grep cannot see: the same false promise re-added as
+    // `subjectClaim`, `idClaim`, `mapSubject`, … Judge the admin-facing copy,
+    // not the identifier.
+    const offenders = (registerAction().params ?? []).filter((p: any) => {
+      const copy = `${p.name ?? ''} ${p.label ?? ''} ${p.helpText ?? ''}`.toLowerCase();
+      const namesSubject = /\bsub\b|subject|user id|userid|user-id/.test(copy);
+      // `mapEmail`/`mapName` mention neither; the scopes param mentions neither.
+      return namesSubject;
+    });
+    expect(
+      offenders.map((p: any) => p.name),
+      'these params collect the federated subject claim, which is hard-wired to '
+        + '`sub` upstream — the value would be refused (INVALID_REQUEST) or silently discarded',
+    ).toEqual([]);
+  });
+
+  it('keeps the claim mappings that ARE still honoured — the over-removal guard', () => {
+    // `oidcMappingSchema` still carries `email` (required) and `name` (required),
+    // and the bridge emits both. A sweep that took these out with `mapId` would
+    // remove real capability, and no `mapId` assertion above would notice.
+    const names = paramNames();
+    expect(names).toContain('mapEmail');
+    expect(names).toContain('mapName');
+  });
+
+  it('ships no translated label for the retired param in any locale', () => {
+    // What the admin actually reads. A stale bundle entry would keep rendering
+    // "Map: User ID claim" for a param the action no longer declares.
+    for (const [locale, bundle] of [
+      ['en', enObjects],
+      ['zh-CN', zhCNObjects],
+      ['ja-JP', jaJPObjects],
+      ['es-ES', esESObjects],
+    ] as const) {
+      const params: Record<string, unknown> =
+        (bundle as any)?.sys_sso_provider?._actions?.register_sso_provider?.params ?? {};
+      expect(Object.keys(params), `${locale} bundle still translates the retired param`).not.toContain('mapId');
+      // Counter-probe: the surviving params ARE translated in this bundle, so an
+      // empty/misshaped lookup path cannot make the assertion above pass vacuously.
+      expect(Object.keys(params), `${locale} bundle lookup path is wrong — it resolved nothing`).toContain('mapEmail');
+    }
+  });
+});

packages/plugins/plugin-auth/src/register-sso-provider.ts

@@ -77,9 +77,14 @@ async function resolveActiveOrganizationId(
  * @param request the raw Web `Request` — its headers carry the caller's session
  *                cookie / bearer + Origin; its body carries the flat form
  *                fields ({ providerId, issuer, domain, clientId, clientSecret,
- *                discoveryEndpoint?, scopes?, mapId?, mapEmail?, mapName? }).
- *                `mapId` is accepted only as the (empty or `sub`) no-op it now
- *                is — see the mapping block below.
+ *                discoveryEndpoint?, scopes?, mapEmail?, mapName? }).
+ *                `mapId` is NOT among them any more: #8222 removed it from the
+ *                `register_sso_provider` action, so the admin form no longer
+ *                offers a user-ID claim mapping. The guard below is kept as
+ *                belt-and-braces for the callers the form does not cover — a
+ *                direct API client, a script, a stale cached console bundle —
+ *                which can still put `mapId` on the wire. It is accepted only as
+ *                the (empty or `sub`) no-op it now is; see the mapping block.
  */
 export async function runRegisterSsoProviderFromForm(
   handle: AuthRequestHandler,