Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Doctor checks that a guest source's two records agree (GBRA-504)
garrytan9d095c514dd9
diff --git a/docs/guides/guest-notes.md b/docs/guides/guest-notes.mdindex fb46b8d5af..03acd011b5 100644--- a/docs/guides/guest-notes.md+++ b/docs/guides/guest-notes.md@@ -239,10 +239,13 @@ source other than `guests`. A credential with a `min_trust` floor abovegbrain doctor --only guest_source --json```-The `guest_source` check reads, and changes nothing. It fails when a guest source-is missing its `guest`, `federated` or `trust_ceiling` flags, has a local-path, is marked guest without its database record, or the brain's-`guests.present` marker is unset (reads would skip the warning); and when a+The `guest_source` check reads, and changes nothing. A source is a guest source+when its config says `guest: true` or it has a guest source record, so its+notes keep their warning if one of the two is lost. The check fails when the+two disagree (one is there without the other) and names the repair,+`gbrain guests init --source <id> --yes`, which restores both and keeps the+writer list. It also fails when a guest source is missing its `federated` or+`trust_ceiling` flags or has a local path, and when awriter names a removed credential or one whose grant reaches beyond the guestsource. It warns when the writer list is empty, no owner is set, a credential boundto you can't read the guest source (it prints the exactdiff --git a/src/commands/doctor/checks/guest-source.ts b/src/commands/doctor/checks/guest-source.tsindex 2a9dfa37ac..564b19c159 100644--- a/src/commands/doctor/checks/guest-source.ts+++ b/src/commands/doctor/checks/guest-source.ts@@ -2,9 +2,10 @@* guest_source doctor check (GBRA-504 slice 4, read-only).** For every guest source (a guest_sources row, or a source whose config says guest: true):- * - fail: the source config lacks guest, federated or the external_untrusted trust_ceiling, it has a local path, the- * config says guest with no guest_sources row, the brain's guests.present marker is unset (reads would skip the- * guest warning), a writer names a removed or unknown credential, or a writer's grant reaches beyond the guest source;+ * - fail: the two guest records disagree (config guest: true with no guest_sources row, or a guest_sources row whose+ * config lacks guest: true; either alone still marks reads, and gbrain guests init restores both), the config lacks+ * federated or the external_untrusted trust_ceiling, it has a local path, a writer names a removed or unknown+ * credential, or a writer's grant reaches beyond the guest source;* - warn: the writer list is empty or names a principal that is not a remote credential, no brain owner is set, a* credential bound to the owner cannot read the source (with the exact grant command, and* gbrain guests grant-owner-clients for all of them), or its min_trust floor hides guest notes (F9).@@ -15,7 +16,7 @@ import type { BrainEngine } from '../../../core/engine.ts';import { agentFix, checkError, infoCheck } from '../check-fix.ts';import { connectedEngine, type DoctorContext, type DoctorEntry } from '../context.ts';import { authSourcesFromGrant, grantFromClient, grantFromRow, grantFromTokenRow } from '../../../core/grants/model.ts';-import { GUEST_SOURCES_PRESENT_KEY } from '../../../core/guests/marker.ts';+import { guestSourceSql } from '../../../core/guests/marker.ts';import { GUEST_TRUST_CEILING } from '../../../core/guests/sources.ts';import { ownerCredentials } from '../../../core/guests/owner-credentials.ts';@@ -41,13 +42,14 @@ async function writerFindings(engine: BrainEngine, source: string, writer: strinreturn [{ level: 'fail', text: 'writer ' + writer + ' is granted ' + [...new Set([auth.sourceId, ...reads])].join(', ') + ', not exactly ' + source }];}-async function sourceFindings(engine: BrainEngine, s: GuestSourceRow, present: boolean): Promise<Finding[]> {+async function sourceFindings(engine: BrainEngine, s: GuestSourceRow): Promise<Finding[]> {const out: Finding[] = [];const init = ['gbrain', 'guests', 'init', '--source', s.id, '--yes'];const config = json(s.config);- if (s.writers === null) return [{ level: 'fail', text: 'source ' + s.id + ' says guest: true in its config but is not a guest source (no guest_sources row), so nothing enforces its writer list or ceiling', fix: init }];- if (!present) out.push({ level: 'fail', text: 'source ' + s.id + ' is a guest source but config ' + GUEST_SOURCES_PRESENT_KEY + ' is unset, so reads skip the guest warning', fix: init });- const flags = [config.guest === true ? null : 'guest', config.federated === true ? null : 'federated',+ const repair = '; its notes still read as guest notes, repair: ' + init.join(' ');+ if (s.writers === null) return [{ level: 'fail', text: 'source ' + s.id + ' says guest: true in its config but has no guest_sources row, so the two guest records disagree and nothing enforces its writer list or ceiling' + repair, fix: init }];+ if (config.guest !== true) out.push({ level: 'fail', text: 'source ' + s.id + ' has a guest_sources row but its config does not say guest: true, so the two guest records disagree' + repair, fix: init });+ const flags = [config.federated === true ? null : 'federated',config.trust_ceiling === GUEST_TRUST_CEILING && s.ceiling === GUEST_TRUST_CEILING ? null : 'trust_ceiling ' + GUEST_TRUST_CEILING].filter(Boolean);if (flags.length) out.push({ level: 'fail', text: 'source ' + s.id + ' is missing ' + flags.join(', '), fix: init });if (s.local_path) out.push({ level: 'fail', text: 'source ' + s.id + ' has a local path; a guest source is database-only' });@@ -72,11 +74,10 @@ export async function guestSourceCheck(engine: BrainEngine): Promise<Check> {try {const sources = await engine.executeRaw<GuestSourceRow>('SELECT s.id, s.local_path, s.config, g.writers, g.trust_ceiling AS ceiling FROM sources s LEFT JOIN guest_sources g ON g.source_id = s.id '- + "WHERE g.source_id IS NOT NULL OR s.config->>'guest' = 'true' ORDER BY s.id");+ + 'WHERE ' + guestSourceSql('s.config', 's.id') + ' ORDER BY s.id');if (!sources.length) return infoCheck(name, 'Not applicable: this brain has no guest source (gbrain guests init).', 'not_applicable');- const present = (await engine.getConfig(GUEST_SOURCES_PRESENT_KEY)) === 'true';const findings: Finding[] = [];- for (const s of sources) findings.push(...await sourceFindings(engine, s, present));+ for (const s of sources) findings.push(...await sourceFindings(engine, s));const ids = sources.map(s => s.id).join(', ');const details = { sources: sources.map(s => ({ source: s.id, writers: s.writers ?? [] })), findings: findings.map(f => ({ level: f.level, text: f.text })) };if (!findings.length) return { name, status: 'ok', message: 'Guest source(s) ' + ids + ': flags, ceiling and writers in place, and every owner credential reads them.', details };diff --git a/test/doctor-guest-source.test.ts b/test/doctor-guest-source.test.tsindex 5fb1e718bb..73cfae7fa6 100644--- a/test/doctor-guest-source.test.ts+++ b/test/doctor-guest-source.test.ts@@ -2,9 +2,10 @@* guest_source doctor check (GBRA-504 slice 4).** Protects: not_applicable without a guest source; ok for a guest source with its flags, ceiling and a live writer- * whose grant is exactly the guest source, read by every owner credential; fail when a source is marked guest but the- * brain's guests.present marker is unset (reads would skip the warning), when a source says guest without its- * guest_sources row, when a writer names a removed client, or when a writer's grant reaches another source; warn, with+ * whose grant is exactly the guest source, read by every owner credential; fail, naming gbrain guests init as the+ * repair, when the two guest records disagree (a guest_sources row whose config lost guest: true, or a config that says+ * guest with no guest_sources row), when a writer names a removed client, or when a writer's grant reaches another+ * source; warn, with* the exact grant command, when an owner credential cannot read the guest source, and when its min_trust floor hides* guest notes (F9). The check reads only: no grant changes. PGLite in-memory, no repository.*/@@ -16,7 +17,6 @@ import { sqlQueryForEngine } from '../src/core/sql-query.ts';import { addMember, bindCredential } from '../src/core/access/members.ts';import { setOwner } from '../src/core/access/owner.ts';import { initGuestSource } from '../src/core/guests/sources.ts';-import { GUEST_SOURCES_PRESENT_KEY } from '../src/core/guests/marker.ts';import { guestSourceCheck } from '../src/commands/doctor/checks/guest-source.ts';import { categorizeCheck } from '../src/core/doctor-categories.ts';import { setMinTrust } from '../src/core/trust/min-trust.ts';@@ -64,21 +64,24 @@ describe('guest_source doctor check', () => {expect({ status: check.status, message: check.message }).toEqual({ status: 'ok', message: expect.stringContaining(SRC) });}, 60_000);- test('a source marked guest while guests.present is unset fails', async () => {+ test('a guest_sources row whose config lost guest: true fails as a disagreement and names the repair', async () => {await healthyBrain();- await engine.executeRaw('DELETE FROM config WHERE key = $1', [GUEST_SOURCES_PRESENT_KEY]);+ await engine.executeRaw("UPDATE sources SET config = config - 'guest' WHERE id = $1", [SRC]);const check = await guestSourceCheck(engine);expect(check.status).toBe('fail');- expect(check.message).toContain(GUEST_SOURCES_PRESENT_KEY);+ expect(check.message).toContain('source ' + SRC + ' has a guest_sources row but its config does not say guest: true');+ expect(check.message).toContain('repair: gbrain guests init --source ' + SRC + ' --yes');expect(check.fix?.argv).toEqual(['gbrain', 'guests', 'init', '--source', SRC, '--yes']);}, 60_000);- test('a source whose config says guest but has no guest_sources row fails', async () => {+ test('a source whose config says guest but has no guest_sources row fails as a disagreement and names the repair', async () => {await healthyBrain();await engine.executeRaw("UPDATE sources SET config = config || '{\"guest\": true}'::jsonb WHERE id = $1", [PLAIN]);const check = await guestSourceCheck(engine);expect(check.status).toBe('fail');- expect(check.message).toContain(PLAIN);+ expect(check.message).toContain('source ' + PLAIN + ' says guest: true in its config but has no guest_sources row');+ expect(check.message).toContain('repair: gbrain guests init --source ' + PLAIN + ' --yes');+ expect(check.fix?.argv).toEqual(['gbrain', 'guests', 'init', '--source', PLAIN, '--yes']);}, 60_000);test('a writer naming a removed client, or a writer granted another source, fails', async () => {diff --git a/test/fixtures/goldens/doctor/hot-checks-postgres-json.json b/test/fixtures/goldens/doctor/hot-checks-postgres-json.jsonindex bcbb72de8b..4b5353e5fc 100644--- a/test/fixtures/goldens/doctor/hot-checks-postgres-json.json+++ b/test/fixtures/goldens/doctor/hot-checks-postgres-json.json@@ -1232,10 +1232,19 @@"severity": "info","status": "ok"},+ {+ "category": "brain",+ "elapsed_ms": "<volatile>",+ "message": "Not applicable: this brain has no guest source (gbrain guests init).",+ "name": "guest_source",+ "readiness_state": "not_applicable",+ "severity": "info",+ "status": "ok"+ },{"category": "ops","elapsed_ms": "<volatile>",- "message": "RLS enabled on 178/178 public tables",+ "message": "RLS enabled on 181/181 public tables","name": "rls","status": "ok"},@@ -1277,7 +1286,7 @@{"category": "meta","elapsed_ms": "<volatile>",- "message": "All 178 table(s) the applied migrations create exist.",+ "message": "All 181 table(s) the applied migrations create exist.","name": "schema_missing_tables","status": "ok"},@@ -6562,10 +6571,19 @@"severity": "info","status": "ok"},+ {+ "category": "brain",+ "elapsed_ms": "<volatile>",+ "message": "Not applicable: this brain has no guest source (gbrain guests init).",+ "name": "guest_source",+ "readiness_state": "not_applicable",+ "severity": "info",+ "status": "ok"+ },{"category": "ops","elapsed_ms": "<volatile>",- "message": "RLS enabled on 178/178 public tables",+ "message": "RLS enabled on 181/181 public tables","name": "rls","status": "ok"},@@ -6607,7 +6625,7 @@{"category": "meta","elapsed_ms": "<volatile>",- "message": "All 178 table(s) the applied migrations create exist.",+ "message": "All 181 table(s) the applied migrations create exist.","name": "schema_missing_tables","status": "ok"},diff --git a/test/fixtures/goldens/doctor/json-postgres-fresh.json b/test/fixtures/goldens/doctor/json-postgres-fresh.jsonindex fadedf9ad3..da3cc89462 100644--- a/test/fixtures/goldens/doctor/json-postgres-fresh.json+++ b/test/fixtures/goldens/doctor/json-postgres-fresh.json@@ -1121,6 +1121,15 @@"severity": "info","status": "ok"},+ {+ "category": "brain",+ "elapsed_ms": "<volatile>",+ "message": "Not applicable: this brain has no guest source (gbrain guests init).",+ "name": "guest_source",+ "readiness_state": "not_applicable",+ "severity": "info",+ "status": "ok"+ },{"category": "ops","elapsed_ms": "<volatile>",