Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
23.7 KB
Raw Blame
import type { BrainEngine } from '../engine.ts';
import type { OperationContext } from '../ops/contract.ts';
import { opError, OperationError } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import { slugUnderBoundPrefixes, matchesSlugAllowList, noSourceGrantError } from '../ops/context.ts';
import { NO_SOURCES } from '../source-id.ts';
import { hasScope } from '../scope.ts';
import { normalizeTokenScopes } from '../legacy-token-scope.ts';
import { authSourcesFromGrant, grantFromTokenRow, tokenGrantRowSelect, type TokenGrantRow } from '../grants/model.ts';
import { readLocalWriter, currentVerifiedLocalWriter, takeRegisteredWriterRow, verifyLocalWriter, type LocalGrant } from './identity.ts';
import { authorizedSlug, type Principal, type SqlEngine, type WriteAuthority, type WriteRequest } from './model.ts';
import { authorizePageVisibility, excludesPrivateWritesAtAdmission } from './page-visibility.ts';
import { currentCallerAccess } from '../search/private-visibility.ts';
import { parseStoredActor, storedActorIdentity } from '../access/actor.ts';
import { ownerSpeaksForItself, sameAttestedActor } from '../access/member-facts.ts';
import { perCallWriteSource, storedPerCallWriteSource } from '../access/attest-sources.ts';
import { pipelined, transactionMemo } from '../page-state/transactions.ts';

function deny(message: string): never { throw new OperationError('permission_denied', message, 'Inspect the current writer registration and source/operation grants.'); }
function strings(value: unknown): value is string[] { return Array.isArray(value) && value.every(v => typeof v === 'string'); }
function operationAllowed(ops: unknown, operation: string): boolean { return ops == null || strings(ops) && ops.includes(operation); }
function prefixAllowed(prefixes: string[] | null | undefined, slug: string): boolean {
  return prefixes == null || slugUnderBoundPrefixes(prefixes, slug);
}
/** A minions job id usable as a namespace key: a positive safe integer (never a string, NaN, zero or fraction). */
function jobNamespaceKey(value: unknown): number | undefined {
  return Number.isSafeInteger(value) && (value as number) > 0 ? value as number : undefined;
}
/**
 * Slug patterns an OAuth client's live grant delegates. A `prefixes` grant lists
 * them; a `job` grant (prefixes stored NULL) delegates only the accepting job's
 * own wiki/agents/<id>/ tree. Every other shape delegates nothing.
 */
