Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
14.1 KB
Raw Blame
/**
 * gbrain OAuth scope hierarchy + allowlist (v0.28).
 *
 * Single source of truth for the 5 scope strings. Used by:
 *  - src/commands/serve-http.ts (scopesSupported, request-time hasScope)
 *  - src/core/oauth-provider.ts (F3 refresh, token issuance, registration)
 *  - src/commands/auth.ts (CLI register-client validation)
 *  - admin/src/lib/scope-constants.ts (HAND-MAINTAINED MIRROR; CI drift check
 *    in scripts/check-admin-scope-drift.sh keeps them aligned)
 *
 * Hierarchy (see plan ASCII diagram):
 *
 *                    admin
 *                      │
 *      ┌──────────┬────┴────┬──────────┐
 *      ▼          ▼         ▼          ▼
 *   sources_admin  users_admin  write  read
 *                                │      ▲
 *                                └──────┘
 *
 * sources_admin and users_admin are siblings (different axes — sources-mgmt
 * vs user-account-mgmt — neither implies the other).
 */

export type Scope = 'read' | 'write' | 'admin' | 'sources_admin' | 'users_admin' | 'agent' | 'skill_editor' | 'skill_publisher' | 'skills_member_self' | 'memory_confirm';

export const ALLOWED_SCOPES: ReadonlySet<Scope> = new Set<Scope>([
  'read',
  'write',
  'admin',
  'sources_admin',
  'users_admin',
  'agent',
  'skill_editor',
  'skill_publisher',
  'skills_member_self',
  'memory_confirm',
]);

/**
 * Sorted list (deterministic for OAuth metadata + drift-check output).
 * Use this when emitting `scopes_supported` over the wire.
 */
export const ALLOWED_SCOPES_LIST: ReadonlyArray<Scope> = Object.freeze([
  'admin',
  'agent',
  'memory_confirm',
  'read',
  'skill_editor',
  'skill_publisher',
  'skills_member_self',
  'sources_admin',
  'users_admin',
  'write',
]);

/**
 * Ceiling for anonymous Dynamic Client Registration (RFC 7591). A network
 * caller that self-registers may hold at most `read write`; every privileged
 * scope needs an operator-created grant (`gbrain auth register-client`, the
 * admin API) or a later `gbrain auth rescope-client`. The owner-approval
 * step on /authorize shows the requested scopes but never narrows them, so
 * the ceiling is what keeps "approve" from meaning "grant admin".
 */
export const DCR_REGISTRABLE_SCOPES: ReadonlySet<Scope> = new Set<Scope>(['read', 'write']);

/**
 * A `client_credentials` DCR client (only reachable under
 * `--enable-dcr-insecure`) mints tokens with NO owner approval at all, so its
 * ceiling is tighter still: read-only.
 */
const DCR_MACHINE_SCOPES: ReadonlySet<Scope> = new Set<Scope>(['read']);

/**
 * #5575 (CEO-6): scopes only the trusted local CLI may grant
 * (`gbrain auth create --scopes ...,memory_confirm`, `auth register-client`,
 * `auth rescope`). `memory_confirm` lets a connection confirm memory as the
 * owner (raise a trust tier), so the admin HTTP API, the admin SPA, `gbrain mcp
 * admin`, API-key minting and dynamic registration all refuse it, and no
 * grant profile or grandfathered token carries it.
 */
export const LOCAL_CLI_ONLY_SCOPES: ReadonlySet<Scope> = new Set<Scope>(['memory_confirm']);

/** null when no local-CLI-only scope is requested; otherwise the refusal message naming the local command. */
export function localCliOnlyScopeViolation(requested: readonly string[]): string | null {
  const over = [...new Set(requested.filter(s => LOCAL_CLI_ONLY_SCOPES.has(s as Scope)))];
  if (over.length === 0) return null;
  return `Scope "${over.join(' ')}" lets a connection confirm memory as the owner, so only the local CLI on the brain host can grant it: `
    + '`gbrain auth create <name> --scopes read,write,memory_confirm` or `gbrain auth rescope --client <client_id> --scopes ...`.';
}

/**
 * null when the requested DCR scopes fit under the ceiling; otherwise the
 * `invalid_client_metadata` message naming the offending scopes + remedy.
 * Unknown scope strings are ignored here (filterAllowedScopes drops them);
 * `agent` keeps its own wording because it also needs delegation bindings.
 */
