Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
22.1 KB
Raw Blame
import { lstatSync } from 'node:fs';
import { resolve } from 'node:path';
import { setCliExitVerdict } from '../core/cli-force-exit.ts';
import { assertNoSymlinks } from '../core/agent-install/state.ts';
import { writeCredentials } from '../core/harness/credentials.ts';
import { validateOAuthClientSetup, writeOAuthClientSetup } from '../core/harness/oauth-setup.ts';
import { harnessAdapter } from '../core/harness/registry.ts';
import { normalizeScopesInput } from '../core/scope.ts';
import { GRANT_PROFILES } from '../core/grants/model.ts';
import { createMcpAdminHttp, McpAdminError, redactAdminValue, type McpAdminHttpOptions } from './mcp-admin-http.ts';

const HELP = `gbrain mcp admin — administer a running server with owner credentials

gbrain mcp admin login-link [--oauth-request ID]
gbrain mcp admin clients
gbrain mcp admin client ID
gbrain mcp admin register NAME --redirect-uri URI [--redirect-uri URI ...]
gbrain mcp admin setup ID --harness ID [--flow authorization-code|client-credentials]
gbrain mcp admin invalidate-tokens|revoke|delete ID [--yes --if-version N]
gbrain mcp admin attest CLIENT_ID --attest-actor qm|none [--attest-ops LIST] [--attest-read person|scope|none] [--dry-run]
gbrain mcp admin members [--all]
gbrain mcp admin member-add ID [--name NAME] [--email ADDR] [--groups G1,G2]
gbrain mcp admin member-set ID --email ADDR|none
gbrain mcp admin member-disable|member-enable ID
gbrain mcp admin links [--member ID]
gbrain mcp admin link MEMBER --qm CANONICAL_ID [--dry-run]
gbrain mcp admin link --email ADDR --qm CANONICAL_ID [--dry-run]
gbrain mcp admin unlink --qm CANONICAL_ID [--dry-run]
gbrain mcp admin memory-proposals list [--source SOURCE] [--cursor CURSOR]
gbrain mcp admin memory-proposals show REQUEST_ID
gbrain mcp admin memory-proposals approve REQUEST_ID [--dry-run]
gbrain mcp admin memory-proposals deny REQUEST_ID --reason TEXT [--dry-run]

--url URL                          Running server URL or /mcp endpoint (required)
--admin-token-file FILE            Private owner credential; otherwise GBRAIN_ADMIN_BOOTSTRAP_TOKEN
--harness ID                       Setup instructions for this harness (default: generic)
--flow FLOW                        Required when an existing client supports both flows
--token-endpoint-auth-method METHOD none (default), client_secret_post, client_secret_basic
--source SOURCE                    New registration write source (default: default); memory-proposals list: only this source
--cursor CURSOR                    memory-proposals list: the next_cursor of the previous page (50 a page, oldest first)
--reason TEXT                      memory-proposals deny: 1 to 500 characters the proposer reads on its receipt
--federated-read S1,S2              New registration read sources
--scopes SCOPES                    New registration scopes (default: read)
--profile PROFILE                  Apply a named access profile during registration
--credentials-out FILE             Explicit private export; required for confidential registration
--dry-run                          Preview registration or lifecycle consequences
--yes --if-version N               Apply reviewed lifecycle action; otherwise preview only
--attest-actor qm|none             Grant or clear the right to name the person a call serves (x-qm-actor)
--attest-ops LIST                  Operations an attested call may run (default get_write_request,memory_recall,memory_write)
--attest-read person|scope|none    How a call that names sources reads them: as the person, or as their audience (none: the default, scope)
--qm ID                            A canonical person id from the trusted system
--email ADDR                       A member's declared email (case-folded, unique); link finds the member by it
--timeout-ms N                     Request timeout, 100..300000 (default: 30000)
--json                             Structured result; credentials stay in private exports

Registration creates authorization_code and refresh_token grants. The native client
initiates OAuth and owns its PKCE verifier. For machine access use gbrain mcp grant.
Setup returns metadata and instructions; add --credentials-out for a private export.
Login links are single-use: deliver the link to the owner without fetching it.
OAuth admin scope does not grant owner administration authority.
`;

