Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
79.2 KB
Raw Blame
#!/usr/bin/env bun
/**
 * GBrain token management.
 *
 * Wired into the CLI as of v0.22.5:
 *   gbrain auth create "claude-desktop"
 *   gbrain auth list
 *   gbrain auth revoke "claude-desktop"
 *   gbrain auth test <url> --token <token>
 *
 * Also runs standalone (no compiled binary required):
 *   DATABASE_URL=... bun run src/commands/auth.ts create "claude-desktop"
 *
 * DB-backed commands route through the active BrainEngine (PGLite or
 * Postgres), so they work regardless of which engine the user's brain is
 * configured for. The env-var DATABASE_URL / GBRAIN_DATABASE_URL still
 * picks Postgres via loadConfig() (config.ts DbUrlSource inference),
 * but the SQL itself goes through engine.executeRaw — never through a
 * postgres.js singleton. `test` only hits a remote URL and doesn't need
 * a local DB.
 */
import { loadConfig, toEngineConfig } from '../core/config.ts';
import { createEngine } from '../core/engine-factory.ts';
import type { BrainEngine } from '../core/engine.ts';
import { assertAllowedScopes } from '../core/scope.ts';
import { isTrustTier, TRUST_TIERS, type TrustTier } from '../core/trust/tier.ts';
import { setMinTrust } from '../core/trust/min-trust.ts';
import { isMissingSchemaObject } from '../core/utils.ts';
import { TOKEN_ID_RE } from '../core/token-mint.ts';
import { normalizeTokenScopes } from '../core/legacy-token-scope.ts';
import { sqlQueryForEngine, type SqlQuery } from '../core/sql-query.ts';
import type { OAuthTransaction } from '../core/oauth-grants.ts';
import { readClientGrant, rescopeClientGrant, resolveGrantProfile, type GrantPatch } from '../core/grants/service.ts';
import { parseClientRescopeArgs, parseRescopeGrantArgs, splitRescopeTarget, type RescopeGrantArgs } from '../core/grants/cli.ts';
import { GRANT_PROFILES, GrantError, TOKEN_TTL_MAX_SECONDS, TOKEN_TTL_MIN_SECONDS, grantFromClient, privatePagesFromColumn, type ClientGrant, type PrivatePagesGrant } from '../core/grants/model.ts';
import { PRIVATE_FACTS_HELP, privateFactsRescopeLines, privateFactsWarning, renderPrivateFacts } from './auth-private-facts.ts';
import { listClientRows } from './auth-client-rows.ts';
import { cliRenderContext, renderAction, type RenderedAction } from '../core/agent-output.ts';
import type { INSTALL_SURFACE_SET_BY } from '../mcp/surface.ts';
import { credentialCensus, exposureServes, sharedTokenNotice, writeExposureNotice } from '../core/grants/shared-exposure.ts';
import { migrateLegacyTokens, parseRescopeTokenArgs, renderLegacyGrantAxis, rescopeLegacyToken, resolveRescopeTarget, type MigrateLegacyResult, type RescopeTokenResult } from '../core/grants/legacy-token.ts';
import { bindCredential, type BindingPatch, type BindingResult } from '../core/access/members.ts';
import { bindingLine, checkBindingTarget, takeBindingFlags } from './auth-binding.ts';
import { mintToken } from './auth-mint.ts';
import { assertCredentialScoped, logReadsUnscopedChange } from '../core/access/requester-scope.ts';
import { exitCliError } from '../cli/cli-error.ts';
export { listClientRows, renderPrivateFacts };
import { OperationError } from '../core/ops/contract.ts';

/**
 * Acquire an engine from the active config, run `fn` with a SqlQuery, and
 * disconnect afterward. Loud-fails when no config is present (matches the
 * prior behavior of getDatabaseUrl(requireDb=true) — auth commands need a
 * brain to write to).
 */
async function withConfiguredSql<T>(
  fn: (sql: SqlQuery, engine: BrainEngine) => Promise<T>,
): Promise<T> {
  const config = loadConfig();
  if (!config) {
    console.error('No GBrain config found. Run `gbrain init` first, or set DATABASE_URL / GBRAIN_DATABASE_URL.');
    process.exit(1);
  }
  const engineConfig = toEngineConfig(config);
  const engine = await createEngine(engineConfig);
  // v0.32: createEngine returns a disconnected instance. PostgresEngine's `sql`
  // getter falls back to `db.getConnection()` (the module-level singleton)
  // when `_sql` is unset, which throws "connect() has not been called" when
  // db.connect() was never invoked either. Auth commands never go through
  // cli.ts's connectEngine() path (early-routed at cli.ts:685), so we must
  // connect the engine here. Without this call, every auth subcommand
  // (create/list/revoke/register-client/revoke-client) crashes with the
  // misleading "No database connection" error.
  await engine.connect(engineConfig);
  const sql = sqlQueryForEngine(engine);
  try {
    return await fn(sql, engine);
  } finally {
    await engine.disconnect();
  }
}

/** GBRA-585 E: the scopes a token bound to a member gets when --scopes is not given; an explicit --scopes always wins. */
export const MEMBER_TOKEN_SCOPES: readonly string[] = ['read', 'write'];

async function create(name: string, opts: { takesHolders?: string[]; scopes?: string[]; minTrust?: TrustTier; binding?: BindingPatch | null } = {}) {
  if (!name) { console.error('Usage: auth create <name> [--takes-holders world,garry] [--scopes read,write] [--min-trust <tier>] [--member <id>] [--reads-unscoped --yes]'); process.exit(1); }
  // #4043 least-privilege: validate scopes at mint time — the verify path
  // treats a filtered-empty scopes array as DENY, so a typo must fail loudly
  // here, never silently brick (or widen) the token.
  if (opts.scopes !== undefined) {
    try {
      if (opts.scopes.length === 0) throw new Error('at least one scope is required');
      assertAllowedScopes(opts.scopes);
    } catch (e: any) {
      console.error(`Invalid --scopes: ${e.message}`);
      process.exit(1);
    }
  }
  const memberDefault = opts.scopes === undefined && !!opts.binding?.member;
  if (memberDefault) opts = { ...opts, scopes: [...MEMBER_TOKEN_SCOPES] };
  try {
    await withConfiguredSql(async (_sql, engine) => {
      await assertCredentialScoped(engine, opts.binding ?? null, 'token', name);
      const { token, id, takesHolders, bound } = await mintToken(engine, name, opts);
      if (bound) auditReadsUnscoped(bound, `token ${name}`, false);
      const scopeLine = memberDefault
        ? `scopes=${JSON.stringify(opts.scopes)} (the default for a token bound to a member; pass --scopes read,write,admin for admin access)`
        : opts.scopes !== undefined
        ? `scopes=${JSON.stringify(opts.scopes)}`
        : 'scopes=full access (grandfathered — pass --scopes read,write to narrow)';
      console.log(`Token created for "${name}" (takes_holders=${JSON.stringify(takesHolders)}, ${scopeLine}${opts.minTrust ? `, min_trust=${opts.minTrust}` : ''}):\n`);
      if (bound) console.log(`${bindingLine(bound)}\n`);
      console.log(`  ${token}\n`);
      console.log('Save this token — it will not be shown again.');
      console.log(`Revoke with: gbrain auth revoke "${name}" (or gbrain auth revoke --id <id> from auth list)`);
      console.log(`Change its grants: gbrain auth rescope --token "${name}" --takes-holders world,garry (or --sources, --operations)`);
      const grant = { principal: { kind: 'legacy_token' as const, id }, scopes: opts.scopes ?? ['read', 'write', 'admin'], sources: { kind: 'default' as const } };
      if (!opts.binding?.mayActFor?.length) writeExposureNotice(sharedTokenNotice({ kind: 'legacy_token', name }, { census: await credentialCensus(engine, grant), serves: await exposureServes(engine) }));
    });
  } catch (e: any) {
    if (e instanceof OperationError) exitCliError(e, 'auth');
    if (e.code === '23505') {
      console.error(`A token named "${name}" already exists. Revoke it first or use a different name.`);
    } else {
      console.error('Error:', e.message);
    }
    process.exit(1);
  }
}

/** `auth set-min-trust <client|token> <tier|none>` (#5575, CEO-18): local-only, the one way to change a read floor. */
async function setMinTrustCmd(rest: string[]) {
  const [target, value] = rest.filter(a => !a.startsWith('--'));
  if (!target || !value || (value !== 'none' && !isTrustTier(value))) {
    console.error(`Usage: auth set-min-trust <client_id|token id|token name> <${TRUST_TIERS.join('|')}|none>`);
    process.exit(1);
  }
  try {
    await withConfiguredSql(async (_sql, engine) => {
      const change = await setMinTrust(engine, target, value === 'none' ? null : value as TrustTier);
      if (rest.includes('--json')) { console.log(JSON.stringify(change)); return; }
      console.log(`${change.kind === 'oauth_client' ? 'OAuth client' : 'Token'} "${change.name}" (${change.id}): min_trust ${change.before ?? 'none'} -> ${change.after ?? 'none'}.`);
      console.log('Applies on its next request: reads never return rows below this tier, whatever min_trust the client asks for.');
    });
  } catch (e: any) {
    console.error('Error:', e.message);
    process.exit(1);
  }
}

/** `auth permissions <name> set-takes-holders <list>`: alias of `auth rescope --token <name> --takes-holders <list>`. */
async function permissions(name: string, action: string, value: string | undefined) {
  if (!name || action !== 'set-takes-holders' || !value) {
    console.error('Usage: auth permissions <name> set-takes-holders world,garry,brain  (alias of: gbrain auth rescope --token <name> --takes-holders <list>)');
    process.exit(1);
  }
  await runRescope(['--token', name, '--takes-holders', value]);
}

