@tumbaland/backend-core 1.32.0 → 1.34.0

package/src/oauth/service.test.ts

@@ -0,0 +1,325 @@
+import { createHash } from 'crypto';
+
+jest.mock('./models', () => ({
+  OAuthClient: { create: jest.fn(), findOne: jest.fn(), find: jest.fn() },
+  AuthorizationCode: { create: jest.fn(), findOneAndUpdate: jest.fn(), exists: jest.fn() },
+  RefreshToken: { create: jest.fn(), findOne: jest.fn(), find: jest.fn(), updateMany: jest.fn() }
+}));
+
+import { AuthorizationCode, OAuthClient, RefreshToken } from './models';
+import {
+  registerClient,
+  isRegisteredRedirect,
+  issueAuthorizationCode,
+  redeemAuthorizationCode,
+  issueRefreshToken,
+  redeemRefreshToken,
+  revokeRefreshTokensForUser
+} from './service';
+
+const mockedCodeUpdate = AuthorizationCode.findOneAndUpdate as unknown as jest.Mock;
+const mockedCodeExists = AuthorizationCode.exists as unknown as jest.Mock;
+const mockedCodeCreate = AuthorizationCode.create as unknown as jest.Mock;
+const mockedClientCreate = OAuthClient.create as unknown as jest.Mock;
+const mockedRefreshCreate = RefreshToken.create as unknown as jest.Mock;
+const mockedRefreshFindOne = RefreshToken.findOne as unknown as jest.Mock;
+const mockedRefreshUpdateMany = RefreshToken.updateMany as unknown as jest.Mock;
+
+const VERIFIER = 'a-code-verifier-long-enough-to-be-real';
+const CHALLENGE = createHash('sha256').update(VERIFIER).digest('base64url');
+
+const storedCode = (over: Record<string, unknown> = {}) => ({
+  clientId: 'client-1',
+  redirectUri: 'https://claude.ai/callback',
+  codeChallenge: CHALLENGE,
+  expiresAt: new Date(Date.now() + 30_000),
+  ...over
+});
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  mockedClientCreate.mockImplementation(async (doc) => doc);
+  mockedCodeCreate.mockImplementation(async (doc) => doc);
+  mockedRefreshCreate.mockImplementation(async (doc) => doc);
+});
+
+describe('registerClient', () => {
+  it('issues a namespaced client id and keeps the redirect URIs', async () => {
+    const client = await registerClient({
+      clientName: 'Claude',
+      redirectUris: ['https://claude.ai/callback']
+    });
+
+    expect(client.clientId).toMatch(/^tmb-client-[0-9a-f]{32}$/);
+    expect(client.redirectUris).toEqual(['https://claude.ai/callback']);
+  });
+
+  it('never issues the same id twice', async () => {
+    const a = await registerClient({ clientName: 'A', redirectUris: ['https://a/cb'] });
+    const b = await registerClient({ clientName: 'B', redirectUris: ['https://b/cb'] });
+    expect(a.clientId).not.toBe(b.clientId);
+  });
+});
+
+describe('isRegisteredRedirect', () => {
+  const client = { redirectUris: ['https://claude.ai/callback'] };
+
+  it('accepts a registered URI', () => {
+    expect(isRegisteredRedirect(client, 'https://claude.ai/callback')).toBe(true);
+  });
+
+  it.each([
+    ['a different host', 'https://evil.example/callback'],
+    ['a path suffix', 'https://claude.ai/callback/extra'],
+    ['an added query', 'https://claude.ai/callback?next=https://evil.example'],
+    ['a prefix', 'https://claude.ai/call']
+  ])('rejects %s — matching is exact, never prefix', (_label, uri) => {
+    // Loose redirect matching is the classic way an authorization code gets
+    // delivered somewhere the client never controlled.
+    expect(isRegisteredRedirect(client, uri)).toBe(false);
+  });
+});
+
+describe('issueAuthorizationCode', () => {
+  it('stores what was consented to, and expires within a minute', async () => {
+    const before = Date.now();
+    await issueAuthorizationCode({
+      clientId: 'client-1',
+      userId: 'u1',
+      userEmail: 'u1@example.com',
+      userName: 'Tester',
+      redirectUri: 'https://claude.ai/callback',
+      scopes: ['relationship:read'],
+      groupId: 'g1',
+      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.expiresAt.getTime() - before).toBeLessThanOrEqual(60_000);
+  });
+});
+
+describe('redeemAuthorizationCode', () => {
+  it('accepts a correct exchange', async () => {
+    mockedCodeUpdate.mockResolvedValue(storedCode());
+
+    const result = await redeemAuthorizationCode(
+      'code',
+      'client-1',
+      'https://claude.ai/callback',
+      VERIFIER
+    );
+
+    expect(result.ok).toBe(true);
+  });
+
+  it('marks the code used in the same operation that reads it', async () => {
+    mockedCodeUpdate.mockResolvedValue(storedCode());
+
+    await redeemAuthorizationCode('code', 'client-1', 'https://claude.ai/callback', VERIFIER);
+
+    // Atomic: two simultaneous exchanges cannot both win, which a
+    // read-then-check would allow.
+    expect(mockedCodeUpdate).toHaveBeenCalledWith(
+      { code: 'code', usedAt: { $exists: false } },
+      { $set: { usedAt: expect.any(Date) } },
+      { new: true }
+    );
+  });
+
+  it('refuses a code that has already been exchanged', async () => {
+    mockedCodeUpdate.mockResolvedValue(null);
+    mockedCodeExists.mockResolvedValue(true);
+
+    await expect(
+      redeemAuthorizationCode('code', 'client-1', 'https://claude.ai/callback', VERIFIER)
+    ).resolves.toEqual({ ok: false, rejection: 'already-used' });
+  });
+
+  it('refuses a code that never existed', async () => {
+    mockedCodeUpdate.mockResolvedValue(null);
+    mockedCodeExists.mockResolvedValue(false);
+
+    await expect(
+      redeemAuthorizationCode('code', 'client-1', 'https://claude.ai/callback', VERIFIER)
+    ).resolves.toEqual({ ok: false, rejection: 'unknown' });
+  });
+
+  it('refuses the wrong PKCE verifier', async () => {
+    // Without this, an intercepted code could be exchanged by whoever stole it.
+    mockedCodeUpdate.mockResolvedValue(storedCode());
+
+    await expect(
+      redeemAuthorizationCode('code', 'client-1', 'https://claude.ai/callback', 'wrong-verifier')
+    ).resolves.toEqual({ ok: false, rejection: 'pkce-failed' });
+  });
+
+  it('refuses a different client redeeming the code', async () => {
+    mockedCodeUpdate.mockResolvedValue(storedCode());
+
+    await expect(
+      redeemAuthorizationCode('code', 'other-client', 'https://claude.ai/callback', VERIFIER)
+    ).resolves.toEqual({ ok: false, rejection: 'client-mismatch' });
+  });
+
+  it('refuses a redirect URI that differs from the one authorized', async () => {
+    mockedCodeUpdate.mockResolvedValue(storedCode());
+
+    await expect(
+      redeemAuthorizationCode('code', 'client-1', 'https://evil.example/cb', VERIFIER)
+    ).resolves.toEqual({ ok: false, rejection: 'redirect-mismatch' });
+  });
+
+  it('refuses an expired code', async () => {
+    mockedCodeUpdate.mockResolvedValue(storedCode({ expiresAt: new Date(Date.now() - 1000) }));
+
+    await expect(
+      redeemAuthorizationCode('code', 'client-1', 'https://claude.ai/callback', VERIFIER)
+    ).resolves.toEqual({ ok: false, rejection: 'expired' });
+  });
+});
+
+describe('refresh token rotation', () => {
+  it('retires the presented token and issues a replacement', async () => {
+    const record = {
+      userId: 'u1',
+      scopes: ['relationship:read'],
+      groupId: null,
+      resource: 'https://mcp.tumbaland.eu',
+      grantedAt: new Date('2026-03-01T00:00:00.000Z'),
+      createdAt: new Date('2026-09-01T00:00:00.000Z'),
+      save: jest.fn()
+    } as Record<string, unknown>;
+    mockedRefreshFindOne.mockResolvedValue(record);
+
+    const result = await redeemRefreshToken('old-token', 'client-1');
+
+    // The old one is dead the moment it is used: a stolen copy stops working as
+    // soon as the honest client refreshes.
+    expect(record.revokedAt).toBeInstanceOf(Date);
+    expect(result.rotatedToken).toBeTruthy();
+    expect(result.rotatedToken).not.toBe('old-token');
+  });
+
+  it('carries the original grant date onto the replacement', async () => {
+    const grantedAt = new Date('2026-03-01T00:00:00.000Z');
+    mockedRefreshFindOne.mockResolvedValue({
+      userId: 'u1',
+      scopes: [],
+      groupId: null,
+      resource: 'r',
+      grantedAt,
+      save: jest.fn()
+    });
+
+    await redeemRefreshToken('old-token', 'client-1');
+
+    // Otherwise the UI would say the user connected an hour ago when they
+    // connected in March.
+    expect(mockedRefreshCreate.mock.calls[0][0].grantedAt).toBe(grantedAt);
+  });
+
+  it('treats reuse of a retired token as a compromise and cuts the whole grant', async () => {
+    // Honest client and thief now both hold tokens from one grant and there is
+    // no way to tell which just called, so everything goes.
+    mockedRefreshFindOne.mockResolvedValue({
+      userId: 'u1',
+      revokedAt: new Date(),
+      scopes: [],
+      groupId: null,
+      resource: 'r',
+      save: jest.fn()
+    });
+    mockedRefreshUpdateMany.mockResolvedValue({ modifiedCount: 1 });
+
+    const result = await redeemRefreshToken('retired-token', 'client-1');
+
+    expect(result).toMatchObject({ ok: false, reused: true });
+    expect(mockedRefreshUpdateMany).toHaveBeenCalledWith(
+      { userId: 'u1', clientId: 'client-1', revokedAt: { $exists: false } },
+      { $set: { revokedAt: expect.any(Date) } }
+    );
+  });
+
+  it('does not report an unknown token as reuse', async () => {
+    mockedRefreshFindOne.mockResolvedValue(null);
+    await expect(redeemRefreshToken('nope', 'client-1')).resolves.toEqual({ ok: false });
+    expect(mockedRefreshUpdateMany).not.toHaveBeenCalled();
+  });
+});
+
+describe('refresh tokens', () => {
+  it('stores only a digest, never the token itself', async () => {
+    const { token } = await issueRefreshToken({
+      clientId: 'client-1',
+      userId: 'u1',
+      scopes: ['relationship:read'],
+      groupId: null,
+      resource: 'https://mcp.tumbaland.eu'
+    });
+
+    const [doc] = mockedRefreshCreate.mock.calls[0];
+    expect(doc.tokenHash).toBe(createHash('sha256').update(token).digest('hex'));
+    expect(JSON.stringify(doc)).not.toContain(token);
+  });
+
+  it('looks a token up by digest and returns what it may do', 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({
+      ok: true,
+      userId: 'u1',
+      groupId: 'g1'
+    });
+  });
+
+  it('refuses a revoked token, which is how an assistant is cut off', async () => {
+    mockedRefreshFindOne.mockResolvedValue({
+      userId: 'u1',
+      revokedAt: new Date(),
+      scopes: [],
+      groupId: null,
+      resource: 'r',
+      save: jest.fn()
+    });
+    mockedRefreshUpdateMany.mockResolvedValue({ modifiedCount: 0 });
+
+    await expect(redeemRefreshToken('tok', 'client-1')).resolves.toMatchObject({ ok: false });
+  });
+
+  it('refuses an unknown token', async () => {
+    mockedRefreshFindOne.mockResolvedValue(null);
+    await expect(redeemRefreshToken('tok', 'client-1')).resolves.toEqual({ ok: false });
+  });
+
+  it('revokes only tokens that are still live', async () => {
+    mockedRefreshUpdateMany.mockResolvedValue({ modifiedCount: 2 });
+
+    await revokeRefreshTokensForUser('u1');
+
+    expect(mockedRefreshUpdateMany).toHaveBeenCalledWith(
+      { userId: 'u1', revokedAt: { $exists: false } },
+      { $set: { revokedAt: expect.any(Date) } }
+    );
+  });
+
+  it('can cut off one assistant without touching the others', async () => {
+    mockedRefreshUpdateMany.mockResolvedValue({ modifiedCount: 1 });
+
+    await revokeRefreshTokensForUser('u1', 'client-1');
+
+    expect(mockedRefreshUpdateMany).toHaveBeenCalledWith(
+      expect.objectContaining({ clientId: 'client-1' }),
+      expect.anything()
+    );
+  });
+});

