@tumbaland/backend-core 1.37.0 → 1.39.0

package/src/apiKeys/middleware.test.ts

@@ -9,6 +9,7 @@ jest.mock('../logging/logger', () => ({
 import jwt from 'jsonwebtoken';
 import { verifyApiKey } from './service';
 import { mintAccessToken, type MintAccessTokenInput } from '../oauth/tokens';
+import { PERSONAL_TENANT } from './types';
 import { authenticateAgent, requireScope, denyApiKeys } from './middleware';
 
 const mockedVerify = verifyApiKey as jest.Mock;
@@ -27,6 +28,9 @@ const req = (over: Partial<Request> = {}): Request =>
 const withKey = (token = 'tmb_live_abcdef123456_secretsecretsecret', over: Partial<Request> = {}) =>
   req({ headers: { authorization: `Bearer ${token}` }, ...over });
 
+/** A grant of one or more tenants; the first is the default unless said otherwise. */
+const grant = (...allowed: string[]) => ({ allowed, default: allowed[0] });
+
 const okVerification = (over: Record<string, unknown> = {}) => ({
   ok: true,
   userId: 'u1',
@@ -34,7 +38,8 @@ const okVerification = (over: Record<string, unknown> = {}) => ({
   userName: 'Tester',
   keyId: 'k1',
   scopes: ['relationship:read', 'relationship:write'],
-  groupId: null,
+  tenants: grant(PERSONAL_TENANT),
+  label: 'Claude Code',
   ...over
 });
 
@@ -111,7 +116,12 @@ describe('authenticateAgent — API keys', () => {
     expect(request.apiKey).toEqual({
       keyId: 'k1',
       scopes: ['relationship:read', 'relationship:write'],
-      groupId: null
+      tenants: grant(PERSONAL_TENANT),
+      actingAs: PERSONAL_TENANT,
+      kind: 'api_key',
+      // What the owner called it, so a trail reads "Claude Code" not an id.
+      label: 'Claude Code',
+      credentialId: 'k1'
     });
   });
 
@@ -167,7 +177,7 @@ it('authenticates a key stored before the owner snapshot existed', async () => {
     userId: 'u1',
     keyId: 'k1',
     scopes: ['relationship:read'],
-    groupId: null
+    tenants: grant(PERSONAL_TENANT)
   });
   const request = withKey();
   const next = jest.fn();
@@ -179,7 +189,7 @@ it('authenticates a key stored before the owner snapshot existed', async () => {
 });
 
 it('treats a verification result with no scopes as granting nothing', async () => {
-  mockedVerify.mockResolvedValue({ ok: true, userId: 'u1', keyId: 'k1', groupId: null });
+  mockedVerify.mockResolvedValue({ ok: true, userId: 'u1', keyId: 'k1', tenants: grant(PERSONAL_TENANT) });
   const res = mockRes();
   const next = jest.fn();
 
@@ -189,9 +199,14 @@ it('treats a verification result with no scopes as granting nothing', async () =
   expect(next).not.toHaveBeenCalled();
 });
 
-describe('authenticateAgent — tenant pinning', () => {
+describe('authenticateAgent — a single-tenant grant', () => {
+  /**
+   * The behaviour a pinned credential always had, kept intact now that a grant
+   * is a set. An agent given one tenant should never learn that a tenant is a
+   * thing it could name — nothing to choose, nothing to get wrong.
+   */
   it('grants a personal key no groups at all', async () => {
-    mockedVerify.mockResolvedValue(okVerification({ groupId: null }));
+    mockedVerify.mockResolvedValue(okVerification({ tenants: grant(PERSONAL_TENANT) }));
     const request = withKey();
 
     await authenticateAgent()(request, mockRes(), jest.fn());
@@ -200,7 +215,7 @@ describe('authenticateAgent — tenant pinning', () => {
   });
 
   it('grants a group key exactly its own group, not the owner’s whole membership', async () => {
-    mockedVerify.mockResolvedValue(okVerification({ groupId: 'g1' }));
+    mockedVerify.mockResolvedValue(okVerification({ tenants: grant('g1') }));
     const request = withKey();
 
     await authenticateAgent()(request, mockRes(), jest.fn());
@@ -208,8 +223,8 @@ describe('authenticateAgent — tenant pinning', () => {
     expect(request.userGroups).toEqual(['g1']);
   });
 
-  it('fills in the pinned group so the caller never has to know it', async () => {
-    mockedVerify.mockResolvedValue(okVerification({ groupId: 'g1' }));
+  it('fills in the group so the caller never has to know it', async () => {
+    mockedVerify.mockResolvedValue(okVerification({ tenants: grant('g1') }));
     const request = withKey();
     const next = jest.fn();
 
@@ -221,7 +236,7 @@ describe('authenticateAgent — tenant pinning', () => {
   });
 
   it('refuses a query that names a different group', async () => {
-    mockedVerify.mockResolvedValue(okVerification({ groupId: 'g1' }));
+    mockedVerify.mockResolvedValue(okVerification({ tenants: grant('g1') }));
     const res = mockRes();
     const next = jest.fn();
 
@@ -232,7 +247,7 @@ describe('authenticateAgent — tenant pinning', () => {
   });
 
   it('refuses a body that names a different group', async () => {
-    mockedVerify.mockResolvedValue(okVerification({ groupId: 'g1' }));
+    mockedVerify.mockResolvedValue(okVerification({ tenants: grant('g1') }));
     const res = mockRes();
     const next = jest.fn();
 
@@ -243,7 +258,7 @@ describe('authenticateAgent — tenant pinning', () => {
   });
 
   it('refuses a personal key that tries to reach into a group', async () => {
-    mockedVerify.mockResolvedValue(okVerification({ groupId: null }));
+    mockedVerify.mockResolvedValue(okVerification({ tenants: grant(PERSONAL_TENANT) }));
     const res = mockRes();
     const next = jest.fn();
 
@@ -253,8 +268,8 @@ describe('authenticateAgent — tenant pinning', () => {
     expect(next).not.toHaveBeenCalled();
   });
 
-  it('allows a request that names the pinned group explicitly', async () => {
-    mockedVerify.mockResolvedValue(okVerification({ groupId: 'g1' }));
+  it('allows a request that names the granted group explicitly', async () => {
+    mockedVerify.mockResolvedValue(okVerification({ tenants: grant('g1') }));
     const next = jest.fn();
 
     await authenticateAgent()(withKey(undefined, { query: { groupId: 'g1' } }), mockRes(), next);
@@ -263,9 +278,84 @@ describe('authenticateAgent — tenant pinning', () => {
   });
 });
 
+describe('authenticateAgent — a multi-tenant grant', () => {
+  /**
+   * What the set buys: one connection reaching a shared journal and private data
+   * without reconnecting. The boundary is unchanged — a tenant outside the grant
+   * is still refused — so these tests are about the choice *inside* it.
+   */
+  const both = { allowed: [PERSONAL_TENANT, 'g1'], default: 'g1' };
+
+  it('acts in the default when the request names nothing', async () => {
+    mockedVerify.mockResolvedValue(okVerification({ tenants: both }));
+    const request = withKey();
+
+    await authenticateAgent()(request, mockRes(), jest.fn());
+
+    expect(request.query.groupId).toBe('g1');
+    expect(request.apiKey?.actingAs).toBe('g1');
+  });
+
+  it('acts in another granted tenant when the request names it', async () => {
+    mockedVerify.mockResolvedValue(okVerification({ tenants: both }));
+    const request = withKey(undefined, { query: { groupId: PERSONAL_TENANT } });
+
+    await authenticateAgent()(request, mockRes(), jest.fn());
+
+    // `personal` is erased rather than passed on: handlers have always read the
+    // personal tenant as an absent groupId, and a literal would reach a query as
+    // a group that cannot exist.
+    expect(request.query.groupId).toBeUndefined();
+    expect(request.apiKey?.actingAs).toBe(PERSONAL_TENANT);
+  });
+
+  it('erases a stale groupId from the body too, not only the query', async () => {
+    mockedVerify.mockResolvedValue(okVerification({ tenants: both }));
+    const request = withKey(undefined, { body: { groupId: PERSONAL_TENANT } });
+
+    await authenticateAgent()(request, mockRes(), jest.fn());
+
+    expect((request.body as Record<string, unknown>).groupId).toBeUndefined();
+  });
+
+  it('still refuses a tenant outside the grant', async () => {
+    mockedVerify.mockResolvedValue(okVerification({ tenants: both }));
+    const res = mockRes();
+    const next = jest.fn();
+
+    await authenticateAgent()(withKey(undefined, { query: { groupId: 'g2' } }), res, next);
+
+    expect(res.status).toHaveBeenCalledWith(403);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('carries every granted group into userGroups, and only those', async () => {
+    mockedVerify.mockResolvedValue(
+      okVerification({ tenants: { allowed: [PERSONAL_TENANT, 'g1', 'g2'], default: 'g1' } })
+    );
+    const request = withKey();
+
+    await authenticateAgent()(request, mockRes(), jest.fn());
+
+    // The personal tenant is not a group and must not appear here, or it would
+    // reach a `groupId: { $in: ... }` clause as a group nobody belongs to.
+    expect(request.userGroups).toEqual(['g1', 'g2']);
+  });
+});
+
 describe('requireScope', () => {
   const keyReq = (scopes: string[]) =>
-    req({ apiKey: { keyId: 'k1', scopes, groupId: null } } as Partial<Request>);
+    req({
+      apiKey: {
+        keyId: 'k1',
+        scopes,
+        tenants: grant(PERSONAL_TENANT),
+        actingAs: PERSONAL_TENANT,
+        kind: 'api_key' as const,
+        label: 'A key',
+        credentialId: 'k1'
+      }
+    } as Partial<Request>);
 
   it('lets a session through unconditionally', () => {
     // Scopes narrow what software may do on a person's behalf, not what the
@@ -343,7 +433,17 @@ describe('denyApiKeys', () => {
     const next = jest.fn();
 
     denyApiKeys(
-      req({ apiKey: { keyId: 'k1', scopes: [], groupId: null } }) as Request,
+      req({
+        apiKey: {
+          keyId: 'k1',
+          scopes: [],
+          tenants: grant(PERSONAL_TENANT),
+          actingAs: PERSONAL_TENANT,
+          kind: 'api_key' as const,
+          label: 'A key',
+          credentialId: 'k1'
+        }
+      }) as Request,
       res,
       next
     );
@@ -369,7 +469,11 @@ describe('authenticateAgent — OAuth access tokens', () => {
       resource: 'https://mcp.example.com',
       issuer: 'https://auth.example.com',
       scopes: ['relationship:read', 'relationship:write'],
-      groupId: null,
+      tenants: [PERSONAL_TENANT],
+      defaultTenant: PERSONAL_TENANT,
+      tenantNames: { [PERSONAL_TENANT]: 'My own data' },
+      clientId: 'client-1',
+      clientName: 'Claude',
       ...over
     }).accessToken;
 
@@ -418,8 +522,8 @@ describe('authenticateAgent — OAuth access tokens', () => {
     expect(next).not.toHaveBeenCalled();
   });
 
-  it('is pinned to the tenant chosen at consent', async () => {
-    const request = withToken(mint({ groupId: 'g1' }));
+  it('acts in the tenant chosen at consent', async () => {
+    const request = withToken(mint({ tenants: ['g1'], defaultTenant: 'g1' }));
     const next = jest.fn();
 
     await authenticateAgent()(request, mockRes(), next);
@@ -434,7 +538,9 @@ describe('authenticateAgent — OAuth access tokens', () => {
   it('refuses a request naming a different tenant', async () => {
     const res = mockRes();
     const next = jest.fn();
-    const request = withToken(mint({ groupId: 'g1' }), { query: { groupId: 'g2' } });
+    const request = withToken(mint({ tenants: ['g1'], defaultTenant: 'g1' }), {
+      query: { groupId: 'g2' }
+    });
 
     await authenticateAgent()(request, res, next);
 

package/src/apiKeys/middleware.ts

@@ -2,11 +2,20 @@ import { NextFunction, Request, RequestHandler, Response } from 'express';
 import jwt from 'jsonwebtoken';
 import { requireEnv } from '../config/env';
 import logger from '../logging/logger';
+import { beginAudit } from '../audit/context';
 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 +25,22 @@ 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;
+  /** which credential this is; they are revoked and audited differently */
+  kind: 'api_key' | 'oauth';
+  /** what the owner called it — a key's name, or the connected app's */
+  label: string;
+  /**
+   * The stable identity of the credential.
+   *
+   * A key's document id, or an OAuth client id — never the access token's
+   * `jti`, which rotates hourly and would make one connection look like a new
+   * actor every time it refreshed.
+   */
+  credentialId: string;
 }
 
 declare global {
@@ -40,10 +63,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,46 +78,64 @@ 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. */
 interface AgentCredential {
-  /** the key id or token id, for the request-scoped context */
+  /** the key's document id, or the OAuth client id */
   credentialId: string;
+  kind: 'api_key' | 'oauth';
+  /** what the owner called it, for a trail a person can read */
+  label: string;
   userId: string;
   email: string;
   name: string;
   scopes: ApiKeyScope[];
-  groupId: string | null;
+  tenants: ApiKeyTenant;
 }
 
 /**
@@ -120,7 +163,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,13 +173,24 @@ 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,
+    kind: credential.kind,
+    label: credential.label,
+    credentialId: credential.credentialId
+  };
 
-  next();
+  // Attribution comes from authentication, so it is established here rather
+  // than mounted separately — a router that authenticates per route would
+  // otherwise have no actor in scope when a router-level middleware ran.
+  beginAudit(req, res, next);
 }
 
 /**
@@ -171,7 +226,7 @@ export const authenticateAgent = (...requiredScopes: ApiKeyScope[]): RequestHand
         const user = claims as UserPayload;
         req.user = user;
         req.userGroups = user.groups ?? [];
-        next();
+        beginAudit(req, res, next);
         return;
       }
 
@@ -186,12 +241,15 @@ export const authenticateAgent = (...requiredScopes: ApiKeyScope[]): RequestHand
       // whose scope collapsed to nothing fell through to "no user context" and
       // answered from the whole collection.
       admitAgent(req, res, next, requiredScopes, {
-        credentialId: claims.jti,
+        // The client, not the token: `jti` is a new value every hour.
+        credentialId: claims.clientId ?? 'unknown-client',
+        kind: 'oauth',
+        label: claims.clientName || 'A connected app',
         userId: claims.sub,
         email: claims.email ?? '',
         name: claims.name ?? '',
         scopes: (claims.scope ?? '').split(' ').filter(isApiKeyScope),
-        groupId: claims.groupId ?? null
+        tenants: readTenants(claims)
       });
       return;
     }
@@ -207,11 +265,13 @@ export const authenticateAgent = (...requiredScopes: ApiKeyScope[]): RequestHand
 
     admitAgent(req, res, next, requiredScopes, {
       credentialId: result.keyId!,
+      kind: 'api_key',
+      label: result.label || 'An API key',
       userId: result.userId!,
       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,34 @@ describe('verifyApiKey', () => {
       userName: 'Tester',
       keyId: 'k1',
       scopes: ['relationship:read', 'album:write'],
-      groupId: 'g1'
+      // The key's own name, so an audit trail reads "Claude" and not "k1".
+      label: 'Claude',
+      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
   });
 
@@ -143,7 +161,8 @@ export const verifyApiKey = async (token: unknown): Promise<ApiKeyVerification>
     userEmail: key.userEmail,
     userName: key.userName,
     keyId: String(key._id),
+    label: key.name,
     scopes: key.scopes,
-    groupId: key.groupId ?? null
+    tenants: readTenants(key)
   };
 };