Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.1 KB
Raw Blame
/**
 * Every gbrain function that pins a search_path ends it with pg_temp (#7632).
 *
 * A pinned `pg_catalog, public` (or `pg_catalog`) does not name pg_temp, and PostgreSQL then searches the calling
 * session's temporary schema first for tables and views. Any role that may create temporary tables (PUBLIC may, by
 * default) could shadow a ledger a guard reads, such as fact_purges, page_purges, take_purges or fact_withdrawals, with an
 * empty temp table or view of the same name, and the guard let a purged claim, page or take, or a withdrawn fact,
 * through: for the owner as much as for any other writer. Named last, pg_temp comes after every other schema for
 * relations, and PostgreSQL never searches it for functions or operators.
 *
 * Every definition gbrain owns now pins `pg_catalog, public, pg_temp` itself (#7785; scripts/check-search-path.sh keeps
 * it so), so a schema replay keeps pg_temp. Historical migration bodies still pin the legacy settings, and so does a
 * brain created before the change, which is what the hardening below completes: ALTER FUNCTION only, no body rewritten,
 * so every guard keeps master's body, SECURITY INVOKER and BEFORE ROW timing.
 * A write role that RLS keeps from a ledger is refused by the guard itself since v318 (#7659, requireLedgerPoliciesSql).
 */

import type { BrainEngine } from './engine.ts';
import { failClosedLedgerGuards } from './guard-ledger-checks.ts';
import { migrationStatementTimeoutMs } from './migration-timeout.ts';
import { isLockTimeoutError } from './retry-matcher.ts';
import { resolveSchemaLockTimeoutMs, schemaLockBlockedError } from './postgres-engine/schema-lock-timeout.ts';

/** The search_path settings gbrain functions pinned before #7632, which the hardening completes with pg_temp. */
export const LEGACY_SEARCH_PATH_SETTINGS = ['search_path=pg_catalog, public', 'search_path=pg_catalog'] as const;

/** The pinned path in a pg_proc.proconfig entry `c.setting` (`search_path=<path>`). */
export const PINNED_PATH_SQL = `substr(c.setting, ${'search_path='.length + 1})`;

/**
 * Every function gbrain installs in public with a pinned search_path, on either engine. The hardening and the doctor
 * check touch only these, so another application's function in a shared database keeps its own search_path. A new
 * pinned function joins this list; scripts/check-search-path.sh (bun run check:search-path) names one that does not,
 * and the fresh-install tests (test/function-search-path-pglite.test.ts, and case 3 of
 * test/e2e/function-search-path-postgres.test.ts) fail until it does.
 */
export const PINNED_FUNCTION_NAMES = [
  'auto_enable_rls', 'bump_page_generation_clock_fn', 'bump_page_generation_fn', 'enforce_minion_queue_protocol',
  'gbrain_access_derive_page_readers', 'gbrain_access_folder_rules', 'gbrain_access_lineage_rules', 'gbrain_access_mark_restricted', 'gbrain_access_norm_readers',
  'gbrain_access_origin_closed_for', 'gbrain_access_origin_hidden_for', 'gbrain_access_origin_labelled_for', 'gbrain_access_origin_restricted', 'gbrain_access_pending_covers', 'gbrain_access_readers', 'gbrain_access_refresh_serves', 'gbrain_access_refresh_serves_trigger', 'gbrain_access_stamp_folder_rules',
  'gbrain_access_state_unreadable',
  'gbrain_advance_page_revision', 'gbrain_advance_tag_revision', 'gbrain_bump_trust_generation',
  'gbrain_clear_atom_page_state', 'gbrain_concept_inputs_private', 'gbrain_count_git_canonical_sources', 'gbrain_count_modifications', 'gbrain_forget_page_retrievals',
  'gbrain_fts_input', 'gbrain_graduation_fence', 'gbrain_guard_deferred_request', 'gbrain_guard_effect_protocol', 'gbrain_guard_guest_records', 'gbrain_guard_inserted_facts',
  'gbrain_guard_protocol_activation', 'gbrain_guard_request_protocol', 'gbrain_guard_skill_publication',
  'gbrain_lease_shared_skill_delivery', 'gbrain_mark_derivation_scope_entry', 'gbrain_owner_only_lineage', 'gbrain_preserve_fact_withdrawal',
  'gbrain_queue_page_projection', 'gbrain_refuse_purged_fact', 'gbrain_refuse_purged_page',
  'gbrain_refuse_purged_take', 'gbrain_refuse_purging_derivation', 'gbrain_release_refresh_barrier', 'gbrain_require_managed_writer',
  'gbrain_require_persistence_protocol', 'gbrain_snapshot_version_trust', 'gbrain_stamp_revision_attribution',
  'gbrain_stamp_trust_tier', 'gbrain_stamp_version_attribution', 'gbrain_stamp_write_attribution', 'gbrain_try_jsonb',
  'notify_minion_job_change', 'update_chunk_search_vector', 'update_page_search_vector',
] as const;

