Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* GBRA-156: an unscoped remote read whose readable sources hold no page,
* while other sources hold pages, is refused instead of answering empty.
*
* 1. Protects: a token with no source grant reads the default source plus the
* federated ones. A new source is not federated by default, so a brain
* whose pages all live in such sources answered every search with `[]`,
* which reads like a clean miss. The read is now refused with
* `sources_not_readable` (class host_only), whose fix is the host command
* that makes the pages readable (federate a source, with the user choosing
* which), without naming any source the connection cannot read.
* 2. Fails when: the refusal is missing on an unscoped read whose scope holds
* no page, it leaks a hidden source id or page text, it fires on a real
* miss inside a scope that holds pages, on a brain where no source holds a
* page, or for a connection whose operator granted it sources (a token
* granted sources, or an OAuth client), or for a read that names a source.
* 3. Existing coverage: `source_binding_narrowed` covers a bound stdio
* connection only (mcp-notice-channels).
* 4. No production seam: production serve-http app, real tokens.
*/
import { afterAll, beforeAll, describe, expect, spyOn, test } from 'bun:test';
import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { importFromContent } from '../src/core/import-file.ts';
import { mintLegacyToken } from '../src/core/token-mint.ts';
import { dispatchToolCall } from '../src/mcp/dispatch.ts';
import { callTool, clientCredentialsToken, envelopeOf, legacyToken, ownerCookie, registerOAuthClient, startServeHttp, type LiveServeHttp, type ToolResultWire } from './helpers/live-mcp-servers.ts';
import { testBackends } from './helpers/test-backends.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { noGrantFloorNext } from '../src/commands/sources-add-next.ts';
const HIDDEN = 'source-hidden';
const CANARY = 'harbourcanary';
const QUERY = 'quillmarsh ledger';
const READS = [
['search', { query: QUERY }],
['search', { query: QUERY, match: 'keyword' }],
['query', { query: QUERY, expand: false }],
['list_pages', {}],
['recall', { query: QUERY }],
] as const;
function rows(result: ToolResultWire): unknown {
return JSON.parse(result.content[0]!.text);
}
for (const kind of testBackends()) {
describe(`sources_not_readable refusal (${kind})`, () => {
let engine: BrainEngine;
let close: () => Promise<void>;
let serve: LiveServeHttp;
let noGrant: string;
let granted: string;
let oauth: string;
beforeAll(async () => {
if (kind === 'postgres') ({ engine, close } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));
else { engine = new PGLiteEngine(); await engine.connect({ engine: 'pglite' } as never); await engine.initSchema(); close = () => engine.disconnect(); }
await engine.executeRaw(`INSERT INTO sources (id, name) VALUES ($1, $1), ('source-empty', 'source-empty') ON CONFLICT (id) DO NOTHING`, [HIDDEN]);
serve = await startServeHttp(engine, { surface: 'full' });
noGrant = await legacyToken(engine, ['read']);
granted = (await mintLegacyToken(engine, { name: 'granted-empty', takesHolders: ['world'], scopes: ['read'], sourceGrant: ['source-empty'] })).token;
const client = await registerOAuthClient(serve, await ownerCookie(serve), 'read');
oauth = await clientCredentialsToken(serve, client.clientId, client.clientSecret, 'read');
}, 180_000);
afterAll(async () => {
await serve?.close();
await close?.();
}, 60_000);
test('a brain where no source holds a page answers empty, as before', async () => {
const out = await callTool(serve.base, noGrant, 'search', { query: QUERY });
expect(out.isError).not.toBe(true);
expect(rows(out)).toEqual([]);
}, 60_000);
// Generated by gstack /ship Step 7 coverage audit (GBRA-156).
// Value: protects=pages held only by an archived source never trigger the refusal; the read answers empty as before;
// fails_when=the archived filter is dropped and the refusal tells the user to federate an archived source;
// why_new=no test puts pages in an archived source; seam=none;
// no_claim=archive lifecycle commands (archived flag set by SQL; PGLite or Postgres unit)
test('pages held only by an archived source do not trigger the refusal', async () => {
await engine.executeRaw(`INSERT INTO sources (id, name) VALUES ('source-archived', 'source-archived') ON CONFLICT (id) DO NOTHING`);
await importFromContent(engine, 'notes/archived-ledger', '# Archived\nThe quillmarsh ledger, archived copy.', { sourceId: 'source-archived', noEmbed: true });
await engine.executeRaw(`UPDATE sources SET archived = true WHERE id = 'source-archived'`);
try {
const out = await callTool(serve.base, noGrant, 'search', { query: QUERY });
expect(out.isError).not.toBe(true);
expect(rows(out)).toEqual([]);
} finally {
await engine.executeRaw(`DELETE FROM pages WHERE source_id = 'source-archived'`);
await engine.executeRaw(`DELETE FROM sources WHERE id = 'source-archived'`);
}
}, 60_000);
describe('once pages sit in a source the no-grant floor cannot read', () => {
beforeAll(async () => {
await importFromContent(engine, 'notes/quillmarsh-ledger', `# Ledger\nThe quillmarsh ledger for the harbour team, ${CANARY}.`, { sourceId: HIDDEN, noEmbed: true });
}, 60_000);
for (const [tool, args] of READS) {
test(`${tool} ${JSON.stringify(args)}: a no-grant token whose sources hold no page is refused with the host fix`, async () => {
const out = await callTool(serve.base, noGrant, tool, args);
expect(out.isError).toBe(true);
const env = envelopeOf(out);
expect(env.code).toBe('sources_not_readable');
expect(env.class).toBe('host_only');
expect(env.fix.argv).toEqual(['gbrain', 'sources', 'federate', '<source>']);
expect(env.fix.inputs?.[0]?.name).toBe('source');
const text = JSON.stringify(out.content);
expect(text).not.toContain(HIDDEN);
expect(text).not.toContain(CANARY);
}, 60_000);
}
// Generated by gstack /ship Step 7 coverage audit (GBRA-156).
// Value: protects=an unbound stdio agent connection is refused like a no-grant token, and a GBRAIN_SOURCE-bound one never is;
// fails_when=the explicitReadBinding exemption is dropped (bound reads refused) or the stdio transport skips the check;
// why_new=every refusal test drives serve-http tokens only; seam=none;
// no_claim=binding resolution from GBRAIN_SOURCE (binding passed as dispatch opts; unit only)
test('stdio: an unbound connection is refused, and a connection bound to a source is not', async () => {
const stdio = { remote: true, transport: 'stdio' as const, sourceId: 'default', takesHoldersAllowList: ['world'] };
const unbound = await dispatchToolCall(engine, 'list_pages', {}, stdio);
expect(unbound.isError).toBe(true);
expect(JSON.parse(unbound.content[0]!.text).error).toBe('sources_not_readable');
expect(JSON.stringify(unbound.content)).not.toContain(HIDDEN);
const bound = await dispatchToolCall(engine, 'list_pages', {}, {
...stdio, explicitReadBinding: { sourceId: 'default', via: 'GBRAIN_SOURCE', sourceIds: ['default'], optedOut: [] },
});
expect(bound.isError).not.toBe(true);
expect(JSON.parse(bound.content[0]!.text)).toEqual([]);
}, 60_000);
// Value: protects=recall and query (its facts arm) from a no-grant connection whose default source holds world facts (remember writes no page) are not refused, while a private fact alone still leaves recall refused;
// fails_when=the refusal decides recall or query from pages alone, or counts facts a remote caller cannot read;
// why_new=the refusal tests seed pages only; seam=none;
// no_claim=fact extraction or the remember write path (fact rows inserted by SQL)
test('recall and query read world facts in a readable source and are not refused; a private fact does not count', async () => {
const [priv] = await engine.executeRaw<{ id: number }>(
`INSERT INTO facts (source_id, fact, visibility, source) VALUES ('default', 'The tidewell gauge is private.', 'private', 'test') RETURNING id`);
try {
const privOnly = await callTool(serve.base, noGrant, 'recall', {});
expect(privOnly.isError).toBe(true);
expect(envelopeOf(privOnly).code).toBe('sources_not_readable');
const [world] = await engine.executeRaw<{ id: number }>(
`INSERT INTO facts (source_id, fact, visibility, source) VALUES ('default', 'The tidewell gauge runs fast.', 'world', 'test') RETURNING id`);
try {
const out = await callTool(serve.base, noGrant, 'recall', {});
expect(out.isError).not.toBe(true);
expect(JSON.stringify(out.content)).toContain('tidewell gauge runs fast');
expect(JSON.stringify(out.content)).not.toContain('is private');
const query = await callTool(serve.base, noGrant, 'query', { query: 'zzyzx nothing matches this', expand: false });
expect(query.isError).not.toBe(true);
const search = await callTool(serve.base, noGrant, 'search', { query: QUERY });
expect(envelopeOf(search).code).toBe('sources_not_readable');
} finally {
await engine.executeRaw(`DELETE FROM facts WHERE id = $1`, [world!.id]);
}
} finally {
await engine.executeRaw(`DELETE FROM facts WHERE id = $1`, [priv!.id]);
}
}, 60_000);
// Value: protects=an authenticated context whose hasSourceGrant is undefined (OAuth or an unrestricted resident registration) never widens to federated sources, so it is never told to federate;
// fails_when=the gate refuses on hasSourceGrant undefined, the opposite of the scope resolver's convention;
// why_new=the serve-http OAuth test always carries a bound source; seam=none;
// no_claim=which transports produce hasSourceGrant undefined (auth passed as dispatch opts; unit only)
test('an auth context with hasSourceGrant undefined does not read the no-grant floor, so it is not refused', async () => {
const out = await dispatchToolCall(engine, 'list_pages', {}, {
remote: true, transport: 'http', sourceId: 'default', takesHoldersAllowList: ['world'],
auth: { token: 'x', clientId: 'client-undefined-grant', scopes: ['read'], sourceId: 'default' } as never,
});
expect(out.isError).not.toBe(true);
expect(JSON.parse(out.content[0]!.text)).toEqual([]);
}, 60_000);
test('an OAuth client always carries a grant (at least its bound source), so it is not refused', async () => {
const out = await callTool(serve.base, oauth, 'search', { query: QUERY });
expect(out.isError).not.toBe(true);
expect(rows(out)).toEqual([]);
}, 60_000);
test('a token the operator granted a source is not refused (its scope is deliberate)', async () => {
const out = await callTool(serve.base, granted, 'search', { query: QUERY });
expect(out.isError).not.toBe(true);
expect(rows(out)).toEqual([]);
}, 60_000);
test('naming a source explicitly is not refused', async () => {
for (const scope of [{ source_id: 'default' }, { source_ids: ['default'] }]) {
const out = await callTool(serve.base, noGrant, 'search', { query: QUERY, ...scope });
expect(out.isError).not.toBe(true);
expect(rows(out)).toEqual([]);
}
}, 60_000);
test('once the source is federated the same token reads the page, and a real miss is not refused', async () => {
await engine.executeRaw(`UPDATE sources SET config = COALESCE(config, '{}'::jsonb) || '{"federated": true}'::jsonb WHERE id = $1`, [HIDDEN]);
try {
const hit = await callTool(serve.base, noGrant, 'search', { query: QUERY });
expect(JSON.stringify(rows(hit))).toContain('quillmarsh-ledger');
const miss = await callTool(serve.base, noGrant, 'search', { query: 'zzyzx nothing matches this' });
expect(miss.isError).not.toBe(true);
expect(rows(miss)).toEqual([]);
} finally {
await engine.executeRaw(`UPDATE sources SET config = config - 'federated' WHERE id = $1`, [HIDDEN]);
}
}, 60_000);
// Generated by gstack /ship Step 9 pass 2 (GBRA-156).
// Value: protects=a refusal check that errors never fails the read; it answers as before;
// fails_when=the fail-open catch is narrowed or removed and a transient database error turns an empty read into an error;
// why_new=no test forces the check to fail; seam=engine.executeRaw spy that throws on the check only;
// no_claim=which database errors occur in practice (forced error)
test('a refusal check that fails never fails the read', async () => {
const real = engine.executeRaw.bind(engine);
const raw = spyOn(engine, 'executeRaw').mockImplementation((async (sql: string, params?: unknown[]) => {
if (sql.includes('AS refuse')) throw new Error('forced refusal check failure');
return real(sql, params as never);
}) as never);
try {
const out = await dispatchToolCall(engine, 'list_pages', {}, { remote: true, transport: 'stdio', sourceId: 'default', takesHoldersAllowList: ['world'] });
expect(out.isError).not.toBe(true);
expect(JSON.parse(out.content[0]!.text)).toEqual([]);
} finally {
raw.mockRestore();
}
}, 60_000);
// Value: protects=a soft-deleted floor page does not count as readable, so the read is still refused;
// fails_when=the deleted_at filter is dropped from the refusal check;
// why_new=no test soft-deletes a floor page; seam=none; no_claim=the soft-delete lifecycle (deleted_at set by SQL)
test('a soft-deleted floor page does not count, so the read is still refused', async () => {
await importFromContent(engine, 'notes/floor-gone', '# Gone\nA deleted note in the default source.', { sourceId: 'default', noEmbed: true });
await engine.executeRaw("UPDATE pages SET deleted_at = now() WHERE source_id = 'default' AND slug = 'notes/floor-gone'");
try {
expect(envelopeOf(await callTool(serve.base, noGrant, 'search', { query: QUERY })).code).toBe('sources_not_readable');
} finally {
await engine.executeRaw("DELETE FROM pages WHERE source_id = 'default' AND slug = 'notes/floor-gone'");
}
}, 60_000);
// Value: protects=private pages count on neither side: a floor holding only a private page is still refused, and other sources holding only private pages never prompt a federate fix that could not expose them;
// fails_when=the refusal check counts pages a remote caller cannot read;
// why_new=no test puts a private page on either side; seam=none; no_claim=search.remote_private_pages visible (default enforce only)
test('private pages count on neither side of the refusal', async () => {
await importFromContent(engine, 'notes/floor-private', '---\nvisibility: private\n---\n# Private\nA private note in the default source.', { sourceId: 'default', noEmbed: true });
try {
expect(envelopeOf(await callTool(serve.base, noGrant, 'search', { query: QUERY })).code).toBe('sources_not_readable');
await engine.executeRaw(`UPDATE pages SET frontmatter = COALESCE(frontmatter, '{}'::jsonb) || '{"visibility": "private"}'::jsonb WHERE source_id = $1`, [HIDDEN]);
const out = await callTool(serve.base, noGrant, 'search', { query: QUERY });
expect(out.isError).not.toBe(true);
expect(rows(out)).toEqual([]);
} finally {
await engine.executeRaw(`UPDATE pages SET frontmatter = frontmatter - 'visibility' WHERE source_id = $1`, [HIDDEN]);
await engine.executeRaw("DELETE FROM pages WHERE source_id = 'default' AND slug = 'notes/floor-private'");
}
}, 60_000);
// Value: protects=quarantined pages count on neither side (#7993): a floor holding only a quarantined page is still refused (and sources add still prints the federate step), and other sources holding only quarantined pages never prompt a federate fix that could not make them searchable;
// fails_when=the refusal check or noGrantFloorNext counts pages search never returns;
// why_new=the private-page test covers visibility only; seam=none; no_claim=how pages become quarantined (marker set by SQL)
test('quarantined pages count on neither side of the refusal, nor in the sources add step', async () => {
const quarantine = (where: string, params: unknown[]) => engine.executeRaw(
`UPDATE pages SET frontmatter = COALESCE(frontmatter, '{}'::jsonb) || '{"quarantine": {"reason": "junk_pattern"}}'::jsonb WHERE ${where}`, params);
await importFromContent(engine, 'notes/floor-quarantined', '# Floor\nA quarantined note in the default source.', { sourceId: 'default', noEmbed: true });
await quarantine("source_id = 'default' AND slug = 'notes/floor-quarantined'", []);
try {
for (const [tool, args] of READS.filter(([tool]) => tool !== 'list_pages')) {
expect(envelopeOf(await callTool(serve.base, noGrant, tool, args)).code).toBe('sources_not_readable');
}
expect((await noGrantFloorNext(engine, HIDDEN))?.argv).toEqual(['gbrain', 'sources', 'federate', HIDDEN]);
await engine.executeRaw("DELETE FROM pages WHERE source_id = 'default' AND slug = 'notes/floor-quarantined'");
await quarantine('source_id = $1', [HIDDEN]);
for (const [tool, args] of READS) {
const out = await callTool(serve.base, noGrant, tool, args);
expect({ tool, isError: out.isError === true }).toEqual({ tool, isError: false });
expect(JSON.stringify(out.content)).not.toContain(CANARY);
}
} finally {
await engine.executeRaw(`UPDATE pages SET frontmatter = frontmatter - 'quarantine' WHERE source_id = $1`, [HIDDEN]);
await engine.executeRaw("DELETE FROM pages WHERE source_id = 'default' AND slug = 'notes/floor-quarantined'");
}
}, 60_000);
// Value: protects=only active world facts keep recall and query from the refusal (#7993); fails_when=a forgotten or lapsed world fact, which recall never returns, suppresses the refusal and the read answers empty;
// why_new=the facts test above seeds an active fact only; seam=none; no_claim=the forget write path (expired_at and valid_until set by SQL)
for (const state of ['forgotten', 'lapsed'] as const) {
test(`a ${state} world fact does not keep recall or query from the refusal`, async () => {
const [fact] = await engine.executeRaw<{ id: number }>(
`INSERT INTO facts (source_id, fact, visibility, source, expired_at, valid_until) VALUES ('default', 'The tidewell gauge runs fast.', 'world', 'test', $1::timestamptz, $2::timestamptz) RETURNING id`,
state === 'forgotten' ? [new Date().toISOString(), null] : [null, '2020-01-01T00:00:00Z']);
try {
for (const [tool, args] of [['recall', {}], ['query', { query: 'zzyzx nothing matches this', expand: false }]] as const) {
const out = await callTool(serve.base, noGrant, tool, args);
expect({ tool, code: envelopeOf(out).code }).toEqual({ tool, code: 'sources_not_readable' });
expect(JSON.stringify(out.content)).not.toContain('tidewell');
}
} finally {
await engine.executeRaw('DELETE FROM facts WHERE id = $1', [fact!.id]);
}
}, 60_000);
}
test('a default source that holds a page but matches nothing answers empty, not refused', async () => {
await importFromContent(engine, 'notes/floor-note', '# Floor\nAn unrelated note in the default source.', { sourceId: 'default', noEmbed: true });
try {
const out = await callTool(serve.base, noGrant, 'search', { query: QUERY });
expect(out.isError).not.toBe(true);
expect(rows(out)).toEqual([]);
} finally {
await engine.executeRaw("DELETE FROM pages WHERE source_id = 'default' AND slug = 'notes/floor-note'");
}
}, 60_000);
});
});
}