function liveDelegation(row: Record<string, unknown>, jobId: unknown): readonly string[] {
  const { delegated_namespace: mode, delegated_slug_prefixes: listed } = row;
  if (mode === 'prefixes') return strings(listed) ? listed : [];
  const key = jobNamespaceKey(jobId);
  return mode === 'job' && listed === null && key !== undefined ? [`wiki/agents/${key}/*`] : [];
}
/** GST-2091: the page writes the brain owner's own credential may make to a private page it reads. */
const OWNER_PRIVATE_WRITES = new Set(['put_page', 'edit_page', 'append_page']);
function skillWrite(operation: string): boolean {
  return ['put_skill', 'delete_skill', 'adopt_skillpack'].includes(operation);
}
function assertSkillWriteScopes(scopes: readonly string[], operation: string, remote: boolean): void {
  if (remote && skillWrite(operation) && (!hasScope(scopes, 'write') || !hasScope(scopes, 'skill_editor'))) {
    deny('Shared skill publication requires an explicit skill_editor grant and write scope.');
  }
}
export async function submissionAuthority(ctx: OperationContext, operation: string, sourceId: string, sourceIncarnation: string, slug: string): Promise<WriteAuthority> {
  if (ctx.replayAuthority) return replayedAuthority(ctx.engine, ctx.replayAuthority, operation, sourceId, sourceIncarnation, slug);
  if (ctx.auth?.sourceId === NO_SOURCES || sourceId === NO_SOURCES) throw noSourceGrantError(operation, ctx.auth);
  if (ctx.auth?.fenceProjectionDegraded || ctx.auth?.grantProjectionDegraded) deny('The grant projection is incomplete.');
  let principal: Principal;
  let localGrant: LocalGrant | undefined;
  if (ctx.auth?.principal) principal = { ...ctx.auth.principal };
  else {
    const verified = currentVerifiedLocalWriter() ?? await verifyLocalWriter(ctx.engine,
      await readLocalWriter(ctx.engine, ctx.remote === false ? 'cli' : 'stdio'));
    if (verified.remote !== (ctx.remote !== false)) deny('The local trust lane does not match this transport.');
    principal = verified.principal;
    localGrant = verified.grant;
    if (!localGrant.sourceIds.includes('*') && !localGrant.sourceIds.includes(sourceId)) deny('The local grant excludes this source.');
  }
  const delegatedJobId = ctx.auth && ctx.viaSubagent ? jobNamespaceKey(ctx.subagentId) : undefined;
  const access = ctx.remote !== false ? currentCallerAccess() : null;
  // GST-359 C1: an attested call stores its actor (never the bare one-member audience), so publication re-resolves the link.
  const actingFor: WriteAuthority['actingFor'] = access?.actor ? { ...access.actor } : access?.audience?.length ? [...access.audience] : undefined;
  const a: WriteAuthority = {
    ...(ctx.agentLabel ? { agentLabel: ctx.agentLabel } : {}),
    version: 1, principal, remote: ctx.remote !== false, sourceId, sourceIncarnation,
    // GBRA-231: a channel audience (anything but one member) never relaxes privacy, so its ceiling hides private pages.
    excludePrivate: (actingFor !== undefined && currentCallerAccess().hidePrivate) || await excludesPrivateWritesAtAdmission(ctx.engine, ctx.remote !== false),
    ...(actingFor ? { actingFor } : {}),
    // GST-363: a stdio server started with --stdio-member stamps that member, so preparation and publication re-resolve
    // the same member (live) instead of whatever config mcp.stdio_member names then.
    ...(principal.kind === 'local_stdio' && ctx.stdioMember !== undefined ? { stdioMember: ctx.stdioMember } : {}),
    ...(access?.actor && ctx.attestedOp ? { attestedOp: ctx.attestedOp } : {}),
    ...(perCallWriteSource(ctx, sourceId, slug) ? { attestedSource: sourceId } : {}),
    autoLinkTrusted: ctx.remote === false || ctx.viaSubagent === true && !ctx.auth && !!ctx.allowedSlugPrefixes?.length,
    takesHolders: ctx.remote === false ? null : [...(ctx.takesHoldersAllowList ?? ['world'])],
    scopes: [...(ctx.auth?.scopes ?? localGrant?.scopes ?? [])],
    operations: ctx.auth?.allowedOperations ? [...ctx.auth.allowedOperations] : localGrant?.operations ?? null,
    slugPrefixes: ctx.auth?.boundSlugPrefixes ? [...ctx.auth.boundSlugPrefixes] : localGrant?.slugPrefixes ?? null,
    ...(ctx.viaSubagent ? { restrictedNamespace: true, delegated: !!ctx.auth,
      ...(delegatedJobId === undefined ? {} : { delegatedJobId }),
      delegatedPrefixes: ctx.allowedSlugPrefixes?.length ? [...ctx.allowedSlugPrefixes]
        : typeof ctx.subagentId === 'number' ? [`wiki/agents/${ctx.subagentId}/*`] : [] } : {}),
  };
  const owner = access?.remotePolicy?.ownerMember;
  if (owner && OWNER_PRIVATE_WRITES.has(operation) && hasScope(a.scopes, 'write') && ownerSpeaksForItself(ctx)) a.ownerWrite = `member:${owner}`;
  if (ctx.auth?.sourceId != null && ctx.auth.sourceId !== sourceId && !a.attestedSource) deny('The source is outside this writer grant.');
  if (!prefixAllowed(a.slugPrefixes, slug)) deny('The target is outside this writer grant.');
  await authorizeWrite(ctx.engine, a, operation, slug);
  if (!skillWrite(operation)) await authorizePageVisibility(ctx.engine, a, slug);
  return a;
}

/**
 * #5984: one local-writer read per transaction; a FOR SHARE read also answers a plain one. #6712 PR 4b: the read the
 * registration check just made answers the authorization that follows it (`withRegisteredLocalWriter`, once).
 */
