Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* GST-363 (PR 2): a brain that serves several people refuses remote reads from a connection bound to nobody.
*
* 1. Protects: on a brain with two or more enabled members (or config access.serves = several), every remote read op
* from a credential or stdio server bound to no member is refused with requester_scope_required before its handler
* runs; a connection that existed when the brain started serving several people reads for 14 days with an in-band
* notice (_meta.access.requester_scope) first; member-bound, audience-naming and attested calls, and credentials
* the operator marked --reads-unscoped, read as before; a one-person brain with several sources sees nothing new;
* hosted brains (access.requester_scope_enforce = false) get the notice and no refusal; agent jobs get the same
* gate; creating an unbound credential on such a brain is refused with credential_scope_required.
* 2. Fails when: a read op answers an unbound key after the grace, a new read op is neither refused nor exempted, the
* grace notice or the refusal loses its fix or date, a bound key or an attested call is refused, the one-person
* brain gets a notice, the hosted switch still refuses a DCR client, or the trigger restarts the grace.
* 3. Existing coverage: setup-serves-several.test.ts (labelling, brainServes), access-qm-actor.test.ts (attested
* calls), access-on-behalf-of.test.ts (audiences), member-read-access.test.ts (bound reads).
* 4. Real seams: legacy tokens through the serve --http legacy transport over a real socket (startHttpTransport) and
* the OAuth verifier; dispatchToolCall remote=true over stdio; the v309 trigger on PGLite (repo-less and a repo
* brain) and Postgres when DATABASE_URL is set; `bun src/cli.ts auth` spawned against a temp GBRAIN_HOME.
*/
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { execFileSync } from 'node:child_process';
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 type { AuthInfo } from '../src/core/ops/contract.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { importFromContent } from '../src/core/import-file.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 { operations } from '../src/core/operations.ts';
import { dispatchToolCall, type ToolResult } from '../src/mcp/dispatch.ts';
import { startHttpTransport } from '../src/mcp/http-transport.ts';
import { RateLimiter } from '../src/mcp/rate-limit.ts';
import { addMember, bindCredential, disableMember, enableMember } from '../src/core/access/members.ts';
import { linkMember } from '../src/core/access/actor.ts';
import { readAudienceAssertions } from '../src/core/access/audience.ts';
import { brainServes } from '../src/core/access/serves.ts';
import { assertCredentialScoped, OWN_JOB_OPS, printUnscopedReadsUpgradeNotice, REQUESTER_SCOPE_EXEMPT, requiresRequesterScope, readReadsUnscopedChanges } from '../src/core/access/requester-scope.ts';
import { unscopedSharedReadsEntry } from '../src/commands/doctor/checks/unscoped-shared-reads.ts';
import type { DoctorContext } from '../src/commands/doctor/context.ts';
import { takeBindingFlags } from '../src/commands/auth-binding.ts';
import { ownerLines } from '../src/commands/access.ts';
import { buildBrainTools } from '../src/core/minions/tools/brain-allowlist.ts';
import { __resetPrivateVisibilityCacheForTests } from '../src/core/search/private-visibility.ts';
import { getBrainHotMemoryMeta } from '../src/core/facts/meta-hook.ts';
import { CODES } from '../src/core/error-registry.ts';
import { testBackends } from './helpers/test-backends.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { runCli } from './helpers/cli-spawn.ts';
import { withEnv } from './helpers/with-env.ts';
const DAY = 24 * 3600 * 1000;
const iso = (ms: number) => new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
const PAGES: Record<string, string> = { 'notes/harbor-alpha': 'canaryalpha', 'notes/harbor-beta': 'canarybeta' };
const pageText = (slug: string, canary: string) => `---\ntype: note\ntitle: ${slug}\n---\n# ${slug}\n\nHarbor ledger notes ${canary}.\n`;
const roots: string[] = [];
afterAll(() => { for (const r of roots) rmSync(r, { recursive: true, force: true }); });
/**
* Every read operation's requester-scope class, reviewed by hand: a new read op fails this list until someone decides
* whether an unbound connection on a several-people brain may call it (add it to REQUESTER_SCOPE_EXEMPT) or not.
*/
const REVIEWED_EXEMPT = ['get_brain_identity', 'get_health', 'get_status_snapshot', 'join_brain', 'leave_brain', 'request_tools', 'search_modes', 'sync_brain_skills', 'whoami'];
type Call = { isError: boolean; text: string; json: Record<string, any>; meta: Record<string, any> | undefined; structured: Record<string, any> | undefined };
function shape(out: ToolResult): Call {
const text = out.content.map(c => c.text).join('\n');
let json: Record<string, any> = {};
try { json = JSON.parse(out.content[0]?.text ?? ''); } catch { /* prose */ }
return { isError: out.isError === true, text, json, meta: out._meta as Record<string, any> | undefined, structured: out.structuredContent as Record<string, any> | undefined };
}
describe('requiresRequesterScope: every read op is classified (deny by default)', () => {
test('every remote op declares mutating, and the exempt list is exactly the reviewed one', () => {
expect(operations.filter(op => op.mutating === undefined).map(op => op.name)).toEqual([]);
expect([...REQUESTER_SCOPE_EXEMPT].sort()).toEqual(REVIEWED_EXEMPT);
expect([...OWN_JOB_OPS].sort()).toEqual(['get_job', 'wait_job']);
for (const op of operations) {
const expected = (op.mutating === false || (op.scope ?? 'read') === 'read') && !REVIEWED_EXEMPT.includes(op.name);
expect({ op: op.name, gated: requiresRequesterScope(op, { scopes: ['read', 'write', 'admin'] }) }).toEqual({ op: op.name, gated: expected });
}
expect(requiresRequesterScope({ name: 'brand_new_read', mutating: undefined })).toBe(true);
expect(requiresRequesterScope(operations.find(op => op.name === 'think'))).toBe(true);
expect(requiresRequesterScope({ name: 'brand_new_read_scope_write', mutating: true, scope: 'read' })).toBe(true);
expect(requiresRequesterScope({ name: 'brand_new_mutating_no_scope', mutating: true })).toBe(true);
expect(requiresRequesterScope({ name: 'get_job', mutating: false }, { scopes: ['read'] })).toBe(false);
expect(requiresRequesterScope({ name: 'get_job', mutating: false }, { scopes: ['admin'] })).toBe(true);
expect(requiresRequesterScope({ name: 'get_job', mutating: false })).toBe(true);
});
});
for (const kind of testBackends()) {
describe(`refusing unscoped reads (${kind}, repo-less)`, () => {
let engine: BrainEngine;
let close: () => Promise<void>;
let server: Awaited<ReturnType<typeof startHttpTransport>>;
const provider = (dcr = false) => new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))), ...(dcr ? { allowClientCredentialsDcr: true } : {}) });
const keys: Record<string, { id: string; token: string }> = {};
const mint = async (name: string, member?: string) => {
const m = await mintLegacyToken(engine, { name, scopes: ['read', 'write'], takesHolders: ['world'] });
if (member) await bindCredential(engine, { kind: 'token', id: m.id }, { member });
keys[name] = { id: m.id, token: m.token };
};
const backdate = (name: string, daysAgo: number) => engine.executeRaw('UPDATE access_tokens SET created_at = $2::timestamptz WHERE id::text = $1', [keys[name]!.id, iso(Date.now() - daysAgo * DAY)]);
const setSince = (daysAgo: number) => engine.setConfig('access.serves_since', iso(Date.now() - daysAgo * DAY));
/** One tools/call over a real socket to the serve --http legacy transport. */
async function http(name: string, tool: string, args: Record<string, unknown>): Promise<Call> {
const res = await fetch(`http://127.0.0.1:${server.port}/mcp`, {
method: 'POST', headers: { authorization: `Bearer ${keys[name]!.token}`, 'content-type': 'application/json', accept: 'application/json, text/event-stream' },
body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: tool, arguments: args } }),
});
return shape((await res.json() as { result: ToolResult }).result);
}
const search = (name: string) => http(name, 'search', { query: 'harbor ledger notes', match: 'keyword', limit: 10 });
const stdio = async (tool: string, args: Record<string, unknown>) => shape(await dispatchToolCall(engine, tool, args, { remote: true, transport: 'stdio', sourceId: 'default', takesHoldersAllowList: ['world'] }));
const oauthCall = async (bearer: string, tool: string, args: Record<string, unknown>, extra: Record<string, unknown> = {}) => {
const auth = await provider().verifyAccessToken(bearer) as unknown as AuthInfo;
return shape(await dispatchToolCall(engine, tool, args, { remote: true, transport: 'http', auth, sourceId: 'default', takesHoldersAllowList: ['world'], ...extra }));
};
function refused(out: Call, reason: string) {
expect({ isError: out.isError, code: out.json.code, reason: out.json.reason }).toEqual({ isError: true, code: 'requester_scope_required', reason });
expect(out.structured?.error).toMatchObject({ code: 'requester_scope_required', reason });
expect(out.structured?.error.fix).toMatchObject({ next: expect.any(String), argv: expect.arrayContaining(['--member', '<MEMBER>']) });
for (const canary of Object.values(PAGES)) expect(out.text).not.toContain(canary);
}
beforeAll(async () => {
if (kind === 'postgres') ({ engine, close } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));
else {
const pglite = new PGLiteEngine();
await pglite.connect({ engine: 'pglite' } as never);
await pglite.initSchema();
engine = pglite;
close = () => pglite.disconnect();
}
__resetPrivateVisibilityCacheForTests();
for (const [slug, canary] of Object.entries(PAGES)) await importFromContent(engine, slug, pageText(slug, canary), { sourceId: 'default', noEmbed: true });
await addMember(engine, 'alice-example');
await mint('old-unbound');
await mint('alice-key', 'alice-example');
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 }),
} });
}, 240_000);
afterAll(async () => { await server?.stop?.(true); await close?.(); }, 60_000);
test('one member: nothing changes, no notice, and the brain has no several-people date', async () => {
const out = await search('old-unbound');
expect(out.isError).toBe(false);
expect(out.text).toContain('canaryalpha');
expect(out.meta?.access?.requester_scope).toBeUndefined();
expect(await engine.getConfig('access.serves_derived')).toBeNull();
expect(await engine.getConfig('access.serves_since')).toBeNull();
}, 60_000);
test('the second member sets the flag and the date once; disabling and re-enabling keeps the date', async () => {
await addMember(engine, 'bob-example');
expect(await engine.getConfig('access.serves_derived')).toBe('several');
const since = await engine.getConfig('access.serves_since');
expect(since).toMatch(/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ$/);
expect((await brainServes(engine))).toMatchObject({ serves: 'several', from: 'members', since });
await disableMember(engine, 'bob-example');
expect(await engine.getConfig('access.serves_derived')).toBe('one');
await enableMember(engine, 'bob-example');
expect(await engine.getConfig('access.serves_derived')).toBe('several');
expect(await engine.getConfig('access.serves_since')).toBe(since);
for (const pinned of ['one', ' One ']) {
await engine.setConfig('access.serves', pinned);
expect({ pinned, serves: (await brainServes(engine)).serves }).toEqual({ pinned, serves: 'one' });
expect((await search('old-unbound')).meta?.access?.requester_scope).toBeUndefined();
}
await engine.unsetConfig('access.serves');
}, 60_000);
test('the derived key unset or set to one by hand on a brain that serves several people is derived again at once', async () => {
expect(await engine.getConfig('access.serves_derived')).toBe('several');
await engine.unsetConfig('access.serves_derived');
expect(await engine.getConfig('access.serves_derived')).toBe('several');
await engine.setConfig('access.serves_derived', 'one');
expect(await engine.getConfig('access.serves_derived')).toBe('several');
expect((await brainServes(engine)).serves).toBe('several');
}, 60_000);
test('over HTTP, an old unbound key inside the grace reads with a notice naming the fix and the date', async () => {
await setSince(1);
await backdate('old-unbound', 2);
const out = await search('old-unbound');
expect(out.isError).toBe(false);
expect(out.text).toContain('canaryalpha');
const notice = out.meta?.access?.requester_scope;
expect(notice).toMatchObject({ state: 'grace', connection: 'token old-unbound' });
expect(Date.parse(notice.refuses_at)).toBe(Date.parse(await engine.getConfig('access.serves_since') as string) + 14 * DAY);
expect(notice.fix).toMatchObject({ argv: ['gbrain', 'auth', 'rescope', '--token', 'old-unbound', '--member', '<MEMBER>'], next: expect.any(String), verify: { argv: ['gbrain', 'access', 'check', '--token', 'old-unbound'] } });
expect(notice.message).toContain('--reads-unscoped --yes');
}, 60_000);
/**
* The request's config reads fail (a statement timeout under load): the whole-table snapshot and the policy read that
* names the serves keys. With `reread` the gate's one re-read of the serves keys fails too.
*/
async function withConfigReadsFailing<T>(reread: boolean, fn: () => Promise<T>): Promise<T> {
const target = engine as unknown as Record<string, unknown>;
const own = { executeRaw: Object.getOwnPropertyDescriptor(engine, 'executeRaw'), getAllConfig: Object.getOwnPropertyDescriptor(engine, 'getAllConfig') };
const realRaw = engine.executeRaw.bind(engine);
const timeout = () => Promise.reject(new Error('canceling statement due to statement timeout'));
target.getAllConfig = timeout;
target.executeRaw = (sql: string, params?: unknown[]) => {
const keys = params?.[0];
const servesRead = /FROM config WHERE key/.test(sql) && Array.isArray(keys) && keys.includes('access.serves');
if (servesRead && (reread || keys.includes('search.remote_private_pages'))) return timeout();
return realRaw(sql, params as never);
};
try { return await fn(); } finally {
for (const [k, d] of Object.entries(own)) if (d) Object.defineProperty(engine, k, d); else delete target[k];
}
}
test('an unreadable serves policy is read again: an unbound key in its grace still gets the notice', async () => {
await engine.setConfig('access.serves', 'several');
await setSince(1);
await backdate('old-unbound', 2);
try {
const out = await withConfigReadsFailing(false, () => search('old-unbound'));
expect(out.isError).toBe(false);
expect(out.meta?.access?.requester_scope).toMatchObject({ state: 'grace', connection: 'token old-unbound' });
} finally { await engine.unsetConfig('access.serves'); }
}, 60_000);
test('when the re-read fails too, the unbound read is refused as retryable and nothing is read', async () => {
await engine.setConfig('access.serves', 'several');
try {
const out = await withConfigReadsFailing(true, () => search('old-unbound'));
expect({ isError: out.isError, code: out.json.code }).toEqual({ isError: true, code: 'requester_scope_unknown' });
expect(out.structured?.error).toMatchObject({ code: 'requester_scope_unknown', fix: { next: 'wait' } });
expect(out.json.message).not.toContain('serves several');
for (const canary of Object.values(PAGES)) expect(out.text).not.toContain(canary);
expect((await withConfigReadsFailing(true, () => search('alice-key'))).isError).toBe(false);
} finally { await engine.unsetConfig('access.serves'); }
}, 60_000);
test('N2: on a brain pinned one, a double config-read failure is a wait-and-retry for an unbound read, saying the settings could not be read; bound callers read', async () => {
await engine.setConfig('access.serves', 'one');
try {
const out = await withConfigReadsFailing(true, () => search('old-unbound'));
expect({ isError: out.isError, code: out.json.code }).toEqual({ isError: true, code: 'requester_scope_unknown' });
const err = out.structured?.error;
expect(err).toMatchObject({ code: 'requester_scope_unknown', detail: 'retry_after_ms=2000',
fix: { next: 'wait', actor: 'provider', argv: ['gbrain', 'doctor', '--json'], consent: [], verify: { argv: ['gbrain', 'access', 'serves', '--json'] } } });
expect({ retryable: out.json.retryable, class: out.json.class }).toEqual({ retryable: true, class: 'retryable' });
expect(err.fix.why).toContain('retry_after_ms=2000');
expect(CODES.requester_scope_unknown.why).toContain('config read');
expect(out.json.message).toContain("settings could not be read");
expect(out.json.message).toContain('not an access decision');
expect(out.json.message).not.toMatch(/denied|bound to nobody|serves several/i);
for (const canary of Object.values(PAGES)) expect(out.text).not.toContain(canary);
const bound = await withConfigReadsFailing(true, () => search('alice-key'));
expect(bound.isError).toBe(false);
expect(bound.meta?.access?.requester_scope).toBeUndefined();
} finally { await engine.unsetConfig('access.serves'); }
}, 60_000);
test('on a one-person brain, a failed first read and a good re-read run the call with no notice', async () => {
await engine.setConfig('access.serves', 'one');
try {
const out = await withConfigReadsFailing(false, () => search('old-unbound'));
expect(out.isError).toBe(false);
expect(out.text).toContain('canaryalpha');
expect(out.meta?.access?.requester_scope).toBeUndefined();
} finally { await engine.unsetConfig('access.serves'); }
}, 60_000);
test('over HTTP, the same key after the grace is refused with the structured code, and the audit line records it', async () => {
await setSince(15);
await backdate('old-unbound', 16);
const out = await search('old-unbound');
refused(out, 'grace_ended');
expect(out.json.message).toContain('token old-unbound');
expect(out.json.message).toContain('two or more enabled members');
const audit = readAudienceAssertions().filter(e => e.outcome === 'requester_scope_required' && e.op === 'search');
expect(audit.length).toBeGreaterThan(0);
expect(JSON.stringify(audit)).not.toContain(keys['old-unbound']!.token);
}, 60_000);
test('a refused unbound connection gets no hot memory on the ops the gate lets through (exempt reads, writes); a bound one still does', async () => {
await setSince(15);
const fact = await dispatchToolCall(engine, 'remember', { fact: 'Harbor ledger notes canaryhotfact', provenance: 'fixture' }, { remote: false, sourceId: 'default' });
expect(fact.isError).toBeFalsy();
const hot = async (tool: string, args: Record<string, unknown>, stdioMember?: string) => {
const out = await dispatchToolCall(engine, tool, args, { remote: true, transport: 'stdio', sourceId: 'default', takesHoldersAllowList: ['world'],
metaHook: getBrainHotMemoryMeta, sessionId: `hot-${tool}-${stdioMember ?? 'unbound'}`, ...(stdioMember ? { stdioMember } : {}) });
return { isError: out.isError === true, all: JSON.stringify(out) };
};
expect((await stdio('search', { query: 'harbor ledger notes', match: 'keyword', limit: 10 })).json).toMatchObject({ code: 'requester_scope_required', reason: 'grace_ended' });
for (const tool of ['whoami', 'get_brain_identity', 'search_modes']) {
const out = await hot(tool, {});
expect({ tool, isError: out.isError, leaked: out.all.includes('canaryhotfact') }).toEqual({ tool, isError: false, leaked: false });
}
const write = await hot('remember', { fact: 'Harbor ledger notes canaryhotwrite', provenance: 'fixture' });
expect(write.all.includes('canaryhotfact')).toBe(false);
const bound = await hot('whoami', {}, 'alice-example');
expect({ isError: bound.isError, sees: bound.all.includes('canaryhotfact') }).toEqual({ isError: false, sees: true });
}, 60_000);
test('over HTTP, a member-bound key is unaffected', async () => {
const out = await search('alice-key');
expect(out.isError).toBe(false);
expect(out.text).toContain('canarybeta');
expect(out.meta?.access).toMatchObject({ member: 'alice-example' });
expect(out.meta?.access?.requester_scope).toBeUndefined();
}, 60_000);
test('a key created after the brain started serving several people is refused at once; whoami still answers', async () => {
await setSince(1);
await mint('fresh-unbound');
refused(await search('fresh-unbound'), 'created_after');
await engine.executeRaw('UPDATE access_tokens SET created_at = $2::timestamptz WHERE id::text = $1', [keys['fresh-unbound']!.id, await engine.getConfig('access.serves_since')]);
refused(await search('fresh-unbound'), 'created_after');
const who = await http('fresh-unbound', 'whoami', {});
expect(who.isError).toBe(false);
expect(who.json.access.requester_scope).toEqual({ state: 'refused', reason: 'created_after', argv: ['gbrain', 'auth', 'rescope', '--token', 'fresh-unbound', '--member', '<MEMBER>'] });
expect((await http('alice-key', 'whoami', {})).json.access.requester_scope).toEqual({ state: 'scoped' });
}, 60_000);
test('enumeration: every gated read op is refused for an unbound key before its handler runs', async () => {
await setSince(15);
const auth = await provider().verifyAccessToken(keys['fresh-unbound']!.token) as unknown as AuthInfo;
const ran: string[] = [];
const saved = new Map(operations.map(op => [op.name, op.handler]));
for (const op of operations) op.handler = (async () => { ran.push(op.name); return {}; }) as typeof op.handler;
const answered: string[] = [];
try {
for (const op of operations.filter(o => (o.mutating === false || o.scope === 'read') && !o.localOnly)) {
const out = shape(await dispatchToolCall(engine, op.name, {}, { remote: true, transport: 'http', auth, sourceId: 'default', takesHoldersAllowList: ['world'] }));
if (op.cliOnly) {
expect({ op: op.name, code: out.json.code }).toEqual({ op: op.name, code: 'trusted_local_only' });
} else if (requiresRequesterScope(op, auth)) {
expect({ op: op.name, code: out.structured?.error?.code }).toEqual({ op: op.name, code: 'requester_scope_required' });
} else answered.push(op.name);
}
} finally {
for (const op of operations) op.handler = saved.get(op.name)!;
}
expect(ran.filter(n => !answered.includes(n))).toEqual([]);
expect(answered.sort()).toEqual([...REVIEWED_EXEMPT, ...OWN_JOB_OPS].sort());
expect(ran).not.toContain('think');
}, 120_000);
test('the opt-out: --reads-unscoped lets one key read with no notice, and removing it refuses again', async () => {
expect(() => takeBindingFlags(['--reads-unscoped'])).toThrow(/--yes/);
expect(takeBindingFlags(['--reads-unscoped', '--yes']).patch).toEqual({ readsUnscoped: true });
expect(takeBindingFlags(['--reads-unscoped', 'none']).patch).toEqual({ readsUnscoped: false });
const set = await bindCredential(engine, { kind: 'token', id: keys['fresh-unbound']!.id }, { readsUnscoped: true });
expect(set).toMatchObject({ reads_unscoped: true, changed: true });
const out = await search('fresh-unbound');
expect(out.isError).toBe(false);
expect(out.meta?.access?.requester_scope).toBeUndefined();
expect((await bindCredential(engine, { kind: 'token', id: keys['fresh-unbound']!.id }, { readsUnscoped: true })).changed).toBe(false);
await bindCredential(engine, { kind: 'token', id: keys['fresh-unbound']!.id }, { readsUnscoped: false });
refused(await search('fresh-unbound'), 'created_after');
}, 60_000);
test('stdio: unbound reads world pages with a notice in the grace (never a member-restricted page) and is refused after it; the fix is the per-harness --stdio-member binding or a per-person HTTP key, on either engine, never config set; a server started with --stdio-member reads plainly', async () => {
const setupFix = ['gbrain', 'setup', '<HARNESS>', '--stdio-member', '<MEMBER>'];
const route = (text: string) => {
expect(text).toContain('gbrain setup claude-code|codex --stdio-member');
expect(text).toContain('gbrain serve --http');
expect(text).not.toContain('PGLite');
};
await importFromContent(engine, 'notes/alice-only', '---\ntype: note\ntitle: alice only\nreadable_by: [alice-example]\n---\n# alice only\n\nHarbor ledger notes canaryalice.\n', { sourceId: 'default', noEmbed: true });
await setSince(1);
const inGrace = await stdio('get_page', { slug: 'notes/harbor-alpha' });
expect(inGrace.isError).toBe(false);
expect(inGrace.text).toContain('canaryalpha');
expect(inGrace.meta?.access?.requester_scope).toMatchObject({ state: 'grace', connection: 'this stdio server', fix: { argv: expect.arrayContaining(setupFix), next: 'tell_user_to_run' } });
route(inGrace.meta?.access?.requester_scope.message);
expect((await stdio('get_page', { slug: 'notes/alice-only' })).text).not.toContain('canaryalice');
await setSince(15);
const after = await stdio('get_page', { slug: 'notes/harbor-alpha' });
expect(after.structured?.error).toMatchObject({ code: 'requester_scope_required', reason: 'grace_ended', fix: { argv: expect.arrayContaining(setupFix) } });
expect(after.text).not.toContain('canaryalpha');
route(after.text);
for (const out of [inGrace, after]) expect(JSON.stringify([out.meta, out.structured, out.text])).not.toContain('config set mcp.stdio_member');
const who = await stdio('whoami', {});
route(who.json.access.note);
expect(who.json.access.requester_scope.argv).toEqual(setupFix);
expect(JSON.stringify(who.json)).not.toContain('config set mcp.stdio_member');
const registered = shape(await dispatchToolCall(engine, 'get_page', { slug: 'notes/alice-only' }, { remote: true, transport: 'stdio', sourceId: 'default', takesHoldersAllowList: ['world'], stdioMember: 'alice-example' }));
expect(registered.isError).toBe(false);
expect(registered.text).toContain('canaryalice');
expect(registered.meta?.access?.requester_scope).toBeUndefined();
await engine.setConfig('mcp.stdio_member', 'alice-example');
const bound = await stdio('get_page', { slug: 'notes/harbor-alpha' });
expect(bound.isError).toBe(false);
expect(bound.meta?.access?.requester_scope).toBeUndefined();
await engine.unsetConfig('mcp.stdio_member');
}, 60_000);
test('R94: on a brain pinned access.serves one, unbound reads (old, new, HTTP, stdio) answer with no notice after any grace; the owner-bound key reads the same private pages here as on a several-people brain', async () => {
await importFromContent(engine, 'notes/owner-private', '---\ntype: note\ntitle: owner private\nvisibility: private\n---\n# owner private\n\nHarbor ledger notes canaryowner.\n', { sourceId: 'default', noEmbed: true });
await engine.setConfig('access.owner_member', 'alice-example');
__resetPrivateVisibilityCacheForTests();
await setSince(30);
await mint('pinned-fresh');
const ownerRead = async () => (await http('alice-key', 'get_page', { slug: 'notes/owner-private' })).json;
const several = await ownerRead();
expect(several.compiled_truth).toContain('canaryowner');
await engine.setConfig('access.serves', 'one');
try {
expect(await ownerRead()).toEqual(several);
for (const name of ['old-unbound', 'pinned-fresh']) {
const out = await search(name);
expect({ name, isError: out.isError }).toEqual({ name, isError: false });
expect(out.text).toContain('canaryalpha');
expect(out.meta?.access?.requester_scope).toBeUndefined();
}
const viaStdio = await stdio('get_page', { slug: 'notes/harbor-alpha' });
expect(viaStdio.isError).toBe(false);
expect(viaStdio.meta?.access?.requester_scope).toBeUndefined();
expect((await http('pinned-fresh', 'whoami', {})).json.access.requester_scope).toEqual({ state: 'not_required' });
await expect(assertCredentialScoped(engine, null, 'token', 'pinned-new')).resolves.toBeUndefined();
} finally {
await engine.unsetConfig('access.serves');
await engine.unsetConfig('access.owner_member');
__resetPrivateVisibilityCacheForTests();
}
}, 60_000);
test('a shared agent naming its audience reads; the same credential with no audience is refused', async () => {
const c = await provider().registerClientManual('agent-' + kind, ['client_credentials'], 'read write', [], 'default');
await bindCredential(engine, { kind: 'client', id: c.clientId }, { mayActFor: ['member:alice-example', 'member:bob-example'] });
const bearer = (await provider().exchangeClientCredentials(c.clientId, c.clientSecret!)).access_token;
const named = await oauthCall(bearer, 'get_page', { slug: 'notes/harbor-alpha' }, { onBehalfOf: { header: 'alice-example' } });
expect(named.isError).toBe(false);
expect(named.meta?.access?.requester_scope).toBeUndefined();
const bare = await oauthCall(bearer, 'get_page', { slug: 'notes/harbor-alpha' });
expect(bare.structured?.error).toMatchObject({ code: 'requester_scope_required', fix: { argv: ['gbrain', 'auth', 'rescope', '--client', c.clientId, '--member', '<MEMBER>'] } });
}, 60_000);
test('an attested call is exempt', async () => {
const c = await provider().registerClientManual('qm-' + kind, ['client_credentials'], 'read write', [], 'default');
await bindCredential(engine, { kind: 'client', id: c.clientId }, { attestActor: 'qm', attestOps: ['get_page', 'search'] });
await linkMember(engine, 'alice-example', 'qm', 'U0ALICE');
const bearer = (await provider().exchangeClientCredentials(c.clientId, c.clientSecret!)).access_token;
const out = await oauthCall(bearer, 'get_page', { slug: 'notes/harbor-alpha' }, { actor: { header: 'U0ALICE' } });
expect(out.isError).toBe(false);
expect(out.text).toContain('canaryalpha');
expect(out.meta?.access).toMatchObject({ member: 'alice-example', actor: { system: 'qm' } });
expect(out.meta?.access?.requester_scope).toBeUndefined();
}, 60_000);
test('hosted switch off: an unbound DCR client registered after the date reads with the notice, and is refused once the switch is on', async () => {
const dcr = await provider(true).clientsStore.registerClient!({ client_name: 'dcr-' + kind, grant_types: ['client_credentials'], scope: 'read', redirect_uris: [], token_endpoint_auth_method: 'client_secret_post' } as never);
const bearer = (await provider().exchangeClientCredentials(dcr.client_id, dcr.client_secret!)).access_token;
await engine.setConfig('access.requester_scope_enforce', 'false');
const off = await oauthCall(bearer, 'get_page', { slug: 'notes/harbor-alpha' });
expect(off.isError).toBe(false);
expect(off.text).toContain('canaryalpha');
expect(off.meta?.access?.requester_scope).toMatchObject({ state: 'not_enforced', refuses_at: null, connection: `OAuth client ${dcr.client_id}` });
await expect(assertCredentialScoped(engine, null, 'token', 'any-name')).resolves.toBeUndefined();
await engine.unsetConfig('access.requester_scope_enforce');
const on = await oauthCall(bearer, 'get_page', { slug: 'notes/harbor-alpha' });
expect(on.structured?.error).toMatchObject({ code: 'requester_scope_required', reason: 'created_after' });
}, 60_000);
test('an agent job from an unbound credential is refused at its first tool call, structured; in the grace it runs', async () => {
const c = await provider().registerClientManual('job-' + kind, ['client_credentials'], 'read write', [], 'default');
const tools = buildBrainTools({ subagentId: 7, engine, config: { engine: 'pglite' } as never, sourceId: 'default',
delegatedAuth: { clientId: c.clientId, scopes: ['read', 'agent'], sourceId: 'default', allowedSources: ['default'] } });
const getPage = tools.find(t => t.name === 'brain_get_page')!;
const ctx = { engine, jobId: 1, signal: new AbortController().signal } as never;
const err = await getPage.execute({ slug: 'notes/harbor-alpha' }, ctx).then(() => null, e => e);
expect(err).toMatchObject({ code: 'requester_scope_required', reason: 'created_after' });
expect(err.fix).toMatchObject({ argv: ['gbrain', 'auth', 'rescope', '--client', c.clientId, '--member', '<MEMBER>'] });
await engine.executeRaw('UPDATE oauth_clients SET client_id_issued_at = $2 WHERE client_id = $1', [c.clientId, Math.floor((Date.now() - 2 * DAY) / 1000)]);
await setSince(1);
const ran = await getPage.execute({ slug: 'notes/harbor-alpha' }, ctx);
expect(JSON.stringify(ran)).toContain('canaryalpha');
}, 60_000);
test('creating an unbound credential on this brain is refused with credential_scope_required and the fix', async () => {
const err = await assertCredentialScoped(engine, null, 'token', 'new-bot').then(() => null, e => e);
expect(err).toMatchObject({ code: 'credential_scope_required' });
expect(err.fix).toMatchObject({ argv: ['gbrain', 'auth', 'create', 'new-bot', '--member', '<MEMBER>'] });
for (const patch of [{ member: 'alice-example' }, { mayActFor: ['member:alice-example'] }, { readsUnscoped: true }, { attestActor: 'qm' }]) {
await expect(assertCredentialScoped(engine, patch, 'client', 'new-bot')).resolves.toBeUndefined();
}
}, 60_000);
});
}
describe('the access owner hint names the per-harness binding', () => {
const view = { owner: 'alice-example', bound_credentials: [], inactive: null } as unknown as Parameters<typeof ownerLines>[0];
test('it names --stdio-member for one harness and the per-person HTTP key, never a bare config set', () => {
const text = ownerLines(view).join('\n');
expect(text).toContain('gbrain setup claude-code|codex --stdio-member alice-example');
expect(text).toContain('gbrain serve --http');
expect(text).toContain('--member alice-example');
expect(text).not.toContain('config set mcp.stdio_member');
});
});
describe('doctor unscoped_shared_reads and the post-upgrade list (pglite, repo-less)', () => {
let engine: BrainEngine;
const doctor = async () => (await unscopedSharedReadsEntry.run({ engine } as unknown as DoctorContext) as Array<Record<string, any>>)[0]!;
beforeAll(async () => {
engine = new PGLiteEngine(); await engine.connect({ engine: 'pglite' } as never); await engine.initSchema();
}, 120_000);
afterAll(async () => { await engine?.disconnect(); }, 60_000);
test('not applicable for one person; fails per unbound credential with its grace end and command; opt-outs are info; hosted warns', async () => {
const old = await mintLegacyToken(engine, { name: 'old-bot', scopes: ['read'], takesHolders: ['world'] });
expect(await doctor()).toMatchObject({ name: 'unscoped_shared_reads', status: 'ok', readiness_state: 'not_applicable' });
for (const id of ['alice-example', 'bob-example']) await addMember(engine, id);
await engine.executeRaw('UPDATE access_tokens SET created_at = $2::timestamptz WHERE id::text = $1', [old.id, iso(Date.now() - 2 * DAY)]);
await engine.setConfig('access.serves_since', iso(Date.now() - DAY));
const fresh = await mintLegacyToken(engine, { name: 'fresh-bot', scopes: ['read'], takesHolders: ['world'] });
const optOut = await mintLegacyToken(engine, { name: 'team-bot', scopes: ['read'], takesHolders: ['world'] });
await bindCredential(engine, { kind: 'token', id: optOut.id }, { readsUnscoped: true });
const bound = await mintLegacyToken(engine, { name: 'alice-bot', scopes: ['read'], takesHolders: ['world'] });
await bindCredential(engine, { kind: 'token', id: bound.id }, { member: 'alice-example' });
const c = await doctor();
expect(c.status).toBe('fail');
expect(c.details.connections).toEqual([
{ connection: 'token fresh-bot', state: 'refused', refuses_at: null, argv: ['gbrain', 'auth', 'rescope', '--token', 'fresh-bot', '--member', '<MEMBER>'] },
{ connection: 'token old-bot', state: 'grace', refuses_at: new Date(Date.parse(await engine.getConfig('access.serves_since') as string) + 14 * DAY).toISOString(), argv: ['gbrain', 'auth', 'rescope', '--token', 'old-bot', '--member', '<MEMBER>'] },
{ connection: 'token team-bot', state: 'reads_unscoped', refuses_at: null, argv: ['gbrain', 'auth', 'rescope', '--token', 'team-bot', '--member', '<MEMBER>'] },
]);
expect(c.message).toContain('Reading unscoped on purpose (--reads-unscoped): token team-bot');
expect(c.fix).toMatchObject({ argv: ['gbrain', 'auth', 'rescope', '--token', 'fresh-bot', '--member', '<MEMBER>'], ask_user: true });
const lines: string[] = [];
const log = console.log;
console.log = (...a: unknown[]) => { lines.push(a.join(' ')); };
try { await printUnscopedReadsUpgradeNotice(engine); } finally { console.log = log; }
expect(lines.join('\n')).toContain('token old-bot: grace until');
expect(lines.join('\n')).toContain('Fix: gbrain auth rescope --token fresh-bot --member <MEMBER>');
expect(lines.join('\n')).not.toContain('team-bot');
await engine.setConfig('access.requester_scope_enforce', 'false');
expect((await doctor()).status).toBe('warn');
await engine.unsetConfig('access.requester_scope_enforce');
for (const t of [old, fresh]) await bindCredential(engine, { kind: 'token', id: t.id }, { member: 'bob-example' });
expect(await doctor()).toMatchObject({ status: 'ok' });
}, 60_000);
});
describe('a one-person brain with several sources sees no refusal and no notice (pglite, repo-less)', () => {
let engine: BrainEngine;
beforeAll(async () => {
engine = new PGLiteEngine(); await engine.connect({ engine: 'pglite' } as never); await engine.initSchema();
for (const src of ['source-a', 'source-b', 'source-c']) await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1) ON CONFLICT (id) DO NOTHING', [src]);
for (const src of ['source-a', 'source-b', 'source-c']) await importFromContent(engine, `notes/${src}`, pageText(`notes/${src}`, `canary${src.replace('-', '')}`), { sourceId: src, noEmbed: true });
await addMember(engine, 'alice-example');
await engine.setConfig('access.owner_member', 'alice-example');
}, 120_000);
afterAll(async () => { await engine?.disconnect(); }, 60_000);
test('an unbound key created today and an unbound stdio server read every source with nothing new in _meta', async () => {
const m = await mintLegacyToken(engine, { name: 'one-person-bot', scopes: ['read'], takesHolders: ['world'], sourceGrant: ['source-a', 'source-b', 'source-c'] });
const auth = await new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine) } as never).verifyAccessToken(m.token) as unknown as AuthInfo;
for (const transport of ['http', 'stdio'] as const) {
const out = shape(await dispatchToolCall(engine, 'search', { query: 'harbor ledger notes', match: 'keyword', limit: 10, source_ids: ['source-a', 'source-b', 'source-c'] },
{ remote: true, transport, ...(transport === 'http' ? { auth } : { localFederatedSourceIds: ['source-b', 'source-c'] }), sourceId: 'source-a', takesHoldersAllowList: ['world'] }));
expect({ transport, isError: out.isError, text: out.isError ? out.text : '' }).toEqual({ transport, isError: false, text: '' });
for (const src of ['sourcea', 'sourceb', 'sourcec']) expect(out.text).toContain(`canary${src}`);
expect(out.meta?.access).not.toHaveProperty('requester_scope');
}
await expect(assertCredentialScoped(engine, null, 'token', 'x')).resolves.toBeUndefined();
expect(await engine.getConfig('access.serves_since')).toBeNull();
}, 60_000);
});
describe('a repo brain behaves the same (pglite, source with a git checkout)', () => {
let engine: BrainEngine;
beforeAll(async () => {
engine = new PGLiteEngine(); await engine.connect({ engine: 'pglite' } as never); await engine.initSchema();
const repo = mkdtempSync(join(tmpdir(), 'gbrain-scope-repo-')); roots.push(repo);
execFileSync('git', ['init', '-q', repo]);
await engine.executeRaw('INSERT INTO sources (id, name, local_path) VALUES ($1, $1, $2) ON CONFLICT (id) DO NOTHING', ['repo-src', repo]);
await importFromContent(engine, 'notes/repo-page', pageText('notes/repo-page', 'canaryrepo'), { sourceId: 'repo-src', noEmbed: true });
for (const id of ['alice-example', 'bob-example']) await addMember(engine, id);
}, 120_000);
afterAll(async () => { await engine?.disconnect(); }, 60_000);
test('unbound stdio in the grace gets the notice, after it the refusal', async () => {
const call = async () => shape(await dispatchToolCall(engine, 'get_page', { slug: 'notes/repo-page' }, { remote: true, transport: 'stdio', sourceId: 'repo-src', takesHoldersAllowList: ['world'] }));
expect((await call()).meta?.access?.requester_scope).toMatchObject({ state: 'grace' });
await engine.setConfig('access.serves_since', iso(Date.now() - 15 * DAY));
expect((await call()).structured?.error).toMatchObject({ code: 'requester_scope_required', reason: 'grace_ended' });
}, 60_000);
});
describe('the CLI refuses an unbound credential and records the opt-out (pglite, spawned)', () => {
test('auth create refuses credential_scope_required; --reads-unscoped needs --yes and lands in the audit trail', async () => {
const home = mkdtempSync(join(tmpdir(), 'gbrain-scope-cli-')); roots.push(home);
const env = { GBRAIN_HOME: home, HOME: home, GBRAIN_AUDIT_DIR: join(home, 'audit') };
const run = (args: string[]) => runCli(args, { env, timeoutMs: 120_000 });
expect((await run(['init', '--pglite', '--no-embedding', '--json'])).exitCode).toBe(0);
for (const id of ['alice-example', 'bob-example']) expect((await run(['access', 'member', 'add', id])).exitCode).toBe(0);
const refused = await run(['auth', 'create', 'shared-bot']);
expect(refused.exitCode).not.toBe(0);
expect(refused.stdout + refused.stderr).toContain('credential_scope_required');
expect(refused.stdout + refused.stderr).not.toMatch(/gbrain_[A-Za-z0-9]{20,}/);
const noYes = await run(['auth', 'create', 'shared-bot', '--reads-unscoped']);
expect(noYes.exitCode).not.toBe(0);
expect(noYes.stdout + noYes.stderr).toContain('--yes');
const optOut = await run(['auth', 'create', 'shared-bot', '--reads-unscoped', '--yes']);
expect(optOut.exitCode).toBe(0);
expect(optOut.stdout).toContain('reads unscoped: yes');
const bound = await run(['auth', 'create', 'alice-bot', '--member', 'alice-example']);
expect(bound.exitCode).toBe(0);
const marked = await run(['access', 'check', '--token', 'shared-bot', '--json']);
expect(JSON.parse(marked.stdout)).toMatchObject({ verdict: 'unbound', reads_unscoped: true });
expect(JSON.parse(marked.stdout).explanation).toContain('--reads-unscoped');
expect(JSON.parse((await run(['access', 'check', '--token', 'alice-bot', '--json'])).stdout)).toMatchObject({ verdict: 'reads_as_member', reads_unscoped: false });
await withEnv({ GBRAIN_AUDIT_DIR: join(home, 'audit') }, () => {
expect(readReadsUnscopedChanges()).toEqual([expect.objectContaining({ credential: 'token shared-bot', reads_unscoped: true, by: 'gbrain auth' })]);
});
}, 180_000);
test('the upgrade path never binds stdio: post-upgrade and apply-migrations on a brain with an owner and two members leave mcp.stdio_member unset', async () => {
const home = mkdtempSync(join(tmpdir(), 'gbrain-scope-upgrade-')); roots.push(home);
const env = { GBRAIN_HOME: home, HOME: home, GBRAIN_AUDIT_DIR: join(home, 'audit') };
const run = (args: string[]) => runCli(args, { env, timeoutMs: 180_000 });
expect((await run(['init', '--pglite', '--no-embedding', '--json'])).exitCode).toBe(0);
expect((await run(['access', 'member', 'add', 'alice-example'])).exitCode).toBe(0);
expect((await run(['auth', 'create', 'old-bot'])).exitCode).toBe(0);
expect((await run(['access', 'member', 'add', 'bob-example'])).exitCode).toBe(0);
const owner = await run(['access', 'owner', 'set', 'alice-example']);
expect(owner.exitCode).toBe(0);
expect(owner.stdout).toContain('--stdio-member alice-example');
expect(owner.stdout).not.toContain('config set mcp.stdio_member');
const stdioMember = async () => (await run(['config', 'get', 'mcp.stdio_member'])).stdout.trim();
const before = await stdioMember();
const post = await run(['post-upgrade']);
expect(post.stdout + post.stderr).toContain('token old-bot');
expect(post.stdout + post.stderr).not.toContain('config set mcp.stdio_member');
await run(['apply-migrations', '--yes', '--non-interactive']);
expect({ before, after: await stdioMember() }).toEqual({ before: '', after: '' });
}, 600_000);
test('auth --help names --reads-unscoped --yes on auth create and register-client, the flags the credential_scope_required refusal asks for', async () => {
const help = await runCli(['auth', '--help'], { timeoutMs: 60_000 });
const text = help.stdout + help.stderr;
expect(text).toMatch(/gbrain auth create <name> [^\n]*\[--reads-unscoped --yes\]/);
expect(text).toMatch(/gbrain auth register-client <name>[\s\S]*--reads-unscoped --yes/);
}, 120_000);
});