Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
20.5 KB
Raw Blame
/**
 * gbrain agent register (cathedral-6) — parser, presets, guards, and the
 * PGLite end-to-end integration (pre-flight → one tx → post-commit audit →
 * exchange → verify round-trip).
 *
 * The 3600s-default regression pin lives here: register ALWAYS writes
 * oauth_clients.token_ttl (default 30d) because the server default for
 * CLI-minted access tokens is one hour.
 */
import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import * as fs from 'node:fs';
import * as path from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { sqlQueryForEngine } from '../src/core/sql-query.ts';
import { GBrainOAuthProvider } from '../src/core/oauth-provider.ts';
import { writeSurfaceChangeAudit } from '../src/core/surface-audit.ts';
import {
  parseAgentRegisterArgs,
  resolvePreset,
  rotateClientSecret,
  ensureWorkspaceSource,
  snapshotGrantSources,
  RegisterError,
  REGISTER_DEFAULT_TOKEN_TTL_SECONDS,
  WORKSPACE_NAME_MAX,
} from '../src/commands/agent-register.ts';
import {
  registerScopedClient,
  preflightOauthClientColumns,
  type RegisterClientArgs,
} from '../src/commands/auth.ts';

function baseRegisterArgs(over: Partial<RegisterClientArgs> = {}): RegisterClientArgs {
  return {
    grantTypes: ['client_credentials'],
    scopes: 'read write',
    sourceId: 'default',
    federatedRead: undefined,
    redirectUris: [],
    tokenEndpointAuthMethod: undefined,
    boundTools: undefined,
    boundSourceId: undefined,
    boundBrainId: undefined,
    boundSlugPrefixes: undefined,
    boundMaxConcurrent: undefined,
    budgetUsdPerDay: undefined,
    tokenTtlSeconds: undefined,
    ...over,
  };
}

// ── parser (pure) ─────────────────────────────────────────────────────────

describe('parseAgentRegisterArgs', () => {
  test('happy path parses all flags', () => {
    const p = parseAgentRegisterArgs([
      'aurora-coder', '--harness', 'claude-code', '--preset', 'coding-agent',
      '--federated-read', 'proj-widget,shared', '--url', 'https://brain.example.com/mcp',
      '--token-ttl', '86400', '--show-token', '--json',
    ]);
    expect(p.name).toBe('aurora-coder');
    expect(p.harness).toBe('claude-code');
    expect(p.preset).toBe('coding-agent');
    expect(p.federatedRead).toEqual(['proj-widget', 'shared']);
    expect(p.tokenTtlSeconds).toBe(86400);
    expect(p.showToken).toBe(true);
    expect(p.json).toBe(true);
  });

  test('requires --harness and validates its values', () => {
    expect(() => parseAgentRegisterArgs(['a'])).toThrow(/--harness is required/);
    expect(() => parseAgentRegisterArgs(['a', '--harness', 'cursor'])).toThrow(/--harness must be one of/);
  });

  test('requires a name (outside --reissue)', () => {
    expect(() => parseAgentRegisterArgs(['--harness', 'codex'])).toThrow(/requires a <name>/);
  });

  test('scope blocklist rejects operator scopes per token', () => {
    for (const bad of ['admin', 'sources_admin', 'users_admin', 'agent']) {
      expect(() => parseAgentRegisterArgs(['a', '--harness', 'codex', '--scopes', `read ${bad}`]))
        .toThrow(/not grantable to an agent client/);
    }
  });

  test('unknown scopes still rejected by the shared allowlist', () => {
    expect(() => parseAgentRegisterArgs(['a', '--harness', 'codex', '--scopes', 'read wrote']))
      .toThrow();
  });

  test('rejects the __all__ literal in --federated-read', () => {
    expect(() => parseAgentRegisterArgs(['a', '--harness', 'codex', '--federated-read', 'default,__all__']))
      .toThrow(/no wildcard read grant exists/);
  });

  test('--federated-read dedupes repeated ids, preserving first-seen order', () => {
    const p = parseAgentRegisterArgs([
      'a', '--harness', 'codex', '--federated-read', 'proj-widget,shared,proj-widget,shared',
    ]);
    expect(p.federatedRead).toEqual(['proj-widget', 'shared']);
  });

  test('url|port mutual exclusion; port bounds', () => {
    expect(() => parseAgentRegisterArgs(['a', '--harness', 'codex', '--url', 'https://x/mcp', '--port', '3131']))
      .toThrow(/--url OR --port/);
    expect(() => parseAgentRegisterArgs(['a', '--harness', 'codex', '--port', '0'])).toThrow(/--port/);
    expect(() => parseAgentRegisterArgs(['a', '--harness', 'codex', '--port', '70000'])).toThrow(/--port/);
  });

  test.each([['0'], ['-1'], ['abc'], ['10000000']])('rejects --token-ttl %s', (raw) => {
    expect(() => parseAgentRegisterArgs(['a', '--harness', 'codex', '--token-ttl', raw]))
      .toThrow(/between 60 and 7776000/);
  });

  test('name validation: shell-unsafe or uppercase names refused', () => {
    expect(() => parseAgentRegisterArgs(['Bad Name', '--harness', 'codex'])).toThrow(/invalid name/);
    expect(() => parseAgentRegisterArgs(['UPPER', '--harness', 'codex'])).toThrow(/invalid name/);
  });

  test('--reissue grammar: no name, no scope flags', () => {
    const p = parseAgentRegisterArgs(['--reissue', 'gbrain_cl_x', '--harness', 'codex']);
    expect(p.reissueClientId).toBe('gbrain_cl_x');
    expect(() => parseAgentRegisterArgs(['name', '--reissue', 'gbrain_cl_x', '--harness', 'codex']))
      .toThrow(/client-id, not a name/);
    expect(() => parseAgentRegisterArgs(['--reissue', 'gbrain_cl_x', '--harness', 'codex', '--scopes', 'read']))
      .toThrow(/scope flags are not allowed/);
  });

  test('unknown flag throws', () => {
    expect(() => parseAgentRegisterArgs(['a', '--harness', 'codex', '--frobnicate'])).toThrow(/Unknown flag/);
  });

  test('--allow-old-serve parses (default false)', () => {
    expect(parseAgentRegisterArgs(['a', '--harness', 'codex']).allowOldServe).toBe(false);
    expect(parseAgentRegisterArgs(['a', '--harness', 'codex', '--allow-old-serve']).allowOldServe).toBe(true);
    // Boolean flag: it must not eat a following positional.
    const p = parseAgentRegisterArgs(['a', '--allow-old-serve', '--harness', 'codex']);
    expect(p.allowOldServe).toBe(true);
    expect(p.name).toBe('a');
    expect(p.harness).toBe('codex');
  });
});

