Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
15.1 KB
Raw Blame
/**
 * E2E for the qm-harness integration recipe (docs/integrations/qm-harness.md):
 * roster-driven provisioning + over-the-wire write fencing.
 *
 * PGLite-based and ungated (no DATABASE_URL needed) — PGLite is
 * single-process, so every provisioning step runs BEFORE `serve --http`
 * starts; after that all access goes over HTTP MCP.
 *
 * Pins, end to end:
 *   - provision-scopes.sh creates a path-less shared source + one bound
 *     client per employee, is idempotent on re-run, and RESCOPES in place
 *     (no secret rotation) when the roster changes;
 *   - thin clients (`init --mcp-only`) can write inside their
 *     bound_slug_prefixes and are rejected with the fence error outside
 *     them (v0.42.70.0 enforceClientSlugFence, over the real transport);
 *   - reads stay source-granular (a bob-example client CAN read
 *     chan-eng/ — the documented shared-source tradeoff).
 *
 * Lane: unit. Run: `bun test test/qm-provisioning.test.ts`. Moved from test/e2e/
 * by the 2026-09 lane-move pilot (PGLite-only, no DATABASE_URL); see
 * docs/test-audit/2026-09-29/implementation/lane-pilot.md.
 */

import { describe, test as testRaw, expect, beforeAll, afterAll } from 'bun:test';
import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync } from 'fs';
import { join } from 'path';
import { tmpdir } from 'os';
import { keylessBrainEnv } from './helpers/provider-env.ts';
import { startServeHttp, type ServeHttp } from './helpers/serve-http.ts';
import { cliDiagnostic, fixtureDiagnostic } from './helpers/fixture-diagnostics.ts';

function test(name: string, fn: () => void | Promise<unknown>): void {
  testRaw(name, fn, 120000);
}

const CLI = join(__dirname, '..', 'src', 'cli.ts');
const SCRIPT = join(__dirname, '..', 'docs', 'integrations', 'qm-harness-snippets', 'provision-scopes.sh');

interface RunResult { exitCode: number; stdout: string; stderr: string; }

