Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Guest notes, slice 2 (GBRA-504): write admission for a guest source.
*
* A guest source (guests/sources.ts) takes page writes only from a principal on its writer list, only as a new page
* through put_page, and only with the guest attribution the broker sends beside the call: the X-Gbrain-Guest header
* (URL-encoded form, `sender_label=<label>&group=<group-slug>`) or request-level `_meta.guest`
* (`{ sender_label, group }`). The attribution joins the stored write intent as `guest_note`, so a
* replay with different attribution is idempotency_conflict, and publication turns it into the page's guest_marks row.
* The page's frontmatter keeps to an allowlist, names the sender and group the attribution names, and is readable
* by exactly the brain owner plus the call's one audience principal. Every refusal here writes nothing; the database
* trigger (trust/schema.ts GUEST_GUARD) is the backstop for any path that bypasses this module.
*/
import type { BrainEngine } from '../engine.ts';
import { OperationError } from '../ops/contract.ts';
import { parseMarkdownHead } from '../markdown.ts';
import { normalizeReaders } from '../access/principals.ts';
import { ownerMemberId } from '../access/owner.ts';
import type { Principal } from '../persistence/model.ts';
import type { GuestSource } from './sources.ts';
import { GUEST_SOURCES_HIDDEN_SQL, type GuestAttribution } from './note.ts';
import { schemaAdmissionRefusal } from '../persistence/schema-admission.ts';
import { isMissingSchemaObject } from '../utils.ts';
export { GUEST_NOTE_INTENT_KEY, type GuestAttribution } from './note.ts';
export const GUEST_HEADER = 'X-Gbrain-Guest';
/** The only frontmatter keys a guest page may carry. */
export const GUEST_FRONTMATTER_KEYS: readonly string[] = ['type', 'title', 'readable_by', 'guest_group', 'guest_sender', 'saved_at'];
const DOCS = (code: string) => `docs/guides/write-refusals.md#${code}`;
/** The attribution channels a transport saw: the header and request-level _meta (its `guest` key). */
export interface GuestChannels { header?: string | null; requestMeta?: unknown }
const LABEL_FORBIDDEN = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}·[\]<>"]/u;
const GROUP_RE = /^[a-z0-9-]{1,64}$/;
const isObj = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v);
export function guestAttributionMissing(why: string): OperationError {
return new OperationError('guest_attribution_missing', `A write to a guest source needs guest attribution: ${why}. Nothing was written.`,
'Send the sender label and group slug beside the call, as request-level _meta.guest {"sender_label": "...", "group": "..."} or the X-Gbrain-Guest header (sender_label=<url-encoded label>&group=<group-slug>). A label is 1 to 64 characters with no control or format characters and none of · [ ] < > ".',
DOCS('guest_attribution_missing'));
}
function checked(value: unknown, channel: string): GuestAttribution {
if (!isObj(value)) throw guestAttributionMissing(`${channel} is not an object with sender_label and group`);
const { sender_label: label, group } = value;
if (typeof label !== 'string' || [...label].length < 1 || [...label].length > 64 || LABEL_FORBIDDEN.test(label) || label.trim() !== label) {
throw guestAttributionMissing(`${channel} sender_label is missing or not an allowed label`);
}
if (typeof group !== 'string' || !GROUP_RE.test(group)) throw guestAttributionMissing(`${channel} group is missing or not a group slug`);
return { sender_label: label, group };
}
/** The attribution a call carries, or null when it carries none; malformed or disagreeing channels refuse. */
export function parseGuestAttribution(channels: GuestChannels | undefined): GuestAttribution | null {
const header = typeof channels?.header === 'string' && channels.header.trim() !== '' ? channels.header : null;
const meta = isObj(channels?.requestMeta) && Object.hasOwn(channels.requestMeta, 'guest') ? channels.requestMeta.guest : undefined;
let fromHeader: GuestAttribution | null = null;
if (header !== null) {
const form = new URLSearchParams(header);
fromHeader = checked({ sender_label: form.get('sender_label'), group: form.get('group') }, 'the ' + GUEST_HEADER + ' header');
}
const fromMeta = meta === undefined ? null : checked(meta, '_meta.guest');
if (fromHeader && fromMeta && (fromHeader.sender_label !== fromMeta.sender_label || fromHeader.group !== fromMeta.group)) {
throw guestAttributionMissing('the ' + GUEST_HEADER + ' header and _meta.guest name different senders or groups');
}
return fromMeta ?? fromHeader;
}
/** A lookup of guest_sources by a role that row-level security keeps from reading it (GUEST_SOURCES_HIDDEN_SQL). */
export function guestSourcesUnreadable(sourceId: string): OperationError {
return new OperationError('writer_coordinator_required',
`writer_coordinator_required: writer state is unreadable to this database role: row-level security hides guest_sources, so gbrain cannot tell whether source ${sourceId} is a guest source. Nothing was written.`,
'Run gbrain as a database role that can read guest_sources (the table owner, a role that bypasses row-level security, or a scoped write role holding the guest_sources SELECT policy in docs/ENGINES.md#derived-state-maintainers), then retry with a new request ID.',
'docs/guides/write-refusals.md#writer-coordinator-required');
}
/**
* A guest-table read that failed: on a brain whose schema is behind the guest-notes migration (no guest_sources table)
* the write is refused migrations_pending (schema-admission.ts), as admission refuses any write on a schema behind this
* build, instead of failing with the raw missing-table error. Any other error is rethrown.
*/
export async function schemaBehindGuests(exec: Pick<BrainEngine, 'executeRaw'>, error: unknown): Promise<never> {
if (isMissingSchemaObject(error, 'table', 'guest_sources')) {
const refusal = await schemaAdmissionRefusal(exec as BrainEngine);
if (refusal) throw refusal;
}
throw error;
}
/**
* The guest_sources row of `sourceId`, or null when it is not a guest source. One statement; refuses
* (guestSourcesUnreadable) when row-level security hides guest_sources from the role instead of answering null.
*/
export async function lookupGuestSource(exec: Pick<BrainEngine, 'executeRaw'>, sourceId: string): Promise<GuestSource | null> {
const [row] = await exec.executeRaw<GuestSource & { hidden: boolean }>(
`SELECT ${GUEST_SOURCES_HIDDEN_SQL} AS hidden, g.source_id, g.writers, g.trust_ceiling FROM (SELECT 1) AS one LEFT JOIN guest_sources g ON g.source_id = $1`, [sourceId])
.catch(e => schemaBehindGuests(exec, e));
if (row?.hidden) throw guestSourcesUnreadable(sourceId);
return row?.source_id ? { source_id: row.source_id, writers: row.writers, trust_ceiling: row.trust_ceiling } : null;
}
export function sourceWriterRestricted(sourceId: string): OperationError {
return new OperationError('source_writer_restricted', `Source ${sourceId} is a guest source: only its listed writers create pages there, and nothing else writes to it. Nothing was written.`,
"Do not retry. Write to another source, or ask the brain owner whether this content belongs in the guest source; changing who may write there is the owner's decision.",
DOCS('source_writer_restricted'));
}
export function guestPageImmutable(what: string): OperationError {
return new OperationError('guest_page_immutable', `${what}: a guest page is saved once, as a new page, and never changed. Nothing was written.`,
'Save the note again under a new slug with put_page, or ask the brain owner to promote the page (gbrain guests promote) and edit the owner page.',
DOCS('guest_page_immutable'));
}
export function guestPagePromoted(slug: string): OperationError {
return new OperationError('guest_page_promoted', `The brain owner kept guest note ${slug} as an owner page, so it is not deleted remotely. Nothing was deleted.`,
'Do not retry. Treat the note as kept; only the brain owner removes it, on the brain host.', DOCS('guest_page_promoted'));
}
export function guestNoteNotYours(slug: string): OperationError {
return new OperationError('permission_denied', `Guest note ${slug} was saved by another writer, so this credential cannot delete it. Nothing was deleted.`,
'Delete only the guest notes this credential saved; the brain owner deletes any guest note on the brain host (gbrain delete).', 'docs/guides/guest-notes.md#save-a-guest-note-for-the-writer');
}
/**
* A remote delete of a page in a guest source: refused when the owner promoted it (guest_promotions) and when its guest
* mark names another writer than `principal` (a writer deletes only what it saved). Checked at submission and in publication.
*/
export async function refuseRemoteGuestDelete(exec: Pick<BrainEngine, 'executeRaw'>, sourceId: string, slug: string, principal: Principal): Promise<void> {
const [page] = await exec.executeRaw<{ hidden: boolean; guest: boolean; kept: boolean; writer: string | null }>(
`SELECT ${GUEST_SOURCES_HIDDEN_SQL} AS hidden, EXISTS (SELECT 1 FROM guest_sources g WHERE g.source_id = p.source_id) AS guest, EXISTS (SELECT 1 FROM guest_promotions g WHERE g.guest_page_id = p.id) AS kept,
(SELECT m.writer_kind || ':' || m.writer_id FROM guest_marks m WHERE m.page_id = p.id) AS writer FROM pages p WHERE p.source_id = $1 AND p.slug = $2 LIMIT 1`, [sourceId, slug])
.catch(e => schemaBehindGuests(exec, e));
if (page?.hidden) throw guestSourcesUnreadable(sourceId);
if (!page?.guest && !page?.kept) return;
if (page.kept) throw guestPagePromoted(slug);
if (page.writer !== principalKey(principal)) throw guestNoteNotYours(slug);
}
const principalKey = (principal: Principal) => `${principal.kind}:${principal.id}`;
export const isListedWriter = (guest: Pick<GuestSource, 'writers'>, principal: Principal) => guest.writers.includes(principalKey(principal));
/**
* The first gate on a guest source, before any page is read: who may submit which operation. A principal not on the
* writer list may only delete or restore, and only from the trusted local CLI (the owner); a listed writer may delete,
* or create through a plain single put_page. Returns the attribution a listed writer's put_page carries.
*/
export function admitGuestOperation(guest: GuestSource, input: { principal: Principal; operation: string; remote: boolean;
plainPut: boolean; params: Record<string, unknown>; channels: GuestChannels | undefined }): GuestAttribution | null {
const { principal, operation } = input;
if (!isListedWriter(guest, principal)) {
if (!input.remote && (operation === 'delete_page' || operation === 'restore_page')) return null;
throw sourceWriterRestricted(guest.source_id);
}
if (operation === 'delete_page') return null;
if (operation !== 'put_page') throw guestPageImmutable(`${operation} on a guest source`);
if (!input.plainPut) throw guestPageImmutable('A batch, staged-upload or imported page write on a guest source');
if (input.params.force === true || input.params.expected_revision !== undefined) throw guestPageImmutable('force or expected_revision on a guest page');
const note = parseGuestAttribution(input.channels);
if (!note) throw guestAttributionMissing('the call carries neither _meta.guest nor the ' + GUEST_HEADER + ' header');
return note;
}
/** Refuses any write other than a page through admitGuestOperation (remember, links, import) on a guest source. */
export async function refuseGuestSourceWrite(engine: Pick<BrainEngine, 'executeRaw'>, sourceId: string, principalOf: () => Promise<Principal>, operation: string): Promise<void> {
const guest = await lookupGuestSource(engine, sourceId);
if (!guest) return;
if (isListedWriter(guest, await principalOf())) throw guestPageImmutable(`${operation} on a guest source`);
throw sourceWriterRestricted(sourceId);
}
export function guestFrontmatterRefused(why: string): OperationError {
return new OperationError('guest_frontmatter_refused', `A guest page's frontmatter ${why}. Nothing was written.`,
`Send only ${GUEST_FRONTMATTER_KEYS.join(', ')} in the frontmatter, with guest_sender and guest_group equal to the attribution's sender_label and group.`,
DOCS('guest_frontmatter_refused'));
}
export function guestReadersInvalid(why: string): OperationError {
return new OperationError('guest_readers_invalid', `A guest page's readable_by ${why}. Nothing was written.`,
'Set readable_by to exactly the brain owner and the one member or group the call speaks for (X-Gbrain-On-Behalf-Of), for example [alice-example, group:team-a].',
DOCS('guest_readers_invalid'));
}
/** The frontmatter allowlist and the sender and group match, read from the raw frontmatter keys. */
export function assertGuestFrontmatter(content: unknown, note: GuestAttribution): Record<string, unknown> {
if (typeof content !== 'string') throw guestFrontmatterRefused('is missing (send the page as content)');
const frontmatter = parseMarkdownHead(content).frontmatter;
const extra = Object.keys(frontmatter).filter(key => !GUEST_FRONTMATTER_KEYS.includes(key));
if (extra.length) throw guestFrontmatterRefused(`carries keys outside the allowlist (${extra.slice(0, 5).join(', ')})`);
if (frontmatter.guest_sender !== note.sender_label) throw guestFrontmatterRefused("has a guest_sender that is not the attribution's sender_label");
if (frontmatter.guest_group !== note.group) throw guestFrontmatterRefused("has a guest_group that is not the attribution's group");
return frontmatter;
}
/** Readers are exactly {owner, the single audience principal}; checked at submission and again at preparation. */
export async function assertGuestReaders(engine: Pick<BrainEngine, 'getConfig'>, frontmatter: Record<string, unknown>, audience: readonly string[] | null | undefined): Promise<string> {
if (!audience || audience.length !== 1 || audience[0] === 'guest') throw guestReadersInvalid('needs a call that speaks for exactly one member or group');
const owner = await ownerMemberId(engine);
if (!owner) throw guestReadersInvalid('cannot be checked: this brain has no owner set (gbrain access owner set)');
const readers = normalizeReaders(frontmatter);
const want = new Set([`member:${owner}`, audience[0]!]);
if (!readers || readers.length !== want.size || !readers.every(r => want.has(r))) throw guestReadersInvalid('is not exactly the brain owner and the audience the call speaks for');
return audience[0]!;
}
/**
* Publication's recheck: the source is still a guest source and the request's principal is still a listed writer. The
* same statement sets gbrain.guest_note to the request's id (the gbrain.write_request it publishes as), which the guest-source trigger (trust/schema.ts GUEST_GUARD)
* requires of a listed writer's page write; any other write to a guest source, such as one admitted before its source
* became a guest source, is refused there (source_writer_restricted or guest_attribution_missing) with no read here.
*/
export async function assertGuestWriterAtPublication(tx: Pick<BrainEngine, 'executeRaw'>, row: { source_id: string; principal_kind: string; principal_id: string; id: string }): Promise<void> {
const [guest] = await tx.executeRaw<{ writers: string[] }>(
"SELECT writers, set_config('gbrain.guest_note', $2, true) AS guest_note FROM guest_sources WHERE source_id = $1 FOR SHARE", [row.source_id, row.id]);
if (!guest || !guest.writers.includes(`${row.principal_kind}:${row.principal_id}`)) throw sourceWriterRestricted(row.source_id);
}
/**
* The guest mark, written in the publication transaction right after the page row. A mark that writes no row (the page
* row is not there to mark) throws, so the publication rolls back instead of leaving a guest page with no mark.
*/
export async function insertGuestMark(tx: Pick<BrainEngine, 'executeRaw'>, row: { source_id: string; slug: string; principal_kind: string; principal_id: string; request_id: string },
note: GuestAttribution, audience: string): Promise<void> {
const marked = await tx.executeRaw(`INSERT INTO guest_marks (page_id, source_id, slug_at_write, audience_member, group_slug, sender_label, saved_at, writer_kind, writer_id, request_id)
SELECT p.id, p.source_id, p.slug, $3, $4, $5, now(), $6, $7, $8 FROM pages p WHERE p.source_id = $1 AND p.slug = $2 RETURNING page_id`,
[row.source_id, row.slug, audience, note.group, note.sender_label, row.principal_kind, row.principal_id, row.request_id]);
if (marked.length !== 1) {
throw new OperationError('storage_error', `The guest mark for ${row.slug} wrote ${marked.length} rows instead of one, so the guest note was not saved. Nothing was written.`,
'Retry the save with a new request_id; if it fails the same way, run gbrain doctor --json on the brain host and report the result.');
}
}