Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* GBRA-231: shared agents read as the audience their harness names (plan v6 section 4).
*
* 1. Protects: a shared agent's call carrying an audience (the X-Gbrain-On-Behalf-Of header or request-level
* _meta.on_behalf_of) reads only the pages every audience entry may read (page readers and folder rules), within
* the agent's source grant; a guest reads no restricted page; the agent's own member binding never adds to it; a
* channel audience never sees a visibility: private page, whatever the agent's grant or an operator hatch says. The
* audience is re-read on every call, bounded by the credential's live may_act_for (stdio: mcp.stdio_may_act_for),
* and refused before work when it sits in tool arguments, is malformed, names someone outside may_act_for or names
* no enabled member. Queued writes and agent jobs keep the audience they were accepted for, and their receipts and
* job reads answer only a caller under that same audience.
* 2. Fails when: an audience reads a page one of its entries may not read (on any read path), the agent's own member
* leaks into an audience view (a guest turn sees the bot's pages), a prompt-injected argument picks the audience,
* a refusal carries page content, a channel sees a private page, a later call keeps an earlier audience, the
* semantic cache key ignores the audience, a stored write or job reads as the credential's member instead of
* its audience, or a receipt or job answers another audience of the same credential.
* 3. Existing coverage (member-read-access, access-writes) pins single-member credentials only.
* 4. Real seams: legacy tokens minted by the token service, bound by the member CLI functions, verified by the
* serve --http verifier and by the legacy bearer transport over a real socket, dispatched through MCP dispatch on
* a repo-less brain (no git checkout; folder rules in the database store); embeddings stubbed.
*/
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
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 { parseRescopeTokenArgs, rescopeLegacyToken } from '../src/core/grants/legacy-token.ts';
import { dispatchToolCall, type ToolResult } from '../src/mcp/dispatch.ts';
import { operationsByName, OperationError } from '../src/core/operations.ts';
import { startHttpTransport } from '../src/mcp/http-transport.ts';
import { RateLimiter } from '../src/mcp/rate-limit.ts';
import { __resetPrivateVisibilityCacheForTests, withCallerAccess } from '../src/core/search/private-visibility.ts';
import { knobsHash, resolveSearchMode } from '../src/core/search/mode.ts';
import { remoteCallerAccess } from '../src/core/access/caller.ts';
import { addGroup, addMember, bindCredential, disableMember } from '../src/core/access/members.ts';
import { proposeRevision } from '../src/core/access/policy.ts';
import { readAudienceAssertions, STDIO_MAY_ACT_FOR_KEY, type AudiencePrincipal } from '../src/core/access/audience.ts';
import { submissionAuthority, authorizeStoredRequest } from '../src/core/persistence/authority.ts';
import { admitWrite } from '../src/core/persistence/journal.ts';
import { buildBrainTools } from '../src/core/minions/tools/brain-allowlist.ts';
import { parseSubmissionAuthority, prepareRemoteAgent, withSubmissionAuthority, type RemoteAgentAuthority } from '../src/core/minions/submission-authority.ts';
import type { AuthInfo, OperationContext } from '../src/core/ops/contract.ts';
import { sharedAgentAccessEntry } from '../src/commands/doctor/checks/shared-agent-access.ts';
import type { DoctorContext } from '../src/commands/doctor/context.ts';
import { testBackends } from './helpers/test-backends.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { withEnv } from './helpers/with-env.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 = 'obo-team';
const PAGES = {
alice: { slug: 'notes/alice-plan', fm: ['readable_by: [alice-example]'], canary: 'canaryoboalice' },
bob: { slug: 'notes/bob-plan', fm: ['readable_by: [bob-example]'], canary: 'canaryobobob' },
both: { slug: 'notes/both-plan', fm: ['readable_by: [alice-example, bob-example]'], canary: 'canaryoboboth' },
team: { slug: 'notes/team-plan', fm: ['readable_by: [group:team-a]'], canary: 'canaryoboteam' },
dan: { slug: 'notes/dan-plan', fm: ['readable_by: [dan-example]'], canary: 'canaryobodan' },
folder: { slug: 'partners/alice-example/brief', fm: [] as string[], canary: 'canaryobofolder' },
quiet: { slug: 'notes/quiet-plan', fm: ['visibility: private'], canary: 'canaryoboquiet' },
} as const;
type Key = keyof typeof PAGES;
const RESTRICTED: Key[] = ['alice', 'bob', 'both', 'team', 'dan', 'folder', 'quiet'];
const OPEN = { slug: 'notes/open-plan', canary: 'canaryoboopen' };
const page = (key: Key) => ['---', 'type: note', 'title: ' + key + ' plan', ...PAGES[key].fm, '---', '# ' + key + ' plan', '',
'Harbor ledger planning notes ' + PAGES[key].canary + ' for the roadmap.'].join('\n');
/** Read paths (label, op, args); a path given the slug may echo it in a not-found error, so it counts content only. */
function reads(key: Key): Array<[string, string, Record<string, unknown>]> {
const slug = PAGES[key].slug;
return [
['search hybrid', 'search', { query: 'harbor ledger planning notes', fields: 'full', limit: 30 }],
['search keyword', 'search', { query: 'planning notes', match: 'keyword', fields: 'full', limit: 30 }],
['query', 'query', { query: 'harbor ledger planning notes', expand: false, fields: 'full', limit: 30 }],
['get_page', 'get_page', { slug }],
['list_pages', 'list_pages', { slug_prefix: slug.slice(0, slug.indexOf('/') + 1) }],
['get_chunks', 'get_chunks', { slug }],
['get_versions', 'get_versions', { slug, include_body: true }],
['resolve_slugs', 'resolve_slugs', { partial: slug.slice(slug.lastIndexOf('/') + 1) }],
];
}
const ECHOES_SLUG = new Set(['get_page', 'get_chunks', 'get_versions']);
const CORE = ['search keyword', 'get_page', 'list_pages'];
type Channels = { header?: string; meta?: unknown };
for (const kind of testBackends()) {
describe('shared agents on_behalf_of (' + kind + ', repo-less)', () => {
let engine: BrainEngine;
let close: () => Promise<void>;
const tokens: Record<string, { id: string; token: string }> = {};
const provider = () => new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });
const verify = async (who: string) => await provider().verifyAccessToken(tokens[who]!.token) as unknown as AuthInfo;
async function call(who: string | null, op: string, params: Record<string, unknown>, ch: Channels = {}, extra: { sessionId?: string } = {}) {
const auth = who ? await verify(who) : undefined;
const out: ToolResult = await dispatchToolCall(engine, op, { ...params }, {
remote: true, transport: who ? 'http' : 'stdio', auth, sourceId: auth?.sourceId ?? SRC, takesHoldersAllowList: ['world'],
...(extra.sessionId ? { sessionId: extra.sessionId } : {}),
onBehalfOf: { header: ch.header, requestMeta: ch.meta === undefined ? undefined : { on_behalf_of: ch.meta } },
});
const text = out.content.map(c => c.text).join('\n');
let json: Record<string, unknown> = {};
try { json = JSON.parse(text); } catch { /* prose */ }
return { isError: out.isError === true, text, json, meta: out._meta };
}
const seen = (text: string, key: Key, label: string) => text.includes(PAGES[key].canary) || (!ECHOES_SLUG.has(label) && text.includes(PAGES[key].slug));
/** Restricted keys a caller (under its channels) sees on any read path, and the paths where each was seen. */
async function visible(who: string | null, ch: Channels, keys: readonly Key[] = RESTRICTED): Promise<Record<string, string[]>> {
const out: Record<string, string[]> = {};
for (const key of keys) {
for (const [label, op, params] of reads(key)) {
const { text } = await call(who, op, params, ch);
if (seen(text, key, label)) (out[key] ??= []).push(label);
}
}
return out;
}
/** Exactly the allowed restricted keys are visible, each on the core paths. */
async function expectView(who: string | null, ch: Channels, allowed: Key[]) {
const got = await visible(who, ch);
expect({ who, ch, keys: Object.keys(got).sort() }).toEqual({ who, ch, keys: [...allowed].sort() });
for (const key of allowed) for (const label of CORE) expect({ key, label, seen: got[key]!.includes(label) }).toEqual({ key, label, seen: true });
}
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]);
for (const id of ['alice-example', 'bob-example', 'dan-example', 'eve-example']) await addMember(engine, id);
await addGroup(engine, 'team-a', ['bob-example']);
await addGroup(engine, 'team-b');
await disableMember(engine, 'eve-example');
await proposeRevision(engine, SRC, [{ id: 'alice', prefix: 'partners/alice-example/', readable_by: ['member:alice-example'] }], { origin: 'cli', store: 'database' });
await importFromContent(engine, OPEN.slug, '---\ntype: note\ntitle: Open plan\n---\n# Open plan\n\nHarbor ledger planning notes ' + OPEN.canary + '.', { sourceId: SRC });
for (const key of Object.keys(PAGES) as Key[]) {
await importFromContent(engine, PAGES[key].slug, page(key), { sourceId: SRC });
await engine.createVersion(PAGES[key].slug, { sourceId: SRC });
}
const mint = async (name: string, binding: { member?: string; mayActFor?: string[] }, scopes = ['read']) => {
const minted = await mintLegacyToken(engine, { name, scopes, takesHolders: ['world'], sourceGrant: [SRC] });
tokens[name] = { id: minted.id, token: minted.token };
if (binding.member || binding.mayActFor) await bindCredential(engine, { kind: 'token', id: minted.id }, binding);
if (!binding.member) await readsUnscopedOnPurpose(engine, minted.id);
};
await mint('bot', { mayActFor: ['member:alice-example', 'member:bob-example', 'group:team-a', 'guest'] });
await mint('bot-dan', { member: 'dan-example', mayActFor: ['guest', 'member:alice-example', 'member:bob-example'] }, ['read', 'write']);
await mint('narrow', { mayActFor: ['member:alice-example'] });
await mint('wild', { mayActFor: ['*'] });
await mint('granted', { mayActFor: ['member:alice-example', 'member:bob-example'] });
await mint('plain', {});
await rescopeLegacyToken(engine, parseRescopeTokenArgs(['granted', '--private-pages', 'granted-sources']));
}, 240_000);
afterAll(async () => {
__setEmbedTransportForTests(null);
resetGateway();
await close?.();
}, 60_000);
test('fixture control: without an audience the bot reads no restricted page and the dan-bound bot reads only dan\'s', async () => {
await expectView('bot', {}, []);
await expectView('bot-dan', {}, ['dan']);
}, 240_000);
test('a two-member audience reads only the pages both members may read', async () => {
await expectView('bot', { header: 'alice-example, bob-example' }, ['both']);
await expectView('bot', { meta: ['bob-example', 'alice-example'] }, ['both']);
}, 240_000);
test('a one-member audience reads as that member: page readers and folder rules', async () => {
await expectView('bot', { meta: ['alice-example'] }, ['alice', 'both', 'folder']);
await expectView('bot', { header: 'bob-example' }, ['bob', 'both', 'team']);
}, 240_000);
test('a group audience counts as one principal and reads what the group may read', async () => {
await expectView('bot', { header: 'group:team-a' }, ['team']);
}, 240_000);
test('a guest reads no restricted page, and the agent\'s own member never adds to an audience view', async () => {
await expectView('bot', { header: 'guest' }, []);
await expectView('bot-dan', { header: 'guest' }, []);
await expectView('bot-dan', { meta: ['alice-example', 'guest'] }, []);
await expectView('bot-dan', { header: 'alice-example' }, ['alice', 'both', 'folder']);
}, 240_000);
test('the audience is read on every call: switching it mid-session never keeps an earlier view', async () => {
const sessionId = 'obo-session-' + randomUUID();
const get = (ch: Channels) => call('bot', 'get_page', { slug: PAGES.alice.slug }, ch, { sessionId });
expect((await get({ header: 'alice-example' })).text).toContain(PAGES.alice.canary);
expect((await get({ header: 'bob-example' })).text).not.toContain(PAGES.alice.canary);
expect((await get({})).text).not.toContain(PAGES.alice.canary);
expect((await get({ meta: ['alice-example'] })).text).toContain(PAGES.alice.canary);
}, 120_000);
test('an audience inside tool arguments is refused before any read, even beside a valid header', async () => {
const cases: Array<[Record<string, unknown>, Channels]> = [
[{ slug: PAGES.alice.slug, on_behalf_of: ['alice-example'] }, {}],
[{ slug: PAGES.alice.slug, _meta: { on_behalf_of: ['alice-example'] } }, {}],
[{ slug: PAGES.alice.slug, on_behalf_of: 'alice-example' }, { header: 'alice-example' }],
];
for (const [params, ch] of cases) {
const out = await call('bot', 'get_page', params, ch);
expect({ isError: out.isError, code: out.json.code }).toEqual({ isError: true, code: 'on_behalf_of_in_arguments' });
expect(out.text).not.toContain(PAGES.alice.canary);
expect(out.json.docs).toContain('write-refusals.md#on_behalf_of_in_arguments');
}
}, 60_000);
test('a malformed, empty, oversized or conflicting audience is refused before any read', async () => {
const cases: Channels[] = [
{ header: '' }, { header: ' , ' }, { header: 'alice-example,,bob-example' }, { header: 'Not Valid' }, { header: 'ext:crm:42' },
{ meta: [] }, { meta: 'alice-example' }, { meta: [7] }, { meta: Array.from({ length: 51 }, (_, i) => 'm' + i + '-example') },
{ header: 'alice-example', meta: ['bob-example'] }, { header: 'alice-example, guest', meta: ['alice-example'] },
];
for (const ch of cases) {
const out = await call('bot', 'get_page', { slug: PAGES.both.slug }, ch);
expect({ ch, code: out.json.code }).toEqual({ ch, code: 'on_behalf_of_invalid_audience' });
expect(out.text).not.toContain(PAGES.both.canary);
}
const same = await call('bot', 'get_page', { slug: PAGES.both.slug }, { header: 'bob-example, Alice-Example', meta: ['alice-example', 'member:bob-example'] });
expect(same.text).toContain(PAGES.both.canary);
}, 120_000);
test('an entry outside may_act_for is refused with the operator\'s command, before membership is checked, and no content', async () => {
const out = await call('narrow', 'get_page', { slug: PAGES.alice.slug }, { header: 'alice-example, bob-example' });
expect(out.json.code).toBe('on_behalf_of_not_permitted');
expect(out.json.message).toContain('token narrow');
expect(out.json.message).toContain('member:bob-example');
expect(out.text).not.toContain(PAGES.alice.canary);
const fix = out.json.fix as Record<string, unknown>;
expect({ next: fix.next, argv: fix.argv }).toEqual({ next: 'tell_user_to_run',
argv: ['gbrain', 'auth', 'rescope', '--token', 'narrow', '--may-act-for', 'member:alice-example,member:bob-example'] });
expect((await call('narrow', 'get_page', { slug: PAGES.alice.slug }, { header: 'ghost-example' })).json.code).toBe('on_behalf_of_not_permitted');
expect((await call('plain', 'get_page', { slug: PAGES.alice.slug }, { meta: ['alice-example'] })).json.code).toBe('on_behalf_of_not_permitted');
expect((await call('bot', 'get_page', { slug: PAGES.alice.slug }, { header: 'group:team-b' })).json.code).toBe('on_behalf_of_not_permitted');
}, 60_000);
test('may_act_for is read on every call: narrowing it refuses the next call', async () => {
expect((await call('narrow', 'get_page', { slug: PAGES.alice.slug }, { header: 'alice-example' })).text).toContain(PAGES.alice.canary);
await bindCredential(engine, { kind: 'token', id: tokens.narrow!.id }, { mayActFor: null });
try {
expect((await call('narrow', 'get_page', { slug: PAGES.alice.slug }, { header: 'alice-example' })).json.code).toBe('on_behalf_of_not_permitted');
} finally {
await bindCredential(engine, { kind: 'token', id: tokens.narrow!.id }, { mayActFor: ['member:alice-example'] });
}
}, 60_000);
test('an unknown or disabled member, or an unknown group, is refused rather than read as a guest', async () => {
for (const header of ['ghost-example', 'eve-example', 'group:no-such-group', 'alice-example, ghost-example']) {
const out = await call('wild', 'get_page', { slug: PAGES.alice.slug }, { header });
expect({ header, code: out.json.code }).toEqual({ header, code: 'on_behalf_of_unknown_member' });
expect(out.text).not.toContain(PAGES.alice.canary);
}
expect((await call('wild', 'get_page', { slug: PAGES.alice.slug }, { header: 'alice-example' })).text).toContain(PAGES.alice.canary);
}, 60_000);
test('privacy relaxes only for a one-member audience: granted_sources and the hatch never open a private page to a channel', async () => {
const quiet = (ch: Channels) => call('granted', 'get_page', { slug: PAGES.quiet.slug }, ch).then(o => o.text.includes(PAGES.quiet.canary));
expect(await quiet({ header: 'alice-example' })).toBe(true);
expect(await quiet({ header: 'alice-example, bob-example' })).toBe(false);
expect(await quiet({})).toBe(true);
await withEnv({ GBRAIN_REMOTE_PRIVATE_PAGES: '1' }, async () => {
expect((await call('bot', 'get_page', { slug: PAGES.quiet.slug }, { header: 'alice-example' })).text).toContain(PAGES.quiet.canary);
expect((await call('bot', 'get_page', { slug: PAGES.quiet.slug }, { header: 'alice-example, guest' })).text).not.toContain(PAGES.quiet.canary);
expect((await call('bot', 'search', { query: 'planning notes', match: 'keyword', fields: 'full', limit: 30 }, { header: 'group:team-a' })).text).not.toContain(PAGES.quiet.canary);
});
}, 120_000);
test('every response carries _meta.access, and whoami returns the same view as access.applied', async () => {
const out = await call('bot', 'search', { query: 'planning notes', match: 'keyword', limit: 5 }, { header: 'alice-example, bob-example' });
const access = out.meta?.access as Record<string, unknown>;
expect(access).toMatchObject({ member: null, groups: [], audience: ['member:alice-example', 'member:bob-example'], relaxation: 'none' });
expect((access.policy_rev as Record<string, number>)[SRC]).toBeGreaterThan(0);
await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1) ON CONFLICT (id) DO NOTHING', ['obo-other-src']);
await proposeRevision(engine, 'obo-other-src', [{ id: 'other', prefix: 'other/', readable_by: ['member:bob-example'] }], { origin: 'cli', store: 'database' });
const scoped = (await call('bot', 'get_page', { slug: OPEN.slug }, { header: 'alice-example' })).meta?.access as Record<string, unknown>;
expect(Object.keys(scoped.policy_rev as Record<string, number>)).toEqual([SRC]);
const single = await call('granted', 'get_page', { slug: OPEN.slug }, { meta: ['bob-example'] });
expect(single.meta?.access).toMatchObject({ member: 'bob-example', groups: ['team-a'], audience: ['member:bob-example'], relaxation: 'granted_sources' });
const plain = await call('bot-dan', 'get_page', { slug: OPEN.slug });
expect(plain.meta?.access).toMatchObject({ member: 'dan-example', audience: null });
const who = await call('bot-dan', 'whoami', {}, { header: 'guest' });
expect((who.json.access as Record<string, unknown>).applied).toMatchObject({ member: null, groups: [], audience: ['guest'] });
expect((who.json.access as Record<string, unknown>).member).toBe('dan-example');
}, 60_000);
test('the semantic cache key differs for each audience, and from an unbound caller', () => {
const knobs = resolveSearchMode({ mode: 'balanced' });
const under = (access: Parameters<typeof withCallerAccess>[0]) => withCallerAccess(access, () => knobsHash(knobs, { excludePrivate: true }));
const unbound = under({ identity: [] });
const pair = under({ identity: [], audience: ['member:alice-example', 'member:bob-example'], audienceIdentities: [['member:alice-example'], ['member:bob-example']] });
const other = under({ identity: [], audience: ['guest', 'member:alice-example'], audienceIdentities: [[], ['member:alice-example']] });
expect(new Set([unbound, pair, other]).size).toBe(3);
});
test('a write under an audience is checked against the audience: an unreadable target is not_found, readers must keep every entry', async () => {
const hidden = await call('bot-dan', 'add_tag', { slug: PAGES.dan.slug, tag: 'x-tag' }, { header: 'guest' });
expect(hidden.json.code).toBe('page_not_found');
const lockout = await call('bot-dan', 'put_page', { slug: 'notes/channel-new', content: '---\ntype: note\nreadable_by: [alice-example]\n---\n# New\n\nNew.' }, { header: 'alice-example, bob-example' });
expect(lockout.json).toMatchObject({ code: 'readable_by_invalid', message: expect.stringContaining('the audience this connection acts for') });
const [rows] = await engine.executeRaw<{ n: number }>("SELECT count(*)::int AS n FROM pages WHERE slug = 'notes/channel-new'");
expect(rows!.n).toBe(0);
const own = await call('bot-dan', 'add_tag', { slug: PAGES.dan.slug, tag: 'x-tag' });
expect(own.isError).toBe(false);
}, 120_000);
test('a stored write keeps its audience: publication re-resolves it, never the principal\'s own member, and a revoked may_act_for refuses it', async () => {
const auth = await verify('bot-dan');
const ctx = { engine, config: { engine: 'pglite' }, sourceId: SRC, auth, remote: true, dryRun: false, takesHoldersAllowList: ['world'],
logger: { info() {}, warn() {}, error() {} } } as unknown as OperationContext;
const [source] = await engine.executeRaw<{ incarnation: string }>('SELECT incarnation FROM sources WHERE id=$1', [SRC]);
const authority = await withCallerAccess(await remoteCallerAccess(engine, auth, undefined, 'http', ['member:alice-example']),
() => submissionAuthority(ctx, 'add_tag', SRC, source!.incarnation, PAGES.alice.slug));
expect(authority.actingFor).toEqual(['member:alice-example']);
const row = await admitWrite(engine, { principal: authority.principal, authority, operation: 'add_tag', sourceId: SRC,
sourceIncarnation: source!.incarnation, slug: PAGES.alice.slug, requestId: randomUUID(), callerIntent: {}, intent: {} });
await authorizeStoredRequest(engine, row);
await bindCredential(engine, { kind: 'token', id: tokens['bot-dan']!.id }, { mayActFor: ['guest'] });
try {
await expect(authorizeStoredRequest(engine, row)).rejects.toMatchObject({ code: 'page_not_found' });
} finally {
await bindCredential(engine, { kind: 'token', id: tokens['bot-dan']!.id }, { mayActFor: ['guest', 'member:alice-example', 'member:bob-example'] });
}
const guest = await withCallerAccess(await remoteCallerAccess(engine, auth, undefined, 'http', ['guest']),
() => submissionAuthority(ctx, 'add_tag', SRC, source!.incarnation, OPEN.slug));
expect({ actingFor: guest.actingFor, excludePrivate: guest.excludePrivate }).toEqual({ actingFor: ['guest'], excludePrivate: true });
const danRow = await admitWrite(engine, { principal: guest.principal, authority: { ...guest }, operation: 'add_tag', sourceId: SRC,
sourceIncarnation: source!.incarnation, slug: PAGES.dan.slug, requestId: randomUUID(), callerIntent: {}, intent: {} });
await expect(authorizeStoredRequest(engine, danRow)).rejects.toMatchObject({ code: 'page_not_found' });
}, 120_000);
test('an agent job reads as the audience it was submitted for, never as its client\'s member', async () => {
const { clientId } = await provider().registerClientManual('obo-agent', ['client_credentials'], 'read', [], SRC);
await bindCredential(engine, { kind: 'client', id: clientId }, { member: 'dan-example', mayActFor: ['guest', 'member:alice-example'] });
const tools = buildBrainTools({ subagentId: 9, engine, config: { engine: 'pglite' } as never, sourceId: SRC,
delegatedAuth: { clientId, scopes: ['read', 'agent'], sourceId: SRC, allowedSources: [SRC] } });
const getPage = tools.find(t => t.name === 'brain_get_page')!;
const read = async (slug: string, actingFor?: string[]) => {
const authority: RemoteAgentAuthority = { version: 1, kind: 'remote_agent', principal: { kind: 'oauth_client', id: clientId },
grant: { scopes: ['read', 'agent'], sourceId: SRC, sourceCreatedAt: new Date(0).toISOString(), allowedTools: ['get_page'], allowedSlugPrefixes: [], ...(actingFor ? { actingFor } : {}) },
payloadHash: '0'.repeat(64) };
expect(parseSubmissionAuthority(authority)).not.toBeNull();
try { return JSON.stringify(await withSubmissionAuthority(authority, () => getPage.execute({ slug }, { engine, jobId: 1, remote: true } as never))); }
catch (e) { return String((e as Error).message); }
};
expect(await read(PAGES.dan.slug)).toContain(PAGES.dan.canary);
expect(await read(PAGES.dan.slug, ['guest'])).not.toContain(PAGES.dan.canary);
expect(await read(PAGES.alice.slug, ['member:alice-example'])).toContain(PAGES.alice.canary);
expect(await read(PAGES.dan.slug, ['member:alice-example'])).not.toContain(PAGES.dan.canary);
await engine.executeRaw("UPDATE oauth_clients SET scope = 'read agent', bound_tools = ARRAY['get_page'], bound_source_id = source_id, federated_read = ARRAY[source_id], delegated_namespace = 'job', delegated_slug_prefixes = NULL, bound_max_concurrent = 1 WHERE client_id = $1", [clientId]);
const agentAuth = { token: 'x', clientId, scopes: ['read', 'agent'], sourceId: SRC, principal: { kind: 'oauth_client', id: clientId } } as unknown as AuthInfo;
const submit = async (audience?: AudiencePrincipal[]) => withCallerAccess(await remoteCallerAccess(engine, agentAuth, undefined, 'http', audience ?? null),
() => prepareRemoteAgent({ engine, auth: agentAuth, remote: true } as unknown as OperationContext, { source_id: SRC, allowed_tools: ['get_page'], allowed_slug_prefixes: [] }));
expect((await submit(['member:alice-example'])).grant.actingFor).toEqual(['member:alice-example']);
expect((await submit()).grant.actingFor).toBeUndefined();
await bindCredential(engine, { kind: 'client', id: clientId }, { mayActFor: ['guest'] });
expect(await read(PAGES.alice.slug, ['member:alice-example'])).not.toContain(PAGES.alice.canary);
expect(parseSubmissionAuthority({ version: 1, kind: 'remote_agent', principal: { kind: 'oauth_client', id: clientId },
grant: { scopes: ['agent'], sourceId: SRC, sourceCreatedAt: 'x', allowedTools: ['get_page'], allowedSlugPrefixes: [], actingFor: [] }, payloadHash: '0'.repeat(64) })).toBeNull();
}, 120_000);
test('an agent job stays with the audience it was submitted for on every owner-fenced job read and cancel', async () => {
const { clientId } = await provider().registerClientManual('obo-jobs', ['client_credentials'], 'read', [], SRC);
await bindCredential(engine, { kind: 'client', id: clientId }, { mayActFor: ['guest', 'member:alice-example', 'member:bob-example'] });
await engine.executeRaw("UPDATE oauth_clients SET scope = 'read agent', bound_tools = ARRAY['get_page'], bound_source_id = source_id, federated_read = ARRAY[source_id], delegated_namespace = 'job', delegated_slug_prefixes = NULL, bound_max_concurrent = 1 WHERE client_id = $1", [clientId]);
const agentAuth = { token: 'x', clientId, scopes: ['read', 'agent'], sourceId: SRC, principal: { kind: 'oauth_client', id: clientId } } as unknown as AuthInfo;
const ctx = { engine, config: {}, logger: { info() {}, warn() {}, error() {} }, dryRun: false, remote: true, transport: 'http', sourceId: SRC, auth: agentAuth } as unknown as OperationContext;
const as = async <T>(audience: AudiencePrincipal[] | null, fn: () => Promise<T>) =>
withCallerAccess(await remoteCallerAccess(engine, agentAuth, undefined, 'http', audience), fn);
const seed = async (audience: AudiencePrincipal[] | null, status: 'completed' | 'waiting') => {
const authority = await as(audience, () => prepareRemoteAgent(ctx, { source_id: SRC, allowed_tools: ['get_page'], allowed_slug_prefixes: [] }));
const marker = 'canaryobojob' + randomUUID().slice(0, 8);
const [row] = await engine.executeRaw<{ id: number }>(
`INSERT INTO minion_jobs (submission_authority, name, status, data, result, finished_at)
VALUES ($1::text::jsonb, 'subagent', $2, $3::text::jsonb, $4::text::jsonb, ${status === 'completed' ? 'now()' : 'NULL'}) RETURNING id`,
[JSON.stringify(authority), status, JSON.stringify({ prompt: 'seeded', __owner_client_id: clientId }), JSON.stringify({ marker })]);
return { id: Number(row!.id), marker };
};
const op = (name: string) => operationsByName[name]!;
const outcome = async (audience: AudiencePrincipal[] | null, fn: () => Promise<unknown>, seen: (out: unknown) => boolean) => {
try { return seen(await as(audience, fn)) ? 'visible' : 'absent'; }
catch (e) { if (e instanceof OperationError) return e.canonical ?? e.code; throw e; }
};
const reads = async (audience: AudiencePrincipal[] | null, job: { id: number; marker: string }) => {
const has = (out: unknown) => (out as { id?: number }).id === job.id;
const listed = (out: unknown) => ((Array.isArray(out) ? out : (out as { jobs: unknown[] }).jobs) as Array<{ id: number }>).some(j => j.id === job.id);
return {
get_agent_job: await outcome(audience, () => op('get_agent_job').handler(ctx, { id: job.id }), out => JSON.stringify(out).includes(job.marker)),
get_job: await outcome(audience, () => op('get_job').handler(ctx, { id: job.id }), has),
wait_job: await outcome(audience, () => op('wait_job').handler(ctx, { id: job.id, timeout_s: 0 }), has),
get_job_progress: await outcome(audience, () => op('get_job_progress').handler(ctx, { id: job.id }), has),
list_jobs: await outcome(audience, () => op('list_jobs').handler(ctx, {}), listed),
list_jobs_finished_since: await outcome(audience, () => op('list_jobs').handler(ctx, { finished_since: '2000-01-01T00:00:00Z' }), listed),
};
};
const VISIBLE = { get_agent_job: 'visible', get_job: 'visible', wait_job: 'visible', get_job_progress: 'visible', list_jobs: 'visible', list_jobs_finished_since: 'visible' };
const HIDDEN = { get_agent_job: 'not_found', get_job: 'not_found', wait_job: 'not_found', get_job_progress: 'not_found', list_jobs: 'absent', list_jobs_finished_since: 'absent' };
const ALICE: AudiencePrincipal[] = ['member:alice-example'];
const BOB: AudiencePrincipal[] = ['member:bob-example'];
const GUEST: AudiencePrincipal[] = ['guest'];
const PAIR: AudiencePrincipal[] = ['member:alice-example', 'member:bob-example'];
const aliceJob = await seed(ALICE, 'completed');
const plainJob = await seed(null, 'completed');
const pairJob = await seed(PAIR, 'completed');
const cases: Array<[string, { id: number; marker: string }, AudiencePrincipal[] | null, typeof VISIBLE]> = [
['alice on her job', aliceJob, ALICE, VISIBLE],
['bob on alice\'s job', aliceJob, BOB, HIDDEN],
['guest on alice\'s job', aliceJob, GUEST, HIDDEN],
['no audience on alice\'s job', aliceJob, null, HIDDEN],
['alice and bob on alice\'s job', aliceJob, PAIR, HIDDEN],
['no audience on the unaudienced job', plainJob, null, VISIBLE],
['alice on the unaudienced job', plainJob, ALICE, HIDDEN],
['guest on the unaudienced job', plainJob, GUEST, HIDDEN],
['the same pair in another order', pairJob, ['member:bob-example', 'member:alice-example'], VISIBLE],
['alice alone on the pair job', pairJob, ALICE, HIDDEN],
];
for (const [label, job, audience, want] of cases) expect({ label, got: await reads(audience, job) }).toEqual({ label, got: want });
const cancel = async (audience: AudiencePrincipal[] | null, id: number) =>
outcome(audience, () => op('cancel_job').handler(ctx, { id }), out => (out as { status?: string }).status === 'cancelled');
const waiting = await seed(ALICE, 'waiting');
for (const audience of [BOB, GUEST, null, PAIR]) expect({ audience, got: await cancel(audience, waiting.id) }).toEqual({ audience, got: 'invalid_params' });
const [still] = await engine.executeRaw<{ status: string }>('SELECT status FROM minion_jobs WHERE id = $1', [waiting.id]);
expect(still!.status).toBe('waiting');
expect(await cancel(ALICE, waiting.id)).toBe('visible');
const plainWaiting = await seed(null, 'waiting');
expect(await cancel(ALICE, plainWaiting.id)).toBe('invalid_params');
expect(await cancel(null, plainWaiting.id)).toBe('visible');
}, 120_000);
test('a write receipt stays with the audience it was written for: get, list, cancel and request_id replay', async () => {
const requestId = 'obo-receipt-' + randomUUID().slice(0, 6);
const content = '---\ntype: note\ntitle: Receipt plan\n---\n# Receipt plan\n\nReceipt plan ' + requestId + '.';
const write = (ch: Channels) => call('bot-dan', 'put_page', { slug: 'notes/' + requestId, content, request_id: requestId }, ch);
const alice = { header: 'alice-example' };
expect((await write(alice)).isError).toBe(false);
expect((await call('bot-dan', 'get_write_request', { request_id: requestId }, alice)).isError).toBe(false);
expect((await call('bot-dan', 'list_write_requests', {}, alice)).text).toContain(requestId);
for (const ch of [{ header: 'bob-example' }, { header: 'guest' }, { header: 'alice-example, bob-example' }, {}]) {
const got = await call('bot-dan', 'get_write_request', { request_id: requestId }, ch);
expect({ ch, isError: got.isError, code: got.json.code ?? got.json.error }).toEqual({ ch, isError: true, code: 'not_found' });
expect({ ch, listed: (await call('bot-dan', 'list_write_requests', {}, ch)).text.includes(requestId) }).toEqual({ ch, listed: false });
const cancelled = await call('bot-dan', 'cancel_write_request', { request_id: requestId }, ch);
expect({ ch, isError: cancelled.isError, code: cancelled.json.code ?? cancelled.json.error }).toEqual({ ch, isError: true, code: 'not_found' });
const replay = await write(ch);
expect({ ch, code: replay.json.code ?? replay.json.error }).toEqual({ ch, code: 'idempotency_conflict' });
}
expect((await write(alice)).isError).toBe(false);
}, 120_000);
test('a stdio server refuses every audience until mcp.stdio_may_act_for lists it', async () => {
const refused = await call(null, 'get_page', { slug: PAGES.alice.slug }, { meta: ['alice-example'] });
expect(refused.json.code).toBe('on_behalf_of_not_permitted');
expect(((refused.json.fix as Record<string, unknown>).argv as string[]).slice(0, 5)).toEqual(['gbrain', 'config', 'set', STDIO_MAY_ACT_FOR_KEY, 'member:alice-example']);
await engine.setConfig(STDIO_MAY_ACT_FOR_KEY, 'alice-example,guest');
try {
expect((await call(null, 'get_page', { slug: PAGES.alice.slug }, { meta: ['alice-example'] })).text).toContain(PAGES.alice.canary);
expect((await call(null, 'get_page', { slug: PAGES.alice.slug }, { meta: ['guest'] })).text).not.toContain(PAGES.alice.canary);
expect((await call(null, 'get_page', { slug: PAGES.bob.slug }, { meta: ['bob-example'] })).json.code).toBe('on_behalf_of_not_permitted');
} finally {
await engine.setConfig(STDIO_MAY_ACT_FOR_KEY, '');
}
}, 60_000);
test('the legacy bearer transport reads the header and request-level _meta over a real socket', async () => {
const 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 }),
} });
try {
const post = async (headers: Record<string, string>, meta?: unknown) => {
const res = await fetch('http://127.0.0.1:' + server.port + '/mcp', {
method: 'POST', headers: { authorization: 'Bearer ' + tokens.bot!.token, 'content-type': 'application/json', ...headers },
body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'get_page', arguments: { slug: PAGES.alice.slug }, ...(meta ? { _meta: meta } : {}) } }),
});
return await res.text();
};
expect(await post({ 'x-gbrain-on-behalf-of': 'alice-example' })).toContain(PAGES.alice.canary);
expect(await post({}, { on_behalf_of: ['alice-example'] })).toContain(PAGES.alice.canary);
expect(await post({ 'X-Gbrain-On-Behalf-Of': 'bob-example' })).not.toContain(PAGES.alice.canary);
expect(await post({})).not.toContain(PAGES.alice.canary);
const conflict = await post({ 'x-gbrain-on-behalf-of': 'alice-example' }, { on_behalf_of: ['bob-example'] });
expect(conflict).toContain('on_behalf_of_invalid_audience');
expect(conflict).not.toContain(PAGES.alice.canary);
} finally {
server.stop(true);
}
}, 60_000);
test('doctor warns on a may_act_for of * (credential or stdio) and is ok on explicit lists', async () => {
const run = async () => (await sharedAgentAccessEntry.run({ engine } as unknown as DoctorContext) as Array<{ name: string; status: string; message: string }>)[0]!;
const warned = await run();
expect(warned.status).toBe('warn');
expect(warned.message).toContain('token wild');
await bindCredential(engine, { kind: 'token', id: tokens.wild!.id }, { mayActFor: ['member:alice-example'] });
try {
expect((await run()).status).toBe('ok');
await engine.setConfig(STDIO_MAY_ACT_FOR_KEY, '*');
try {
const stdio = await run();
expect(stdio.status).toBe('warn');
expect(stdio.message).toContain(STDIO_MAY_ACT_FOR_KEY);
} finally {
await engine.setConfig(STDIO_MAY_ACT_FOR_KEY, '');
}
} finally {
await bindCredential(engine, { kind: 'token', id: tokens.wild!.id }, { mayActFor: ['*'] });
}
}, 60_000);
test('each assertion is appended to the audit trail with its outcome', async () => {
const before = readAudienceAssertions().length;
await call('bot', 'get_page', { slug: OPEN.slug }, { header: 'alice-example' });
await call('narrow', 'get_page', { slug: OPEN.slug }, { header: 'bob-example' });
const added = readAudienceAssertions().slice(before);
expect(added.map(e => ({ outcome: e.outcome, audience: e.audience, op: e.op, transport: e.transport }))).toEqual([
{ outcome: 'accepted', audience: ['member:alice-example'], op: 'get_page', transport: 'http' },
{ outcome: 'on_behalf_of_not_permitted', audience: ['member:bob-example'], op: 'get_page', transport: 'http' },
]);
expect(added[0]!.principal).toBe('legacy_token:' + tokens.bot!.id);
}, 60_000);
});
}
describe('shared agents on an unrestricted brain (pglite, repo-less)', () => {
let engine: PGLiteEngine;
beforeAll(async () => {
engine = new PGLiteEngine();
await engine.connect({ engine: 'pglite' } as never);
await engine.initSchema();
}, 120_000);
afterAll(async () => {
__resetPrivateVisibilityCacheForTests();
await engine.disconnect();
});
test('a channel audience never sees a private page under the operator hatch before any member exists', async () => {
try {
await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1)', ['obo-open-src']);
await importFromContent(engine, 'notes/quiet', '---\ntype: note\ntitle: Quiet\nvisibility: private\n---\n# Quiet\n\nHarbor ledger canaryoboopenquiet.', { sourceId: 'obo-open-src', noEmbed: true });
await addGroup(engine, 'room-a');
await addGroup(engine, 'room-b');
const minted = await mintLegacyToken(engine, { name: 'chan-bot', scopes: ['read'], takesHolders: ['world'], sourceGrant: ['obo-open-src'] });
await bindCredential(engine, { kind: 'token', id: minted.id }, { mayActFor: ['guest', 'group:room-a', 'group:room-b'] });
const provider = new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });
await withEnv({ GBRAIN_REMOTE_PRIVATE_PAGES: '1' }, async () => {
__resetPrivateVisibilityCacheForTests();
const auth = await provider.verifyAccessToken(minted.token) as unknown as AuthInfo;
const read = async (op: string, params: Record<string, unknown>, header?: string) => (await dispatchToolCall(engine, op, params, {
remote: true, transport: 'http', auth, sourceId: 'obo-open-src', takesHoldersAllowList: ['world'], ...(header ? { onBehalfOf: { header } } : {}) })).content.map(c => c.text).join('\n');
expect(await read('get_page', { slug: 'notes/quiet' })).toContain('canaryoboopenquiet');
for (const header of ['guest', 'group:room-a, group:room-b', 'group:room-a']) {
expect(await read('get_page', { slug: 'notes/quiet' }, header)).not.toContain('canaryoboopenquiet');
expect(await read('search', { query: 'harbor ledger', match: 'keyword', fields: 'full' }, header)).not.toContain('canaryoboopenquiet');
expect(await read('list_pages', {}, header)).not.toContain('notes/quiet');
}
});
} finally {
__resetPrivateVisibilityCacheForTests();
}
}, 120_000);
});