Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.4 KB
Raw Blame
/**
 * token-mint.ts — legacy bearer-token mint/revoke for programmatic callers
 * (#4043 `gbrain bootstrap harness`; extracted from src/commands/auth.ts's
 * private logic, using the canonical hashToken/generateToken from utils.ts).
 *
 * Least-privilege by construction: scopes land in the original-schema
 * `access_tokens.scopes TEXT[]` column (structurally immune to the
 * permissions-object-replacement wipe class). F3: the grant lands in the
 * unified columns (source_grant, source_id, federated_read,
 * allowed_operations, takes_holders) with a `permissions` JSONB mirror for
 * older binaries; the federation grant is an array, element 0 = write floor.
 *
 * Rotation contract [C7]: mint FIRST, revoke the previous token BY ID only
 * after the new one is wired and smoke-tested. revokeLegacyTokenById never
 * touches same-name siblings — names are not unique and may belong to
 * hand-minted tokens.
 */

import type { BrainEngine } from './engine.ts';
import { ALLOWED_SCOPES_LIST, assertAllowedScopes } from './scope.ts';
import type { SqlQuery } from './sql-query.ts';
import { forgetWakePrincipal } from './wakeshift/forget.ts';
import { opError } from './ops/contract.ts';
import { generateToken, hashToken, isUndefinedColumnError } from './utils.ts';
import { permissionsMirror, privatePagesFromColumn, tokenGrantColumnValues, tokenGrantFromPermissions, TOKEN_GRANT_COLUMNS, type GrantSources, type PrincipalGrant, type PrivatePagesGrant } from './grants/model.ts';

/** Canonical token-id shape — shared with the `auth revoke --id` CLI gate. */
export const TOKEN_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

export interface MintLegacyTokenOpts {
  name: string;
  /** Per-token takes-holder allow-list; harness default ['world']. `[]` is stored as deny-all. */
  takesHolders: string[];
  /** Scope grant → the scopes TEXT[] column. Must be non-empty known scopes. */
  scopes: string[];
  /**
   * Federation grant → permissions.source_id (array; element 0 = write
   * floor). Omit for the historical default-source floor; `[]` is stored as
   * the explicit no-source grant.
   */
  sourceGrant?: string[];
  allowedOperations?: string[];
}

export interface MintedLegacyToken {
  /** Plaintext token — shown/wired once, never stored. */
  token: string;
  /** Row id — the ONLY safe revocation key (names are not unique). */
  id: string;
  name: string;
  scopes: string[];
  /** Rotation only: operations this run would grant that the carried snapshot withheld. */
  withheldOperations?: string[];
  /** Rotation only (#8104): the replaced token's private-pages grant, which a rotation never carries. */
  uncarriedPrivatePages?: Exclude<PrivatePagesGrant, 'none'>;
}

/**
 * Mint a scoped legacy bearer token. Throws on unknown/empty scopes (typos
 * fail loudly at mint time — the verify path treats a filtered-empty array
 * as deny, so a silent bad write would brick the token, not widen it).
 */
export async function mintLegacyToken(
  engine: BrainEngine,
  opts: MintLegacyTokenOpts,
): Promise<MintedLegacyToken> {
  if (!opts.name || !opts.name.trim()) {
    throw new Error('token name is required');
  }
  if (opts.scopes.length === 0) {
    throw new Error(`token scopes must be a non-empty subset of: ${ALLOWED_SCOPES_LIST.join(', ')}`);
  }
  assertAllowedScopes(opts.scopes);
  if (opts.allowedOperations !== undefined) {
    const { operations } = await import('./operations.ts');
    const names = new Set(operations.filter(op => !op.localOnly).map(op => op.name));
    if (!Array.isArray(opts.allowedOperations) || opts.allowedOperations.some(name => !names.has(name))) {
      throw new Error('allowedOperations must contain only registered remote operation names');
    }
  }
  const token = generateToken('gbrain_');
  const sources: GrantSources = opts.sourceGrant === undefined ? { kind: 'default' }
    : opts.sourceGrant.length === 0 ? { kind: 'none' }
    : { kind: 'federated', writeSource: opts.sourceGrant[0], readSources: [...opts.sourceGrant] };
  const rows = await insertUnifiedToken(engine, {
    name: opts.name, tokenHash: hashToken(token), scopes: opts.scopes,
    grant: { sources, takesHolders: opts.takesHolders, allowedOperations: opts.allowedOperations === undefined ? null : [...new Set(opts.allowedOperations)] },
  });
  const id = rows[0]?.id;
  if (!id) throw new Error('token insert returned no id');
  return { token, id, name: opts.name, scopes: [...opts.scopes] };
}

