@tumbaland/backend-core 1.33.0 → 1.34.0

package/dist/oauth/tokens.js

@@ -0,0 +1,79 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseScopes = exports.verifyAccessToken = exports.mintAccessToken = void 0;
+const crypto_1 = require("crypto");
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+const env_1 = require("../config/env");
+const types_1 = require("../apiKeys/types");
+/**
+ * Access tokens for the OAuth flow that lets an assistant connect to Tumbaland.
+ *
+ * These are JWTs rather than database rows so the MCP server can validate one
+ * without a query on every tool call, and because OAuth expects short-lived
+ * bearer tokens with a refresh path rather than the indefinite credentials an
+ * API key is. The trade is that a token cannot be revoked before it expires —
+ * hence the deliberately short life, with revocation applied at the refresh
+ * token, which is the thing that actually persists.
+ */
+/** Marks a token as issued by the OAuth flow, for the MCP resource specifically. */
+const 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;
+const mintAccessToken = (input) => {
+    const scope = input.scopes.join(' ');
+    const accessToken = jsonwebtoken_1.default.sign({
+        sub: input.userId,
+        aud: input.resource,
+        iss: input.issuer,
+        scope,
+        groupId: input.groupId,
+        email: input.email,
+        name: input.name,
+        typ: TOKEN_TYPE,
+        jti: (0, crypto_1.randomUUID)()
+    }, (0, env_1.requireEnv)('JWT_SECRET'), { expiresIn: ACCESS_TOKEN_TTL_SECONDS });
+    return { accessToken, expiresIn: ACCESS_TOKEN_TTL_SECONDS, scope };
+};
+exports.mintAccessToken = mintAccessToken;
+/**
+ * Check a bearer token presented to the MCP server.
+ *
+ * Two checks beyond the signature carry real weight. The audience must match
+ * this server: a token minted for one resource must not work against another,
+ * which is what RFC 8707 binding is for and what stops a token obtained for
+ * somewhere else being replayed here. And the type must be `mcp_access`, so an
+ * ordinary session JWT — same secret, same issuer, but no scopes and no tenant
+ * pin — cannot be presented as an access token and quietly get everything.
+ */
+const verifyAccessToken = (token, expectedAudience) => {
+    let claims;
+    try {
+        claims = jsonwebtoken_1.default.verify(token, (0, env_1.requireEnv)('JWT_SECRET'));
+    }
+    catch (error) {
+        const expired = error?.name === 'TokenExpiredError';
+        return { ok: false, rejection: expired ? 'expired' : 'bad-signature' };
+    }
+    if (claims.typ !== TOKEN_TYPE)
+        return { ok: false, rejection: 'wrong-type' };
+    if (claims.aud !== expectedAudience)
+        return { ok: false, rejection: 'wrong-audience' };
+    if (!claims.sub)
+        return { ok: false, rejection: 'malformed' };
+    return {
+        ok: true,
+        userId: claims.sub,
+        email: claims.email ?? '',
+        name: claims.name ?? '',
+        scopes: (claims.scope ?? '').split(' ').filter(types_1.isApiKeyScope),
+        groupId: claims.groupId ?? null
+    };
+};
+exports.verifyAccessToken = verifyAccessToken;
+/** Parse a space-separated `scope` parameter, dropping anything we do not define. */
+const parseScopes = (scope) => typeof scope === 'string' ? scope.split(/\s+/).filter(types_1.isApiKeyScope) : [];
+exports.parseScopes = parseScopes;
+//# sourceMappingURL=tokens.js.map

