@tumbaland/backend-core 1.35.0 → 1.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tumbaland/backend-core",
-  "version": "1.35.0",
+  "version": "1.37.0",
   "description": "Core shared functionality for Tumbaland backend services",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/apiKeys/middleware.test.ts

@@ -8,6 +8,7 @@ jest.mock('../logging/logger', () => ({
 
 import jwt from 'jsonwebtoken';
 import { verifyApiKey } from './service';
+import { mintAccessToken, type MintAccessTokenInput } from '../oauth/tokens';
 import { authenticateAgent, requireScope, denyApiKeys } from './middleware';
 
 const mockedVerify = verifyApiKey as jest.Mock;
@@ -351,3 +352,110 @@ 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'],
+      groupId: null,
+      ...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('is pinned to the tenant chosen at consent', async () => {
+    const request = withToken(mint({ groupId: '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({ groupId: '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();
+  });
+});

package/src/apiKeys/middleware.ts

@@ -2,10 +2,11 @@ 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 { isApiKeyScope, type ApiKeyScope } from './types';
 
 /**
  * Request-scoped facts about the key a request arrived on. Absent on ordinary
@@ -83,6 +84,60 @@ const applyTenantPin = (req: Request, groupId: string | null): boolean => {
   return true;
 };
 
+/** 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[];
+  groupId: string | null;
+}
+
+/**
+ * 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;
+  }
+
+  if (!applyTenantPin(req, credential.groupId)) {
+    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 pinned group, 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 };
+
+  next();
+}
+
 /**
  * Authenticate a request that software may legitimately be making.
  *
@@ -104,14 +159,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),
+        groupId: claims.groupId ?? null
+      });
       return;
     }
 
@@ -124,37 +205,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 ?? [],
+      groupId: result.groupId ?? null
+    });
   };
 
 /**
@@ -166,7 +224,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 +239,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 +248,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/middleware/authMiddleware.test.ts

@@ -1,6 +1,7 @@
 import { Request, Response } from 'express';
 import jwt from 'jsonwebtoken';
 import { authenticateToken, optionalAuth } from './authMiddleware';
+import { mintAccessToken } from '../oauth/tokens';
 import { UserPayload } from '../types/auth';
 
 function mockReq(overrides: Partial<Request> = {}): Request {
@@ -171,3 +172,51 @@ 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'],
+      groupId: null
+    }).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();
+  });
+});

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/service.test.ts

@@ -39,11 +39,43 @@ const storedCode = (over: Record<string, unknown> = {}) => ({
 beforeEach(() => {
   jest.clearAllMocks();
   mockedClientCreate.mockImplementation(async (doc) => doc);
+  (OAuthClient.findOne as jest.Mock).mockResolvedValue(null);
   mockedCodeCreate.mockImplementation(async (doc) => doc);
   mockedRefreshCreate.mockImplementation(async (doc) => doc);
 });
 
 describe('registerClient', () => {
+  it('returns the existing client when the same callback re-registers', async () => {
+    // The Claude app re-registers on every connect attempt. Minting a fresh id
+    // each time left three identical "Claude" rows in connected apps, only one
+    // of which any given disconnect would cut off.
+    (OAuthClient.findOne as jest.Mock).mockResolvedValue({
+      clientId: 'tmb-client-existing',
+      clientName: 'Claude',
+      redirectUris: ['https://claude.ai/api/mcp/auth_callback']
+    });
+
+    const client = await registerClient({
+      clientName: 'Claude',
+      redirectUris: ['https://claude.ai/api/mcp/auth_callback']
+    });
+
+    expect(client.clientId).toBe('tmb-client-existing');
+    expect(mockedClientCreate).not.toHaveBeenCalled();
+  });
+
+  it('matches on the exact set of callbacks, which is what identifies the app', async () => {
+    (OAuthClient.findOne as jest.Mock).mockResolvedValue(null);
+
+    await registerClient({ clientName: 'Claude', redirectUris: ['https://b/cb', 'https://a/cb'] });
+
+    // Sorted and size-constrained: a client registering a superset is a
+    // different client, and an authorization code is delivered to that URL.
+    expect((OAuthClient.findOne as jest.Mock).mock.calls[0][0]).toEqual({
+      redirectUris: { $size: 2, $all: ['https://a/cb', 'https://b/cb'] }
+    });
+  });
+
   it('issues a namespaced client id and keeps the redirect URIs', async () => {
     const client = await registerClient({
       clientName: 'Claude',
@@ -181,6 +213,29 @@ describe('redeemAuthorizationCode', () => {
   });
 });
 
+describe('issueRefreshToken', () => {
+  it('retires any grant the same client already held for this user', async () => {
+    // Reconnecting is a re-authorization, not a second connection: two live
+    // grants would leave stale scopes beside the new ones and a disconnect
+    // that only cut one of them.
+    mockedRefreshUpdateMany.mockResolvedValue({ modifiedCount: 1 });
+
+    await issueRefreshToken({
+      clientId: 'client-1',
+      userId: 'u1',
+      scopes: ['relationship:read'],
+      groupId: null,
+      resource: 'https://mcp.tumbaland.eu'
+    });
+
+    expect(mockedRefreshUpdateMany).toHaveBeenCalledWith(
+      { userId: 'u1', clientId: 'client-1', revokedAt: { $exists: false } },
+      { $set: { revokedAt: expect.any(Date) } }
+    );
+    expect(mockedRefreshCreate).toHaveBeenCalled();
+  });
+});
+
 describe('refresh token rotation', () => {
   it('retires the presented token and issues a replacement', async () => {
     const record = {

package/src/oauth/service.ts

@@ -29,13 +29,35 @@ export interface RegisteredClient {
   redirectUris: string[];
 }
 
+/**
+ * Register a client, or hand back the one that is already registered.
+ *
+ * Clients re-register freely — the Claude app does it on every connect attempt
+ * — and minting a fresh id each time left a user staring at three identical
+ * "Claude" entries in their connected apps, only one of which any given
+ * disconnect would cut off.
+ *
+ * Matching on the exact redirect URIs is what makes this safe. These are public
+ * clients with no secret, so a `client_id` is an identifier rather than a
+ * credential; anything presenting the same callback URL *is* the same
+ * application, because that URL is what an authorization code gets delivered
+ * to. A different app cannot claim it without already controlling it.
+ */
 export const registerClient = async (input: RegisterClientInput): Promise<RegisteredClient> => {
-  const client = await OAuthClient.create({
-    clientId: `tmb-client-${randomBytes(16).toString('hex')}`,
-    clientName: input.clientName.slice(0, 200),
-    redirectUris: input.redirectUris
+  const redirectUris = [...input.redirectUris].sort();
+
+  const existing = await OAuthClient.findOne({
+    redirectUris: { $size: redirectUris.length, $all: redirectUris }
   });
 
+  const client =
+    existing ??
+    (await OAuthClient.create({
+      clientId: `tmb-client-${randomBytes(16).toString('hex')}`,
+      clientName: input.clientName.slice(0, 200),
+      redirectUris
+    }));
+
   return {
     clientId: client.clientId,
     clientName: client.clientName,
@@ -133,6 +155,13 @@ export interface IssuedRefreshToken {
   token: string;
 }
 
+/**
+ * Start a grant, replacing any the same client already held for this user.
+ *
+ * Reconnecting is a re-authorization, not a second connection: without this,
+ * approving twice leaves two live grants, the newer scopes sitting beside the
+ * older ones, and a disconnect that revokes only one of them.
+ */
 export const issueRefreshToken = async (input: {
   clientId: string;
   userId: string;
@@ -140,6 +169,11 @@ export const issueRefreshToken = async (input: {
   groupId: string | null;
   resource: string;
 }): Promise<IssuedRefreshToken> => {
+  await RefreshToken.updateMany(
+    { userId: input.userId, clientId: input.clientId, revokedAt: { $exists: false } },
+    { $set: { revokedAt: new Date() } }
+  );
+
   const token = randomBytes(32).toString('base64url');
   await RefreshToken.create({ ...input, tokenHash: sha256(token) });
   return { token };
@@ -239,7 +273,9 @@ export const listConnections = async (userId: string) => {
     scopes: token.scopes,
     groupId: token.groupId ?? null,
     createdAt: (token.grantedAt ?? token.createdAt).toISOString(),
-    lastUsedAt: token.lastUsedAt?.toISOString() ?? null,
+    // Set when the refresh token is exchanged, not when a tool runs — access
+    // tokens are validated statelessly, so the server never sees ordinary use.
+    lastRenewedAt: token.lastUsedAt?.toISOString() ?? null,
     revokedAt: token.revokedAt?.toISOString() ?? null
   }));
 };

package/src/oauth/tokens.ts

@@ -15,7 +15,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;
@@ -31,7 +31,7 @@ export interface AccessTokenClaims {
   groupId: string | null;
   email: string;
   name: string;
-  typ: typeof TOKEN_TYPE;
+  typ: typeof ACCESS_TOKEN_TYPE;
   jti: string;
   exp: number;
   iat: number;
@@ -66,7 +66,7 @@ export const mintAccessToken = (input: MintAccessTokenInput): MintedAccessToken
       groupId: input.groupId,
       email: input.email,
       name: input.name,
-      typ: TOKEN_TYPE,
+      typ: ACCESS_TOKEN_TYPE,
       jti: randomUUID()
     },
     requireEnv('JWT_SECRET'),
@@ -108,7 +108,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' };
 
@@ -122,6 +122,20 @@ export const verifyAccessToken = (
   };
 };
 
+/**
+ * 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) : [];