@tumbaland/backend-core 1.37.0 → 1.38.0

package/src/apiKeys/middleware.ts

@@ -6,7 +6,15 @@ import { isAccessTokenClaims, type AccessTokenClaims } from '../oauth/tokens';
 import type { UserPayload } from '../types/auth';
 import { looksLikeApiKey } from './crypto';
 import { verifyApiKey } from './service';
-import { isApiKeyScope, type ApiKeyScope } from './types';
+import {
+  PERSONAL_TENANT,
+  groupIdsOf,
+  isApiKeyScope,
+  readTenants,
+  type ApiKeyScope,
+  type ApiKeyTenant,
+  type Tenant
+} from './types';
 
 /**
  * Request-scoped facts about the key a request arrived on. Absent on ordinary
@@ -16,8 +24,10 @@ import { isApiKeyScope, type ApiKeyScope } from './types';
 export interface ApiKeyContext {
   keyId: string;
   scopes: ApiKeyScope[];
-  /** the tenant this key is pinned to; null means the owner's personal data */
-  groupId: string | null;
+  /** every tenant this credential may act in, and the one it acts in by default */
+  tenants: ApiKeyTenant;
+  /** the tenant this particular request resolved to */
+  actingAs: Tenant;
 }
 
 declare global {
@@ -40,10 +50,12 @@ const unauthorized = (res: Response): void => {
  * The tenant a request is asking to act in, wherever it named one.
  *
  * Handlers read `groupId` from either the query string or the body depending on
- * the verb, so both are checked — a pin that only covered one of them would be
- * no pin at all.
+ * the verb, so both are checked — a rule that only covered one of them would be
+ * no rule at all. A caller names the personal tenant with the literal
+ * `personal`, since "no group" is what the resolved default gets written into
+ * and would otherwise be indistinguishable from not having asked.
  */
-const requestedGroupId = (req: Request): string | undefined => {
+const requestedTenant = (req: Request): Tenant | undefined => {
   const fromQuery = req.query?.groupId;
   if (typeof fromQuery === 'string' && fromQuery.length > 0) return fromQuery;
 
@@ -53,35 +65,50 @@ const requestedGroupId = (req: Request): string | undefined => {
   return undefined;
 };
 
+/** Express 5 makes `req.query` a getter, so it is redefined rather than assigned. */
+const setQueryGroupId = (req: Request, groupId: string | undefined): void => {
+  const query = { ...req.query } as Record<string, unknown>;
+  if (groupId === undefined) delete query.groupId;
+  else query.groupId = groupId;
+
+  Object.defineProperty(req, 'query', {
+    value: query,
+    writable: true,
+    configurable: true,
+    enumerable: true
+  });
+};
+
 /**
- * Hold a key to the tenant it was issued for.
+ * Hold a credential to the tenants it was granted, and settle which one this
+ * request is acting in.
+ *
+ * A request naming a tenant outside the grant is refused outright — that
+ * boundary is the whole reason a credential is safe to hand to an agent, and it
+ * is unchanged by the grant being a set rather than one. What the set adds is a
+ * choice *inside* it, which is what lets one connection reach a shared journal
+ * and a private photo library without reconnecting.
  *
- * Two things happen here, and the second is the one that makes keys pleasant to
- * use. A request that names a *different* tenant is refused outright — the pin
- * is the whole reason a key is safe to hand to an agent. A request that names
- * none has the pinned tenant written in for it, so the agent never has to know a
- * group id exists, and a handler's `if (groupId) ... else personal` branch lands
- * where the key's owner intended.
+ * A request that names nothing gets the default written in for it, so an agent
+ * granted a single tenant never has to know a group id exists and a handler's
+ * `if (groupId) … else personal` branch lands where the owner intended.
  */
-const applyTenantPin = (req: Request, groupId: string | null): boolean => {
-  const requested = requestedGroupId(req);
+const applyTenantGrant = (req: Request, tenants: ApiKeyTenant): Tenant | null => {
+  const requested = requestedTenant(req) ?? tenants.default;
 
-  if (requested !== undefined && requested !== groupId) return false;
+  if (!tenants.allowed.includes(requested)) return null;
 
-  if (groupId !== null && requested === undefined) {
-    // Express 5 makes req.query a getter, so it is redefined rather than assigned.
-    Object.defineProperty(req, 'query', {
-      value: { ...req.query, groupId },
-      writable: true,
-      configurable: true,
-      enumerable: true
-    });
-    if (req.body && typeof req.body === 'object') {
-      (req.body as Record<string, unknown>).groupId = groupId;
-    }
+  // Resolved either way, including when the caller asked for exactly what the
+  // default already was: handlers read the personal tenant as an absent
+  // `groupId`, so `personal` has to be erased rather than passed through.
+  const groupId = requested === PERSONAL_TENANT ? undefined : requested;
+  setQueryGroupId(req, groupId);
+  if (req.body && typeof req.body === 'object') {
+    if (groupId === undefined) delete (req.body as Record<string, unknown>).groupId;
+    else (req.body as Record<string, unknown>).groupId = groupId;
   }
 
-  return true;
+  return requested;
 };
 
 /** A verified non-session credential, whichever kind it arrived as. */
@@ -92,7 +119,7 @@ interface AgentCredential {
   email: string;
   name: string;
   scopes: ApiKeyScope[];
-  groupId: string | null;
+  tenants: ApiKeyTenant;
 }
 
 /**
@@ -120,7 +147,8 @@ function admitAgent(
     return;
   }
 
-  if (!applyTenantPin(req, credential.groupId)) {
+  const actingAs = applyTenantGrant(req, credential.tenants);
+  if (actingAs === null) {
     res.status(403).json({
       success: false,
       message: 'Credential is not permitted to act in the requested group'
@@ -129,11 +157,16 @@ function admitAgent(
   }
 
   req.user = { id: credential.userId, email: credential.email, name: credential.name };
-  // Only the pinned group, never the owner's full membership: this is what
+  // Only the granted groups, never the owner's full membership: this is what
   // stops a credential reaching a group it was not issued for through any
   // handler that consults `userGroups` instead of the `groupId` parameter.
-  req.userGroups = credential.groupId ? [credential.groupId] : [];
-  req.apiKey = { keyId: credential.credentialId, scopes: credential.scopes, groupId: credential.groupId };
+  req.userGroups = groupIdsOf(credential.tenants.allowed);
+  req.apiKey = {
+    keyId: credential.credentialId,
+    scopes: credential.scopes,
+    tenants: credential.tenants,
+    actingAs
+  };
 
   next();
 }
@@ -191,7 +224,7 @@ export const authenticateAgent = (...requiredScopes: ApiKeyScope[]): RequestHand
         email: claims.email ?? '',
         name: claims.name ?? '',
         scopes: (claims.scope ?? '').split(' ').filter(isApiKeyScope),
-        groupId: claims.groupId ?? null
+        tenants: readTenants(claims)
       });
       return;
     }
@@ -211,7 +244,7 @@ export const authenticateAgent = (...requiredScopes: ApiKeyScope[]): RequestHand
       email: result.userEmail ?? '',
       name: result.userName ?? '',
       scopes: result.scopes ?? [],
-      groupId: result.groupId ?? null
+      tenants: result.tenants ?? readTenants({})
     });
   };
 

package/src/apiKeys/service.test.ts

@@ -11,6 +11,7 @@ jest.mock('./ApiKey', () => ({
 }));
 
 import { ApiKey } from './ApiKey';
+import { PERSONAL_TENANT } from './types';
 import {
   createApiKey,
   listApiKeys,
@@ -43,7 +44,8 @@ function storedKey(over: Record<string, unknown> = {}) {
     sealedIv: 'iv',
     sealedTag: 'tag',
     scopes: ['relationship:read'],
-    groupId: null,
+    tenants: [PERSONAL_TENANT],
+    defaultTenant: PERSONAL_TENANT,
     revealCount: 0,
     lastRevealedAt: undefined as Date | undefined,
     createdAt: CREATED_AT,
@@ -98,14 +100,30 @@ describe('createApiKey', () => {
     expect(stored.sealedTag).toBeTruthy();
   });
 
-  it('defaults an unpinned key to the owner’s personal scope', async () => {
+  it('defaults a key with no stated tenants to the owner’s personal data', async () => {
     await createApiKey(input);
-    expect(mockedCreate.mock.calls[0][0].groupId).toBeNull();
+    expect(mockedCreate.mock.calls[0][0].tenants).toEqual([PERSONAL_TENANT]);
+    expect(mockedCreate.mock.calls[0][0].defaultTenant).toBe(PERSONAL_TENANT);
   });
 
-  it('pins a key to the group it was issued for', async () => {
-    await createApiKey({ ...input, groupId: 'g1' });
-    expect(mockedCreate.mock.calls[0][0].groupId).toBe('g1');
+  it('stores every tenant a key was granted', async () => {
+    await createApiKey({ ...input, tenants: [PERSONAL_TENANT, 'g1'], defaultTenant: 'g1' });
+
+    expect(mockedCreate.mock.calls[0][0].tenants).toEqual([PERSONAL_TENANT, 'g1']);
+    expect(mockedCreate.mock.calls[0][0].defaultTenant).toBe('g1');
+  });
+
+  it('refuses to store a default outside the grant', async () => {
+    // A key acting by default in something it cannot reach would authenticate
+    // and then fail every call that did not name a tenant explicitly.
+    await createApiKey({ ...input, tenants: ['g1'], defaultTenant: 'g2' });
+
+    expect(mockedCreate.mock.calls[0][0].defaultTenant).toBe('g1');
+  });
+
+  it('reads an empty grant as the safest non-empty one', async () => {
+    await createApiKey({ ...input, tenants: [] });
+    expect(mockedCreate.mock.calls[0][0].tenants).toEqual([PERSONAL_TENANT]);
   });
 
   it('snapshots the owner so verification needs no second query', async () => {
@@ -311,10 +329,14 @@ describe('verifyApiKey', () => {
     expect(mockedFindOne).toHaveBeenCalledWith({ keyId: parseKey(token)!.id });
   });
 
-  it('returns the identity, scopes and tenant a valid key carries', async () => {
+  it('returns the identity, scopes and tenants a valid key carries', async () => {
     const { token } = generateKey();
     mockedFindOne.mockResolvedValue(
-      acceptingKey(token, { scopes: ['relationship:read', 'album:write'], groupId: 'g1' })
+      acceptingKey(token, {
+        scopes: ['relationship:read', 'album:write'],
+        tenants: [PERSONAL_TENANT, 'g1'],
+        defaultTenant: 'g1'
+      })
     );
 
     await expect(verifyApiKey(token)).resolves.toEqual({
@@ -324,7 +346,32 @@ describe('verifyApiKey', () => {
       userName: 'Tester',
       keyId: 'k1',
       scopes: ['relationship:read', 'album:write'],
-      groupId: 'g1'
+      tenants: { allowed: [PERSONAL_TENANT, 'g1'], default: 'g1' }
+    });
+  });
+
+  it('reads a key issued before tenants were a set', async () => {
+    // Keys stored under the single-tenant model carry `groupId` and no array.
+    // Without this fallback every connected assistant would break at once on
+    // the deploy that introduced the set.
+    const { token } = generateKey();
+    mockedFindOne.mockResolvedValue(
+      acceptingKey(token, { tenants: undefined, defaultTenant: undefined, groupId: 'g1' })
+    );
+
+    await expect(verifyApiKey(token)).resolves.toMatchObject({
+      tenants: { allowed: ['g1'], default: 'g1' }
+    });
+  });
+
+  it('reads an old personal key as the personal tenant, not as no tenant', async () => {
+    const { token } = generateKey();
+    mockedFindOne.mockResolvedValue(
+      acceptingKey(token, { tenants: undefined, defaultTenant: undefined, groupId: null })
+    );
+
+    await expect(verifyApiKey(token)).resolves.toMatchObject({
+      tenants: { allowed: [PERSONAL_TENANT], default: PERSONAL_TENANT }
     });
   });
 

package/src/apiKeys/service.ts

@@ -7,7 +7,14 @@ import {
   parseKey,
   secretMatches
 } from './crypto';
-import type { ApiKeyScope, ApiKeySummary, ApiKeyVerification } from './types';
+import {
+  PERSONAL_TENANT,
+  readTenants,
+  type ApiKeyScope,
+  type ApiKeySummary,
+  type ApiKeyVerification,
+  type Tenant
+} from './types';
 
 export interface CreateApiKeyInput {
   userId: string;
@@ -15,8 +22,10 @@ export interface CreateApiKeyInput {
   userName: string;
   name: string;
   scopes: ApiKeyScope[];
-  /** null pins the key to the user's own non-group data */
-  groupId?: string | null;
+  /** every tenant the key may act in; defaults to the user's own data alone */
+  tenants?: Tenant[];
+  /** which of them it acts in when a request names none */
+  defaultTenant?: Tenant;
   expiresAt?: Date | null;
 }
 
@@ -31,7 +40,9 @@ const toSummary = (key: IApiKey): ApiKeySummary => ({
   name: key.name,
   prefix: displayPrefix(key.keyId),
   scopes: key.scopes,
-  groupId: key.groupId ?? null,
+  ...(({ allowed, default: fallback }) => ({ tenants: allowed, defaultTenant: fallback }))(
+    readTenants(key)
+  ),
   createdAt: key.createdAt.toISOString(),
   lastUsedAt: key.lastUsedAt?.toISOString() ?? null,
   expiresAt: key.expiresAt?.toISOString() ?? null,
@@ -39,6 +50,10 @@ const toSummary = (key: IApiKey): ApiKeySummary => ({
 });
 
 export const createApiKey = async (input: CreateApiKeyInput): Promise<CreatedApiKey> => {
+  // A key that reaches nowhere would authenticate and then fail every call, so
+  // an empty grant is read as the safest non-empty one rather than stored.
+  const tenants = input.tenants?.length ? input.tenants : [PERSONAL_TENANT];
+
   const { token, id, hash } = generateKey();
   const sealed = encryptSecret(token);
 
@@ -53,7 +68,10 @@ export const createApiKey = async (input: CreateApiKeyInput): Promise<CreatedApi
     sealedIv: sealed.iv,
     sealedTag: sealed.tag,
     scopes: input.scopes,
-    groupId: input.groupId ?? null,
+    tenants,
+    defaultTenant: tenants.includes(input.defaultTenant ?? '')
+      ? input.defaultTenant
+      : (tenants[0] as Tenant),
     expiresAt: input.expiresAt ?? undefined
   });
 
@@ -144,6 +162,6 @@ export const verifyApiKey = async (token: unknown): Promise<ApiKeyVerification>
     userName: key.userName,
     keyId: String(key._id),
     scopes: key.scopes,
-    groupId: key.groupId ?? null
+    tenants: readTenants(key)
   };
 };

package/src/apiKeys/types.ts

@@ -24,17 +24,69 @@ export const isApiKeyScope = (value: unknown): value is ApiKeyScope =>
   typeof value === 'string' && (API_KEY_SCOPES as readonly string[]).includes(value);
 
 /**
- * The tenant a key acts in, fixed when the key is created.
+ * A tenant a credential may act in: a group id, or the user's own data.
  *
- * The web app picks this per request from a tenant selector, but an agent has no
- * such UI and no way to know it guessed wrong — so the choice is made once, by a
- * person, and the key cannot escape it. `groupId: null` means the user's own
- * non-group data.
+ * Personal is a named sentinel rather than `null` so that a tenant is always a
+ * plain string — storable in an array, sendable in a JWT claim, comparable
+ * without a special case at every layer. It cannot collide with a real tenant:
+ * group ids are 24-character hex.
+ */
+export const PERSONAL_TENANT = 'personal';
+
+export type Tenant = string;
+
+/** The `groupId` a tenant corresponds to, as handlers have always read it. */
+export const groupIdOf = (tenant: Tenant): string | null =>
+  tenant === PERSONAL_TENANT ? null : tenant;
+
+/**
+ * Which tenants a credential may act in, and which one it acts in by default.
+ *
+ * The web app picks a tenant per request from a selector; an agent has no such
+ * UI. So the *set* is chosen once, by a person, and the credential cannot escape
+ * it — but within that set the caller may name one per request, which is what
+ * lets a single connection reach both a shared journal and a private photo
+ * library without reconnecting.
+ *
+ * `allowed` is never empty and always contains `default`. A credential granted
+ * exactly one tenant behaves precisely as a pinned one did: nothing to name,
+ * nothing to get wrong.
  */
 export interface ApiKeyTenant {
-  groupId: string | null;
+  allowed: Tenant[];
+  default: Tenant;
 }
 
+/** Just the groups, for the `req.userGroups` every handler already reads. */
+export const groupIdsOf = (tenants: Tenant[]): string[] =>
+  tenants.filter((tenant) => tenant !== PERSONAL_TENANT);
+
+/**
+ * Read a stored tenant grant, tolerating one written before tenants were a set.
+ *
+ * Keys and grants issued under the old single-tenant model carry `groupId`
+ * alone. Falling back to it here means they keep working across the deploy
+ * rather than every connected assistant breaking at once.
+ */
+export const readTenants = (stored: {
+  tenants?: Tenant[] | null;
+  defaultTenant?: Tenant | null;
+  groupId?: string | null;
+}): ApiKeyTenant => {
+  const allowed =
+    stored.tenants && stored.tenants.length > 0
+      ? stored.tenants
+      : [stored.groupId ?? PERSONAL_TENANT];
+
+  const fallbackDefault = allowed[0] as Tenant;
+  const preferred = stored.defaultTenant ?? fallbackDefault;
+
+  return {
+    allowed,
+    default: allowed.includes(preferred) ? preferred : fallbackDefault
+  };
+};
+
 /** A key as the API hands it back — never including the secret. */
 export interface ApiKeySummary {
   id: string;
@@ -42,7 +94,8 @@ export interface ApiKeySummary {
   /** the public half, shown in listings so a key is identifiable at a glance */
   prefix: string;
   scopes: ApiKeyScope[];
-  groupId: string | null;
+  tenants: Tenant[];
+  defaultTenant: Tenant;
   createdAt: string;
   lastUsedAt: string | null;
   expiresAt: string | null;
@@ -65,5 +118,5 @@ export interface ApiKeyVerification {
   userName?: string;
   keyId?: string;
   scopes?: ApiKeyScope[];
-  groupId?: string | null;
+  tenants?: ApiKeyTenant;
 }

package/src/middleware/authMiddleware.test.ts

@@ -1,6 +1,7 @@
 import { Request, Response } from 'express';
 import jwt from 'jsonwebtoken';
 import { authenticateToken, optionalAuth } from './authMiddleware';
+import { PERSONAL_TENANT } from '../apiKeys/types';
 import { mintAccessToken } from '../oauth/tokens';
 import { UserPayload } from '../types/auth';
 
@@ -192,7 +193,9 @@ describe('OAuth access tokens are not sessions', () => {
       resource: 'https://mcp.example.com',
       issuer: 'https://auth.example.com',
       scopes: ['relationship:read'],
-      groupId: null
+      tenants: [PERSONAL_TENANT],
+      defaultTenant: PERSONAL_TENANT,
+      tenantNames: {}
     }).accessToken;
 
   it('refuses one on a session-only route', () => {

package/src/oauth/models.ts

@@ -1,4 +1,5 @@
 import mongoose, { Document, Schema } from 'mongoose';
+import { PERSONAL_TENANT, type Tenant } from '../apiKeys/types';
 
 /**
  * A client registered through RFC 7591 Dynamic Client Registration.
@@ -46,7 +47,13 @@ export interface IAuthorizationCode extends Document {
   userName: string;
   redirectUri: string;
   scopes: string[];
-  groupId: string | null;
+  /** every tenant the user approved, and the one chosen as the default */
+  tenants: Tenant[];
+  defaultTenant: Tenant;
+  /** what each approved tenant is called, snapshotted at consent */
+  tenantNames: Record<Tenant, string>;
+  /** the single tenant an older grant was pinned to; read by `readTenants` */
+  groupId?: string | null;
   /** RFC 8707: the MCP server this will be minted for */
   resource: string;
   /** PKCE, always S256 — the spec does not allow `plain` */
@@ -66,6 +73,10 @@ const AuthorizationCodeSchema = new Schema<IAuthorizationCode>(
     userName: { type: String, default: '' },
     redirectUri: { type: String, required: true },
     scopes: { type: [String], default: [] },
+    tenants: { type: [String], default: () => [PERSONAL_TENANT] },
+    defaultTenant: { type: String, default: PERSONAL_TENANT },
+    tenantNames: { type: Schema.Types.Mixed, default: () => ({}) },
+    // Written by the single-tenant model this replaced; read-only now.
     groupId: { type: String, default: null },
     resource: { type: String, required: true },
     codeChallenge: { type: String, required: true },
@@ -96,7 +107,11 @@ export interface IRefreshToken extends Document {
   clientId: string;
   userId: string;
   scopes: string[];
-  groupId: string | null;
+  tenants: Tenant[];
+  defaultTenant: Tenant;
+  tenantNames: Record<Tenant, string>;
+  /** the single tenant an older grant was pinned to; read by `readTenants` */
+  groupId?: string | null;
   resource: string;
   /**
    * When the user actually connected this assistant.
@@ -118,6 +133,10 @@ const RefreshTokenSchema = new Schema<IRefreshToken>(
     clientId: { type: String, required: true },
     userId: { type: String, required: true, index: true },
     scopes: { type: [String], default: [] },
+    tenants: { type: [String], default: () => [PERSONAL_TENANT] },
+    defaultTenant: { type: String, default: PERSONAL_TENANT },
+    tenantNames: { type: Schema.Types.Mixed, default: () => ({}) },
+    // Written by the single-tenant model this replaced; read-only now.
     groupId: { type: String, default: null },
     resource: { type: String, required: true },
     grantedAt: { type: Date, default: Date.now },

package/src/oauth/service.test.ts

@@ -1,4 +1,5 @@
 import { createHash } from 'crypto';
+import { PERSONAL_TENANT } from '../apiKeys/types';
 
 jest.mock('./models', () => ({
   OAuthClient: { create: jest.fn(), findOne: jest.fn(), find: jest.fn() },
@@ -122,13 +123,21 @@ describe('issueAuthorizationCode', () => {
       userName: 'Tester',
       redirectUri: 'https://claude.ai/callback',
       scopes: ['relationship:read'],
-      groupId: 'g1',
+      tenants: ['g1'],
+      defaultTenant: 'g1',
+      tenantNames: { g1: 'Irja & Tom' },
       resource: 'https://mcp.tumbaland.eu',
       codeChallenge: CHALLENGE
     });
 
     const [doc] = mockedCodeCreate.mock.calls[0];
-    expect(doc).toMatchObject({ userId: 'u1', groupId: 'g1', scopes: ['relationship:read'] });
+    expect(doc).toMatchObject({
+      userId: 'u1',
+      tenants: ['g1'],
+      defaultTenant: 'g1',
+      tenantNames: { g1: 'Irja & Tom' },
+      scopes: ['relationship:read']
+    });
     expect(doc.expiresAt.getTime() - before).toBeLessThanOrEqual(60_000);
   });
 });
@@ -224,7 +233,9 @@ describe('issueRefreshToken', () => {
       clientId: 'client-1',
       userId: 'u1',
       scopes: ['relationship:read'],
-      groupId: null,
+      tenants: [PERSONAL_TENANT],
+      defaultTenant: PERSONAL_TENANT,
+      tenantNames: {},
       resource: 'https://mcp.tumbaland.eu'
     });
 
@@ -311,7 +322,9 @@ describe('refresh tokens', () => {
       clientId: 'client-1',
       userId: 'u1',
       scopes: ['relationship:read'],
-      groupId: null,
+      tenants: [PERSONAL_TENANT],
+      defaultTenant: PERSONAL_TENANT,
+      tenantNames: {},
       resource: 'https://mcp.tumbaland.eu'
     });
 
@@ -324,7 +337,9 @@ describe('refresh tokens', () => {
     mockedRefreshFindOne.mockResolvedValue({
       userId: 'u1',
       scopes: ['relationship:read'],
-      groupId: 'g1',
+      tenants: [PERSONAL_TENANT, 'g1'],
+      defaultTenant: 'g1',
+      tenantNames: { g1: 'Irja & Tom' },
       resource: 'https://mcp.tumbaland.eu',
       grantedAt: new Date(),
       save: jest.fn()
@@ -333,7 +348,44 @@ describe('refresh tokens', () => {
     await expect(redeemRefreshToken('tok', 'client-1')).resolves.toMatchObject({
       ok: true,
       userId: 'u1',
-      groupId: 'g1'
+      tenants: { allowed: [PERSONAL_TENANT, 'g1'], default: 'g1' }
+    });
+  });
+
+  it('carries the tenants through rotation rather than re-deriving them', async () => {
+    mockedRefreshFindOne.mockResolvedValue({
+      userId: 'u1',
+      scopes: ['relationship:read'],
+      tenants: [PERSONAL_TENANT, 'g1'],
+      defaultTenant: 'g1',
+      tenantNames: { g1: 'Irja & Tom' },
+      resource: 'https://mcp.tumbaland.eu',
+      grantedAt: new Date(),
+      save: jest.fn()
+    });
+
+    await redeemRefreshToken('tok', 'client-1');
+
+    // Rotation reissues the same grant; re-deriving would quietly narrow a
+    // connection every time it refreshed.
+    const [doc] = mockedRefreshCreate.mock.calls.at(-1)!;
+    expect(doc.tenants).toEqual([PERSONAL_TENANT, 'g1']);
+    expect(doc.defaultTenant).toBe('g1');
+    expect(doc.tenantNames).toEqual({ g1: 'Irja & Tom' });
+  });
+
+  it('reads a grant issued before tenants were a set', async () => {
+    mockedRefreshFindOne.mockResolvedValue({
+      userId: 'u1',
+      scopes: ['relationship:read'],
+      groupId: 'g1',
+      resource: 'https://mcp.tumbaland.eu',
+      grantedAt: new Date(),
+      save: jest.fn()
+    });
+
+    await expect(redeemRefreshToken('tok', 'client-1')).resolves.toMatchObject({
+      tenants: { allowed: ['g1'], default: 'g1' }
     });
   });