Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.9 KB
Raw Blame
import { createHash } from 'node:crypto';
import { readFileSync, readdirSync } from 'node:fs';
import { join } from 'node:path';

/**
 * Tamper-evidence manifest for the bundled `skills/` tree (#159).
 *
 * NOT a signature system: the manifest is a committed sha256 inventory that
 * makes silent edits to bundled skill files visible (doctor warns, CI diffs).
 * Anyone who can edit skills/ can also regenerate the manifest — the value is
 * that the edit becomes an explicit, reviewable diff instead of an invisible
 * behavior change in a fat-markdown skill an agent will later execute.
 *
 * Regenerate after any change under skills/:
 *   bun run scripts/generate-skills-manifest.ts
 * Freshness is CI-guarded by scripts/check-skills-manifest-fresh.sh.
 */

/** Committed manifest filename, lives inside the skills dir it describes. */
export const SKILLS_MANIFEST_FILENAME = 'skills.lock.json';

/** Relative posix path → sha256 hex digest. */
export type SkillsManifest = Record<string, string>;

export interface SkillsManifestDrift {
  /** Present in manifest and on disk, but content hash differs. */
  modified: string[];
  /** Present in manifest, absent on disk. */
  missing: string[];
  /** Present on disk, absent from manifest. */
  extra: string[];
}

/**
 * Hash every regular file under `dir` (recursive). Paths are '/'-separated
 * relative paths, sorted, so output is deterministic across platforms. The
 * manifest file itself is excluded from its own hash set. Symlinks and other
 * non-regular entries are skipped.
 */
export function computeSkillsManifest(dir: string): SkillsManifest {
  const files: string[] = [];
  const walk = (rel: string): void => {
    for (const entry of readdirSync(join(dir, rel), { withFileTypes: true })) {
      const relPath = rel ? `${rel}/${entry.name}` : entry.name;
      if (entry.isDirectory()) walk(relPath);
      else if (entry.isFile() && relPath !== SKILLS_MANIFEST_FILENAME) files.push(relPath);
    }
  };
  walk('');
  files.sort();
  const manifest: SkillsManifest = {};
  for (const f of files) {
    manifest[f] = createHash('sha256').update(readFileSync(join(dir, f))).digest('hex');
  }
  return manifest;
}

/** Canonical serialized form: 2-space JSON + trailing newline. */
export function renderSkillsManifest(dir: string): string {
  return JSON.stringify(computeSkillsManifest(dir), null, 2) + '\n';
}

/** Compare `dir`'s current contents against a previously computed manifest. */
export function verifySkillsManifest(dir: string, manifest: SkillsManifest): SkillsManifestDrift {
  const actual = computeSkillsManifest(dir);
  const modified: string[] = [];
  const missing: string[] = [];
  for (const [path, hash] of Object.entries(manifest)) {
    if (!(path in actual)) missing.push(path);
    else if (actual[path] !== hash) modified.push(path);
  }
  const extra = Object.keys(actual).filter((p) => !(p in manifest));
  return { modified, missing, extra };
}

/** Append-only record of every released hash of each bundled file; lives beside the lock, which records its hash. */
export const SKILLS_LOCK_HISTORY_FILENAME = 'skills.lock.history.json';
export const SKILLS_LOCK_HISTORY_SCHEMA = 'gbrain-skills-lock-history-v1';

export interface SkillsLockHistory {
  schema_version: typeof SKILLS_LOCK_HISTORY_SCHEMA;
  /** Skills-relative posix path → every released sha256 of that file, sorted. */
  files: Record<string, string[]>;
}

