Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: pre-landing review fixes (pass 2)

garrytan435eea6d109a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cca0c7628e..dcbd41b06a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,7 +12,7 @@ identifiers and attribution are available in the pre-removal Git revision
## [Unreleased]
-**A page a member-bound credential creates in the `default` source is now readable only by that member.** A token bound with `gbrain auth rescope --member <id>` and no `--sources` writes to `default`, the source every credential without a source grant reads, and so does a token granted `--sources default` and an OAuth client left at its registration default. Its `put_page` (and every page write through the same path) used to create an ordinary page there, which another member and an unbound token read through `get_page`, `search`, `query`, `recall` and `list_pages`; its `remember` facts were already kept on the member's own page. A page such a credential creates is now written with `readable_by: [member:<id>]`, in the database row on a repo-less brain and in the file on a repo brain; rewriting it without `readable_by` keeps the stored readers, and the member widens it by naming readers. An edit to an existing page that names no readers leaves it shared, and `POST /ingest`, which cannot keep a page to a member, refuses such a credential with `permission_denied`. Member-bound credentials whose write source is another source (the documented `--sources private-<member>,default` shape) and unbound credentials write exactly as before. Pages derived from such a page (extracted atoms, chronicle events, `derived_from` pages, and a synthesized concept that uses it) follow the rule for pages with readers and are readable by no remote caller, the writer included. A page that teammates should read, such as a shared `people/` or `companies/` entity page or a page in a folder a rule already scopes to a group, names its readers when it is created; otherwise the first member to create a slug keeps it, and other members writing that slug get `page_not_found`. Pages written before this release keep whatever readers they have: `gbrain access who-can-read <slug>` shows who reads one.
+**A page a member-bound credential creates in the `default` source is now readable only by that member.** A token bound with `gbrain auth rescope --member <id>` and no `--sources` writes to `default`, the source every credential without a source grant reads, and so does a token granted `--sources default` and an OAuth client left at its registration default. Its `put_page` (and every page write through the same path) used to create an ordinary page there, which another member and an unbound token read through `get_page`, `search`, `query`, `recall` and `list_pages`; its `remember` facts were already kept on the member's own page. A page such a credential creates is now written with `readable_by: [member:<id>]`, in the database row on a repo-less brain and in the file on a repo brain; rewriting it without `readable_by` keeps the stored readers, and the member widens it by naming readers. An edit to an existing page that names no readers leaves it shared, and `POST /ingest`, which cannot keep a page to a member, refuses such a credential with `permission_denied`. Member-bound credentials whose write source is another source (the documented `--sources private-<member>,default` shape) and unbound credentials write exactly as before, apart from slugs a member now creates. Pages derived from such a page (extracted atoms, chronicle events, `derived_from` pages, and a synthesized concept that uses it) follow the rule for pages with readers and are readable by no remote caller, the writer included. A page that teammates should read, such as a shared `people/` or `companies/` entity page or a page in a folder a rule already scopes to a group, names its readers when it is created; otherwise the first member to create a slug keeps it, and every other remote credential writing that slug (another member, an unbound token, a shared agent) gets `page_not_found`. The operator widens such a page from the brain host by adding `readable_by` to it (the local CLI is not member-scoped). A member-bound `put_page` over a page deleted within the last 72 hours is a create, so it is kept to the member too. Pages written before this release keep whatever readers they have: `gbrain access who-can-read <slug>` shows who reads one.
### Itemized changes
diff --git a/docs/guides/multi-source-brains.md b/docs/guides/multi-source-brains.md
index ec26fc12bb..7f0fc2c776 100644
--- a/docs/guides/multi-source-brains.md
+++ b/docs/guides/multi-source-brains.md
@@ -260,7 +260,9 @@ who may read it, before any member's bot connects:
writer included. A page teammates should read (a shared `people/` or
`companies/` page, or a page in a folder a rule scopes to a group) names its
readers when it is created; otherwise the first member to create a slug
- keeps it. Before this release those
+ keeps it, and every other remote credential writing that slug gets
+ `page_not_found` until the operator adds `readable_by` on the brain host.
+ Before this release those
pages named no readers, so other members and unbound tokens read them:
check pages a member wrote with `gbrain access who-can-read <slug>` and add
`readable_by` on the brain host to any that should stay private.
diff --git a/docs/tutorials/company-brain.md b/docs/tutorials/company-brain.md
index 0806995a3e..6b31328e26 100644
--- a/docs/tutorials/company-brain.md
+++ b/docs/tutorials/company-brain.md
@@ -130,7 +130,7 @@ gbrain access check --token alice-laptop # what this credential can rea
gbrain access who-can-read notes/renewal-notes # the members and groups a page admits
```
-A credential bound with `--member` whose write source is `default` (a token with no `--sources` or `--sources default`, or an OAuth client left at its registration default) writes where every credential without a source grant reads, so a page it creates is written with `readable_by: [member:<id>]` and only that member reads it; it keeps those readers when the member rewrites it without the field, and the member shares it by naming readers (`readable_by: [alice-example, group:team-a]`). An edit to an existing page that names no readers leaves it shared, `remember` facts go on the member's own page as before, and `POST /ingest` refuses such a credential. Pages derived from such a page (extracted atoms, chronicle events, `derived_from` pages, and a synthesized concept that uses it) follow the rule for pages with readers and are readable by no remote caller, the writer included. A page that teammates should read, such as a shared `people/` or `companies/` entity page or a page in a folder a rule already scopes to a group, names its readers when it is created; otherwise the first member to create a slug keeps it, and other members writing that slug get `page_not_found`. A credential whose write source is another source (`--sources private-alice-example,default`, first id the write source) keeps writing exactly what it sends. Earlier releases wrote these pages with no readers, so other members and unbound tokens read them; run `gbrain access who-can-read <slug>` on pages your members wrote and add `readable_by` on the host where needed.
+A credential bound with `--member` whose write source is `default` (a token with no `--sources` or `--sources default`, or an OAuth client left at its registration default) writes where every credential without a source grant reads, so a page it creates is written with `readable_by: [member:<id>]` and only that member reads it; it keeps those readers when the member rewrites it without the field, and the member shares it by naming readers (`readable_by: [alice-example, group:team-a]`). An edit to an existing page that names no readers leaves it shared, `remember` facts go on the member's own page as before, and `POST /ingest` refuses such a credential. Pages derived from such a page (extracted atoms, chronicle events, `derived_from` pages, and a synthesized concept that uses it) follow the rule for pages with readers and are readable by no remote caller, the writer included. A page that teammates should read, such as a shared `people/` or `companies/` entity page or a page in a folder a rule already scopes to a group, names its readers when it is created; otherwise the first member to create a slug keeps it, and every other remote credential writing that slug (another member, an unbound token, a shared agent) gets `page_not_found`. The operator widens such a page from the brain host by adding `readable_by` to it. A member-bound `put_page` over a page deleted within the last 72 hours is a create, so it is kept to the member too. A credential whose write source is another source (`--sources private-alice-example,default`, first id the write source) keeps writing exactly what it sends. Earlier releases wrote these pages with no readers, so other members and unbound tokens read them; run `gbrain access who-can-read <slug>` on pages your members wrote and add `readable_by` on the host where needed.
A remote caller whose credential is bound to a listed member (directly or through a group) reads the page on every read path; every other remote caller, including an unbound token, an unbound stdio server, a bot with `--private-pages granted-sources` and an operator escape hatch (`GBRAIN_REMOTE_PRIVATE_PAGES=1`, `search.remote_private_pages=visible`), gets the same `not_found` as for a page that does not exist. `readable_by` only narrows: a `visibility: private` page stays private to a listed member unless the member's credential also has `--private-pages granted-sources`. A malformed `readable_by` reads as nobody. A page derived from a restricted page (an extracted atom, a synthesized concept, a chronicle event) is readable by no remote caller. The local CLI is unchanged; `--as <member>` previews one member's view. Pages that already carried `readable_by` before you upgraded read as nobody until `gbrain repair access` (preview, then `--apply`) derives their readers. This works the same on a repo-less brain: members, groups and bindings live in the database.
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index ec0d7b73d7..2f75007567 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1489,7 +1489,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.618.0', id: 'refresh_replan_own_commits_8828', text: 'A `gbrain sources refresh` whose checkout HEAD moved while it waited for writes admitted before its fence no longer refuses `refresh_source_changed` when every commit since its start is one of gbrain\'s own (in the commit ledger) and the upstream branch holds them: it takes HEAD as its start and fast-forwards to the upstream. A HEAD move that includes a commit gbrain did not make, or gbrain\'s commits the upstream does not hold yet, still refuses as before.' },
{ since: '0.60.619.0', id: 'managed_commit_push_unpublished_gst1923', text: 'On a managed checkout, `gbrain git commit-push -m <msg> -- <paths>` now reports how many commits the upstream lacks as last fetched (`unpublished` in `--json`, `null` when there is no upstream) and says nothing was pushed, instead of answering `nothing to commit; <remote>/<branch> at -` and logging `[push] ok-already-on-remote` for a commit that already existed. It writes no push-log line on a managed checkout. It still never pushes there; `gbrain git commit-push --push-only --keep-checkout --path <checkout>` publishes.' },
{ since: '0.60.620.0', id: 'refresh_publish_diverged_default_gbra386', text: 'A diverged managed checkout now publishes its local commits on `gbrain sources refresh` by default when the worktree\'s Git durability is on: `sources.refresh_publish_diverged` unset now means on there (it used to mean off), merged with the upstream in memory, never rebased or forced. The refresh publish first scans what the local commits add (messages, added lines, merge resolutions) and refuses the new `publish_secret_found` naming the file, line and rule, never the value, when one looks like a secret; `gbrain git commit-push --push-only --scan-secrets` runs the same gate. Unset with durability not on still refuses, naming `gbrain sources writer git-durability <source> --enable`; `false` turns it off.' },
- { since: 'TBD', id: 'ungranted_member_writes_gst2051', text: 'A token or OAuth client bound to a member (`gbrain auth rescope --member <id>`) whose write source is `default` (no `--sources`, `--sources default`, or an OAuth client at its registration default) writes where every credential without a source grant reads. A page it creates there is now written with `readable_by: [member:<id>]`, so other members and unbound tokens no longer read it; rewriting it without `readable_by` keeps those readers, naming readers widens it, an edit to an existing page with no readers leaves it shared, and `POST /ingest` refuses such a credential. Pages derived from such a page (atoms, chronicle events, `derived_from` pages, a synthesized concept using it) are readable by no remote caller, the writer included; a page teammates should read names its readers when created. Credentials writing to another source and unbound credentials are unchanged, and pages written before the upgrade keep their readers (`gbrain access who-can-read <slug>`).' },
+ { since: 'TBD', id: 'ungranted_member_writes_gst2051', text: 'A token or OAuth client bound to a member (`gbrain auth rescope --member <id>`) whose write source is `default` (no `--sources`, `--sources default`, or an OAuth client at its registration default) writes where every credential without a source grant reads. A page it creates there is now written with `readable_by: [member:<id>]`, so other members and unbound tokens no longer read it; rewriting it without `readable_by` keeps those readers, naming readers widens it, an edit to an existing page with no readers leaves it shared, and `POST /ingest` refuses such a credential. Pages derived from such a page (atoms, chronicle events, `derived_from` pages, a synthesized concept using it) are readable by no remote caller, the writer included; a page teammates should read names its readers when created, because every other remote credential, unbound tokens included, gets page_not_found writing a slug a member created until the operator adds readable_by on the brain host. Credentials writing to another source and unbound credentials are unchanged, and pages written before the upgrade keep their readers (`gbrain access who-can-read <slug>`).' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */
diff --git a/test/access-ungranted-member-writes.test.ts b/test/access-ungranted-member-writes.test.ts
index 464e0c80e0..d663affcc2 100644
--- a/test/access-ungranted-member-writes.test.ts
+++ b/test/access-ungranted-member-writes.test.ts
@@ -125,7 +125,16 @@ for (const kind of testBackends()) {
for (const who of ['bob', 'public', 'alice']) expect((await call(who, 'get_page', { slug: derived })).json.code).toBe('page_not_found');
const control = 'notes/derived-shared-' + canary;
await importFromContent(engine, control, ['---', 'type: note', 'title: Control ' + canary, 'derived_from: [' + SHARED_PAGE + ']', '---', '# Control', '', 'Control code ' + canary + '.'].join('\n'), { sourceId: 'default', noEmbed: true });
- expect((await call('bob', 'get_page', { slug: control })).json.code).toBeUndefined();
+ const read = await call('bob', 'get_page', { slug: control, include_content: true });
+ expect({ isError: read.isError, body: read.text.includes('Control code ' + canary + '.') }).toEqual({ isError: false, body: true });
+ }, 240_000);
+
+ test('another member or an unbound token writing a slug the member created gets page_not_found and changes nothing', async () => {
+ const canary = marker('claim');
+ const slug = 'notes/alice-claim-' + canary;
+ expect((await call('alice', 'put_page', { slug, content: note('Alice claim', 'Alice ' + canary + '.') })).isError).toBe(false);
+ for (const who of ['bob', 'public']) expect((await call(who, 'put_page', { slug, content: note('Other claim', who + ' ' + canary + '.') })).json.code).toBe('page_not_found');
+ expect(await stored(slug)).toMatchObject({ page_readers: ['member:alice-example'], body: expect.stringContaining('Alice ' + canary) });
}, 240_000);
test('a token granted --sources default and an OAuth client at its registration default are kept to their member too', async () => {