Skip to content

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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 NULL
AND ${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: s
return `(${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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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'/);