// ── snapshot grant (daily-driver) — workspace exclusion ───────────────────

describe('snapshotGrantSources', () => {
  test('excludes *-workspace sources from the snapshot grant, keeps the rest', () => {
    const r = snapshotGrantSources(['default', 'proj-widget', 'x-workspace', 'nova-notes', 'aurora-coder-workspace']);
    expect(r.granted).toEqual(['default', 'proj-widget', 'nova-notes']);
    expect(r.excludedWorkspaces).toEqual(['x-workspace', 'aurora-coder-workspace']);
  });

  test('no workspaces → nothing excluded', () => {
    const r = snapshotGrantSources(['default', 'proj-widget']);
    expect(r.granted).toEqual(['default', 'proj-widget']);
    expect(r.excludedWorkspaces).toEqual([]);
  });

  test('an EXPLICIT --federated-read grant of a workspace bypasses the snapshot (no filtering)', () => {
    // The exclusion lives in the snapshot branch only: an explicit grant
    // resolves through preset.federatedRead = flags.federatedRead verbatim.
    const flags = { showToken: false, json: false, allowOldServe: false, name: 'aurora', harness: 'claude-code' } as any;
    const r = resolvePreset({ ...flags, preset: 'daily-driver', federatedRead: ['x-workspace', 'proj-widget'] });
    expect(r.federatedRead).toEqual(['x-workspace', 'proj-widget']);
  });
});

// ── presets (pure) ────────────────────────────────────────────────────────

