Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
14.6 KB
Raw Blame
/**
 * GST-1113 (gaps 1+2 of the internal QM provider): scope sources. Each shared QM scope (a project, channel, team or org)
 * is its own gbrain source, marked `config.qm_scope: true`. The mark is sticky: it is set when the source first enters a
 * credential's `attest_sources` and no credential change clears it, so the scope's memory stays fenced after the scope
 * credential is revoked, rotated or narrowed. An attested memory_write may name a marked source its credential lists
 * (source_id) and lands on that source's scope page (`memory/scope`, world facts read by whoever holds read on the
 * source). Four rules keep a scope's audience exactly the credentials that list it:
 *  - perCallWriteSource / storedPerCallWriteSource: the one exception to one write source per credential, only for the
 *    scope page, live at submission and re-checked at publication (actorCoverage with the source);
 *  - assertScopeSourceGrant: no credential's read grant may name a marked source it does not list itself;
 *  - assertAttestSources: a source joins attest_sources (and is marked) only when no other credential reads it and it is
 *    not default, federated or the credential's own write source; it leaves only after the credential's read grant drops it;
 *  - a marked source is never federated (isSourceFederated reads the mark), so no connection without a grant reads it.
 * Everything is database state, so a repo-less brain gets it unchanged.
 */
import type { BrainEngine } from '../engine.ts';
import type { OperationContext } from '../ops/contract.ts';
import { opError, type OperationError } from '../ops/contract.ts';
import type { WriteAuthority } from '../persistence/model.ts';
import { currentCallerAccess } from '../search/private-visibility.ts';
import { sqlQueryForEngine, type SqlQuery } from '../sql-query.ts';
import { GrantError, grantFromRow, grantFromTokenRow, type ClientGrant, type GrantSources } from '../grants/model.ts';
import { isScopeSourceConfig, normalizeSourceConfig, parseSourceConfig } from '../sources-load.ts';
import { SCOPE_PAGE_SLUG } from './principals.ts';

export { SCOPE_ATTEST_OPS } from './actor-model.ts';

/**
 * Whether this live write may target `sourceId` instead of the credential's own source: an attested memory_write that
 * named it, on a right listing it, and (when the slug is known) only for the scope page.
 */
export function perCallWriteSource(ctx: Pick<OperationContext, 'remote' | 'attestedOp' | 'attestedSource' | 'auth'>, sourceId: string, slug?: string): boolean {
  if (ctx.remote === false || ctx.attestedOp !== 'memory_write' || ctx.attestedSource !== sourceId) return false;
  if (slug !== undefined && slug !== SCOPE_PAGE_SLUG) return false;
  return !!currentCallerAccess().actor && !!ctx.auth?.attest?.sources?.includes(sourceId);
}

/**
 * The stored form: the scope source an attested memory_write was accepted for, when this authority writes it to the
 * scope page, else null. authorizeWrite exempts the owner's write source for it and re-checks it (actorCoverage).
 */
export function storedPerCallWriteSource(a: Pick<WriteAuthority, 'actingFor' | 'attestedOp' | 'attestedSource' | 'sourceId'>, slug: string): string | null {
  return a.actingFor && !Array.isArray(a.actingFor) && a.attestedOp === 'memory_write' && a.attestedSource === a.sourceId && slug === SCOPE_PAGE_SLUG
    ? a.attestedSource : null;
}

export function sourceNotAttested(sourceId: string): OperationError {
  return opError('permission_denied', `Source ${sourceId} is not one of this connection's scope sources, so nothing was saved.`,
    'Send source_id only for a scope source the brain operator listed for this credential with gbrain auth rescope --attest-sources, or omit it to save on the person\'s own member page.',
    { reason: 'source_not_attested', why: 'A scope source holds memory every member of that scope reads; only the sources the operator listed may receive it.' });
}

type Db = BrainEngine | SqlQuery;
const sqlOf = (db: Db): SqlQuery => typeof db === 'function' ? db : sqlQueryForEngine(db);

/**
 * The marked scope sources among `ids`. `lock` takes their rows in id order inside the caller's transaction: a grant
 * write FOR SHARE, an attest_sources change FOR UPDATE on the sources it marks, so the two serialize instead of each
 * missing the other's commit, while grant writes and publications (source FOR SHARE, then credential) never wait on
 * each other's source locks. Callers lock their credential row first.
 */
export async function markedScopeSources(db: Db, ids: readonly string[], lock?: 'share' | 'update'): Promise<Set<string>> {
  if (!ids.length) return new Set();
  const sql = sqlOf(db);
  const list = JSON.stringify([...new Set(ids)]);
  const rows = lock === 'update'
    ? await sql`SELECT id, config FROM sources WHERE id IN (SELECT jsonb_array_elements_text(${list}::text::jsonb)) ORDER BY id FOR UPDATE`
    : lock === 'share'
      ? await sql`SELECT id, config FROM sources WHERE id IN (SELECT jsonb_array_elements_text(${list}::text::jsonb)) ORDER BY id FOR SHARE`
      : await sql`SELECT id, config FROM sources WHERE id IN (SELECT jsonb_array_elements_text(${list}::text::jsonb))`;
  return new Set(rows.filter(r => isScopeSourceConfig(r.config)).map(r => String(r.id)));
}

