@@ -0,0 +1,16 @@
+---
+'@objectstack/plugin-auth': minor
+'@objectstack/platform-objects': patch
+---
+
+feat(plugin-auth): an OAuth consent binds the consenting user's active organization, the access token carries it as `organization_id`, and `verifyMcpAccessToken` returns it as `organizationId`
+
+Clause-②: yes (widening)
+
+- **What changed.** When a user consents to an OAuth client, the embedded authorization server records the consenting session's active organization as the consent's `reference_id`. The value rides the authorization code onto the refresh family it starts (`sys_oauth_refresh_token.reference_id`), and every access token minted from either carries it as the `organization_id` claim. It is written through the installed `@better-auth/oauth-provider`'s own seams (`postLogin.consentReferenceId` and `customAccessTokenClaims`); no new configuration key or environment variable.
+- **The session's organization, never the request's.** The value is read from the consenting session only. Nothing in the authorize request, the consent body or the client's registration can choose it.
+- **No organization, no claim.** A user with no active organization at consent gets a consent with no reference, and tokens with no `organization_id`. There is no guessed or default organization; such a token's principal resolves with global grants only.
+- **A refresh keeps the consent's organization.** A refresh token mints access tokens in the organization its consent bound, even after the user switches the browser session to another organization. Authorizing again while another organization is active asks for a second consent, for that organization.
+- **Existing consents re-confirm once.** A consent stored before this change has no reference, so the next authorization made while the user has an active organization shows the consent page again, once. Until the user re-confirms, a refresh family started before this change keeps minting tokens with no `organization_id`, so they carry global grants only.
+- **`AuthManager.verifyMcpAccessToken`.** Its result type gains `organizationId?: string`, matching `IAuthService.verifyMcpAccessToken` in `@objectstack/spec/contracts`, and it returns the token's `organization_id` claim there. A token whose `organization_id` is present but is not a non-empty string is refused, as every other malformed token is: this server never mints one. The organization is a record, not an authorization. The caller vets it on every request by the rule that vets a session's active organization (`vetOrganizationClaim`, `@objectstack/core`).
+- **`@objectstack/platform-objects`.** The `reference_id` field description on `sys_oauth_consent`, `sys_oauth_refresh_token` and `sys_oauth_access_token` now names the bound organization, instead of "Caller-supplied correlation identifier". Prose only; no field, type or schema change.
@@ -1587,7 +1587,7 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
       },
       reference_id: {
         label: "Reference ID",
-        help: "Caller-supplied correlation identifier"
+        help: "Organization bound by the consent this token was issued under; empty when none was bound"
       },
       authorization_code_id: {
         label: "Authorization Code ID",
@@ -1647,7 +1647,7 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
       },
       reference_id: {
         label: "Reference ID",
-        help: "Caller-supplied correlation identifier"
+        help: "Organization bound by the consent that started this refresh family; empty when none was bound"
       },
       authorization_code_id: {
         label: "Authorization Code ID",
@@ -1715,7 +1715,7 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
       },
       reference_id: {
         label: "Reference ID",
-        help: "Caller-supplied correlation identifier"
+        help: "Organization this consent binds: the consenting user's active organization at consent; empty when none was active"
       },
       resources: {
         label: "Resources",
 
@@ -1587,7 +1587,7 @@ export const esESObjects: NonNullable<TranslationData['objects']> = {
       },
       reference_id: {
         label: "ID de referencia",
-        help: "Identificador de correlación proporcionado por quien llama."
+        help: "Organización vinculada por el consentimiento con el que se emitió este token; vacío si no se vinculó ninguna."
       },
       authorization_code_id: {
         label: "ID del código de autorización",
@@ -1647,7 +1647,7 @@ export const esESObjects: NonNullable<TranslationData['objects']> = {
       },
       reference_id: {
         label: "ID de referencia",
-        help: "Identificador de correlación proporcionado por quien llama."
+        help: "Organización vinculada por el consentimiento que inició esta familia de tokens de actualización; vacío si no se vinculó ninguna."
       },
       authorization_code_id: {
         label: "ID del código de autorización",
@@ -1715,7 +1715,7 @@ export const esESObjects: NonNullable<TranslationData['objects']> = {
       },
       reference_id: {
         label: "ID de referencia",
-        help: "Identificador de correlación proporcionado por quien llama."
+        help: "Organización que vincula este consentimiento: la organización activa del usuario al consentir; vacío si no había ninguna."
       },
       resources: {
         label: "Recursos",
 
@@ -1587,7 +1587,7 @@ export const jaJPObjects: NonNullable<TranslationData['objects']> = {
       },
       reference_id: {
         label: "参照 ID",
-        help: "呼び出し元が指定した相関識別子"
+        help: "このトークンの発行根拠となった同意が紐づけた組織。紐づけがない場合は空"
       },
       authorization_code_id: {
         label: "認可コード ID",
@@ -1647,7 +1647,7 @@ export const jaJPObjects: NonNullable<TranslationData['objects']> = {
       },
       reference_id: {
         label: "参照 ID",
-        help: "呼び出し元が指定した相関識別子"
+        help: "このリフレッシュトークン系列を開始した同意が紐づけた組織。紐づけがない場合は空"
       },
       authorization_code_id: {
         label: "認可コード ID",
@@ -1715,7 +1715,7 @@ export const jaJPObjects: NonNullable<TranslationData['objects']> = {
       },
       reference_id: {
         label: "参照 ID",
-        help: "呼び出し元が指定した相関識別子"
+        help: "この同意が紐づける組織。同意時のユーザーのアクティブな組織で、アクティブな組織がなかった場合は空"
       },
       resources: {
         label: "リソース",
 
@@ -1587,7 +1587,7 @@ export const zhCNObjects: NonNullable<TranslationData['objects']> = {
       },
       reference_id: {
         label: "引用 ID",
-        help: "调用方提供的关联标识符"
+        help: "签发该令牌所依据的同意所绑定的组织；未绑定组织时为空"
       },
       authorization_code_id: {
         label: "授权码 ID",
@@ -1647,7 +1647,7 @@ export const zhCNObjects: NonNullable<TranslationData['objects']> = {
       },
       reference_id: {
         label: "引用 ID",
-        help: "调用方提供的关联标识符"
+        help: "开启该刷新令牌族的同意所绑定的组织；未绑定组织时为空"
       },
       authorization_code_id: {
         label: "授权码 ID",
@@ -1715,7 +1715,7 @@ export const zhCNObjects: NonNullable<TranslationData['objects']> = {
       },
       reference_id: {
         label: "引用 ID",
-        help: "调用方提供的关联标识符"
+        help: "该同意绑定的组织：同意时用户的当前活动组织；同意时无活动组织则为空"
       },
       resources: {
         label: "资源",
 
@@ -94,7 +94,7 @@ export const SysOauthAccessToken = ObjectSchema.create({
       label: 'Reference ID',
       required: false,
       maxLength: 255,
-      description: 'Caller-supplied correlation identifier',
+      description: 'Organization bound by the consent this token was issued under; empty when none was bound',
     }),
 
     authorization_code_id: Field.text({
 
@@ -63,7 +63,8 @@ export const SysOauthConsent = ObjectSchema.create({
       label: 'Reference ID',
       required: false,
       maxLength: 255,
-      description: 'Caller-supplied correlation identifier',
+      description:
+        "Organization this consent binds: the consenting user's active organization at consent; empty when none was active",
     }),
 
     resources: Field.textarea({
 
@@ -87,7 +87,7 @@ export const SysOauthRefreshToken = ObjectSchema.create({
       label: 'Reference ID',
       required: false,
       maxLength: 255,
-      description: 'Caller-supplied correlation identifier',
+      description: 'Organization bound by the consent that started this refresh family; empty when none was bound',
     }),
 
     authorization_code_id: Field.text({
 
@@ -443,6 +443,42 @@ describe('verifyMcpAccessToken (local JWKS verification, fail-closed)', () => {
     });
   });
 
+  // ── the bound organization, by CLAIM SHAPE (#24166) ─────────────────────
+  // What the real authorization server mints, and from where, is pinned in
+  // auth-manager.oauth-consent-organization.test.ts against a running server.
+  // These pin how the verifier READS the claim, including shapes that server
+  // never mints.
+
+  it('returns the `organization_id` claim as `organizationId`', async () => {
+    const token = await signToken({ sub: 'user-1', client_id: 'client-abc', organization_id: 'org-a' });
+    expect(await manager().verifyMcpAccessToken(token)).toEqual({
+      userId: 'user-1',
+      scopes: ['data:read', 'data:write'],
+      clientId: 'client-abc',
+      organizationId: 'org-a',
+    });
+  });
+
+  it('a token with no `organization_id` claim resolves with no `organizationId` member at all', async () => {
+    const res = await manager().verifyMcpAccessToken(await signToken());
+    expect(res).not.toBeNull();
+    expect(Object.keys(res!)).not.toContain('organizationId');
+  });
+
+  it('refuses a token whose `organization_id` is present but is not a non-empty string', async () => {
+    // Not read as "no organization": a claim this server never mints is doubt,
+    // and the method is fail-closed on doubt. The string case beside it is the
+    // control, so a method that refuses everything cannot satisfy this.
+    for (const organization_id of [42, '', ['org-a'], { id: 'org-a' }, null]) {
+      const token = await signToken({ organization_id });
+      expect(
+        await manager().verifyMcpAccessToken(token),
+        `organization_id ${JSON.stringify(organization_id)} must be refused`,
+      ).toBeNull();
+    }
+    expect(await manager().verifyMcpAccessToken(await signToken({ organization_id: 'org-a' }))).not.toBeNull();
+  });
+
   it('rejects garbage / non-JWT input without touching the JWKS', async () => {
     const m = manager();
     expect(await m.verifyMcpAccessToken('')).toBeNull();