Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* GST-2059: the brain owner reads the whole personal brain over remote MCP.
*
* 1. Protects: a credential bound to the member config access.owner_member names (`gbrain access owner set`),
* and every delegate credential bound to the same member, reads visibility: private pages, privacy-alias pages
* (access: private), derived pages that default to private and private facts through get_page, search, query and
* recall. Every other caller keeps exactly the read policy it had: another member, an unbound token, the owner's
* credential speaking for a channel audience, and the owner after `gbrain access owner clear`. Member access
* (readable_by) stays mandatory for the owner too.
* 2. Fails when: the owner's agent gets not_found for its own private pages, or any non-owner caller sees one.
* 3. Real seams: tokens minted by the token service and verified by the serve --http verifier, dispatched through MCP
* dispatch as serve-http-mcp does (remote: true), on a repo-less brain (no git checkout); embeddings stubbed.
*/
import { afterAll, beforeAll, describe, expect, 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 { configureGateway, resetGateway, __setEmbedTransportForTests } from '../src/core/ai/gateway.ts';
import { GBrainOAuthProvider } from '../src/core/oauth-provider.ts';
import { sqlQueryForEngine } from '../src/core/sql-query.ts';
import { mintLegacyToken } from '../src/core/token-mint.ts';
import { noGrantFederatedScope } from '../src/core/source-resolver.ts';
import { dispatchToolCall } from '../src/mcp/dispatch.ts';
import { __resetPrivateVisibilityCacheForTests, currentCallerAccess, withCallerAccess } from '../src/core/search/private-visibility.ts';
import { clearOwner, ownerView, setOwner } from '../src/core/access/owner.ts';
import { bindCredential } from '../src/core/access/members.ts';
import { accessCheck } from '../src/commands/access.ts';
import { openAsPreview } from '../src/cli/as-preview.ts';
import type { AuthInfo } from '../src/core/ops/contract.ts';
import { getBrainHotMemoryMeta, __resetHotMemoryCacheForTests } from '../src/core/facts/meta-hook.ts';
import { testBackends } from './helpers/test-backends.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { readsUnscopedOnPurpose } from './helpers/reads-unscoped.ts';
const DIMS = 1536;
function vectorFor(text: string): number[] {
const v = new Array<number>(DIMS).fill(0);
for (const w of text.toLowerCase().match(/[a-z]+/g) ?? []) {
let h = 0;
for (const ch of w) h = (h * 31 + ch.charCodeAt(0)) >>> 0;
v[h % DIMS] += 1;
}
const n = Math.hypot(...v) || 1;
return v.map(x => x / n);
}
const SRC = 'own-src';
const OWNER = 'owner-example';
/** Pages the owner reads and no other remote caller does. */
const PRIVATE = {
flagged: { slug: 'notes/flagged-plan', canary: 'canaryownflag', fm: ['visibility: private'] },
aliased: { slug: 'notes/aliased-plan', canary: 'canaryownalias', fm: ['access: private'] },
derived: { slug: 'atoms/derived-plan', canary: 'canaryownatom', fm: ['type: atom', 'source_slug: notes/open-plan'] },
} as const;
type PrivateKey = keyof typeof PRIVATE;
const OPEN = { slug: 'notes/open-plan', canary: 'canaryownopen' };
/** Another person's page: member access keeps it from the owner too. */
const BOBS = { slug: 'notes/bob-plan', canary: 'canaryownbob' };
const PRIVATE_FACT = 'canaryownfact';
/** GST-2089: a private dated fact about a person, which think's trajectory reads. */
const PERSON = 'people/carol-example';
const PRIVATE_TRAJECTORY = 'canaryowntraj';
/** Private facts the owner must not read: one taken from another person's readable_by page, one in a source its grant does not read. */
const BOBS_FACT = 'canaryownbobfact';
const UNGRANTED_FACT = 'canaryownungranted';
const pageText = (title: string, canary: string, fm: readonly string[]) =>
['---', ...(fm.some(l => l.startsWith('type:')) ? [] : ['type: note']), `title: ${title}`, ...fm, '---', `# ${title}`, '', `Harbor ledger planning notes ${canary} for the roadmap.`].join('\n');
/** The four read paths the owner must have, each with arguments the page answers. */
function reads(slug: string): Array<[string, string, Record<string, unknown>]> {
return [
['get_page', 'get_page', { slug }],
['search', 'search', { query: 'harbor ledger planning notes', fields: 'full', limit: 20 }],
['search keyword', 'search', { query: 'planning notes', match: 'keyword', fields: 'full', limit: 20 }],
['query', 'query', { query: 'harbor ledger planning notes', expand: false, fields: 'full', limit: 20 }],
['recall', 'recall', { query: 'harbor ledger planning notes' }],
];
}
for (const kind of testBackends()) {
describe(`owner reads (${kind}, repo-less)`, () => {
let engine: BrainEngine;
let close: () => Promise<void>;
const tokens: Record<string, string> = {};
const provider = () => new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });
async function call(who: string, op: string, params: Record<string, unknown>, header?: string, extra: { metaHook?: typeof getBrainHotMemoryMeta } = {}): Promise<{ isError: boolean; text: string; meta: Record<string, unknown> | undefined }> {
const auth = await provider().verifyAccessToken(tokens[who]!) as unknown as AuthInfo;
const sourceId = auth.sourceId ?? 'default';
const localFederated = await noGrantFederatedScope(engine, auth.hasSourceGrant, sourceId);
const out = await dispatchToolCall(engine, op, { ...params }, {
remote: true, transport: 'http', auth, sourceId, takesHoldersAllowList: auth.takesHoldersAllowList ?? ['world'],
...(localFederated ? { localFederatedSourceIds: localFederated } : {}), ...(header ? { onBehalfOf: { header } } : {}), ...extra,
});
return { isError: out.isError === true, text: out.content.map(c => c.text).join('\n'), meta: out._meta as Record<string, unknown> | undefined };
}
/** Which private pages `who` sees, per read path (get_page echoes the slug in its not_found, so content decides). */
async function privateSeenBy(who: string, header?: string): Promise<Record<string, PrivateKey[]>> {
const out: Record<string, PrivateKey[]> = {};
for (const key of Object.keys(PRIVATE) as PrivateKey[]) {
for (const [label, op, params] of reads(PRIVATE[key].slug)) {
const { text } = await call(who, op, params, header);
if (text.includes(PRIVATE[key].canary)) (out[label] ??= []).push(key);
}
}
return out;
}
const ALL: Record<string, PrivateKey[]> = Object.fromEntries(reads('x').map(([label]) => [label, label === 'get_page' ? ['flagged', 'aliased', 'derived'] : ['flagged', 'aliased', 'derived']]));
beforeAll(async () => {
configureGateway({ embedding_model: 'openai:text-embedding-3-small', embedding_dimensions: DIMS, env: { OPENAI_API_KEY: 'test' } });
__setEmbedTransportForTests((async ({ values }: { values: string[] }) => ({ embeddings: values.map(vectorFor) })) as never);
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(); }
__resetPrivateVisibilityCacheForTests();
await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1) ON CONFLICT (id) DO NOTHING', [SRC]);
await importFromContent(engine, OPEN.slug, pageText('Open plan', OPEN.canary, []), { sourceId: SRC });
for (const key of Object.keys(PRIVATE) as PrivateKey[]) {
await importFromContent(engine, PRIVATE[key].slug, pageText(`${key} plan`, PRIVATE[key].canary, PRIVATE[key].fm), { sourceId: SRC });
}
await importFromContent(engine, BOBS.slug, pageText('Bob plan', BOBS.canary, ['readable_by: [bob-example]']), { sourceId: SRC });
const fact = await dispatchToolCall(engine, 'remember', { fact: `Harbor ledger planning notes ${PRIVATE_FACT}`, provenance: 'fixture', entity: OPEN.slug, visibility: 'private' }, { remote: false, sourceId: SRC });
if (fact.isError) throw new Error(`fixture remember: ${fact.content.map(c => c.text).join(' ')}`);
// think resolves trajectory entities in its scalar source, which is default for a caller with a source grant.
for (const sourceId of [SRC, 'default']) await importFromContent(engine, PERSON, ['---', 'type: person', 'title: Carol Example', '---', '# Carol Example', '', 'Carol is a founder.'].join('\n'), { sourceId });
await engine.executeRaw(`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, valid_from, source, event_type)
VALUES ($1, $2, $3, 'event', 'private', '2026-05-01T00:00:00Z', 'fixture', 'job_change')`, [SRC, PERSON, `Carol switched jobs ${PRIVATE_TRAJECTORY}`]);
for (const [sourceId, canary, provenance] of [[SRC, BOBS_FACT, BOBS.slug], ['default', UNGRANTED_FACT, null]] as const) {
await engine.executeRaw(`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, valid_from, source, event_type, source_markdown_slug)
VALUES ($1, $2, $3, 'event', 'private', '2026-06-01T00:00:00Z', 'fixture', 'job_change', $4)`, [sourceId, PERSON, `Harbor ledger planning notes ${canary}`, provenance]);
}
for (const id of [OWNER, 'bob-example']) await engine.executeRaw('INSERT INTO access_members (id) VALUES ($1)', [id]);
const mint = async (name: string, member?: string, mayActFor?: string[]) => {
const minted = await mintLegacyToken(engine, { name, scopes: ['read'], takesHolders: ['world'], sourceGrant: [SRC] });
tokens[name] = minted.token;
if (member) await bindCredential(engine, { kind: 'token', id: minted.id }, { member, ...(mayActFor ? { mayActFor } : {}) });
else await readsUnscopedOnPurpose(engine, minted.id);
};
await mint('owner', OWNER, [`member:${OWNER}`, 'member:bob-example']);
await mint('delegate', OWNER);
await mint('bob', 'bob-example');
await mint('unbound');
await setOwner(engine, OWNER);
}, 240_000);
afterAll(async () => {
__setEmbedTransportForTests(null);
resetGateway();
await close?.();
}, 60_000);
test('fixture control: a trusted local caller reads every private page and the private fact', async () => {
for (const key of Object.keys(PRIVATE) as PrivateKey[]) {
const out = await dispatchToolCall(engine, 'get_page', { slug: PRIVATE[key].slug }, { remote: false, sourceId: SRC });
expect({ key, seen: out.content.map(c => c.text).join('\n').includes(PRIVATE[key].canary) }).toEqual({ key, seen: true });
}
const recall = await dispatchToolCall(engine, 'recall', { query: 'harbor ledger planning notes' }, { remote: false, sourceId: SRC });
expect(recall.content.map(c => c.text).join('\n')).toContain(PRIVATE_FACT);
});
test('the owner and a delegate bound to the owner read every private page through get_page, search, query and recall', async () => {
expect(await privateSeenBy('owner')).toEqual(ALL);
expect(await privateSeenBy('delegate')).toEqual(ALL);
}, 240_000);
test('the owner recalls private facts; no other caller does', async () => {
for (const who of ['owner', 'delegate']) expect({ who, seen: (await call(who, 'recall', { query: 'harbor ledger planning notes' })).text.includes(PRIVATE_FACT) }).toEqual({ who, seen: true });
for (const who of ['bob', 'unbound']) expect({ who, seen: (await call(who, 'recall', { query: 'harbor ledger planning notes' })).text.includes(PRIVATE_FACT) }).toEqual({ who, seen: false });
}, 120_000);
/** GST-2089: which fact surfaces show `who` a private fact: the query facts arm, ranked recall, hot memory, delta, context_pack and think's trajectory. */
async function privateFactsSeenBy(who: string, header?: string, canary = PRIVATE_FACT): Promise<string[]> {
const seen: string[] = [];
const surfaces: Array<[string, () => Promise<string>, string]> = [
['query', async () => (await call(who, 'query', { query: 'harbor ledger planning notes', expand: false, limit: 20 }, header)).text, canary],
['recall question', async () => (await call(who, 'recall', { question: `Harbor ledger planning notes ${canary}` }, header)).text, canary],
['recall entity question', async () => (await call(who, 'recall', { entity: OPEN.slug, question: `Harbor ledger planning notes ${canary}` }, header)).text, canary],
['hot memory', async () => JSON.stringify((await call(who, 'get_page', { slug: OPEN.slug }, header, { metaHook: getBrainHotMemoryMeta })).meta?.brain_hot_memory ?? null), canary],
['delta', async () => (await call(who, 'delta', { since: '2000-01-01T00:00:00Z' }, header)).text, canary],
['context_pack', async () => (await call(who, 'context_pack', { entities: OPEN.slug }, header)).text, canary],
['think trajectory', async () => (await call(who, 'think', { question: 'When did Carol last switch jobs?' }, header)).text.match(/TRAJECTORY_INJECTED_\d+_POINTS/)?.[0] ?? '', 'TRAJECTORY_INJECTED'],
];
for (const [label, read, shown] of surfaces) if ((await read()).includes(shown)) seen.push(label);
return seen;
}
const FACT_SURFACES = ['query', 'recall question', 'recall entity question', 'hot memory', 'delta', 'context_pack', 'think trajectory'];
test('fixture control: a trusted local caller gets the private facts on every fact surface', async () => {
const local = (op: string, params: Record<string, unknown>) => dispatchToolCall(engine, op, params, { remote: false, sourceId: SRC }).then(o => o.content.map(c => c.text).join('\n'));
expect(await local('recall', { question: `Harbor ledger planning notes ${PRIVATE_FACT}` })).toContain(PRIVATE_FACT);
expect(await local('think', { question: 'When did Carol last switch jobs?' })).toMatch(/TRAJECTORY_INJECTED_\d+_POINTS/);
expect(await local('recall', { question: `Harbor ledger planning notes ${BOBS_FACT}` })).toContain(BOBS_FACT);
expect((await dispatchToolCall(engine, 'recall', { question: `Harbor ledger planning notes ${UNGRANTED_FACT}` }, { remote: false, sourceId: 'default' })).content.map(c => c.text).join('\n')).toContain(UNGRANTED_FACT);
}, 120_000);
test('GST-2089: the owner and its delegate get private facts on every fact surface; another member and an unbound token get world-only facts', async () => {
__resetHotMemoryCacheForTests();
for (const who of ['owner', 'delegate']) expect({ who, seen: await privateFactsSeenBy(who) }).toEqual({ who, seen: FACT_SURFACES });
for (const who of ['bob', 'unbound']) expect({ who, seen: await privateFactsSeenBy(who) }).toEqual({ who, seen: [] });
}, 240_000);
test('GST-2089: the owner reads no private fact taken from another person\'s readable_by page or kept in a source its grant does not read', async () => {
__resetHotMemoryCacheForTests();
for (const canary of [BOBS_FACT, UNGRANTED_FACT]) expect({ canary, seen: (await privateFactsSeenBy('owner', undefined, canary)).filter(s => s !== 'think trajectory') }).toEqual({ canary, seen: [] });
expect((await call('owner', 'think', { question: 'When did Carol last switch jobs?' })).text).toContain('TRAJECTORY_INJECTED_1_POINTS');
}, 240_000);
test('GST-2089: the owner speaking for itself alone keeps private facts; for a channel audience it gets world-only facts', async () => {
__resetHotMemoryCacheForTests();
expect(await privateFactsSeenBy('owner', `member:${OWNER}`)).toEqual(FACT_SURFACES);
expect(await privateFactsSeenBy('owner', `member:${OWNER},member:bob-example`)).toEqual([]);
}, 240_000);
test('GST-2089: hot memory keys on the caller: after the owner warms the entry, the next caller with the same session reads world-only facts', async () => {
const hot = async (who: string, header?: string) => JSON.stringify((await call(who, 'get_page', { slug: OPEN.slug }, header, { metaHook: getBrainHotMemoryMeta })).meta?.brain_hot_memory ?? null);
for (const next of [['bob'], ['unbound'], ['owner', `member:${OWNER},member:bob-example`]] as const) {
__resetHotMemoryCacheForTests();
expect(await hot('owner')).toContain(PRIVATE_FACT);
expect({ next, seen: (await hot(next[0], next[1])).includes(PRIVATE_FACT) }).toEqual({ next, seen: false });
}
// With privacy relaxed by the operator, the same credential after `gbrain access owner clear` shares the owner's
// page tier and identity; the fact tier still keeps it off the owner's cached private facts.
await engine.setConfig('search.remote_private_pages', 'visible');
__resetPrivateVisibilityCacheForTests();
__resetHotMemoryCacheForTests();
try {
expect(await hot('owner')).toContain(PRIVATE_FACT);
await clearOwner(engine);
expect(await hot('owner')).not.toContain(PRIVATE_FACT);
} finally {
await setOwner(engine, OWNER);
await engine.unsetConfig('search.remote_private_pages');
__resetPrivateVisibilityCacheForTests();
}
}, 120_000);
test('another member and an unbound token still see no private page on any path, after the owner read them', async () => {
expect(await privateSeenBy('bob')).toEqual({});
expect(await privateSeenBy('unbound')).toEqual({});
}, 240_000);
test('member access stays mandatory for the owner: another person\'s readable_by page is not_found', async () => {
const own = await call('owner', 'get_page', { slug: BOBS.slug });
expect(own.text).not.toContain(BOBS.canary);
expect((await call('bob', 'get_page', { slug: BOBS.slug })).text).toContain(BOBS.canary);
});
test('the owner speaking for a channel audience reads no private page; for itself alone it keeps the relaxation', async () => {
expect(await privateSeenBy('owner', `member:${OWNER},member:bob-example`)).toEqual({});
expect((await call('owner', 'get_page', { slug: PRIVATE.flagged.slug }, `member:${OWNER}`)).text).toContain(PRIVATE.flagged.canary);
}, 240_000);
test('_meta.access names the owner relaxation only for owner reads', async () => {
const relaxation = async (who: string) => ((await call(who, 'get_page', { slug: OPEN.slug })).meta?.access as { relaxation?: string } | undefined)?.relaxation;
expect(await relaxation('owner')).toBe('owner');
expect(await relaxation('bob')).toBe('none');
expect(await relaxation('unbound')).toBe('none');
});
test('access check and --as preview report the owner view', async () => {
expect((await accessCheck(engine, { token: 'owner' })).owner).toBe(true);
expect((await accessCheck(engine, { token: 'bob' })).owner).toBe(false);
const asOwner = await openAsPreview(engine, OWNER, 'get');
const page = await asOwner.run(() => dispatchToolCall(engine, 'get_page', { slug: PRIVATE.aliased.slug }, asOwner.context({ remote: false, sourceId: SRC })));
expect(page.content.map(c => c.text).join('\n')).toContain(PRIVATE.aliased.canary);
const asBob = await openAsPreview(engine, 'bob-example', 'get');
const hidden = await asBob.run(() => dispatchToolCall(engine, 'get_page', { slug: PRIVATE.aliased.slug }, asBob.context({ remote: false, sourceId: SRC })));
expect(hidden.content.map(c => c.text).join('\n')).not.toContain(PRIVATE.aliased.canary);
});
test('with no owner named, the owner\'s credential reads like any member again', async () => {
expect((await ownerView(engine)).bound_credentials.map(c => c.name).sort()).toEqual(['delegate', 'owner']);
await clearOwner(engine);
try {
expect(await privateSeenBy('owner')).toEqual({});
} finally {
await setOwner(engine, OWNER);
}
}, 240_000);
test('setting a disabled or unknown member as owner is refused and leaves the owner unchanged', async () => {
await expect(setOwner(engine, 'nobody-example')).rejects.toThrow();
await expect(setOwner(engine, 'Not Valid')).rejects.toThrow();
expect((await ownerView(engine)).owner).toBe(OWNER);
});
});
}
test('a fresh identity nested under the owner hides private pages unless it says otherwise', () => {
const nested = withCallerAccess({ identity: ['member:owner-example'], hidePrivate: false, owner: true }, () =>
withCallerAccess({ identity: ['member:bob-example'] }, () => currentCallerAccess()));
expect(nested.owner).toBe(false);
expect(nested.hidePrivate).toBe(true);
});