@tumbaland/backend-core 1.36.0 → 1.38.0

package/src/middleware/authMiddleware.ts

@@ -1,6 +1,7 @@
 import { Request, Response, NextFunction } from 'express';
 import jwt from 'jsonwebtoken';
 import { requireEnv } from '../config/env';
+import { isAccessTokenClaims } from '../oauth/tokens';
 import { UserPayload } from '../types/auth';
 
 /**
@@ -8,6 +9,13 @@ import { UserPayload } from '../types/auth';
  * Verifies JWT token and attaches user info (and its embedded groups) to
  * the request — typed via the global `Express.Request` augmentation in
  * `../types/auth`, no `(req as any)` cast needed.
+ *
+ * OAuth access tokens are refused outright. They are signed with the same
+ * secret, so they verify here, but they mean something this middleware has no
+ * way to honour: an assistant acting within scopes, pinned to one tenant.
+ * Routes that software may legitimately reach use `authenticateAgent`, which
+ * enforces both — so anything still guarded by this one is a person's to do,
+ * and letting a token through would be handing an assistant the account.
  */
 export function authenticateToken(req: Request, res: Response, next: NextFunction): void {
   try {
@@ -19,7 +27,16 @@ export function authenticateToken(req: Request, res: Response, next: NextFunctio
       return;
     }
 
-    const user = jwt.verify(token, JWT_SECRET) as UserPayload;
+    const claims = jwt.verify(token, JWT_SECRET);
+    if (isAccessTokenClaims(claims)) {
+      res.status(403).json({
+        success: false,
+        message: 'This operation requires an interactive session, not a connected assistant'
+      });
+      return;
+    }
+
+    const user = claims as UserPayload;
     req.user = user;
     req.userGroups = user.groups ?? [];
     next();
@@ -46,9 +63,14 @@ export function optionalAuth(req: Request, _res: Response, next: NextFunction):
     const token = req.cookies?.access_token || req.headers.authorization?.replace('Bearer ', '');
 
     if (token) {
-      const user = jwt.verify(token, JWT_SECRET) as UserPayload;
-      req.user = user;
-      req.userGroups = user.groups ?? [];
+      const claims = jwt.verify(token, JWT_SECRET);
+      // An access token is not a session; treated as none, exactly like an
+      // expired cookie, so the route still answers with its public form.
+      if (!isAccessTokenClaims(claims)) {
+        const user = claims as UserPayload;
+        req.user = user;
+        req.userGroups = user.groups ?? [];
+      }
     }
   } catch {
     // Deliberately ignored — see above.

package/src/oauth/index.ts

@@ -19,5 +19,11 @@ export type {
   CodeRejection,
   RefreshRedemption
 } from './service';
-export { mintAccessToken, verifyAccessToken, parseScopes } from './tokens';
+export {
+  mintAccessToken,
+  verifyAccessToken,
+  parseScopes,
+  isAccessTokenClaims,
+  ACCESS_TOKEN_TYPE
+} from './tokens';
 export type { AccessTokenClaims, MintAccessTokenInput, MintedAccessToken, AccessTokenVerification } from './tokens';

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' }
     });
   });
 

package/src/oauth/service.ts

@@ -1,6 +1,11 @@
 import { createHash, randomBytes, timingSafeEqual } from 'crypto';
 import { AuthorizationCode, IAuthorizationCode, OAuthClient, RefreshToken } from './models';
-import type { ApiKeyScope } from '../apiKeys/types';
+import {
+  readTenants,
+  type ApiKeyScope,
+  type ApiKeyTenant,
+  type Tenant
+} from '../apiKeys/types';
 
 /** How long a user has between approving and the client exchanging the code. */
 const CODE_TTL_MS = 60 * 1000;
@@ -84,7 +89,9 @@ export interface IssueCodeInput {
   userName: string;
   redirectUri: string;
   scopes: ApiKeyScope[];
-  groupId: string | null;
+  tenants: Tenant[];
+  defaultTenant: Tenant;
+  tenantNames: Record<Tenant, string>;
   resource: string;
   codeChallenge: string;
 }