type Flow = 'authorization-code' | 'client-credentials';
interface AdminArgs {
  command: string;
  sub?: string;
  target?: string;
  values: Map<string, string[]>;
  flags: Set<string>;
}
const common = ['--url', '--admin-token-file', '--timeout-ms'];
const commandValues: Record<string, string[]> = {
  'login-link': ['--oauth-request'], clients: [], client: [],
  register: ['--redirect-uri', '--token-endpoint-auth-method', '--source', '--federated-read', '--scopes', '--profile', '--credentials-out', '--harness'],
  setup: ['--harness', '--flow', '--credentials-out'],
  'invalidate-tokens': ['--if-version'], revoke: ['--if-version'], delete: ['--if-version'],
  attest: ['--attest-actor', '--attest-ops', '--attest-read'], members: [], 'member-add': ['--name', '--groups', '--email'], 'member-set': ['--email'], 'member-disable': [], 'member-enable': [],
  links: ['--member'], link: ['--qm', '--email'], unlink: ['--qm'], 'memory-proposals': [],
};
/** GST-2407: memory-proposals takes a subcommand; show, approve and deny take exactly one request id. */
const proposalValues: Record<string, string[]> = { list: ['--source', '--cursor'], show: [], approve: [], deny: ['--reason'] };
const untargeted = ['login-link', 'clients', 'members', 'links', 'unlink'];
const previewable = ['register', 'invalidate-tokens', 'revoke', 'delete', 'attest', 'link', 'unlink'];

export function parseMcpAdmin(args: string[]): AdminArgs {
  const command = args[0];
  if (!command || !Object.hasOwn(commandValues, command)) throw new McpAdminError('invalid_admin_command', `Expected one of: ${Object.keys(commandValues).join(', ')}. Use mcp admin --help.`);
  const proposals = command === 'memory-proposals';
  const sub = proposals ? args[1] : undefined;
  if (proposals && !Object.hasOwn(proposalValues, sub ?? '')) throw new McpAdminError('invalid_admin_command', 'memory-proposals takes list, show, approve or deny.');
  const at = proposals ? 2 : 1;
  const targeted = proposals ? sub !== 'list' : !untargeted.includes(command) && !(command === 'link' && args[1]?.startsWith('-'));
  const target = targeted ? args[at] : undefined;
  if (targeted && (!target || target.startsWith('-'))) throw new McpAdminError('missing_target', `${proposals ? `memory-proposals ${sub}` : command} requires ${proposals ? 'a request ID' : command === 'register' ? 'a name' : command.startsWith('member') || command === 'link' ? 'a member ID' : 'a client ID'}.`);
  const allowedValues = new Set([...common, ...(proposals ? proposalValues[sub!]! : commandValues[command])]);
  const lifecycle = ['invalidate-tokens', 'revoke', 'delete'].includes(command);
  const preview = proposals ? sub === 'approve' || sub === 'deny' : previewable.includes(command);
  const allowedFlags = new Set(['--json', ...(preview ? ['--dry-run'] : []), ...(lifecycle ? ['--yes'] : []), ...(command === 'members' ? ['--all'] : [])]);
  const values = new Map<string, string[]>();
  const flags = new Set<string>();
  for (let i = targeted ? at + 1 : at; i < args.length; i++) {
    const flag = args[i];
    if (allowedFlags.has(flag)) {
      if (flags.has(flag)) throw new McpAdminError('invalid_arguments', `Duplicate argument: ${flag}`);
      flags.add(flag);
    } else if (allowedValues.has(flag)) {
      if (values.has(flag) && flag !== '--redirect-uri') throw new McpAdminError('invalid_arguments', `Duplicate argument: ${flag}`);
      const value = args[++i];
      if (!value || value.startsWith('--')) throw new McpAdminError('invalid_arguments', `${flag} requires a value.`);
      values.set(flag, [...(values.get(flag) ?? []), value]);
    } else throw new McpAdminError('invalid_arguments', `Unknown administration argument: ${flag}. Use --help.`);
  }
  if (!values.has('--url')) throw new McpAdminError('invalid_arguments', '--url is required. Point it at the existing running server.');
  if (flags.has('--yes') && flags.has('--dry-run')) throw new McpAdminError('invalid_arguments', 'Choose --dry-run or --yes, not both.');
  if (flags.has('--yes') && !values.has('--if-version')) throw new McpAdminError('revision_required', 'Preview the action first, then apply with --yes --if-version <reviewed-revision>.');
  return { command, ...(sub === undefined ? {} : { sub }), target, values, flags };
}

type AdminClient = ReturnType<typeof createMcpAdminHttp>;
const list = (raw: string | undefined) => raw === undefined ? undefined : raw.split(',').map(s => s.trim()).filter(Boolean);