function localWriterRow(engine: SqlEngine, id: string, lock: boolean): Promise<Array<{ lane: string; revoked_at: unknown; grant_ceiling: LocalGrant }>> {
  const registered = lock ? undefined : takeRegisteredWriterRow(id);
  if (registered) return Promise.resolve([registered]);
  const key = `local-writer:${id}`;
  return transactionMemo(engine, lock ? [`${key}:share`] : [key, `${key}:share`],
    () => engine.executeRaw<{ lane: string; revoked_at: unknown; grant_ceiling: LocalGrant }>(
      `SELECT lane,revoked_at,grant_ceiling FROM persistence_local_writers WHERE id=$1::uuid${lock ? ' FOR SHARE' : ''}`, [id]));
}
/** #5984: one membership read per source per transaction; a FOR SHARE read also answers a plain one. */
function sourceMembership(engine: SqlEngine, sourceId: string, lock: boolean) {
  return transactionMemo(engine, lock ? [`source-membership:${sourceId}:share`] : [`source-membership:${sourceId}`, `source-membership:${sourceId}:share`],
    () => engine.executeRaw<{ incarnation: string; archived: boolean }>(`SELECT incarnation,archived FROM sources WHERE id=$1${lock ? ' FOR SHARE' : ''}`, [sourceId]));
}
/**
 * #5984: the reads `authorizeStoredRequest` shares across the rows of one
 * transaction (each source's membership, each local writer), as calls a
 * caller pipelines; the rows' own checks then answer them from the memo.
 */
export function storedAuthorizationReads(engine: SqlEngine, rows: readonly WriteRequest[], lock = false): Array<() => Promise<unknown>> {
  const sources = [...new Set(rows.map(row => row.source_id))];
  const writers = [...new Set(rows.flatMap(row => ['local_cli', 'local_stdio'].includes(row.authority?.principal?.kind) ? [row.authority.principal.id] : []))];
  return [...sources.map(id => () => sourceMembership(engine, id, lock)), ...writers.map(id => () => localWriterRow(engine, id, lock))];
}
/**
 * #5994: a failed write replayed by `gbrain repair failed-writes` keeps its
 * original authority ceiling instead of the replay context's: the same
 * principal, delegation, scopes, holders and autoLinkTrusted, for the same
 * source incarnation, re-authorized against the live grant (a revoked or
 * narrowed grant refuses here and again at publication). Admission recomputes
 * the database-only reason; published-take bookkeeping is not carried.
 */
async function replayedAuthority(engine: SqlEngine, stored: WriteAuthority, operation: string, sourceId: string, sourceIncarnation: string, slug: string): Promise<WriteAuthority> {
  if (stored.sourceId !== sourceId || stored.sourceIncarnation !== sourceIncarnation) deny('The source was removed and re-added since the original write.');
  const { databaseOnlyReason: _reason, takeHoldersUsed: _used, ...kept } = stored;
  const a: WriteAuthority = structuredClone(kept);
  if (!prefixAllowed(a.slugPrefixes, slug)) deny('The target is outside this writer grant.');
  await authorizeWrite(engine, a, operation, slug);
  if (!skillWrite(operation)) await authorizePageVisibility(engine, a, slug);
  return a;
}

/**
 * #6517: whether a receipt may name another page's slug to this writer: the trusted local owner always; a remote
 * writer only when the slug is inside its prefix grant (and delegated namespace) and visible to it.
 */