export function dcrScopeViolation(requested: readonly string[], grantTypes: readonly string[]): string | null {
  if (requested.includes('agent')) {
    return 'agent scope requires an operator-approved grant with explicit delegation bindings; dynamic registration cannot grant it';
  }
  const localOnly = localCliOnlyScopeViolation(requested);
  if (localOnly) return localOnly;
  const machine = grantTypes.includes('client_credentials');
  const ceiling = machine ? DCR_MACHINE_SCOPES : DCR_REGISTRABLE_SCOPES;
  const over = [...new Set(requested.filter((s) => isScope(s) && !ceiling.has(s)))];
  if (over.length === 0) return null;
  const limit = [...ceiling].join(' ');
  return (
    `Scope "${over.join(' ')}" cannot be granted through dynamic client registration; ` +
    (machine
      ? `a client_credentials registration is limited to \`${limit}\` because it is issued without owner approval. `
      : `self-registered clients are limited to \`${limit}\`. `) +
    'Register the client with `gbrain auth register-client` / the admin API instead, ' +
    'or register with a narrower scope and widen it later with `gbrain auth rescope-client <client_id> --scopes ...`.'
  );
}

/**
 * `scopes_supported` for OAuth discovery. The MCP SDK router emits ONE value
 * into the RFC 8414 authorization-server document and the RFC 9728
 * protected-resource document(s), so this is the single place that decides
 * what a client reading discovery is told it may ask for:
 *
 *  - DCR enabled (either mode): exactly the anonymous-registration ceiling,
 *    `read write`, in canonical order. Clients commonly copy `scopes_supported`
 *    verbatim into their /register request; advertising a privileged scope
 *    would steer every such client straight into `dcrScopeViolation` (HTTP 400)
 *    even though the server is willing to register it at `read write`. The
 *    tighter read-only ceiling for `client_credentials` registrations stays in
 *    `dcrScopeViolation` — authorization_code is the DCR default and may hold
 *    both, so advertising `read` alone would under-describe it.
 *  - DCR disabled: every scope except operator-only `agent`, which also needs
 *    delegation bindings no OAuth request can carry, and the local-CLI-only
 *    `memory_confirm`. Operator-registered clients see the full set they may hold.
 *
 * Narrowed discovery never narrows an operator-registered client: one that
 * omits `scope` at /authorize or /token receives its full registered set
 * (`grantScopes` in oauth-grants.ts falls back to the row's scope), and an
 * explicit request is intersected with its registration, not with this list.
 */
export function scopesSupportedForDiscovery(opts: { enableDcr: boolean }): Scope[] {
  return opts.enableDcr
    ? ALLOWED_SCOPES_LIST.filter((s) => DCR_REGISTRABLE_SCOPES.has(s))
    : ALLOWED_SCOPES_LIST.filter((s) => s !== 'agent' && !LOCAL_CLI_ONLY_SCOPES.has(s));
}

/**
 * Hierarchy table: which required scopes are implied by which granted scope.
 * `admin` implies all (escape hatch for legacy + super-admin tokens).
 * `write` implies `read`. The two `*_admin` siblings only imply themselves.
 *
 * v0.38 (D13): `agent` is a SIBLING, not implied by admin. A super-admin
 * token still needs to be re-registered with explicit bindings to submit
 * subagent jobs. This prevents existing admin clients from silently gaining
 * agent-dispatch capability on upgrade.
 *
 * #5575: `memory_confirm` (confirm memory as the owner) is a sibling too:
 * admin never implies it, so grandfathered full-access tokens and admin
 * clients cannot raise a trust tier.
 */
const IMPLIES: Record<Scope, ReadonlySet<Scope>> = {
  admin: new Set(['admin', 'sources_admin', 'users_admin', 'write', 'read']),
  write: new Set(['write', 'read']),
  sources_admin: new Set(['sources_admin']),
  users_admin: new Set(['users_admin']),
  read: new Set(['read']),
  agent: new Set(['agent']),
  skill_editor: new Set(['skill_editor']),
  skill_publisher: new Set(['skill_publisher']),
  skills_member_self: new Set(['skills_member_self']),
  memory_confirm: new Set(['memory_confirm']),
};

/**
 * Does the granted scope set include something that satisfies `required`?
 * - admin in granted → true for any required
 * - write in granted → true for {write, read}
 * - sources_admin in granted → true for {sources_admin}
 * - users_admin in granted → true for {users_admin}
 * - read in granted → true for {read}
 *
 * Unknown scopes in `granted` are ignored (forward-compat — pre-allowlist
 * tokens with bogus scopes don't crash hasScope; they just don't satisfy).
 */
export function hasScope(grantedScopes: readonly string[], requiredScope: string): boolean {
  for (const granted of grantedScopes) {
    if (!isScope(granted)) continue;
    const implied = IMPLIES[granted];
    if (implied.has(requiredScope as Scope)) return true;
  }
  return false;
}

export function operationScopesAllowed(
  grantedScopes: readonly string[],
  operation: { scope?: string; requiredScopes?: readonly string[]; agentCallable?: boolean },
): boolean {
  return (hasScope(grantedScopes, operation.scope ?? 'read')
    || (operation.agentCallable === true && hasScope(grantedScopes, 'agent')))
    && (operation.requiredScopes ?? []).every(scope => hasScope(grantedScopes, scope));
}

