@tumbaland/backend-core 1.43.0 → 1.45.0

package/src/oauth/models.ts

@@ -1,164 +0,0 @@
-import mongoose, { Document, Schema } from 'mongoose';
-import { auditPlugin } from '../audit/plugin';
-import { PERSONAL_TENANT, type Tenant } from '../apiKeys/types';
-
-/**
- * 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[];
-  /** every tenant the user approved, and the one chosen as the default */
-  tenants: Tenant[];
-  defaultTenant: Tenant;
-  /** what each approved tenant is called, snapshotted at consent */
-  tenantNames: Record<Tenant, string>;
-  /** the single tenant an older grant was pinned to; read by `readTenants` */
-  groupId?: string | null;
-  /** RFC 8707: the MCP server this will be minted for */
-  resource: string;
-  /** PKCE, always S256 — the spec does not allow `plain` */
-  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: [] },
-    tenants: { type: [String], default: () => [PERSONAL_TENANT] },
-    defaultTenant: { type: String, default: PERSONAL_TENANT },
-    tenantNames: { type: Schema.Types.Mixed, default: () => ({}) },
-    // Written by the single-tenant model this replaced; read-only now.
-    groupId: { type: String, default: null },
-    resource: { type: String, required: true },
-    codeChallenge: { type: String, required: true },
-    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[];
-  tenants: Tenant[];
-  defaultTenant: Tenant;
-  tenantNames: Record<Tenant, string>;
-  /** the single tenant an older grant was pinned to; read by `readTenants` */
-  groupId?: string | null;
-  resource: string;
-  /**
-   * When the user actually connected this assistant.
-   *
-   * 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: [] },
-    tenants: { type: [String], default: () => [PERSONAL_TENANT] },
-    defaultTenant: { type: String, default: PERSONAL_TENANT },
-    tenantNames: { type: Schema.Types.Mixed, default: () => ({}) },
-    // Written by the single-tenant model this replaced; read-only now.
-    groupId: { type: String, default: null },
-    resource: { type: String, required: true },
-    grantedAt: { type: Date, default: Date.now },
-    revokedAt: { type: Date },
-    lastUsedAt: { type: Date }
-  },
-  { timestamps: true, collection: 'oauth_refresh_tokens' }
-);
-
-RefreshTokenSchema.index({ userId: 1, createdAt: -1 });
-
-/**
- * A grant appearing and being revoked is the shape of "who connected Claude,
- * and when did it stop" — the question the connections page answers for the
- * present and this answers for the past.
- *
- * `tokenHash` is redacted: it is the only thing standing between a copy of this
- * collection and a working refresh token.
- */
-RefreshTokenSchema.plugin(auditPlugin, { resource: 'connection', redact: ['tokenHash'] });
-
-export const RefreshToken = mongoose.models.RefreshToken
-  ? (mongoose.models.RefreshToken as mongoose.Model<IRefreshToken>)
-  : mongoose.model<IRefreshToken>('RefreshToken', RefreshTokenSchema);

package/src/oauth/service.test.ts

@@ -1,432 +0,0 @@
-import { createHash } from 'crypto';
-import { PERSONAL_TENANT } from '../apiKeys/types';
-
-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);
-  (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',
-      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'],
-      tenants: ['g1'],
-      defaultTenant: 'g1',
-      tenantNames: { g1: 'Irja & Tom' },
-      resource: 'https://mcp.tumbaland.eu',
-      codeChallenge: CHALLENGE
-    });
-
-    const [doc] = mockedCodeCreate.mock.calls[0];
-    expect(doc).toMatchObject({
-      userId: 'u1',
-      tenants: ['g1'],
-      defaultTenant: 'g1',
-      tenantNames: { g1: 'Irja & Tom' },
-      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('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'],
-      tenants: [PERSONAL_TENANT],
-      defaultTenant: PERSONAL_TENANT,
-      tenantNames: {},
-      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 = {
-      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'],
-      tenants: [PERSONAL_TENANT],
-      defaultTenant: PERSONAL_TENANT,
-      tenantNames: {},
-      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'],
-      tenants: [PERSONAL_TENANT, 'g1'],
-      defaultTenant: 'g1',
-      tenantNames: { g1: 'Irja & Tom' },
-      resource: 'https://mcp.tumbaland.eu',
-      grantedAt: new Date(),
-      save: jest.fn()
-    });
-
-    await expect(redeemRefreshToken('tok', 'client-1')).resolves.toMatchObject({
-      ok: true,
-      userId: 'u1',
-      tenants: { allowed: [PERSONAL_TENANT, 'g1'], default: 'g1' }
-    });
-  });
-
-  it('carries the tenants through rotation rather than re-deriving them', async () => {
-    mockedRefreshFindOne.mockResolvedValue({
-      userId: 'u1',
-      scopes: ['relationship:read'],
-      tenants: [PERSONAL_TENANT, 'g1'],
-      defaultTenant: 'g1',
-      tenantNames: { g1: 'Irja & Tom' },
-      resource: 'https://mcp.tumbaland.eu',
-      grantedAt: new Date(),
-      save: jest.fn()
-    });
-
-    await redeemRefreshToken('tok', 'client-1');
-
-    // Rotation reissues the same grant; re-deriving would quietly narrow a
-    // connection every time it refreshed.
-    const [doc] = mockedRefreshCreate.mock.calls.at(-1)!;
-    expect(doc.tenants).toEqual([PERSONAL_TENANT, 'g1']);
-    expect(doc.defaultTenant).toBe('g1');
-    expect(doc.tenantNames).toEqual({ g1: 'Irja & Tom' });
-  });
-
-  it('reads a grant issued before tenants were a set', async () => {
-    mockedRefreshFindOne.mockResolvedValue({
-      userId: 'u1',
-      scopes: ['relationship:read'],
-      groupId: 'g1',
-      resource: 'https://mcp.tumbaland.eu',
-      grantedAt: new Date(),
-      save: jest.fn()
-    });
-
-    await expect(redeemRefreshToken('tok', 'client-1')).resolves.toMatchObject({
-      tenants: { allowed: ['g1'], default: 'g1' }
-    });
-  });
-
-  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()
-    );
-  });
-});