/**
 * Insert a token born on the unified grant shape: the grant columns at
 * revision 1 plus the `permissions` JSONB mirror older binaries read
 * (`GRANT_MIRROR_WINDOW_ENDS`). A brain whose schema predates the columns
 * refuses with `migrations_pending` instead of writing a JSONB-only grant.
 * Scopes bind as a Postgres array literal through a TEXT param + ::text[]
 * (values are allowlisted); omitted scopes stay NULL (grandfathered full
 * access). The JSONB object binds as a raw object, exactly as executeRawJsonb
 * binds it (no double-encode).
 */
export async function insertUnifiedToken(engine: BrainEngine, opts: {
  name: string; tokenHash: string; scopes?: string[];
  grant: Pick<PrincipalGrant, 'sources' | 'allowedOperations' | 'takesHolders'>;
}): Promise<Array<{ id: string }>> {
  const scopes = opts.scopes === undefined ? null : `{${opts.scopes.join(',')}}`;
  const { assertScopeSourceGrant, sourcesOf } = await import('./access/attest-sources.ts');
  const reads = sourcesOf(opts.grant.sources).reads;
  const insert = (db: BrainEngine) => db.executeRaw<{ id: string }>(
    `INSERT INTO access_tokens (name, token_hash, scopes, permissions, ${TOKEN_GRANT_COLUMNS.join(', ')}, grant_revision)
     VALUES ($1, $2, $3::text[], $4::jsonb, $5, $6, $7::text[], $8::text[], $9::text[], 1)
     RETURNING id`,
    [opts.name, opts.tokenHash, scopes, permissionsMirror(opts.grant, {}), ...tokenGrantColumnValues(opts.grant)],
  );
  try {
    // GST-1113: a grant reading a named source checks it and inserts in one transaction, under the source row locks.
    if (!reads.some(s => s !== 'default')) return await insert(engine);
    return await engine.transaction(async tx => {
      await assertScopeSourceGrant(tx, null, reads);
      return insert(tx);
    });
  } catch (e) {
    // isUndefinedColumnError also matches message-shaped variants: some
    // driver-wrapped errors drop the SQLSTATE code.
    if (['scopes', 'permissions', 'grant_revision', ...TOKEN_GRANT_COLUMNS].some(column => isUndefinedColumnError(e, column))) {
      throw opError('migrations_pending',
        'This brain is missing the access-token grant columns, so it cannot mint a token.',
        'Apply the pending schema migrations on the brain host, then mint the token again.',
        { why: 'Tokens are born on the unified grant columns; a brain whose schema predates them has not run its migrations.',
          fix: { argv: ['gbrain', 'apply-migrations', '--yes'], consent: [], actor: 'agent', requires_exclusive: true,
            why: 'Applies the pending schema migrations, including the token grant columns; no user decision needed.', verify: { argv: ['gbrain', 'doctor', '--json'] } } });
    }
    throw e;
  }
}

/**
 * Revoke exactly one token by row id. Returns false when no ACTIVE row with
 * that id exists (already revoked or never existed) — callers treat that as
 * already-done, not failure.
 */
export async function revokeLegacyTokenById(sql: SqlQuery, id: string): Promise<boolean> {
  if (!TOKEN_ID_RE.test(id)) {
    throw new Error(`not a token id (expected a UUID): ${id}`);
  }
  const rows = await sql`
    UPDATE access_tokens SET revoked_at = now()
    WHERE id = ${id}::uuid AND revoked_at IS NULL
    RETURNING 1 AS ok
  `;
  if (rows.length > 0) await forgetWakePrincipal(sql, { kind: 'legacy_token', id });
  return rows.length > 0;
}

