Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: pre-landing review fixes (pass 2): pinned questions stay out of the private-pages grant

garrytane1011657aa15
diff --git a/docs/guides/multi-source-brains.md b/docs/guides/multi-source-brains.md
index 16059244e1..87ff89e39e 100644
--- a/docs/guides/multi-source-brains.md
+++ b/docs/guides/multi-source-brains.md
@@ -253,12 +253,12 @@ it, before any member's bot connects:
A token with no source grant, a federated source the grant does not name,
and a request's `source_ids` never add a source; `context_pack`, `delta`
- and writes keep hiding private pages. In a named source the grant opens
- every page remote reads treat as private, not only `visibility: private`:
- pages with a privacy alias (`access`, `confidentiality`), atoms, concepts
- and events derived from private or unknown origins, and pages whose
- declared lineage is private. `--private-pages none` hides them again on the
- next request, and `gbrain auth list` shows each token's setting.
+ and writes keep hiding private pages. In a named source the grant also
+ opens pages with a privacy alias (`access`, `confidentiality`), atoms,
+ concepts and events derived from private or unknown origins, and pages
+ whose declared lineage is private; pinned questions stay owner-only.
+ `--private-pages none` hides them again on the next request, and
+ `gbrain auth list` shows each token's setting.
> **Warning: one shared source has no boundary inside it.** A bot that answers
> everyone with one unscoped token over a single source exposes everything in
diff --git a/docs/mcp/ADMIN.md b/docs/mcp/ADMIN.md
index a9968a8f03..b643bc87f2 100644
--- a/docs/mcp/ADMIN.md
+++ b/docs/mcp/ADMIN.md
@@ -428,7 +428,7 @@ gbrain auth rescope --client CLIENT_ID --private-pages none # hide them again
| `--takes-holders` | `a,b` or `none` | Takes-holder allow-list for a token or client (default `world`); `none` hides every take. |
| `--operations` | `op,...`, `none` or `all` | Operation snapshot; `none` refuses every operation. Client only: `all` stores no snapshot and clears the profile, so the scopes and the surface alone decide, including operations later upgrades add (tokens: `--reset-default operations`). |
| `--scopes` | `read,write,...` | Replaces the scopes. |
-| `--private-pages` | `granted-sources` or `none` | Whether remote reads see `visibility: private` pages. `none` (the default for every token and client) hides them, as before. `granted-sources` shows them only in the sources this grant names: a token's `--sources` list, or a client's write source plus its read sources. The no-grant floor, federated sources the grant does not name, a client's bound source and a request's `source_id` / `source_ids` never add a source. `context_pack`, `delta` and every write keep hiding private pages. In a named source it opens every page remote reads treat as private, not only `visibility: private`: privacy-alias pages (`access`, `confidentiality`), atoms, concepts and events derived from private or unknown origins, and pages with private declared lineage. Stored in its own column, not in the legacy permissions JSON. |
+| `--private-pages` | `granted-sources` or `none` | Whether remote reads see `visibility: private` pages. `none` (the default for every token and client) hides them, as before. `granted-sources` shows them only in the sources this grant names: a token's `--sources` list, or a client's write source plus its read sources. The no-grant floor, federated sources the grant does not name, a client's bound source and a request's `source_id` / `source_ids` never add a source. `context_pack`, `delta` and every write keep hiding private pages. In a named source it also opens privacy-alias pages (`access`, `confidentiality`), atoms, concepts and events derived from private or unknown origins, and pages with private declared lineage; pinned questions stay owner-only. Stored in its own column, not in the legacy permissions JSON. |
| `--reset-default` | `sources,takes-holders,operations` | Token only: restores the `auth create` default for those axes: no source grant (the historical `default` floor), holders `world`, no operation snapshot. |
| `--refresh-operations` | with optional `--add op,...` or `--all-new` | Token only: previews operations added since the snapshot. Without `--add` or `--all-new` nothing is widened. |
| `--if-version` | `N` | Refuses unless the stored grant revision is `N`; the refusal names the current revision. |
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 62e7cf9efa..4ff22f9fe7 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1296,7 +1296,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
// GBRA-199. since: '0.60.503.0' is stamped at the merge slot.
{ since: '0.60.503.0', id: 'registration_lists_verbs_gbra199', text: 'New MCP registrations gbrain writes now list only the seven memory verbs (`recall`, `remember`, `entity`, …) and `request_tools` in tools/list: `gbrain setup claude-code|codex`, `gbrain bootstrap hooks`, the readiness and `gbrain init` registration lines (`serve --surface starter --advertise verbs`: the starter tools stay callable) and `gbrain mcp expose` (its `serve --http` runs with `--surface full --advertise verbs`, so clients without their own surface see that list and every operation stays callable). `request_tools` lists the rest and returns any tool\'s full schema, and a tool it describes joins the session\'s list. The initialize instructions follow the listed tools, so they point agents at `recall` instead of `search`. Existing registrations and exposures keep their listing, and an explicit `--surface full` (or starter, or verbs) lists that whole surface. New `gbrain serve --advertise <verbs|starter|full>` sets the listing per server and wins over config `mcp.advertised_surface`; a listing narrower than the callable set now always includes `request_tools`. Remote harness and bot clients get the same listing: a new `gbrain mcp provision` grant with the memory-reader, memory-writer or coding-agent profile and a new `gbrain agent register` daily-driver or coding-agent client keep the full callable surface but list the verbs and `request_tools` (`auth list-clients` shows `full (set by install)`); `gbrain auth rescope-client <id> --surface full` lists everything, and clients the operator pinned before keep their listing. Plugin manifests and a bare `serve` are unchanged.' },
{ since: '0.60.452.0', id: 'sources_add_federation_warning_gbra156', text: '`gbrain sources add` without `--federated` or `--no-federated` now warns on stderr that the new source is not federated, so a remote token or agent connection with no source grant cannot read its pages, and names `gbrain sources federate <id>` and `gbrain auth rescope --token <name> --sources <id>`. The stored default is still non-federated.' },
- { since: 'TBD', id: 'private_pages_granted_sources_gbra156', text: 'Access tokens and OAuth clients have a new private-pages grant, `none` for every existing and new token and client, so remote reads still hide `visibility: private` pages until the brain host opts a connection in: `gbrain auth rescope --token <name> --private-pages granted-sources` (or `--client <id>`) lets it read private pages in the sources its grant names, and only those; in a named source that covers every page remote reads treat as private (privacy-alias pages and atoms, concepts and events derived from private or unknown origins), not only `visibility: private`. A token with no source grant, federated sources the grant does not name and a request\'s `source_ids` never add one; `context_pack`, `delta` and writes keep hiding private pages. `--private-pages none` turns it off on the next request.' },
+ { since: 'TBD', id: 'private_pages_granted_sources_gbra156', text: 'Access tokens and OAuth clients have a new private-pages grant, `none` for every existing and new token and client, so remote reads still hide `visibility: private` pages until the brain host opts a connection in: `gbrain auth rescope --token <name> --private-pages granted-sources` (or `--client <id>`) lets it read private pages in the sources its grant names, and only those; in a named source that also covers privacy-alias pages and atoms, concepts and events derived from private or unknown origins, while pinned questions stay owner-only. A token with no source grant, federated sources the grant does not name and a request\'s `source_ids` never add one; `context_pack`, `delta` and writes keep hiding private pages. `--private-pages none` turns it off on the next request.' },
// GBRA-187 harness-eval items (HARN-2, HARN-5). `since` is stamped at the merge slot.
{ since: '0.60.456.0', id: 'skillpack_skill_name', text: 'list_brain_skillpack now names each skill `name` instead of `slug`, and get_skill with source_id returns `name` too, matching the get_skill parameter it feeds. A skill name is not a page slug; clients that read `skills[].slug` read `skills[].name` instead.' },
{ since: '0.60.456.0', id: 'openclaw_core_scaffold', text: '`gbrain skillpack scaffold --harness openclaw` now installs five brain-first skills (query, brain-ops, capture, data-loss-gate, resolve-before-asking) instead of the full bundle, because OpenClaw lists every workspace skill in every prompt. `--all` installs the full bundle; existing workspaces are not changed.' },
diff --git a/src/core/engine-sql/pages.ts b/src/core/engine-sql/pages.ts
index 453d3164d0..398c84b376 100644
--- a/src/core/engine-sql/pages.ts
+++ b/src/core/engine-sql/pages.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 ${orPrivateReadableSource('p', `${privatePagesFilterFragment('p')} AND ${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/search/private-visibility.ts b/src/core/search/private-visibility.ts
index 0e1e8b49e0..23fab521af 100644
--- a/src/core/search/private-visibility.ts
+++ b/src/core/search/private-visibility.ts
@@ -87,30 +87,32 @@ export function privateReadableSources(): readonly string[] {
}
/**
- * `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`, widened to pages (`pageAlias`, a code-provided alias)
+ * whose source is in the current private-readable set. A page carrying the
+ * `pinned_question` marker never widens: pinned questions stay owner-private
+ * (src/core/questions/pages.ts). The ids are embedded as literals: each passed
+ * isValidSourceId, whose alphabet has no quote or backslash.
*/
-export function orPrivateReadableSource(sourceIdSql: string, visiblePredicate: string): string {
+export function orPrivateReadableSource(pageAlias: string, visiblePredicate: string): string {
const ids = privateReadableSources();
if (ids.length === 0) return visiblePredicate;
- return `(${sourceIdSql} IN (${ids.map(id => `'${id}'`).join(', ')}) OR ${visiblePredicate})`;
+ return `((${pageAlias}.source_id IN (${ids.map(id => `'${id}'`).join(', ')}) AND NOT COALESCE(${pageAlias}.frontmatter ? 'pinned_question', false)) 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. */
export function privatePagesFilterForCaller(pageAlias: string): string {
- return orPrivateReadableSource(`${pageAlias}.source_id`, privatePagesFilterFragment(pageAlias));
+ return orPrivateReadableSource(pageAlias, privatePagesFilterFragment(pageAlias));
}
/** privatePagesFilterFragmentFast for a remote read. */
export function privatePagesFilterFastForCaller(pageAlias: string): string {
- return orPrivateReadableSource(`${pageAlias}.source_id`, privatePagesFilterFragmentFast(pageAlias));
+ return orPrivateReadableSource(pageAlias, privatePagesFilterFragmentFast(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. */
+/** isPrivatePage for a remote read: false for a page whose `source_id` is private-readable, unless it carries the `pinned_question` marker; a row without `source_id` keeps the plain rule. */
export function isPrivatePageForCaller(page: { type?: string | null; frontmatter?: unknown; source_id?: string | null }): boolean {
if (!isPrivatePage(page)) return false;
+ if (typeof page.frontmatter === 'object' && page.frontmatter !== null && (page.frontmatter as Record<string, unknown>).pinned_question != null) return true;
return !(typeof page.source_id === 'string' && privateReadableSources().includes(page.source_id));
}
diff --git a/src/core/verbs/entity-card.ts b/src/core/verbs/entity-card.ts
index 081b41d1ce..580e0879b6 100644
--- a/src/core/verbs/entity-card.ts
+++ b/src/core/verbs/entity-card.ts
@@ -309,7 +309,7 @@ export async function selectEntityCandidates(
const { orPrivateReadableSource, privatePagesFilterFragment, 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 ${orPrivateReadableSource('pages', privatePagesFilterFragment('pages'))}` : '';
const norm = normalizeAlias(trimmed);
const titleLc = trimmed.toLowerCase();
diff --git a/test/private-pages-grant.test.ts b/test/private-pages-grant.test.ts
index 58daad5a3a..56faed48dc 100644
--- a/test/private-pages-grant.test.ts
+++ b/test/private-pages-grant.test.ts
@@ -268,6 +268,30 @@ for (const kind of testBackends()) {
}
});
+ test('in a granted source the grant opens privacy-alias pages and derived atoms, never a pinned question', async () => {
+ const extra: Array<[string, string, string]> = [
+ ['drafts/harbor-memo', 'canaryaliaspriv', ['---', 'type: note', 'title: Harbor memo', 'confidentiality: secret', '---', '# Harbor memo', '', 'Harbor memo canaryaliaspriv.'].join('\n')],
+ ['atoms/harbor-atom', 'canaryatompriv', ['---', 'type: atom', 'title: Harbor atom', '---', '# Harbor atom', '', 'Harbor atom canaryatompriv.'].join('\n')],
+ ['questions/harbor-pin', 'canarypinpriv', ['---', 'type: question', 'title: Harbor pin', 'visibility: private', 'pinned_question: pin-example', '---', '# Harbor pin', '', 'Owner note canarypinpriv.'].join('\n')],
+ ];
+ for (const [slug, , body] of extra) await importFromContent(engine, slug, body, { sourceId: ALICE });
+ for (const [slug, canary] of extra) expect({ slug, seen: (await local('get_page', { slug })).includes(canary) }).toEqual({ slug, seen: true });
+ for (const owner of ['alice-example', 'client-alice']) {
+ for (const [slug, canary] of extra) {
+ const out = await call(tokens[owner], 'get_page', { slug });
+ expect({ owner, slug, seen: out.text.includes(canary) }).toEqual({ owner, slug, seen: !slug.startsWith('questions/') });
+ }
+ const listed = await call(tokens[owner], 'list_pages', { slug_prefix: 'questions/' });
+ expect({ owner, listed: listed.text.includes('questions/harbor-pin') }).toEqual({ owner, listed: false });
+ }
+ for (const other of ['bob-example', 'floor', 'alice-none']) {
+ for (const [slug, canary] of extra) {
+ const out = await call(tokens[other], 'get_page', { slug, source_id: ALICE });
+ expect({ other, slug, leaked: out.text.includes(canary) }).toEqual({ other, slug, leaked: false });
+ }
+ }
+ });
+
test('a rescope back to none hides the pages on the next call (token and client)', async () => {
expect((await call(tokens['alice-example'], 'get_page', { slug: PRIVATE_SLUG })).text).toContain(SECRET[ALICE]);
await rescopeToken('alice-example', '--private-pages', 'none');