Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Guest notes, slice 4 (GBRA-504, decision K1, F9, F10): the brain owner's credentials and the guest source.
*
* The owner's local CLI and stdio reads already include every federated source, guest sources too. A token or OAuth
* client bound to the owner (member_id = config access.owner_member) reads only the sources its grant names, so it
* sees guest notes only once a guest source is on its read list. ownerCredentials lists each such credential with its
* read list, whether it reads the guest source, the read list it would have with it, the exact grant command, and its
* min_trust floor (a floor above external_untrusted hides every guest note, F9). grantOwnerCredentials is the one
* writer: 'gbrain guests grant-owner-clients --yes' adds the guest source to each read list as a compare-and-set on
* the grant revision the preview read, keeps every source already there, and never runs on its own: gbrain widens no
* grant on upgrade or init. The doctor check guest_source (commands/doctor/checks/guest-source.ts) reads the same list.
*/
import type { BrainEngine } from '../engine.ts';
import { ownerMemberId } from '../access/owner.ts';
import { GrantError, grantFromClient, grantFromRow, grantFromTokenRow, TOKEN_GRANT_ROW_COLUMNS, type PrincipalGrant } from '../grants/model.ts';
import { readClientGrant, rescopeClientGrant } from '../grants/service.ts';
import { rescopeLegacyToken } from '../grants/legacy-token.ts';
import { compareTrust, storedMinTrust, type TrustTier } from '../trust/tier.ts';
export interface OwnerCredential {
kind: 'client' | 'token';
id: string;
name: string;
revision: number;
/** none: the explicit no-source grant; default: no source grant (reads the default source only). */
grant: PrincipalGrant['sources']['kind'];
writeSource: string | null;
readSources: string[];
readsGuest: boolean;
/** The read list with the guest source added; null when there is nothing gbrain may add to (no-source grant). */
after: string[] | null;
/** The exact command that adds the guest source to this one grant, at the revision read. */
command: string | null;
minTrust: TrustTier | null;
/** The floor admits no guest note (above external_untrusted). */
floorHidesGuests: boolean;
}
function readsOf(g: PrincipalGrant): { write: string | null; reads: string[] } {
switch (g.sources.kind) {
case 'none': return { write: null, reads: [] };
case 'default': return { write: 'default', reads: ['default'] };
case 'scalar': return { write: g.sources.writeSource, reads: [g.sources.writeSource] };
case 'federated': return { write: g.sources.writeSource, reads: [...g.sources.readSources] };
}
}
function credential(kind: 'client' | 'token', id: string, name: string, g: PrincipalGrant, minTrustValue: unknown, guest: string): OwnerCredential {
const { write, reads } = readsOf(g);
const readsGuest = reads.includes(guest);
const tokenListKept = kind === 'client' || g.sources.kind !== 'federated' || reads[0] === write;
const after = g.sources.kind === 'none' || !tokenListKept ? null : readsGuest ? reads : [...reads, guest];
const rev = ' --if-version ' + g.revision;
const command = readsGuest || !after ? null
: kind === 'token' ? 'gbrain auth rescope-token --id ' + id + ' --sources ' + after.join(',') + rev
: g.sources.kind === 'default' ? 'gbrain auth rescope --client ' + id + ' --sources ' + after.join(',') + rev
: 'gbrain auth rescope --client ' + id + ' --read-sources ' + after.join(',') + rev;
const minTrust = storedMinTrust(minTrustValue) ?? null;
return { kind, id, name, revision: g.revision, grant: g.sources.kind, writeSource: write, readSources: reads, readsGuest, after, command,
minTrust, floorHidesGuests: minTrust !== null && compareTrust(minTrust, 'external_untrusted') > 0 };
}
/** An access_tokens row as JSON with only the columns a grant and its read floor need: never the token hash. */
export const tokenGrantJsonSql = (alias: string) => `jsonb_build_object(${[...TOKEN_GRANT_ROW_COLUMNS, 'min_trust'].map(c => `'${c}', ${alias}.${c}`).join(', ')})`;
const json = (v: unknown) => (typeof v === 'string' ? JSON.parse(v) : v) as Record<string, unknown>;
/** Every live credential bound to the brain owner, read against guest source guestSourceId; no owner, no credentials. */
export async function ownerCredentials(engine: BrainEngine, guestSourceId: string): Promise<{ owner: string | null; credentials: OwnerCredential[] }> {
const owner = await ownerMemberId(engine);
if (!owner) return { owner, credentials: [] };
const rows = await engine.executeRaw<{ kind: 'client' | 'token'; id: string; name: string; row: unknown }>(
"SELECT 'token' AS kind, t.id::text AS id, t.name, " + tokenGrantJsonSql('t') + " AS row FROM access_tokens t WHERE t.member_id = $1 AND t.revoked_at IS NULL "
+ "UNION ALL SELECT 'client' AS kind, c.client_id AS id, COALESCE(c.client_name, c.client_id) AS name, to_jsonb(c) - 'client_secret_hash' AS row "
+ "FROM oauth_clients c WHERE c.member_id = $1 AND (to_jsonb(c)->>'deleted_at') IS NULL ORDER BY 1, 3, 2", [owner]);
return { owner, credentials: rows.map(r => {
const row = json(r.row);
const grant = r.kind === 'token' ? grantFromTokenRow(row) : grantFromClient(grantFromRow(row));
return credential(r.kind, r.id, r.name, grant, row.min_trust, guestSourceId);
}) };
}
export interface GrantOutcome { kind: 'client' | 'token'; id: string; name: string; outcome: 'granted' | 'conflict' | 'skipped' | 'failed'; detail?: string }
/**
* Adds guestSourceId to the read list of each previewed credential that lacks it, at the revision the preview read.
* A grant changed since (another edit, a rescope) is a conflict and stays as it is; each result is read back and must
* equal the previewed list plus the guest source. Any other failure is that credential's outcome (failed, with the
* error), so one credential never stops the others.
*/
export async function grantOwnerCredentials(engine: BrainEngine, guestSourceId: string, plan: readonly OwnerCredential[]): Promise<GrantOutcome[]> {
const out: GrantOutcome[] = [];
for (const c of plan) {
const base = { kind: c.kind, id: c.id, name: c.name };
if (c.readsGuest) continue;
if (!c.after) { out.push({ ...base, outcome: 'skipped', detail: c.grant === 'none' ? 'it has no source grant' : 'its write source is not on its read list; change it by hand' }); continue; }
try {
if (c.kind === 'client') {
const patch = c.grant === 'default' ? { sourceId: 'default', federatedRead: c.after } : { federatedRead: c.after };
await rescopeClientGrant(engine, c.id, patch, { actor: 'operator:guests-grant-owner-clients', expectedRevision: c.revision });
const now = grantFromClient(await readClientGrant(engine, c.id));
if (JSON.stringify(readsOf(now).reads) !== JSON.stringify(c.after)) throw new Error('read back ' + readsOf(now).reads.join(', '));
} else {
const result = await rescopeLegacyToken(engine, { target: { id: c.id }, sources: c.after, expectedRevision: c.revision,
reset: [], refreshOperations: false, allNew: false, dryRun: false, json: false });
if (JSON.stringify(result.after.sources) !== JSON.stringify(c.after)) throw new Error('read back ' + JSON.stringify(result.after.sources));
}
out.push({ ...base, outcome: 'granted' });
} catch (e) {
const conflict = e instanceof GrantError && e.code === 'grant_conflict';
out.push({ ...base, outcome: conflict ? 'conflict' : 'failed', detail: e instanceof Error ? e.message : String(e) });
}
}
return out;
}