/** GST-1094 gap 4: the attest right, members and canonical-id links, over the owner session (serve-http-access.ts). */
const ACCESS_COMMANDS: Record<string, (client: AdminClient, parsed: AdminArgs, value: (flag: string) => string | undefined) => Promise<unknown>> = {
  attest: (client, parsed, value) => {
    const actor = value('--attest-actor');
    const ops = value('--attest-ops');
    const read = value('--attest-read');
    if (actor === undefined && ops === undefined && read === undefined) throw new McpAdminError('invalid_arguments', 'attest needs --attest-actor qm|none, --attest-ops <list> and/or --attest-read person|scope|none.');
    const dryRun = parsed.flags.has('--dry-run');
    return client.request('/admin/api/access/attest', { method: 'POST', mutation: !dryRun, nextAction: `gbrain mcp admin client ${parsed.target} --url ${client.base}`, body: {
      clientId: parsed.target, dryRun, ...(actor === undefined ? {} : { attestActor: actor === 'none' ? null : actor }), ...(ops === undefined ? {} : { attestOps: list(ops) }), ...(read === undefined ? {} : { attestRead: read === 'none' ? null : read }) } });
  },
  members: (client, parsed) => client.request(`/admin/api/access/members${parsed.flags.has('--all') ? '?all=1' : ''}`),
  'member-add': (client, parsed, value) => client.request('/admin/api/access/members', { method: 'POST', mutation: true, nextAction: `gbrain mcp admin members --url ${client.base}`,
    body: { action: 'add', id: parsed.target, ...(value('--name') === undefined ? {} : { name: value('--name') }), ...(value('--email') === undefined ? {} : { email: value('--email') }),
      ...(value('--groups') === undefined ? {} : { groups: list(value('--groups')) }) } }),
  'member-set': (client, parsed, value) => {
    const email = value('--email');
    if (email === undefined) throw new McpAdminError('invalid_arguments', 'member-set needs --email <addr>|none.');
    return client.request('/admin/api/access/members', { method: 'POST', mutation: true, nextAction: `gbrain mcp admin members --url ${client.base}`, body: { action: 'set', id: parsed.target, email: email === 'none' ? null : email } });
  },
  'member-disable': (client, parsed) => client.request('/admin/api/access/members', { method: 'POST', mutation: true, nextAction: `gbrain mcp admin members --url ${client.base}`, body: { action: 'disable', id: parsed.target } }),
  'member-enable': (client, parsed) => client.request('/admin/api/access/members', { method: 'POST', mutation: true, nextAction: `gbrain mcp admin members --url ${client.base}`, body: { action: 'enable', id: parsed.target } }),
  links: (client, _parsed, value) => client.request(`/admin/api/access/member-links${value('--member') ? `?member=${encodeURIComponent(value('--member')!)}` : ''}`),
  link: (client, parsed, value) => linkRequest(client, parsed, value, 'link'),
  unlink: (client, parsed, value) => linkRequest(client, parsed, value, 'unlink'),
  'memory-proposals': (client, parsed, value) => {
    if (parsed.sub === 'list') {
      const query = new URLSearchParams({ ...(value('--source') === undefined ? {} : { source: value('--source')! }), ...(value('--cursor') === undefined ? {} : { cursor: value('--cursor')! }) });
      return client.request(`/admin/api/memory-proposals${query.size ? `?${query}` : ''}`);
    }
    const path = `/admin/api/memory-proposals/${encodeURIComponent(parsed.target!)}`;
    if (parsed.sub === 'show') return client.request(path);
    const reason = value('--reason');
    if (parsed.sub === 'deny' && reason === undefined) throw new McpAdminError('invalid_arguments', 'deny needs --reason TEXT: the proposer reads it on its receipt.');
    const dryRun = parsed.flags.has('--dry-run');
    return client.request(path, { method: 'POST', mutation: !dryRun, nextAction: `gbrain mcp admin memory-proposals show ${parsed.target} --url ${client.base}`,
      body: { action: parsed.sub, dryRun, ...(reason === undefined ? {} : { reason }) } });
  },
};

function linkRequest(client: AdminClient, parsed: AdminArgs, value: (flag: string) => string | undefined, action: 'link' | 'unlink'): Promise<unknown> {
  const externalId = value('--qm');
  if (externalId === undefined) throw new McpAdminError('invalid_arguments', `${action} needs --qm <canonical id>.`);
  const email = value('--email');
  if (action === 'link' && (email === undefined) === (parsed.target === undefined)) throw new McpAdminError('invalid_arguments', 'link needs a member ID or --email <addr>, not both.');
  const dryRun = parsed.flags.has('--dry-run');
  return client.request('/admin/api/access/member-links', { method: 'POST', mutation: !dryRun, nextAction: `gbrain mcp admin links --url ${client.base}`,
    body: { action, externalId, dryRun, ...(action === 'link' ? (email === undefined ? { member: parsed.target } : { email }) : {}) } });
}

