@tumbaland/backend-core 1.33.0 → 1.34.0

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

package/src/oauth/tokens.ts

@@ -0,0 +1,127 @@
+import { randomUUID } from 'crypto';
+import jwt from 'jsonwebtoken';
+import { requireEnv } from '../config/env';
+import { isApiKeyScope, 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. */
+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;
+
+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 const mintAccessToken = (input: MintAccessTokenInput): MintedAccessToken => {
+  const scope = input.scopes.join(' ');
+
+  const accessToken = jwt.sign(
+    {
+      sub: input.userId,
+      aud: input.resource,
+      iss: input.issuer,
+      scope,
+      groupId: input.groupId,
+      email: input.email,
+      name: input.name,
+      typ: TOKEN_TYPE,
+      jti: randomUUID()
+    },
+    requireEnv('JWT_SECRET'),
+    { expiresIn: ACCESS_TOKEN_TTL_SECONDS }
+  );
+
+  return { accessToken, expiresIn: ACCESS_TOKEN_TTL_SECONDS, scope };
+};
+
+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 const verifyAccessToken = (
+  token: string,
+  expectedAudience: string
+): AccessTokenVerification => {
+  let claims: AccessTokenClaims;
+  try {
+    claims = jwt.verify(token, requireEnv('JWT_SECRET')) as AccessTokenClaims;
+  } catch (error) {
+    const expired = (error as 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(isApiKeyScope),
+    groupId: claims.groupId ?? null
+  };
+};
+
+/** Parse a space-separated `scope` parameter, dropping anything we do not define. */
+export const parseScopes = (scope: unknown): ApiKeyScope[] =>
+  typeof scope === 'string' ? scope.split(/\s+/).filter(isApiKeyScope) : [];