/**
 * Appends pg_temp to the pinned search_path of every gbrain function (PINNED_FUNCTION_NAMES) in public the current
 * role may alter that still pins `pg_catalog, public` or `pg_catalog`. A function the role does not own is
 * left as it was, and so is a procedure (ALTER FUNCTION refuses one, and gbrain installs none). Shared by the schema blob (its last
 * statement, so a replay's CREATE OR REPLACE never leaves a function without it), hardenFunctionSearchPaths below
 * (migration v277 and the end of every migration run) and `gbrain reindex-search-vector`, which rewrites the
 * search_vector trigger functions.
 */
export const FUNCTION_SEARCH_PATH_HARDENING_SQL = `DO $harden$
DECLARE f RECORD;
BEGIN
  FOR f IN SELECT p.oid::regprocedure AS sig, ${PINNED_PATH_SQL} AS path
    FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace CROSS JOIN LATERAL unnest(p.proconfig) AS c(setting)
    WHERE n.nspname = 'public' AND p.prokind = 'f' AND c.setting IN (${LEGACY_SEARCH_PATH_SETTINGS.map(v => `'${v}'`).join(', ')})
      AND p.proname IN (${PINNED_FUNCTION_NAMES.map(name => `'${name}'`).join(', ')})
      AND pg_has_role(current_user, p.proowner, 'USAGE')
    ORDER BY 1
  LOOP
    EXECUTE format('ALTER FUNCTION %s SET search_path = %s, pg_temp', f.sig, f.path);
  END LOOP;
END $harden$;`;

/** The gbrain functions (regprocedure text) whose pinned search_path is still a legacy setting. */
export async function legacySearchPathFunctions(engine: BrainEngine): Promise<string[]> {
  return (await engine.executeRaw<{ sig: string }>(
    `SELECT p.oid::regprocedure::text AS sig FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
      WHERE n.nspname = 'public' AND p.prokind = 'f' AND p.proconfig && $1::text[] AND p.proname = ANY($2::text[]) ORDER BY 1`,
    [[...LEGACY_SEARCH_PATH_SETTINGS], [...PINNED_FUNCTION_NAMES]])).map(r => r.sig);
}

/** Attempts of the hardening when another session's ALTER or CREATE OR REPLACE updates the same pg_proc row. */
const CONCURRENT_UPDATE_ATTEMPTS = 3;

function isConcurrentCatalogUpdate(error: unknown): boolean {
  return /tuple concurrently updated/i.test(error instanceof Error ? error.message : String(error));
}

/**
 * A failure to re-create a purge or withdrawal guard other than another role owning it. It carries no `code` of its own,
 * so a lock timeout in the re-create never reads as the migration run's lock refusal; the database error is its cause.
 */
export class LedgerGuardRecreateError extends Error {
  constructor(cause: unknown) {
    super(`purge or withdrawal guards not re-created (${cause instanceof Error ? cause.message : String(cause)}); gbrain doctor (guard_ledger_checks) names the ones left without their ledger check`, { cause });
    this.name = 'LedgerGuardRecreateError';
  }
}

