@tumbaland/backend-core 1.44.0 → 1.45.0

package/src/oauth/service.ts

@@ -1,299 +0,0 @@
-import { createHash, randomBytes, timingSafeEqual } from 'crypto';
-import { AuthorizationCode, IAuthorizationCode, OAuthClient, RefreshToken } from './models';
-import {
-  readTenants,
-  type ApiKeyScope,
-  type ApiKeyTenant,
-  type Tenant
-} 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[];
-}
-
-/**
- * Register a client, or hand back the one that is already registered.
- *
- * Clients re-register freely — the Claude app does it on every connect attempt
- * — and minting a fresh id each time left a user staring at three identical
- * "Claude" entries in their connected apps, only one of which any given
- * disconnect would cut off.
- *
- * Matching on the exact redirect URIs is what makes this safe. These are public
- * clients with no secret, so a `client_id` is an identifier rather than a
- * credential; anything presenting the same callback URL *is* the same
- * application, because that URL is what an authorization code gets delivered
- * to. A different app cannot claim it without already controlling it.
- */
-export const registerClient = async (input: RegisterClientInput): Promise<RegisteredClient> => {
-  const redirectUris = [...input.redirectUris].sort();
-
-  const existing = await OAuthClient.findOne({
-    redirectUris: { $size: redirectUris.length, $all: redirectUris }
-  });
-
-  const client =
-    existing ??
-    (await OAuthClient.create({
-      clientId: `tmb-client-${randomBytes(16).toString('hex')}`,
-      clientName: input.clientName.slice(0, 200),
-      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[];
-  tenants: Tenant[];
-  defaultTenant: Tenant;
-  tenantNames: Record<Tenant, string>;
-  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;
-}
-
-/**
- * Start a grant, replacing any the same client already held for this user.
- *
- * Reconnecting is a re-authorization, not a second connection: without this,
- * approving twice leaves two live grants, the newer scopes sitting beside the
- * older ones, and a disconnect that revokes only one of them.
- */
-export const issueRefreshToken = async (input: {
-  clientId: string;
-  userId: string;
-  scopes: ApiKeyScope[];
-  tenants: Tenant[];
-  defaultTenant: Tenant;
-  tenantNames: Record<Tenant, string>;
-  resource: string;
-}): Promise<IssuedRefreshToken> => {
-  await RefreshToken.updateMany(
-    { userId: input.userId, clientId: input.clientId, revokedAt: { $exists: false } },
-    { $set: { revokedAt: new Date() } }
-  );
-
-  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[];
-  tenants?: ApiKeyTenant;
-  tenantNames?: Record<Tenant, string>;
-  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,
-    // Carried, not reset: rotation reissues the same grant, and re-deriving the
-    // tenants would quietly narrow a connection every time it refreshed.
-    tenants: record.tenants,
-    defaultTenant: record.defaultTenant,
-    tenantNames: record.tenantNames,
-    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[],
-    tenants: readTenants(record),
-    tenantNames: record.tenantNames ?? {},
-    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,
-    ...(({ allowed, default: fallback }) => ({ tenants: allowed, defaultTenant: fallback }))(
-      readTenants(token)
-    ),
-    tenantNames: token.tenantNames ?? {},
-    createdAt: (token.grantedAt ?? token.createdAt).toISOString(),
-    // Set when the refresh token is exchanged, not when a tool runs — access
-    // tokens are validated statelessly, so the server never sees ordinary use.
-    lastRenewedAt: token.lastUsedAt?.toISOString() ?? null,
-    revokedAt: token.revokedAt?.toISOString() ?? null
-  }));
-};

package/src/oauth/tokens.test.ts

@@ -1,146 +0,0 @@
-const ORIGINAL_ENV = process.env;
-
-import jwt from 'jsonwebtoken';
-import { PERSONAL_TENANT } from '../apiKeys/types';
-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'],
-    tenants: [PERSONAL_TENANT],
-    defaultTenant: PERSONAL_TENANT,
-    tenantNames: { [PERSONAL_TENANT]: 'My own data' },
-    clientId: 'client-1',
-    clientName: 'Claude',
-    ...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 granted tenants, so a token cannot wander outside them', () => {
-    const claims = jwt.decode(
-      mint({ tenants: [PERSONAL_TENANT, 'g1'], defaultTenant: 'g1' }).accessToken
-    ) as Record<string, unknown>;
-
-    expect(claims.tenants).toEqual([PERSONAL_TENANT, 'g1']);
-    expect(claims.defaultTenant).toBe('g1');
-  });
-
-  it('carries what each tenant is called, since nothing downstream can look it up', () => {
-    const claims = jwt.decode(
-      mint({ tenants: ['g1'], defaultTenant: 'g1', tenantNames: { g1: 'Irja & Tom' } }).accessToken
-    ) as Record<string, unknown>;
-
-    expect(claims.tenantNames).toEqual({ g1: 'Irja & Tom' });
-  });
-
-  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'],
-      tenants: { allowed: [PERSONAL_TENANT], default: PERSONAL_TENANT }
-    });
-  });
-
-  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