async function spawn(cmd: string[], env: Record<string, string | undefined>, cwd?: string): Promise<RunResult> {
  const fullEnv = keylessBrainEnv(process.env, env.GBRAIN_HOME!, {
    GBRAIN_REMOTE_CLIENT_SECRET: undefined,
    DATABASE_URL: undefined,
    GBRAIN_DATABASE_URL: undefined,
    ...env,
  });
  const proc = Bun.spawn({ cmd, env: fullEnv, cwd, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' });
  const [stdout, stderr, exitCode] = await Promise.all([
    new Response(proc.stdout).text(),
    new Response(proc.stderr).text(),
    proc.exited,
  ]);
  return { exitCode, stdout, stderr };
}

const gbrain = (args: string[], home: string, extraEnv: Record<string, string | undefined> = {}) =>
  spawn(['bun', '--no-env-file', 'run', CLI, ...args], { GBRAIN_HOME: home, ...extraEnv });

describe('qm-harness provisioning + write fence (e2e, PGLite)', () => {
  let hostHome: string;
  let workDir: string;
  let aliceHome: string;
  let bobHome: string;
  let server: ServeHttp | null = null;
  let serverPort: number;
  const creds: Record<string, { clientId: string; secret: string }> = {};
  let rerunCredsGrew = true; // set false when idempotency holds

  const rosterPath = () => join(workDir, 'roster.tsv');
  const statePath = () => join(workDir, 'roster.tsv.state.tsv');
  const secretsPath = () => join(workDir, 'roster.tsv.new-credentials.tsv');

  async function provision(): Promise<RunResult> {
    return spawn(
      ['bash', SCRIPT, rosterPath(), '--gbrain', `bun --no-env-file run ${CLI}`, '--budget-usd-per-day', '5'],
      { GBRAIN_HOME: hostHome },
      workDir,
    );
  }

  beforeAll(async () => {
    hostHome = mkdtempSync(join(tmpdir(), 'gbrain-qm-host-'));
    workDir = mkdtempSync(join(tmpdir(), 'gbrain-qm-work-'));
    aliceHome = mkdtempSync(join(tmpdir(), 'gbrain-qm-alice-'));
    bobHome = mkdtempSync(join(tmpdir(), 'gbrain-qm-bob-'));

    // 1. Host brain on PGLite, embedding deferred (FTS is enough here).
    const init = await gbrain(['init', '--pglite', '--no-embedding'], hostHome);
    if (init.exitCode !== 0) throw new Error(cliDiagnostic(`host init failed`, init));

    // 2. Roster v1: alice in eng, bob in product.
    writeFileSync(rosterPath(), [
      'channel eng',
      'channel product',
      'employee alice-example eng',
      'employee bob-example product',
      '',
    ].join('\n'));
    const p1 = await provision();
    if (p1.exitCode !== 0) throw new Error(cliDiagnostic(`provision v1 failed`, p1));

    for (const line of readFileSync(secretsPath(), 'utf8').trim().split('\n')) {
      const [slug, clientId, secret] = line.split('\t');
      creds[slug] = { clientId, secret };
    }

    // 3. Idempotency: re-run with the same roster mints no new secrets.
    const before = readFileSync(secretsPath(), 'utf8');
    const p2 = await provision();
    if (p2.exitCode !== 0) throw new Error(cliDiagnostic(`provision re-run failed`, p2));
    rerunCredsGrew = readFileSync(secretsPath(), 'utf8') !== before;

    // 4. Roster churn: alice joins product → rescope in place.
    writeFileSync(rosterPath(), [
      'channel eng',
      'channel product',
      'employee alice-example eng,product',
      'employee bob-example product',
      '',
    ].join('\n'));
    const p3 = await provision();
    if (p3.exitCode !== 0) throw new Error(cliDiagnostic(`provision rescope failed`, p3));

    // 4b. An UNBOUND client, standing in for a webhook integration. Registered
    //     here because PGLite is single-process: once serve --http holds the
    //     lock, no host-side CLI command can run.
    const wh = await gbrain([
      'auth', 'register-client', 'webhook-integration',
      '--grant-types', 'client_credentials', '--scopes', 'read write',
    ], hostHome);
    if (wh.exitCode !== 0) throw new Error(cliDiagnostic(`webhook client registration failed`, wh));
    creds['webhook-integration'] = {
      clientId: wh.stdout.match(/Client ID:\s+(gbrain_cl_\S+)/)?.[1] ?? '',
      secret: wh.stdout.match(/Client Secret:\s+(gbrain_cs_\S+)/)?.[1] ?? '',
    };

    // 5. Serve over HTTP MCP (holds the PGLite lock from here on).
    server = await startServeHttp({
      cwd: process.cwd(),
      env: keylessBrainEnv(process.env, hostHome, {
        DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined, GBRAIN_REMOTE_CLIENT_SECRET: undefined,
      }),
      timeoutMs: 30_000,
    });
    serverPort = server.port;

    // 6. Thin-client bootstrap for both scopes (the once-per-sandbox step).
    //    --oauth-client-secret (NOT the env var) on purpose: an env-sourced
    //    secret is deliberately not persisted to config.json, and qm has no
    //    per-scope env to keep it in. Every later call below runs WITHOUT the
    //    env var, so the suite proves the documented setup actually survives
    //    the init session instead of masking it.
    for (const [slug, home] of [['alice-example', aliceHome], ['bob-example', bobHome]] as const) {
      const tc = await gbrain([
        'init', '--mcp-only',
        '--issuer-url', `http://127.0.0.1:${serverPort}`,
        '--mcp-url', `http://127.0.0.1:${serverPort}/mcp`,
        '--oauth-client-id', creds[slug].clientId,
        '--oauth-client-secret', creds[slug].secret,
      ], home);
      if (tc.exitCode !== 0) throw new Error(cliDiagnostic(`thin-client init (${slug}) failed`, tc));
    }
  }, 300_000);

  afterAll(async () => {
    await server?.stop();
    for (const dir of [hostHome, workDir, aliceHome, bobHome]) {
      if (dir) rmSync(dir, { recursive: true, force: true });
    }
  }, 30_000);

  // No GBRAIN_REMOTE_CLIENT_SECRET: auth must come from the persisted config.
  const asAlice = (args: string[]) => gbrain(args, aliceHome);
  const asBob = (args: string[]) => gbrain(args, bobHome);

  async function mintToken(slug: string): Promise<string> {
    const { clientId, secret } = creds[slug];
    const res = await fetch(`http://127.0.0.1:${serverPort}/token`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: `grant_type=client_credentials&client_id=${encodeURIComponent(clientId)}`
        + `&client_secret=${encodeURIComponent(secret)}&scope=${encodeURIComponent('read write')}`,
    });
    if (!res.ok) throw new Error(fixtureDiagnostic("token mint", `status=${res.status} ${await res.text()}`));
    return ((await res.json()) as { access_token: string }).access_token;
  }

  async function mcpCall(token: string, toolName: string, args: Record<string, unknown>): Promise<string> {
    const res = await fetch(`http://127.0.0.1:${serverPort}/mcp`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
        'Accept': 'application/json, text/event-stream',
      },
      body: JSON.stringify({
        jsonrpc: '2.0', id: 1, method: 'tools/call',
        params: { name: toolName, arguments: args },
      }),
    });
    return res.text();
  }

  test('provisioning minted one bound client per employee, exactly once', () => {
    // Only the roster-provisioned clients; 'webhook-integration' is registered
    // separately by the suite to prove the /ingest deny is scoped to bound clients.
    expect(Object.keys(creds).filter(k => k !== 'webhook-integration').sort())
      .toEqual(['alice-example', 'bob-example']);
    expect(creds['alice-example'].clientId).toStartWith('gbrain_cl_');
    expect(creds['alice-example'].secret).toStartWith('gbrain_cs_');
    expect(rerunCredsGrew).toBe(false);
    expect(existsSync(statePath())).toBe(true);
  });

  test('alice writes inside her prefixes (personal + channel)', async () => {
    const own = await asAlice(['put', 'emp-alice-example/notes/hello', '--content', '# hello\nmine']);
    expect(own.exitCode, cliDiagnostic("qm CLI", own)).toBe(0);
    const chan = await asAlice(['put', 'chan-eng/notes/standup', '--content', '# standup\nshared']);
    expect(chan.exitCode, cliDiagnostic("qm CLI", chan)).toBe(0);
  });

  test('roster churn took effect: alice can write chan-product/ after rescope', async () => {
    const joined = await asAlice(['put', 'chan-product/notes/joined', '--content', '# joined']);
    expect(joined.exitCode, cliDiagnostic("qm CLI", joined)).toBe(0);
  });

  test("alice cannot write bob's namespace or an unbound prefix", async () => {
    const bobNs = await asAlice(['put', 'emp-bob-example/notes/nope', '--content', 'x']);
    expect(bobNs.exitCode, cliDiagnostic("qm CLI", bobNs)).not.toBe(0);
    expect(bobNs.stdout + bobNs.stderr).toMatch(/bound_slug_prefixes/);

    const stray = await asAlice(['put', 'org-notes/anything', '--content', 'x']);
    expect(stray.exitCode, cliDiagnostic("qm CLI", stray)).not.toBe(0);
    expect(stray.stdout + stray.stderr).toMatch(/bound_slug_prefixes/);
  });

  test('bob is fenced to HIS prefixes (not in eng)', async () => {
    const own = await asBob(['put', 'emp-bob-example/notes/hello', '--content', '# hi']);
    expect(own.exitCode, cliDiagnostic("qm CLI", own)).toBe(0);
    const eng = await asBob(['put', 'chan-eng/notes/nope', '--content', 'x']);
    expect(eng.exitCode, cliDiagnostic("qm CLI", eng)).not.toBe(0);
    expect(eng.stdout + eng.stderr).toMatch(/bound_slug_prefixes/);
  });

  test('reads stay source-granular: bob CAN read chan-eng pages (documented tradeoff)', async () => {
    const read = await asBob(['get', 'chan-eng/notes/standup']);
    expect(read.exitCode, cliDiagnostic("qm CLI", read)).toBe(0);
    expect(read.stdout).toContain('standup');
  });

  test('the documented health check works on a read+write client (no admin scope)', async () => {
    const who = await asAlice(['whoami']);
    expect(who.exitCode, cliDiagnostic("qm CLI", who)).toBe(0);
    expect(who.stdout).toContain(creds['alice-example'].clientId);
  });

  test('POST /ingest is closed to bound clients — it bypasses the op layer entirely', async () => {
    const post = async (token: string, slug: string | null) => {
      const headers: Record<string, string> = {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'text/markdown',
      };
      if (slug) headers['X-Gbrain-Slug'] = slug;
      const res = await fetch(`http://127.0.0.1:${serverPort}/ingest`, {
        method: 'POST', headers,
        body: '---\ntype: note\ntitle: x\n---\n# injected',
      });
      return { status: res.status, body: await res.text() };
    };
    const bound = await mintToken('alice-example');

    // The bypass this closes: /ingest queues a job for a handler that skips
    // the put_page op layer AND refuses to honor a source id for untrusted
    // payloads, so the write lands in the `default` source. Fencing only the
    // slug would still have written the right slug into the wrong source.
    const outside = await post(bound, 'wiki/ceo-comp');
    expect(outside.status).toBe(403);
    expect(outside.body).toContain('not available to clients restricted to slug prefixes');

    // Even an IN-prefix slug is refused — the source, not just the slug, is
    // outside the client's grant.
    expect((await post(bound, 'emp-alice-example/inbox/note')).status).toBe(403);
    expect((await post(bound, null)).status).toBe(403);
  });

  test('/ingest still works for an unbound webhook client (deny is scoped to bound clients)', async () => {
    expect(creds['webhook-integration'].clientId).toStartWith('gbrain_cl_');
    const token = await mintToken('webhook-integration');

    const res = await fetch(`http://127.0.0.1:${serverPort}/ingest`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'text/markdown',
        'X-Gbrain-Slug': 'inbox/webhook-note',
      },
      body: '---\ntype: note\ntitle: x\n---\n# from a webhook',
    });
    expect([200, 202]).toContain(res.status);
  });

  test('write ops that cannot be slug-fenced are denied to a bound client', async () => {
    // extract_entities mutates people/* and companies/* timelines; extract_facts
    // appends to any entity's fact fence; forget_fact targets a fact by numeric
    // id across sources; ontology_propose writes claims keyed to any entity.
    // None takes a fenceable slug, so all are denied at dispatch rather than
    // left silently unfenced.
    const token = await mintToken('alice-example');
    const cases: Array<[string, Record<string, unknown>]> = [
      ['extract_entities', { text: 'Bob Victim did a bad thing.', source_slug: 'emp-alice-example/notes/hello' }],
      ['extract_facts', { turn_text: 'Bob Victim admitted it.', entity_hints: ['people/bob-victim'] }],
      ['forget_fact', { id: 1, reason: 'retracted' }],
      ['ontology_propose', { entity: 'emp-bob-example/profile', dimension: 'role', value: 'terminated' }],
    ];
    for (const [tool, args] of cases) {
      const body = await mcpCall(token, tool, args);
      expect(body).toMatch(/not available to slug-bound clients/);
    }
  });

  test('a fenced write op still works over the same transport (allow-list is not a blanket deny)', async () => {
    const token = await mintToken('alice-example');
    const ok = await mcpCall(token, 'put_page', {
      slug: 'emp-alice-example/notes/via-mcp', content: '# via mcp',
    });
    expect(ok).not.toMatch(/not available to slug-bound clients/);
    expect(ok).not.toMatch(/permission_denied/);

    const denied = await mcpCall(token, 'put_page', {
      slug: 'emp-bob-example/notes/nope', content: '# nope',
    });
    expect(denied).toMatch(/bound_slug_prefixes/);
  });
});