@tumbaland/backend-core 1.33.0 → 1.35.0

package/dist/oauth/tokens.d.ts

@@ -0,0 +1,69 @@
+import { type ApiKeyScope } from '../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. */
+declare const TOKEN_TYPE = "mcp_access";
+export interface AccessTokenClaims {
+    /** the user the assistant is acting for */
+    sub: string;
+    /** the MCP server this token may be used against — RFC 8707 audience binding */
+    aud: string;
+    iss: string;
+    scope: string;
+    /** the tenant the token is pinned to; null means the user's personal data */
+    groupId: string | null;
+    email: string;
+    name: string;
+    typ: typeof TOKEN_TYPE;
+    jti: string;
+    exp: number;
+    iat: number;
+}
+export interface MintAccessTokenInput {
+    userId: string;
+    email: string;
+    name: string;
+    /** the canonical URI of the MCP server the token is for */
+    resource: string;
+    issuer: string;
+    scopes: ApiKeyScope[];
+    groupId: string | null;
+}
+export interface MintedAccessToken {
+    accessToken: string;
+    expiresIn: number;
+    scope: string;
+}
+export declare const mintAccessToken: (input: MintAccessTokenInput) => MintedAccessToken;
+export interface AccessTokenVerification {
+    ok: boolean;
+    rejection?: 'malformed' | 'expired' | 'wrong-audience' | 'wrong-type' | 'bad-signature';
+    userId?: string;
+    email?: string;
+    name?: string;
+    scopes?: ApiKeyScope[];
+    groupId?: string | null;
+}
+/**
+ * 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.
+ */
+export declare const verifyAccessToken: (token: string, expectedAudience: string) => AccessTokenVerification;
+/** Parse a space-separated `scope` parameter, dropping anything we do not define. */
+export declare const parseScopes: (scope: unknown) => ApiKeyScope[];
+export {};
+//# sourceMappingURL=tokens.d.ts.map

package/dist/oauth/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/oauth/tokens.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEnE;;;;;;;;;GASG;AAEH,oFAAoF;AACpF,QAAA,MAAM,UAAU,eAAe,CAAC;AAKhC,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,OAAO,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,eAAe,GAAI,OAAO,oBAAoB,KAAG,iBAoB7D,CAAC;AAEF,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,CAAC,EAAE,WAAW,GAAG,SAAS,GAAG,gBAAgB,GAAG,YAAY,GAAG,eAAe,CAAC;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAC5B,OAAO,MAAM,EACb,kBAAkB,MAAM,KACvB,uBAqBF,CAAC;AAEF,qFAAqF;AACrF,eAAO,MAAM,WAAW,GAAI,OAAO,OAAO,KAAG,WAAW,EACmB,CAAC"}

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.35.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/middleware/corsMiddleware.test.ts

@@ -94,3 +94,42 @@ describe('createCorsMiddleware', () => {
     process.env = ORIGINAL_ENV;
   });
 });
+
+describe('bypassPaths', () => {
+  const run = (middleware: ReturnType<typeof createCorsMiddleware>, path: string, origin?: string) => {
+    const req = { path, method: 'POST', headers: origin ? { origin } : {} } as never;
+    const res = { setHeader: jest.fn(), getHeader: jest.fn(), end: jest.fn() } as never;
+    const next = jest.fn();
+    middleware(req, res, next);
+    return next;
+  };
+
+  it('lets a bypassed path through with an origin that would otherwise be blocked', () => {
+    // Firefox sends a literal `Origin: null` on the consent form POST after the
+    // login redirect. It is truthy, matches no whitelist entry, and turned an
+    // approved consent into a 500.
+    const middleware = createCorsMiddleware({ origins: 'https://app.example', bypassPaths: ['/oauth'] });
+
+    const next = run(middleware, '/oauth/authorize', 'null');
+
+    expect(next).toHaveBeenCalledWith();
+  });
+
+  it('still checks the origin on every other path', () => {
+    const middleware = createCorsMiddleware({ origins: 'https://app.example', bypassPaths: ['/oauth'] });
+
+    const next = run(middleware, '/auth/profile', 'null');
+
+    expect(next).toHaveBeenCalledWith(expect.objectContaining({ message: expect.stringContaining('CORS') }));
+  });
+
+  it('matches by prefix, so nested oauth routes are covered too', () => {
+    const middleware = createCorsMiddleware({ origins: 'https://app.example', bypassPaths: ['/oauth'] });
+    expect(run(middleware, '/oauth/token', 'null')).toHaveBeenCalledWith();
+  });
+
+  it('changes nothing when no bypass is configured', () => {
+    const middleware = createCorsMiddleware({ origins: 'https://app.example' });
+    expect(run(middleware, '/oauth/authorize', 'null')).toHaveBeenCalledWith(expect.any(Error));
+  });
+});

package/src/middleware/corsMiddleware.ts

@@ -1,4 +1,5 @@
 import cors from 'cors';
+import type { RequestHandler } from 'express';
 import logger from '../logging/logger';
 
 export interface CorsMiddlewareOptions {
@@ -8,6 +9,21 @@ export interface CorsMiddlewareOptions {
    */
   origins?: string;
   exposedHeaders?: string[];
+  /**
+   * Path prefixes that skip the origin check entirely.
+   *
+   * For endpoints the browser *navigates* to rather than fetches — an OAuth
+   * authorize page and the consent form it posts back. CORS governs
+   * script-initiated cross-origin reads and has nothing to say about a
+   * top-level form submission, but it still blocks one: Firefox sends a
+   * literal `Origin: null` after a cross-site redirect chain, which is truthy,
+   * matches no whitelist entry, and turns a legitimate consent into a 500.
+   *
+   * Nothing is weakened by skipping them. These routes carry no XHR-readable
+   * data, and what actually protects the consent POST is its signed consent
+   * token, not the origin header.
+   */
+  bypassPaths?: string[];
 }
 
 /**
@@ -15,8 +31,10 @@ export interface CorsMiddlewareOptions {
  * Requests without an Origin header (server-to-server, curl, health checks)
  * are always allowed; browser requests must match the whitelist.
  */
-export function createCorsMiddleware(options: CorsMiddlewareOptions = {}) {
-  return cors({
+export function createCorsMiddleware(options: CorsMiddlewareOptions = {}): RequestHandler {
+  const bypassPaths = options.bypassPaths ?? [];
+
+  const corsHandler = cors({
     origin: (origin, callback) => {
       const allowedOrigins = (options.origins ?? process.env.CORS_ORIGIN ?? '')
         .split(',')
@@ -37,4 +55,11 @@ export function createCorsMiddleware(options: CorsMiddlewareOptions = {}) {
     allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With', 'x-correlation-id', 'x-session-id'],
     exposedHeaders: options.exposedHeaders
   });
+
+  if (bypassPaths.length === 0) return corsHandler as RequestHandler;
+
+  return (req, res, next) => {
+    if (bypassPaths.some((prefix) => req.path.startsWith(prefix))) return next();
+    return (corsHandler as RequestHandler)(req, res, next);
+  };
 }

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