export async function slugDisclosable(engine: SqlEngine, a: WriteAuthority, slug: string): Promise<boolean> {
  if (!a.remote) return true;
  if (!prefixAllowed(a.slugPrefixes, slug)) return false;
  if ((a.delegated || a.restrictedNamespace) && !matchesSlugAllowList(slug, a.delegatedPrefixes ?? [])) return false;
  return authorizePageVisibility(engine, a, slug).then(() => true, () => false);
}
/** Caller holds source guards first. FOR SHARE serializes publication against revocation. */
export async function authorizeWrite(engine: SqlEngine, a: WriteAuthority, operation: string, page: string, lock = false): Promise<void> {
  const slug = authorizedSlug(a, page);
  if (a.version !== 1 || !a.principal || !a.sourceId || !a.sourceIncarnation) deny('Missing durable write authority.');
  assertSkillWriteScopes(a.scopes, operation, a.remote);
  // GST-359: an attested write is granted by the public operation the person's system called (memory_write runs remember).
  const granted = a.actingFor && !Array.isArray(a.actingFor) && a.attestedOp ? a.attestedOp : operation;
  if (!hasScope(a.scopes, a.delegated ? 'agent' : 'write') || !operationAllowed(a.operations, granted) || !prefixAllowed(a.slugPrefixes, slug)) deny('The operation exceeds its original accepted grant.');
  if ((a.delegated || a.restrictedNamespace) && (!a.delegatedPrefixes?.length || !matchesSlugAllowList(slug, a.delegatedPrefixes))) deny('The target exceeds the accepted delegated namespace.');
  if (a.actingFor && !Array.isArray(a.actingFor)) {
    const actor = parseStoredActor(a.actingFor);
    if (!actor) deny('The accepted attested actor is malformed.');
    // GST-1113: lock the credential row before reading its attest right, so a concurrent removal commits before or after this publication.
    if (lock && a.principal.kind === 'oauth_client') await engine.executeRaw('SELECT 1 FROM oauth_clients WHERE client_id=$1 FOR SHARE', [a.principal.id]);
    if (lock && a.principal.kind === 'legacy_token') await engine.executeRaw('SELECT 1 FROM access_tokens WHERE id=$1 FOR SHARE', [a.principal.id]);
    await storedActorIdentity(engine, a.principal, actor, a.attestedOp ?? operation, storedPerCallWriteSource(a, slug) ?? undefined);
  }
  // GST-1113: the one exception to the owner's single write source (the scope page), re-checked against the live attest_sources above.
  // A live grant of no sources writes nothing, so it refuses before that exception.
  const ownSource = (source: unknown, sourcesNone: boolean) => !sourcesNone && (source === a.sourceId || storedPerCallWriteSource(a, slug) !== null);
  const suffix = lock ? ' FOR SHARE' : '';
  if (a.principal.kind === 'oauth_client') {
    const [row] = await engine.executeRaw<Record<string, unknown>>(`SELECT deleted_at,scope,source_id,source_grant,allowed_operations,
      bound_slug_prefixes,bound_tools,delegated_namespace,delegated_slug_prefixes FROM oauth_clients WHERE client_id=$1${suffix}`, [a.principal.id]);
    if (!row || row.deleted_at != null || !ownSource(row.source_id, row.source_grant === 'none')) deny('The owning OAuth client is revoked or its source changed.');
    const scopes = typeof row.scope === 'string' ? row.scope.split(/\s+/) : [];
    assertSkillWriteScopes(scopes, operation, a.remote);
    if (skillWrite(operation) && (!strings(row.allowed_operations) || !row.allowed_operations.includes(operation))) deny('The current skill operation grant was removed.');
    if (!hasScope(scopes, a.delegated ? 'agent' : 'write')) deny('The current OAuth grant no longer permits this write.');
    if (a.delegated) {
      if (!strings(row.bound_tools) || !row.bound_tools.some(t => t.replace(/^(?:brain_|mcp__gbrain__)/, '') === operation)) deny('The delegated tool was removed from the current grant.');
      if (!matchesSlugAllowList(slug, liveDelegation(row, a.delegatedJobId))) deny('The delegated namespace was narrowed.');
    } else if (!operationAllowed(row.allowed_operations, granted) ||
      (row.bound_slug_prefixes != null && (!strings(row.bound_slug_prefixes) || !prefixAllowed(row.bound_slug_prefixes, slug)))) deny('The current operation or slug grant excludes this write.');
    return;
  }
  if (a.principal.kind === 'legacy_token') {
    // GST-2314: named columns, not SELECT *: inside this transaction a plan cached before a migration added a column fails 0A000.
    const [row] = await engine.executeRaw<TokenGrantRow & { revoked_at: unknown }>(`SELECT ${await tokenGrantRowSelect(engine)},revoked_at FROM access_tokens WHERE id=$1${suffix}`, [a.principal.id]);
    if (!row || row.revoked_at != null) deny('The owning token is revoked.');
    const grant = grantFromTokenRow(row);
    if (grant.permissionsMalformed) deny('The current legacy grant is malformed.');
    assertSkillWriteScopes(normalizeTokenScopes(row.scopes) ?? [], operation, a.remote);
    const liveOperations = grant.allowedOperations;
    if (!operationAllowed(liveOperations, granted) || skillWrite(operation) && !liveOperations?.includes(operation)) deny('The current legacy operation grant excludes this write.');
    if (!hasScope(grant.scopes, 'write') || !ownSource(authSourcesFromGrant(grant).sourceId, grant.sources.kind === 'none')) deny('The current token no longer permits this source write.');
    return;
  }
  if (a.principal.kind === 'local_cli' || a.principal.kind === 'local_stdio') {
    // #5984: one local-writer read per transaction; a FOR SHARE read also answers a plain one.
    const [row] = await localWriterRow(engine, a.principal.id, lock);
    const lane = a.principal.kind === 'local_cli' ? 'cli' : 'stdio';
    if (!row || row.revoked_at != null || row.lane !== lane || a.remote !== (lane === 'stdio')) deny('The local writer is revoked or its trust lane changed.');
    const g = row.grant_ceiling;
    assertSkillWriteScopes(g?.scopes ?? [], operation, a.remote);
    if (!g || !strings(g.sourceIds) || !(g.sourceIds.includes('*') || g.sourceIds.includes(a.sourceId)) ||
      !hasScope(g.scopes, 'write') || !operationAllowed(g.operations, operation) || !prefixAllowed(g.slugPrefixes, slug)) deny('The current local writer grant excludes this request.');
    return;
  }
  deny('Application authority is unavailable through submitted write requests.');
}
/** `pageVisibility: false` is for a caller that checks the target's visibility itself after locking the page. */
export async function authorizeStoredRequest(engine: SqlEngine, row: WriteRequest, lock = false, opts: { pageVisibility?: boolean } = {}): Promise<void> {
  // #5984: one membership read per source per transaction; a FOR SHARE read also answers a plain one.
  // The source lock and the writer check are sent together in lock order; a source refusal is reported first.
  await pipelined(engine, [
    async () => {
      const [source] = await sourceMembership(engine, row.source_id, lock);
      if (!source || source.archived || source.incarnation !== row.source_incarnation) {
        throw opError('source_changed', 'The accepted source is no longer active.',
          `Source ${row.source_id} was archived, removed, or recreated after request ${row.request_id} was accepted, so it will not be applied. Check the source's writer status; a new write must target the current source.`,
          { fix: readFix(`Shows source ${row.source_id}'s current registration and requests, read-only.`, { argv: ['gbrain', 'sources', 'writer', 'status', '--source', row.source_id, '--json'] }) });
      }
    },
    () => authorizeWrite(engine, row.authority, row.operation, row.slug, lock),
  ]);
  if (skillWrite(row.operation)) {
    const affected = (row.authority as WriteAuthority & { skillSlugsUsed?: unknown }).skillSlugsUsed;
    if (affected !== undefined) {
      if (!strings(affected) || affected.length === 0) deny('The skill receipt has invalid retained target authority.');
      for (const slug of affected) await authorizeWrite(engine, row.authority, row.operation, slug, lock);
    }
  }
  if (!skillWrite(row.operation) && opts.pageVisibility !== false) await authorizePageVisibility(engine, row.authority, row.slug);
  if (row.authority.remote && ['takes_add', 'takes_update', 'takes_resolve', 'takes_supersede'].includes(row.operation)) {
    await authorizeStoredTakeHolders(engine, row);
  }
  if (row.outcome?.status === 'duplicate' && typeof row.outcome.slug === 'string' && row.outcome.slug !== row.slug) {
    await authorizeWrite(engine, row.authority, row.operation, row.outcome.slug, lock);
    await authorizePageVisibility(engine, row.authority, row.outcome.slug);
  }
}

