@tumbaland/backend-core 1.36.0 → 1.38.0

package/src/apiKeys/ApiKey.ts

@@ -1,5 +1,5 @@
 import mongoose, { Document, Schema } from 'mongoose';
-import type { ApiKeyScope } from './types';
+import { PERSONAL_TENANT, type ApiKeyScope, type Tenant } from './types';
 
 /**
  * One API key. Lives in backend-core rather than auth-service because both
@@ -31,8 +31,17 @@ export interface IApiKey extends Document {
   sealedIv: string;
   sealedTag: string;
   scopes: ApiKeyScope[];
-  /** the tenant this key acts in; null means the user's own non-group data */
-  groupId: string | null;
+  /** every tenant this key may act in; see `Tenant` */
+  tenants: Tenant[];
+  /** the one it acts in when a request names none; always a member of `tenants` */
+  defaultTenant: Tenant;
+  /**
+   * The single tenant this key was pinned to, before tenants were a set.
+   *
+   * Kept so keys issued under the old model keep working; `readTenants` falls
+   * back to it. Nothing writes it any more.
+   */
+  groupId?: string | null;
   lastUsedAt?: Date;
   expiresAt?: Date;
   revokedAt?: Date;
@@ -55,8 +64,11 @@ const ApiKeySchema = new Schema<IApiKey>(
     sealedIv: { type: String, required: true },
     sealedTag: { type: String, required: true },
     scopes: { type: [String], default: [] },
-    // Explicitly nullable rather than optional: "personal scope" is a decision the
+    // Defaulted rather than optional: which data a key reaches is a decision the
     // creator made, and it must not be indistinguishable from a field nobody set.
+    tenants: { type: [String], default: () => [PERSONAL_TENANT] },
+    defaultTenant: { type: String, default: PERSONAL_TENANT },
+    // Written by the single-tenant model this replaced; read-only now.
     groupId: { type: String, default: null },
     lastUsedAt: { type: Date },
     expiresAt: { type: Date },

package/src/apiKeys/index.ts

@@ -11,8 +11,22 @@ export {
 export type { CreateApiKeyInput, CreatedApiKey } from './service';
 export { authenticateAgent, requireScope, denyApiKeys } from './middleware';
 export type { ApiKeyContext } from './middleware';
-export { API_KEY_SCOPES, isApiKeyScope } from './types';
-export type { ApiKeyScope, ApiKeySummary, ApiKeyVerification, ApiKeyRejection } from './types';
+export {
+  API_KEY_SCOPES,
+  isApiKeyScope,
+  PERSONAL_TENANT,
+  groupIdOf,
+  groupIdsOf,
+  readTenants
+} from './types';
+export type {
+  ApiKeyScope,
+  ApiKeySummary,
+  ApiKeyVerification,
+  ApiKeyRejection,
+  ApiKeyTenant,
+  Tenant
+} from './types';
 export {
   looksLikeApiKey,
   displayPrefix,

package/src/apiKeys/middleware.test.ts

@@ -8,6 +8,8 @@ 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;
@@ -26,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',
@@ -33,7 +38,7 @@ const okVerification = (over: Record<string, unknown> = {}) => ({
   userName: 'Tester',
   keyId: 'k1',
   scopes: ['relationship:read', 'relationship:write'],
-  groupId: null,
+  tenants: grant(PERSONAL_TENANT),
   ...over
 });
 
@@ -110,7 +115,8 @@ describe('authenticateAgent — API keys', () => {
     expect(request.apiKey).toEqual({
       keyId: 'k1',
       scopes: ['relationship:read', 'relationship:write'],
-      groupId: null
+      tenants: grant(PERSONAL_TENANT),
+      actingAs: PERSONAL_TENANT
     });
   });
 
@@ -166,7 +172,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();
@@ -178,7 +184,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();
 
@@ -188,9 +194,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());
@@ -199,7 +210,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());
@@ -207,8 +218,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();
 
@@ -220,7 +231,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();
 
@@ -231,7 +242,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();
 
@@ -242,7 +253,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();
 
@@ -252,8 +263,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);
@@ -262,9 +273,76 @@ 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 }
+    } as Partial<Request>);
 
   it('lets a session through unconditionally', () => {
     // Scopes narrow what software may do on a person's behalf, not what the
@@ -342,7 +420,9 @@ 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 }
+      }) as Request,
       res,
       next
     );
