Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Access lineage review fixes: enforced output guard and granted_sources wording
garrytanef997209332c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 9170d2ec29..8286ca1bed 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -21,7 +21,8 @@ identifiers and attribution are available in the pre-removal Git revision- Migration v305 (`src/core/schema-migrations/v305-access-lineage-designs.ts`): `access_rules.covers_derived` (default true), `access_members.kind` (`person` | `audience`, default `person`), the SQL function `gbrain_access_lineage_rules()`, and new versions of `gbrain_access_origin_restricted()`, `gbrain_access_origin_closed_for()` (10 arguments) and `gbrain_access_origin_hidden_for()` (9 arguments); the v304 signatures stay as wrappers. Nothing is rewritten, and every existing rule keeps its digest.- Raw-only rules: `src/core/access/folder-rules.ts` (`covers_derived: false` in `access.yml`, the held widening `derived_released` and the narrowing `derived_covered`), `src/core/access/policy.ts` (stored, compared and previewed with `lineage` in `gbrain access apply`), `src/commands/access-rules.ts` (`rule add --raw-only`).- Audience members: `src/core/access/members.ts` (`setMemberKind`, `member add --kind`, refused for remote callers with `permission_denied`), `src/core/search/private-visibility.ts` (the owner's read of an audience member page, its versions, derived pages and facts), `gbrain access member kind <id> person|audience`; `member list` shows the kind.-- Member lineage: config `access.members_read_lineage` (`src/core/access/lineage.ts`, `gbrain access members-read-lineage [on|off]`, refused for remote callers); `src/core/access/caller.ts` and `src/cli/as-preview.ts` give it to a member speaking for itself, never to an audience of several, an unbound credential or a `granted_sources` grant; `whoami` adds `members_read_lineage` while it is on.+- Member lineage: config `access.members_read_lineage` (`src/core/access/lineage.ts`, `gbrain access members-read-lineage [on|off]`, refused for remote callers); `src/core/access/caller.ts` and `src/cli/as-preview.ts` give it to a member speaking for itself, never to an audience of several or an unbound credential (an unbound `granted_sources` token included), while a member-bound `granted_sources` token gets its member's lineage; `whoami` adds `members_read_lineage` while it is on.+- `src/cli/enforced-member.ts`: the enforced member CLI's output guard judges slugs under the record the read ran under, so with member lineage on it no longer withholds output naming a derived page the member reads.- The semantic cache key (`src/core/search/mode.ts`) and the per-caller key (`src/core/access/member-facts.ts`) carry the member lineage and the owner's audience members.- `gbrain access check` and `who-can-read` explain all three; doctor `access_raw_only_rules`, `access_audience_members` and `access_members_read_lineage` (`src/commands/doctor/checks/access-lineage.ts`).- Docs: `docs/guides/access-designations.md` (raw-only rules, audience members, members read lineage), key-files entry.diff --git a/docs/guides/access-designations.md b/docs/guides/access-designations.mdindex 9cd98fb303..18fd04e9dd 100644--- a/docs/guides/access-designations.md+++ b/docs/guides/access-designations.md@@ -204,8 +204,9 @@ page, and doctor's `access_audience_members` lists the audience members.upgrade) gives every member's credential the owner's lineage rule: a member speaking for itself (no audience, or anaudience of that one member) reads a derived page or a fact when it reads every origin of it, on every read path andin `--as <member>`. Summaries of a page then reach everyone that page lists, so turn it on only when that is what the-members expect. It never applies to an audience of several members, a group or a guest, an attested call, an unbound-credential or a `granted_sources` grant, never widens a write, and leaves the owner opt-in to the owner. Only the brain+members expect. It never applies to an audience of several members, a group or a guest, an attested call, or an unbound+credential (an unbound `granted_sources` token included); a member-bound `granted_sources` token reads with its+member's lineage. It never widens a write, and leaves the owner opt-in to the owner. Only the brainoperator on the brain host sets it; a remote caller is refused. While it is on, every remote caller's `whoami` says so(`members_read_lineage`), `gbrain access check` reports it, `who-can-read` names it on pages it opens, and doctorreports `access_members_read_lineage`. `gbrain access members-read-lineage off` is the undo.diff --git a/src/cli/enforced-member.ts b/src/cli/enforced-member.tsindex d493e45301..6af5bb7ff6 100644--- a/src/cli/enforced-member.ts+++ b/src/cli/enforced-member.ts@@ -480,7 +480,9 @@ async function ownEnforcedReceipt(id: unknown): Promise<boolean> {/*** Output guard (defense in depth): true when any whole string in result is the slug of a page the member cannot read- * and no page it reads carries the same slug. The caller then withholds the whole output.+ * and no page it reads carries the same slug. The caller then withholds the whole output. Pages are judged under the+ * record the read ran under (a read-only operation with the enforced overrides), so a derived page the member reads+ * through access.members_read_lineage is not withheld; when that record cannot be built, the output is withheld.*/export async function namesHiddenPage(engine: BrainEngine, command: string, result: unknown): Promise<boolean> {const strings = new Set<string>();@@ -493,8 +495,11 @@ export async function namesHiddenPage(engine: BrainEngine, command: string, resuwalk(result, 0);if (!strings.size) return false;const ea = await enforcedAccess(engine, command);- const { withCallerAccess, readPolicyFragment } = await import('../core/search/private-visibility.ts');- const policy = withCallerAccess(ea.access, () => readPolicyFragment('p', ea.access.identity, true, ea.access.satisfiedRuleIds));+ const [{ withCallerAccess, callerAccessAllowedSql, privacyPartSql }, { remoteCallerAccess }] = await Promise.all([+ import('../core/search/private-visibility.ts'), import('../core/access/caller.ts')]);+ const read = await remoteCallerAccess(engine, undefined, [], 'stdio', null, ea.member, true).catch(() => null);+ if (!read) return true;+ const policy = withCallerAccess({ ...read, hidePrivate: true, owner: false, privateReadableSources: [] }, () => '(' + callerAccessAllowedSql('p') + ' AND ' + privacyPartSql('p') + ')');const hidden = ea.hiddenSources.size ? '(NOT (' + policy + ') OR p.source_id = ANY($2::text[]))' : 'NOT (' + policy + ')';const rows = await engine.executeRaw<{ slug: string; hidden: boolean }>('SELECT p.slug, ' + hidden + ' AS hidden FROM pages p WHERE p.slug = ANY($1::text[])',ea.hiddenSources.size ? [[...strings], [...ea.hiddenSources]] : [[...strings]]);diff --git a/test/access-members-read-lineage.test.ts b/test/access-members-read-lineage.test.tsindex 84fe2388c6..76f6ae96a3 100644--- a/test/access-members-read-lineage.test.ts+++ b/test/access-members-read-lineage.test.ts@@ -11,15 +11,18 @@ import { authorizePageVisibility } from '../src/core/persistence/page-visibilityimport type { WriteAuthority } from '../src/core/persistence/model.ts';import { buildLineageBrain, derivedOf, factsOf, type LineageBrain, type Seen } from './helpers/access-lineage-fixture.ts';import { testBackends } from './helpers/test-backends.ts';+import { withEnv } from './helpers/with-env.ts';+import { ENFORCED_MEMBER_ENV, enforcedRead, namesHiddenPage } from '../src/cli/enforced-member.ts';import { PGLiteEngine } from '../src/core/pglite-engine.ts';/*** GBRA-108 Design 3: config access.members_read_lineage (off by default; set only by the operator on the brain host).* 1. Protects: with it on, a member's credential speaking for itself (no audience, or an audience of exactly that one* member) reads the atoms, derived_from pages, synthesized concepts, Life Chronicle events and facts whose origins it- * reads, on every read path, as the owner already does. Off, nothing changes. An unbound credential, a- * granted_sources credential, an audience of several members, and the owner (whose own lineage and opt-in are- * separate) read exactly the same off and on, and no write widens.+ * reads, on every read path, as the owner already does; a member-bound granted_sources credential reads exactly+ * what its member reads. Off, nothing changes. An unbound credential (an unbound granted_sources one included), an+ * audience of several members, and the owner (whose own lineage and opt-in are separate) read exactly the same off+ * and on, and no write widens. The enforced member CLI's output guard agrees with the read.* 2. Fails when: a member misses a derivative or fact of an origin it reads, or reads one of an origin it does not; any* non-target caller's view changes; the --as preview disagrees with the key; whoami, access check, who-can-read or* doctor do not report the setting; a remote caller turns it on; or the cache keys do not change with it.@@ -99,7 +102,7 @@ for (const kind of testBackends()) {{ name: 'as-alice', as: 'alice-example' },{ name: 'solo', mayActFor: ['member:alice-example', 'member:bob-example'], audience: ['alice-example'] },{ name: 'pair', mayActFor: ['member:alice-example', 'member:bob-example'], audience: ['alice-example', 'bob-example'] },- { name: 'unbound' }, { name: 'granted', grantedSources: true }],+ { name: 'unbound' }, { name: 'granted', grantedSources: true }, { name: 'alice-granted', member: 'alice-example', grantedSources: true }],});}, 300_000);afterAll(async () => { await b?.close(); }, 60_000);@@ -110,6 +113,7 @@ for (const kind of testBackends()) {expect(off.bob).toEqual(b.expected(['team', 'both', 'open'], []));expect(off.solo).toEqual(off.alice);expect(off['as-alice']).toEqual(off.alice);+ expect(await b.seenBy('alice-granted')).toEqual(off.alice);expect(off.pair).toEqual(b.expected(['both', 'open'], []));for (const who of ['owner', 'carol', 'unbound', 'granted']) expect({ who, seen: off[who] }).toEqual({ who, seen: b.expected(['open'], []) });expect((await whoami('alice')).access.members_read_lineage).toBeUndefined();@@ -124,10 +128,11 @@ for (const kind of testBackends()) {expect(await b.seenBy('alice')).toEqual(alice);expect(await b.seenBy('solo')).toEqual(alice);expect(await b.seenBy('as-alice')).toEqual(alice);+ expect(await b.seenBy('alice-granted')).toEqual(alice);expect(await b.seenBy('bob')).toEqual(b.expected(['team', 'both', 'open', ...derivedOf(b.keys, ['team', 'both'])], factsOf(b.keys, ['team', 'both'])));}, 600_000);- test('on: the owner, another member, an audience of several, an unbound and a granted_sources credential read the same', async () => {+ test('on: the owner, another member, an audience of several, and unbound credentials (granted_sources included) read the same', async () => {for (const who of UNCHANGED) expect({ who, seen: await b.seenBy(who) }).toEqual({ who, seen: off[who]! });}, 600_000);@@ -149,6 +154,23 @@ for (const kind of testBackends()) {}}, 600_000);+ test('on: the enforced member CLI output guard withholds no derived page the member reads, and still one it does not', async () => {+ await withEnv({ [ENFORCED_MEMBER_ENV]: 'alice-example' }, async () => {+ const atom = b.pageSlug('al.atom')!;+ expect(JSON.stringify(await enforcedRead(b.engine, 'get', 'get_page', { slug: atom }, { sourceId: SRC }))).toContain(b.canary('al.atom'));+ expect(await namesHiddenPage(b.engine, 'get', { slug: atom })).toBe(false);+ expect(await namesHiddenPage(b.engine, 'get', { slug: b.pageSlug('team.atom')! })).toBe(true);+ await setMembersReadLineage(b.engine, false, { remote: false });+ __resetPrivateVisibilityCacheForTests();+ try {+ expect(await namesHiddenPage(b.engine, 'get', { slug: atom })).toBe(true);+ } finally {+ await setMembersReadLineage(b.engine, true, { remote: false });+ __resetPrivateVisibilityCacheForTests();+ }+ });+ }, 600_000);+test('the owner opt-in stays the owner\'s: it changes nothing for a member reading with lineage', async () => {await setOwnerReadsRestricted(b.engine, true, { remote: false });__resetPrivateVisibilityCacheForTests();@@ -160,6 +182,7 @@ for (const kind of testBackends()) {expect(await cli(['members-read-lineage', 'off'])).toMatchObject({ members_read_lineage: false });__resetPrivateVisibilityCacheForTests();for (const who of ['alice', 'bob', 'solo']) expect({ who, seen: await b.seenBy(who) }).toEqual({ who, seen: off[who]! });+ expect(await b.seenBy('alice-granted')).toEqual(off.alice);}, 600_000);});}