/** Receipt/replay access uses the same holder intersection as publication. */
async function authorizeStoredTakeHolders(engine: SqlEngine, row: WriteRequest): Promise<void> {
  const retained = row.authority.takeHoldersUsed;
  if (retained !== undefined) {
    if (!strings(retained) || retained.length === 0) deny('The take receipt has invalid retained holder authority.');
    for (const holder of retained) await authorizeTakeHolder(engine, row.authority, holder);
    return;
  }
  // Queued requests have no publication metadata yet. Legacy terminal rows may
  // also lack it; use retained outcome or current canonical target rows, and
  // refuse a committed receipt whose affected holder can no longer be proven.
  const holders = new Set<string>();
  for (const holder of [row.intent?.holder, row.outcome?.holder]) {
    if (typeof holder === 'string') holders.add(holder);
  }
  const numbers = [row.intent?.row_num, row.outcome?.row_num, row.outcome?.old_row, row.outcome?.new_row]
    .filter((value): value is number => Number.isSafeInteger(value) && Number(value) > 0);
  if (row.page_id !== null && numbers.length) {
    const targets = await engine.executeRaw<{ holder: string }>(
      'SELECT DISTINCT holder FROM takes WHERE page_id=$1 AND row_num=ANY($2::integer[])', [row.page_id, numbers]);
    for (const target of targets) holders.add(target.holder);
  }
  if (row.state === 'committed' && holders.size === 0) deny('The legacy take receipt has no verifiable holder authority.');
  for (const holder of holders) await authorizeTakeHolder(engine, row.authority, holder);
}
/**
 * #6007: one access check answers identical read-only statements once (the
 * current and the stored authority read the same writer row and visibility).
 * The memo lives for that single check and holds no locking reads.
 */