/**
 * Re-creates every purge or withdrawal guard left without its ledger check that the role owns (guard-ledger-checks.ts,
 * #7659) and returns the failure, or null. Only a guard another role owns stays silent (SQLSTATE 42501): v318 and doctor's
 * guard_ledger_checks name it, and every later migration run retries it. A concurrent update of the same pg_proc row is
 * retried like the hardening's.
 */
async function recreateLedgerGuards(engine: BrainEngine, attempt = 1): Promise<LedgerGuardRecreateError | null> {
  try {
    await failClosedLedgerGuards(engine);
    return null;
  } catch (error) {
    if ((error as { code?: string } | null)?.code === '42501') return null;
    if (isConcurrentCatalogUpdate(error) && attempt < CONCURRENT_UPDATE_ATTEMPTS) {
      await new Promise(resolve => setTimeout(resolve, 100 * attempt));
      return recreateLedgerGuards(engine, attempt + 1);
    }
    return new LedgerGuardRecreateError(error);
  }
}

/** The stderr line a migration run prints when hardenFunctionSearchPaths throws, naming the doctor check that lists what is left. */
export function hardenFailureLine(error: unknown): string {
  if (error instanceof LedgerGuardRecreateError) return `  guards: ${error.message}\n`;
  const guardFailure = (error as { guardFailure?: unknown } | null)?.guardFailure;
  return `  search_path: pg_temp not restored on gbrain functions (${error instanceof Error ? error.message : String(error)}); gbrain doctor (function_search_path) names them\n`
    + (guardFailure instanceof LedgerGuardRecreateError ? `  guards: ${guardFailure.message}\n` : '');
}

/**
 * Re-creates the guards (recreateLedgerGuards), then puts pg_temp back (pinTempLast) and returns what that left. A
 * failed re-create never skips the pg_temp hardening: it is thrown as a LedgerGuardRecreateError once the hardening has
 * run. When the hardening fails too, its own error is thrown (a lock refusal keeps its meaning for the migration run)
 * with the re-create failure attached as `guardFailure`, which hardenFailureLine prints as well.
 */
export async function hardenFunctionSearchPaths(engine: BrainEngine): Promise<string[] | null> {
  const guardFailure = await recreateLedgerGuards(engine);
  let left: string[] | null;
  try {
    left = await pinTempLast(engine);
  } catch (error) {
    if (guardFailure && error instanceof Error) Object.assign(error, { guardFailure });
    throw error;
  }
  if (guardFailure) throw guardFailure;
  return left;
}

/**
 * Runs the hardening in one short transaction with the migration statement and lock timeouts and returns the
 * functions it had to leave (owned by another role), [] when none needed it, or null when the hardening committed but
 * listing what it left failed. A pg_proc row lock it cannot take
 * becomes `schema_lock_blocked`; a concurrent update of the same pg_proc row (`apply-migrations --force-schema` beside
 * another process's boot) is retried, since the step is idempotent.
 */
async function pinTempLast(engine: BrainEngine, attempt = 1): Promise<string[] | null> {
  if ((await legacySearchPathFunctions(engine)).length === 0) return [];
  const lockTimeoutMs = resolveSchemaLockTimeoutMs();
  try {
    await engine.transaction(async tx => {
      if (engine.kind === 'postgres') {
        await tx.executeRaw(`SET LOCAL statement_timeout = '${migrationStatementTimeoutMs()}'`);
        await tx.executeRaw(`SET LOCAL lock_timeout = '${lockTimeoutMs}ms'`);
      }
      await tx.runMigration(277, FUNCTION_SEARCH_PATH_HARDENING_SQL);
    });
  } catch (error) {
    if (isLockTimeoutError(error)) {
      throw schemaLockBlockedError({ step: 'search_path hardening', timeoutMs: lockTimeoutMs, sessions: null, sampledDuringWait: false, lock: 'a gbrain function row lock (pg_proc)' });
    }
    if (isConcurrentCatalogUpdate(error) && attempt < CONCURRENT_UPDATE_ATTEMPTS) {
      await new Promise(resolve => setTimeout(resolve, 100 * attempt));
      return pinTempLast(engine, attempt + 1);
    }
    throw error;
  }
  return legacySearchPathFunctions(engine).catch(() => null);
}