Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
13.3 KB
Raw Blame
/**
 * #8664: a hosted caller can share one credential across several AIs, so the brain recorded which principal wrote a
 * page but not which AI. An HTTP MCP request may now carry the X-Gbrain-Agent-Label header; the write records it on
 * its request's authority and attribution reads show it as agent_label. No column, no migration, no new auth path.
 *
 * Protects: both HTTP transports (the OAuth serve --http mount and the legacy bearer transport) read the header and
 * admission records it, on a managed-worktree brain and on a repo-less brain; an unlabelled write is unchanged; a
 * label is unverified text that never changes what the request may do (the stored authority is otherwise identical,
 * and a read-only token is still refused); a label that is not 1-120 printable ASCII characters is dropped, never
 * stored or refused; an allowlisted browser origin's CORS preflight on either transport allows the header.
 * Fails when: the header is dropped before admission, invented at read time, read by authorization, or a value that is
 * unsafe to render (controls, bidi or zero-width characters, non-ASCII bytes) reaches the record.
 * Seams: the mounted SDK transport and the legacy Bun transport over real sockets with real bearer tokens, and the
 * attribution op a read already has. PGLite only: this is a header-to-row path, not a database behaviour.
 */
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import type { Server } from 'node:http';
import type { AddressInfo } from 'node:net';
import express from 'express';
import { mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { GBrainOAuthProvider } from '../src/core/oauth-provider.ts';
import { sqlQueryForEngine } from '../src/core/sql-query.ts';
import { hashToken } from '../src/core/utils.ts';
import { operationsByName, type OperationContext } from '../src/core/operations.ts';
import { mountMcp } from '../src/commands/serve-http-mcp.ts';
import type { ServeHttpContext } from '../src/commands/serve-http.ts';
import { startHttpTransport } from '../src/mcp/http-transport.ts';
import { RateLimiter } from '../src/mcp/rate-limit.ts';
import { claimWorktree } from '../src/core/persistence/ownership.ts';
import { registerLocalWriter } from '../src/core/persistence/identity.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { AGENT_LABEL_HEADER, parseAgentLabel } from '../src/core/persistence/attribution.ts';
import { buildServeHttpApp } from '../src/commands/serve-http.ts';
import { withEnv } from './helpers/with-env.ts';

const CONFIG = { engine: 'pglite', embedding_disabled: true } as const;
const content = (title: string) => '---\ntype: note\ntitle: ' + title + '\n---\n\n# ' + title + '\n\nA synthetic page.\n';

async function addToken(engine: BrainEngine, name: string, token: string, scopes: string): Promise<void> {
  await engine.executeRaw('INSERT INTO access_tokens(name,token_hash,scopes) VALUES($1,$2,$3::text[])', [name, hashToken(token), scopes]);
}
/** One real tools/call put_page; returns the raw response text. */
async function putPage(engine: BrainEngine, url: string, token: string, slug: string, title: string, label?: string): Promise<string> {
  const snapshot = await engine.readPageSnapshot(slug, { sourceId: 'default' });
  const response = await fetch(url, { method: 'POST',
    headers: { authorization: 'Bearer ' + token, 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream', ...(label === undefined ? {} : { [AGENT_LABEL_HEADER]: label }) },
    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'put_page',
      arguments: { slug, content: content(title), ...(snapshot ? { expected_revision: snapshot.revision } : {}) } } }) });
  expect(response.status).toBe(200);
  return await response.text();
}
async function put(engine: BrainEngine, url: string, token: string, slug: string, title: string, label?: string): Promise<void> {
  expect((await putPage(engine, url, token, slug, title, label)).includes('"isError":true')).toBe(false);
}
const attributed = async (engine: BrainEngine, slug: string) => await operationsByName.get_write_attribution.handler({
  engine, sourceId: 'default', remote: false, config: CONFIG, logger: { info() {}, warn() {}, error() {} },
} as unknown as OperationContext, { slug }) as Record<string, any>;

test('a label is 1-120 printable ASCII characters after trimming; anything else is dropped', () => {
  expect(parseAgentLabel('  Claude Code  ')).toBe('Claude Code');
  expect(parseAgentLabel('codex/gpt-6.1-sol')).toBe('codex/gpt-6.1-sol');
  expect(parseAgentLabel('x'.repeat(120))).toBe('x'.repeat(120));
  for (const bad of [undefined, null, '', '  ', 'x'.repeat(121), 'bad' + String.fromCharCode(7) + 'label', 'line\nbreak', 'tab\there',
    'caf' + String.fromCharCode(0xe9), 'Codex' + String.fromCharCode(0x202e) + 'edoC', 'zero' + String.fromCharCode(0x200b) + 'width',
    'sep' + String.fromCharCode(0x2028) + 'arator', 'c1' + String.fromCharCode(0x85) + 'control']) {
    expect(parseAgentLabel(bad)).toBeUndefined();
  }
});

