Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
GBRA-218 A1 step 1: caller-access record, mandatory readers predicate, member identity in dispatch
garrytan015b79c33268
diff --git a/src/core/access/caller.ts b/src/core/access/caller.tsnew file mode 100644index 0000000000..e1dbc4bf23--- /dev/null+++ b/src/core/access/caller.ts@@ -0,0 +1,46 @@+/**+ * GBRA-218: the caller-access record of one remote MCP operation. The+ * credential's verifier-derived principal (never a display name or request+ * data) names the token or OAuth client; its bound member, when the member is+ * live, plus that member's groups form the identity readers are checked+ * against. A brain with no member-access restriction skips the lookup.+ * Every failure (pre-migration schema, unreadable row, unknown member) yields+ * an empty identity, which reads no restricted page (fail closed).+ */+import type { BrainEngine } from '../engine.ts';+import type { AuthInfo } from '../ops/contract.ts';+import { accessRestrictionsPresent, remotePrivacyRelaxed, type CallerAccess } from '../search/private-visibility.ts';+import { identityFor, normalizePrincipal } from './principals.ts';++const MEMBER_SQL = (credential: string) => `SELECT m.id, COALESCE(array_agg(g.group_id ORDER BY g.group_id) FILTER (WHERE g.group_id IS NOT NULL), '{}') AS groups+ FROM access_members m LEFT JOIN access_group_members g ON g.member_id = m.id+ WHERE m.id = (${credential}) AND m.disabled_at IS NULL AND m.tombstoned_at IS NULL+ GROUP BY m.id`;++/** The member identity bound to `auth`'s principal; empty when unbound, unknown or unreadable. */+export async function memberIdentityFor(engine: BrainEngine, auth: AuthInfo | undefined): Promise<string[]> {+ const principal = auth?.principal;+ if (!principal) return [];+ const credential = principal.kind === 'legacy_token'+ ? 'SELECT member_id FROM access_tokens WHERE id::text = $1'+ : 'SELECT member_id FROM oauth_clients WHERE client_id = $1';+ try {+ const [row] = await engine.executeRaw<{ id: string; groups: string[] }>(MEMBER_SQL(credential), [principal.id]);+ if (!row || normalizePrincipal(`member:${row.id}`) !== `member:${row.id}`) return [];+ const groups = (row.groups ?? []).filter(g => normalizePrincipal(`group:${g}`) === `group:${g}`);+ return identityFor(row.id, groups);+ } catch {+ return [];+ }+}++/** The CallerAccess fields for a remote operation (identity, privacy relaxation and the GBRA-156 private-readable set). */+export async function remoteCallerAccess(engine: BrainEngine, auth: AuthInfo | undefined, privateSources: readonly string[] | undefined): Promise<Partial<CallerAccess>> {+ const [relaxed, restricted] = await Promise.all([remotePrivacyRelaxed(engine), accessRestrictionsPresent(engine)]);+ return {+ identity: restricted ? await memberIdentityFor(engine, auth) : [],+ privateReadableSources: privateSources ?? [],+ hidePrivate: !relaxed,+ applyRemoteReadPolicy: false,+ };+}diff --git a/src/core/access/principals.ts b/src/core/access/principals.tsnew file mode 100644index 0000000000..304167adcf--- /dev/null+++ b/src/core/access/principals.ts@@ -0,0 +1,67 @@+/**+ * GBRA-218: member and group principals for per-member read access.+ *+ * A page names its readers in frontmatter `readable_by` (a string or a list).+ * normalizeReaders() is the row twin of the SQL function gbrain_access_readers()+ * (schema migration v274); test/access-principals.test.ts holds the two equal+ * on a generated corpus, so the predicate and every TypeScript check agree.+ *+ * absent key → null (no page-level restriction)+ * valid string or list → sorted, distinct ['member:<id>' | 'group:<g>']+ * anything else → ['!nobody'] (present but malformed: readable by no remote caller)+ */++export const ACCESS_ID_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;+export const NOBODY = '!nobody';+const MAX_READERS = 256;++export type Principal = `member:${string}` | `group:${string}`;++/** One readers entry normalized, or null when it is not a valid principal. */+export function normalizePrincipal(raw: string): Principal | null {+ const v = raw.replace(/^ +| +$/g, '').replace(/[A-Z]/g, c => c.toLowerCase());+ if (v.startsWith('group:')) return ACCESS_ID_RE.test(v.slice(6)) ? v as Principal : null;+ const id = v.startsWith('member:') ? v.slice(7) : v;+ return ACCESS_ID_RE.test(id) ? `member:${id}` : null;+}++/** The normalized readers of a frontmatter object (see the module comment). */+export function normalizeReaders(frontmatter: unknown): string[] | null {+ if (typeof frontmatter !== 'object' || frontmatter === null || Array.isArray(frontmatter)) return null;+ if (!Object.prototype.hasOwnProperty.call(frontmatter, 'readable_by')) return null;+ const value = (frontmatter as Record<string, unknown>).readable_by;+ const list = typeof value === 'string' ? [value]+ : Array.isArray(value) && value.length >= 1 && value.length <= MAX_READERS && value.every(v => typeof v === 'string') ? value as string[]+ : null;+ if (!list) return [NOBODY];+ const out = new Set<string>();+ for (const entry of list) {+ const p = normalizePrincipal(entry);+ if (!p) return [NOBODY];+ out.add(p);+ }+ return [...out].sort();+}++/** True when the frontmatter names readers at all (valid or not). */+export function hasReaders(frontmatter: unknown): boolean {+ return typeof frontmatter === 'object' && frontmatter !== null+ && Object.prototype.hasOwnProperty.call(frontmatter, 'readable_by');+}++/** Whether a caller with `identity` may read a page carrying `frontmatter` at the page layer. */+export function readersAllow(frontmatter: unknown, identity: readonly string[]): boolean {+ const readers = normalizeReaders(frontmatter);+ if (readers === null) return true;+ return readers.some(r => identity.includes(r));+}++/** An identity set is safe to embed as SQL literals: every entry is a normalized principal. */+export function validIdentity(identity: readonly string[]): boolean {+ return identity.every(p => normalizePrincipal(p) === p);+}++/** The identity set of a member: itself plus each of its groups. */+export function identityFor(memberId: string, groups: readonly string[]): string[] {+ return [`member:${memberId}`, ...groups.map(g => `group:${g}`)].sort();+}diff --git a/src/core/engine-sql/pages.ts b/src/core/engine-sql/pages.tsindex 2005593a30..317affd78a 100644--- a/src/core/engine-sql/pages.ts+++ b/src/core/engine-sql/pages.ts@@ -22,7 +22,7 @@ import { moveSlugBindings, recordRenameAlias } from '../page-state/rename-alias.import { segmentedRevertRefusal } from '../page-state/versions.ts';import { sanitizeText } from '../batch-rows.ts';import { SAFE_FENCE_CHUNKER_VERSION, bodyWriteChunkVersion } from '../search/safe-chunks.ts';-import { orPrivateReadableSource, privatePagesFilterFragment, privateSnapshotFilterFragment, privatePagesFilterForCaller } from '../search/private-visibility.ts';+import { privatePagesFilterFragment, privateSnapshotFilterFragment, privatePagesFilterForCaller, privacyForCaller, readersAllowedSql, callerIdentity } from '../search/private-visibility.ts';import { quarantineFilterFragment } from '../quarantine.ts';import { rederiveHiddenSql } from '../eligibility/sql.ts';import { validateSlug, contentHash, isBlankBody, rowToPage, rowToStalePage, isMissingSchemaObject, warnOncePerProcess } from '../utils.ts';@@ -1011,7 +1011,7 @@ export async function getVersions<B extends boolean = true>(opts?: GetVersionsOpts<B>,): Promise<PageVersionRows<B>> {const privacy = opts?.excludePrivate- ? trustedSql(`AND ${orPrivateReadableSource('p.source_id', `${privatePagesFilterFragment('p')} AND ${privateSnapshotFilterFragment('pv')}`)}`) : sqlFragment``;+ ? trustedSql(`AND ${privatePagesFilterForCaller('p')} AND ${readersAllowedSql('pv', callerIdentity())} AND ${privacyForCaller('p.source_id', privateSnapshotFilterFragment('pv'))}`) : sqlFragment``;const scope = opts?.sourceIds && opts.sourceIds.length > 0? sqlFragment`AND p.source_id = ANY(${opts.sourceIds}::text[])`: opts?.sourceId ? sqlFragment`AND p.source_id = ${opts.sourceId}` : sqlFragment``;diff --git a/src/core/schema-migrations/latest.generated.ts b/src/core/schema-migrations/latest.generated.tsindex 1a209b9221..6d1e21ecc7 100644--- a/src/core/schema-migrations/latest.generated.ts+++ b/src/core/schema-migrations/latest.generated.ts@@ -4,4 +4,4 @@// The highest schema migration version (migrate.ts LATEST_VERSION), importable without// loading the migrations themselves.-export const LATEST_SCHEMA_VERSION = 273;+export const LATEST_SCHEMA_VERSION = 274;diff --git a/src/core/schema-migrations/registry.generated.ts b/src/core/schema-migrations/registry.generated.tsindex 97a2b0ea61..667e31f41d 100644--- a/src/core/schema-migrations/registry.generated.ts+++ b/src/core/schema-migrations/registry.generated.ts@@ -274,6 +274,7 @@ import { v270 } from './v270-pages-source-created-index.ts';import { v271 } from './v271-facts-superseded-by-index.ts';import { v272 } from './v272-git-canonical-declared.ts';import { v273 } from './v273-principal-private-pages.ts';+import { v274 } from './v274-member-read-access.ts';// Array order is historical (see HISTORICAL_ARRAY_ORDER in the generator); the// runner sorts by version before applying.@@ -546,4 +547,5 @@ export const MIGRATIONS: Migration[] = [v271,v272,v273,+ v274,];diff --git a/src/core/schema-migrations/v274-member-read-access.ts b/src/core/schema-migrations/v274-member-read-access.tsnew file mode 100644index 0000000000..5955dad7d8--- /dev/null+++ b/src/core/schema-migrations/v274-member-read-access.ts@@ -0,0 +1,88 @@+import type { Migration } from './types.ts';++// Applied by src/core/migrate.ts on the next initSchema(); see docs/ENGINES.md+// ("Canonical schema sources") for when schema.sql or a TS fragment also changes.+//+// GBRA-218: per-member read access inside one source. Members and groups name+// people; a token or OAuth client may be bound to one member (member_id) and,+// for shared agents, list whom it may act for (may_act_for). A page names its+// readers in frontmatter `readable_by`; gbrain_access_readers() is the one SQL+// normalization of that value (src/core/access/principals.ts is its row twin,+// and test/access-principals.test.ts holds them equal). It reads the live+// frontmatter, so no writer, rename or backfill can leave a stale copy. Nothing+// is rewritten on upgrade. A trigger sets config access.restrictions_present+// once any page names readers or any member exists (sticky), so a brain with no+// restriction keeps every pre-GBRA-218 read path and escape hatch exactly.+// No schema.sql mirror: like v273, these exist only+// through migrations. Provisional number: renumbered at the merge slot.+export const v274: Migration = {+ version: 274,+ name: 'member_read_access',+ idempotent: true,+ sql: `+CREATE TABLE IF NOT EXISTS access_members (+ id TEXT PRIMARY KEY CHECK (id ~ '^[a-z0-9][a-z0-9._-]{0,63}$'),+ display_name TEXT,+ disabled_at TIMESTAMPTZ,+ tombstoned_at TIMESTAMPTZ,+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now()+);+CREATE TABLE IF NOT EXISTS access_groups (+ id TEXT PRIMARY KEY CHECK (id ~ '^[a-z0-9][a-z0-9._-]{0,63}$'),+ created_at TIMESTAMPTZ NOT NULL DEFAULT now()+);+CREATE TABLE IF NOT EXISTS access_group_members (+ group_id TEXT NOT NULL REFERENCES access_groups(id) ON DELETE CASCADE,+ member_id TEXT NOT NULL REFERENCES access_members(id) ON DELETE CASCADE,+ PRIMARY KEY (group_id, member_id)+);+CREATE INDEX IF NOT EXISTS access_group_members_member_idx ON access_group_members (member_id);+ALTER TABLE access_tokens ADD COLUMN IF NOT EXISTS member_id TEXT;+ALTER TABLE access_tokens ADD COLUMN IF NOT EXISTS may_act_for TEXT[];+ALTER TABLE oauth_clients ADD COLUMN IF NOT EXISTS member_id TEXT;+ALTER TABLE oauth_clients ADD COLUMN IF NOT EXISTS may_act_for TEXT[];+CREATE OR REPLACE FUNCTION gbrain_access_norm_readers(vals TEXT[]) RETURNS TEXT[]+ LANGUAGE sql IMMUTABLE PARALLEL SAFE SET search_path = pg_catalog AS $fn$+ SELECT CASE WHEN count(*) > 0 AND bool_and(n IS NOT NULL) THEN array_agg(DISTINCT n COLLATE "C" ORDER BY n COLLATE "C") ELSE ARRAY['!nobody'] END+ FROM (+ SELECT CASE+ WHEN v ~ '^(member:)?[a-z0-9][a-z0-9._-]{0,63}$' THEN 'member:' || regexp_replace(v, '^member:', '')+ WHEN v ~ '^group:[a-z0-9][a-z0-9._-]{0,63}$' THEN v+ ELSE NULL END AS n+ FROM (SELECT translate(btrim(x, ' '), 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz') AS v FROM unnest(vals) AS x) AS raw+ ) AS normalized+$fn$;+CREATE OR REPLACE FUNCTION gbrain_access_readers(fm JSONB) RETURNS TEXT[]+ LANGUAGE sql IMMUTABLE PARALLEL SAFE SET search_path = pg_catalog, public AS $fn$+ SELECT CASE+ WHEN fm IS NULL OR jsonb_typeof(fm) <> 'object' OR NOT (fm ? 'readable_by') THEN NULL+ WHEN jsonb_typeof(fm->'readable_by') = 'string' THEN gbrain_access_norm_readers(ARRAY[fm->>'readable_by'])+ WHEN jsonb_typeof(fm->'readable_by') = 'array'+ AND jsonb_array_length(fm->'readable_by') BETWEEN 1 AND 256+ AND NOT EXISTS (SELECT 1 FROM jsonb_array_elements(fm->'readable_by') AS e WHERE jsonb_typeof(e) <> 'string')+ THEN gbrain_access_norm_readers(ARRAY(SELECT jsonb_array_elements_text(fm->'readable_by')))+ ELSE ARRAY['!nobody'] END+$fn$;+CREATE OR REPLACE FUNCTION gbrain_access_mark_restricted() RETURNS trigger+ LANGUAGE plpgsql SET search_path = pg_catalog, public AS $fn$+BEGIN+ IF NOT EXISTS (SELECT 1 FROM config WHERE key = 'access.restrictions_present' AND value = '1') THEN+ INSERT INTO config (key, value) VALUES ('access.restrictions_present', '1')+ ON CONFLICT (key) DO UPDATE SET value = '1';+ END IF;+ RETURN NULL;+END+$fn$;+DROP TRIGGER IF EXISTS pages_access_mark_restricted ON pages;+CREATE TRIGGER pages_access_mark_restricted AFTER INSERT OR UPDATE OF frontmatter ON pages+ FOR EACH ROW WHEN (NEW.frontmatter ? 'readable_by') EXECUTE FUNCTION gbrain_access_mark_restricted();+DROP TRIGGER IF EXISTS access_members_mark_restricted ON access_members;+CREATE TRIGGER access_members_mark_restricted AFTER INSERT ON access_members+ FOR EACH ROW EXECUTE FUNCTION gbrain_access_mark_restricted();+INSERT INTO config (key, value)+ SELECT 'access.restrictions_present', '1'+ WHERE EXISTS (SELECT 1 FROM pages WHERE frontmatter ? 'readable_by') OR EXISTS (SELECT 1 FROM access_members)+ ON CONFLICT (key) DO UPDATE SET value = '1';+`,+};diff --git a/src/core/search/mode.ts b/src/core/search/mode.tsindex 1e0b51ef0a..da00404b1e 100644--- a/src/core/search/mode.ts+++ b/src/core/search/mode.ts@@ -27,7 +27,7 @@ import { normalizeChainSlots } from './relational-chain.ts';import { createHash } from 'crypto';import { CR_MODES, type CRMode } from '../types.ts';import { getFtsLanguage } from '../fts-language.ts';-import { privateReadableSources } from './private-visibility.ts';+import { privateReadableSources, currentCallerAccess } from './private-visibility.ts';import { loadConfigSnapshot, type BulkConfigReader } from '../config-snapshot.ts';import { pickDecideConfig } from '../ai/decide/config.ts';import { getRecipe } from '../ai/recipes/index.ts';@@ -1305,6 +1305,13 @@ export function knobsHash(// set (read here so every knobsHash() caller is covered); an empty set adds no part and keeps the key.const privateReadable = ctx?.excludePrivate === true ? privateReadableSources() : [];if (privateReadable.length) parts.push(`xpr=${[...privateReadable].sort().join(',')}`);+ // GBRA-218 (append-only, no bump): a read under the read policy keys on its member identity (sorted at+ // record time) and on an operator privacy relaxation; an unbound, unrelaxed read adds no part.+ if (ctx?.excludePrivate === true) {+ const access = currentCallerAccess();+ if (access.identity.length) parts.push(`xid=${createHash('sha256').update(access.identity.join(',')).digest('hex').slice(0, 16)}`);+ if (!access.hidePrivate) parts.push('xhp=0');+ }const h = createHash('sha256');h.update(parts.join('|'));return h.digest('hex').slice(0, 16);diff --git a/src/core/search/private-visibility.ts b/src/core/search/private-visibility.tsindex 0e1e8b49e0..75b0301b71 100644--- a/src/core/search/private-visibility.ts+++ b/src/core/search/private-visibility.ts@@ -23,6 +23,7 @@import { AsyncLocalStorage } from 'node:async_hooks';import type { BrainEngine } from '../engine.ts';import { isValidSourceId } from '../source-id.ts';+import { hasReaders, readersAllow, validIdentity } from '../access/principals.ts';export const REMOTE_PRIVATE_PAGES_KEY = 'search.remote_private_pages';@@ -46,11 +47,71 @@ function derivedPageSql(pageAlias: string): string {* is a code-provided literal, never user input.*/export function privatePagesFilterFragment(pageAlias: string): string {+ return `(${accessAllowedSql(pageAlias, [])} AND ${privacyPartSql(pageAlias)})`;+}++/** The privacy rules alone (visibility, aliases, pinned questions, lineage): what the escape hatches and granted_sources may relax. */+function privacyPartSql(pageAlias: string): string {return `(${privateSnapshotFilterFragment(pageAlias)}AND NOT ${derivedOriginPrivateSql(pageAlias)}AND NOT ${declaredLineagePrivateSql(pageAlias)})`;}+/**+ * GBRA-218: the mandatory member-access predicate. A page that names readers+ * in frontmatter `readable_by` passes only for a caller whose identity+ * (`member:<id>` and its `group:<g>` entries) meets them, through the one SQL+ * normalization gbrain_access_readers() (malformed values read as nobody). A+ * page derived from a page that names readers is readable by no remote caller+ * (originRestrictedSql). No escape hatch, operator opt-out or granted source+ * relaxes this part; with an empty identity it hides every restricted page.+ * `identity` must pass validIdentity (its alphabet has no quote), so it is+ * embedded as literals; anything else empties it (fail closed).+ */+export function accessAllowedSql(pageAlias: string, identity: readonly string[]): string {+ return `(${readersAllowedSql(pageAlias, identity)} AND NOT ${originRestrictedSql(pageAlias)})`;+}++/** The readers test alone on any row with a `frontmatter` column (a page or a version snapshot), without lineage. */+export function readersAllowedSql(alias: string, identity: readonly string[]): string {+ const ids = identity.length && validIdentity(identity) ? identity : [];+ const listed = ids.length ? ` OR gbrain_access_readers(${alias}.frontmatter) && ARRAY[${ids.map(id => `'${id}'`).join(', ')}]::text[]` : '';+ return `(${alias}.frontmatter->'readable_by' IS NULL${listed})`;+}++/** A page names readers (valid or not); SQL twin of hasReaders. */+function namesReadersSql(alias: string): string {+ return `(${alias}.frontmatter->'readable_by' IS NOT NULL)`;+}++/**+ * GBRA-218 (plan D4): a derived page whose origin names readers is readable+ * by no remote caller, members included, whatever its own fields say: an atom+ * of such a page, a synthesized concept with such an input (or an input+ * atom's origin), a Life Chronicle event extracted from one, or a page whose+ * declared `derived_from` names one. Read-time, so derivatives written before+ * the origin gained readers are covered; new derivations are stamped private+ * by isDerivationPrivate.+ */+function originRestrictedSql(p: string): string {+ const restrictedOrigin = (atom: string, alias: string) => `EXISTS (SELECT 1 FROM pages ${alias} WHERE ${alias}.source_id = ${atom}.source_id+ AND ${alias}.slug = ${atom}.frontmatter->>'source_slug' AND ${namesReadersSql(alias)})`;+ return `((CASE WHEN ${p}.type = 'atom' THEN ${restrictedOrigin(p, 'acl_origin')}+ WHEN ${derivedPageSql(p)} THEN EXISTS (SELECT 1 FROM links acl_input_link+ JOIN pages acl_input ON acl_input.id = acl_input_link.to_page_id+ WHERE acl_input_link.from_page_id = ${p}.id AND acl_input_link.link_source = 'concept-provenance'+ AND acl_input_link.link_type = 'synthesized_from'+ AND (${namesReadersSql('acl_input')} OR ${restrictedOrigin('acl_input', 'acl_input_origin')}))+ WHEN ${p}.type = 'event' AND ${p}.frontmatter->>'captured_via' LIKE 'life-chronicle:%' THEN EXISTS (SELECT 1 FROM pages acl_chronicle+ WHERE acl_chronicle.source_id = ${p}.source_id AND acl_chronicle.slug = ${p}.frontmatter->'event'->>'depth' AND ${namesReadersSql('acl_chronicle')})+ ELSE false END)+ OR (CASE WHEN jsonb_typeof(${p}.frontmatter->'derived_from') IN ('array', 'string') THEN EXISTS (+ SELECT 1 FROM pages acl_declared WHERE acl_declared.source_id = ${p}.source_id AND ${namesReadersSql('acl_declared')}+ AND acl_declared.slug = ANY(ARRAY(SELECT regexp_replace(declared.slug, '\\.md$', '') FROM jsonb_array_elements_text(+ CASE WHEN jsonb_typeof(${p}.frontmatter->'derived_from') = 'array' THEN ${p}.frontmatter->'derived_from'+ ELSE jsonb_build_array(${p}.frontmatter->'derived_from') END) AS declared(slug)))) ELSE false END))`;+}+/*** `privatePagesFilterFragment` with a cheap first test: a page with no* `visibility` or `derived_from` key (nor, unless the operator turned@@ -61,36 +122,79 @@ export function privatePagesFilterFragment(pageAlias: string): string {export function privatePagesFilterFragmentFast(pageAlias: string): string {return `((${pageAlias}.frontmatter->'visibility' IS NULL AND ${pageAlias}.frontmatter->'derived_from' IS NULL${honorAliases()? `\n AND ${pageAlias}.frontmatter->'access' IS NULL AND ${pageAlias}.frontmatter->'confidentiality' IS NULL` : ''}+ AND ${pageAlias}.frontmatter->'readable_by' IS NULLAND ${pageAlias}.type NOT IN ('atom', 'concept', 'event'))OR ${privatePagesFilterFragment(pageAlias)})`;}/**- * GBRA-156: the sources whose private pages the current remote read may see,- * from its grant's `private_pages: granted_sources` axis (the sources the- * grant names explicitly; never the no-grant floor, federation, an OAuth- * client's bound source or a request's `source_ids`). Set only by MCP- * dispatch around a non-mutating operation; empty everywhere else (local- * CLI, writes, jobs, cycles), so every other path keeps the rule above.+ * The current caller's access record. MCP dispatch sets it around every remote+ * operation (src/mcp/dispatch.ts), and a local `--as <member>` read sets it+ * with applyRemoteReadPolicy. Fields:+ * - identity: GBRA-218, the caller's member and group principals (empty when+ * the credential is bound to no member);+ * - privateReadableSources: GBRA-156, the sources whose private pages the read+ * may see, from its grant's `private_pages: granted_sources` axis (never the+ * no-grant floor, federation, an OAuth client's bound source or a request's+ * `source_ids`); empty for writes;+ * - hidePrivate: false only when an operator relaxed privacy for remote reads+ * (GBRAIN_REMOTE_PRIVATE_PAGES=1 or search.remote_private_pages=visible).+ * Outside any record (local CLI, jobs, cycles) the identity is empty, no+ * source is private-readable and hidePrivate follows the process's hatch+ * state, so caller-aware fragments still fail closed on restricted pages.*/-const privateReadable = new AsyncLocalStorage<readonly string[]>();+export interface CallerAccess {+ identity: readonly string[];+ privateReadableSources: readonly string[];+ hidePrivate: boolean;+ applyRemoteReadPolicy: boolean;+}+const callerAccessStore = new AsyncLocalStorage<CallerAccess>();++/** The current read's caller-access record (see CallerAccess). */+export function currentCallerAccess(): CallerAccess {+ return callerAccessStore.getStore() ?? { identity: [], privateReadableSources: [], hidePrivate: !processPrivacyRelaxed(), applyRemoteReadPolicy: false };+}++/** Runs `fn` under `access` merged over the current record; an invalid identity or source id empties that set (fail closed). */+export function withCallerAccess<T>(access: Partial<CallerAccess>, fn: () => T): T {+ const base = currentCallerAccess();+ const identity = access.identity ?? base.identity;+ const sources = access.privateReadableSources ?? base.privateReadableSources;+ return callerAccessStore.run(Object.freeze({+ identity: identity.length && validIdentity(identity) ? Object.freeze([...new Set(identity)].sort()) : Object.freeze([]),+ privateReadableSources: sources.length && sources.every(isValidSourceId) ? Object.freeze([...new Set(sources)]) : Object.freeze([]),+ hidePrivate: access.hidePrivate ?? base.hidePrivate,+ applyRemoteReadPolicy: access.applyRemoteReadPolicy ?? base.applyRemoteReadPolicy,+ }), fn);+}++/** Runs `fn` outside any caller's record, for work a request spawns that must not inherit its view. */+export function withoutCallerAccess<T>(fn: () => T): T {+ return callerAccessStore.exit(fn);+}/** Runs `fn` with `sourceIds` as the private-readable set; an invalid id empties the whole set (fail closed). */export function withPrivateReadableSources<T>(sourceIds: readonly string[] | undefined, fn: () => T): T {- const ids = sourceIds?.length && sourceIds.every(isValidSourceId) ? Object.freeze([...new Set(sourceIds)]) : Object.freeze([]);- return privateReadable.run(ids, fn);+ return withCallerAccess({ privateReadableSources: sourceIds ?? [] }, fn);}/** The private-readable set of the current read; empty outside a granted remote read. */export function privateReadableSources(): readonly string[] {- return privateReadable.getStore() ?? [];+ return currentCallerAccess().privateReadableSources;+}++/** The current caller's member identity; empty outside a bound remote read or a local --as. */+export function callerIdentity(): readonly string[] {+ return currentCallerAccess().identity;}/**- * `visiblePredicate`, widened to rows whose source (`sourceIdSql`, a- * code-provided column reference) is in the current private-readable set.- * The ids are embedded as literals: each passed isValidSourceId, whose- * alphabet has no quote or backslash.+ * `visiblePredicate` (a privacy-only predicate), widened to rows whose source+ * (`sourceIdSql`, a code-provided column reference) is in the current+ * private-readable set. Never pass a predicate that contains accessAllowedSql:+ * the widening would reach it. The ids are embedded as literals: each passed+ * isValidSourceId, whose alphabet has no quote or backslash.*/export function orPrivateReadableSource(sourceIdSql: string, visiblePredicate: string): string {const ids = privateReadableSources();@@ -98,20 +202,48 @@ export function orPrivateReadableSource(sourceIdSql: string, visiblePredicate: sreturn `(${sourceIdSql} IN (${ids.map(id => `'${id}'`).join(', ')}) OR ${visiblePredicate})`;}-/** privatePagesFilterFragment for a remote read: a page in a private-readable source passes. Read sites only; derived-visibility decisions keep the plain fragment. */+/**+ * A privacy-only predicate for the current caller: TRUE when an operator+ * relaxed privacy, else widened only to private-readable sources. Never pass+ * a predicate that contains accessAllowedSql or readersAllowedSql.+ */+export function privacyForCaller(sourceIdSql: string, privacyPredicate: string): string {+ return currentCallerAccess().hidePrivate ? orPrivateReadableSource(sourceIdSql, privacyPredicate) : 'TRUE';+}++function callerPrivacySql(pageAlias: string, privacyPredicate: string): string {+ return privacyForCaller(`${pageAlias}.source_id`, privacyPredicate);+}++/** privatePagesFilterFragment for a remote read: the caller's member access, then the privacy part with its grant and hatch. Read sites only; derived-visibility decisions keep the plain fragment. */export function privatePagesFilterForCaller(pageAlias: string): string {- return orPrivateReadableSource(`${pageAlias}.source_id`, privatePagesFilterFragment(pageAlias));+ return `(${accessAllowedSql(pageAlias, callerIdentity())} AND ${callerPrivacySql(pageAlias, privacyPartSql(pageAlias))})`;}/** privatePagesFilterFragmentFast for a remote read. */export function privatePagesFilterFastForCaller(pageAlias: string): string {- return orPrivateReadableSource(`${pageAlias}.source_id`, privatePagesFilterFragmentFast(pageAlias));+ return `(${accessAllowedSql(pageAlias, callerIdentity())} AND ${callerPrivacySql(pageAlias, privacyPartFastSql(pageAlias))})`;}-/** isPrivatePage for a remote read: false for a page whose `source_id` is private-readable; a row without `source_id` keeps the plain rule. */+/** The fast form of privacyPartSql (see privatePagesFilterFragmentFast). */+function privacyPartFastSql(pageAlias: string): string {+ return `((${pageAlias}.frontmatter->'visibility' IS NULL AND ${pageAlias}.frontmatter->'derived_from' IS NULL${honorAliases()+ ? `\n AND ${pageAlias}.frontmatter->'access' IS NULL AND ${pageAlias}.frontmatter->'confidentiality' IS NULL` : ''}+ AND ${pageAlias}.type NOT IN ('atom', 'concept', 'event'))+ OR ${privacyPartSql(pageAlias)})`;+}++/**+ * isPrivatePage for a remote read: true when the page names readers the+ * caller does not meet; otherwise the privacy rule, false for a page whose+ * `source_id` is private-readable or when an operator relaxed privacy. A row+ * without `source_id` keeps the plain privacy rule.+ */export function isPrivatePageForCaller(page: { type?: string | null; frontmatter?: unknown; source_id?: string | null }): boolean {- if (!isPrivatePage(page)) return false;- return !(typeof page.source_id === 'string' && privateReadableSources().includes(page.source_id));+ const access = currentCallerAccess();+ if (!readersAllow(page.frontmatter, access.identity)) return true;+ if (!access.hidePrivate || !isPrivacyPrivatePage(page)) return false;+ return !(typeof page.source_id === 'string' && access.privateReadableSources.includes(page.source_id));}/**@@ -246,7 +378,7 @@ export function isDerivationPrivate(page: { type?: string | null; frontmatter?:/** SQL twin of isDerivationPrivate. */export function derivationPrivateSql(alias: string): string {- return `(NOT ${privateSnapshotFilterFragment(alias)} OR ${privacyAliasSql(alias)})`;+ return `(NOT ${privateSnapshotFilterFragment(alias)} OR ${privacyAliasSql(alias)} OR ${namesReadersSql(alias)})`;}/**@@ -322,6 +454,11 @@ export function privateProvenanceFilterFragment(factAlias: string): string {* page, and an absent value hides only derived atoms and concepts.*/export function isPrivatePage(page: { type?: string | null; frontmatter?: unknown }): boolean {+ return hasReaders(page.frontmatter) || isPrivacyPrivatePage(page);+}++/** isPrivatePage without the member-access rule: visibility, aliases and pinned questions only. */+function isPrivacyPrivatePage(page: { type?: string | null; frontmatter?: unknown }): boolean {const frontmatter = typeof page.frontmatter === 'object' && page.frontmatter !== null? page.frontmatter as Record<string, unknown> : {};if (frontmatter.pinned_question != null) return true;@@ -371,39 +508,80 @@ export async function findPrivateOnlySlugs(const CACHE_TTL_MS = 30_000;let cache = new WeakMap<BrainEngine, { at: number; expose: boolean }>();+const exposeEngines = new Set<BrainEngine>();+const strictEngines = new Set<BrainEngine>();++/** GBRA-218: set once a page names readers or a member exists (sticky; a trigger and `gbrain access` write it). */+export const ACCESS_RESTRICTIONS_KEY = 'access.restrictions_present';/** Test helper: drop the per-engine config cache. */export function __resetPrivateVisibilityCacheForTests(): void {cache = new WeakMap();honorAliasEngines.clear();aliasOptOutEngines.clear();+ exposeEngines.clear();+ strictEngines.clear();+}++/**+ * The process-wide privacy relaxation used when no caller record exists:+ * the env hatch, or a brain that opted out while none in this process stayed+ * strict (the same lean-private rule as visibility.honor_aliases).+ */+function processPrivacyRelaxed(): boolean {+ return process.env.GBRAIN_REMOTE_PRIVATE_PAGES === '1' || (exposeEngines.size > 0 && strictEngines.size === 0);+}++/**+ * Has an operator relaxed privacy for remote reads on this brain+ * (GBRAIN_REMOTE_PRIVATE_PAGES=1 or search.remote_private_pages=visible)?+ * The only reader of either switch: every privacy decision comes through here+ * or through resolveExcludePrivatePages. Config lookups are cached 30s per+ * engine; a failed lookup counts as "not relaxed" (fail-closed).+ */+export async function remotePrivacyRelaxed(engine: BrainEngine): Promise<boolean> {+ if (process.env.GBRAIN_REMOTE_PRIVATE_PAGES === '1') return true; // incident escape hatch+ const hit = cache.get(engine);+ if (hit && Date.now() - hit.at < CACHE_TTL_MS) return hit.expose;+ let expose: boolean;+ try {+ const v = await engine.getConfig(REMOTE_PRIVATE_PAGES_KEY);+ expose = v === 'visible' || v === 'true' || v === '1';+ } catch {+ expose = false; // config unreadable → enforce (fail-closed)+ }+ await readHonorAliases(engine);+ cache.set(engine, { at: Date.now(), expose });+ (expose ? exposeEngines : strictEngines).add(engine);+ (expose ? strictEngines : exposeEngines).delete(engine);+ return expose;+}++/** GBRA-218: does this brain hold member-access restrictions? Read live (the request snapshot answers it inside a read); unreadable counts as yes. */+export async function accessRestrictionsPresent(engine: BrainEngine): Promise<boolean> {+ try {+ return (await engine.getConfig(ACCESS_RESTRICTIONS_KEY)) === '1';+ } catch {+ return true;+ }}/**- * Should this caller's page reads exclude `visibility: private` pages?- * `remote` follows the repo trust convention: anything that is not strictly- * `false` is untrusted. Config lookups are cached 30s per engine; a failed- * lookup counts as "not opted out" (fail-closed).+ * Should this caller's page reads apply the read-policy fragment+ * (`excludePrivate`)? `remote` follows the repo trust convention: anything+ * that is not strictly `false` is untrusted. A trusted local caller applies+ * it only under a local `--as <member>` record. A remote caller always+ * applies it, except when an operator relaxed privacy and the brain holds no+ * member-access restriction, where the hatches keep their pre-GBRA-218+ * meaning. With restrictions present the fragment still applies under a+ * hatch: caller-aware fragments relax only their privacy part, and the+ * member-access part (accessAllowedSql) stays mandatory.*/export async function resolveExcludePrivatePages(engine: BrainEngine,remote: boolean | undefined,): Promise<boolean> {- if (remote === false) return false; // trusted local CLI sees everything- if (process.env.GBRAIN_REMOTE_PRIVATE_PAGES === '1') return false; // incident escape hatch- const hit = cache.get(engine);- let expose: boolean;- if (hit && Date.now() - hit.at < CACHE_TTL_MS) {- expose = hit.expose;- } else {- try {- const v = await engine.getConfig(REMOTE_PRIVATE_PAGES_KEY);- expose = v === 'visible' || v === 'true' || v === '1';- } catch {- expose = false; // config unreadable → enforce (fail-closed)- }- await readHonorAliases(engine);- cache.set(engine, { at: Date.now(), expose });- }- return !expose;+ if (remote === false) return currentCallerAccess().applyRemoteReadPolicy;+ if (!await remotePrivacyRelaxed(engine)) return true;+ return accessRestrictionsPresent(engine);}diff --git a/src/core/verbs/entity-card.ts b/src/core/verbs/entity-card.tsindex 081b41d1ce..1cfa4f6509 100644--- a/src/core/verbs/entity-card.ts+++ b/src/core/verbs/entity-card.ts@@ -306,10 +306,10 @@ export async function selectEntityCandidates(scope: EntityLookupScope,opts: { omitQuarantined?: boolean; suggest?: boolean; variants?: boolean } = {},): Promise<EntityCandidates> {- const { orPrivateReadableSource, privatePagesFilterFragment, privatePagesFilterForCaller } = await import('../search/private-visibility.ts');+ const { privatePagesFilterForCaller } = await import('../search/private-visibility.ts');// Predicate text lives ONCE (private-visibility.ts) — both card queries// below select `FROM pages` unaliased, so qualify with the table name.- const privatePredicate = scope.excludePrivate ? ` AND ${orPrivateReadableSource('pages.source_id', privatePagesFilterFragment('pages'))}` : '';+ const privatePredicate = scope.excludePrivate ? ` AND ${privatePagesFilterForCaller('pages')}` : '';const norm = normalizeAlias(trimmed);const titleLc = trimmed.toLowerCase();diff --git a/src/mcp/dispatch.ts b/src/mcp/dispatch.tsindex b681058237..b7707869cb 100644--- a/src/mcp/dispatch.ts+++ b/src/mcp/dispatch.ts@@ -14,7 +14,8 @@ import type { OperationContext, AuthInfo } from '../core/operations.ts';import type { OperationMeta } from '../core/ops/contract.ts';import { loadConfig } from '../core/config.ts';import { withRequestConfigSnapshot, withoutRequestConfigSnapshot } from '../core/config-snapshot.ts';-import { withPrivateReadableSources } from '../core/search/private-visibility.ts';+import { withCallerAccess } from '../core/search/private-visibility.ts';+import { remoteCallerAccess } from '../core/access/caller.ts';import { resolveBrainId } from '../core/brain-resolver.ts';import { getCliOptions } from '../core/cli-options.ts';import { VERB_NAMES, MEMORY_VERBS_VERSION } from '../core/verbs.ts';@@ -897,7 +898,11 @@ export async function dispatchToolCall(const readOnly = operations.find(o => o.name === name)?.mutating === false;const privateSources = readOnly && opts.remote !== false && !WORLD_ONLY_PACK_OPS.has(name) ? opts.auth?.privatePages?.sources : undefined;const resolved = opts.metaHook && (opts.hotMemoryOff === true || hotMemoryOffIn(params)) ? { ...opts, metaHook: undefined } : opts;- const run = () => withPrivateReadableSources(privateSources, () => withRequestIdentityMemo(() => dispatchResolvedCall(engine, name, params, resolved)));+ // GBRA-218: a remote call also carries its credential's member identity, which every caller-aware read checks page readers against.+ const run = async () => {+ const access = opts.remote === false ? { privateReadableSources: [] } : await remoteCallerAccess(engine, opts.auth, privateSources);+ return withCallerAccess(access, () => withRequestIdentityMemo(() => dispatchResolvedCall(engine, name, params, resolved)));+ };if (name === 'search' || name === 'query') return withSearchConnectionBudget(() => withRequestConfigSnapshot(engine, run));return readOnly? withRequestConfigSnapshot(engine, run)diff --git a/test/access-principals.test.ts b/test/access-principals.test.tsnew file mode 100644index 0000000000..7949a4ac70--- /dev/null+++ b/test/access-principals.test.ts@@ -0,0 +1,78 @@+/**+ * GBRA-218: readers normalization parity.+ *+ * 1. Protects: the SQL function gbrain_access_readers() (migration v274),+ * which every read predicate uses, and normalizeReaders(), which every+ * TypeScript check (isPrivatePage, isPrivatePageForCaller) uses, return the+ * same readers for the same frontmatter.+ * 2. Fails when: either side accepts, rejects, trims, case-folds, dedupes or+ * orders a readable_by value differently, so a page could read as+ * restricted on one path and open on another.+ * 3. Real seams: the migrated PGLite schema; a generated corpus of valid,+ * malformed and edge-case values, compared row by row.+ */+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';+import { PGLiteEngine } from '../src/core/pglite-engine.ts';+import { NOBODY, hasReaders, normalizePrincipal, normalizeReaders, readersAllow } from '../src/core/access/principals.ts';++let engine: PGLiteEngine;+beforeAll(async () => {+ engine = new PGLiteEngine();+ await engine.connect({});+ await engine.initSchema();+});+afterAll(async () => { await engine.disconnect(); });++const ENTRIES = ['alice-example', 'Alice-Example', ' bob-example ', 'member:carol', 'MEMBER:carol', 'group:team-a', 'GROUP:Team-A',+ 'group:', 'member:', '', ' ', '\tdan', 'dan\n', 'eve example', 'a.b_c-d', '-lead', '.lead', 'x'.repeat(64), 'y'.repeat(65),+ 'group:group:x', 'member:group:x', 'member:member:x', 'k\u212Aelvin', 'caf\u00e9', 'İstanbul', 'zed:z', '0', 'group:0'];++function corpus(): unknown[] {+ const out: unknown[] = [{}, { title: 'x' }, { readable_by: null }, { readable_by: [] }, { readable_by: 7 }, { readable_by: true },+ { readable_by: { member: 'a' } }, { readable_by: ['alice-example', 3] }, { readable_by: ['alice-example', null] },+ { readable_by: Array.from({ length: 256 }, (_, i) => `m${i}`) }, { readable_by: Array.from({ length: 257 }, (_, i) => `m${i}`) },+ { readable_by: ['b', 'a', 'B', 'member:a'] }, { readable_by: ['a.b', 'a-b', 'a_b', 'a0', 'group:a'] }];+ for (const e of ENTRIES) out.push({ readable_by: e }, { readable_by: [e] }, { readable_by: [e, 'alice-example'] });+ for (let i = 0; i < ENTRIES.length; i++) out.push({ readable_by: [ENTRIES[i], ENTRIES[(i * 7 + 3) % ENTRIES.length], ENTRIES[(i * 11 + 5) % ENTRIES.length]] });+ return out;+}++describe('gbrain_access_readers parity', () => {+ test('SQL and TypeScript normalize every corpus value identically', async () => {+ const values = corpus();+ const rows = await engine.executeRaw<{ i: number; readers: string[] | null }>(+ `SELECT (v.ordinality - 1)::int AS i, gbrain_access_readers(v.value) AS readers FROM jsonb_array_elements($1::jsonb) WITH ORDINALITY AS v`,+ [JSON.stringify(values)]);+ expect(rows.length).toBe(values.length);+ const mismatches = rows.filter(r => JSON.stringify(r.readers) !== JSON.stringify(normalizeReaders(values[r.i])))+ .map(r => ({ value: values[r.i], sql: r.readers, ts: normalizeReaders(values[r.i]) }));+ expect(mismatches).toEqual([]);+ });++ test('a non-object frontmatter names no readers on either side', async () => {+ for (const fm of [null, [], ['readable_by'], 'readable_by', 3]) {+ const [row] = await engine.executeRaw<{ readers: string[] | null }>('SELECT gbrain_access_readers($1::jsonb) AS readers', [JSON.stringify(fm)]);+ expect(row.readers).toBeNull();+ expect(normalizeReaders(fm)).toBeNull();+ }+ });+});++describe('principal rules', () => {+ test('bare ids are members; prefixes and ASCII case fold; anything else is invalid', () => {+ expect(normalizePrincipal('Alice-Example')).toBe('member:alice-example');+ expect(normalizePrincipal('GROUP:Team-A')).toBe('group:team-a');+ expect(normalizePrincipal('k\u212Aelvin')).toBeNull();+ expect(normalizePrincipal('\tdan')).toBeNull();+ expect(normalizePrincipal('member:group:x')).toBeNull();+ });++ test('a malformed readers value reads as nobody, and nobody is no identity', () => {+ expect(normalizeReaders({ readable_by: ['alice-example', 'not valid'] })).toEqual([NOBODY]);+ expect(readersAllow({ readable_by: 'not valid' }, ['member:alice-example', NOBODY.slice(1)])).toBe(false);+ expect(hasReaders({ readable_by: null })).toBe(true);+ expect(readersAllow({ readable_by: ['group:team-a'] }, ['member:bob-example', 'group:team-a'])).toBe(true);+ expect(readersAllow({ readable_by: ['group:team-a'] }, [])).toBe(false);+ expect(readersAllow({ title: 'open' }, [])).toBe(true);+ });+});diff --git a/test/member-read-access.test.ts b/test/member-read-access.test.tsnew file mode 100644index 0000000000..984e44755e--- /dev/null+++ b/test/member-read-access.test.ts@@ -0,0 +1,232 @@+/**+ * GBRA-218: per-member read access inside one source (frontmatter readable_by).+ *+ * 1. Protects: a page that names readers is read remotely only by a credential+ * bound to a live member those readers name (directly or through a group);+ * every other remote caller (unbound tokens, other members, granted_sources+ * bots) gets nothing from it on any read path, and no operator switch+ * (GBRAIN_REMOTE_PRIVATE_PAGES=1, search.remote_private_pages=visible) or+ * private_pages grant relaxes that. Readers never relax visibility: private.+ * 2. Fails when: a restricted page, its timeline, chunks, versions or links leak+ * to an unlisted caller on a read path, under a hatch or through a grant; a+ * malformed readers value reads as open; a disabled member keeps access; or+ * a listed member cannot read their own page on the core read paths.+ * 3. Existing coverage (private-pages-grant) pins visibility: private only.+ * 4. Real seams: tokens minted by the token service and bound with SQL until+ * the member CLI lands, verified by the serve --http verifier, dispatched+ * through MCP dispatch as serve-http-mcp does; a repo-less brain (no git+ * checkout, the default keyless install); embeddings stubbed.+ */+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';+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 { noGrantFederatedScope } from '../src/core/source-resolver.ts';+import { dispatchToolCall } from '../src/mcp/dispatch.ts';+import { __resetPrivateVisibilityCacheForTests } from '../src/core/search/private-visibility.ts';+import type { AuthInfo } 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 = 'mr-team';+const PAGES = {+ alice: { slug: 'notes/alice-plan', readers: '[alice-example]', canary: 'canarymralice' },+ team: { slug: 'notes/team-plan', readers: '[group:team-a]', canary: 'canarymrteam' },+ malformed: { slug: 'notes/odd-plan', readers: '[alice-example, not valid]', canary: 'canarymrodd' },+ privateAlice: { slug: 'notes/quiet-plan', readers: 'alice-example', canary: 'canarymrquiet', extra: 'visibility: private' },+} as const;+type PageKey = keyof typeof PAGES;+const OPEN = { slug: 'notes/open-plan', canary: 'canarymropen' };+const TARGET = 'notes/shared-roadmap';++function page(key: PageKey): string {+ const p = PAGES[key];+ return ['---', 'type: note', `title: ${key} plan`, `readable_by: ${p.readers}`, ...('extra' in p ? [p.extra] : []), '---',+ `# ${key} plan`, '', `Harbor ledger planning notes ${p.canary} for the roadmap.`].join('\n');+}++/** Every remote read path, with arguments a restricted page in SRC answers. */+function reads(slug: string): Array<[string, string, Record<string, unknown>]> {+ return [+ ['search hybrid', 'search', { query: 'harbor ledger planning notes', fields: 'full', limit: 20 }],+ ['search keyword', 'search', { query: 'planning notes', match: 'keyword', fields: 'full', limit: 20 }],+ ['query', 'query', { query: 'harbor ledger planning notes', expand: false, fields: 'full', limit: 20 }],+ ['recall', 'recall', { query: 'harbor ledger planning notes' }],+ ['get_page', 'get_page', { slug }],+ ['list_pages', 'list_pages', { slug_prefix: 'notes/' }],+ ['get_chunks', 'get_chunks', { slug }],+ ['get_versions', 'get_versions', { slug, include_body: true }],+ ['get_timeline', 'get_timeline', { slug }],+ ['get_links', 'get_links', { slug }],+ ['get_backlinks', 'get_backlinks', { slug: TARGET }],+ ['traverse_graph', 'traverse_graph', { slug, depth: 1 }],+ ['resolve_slugs', 'resolve_slugs', { partial: slug.slice('notes/'.length) }],+ ];+}+const ECHOES_SLUG = new Set(['get_page', 'get_chunks', 'get_versions', 'get_timeline', 'get_links', 'traverse_graph']);+const LINK_PATHS = new Set(['get_links', 'traverse_graph']);+const CORE = new Set(['search hybrid', 'search keyword', 'get_page', 'list_pages', 'get_chunks', 'get_timeline']);++for (const kind of testBackends()) {+ describe(`member read access (${kind}, repo-less)`, () => {+ let engine: BrainEngine;+ let close: () => Promise<void>;+ const tokens: Record<string, string> = {};+ const tokenIds: Record<string, string> = {};++ const provider = () => new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });++ async function call(who: string, op: string, params: Record<string, unknown>): Promise<{ isError: boolean; text: string }> {+ const auth = await provider().verifyAccessToken(tokens[who]) as unknown as AuthInfo;+ const sourceId = auth.sourceId ?? 'default';+ const localFederated = await noGrantFederatedScope(engine, auth.hasSourceGrant, sourceId);+ const out = await dispatchToolCall(engine, op, { ...params }, {+ remote: true, transport: 'http', auth, sourceId, takesHoldersAllowList: auth.takesHoldersAllowList ?? ['world'],+ ...(localFederated ? { localFederatedSourceIds: localFederated } : {}),+ });+ return { isError: out.isError === true, text: out.content.map(c => c.text).join('\n') };+ }+ /** Did a read reveal the page? A path given the slug may echo it in a not-found error, so those count its content or its outgoing link. */+ const seen = (text: string, key: PageKey, label = 'search hybrid') => text.includes(PAGES[key].canary)+ || (ECHOES_SLUG.has(label) ? (LINK_PATHS.has(label) && text.includes(TARGET)) : text.includes(PAGES[key].slug));++ /** Which restricted pages `who` sees on each read path. */+ async function visibleTo(who: string, keys: readonly PageKey[]): Promise<Record<string, PageKey[]>> {+ const out: Record<string, PageKey[]> = {};+ for (const key of keys) {+ for (const [label, op, params] of reads(PAGES[key].slug)) {+ const { text } = await call(who, op, params);+ if (seen(text, key, label)) (out[label] ??= []).push(key);+ }+ }+ 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]);+ await importFromContent(engine, TARGET, '---\ntype: note\ntitle: Shared roadmap\n---\n# Shared roadmap\n\nThe shared roadmap.', { sourceId: SRC });+ await importFromContent(engine, OPEN.slug, `---\ntype: note\ntitle: Open plan\n---\n# Open plan\n\nHarbor ledger planning notes ${OPEN.canary}.`, { sourceId: SRC });+ for (const key of Object.keys(PAGES) as PageKey[]) {+ const { slug, canary } = PAGES[key];+ await importFromContent(engine, slug, page(key), { sourceId: SRC });+ await importFromContent(engine, slug, page(key) + '\n\nSecond draft.', { sourceId: SRC });+ await engine.addLink(slug, TARGET, 'roadmap', 'mentions', 'manual', undefined, undefined, { fromSourceId: SRC, toSourceId: SRC });+ await engine.addTimelineEntry(slug, { date: '2026-09-01', summary: `Planning call ${canary}` }, { sourceId: SRC });+ await engine.createVersion(slug, { sourceId: SRC });+ }+ for (const id of ['alice-example', 'bob-example', 'dan-example']) await engine.executeRaw('INSERT INTO access_members (id) VALUES ($1)', [id]);+ await engine.executeRaw("INSERT INTO access_groups (id) VALUES ('team-a')");+ await engine.executeRaw("INSERT INTO access_group_members (group_id, member_id) VALUES ('team-a', 'bob-example')");+ const mint = async (name: string, member?: string) => {+ const minted = await mintLegacyToken(engine, { name, scopes: ['read'], takesHolders: ['world'], sourceGrant: [SRC] });+ tokens[name] = minted.token;+ tokenIds[name] = minted.id;+ if (member) await engine.executeRaw('UPDATE access_tokens SET member_id = $2 WHERE id = $1::uuid', [minted.id, member]);+ };+ await mint('alice', 'alice-example');+ await mint('bob', 'bob-example');+ await mint('dan', 'dan-example');+ await mint('unbound');+ await mint('bot');+ await mint('alice-granted', 'alice-example');+ await mint('ghost', 'nobody-example');+ await rescopeLegacyToken(engine, parseRescopeTokenArgs(['bot', '--private-pages', 'granted-sources']));+ await rescopeLegacyToken(engine, parseRescopeTokenArgs(['alice-granted', '--private-pages', 'granted-sources']));+ }, 240_000);++ afterAll(async () => {+ __setEmbedTransportForTests(null);+ resetGateway();+ await close?.();+ }, 60_000);++ test('the brain records that it holds restrictions', async () => {+ const [row] = await engine.executeRaw<{ value: string }>("SELECT value FROM config WHERE key = 'access.restrictions_present'");+ expect(row?.value).toBe('1');+ });++ test('fixture control: a trusted local caller reads every restricted page', async () => {+ for (const key of Object.keys(PAGES) as PageKey[]) {+ const out = await dispatchToolCall(engine, 'get_page', { slug: PAGES[key].slug }, { remote: false, sourceId: SRC });+ expect({ key, seen: seen(out.content.map(c => c.text).join('\n'), key) }).toEqual({ key, seen: true });+ }+ });++ test('an unbound token, a bot with granted_sources, an unknown member and an unlisted member see no restricted page on any path', async () => {+ for (const who of ['unbound', 'bot', 'ghost', 'dan']) {+ expect({ who, visible: await visibleTo(who, Object.keys(PAGES) as PageKey[]) }).toEqual({ who, visible: {} });+ }+ }, 240_000);++ test('a listed member reads their page on the core paths, and only theirs', async () => {+ const alice = await visibleTo('alice', ['alice', 'team', 'malformed', 'privateAlice']);+ for (const [label, keys] of Object.entries(alice)) expect({ label, keys }).toEqual({ label, keys: ['alice'] });+ for (const label of CORE) expect({ label, keys: alice[label] }).toEqual({ label, keys: ['alice'] });+ const bob = await visibleTo('bob', ['alice', 'team', 'malformed', 'privateAlice']);+ for (const [label, keys] of Object.entries(bob)) expect({ label, keys }).toEqual({ label, keys: ['team'] });+ for (const label of CORE) expect({ label, keys: bob[label] }).toEqual({ label, keys: ['team'] });+ }, 240_000);++ test('readers never relax visibility: private; a private_pages grant opens it to a listed member only', async () => {+ expect(Object.values(await visibleTo('alice', ['privateAlice'])).flat()).toEqual([]);+ const granted = await visibleTo('alice-granted', ['privateAlice']);+ expect(granted['get_page']).toEqual(['privateAlice']);+ expect(Object.values(await visibleTo('bot', ['privateAlice'])).flat()).toEqual([]);+ }, 240_000);++ for (const [hatch, run] of [+ ['GBRAIN_REMOTE_PRIVATE_PAGES=1', <T>(fn: () => Promise<T>) => withEnv({ GBRAIN_REMOTE_PRIVATE_PAGES: '1' }, fn)],+ ['search.remote_private_pages=visible', async <T>(fn: () => Promise<T>) => {+ await engine.setConfig('search.remote_private_pages', 'visible');+ __resetPrivateVisibilityCacheForTests();+ try { return await fn(); } finally { await engine.setConfig('search.remote_private_pages', 'hidden'); __resetPrivateVisibilityCacheForTests(); }+ }],+ ] as const) {+ test(`${hatch} relaxes visibility only: restricted pages stay with their readers`, async () => {+ await run(async () => {+ for (const who of ['unbound', 'bot', 'dan']) {+ expect({ who, visible: await visibleTo(who, Object.keys(PAGES) as PageKey[]) }).toEqual({ who, visible: {} });+ }+ const alice = await visibleTo('alice', ['alice', 'team', 'malformed', 'privateAlice']);+ for (const [label, keys] of Object.entries(alice)) expect({ label, keys: keys.filter(k => k !== 'privateAlice') }).toEqual({ label, keys: ['alice'] });+ expect(alice['get_page']).toEqual(['alice', 'privateAlice']);+ const open = await call('unbound', 'get_page', { slug: OPEN.slug });+ expect(open.text).toContain(OPEN.canary);+ });+ }, 240_000);+ }++ test('a disabled member loses access on the next request', async () => {+ await engine.executeRaw("UPDATE access_members SET disabled_at = now() WHERE id = 'alice-example'");+ try {+ expect(await visibleTo('alice', ['alice'])).toEqual({});+ } finally {+ await engine.executeRaw("UPDATE access_members SET disabled_at = NULL WHERE id = 'alice-example'");+ }+ expect((await visibleTo('alice', ['alice']))['get_page']).toEqual(['alice']);+ }, 120_000);+ });+}diff --git a/test/private-visibility.test.ts b/test/private-visibility.test.tsindex dc6de69aaa..e518783d0b 100644--- a/test/private-visibility.test.ts+++ b/test/private-visibility.test.ts@@ -376,7 +376,7 @@ describe('shared private predicate lives once (#4352 remediation)', () => {test('entity-card composes privatePagesFilterFragment instead of hand-rolling the predicate', () => {// test-reads-source-ok[trust-boundary]: structural "lives ONCE" guard — a duplicated predicate behaves identically until visibility semantics drift, so only the text can catch it (#4352)const src = readFileSync(join(import.meta.dir, '../src/core/verbs/entity-card.ts'), 'utf8');- expect(src).toContain('privatePagesFilterFragment');+ expect(src).toMatch(/privatePagesFilter(Fragment|ForCaller)\(/);// The predicate TEXT must not be duplicated — silent drift risk if// visibility semantics ever change (sql-ranking.ts's "lives ONCE" claim).expect(src).not.toMatch(/frontmatter->>\s*'visibility'/);