package/dist/oauth/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/oauth/tokens.ts"],"names":[],"mappings":";;;;;;AAAA,mCAAoC;AACpC,gEAA+B;AAC/B,uCAA2C;AAC3C,4CAAmE;AAEnE;;;;;;;;;GASG;AAEH,oFAAoF;AACpF,MAAM,UAAU,GAAG,YAAY,CAAC;AAEhC,oFAAoF;AACpF,MAAM,wBAAwB,GAAG,EAAE,GAAG,EAAE,CAAC;AAoClC,MAAM,eAAe,GAAG,CAAC,KAA2B,EAAqB,EAAE;IAChF,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAErC,MAAM,WAAW,GAAG,sBAAG,CAAC,IAAI,CAC1B;QACE,GAAG,EAAE,KAAK,CAAC,MAAM;QACjB,GAAG,EAAE,KAAK,CAAC,QAAQ;QACnB,GAAG,EAAE,KAAK,CAAC,MAAM;QACjB,KAAK;QACL,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,GAAG,EAAE,UAAU;QACf,GAAG,EAAE,IAAA,mBAAU,GAAE;KAClB,EACD,IAAA,gBAAU,EAAC,YAAY,CAAC,EACxB,EAAE,SAAS,EAAE,wBAAwB,EAAE,CACxC,CAAC;IAEF,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,wBAAwB,EAAE,KAAK,EAAE,CAAC;AACrE,CAAC,CAAC;AApBW,QAAA,eAAe,mBAoB1B;AAYF;;;;;;;;;GASG;AACI,MAAM,iBAAiB,GAAG,CAC/B,KAAa,EACb,gBAAwB,EACC,EAAE;IAC3B,IAAI,MAAyB,CAAC;IAC9B,IAAI,CAAC;QACH,MAAM,GAAG,sBAAG,CAAC,MAAM,CAAC,KAAK,EAAE,IAAA,gBAAU,EAAC,YAAY,CAAC,CAAsB,CAAC;IAC5E,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAI,KAAe,EAAE,IAAI,KAAK,mBAAmB,CAAC;QAC/D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,EAAE,CAAC;IACzE,CAAC;IAED,IAAI,MAAM,CAAC,GAAG,KAAK,UAAU;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;IAC7E,IAAI,MAAM,CAAC,GAAG,KAAK,gBAAgB;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,CAAC;IACvF,IAAI,CAAC,MAAM,CAAC,GAAG;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC;IAE9D,OAAO;QACL,EAAE,EAAE,IAAI;QACR,MAAM,EAAE,MAAM,CAAC,GAAG;QAClB,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,EAAE;QACzB,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,EAAE;QACvB,MAAM,EAAE,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,qBAAa,CAAC;QAC7D,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;KAChC,CAAC;AACJ,CAAC,CAAC;AAxBW,QAAA,iBAAiB,qBAwB5B;AAEF,qFAAqF;AAC9E,MAAM,WAAW,GAAG,CAAC,KAAc,EAAiB,EAAE,CAC3D,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,qBAAa,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAD/D,QAAA,WAAW,eACoD"}

package/jest.config.js

@@ -8,7 +8,17 @@ module.exports = {
     '^.+\\.ts$': ['ts-jest', { tsconfig: { types: ['jest', 'node'] } }]
   },
   coverageProvider: 'v8',
-  collectCoverageFrom: ['src/**/*.ts', '!src/**/*.test.ts', '!src/index.ts', '!src/types/**'],
+  // Barrels are excluded, not just the root one: a file of `export { x } from
+  // './y'` has no logic to test, but Jest counts every re-exported function as
+  // an uncovered one — which is what held global function coverage at ~78%
+  // while every module underneath was thoroughly tested.
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.test.ts',
+    '!src/index.ts',
+    '!src/**/index.ts',
+    '!src/types/**'
+  ],
   coverageReporters: ['text', 'json-summary'],
   coverageThreshold: { global: { statements: 90, branches: 80, functions: 90, lines: 90 } }
 };

package/package.json

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

package/src/index.ts

@@ -33,6 +33,9 @@ export * from './groups';
 // API keys (non-browser clients: MCP servers, scripts, agents)
 export * from './apiKeys';
 
