Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

D: acting_user on a may_act_for credential reads the narrow-only intersection (HARN-1 option b)

garrytan377177b78a39
diff --git a/docs/contracts/qm-memory-provider/v1.json b/docs/contracts/qm-memory-provider/v1.json
index 3ef5010a9e..d33ab86c4c 100644
--- a/docs/contracts/qm-memory-provider/v1.json
+++ b/docs/contracts/qm-memory-provider/v1.json
@@ -11,7 +11,7 @@
"actor": {
"header": "x-qm-actor",
"argument": "acting_user",
- "argument_rule": "optional; on an attested call it must equal the header; with no header it is accepted only from a credential bound to a member and only naming that member (its member id or a canonical id linked to it), and the call then runs exactly as the credential; never chooses the person on its own",
+ "argument_rule": "optional; on an attested call it must equal the header; with no header it is accepted only from a credential bound to a member and only naming that member (its member id or a canonical id linked to it), and the call then runs exactly as the credential, or from a credential bound to no member naming a member its may_act_for lists, and the call then reads only what both the credential and that member may read, never a visibility: private page; never widens what the credential reads",
"actor_id": {
"pattern": "^[\\x21-\\x7e]{1,256}$",
"case_folding": false
@@ -251,7 +251,7 @@
{
"code": "actor_not_attested",
"class": "host_only",
- "summary": "A call named the person it serves (the x-qm-actor header or the acting_user argument) in a way gbrain does not honour: the credential holds no attest right, the operation is not in its attested operations, the argument differs from the header, names anyone but a member-bound credential's own member, or comes without an attested header from a credential bound to no member, or the id is not 1-256 visible ASCII characters; or a write that saves only as an attested person (memory_write) named none; or the request carries x-qm-audience, a channel audience gbrain does not serve yet. Nothing was read or written.",
+ "summary": "A call named the person it serves (the x-qm-actor header or the acting_user argument) in a way gbrain does not honour: the credential holds no attest right, the operation is not in its attested operations, the argument differs from the header, names anyone but a member-bound credential's own member or a member a may_act_for credential covers, or comes without an attested header from a credential bound to no member and listing no may_act_for, or the id is not 1-256 visible ASCII characters; or a write that saves only as an attested person (memory_write) named none; or the request carries x-qm-audience, a channel audience gbrain does not serve yet. Nothing was read or written.",
"suggestion": "Read reason: no_attest_right and op_not_attested are the brain operator's call (gbrain auth rescope --client <id> --attest-actor qm [--attest-ops <list>]); argument_mismatch, argument_without_attestation, invalid_actor_id, actor_required and audience_not_supported are fixed in the calling harness.",
"docs": "docs/guides/write-refusals.md#actor_not_attested",
"reasons": [
@@ -268,12 +268,12 @@
{
"reason": "argument_mismatch",
"fixed_by": "calling_harness",
- "fix": "Send acting_user equal to the x-qm-actor header (with no header, on a credential bound to a member: that member id or a canonical id linked to it), or omit it."
+ "fix": "Send acting_user equal to the x-qm-actor header (with no header: on a credential bound to a member, that member id or a canonical id linked to it; on a may_act_for credential, a member it lists), or omit it. One message covers every id a may_act_for credential may not name, existing or not."
},
{
"reason": "argument_without_attestation",
"fixed_by": "calling_harness",
- "fix": "Remove acting_user, or send the x-qm-actor header from a credential holding the attest right; a credential bound to no member never sends acting_user alone."
+ "fix": "Remove acting_user, or send the x-qm-actor header from a credential holding the attest right; a credential bound to no member and listing no may_act_for never sends acting_user alone."
},
{
"reason": "invalid_actor_id",
diff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.md
index d3e71c3211..4d1a055c7e 100644
--- a/docs/guides/error-codes.md
+++ b/docs/guides/error-codes.md
@@ -165,7 +165,7 @@ More: [docs/guides/write-refusals.md#access_rule_invalid](../../docs/guides/writ
| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |
|---|---|---|---|---|---|---|
-| A call named the person it serves (the x-qm-actor header or the acting_user argument) in a way gbrain does not honour: the credential holds no attest right, the operation is not in its attested operations, the argument differs from the header, names anyone but a member-bound credential's own member, or comes without an attested header from a credential bound to no member, or the id is not 1-256 visible ASCII characters; or a write that saves only as an attested person (memory_write) named none; or the request carries x-qm-audience, a channel audience gbrain does not serve yet. Nothing was read or written. | Naming a person decides whose notes are read and written as; only a credential the brain operator granted the attest right may do it, only for the operations it lists, and text in a conversation never chooses it. | Read reason: no_attest_right and op_not_attested are the brain operator's call (gbrain auth rescope --client <id> --attest-actor qm [--attest-ops <list>]); argument_mismatch, argument_without_attestation, invalid_actor_id, actor_required and audience_not_supported are fixed in the calling harness. | user | `gbrain doctor --json` | 1 | no |
+| A call named the person it serves (the x-qm-actor header or the acting_user argument) in a way gbrain does not honour: the credential holds no attest right, the operation is not in its attested operations, the argument differs from the header, names anyone but a member-bound credential's own member or a member a may_act_for credential covers, or comes without an attested header from a credential bound to no member and listing no may_act_for, or the id is not 1-256 visible ASCII characters; or a write that saves only as an attested person (memory_write) named none; or the request carries x-qm-audience, a channel audience gbrain does not serve yet. Nothing was read or written. | Naming a person decides whose notes are read and written as; only a credential the brain operator granted the attest right may do it, only for the operations it lists, and text in a conversation never chooses it. | Read reason: no_attest_right and op_not_attested are the brain operator's call (gbrain auth rescope --client <id> --attest-actor qm [--attest-ops <list>]); argument_mismatch, argument_without_attestation, invalid_actor_id, actor_required and audience_not_supported are fixed in the calling harness. | user | `gbrain doctor --json` | 1 | no |
Reasons: `no_attest_right`, `op_not_attested`, `argument_mismatch`, `argument_without_attestation`, `invalid_actor_id`, `actor_required`, `audience_not_supported`.
diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.md
index 4c523a4f75..e6b2378b03 100644
--- a/docs/guides/write-refusals.md
+++ b/docs/guides/write-refusals.md
@@ -984,7 +984,7 @@ Links and the right live in the database, so they are the same on a repo-less br
| Code | What happened | What to do |
|---|---|---|
-| <a id="actor_not_attested"></a>`actor_not_attested` | The call named a person in a way gbrain does not honour. `reason` says which: `no_attest_right` (the credential holds no attest right, or the token of an attest client was issued before the upgrade or by another grant: the message then says to take a new client-credentials token), `op_not_attested` (the operation is not in the credential's attested operations, or is not attestable yet: `list_write_conflicts`, `capture`, `extract_facts` and `takes_add|update|resolve|supersede`; also when a queued write or agent job tool call runs after its operation was removed from the list), `argument_mismatch` (the `acting_user` argument differs from the header, or, with no header on a credential bound to a member, names anyone but that member; its own member id or a canonical id linked to it is dropped and the call runs exactly as the credential), `argument_without_attestation` (`acting_user` came without an attested header from a credential bound to no member, over stdio, or beside an `on_behalf_of` audience), `invalid_actor_id` (the header or argument is not 1-256 visible ASCII characters), `actor_required` (`memory_write` named no attested person) or `audience_not_supported` (the request carries `x-qm-audience`, QM's channel audience, which is refused on every call until wave 2). Nothing was read or written. | `no_attest_right` and `op_not_attested` are the brain operator's call: `fix` carries `gbrain auth rescope --client <id> --attest-actor qm [--attest-ops <list>]`. The other five are fixed in the calling harness: send the canonical id unchanged in the header from the attest credential, the same value or nothing in `acting_user` (on a member-bound credential with no header: its own member id, a canonical id linked to it, or nothing), and no `x-qm-audience`. |
+| <a id="actor_not_attested"></a>`actor_not_attested` | The call named a person in a way gbrain does not honour. `reason` says which: `no_attest_right` (the credential holds no attest right, or the token of an attest client was issued before the upgrade or by another grant: the message then says to take a new client-credentials token), `op_not_attested` (the operation is not in the credential's attested operations, or is not attestable yet: `list_write_conflicts`, `capture`, `extract_facts` and `takes_add|update|resolve|supersede`; also when a queued write or agent job tool call runs after its operation was removed from the list), `argument_mismatch` (the `acting_user` argument differs from the header, or, with no header on a credential bound to a member, names anyone but that member; its own member id or a canonical id linked to it is dropped and the call runs exactly as the credential; or, on a credential bound to no member that lists `may_act_for`, names no member it covers, with one message whether or not the id exists; a covered member, by id or linked canonical id, is read as the intersection of what the credential and that member may read, never a `visibility: private` page), `argument_without_attestation` (`acting_user` came without an attested header from a credential bound to no member and listing no `may_act_for`, over stdio, or beside an `on_behalf_of` audience), `invalid_actor_id` (the header or argument is not 1-256 visible ASCII characters), `actor_required` (`memory_write` named no attested person) or `audience_not_supported` (the request carries `x-qm-audience`, QM's channel audience, which is refused on every call until wave 2). Nothing was read or written. | `no_attest_right` and `op_not_attested` are the brain operator's call: `fix` carries `gbrain auth rescope --client <id> --attest-actor qm [--attest-ops <list>]`. The other five are fixed in the calling harness: send the canonical id unchanged in the header from the attest credential, the same value or nothing in `acting_user` (with no header: on a member-bound credential its own member id or a canonical id linked to it, on a may_act_for credential a member it lists, or nothing), and no `x-qm-audience`. |
| <a id="actor_unlinked"></a>`actor_unlinked` | The id is not linked to an enabled member: never linked, unlinked, or the member is disabled or removed. Ids compare exactly, with no case folding. Nothing was read or written. A queued write or agent job made for the person is refused the same way when its link is gone or now names another member. `memory_recall` answers it as an empty success instead (`structuredContent: {facts: [], truncated: false, code: "actor_unlinked"}`), so a person not yet linked reads nothing. | The brain operator links it: `gbrain access member link <member> --qm <id>` (or `gbrain access member enable <member>`). |
## Related
diff --git a/scripts/build-qm-memory-contract.ts b/scripts/build-qm-memory-contract.ts
index 725917fe04..be084cb4f0 100644
--- a/scripts/build-qm-memory-contract.ts
+++ b/scripts/build-qm-memory-contract.ts
@@ -20,8 +20,8 @@ export const QM_CONTRACT_PATH = join(import.meta.dir, '..', 'docs', 'contracts',
export const ACTOR_REASON_FIXES: Record<string, { fixed_by: 'brain_operator' | 'calling_harness'; fix: string }> = {
no_attest_right: { fixed_by: 'brain_operator', fix: 'gbrain auth rescope --client <id> --attest-actor qm on the brain host; a client that already holds the right takes a new token with grant_type=client_credentials.' },
op_not_attested: { fixed_by: 'brain_operator', fix: 'gbrain auth rescope --client <id> --attest-actor qm --attest-ops <list>; a deferred operation cannot be attested yet.' },
- argument_mismatch: { fixed_by: 'calling_harness', fix: 'Send acting_user equal to the x-qm-actor header (with no header, on a credential bound to a member: that member id or a canonical id linked to it), or omit it.' },
- argument_without_attestation: { fixed_by: 'calling_harness', fix: 'Remove acting_user, or send the x-qm-actor header from a credential holding the attest right; a credential bound to no member never sends acting_user alone.' },
+ argument_mismatch: { fixed_by: 'calling_harness', fix: 'Send acting_user equal to the x-qm-actor header (with no header: on a credential bound to a member, that member id or a canonical id linked to it; on a may_act_for credential, a member it lists), or omit it. One message covers every id a may_act_for credential may not name, existing or not.' },
+ argument_without_attestation: { fixed_by: 'calling_harness', fix: 'Remove acting_user, or send the x-qm-actor header from a credential holding the attest right; a credential bound to no member and listing no may_act_for never sends acting_user alone.' },
invalid_actor_id: { fixed_by: 'calling_harness', fix: 'Send the canonical id unchanged: 1-256 visible ASCII characters, no spaces.' },
actor_required: { fixed_by: 'calling_harness', fix: 'memory_write saves only as an attested person: send x-qm-actor from a credential holding the attest right.' },
audience_not_supported: { fixed_by: 'calling_harness', fix: 'Send the call without x-qm-audience; channel turns are refused until wave 2 and nothing is read or written.' },
@@ -58,7 +58,7 @@ export function buildQmMemoryContract(): Record<string, unknown> {
transport: { protocol: 'mcp', session: 'stateless', session_header_issued: false, success_codes_in: 'structuredContent',
unknown_arguments: 'an argument a read tool does not declare is ignored and reported only in _meta.warnings ([{code: "unknown_param", param, suggestion?}]), never in content; a write tool refuses it with invalid_params' },
actor: {
- header: ACTOR_HEADER, argument: ACTOR_ARGUMENT, argument_rule: 'optional; on an attested call it must equal the header; with no header it is accepted only from a credential bound to a member and only naming that member (its member id or a canonical id linked to it), and the call then runs exactly as the credential; never chooses the person on its own',
+ header: ACTOR_HEADER, argument: ACTOR_ARGUMENT, argument_rule: 'optional; on an attested call it must equal the header; with no header it is accepted only from a credential bound to a member and only naming that member (its member id or a canonical id linked to it), and the call then runs exactly as the credential, or from a credential bound to no member naming a member its may_act_for lists, and the call then reads only what both the credential and that member may read, never a visibility: private page; never widens what the credential reads',
actor_id: { pattern: EXTERNAL_ID_RE.source, case_folding: false },
system: 'qm', default_attest_ops: [...DEFAULT_ATTEST_OPS], deferred_ops: [...ACTOR_DEFERRED_OPS].sort(),
audit: 'the audit trail and stored writes record the canonical external id as sent, with its linked member',
diff --git a/src/core/access/actor.ts b/src/core/access/actor.ts
index 2eb5889db6..43f1624c28 100644
--- a/src/core/access/actor.ts
+++ b/src/core/access/actor.ts
@@ -20,7 +20,8 @@ import type { CallerAccess } from '../search/private-visibility.ts';
import { identityFor } from './principals.ts';
import { isUndefinedColumnError, isUndefinedTableError } from '../utils.ts';
import { memberIdentity } from './members.ts';
-import { folderAccessFor, memberIdentityFor } from './caller.ts';
+import { enabledMemberIdentity, folderAccessFor, folderAccessForAll, mayActForOf, memberIdentityFor } from './caller.ts';
+import { GUEST, mayActForCovers } from './audience.ts';
import { ACTOR_ARGUMENT, ACTOR_DEFERRED_OPS, ACTOR_HEADER, attestRightFrom, DEFAULT_ATTEST_OPS, EXTERNAL_ID_RE, QM_AUDIENCE_HEADER, type AttestedActor, type AttestRight } from './actor-model.ts';
export * from './actor-model.ts';
@@ -35,7 +36,7 @@ export interface AttestableOpShape { scope?: string; requiredScopes?: readonly s
type Principal = { kind: string; id: string };
export interface ActorCaller {
- auth?: Pick<AuthInfo, 'attest' | 'member' | 'clientName'> & { principal?: Principal };
+ auth?: Pick<AuthInfo, 'attest' | 'member' | 'mayActFor' | 'clientId' | 'clientName'> & { principal?: Principal };
principal?: Principal;
}
@@ -100,7 +101,7 @@ function credentialArgv(caller: ActorCaller): string[] {
const transportOf = (transport?: string) => ({ remote: true, transport: transport === 'stdio' ? 'stdio' as const : 'http' as const });
/** actor_not_attested with its reason, remedy and (where the operator can fix it) the rescope command. */
-export function actorNotAttested(reason: ActorReason, caller: ActorCaller, ctx: { op: string; transport?: string; right?: AttestRight | null; reissue?: boolean; memberBound?: boolean }): OperationError {
+export function actorNotAttested(reason: ActorReason, caller: ActorCaller, ctx: { op: string; transport?: string; right?: AttestRight | null; reissue?: boolean; memberBound?: boolean; mayActFor?: boolean }): OperationError {
const docs = ERROR_CATALOGUE.actor_not_attested.docs;
const rescope = (extra: string[]) => ['gbrain', 'auth', 'rescope', ...credentialArgv(caller), ...extra];
const hostOnly = (message: string, argv: string[], why: string, suggestion: string) =>
@@ -124,6 +125,10 @@ export function actorNotAttested(reason: ActorReason, caller: ActorCaller, ctx:
'Lets an attested call run this operation as the person it names. Widening what a trusted system may do as a person is the brain operator\'s decision.',
`An attested call runs only the operations the operator listed (default ${DEFAULT_ATTEST_OPS.join(', ')}); admin and membership operations never.`);
case 'argument_mismatch':
+ if (ctx.mayActFor) {
+ return opError('actor_not_attested', `The ${ACTOR_ARGUMENT} argument names no one this credential may act for, so nothing was read or written.`,
+ `Leave ${ACTOR_ARGUMENT} out, or name a member this credential's may_act_for lists (gbrain auth rescope ... --may-act-for <list> on the brain host). It reads only what both the credential and that member may read; text in a conversation never widens whose notes are read.`, { reason, docs });
+ }
if (ctx.memberBound) {
return opError('actor_not_attested', `The ${ACTOR_ARGUMENT} argument names someone other than this credential's member, so nothing was read or written.`,
`Leave ${ACTOR_ARGUMENT} out, or send this credential's own member id or a canonical id linked to it. A credential bound to a member reads only as that member; text in a conversation never chooses whose notes are read.`, { reason, docs });
@@ -261,19 +266,47 @@ export async function resolveAttestedActor(engine: Pick<BrainEngine, 'executeRaw
}
/**
- * HARN-1: acting_user with no header, on a credential bound to a member (no stdio, no on_behalf_of audience). The
- * member id, or a canonical id linked to it, is stripped and the call runs exactly as the credential; any other value
- * is argument_mismatch, so the argument never widens or switches whose notes are read, and never tells an existing id
- * from an unknown one. Every other caller is refused argument_without_attestation as before.
+ * HARN-1: acting_user with no header (no stdio, no on_behalf_of audience). On a credential bound to a member, that
+ * member id or a canonical id linked to it is stripped and the call runs exactly as the credential; any other value is
+ * argument_mismatch. On a credential bound to no member that lists may_act_for, a member it covers (by id, or by a
+ * canonical id linked to it) is read as the intersection of the credential's own empty identity and the member's
+ * (narrowedCallerAccess); anything else is one argument_mismatch, so it never tells an existing id from an unknown one.
+ * The argument never widens whose notes are read. Every other caller is refused argument_without_attestation.
*/
async function ownMemberArgument(engine: Pick<BrainEngine, 'executeRaw'>, input: { params?: Record<string, unknown>; auth?: ActorCaller['auth']; transport?: string; audienceAsserted: boolean },
- argument: string, caller: ActorCaller, ctx: { op: string; transport?: string }): Promise<{ params: Record<string, unknown> }> {
- const own = input.transport === 'stdio' || input.audienceAsserted || !input.auth ? null
- : (await memberIdentityFor(engine, input.auth)).find(p => p.startsWith('member:'))?.slice('member:'.length) ?? null;
- if (!own) throw actorNotAttested('argument_without_attestation', caller, ctx);
- if (argument !== own && (await linkedMember(engine, 'qm', argument))?.member !== own) throw actorNotAttested('argument_mismatch', caller, { ...ctx, memberBound: true });
+ argument: string, caller: ActorCaller, ctx: { op: string; transport?: string }): Promise<{ params: Record<string, unknown>; access?: Partial<CallerAccess> }> {
+ if (input.transport === 'stdio' || input.audienceAsserted || !input.auth) throw actorNotAttested('argument_without_attestation', caller, ctx);
const { [ACTOR_ARGUMENT]: _stripped, ...params } = input.params ?? {};
- return { params };
+ const own = (await memberIdentityFor(engine, input.auth)).find(p => p.startsWith('member:'))?.slice('member:'.length) ?? null;
+ if (own) {
+ if (argument !== own && (await linkedMember(engine, 'qm', argument))?.member !== own) throw actorNotAttested('argument_mismatch', caller, { ...ctx, memberBound: true });
+ return { params };
+ }
+ const mayActFor = await mayActForOf(engine, { auth: input.auth, transport: input.transport });
+ if (!mayActFor?.length) throw actorNotAttested('argument_without_attestation', caller, ctx);
+ const direct = await enabledMemberIdentity(engine, argument);
+ const member = direct.length ? { member: argument, identity: direct } : await linkedMember(engine, 'qm', argument);
+ if (!member || !mayActForCovers(mayActFor, `member:${member.member}`)) throw actorNotAttested('argument_mismatch', caller, { ...ctx, mayActFor: true });
+ return { params, access: await narrowedCallerAccess(engine, member.member, member.identity) };
+}
+
+/**
+ * HARN-1: a may_act_for credential reading for one covered member through acting_user: B's multi-entry intersection of
+ * the credential's own empty identity (`guest`) and the member's, so a page must be readable by both, and privacy is
+ * never relaxed (no granted_sources, no hatch). Writes run as no member (callerMember is null for an intersection).
+ */
+async function narrowedCallerAccess(engine: Pick<BrainEngine, 'executeRaw'>, member: string, identity: string[]): Promise<Partial<CallerAccess>> {
+ const identities = [[], identity];
+ return {
+ identity: [],
+ audience: [GUEST, `member:${member}`],
+ audienceIdentities: identities,
+ ...await folderAccessForAll(engine, identities),
+ privateReadableSources: [],
+ hidePrivate: true,
+ applyRemoteReadPolicy: false,
+ restricted: true,
+ };
}
export interface MemberLink { system: string; external_id: string; member_id: string; created_at: string | null }
diff --git a/src/core/access/caller.ts b/src/core/access/caller.ts
index cb5d0443ce..06174124b2 100644
--- a/src/core/access/caller.ts
+++ b/src/core/access/caller.ts
@@ -41,6 +41,9 @@ async function liveIdentity(engine: Pick<BrainEngine, 'executeRaw'>, memberSql:
}
}
+/** HARN-1: an enabled member's identity by exact id; empty when absent, disabled or unreadable. */
+export const enabledMemberIdentity = (engine: Pick<BrainEngine, 'executeRaw'>, id: string) => liveIdentity(engine, '$1', id);
+
/**
* The member identity bound to `auth`: the verifier's join when present, else a lookup from its principal; empty
* when unbound, unknown or unreadable. A write's publication passes only its stored principal, so a member disabled
@@ -110,7 +113,7 @@ export interface AudienceCaller {
* lookup from the stored principal (a revoked token or deleted client permits nothing), else for a stdio server
* config mcp.stdio_may_act_for. Unreadable or ill-formed values permit nothing.
*/
-async function mayActForOf(engine: Pick<BrainEngine, 'executeRaw'>, caller: AudienceCaller): Promise<string[] | null> {
+export async function mayActForOf(engine: Pick<BrainEngine, 'executeRaw'>, caller: AudienceCaller): Promise<string[] | null> {
const auth = caller.auth;
if (auth?.member !== undefined) return auth.mayActFor ?? null;
const principal = auth?.principal ?? caller.principal;
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index dd185ab480..f3c6dcdf5f 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1376,7 +1376,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: 'TBD', id: 'member_read_access_gbra218', text: 'A page whose frontmatter names readers (`readable_by: [alice-example, group:team-a]`) is now read remotely only by a token, OAuth client or stdio server bound to a listed member (`gbrain access member add`, `gbrain auth rescope --token <name> --member <id>`, config `mcp.stdio_member`). Every other remote caller gets the same `not_found` as for a missing page, including unbound credentials, a `--private-pages granted-sources` bot and both escape hatches (`GBRAIN_REMOTE_PRIVATE_PAGES=1`, `search.remote_private_pages=visible`), which relax only `visibility: private`. A malformed `readable_by` reads as nobody, and a page derived from a restricted page reads as nobody remotely. Pages that already named `readable_by` before this upgrade read as nobody remotely until `gbrain repair access` (preview, then `--apply`). The local CLI is unchanged; `--as <member>` previews one member\'s view.' },
{ since: 'TBD', id: 'member_access_hatch_scope_gbra218', text: 'On a brain where any page names readers or any member exists, the escape hatches no longer turn the remote read filter off: remote reads still hide pages the caller\'s member is not listed on, and secondary surfaces that use the identity-free filter (proactive brief, retrieval reflex, entity resolution, known-as-of) hide every restricted page and keep hiding `visibility: private` pages under a hatch. A brain with no restriction keeps the old hatch behaviour exactly. A credential bound to a disabled or removed member is refused at verification (`access_member_disabled`).' },
{ since: 'TBD', id: 'shared_agent_audience_gbra231', text: 'A shared agent can now read as the people a turn serves: its harness names the audience in the `X-Gbrain-On-Behalf-Of` header or request-level `_meta.on_behalf_of` (member ids, `group:<id>`, `guest`), and the call returns only pages every entry may read, within the agent\'s own source grant; a channel audience (more than one member, a group or a guest) never sees a `visibility: private` page. Each entry must be in the credential\'s `may_act_for` (`gbrain auth rescope --token <name> --may-act-for <list>`; for stdio, config `mcp.stdio_may_act_for`), which earlier releases stored without enforcing. An audience inside tool arguments is refused (`on_behalf_of_in_arguments`). Every remote MCP response now carries `_meta.access` (member, groups, audience, policy revisions, privacy relaxation), and `whoami` returns it as `access.applied`.' },
- { since: 'TBD', id: 'qm_attested_actor_gst359', text: 'A trusted system can now name the person a call serves: a client-credentials client the brain host grants the attest right (`gbrain auth rescope --client <id> --attest-actor qm`) sends `x-qm-actor: <canonical id>`, and each attested operation runs as the member that id is linked to (`gbrain access member link <member> --qm <id>`), never reading `visibility: private` pages; `capture`, `extract_facts`, take writes and `list_write_conflicts` are not attestable yet. A call that sends `x-qm-actor` or an `acting_user` argument without that right, for an operation outside the credential\'s `--attest-ops`, or with an id that is not 1-256 visible ASCII characters is refused (`actor_not_attested`), except that a credential bound to a member may send `acting_user` with no header: its own member id or a canonical id linked to it is dropped and the call runs exactly as the credential, and any other value is refused (`actor_not_attested` reason `argument_mismatch`); an id with no link to an enabled member is refused (`actor_unlinked`). Refusals carry their code in `structuredContent.error`. Every MCP server\'s `serverInfo` now includes a one-line `description`.' },
+ { since: 'TBD', id: 'qm_attested_actor_gst359', text: 'A trusted system can now name the person a call serves: a client-credentials client the brain host grants the attest right (`gbrain auth rescope --client <id> --attest-actor qm`) sends `x-qm-actor: <canonical id>`, and each attested operation runs as the member that id is linked to (`gbrain access member link <member> --qm <id>`), never reading `visibility: private` pages; `capture`, `extract_facts`, take writes and `list_write_conflicts` are not attestable yet. A call that sends `x-qm-actor` or an `acting_user` argument without that right, for an operation outside the credential\'s `--attest-ops`, or with an id that is not 1-256 visible ASCII characters is refused (`actor_not_attested`), except that a credential bound to a member may send `acting_user` with no header: its own member id or a canonical id linked to it is dropped and the call runs exactly as the credential, and a credential bound to no member that lists `may_act_for` may name a member it covers there and then reads only what both the credential and that member may read, never a `visibility: private` page; any other value is refused (`actor_not_attested` reason `argument_mismatch`, one message whether or not the id exists); an id with no link to an enabled member is refused (`actor_unlinked`). Refusals carry their code in `structuredContent.error`. Every MCP server\'s `serverInfo` now includes a one-line `description`.' },
{ since: 'TBD', id: 'member_facts_gst359', text: 'A fact a member saves remotely (`remember` attested as a person, or from a credential bound to one member) now goes on that member\'s own page `memory/members/<member>`, created with `readable_by: [member:<id>]`, as a `visibility: private` fact with the entity kept as metadata, instead of on the entity page where every reader of the source recalled it. Only that member recalls it; it never dedups against, supersedes or contests another page\'s fact, never consolidates into a take, and keeps its readers through a fence rebuild and relink. Under one attest client, hot memory, `delta` cursors, write receipts (`get_write_request`, `list_write_requests`, `cancel_write_request`, replays by `request_id`) and agent jobs (`get_agent_job`) are kept to the person they were made for: another person and the client\'s bare calls get `not_found`. `remember`, `delta`, the receipt operations, `submit_agent` and `get_agent_job` are now attestable.' },
{ since: 'TBD', id: 'qm_memory_provider_gst359', text: 'QM can now keep per-person memory: `memory_recall` and `memory_write`, the default attested operations of an attest client with `get_write_request` (`gbrain auth rescope --client <id> --attest-actor qm`), read the person\'s own recent facts first and then the facts they may read, and save facts on that person\'s own page `memory/members/<member>`, readable by them alone. `memory_write` needs an attested person (`actor_not_attested` reason `actor_required` otherwise), and a reused `idempotency_key` returns the first receipt for the same person only. `forget` and `forget_fact` are now attestable: for an attested person or a credential bound to a member they withdraw only a fact on that member\'s own page, and only on that page; any other fact is `not_found`. A request carrying `x-qm-audience` is refused (`actor_not_attested` reason `audience_not_supported`) until channel audiences are served. `remember` and `memory_write` accept `valid_from` only as an ISO 8601 date or time in years 0001-9999. `recall` now takes `max_chars` (a whole number from 200 to 12000, as `memory_recall`): it keeps the whole facts, then results, whose text fits, adds no marker and returns `truncated`; without it `recall` is unchanged. The contract QM vendors is `docs/contracts/qm-memory-provider/v1.json`.' },
{ since: 'TBD', id: 'unknown_param_meta_only_harn15', text: 'A read that ignores a parameter the tool does not declare (`mcp.strict_params` `warn`, the default) no longer adds a `[gbrain notice unknown_param kind=info]` text block to the result: the warning is only in `_meta.warnings` (`{code: \'unknown_param\', param, suggestion?}`), so a harness that stores tool output in its turns never stores it. Writes still refuse unknown parameters, and `reject` mode is unchanged.' },
diff --git a/src/core/error-registry.ts b/src/core/error-registry.ts
index a4409e66cd..cec70ae3c5 100644
--- a/src/core/error-registry.ts
+++ b/src/core/error-registry.ts
@@ -68,7 +68,7 @@ export const CODES = {
on_behalf_of_invalid_audience: { class: 'caller', summary: "A shared agent's request named its audience (the X-Gbrain-On-Behalf-Of header or request-level _meta.on_behalf_of) in a form gbrain does not accept: empty, more than 50 entries, an entry that is not a member id, group:<id> or guest, or a header and _meta that name different audiences. Nothing was read.", why: 'The audience decides whose notes the agent may read, so an audience gbrain cannot read exactly is refused instead of guessed.', docs: 'docs/guides/write-refusals.md#on_behalf_of_invalid_audience', suggestion: 'Fix the harness code that sets the audience: 1-50 entries, each a member id, group:<id> or guest, the same in the header and _meta when both are sent.' },
on_behalf_of_unknown_member: { class: 'caller', summary: "A shared agent's audience names a member who is not enabled on this brain, or a group that does not exist, so nothing was read.", why: 'An unknown or disabled entry is refused rather than read as a guest, so a typo or a removed person never quietly changes what the agent reads.', docs: 'docs/guides/write-refusals.md#on_behalf_of_unknown_member', suggestion: 'Name enabled members and existing groups only (gbrain access member list --all, gbrain access group list on the brain host); a person who is not a member joins the audience as guest.' },
on_behalf_of_not_permitted: { class: 'host_only', actor: 'user', summary: "A shared agent asserted an audience its credential's may_act_for does not list (for a stdio server, config mcp.stdio_may_act_for), so nothing was read.", why: 'A shared agent acts only for the people the brain operator approved for its credential; widening that list is the operator\'s decision, never the agent\'s.', docs: 'docs/guides/write-refusals.md#on_behalf_of_not_permitted', suggestion: 'The brain operator decides whether to approve the audience: gbrain auth rescope --token <name>|--client <id> --may-act-for <list> on the brain host. Until then, call without the audience.' },
- actor_not_attested: { class: 'host_only', actor: 'user', reasons: ['no_attest_right', 'op_not_attested', 'argument_mismatch', 'argument_without_attestation', 'invalid_actor_id', 'actor_required', 'audience_not_supported'], summary: "A call named the person it serves (the x-qm-actor header or the acting_user argument) in a way gbrain does not honour: the credential holds no attest right, the operation is not in its attested operations, the argument differs from the header, names anyone but a member-bound credential's own member, or comes without an attested header from a credential bound to no member, or the id is not 1-256 visible ASCII characters; or a write that saves only as an attested person (memory_write) named none; or the request carries x-qm-audience, a channel audience gbrain does not serve yet. Nothing was read or written.", why: 'Naming a person decides whose notes are read and written as; only a credential the brain operator granted the attest right may do it, only for the operations it lists, and text in a conversation never chooses it.', docs: 'docs/guides/write-refusals.md#actor_not_attested', suggestion: 'Read reason: no_attest_right and op_not_attested are the brain operator\'s call (gbrain auth rescope --client <id> --attest-actor qm [--attest-ops <list>]); argument_mismatch, argument_without_attestation, invalid_actor_id, actor_required and audience_not_supported are fixed in the calling harness.' },
+ actor_not_attested: { class: 'host_only', actor: 'user', reasons: ['no_attest_right', 'op_not_attested', 'argument_mismatch', 'argument_without_attestation', 'invalid_actor_id', 'actor_required', 'audience_not_supported'], summary: "A call named the person it serves (the x-qm-actor header or the acting_user argument) in a way gbrain does not honour: the credential holds no attest right, the operation is not in its attested operations, the argument differs from the header, names anyone but a member-bound credential's own member or a member a may_act_for credential covers, or comes without an attested header from a credential bound to no member and listing no may_act_for, or the id is not 1-256 visible ASCII characters; or a write that saves only as an attested person (memory_write) named none; or the request carries x-qm-audience, a channel audience gbrain does not serve yet. Nothing was read or written.", why: 'Naming a person decides whose notes are read and written as; only a credential the brain operator granted the attest right may do it, only for the operations it lists, and text in a conversation never chooses it.', docs: 'docs/guides/write-refusals.md#actor_not_attested', suggestion: 'Read reason: no_attest_right and op_not_attested are the brain operator\'s call (gbrain auth rescope --client <id> --attest-actor qm [--attest-ops <list>]); argument_mismatch, argument_without_attestation, invalid_actor_id, actor_required and audience_not_supported are fixed in the calling harness.' },
actor_unlinked: { class: 'host_only', actor: 'user', summary: 'An attested call named a person whose canonical id is not linked to an enabled member of this brain (never linked, unlinked, or the member is disabled or removed), so nothing was read or written.', why: 'An attested call reads and writes as exactly one member; an unknown person is refused rather than read as a guest, and unlinking or disabling takes effect on the next call.', docs: 'docs/guides/write-refusals.md#actor_unlinked', suggestion: 'The brain operator links the id to its member: gbrain access member link <member> --qm <id> (or enables the member).' },
on_behalf_of_in_arguments: { class: 'caller', summary: 'A tool call carried on_behalf_of inside its arguments, where conversation text could set it, so it was refused and nothing was read.', why: 'Only harness code may name whose notes a shared agent reads: the X-Gbrain-On-Behalf-Of header or request-level _meta.on_behalf_of, never tool arguments.', docs: 'docs/guides/write-refusals.md#on_behalf_of_in_arguments', suggestion: 'Remove on_behalf_of from the tool arguments. Harness code sends it as the X-Gbrain-On-Behalf-Of header or request-level _meta.on_behalf_of; other stdio clients use a credential bound to one member or config mcp.stdio_member.' },
access_policy_invalid: { class: 'host_only', actor: 'user', docs: 'docs/guides/write-refusals.md#access_policy_invalid', summary: "A source's folder-rule policy (the committed .gbrain/access.yml, or a file given to gbrain access rule import) does not validate, so it was not applied: the last applied rules stay in force and every prefix the bad file names reads as nobody (the whole source when its prefixes cannot be read).", why: 'A typo in an access file must never open a folder: an unreadable revision keeps the previous rules and hides what it touches until it is fixed.', suggestion: 'Show each problem with its line (gbrain access rule list --source <id>), fix the file, commit it with gbrain git commit-push and sync the source (gbrain sync --source <id> --no-pull).', fix: { argv: ['gbrain', 'access', 'rule', 'list', '--source', '{source_id}', '--json'], consent: [], actor: 'agent', requires_exclusive: false, why: 'Lists the applied rules and each problem in the policy file with its line; changes nothing.' } },
diff --git a/src/mcp/dispatch.ts b/src/mcp/dispatch.ts
index f252187478..26ec61dd91 100644
--- a/src/mcp/dispatch.ts
+++ b/src/mcp/dispatch.ts
@@ -938,7 +938,7 @@ export async function dispatchToolCall(
assertion(e.code as AudienceAuditEvent['outcome'], e.reason);
return qmMemoryToolResult(name, actorNamed ? actorRefusal(e, opts, name, header, params) : errorResult(e, opts, { op: name }));
}
- if (audience || attested?.actor) assertion('accepted');
+ if (audience || attested?.access) assertion('accepted');
const callParams = attested ? attested.params : params;
return withCallerAccess(access, async () => {
const out = await withRequestIdentityMemo(() => dispatchResolvedCall(engine, name, callParams, resolved));
diff --git a/test/access-qm-actor.test.ts b/test/access-qm-actor.test.ts
index 8243279fec..716d46c3ad 100644
--- a/test/access-qm-actor.test.ts
+++ b/test/access-qm-actor.test.ts
@@ -130,7 +130,10 @@ for (const kind of testBackends()) {
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);
+ await bindCredential(engine, { kind: 'client', id: await register('anyone') }, { mayActFor: ['*'] });
+ await bindCredential(engine, { kind: 'client', id: await register('bob') }, { member: 'bob-example' });
+ for (const name of ['qm', 'plain', 'defaults', 'alice', 'agent', 'anyone', 'bob']) await issue(name);
+ await engine.executeRaw("UPDATE oauth_clients SET private_pages = 'granted_sources' WHERE client_id = $1", [clients.agent!.id]);
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' });
@@ -253,14 +256,76 @@ for (const kind of testBackends()) {
}
}, 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 () => {
+ test('HARN-1: a bare credential, stdio, and acting_user beside an on_behalf_of audience are refused argument_without_attestation', async () => {
for (const id of ['alice-example', ALICE_ID, 'bob-example']) {
- for (const bearer of [clients.agent!.token, clients.plain!.token, null]) {
+ for (const bearer of [clients.plain!.token, null]) {
await refused(call(bearer, 'get_page', { slug: PAGES.alice.slug, acting_user: id }), 'actor_not_attested', 'argument_without_attestation');
}
+ await refused(call(clients.agent!.token, 'get_page', { slug: PAGES.alice.slug, acting_user: id }, { obo: 'bob-example' }), 'actor_not_attested', 'argument_without_attestation');
}
}, 60_000);
+ test('HARN-1 may_act_for: a covered acting_user reads only what both the credential and the member read, never a private page', async () => {
+ const agent = clients.agent!.token;
+ const bob = clients.bob!.token;
+ const canaries = (text: string) => (Object.keys(PAGES) as Key[]).filter(k => text.includes(PAGES[k].canary));
+ const subset = (named: string, own: string, member: string) => {
+ for (const k of canaries(named)) { expect(canaries(own)).toContain(k); expect(canaries(member)).toContain(k); }
+ };
+ expect((await getAs(undefined, 'quiet', agent)).text).toContain(PAGES.quiet.canary);
+ expect((await getAs(undefined, 'quiet', bob)).text).not.toContain(PAGES.quiet.canary);
+ expect((await getAs(undefined, 'bob', bob)).text).toContain(PAGES.bob.canary);
+ expect((await getAs(undefined, 'bob', agent)).text).not.toContain(PAGES.bob.canary);
+ const search = (bearer: string, extra: Record<string, unknown> = {}) => call(bearer, 'search', { query: 'harbor ledger qm notes', match: 'keyword', fields: 'full', limit: 30, ...extra });
+ const recall = (bearer: string, extra: Record<string, unknown> = {}) => call(bearer, 'recall', { query: 'harbor ledger qm notes', ...extra });
+ for (const id of ['bob-example', BOB_ID]) {
+ for (const key of Object.keys(PAGES) as Key[]) {
+ const named = await getAs(undefined, key, agent, { acting_user: id });
+ subset(named.text, (await getAs(undefined, key, agent)).text, (await getAs(undefined, key, bob)).text);
+ expect(named.text).not.toContain('acting_user');
+ }
+ const named = await getAs(undefined, 'open', agent, { acting_user: id });
+ expect(named.text).toContain(PAGES.open.canary);
+ expect(named.meta?.access).toMatchObject({ member: null, audience: ['guest', 'member:bob-example'], relaxation: 'none' });
+ for (const key of ['quiet', 'bob', 'alice', 'both'] as Key[]) expect((await getAs(undefined, key, agent, { acting_user: id })).text).not.toContain(PAGES[key].canary);
+ const s = await search(agent, { acting_user: id });
+ expect(s.isError).toBe(false);
+ subset(s.text, (await search(agent)).text, (await search(bob)).text);
+ expect(canaries(s.text)).toEqual(['open']);
+ const r = await recall(agent, { acting_user: id });
+ expect(r.isError).toBe(false);
+ subset(r.text, (await recall(agent)).text, (await recall(bob)).text);
+ expect(canaries(r.text)).toEqual(['open']);
+ for (const key of ['quiet', 'bob', 'alice', 'both'] as Key[]) expect(r.text).not.toContain(PAGES[key].canary);
+ }
+ await withEnv({ GBRAIN_REMOTE_PRIVATE_PAGES: '1' }, async () => {
+ __resetPrivateVisibilityCacheForTests();
+ try {
+ expect((await getAs(undefined, 'quiet', agent, { acting_user: 'bob-example' })).text).not.toContain(PAGES.quiet.canary);
+ const s = await search(agent, { acting_user: 'bob-example' });
+ expect(s.text).not.toContain(PAGES.quiet.canary);
+ expect(s.meta?.access).toMatchObject({ relaxation: 'none' });
+ expect((await recall(agent, { acting_user: 'bob-example' })).text).not.toContain(PAGES.quiet.canary);
+ } finally {
+ __resetPrivateVisibilityCacheForTests();
+ }
+ });
+ }, 180_000);
+
+ test('HARN-1 may_act_for: an id outside may_act_for, an unknown id and an unlinked id are refused alike, revealing nothing', async () => {
+ const messages = new Set<string>();
+ const cases: Array<[string, string]> = [[clients.agent!.token, 'dan-example'], [clients.agent!.token, 'nobody-example'], [clients.agent!.token, 'U0NOBODY'],
+ [clients.anyone!.token, 'nobody-example'], [clients.anyone!.token, 'U0NOBODY']];
+ for (const [bearer, id] of cases) {
+ for (const key of ['open', 'bob'] as Key[]) {
+ const out = await refused(getAs(undefined, key, bearer, { acting_user: id }), 'actor_not_attested', 'argument_mismatch');
+ messages.add(String(out.json.message) + '|' + String(out.json.suggestion));
+ expect(out.text).not.toContain(id);
+ }
+ }
+ expect(messages.size).toBe(1);
+ }, 120_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]);