@tumbaland/backend-core 1.36.0 → 1.38.0

package/src/apiKeys/middleware.ts

@@ -2,10 +2,19 @@ import { NextFunction, Request, RequestHandler, Response } from 'express';
 import jwt from 'jsonwebtoken';
 import { requireEnv } from '../config/env';
 import logger from '../logging/logger';
+import { isAccessTokenClaims, type AccessTokenClaims } from '../oauth/tokens';
 import type { UserPayload } from '../types/auth';
 import { looksLikeApiKey } from './crypto';
 import { verifyApiKey } from './service';
-import 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
@@ -15,8 +24,10 @@ import 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 {
@@ -39,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;
 
@@ -52,37 +65,112 @@ 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);
-
-  if (requested !== undefined && requested !== groupId) return false;
-
-  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;
-    }
+const applyTenantGrant = (req: Request, tenants: ApiKeyTenant): Tenant | null => {
+  const requested = requestedTenant(req) ?? tenants.default;
+
+  if (!tenants.allowed.includes(requested)) return null;
+
+  // 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 */
+  credentialId: string;
+  userId: string;
+  email: string;
+  name: string;
+  scopes: ApiKeyScope[];
+  tenants: ApiKeyTenant;
+}
+
+/**
+ * Admit software acting for a user, on the terms its credential carries.
+ *
+ * Shared by both non-session credentials on purpose. An API key and an OAuth
+ * access token differ entirely in how they are issued and verified, and not at
+ * all in what they mean once they are: a user, a set of scopes, and one tenant.
+ * Settling that in one place is what keeps the two from drifting into subtly
+ * different amounts of access.
+ */
+function admitAgent(
+  req: Request,
+  res: Response,
+  next: NextFunction,
+  requiredScopes: ApiKeyScope[],
+  credential: AgentCredential
+): void {
+  const missing = requiredScopes.filter((scope) => !credential.scopes.includes(scope));
+  if (missing.length > 0) {
+    res.status(403).json({
+      success: false,
+      message: `Credential is missing required scope: ${missing.join(', ')}`
+    });
+    return;
+  }
+
+  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'
+    });
+    return;
+  }
+
+  req.user = { id: credential.userId, email: credential.email, name: credential.name };
+  // 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 = groupIdsOf(credential.tenants.allowed);
+  req.apiKey = {
+    keyId: credential.credentialId,
+    scopes: credential.scopes,
+    tenants: credential.tenants,
+    actingAs
+  };
+
+  next();
+}
+
 /**
  * Authenticate a request that software may legitimately be making.
  *
@@ -104,14 +192,40 @@ export const authenticateAgent = (...requiredScopes: ApiKeyScope[]): RequestHand
     }
 
     if (!looksLikeApiKey(token)) {
+      let claims: UserPayload | AccessTokenClaims;
       try {
-        const user = jwt.verify(token, requireEnv('JWT_SECRET')) as UserPayload;
+        claims = jwt.verify(token, requireEnv('JWT_SECRET')) as UserPayload | AccessTokenClaims;
+      } catch {
+        unauthorized(res);
+        return;
+      }
+
+      if (!isAccessTokenClaims(claims)) {
+        const user = claims as UserPayload;
         req.user = user;
         req.userGroups = user.groups ?? [];
         next();
-      } catch {
-        unauthorized(res);
+        return;
       }
+
+      // An OAuth access token: signed with the same secret as a session and
+      // arriving in the same header, but nothing like one. It names its user in
+      // `sub`, carries scopes, and is pinned to a tenant — so it is admitted
+      // the way a key is, not the way a person is.
+      //
+      // Reading it as a session was the original bug and it failed quietly: the
+      // claims have no `id` and no `groups`, so `req.user.id` arrived as
+      // `undefined`, scoped writes were refused as inaccessible, and a read
+      // 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,
+        userId: claims.sub,
+        email: claims.email ?? '',
+        name: claims.name ?? '',
+        scopes: (claims.scope ?? '').split(' ').filter(isApiKeyScope),
+        tenants: readTenants(claims)
+      });
       return;
     }
 
@@ -124,37 +238,14 @@ export const authenticateAgent = (...requiredScopes: ApiKeyScope[]): RequestHand
       return;
     }
 
-    const scopes = result.scopes ?? [];
-    const missing = requiredScopes.filter((scope) => !scopes.includes(scope));
-    if (missing.length > 0) {
-      res.status(403).json({
-        success: false,
-        message: `API key is missing required scope: ${missing.join(', ')}`
-      });
-      return;
-    }
-
-    const groupId = result.groupId ?? null;
-    if (!applyTenantPin(req, groupId)) {
-      res.status(403).json({
-        success: false,
-        message: 'API key is not permitted to act in the requested group'
-      });
-      return;
-    }
-
-    req.user = {
-      id: result.userId!,
+    admitAgent(req, res, next, requiredScopes, {
+      credentialId: result.keyId!,
+      userId: result.userId!,
       email: result.userEmail ?? '',
-      name: result.userName ?? ''
-    };
-    // Only the pinned group, never the owner's full membership: this is what
-    // stops a key reaching a group it was not issued for through any handler
-    // that consults `userGroups` instead of the `groupId` parameter.
-    req.userGroups = groupId ? [groupId] : [];
-    req.apiKey = { keyId: result.keyId!, scopes, groupId };
-
-    next();
+      name: result.userName ?? '',
+      scopes: result.scopes ?? [],
+      tenants: result.tenants ?? readTenants({})
+    });
   };
 
 /**
@@ -166,7 +257,9 @@ export const authenticateAgent = (...requiredScopes: ApiKeyScope[]): RequestHand
  * door for lacking a scope half the router never uses.
  *
  * A session passes unconditionally: scopes narrow what software may do on a
- * person's behalf, not what the person may do themselves.
+ * person's behalf, not what the person may do themselves. Everything that is
+ * not a session — an API key or an OAuth access token alike — arrives with
+ * `req.apiKey` set and is held to it.
  */
 export const requireScope = (...requiredScopes: ApiKeyScope[]): RequestHandler =>
   function requireScopeHandler(req, res, next) {
@@ -179,7 +272,7 @@ export const requireScope = (...requiredScopes: ApiKeyScope[]): RequestHandler =
     if (missing.length > 0) {
       res.status(403).json({
         success: false,
-        message: `API key is missing required scope: ${missing.join(', ')}`
+        message: `Credential is missing required scope: ${missing.join(', ')}`
       });
       return;
     }
@@ -188,7 +281,7 @@ export const requireScope = (...requiredScopes: ApiKeyScope[]): RequestHandler =
   };
 
 /**
- * Refuse API keys on a route that a session may still use.
+ * Refuse every non-session credential on a route that a session may still use.
  *
  * For the handful of operations that should stay a person's to perform — key
  * management itself, most obviously, since a key that can mint keys is a key

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,8 @@
 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';
 
 function mockReq(overrides: Partial<Request> = {}): Request {
@@ -171,3 +173,53 @@ describe('optionalAuth', () => {
     expect(res.status).not.toHaveBeenCalled();
   });
 });
+
+describe('OAuth access tokens are not sessions', () => {
+  const ORIGINAL_ENV = process.env;
+
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV, JWT_SECRET: 'test-secret' };
+  });
+
+  afterEach(() => {
+    process.env = ORIGINAL_ENV;
+  });
+
+  const accessToken = () =>
+    mintAccessToken({
+      userId: 'u1',
+      email: 'u1@example.com',
+      name: 'Tester',
+      resource: 'https://mcp.example.com',
+      issuer: 'https://auth.example.com',
+      scopes: ['relationship:read'],
+      tenants: [PERSONAL_TENANT],
+      defaultTenant: PERSONAL_TENANT,
+      tenantNames: {}
+    }).accessToken;
+
+  it('refuses one on a session-only route', () => {
+    const res = mockRes();
+    const next = jest.fn();
+    const req = mockReq({ headers: { authorization: `Bearer ${accessToken()}` } });
+
+    // It verifies — same secret — so nothing but the type check stands between
+    // an assistant and every route that has no scopes to be held to.
+    authenticateToken(req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(403);
+    expect(next).not.toHaveBeenCalled();
+    expect(req.user).toBeUndefined();
+  });
+
+  it('treats one as no session at all on an optional-auth route', () => {
+    const next = jest.fn();
+    const req = mockReq({ headers: { authorization: `Bearer ${accessToken()}` } });
+
+    optionalAuth(req, mockRes(), next);
+
+    // The route still answers, in its public form — the same as a stale cookie.
+    expect(next).toHaveBeenCalled();
+    expect(req.user).toBeUndefined();
+  });
+});