function destinationAvailable(path: string): void {
  const target = resolve(path);
  assertNoSymlinks(target);
  try { lstatSync(target); throw new McpAdminError('credential_destination_exists', 'The credential destination already exists. Choose a new private output file.'); }
  catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
}

function saveExport(path: string, result: Record<string, unknown>): void {
  if (result.oauthSetup) {
    const setup = validateOAuthClientSetup(result.oauthSetup);
    if (setup.client.token_endpoint_auth_method !== 'none' && !setup.client.client_secret) throw new Error('Confidential export is missing its client secret');
    writeOAuthClientSetup(path, setup);
  }
  else if (result.credentials) writeCredentials(path, result.credentials as Parameters<typeof writeCredentials>[1]);
  else throw new Error('Server did not return a private setup export');
}

function flowValue(value: string | undefined): Flow | undefined {
  if (value === undefined) return undefined;
  const flow = value.replace(/_/g, '-');
  if (flow !== 'authorization-code' && flow !== 'client-credentials') throw new McpAdminError('invalid_flow', '--flow must be authorization-code or client-credentials.');
  return flow;
}

export async function runMcpAdmin(args: string[], dependencies: Pick<McpAdminHttpOptions, 'fetchImpl' | 'bootstrapToken'> = {}): Promise<void> {
  let sanitize = (message: string) => String(redactAdminValue(message, [dependencies.bootstrapToken ?? process.env.GBRAIN_ADMIN_BOOTSTRAP_TOKEN ?? '']));
  let stage = 'input'; let endpoint: string | undefined; let clientId: string | undefined;
  try {
    if (!args.length || args.includes('--help') || args.includes('-h')) { console.log(HELP); return; }
    const parsed = parseMcpAdmin(args);
    stage = parsed.command;
    if (!['register', 'link', 'memory-proposals'].includes(parsed.command) && !parsed.command.startsWith('member')) clientId = parsed.target;
    const value = (flag: string) => parsed.values.get(flag)?.[0];
    const json = parsed.flags.has('--json');
    const print = (result: unknown) => console.log(sanitize(JSON.stringify(redactAdminValue(result), null, json ? undefined : 2)));
    const client = createMcpAdminHttp({ url: value('--url')!, adminTokenFile: value('--admin-token-file'),
      timeoutMs: value('--timeout-ms') === undefined ? undefined : Number(value('--timeout-ms')), ...dependencies });
    sanitize = client.sanitize;
    endpoint = client.base;
    const inspect = parsed.target && parsed.command !== 'register'
      ? `gbrain mcp admin client ${parsed.target} --url ${client.base}`
      : `gbrain mcp admin clients --url ${client.base}`;
    const path = `/admin/api/clients/${encodeURIComponent(parsed.target ?? '')}`;
    if (parsed.command === 'login-link') {
      const link = await client.loginLink(value('--oauth-request'));
      console.log(JSON.stringify({ status: 'login_link', ...link, next_action: 'Open this single-use link in the owner browser. Do not fetch it to test it.' }, null, json ? undefined : 2));
      return;
    }
    if (parsed.command === 'clients' || parsed.command === 'client') {
      print(await client.request(parsed.command === 'clients' ? '/admin/api/clients' : path));
      return;
    }
    if (parsed.command in ACCESS_COMMANDS) {
      const result = await ACCESS_COMMANDS[parsed.command]!(client, parsed, value);
      print(result);
      if (parsed.sub === 'approve' && (result as { outcome?: string }).outcome === 'failed') setCliExitVerdict(1);
      return;
    }
    if (parsed.command === 'register') {
      const redirects = parsed.values.get('--redirect-uri') ?? [];
      if (!redirects.length) throw new McpAdminError('redirect_uri_required', 'Native OAuth registration requires at least one --redirect-uri supplied by the client harness.');
      const method = value('--token-endpoint-auth-method') ?? 'none';
      if (!['none', 'client_secret_post', 'client_secret_basic'].includes(method)) throw new McpAdminError('invalid_auth_method', 'Choose none, client_secret_post, or client_secret_basic.');
      const dryRun = parsed.flags.has('--dry-run');
      const output = value('--credentials-out');
      if (!dryRun && method !== 'none' && !output) throw new McpAdminError('credential_destination_required', 'Confidential registration requires --credentials-out <private-file> before creating the client.');
      if (!dryRun && output) destinationAvailable(output);
      const profile = value('--profile');
      if (profile !== undefined && !(GRANT_PROFILES as readonly string[]).includes(profile)) throw new McpAdminError('invalid_profile', `Choose a profile from: ${GRANT_PROFILES.join(', ')}.`);
      const harness = harnessAdapter(value('--harness') ?? 'generic').id;
      const result = await client.request('/admin/api/register-client', { method: 'POST', mutation: !dryRun, nextAction: inspect, body: {
        name: parsed.target, grantTypes: ['authorization_code', 'refresh_token'], redirectUris: redirects, tokenEndpointAuthMethod: method, dryRun, harness,
        ...(value('--source') === undefined ? {} : { source: value('--source') }),
        ...(profile === undefined ? {} : { profile }),
        ...(value('--scopes') === undefined ? {} : { scopes: normalizeScopesInput(value('--scopes')) }),
        ...(value('--federated-read') === undefined ? {} : { federatedRead: value('--federated-read')!.split(',').map(s => s.trim()).filter(Boolean) }),
      } });
      if (!dryRun && typeof result.clientId !== 'string') throw new McpAdminError('admin_outcome_unknown', 'Registration returned no client identifier. Inspect the existing client list before another registration.', 'unknown', inspect);
      if (!dryRun) clientId = result.clientId as string;
      if (!dryRun && output) {
        try { saveExport(output, result); }
        catch { throw new McpAdminError('credential_delivery_incomplete', `Registration completed for client ${String(result.clientId)} but its private export could not be saved. Recover setup into a new private file; do not repeat registration.`, undefined,
          `gbrain mcp admin setup ${String(result.clientId)} --harness ${harness} --flow authorization-code --credentials-out <private-file> --url ${client.base}`); }
      }
      const { clientSecret: _secret, credentials: _credentials, ...safe } = result;
      print({ status: dryRun ? 'preview' : 'registered', ...safe, ...(output && !dryRun ? { credential_file: output } : {}) });
      return;
    }
    if (parsed.command === 'setup') {
      const harness = harnessAdapter(value('--harness') ?? 'generic').id;
      const flow = flowValue(value('--flow'));
      const query = new URLSearchParams({ harness, ...(flow === undefined ? {} : { flow }) });
      const result = await client.request(`${path}/setup?${query}`);
      const output = value('--credentials-out');
      if (output) {
        const exported = await client.request('/admin/api/recover-client', { method: 'POST', body: { clientId: parsed.target, harness, ...(flow === undefined ? {} : { flow }) } });
        try { saveExport(output, exported); }
        catch { throw new McpAdminError('credential_delivery_incomplete', 'The private setup export could not be saved. Choose a private output file for this registration and repeat setup.', undefined, inspect); }
      }
      print({ ...result, ...(output ? { credential_file: output } : {}) });
      return;
    }
    const expectedRevision = value('--if-version') === undefined ? undefined : Number(value('--if-version'));
    if (expectedRevision !== undefined && (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0)) throw new McpAdminError('invalid_revision', '--if-version must be a nonnegative integer from a fresh preview.');
    const apply = parsed.flags.has('--yes');
    const result = await client.request(`${path}/lifecycle`, { method: 'POST', mutation: apply, nextAction: inspect,
      body: { action: parsed.command, dryRun: !apply, ...(expectedRevision === undefined ? {} : { expectedRevision }), ...(apply ? { yes: true } : {}) } });
    print(result);
  } catch (error) {
    console.log(JSON.stringify({ status: 'error', reason: error instanceof McpAdminError ? error.code : 'mcp_admin_failed',
      stage, ...(endpoint ? { endpoint } : {}), ...(clientId ? { client_id: sanitize(clientId) } : {}),
      message: sanitize(error instanceof Error ? error.message : 'Administration failed'),
      outcome: error instanceof McpAdminError && error.outcome ? error.outcome : 'failed',
      ...(error instanceof McpAdminError && error.nextAction ? { next_action: sanitize(error.nextAction) } : {}),
      ...(error instanceof McpAdminError && error.httpStatus ? { http_status: error.httpStatus } : {}),
      ...(error instanceof McpAdminError && error.retryAfter ? { retry_after: error.retryAfter } : {}) }));
    setCliExitVerdict(1);
  }
}