describe('OAuth serve --http mount, managed worktree brain', () => {
  const SLUG = 'notes/labelled-write';
  const TOKEN = 'synthetic-agent-label-' + process.pid;
  const READER = 'synthetic-agent-label-reader-' + process.pid;
  let engine: BrainEngine;
  let root: string;
  let http: Server;
  let url: string;

  beforeAll(async () => {
    const db = new PGLiteEngine();
    await db.connect({});
    await db.initSchema();
    engine = db;
    root = mkdtempSync(join(tmpdir(), 'gbrain-agent-label-'));
    await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
    await engine.executeRaw('UPDATE sources SET local_path=$1 WHERE id=\'default\'', [root]);
    await claimWorktree(engine, 'default', root);
    await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
    await registerLocalWriter(engine, 'cli');
    await addToken(engine, 'Synthetic writer token', TOKEN, '{read,write}');
    await addToken(engine, 'Synthetic reader token', READER, '{read}');
    const provider = new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });
    const app = express();
    mountMcp(app, { engine, config: CONFIG, resourceVerifier: provider,
      resourceMetadataUrl: 'http://127.0.0.1/resource', mcpResourceUrl: new URL('http://127.0.0.1/mcp'),
      mcpOperationsBase: Object.values(operationsByName).filter(op => !op.localOnly && !op.cliOnly), broadcastEvent() {} } as unknown as ServeHttpContext);
    http = await new Promise(resolve => { const listener = app.listen(0, '127.0.0.1', () => resolve(listener)); });
    url = 'http://127.0.0.1:' + (http.address() as AddressInfo).port + '/mcp';
  }, 120_000);

  afterAll(async () => {
    await disposePersistenceConsumer(engine);
    if (http) await new Promise<void>(resolve => http.close(() => resolve()));
    await engine.disconnect();
    rmSync(root, { recursive: true, force: true });
  });

  test('a labelled write records the label the caller declared, and attribution reads show it', async () => {
    await put(engine, url, TOKEN, SLUG, 'First by Claude', 'Claude Code');
    expect((await attributed(engine, SLUG)).live_revision.written_by.agent_label).toBe('Claude Code');

    await put(engine, url, TOKEN, SLUG, 'Then by Codex', '  Codex  ');
    const second = await attributed(engine, SLUG);
    expect(second.created.agent_label).toBe('Claude Code');
    expect(second.last.agent_label).toBe('Codex');
    expect(second.live_revision.written_by.agent_label).toBe('Codex');

    await put(engine, url, TOKEN, SLUG, 'Unlabelled edit');
    const third = await attributed(engine, SLUG);
    expect(third.live_revision.written_by.agent_label).toBeUndefined();
    expect('agent_label' in third.live_revision.written_by).toBe(false);

    await put(engine, url, TOKEN, SLUG, 'Too long', 'x'.repeat(121));
    expect((await attributed(engine, SLUG)).live_revision.written_by.agent_label).toBeUndefined();
  }, 240_000);

  test('a label is never authority: the stored authority is otherwise identical and a read-only token is still refused', async () => {
    const slug = 'notes/authority-check';
    await put(engine, url, TOKEN, slug, 'Authority by Claude', 'Claude Code');
    await put(engine, url, TOKEN, slug, 'Authority by Codex', 'Codex');
    await put(engine, url, TOKEN, slug, 'Authority unlabelled');
    const rows = await engine.executeRaw<{ label: string | null; rest: Record<string, unknown> }>(
      "SELECT authority->>'agentLabel' AS label, authority - 'agentLabel' AS rest FROM persistence_requests WHERE slug=$1 ORDER BY created_at", [slug]);
    expect(rows.map(r => r.label)).toEqual(['Claude Code', 'Codex', null]);
    const rest = rows.map(r => typeof r.rest === 'string' ? JSON.parse(r.rest) : r.rest);
    for (const other of rest.slice(1)) expect(other).toEqual(rest[0]);

    const refused = await putPage(engine, url, READER, 'notes/reader-attempt', 'Reader attempt', 'admin');
    expect(refused).toContain('"isError":true');
    expect(await engine.readPageSnapshot('notes/reader-attempt', { sourceId: 'default' })).toBeNull();
  }, 240_000);
});

