Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.1 KB
Raw Blame
/**
 * GST-359 C1: the attested actor over the real `gbrain serve --http` (serve-http-mcp.ts), with a client-credentials
 * client granted the attest right and person links made by the real CLI (`gbrain auth rescope --attest-actor`,
 * `gbrain access member link`).
 *
 * 1. Protects: the x-qm-actor boundary on the production HTTP transport, not only dispatch: the header reaches
 *    dispatch on tools/call, initialize accepts and ignores it on a stateless server (no Mcp-Session-Id) and carries
 *    serverInfo.description, and every outcome row of the actor table answers as specified with structuredContent.
 * 2. Fails when: serve-http drops the header, a client without the right reads with it, an argument changes the
 *    person, an unlinked id reads anything, initialize issues a session id, or the CLI grant or link does not persist.
 * 3. Existing coverage: test/access-qm-actor.test.ts pins dispatch, publication, jobs and the legacy bearer transport.
 * 4. No production seam.
 *
 * Run: DATABASE_URL=... GBRAIN_TEST_ALLOW_DATABASE_URL=1 bun test test/e2e/serve-http-qm-actor.test.ts
 */
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { execFileSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { setupDB, teardownDB, hasDatabase, removeMembers } from './helpers.ts';
import type { PostgresEngine } from '../../src/core/postgres-engine.ts';
import { importFromContent } from '../../src/core/import-file.ts';
import { GBrainOAuthProvider } from '../../src/core/oauth-provider.ts';
import { sqlQueryForEngine } from '../../src/core/sql-query.ts';
import { addMember } from '../../src/core/access/members.ts';
import { MCP_SERVER_DESCRIPTION } from '../../src/mcp/instructions.ts';

const skip = !hasDatabase();
const describeE2E = skip ? describe.skip : describe;
if (skip) console.log('Skipping E2E serve-http-qm-actor tests (DATABASE_URL not set)');

const PORT = 19163;
const BASE = `http://localhost:${PORT}`;
const PAGES = {
  alice: { slug: 'notes/qm-e2e-alice', readers: '[alice-example]', canary: 'canaryqmealice' },
  bob: { slug: 'notes/qm-e2e-bob', readers: '[bob-example]', canary: 'canaryqmebob' },
} as const;
const ALICE_ID = 'U0ALICE';
const BOB_ID = 'oidc:3f2a:bob-example';
const MEMBERS = ['alice-example', 'bob-example'];

describeE2E('/mcp attested actor (x-qm-actor) over serve --http', () => {
  let serverProcess: ReturnType<typeof import('child_process').spawn> | null = null;
  let engine: PostgresEngine;
  const tokens: Record<'qm' | 'plain', string> = { qm: '', plain: '' };
  let qmClientId = '';
  let plainClientId = '';
  const cli = (...args: string[]) => execFileSync('bun', ['run', 'src/cli.ts', ...args], { cwd: process.cwd(), env: { ...process.env }, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });

  beforeAll(async () => {
    engine = await setupDB();
    for (const id of MEMBERS) await addMember(engine, id);
    for (const p of Object.values(PAGES)) {
      const out = await importFromContent(engine, p.slug, `---\ntype: note\nreadable_by: ${p.readers}\n---\n# Harbor plan\n\nHarbor plan notes ${p.canary}.`, { noEmbed: true });
      expect(out.status).toBe('imported');
    }
    const provider = new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });
    const qm = await provider.registerClientManual('qm-e2e-' + randomUUID().slice(0, 8), ['client_credentials'], 'read', [], 'default');
    const plain = await provider.registerClientManual('qm-e2e-plain-' + randomUUID().slice(0, 8), ['client_credentials'], 'read', [], 'default');
    qmClientId = qm.clientId;
    plainClientId = plain.clientId;
    expect(cli('auth', 'rescope', '--client', qmClientId, '--attest-actor', 'qm', '--attest-ops', 'get_page,search')).toContain('attests actor: qm for get_page, search');
    expect(cli('access', 'member', 'link', 'alice-example', '--qm', ALICE_ID)).toContain('Linked qm:' + ALICE_ID);
    expect(cli('access', 'member', 'link', 'bob-example', '--qm', BOB_ID)).toContain('-> bob-example');
    expect(JSON.parse(cli('access', 'member', 'links', '--json')).links.length).toBe(2);
    expect(() => cli('access', 'member', 'link', 'alice-example', '--qm', 'L'.repeat(257))).toThrow(/invalid_external_id|access_member_invalid/);
    const { spawn } = await import('child_process');
    serverProcess = spawn('bun', ['run', 'src/cli.ts', 'serve', '--http', '--port', String(PORT), '--public-url', BASE], {
      cwd: process.cwd(), env: { ...process.env }, stdio: ['ignore', 'pipe', 'pipe'],
    });
    let stderr = '';
    serverProcess.stderr?.on('data', (d: Buffer) => { stderr += d.toString(); });
    let up = false;
    for (let i = 0; i < 30 && !up; i++) {
      try { up = (await fetch(`${BASE}/health`)).ok; } catch { /* not up yet */ }
      if (!up) await new Promise(r => setTimeout(r, 500));
    }
    if (!up) throw new Error('Server failed to start within 15s.\nstderr: ' + stderr.slice(-500));
    for (const [key, c] of [['qm', qm], ['plain', plain]] as const) {
      const res = await fetch(`${BASE}/token`, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: new URLSearchParams({ grant_type: 'client_credentials', client_id: c.clientId, client_secret: c.clientSecret! }) });
      expect(res.status).toBe(200);
      tokens[key] = (await res.json() as { access_token: string }).access_token;
    }
  }, 90_000);

  afterAll(async () => {
    if (serverProcess) {
      serverProcess.kill('SIGTERM');
      await new Promise(r => setTimeout(r, 1000));
      if (!serverProcess.killed) serverProcess.kill('SIGKILL');
    }
    await removeMembers(MEMBERS);
    await teardownDB();
  }, 30_000);

  async function rpc(who: 'qm' | 'plain', body: Record<string, unknown>, actor?: string) {
    const res = await fetch(`${BASE}/mcp`, {
      method: 'POST',
      headers: { Authorization: `Bearer ${tokens[who]}`, 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream',
        ...(actor !== undefined ? { 'x-qm-actor': actor } : {}) },
      body: JSON.stringify({ jsonrpc: '2.0', id: 1, ...body }),
    });
    expect(res.status).toBe(200);
    const text = (await res.text()).trim();
    const parsed = JSON.parse(text.startsWith('{') ? text : text.split('\n').filter(l => l.startsWith('data:')).pop()!.slice(5).trim());
    return { res, rpc: parsed as { result: Record<string, any>; error?: unknown } };
  }
  const get = async (who: 'qm' | 'plain', slug: string, actor?: string, args: Record<string, unknown> = {}) => {
    const { rpc: out } = await rpc(who, { method: 'tools/call', params: { name: 'get_page', arguments: { slug, ...args } } }, actor);
    expect(out.error).toBeUndefined();
    return { text: (out.result.content as Array<{ text: string }>).map(c => c.text).join('\n'), structured: out.result.structuredContent, meta: out.result._meta, isError: out.result.isError === true };
  };

  test('initialize accepts the header, issues no Mcp-Session-Id, and carries serverInfo.description', async () => {
    const { res, rpc: out } = await rpc('qm', { method: 'initialize', params: { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 'qm-e2e', version: '1' } } }, ALICE_ID);
    expect(res.headers.get('mcp-session-id')).toBeNull();
    expect(out.result.serverInfo).toMatchObject({ name: 'gbrain', description: MCP_SERVER_DESCRIPTION });
    expect(typeof out.result.instructions).toBe('string');
  }, 30_000);

  test('each call reads as the linked member; without the header the client reads no restricted page', async () => {
    expect((await get('qm', PAGES.alice.slug, ALICE_ID)).text).toContain(PAGES.alice.canary);
    expect((await get('qm', PAGES.bob.slug, ALICE_ID)).text).not.toContain(PAGES.bob.canary);
    expect((await get('qm', PAGES.bob.slug, BOB_ID)).text).toContain(PAGES.bob.canary);
    expect((await get('qm', PAGES.alice.slug)).text).not.toContain(PAGES.alice.canary);
    const named = await get('qm', PAGES.alice.slug, ALICE_ID, { acting_user: ALICE_ID });
    expect(named.text).toContain(PAGES.alice.canary);
    expect(named.meta?.access).toMatchObject({ member: 'alice-example', audience: ['member:alice-example'], actor: { system: 'qm' } });
  }, 60_000);

  test('every refusal row answers with its code and reason in the text block and structuredContent', async () => {
    const cases: Array<[Promise<Awaited<ReturnType<typeof get>>>, string, string | undefined]> = [
      [get('plain', PAGES.alice.slug, ALICE_ID), 'actor_not_attested', 'no_attest_right'],
      [rpc('qm', { method: 'tools/call', params: { name: 'list_pages', arguments: {} } }, ALICE_ID).then(({ rpc: o }) => ({ text: o.result.content[0].text, structured: o.result.structuredContent, meta: undefined, isError: true })), 'actor_not_attested', 'op_not_attested'],
      [get('qm', PAGES.alice.slug, ALICE_ID, { acting_user: BOB_ID }), 'actor_not_attested', 'argument_mismatch'],
      [get('qm', PAGES.alice.slug, undefined, { acting_user: ALICE_ID }), 'actor_not_attested', 'argument_without_attestation'],
      [get('qm', PAGES.alice.slug, 'L'.repeat(257)), 'actor_not_attested', 'invalid_actor_id'],
      [get('qm', PAGES.alice.slug, 'u0alice'), 'actor_unlinked', undefined],
    ];
    for (const [pending, code, reason] of cases) {
      const out = await pending;
      const json = JSON.parse(out.text);
      expect({ code: json.code, reason: json.reason }).toEqual({ code, reason });
      expect(out.structured.error).toMatchObject({ code, ...(reason ? { reason } : {}) });
      expect(out.text).not.toContain(PAGES.alice.canary);
    }
    const fix = (await get('plain', PAGES.alice.slug, ALICE_ID)).structured.error.fix;
    expect(fix.argv).toEqual(['gbrain', 'auth', 'rescope', '--client', plainClientId, '--attest-actor', 'qm']);
  }, 60_000);

  test('under the header tools/list lists only the attested operations and resources/read refuses', async () => {
    const list = async (actor?: string) => ((await rpc('qm', { method: 'tools/list', params: {} }, actor)).rpc.result.tools as Array<{ name: string }>).map(t => t.name).sort();
    expect(await list(ALICE_ID)).toEqual(['get_page', 'search']);
    const plainList = await list();
    expect(plainList).toContain('get_page');
    expect(plainList.length).toBeGreaterThan(2);
    const read = async (actor?: string) => (await rpc('qm', { method: 'resources/read', params: { uri: 'gbrain://capabilities' } }, actor)).rpc as { result?: { contents: unknown[] }; error?: { message: string; data?: { code?: string } } };
    const refused = await read(ALICE_ID);
    expect(refused.result).toBeUndefined();
    expect(refused.error?.data?.code).toBe('actor_not_attested');
    expect((await read()).result?.contents.length).toBe(1);
  }, 60_000);

  test('unlinking with the CLI refuses the next call', async () => {
    expect(cli('access', 'member', 'unlink', '--qm', BOB_ID, '--dry-run')).toContain('Would unlink');
    expect((await get('qm', PAGES.bob.slug, BOB_ID)).text).toContain(PAGES.bob.canary);
    cli('access', 'member', 'unlink', '--qm', BOB_ID);
    const out = await get('qm', PAGES.bob.slug, BOB_ID);
    expect(out.structured.error.code).toBe('actor_unlinked');
    expect(out.text).not.toContain(PAGES.bob.canary);
    expect(qmClientId).not.toBe('');
  }, 60_000);
});