function onceReads(engine: BrainEngine): BrainEngine {
  const reads = new Map<string, Promise<unknown[]>>();
  return new Proxy(engine, { get(target, key) {
    if (key === 'executeRaw') return (sql: string, params?: unknown[], opts?: { signal?: AbortSignal }) => {
      if (/\bFOR (?:SHARE|UPDATE)\b/i.test(sql)) return target.executeRaw(sql, params, opts);
      const id = JSON.stringify([sql, params ?? null]);
      let read = reads.get(id);
      if (!read) { read = target.executeRaw(sql, params, opts); reads.set(id, read); read.catch(() => reads.delete(id)); }
      return read;
    };
    const value = Reflect.get(target, key, target);
    return typeof value === 'function' ? value.bind(target) : value;
  } });
}
export async function ownRequestAccessible(ctx: OperationContext, row: WriteRequest): Promise<boolean> {
  try {
    const engine = onceReads(ctx.engine);
    const auth = await submissionAuthority({ ...ctx, engine, attestedOp: row.authority?.attestedOp, attestedSource: row.authority?.attestedSource }, row.operation, row.source_id, row.source_incarnation, row.slug);
    if (auth.principal.kind !== row.principal_kind || auth.principal.id !== row.principal_id) return false;
    // GST-359 C2: under one credential, a receipt belongs to the person or audience it was written for.
    if (!sameAttestedActor(row.authority?.actingFor)) return false;
    await authorizeStoredRequest(engine, row);
    return true;
  } catch (error) {
    if (error instanceof OperationError && ['permission_denied','source_changed','writer_registration_required','page_not_found'].includes(error.code)) return false;
    throw error;
  }
}


/** Caller holds the same principal guard as revocation/rescoping. */
export async function authorizeTakeHolder(engine: SqlEngine, authority: WriteAuthority, holder: string): Promise<void> {
  if (!authority.remote) return;
  if (!(authority.takesHolders ?? ['world']).includes(holder)) deny('The take holder exceeds the original grant.');
  let current = ['world'];
  if (authority.principal.kind === 'legacy_token') {
    const [row] = await engine.executeRaw<Record<string, unknown>>('SELECT * FROM access_tokens WHERE id=$1 AND revoked_at IS NULL', [authority.principal.id]);
    if (!row) deny('The owning token is revoked.');
    current = grantFromTokenRow(row).takesHolders ?? ['world'];
  } else if (authority.principal.kind === 'oauth_client') {
    const [row] = await engine.executeRaw<{ takes_holders: unknown }>('SELECT takes_holders FROM oauth_clients WHERE client_id=$1 AND deleted_at IS NULL', [authority.principal.id]);
    if (!row) deny('The owning OAuth client is revoked.');
    current = row.takes_holders == null ? ['world'] : strings(row.takes_holders) ? row.takes_holders : [];
  }
  if (!current.includes(holder)) deny('The current holder grant excludes this write.');
}