export interface CredentialRef { kind: 'token' | 'client'; id: string }
interface CredentialSources { ref: CredentialRef; reads: string[]; write: string | null; attest: string[]; privatePages: boolean; privateFacts: boolean; label: string }

const same = (a: CredentialRef, b: CredentialRef | null | undefined) => !!b && a.kind === b.kind && a.id === b.id;
const strings = (v: unknown): string[] => Array.isArray(v) ? v.filter((s): s is string => typeof s === 'string') : [];

/** The sources an OAuth client's grant reads: none, or its write source (default when unset) and federated_read. */
export function clientGrantReads(g: Pick<ClientGrant, 'sourcesNone' | 'sourceId' | 'federatedRead'>): string[] {
  return g.sourcesNone === true ? [] : [...new Set([g.sourceId ?? 'default', ...g.federatedRead])];
}

/** A principal grant's read sources and write source. */
export function sourcesOf(s: GrantSources): { reads: string[]; write: string | null } {
  if (s.kind === 'default') return { reads: ['default'], write: 'default' };
  if (s.kind === 'scalar') return { reads: [s.writeSource], write: s.writeSource };
  if (s.kind === 'federated') return { reads: [...new Set([s.writeSource, ...s.readSources])], write: s.writeSource };
  return { reads: [], write: null };
}

/** Every live credential's read sources, write source and attest_sources, read through the canonical grant model. */
async function credentialSources(sql: SqlQuery): Promise<CredentialSources[]> {
  const clients = await sql`SELECT * FROM oauth_clients WHERE (to_jsonb(oauth_clients)->>'deleted_at') IS NULL`;
  const tokens = await sql`SELECT * FROM access_tokens WHERE revoked_at IS NULL`;
  return [
    ...clients.map(row => {
      const g = grantFromRow(row);
      return { ref: { kind: 'client' as const, id: g.clientId }, reads: clientGrantReads(g), write: g.sourcesNone === true ? null : g.sourceId ?? 'default',
        attest: strings(row.attest_sources), privatePages: row.private_pages === 'granted_sources', privateFacts: row.private_facts === 'granted_sources', label: `OAuth client ${g.clientId}` };
    }),
    ...tokens.map(row => ({ ref: { kind: 'token' as const, id: String(row.id) }, ...sourcesOf(grantFromTokenRow(row).sources),
      attest: strings(row.attest_sources), privatePages: row.private_pages === 'granted_sources', privateFacts: row.private_facts === 'granted_sources', label: `token ${String(row.name ?? row.id)}` })),
  ];
}

/**
 * Refuses a grant whose read sources name a marked scope source this credential does not list. `self` is the credential
 * being written (null for one not inserted yet), whose stored attest_sources are honoured. `default` is never a scope
 * source (applyAttestSources refuses it), so a default-only grant reads nothing.
 */
export async function assertScopeSourceGrant(db: Db, self: CredentialRef | null, reads: readonly string[], opts: { privatePages?: boolean; privateFacts?: boolean; writeSource?: string | null } = {}): Promise<void> {
  const sql = sqlOf(db);
  const attest = self && (opts.privatePages || opts.privateFacts || opts.writeSource) ? (await credentialSources(sql)).find(c => same(c.ref, self))?.attest ?? [] : [];
  if (opts.privatePages && attest.length) {
    throw new GrantError('invalid_grant', 'This credential lists scope sources (--attest-sources), so it cannot hold the private-pages grant; nothing changed. '
      + 'A scope credential reads only shared memory: use a separate credential for private pages.');
  }
  if (opts.privateFacts && attest.length) {
    throw new GrantError('invalid_grant', 'This credential lists scope sources (--attest-sources), so it cannot hold the private-facts grant; nothing changed. '
      + 'A scope credential reads only shared memory: use a separate credential for private facts.');
  }
  if (opts.writeSource && attest.includes(opts.writeSource)) {
    throw new GrantError('invalid_grant', `Source ${opts.writeSource} is in this credential's --attest-sources, so it cannot be its write source (where member pages live); nothing changed. `
      + 'Keep member pages and each scope in separate sources: pick another write source.');
  }
  const candidates = reads.filter(s => s !== 'default');
  if (!candidates.length) return;
  const marked = await markedScopeSources(sql, candidates, 'share');
  if (!marked.size) return;
  const own = self ? (await credentialSources(sql)).find(c => same(c.ref, self))?.attest ?? [] : [];
  const reserved = [...marked].filter(s => !own.includes(s)).sort();
  if (!reserved.length) return;
  throw new GrantError('invalid_grant', `Source ${reserved.join(', ')} is a QM scope source, so only the scope credential may read it; nothing changed. `
    + 'A scope\'s memory is read only through the credential that lists it in --attest-sources. Grant another source instead.');
}

