Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.3 KB
Raw Blame
/**
 * GBRA-218 (A2) folder rules across export and import (plan §15 "Backups and
 * moves", §16 "Import barrier").
 *
 * Export writes each source's applied rulebook (never a held widening): a
 * one-source export as .gbrain/access.yml plus .gbrain/access.approved, the
 * files a git-backed source keeps; an export of several sources as
 * .gbrain/access/<source>.yml, including sources with no exported page. A
 * source whose committed policy file is invalid has prefixes reading as
 * nobody that no rulebook can express, so its export refuses instead of
 * carrying a wider rulebook.
 *
 * Import installs the chosen rulebook before it publishes any page, through
 * proposeRevision: narrowing applies at once (with durable pending coverage
 * until restamped), widening is held for gbrain access apply. Source-qualified
 * files are mapped explicitly with --access-policy <exported-source> (a lone
 * one is taken as is); with several and no choice, the import refuses before
 * writing anything.
 */
import { existsSync, readdirSync, readFileSync } from 'fs';
import { join } from 'path';
import type { BrainEngine } from '../engine.ts';
import { opError } from '../ops/contract.ts';
import { parsePolicyYaml, serializePolicyYaml, type FolderRule } from './folder-rules.ts';
import { appliedRules, coverageRows, proposeRevision, readAccessStore, type ProposalResult } from './policy.ts';
import { APPROVED_FILE, POLICY_FILE, isGitWorkTree, sourcePolicyRoot } from './policy-git.ts';

const EXPORT_HEADER = 'Folder rules exported by gbrain export (the applied rulebook).';
export const SOURCE_POLICY_DIR = '.gbrain/access';

/** The policy files an export carries for one source, or for every source with folder rules when sourceId is null. */
export async function exportPolicyFiles(engine: BrainEngine, sourceId: string | null): Promise<Array<{ path: string; content: string }>> {
  const sources = sourceId ? [sourceId]
    : (await engine.executeRaw<{ source_id: string }>('SELECT source_id FROM access_policy_state ORDER BY source_id')).map(r => r.source_id);
  const files: Array<{ path: string; content: string }> = [];
  for (const source of sources) {
    const invalid = (await coverageRows(engine, source)).filter(c => c.reason === 'invalid');
    if (invalid.length) {
      throw opError('access_policy_invalid', `Source ${source}'s committed folder-rule file does not validate, so ${invalid.map(c => c.prefix || 'the whole source').join(', ')} read as nobody and no exported rulebook can carry that; nothing was exported.`,
        `See the problems with gbrain access rule list --source ${source}, fix .gbrain/access.yml, commit it and sync, then export again; other sources export one at a time with gbrain export --source.`);
    }
    const rules = await appliedRules(engine, source);
    if (!rules.length) continue;
    const text = serializePolicyYaml(rules, EXPORT_HEADER);
    if (sourceId) files.push({ path: POLICY_FILE, content: text }, { path: APPROVED_FILE, content: text });
    else files.push({ path: `${SOURCE_POLICY_DIR}/${source}.yml`, content: text });
  }
  return files;
}

/** The rulebook an import tree carries for its destination, or null when it carries none (or the caller chose none). */
export function importPolicyChoice(dir: string, choice: string | undefined): { file: string; rules: FolderRule[] } | null {
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- dir is the import tree itself, which gbrain import already reads whole; POLICY_FILE is a constant
  const single = join(dir, POLICY_FILE);
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- same: constant suffix under the import tree
  const qualifiedDir = join(dir, SOURCE_POLICY_DIR);
  const qualified = existsSync(qualifiedDir) ? readdirSync(qualifiedDir).filter(f => f.endsWith('.yml')).map(f => f.slice(0, -4)).sort() : [];
  if (choice === 'none') return null;
  let file: string;
  if (choice !== undefined) {
    if (!qualified.includes(choice)) {
      throw opError('access_policy_invalid', `The import tree has no folder-rule file for source "${choice}" (${qualified.length ? `it has ${qualified.join(', ')}` : 'it has no source-qualified rule file'}); nothing was imported.`,
        `Pass --access-policy with one of the listed sources, or --access-policy none to import without folder rules.`);
    }
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- choice is in qualified, a readdirSync listing of qualifiedDir, so it names a file in that directory and carries no separator
    file = join(qualifiedDir, choice + '.yml');
  } else if (existsSync(single)) {
    file = single;
  } else if (qualified.length === 1) {
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- qualified[0] is a readdirSync entry of qualifiedDir
    file = join(qualifiedDir, qualified[0] + '.yml');
  } else if (qualified.length) {
    throw opError('access_policy_invalid', `The import tree carries folder rules for several sources (${qualified.join(', ')}) and none was chosen for the destination; nothing was imported.`,
      `Run the import again with --access-policy ${qualified[0]} (or another of ${qualified.join(', ')}) naming the exported source whose rules this destination takes, or --access-policy none to import without folder rules.`);
  } else return null;
  const parsed = parsePolicyYaml(readFileSync(file, 'utf8'));
  if (!parsed.ok) {
    throw opError('access_policy_invalid', `${file} does not validate: ${parsed.problems.map(p => `${p.line ? `line ${p.line}: ` : ''}${p.message}`).join('; ')}; nothing was imported.`,
      'Fix the file and run the import again.');
  }
  return { file, rules: parsed.rules };
}

/** gbrain import's barrier: reads --access-policy from the import argv, installs the rulebook and reports it; a refusal is printed before it is rethrown. */
export async function importPolicyBarrier(engine: BrainEngine, sourceId: string, dir: string, args: readonly string[], log: (line: string) => void): Promise<void> {
  const flag = args.indexOf('--access-policy');
  try {
    const policy = await installImportedPolicy(engine, sourceId, dir, flag === -1 ? undefined : args[flag + 1]);
    if (!policy) return;
    log(`Folder rules from ${policy.file}: revision ${policy.revision} ${policy.state}${policy.held.length ? ` (widening held: preview with gbrain access apply --source ${sourceId})` : ''}`);
  } catch (error) {
    const e = error as Error & { suggestion?: string };
    console.error(`${e.message}${e.suggestion ? ` ${e.suggestion}` : ''}`);
    throw error;
  }
}

/** The import barrier: installs the tree's rulebook for the destination before any page is published. */
export async function installImportedPolicy(engine: BrainEngine, sourceId: string, dir: string, choice: string | undefined): Promise<(ProposalResult & { file: string }) | null> {
  const picked = importPolicyChoice(dir, choice);
  if (!picked) return null;
  let store = await readAccessStore(engine, sourceId);
  if (!store) {
    const root = await sourcePolicyRoot(engine, sourceId);
    store = root && isGitWorkTree(root) ? 'git' : 'database';
  }
  const result = await proposeRevision(engine, sourceId, picked.rules, { origin: 'import', store });
  return { ...result, file: picked.file };
}