export function parseSkillsLockHistory(text: string): SkillsLockHistory {
  const raw = JSON.parse(text) as Partial<SkillsLockHistory>;
  if (raw?.schema_version !== SKILLS_LOCK_HISTORY_SCHEMA || typeof raw.files !== 'object' || raw.files === null || Array.isArray(raw.files)) {
    throw new Error(`${SKILLS_LOCK_HISTORY_FILENAME} is not a ${SKILLS_LOCK_HISTORY_SCHEMA} document`);
  }
  for (const [path, hashes] of Object.entries(raw.files)) {
    if (!Array.isArray(hashes) || !hashes.every(h => typeof h === 'string' && /^[0-9a-f]{64}$/.test(h))) {
      throw new Error(`${SKILLS_LOCK_HISTORY_FILENAME}: ${path} must list sha256 hex digests`);
    }
  }
  return { schema_version: SKILLS_LOCK_HISTORY_SCHEMA, files: raw.files as Record<string, string[]> };
}

/** Union of `history` and the lock's hashes (the lock's own entry for the history file is skipped). Sorted, deterministic. */
export function mergeSkillsLockHistory(history: SkillsLockHistory | null, lock: SkillsManifest): SkillsLockHistory {
  const merged = new Map<string, Set<string>>();
  for (const [path, hashes] of Object.entries(history?.files ?? {})) merged.set(path, new Set(hashes));
  for (const [path, hash] of Object.entries(lock)) {
    if (path === SKILLS_LOCK_HISTORY_FILENAME) continue;
    (merged.get(path) ?? merged.set(path, new Set()).get(path)!).add(hash);
  }
  const files: Record<string, string[]> = {};
  for (const path of [...merged.keys()].sort()) files[path] = [...merged.get(path)!].sort();
  return { schema_version: SKILLS_LOCK_HISTORY_SCHEMA, files };
}

export function renderSkillsLockHistory(history: SkillsLockHistory): string {
  return JSON.stringify(history, null, 2) + '\n';
}

/** Every (path, hash) in `previous` that `current` dropped: the append-only contract's violations. */
export function droppedHistoryEntries(previous: SkillsLockHistory, current: SkillsLockHistory): string[] {
  const dropped: string[] = [];
  for (const [path, hashes] of Object.entries(previous.files)) {
    const kept = new Set(current.files[path] ?? []);
    for (const hash of hashes) if (!kept.has(hash)) dropped.push(`${path} ${hash}`);
  }
  return dropped;
}

export type VerifiedSkillsLockHistory =
  | { ok: true; history: SkillsLockHistory }
  | { ok: false; reason: string };

/**
 * Read the history beside `skillsDir`'s lock and verify its sha256 against
 * the lock's entry for it. Corruption detection only: a missing lock, a
 * missing history, a hash mismatch or an unparseable file is `ok: false`.
 */
export function loadVerifiedSkillsLockHistory(skillsDir: string): VerifiedSkillsLockHistory {
  let lock: SkillsManifest;
  let bytes: Buffer;
  try {
    lock = JSON.parse(readFileSync(join(skillsDir, SKILLS_MANIFEST_FILENAME), 'utf-8')) as SkillsManifest;
    bytes = readFileSync(join(skillsDir, SKILLS_LOCK_HISTORY_FILENAME));
  } catch (err) {
    return { ok: false, reason: `cannot read ${SKILLS_MANIFEST_FILENAME} or ${SKILLS_LOCK_HISTORY_FILENAME}: ${(err as Error).message}` };
  }
  const expected = lock[SKILLS_LOCK_HISTORY_FILENAME];
  const actual = createHash('sha256').update(bytes).digest('hex');
  if (!expected) return { ok: false, reason: `${SKILLS_MANIFEST_FILENAME} records no hash for ${SKILLS_LOCK_HISTORY_FILENAME}` };
  if (expected !== actual) return { ok: false, reason: `${SKILLS_LOCK_HISTORY_FILENAME} sha256 ${actual.slice(0, 12)} does not match the lock's ${expected.slice(0, 12)}` };
  try {
    return { ok: true, history: parseSkillsLockHistory(bytes.toString('utf-8')) };
  } catch (err) {
    return { ok: false, reason: (err as Error).message };
  }
}