package/src/oauth/service.ts

@@ -0,0 +1,245 @@
+import { createHash, randomBytes, timingSafeEqual } from 'crypto';
+import { AuthorizationCode, IAuthorizationCode, OAuthClient, RefreshToken } from './models';
+import type { ApiKeyScope } from '../apiKeys/types';
+
+/** How long a user has between approving and the client exchanging the code. */
+const CODE_TTL_MS = 60 * 1000;
+
+const sha256 = (value: string): string => createHash('sha256').update(value).digest('hex');
+
+/** base64url of the SHA-256 digest, which is what PKCE `S256` specifies. */
+const s256 = (verifier: string): string =>
+  createHash('sha256').update(verifier).digest('base64url');
+
+const constantTimeEquals = (a: string, b: string): boolean => {
+  const left = Buffer.from(a);
+  const right = Buffer.from(b);
+  if (left.length !== right.length) return false;
+  return timingSafeEqual(left, right);
+};
+
+export interface RegisterClientInput {
+  clientName: string;
+  redirectUris: string[];
+}
+
+export interface RegisteredClient {
+  clientId: string;
+  clientName: string;
+  redirectUris: string[];
+}
+
+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
+  });
+
+  return {
+    clientId: client.clientId,
+    clientName: client.clientName,
+    redirectUris: client.redirectUris
+  };
+};
+
+export const findClient = (clientId: string) => OAuthClient.findOne({ clientId });
+
+/**
+ * Whether a client may be sent back to this URI.
+ *
+ * Exact string match, deliberately. Prefix or wildcard matching on redirect URIs
+ * is the classic way an authorization code ends up delivered to somewhere the
+ * client never controlled.
+ */
+export const isRegisteredRedirect = (client: { redirectUris: string[] }, uri: string): boolean =>
+  client.redirectUris.includes(uri);
+
+export interface IssueCodeInput {
+  clientId: string;
+  userId: string;
+  userEmail: string;
+  userName: string;
+  redirectUri: string;
+  scopes: ApiKeyScope[];
+  groupId: string | null;
+  resource: string;
+  codeChallenge: string;
+}
+
+export const issueAuthorizationCode = async (input: IssueCodeInput): Promise<string> => {
+  const code = randomBytes(32).toString('base64url');
+
+  await AuthorizationCode.create({
+    ...input,
+    code,
+    expiresAt: new Date(Date.now() + CODE_TTL_MS)
+  });
+
+  return code;
+};
+
+export type CodeRejection =
+  | 'unknown'
+  | 'expired'
+  | 'already-used'
+  | 'client-mismatch'
+  | 'redirect-mismatch'
+  | 'pkce-failed';
+
+export interface CodeRedemption {
+  ok: boolean;
+  rejection?: CodeRejection;
+  code?: IAuthorizationCode;
+}
+
+/**
+ * Exchange a code, once.
+ *
+ * The `usedAt` stamp is set by the same atomic update that fetches the code, so
+ * two simultaneous exchanges cannot both succeed — a replayed code loses the
+ * race rather than being caught by a check that ran a moment earlier.
+ */
+export const redeemAuthorizationCode = async (
+  code: string,
+  clientId: string,
+  redirectUri: string,
+  codeVerifier: string
+): Promise<CodeRedemption> => {
+  const record = await AuthorizationCode.findOneAndUpdate(
+    { code, usedAt: { $exists: false } },
+    { $set: { usedAt: new Date() } },
+    { new: true }
+  );
+
+  if (!record) {
+    // Either it never existed or it has already been redeemed; the client is
+    // told the same thing for both.
+    const existed = await AuthorizationCode.exists({ code });
+    return { ok: false, rejection: existed ? 'already-used' : 'unknown' };
+  }
+
+  if (record.expiresAt.getTime() <= Date.now()) return { ok: false, rejection: 'expired' };
+  if (record.clientId !== clientId) return { ok: false, rejection: 'client-mismatch' };
+  if (record.redirectUri !== redirectUri) return { ok: false, rejection: 'redirect-mismatch' };
+  if (!constantTimeEquals(s256(codeVerifier), record.codeChallenge)) {
+    return { ok: false, rejection: 'pkce-failed' };
+  }
+
+  return { ok: true, code: record };
+};
+
+export interface IssuedRefreshToken {
+  token: string;
+}
+
+export const issueRefreshToken = async (input: {
+  clientId: string;
+  userId: string;
+  scopes: ApiKeyScope[];
+  groupId: string | null;
+  resource: string;
+}): Promise<IssuedRefreshToken> => {
+  const token = randomBytes(32).toString('base64url');
+  await RefreshToken.create({ ...input, tokenHash: sha256(token) });
+  return { token };
+};
+
+export interface RefreshRedemption {
+  ok: boolean;
+  /** true when a retired token was presented again — treated as a compromise */
+  reused?: boolean;
+  userId?: string;
+  scopes?: ApiKeyScope[];
+  groupId?: string | null;
+  resource?: string;
+  /** the replacement the client must store; the presented one is now dead */
+  rotatedToken?: string;
+}
+
+/**
+ * Exchange a refresh token for a new one, rotating as we go.
+ *
+ * Rotation matters because these are the long-lived half: an access token is
+ * gone within the hour, but a refresh token that never changes is a permanent
+ * credential for whoever obtains a copy. Each use retires the old token and
+ * issues a fresh one, so a stolen copy stops working as soon as the legitimate
+ * client refreshes.
+ *
+ * Reuse of an already-rotated token is treated as theft rather than as an
+ * ordinary failure: the honest client and the thief now both hold tokens
+ * descended from the same grant, and there is no way to tell which just called.
+ * So the whole chain is revoked and the user reconnects — noisy, but the
+ * alternative is leaving an attacker with working access.
+ */
+export const redeemRefreshToken = async (
+  token: string,
+  clientId: string
+): Promise<RefreshRedemption> => {
+  const record = await RefreshToken.findOne({ tokenHash: sha256(token), clientId });
+  if (!record) return { ok: false };
+
+  if (record.revokedAt) {
+    // Already rotated or explicitly revoked. If something is still presenting
+    // it, a copy is loose — cut every token in this grant.
+    await RefreshToken.updateMany(
+      { userId: record.userId, clientId, revokedAt: { $exists: false } },
+      { $set: { revokedAt: new Date() } }
+    );
+    return { ok: false, reused: true };
+  }
+
+  record.revokedAt = new Date();
+  record.lastUsedAt = new Date();
+  await record.save();
+
+  const rotated = randomBytes(32).toString('base64url');
+  await RefreshToken.create({
+    tokenHash: sha256(rotated),
+    clientId,
+    userId: record.userId,
+    scopes: record.scopes,
+    groupId: record.groupId ?? null,
+    resource: record.resource,
+    // Carried, not reset: this is still the grant the user approved.
+    grantedAt: record.grantedAt ?? record.createdAt
+  });
+
+  return {
+    ok: true,
+    userId: record.userId,
+    scopes: record.scopes as ApiKeyScope[],
+    groupId: record.groupId ?? null,
+    resource: record.resource,
+    rotatedToken: rotated
+  };
+};
+
+/** Cut off an assistant: without a refresh token it can obtain nothing new. */
+export const revokeRefreshTokensForUser = async (
+  userId: string,
+  clientId?: string
+): Promise<number> => {
+  const filter: Record<string, unknown> = { userId, revokedAt: { $exists: false } };
+  if (clientId) filter.clientId = clientId;
+
+  const result = await RefreshToken.updateMany(filter, { $set: { revokedAt: new Date() } });
+  return result.modifiedCount;
+};
+
+export const listConnections = async (userId: string) => {
+  const tokens = await RefreshToken.find({ userId }).sort({ createdAt: -1 });
+  const clients = await OAuthClient.find({ clientId: { $in: tokens.map((t) => t.clientId) } });
+  const nameById = new Map(clients.map((client) => [client.clientId, client.clientName]));
+
+  return tokens.map((token) => ({
+    id: String(token._id),
+    clientId: token.clientId,
+    clientName: nameById.get(token.clientId) ?? 'Unknown app',
+    scopes: token.scopes,
+    groupId: token.groupId ?? null,
+    createdAt: (token.grantedAt ?? token.createdAt).toISOString(),
+    lastUsedAt: token.lastUsedAt?.toISOString() ?? null,
+    revokedAt: token.revokedAt?.toISOString() ?? null
+  }));
+};