export function isScope(s: string): s is Scope {
  return ALLOWED_SCOPES.has(s as Scope);
}

/**
 * Validate that every scope in the input is allowed. Throws on the first
 * unknown scope. Used at OAuth client registration time (CLI, DCR, manual).
 */
export class InvalidScopeError extends Error {
  constructor(public readonly invalidScope: string, public readonly allScopes: readonly string[]) {
    super(
      `Unknown scope "${invalidScope}". Allowed: ${ALLOWED_SCOPES_LIST.join(', ')}.`,
    );
    this.name = 'InvalidScopeError';
  }
}

export function assertAllowedScopes(scopes: readonly string[]): void {
  for (const s of scopes) {
    if (!isScope(s)) throw new InvalidScopeError(s, scopes);
  }
}

/**
 * Split a requested scope list into allowed vs unknown entries.
 *
 * Used by the unauthenticated DCR path so clients that send OIDC-style
 * extras (e.g. `offline_access`, `openid`) still register successfully
 * with the intersection of known scopes. RFC 7591 §2 lets the AS replace
 * client metadata values; dropping unknowns is that replacement.
 *
 * Operator-trusted paths (CLI / admin) keep using `assertAllowedScopes`
 * so typos surface loudly instead of silently shrinking the grant.
 */
export function filterAllowedScopes(scopes: readonly string[]): {
  allowed: Scope[];
  dropped: string[];
} {
  const allowed: Scope[] = [];
  const dropped: string[] = [];
  const seen = new Set<string>();
  for (const s of scopes) {
    if (seen.has(s)) continue;
    seen.add(s);
    if (isScope(s)) allowed.push(s);
    else dropped.push(s);
  }
  return { allowed, dropped };
}

/**
 * Parse a space-separated scope string (OAuth wire format) into an array,
 * dropping empty fragments. Does NOT validate against ALLOWED_SCOPES — call
 * assertAllowedScopes afterward at registration time.
 */
export function parseScopeString(s: string | undefined | null): string[] {
  if (!s) return [];
  return s.split(' ').filter(Boolean);
}

/**
 * v0.39.3.0 WARN-9 + CV12 — normalize the `scopes` (or `scope`) field that
 * arrives from the admin SPA's register-client request body to the
 * space-separated wire format `registerClientManual` expects. Three valid
 * input shapes; everything else throws Error to be caught and surfaced
 * as 400 invalid_scopes.
 *
 * Valid shapes:
 *   - `undefined` / `null` / missing  →  defaults to 'read'
 *   - `string`                         →  split on /\s+/, filter empty,
 *                                         dedupe, validate each, re-join
 *   - `string[]`                       →  validate each element is a non-
 *                                         empty single scope (no internal
 *                                         whitespace — that's the bug
 *                                         shape codex flagged where
 *                                         ['read write'] silently lets
 *                                         `read write` through as a single
 *                                         unknown scope), dedupe, validate
 *                                         each against ALLOWED_SCOPES
 *
 * Rejection cases:
 *   - non-string non-array (number, object, boolean) → Error
 *   - empty array after normalization → Error
 *   - array element with internal whitespace → Error (the ['read write'] bug)
 *   - array element that's not a string (null, number, ...) → Error
 *   - any element not in ALLOWED_SCOPES → InvalidScopeError
 *
 * Returns the space-separated string (e.g. 'read write') in sorted order
 * for determinism so two registrations with the same scope set produce
 * identical DB rows.
 */
export function normalizeScopesInput(raw: unknown): string {
  if (raw == null) return 'read';

  let candidates: string[];

  if (typeof raw === 'string') {
    candidates = raw.split(/\s+/).filter(Boolean);
  } else if (Array.isArray(raw)) {
    for (const el of raw) {
      if (typeof el !== 'string') {
        throw new Error(
          `scopes array must contain only strings, got ${el === null ? 'null' : typeof el}`,
        );
      }
      if (el.length === 0) {
        throw new Error('scopes array must not contain empty strings');
      }
      if (/\s/.test(el)) {
        throw new Error(
          `scopes array element "${el}" contains whitespace. Each element must be a single scope name; use ['read', 'write'] not ['read write'].`,
        );
      }
    }
    candidates = raw as string[];
  } else {
    throw new Error(
      `scopes must be a string or array of strings, got ${typeof raw}`,
    );
  }

  // Dedupe via Set + sort for stable output.
  const deduped = Array.from(new Set(candidates)).sort();

  if (deduped.length === 0) {
    throw new Error('scopes is empty after normalization');
  }

  // Validate against ALLOWED_SCOPES (throws InvalidScopeError on miss).
  assertAllowedScopes(deduped);
  // Every caller of this normalizer is an admin HTTP surface (or its remote CLI), never the local CLI.
  const localOnly = localCliOnlyScopeViolation(deduped);
  if (localOnly) throw new Error(localOnly);

  return deduped.join(' ');
}