Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* GST-359 C1: the attested actor (x-qm-actor) and member links.
*
* 1. Protects: a QM call reads and writes as exactly the member its canonical person id is linked to, and only when
* the credential holds the attest right (a client-credentials client or member-less legacy token, checked on the
* token's own grant), the operation is in its attested list, and any acting_user argument equals the header. An
* attested call never reads a visibility: private page, whatever the attest client's grant or the operator hatch
* says. Links compare exactly, and unlink or disable take effect on the next call, at write publication and at a
* job's next tool call (one coverage function, actorCoverage).
* 2. Fails when: a header widens a client that holds no right, an argument picks or changes the person, an id is
* case-folded or truncated, an attested call inherits granted_sources or the hatch, a stored write or job keeps
* reading as a member after the link is gone, a refusal lacks structuredContent.error, or initialize loses its
* description or changes its instructions.
* 3. Existing coverage: test/access-on-behalf-of.test.ts pins B's audience path, which this reuses for one member.
* 4. Real seams: OAuth clients registered and issued tokens by the provider's client-credentials grant, legacy tokens
* minted by the token service, 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; embeddings stubbed.
*/
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { createHash, 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 { startHttpTransport } from '../src/mcp/http-transport.ts';
import { RateLimiter } from '../src/mcp/rate-limit.ts';
import { GBRAIN_MCP_INSTRUCTIONS, MCP_SERVER_DESCRIPTION } from '../src/mcp/instructions.ts';
import { __resetPrivateVisibilityCacheForTests, withCallerAccess } from '../src/core/search/private-visibility.ts';
import { addMember, bindCredential, disableMember, enableMember, setMemberEmail } from '../src/core/access/members.ts';
import { ACTOR_DEFERRED_OPS, attestedCallerAccess, linkMember, linkMemberByEmail, listMemberLinks, parseAttestOps, unlinkMember } from '../src/core/access/actor.ts';
import { readAudienceAssertions } from '../src/core/access/audience.ts';
import { operationsByName } from '../src/core/operations.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 { testBackends } from './helpers/test-backends.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { withEnv } from './helpers/with-env.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 = 'qm-team';
const PAGES = {
alice: { slug: 'notes/qm-alice', fm: ['readable_by: [alice-example]'], canary: 'canaryqmalice' },
bob: { slug: 'notes/qm-bob', fm: ['readable_by: [bob-example]'], canary: 'canaryqmbob' },
both: { slug: 'notes/qm-both', fm: ['readable_by: [alice-example, bob-example]'], canary: 'canaryqmboth' },
quiet: { slug: 'notes/qm-quiet', fm: ['visibility: private'], canary: 'canaryqmquiet' },
open: { slug: 'notes/qm-open', fm: [] as string[], canary: 'canaryqmopen' },
} as const;
type Key = keyof typeof PAGES;
const page = (key: Key) => ['---', 'type: note', 'title: ' + key + ' qm plan', ...PAGES[key].fm, '---', '# ' + key + ' qm plan', '',
'Harbor ledger qm notes ' + PAGES[key].canary + ' for the roadmap.'].join('\n');
const ALICE_ID = 'U0ALICE';
const BOB_ID = '[email protected]';
const OIDC_ID = 'oidc:3f2a9c:alice-example';
const LONG_ID = 'L'.repeat(256);
const ATTEST_OPS = ['get_page', 'list_pages', 'remember', 'search', 'whoami'];
for (const kind of testBackends()) {
describe('attested actor x-qm-actor (' + kind + ', repo-less)', () => {
let engine: BrainEngine;
let close: () => Promise<void>;
const provider = () => new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });
const clients: Record<string, { id: string; secret: string; token: string }> = {};
const tokens: Record<string, { id: string; token: string }> = {};
const verify = async (bearer: string) => await provider().verifyAccessToken(bearer) as unknown as AuthInfo;
const issue = async (name: string) => {
const c = clients[name]!;
c.token = (await provider().exchangeClientCredentials(c.id, c.secret)).access_token;
};
async function call(bearer: string | null, op: string, params: Record<string, unknown>, ch: { actor?: string; obo?: string; meta?: unknown } = {}) {
const auth = bearer ? await verify(bearer) : undefined;
const out: ToolResult = await dispatchToolCall(engine, op, { ...params }, {
remote: true, transport: bearer ? 'http' : 'stdio', auth, sourceId: SRC, takesHoldersAllowList: ['world'],
...(ch.actor !== undefined ? { actor: { header: ch.actor } } : {}),
onBehalfOf: { header: ch.obo, 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, first: out.content[0]?.text, json, meta: out._meta, structured: out.structuredContent as { error?: Record<string, unknown> } | undefined };
}
const qm = () => clients.qm!.token;
const getAs = (actor: string | undefined, key: Key, bearer = qm(), extra: Record<string, unknown> = {}) =>
call(bearer, 'get_page', { slug: PAGES[key].slug, ...extra }, actor === undefined ? {} : { actor });
async function refused(p: Promise<Awaited<ReturnType<typeof call>>>, code: string, reason?: string) {
const out = await p;
expect({ isError: out.isError, code: out.json.code, reason: out.json.reason }).toEqual({ isError: true, code, reason });
expect(out.structured?.error).toMatchObject({ code, ...(reason ? { reason } : {}) });
for (const key of Object.keys(PAGES) as Key[]) expect(out.text).not.toContain(PAGES[key].canary);
return out;
}
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']) await addMember(engine, id);
for (const key of Object.keys(PAGES) as Key[]) await importFromContent(engine, PAGES[key].slug, page(key), { sourceId: SRC });
const register = async (name: string, grantTypes = ['client_credentials']) => {
const c = await provider().registerClientManual('qm-' + name + '-' + randomUUID().slice(0, 8), grantTypes, 'read write', [], SRC);
clients[name] = { id: c.clientId, secret: c.clientSecret ?? '', token: '' };
return c.clientId;
};
// GST-363: these attest credentials' calls without x-qm-actor read unscoped on purpose on this several-member brain.
await bindCredential(engine, { kind: 'client', id: await register('qm') }, { attestActor: 'qm', attestOps: ATTEST_OPS, readsUnscoped: true });
await register('plain');
await bindCredential(engine, { kind: 'client', id: await register('defaults') }, { attestActor: 'qm' });
await register('code', ['authorization_code']);
await bindCredential(engine, { kind: 'client', id: await register('alice') }, { member: 'alice-example' });
await bindCredential(engine, { kind: 'client', id: await register('agent') }, { mayActFor: ['member:alice-example', 'member:bob-example'] });
for (const name of ['qm', 'plain', 'defaults', 'alice', 'agent']) await issue(name);
const aliceLegacy = await mintLegacyToken(engine, { name: 'qm-alice-legacy', scopes: ['read', 'write'], takesHolders: ['world'], sourceGrant: [SRC] });
tokens.aliceLegacy = { id: aliceLegacy.id, token: aliceLegacy.token };
await bindCredential(engine, { kind: 'token', id: aliceLegacy.id }, { member: 'alice-example' });
await engine.executeRaw("UPDATE oauth_clients SET private_pages = 'granted_sources' WHERE client_id = $1", [clients.qm!.id]);
const minted = await mintLegacyToken(engine, { name: 'qm-legacy', scopes: ['read', 'write'], takesHolders: ['world'], sourceGrant: [SRC] });
tokens.legacy = { id: minted.id, token: minted.token };
await bindCredential(engine, { kind: 'token', id: minted.id }, { attestActor: 'qm', attestOps: ATTEST_OPS, readsUnscoped: true });
await rescopeLegacyToken(engine, parseRescopeTokenArgs(['qm-legacy', '--private-pages', 'granted-sources']));
await linkMember(engine, 'alice-example', 'qm', ALICE_ID);
await linkMember(engine, 'alice-example', 'qm', OIDC_ID);
await linkMember(engine, 'alice-example', 'qm', LONG_ID);
await linkMember(engine, 'bob-example', 'qm', BOB_ID);
}, 240_000);
afterAll(async () => {
__setEmbedTransportForTests(null);
resetGateway();
await close?.();
}, 60_000);
test('an attested call reads as the linked member, reports it in _meta.access, and never echoes the id', async () => {
const out = await getAs(ALICE_ID, 'alice');
expect(out.isError).toBe(false);
expect(out.text).toContain(PAGES.alice.canary);
expect(out.meta?.access).toMatchObject({ member: 'alice-example', audience: ['member:alice-example'], actor: { system: 'qm' }, relaxation: 'none' });
expect(JSON.stringify(out.meta?.access)).not.toContain(ALICE_ID);
expect((await getAs(ALICE_ID, 'both')).text).toContain(PAGES.both.canary);
expect((await getAs(ALICE_ID, 'bob')).text).not.toContain(PAGES.bob.canary);
expect((await getAs(undefined, 'alice')).text).not.toContain(PAGES.alice.canary);
const legacy = await getAs(ALICE_ID, 'alice', tokens.legacy!.token);
expect(legacy.text).toContain(PAGES.alice.canary);
}, 120_000);
test('two linked members: each reads only their own readers pages through the same attest client', async () => {
const keyword = (actor: string) => call(qm(), 'search', { query: 'harbor ledger qm notes', match: 'keyword', fields: 'full', limit: 30 }, { actor });
const alice = (await keyword(ALICE_ID)).text;
const bob = (await keyword(BOB_ID)).text;
expect([alice.includes(PAGES.alice.canary), alice.includes(PAGES.bob.canary), alice.includes(PAGES.both.canary)]).toEqual([true, false, true]);
expect([bob.includes(PAGES.alice.canary), bob.includes(PAGES.bob.canary), bob.includes(PAGES.both.canary)]).toEqual([false, true, true]);
expect((await getAs(BOB_ID, 'alice')).text).not.toContain(PAGES.alice.canary);
const list = (await call(qm(), 'list_pages', { slug_prefix: 'notes/' }, { actor: BOB_ID })).text;
expect(list.includes(PAGES.alice.slug)).toBe(false);
expect(list.includes(PAGES.bob.slug)).toBe(true);
}, 120_000);
test('an attested call never reads a visibility: private page, even with granted_sources on the client and the operator hatch', async () => {
expect((await getAs(undefined, 'quiet')).text).toContain(PAGES.quiet.canary);
expect((await getAs(ALICE_ID, 'quiet')).text).not.toContain(PAGES.quiet.canary);
expect((await getAs(ALICE_ID, 'quiet', tokens.legacy!.token)).text).not.toContain(PAGES.quiet.canary);
await withEnv({ GBRAIN_REMOTE_PRIVATE_PAGES: '1' }, async () => {
__resetPrivateVisibilityCacheForTests();
try {
expect((await getAs(ALICE_ID, 'quiet')).text).not.toContain(PAGES.quiet.canary);
const search = await call(qm(), 'search', { query: 'harbor ledger qm notes', match: 'keyword', fields: 'full', limit: 30 }, { actor: ALICE_ID });
expect(search.text).not.toContain(PAGES.quiet.canary);
expect(search.text).toContain(PAGES.open.canary);
const list = await call(qm(), 'list_pages', { slug_prefix: 'notes/' }, { actor: ALICE_ID });
expect(list.text).not.toContain(PAGES.quiet.slug);
expect(search.meta?.access).toMatchObject({ relaxation: 'none' });
} finally {
__resetPrivateVisibilityCacheForTests();
}
});
}, 120_000);
test('acting_user equal to the header is accepted and stripped before the handler', async () => {
const out = await getAs(ALICE_ID, 'alice', qm(), { acting_user: ALICE_ID });
expect(out.isError).toBe(false);
expect(out.text).toContain(PAGES.alice.canary);
expect(out.text).not.toContain('acting_user');
expect(JSON.stringify(out.meta ?? {})).not.toContain('acting_user');
}, 60_000);
test('refusals: no right, op not attested, argument mismatch, argument without attestation, invalid id', async () => {
const noRight = await refused(getAs(ALICE_ID, 'alice', clients.plain!.token), 'actor_not_attested', 'no_attest_right');
expect((noRight.json.fix as { argv: string[] }).argv).toEqual(['gbrain', 'auth', 'rescope', '--client', clients.plain!.id, '--attest-actor', 'qm']);
expect((noRight.structured!.error!.fix as { argv: string[] }).argv).toEqual(['gbrain', 'auth', 'rescope', '--client', clients.plain!.id, '--attest-actor', 'qm']);
expect(noRight.json.docs).toContain('write-refusals.md#actor_not_attested');
const op = await refused(call(qm(), 'resolve_slugs', { partial: 'qm-alice' }, { actor: ALICE_ID }), 'actor_not_attested', 'op_not_attested');
expect((op.json.fix as { argv: string[] }).argv.slice(-2)).toEqual(['--attest-ops', [...ATTEST_OPS, 'resolve_slugs'].sort().join(',')]);
await refused(getAs(ALICE_ID, 'alice', clients.defaults!.token), 'actor_not_attested', 'op_not_attested');
await refused(getAs(ALICE_ID, 'alice', qm(), { acting_user: BOB_ID }), 'actor_not_attested', 'argument_mismatch');
await refused(getAs(ALICE_ID, 'alice', qm(), { acting_user: 'u0alice' }), 'actor_not_attested', 'argument_mismatch');
await refused(getAs(undefined, 'alice', qm(), { acting_user: ALICE_ID }), 'actor_not_attested', 'argument_without_attestation');
await refused(getAs(ALICE_ID, 'alice', clients.plain!.token, { acting_user: ALICE_ID }), 'actor_not_attested', 'argument_without_attestation');
await refused(call(null, 'get_page', { slug: PAGES.alice.slug, acting_user: ALICE_ID }), 'actor_not_attested', 'argument_without_attestation');
for (const bad of ['', 'U0 ALICE', 'U0ALICE\u0007', 'L'.repeat(257), 'caf\u00e9']) {
await refused(getAs(bad, 'alice'), 'actor_not_attested', 'invalid_actor_id');
}
await refused(getAs(ALICE_ID, 'alice', qm(), { acting_user: 'L'.repeat(257) }), 'actor_not_attested', 'invalid_actor_id');
await refused(getAs(ALICE_ID, 'alice', qm(), { acting_user: 7 }), 'actor_not_attested', 'invalid_actor_id');
}, 120_000);
test('HARN-1: on a member-bound credential, acting_user naming its own member runs exactly as the token; anyone else is argument_mismatch', async () => {
const canaries = (text: string) => (Object.keys(PAGES) as Key[]).filter(k => text.includes(PAGES[k].canary));
for (const bearer of [clients.alice!.token, tokens.aliceLegacy!.token]) {
expect((await getAs(undefined, 'alice', bearer)).text).toContain(PAGES.alice.canary);
for (const key of Object.keys(PAGES) as Key[]) {
const plain = await getAs(undefined, key, bearer);
for (const id of ['alice-example', ALICE_ID, OIDC_ID]) {
const named = await getAs(undefined, key, bearer, { acting_user: id });
expect({ isError: named.isError, first: named.first }).toEqual({ isError: plain.isError, first: plain.first });
expect(named.meta?.access).toEqual(plain.meta?.access);
expect(named.text).not.toContain('acting_user');
expect(JSON.stringify(named.meta?.warnings ?? [])).not.toContain('acting_user');
}
}
const search = (extra: Record<string, unknown>) => call(bearer, 'search', { query: 'harbor ledger qm notes', match: 'keyword', fields: 'full', limit: 30, ...extra });
const own = canaries((await search({})).text);
expect(own).toEqual(expect.arrayContaining(['alice', 'both', 'open']));
expect(own).not.toContain('bob');
expect(canaries((await search({ acting_user: 'alice-example' })).text)).toEqual(own);
expect(canaries((await search({ acting_user: ALICE_ID })).text)).toEqual(own);
for (const id of ['bob-example', BOB_ID, 'dan-example', 'nobody-example', 'U0NOBODY']) {
for (const key of ['bob', 'alice'] as Key[]) await refused(getAs(undefined, key, bearer, { acting_user: id }), 'actor_not_attested', 'argument_mismatch');
await refused(search({ acting_user: id }), 'actor_not_attested', 'argument_mismatch');
}
await refused(getAs(ALICE_ID, 'alice', bearer, { acting_user: ALICE_ID }), 'actor_not_attested', 'argument_without_attestation');
await refused(call(bearer, 'get_page', { slug: PAGES.alice.slug, acting_user: 'alice-example' }, { obo: 'alice-example' }), 'actor_not_attested', 'argument_without_attestation');
}
}, 120_000);
test('HARN-1: acting_user never widens a credential bound to no member: a may_act_for credential, a bare credential and stdio are refused', async () => {
for (const id of ['alice-example', ALICE_ID, 'bob-example']) {
for (const bearer of [clients.agent!.token, clients.plain!.token, null]) {
await refused(call(bearer, 'get_page', { slug: PAGES.alice.slug, acting_user: id }), 'actor_not_attested', 'argument_without_attestation');
}
}
}, 60_000);
test('the right follows the token\'s grant: an authorization-code token of an attest client is not attested', async () => {
const hash = createHash('sha256').update(qm()).digest('hex');
await engine.executeRaw("UPDATE oauth_tokens SET grant_type = 'authorization_code' WHERE token_hash = $1", [hash]);
try {
await refused(getAs(ALICE_ID, 'alice'), 'actor_not_attested', 'no_attest_right');
} finally {
await engine.executeRaw("UPDATE oauth_tokens SET grant_type = 'client_credentials' WHERE token_hash = $1", [hash]);
}
await engine.executeRaw('UPDATE oauth_tokens SET grant_type = NULL WHERE token_hash = $1', [hash]);
try {
const old = await refused(getAs(ALICE_ID, 'alice'), 'actor_not_attested', 'no_attest_right');
expect(old.json.message).toContain('holds the attest right');
expect(String(old.json.suggestion ?? old.json.next ?? old.text)).toContain('grant_type=client_credentials');
expect(old.structured!.error!.fix).toBeUndefined();
} finally {
await engine.executeRaw("UPDATE oauth_tokens SET grant_type = 'client_credentials' WHERE token_hash = $1", [hash]);
}
const plain = await refused(getAs(ALICE_ID, 'alice', clients.plain!.token), 'actor_not_attested', 'no_attest_right');
expect(plain.json.message).not.toContain('holds the attest right');
expect((await getAs(ALICE_ID, 'alice')).text).toContain(PAGES.alice.canary);
}, 60_000);
test('the header beside an on_behalf_of audience is refused as an invalid audience', async () => {
await refused(call(qm(), 'get_page', { slug: PAGES.alice.slug }, { actor: ALICE_ID, obo: 'alice-example' }), 'on_behalf_of_invalid_audience');
await refused(call(qm(), 'get_page', { slug: PAGES.alice.slug }, { actor: ALICE_ID, meta: ['alice-example'] }), 'on_behalf_of_invalid_audience');
}, 60_000);
test('links compare exactly: case, 256 characters and colons; unlink and disable apply on the next call', async () => {
expect((await getAs(OIDC_ID, 'alice')).text).toContain(PAGES.alice.canary);
expect((await getAs(LONG_ID, 'alice')).text).toContain(PAGES.alice.canary);
const unlinked = await refused(getAs('u0alice', 'alice'), 'actor_unlinked');
expect((unlinked.json.fix as { argv: string[] }).argv).toEqual(['gbrain', 'access', 'member', 'link', '<member>', '--qm', 'u0alice']);
expect(unlinked.json.docs).toContain('write-refusals.md#actor_unlinked');
await refused(getAs('L'.repeat(255), 'alice'), 'actor_unlinked');
await refused(getAs(OIDC_ID.toUpperCase(), 'alice'), 'actor_unlinked');
await unlinkMember(engine, 'qm', OIDC_ID);
try {
await refused(getAs(OIDC_ID, 'alice'), 'actor_unlinked');
} finally {
await linkMember(engine, 'alice-example', 'qm', OIDC_ID);
}
await disableMember(engine, 'bob-example');
try {
await refused(getAs(BOB_ID, 'both'), 'actor_unlinked');
} finally {
await enableMember(engine, 'bob-example');
}
expect((await getAs(BOB_ID, 'both')).text).toContain(PAGES.both.canary);
}, 120_000);
test('link commands refuse duplicates, invalid ids and members that are not enabled; previews write nothing', async () => {
await expect(linkMember(engine, 'bob-example', 'qm', ALICE_ID)).rejects.toMatchObject({ code: 'access_member_invalid', reason: 'link_exists' });
await expect(linkMember(engine, 'alice-example', 'qm', ALICE_ID)).rejects.toMatchObject({ code: 'access_member_invalid', reason: 'link_exists' });
for (const bad of ['', 'has space', 'L'.repeat(257), 'tab\there']) {
await expect(linkMember(engine, 'alice-example', 'qm', bad)).rejects.toMatchObject({ code: 'access_member_invalid', reason: 'invalid_external_id' });
}
await expect(linkMember(engine, 'ghost-example', 'qm', 'U0GHOST')).rejects.toMatchObject({ code: 'access_member_invalid', reason: 'unknown' });
await disableMember(engine, 'dan-example');
try {
await expect(linkMember(engine, 'dan-example', 'qm', 'U0DAN')).rejects.toMatchObject({ code: 'access_member_invalid', reason: 'disabled' });
} finally {
await enableMember(engine, 'dan-example');
}
const preview = await linkMember(engine, 'dan-example', 'qm', 'U0DAN', { dryRun: true });
expect(preview.applied).toBe(false);
expect((await listMemberLinks(engine, { member: 'dan-example' })).length).toBe(0);
await expect(unlinkMember(engine, 'qm', 'U0DAN')).rejects.toMatchObject({ reason: 'unknown_link' });
for (const bad of ['L'.repeat(257), 'has space', 'bell\u0007', 'caf\u00e9', '']) {
await expect(engine.executeRaw("INSERT INTO access_member_links (system, external_id, member_id) VALUES ('qm', $1, 'dan-example')", [bad])).rejects.toThrow();
}
expect((await listMemberLinks(engine, { member: 'alice-example' })).map(l => l.external_id).sort()).toEqual([ALICE_ID, LONG_ID, OIDC_ID].sort());
}, 60_000);
test('GST-1158: link by declared email links exactly as link by member id; it never creates a member or picks among several', async () => {
await setMemberEmail(engine, 'dan-example', '[email protected]');
try {
const preview = await linkMemberByEmail(engine, '[email protected]', 'qm', 'U0DAN-EMAIL', { dryRun: true });
expect(preview).toEqual({ applied: false, link: { system: 'qm', external_id: 'U0DAN-EMAIL', member_id: 'dan-example', created_at: null } });
expect(await listMemberLinks(engine, { member: 'dan-example' })).toEqual([]);
expect(await linkMemberByEmail(engine, '[email protected]', 'qm', 'U0DAN-EMAIL')).toMatchObject({ applied: true, link: { system: 'qm', external_id: 'U0DAN-EMAIL', member_id: 'dan-example' } });
await expect(linkMemberByEmail(engine, '[email protected]', 'qm', 'U0DAN-EMAIL')).rejects.toMatchObject({ code: 'access_member_invalid', reason: 'link_exists' });
await expect(linkMemberByEmail(engine, '[email protected]', 'qm', ALICE_ID)).rejects.toMatchObject({ code: 'access_member_invalid', reason: 'link_exists' });
await expect(linkMemberByEmail(engine, '[email protected]', 'qm', 'has space')).rejects.toMatchObject({ code: 'access_member_invalid', reason: 'invalid_external_id' });
const count = async () => (await engine.executeRaw<{ n: number }>('SELECT count(*)::int AS n FROM access_members'))[0]!.n;
const members = await count();
await expect(linkMemberByEmail(engine, '[email protected]', 'qm', 'U0NOBODY')).rejects.toMatchObject({ code: 'not_found' });
expect(await count()).toBe(members);
expect(await engine.executeRaw("SELECT 1 FROM access_member_links WHERE external_id = 'U0NOBODY'")).toEqual([]);
await disableMember(engine, 'dan-example');
try {
await expect(linkMemberByEmail(engine, '[email protected]', 'qm', 'U0DAN-2')).rejects.toMatchObject({ code: 'access_member_invalid', reason: 'disabled' });
} finally {
await enableMember(engine, 'dan-example');
}
const rollback = new Error('rollback');
await expect(engine.transaction(async tx => {
await tx.executeRaw('DROP INDEX access_members_email_key');
await tx.executeRaw("UPDATE access_members SET email = '[email protected]' WHERE id = 'bob-example'");
await expect(linkMemberByEmail(tx, '[email protected]', 'qm', 'U0AMBIG')).rejects.toMatchObject({ code: 'access_member_invalid', reason: 'email_ambiguous' });
expect(await tx.executeRaw("SELECT 1 FROM access_member_links WHERE external_id = 'U0AMBIG'")).toEqual([]);
throw rollback;
})).rejects.toBe(rollback);
expect((await engine.executeRaw<{ email: string | null }>("SELECT email FROM access_members WHERE id = 'bob-example'"))[0]!.email).toBeNull();
await expect(engine.executeRaw("UPDATE access_members SET email = '[email protected]' WHERE id = 'bob-example'")).rejects.toThrow();
} finally {
await unlinkMember(engine, 'qm', 'U0DAN-EMAIL').catch(() => undefined);
await setMemberEmail(engine, 'dan-example', null);
}
}, 60_000);
test('the attest right is granted only to a member-less client-credentials client or legacy token, for attestable ops', async () => {
await expect(bindCredential(engine, { kind: 'client', id: clients.code!.id }, { attestActor: 'qm' })).rejects.toMatchObject({ code: 'invalid_params' });
await expect(bindCredential(engine, { kind: 'client', id: clients.qm!.id }, { member: 'dan-example' })).rejects.toMatchObject({ code: 'invalid_params' });
await expect(bindCredential(engine, { kind: 'client', id: clients.plain!.id }, { attestOps: ['get_page'] })).rejects.toMatchObject({ code: 'invalid_params' });
const minted = await mintLegacyToken(engine, { name: 'qm-bound', scopes: ['read'], takesHolders: ['world'], sourceGrant: [SRC] });
await bindCredential(engine, { kind: 'token', id: minted.id }, { member: 'dan-example' });
await expect(bindCredential(engine, { kind: 'token', id: minted.id }, { attestActor: 'qm' })).rejects.toMatchObject({ code: 'invalid_params' });
const lookup = (name: string) => operationsByName[name];
for (const op of ['get_stats', 'run_doctor', 'sync_brain', 'file_upload', 'purge_fact', 'no_such_op']) expect(() => parseAttestOps(op, lookup)).toThrow();
expect(parseAttestOps('memory_write,get_page,memory_recall', lookup)).toEqual(['get_page', 'memory_recall', 'memory_write']);
const cleared = await bindCredential(engine, { kind: 'client', id: clients.defaults!.id }, { attestActor: null }, { dryRun: true });
expect(cleared.attest_actor).toBeUndefined();
}, 60_000);
test('a pending attested write publishes as the member and is refused after unlink, relink to another member, or disable', async () => {
const auth = await verify(qm());
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 actor = { system: 'qm', external_id: ALICE_ID, member: 'alice-example' };
const authority = await withCallerAccess(await attestedCallerAccess(engine, actor, ['member:alice-example']),
() => submissionAuthority(ctx, 'remember', SRC, source!.incarnation, PAGES.alice.slug));
expect({ actingFor: authority.actingFor, excludePrivate: authority.excludePrivate }).toEqual({ actingFor: actor, excludePrivate: true });
const row = await admitWrite(engine, { principal: authority.principal, authority, operation: 'remember', sourceId: SRC,
sourceIncarnation: source!.incarnation, slug: PAGES.alice.slug, requestId: randomUUID(), callerIntent: {}, intent: {} });
await authorizeStoredRequest(engine, row);
// GST-2249 W1: an attested page write is refused at admission, and one queued before the boundary widened fails when re-resolved.
await expect(admitWrite(engine, { principal: authority.principal, authority, operation: 'add_tag', sourceId: SRC,
sourceIncarnation: source!.incarnation, slug: PAGES.alice.slug, requestId: randomUUID(), callerIntent: {}, intent: {} })).rejects.toMatchObject({ code: 'actor_not_attested', reason: 'op_not_attested' });
await expect(authorizeStoredRequest(engine, { ...row, operation: 'add_tag' })).rejects.toMatchObject({ code: 'actor_not_attested', reason: 'op_not_attested' });
await unlinkMember(engine, 'qm', ALICE_ID);
try {
await expect(authorizeStoredRequest(engine, row)).rejects.toMatchObject({ code: 'actor_unlinked' });
await linkMember(engine, 'bob-example', 'qm', ALICE_ID);
await expect(authorizeStoredRequest(engine, row)).rejects.toMatchObject({ code: 'actor_unlinked' });
await unlinkMember(engine, 'qm', ALICE_ID);
} finally {
await linkMember(engine, 'alice-example', 'qm', ALICE_ID);
}
await authorizeStoredRequest(engine, row);
await disableMember(engine, 'alice-example');
try {
await expect(authorizeStoredRequest(engine, row)).rejects.toMatchObject({ code: 'actor_unlinked' });
} finally {
await enableMember(engine, 'alice-example');
}
await bindCredential(engine, { kind: 'client', id: clients.qm!.id }, { attestActor: null });
try {
await expect(authorizeStoredRequest(engine, row)).rejects.toMatchObject({ code: 'actor_not_attested' });
} finally {
await bindCredential(engine, { kind: 'client', id: clients.qm!.id }, { attestActor: 'qm', attestOps: ATTEST_OPS });
}
await bindCredential(engine, { kind: 'client', id: clients.qm!.id }, { attestActor: 'qm', attestOps: ATTEST_OPS.filter(op => op !== 'remember') });
try {
await expect(authorizeStoredRequest(engine, row)).rejects.toMatchObject({ code: 'actor_not_attested', reason: 'op_not_attested' });
} finally {
await bindCredential(engine, { kind: 'client', id: clients.qm!.id }, { attestActor: 'qm', attestOps: ATTEST_OPS });
}
await authorizeStoredRequest(engine, row);
const live = await call(qm(), 'remember', { fact: 'Alice keeps the harbor key', provenance: 'qm test' }, { actor: ALICE_ID });
expect([live.isError, live.json.page]).toEqual([false, 'memory/members/alice-example']);
await refused(call(qm(), 'add_tag', { slug: PAGES.alice.slug, tag: 'qm-tag' }, { actor: ALICE_ID }), 'actor_not_attested', 'op_not_attested');
}, 120_000);
test('an agent job submitted for an attested actor reads as the member until the link is gone', async () => {
const { clientId } = await provider().registerClientManual('qm-agent-' + randomUUID().slice(0, 8), ['client_credentials'], 'read', [], SRC);
await bindCredential(engine, { kind: 'client', id: clientId }, { attestActor: 'qm', attestOps: ['get_page'] });
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 actor = { system: 'qm', external_id: BOB_ID, member: 'bob-example' };
const agentAuth = { token: 'x', clientId, scopes: ['read', 'agent'], sourceId: SRC, principal: { kind: 'oauth_client', id: clientId } } as unknown as AuthInfo;
const submitted = await withCallerAccess(await attestedCallerAccess(engine, actor, ['member:bob-example']),
() => prepareRemoteAgent({ engine, auth: agentAuth, remote: true } as unknown as OperationContext, { source_id: SRC, allowed_tools: ['get_page'], allowed_slug_prefixes: [] }));
expect({ actor: submitted.grant.actor, actingFor: submitted.grant.actingFor }).toEqual({ actor, actingFor: undefined });
const tools = buildBrainTools({ subagentId: 11, 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 authority: RemoteAgentAuthority = { ...submitted, payloadHash: '0'.repeat(64) };
expect(parseSubmissionAuthority(authority)).not.toBeNull();
const read = async (slug: string) => {
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.bob.slug)).toContain(PAGES.bob.canary);
expect(await read(PAGES.alice.slug)).not.toContain(PAGES.alice.canary);
await unlinkMember(engine, 'qm', BOB_ID);
try {
const after = await read(PAGES.bob.slug);
expect(after).not.toContain(PAGES.bob.canary);
expect(after).toContain('not linked');
} finally {
await linkMember(engine, 'bob-example', 'qm', BOB_ID);
}
await bindCredential(engine, { kind: 'client', id: clientId }, { attestActor: 'qm', attestOps: ['search'] });
try {
const removed = await read(PAGES.bob.slug);
expect(removed).not.toContain(PAGES.bob.canary);
expect(removed).toContain('get_page is not in this connection');
} finally {
await bindCredential(engine, { kind: 'client', id: clientId }, { attestActor: 'qm', attestOps: ['get_page'] });
}
expect(await read(PAGES.bob.slug)).toContain(PAGES.bob.canary);
const bad = (grant: Record<string, unknown>) => parseSubmissionAuthority({ ...authority, grant: { ...authority.grant, ...grant } });
expect(bad({ actor: { ...actor, external_id: 'has space' } })).toBeNull();
expect(bad({ actingFor: ['member:bob-example'] })).toBeNull();
}, 120_000);
test('operations not keyed to the person yet are never attested: refused at rescope, at bind and at every call', async () => {
const lookup = (name: string) => operationsByName[name];
for (const op of ACTOR_DEFERRED_OPS) {
expect(() => parseAttestOps('get_page,' + op, lookup)).toThrow(/cannot run yet/);
await expect(bindCredential(engine, { kind: 'client', id: clients.qm!.id }, { attestActor: 'qm', attestOps: ['get_page', op] })).rejects.toMatchObject({ code: 'invalid_params' });
}
// GST-359 C2 keyed remember, delta, the write receipts and agent jobs to the person (test/access-member-facts.test.ts);
// D keyed forget and forget_fact to the person's own member page (test/qm-memory-tools.test.ts).
for (const op of ['capture', 'extract_facts', 'takes_add', 'list_write_conflicts', 'add_timeline_entry', 'add_link', 'put_page', 'edit_page', 'delete_page', 'add_tag', 'append_page']) {
expect(ACTOR_DEFERRED_OPS.has(op)).toBe(true);
}
for (const op of ['get_agent_job', 'submit_agent', 'get_write_request', 'list_write_requests', 'cancel_write_request', 'delta', 'remember', 'forget', 'forget_fact']) {
expect(ACTOR_DEFERRED_OPS.has(op)).toBe(false);
}
const { clientId, clientSecret } = await provider().registerClientManual('qm-jobs-' + randomUUID().slice(0, 8), ['client_credentials'], 'read write', [], SRC);
await engine.executeRaw("UPDATE oauth_clients SET scope = 'read write agent', bound_tools = $2, 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, ['get_page', ...ACTOR_DEFERRED_OPS]]);
await bindCredential(engine, { kind: 'client', id: clientId }, { attestActor: 'qm', attestOps: ['get_page'] });
await engine.executeRaw('UPDATE oauth_clients SET attest_ops = $2 WHERE client_id = $1', [clientId, ['get_page', ...ACTOR_DEFERRED_OPS]]);
const bearer = (await provider().exchangeClientCredentials(clientId, clientSecret!)).access_token;
const deferredCalls: Array<[string, Record<string, unknown>]> = [
['list_write_conflicts', {}], ['capture', { content: 'note' }], ['extract_facts', { text: 'x' }],
['takes_add', { page_slug: PAGES.alice.slug, claim: 'x' }], ['takes_update', { page_slug: PAGES.alice.slug, row: 1, weight: 0.5 }],
['takes_resolve', { page_slug: PAGES.alice.slug, row: 1, quality: 'correct' }], ['takes_supersede', { page_slug: PAGES.alice.slug, row: 1, claim: 'y' }],
// GST-1158 F9: direct page writes wait for owner-approved proposals.
['add_timeline_entry', { slug: PAGES.alice.slug, date: '2026-11-03', summary: 'x' }], ['add_link', { from: PAGES.alice.slug, to: PAGES.bob.slug }],
['put_page', { slug: PAGES.alice.slug, content: '# x\n' }], ['edit_page', { slug: PAGES.alice.slug, expected_revision: '00000000-0000-0000-0000-000000000000', edits: [{ old_text: 'a', new_text: 'b' }] }],
// GST-2249 W1: every other page write waits for owner approval too.
['append_page', { slug: PAGES.alice.slug, content: 'x' }], ['put_pages', { pages: [{ slug: PAGES.alice.slug, content: '# x\n' }] }],
['delete_page', { slug: PAGES.alice.slug }], ['restore_page', { slug: PAGES.alice.slug }],
['revert_version', { slug: PAGES.alice.slug, version_id: 1 }],
['add_tag', { slug: PAGES.alice.slug, tag: 'x' }], ['remove_tag', { slug: PAGES.alice.slug, tag: 'x' }],
['remove_link', { from: PAGES.alice.slug, to: PAGES.bob.slug }],
['begin_page_upload', { slug: PAGES.alice.slug, total_bytes: 1 }], ['upload_page_part', { upload_id: 'x', part: 1, content: 'x' }],
['commit_page_upload', { upload_id: 'x' }], ['abort_page_upload', { upload_id: 'x' }],
['put_raw_data', { slug: PAGES.alice.slug, source: 'crm-example', data: {} }],
['extract_entities', { text: 'Alice met Bob.' }], ['ontology_propose', { subject: PAGES.alice.slug, fact: 'x' }],
['confirm_memory', { ref: 'p:' + SRC + '/' + PAGES.alice.slug }], ['promote_guest_note', { slug: PAGES.alice.slug }], ['loops_close', { id: 1 }],
['questions_pin', { question: 'x?' }], ['questions_refresh', { id: 1 }], ['questions_unpin', { id: 1 }],
// Shared rows with no page: answer feedback, the ingest log and loop suppression.
['rate_answer', { answer_id: 'x', rating: 'up' }], ['log_ingest', { source_type: 'note', source_ref: 'x', pages_updated: [], summary: 'x' }],
['loops_mute', { sender: '[email protected]' }], ['loops_unmute', { sender: '[email protected]' }],
];
expect(new Set(deferredCalls.map(([op]) => op))).toEqual(new Set(ACTOR_DEFERRED_OPS));
for (const [op, params] of deferredCalls) {
const out = await refused(call(bearer, op, params, { actor: ALICE_ID }), 'actor_not_attested', 'op_not_attested');
expect(out.structured!.error!.fix).toBeUndefined();
}
expect((await call(bearer, 'get_page', { slug: PAGES.alice.slug }, { actor: ALICE_ID })).text).toContain(PAGES.alice.canary);
}, 120_000);
test('the legacy bearer transport reads x-qm-actor over a real socket and serves the description on initialize', 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>, body: Record<string, unknown>) => {
const res = await fetch('http://127.0.0.1:' + server.port + '/mcp', {
method: 'POST', headers: { authorization: 'Bearer ' + tokens.legacy!.token, 'content-type': 'application/json', ...headers },
body: JSON.stringify({ jsonrpc: '2.0', id: 1, ...body }),
});
return await res.json() as { result: Record<string, unknown> };
};
const tool = (headers: Record<string, string>, args: Record<string, unknown> = {}) => post(headers, { method: 'tools/call', params: { name: 'get_page', arguments: { slug: PAGES.alice.slug, ...args } } });
expect(JSON.stringify(await tool({ 'x-qm-actor': ALICE_ID }))).toContain(PAGES.alice.canary);
expect(JSON.stringify(await tool({}))).not.toContain(PAGES.alice.canary);
const mismatch = await tool({ 'X-QM-Actor': ALICE_ID }, { acting_user: BOB_ID });
expect((mismatch.result.structuredContent as { error: { code: string; reason: string } }).error).toMatchObject({ code: 'actor_not_attested', reason: 'argument_mismatch' });
const init = await post({ 'x-qm-actor': ALICE_ID }, { method: 'initialize', params: { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 't', version: '1' } } });
expect((init.result.serverInfo as { description: string }).description).toBe(MCP_SERVER_DESCRIPTION);
} finally {
server.stop(true);
}
}, 60_000);
test('each actor assertion is appended to the audit trail with outcome and reason, never page content', async () => {
const before = readAudienceAssertions().length;
await getAs(ALICE_ID, 'alice');
await getAs(ALICE_ID, 'alice', clients.plain!.token);
await getAs('u0alice', 'alice');
const added = readAudienceAssertions().slice(before);
expect(added.map(e => ({ outcome: e.outcome, audience: e.audience, actor: e.actor }))).toEqual([
{ outcome: 'accepted', audience: ['member:alice-example'], actor: { system: 'qm', external_id: ALICE_ID } },
{ outcome: 'actor_not_attested', audience: [], actor: { system: 'qm', external_id: ALICE_ID, reason: 'no_attest_right' } },
{ outcome: 'actor_unlinked', audience: [], actor: { system: 'qm', external_id: 'u0alice' } },
]);
expect(JSON.stringify(added)).not.toContain(PAGES.alice.canary);
}, 60_000);
});
}
describe('serverInfo.description (GST-359 item 6)', () => {
test('fits 120 characters, carries the brain-first rule, and leaves instructions byte-identical', () => {
expect(MCP_SERVER_DESCRIPTION.length).toBeLessThanOrEqual(120);
expect(MCP_SERVER_DESCRIPTION).toContain('gbrain');
expect(MCP_SERVER_DESCRIPTION).toContain('remember');
// GBRA-219 (#7795): the memory_conversation_mode switch clause is the only change to the instructions since this pin.
expect(createHash('sha256').update(GBRAIN_MCP_INSTRUCTIONS).digest('hex')).toBe('5164ac196ce534a6fd981895b8566fa85c7c1567025096f47ba19678f934bf65');
});
});