Skip to content

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.md
index 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.md
index 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 an
audience of that one member) reads a derived page or a fact when it reads every origin of it, on every read path and
in `--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 brain
operator 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 doctor
reports `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.ts
index 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, resu
walk(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.ts
index 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-visibility
import 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);
});
}