/**
 * #5893 rotation carry-over: the grants a rotated harness token inherits from
 * the token it replaces. Takes holders and the source grant are carried as
 * stored, explicit empty lists included (an explicit `--source` on this run
 * wins over the stored source grant). A stored operation snapshot is carried
 * as stored, narrowed to the operations this run would grant, plus only the
 * operations a skills-policy change adds; `[]` stays `[]`. Operations new
 * since the snapshot are withheld (reported, never silently granted): widen
 * with `gbrain auth rescope --token <name> --refresh-operations`.
 *
 * F3: the prior grant is read from its `permissions` JSONB through the shared
 * parser. On a unified row that JSONB mirrors the columns. On a drifted row
 * (an older gbrain edited the JSONB after migration) the edit is the newest
 * operator intent, so rotation carries it, the same resolution as
 * `auth rescope --adopt-permissions`; the replacement is born unified and the
 * drifted row is revoked after the swap.
 */
export function carryLegacyGrant(priorRaw: unknown, fresh: {
  sourceGrant?: string[]; explicitSource: boolean; allowedOperations: string[]; policyAdded: string[];
}): { takesHolders: string[]; sourceGrant?: string[]; allowedOperations: string[]; withheldOperations: string[] } {
  const prior = tokenGrantFromPermissions(priorRaw);
  const takesHolders = prior.takesHolders ?? ['world'];
  const stored = prior.sources;
  const storedSource = stored.kind === 'default' ? undefined : stored.kind === 'none' ? []
    : stored.kind === 'scalar' ? [stored.writeSource] : stored.readSources;
  const sourceGrant = fresh.explicitSource || storedSource === undefined ? fresh.sourceGrant : storedSource;
  const priorOps = prior.allowedOperations ?? undefined;
  if (priorOps === undefined) return { takesHolders, sourceGrant, allowedOperations: fresh.allowedOperations, withheldOperations: [] };
  const allowedOperations = priorOps.length === 0 ? [] : [...new Set([
    ...priorOps.filter(op => fresh.allowedOperations.includes(op)), ...fresh.policyAdded,
  ])].sort();
  return { takesHolders, sourceGrant, allowedOperations,
    withheldOperations: fresh.allowedOperations.filter(op => !allowedOperations.includes(op)) };
}

/**
 * #8104: an active token's private-pages grant. Rotation does not carry it (the replacement starts at `none`), so the
 * harness names the rescope that grants it again. `none` when the token is gone or the brain predates the column.
 */
export async function readActiveTokenPrivatePages(engine: BrainEngine, id: string): Promise<PrivatePagesGrant> {
  if (!TOKEN_ID_RE.test(id)) return 'none';
  try {
    const [row] = await engine.executeRaw<{ private_pages: unknown }>(
      'SELECT private_pages FROM access_tokens WHERE id = $1::uuid AND revoked_at IS NULL', [id]);
    return privatePagesFromColumn(row?.private_pages);
  } catch (e) {
    if (isUndefinedColumnError(e, 'private_pages')) return 'none';
    throw e;
  }
}

/** #8104: the note a rotation prints beside the withheld-operations note when the replaced token had a private-pages grant. */
export function uncarriedPrivatePagesNote(name: string, mode: Exclude<PrivatePagesGrant, 'none'>): string {
  return `token ${name}: private-pages grant not carried; run \`gbrain auth rescope --token ${name} --private-pages ${mode.replace('_', '-')}\` to grant it again.`;
}

/** The stored grant of an active token, or undefined when it is gone or revoked. */
export async function readActiveTokenPermissions(engine: BrainEngine, id: string): Promise<unknown> {
  if (!TOKEN_ID_RE.test(id)) return undefined;
  const [row] = await engine.executeRaw<{ permissions: unknown }>(
    'SELECT permissions FROM access_tokens WHERE id = $1::uuid AND revoked_at IS NULL', [id]);
  return row ? row.permissions ?? {} : undefined;
}