function attestInvalid(message: string, suggestion: string): OperationError {
  return opError('invalid_params', message, suggestion, { reason: 'scope_source_reserved',
    why: 'A scope source holds memory every member of that scope reads: only credentials that list it may read it, so it must not already be readable by anyone else.' });
}

/**
 * Checks an attest_sources change for one credential (gbrain auth rescope --attest-sources) and marks each newly listed
 * source, and each listed source that lost its mark (a restore), inside the caller's transaction. The mark is never
 * cleared here. Returns whether anything was checked.
 */
export async function applyAttestSources(db: Db, self: CredentialRef, next: readonly string[] | null, before: readonly string[] | null, opts: { dryRun?: boolean } = {}): Promise<boolean> {
  const sql = sqlOf(db);
  const marked = await markedScopeSources(sql, next ?? []);
  const added = (next ?? []).filter(s => !(before ?? []).includes(s) || !marked.has(s));
  const dropped = (before ?? []).filter(s => !(next ?? []).includes(s));
  if (!added.length && !dropped.length) return false;
  // The caller holds this credential's row FOR UPDATE; the sources it marks are locked before the other grants are read.
  await markedScopeSources(sql, added, 'update');
  const all = await credentialSources(sql);
  const mine = all.find(c => same(c.ref, self));
  const stillRead = dropped.filter(s => mine?.reads.includes(s));
  if (stillRead.length) {
    throw attestInvalid(`This credential still reads ${stillRead.join(', ')}, so it cannot leave --attest-sources; nothing changed.`,
      'Remove it from the read grant first (gbrain auth rescope ... --federated-read <list without it>), then from --attest-sources.');
  }
  if (added.length && mine?.privatePages) {
    throw attestInvalid('This credential holds the private-pages grant, so it cannot list scope sources; nothing changed.', 'Clear it first (gbrain auth rescope ... --private-pages none): a scope credential reads only shared memory.');
  }
  if (added.length && mine?.privateFacts) {
    throw attestInvalid('This credential holds the private-facts grant, so it cannot list scope sources; nothing changed.', 'Clear it first (gbrain auth rescope ... --private-facts none): a scope credential reads only shared memory.');
  }
  for (const s of added) {
    const [row] = await sql`SELECT archived, config FROM sources WHERE id = ${s}`;
    if (!row || row.archived === true) throw attestInvalid(`--attest-sources names ${s}, which is not an active source.`, 'Add a dedicated source for the scope first (gbrain sources add <id>: with a path on a repo brain, without one on a repo-less brain), then list it.');
    if (s === 'default' || parseSourceConfig(row.config).federated === true) throw attestInvalid(`--attest-sources names ${s}, which every connection without a source grant reads (${s === 'default' ? 'the default source' : 'a federated source'}).`, 'Use a dedicated, unfederated source per scope.');
    if (mine?.write === s) throw attestInvalid(`--attest-sources names ${s}, this credential's own write source (where member pages live).`, 'Keep member pages and each scope in separate sources: list only scope sources.');
    const readers = all.filter(c => !same(c.ref, self) && c.reads.includes(s) && !c.attest.includes(s));
    if (readers.length) {
      throw attestInvalid(`--attest-sources names ${s}, which ${readers.slice(0, 3).map(c => c.label).join(', ')}${readers.length > 3 ? ` and ${readers.length - 3} more` : ''} can already read.`,
        `Remove ${s} from those credentials' read grants first, or use a new source for the scope.`);
    }
  }
  if (opts.dryRun) return true;
  for (const s of added) {
    const [row] = await sql`SELECT config FROM sources WHERE id = ${s}`;
    await sql`UPDATE sources SET config = ${JSON.stringify({ ...normalizeSourceConfig(row!.config), qm_scope: true, federated: false })}::text::jsonb WHERE id = ${s}`;
  }
  return true;
}

/** A remote memory_recall that names no source reads no scope source: a scope is read only by naming it. */
export async function withoutScopeSources(ctx: Pick<OperationContext, 'remote' | 'engine'>, sources: string[]): Promise<string[]> {
  if (ctx.remote === false) return sources;
  const marked = await markedScopeSources(ctx.engine, sources);
  return marked.size ? sources.filter(s => !marked.has(s)) : sources;
}

/** Refuses `gbrain sources federate` on a scope source: federation would let every connection without a source grant read it. */
export async function assertNotScopeSource(db: Db, sourceId: string): Promise<void> {
  if ((await markedScopeSources(db, [sourceId])).size) {
    throw attestInvalid(`Source ${sourceId} is a QM scope source, so it cannot be federated.`, 'Leave it unfederated; the scope credential reads it by grant.');
  }
}