Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
21.8 KB
Raw Blame
/** OAuth grant lifecycle. Every grant mutation locks the same client row. */
import { createHash } from 'node:crypto';
import { redirectUriMatches } from '@modelcontextprotocol/sdk/server/auth/handlers/authorize.js';
import type { AuthorizationParams } from '@modelcontextprotocol/sdk/server/auth/provider.js';
import type { OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
import { InvalidClientError, InvalidGrantError, InvalidRequestError, InvalidTargetError, ServerError, TooManyRequestsError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
import type { SqlQuery } from './sql-query.ts';
import { generateToken, hashToken } from './utils.ts';
import { hasScope, parseScopeString } from './scope.ts';
import { TOKEN_TTL_MAX_SECONDS, intersectGrantedScopes } from './grants/model.ts';
import { safeHexEqual } from './timing-safe.ts';
import { isStalePlanError } from './retry-matcher.ts';
import { clientHoldsAuthorization, GrantError, recordFirstConsentInTransaction } from './grants/service.ts';

export type OAuthTransaction = <T>(fn: (sql: SqlQuery) => Promise<T>) => Promise<T>;
type ClientRow = Record<string, unknown>;
export function oauthPgArray(values: string[]): string {
  return `{${values.map(s => `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`).join(',')}}`;
}

function assertActive(row: ClientRow | undefined): asserts row is ClientRow {
  if (!row || row.deleted_at != null) throw new InvalidClientError('Invalid client or client has been revoked');
}

function grantScopes(row: ClientRow, requested?: string[]): string[] {
  const allowed = parseScopeString(row.scope as string | undefined);
  return (requested?.length ? requested : allowed).filter(scope => hasScope(allowed, scope));
}

/**
 * #5222 — the one RFC 8707 resource canonicalizer, shared by /authorize, code
 * exchange, refresh and bearer verification. `canonical` is the server's /mcp
 * resource, derived from the configured public URL and never from `Host` or
 * forwarded headers. The issuer origin is an alias of it (some clients send
 * the origin root even after reading the protected-resource metadata). URL
 * parsing normalizes scheme and host case and default ports; a trailing
 * slash is ignored. Anything else is `invalid_target`, naming the accepted
 * resource so the client fails loudly instead of looping on a token /mcp
 * will refuse.
 */
export function canonicalOAuthResource(requested: URL | string, canonical: URL): URL {
  const accepted = `use ${canonical.toString()} (or its origin ${canonical.origin})`;
  let url: URL;
  try {
    url = new URL(requested.toString());
  } catch {
    throw new InvalidTargetError(`Invalid resource; ${accepted}`);
  }
  const path = url.pathname.replace(/\/+$/, '');
  if (url.origin === canonical.origin && !url.username && !url.password && !url.search && !url.hash
    && (path === '' || path === canonical.pathname.replace(/\/+$/, ''))) {
    return new URL(canonical.toString());
  }
  throw new InvalidTargetError(`Resource ${url.toString()} is not served here; ${accepted}`);
}

/** Compare policy, not a mutable reference or only the display name. */
function policyDigest(row: ClientRow): string {
  const fields = ['client_id', 'client_name', 'redirect_uris', 'grant_types', 'scope',
    'client_secret_hash', 'token_endpoint_auth_method', 'client_secret_expires_at',
    'source_id', 'federated_read', 'bound_tools', 'bound_source_id', 'bound_brain_id',
    'bound_slug_prefixes', 'bound_max_concurrent', 'budget_usd_per_day', 'surface', 'token_ttl',
    'allowed_operations', 'delegated_slug_prefixes', 'delegated_namespace', 'grant_profile',
    'grant_revision', 'grant_repair_reasons', 'registered_via'];
  return hashToken(JSON.stringify(fields.map(field => row[field] ?? null)));
}

export interface OAuthConsentDetails {
  id: string;
  clientId: string;
  clientName: string;
  redirectUri: string;
  scopes: string[];
  sourceId: string | null;
  allowedSources: string[];
  resource: string | null;
  allowedOperations: string[] | null;
  boundSlugPrefixes: string[] | null;
  delegatedTools: string[] | null;
  delegatedSlugPrefixes: string[] | null;
  delegatedNamespace: string | null;
  expiresAt: number;
  /**
   * #6202: `editable` only for a self-registered client's first consent
   * (`registered_via='dcr'`, revision 0, no `client_credentials`, a source
   * grant); `options` are the active sources then, `[]` otherwise.
   */
  sourceChoice: { editable: boolean; options: Array<{ id: string; name: string }> };
}
interface PendingAuthorization {
  details: OAuthConsentDetails;
  params: AuthorizationParams;
  policy: string;
  status: 'pending' | 'processing' | 'approved' | 'denied' | 'failed';
}

export class OAuthConsentError extends Error {
  constructor(readonly status: number, readonly code: string, message: string) { super(message); }
}

/** Global ceiling on the in-memory pending store; a full store rejects new requests rather than evicting live ones. */
const MAX_PENDING_TOTAL = 1000;
/**
 * Per-client ceiling on requests still awaiting a decision. Without it a handful of callers could fill
 * the global store on behalf of one self-registered client; with it, no single client_id can consume
 * more than a sliver of the capacity every other client shares. Decided (approved/denied/failed) entries
 * stay in the store until expiry but do not count: only the owner can move a request out of `pending`.
 */
const MAX_PENDING_PER_CLIENT = 10;

export class OAuthGrants {
  private readonly pending = new Map<string, PendingAuthorization>();
  constructor(private readonly options: {
    sql: SqlQuery;
    transaction?: OAuthTransaction;
    tokenTtl: number;
    refreshTtl: number;
    now?: () => number;
    /** #5222: the canonical /mcp resource; unset keeps exact-match resource semantics. */
    resourceUrl?: URL;
  }) {}

  private canonicalResource(requested: URL | undefined): URL | undefined {
    if (!requested || !this.options.resourceUrl) return requested;
    return canonicalOAuthResource(requested, this.options.resourceUrl);
  }

  private now(): number { return (this.options.now ?? Date.now)(); }
  private async locked<T>(clientId: string, fn: (sql: SqlQuery, row: ClientRow) => Promise<T>): Promise<T> {
    const options = this.options;
    if (!options.transaction) throw new ServerError('OAuth grant transactions are unavailable');
    // GST-2260: a stale plan on the client read runs the transaction again. That read comes before the callback writes
    // anything, so the second run is safe even when the caller's transaction is not a real one (mcp-provision).
    let entered = false;
    const run = () => options.transaction!(async sql => {
      const [row] = await sql`SELECT * FROM oauth_clients WHERE client_id = ${clientId} FOR UPDATE`;
      entered = true;
      assertActive(row);
      return fn(sql, row);
    });
    try {
      return await run();
    } catch (error) {
      if (entered || !isStalePlanError(error)) throw error;
      return run();
    }
  }

  private prune(): void {
    const now = this.now();
    for (const [id, pending] of this.pending) {
      if (pending.details.expiresAt <= now) this.pending.delete(id);
    }
  }

  /** Synchronous: prune, then enforce the global and per-client ceilings. Callers must not await between this and the insert. */
  private assertCapacity(clientId: string): void {
    this.prune();
    if (this.pending.size >= MAX_PENDING_TOTAL) throw new TooManyRequestsError('Too many pending requests. Try again shortly.');
    let awaiting = 0;
    for (const pending of this.pending.values()) {
      if (pending.status === 'pending' && pending.details.clientId === clientId && ++awaiting >= MAX_PENDING_PER_CLIENT) {
        throw new TooManyRequestsError('Too many pending requests for this client. Complete or wait for an earlier request before starting another.');
      }
    }
  }

  async begin(clientId: string, params: AuthorizationParams): Promise<string> {
    const resource = this.canonicalResource(params.resource);
    this.assertCapacity(clientId);
    if (!/^[A-Za-z0-9_-]{43}$/.test(params.codeChallenge)) throw new InvalidRequestError('S256 PKCE challenge required');
    const [row] = await this.options.sql`SELECT * FROM oauth_clients WHERE client_id = ${clientId}`;
    assertActive(row);
    if (!Array.isArray(row.grant_types) || !row.grant_types.includes('authorization_code')) {
      throw new InvalidClientError('Authorization code grant not authorized for this client');
    }
    if (!Array.isArray(row.redirect_uris) || !row.redirect_uris.some(uri => typeof uri === 'string' && redirectUriMatches(params.redirectUri, uri))) {
      throw new InvalidRequestError('Redirect URI does not match registered client');
    }
    const editable = row.registered_via === 'dcr' && Number(row.grant_revision) === 0
      && !row.grant_types.includes('client_credentials') && row.source_grant !== 'none'
      && !await clientHoldsAuthorization(this.options.sql, clientId);
    const options = editable
      ? (await this.options.sql`SELECT id, name FROM sources WHERE archived = false ORDER BY id`).map(r => ({ id: String(r.id), name: String(r.name) }))
      : [];
    // No await between the capacity check and insert: concurrent DB reads cannot overfill the store or a client's budget.
    this.assertCapacity(clientId);
    const id = generateToken('');
    const details: OAuthConsentDetails = {
      id, clientId, clientName: typeof row.client_name === 'string' ? row.client_name : clientId,
      redirectUri: params.redirectUri, scopes: grantScopes(row, params.scopes),
      sourceId: typeof row.source_id === 'string' ? row.source_id : null,
      allowedSources: Array.isArray(row.federated_read) ? [...row.federated_read] as string[] : [],
      allowedOperations: Array.isArray(row.allowed_operations) ? [...row.allowed_operations] as string[] : null,
      boundSlugPrefixes: Array.isArray(row.bound_slug_prefixes) ? [...row.bound_slug_prefixes] as string[] : null,
      delegatedTools: Array.isArray(row.bound_tools) ? [...row.bound_tools] as string[] : null,
      delegatedSlugPrefixes: Array.isArray(row.delegated_slug_prefixes) ? [...row.delegated_slug_prefixes] as string[] : null,
      delegatedNamespace: typeof row.delegated_namespace === 'string' ? row.delegated_namespace : null,
      resource: resource?.toString() ?? null, expiresAt: this.now() + 10 * 60_000,
      sourceChoice: { editable, options },
    };
    this.pending.set(id, {
      details, params: { ...params, scopes: [...details.scopes], resource },
      policy: policyDigest(row), status: 'pending',
    });
    return id;
  }

  details(id: string): OAuthConsentDetails {
    this.prune();
    const pending = this.pending.get(id);
    if (!pending || pending.status !== 'pending') {
      throw new OAuthConsentError(410, 'authorization_unavailable', 'This request expired, was completed, or the server restarted. Restart the connection from your client.');
    }
    return structuredClone(pending.details);
  }

  hasPending(id: unknown): id is string {
    if (typeof id !== 'string' || !/^[a-f0-9]{64}$/.test(id)) return false;
    try { this.details(id); return true; } catch { return false; }
  }

  async decide(id: string, approve: boolean, choice?: { sourceId: string }): Promise<string> {
    const { sourceChoice } = this.details(id);
    if (choice !== undefined && (!approve || !sourceChoice.editable || !sourceChoice.options.some(o => o.id === choice.sourceId))) {
      // Refused before the claim: the request stays pending and the owner can reload it.
      throw new OAuthConsentError(403, 'invalid_consent', 'Reload this request and review it again before approving.');
    }
    const pending = this.pending.get(id)!;
    pending.status = 'processing'; // claim synchronously before the first await
    const redirect = new URL(pending.params.redirectUri);
    if (pending.params.state) redirect.searchParams.set('state', pending.params.state);
    if (!approve) {
      pending.status = 'denied';
      redirect.searchParams.set('error', 'access_denied');
      return redirect.toString();
    }
    try {
      const code = await this.locked(pending.details.clientId, async (sql, row) => {
        if (pending.details.expiresAt <= this.now()) throw new OAuthConsentError(410, 'authorization_expired', 'This request expired. Restart the connection from your client.');
        if (policyDigest(row) !== pending.policy) throw new OAuthConsentError(409, 'client_policy_changed', 'Client permissions changed. Restart the connection and review the new request.');
        if (sourceChoice.editable) {
          // The first consent always consumes eligibility (revision 0 → 1), with or without a new source.
          try {
            await recordFirstConsentInTransaction(sql, pending.details.clientId, choice?.sourceId, 'owner');
          } catch (error) {
            if (error instanceof GrantError) throw new OAuthConsentError(409, 'client_policy_changed', 'Client permissions changed. Restart the connection and review the new request.');
            throw error;
          }
        }
        const code = generateToken('gbrain_code_');
        await sql`
          INSERT INTO oauth_codes (code_hash, client_id, scopes, code_challenge,
            code_challenge_method, redirect_uri, state, resource, expires_at)
          VALUES (${hashToken(code)}, ${pending.details.clientId}, ${oauthPgArray(pending.details.scopes)},
            ${pending.params.codeChallenge}, ${'S256'}, ${pending.params.redirectUri},
            ${pending.params.state ?? null}, ${pending.details.resource}, ${Math.floor(this.now() / 1000) + 600})
        `;
        return code;
      });
      pending.status = 'approved';
      redirect.searchParams.set('code', code);
      return redirect.toString();
    } catch (error) {
      pending.status = 'failed'; // uncertain commit is terminal; never retry this request
      throw error;
    }
  }

  async exchangeCode(clientId: string, code: string, verifier?: string, redirectUri?: string, resource?: URL, secretHash?: string): Promise<OAuthTokens> {
    const requested = this.canonicalResource(resource);
    return this.locked(clientId, async (sql, client) => {
      this.assertCredentialPolicy(client, secretHash);
      const [row] = await sql`SELECT * FROM oauth_codes WHERE code_hash = ${hashToken(code)} AND client_id = ${clientId} FOR UPDATE`;
      if (!row || !Number.isFinite(Number(row.expires_at)) || Number(row.expires_at) <= Math.floor(this.now() / 1000) || row.expires_at == null) throw new InvalidGrantError('Authorization code not found or expired');
      if (redirectUri === undefined || redirectUri !== row.redirect_uri) throw new InvalidGrantError('Redirect URI does not match authorization code');
      if (typeof verifier !== 'string' || !/^[A-Za-z0-9._~-]{43,128}$/.test(verifier)
        || row.code_challenge_method !== 'S256'
        || createHash('sha256').update(verifier).digest('base64url') !== row.code_challenge) {
        throw new InvalidGrantError('Invalid S256 PKCE verifier');
      }
      const target = this.resource(row.resource, requested);
      const scopes = this.currentScopes(client, row.scopes as string[]);
      await sql`DELETE FROM oauth_codes WHERE code_hash = ${hashToken(code)} AND client_id = ${clientId}`;
      return this.issue(sql, client, scopes, target, true, 'authorization_code');
    });
  }

  async refresh(clientId: string, token: string, requested?: string[], resource?: URL, secretHash?: string): Promise<OAuthTokens> {
    const requestedResource = this.canonicalResource(resource);
    return this.locked(clientId, async (sql, client) => {
      this.assertCredentialPolicy(client, secretHash);
      const [row] = await sql`SELECT * FROM oauth_tokens WHERE token_hash = ${hashToken(token)} AND token_type = 'refresh' AND client_id = ${clientId} FOR UPDATE`;
      if (!row) throw new InvalidGrantError('Refresh token not found');
      if (row.expires_at == null || !Number.isFinite(Number(row.expires_at)) || Number(row.expires_at) <= Math.floor(this.now() / 1000)) throw new InvalidGrantError('Refresh token expired');
      const original = Array.isArray(row.scopes) ? row.scopes as string[] : [];
      if (requested?.some(scope => !hasScope(original, scope))) throw new InvalidGrantError('Requested scope exceeds refresh token grant');
      if (requested?.some(scope => !hasScope(parseScopeString(client.scope as string | undefined), scope))) throw new InvalidGrantError('Requested scope exceeds current client grant');
      const scopes = this.currentScopes(client, requested ?? original);
      const target = this.resource(row.resource, requestedResource);
      await sql`DELETE FROM oauth_tokens WHERE token_hash = ${hashToken(token)} AND token_type = 'refresh' AND client_id = ${clientId}`;
      return this.issue(sql, client, scopes, target, true, 'refresh_token');
    });
  }

  private currentScopes(client: ClientRow, original: string[]): string[] {
    const allowed = parseScopeString(client.scope as string | undefined);
    return intersectGrantedScopes(original ?? [], allowed);
  }

  private assertCredentialPolicy(client: ClientRow, secretHash?: string): void {
    if ((client.client_secret_hash ?? undefined) !== secretHash) throw new InvalidClientError('Client credentials changed; authenticate again');
    const expires = Number(client.client_secret_expires_at);
    if (secretHash && expires > 0 && expires <= Math.floor(this.now() / 1000)) throw new InvalidClientError('Client credentials expired');
  }

  /** `requested` is already canonical; a stored origin-bound grant from before #5222 canonicalizes the same way. */
  private resource(stored: unknown, requested?: URL): URL | undefined {
    if (typeof stored === 'string' && stored) {
      let approved: URL;
      try {
        approved = this.canonicalResource(new URL(stored))!;
      } catch {
        throw new InvalidGrantError('The approved grant is bound to a resource this server does not serve; reconnect the client');
      }
      if (requested && requested.toString() !== approved.toString()) throw new InvalidGrantError('Requested resource exceeds the approved grant');
      return approved;
    }
    return requested; // pre-resource grants remain valid on upgrade
  }

  async clientCredentials(clientId: string, secret: string, requested?: string): Promise<OAuthTokens> {
    return this.locked(clientId, async (sql, client) => {
      if (!Array.isArray(client.grant_types) || !client.grant_types.includes('client_credentials')) throw new InvalidGrantError('Client credentials grant not authorized for this client');
      if (typeof client.client_secret_hash !== 'string' || !/^[a-f0-9]{64}$/i.test(client.client_secret_hash) || !safeHexEqual(client.client_secret_hash, hashToken(secret))) throw new InvalidClientError('Invalid client secret');
      this.assertCredentialPolicy(client, client.client_secret_hash);
      return this.issue(sql, client, grantScopes(client, requested ? parseScopeString(requested) : undefined), undefined, false, 'client_credentials');
    });
  }

  async revokeToken(clientId: string, token: string, secretHash?: string): Promise<void> {
    await this.locked(clientId, async (sql, client) => {
      this.assertCredentialPolicy(client, secretHash);
      await sql`DELETE FROM oauth_tokens WHERE token_hash = ${hashToken(token)} AND client_id = ${clientId}`;
    });
  }

  async revokeClient(clientId: string): Promise<void> {
    if (!this.options.transaction) throw new ServerError('OAuth grant transactions are unavailable');
    await this.options.transaction(async sql => {
      const [row] = await sql`SELECT * FROM oauth_clients WHERE client_id = ${clientId} FOR UPDATE`;
      if (!row) return;
      // Inspect optional schema before the statement; catching a missing column inside a PG transaction aborts it.
      if ('deleted_at' in row) await sql`UPDATE oauth_clients SET deleted_at = now() WHERE client_id = ${clientId}`;
      else await sql`DELETE FROM oauth_clients WHERE client_id = ${clientId}`;
      await sql`DELETE FROM oauth_codes WHERE client_id = ${clientId}`;
      await sql`DELETE FROM oauth_tokens WHERE client_id = ${clientId}`;
    });
  }

  /**
   * GST-359 C1: each token records the grant that issued it (oauth_tokens.grant_type); only client_credentials tokens
   * may attest an actor. grant_type is migration-only (v286, beside oauth_clients.attest_actor), so a schema without it
   * issues unmarked tokens, which never attest. The locked client row tells which: a failed INSERT would abort the
   * surrounding transaction, so the schema is inspected before the statement.
   */
  private async issue(sql: SqlQuery, client: ClientRow, scopes: string[], resource: URL | undefined, refresh: boolean, grant: 'authorization_code' | 'refresh_token' | 'client_credentials'): Promise<OAuthTokens> {
    const clientId = client.client_id as string;
    const override = Number(client.token_ttl);
    const ttl = Math.min(Number.isFinite(override) && override > 0 ? override : this.options.tokenTtl, TOKEN_TTL_MAX_SECONDS);
    const now = Math.floor(this.now() / 1000);
    const marked = 'attest_actor' in client;
    const insert = (token: string, type: 'access' | 'refresh', expiresAt: number) => marked
      ? sql`INSERT INTO oauth_tokens (token_hash, token_type, client_id, scopes, expires_at, resource, created_at, grant_type)
          VALUES (${hashToken(token)}, ${type}, ${clientId}, ${oauthPgArray(scopes)}, ${expiresAt}, ${resource?.toString() ?? null}, to_timestamp(${now}), ${grant})`
      : sql`INSERT INTO oauth_tokens (token_hash, token_type, client_id, scopes, expires_at, resource, created_at)
          VALUES (${hashToken(token)}, ${type}, ${clientId}, ${oauthPgArray(scopes)}, ${expiresAt}, ${resource?.toString() ?? null}, to_timestamp(${now}))`;
    const access = generateToken('gbrain_at_');
    await insert(access, 'access', now + ttl);
    const result: OAuthTokens = { access_token: access, token_type: 'bearer', expires_in: ttl, scope: scopes.join(' ') };
    if (refresh) {
      const token = generateToken('gbrain_rt_');
      await insert(token, 'refresh', now + this.options.refreshTtl);
      result.refresh_token = token;
    }
    return result;
  }
}