@@ -166,7 +173,9 @@ export const issueRefreshToken = async (input: {
   clientId: string;
   userId: string;
   scopes: ApiKeyScope[];
-  groupId: string | null;
+  tenants: Tenant[];
+  defaultTenant: Tenant;
+  tenantNames: Record<Tenant, string>;
   resource: string;
 }): Promise<IssuedRefreshToken> => {
   await RefreshToken.updateMany(
@@ -185,7 +194,8 @@ export interface RefreshRedemption {
   reused?: boolean;
   userId?: string;
   scopes?: ApiKeyScope[];
-  groupId?: string | null;
+  tenants?: ApiKeyTenant;
+  tenantNames?: Record<Tenant, string>;
   resource?: string;
   /** the replacement the client must store; the presented one is now dead */
   rotatedToken?: string;
@@ -233,7 +243,11 @@ export const redeemRefreshToken = async (
     clientId,
     userId: record.userId,
     scopes: record.scopes,
-    groupId: record.groupId ?? null,
+    // Carried, not reset: rotation reissues the same grant, and re-deriving the
+    // tenants would quietly narrow a connection every time it refreshed.
+    tenants: record.tenants,
+    defaultTenant: record.defaultTenant,
+    tenantNames: record.tenantNames,
     resource: record.resource,
     // Carried, not reset: this is still the grant the user approved.
     grantedAt: record.grantedAt ?? record.createdAt
@@ -243,7 +257,8 @@ export const redeemRefreshToken = async (
     ok: true,
     userId: record.userId,
     scopes: record.scopes as ApiKeyScope[],
-    groupId: record.groupId ?? null,
+    tenants: readTenants(record),
+    tenantNames: record.tenantNames ?? {},
     resource: record.resource,
     rotatedToken: rotated
   };
@@ -271,7 +286,10 @@ export const listConnections = async (userId: string) => {
     clientId: token.clientId,
     clientName: nameById.get(token.clientId) ?? 'Unknown app',
     scopes: token.scopes,
-    groupId: token.groupId ?? null,
+    ...(({ allowed, default: fallback }) => ({ tenants: allowed, defaultTenant: fallback }))(
+      readTenants(token)
+    ),
+    tenantNames: token.tenantNames ?? {},
     createdAt: (token.grantedAt ?? token.createdAt).toISOString(),
     // Set when the refresh token is exchanged, not when a tool runs — access
     // tokens are validated statelessly, so the server never sees ordinary use.

package/src/oauth/tokens.test.ts

@@ -1,6 +1,7 @@
 const ORIGINAL_ENV = process.env;
 
 import jwt from 'jsonwebtoken';
+import { PERSONAL_TENANT } from '../apiKeys/types';
 import { mintAccessToken, verifyAccessToken, parseScopes } from './tokens';
 
 const RESOURCE = 'https://mcp.tumbaland.eu';
@@ -14,7 +15,9 @@ const mint = (over: Partial<Parameters<typeof mintAccessToken>[0]> = {}) =>
     resource: RESOURCE,
     issuer: ISSUER,
     scopes: ['relationship:read', 'relationship:write'],
-    groupId: null,
+    tenants: [PERSONAL_TENANT],
+    defaultTenant: PERSONAL_TENANT,
+    tenantNames: { [PERSONAL_TENANT]: 'My own data' },
     ...over
   });
 
@@ -38,9 +41,21 @@ describe('mintAccessToken', () => {
     expect(expiresIn).toBe(3600);
   });
 
-  it('carries the tenant pin, so a token cannot wander between groups', () => {
-    const claims = jwt.decode(mint({ groupId: 'g1' }).accessToken) as Record<string, unknown>;
-    expect(claims.groupId).toBe('g1');
+  it('carries the granted tenants, so a token cannot wander outside them', () => {
+    const claims = jwt.decode(
+      mint({ tenants: [PERSONAL_TENANT, 'g1'], defaultTenant: 'g1' }).accessToken
+    ) as Record<string, unknown>;
+
+    expect(claims.tenants).toEqual([PERSONAL_TENANT, 'g1']);
+    expect(claims.defaultTenant).toBe('g1');
+  });
+
+  it('carries what each tenant is called, since nothing downstream can look it up', () => {
+    const claims = jwt.decode(
+      mint({ tenants: ['g1'], defaultTenant: 'g1', tenantNames: { g1: 'Irja & Tom' } }).accessToken
+    ) as Record<string, unknown>;
+
+    expect(claims.tenantNames).toEqual({ g1: 'Irja & Tom' });
   });
 
   it('gives every token a distinct id', () => {
@@ -59,7 +74,7 @@ describe('verifyAccessToken', () => {
       userId: 'u1',
       email: 'u1@example.com',
       scopes: ['relationship:read', 'relationship:write'],
-      groupId: null
+      tenants: { allowed: [PERSONAL_TENANT], default: PERSONAL_TENANT }
     });
   });
 

package/src/oauth/tokens.ts

@@ -1,7 +1,13 @@
 import { randomUUID } from 'crypto';
 import jwt from 'jsonwebtoken';
 import { requireEnv } from '../config/env';
-import { isApiKeyScope, type ApiKeyScope } from '../apiKeys/types';
+import {
+  isApiKeyScope,
+  readTenants,
+  type ApiKeyScope,
+  type ApiKeyTenant,
+  type Tenant
+} from '../apiKeys/types';
 
 /**
  * Access tokens for the OAuth flow that lets an assistant connect to Tumbaland.
@@ -15,7 +21,7 @@ import { isApiKeyScope, type ApiKeyScope } from '../apiKeys/types';
  */
 
 /** Marks a token as issued by the OAuth flow, for the MCP resource specifically. */
-const TOKEN_TYPE = 'mcp_access';
+export const ACCESS_TOKEN_TYPE = 'mcp_access';
 
 /** Short enough that a leaked token is a small window, long enough to be usable. */
 const ACCESS_TOKEN_TTL_SECONDS = 60 * 60;
@@ -27,11 +33,25 @@ export interface AccessTokenClaims {
   aud: string;
   iss: string;
   scope: string;
-  /** the tenant the token is pinned to; null means the user's personal data */
-  groupId: string | null;
+  /** every tenant this token may act in */
+  tenants: Tenant[];
+  /** the one it acts in when a call names none */
+  defaultTenant: Tenant;
+  /**
+   * What each tenant is called, for a client that has to offer the choice.
+   *
+   * Carried on the token because the only place these names are known is the
+   * consent screen that rendered them, and the MCP server — which has to name
+   * the choice to a model — cannot reach group-service. A snapshot: a group
+   * renamed after the connection was made shows its old name until reconnect,
+   * which is the same trade the owner's name on an API key already makes.
+   */
+  tenantNames: Record<Tenant, string>;
+  /** the single tenant an older token was pinned to; read by `readTenants` */
+  groupId?: string | null;
   email: string;
   name: string;
-  typ: typeof TOKEN_TYPE;
+  typ: typeof ACCESS_TOKEN_TYPE;
   jti: string;
   exp: number;
   iat: number;
@@ -45,7 +65,9 @@ export interface MintAccessTokenInput {
   resource: string;
   issuer: string;
   scopes: ApiKeyScope[];
-  groupId: string | null;
+  tenants: Tenant[];
+  defaultTenant: Tenant;
+  tenantNames: Record<Tenant, string>;
 }
 
 export interface MintedAccessToken {
@@ -63,10 +85,12 @@ export const mintAccessToken = (input: MintAccessTokenInput): MintedAccessToken
       aud: input.resource,
       iss: input.issuer,
       scope,
-      groupId: input.groupId,
+      tenants: input.tenants,
+      defaultTenant: input.defaultTenant,
+      tenantNames: input.tenantNames,
       email: input.email,
       name: input.name,
-      typ: TOKEN_TYPE,
+      typ: ACCESS_TOKEN_TYPE,
       jti: randomUUID()
     },
     requireEnv('JWT_SECRET'),
@@ -83,7 +107,8 @@ export interface AccessTokenVerification {
   email?: string;
   name?: string;
   scopes?: ApiKeyScope[];
-  groupId?: string | null;
+  tenants?: ApiKeyTenant;
+  tenantNames?: Record<Tenant, string>;
 }
 
 /**
@@ -108,7 +133,7 @@ export const verifyAccessToken = (
     return { ok: false, rejection: expired ? 'expired' : 'bad-signature' };
   }
 
-  if (claims.typ !== TOKEN_TYPE) return { ok: false, rejection: 'wrong-type' };
+  if (!isAccessTokenClaims(claims)) return { ok: false, rejection: 'wrong-type' };
   if (claims.aud !== expectedAudience) return { ok: false, rejection: 'wrong-audience' };
   if (!claims.sub) return { ok: false, rejection: 'malformed' };
 
@@ -118,10 +143,25 @@ export const verifyAccessToken = (
     email: claims.email ?? '',
     name: claims.name ?? '',
     scopes: (claims.scope ?? '').split(' ').filter(isApiKeyScope),
-    groupId: claims.groupId ?? null
+    tenants: readTenants(claims),
+    tenantNames: claims.tenantNames ?? {}
   };
 };
 
+/**
+ * Tell an OAuth access token apart from an ordinary session JWT.
+ *
+ * They are signed with the same secret and arrive in the same header, so
+ * anything holding one has to ask which it got. Getting this wrong is not a
+ * subtle failure: read as a session, an access token has no `id` and no
+ * `groups`, so `req.user.id` lands as `undefined` and every scoped query goes
+ * out unbounded.
+ */
+export const isAccessTokenClaims = (claims: unknown): claims is AccessTokenClaims =>
+  typeof claims === 'object' &&
+  claims !== null &&
+  (claims as AccessTokenClaims).typ === ACCESS_TOKEN_TYPE;
+
 /** Parse a space-separated `scope` parameter, dropping anything we do not define. */
 export const parseScopes = (scope: unknown): ApiKeyScope[] =>
   typeof scope === 'string' ? scope.split(/\s+/).filter(isApiKeyScope) : [];