describe('legacy bearer transport, repo-less brain', () => {
  const SLUG = 'notes/repoless-labelled';
  const TOKEN = 'synthetic-agent-label-legacy-' + process.pid;
  let engine: BrainEngine;
  let server: { port: number; stop: (force?: boolean) => unknown };
  let url: string;

  beforeAll(async () => {
    const db = new PGLiteEngine();
    await db.connect({});
    await db.initSchema();
    engine = db;
    const [source] = await engine.executeRaw<{ local_path: string | null }>("SELECT local_path FROM sources WHERE id='default'");
    expect(source?.local_path ?? null).toBeNull();
    await addToken(engine, 'Synthetic legacy token', TOKEN, '{read,write}');
    server = await startHttpTransport({ port: 0, engine, surface: 'full', limiters: {
      ip: new RateLimiter({ limit: 10_000, windowMs: 60_000, lruCap: 100 }),
      token: new RateLimiter({ limit: 10_000, windowMs: 60_000, lruCap: 100 }),
    } }) as unknown as { port: number; stop: (force?: boolean) => unknown };
    url = 'http://127.0.0.1:' + server.port + '/mcp';
  }, 120_000);

  afterAll(async () => {
    await server?.stop(true);
    await disposePersistenceConsumer(engine);
    await engine.disconnect();
  });

  test('the legacy transport records the label on a repo-less brain and drops a non-ASCII one', async () => {
    await put(engine, url, TOKEN, SLUG, 'Repo-less by Claude', 'Claude Code');
    expect((await attributed(engine, SLUG)).live_revision.written_by.agent_label).toBe('Claude Code');

    await put(engine, url, TOKEN, SLUG, 'Repo-less latin1 label', 'caf' + String.fromCharCode(0xe9));
    const after = await attributed(engine, SLUG);
    expect(after.live_revision.written_by.agent_label).toBeUndefined();
    expect(after.created.agent_label).toBe('Claude Code');
  }, 240_000);
});

describe('a browser caller on an allowlisted origin may send the header', () => {
  const ORIGIN = 'https://allowed.example';
  let engine: BrainEngine;
  let http: Server;
  let legacy: { port: number; stop: (force?: boolean) => unknown };

  beforeAll(async () => {
    const db = new PGLiteEngine();
    await db.connect({});
    await db.initSchema();
    engine = db;
    await withEnv({ GBRAIN_HTTP_CORS_ORIGIN: ORIGIN }, async () => {
      const app = express();
      http = await new Promise(resolve => { const listener = app.listen(0, '127.0.0.1', () => resolve(listener)); });
      const port = (http.address() as AddressInfo).port;
      await buildServeHttpApp(app, engine, { port, tokenTtl: 3600, enableDcr: false, publicUrl: 'http://127.0.0.1:' + port });
      legacy = await startHttpTransport({ port: 0, engine, surface: 'full', limiters: {
        ip: new RateLimiter({ limit: 10_000, windowMs: 60_000, lruCap: 100 }),
        token: new RateLimiter({ limit: 10_000, windowMs: 60_000, lruCap: 100 }),
      } }) as unknown as { port: number; stop: (force?: boolean) => unknown };
    });
  }, 120_000);

  afterAll(async () => {
    await legacy?.stop(true);
    if (http) await new Promise<void>(resolve => { http.closeAllConnections?.(); http.close(() => resolve()); });
    await engine.disconnect();
  });

  const preflight = async (port: number) => await fetch('http://127.0.0.1:' + port + '/mcp', { method: 'OPTIONS', headers: {
    Origin: ORIGIN, 'Access-Control-Request-Method': 'POST', 'Access-Control-Request-Headers': 'authorization, content-type, x-gbrain-agent-label' } });
  const allowsLabel = (response: Response) => (response.headers.get('access-control-allow-headers') ?? '').toLowerCase().split(/\s*,\s*/).includes(AGENT_LABEL_HEADER.toLowerCase());

  test('the OAuth serve --http mount allows the header in its preflight', async () => {
    const response = await preflight((http.address() as AddressInfo).port);
    expect(response.headers.get('access-control-allow-origin')).toBe(ORIGIN);
    expect(allowsLabel(response)).toBe(true);
  });

  test('the legacy bearer transport allows the header in its preflight', async () => {
    const response = await preflight(legacy.port);
    expect(response.headers.get('access-control-allow-origin')).toBe(ORIGIN);
    expect(allowsLabel(response)).toBe(true);
  });
});