/** Render a token row's scope grant honestly (#4043: NULL = grandfathered).
 * Routes through the SAME normalizer the verify path uses — the ops surface
 * must never claim admin on a row the serve actually scopes or denies. */
/** GBRA-156: the private-pages axis as `auth list`, `auth clients` and `auth rescope` print it. */
export function renderPrivatePages(mode: PrivatePagesGrant | undefined): string {
  return mode === 'granted_sources' ? 'granted-sources (private pages in the sources this grant names)' : 'none';
}

export function renderTokenScopes(scopes: unknown): string {
  const normalized = normalizeTokenScopes(scopes);
  if (normalized === undefined) return 'admin (grandfathered)';
  if (normalized.length === 0) return '(deny-all)';
  return normalized.join(',');
}

async function list(json: boolean) {
  await withConfiguredSql(async (sql) => {
    // SELECT * reads every schema generation (private_pages and private_facts arrive with their migrations; absent reads as none).
    const rows = await sql`
      SELECT * FROM access_tokens
      ORDER BY created_at DESC
    `;
    const memberStatus = await (await import('../core/access/token-member-status.ts')).tokenMemberStatuses(sql, rows);
    if (json) {
      console.log(JSON.stringify(rows.map(r => ({
        id: String(r.id), name: r.name, scopes: renderTokenScopes(r.scopes), created_at: r.created_at, last_used_at: r.last_used_at ?? null,
        status: r.revoked_at ? 'revoked' : 'active', private_pages: privatePagesFromColumn(r.private_pages), private_facts: privatePagesFromColumn(r.private_facts), member_status: memberStatus(r),
      })), null, 2));
      return;
    }
    if (rows.length === 0) {
      console.log('No tokens found. Create one: gbrain auth create "my-client"');
      return;
    }
    console.log('ID                                    Name                  Scopes                 Created              Last Used            Status   Private facts    Private pages');
    console.log('─'.repeat(158));
    for (const r of rows) {
      const id = String(r.id).padEnd(36);
      const name = (r.name as string).padEnd(20);
      const scopes = renderTokenScopes(r.scopes).padEnd(21);
      const created = new Date(r.created_at as string).toISOString().slice(0, 19);
      const lastUsed = r.last_used_at ? new Date(r.last_used_at as string).toISOString().slice(0, 19) : 'never'.padEnd(19);
      const status = (r.revoked_at ? 'REVOKED' : (memberStatus(r) ?? 'enabled') !== 'enabled' ? 'refused' : 'active').padEnd(7);
      const facts = privatePagesFromColumn(r.private_facts) === 'granted_sources' ? 'granted-sources' : 'none';
      console.log(`${id}  ${name}  ${scopes}  ${created}  ${lastUsed}  ${status}  ${facts.padEnd(15)}  ${renderPrivatePages(privatePagesFromColumn(r.private_pages))}`);
    }
  });
}

async function revoke(name: string) {
  if (!name) { console.error('Usage: auth revoke <name> | auth revoke --id <uuid>'); process.exit(1); }
  await withConfiguredSql(async (sql) => {
    const rows = await sql`
      UPDATE access_tokens SET revoked_at = now()
      WHERE name = ${name} AND revoked_at IS NULL
      RETURNING id
    `;
    for (const row of rows) await (await import('../core/wakeshift/forget.ts')).forgetWakePrincipal(sql, { kind: 'legacy_token', id: String(row.id) });
    if (rows.length === 0) {
      console.error(`No active token found with name "${name}".`);
      process.exit(1);
    }
    if (rows.length > 1) {
      console.log(`Note: ${rows.length} active tokens carried the name "${name}" — all revoked. Use revoke --id for precision.`);
    }
    console.log(`Token "${name}" revoked.`);
  });
}

/** #4043: names are not unique — revoke-by-id is the precise path. The
 * revocation semantics are canonical in src/core/token-mint.ts
 * (revokeLegacyTokenById); this CLI wrapper keeps its own UPDATE only to
 * RETURN the name for the confirmation line — keep the two in lockstep. */
async function revokeById(id: string) {
  if (!id || !TOKEN_ID_RE.test(id)) {
    console.error('Usage: auth revoke --id <uuid>   (ids are shown by `gbrain auth list`)');
    process.exit(1);
  }
  await withConfiguredSql(async (sql) => {
    const rows = await sql`
      UPDATE access_tokens SET revoked_at = now()
      WHERE id = ${id}::uuid AND revoked_at IS NULL
      RETURNING name
    `;
    if (rows.length === 0) {
      console.error(`No active token found with id "${id}".`);
      process.exit(1);
    }
    await (await import('../core/wakeshift/forget.ts')).forgetWakePrincipal(sql, { kind: 'legacy_token', id });
    console.log(`Token "${rows[0].name}" (${id}) revoked.`);
  });
}