describe('resolvePreset', () => {
  const flags = (over: Record<string, unknown>) =>
    ({ showToken: false, json: false, name: 'aurora', harness: 'claude-code', ...over }) as any;

  test('daily-driver: snapshot grant, default write source, full surface listing the verbs (S0/D4, GBRA-199)', () => {
    const r = resolvePreset(flags({ preset: 'daily-driver' }));
    expect(r).toEqual({
      scopes: 'read write',
      writeSource: 'default',
      federatedRead: 'snapshot',
      surface: 'full',
      surfaceSetBy: 'install',
      workspaceDerived: false,
    });
  });

  test('coding-agent: derived workspace first in the read list, full surface (S0/D4)', () => {
    const r = resolvePreset(flags({ preset: 'coding-agent', federatedRead: ['proj-widget'] }));
    expect(r.writeSource).toBe('aurora-workspace');
    expect(r.workspaceDerived).toBe(true);
    expect(r.federatedRead).toEqual(['aurora-workspace', 'proj-widget']);
    expect(r.surface).toBe('full');
    expect(resolvePreset(flags({ preset: 'coding-agent', federatedRead: ['proj-widget'], surface: 'starter' })).surface).toBe('starter');
  });

  test('coding-agent without --federated-read fails loud', () => {
    expect(() => resolvePreset(flags({ preset: 'coding-agent' }))).toThrow(/requires --federated-read/);
  });

  test('explicit flags beat preset', () => {
    const r = resolvePreset(flags({
      preset: 'coding-agent', federatedRead: ['proj-widget'],
      source: 'shared', scopes: 'read', surface: 'full',
    }));
    expect(r.writeSource).toBe('shared');
    expect(r.workspaceDerived).toBe(false);
    expect(r.scopes).toBe('read');
    expect(r.surface).toBe('full');
  });

  test(`workspace derivation: ${WORKSPACE_NAME_MAX}-char name ok, ${WORKSPACE_NAME_MAX + 1} refused with guidance`, () => {
    const ok = 'a'.repeat(WORKSPACE_NAME_MAX);
    const long = 'a'.repeat(WORKSPACE_NAME_MAX + 1);
    expect(resolvePreset(flags({ name: ok, preset: 'coding-agent', federatedRead: ['x'] })).writeSource)
      .toBe(`${ok}-workspace`);
    expect(() => resolvePreset(flags({ name: long, preset: 'coding-agent', federatedRead: ['x'] })))
      .toThrow(/Pass --source <id> or shorten the name/);
    expect(() => resolvePreset(flags({ name: 'a'.repeat(33), preset: 'coding-agent', federatedRead: ['x'] })))
      .toThrow(/shorten the name/);
  });

  test('underscore names cannot derive a workspace (SOURCE_ID_RE)', () => {
    expect(() => resolvePreset(flags({ name: 'my_agent', preset: 'coding-agent', federatedRead: ['x'] })))
      .toThrow(/Pass --source/);
  });

  test('no preset: passthrough defaults matching auth register-client, no surface', () => {
    const r = resolvePreset(flags({}));
    expect(r).toEqual({
      scopes: 'read write',
      writeSource: 'default',
      federatedRead: ['default'],
      surface: undefined,
      workspaceDerived: false,
    });
  });
});

// ── structural guards (the PGLite self-deadlock class) ───────────────────