+// OAuth 2.1 authorization server, for assistants connecting over MCP
+export * from './oauth';
+
 // Middleware
 export { authenticateToken, optionalAuth } from './middleware/authMiddleware';
 export {

package/src/oauth/index.ts

@@ -0,0 +1,23 @@
+export { OAuthClient, AuthorizationCode, RefreshToken } from './models';
+export type { IOAuthClient, IAuthorizationCode, IRefreshToken } from './models';
+export {
+  registerClient,
+  findClient,
+  isRegisteredRedirect,
+  issueAuthorizationCode,
+  redeemAuthorizationCode,
+  issueRefreshToken,
+  redeemRefreshToken,
+  revokeRefreshTokensForUser,
+  listConnections
+} from './service';
+export type {
+  RegisterClientInput,
+  RegisteredClient,
+  IssueCodeInput,
+  CodeRedemption,
+  CodeRejection,
+  RefreshRedemption
+} from './service';
+export { mintAccessToken, verifyAccessToken, parseScopes } from './tokens';
+export type { AccessTokenClaims, MintAccessTokenInput, MintedAccessToken, AccessTokenVerification } from './tokens';

package/src/oauth/models.ts

@@ -0,0 +1,134 @@
+import mongoose, { Document, Schema } from 'mongoose';
+
+/**
+ * A client registered through RFC 7591 Dynamic Client Registration.
+ *
+ * Assistants register themselves — nobody is going to pre-provision Claude,
+ * ChatGPT and Gemini by hand, and the MCP spec expects a server to accept
+ * registrations. Clients are public (no secret): the caller is a browser-driven
+ * flow that cannot keep one, which is exactly why PKCE is mandatory here.
+ */
+export interface IOAuthClient extends Document {
+  clientId: string;
+  clientName: string;
+  redirectUris: string[];
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+const OAuthClientSchema = new Schema<IOAuthClient>(
+  {
+    clientId: { type: String, required: true, unique: true, index: true },
+    clientName: { type: String, required: true, maxlength: 200 },
+    redirectUris: { type: [String], required: true }
+  },
+  { timestamps: true, collection: 'oauth_clients' }
+);
+
+export const OAuthClient = mongoose.models.OAuthClient
+  ? (mongoose.models.OAuthClient as mongoose.Model<IOAuthClient>)
+  : mongoose.model<IOAuthClient>('OAuthClient', OAuthClientSchema);
+
+/**
+ * A one-time authorization code, alive for the seconds between the user
+ * approving and the client exchanging it.
+ *
+ * Everything the token will assert is fixed here, at the moment consent is
+ * given: which scopes, which tenant, which resource. The exchange cannot widen
+ * any of it, so a client that asks for more at the token endpoint than the user
+ * agreed to gets what the user agreed to.
+ */
+export interface IAuthorizationCode extends Document {
+  code: string;
+  clientId: string;
+  userId: string;
+  userEmail: string;
+  userName: string;
+  redirectUri: string;
+  scopes: string[];
+  groupId: string | null;
+  /** RFC 8707: the MCP server this will be minted for */
+  resource: string;
+  /** PKCE, always S256 — the spec does not allow `plain` */
+  codeChallenge: string;
+  /** set once the code is exchanged, so a replay is detectable rather than silent */
+  usedAt?: Date;
+  expiresAt: Date;
+  createdAt: Date;
+}
+
+const AuthorizationCodeSchema = new Schema<IAuthorizationCode>(
+  {
+    code: { type: String, required: true, unique: true, index: true },
+    clientId: { type: String, required: true },
+    userId: { type: String, required: true },
+    userEmail: { type: String, required: true },
+    userName: { type: String, default: '' },
+    redirectUri: { type: String, required: true },
+    scopes: { type: [String], default: [] },
+    groupId: { type: String, default: null },
+    resource: { type: String, required: true },
+    codeChallenge: { type: String, required: true },
+    usedAt: { type: Date },
+    expiresAt: { type: Date, required: true }
+  },
+  { timestamps: { createdAt: true, updatedAt: false }, collection: 'oauth_authorization_codes' }
+);
+
+// Codes are short-lived and never read after expiry; let Mongo sweep them so a
+// replay cannot be attempted against a record nobody is cleaning up.
+AuthorizationCodeSchema.index({ expiresAt: 1 }, { expireAfterSeconds: 0 });
+
+export const AuthorizationCode = mongoose.models.AuthorizationCode
+  ? (mongoose.models.AuthorizationCode as mongoose.Model<IAuthorizationCode>)
+  : mongoose.model<IAuthorizationCode>('AuthorizationCode', AuthorizationCodeSchema);
+
+/**
+ * A refresh token: the part that actually persists, and therefore the part
+ * revocation acts on.
+ *
+ * Access tokens are unrevokable JWTs by design, kept short so that matters
+ * little. Cutting off an assistant means deleting its refresh token, after
+ * which it can obtain nothing new.
+ */
+export interface IRefreshToken extends Document {
+  tokenHash: string;
+  clientId: string;
+  userId: string;
+  scopes: string[];
+  groupId: string | null;
+  resource: string;
+  /**
+   * When the user actually connected this assistant.
+   *
+   * Distinct from `createdAt`, which rotation resets on every refresh — showing
+   * that in the UI would tell someone they connected Claude an hour ago when
+   * they did it in March.
+   */
+  grantedAt: Date;
+  revokedAt?: Date;
+  lastUsedAt?: Date;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+const RefreshTokenSchema = new Schema<IRefreshToken>(
+  {
+    tokenHash: { type: String, required: true, unique: true, index: true },
+    clientId: { type: String, required: true },
+    userId: { type: String, required: true, index: true },
+    scopes: { type: [String], default: [] },
+    groupId: { type: String, default: null },
+    resource: { type: String, required: true },
+    grantedAt: { type: Date, default: Date.now },
+    revokedAt: { type: Date },
+    lastUsedAt: { type: Date }
+  },
+  { timestamps: true, collection: 'oauth_refresh_tokens' }
+);
+
+RefreshTokenSchema.index({ userId: 1, createdAt: -1 });
+
+export const RefreshToken = mongoose.models.RefreshToken
+  ? (mongoose.models.RefreshToken as mongoose.Model<IRefreshToken>)
+  : mongoose.model<IRefreshToken>('RefreshToken', RefreshTokenSchema);

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()
+    );
+  });
+});