async function test(url: string, token: string) {
  if (!url || !token) {
    console.error('Usage: auth test <url> --token <token>');
    process.exit(1);
  }

  const startTime = Date.now();
  console.log(`Testing MCP server at ${url}...\n`);

  // Step 1: Initialize
  try {
    const initRes = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`,
        'Accept': 'application/json, text/event-stream',
      },
      body: JSON.stringify({
        jsonrpc: '2.0',
        method: 'initialize',
        params: {
          protocolVersion: '2025-03-26',
          capabilities: {},
          clientInfo: { name: 'gbrain-smoke-test', version: '1.0' },
        },
        id: 1,
      }),
    });

    if (!initRes.ok) {
      console.error(`  Initialize failed: ${initRes.status} ${initRes.statusText}`);
      const body = await initRes.text();
      if (body) console.error(`  ${body}`);
      process.exit(1);
    }
    console.log('  ✓ Initialize handshake');
  } catch (e: any) {
    console.error(`  ✗ Connection failed: ${e.message}`);
    process.exit(1);
  }

  // Step 2: List tools
  try {
    const listRes = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`,
        'Accept': 'application/json, text/event-stream',
      },
      body: JSON.stringify({
        jsonrpc: '2.0',
        method: 'tools/list',
        params: {},
        id: 2,
      }),
    });

    if (!listRes.ok) {
      console.error(`  ✗ tools/list failed: ${listRes.status}`);
      process.exit(1);
    }

    const text = await listRes.text();
    // Parse SSE or JSON response
    let toolCount = 0;
    if (text.includes('event:')) {
      // SSE format: extract data lines
      const dataLines = text.split('\n').filter(l => l.startsWith('data:'));
      for (const line of dataLines) {
        try {
          const data = JSON.parse(line.slice(5));
          if (data.result?.tools) toolCount = data.result.tools.length;
        } catch { /* skip non-JSON lines */ }
      }
    } else {
      try {
        const data = JSON.parse(text);
        toolCount = data.result?.tools?.length || 0;
      } catch { /* parse error */ }
    }

    console.log(`  ✓ tools/list: ${toolCount} tools available`);
  } catch (e: any) {
    console.error(`  ✗ tools/list failed: ${e.message}`);
    process.exit(1);
  }

  // Step 3: Call get_stats (real tool call)
  try {
    const statsRes = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`,
        'Accept': 'application/json, text/event-stream',
      },
      body: JSON.stringify({
        jsonrpc: '2.0',
        method: 'tools/call',
        params: { name: 'get_stats', arguments: {} },
        id: 3,
      }),
    });

    if (!statsRes.ok) {
      console.error(`  ✗ get_stats failed: ${statsRes.status}`);
      process.exit(1);
    }
    console.log('  ✓ get_stats: brain is responding');
  } catch (e: any) {
    console.error(`  ✗ get_stats failed: ${e.message}`);
    process.exit(1);
  }

  const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
  console.log(`\n🧠 Your brain is live! (${elapsed}s)`);
}

async function revokeClient(clientId: string) {
  if (!clientId) {
    console.error('Usage: auth revoke-client <client_id>');
    process.exit(1);
  }
  try {
    await withConfiguredSql(async (sql) => {
      // Atomic single-statement delete: no race window between count + delete.
      // Postgres cascades to oauth_tokens and oauth_codes (FK ON DELETE CASCADE
      // declared in src/schema.sql:370,382) before the transaction commits.
      const rows = await sql`
        DELETE FROM oauth_clients WHERE client_id = ${clientId}
        RETURNING client_id, client_name
      `;
      if (rows.length === 0) {
        console.error(`No client found with id "${clientId}"`);
        process.exit(1);
      }
      await (await import('../core/wakeshift/forget.ts')).forgetWakePrincipal(sql, { kind: 'oauth_client', id: clientId });
      console.log(`OAuth client revoked: "${rows[0].client_name}" (${clientId})`);
      console.log('Tokens and authorization codes purged via cascade.');
    });
  } catch (e: any) {
    console.error('Error:', e.message);
    process.exit(1);
  }
}

/**
 * Parse `gbrain auth register-client` argv. Walks the array once instead of
 * the prior `indexOf`-based pattern which (a) silently took only the FIRST
 * occurrence of a repeatable flag (defeated `--redirect-uri https://a
 * --redirect-uri https://b` — only `https://a` made it through), and (b)
 * accepted bare values via lookahead even when adjacent to another flag.
 *
 * v0.41.3 (T3): proper loop-based parser so `--redirect-uri` is repeatable,
 * and `--token-endpoint-auth-method` is recognized. Repeatable flags
 * accumulate into arrays. Unknown flags throw a usage error.
 */
export interface RegisterClientArgs {
  grantTypes: string[];
  scopes: string;
  sourceId: string;
  federatedRead: string[] | undefined;
  redirectUris: string[];
  tokenEndpointAuthMethod: string | undefined;
  boundTools: string[] | undefined;
  delegatedSlugPrefixes?: string[] | null;
  delegatedNamespace?: 'prefixes' | 'job';
  boundSourceId: string | undefined;
  boundBrainId: string | undefined;
  boundSlugPrefixes: string[] | undefined;
  boundMaxConcurrent: number | undefined;
  budgetUsdPerDay: string | null | undefined;
  tokenTtlSeconds: number | undefined;
}

/** --token-ttl bounds: 1 minute .. 90 days (defined in src/core/grants/model.ts). The SERVER default for CLI-minted
 * access tokens is 3600s (oauth-provider.ts tokenTtl) — NOT 30 days; callers
 * that promise long-lived tokens must write oauth_clients.token_ttl. */
export { TOKEN_TTL_MIN_SECONDS, TOKEN_TTL_MAX_SECONDS };

/**
 * Shared --token-ttl value parser (auth register-client + agent register).
 * `hint` is the parser-specific tail naming what omitting the flag means
 * (the two commands have different defaults). Throws the canonical bounds
 * message on anything outside [TOKEN_TTL_MIN_SECONDS, TOKEN_TTL_MAX_SECONDS].
 */
export function parseTokenTtl(raw: string, hint: string): number {
  const v = Number(raw);
  if (!Number.isInteger(v) || v < TOKEN_TTL_MIN_SECONDS || v > TOKEN_TTL_MAX_SECONDS) {
    throw new Error(
      `--token-ttl must be an integer number of seconds between ${TOKEN_TTL_MIN_SECONDS} and ${TOKEN_TTL_MAX_SECONDS} (90 days); got ${JSON.stringify(raw)}. ${hint}`,
    );
  }
  return v;
}

export function parseRegisterClientArgs(args: string[]): RegisterClientArgs {
  const out: RegisterClientArgs = {
    grantTypes: ['client_credentials'],
    scopes: 'read',
    sourceId: 'default',
    federatedRead: undefined,
    redirectUris: [],
    tokenEndpointAuthMethod: undefined,
    boundTools: undefined,
    boundSourceId: undefined,
    boundBrainId: undefined,
    boundSlugPrefixes: undefined,
    boundMaxConcurrent: undefined,
    budgetUsdPerDay: undefined,
    tokenTtlSeconds: undefined,
  };
  let i = 0;
  let grantTypesSet = false;
  while (i < args.length) {
    const flag = args[i];
    const value = args[i + 1];
    const requireValue = () => {
      if (value === undefined || value.startsWith('--')) {
        throw new Error(`${flag} requires a value`);
      }
      return value;
    };
    switch (flag) {
      case '--grant-types': {
        const v = requireValue();
        out.grantTypes = v.split(',').map(s => s.trim()).filter(Boolean);
        grantTypesSet = out.grantTypes.length > 0;
        i += 2;
        break;
      }
      case '--scopes': {
        // v0.42.x: accept comma-separated input (`--scopes read,write,admin`)
        // in addition to the space-separated OAuth wire form
        // (`--scopes "read write admin"`). init.ts's own registration hint
        // (line ~730) recommends the comma form, but the parser previously
        // only split on whitespace, so a comma-joined string fell through
        // as a single unrecognized token and registerClientManual's
        // assertAllowedScopes rejected it as `Unknown scope
        // "read,write,admin"` — self-contradicting the hint. Normalizing
        // here (rather than in the shared parseScopeString) keeps that
        // function's OAuth-wire-format (RFC 6749 space-delimited) contract
        // intact for DCR/refresh/request-scope parsing, which stays
        // comma-agnostic on purpose.
        const v = requireValue();
        const normalized = v.split(/[\s,]+/).filter(Boolean).join(' ');
        // Zero-token input (`--scopes ","`, `--scopes ",,,"`, `--scopes "  "`,
        // `--scopes ""`) collapses to an empty string under the split above.
        // parseScopeString('') returns [] downstream, and
        // assertAllowedScopes([]) passes vacuously on an empty list — so
        // without this guard, registerClientManual would silently register
        // a client with no usable scopes instead of reporting malformed
        // input. Reject here, at the parser boundary, with a clear message
        // rather than relying on whatever downstream error the raw string
        // happens to produce.
        if (!normalized) {
          throw new Error(`--scopes requires at least one scope (got ${JSON.stringify(v)})`);
        }
        out.scopes = normalized;
        i += 2; break;
      }
      case '--source': out.sourceId = requireValue(); i += 2; break;
      case '--federated-read': {
        const v = requireValue();
        out.federatedRead = v.split(',').map(s => s.trim()).filter(Boolean);
        i += 2; break;
      }
      case '--redirect-uri':
        out.redirectUris.push(requireValue());
        i += 2; break;
      case '--token-endpoint-auth-method':
        out.tokenEndpointAuthMethod = requireValue();
        i += 2; break;
      case '--bound-tools': {
        const v = requireValue();
        out.boundTools = v.split(',').map(s => s.trim()).filter(Boolean);
        if (out.boundTools.length === 0) throw new Error('--bound-tools requires at least one tool name');
        i += 2; break;
      }
      case '--delegated-slug-prefixes': out.delegatedSlugPrefixes = requireValue().split(',').map(s => s.trim()).filter(Boolean); i += 2; break;
      case '--delegated-namespace': {
        const value = requireValue();
        if (value !== 'job' && value !== 'prefixes') throw new Error('--delegated-namespace must be job or prefixes');
        out.delegatedNamespace = value;
        i += 2; break;
      }
      case '--bound-source': out.boundSourceId = requireValue(); i += 2; break;
      case '--bound-brain': out.boundBrainId = requireValue(); i += 2; break;
      case '--bound-slug-prefixes': {
        const v = requireValue();
        out.boundSlugPrefixes = v.split(',').map(s => s.trim()).filter(Boolean);
        i += 2; break;
      }
      case '--bound-max-concurrent': {
        const v = Number(requireValue());
        if (!Number.isInteger(v) || v < 1) {
          throw new Error('--bound-max-concurrent must be a positive integer');
        }
        out.boundMaxConcurrent = v;
        i += 2; break;
      }
      case '--budget-usd-per-day': {
        const v = requireValue();
        if (v !== 'unlimited' && !/^\d+(?:\.\d{1,2})?$/.test(v)) {
          throw new Error('--budget-usd-per-day must be a non-negative decimal with at most 2 decimal places');
        }
        out.budgetUsdPerDay = v === 'unlimited' ? null : v;
        i += 2; break;
      }
      case '--token-ttl': {
        out.tokenTtlSeconds = parseTokenTtl(requireValue(), 'Omit the flag to keep the server default.');
        i += 2; break;
      }
      default:
        throw new Error(`Unknown flag: ${flag}`);
    }
  }
  // v0.41.3: if --grant-types not explicitly set and any --redirect-uri was
  // passed, infer authorization_code + refresh_token. The single-flag path
  // (just --redirect-uri ...) is the SECURITY.md-recommended pre-registration
  // pattern; making operators redundantly pass `--grant-types` is footgun.
  if (!grantTypesSet && out.redirectUris.length > 0) {
    out.grantTypes = ['authorization_code', 'refresh_token'];
  }
  return out;
}

/**
 * Column pre-flight (cathedral-6): decide statement shapes BEFORE any
 * transaction. Postgres/PGLite abort the whole tx on any statement error
 * (25P02) and SqlQuery has no savepoint seam, so "catch 42703 and continue"
 * is impossible inside a tx — optional-column degrades must be decided here,
 * outside, once.
 */
export async function preflightOauthClientColumns(sql: SqlQuery): Promise<Set<string>> {
  const rows = await sql`
    SELECT column_name FROM information_schema.columns
    WHERE table_name = 'oauth_clients'
      AND table_schema = current_schema()
      AND column_name IN ('token_ttl', 'surface', 'federated_read', 'source_id', 'deleted_at')
  `;
  return new Set(rows.map(r => String(r.column_name)));
}

export interface RegisterScopedClientOpts {
  /** Explicit normalized profile snapshot; old callers keep legacy operation grants. */
  grant?: GrantPatch;
  /** GST-1113: runs the grant insert in one transaction (callers not already inside one). */
  transaction?: OAuthTransaction;
  /** Per-client access-token TTL to persist (oauth_clients.token_ttl). */
  tokenTtlSeconds?: number;
  /** Per-client tool-surface tier, written via provider.rescopeClient — the
   * ONLY surface-column writer (sets surface_set_by='operator', the lock
   * request_tools cannot override). Never a raw column UPDATE. */
  surface?: 'verbs' | 'starter' | 'full';
  /** INSTALL_SURFACE_SET_BY when `surface` is an install default (the client lists the memory verbs). */
  surfaceSetBy?: 'operator' | typeof INSTALL_SURFACE_SET_BY;
  /** Result of preflightOauthClientColumns — decides which optional-column
   * writes are attempted. Absent → attempt everything (caller owns errors). */
  columns?: Set<string>;
}

/**
 * The data a scoped-client registration produces — everything a printer
 * (auth register-client's byte-pinned block, agent register's summary,
 * or the admin HTTP route) needs, with ZERO console output produced here.
 */
export interface RegisteredClient {
  clientId: string;
  clientSecret?: string;
  grantTypes: string[];
  scopes: string;
  authMethod: string;
  redirectUris: string[];
  sourceId: string;
  federatedRead: string[];
  surface?: 'verbs' | 'starter' | 'full';
  tokenTtl?: number;
  created: { source: boolean };
  /** Previous surface row value when opts.surface was written (for the
   * post-commit audit row — audit is fail-open and NEVER runs in the tx). */
  surfaceOld?: string | null;
  /** Optional-column writes skipped by the pre-flight (pre-migration brain). */
  skipped?: { tokenTtl?: boolean; surface?: boolean };
}

/**
 * Exit-free, print-free registration core (cathedral-6 seam). Named
 * registerScopedClient — not run*Core — because unlike the other peels it
 * returns data instead of printing. Takes an INJECTED SqlQuery handle:
 * callers on the engine-bound CLI lane pass the dispatcher's engine's sql
 * (a second withConfiguredSql engine self-deadlocks PGLite's single-writer
 * lock); `registerClient` below keeps withConfiguredSql for the
 * early-routed auth lane. Throws on failure — the thin callers own
 * exit/print mapping.
 */
export async function registerScopedClient(
  sql: SqlQuery,
  name: string,
  parsed: RegisterClientArgs,
  opts: RegisterScopedClientOpts = {},
): Promise<RegisteredClient> {
  const { grantTypes, scopes, sourceId, federatedRead, redirectUris, tokenEndpointAuthMethod } = parsed;
  const agentBindings = parsed.boundTools || parsed.boundSourceId || parsed.boundBrainId ||
    parsed.boundSlugPrefixes || parsed.boundMaxConcurrent !== undefined || parsed.budgetUsdPerDay !== undefined
    ? {
      boundTools: parsed.boundTools,
      delegatedSlugPrefixes: parsed.delegatedSlugPrefixes,
      delegatedNamespace: parsed.delegatedNamespace,
      boundSourceId: parsed.boundSourceId,
      boundBrainId: parsed.boundBrainId,
      boundSlugPrefixes: parsed.boundSlugPrefixes,
      boundMaxConcurrent: parsed.boundMaxConcurrent,
      budgetUsdPerDay: parsed.budgetUsdPerDay,
    }
    : undefined;
  const { GBrainOAuthProvider } = await import('../core/oauth-provider.ts');
  const provider = new GBrainOAuthProvider({ sql, transaction: opts.transaction });
  const { clientId, clientSecret } = await provider.registerClientManual(
    name, grantTypes, scopes, redirectUris, sourceId, federatedRead, tokenEndpointAuthMethod, agentBindings, opts.grant,
  );

  const ttl = parsed.tokenTtlSeconds ?? opts.tokenTtlSeconds;
  let tokenTtl: number | undefined;
  let ttlSkipped = false;
  if (ttl !== undefined) {
    if (opts.columns && !opts.columns.has('token_ttl')) {
      // Pre-migration brain: the degrade was decided by the pre-flight,
      // OUTSIDE any transaction — nothing here throws-and-continues.
      ttlSkipped = true;
    } else {
      const updated = await sql`
        UPDATE oauth_clients SET token_ttl = ${ttl}
        WHERE client_id = ${clientId}
        RETURNING client_id
      `;
      if (updated.length === 0) {
        throw new Error(`token_ttl update matched no row for client ${clientId}`);
      }
      tokenTtl = ttl;
    }
  }

  let surfaceApplied: 'verbs' | 'starter' | 'full' | undefined;
  let surfaceOld: string | null | undefined;
  let surfaceSkipped = false;
  if (opts.surface !== undefined) {
    if (opts.columns && !opts.columns.has('surface')) {
      surfaceSkipped = true;
    } else {
      const rescoped = await provider.rescopeClient(clientId, { surface: opts.surface, surfaceSetBy: opts.surfaceSetBy });
      surfaceApplied = opts.surface;
      surfaceOld = rescoped.surfaceOld ?? null;
    }
  }

  return {
    clientId,
    ...(clientSecret ? { clientSecret } : {}),
    grantTypes,
    scopes,
    authMethod: tokenEndpointAuthMethod || 'client_secret_post',
    redirectUris,
    sourceId,
    federatedRead: federatedRead && federatedRead.length > 0 ? federatedRead : [sourceId],
    ...(tokenTtl !== undefined ? { tokenTtl } : {}),
    ...(surfaceApplied !== undefined ? { surface: surfaceApplied } : {}),
    ...(surfaceOld !== undefined ? { surfaceOld } : {}),
    created: { source: false },
    ...(ttlSkipped || surfaceSkipped
      ? { skipped: { ...(ttlSkipped ? { tokenTtl: true } : {}), ...(surfaceSkipped ? { surface: true } : {}) } }
      : {}),
  };
}

/**
 * The exact lines `auth register-client` prints. BYTE-IDENTICAL contract:
 * connect.ts:defaultRegisterOAuthClient regex-scrapes `Client ID:` /
 * `Client Secret:` from this output in PRODUCTION, and 7+ e2e assertions pin
 * it — pinned by test/auth-register-client-output-pin.test.ts. Each array
 * element is one console.log call (embedded \n are intentional).
 */
export function formatRegisterClientOutput(name: string, r: RegisteredClient, parsed: RegisterClientArgs): string[] {
  const hasBindings = parsed.boundTools || parsed.boundSourceId || parsed.boundBrainId ||
    parsed.boundSlugPrefixes || parsed.boundMaxConcurrent !== undefined || parsed.budgetUsdPerDay !== undefined;
  const lines: string[] = [];
  lines.push(`OAuth client registered: "${name}"\n`);
  lines.push(`  Client ID:           ${r.clientId}`);
  if (r.clientSecret) {
    lines.push(`  Client Secret:       ${r.clientSecret}\n`);
  } else {
    lines.push(`  Client Secret:       <public client — none issued>\n`);
  }
  lines.push(`  Grant types:         ${r.grantTypes.join(', ')}`);
  lines.push(`  Scopes:              ${r.scopes}`);
  lines.push(`  Token auth method:   ${r.authMethod}`);
  if (r.redirectUris.length > 0) {
    lines.push(`  Redirect URIs:       ${r.redirectUris.join(', ')}`);
  }
  lines.push(`  Write source:        ${r.sourceId}`);
  lines.push(`  Federated reads:     ${r.federatedRead.join(', ')}`);
  if (hasBindings) {
    lines.push(`  Bound tools:         ${(parsed.boundTools ?? []).join(', ') || '<none>'}`);
    lines.push(`  Bound source:        ${parsed.boundSourceId ?? '<none>'}`);
    lines.push(`  Bound brain:         ${parsed.boundBrainId ?? '<none>'}`);
    lines.push(`  Bound slug prefixes:${parsed.boundSlugPrefixes ? ' ' + parsed.boundSlugPrefixes.join(', ') : ' <none>'}`);
    lines.push(`  Max concurrency:     ${parsed.boundMaxConcurrent ?? 1}`);
    lines.push(`  Daily budget USD:    ${parsed.budgetUsdPerDay ?? '<none>'}`);
  }
  lines.push('');
  if (r.clientSecret) {
    lines.push('Save the client secret — it will not be shown again.');
  } else {
    lines.push('Public client (PKCE-only) — no secret needed.');
  }
  lines.push(`Revoke with: gbrain auth revoke-client "${r.clientId}"`);
  return lines;
}

async function registerClient(name: string, args: string[]) {
  if (!name) {
    console.error('Usage: auth register-client <name> [--grant-types G] [--scopes S] [--source SOURCE] [--federated-read SRC1,SRC2,...] [--redirect-uri URI ...] [--token-endpoint-auth-method client_secret_post|client_secret_basic|none] [--bound-tools T1,T2] [--bound-source SOURCE] [--bound-brain BRAIN] [--bound-slug-prefixes P1,P2] [--bound-max-concurrent N] [--budget-usd-per-day USD] [--token-ttl SECONDS] [--member <id>] [--reads-unscoped --yes]');
    process.exit(1);
  }
  let parsed: RegisterClientArgs;
  let binding: ReturnType<typeof takeBindingFlags>;
  try { binding = takeBindingFlags(args); } catch (e) { exitCliError(e, 'auth'); }
  try {
    parsed = parseRegisterClientArgs(binding.args);
  } catch (e: any) {
    console.error(`Error: ${e.message}`);
    console.error('Usage: auth register-client <name> [--grant-types G] [--scopes S] [--source SOURCE] [--federated-read SRC1,SRC2,...] [--redirect-uri URI ...] [--token-endpoint-auth-method client_secret_post|client_secret_basic|none] [--bound-tools T1,T2] [--bound-source SOURCE] [--bound-brain BRAIN] [--bound-slug-prefixes P1,P2] [--bound-max-concurrent N] [--budget-usd-per-day USD] [--token-ttl SECONDS] [--member <id>] [--reads-unscoped --yes]');
    process.exit(1);
  }

  try {
    await withConfiguredSql(async (sql, engine) => {
      await checkBindingTarget(engine, binding.patch);
      await assertCredentialScoped(engine, binding.patch, 'client', name);
      const columns = parsed.tokenTtlSeconds !== undefined
        ? await preflightOauthClientColumns(sql)
        : undefined;
      const registered = await registerScopedClient(sql, name, parsed, { columns, transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });
      const bound = binding.patch ? await bindCredential(engine, { kind: 'client', id: registered.clientId }, binding.patch) : null;
      if (bound) auditReadsUnscoped(bound, `OAuth client ${registered.clientId}`, false);
      if (registered.skipped?.tokenTtl) {
        console.error('Note: this brain predates the token_ttl column; run `gbrain apply-migrations --yes`, then rescope. The server default TTL applies.');
      }
      for (const line of formatRegisterClientOutput(name, registered, parsed)) {
        console.log(line);
      }
      if (bound) console.log(bindingLine(bound));
      const grant = await readClientGrant(engine, registered.clientId).then(grantFromClient).catch(() => null);
      if (grant && !binding.patch?.mayActFor?.length) writeExposureNotice(sharedTokenNotice({ kind: 'oauth_client', id: registered.clientId, name }, { census: await credentialCensus(engine, grant), serves: await exposureServes(engine) }));
    });
  } catch (e: any) {
    if (e instanceof OperationError) exitCliError(e, 'auth');
    console.error('Error:', e.message);
    process.exit(1);
  }
}

/**
 * v0.42.x (#1914): rescope an existing OAuth client's write source and/or
 * federated read scope. This is the operator surface the DCR registration
 * comment promised ("rescope via the CLI later") — DCR clients land with
 * source_id='default' / federated_read=['default'] and must not self-widen,
 * so widening happens here (trusted local CLI) or via the requireAdmin
 * /admin/api/rescope-client endpoint.
 */
/**
 * WP4: parse the `--surface` rescope value. 'clear' → null (clears both
 * surface AND surface_set_by); one of the three known surfaces → itself;
 * anything else → undefined (caller errors out). Exported for unit tests.
 */
export function parseRescopeSurfaceValue(value: string): 'verbs' | 'starter' | 'full' | null | undefined {
  if (value === 'clear') return null;
  if (value === 'verbs' || value === 'starter' || value === 'full') return value;
  return undefined;
}

async function rescopeClient(clientId: string, args: string[]) {
  if (!clientId) { console.error('Usage: auth rescope-client <client_id> [--profile PROFILE] [grant flags] [--repair] [--dry-run] [--json]  (alias of: gbrain auth rescope --client <client_id>)'); process.exit(1); }
  await runRescope(['--client', clientId, ...args], parseRescopeGrantArgs);
}

/** `gbrain auth rescope-token`: alias of `gbrain auth rescope --token` (src/core/grants/legacy-token.ts). */
async function rescopeToken(args: string[]) {
  await runRescope(args, undefined, true);
}

/**
 * F3 `gbrain auth rescope`: one grant editor for legacy tokens and OAuth
 * clients (src/core/grants/cli.ts splits the target). Refusals print the
 * reason and the next command; with --json they also print a JSON error on
 * stdout so an agent never has to read stderr.
 */
async function runRescope(rawArgs: string[], clientParser?: (args: string[]) => RescopeGrantArgs, tokenArgs = false) {
  const json = rawArgs.includes('--json');
  let binding: ReturnType<typeof takeBindingFlags>;
  try { binding = takeBindingFlags(rawArgs); } catch (e) { exitCliError(e, 'auth'); }
  const args = binding.args;
  const dryRun = args.includes('--dry-run');
  try {
    const command = tokenArgs ? { kind: 'token' as const, args } : splitRescopeTarget(args);
    await withConfiguredSql(async (_sql, engine) => {
      if (command.kind === 'migrate-legacy') return printMigrateLegacy(await migrateLegacyTokens(engine, { dryRun: command.dryRun }), command.json);
      const target = command.kind === 'bare' ? await resolveRescopeTarget(engine, command.name) : command.kind === 'client' ? command : { kind: 'token' as const };
      if (!binding.patch) {
        if (target.kind === 'client') {
          return rescopeClientWith(engine, target.clientId, clientParser ? clientParser(command.args) : parseClientRescopeArgs(target.clientId, command.args));
        }
        const parsedToken = parseRescopeTokenArgs(command.kind === 'bare' ? [command.name, ...command.args] : command.args);
        return printTokenRescope(await rescopeLegacyToken(engine, parsedToken), parsedToken.json);
      }
      // GBRA-218: the binding is validated before any grant changes and applied after them; it is not a grant axis.
      await checkBindingTarget(engine, binding.patch);
      if (target.kind === 'client') {
        const clientId = target.clientId;
        const parsedClient = clientParser ? clientParser(command.args) : parseClientRescopeArgs(clientId, command.args);
        const bindLater = async () => {
          const bound = await bindCredential(engine, { kind: 'client', id: clientId }, binding.patch!, { dryRun });
          auditReadsUnscoped(bound, `OAuth client ${clientId}`, dryRun);
          return bound;
        };
        return rescopeClientWith(engine, clientId, parsedClient, bindLater);
      }
      const tokenArgv = command.kind === 'bare' ? [command.name, ...command.args] : command.args;
      const parsed = parseRescopeTokenArgs(tokenArgv);
      const result = await rescopeLegacyToken(engine, parsed);
      const bound = await bindCredential(engine, { kind: 'token', id: result.id }, binding.patch, { dryRun });
      auditReadsUnscoped(bound, `token ${result.name}`, dryRun);
      printTokenRescope(result, parsed.json, bound);
    });
  } catch (error) {
    if (error instanceof OperationError) exitCliError(error, 'auth');
    const message = error instanceof Error ? error.message : String(error);
    const grantError = error instanceof GrantError ? error : undefined;
    const fix = grantError?.code === 'client_not_found' ? renderAction(CLIENT_NOT_FOUND_FIX, cliRenderContext()) : undefined;
    if (json) {
      console.log(JSON.stringify({ error: { code: grantError?.code ?? 'rescope_failed', reasons: grantError?.reasons ?? [], message, ...(fix ? { fix, docs: 'docs/guides/error-codes.md#client_not_found' } : {}) } }, null, 2));
    }
    console.error('Error:', message);
    if (fix) console.error('Fix: Run gbrain auth clients --json on this brain, then retry with an existing client id. No grants or tokens changed.');
    process.exit(1);
  }
}

/** GST-363: every grant or removal of --reads-unscoped lands in the access-reads-unscoped audit trail. */
function auditReadsUnscoped(b: BindingResult, credential: string, dryRun: boolean): void {
  if (b.reads_unscoped !== undefined && b.changed && !dryRun) logReadsUnscopedChange({ credential, reads_unscoped: b.reads_unscoped, by: 'gbrain auth' });
}

const CLIENT_NOT_FOUND_FIX = {
  argv: ['gbrain', 'auth', 'clients', '--json'], consent: [], actor: 'agent' as const, requires_exclusive: false,
  why: 'Read-only: lists the OAuth clients registered on this brain so the call can be retried with an existing client id. No grants or tokens changed.',
  verify: { argv: ['gbrain', 'auth', 'clients', '--json'] },
};

async function rescopeClientWith(engine: BrainEngine, clientId: string, parsed: RescopeGrantArgs, bind?: () => Promise<BindingResult>) {
  const existing = await readClientGrant(engine, clientId);
  if (parsed.printOnly) {
    const bound = bind ? await bind() : undefined;
    if (parsed.json) {
      console.log(JSON.stringify({ before: existing, after: existing, revision: existing.revision, dryRun: true, changed: false, written: false, principal_grant: grantFromClient(existing), ...(bound ? { binding: bound } : {}) }, null, 2));
      return;
    }
    console.log(`OAuth client grants: ${existing.clientName} (${clientId})`);
    console.log(`  Revision: ${existing.revision}`);
    printClientGrantAxes(existing);
    if (bound) { console.log(bindingLine(bound, parsed.dryRun)); return; }
    console.log(`No change made. To change a grant, pass a grant flag, for example: gbrain auth rescope --client ${clientId} --sources default --dry-run`);
    return;
  }
  const profile = parsed.profile ? resolveGrantProfile({
    profile: parsed.profile, existing, sourceId: parsed.patch.sourceId ?? existing.sourceId ?? 'default',
    boundTools: parsed.patch.boundTools ?? undefined,
    federatedRead: parsed.patch.federatedRead,
    boundSlugPrefixes: parsed.patch.boundSlugPrefixes,
    delegatedSlugPrefixes: parsed.patch.delegatedSlugPrefixes ?? undefined,
    delegatedNamespace: parsed.patch.delegatedNamespace,
  }) : {};
  const result = await rescopeClientGrant(engine, clientId, { ...profile, ...parsed.patch }, {
    actor: 'operator:cli', expectedRevision: parsed.expectedRevision ?? existing.revision,
    repair: parsed.repair, dryRun: parsed.dryRun,
  });
  const bound = bind ? await bind() : undefined;
  if (parsed.json) { console.log(JSON.stringify({ ...result, principal_grant: grantFromClient(result.after), ...(bound ? { binding: bound } : {}) }, null, 2)); return; }
  console.log(`OAuth client ${parsed.dryRun ? 'grant preview' : 'rescoped'}: ${result.after.clientName} (${clientId})`);
  console.log(`  Revision: ${result.before.revision} -> ${result.after.revision}`);
  printClientGrantAxes(result.after, parsed.dryRun ? result.before : undefined);
  if (bound) console.log(bindingLine(bound, parsed.dryRun));
  console.log('Restrictions apply on the next request. Added scopes require a new access token; the client secret is unchanged.');
}

/** A grant's axes, one line each; with `before` (a preview) a changed axis reads `before -> after`. */
function printClientGrantAxes(grant: ClientGrant, before?: ClientGrant) {
  const axes: Array<[string, (g: ClientGrant) => string]> = [['Scopes', g => g.scopes.join(' ') || '<none>'], ['Write source', g => g.sourcesNone ? 'none (every read and write refused)' : String(g.sourceId)],
    ['Federated reads', g => g.federatedRead.join(', ') || '<none>'], ['Operations', g => g.allowedOperations === null ? 'all (no snapshot)' : g.allowedOperations.join(', ') || 'none'],
    ['Slug prefixes', g => g.boundSlugPrefixes?.join(', ') || '<none>'], ['Takes holders', g => g.takesHolders === null ? 'world (default)' : g.takesHolders.join(', ') || 'none (every take hidden)'],
    ['Private pages', g => renderPrivatePages(g.privatePages)], ['Private facts', g => renderPrivateFacts(g.privateFacts)], ['Tool surface', g => g.surface ?? '<server default>'], ['Delegated spending', g => g.budgetUsdPerDay === null ? 'unlimited' : '$' + g.budgetUsdPerDay + '/day']];
  for (const [label, render] of axes) { const after = render(grant), was = before ? render(before) : after; console.log(`  ${label}: ${was === after ? after : `${was} -> ${after}`}`); }
  if (before) for (const line of privateFactsWarning(before.privateFacts, grant.privateFacts)) console.log(line);
}

function printTokenRescope(result: RescopeTokenResult, json: boolean, bound?: BindingResult) {
  if (json) { console.log(JSON.stringify(bound ? { ...result, binding: bound } : result, null, 2)); return; }
  const verb = !result.changed ? 'grants' : result.dryRun ? 'grant preview' : 'rescoped';
  console.log(`Legacy token ${verb}: ${result.name} (${result.id})`);
  const rows: Array<[string, 'sources' | 'takesHolders' | 'operations']> = [['Sources', 'sources'], ['Takes holders', 'takesHolders'], ['Operations', 'operations']];
  for (const [label, key] of rows) {
    const before = renderLegacyGrantAxis(result.before[key]);
    const after = renderLegacyGrantAxis(result.after[key]);
    console.log(`  ${label}: ${before === after ? after : `${before} -> ${after}`}`);
  }
  if (result.before.privatePages || result.after.privatePages) {
    const [ppBefore, ppAfter] = [renderPrivatePages(result.before.privatePages), renderPrivatePages(result.after.privatePages)];
    console.log(`  Private pages: ${ppBefore === ppAfter ? ppAfter : `${ppBefore} -> ${ppAfter}`}`);
  }
  for (const line of privateFactsRescopeLines(result.before.privateFacts, result.after.privateFacts)) console.log(line);
  console.log(`  Grant revision: ${result.revision.before === result.revision.after ? result.revision.after : `${result.revision.before} -> ${result.revision.after}`}`);
  if (bound) console.log(bindingLine(bound, result.dryRun));
  if (result.drift.length && !result.written) {
    console.log(`  Drift: ${result.drift.join(', ')} deny every request (the permissions JSON disagrees with the grant columns). `
      + `Ask the user which grant is intended, then run gbrain auth rescope --token ${result.name} --adopt-permissions or --adopt-columns.`);
  }
  if (result.shape === 'legacy_permissions' && !result.written) {
    console.log(`  Shape: legacy permissions JSON (still enforced). The next grant edit migrates it, or run gbrain auth rescope --migrate-legacy.`);
  }
  if (result.migrated) console.log('  Migrated to the unified grant columns; the permissions JSON is kept as a mirror for older gbrain binaries.');
  if (result.refresh) {
    const { available, added, unregistered, materialized } = result.refresh;
    if (materialized) {
      console.log('  This token has no operation snapshot: it reaches every operation its scopes allow except membership operations, which need explicit approval.');
      console.log('  Adding one writes a snapshot of every operation its scopes allow today plus the ones you add; operations later upgrades add then need --refresh-operations.');
    }
    console.log(`  ${materialized ? 'Operations that need approval' : 'New operations available'}: ${available.length ? available.join(', ') : 'none'}`);
    if (unregistered.length) console.log(`  Granted but no longer registered: ${unregistered.join(', ')}`);
    if (added.length) console.log(`  Added: ${added.join(', ')}`);
    else if (available.length) {
      const add = available.length <= 8 ? `--add ${available.join(',')}` : '--add <op,...>';
      console.log(`  Nothing widened. Grant them with: gbrain auth rescope --token ${result.name} --refresh-operations ${add}${materialized ? '' : ' (or --all-new)'}`);
    }
  }
  if (result.changed && !result.dryRun) console.log('Grants apply on the next request; the token secret is unchanged.');
}

function printMigrateLegacy(result: MigrateLegacyResult, json: boolean) {
  if (json) { console.log(JSON.stringify(result, null, 2)); return; }
  const verb = result.dryRun ? 'Would migrate' : 'Migrated';
  console.log(`${verb} ${result.migrated.length} legacy token(s) to the unified grant columns; no effective grant changes.`);
  for (const t of result.migrated) {
    console.log(`  ${t.name} (${t.id}): sources ${renderLegacyGrantAxis(t.grant.sources)}; takes holders ${renderLegacyGrantAxis(t.grant.takesHolders)}; operations ${renderLegacyGrantAxis(t.grant.operations)}`);
  }
  for (const t of result.skipped) console.log(`  Skipped ${t.name} (${t.id}): ${t.reason}. Fix: ${t.fix}`);
  if (result.dryRun && result.migrated.length) console.log('Apply with: gbrain auth rescope --migrate-legacy');
}

/**
 * E4 (WP4 expansion): `gbrain auth clients [--usage] [--days N] [--json]`.
 *
 * Lists OAuth clients with their scopes + per-client MCP tool surface
 * (`surface` / `surface_set_by`, WP4), and with `--usage` joins the
 * per-client op-call usage from `mcp_request_log` via the shared reader
 * (src/core/mcp-usage.ts — same hygiene rules as the E3 advisor collector
 * and scripts/derive-starter-ops.ts). Legacy bearer tokens that called in
 * the window appear too (they log under their token name) but carry no
 * per-client surface row. stdio clients never appear — that transport does
 * not write mcp_request_log.
 */
export function parseAuthClientsArgs(args: string[]): { usage: boolean; days: number; json: boolean } {
  const out = { usage: false, days: 30, json: false };
  for (let i = 0; i < args.length; i++) {
    const flag = args[i];
    if (flag === '--usage') out.usage = true;
    else if (flag === '--json') out.json = true;
    else if (flag === '--days') {
      const v = Number(args[i + 1]);
      if (!Number.isInteger(v) || v < 1 || v > 3650) {
        throw new Error('--days must be an integer between 1 and 3650');
      }
      out.days = v;
      i++;
    } else {
      throw new Error(`Unknown flag: ${flag}`);
    }
  }
  return out;
}

export interface ClientRow {
  client_id: string;
  client_name: string | null;
  scope: string | null;
  surface: string | null;
  surface_set_by: string | null;
  source_id: string | null;
  federated_read: string[] | null;
  /** The operation snapshot: NULL = none stored; absent = the brain predates the column. */
  allowed_operations?: string[] | null;
  /** Soft-revoke stamp (`auth` lifecycle revoke); absent on schemas without it. */
  deleted_at?: string | Date | null;
  /** GBRA-156 private-pages axis; absent on schemas without it (reads as none). */
  private_pages?: string | null;
  /** GBRA-575 private-facts axis; absent on schemas without it (reads as none). */
  private_facts?: string | null;
}

/** The operation-snapshot axis of one client, as `auth clients` reports it. */
export interface ClientOperationsView {
  /** 'all' = no snapshot (SQL NULL); [] = deny-all; a list = pinned; 'unavailable' = old schema. */
  operations: 'all' | string[] | 'unavailable';
  operations_state: 'all' | 'none' | 'list' | 'unavailable';
  /** true only for 'all': operations later upgrades add are reachable without a regrant. */
  includes_future_operations: boolean | null;
  revoked: boolean;
  /** The re-pin command for a live client with no snapshot. */
  fix?: RenderedAction;
}

/**
 * Four distinct operation states (#6008 visibility): SQL NULL is `all` on the
 * operation-snapshot axis only (scopes, surface and source limits still
 * apply); an empty array refuses every operation; a list is pinned; a schema
 * without the column is `unavailable`, never guessed.
 */
export function clientOperationsView(row: ClientRow): ClientOperationsView {
  const revoked = row.deleted_at != null;
  const ops = row.allowed_operations;
  if (ops === undefined) return { operations: 'unavailable', operations_state: 'unavailable', includes_future_operations: null, revoked };
  if (ops === null) {
    const view: ClientOperationsView = { operations: 'all', operations_state: 'all', includes_future_operations: true, revoked };
    if (revoked) return view;
    view.fix = renderAction({
      argv: ['gbrain', 'auth', 'rescope', '--client', row.client_id, '--operations', '<OPERATIONS>'],
      inputs: [{ name: 'OPERATIONS', how: `Ask the user which operations this client should keep (comma-separated, e.g. search,get_page,remember), or pin a profile instead: gbrain auth rescope --client ${row.client_id} --profile <profile> (${GRANT_PROFILES.join(', ')}).` }],
      consent: [], actor: 'agent', requires_exclusive: false,
      why: 'This client has no operation snapshot, so it reaches every operation its scopes and surface allow, including operations later upgrades add. A pinned list or profile keeps new operations from arriving without a regrant.',
      verify: { argv: ['gbrain', 'auth', 'clients', '--json'] },
    }, cliRenderContext());
    return view;
  }
  return { operations: ops, operations_state: ops.length === 0 ? 'none' : 'list', includes_future_operations: false, revoked };
}

/** Text lines for the operation axis (and revocation) of one client. */
export function clientOperationsLines(row: ClientRow): string[] {
  const view = clientOperationsView(row);
  const lines: string[] = [];
  if (view.revoked) lines.push(`  revoked: ${row.deleted_at instanceof Date ? row.deleted_at.toISOString() : String(row.deleted_at)} (credentials no longer work)`);
  if (view.operations_state === 'unavailable') lines.push('  operations: unavailable (this brain predates per-client operation snapshots)');
  else if (view.operations_state === 'none') lines.push('  operations: none (deny-all snapshot)');
  else if (view.operations_state === 'list') {
    const ops = view.operations as string[];
    lines.push(`  operations: ${ops.length} pinned (${ops.slice(0, 8).join(', ')}${ops.length > 8 ? ', ...' : ''})`);
  } else {
    lines.push('  operations: all (no snapshot; includes operations later upgrades add; scopes, surface and source limits still apply)');
    if (view.fix) lines.push(`    re-pin: gbrain auth rescope --client ${row.client_id} --operations <op,...>  (or --profile <profile>)`);
  }
  return lines;
}

/** Clients whose stored or outstanding access-token lifetime an upgrade brought inside the 90-day maximum. */
export async function tokenLifetimeClampedClients(engine: BrainEngine): Promise<Set<string>> {
  try {
    const rows = await engine.executeRaw<{ client_id: string }>(
      `SELECT DISTINCT client_id FROM oauth_grant_audit WHERE actor = 'migration' AND action IN ('clamp_token_ttl', 'shorten_access_tokens')`,
    );
    return new Set(rows.map(r => r.client_id));
  } catch (e) {
    if (isMissingSchemaObject(e, 'table', 'oauth_grant_audit')) return new Set();
    throw e;
  }
}

async function clientsCmd(args: string[]) {
  const usageLine = 'Usage: auth clients [--usage] [--days N] [--json]';
  let parsed: { usage: boolean; days: number; json: boolean };
  try {
    parsed = parseAuthClientsArgs(args);
  } catch (e: any) {
    console.error(`Error: ${e.message}`);
    console.error(usageLine);
    process.exit(1);
  }
  try {
    await withConfiguredSql(async (_sql, engine) => {
      // Degrade ladder lives in listClientRows: a pre-migration brain still
      // gets the listing (missing columns render as null) instead of an error.
      const clients = await listClientRows(engine);
      const lifetimeClamped = await tokenLifetimeClampedClients(engine);

      const { readClientOpUsageWithCoverage, truncatedWindowNote } = await import('../core/mcp-usage.ts');
      const { clients: usage, coverage } = parsed.usage ? await readClientOpUsageWithCoverage(engine, { days: parsed.days }) : { clients: [], coverage: null };
      const windowNote = coverage?.truncated ? truncatedWindowNote(coverage) : null;
      const usageByToken = new Map(usage.map(u => [u.token_name, u]));
      const clientIds = new Set(clients.map(c => c.client_id));
      const legacyUsage = usage.filter(u => !clientIds.has(u.token_name));

      if (parsed.json) {
        console.log(JSON.stringify({
          window_days: parsed.days,
          usage_included: parsed.usage,
          ...(coverage ? { window_truncated: coverage.truncated, covered_days: coverage.covered_days, pruned_before: coverage.pruned_before, window_note: windowNote } : {}),
          clients: clients.map(c => ({
            client_id: c.client_id,
            client_name: c.client_name,
            scopes: c.scope,
            surface: c.surface,
            surface_set_by: c.surface_set_by,
            source_id: c.source_id,
            federated_read: c.federated_read,
            private_pages: privatePagesFromColumn(c.private_pages),
            private_facts: privatePagesFromColumn(c.private_facts),
            ...clientOperationsView(c),
            revoked_at: c.deleted_at ?? null,
            token_lifetime_clamped: lifetimeClamped.has(c.client_id),
            usage: usageByToken.get(c.client_id) ?? null,
          })),
          // Legacy bearer tokens seen in the window (no oauth_clients row).
          legacy_tokens: legacyUsage,
        }, null, 2));
        return;
      }

      if (clients.length === 0 && legacyUsage.length === 0) {
        console.log('No OAuth clients registered. Register one: gbrain auth register-client "my-client"');
        return;
      }
      if (windowNote) console.log(`${windowNote}\n`);
      const fmtTop = (u: (typeof usage)[number]) =>
        Object.entries(u.ops).slice(0, 5).map(([op, n]) => `${op}(${n})`).join(', ');
      for (const c of clients) {
        const u = usageByToken.get(c.client_id);
        console.log(`${c.client_name ?? '<unnamed>'} (${c.client_id})`);
        const surfaceStr = c.surface
          ? `${c.surface}${c.surface_set_by ? ` (set by ${c.surface_set_by})` : ''}`
          : '<server/config resolution>';
        console.log(`  scopes: ${c.scope ?? '<none>'}    surface: ${surfaceStr}`);
        console.log(`  write source: ${c.source_id ?? '<none>'}    federated reads: ${(c.federated_read ?? []).join(', ') || '<none>'}`);
        console.log(`  private pages: ${renderPrivatePages(privatePagesFromColumn(c.private_pages))}`);
        console.log(`  private facts: ${renderPrivateFacts(privatePagesFromColumn(c.private_facts))}`);
        for (const line of clientOperationsLines(c)) console.log(line);
        if (lifetimeClamped.has(c.client_id)) console.log('  access-token lifetime: clamped to the 90-day maximum by an upgrade (docs/mcp/ADMIN.md#access-token-lifetime)');
        if (parsed.usage) {
          if (u) {
            const auto = u.likely_automation ? '    [automation-shaped: >90% context_pack/delta]' : '';
            console.log(`  calls (${parsed.days}d): ${u.total_calls} across ${u.distinct_ops.length} ops    last seen: ${u.last_seen}${auto}`);
            console.log(`  top ops: ${fmtTop(u)}`);
          } else {
            console.log(`  calls (${parsed.days}d): 0 (no HTTP MCP calls in window; stdio use is not logged)`);
          }
        }
        console.log('');
      }
      if (parsed.usage && legacyUsage.length > 0) {
        console.log(`Legacy bearer tokens seen in the last ${parsed.days}d (no per-client surface row):`);
        for (const u of legacyUsage) {
          const auto = u.likely_automation ? '    [automation-shaped]' : '';
          console.log(`  ${u.token_name}: ${u.total_calls} calls across ${u.distinct_ops.length} ops    last seen: ${u.last_seen}${auto}`);
          console.log(`    top ops: ${fmtTop(u)}`);
        }
      }
    });
  } catch (e: any) {
    console.error('Error:', e.message);
    process.exit(1);
  }
}

/**
 * Entry point for the `gbrain auth` CLI subcommand. Also reused by the
 * direct-script path (see bottom of file) so `bun run src/commands/auth.ts`
 * still works.
 */
/**
 * Parse `auth create` args into `{ name, takesHolders, scopes }`.
 *
 * Exported + pure so the positional-vs-flag logic is unit-testable. Only
 * excludes flag VALUES from the positional search when their flag is
 * present — the pre-v0.41 inline version used `rest[takesIdx + 1]` which
 * resolved to `rest[0]` when `takesIdx === -1`, silently dropping the name on
 * the bare `gbrain auth create <name>` form.
 *
 * --scopes accepts comma- and/or whitespace-separated input (the
 * register-client #3990 normalization precedent). Validation against the
 * allowed scope set happens in create() so the error path exits cleanly.
 */
export function parseAuthCreateArgs(rest: string[]): { name: string; takesHolders?: string[]; scopes?: string[]; minTrust?: TrustTier; error?: string } {
  const takesIdx = rest.indexOf('--takes-holders');
  const takesValue = takesIdx >= 0 ? rest[takesIdx + 1] : undefined;
  // Fail closed on a missing/flag-like value: `--scopes` as the last arg
  // silently minting a grandfathered FULL-ACCESS token is the exact
  // fail-open-by-silent-precedence class the harness parser rejects [X14].
  if (takesIdx >= 0 && (takesValue === undefined || takesValue.startsWith('--'))) {
    return { name: '', error: 'the takes-holders flag requires a value (e.g. world,garry)' };
  }
  const takesHolders = takesValue !== undefined
    ? takesValue.split(',').map(s => s.trim()).filter(Boolean)
    : undefined;
  const scopesIdx = rest.indexOf('--scopes');
  const scopesValue = scopesIdx >= 0 ? rest[scopesIdx + 1] : undefined;
  if (scopesIdx >= 0 && (scopesValue === undefined || scopesValue.startsWith('--'))) {
    return { name: '', error: 'the scopes flag requires a value (e.g. read,write) — omitting it would mint a full-access token' };
  }
  const scopes = scopesValue !== undefined
    ? scopesValue.split(/[\s,]+/).map(s => s.trim()).filter(Boolean)
    : undefined;
  const minIdx = rest.indexOf('--min-trust');
  const minValue = minIdx >= 0 ? rest[minIdx + 1] : undefined;
  if (minIdx >= 0 && !isTrustTier(minValue)) {
    return { name: '', error: `the min-trust flag requires a tier: ${TRUST_TIERS.join(', ')}` };
  }
  const positional = rest.find(a => !a.startsWith('--') && a !== takesValue && a !== scopesValue && a !== minValue);
  return { name: positional || '', takesHolders, ...(scopes !== undefined ? { scopes } : {}), ...(isTrustTier(minValue) ? { minTrust: minValue } : {}) };
}

const AUTH_USAGE = `GBrain Token Management

Admin dashboard login (running HTTP server):
  For "Give me the GBrain admin login link", use POST /admin/api/issue-magic-link
  with the server bootstrap credential through the host's protected credential flow.
  It returns a five-minute, single-use owner login link. Deliver it privately;
  do not GET the generated link to check it. A static /admin/ URL only opens the login page.
  This does not create an MCP bearer token. See docs/mcp/DEPLOY.md.

Usage:
  gbrain auth create <name> [--takes-holders world,garry,brain] [--scopes read,write] [--min-trust <tier>] [--member <id>] [--reads-unscoped --yes]
                                                          Create a legacy bearer token. v0.28: --takes-holders
                                                          sets the per-token allow-list for the takes.holder
                                                          field (default: ["world"]). MCP-bound calls to
                                                          takes_list / takes_search / query filter by this.
                                                          --scopes narrows the token to the listed op scopes
                                                          (comma or space separated; omit = read,write with
                                                          --member, else full access, grandfathered).
                                                          --min-trust sets the token's read floor: reads never
                                                          return rows below that trust tier (${TRUST_TIERS.join(', ')});
                                                          memory_confirm in --scopes lets the token confirm
                                                          memory as you (local CLI only; never via admin API)
                                                          On a brain that serves several people a new token needs
                                                          --member <id>, or --reads-unscoped --yes to read every
                                                          page no rule restricts on purpose (credential_scope_required)
  gbrain auth set-min-trust <client|token> <tier|none>    Set or clear the read floor of an OAuth client (id)
                                                          or legacy token (id or name). Local CLI only.
  gbrain auth list [--json]                                List all tokens (id, scopes, usage, private facts and pages)
  gbrain auth revoke <name>                                Revoke a legacy token (ALL active rows with that name)
  gbrain auth revoke --id <uuid>                           Revoke exactly one token by id (names are not unique)
  gbrain auth rescope --token <name>|--id <uuid>|--client <client_id>|<name> [options]
                                                          Change a legacy token's or OAuth client's grants in
                                                          place. Only the flags you pass change; the secret is
                                                          unchanged. With no grant flag it prints the stored
                                                          grants. A bare name matching both a token and a
                                                          client refuses; pass --token or --client.
     --sources <id1,id2,...|none>                         Source grant (first = write source; 'none' = deny-all,
                                                          scopes and secret unchanged)
     --read-sources <id1,id2,...>                         Client only: a read set that differs from --sources
     --takes-holders <h1,h2,...|none>                     Takes-holder allow-list (default world; 'none' = deny-all)
     --operations <op1,op2,...|none|all>                  Operation snapshot ('none' = deny-all). Client only:
                                                          'all' = no snapshot: every operation the scopes and the
                                                          surface allow, including ones later upgrades add; clears
                                                          the profile (tokens: --reset-default operations)
     --scopes <read,write,...>                            Replace the scopes
     --member <id|none>                                   Bind the token or client to a member: remote reads of
                                                          pages naming readers (readable_by) see what that member
                                                          may read; 'none' unbinds (see gbrain access --help)
     --may-act-for <list|none>                            Shared agents: member ids, group:<id>, guest or * the
                                                          harness may name as a request's audience
                                                          (X-Gbrain-On-Behalf-Of or _meta.on_behalf_of)
     --attest-actor <qm|none> [--attest-ops <op,...>]     A client-credentials client or member-less token may name
                                                          the person a QM call serves (x-qm-actor; linked with gbrain
                                                          access member link); ops default get_write_request,
                                                          memory_recall,memory_write
     --attest-read <person|scope|none>                    How an attested call that names sources reads them:
                                                          person, or scope (every call must then name a person);
                                                          none (default) reads them as the scope
     --private-pages <granted-sources|none>               Remote reads see visibility: private pages in the
                                                          sources this grant names explicitly (never the
                                                          no-grant floor, federation, a client's bound source
                                                          or a request's source_ids); 'none' (default) hides them
${PRIVATE_FACTS_HELP}
     --reset-default <sources,takes-holders,operations>   Token only: restore the auth create default for those axes
     --refresh-operations [--add <op,...>|--all-new]      Token only: preview operations added since the snapshot;
                                                          widen only by the ones --add names (or all with --all-new)
     --if-version <N>                                     Refuse unless the stored grant revision is N
     --adopt-permissions | --adopt-columns                Token only: resolve grant drift by keeping the permissions
                                                          JSON (an older gbrain's edit) or restoring the columns
     --dry-run / --json                                   Preview without writing / machine-readable output
                                                          (--json also prints refusals as JSON on stdout)
     Client-only flags of rescope-client (--surface, --bound-*, --profile, ...) pass through.
  gbrain auth rescope --migrate-legacy [--dry-run] [--json]
                                                          Write the unified grant columns for every token still on
                                                          the permissions-JSON shape; changes no effective grant
  gbrain auth rescope-token <name>|--id <uuid> [options]  Alias of: auth rescope --token <name> [options]
  gbrain auth permissions <name> set-takes-holders <h1,h2,h3>
                                                          Alias of: auth rescope --token <name> --takes-holders
  gbrain auth register-client <name> [options]             Register an OAuth 2.1 client (v0.26+)
     --grant-types <client_credentials,authorization_code>  (default: client_credentials;
                                                            auto-set to authorization_code,refresh_token
                                                            when --redirect-uri is passed)
     --scopes "<read write admin>"                         (default: read)
     --source <id>                                         (default: default)
     --federated-read <id1,id2,...>                        (default: [source])
     --redirect-uri <https://...>                          (v0.41.3+; repeatable; required for authorization_code)
     --token-endpoint-auth-method <method>                 (v0.41.3+; client_secret_post | client_secret_basic | none;
                                                            'none' = public PKCE-only client, no secret minted)
     --member <id> / --may-act-for <list>                  Bind the client to a member (see auth rescope)
     --reads-unscoped --yes                                Read unscoped on a brain that serves several people
                                                          (without it or --member, refused: see auth create)
     --bound-tools <tool1,tool2>                           Bind submit_agent to an allow-list of tools
     --bound-source <id>                                   Bind submit_agent jobs to a source id
     --bound-brain <id>                                    Bind submit_agent jobs to a brain id
     --bound-slug-prefixes <prefix1,prefix2>               Fence ALL direct slug writes (put_page, delete_page,
                                                          tags, links, timeline, revert, raw data) AND
                                                          submit_agent to these prefixes. Each MUST end with
                                                          '/' or '/*' — a boundary-less 'emp-alice' would also
                                                          name 'emp-alice-2/...'. Ops that write by something
                                                          other than a slug (extract_*, forget_fact,
                                                          ontology_propose, sources_*) and POST /ingest become
                                                          unavailable to a bound client. Omit = full-source writes.
     --bound-max-concurrent <n>                            Bound submit_agent concurrency (default: 1)
     --budget-usd-per-day <usd>                            Bound submit_agent daily spend cap
  gbrain auth rescope-client <client_id> [options]        Alias of: auth rescope --client <client_id>, with these
                                                          legacy flags. Change an existing client's source scope
                                                          (e.g. a DCR client stuck on the 'default' source). Only
                                                          the flags you pass change; the other axes are left as-is.
     --source <id>                                        New write source
     --federated-read <id1,id2,...>                       New read-scope source list
     --bound-slug-prefixes <p1,p2|none>                   Replace the slug-prefix write fence ('none' clears it)
     --surface <verbs|starter|full|clear>                 Pin the client's MCP tool surface (operator lock —
                                                          request_tools cannot override; 'clear' removes the pin
                                                          so server/config resolution applies again). Always
                                                          bounded by the server's --surface ceiling.
  gbrain auth clients [--usage] [--days N] [--json]       List OAuth clients with scopes, write source, federated
                                                          reads, tool surface + operation snapshot ('all' = no
                                                          snapshot, includes future operations; re-pin with
                                                          auth rescope --client <id> --operations|--profile). --usage
                                                          joins per-client op-call counts, top ops, and last-seen
                                                          from mcp_request_log (default 30d window; HTTP clients
                                                          only — stdio use is not logged). Automation-shaped
                                                          clients (>90% context_pack/delta) are flagged. A window
                                                          reaching past pruned request-log history says so.
  gbrain auth revoke-client <client_id>                   Hard-delete an OAuth 2.1 client (cascades to tokens + codes)
  gbrain auth local-writer list|register|revoke            Manage durable local CLI/stdio writers (see --help)
  gbrain auth test <url> --token <token>                  Smoke-test a remote MCP server
`;

export async function runAuth(args: string[]): Promise<void> {
  if (args[0] === 'local-writer') {
    const { runPersistenceAdminCli } = await import('./persistence-admin.ts');
    return runPersistenceAdminCli('local-writer', args.slice(1));
  }
  // #4083 follow-up: print usage whenever --help/-h appears ANYWHERE in
  // args, before dispatching to a subcommand. Without this early return,
  // `gbrain auth create foo --help` (or revoke/register-client/... +
  // --help) actually EXECUTES the subcommand instead of showing help,
  // once `auth` joined CLI_ONLY_SELF_HELP and the generic --help
  // short-circuit in cli.ts stopped intercepting it first. Same pattern
  // as sync.ts's own `args.includes('--help') || args.includes('-h')`
  // early-return.
  if (args.includes('--help') || args.includes('-h')) {
    console.log(AUTH_USAGE);
    return;
  }
  const [cmd, ...rest] = args;
  switch (cmd) {
    case 'create': {
      // v0.28: optional --takes-holders world,garry,brain (default: world only)
      // #4043: optional --scopes read,write (default: full access, grandfathered)
      let binding: ReturnType<typeof takeBindingFlags>;
      try { binding = takeBindingFlags(rest); } catch (e) { exitCliError(e, 'auth'); }
      const parsed = parseAuthCreateArgs(binding.args);
      if (parsed.error) {
        console.error(`Error: ${parsed.error}`);
        process.exit(1);
      }
      await create(parsed.name, { takesHolders: parsed.takesHolders, scopes: parsed.scopes, minTrust: parsed.minTrust, binding: binding.patch });
      return;
    }
    case 'set-min-trust': await setMinTrustCmd(rest); return;
    case 'list': await list(rest.includes('--json')); return;
    case 'revoke': {
      if (rest[0] === '--id') { await revokeById(rest[1] || ''); return; }
      await revoke(rest[0]);
      return;
    }
    case 'permissions': {
      // gbrain auth permissions <name> set-takes-holders world,garry
      await permissions(rest[0] || '', rest[1] || '', rest[2]);
      return;
    }
    case 'register-client': await registerClient(rest[0], rest.slice(1)); return;
    case 'rescope-client': await rescopeClient(rest[0], rest.slice(1)); return;
    case 'rescope-token': await rescopeToken(rest); return;
    case 'rescope': await runRescope(rest); return;
    case 'revoke-client': await revokeClient(rest[0]); return;
    case 'clients': await clientsCmd(rest); return;
    case 'test': {
      const tokenIdx = rest.indexOf('--token');
      const url = rest.find(a => !a.startsWith('--') && a !== rest[tokenIdx + 1]);
      const token = tokenIdx >= 0 ? rest[tokenIdx + 1] : '';
      await test(url || '', token || '');
      return;
    }
    default:
      console.log(AUTH_USAGE);
  }
}

// Direct-script entry point — only runs when this file is invoked as the main module
// (e.g. `bun run src/commands/auth.ts ...`). When imported by cli.ts, this block is skipped.
if (import.meta.main) {
  const { directEntryArgs } = await import('../cli/flag-equals.ts');
  const { exitCliError } = await import('../cli/cli-error.ts');
  const argv = await directEntryArgs('auth', process.argv.slice(2)).catch((e: unknown) => exitCliError(e, 'auth'));
  if ('refusal' in argv) exitCliError(argv.refusal, 'auth', { legacy: argv.legacy });
  else await runAuth(argv.args);
}