Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Engine graduation target side (`src/core/persistence/graduation-target.ts`).
*
* Protects: route resolution (`--url` / `--url-env`, explicit and derived DDL
* routes, no automatic session-pooler route), the target identity hash that
* excludes the password, redaction (no display form, refusal or blocker
* carries the password), plan blockers from a probe, and on Postgres the
* read-only probes (empty database, initialised seed-only schema, a schema
* with user rows, denied replica mode with table ownership, a non-owner with
* no bypass, wrong password), the nonce cross-check between routes (same
* database passes, a different database refuses) and the target engine pair.
* Fails when: a secret leaks into output, a password rotation changes the
* identity, a probe writes, or routes naming different databases pass.
* Seams: none; the Postgres cases need DATABASE_URL.
*/
import { afterAll, describe, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import postgres from '#postgres';
import { PostgresEngine } from '../src/core/postgres-engine.ts';
import type { TargetProbe } from '../src/core/persistence/engine-graduation.types.ts';
import {
assertTargetReachable, chooseTriggerBypass, connectTargetEngines, crossCheckRoutes, probeTarget, redactTargetUrl, resolveTargetRoutes,
targetIdentity, targetProbeBlockers,
} from '../src/core/persistence/graduation-target.ts';
import { assertSafeE2eDatabaseUrl } from './helpers/db-guard.ts';
import { LAST_KNOWN_OP, queueRefresh } from '../src/commands/doctor/last-known.ts';
const SECRET = 's3cr3t-Pa55';
const thrown = (fn: () => unknown): Record<string, any> => {
try { fn(); } catch (error) { return (error as { toJSON(): Record<string, any> }).toJSON(); }
throw new Error('expected a refusal');
};
describe('routes, identity and redaction', () => {
test('--url-env reads the URL from the named variable; displays never carry the password', () => {
const routes = resolveTargetRoutes({ urlEnv: 'GBRAIN_TARGET_URL', env: { GBRAIN_TARGET_URL: `postgresql://alice:${SECRET}@db.example.com:6432/brain?sslmode=require&password=${SECRET}` } });
expect(routes).toMatchObject({ main: 'postgres://[email protected]:6432/brain', ddl: 'postgres://[email protected]:6432/brain', urlEnv: 'GBRAIN_TARGET_URL' });
expect(routes.ddlUrl).toBe(routes.mainUrl);
expect(JSON.stringify({ main: routes.main, ddl: routes.ddl })).not.toContain(SECRET);
});
test('Supabase transaction pooler derives the direct DDL route; an explicit override wins and is final', () => {
const url = `postgresql://postgres.abcdefghijklmnop:${SECRET}@aws-0-us-east-1.pooler.supabase.com:6543/postgres`;
const derived = resolveTargetRoutes({ url, env: {} });
expect(derived.ddl).toBe('postgres://[email protected]:5432/postgres');
const session = `postgresql://postgres.abcdefghijklmnop:${SECRET}@aws-0-us-east-1.pooler.supabase.com:5432/postgres`;
const explicit = resolveTargetRoutes({ url, env: { GBRAIN_DIRECT_DATABASE_URL: session } });
expect(explicit.ddlUrl).toBe(session);
expect(explicit.ddl).not.toContain(SECRET);
});
test('missing, doubled and non-Postgres targets refuse with --url-env commands', () => {
const missing = thrown(() => resolveTargetRoutes({ urlEnv: 'MY_TARGET', env: {} }));
expect(missing).toMatchObject({ code: 'graduation_target_unsupported' });
expect(missing.fix.argv).toEqual(['gbrain', 'migrate', '--to', 'postgres', '--url-env', 'MY_TARGET', '--plan', '--json']);
expect(thrown(() => resolveTargetRoutes({ url: 'postgres://a@h/d', urlEnv: 'X', env: { X: 'postgres://a@h/d' } })).code).toBe('graduation_target_unsupported');
const mysql = thrown(() => resolveTargetRoutes({ url: `mysql://root:${SECRET}@h/d`, env: {} }));
expect(JSON.stringify(mysql)).not.toContain(SECRET);
});
test('the identity hashes host, port, database and user, never the password', () => {
const a = targetIdentity(`postgres://alice:${SECRET}@DB.example.com/brain`);
const b = targetIdentity('postgres://alice:[email protected]:5432/brain');
expect(a).toEqual(b);
expect(a).toMatchObject({ host: 'db.example.com', port: 5432, database: 'brain', user: 'alice' });
expect(JSON.stringify(a)).not.toContain(SECRET);
expect(targetIdentity('postgres://alice:[email protected]/other').id).not.toBe(a.id);
expect(targetIdentity('postgres://bob:[email protected]/brain').id).not.toBe(a.id);
expect(targetIdentity('postgres://[email protected]').database).toBe('alice');
expect(redactTargetUrl(`postgres://alice:${SECRET}@h:1/d?password=${SECRET}`)).toBe('postgres://alice@h:1/d');
});
});
const baseProbe: TargetProbe = {
reachable: true, auth: true, ddl: { reachable: true, auth: true }, serverVersion: '16.4', serverVersionNum: 160004,
vector: { installed: null, available: '0.8.0', halfvec: true }, createPrivilege: { database: true, schema: true },
replicaRole: true, ownsTables: true, triggerBypass: 'session_replication_role', gbrainSchema: false, empty: true, nonEmptyTables: [],
embeddingColumns: [], otherSessions: 0,
};
describe('plan blockers from a probe', () => {
const routes = { main: 'postgres://alice@h:5432/d', ddl: 'postgres://alice@h:5432/d', urlEnv: 'GBRAIN_TARGET_URL' };
test('a ready target has none', () => { expect(targetProbeBlockers(baseProbe, routes)).toEqual([]); });
test('each unmet prerequisite names itself', () => {
const probe: TargetProbe = { ...baseProbe, serverVersion: '13.9', serverVersionNum: 130009, vector: { installed: '0.6.0', available: '0.6.0', halfvec: false },
createPrivilege: { database: false, schema: false }, replicaRole: false, ownsTables: false, triggerBypass: null, empty: false, nonEmptyTables: ['pages'],
embeddingColumns: [{ relation: 'content_chunks', column: 'embedding', type: 'vector(768)', dims: 768 }] };
const ids = targetProbeBlockers(probe, routes, [{ relation: 'content_chunks', column: 'embedding', type: 'vector(1536)', dims: 1536 }]).map(b => `${b.kind}:${b.id}`);
expect(ids).toEqual(['target_unsupported:server_version', 'target_unsupported:vector_halfvec', 'target_unsupported:create_privilege',
'target_unsupported:trigger_bypass', 'target_not_empty:target', 'embedding_dimension:content_chunks.embedding']);
});
test('a non-superuser role gets the exact SQL a DBA runs for vector, BYPASSRLS and the auto-RLS event trigger', () => {
const probe: TargetProbe = { ...baseProbe, vector: { installed: null, available: '0.8.0', halfvec: true },
role: { name: 'gbrain_app', superuser: false, bypassRls: false }, autoRls: { eventTrigger: false, functionOwner: null } };
const blockers = targetProbeBlockers(probe, routes);
expect(blockers.map(b => b.id)).toEqual(['vector_extension', 'bypassrls', 'auto_rls_event_trigger']);
expect(blockers[0]!.detail).toContain('CREATE EXTENSION IF NOT EXISTS vector;');
expect(blockers[1]!.detail).toContain('ALTER ROLE "gbrain_app" BYPASSRLS;');
expect(blockers[2]!.detail).toContain('ALTER FUNCTION public.auto_enable_rls() OWNER TO "gbrain_app";');
const owned = targetProbeBlockers({ ...probe, vector: { installed: '0.8.0', available: '0.8.0', halfvec: true }, role: { name: 'gbrain_app', superuser: false, bypassRls: true },
autoRls: { eventTrigger: true, functionOwner: 'postgres' } }, routes);
expect(owned.map(b => b.id)).toEqual(['auto_rls_owner']);
expect(targetProbeBlockers({ ...probe, role: { name: 'postgres', superuser: true, bypassRls: true } }, routes)).toEqual([]);
});
test('auth failure, unreachable DDL route and the forced bypass', () => {
const auth = thrown(() => assertTargetReachable({ ...baseProbe, auth: false, error: { code: '28P01', message: 'password authentication failed' } }, routes));
expect(auth).toMatchObject({ code: 'graduation_target_auth_failed' });
expect(auth.fix.argv).toContain('--url-env');
const ddl = thrown(() => assertTargetReachable({ ...baseProbe, ddl: { reachable: false, auth: false, error: { code: 'ENETUNREACH', message: 'x' } } }, routes));
expect(ddl).toMatchObject({ code: 'graduation_target_ddl_unreachable' });
expect(ddl.suggestion).toContain('GBRAIN_DIRECT_DATABASE_URL');
expect(chooseTriggerBypass({ replicaRole: false, triggerBypass: 'disable_trigger' }, 'session_replication_role')).toBeNull();
expect(chooseTriggerBypass({ replicaRole: true, triggerBypass: 'session_replication_role' }, 'disable_trigger')).toBe('disable_trigger');
});
});
const databaseUrl = process.env.DATABASE_URL;
describe.skipIf(!databaseUrl)('Postgres probes and the route cross-check', () => {
const created: string[] = [];
const roles: string[] = [];
const admin = databaseUrl ? (assertSafeE2eDatabaseUrl(databaseUrl), postgres(databaseUrl, { max: 1, prepare: false, onnotice: () => {} })) : null;
const urlFor = (database: string, user?: string, password?: string) => {
const url = new URL(databaseUrl!); url.pathname = `/${database}`;
if (user) { url.username = user; url.password = password ?? ''; }
return url.toString();
};
const freshDatabase = async (owner?: string) => {
const name = `gbrain_test_graduation_target_${randomUUID().replace(/-/g, '')}`;
await admin!.unsafe(`CREATE DATABASE ${name}${owner ? ` OWNER ${owner}` : ''}`);
created.push(name);
return name;
};
afterAll(async () => {
for (const name of created) await admin!.unsafe(`DROP DATABASE IF EXISTS ${name} WITH (FORCE)`).catch(() => {});
for (const role of roles) await admin!.unsafe(`DROP ROLE IF EXISTS ${role}`).catch(() => {});
await admin?.end();
});
test('empty, seed-only and non-empty targets; probes never write', async () => {
const name = await freshDatabase();
const routes = resolveTargetRoutes({ url: urlFor(name), env: {} });
const empty = await probeTarget(routes);
expect(empty).toMatchObject({ reachable: true, auth: true, empty: true, gbrainSchema: false, replicaRole: true, triggerBypass: 'session_replication_role',
createPrivilege: { database: true, schema: true }, ddl: { reachable: true, auth: true } });
expect(empty.serverVersionNum).toBeGreaterThanOrEqual(140000);
expect(empty.vector.halfvec).toBe(true);
expect(targetProbeBlockers(empty, routes)).toEqual([]);
const db = postgres(routes.mainUrl, { max: 1, onnotice: () => {} });
const [relations] = await db.unsafe("SELECT count(*)::int AS n FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = 'public'");
expect(relations!.n).toBe(0);
await db.end();
const engine = new PostgresEngine();
await engine.connect({ database_url: routes.mainUrl, poolSize: 2 });
try {
await engine.initSchema();
const seeded = await probeTarget(routes);
expect(seeded).toMatchObject({ empty: true, gbrainSchema: true, nonEmptyTables: [] });
expect(seeded.embeddingColumns.map(c => `${c.relation}.${c.column}`)).toEqual(expect.arrayContaining(['content_chunks.embedding', 'facts.embedding']));
// #7142: a doctor run's last known results and its queued refresh are not brain data.
await engine.executeRaw(`INSERT INTO op_checkpoints (op, fingerprint, completed_keys) VALUES ($1, 'queue_health', '[{}]'::jsonb), ($1, 'schema_version', '[{}]'::jsonb)`, [LAST_KNOWN_OP]);
expect(await queueRefresh(engine)).not.toBeNull();
expect(await probeTarget(routes)).toMatchObject({ empty: true, nonEmptyTables: [] });
await engine.executeRaw("INSERT INTO sources (id, name) VALUES ('notes', 'Notes')");
await engine.executeRaw("UPDATE persistence_brain SET enabled = true");
const used = await probeTarget(routes);
expect(used.empty).toBe(false);
expect(used.nonEmptyTables).toEqual(['persistence_brain', 'sources']);
} finally { await engine.disconnect(); }
}, 120_000);
test('a wrong password is an auth failure with nothing secret in the refusal', async () => {
const name = await freshDatabase();
const routes = resolveTargetRoutes({ url: urlFor(name, new URL(databaseUrl!).username, SECRET), env: {} });
const probe = await probeTarget(routes, { timeoutSeconds: 5 });
expect(probe).toMatchObject({ reachable: true, auth: false });
const json = thrown(() => assertTargetReachable(probe, routes));
expect(json.code).toBe('graduation_target_auth_failed');
expect(JSON.stringify({ json, probe })).not.toContain(SECRET);
}, 60_000);
test('a non-superuser owner cannot use replica mode but owns its tables; a non-owner has no bypass', async () => {
const owner = `gbrain_grad_owner_${randomUUID().slice(0, 8)}`;
const other = `gbrain_grad_other_${randomUUID().slice(0, 8)}`;
await admin!.unsafe(`CREATE ROLE ${owner} LOGIN PASSWORD 'pw'`); roles.push(owner);
await admin!.unsafe(`CREATE ROLE ${other} LOGIN PASSWORD 'pw'`); roles.push(other);
const name = await freshDatabase(owner);
const db = postgres(urlFor(name), { max: 1, onnotice: () => {} });
await db.unsafe(`ALTER SCHEMA public OWNER TO ${owner}`);
await db.unsafe(`CREATE TABLE owned (id int PRIMARY KEY)`);
await db.unsafe(`ALTER TABLE owned OWNER TO ${owner}`);
await db.unsafe(`GRANT CONNECT ON DATABASE ${name} TO ${other}`);
await db.end();
const ownerProbe = await probeTarget(resolveTargetRoutes({ url: urlFor(name, owner, 'pw'), env: {} }));
expect(ownerProbe).toMatchObject({ replicaRole: false, ownsTables: true, triggerBypass: 'disable_trigger' });
const otherProbe = await probeTarget(resolveTargetRoutes({ url: urlFor(name, other, 'pw'), env: {} }));
expect(otherProbe).toMatchObject({ replicaRole: false, ownsTables: false, triggerBypass: null });
expect(targetProbeBlockers(otherProbe, { main: 'm' }).map(b => b.id)).toContain('trigger_bypass');
}, 60_000);
test('the nonce cross-check passes for one database and refuses a DDL route to another', async () => {
const a = await freshDatabase();
const b = await freshDatabase();
const pair = await connectTargetEngines(resolveTargetRoutes({ url: urlFor(a), env: { GBRAIN_DIRECT_DATABASE_URL: urlFor(a) } }));
try {
await crossCheckRoutes(pair.main, pair.ddl, 'run-same');
} finally { await pair.close(); }
const wrong = await connectTargetEngines(resolveTargetRoutes({ url: urlFor(a), env: { GBRAIN_DIRECT_DATABASE_URL: urlFor(b) } }));
try {
let error: unknown;
try { await crossCheckRoutes(wrong.main, wrong.ddl, 'run-wrong'); } catch (e) { error = e; }
const json = (error as { toJSON(): Record<string, any> }).toJSON();
expect(json.code).toBe('graduation_target_ddl_unreachable');
expect(json.why).toContain('run-wrong');
} finally { await wrong.close(); }
expect(process.env.GBRAIN_DIRECT_DATABASE_URL).toBeUndefined();
}, 60_000);
});