package/src/oauth/tokens.test.ts

@@ -0,0 +1,129 @@
+const ORIGINAL_ENV = process.env;
+
+import jwt from 'jsonwebtoken';
+import { mintAccessToken, verifyAccessToken, parseScopes } from './tokens';
+
+const RESOURCE = 'https://mcp.tumbaland.eu';
+const ISSUER = 'https://auth-api.tumbaland.eu';
+
+const mint = (over: Partial<Parameters<typeof mintAccessToken>[0]> = {}) =>
+  mintAccessToken({
+    userId: 'u1',
+    email: 'u1@example.com',
+    name: 'Tester',
+    resource: RESOURCE,
+    issuer: ISSUER,
+    scopes: ['relationship:read', 'relationship:write'],
+    groupId: null,
+    ...over
+  });
+
+beforeEach(() => {
+  process.env = { ...ORIGINAL_ENV, JWT_SECRET: 'test-jwt-secret' };
+});
+
+afterEach(() => {
+  process.env = ORIGINAL_ENV;
+});
+
+describe('mintAccessToken', () => {
+  it('binds the token to one resource and carries the granted scopes', () => {
+    const { accessToken, scope, expiresIn } = mint();
+    const claims = jwt.decode(accessToken) as Record<string, unknown>;
+
+    expect(claims.aud).toBe(RESOURCE);
+    expect(claims.iss).toBe(ISSUER);
+    expect(claims.sub).toBe('u1');
+    expect(scope).toBe('relationship:read relationship:write');
+    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('gives every token a distinct id', () => {
+    const a = jwt.decode(mint().accessToken) as Record<string, unknown>;
+    const b = jwt.decode(mint().accessToken) as Record<string, unknown>;
+    expect(a.jti).not.toBe(b.jti);
+  });
+});
+
+describe('verifyAccessToken', () => {
+  it('accepts a token minted for this resource', () => {
+    const { accessToken } = mint();
+
+    expect(verifyAccessToken(accessToken, RESOURCE)).toMatchObject({
+      ok: true,
+      userId: 'u1',
+      email: 'u1@example.com',
+      scopes: ['relationship:read', 'relationship:write'],
+      groupId: null
+    });
+  });
+
+  it('refuses a token minted for a different resource', () => {
+    // RFC 8707 audience binding: a token obtained for somewhere else must not
+    // be replayable here, which is the whole point of the resource parameter.
+    const { accessToken } = mint({ resource: 'https://mcp.someone-else.example' });
+
+    expect(verifyAccessToken(accessToken, RESOURCE)).toEqual({
+      ok: false,
+      rejection: 'wrong-audience'
+    });
+  });
+
+  it('refuses an ordinary session JWT presented as an access token', () => {
+    // Same secret, same issuer — but no scopes and no tenant pin. Without the
+    // type check a user's session cookie would authenticate as an assistant
+    // holding every permission.
+    const session = jwt.sign(
+      { id: 'u1', email: 'u1@example.com', name: 'Tester', groups: ['g1'] },
+      'test-jwt-secret'
+    );
+
+    expect(verifyAccessToken(session, RESOURCE)).toEqual({ ok: false, rejection: 'wrong-type' });
+  });
+
+  it('refuses a token signed with a different secret', () => {
+    const forged = jwt.sign({ sub: 'u1', aud: RESOURCE, typ: 'mcp_access' }, 'not-the-secret');
+    expect(verifyAccessToken(forged, RESOURCE)).toEqual({ ok: false, rejection: 'bad-signature' });
+  });
+
+  it('reports an expired token distinctly, so the client knows to refresh', () => {
+    const expired = jwt.sign(
+      { sub: 'u1', aud: RESOURCE, typ: 'mcp_access', scope: '' },
+      'test-jwt-secret',
+      { expiresIn: -10 }
+    );
+
+    expect(verifyAccessToken(expired, RESOURCE)).toEqual({ ok: false, rejection: 'expired' });
+  });
+
+  it('refuses gibberish rather than throwing', () => {
+    expect(verifyAccessToken('not-a-token', RESOURCE).ok).toBe(false);
+  });
+
+  it('drops scopes it does not define, so a forged claim grants nothing', () => {
+    const token = jwt.sign(
+      { sub: 'u1', aud: RESOURCE, typ: 'mcp_access', scope: 'relationship:read admin:everything' },
+      'test-jwt-secret'
+    );
+
+    expect(verifyAccessToken(token, RESOURCE).scopes).toEqual(['relationship:read']);
+  });
+});
+
+describe('parseScopes', () => {
+  it('keeps only scopes the system defines', () => {
+    expect(parseScopes('relationship:read admin:all finance:write')).toEqual([
+      'relationship:read',
+      'finance:write'
+    ]);
+  });
+
+  it.each([[undefined], [null], [42], ['']])('returns nothing for %s', (value) => {
+    expect(parseScopes(value)).toEqual([]);
+  });
+});