@@ -351,3 +431,114 @@ describe('denyApiKeys', () => {
     expect(next).not.toHaveBeenCalled();
   });
 });
+
+describe('authenticateAgent — OAuth access tokens', () => {
+  /**
+   * Minted by the real thing rather than hand-signed. The bug this covers was
+   * that an access token verified as a session — same secret, same header — and
+   * its claims were then read as a session's: `sub` instead of `id`, no
+   * `groups`. Every one of those details has to come from the code that issues
+   * them, or the test simply re-encodes whatever the middleware happens to do.
+   */
+  const mint = (over: Partial<MintAccessTokenInput> = {}) =>
+    mintAccessToken({
+      userId: 'u1',
+      email: 'u1@example.com',
+      name: 'Tester',
+      resource: 'https://mcp.example.com',
+      issuer: 'https://auth.example.com',
+      scopes: ['relationship:read', 'relationship:write'],
+      tenants: [PERSONAL_TENANT],
+      defaultTenant: PERSONAL_TENANT,
+      tenantNames: { [PERSONAL_TENANT]: 'My own data' },
+      ...over
+    }).accessToken;
+
+  const withToken = (token: string, over: Partial<Request> = {}) =>
+    req({ headers: { authorization: `Bearer ${token}` }, ...over });
+
+  it('names the user, so scoped queries are bounded', async () => {
+    const request = withToken(mint());
+    const next = jest.fn();
+
+    await authenticateAgent('relationship:write')(request, mockRes(), next);
+
+    expect(next).toHaveBeenCalled();
+    // Read as a session this was `undefined`, which reached handlers as "no
+    // user" rather than as a refusal: writes were rejected as inaccessible and
+    // reads fell through to an unscoped query.
+    expect(request.user?.id).toBe('u1');
+    expect(request.user?.email).toBe('u1@example.com');
+  });
+
+  it('is held to its scopes, exactly as a key is', async () => {
+    const res = mockRes();
+    const next = jest.fn();
+    const request = withToken(mint({ scopes: ['relationship:read'] }));
+
+    await authenticateAgent('relationship:write')(request, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(403);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('carries an apiKey context, so requireScope applies downstream', async () => {
+    const request = withToken(mint({ scopes: ['relationship:read'] }));
+
+    await authenticateAgent()(request, mockRes(), jest.fn());
+
+    // Without this the token looked like a session and every requireScope on
+    // every route waved it through.
+    expect(request.apiKey?.scopes).toEqual(['relationship:read']);
+
+    const res = mockRes();
+    const next = jest.fn();
+    requireScope('relationship:write')(request, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(403);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  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);
+
+    expect(next).toHaveBeenCalled();
+    expect(request.userGroups).toEqual(['g1']);
+    // Written in for a caller that named none, so a handler's group branch
+    // lands where the person who approved the connection intended.
+    expect(request.query.groupId).toBe('g1');
+  });
+
+  it('refuses a request naming a different tenant', async () => {
+    const res = mockRes();
+    const next = jest.fn();
+    const request = withToken(mint({ tenants: ['g1'], defaultTenant: 'g1' }), {
+      query: { groupId: 'g2' }
+    });
+
+    await authenticateAgent()(request, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(403);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('is refused by denyApiKeys, like any other credential software holds', async () => {
+    const request = withToken(mint());
+    await authenticateAgent()(request, mockRes(), jest.fn());
+
+    const res = mockRes();
+    const next = jest.fn();
+    denyApiKeys(request, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(403);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('never consults the API key store', async () => {
+    await authenticateAgent()(withToken(mint()), mockRes(), jest.fn());
+    expect(mockedVerify).not.toHaveBeenCalled();
+  });
+});