@@ -1,186 +0,0 @@
-import { randomUUID } from 'crypto';
-import jwt from 'jsonwebtoken';
-import { requireEnv } from '../config/env';
-import {
-  isApiKeyScope,
-  readTenants,
-  type ApiKeyScope,
-  type ApiKeyTenant,
-  type Tenant
-} 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. */
-export const ACCESS_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;
-  /** every tenant this token may act in */
-  tenants: Tenant[];
-  /** the one it acts in when a call names none */
-  defaultTenant: Tenant;
-  /**
-   * What each tenant is called, for a client that has to offer the choice.
-   *
-   * Carried on the token because the only place these names are known is the
-   * consent screen that rendered them, and the MCP server — which has to name
-   * the choice to a model — cannot reach group-service. A snapshot: a group
-   * renamed after the connection was made shows its old name until reconnect,
-   * which is the same trade the owner's name on an API key already makes.
-   */
-  tenantNames: Record<Tenant, string>;
-  /** the single tenant an older token was pinned to; read by `readTenants` */
-  groupId?: string | null;
-  /**
-   * Which app this token was issued to.
-   *
-   * `jti` identifies the token and rotates every hour, so it cannot stand in for
-   * the connection — an audit trail built on it would show a different actor
-   * each time the assistant refreshed. The client id is stable for the life of
-   * the grant, and the name is snapshotted alongside it for the same reason the
-   * tenant names are: nothing downstream can look it up.
-   */
-  clientId: string;
-  clientName: string;
-  email: string;
-  name: string;
-  typ: typeof ACCESS_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[];
-  tenants: Tenant[];
-  defaultTenant: Tenant;
-  tenantNames: Record<Tenant, string>;
-  clientId: string;
-  clientName: string;
-}
-
-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,
-      tenants: input.tenants,
-      defaultTenant: input.defaultTenant,
-      tenantNames: input.tenantNames,
-      clientId: input.clientId,
-      clientName: input.clientName,
-      email: input.email,
-      name: input.name,
-      typ: ACCESS_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[];
-  tenants?: ApiKeyTenant;
-  tenantNames?: Record<Tenant, string>;
-  clientId?: string;
-  clientName?: string;
-}
-
-/**
- * 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 (!isAccessTokenClaims(claims)) 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),
-    tenants: readTenants(claims),
-    tenantNames: claims.tenantNames ?? {},
-    clientId: claims.clientId,
-    clientName: claims.clientName
-  };
-};
-
-/**
- * Tell an OAuth access token apart from an ordinary session JWT.
- *
- * They are signed with the same secret and arrive in the same header, so
- * anything holding one has to ask which it got. Getting this wrong is not a
- * subtle failure: read as a session, an access token has no `id` and no
- * `groups`, so `req.user.id` lands as `undefined` and every scoped query goes
- * out unbounded.
- */
-export const isAccessTokenClaims = (claims: unknown): claims is AccessTokenClaims =>
-  typeof claims === 'object' &&
-  claims !== null &&
-  (claims as AccessTokenClaims).typ === ACCESS_TOKEN_TYPE;
-
-/** 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) : [];

package/src/testing/serviceTestSetup.ts

@@ -1,17 +0,0 @@
-import { overrideSessionCheckForTests } from '../auth/session';
-import { overrideMembershipLookupForTests } from '../groups/membership';
-
-/**
- * Jest setup for service test suites: they sign session tokens without a
- * session and run with no database or group-service, so every token's session
- * counts as live and its `groups` claim stands in for group membership.
- * The session check itself is tested in backend-core (auth/session.test.ts).
- *
- * Loaded through the package's test-only entry point:
- *   setupFiles: ['@tumbaland/backend-core/testing']
- */
-overrideSessionCheckForTests(async () => true);
-
-// No group-service either: a test token's own `groups` claim is taken as the
-// person's membership. The live lookup is tested in groups/membership.test.ts.
-overrideMembershipLookupForTests(async (user) => user.groups ?? []);