Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #4768 (stdio half): `gbrain serve --access read-only` over a real MCP stdio
* session on a hermetic PGLite brain, on every surface tier.
*
* Protects: the read-only ceiling is one operation set for tools/list, the
* capabilities resource and dispatch; guessed mutating tools (put_page,
* delete_page, remember, capture) and request_tools are refused before any
* handler runs (no page is written); read operations keep working; the
* default (no flag) is unchanged; `--http --access read-only` refuses.
* Regression it catches: a catalog-only filter that leaves dispatch resolving
* the global catalog, or a predicate that admits mutating operations.
*/
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { spawnSync } from 'node:child_process';
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { keylessBrainEnv } from './helpers/provider-env.ts';
import { operations } from '../src/core/operations.ts';
import { isReadOnlyOperation, parseAccessFlag, parseSurfaceFlag } from '../src/mcp/surface.ts';
import { CAPABILITIES_URI } from '../src/mcp/capabilities.ts';
const MARKER = 'readonly-marker-4768';
let home: string;
let env: Record<string, string>;
function cli(args: string[]) {
return spawnSync('bun', ['--no-env-file', 'run', 'src/cli.ts', ...args], { cwd: process.cwd(), env, encoding: 'utf8' });
}
async function session(args: string[]): Promise<{ client: Client; close: () => Promise<void> }> {
const transport = new StdioClientTransport({ command: 'bun', args: ['--no-env-file', 'run', 'src/cli.ts', 'serve', ...args], cwd: process.cwd(), env });
const client = new Client({ name: 'gbrain-read-only-test', version: '1.0.0' }, { capabilities: {} });
await client.connect(transport);
return { client, close: async () => { await client.close().catch(() => {}); await transport.close().catch(() => {}); } };
}
const errorOf = (result: unknown): string | undefined => {
const r = result as { isError?: boolean; content?: Array<{ text?: string }> };
if (!r.isError) return undefined;
try { return (JSON.parse(r.content?.[0]?.text ?? '{}') as { error?: string }).error ?? 'error'; } catch { return 'error'; }
};
beforeAll(() => {
home = mkdtempSync(join(tmpdir(), 'gbrain-stdio-read-only-'));
env = keylessBrainEnv(process.env, home, { DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined, GBRAIN_REMOTE_CLIENT_SECRET: undefined });
delete env.GBRAIN_SOURCE;
expect(cli(['init', '--pglite', '--no-embedding', '--non-interactive']).status).toBe(0);
const notes = join(home, 'notes');
mkdirSync(notes, { recursive: true });
writeFileSync(join(notes, 'marker.md'), `---\ntitle: ${MARKER} note\n---\n\n# ${MARKER}\n\nRead-only stdio fixture prose.\n`);
expect(cli(['import', notes, '--no-embed']).status).toBe(0);
}, 120_000);
afterAll(() => { if (home) rmSync(home, { recursive: true, force: true }); });
test('the read-only predicate admits only non-mutating read operations of the live registry', () => {
for (const op of operations) {
if (op.scope !== 'read' || op.mutating === true || op.requiredScopes?.length) expect(isReadOnlyOperation(op)).toBe(false);
}
for (const name of ['put_page', 'delete_page', 'remember', 'capture', 'forget', 'request_tools', 'think', 'join_brain']) {
expect(isReadOnlyOperation(operations.find(op => op.name === name)!)).toBe(false);
}
for (const name of ['search', 'get_page', 'query', 'recall']) expect(isReadOnlyOperation(operations.find(op => op.name === name)!)).toBe(true);
});
test('--access reads both forms; a read-only value is never widened, and a bad value refuses', () => {
expect(parseAccessFlag([])).toBe('full');
for (const args of [['--access', 'read-only'], ['--access=read-only'], ['--access=full', '--access', 'read-only'], ['--access', 'read-only', '--access=full']])
expect(parseAccessFlag(args)).toBe('read-only');
for (const args of [['--access', 'full'], ['--access=full']]) expect(parseAccessFlag(args)).toBe('full');
for (const args of [['--access'], ['--access='], ['--access=readonly'], ['--access', '--surface']])
expect(() => parseAccessFlag(args)).toThrow(/--access takes read-only or full/);
});
test('--surface reads both forms; a repeated flag takes the narrowest value, and a bad value refuses', () => {
expect(parseSurfaceFlag([])).toBeNull();
for (const args of [['--surface', 'verbs'], ['--http', '--surface=verbs'], ['--surface=full', '--surface', 'verbs'], ['--surface', 'starter', '--surface=verbs']])
expect(parseSurfaceFlag(args)).toBe('verbs');
expect(parseSurfaceFlag(['--surface=starter'])).toBe('starter');
// The wider value last never widens: narrowest wins whatever the order.
expect(parseSurfaceFlag(['--surface', 'verbs', '--surface=full'])).toBe('verbs');
for (const args of [['--surface'], ['--surface='], ['--surface', '--http']]) expect(() => parseSurfaceFlag(args)).toThrow(/--surface requires a value/);
expect(() => parseSurfaceFlag(['--surface=all'])).toThrow(/Unknown --surface "all"/);
});
test('a stdio serve with --surface=verbs lists the verbs surface, not the full one', async () => {
const listed = async (args: string[]) => {
const { client, close } = await session(args);
try { return (await client.listTools()).tools.map(tool => tool.name).sort(); } finally { await close(); }
};
const verbs = await listed(['--surface', 'verbs']);
expect(await listed(['--surface=verbs'])).toEqual(verbs);
expect((await listed([])).length).toBeGreaterThan(verbs.length);
}, 90_000);
describe('serve --access read-only', () => {
for (const surface of ['full', 'starter', 'verbs'] as const) {
test(`${surface}: catalog, capabilities and dispatch agree and refuse every mutation`, async () => {
const { client, close } = await session(['--surface', surface, '--access', 'read-only']);
try {
const listed = (await client.listTools()).tools.map(tool => tool.name).sort();
expect(listed.length).toBeGreaterThan(0);
for (const name of listed) expect(isReadOnlyOperation(operations.find(op => op.name === name)!)).toBe(true);
const resource = (await client.readResource({ uri: CAPABILITIES_URI })).contents[0] as { text: string };
const capabilities = JSON.parse(resource.text) as { access: string; available_operations: string[] };
expect(capabilities.access).toBe('read-only');
expect([...capabilities.available_operations].sort()).toEqual(listed);
for (const [name, args] of [
['put_page', { slug: 'notes/injected', content: '# Injected' }],
['delete_page', { slug: 'marker' }],
['remember', { fact: 'Injected fact', entity: 'marker' }],
['capture', { content: 'Injected capture' }],
['request_tools', { tools: ['put_page'] }],
] as const) {
expect(errorOf(await client.callTool({ name, arguments: { ...args } }))).toBe('unknown_tool');
}
const read = surface === 'verbs' ? 'recall' : 'search';
const result = await client.callTool({ name: read, arguments: read === 'recall' ? { query: MARKER } : { query: MARKER, limit: 5 } });
expect(errorOf(result)).toBeUndefined();
} finally { await close(); }
}, 60_000);
}
test('--access=read-only is the same ceiling, not a full-access serve', async () => {
const { client, close } = await session(['--access=read-only']);
try {
const listed = (await client.listTools()).tools.map(tool => tool.name);
expect(listed.length).toBeGreaterThan(0);
for (const name of listed) expect(isReadOnlyOperation(operations.find(op => op.name === name)!)).toBe(true);
expect(errorOf(await client.callTool({ name: 'put_page', arguments: { slug: 'notes/injected', content: '# Injected' } }))).toBe('unknown_tool');
} finally { await close(); }
}, 60_000);
test('nothing was written and the default access is unchanged', async () => {
const { client, close } = await session([]);
try {
const names = new Set((await client.listTools()).tools.map(tool => tool.name));
expect(names.has('put_page')).toBe(true);
const page = await client.callTool({ name: 'get_page', arguments: { slug: 'notes/injected' } });
expect(errorOf(page)).toBe('page_not_found');
expect(errorOf(await client.callTool({ name: 'get_page', arguments: { slug: 'marker' } }))).toBeUndefined();
} finally { await close(); }
}, 60_000);
test('--http --access read-only refuses with the per-token fix', () => {
const refused = cli(['serve', '--http', '--access', 'read-only', '--port', '0']);
expect(refused.status).not.toBe(0);
expect(refused.stderr).toContain('gbrain auth rescope-token <name> --operations');
const refusedEq = cli(['serve', '--http', '--access=read-only', '--port', '0']);
expect(refusedEq.status).not.toBe(0);
expect(refusedEq.stderr).toContain('gbrain auth rescope-token <name> --operations');
});
});