describe('structural guards', () => {
  const src = fs.readFileSync(path.join(import.meta.dir, '../src/commands/agent-register.ts'), 'utf8');

  test('agent-register never acquires its own engine (withConfiguredSql / .connect are banned)', () => {
    expect(src).not.toMatch(/withConfiguredSql/);
    expect(src).not.toMatch(/\.connect\(/);
    expect(src).not.toMatch(/createEngine\(/);
  });

  test('registerScopedClient core is print-free and exit-free', () => {
    const auth = fs.readFileSync(path.join(import.meta.dir, '../src/commands/auth.ts'), 'utf8');
    const coreStart = auth.indexOf('export async function registerScopedClient');
    const coreEnd = auth.indexOf('export function formatRegisterClientOutput');
    const core = auth.slice(coreStart, coreEnd);
    expect(coreStart).toBeGreaterThan(0);
    // Call sites only — prose in neighboring docblocks may NAME console.log.
    expect(core).not.toMatch(/console\.\w+\s*\(/);
    expect(core).not.toMatch(/process\.exit\s*\(/);
  });
});

// ── PGLite integration ────────────────────────────────────────────────────

let engine: PGLiteEngine;

beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({ database_url: '' });
  await engine.initSchema();
});

afterAll(async () => {
  await engine.disconnect();
});

beforeEach(async () => {
  await engine.executeRaw('DELETE FROM oauth_tokens');
  await engine.executeRaw('DELETE FROM oauth_clients');
});

describe('PGLite integration (pre-flight → tx → audit → exchange)', () => {
  test('end-to-end: row, ttl, surface via rescope, audit row, verify round-trip', async () => {
    const sql = sqlQueryForEngine(engine);
    const columns = await preflightOauthClientColumns(sql);
    expect(columns.has('token_ttl')).toBe(true);
    expect(columns.has('surface')).toBe(true);
    expect(columns.has('deleted_at')).toBe(true);

    let registered!: Awaited<ReturnType<typeof registerScopedClient>>;
    await engine.transaction(async (tx) => {
      const txSql = sqlQueryForEngine(tx);
      registered = await registerScopedClient(txSql, 'itest-agent', baseRegisterArgs({
        sourceId: 'default',
        federatedRead: ['default'],
      }), {
        tokenTtlSeconds: REGISTER_DEFAULT_TOKEN_TTL_SECONDS,
        surface: 'starter',
        columns,
      });
    });

    expect(registered.tokenTtl).toBe(REGISTER_DEFAULT_TOKEN_TTL_SECONDS);
    expect(registered.surface).toBe('starter');
    expect(registered.clientSecret).toMatch(/^gbrain_cs_/);

    // Row state: ttl written, surface set through the audited writer path
    // (surface_set_by='operator' — the request_tools lock).
    const rows = await engine.executeRaw<Record<string, unknown>>(
      `SELECT token_ttl, surface, surface_set_by FROM oauth_clients WHERE client_id = $1`,
      [registered.clientId],
    );
    expect(rows[0].token_ttl).toBe(REGISTER_DEFAULT_TOKEN_TTL_SECONDS);
    expect(rows[0].surface).toBe('starter');
    expect(rows[0].surface_set_by).toBe('operator');

    // Post-commit fail-open audit (designed position — never inside the tx).
    const audited = await writeSurfaceChangeAudit(engine, {
      actor: 'operator',
      client_id: registered.clientId,
      old: registered.surfaceOld ?? null,
      new: 'starter',
      via: 'register_cli',
    });
    expect(audited).toBe(true);
    const auditRows = await engine.executeRaw<Record<string, unknown>>(
      `SELECT operation FROM mcp_request_log WHERE operation = 'surface_change'`,
    );
    expect(auditRows.length).toBe(1);

    // Exchange on the OUTER engine (tx sql is dead after commit) — the
    // 3600s-default regression pin: expires_in must reflect the 30d column.
    const provider = new GBrainOAuthProvider({ sql, transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });
    const tokens = await provider.exchangeClientCredentials(registered.clientId, registered.clientSecret!);
    expect(tokens.expires_in).toBe(REGISTER_DEFAULT_TOKEN_TTL_SECONDS);

    const auth = await provider.verifyAccessToken(tokens.access_token);
    expect((auth as any).sourceId).toBe('default');
    expect((auth as any).allowedSources).toEqual(['default']);
  });

  test('42703 degrade path: missing columns are skipped OUTSIDE the tx, register still lands', async () => {
    const sql = sqlQueryForEngine(engine);
    // Simulate a pre-migration brain: a column set that lacks token_ttl+surface.
    const columns = new Set(['source_id', 'federated_read', 'deleted_at']);
    let registered!: Awaited<ReturnType<typeof registerScopedClient>>;
    await engine.transaction(async (tx) => {
      const txSql = sqlQueryForEngine(tx);
      registered = await registerScopedClient(txSql, 'itest-degrade', baseRegisterArgs(), {
        tokenTtlSeconds: REGISTER_DEFAULT_TOKEN_TTL_SECONDS,
        surface: 'starter',
        columns,
      });
    });
    expect(registered.skipped).toEqual({ tokenTtl: true, surface: true });
    expect(registered.tokenTtl).toBeUndefined();
    const rows = await engine.executeRaw<Record<string, unknown>>(
      `SELECT client_id, token_ttl FROM oauth_clients WHERE client_id = $1`,
      [registered.clientId],
    );
    expect(rows.length).toBe(1);
    expect(rows[0].token_ttl).toBeNull();
  });

  test('reissue: rotation invalidates the old secret, keeps one row, new secret works', async () => {
    const sql = sqlQueryForEngine(engine);
    let registered!: Awaited<ReturnType<typeof registerScopedClient>>;
    await engine.transaction(async (tx) => {
      registered = await registerScopedClient(sqlQueryForEngine(tx), 'itest-rotate', baseRegisterArgs(), {});
    });
    const oldSecret = registered.clientSecret!;
    const provider = new GBrainOAuthProvider({ sql, transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });
    await provider.exchangeClientCredentials(registered.clientId, oldSecret); // sanity: works pre-rotation

    const newSecret = await rotateClientSecret(engine, registered.clientId, 'itest-rotate');
    expect(newSecret).toMatch(/^gbrain_cs_/);
    expect(newSecret).not.toBe(oldSecret);

    await expect(provider.exchangeClientCredentials(registered.clientId, oldSecret)).rejects.toThrow();
    const tokens = await provider.exchangeClientCredentials(registered.clientId, newSecret);
    expect(tokens.access_token).toBeTruthy();

    const rows = await engine.executeRaw<Record<string, unknown>>(
      `SELECT count(*) AS n FROM oauth_clients WHERE client_name = $1`, ['itest-rotate'],
    );
    expect(Number(rows[0].n)).toBe(1);
  });
});

// ── ensureWorkspaceSource (create-or-clean-reuse, refuse dirty/archived) ──

describe('ensureWorkspaceSource', () => {
  const sql = () => sqlQueryForEngine(engine);

  test('creates the source when missing (returns true)', async () => {
    const created = await ensureWorkspaceSource(engine, sql(), 'ews-new-workspace');
    expect(created).toBe(true);
    const rows = await engine.executeRaw<{ id: string }>(
      `SELECT id FROM sources WHERE id = $1`, ['ews-new-workspace'],
    );
    expect(rows.length).toBe(1);
  });

  test('reuses an existing CLEAN source (returns false)', async () => {
    await engine.executeRaw(
      `INSERT INTO sources (id, name) VALUES ('ews-clean-workspace', 'ews-clean-workspace')`,
    );
    const created = await ensureWorkspaceSource(engine, sql(), 'ews-clean-workspace');
    expect(created).toBe(false);
  });

  test('archived-but-empty workspace is refused with an unarchive hint (never silently reused)', async () => {
    await engine.executeRaw(
      `INSERT INTO sources (id, name, archived) VALUES ('ews-archived-workspace', 'ews-archived-workspace', true)`,
    );
    const caught = await ensureWorkspaceSource(engine, sql(), 'ews-archived-workspace')
      .then(() => null, (e: unknown) => e);
    expect(caught).toBeInstanceOf(RegisterError);
    expect((caught as RegisterError).reason).toBe('archived_source');
    expect((caught as Error).message).toMatch(/exists but is archived — unarchive it/);
  });

  test('source holding pages is dirty', async () => {
    await engine.executeRaw(
      `INSERT INTO sources (id, name) VALUES ('ews-pages-workspace', 'ews-pages-workspace')`,
    );
    await engine.executeRaw(
      `INSERT INTO pages (source_id, slug, type, title) VALUES ('ews-pages-workspace', 'ews/p1', 'note', 'p1')`,
    );
    await expect(ensureWorkspaceSource(engine, sql(), 'ews-pages-workspace'))
      .rejects.toThrow(/holds 1 pages/);
  });

  test('source holding FACTS (zero pages) is dirty too — the primary agent write lane', async () => {
    await engine.executeRaw(
      `INSERT INTO sources (id, name) VALUES ('ews-facts-workspace', 'ews-facts-workspace')`,
    );
    await engine.executeRaw(
      `INSERT INTO facts (source_id, fact, source) VALUES ('ews-facts-workspace', 'agent memory row', 'test')`,
    );
    const caught = await ensureWorkspaceSource(engine, sql(), 'ews-facts-workspace')
      .then(() => null, (e: unknown) => e);
    expect((caught as RegisterError).reason).toBe('dirty_source');
    expect((caught as Error).message).toMatch(/holds 1 facts/);
  });

  test('source backed by a local path is dirty', async () => {
    await engine.executeRaw(
      `INSERT INTO sources (id, name, local_path) VALUES ('ews-path-workspace', 'ews-path-workspace', '/tmp/x')`,
    );
    await expect(ensureWorkspaceSource(engine, sql(), 'ews-path-workspace'))
      .rejects.toThrow(/backed by a local path/);
  });

  test('source holding FILES (zero pages, zero facts) is dirty too — files can exist page-less', async () => {
    await engine.executeRaw(
      `INSERT INTO sources (id, name) VALUES ('ews-files-workspace', 'ews-files-workspace')`,
    );
    await engine.executeRaw(
      `INSERT INTO files (source_id, filename, storage_path, content_hash)
       VALUES ('ews-files-workspace', 'notes.pdf', 'files/notes.pdf', 'deadbeef')`,
    );
    const caught = await ensureWorkspaceSource(engine, sql(), 'ews-files-workspace')
      .then(() => null, (e: unknown) => e);
    expect((caught as RegisterError).reason).toBe('dirty_source');
    expect((caught as Error).message).toMatch(/holds 1 files/);
  });
});