@smartmemory/compose 0.3.6-beta → 0.3.8

package/lib/canon-guard.js

@@ -0,0 +1,245 @@
+/**
+ * canon-guard.js — COMP-CANON-GUARD S4 (pure logic for the write-time hook).
+ *
+ * Two responsibilities, both pure (no I/O — the runtime wrapper
+ * .claude/hooks/canon-guard.mjs and bin/compose.js do the I/O):
+ *
+ *   1. decideCanonGuard — the PreToolUse decision. Deny a raw Write/Edit to a
+ *      path the registry marks hook-enforced (docs/judgment/**), naming the
+ *      tool that owns it. Allow everything else. FAIL OPEN on any malformed
+ *      input — a guard that wedges the session is worse than one that misses.
+ *
+ *   2. installGuardHook / uninstallGuardHook / guardHookStatus — idempotent
+ *      transforms over a parsed .claude/settings.json object that register the
+ *      hook under hooks.PreToolUse without disturbing existing hooks.
+ *
+ * The hook is the 'hook' enforcement point of the shared canon-registry. It is
+ * Claude-runtime-scoped: Codex-dispatched edits and Bash (sed/heredoc) bypass
+ * it — the runtime-neutral backstop is S5/S6 (see design.md honest limits).
+ */
+import { relative, resolve, isAbsolute, dirname, basename, join } from 'node:path';
+import { existsSync, realpathSync } from 'node:fs';
+import { matchEntry } from './canon-registry.js';
+
+/** Tools whose file writes the hook intercepts. */
+export const GUARDED_TOOLS = new Set(['Write', 'Edit', 'NotebookEdit']);
+
+/** How the hook registers in .claude/settings.json. */
+export const HOOK_MATCHER = 'Write|Edit|NotebookEdit';
+export const HOOK_COMMAND = 'node "${CLAUDE_PROJECT_DIR}/.claude/hooks/canon-guard.mjs"';
+
+/**
+ * A command is ours iff it executes a file whose leaf name is exactly
+ * canon-guard.mjs. This is stricter than a loose substring: it matches our
+ * command and a drifted path (node old/canon-guard.mjs → still ours, so status
+ * reports 'stale'), but NOT a different script (canon-guard-v2.mjs) and not an
+ * unrelated command that merely names the file inside a larger word.
+ */
+const OUR_SCRIPT_RE = /(?:^|[\s"'/\\=])canon-guard\.mjs(?:$|[\s"';:&|)(<>])/;
+
+/** True if a hook entry is our canon-guard hook (by executed-script leaf name). */
+function isOurHookEntry(h) {
+  return !!h && h.type === 'command' && typeof h.command === 'string' && OUR_SCRIPT_RE.test(h.command);
+}
+
+/**
+ * Strip the macOS data-volume firmlink prefix. /System/Volumes/Data mirrors /,
+ * so /System/Volumes/Data/Users/x IS /Users/x — but realpath does NOT collapse
+ * firmlinks (unlike symlinks), so this must be done by hand.
+ */
+function stripFirmlink(x) {
+  return x.replace(/^\/System\/Volumes\/Data(?=\/)/, '') || x;
+}
+
+/**
+ * Canonicalize a path to defeat filesystem aliasing before lexical matching:
+ * realpath collapses symlinks and case folding; stripFirmlink handles the macOS
+ * /System/Volumes/Data firmlink realpath leaves alone. The target of a Write may
+ * not exist yet, so realpath the longest existing ancestor and re-append the
+ * not-yet-created tail. Best-effort — falls back to a lexical resolve on any
+ * error (the caller fails open regardless).
+ *
+ * NOT alias-proof against every vector (bind mounts, hardlinks) — those are the
+ * same runtime-scoped bucket as the Bash bypass, closed by S5/S6 on the tree.
+ */
+export function realpathCanonicalize(p) {
+  try {
+    // Do NOT resolve(p) up front: resolve() collapses `..` LEXICALLY before any
+    // symlink resolves, so `symlink/../real` mis-normalizes (Codex S4 r2 finding
+    // 1). realpath resolves `..` and symlinks together but needs an existing
+    // path — so walk up the RAW path to the longest existing prefix, realpath
+    // THAT, and re-append the not-yet-created tail.
+    let cur = p;
+    const tail = [];
+    while (cur && !existsSync(cur)) {
+      const parent = dirname(cur);
+      if (parent === cur) { cur = ''; break; } // reached root, nothing existed
+      tail.unshift(basename(cur));
+      cur = parent;
+    }
+    if (!cur) return stripFirmlink(resolve(p)); // nothing existed → lexical fallback
+    let base;
+    try { base = realpathSync.native(cur); } catch { base = resolve(cur); }
+    const full = tail.length ? join(base, ...tail) : base;
+    return stripFirmlink(full);
+  } catch {
+    return resolve(p);
+  }
+}
+
+/**
+ * Decide whether to deny a PreToolUse tool call.
+ *
+ * @param {object} args
+ * @param {string} [args.toolName]
+ * @param {object} [args.toolInput]     - the tool's arguments (file_path / notebook_path)
+ * @param {string} [args.cwd]           - session cwd (for resolving a relative file_path)
+ * @param {string} [args.projectRoot]   - repo root the registry patterns are relative to
+ * @param {string} [args.featuresDir='docs/features']
+ * @param {(p:string)=>string} [args.canonicalize] - map a path to its real, alias-free form.
+ *   The runtime wrapper passes realpathCanonicalize; pure tests inject a stub or omit it.
+ * @param {string} [args.profile] - the caller's MCP profile (COMPOSE_SESSION_PROFILE).
+ *   Only changes the ESCAPE SENTENCE of the deny message, never the verdict:
+ *   `canon_override_grant` is denied to restricted profiles by IMPLEMENTER_DENY /
+ *   REVIEWER_ALLOW, so telling a restricted caller to mint a grant sends it to a
+ *   tool it cannot call. Absent/unknown → the unrestricted wording (fail-open).
+ * @returns {{deny: boolean, reason?: string, path?: string}}
+ */
+export function decideCanonGuard({ toolName, toolInput, cwd, projectRoot, featuresDir = 'docs/features', canonicalize, profile } = {}) {
+  try {
+    if (!GUARDED_TOOLS.has(toolName)) return { deny: false };
+    const raw = toolInput && (toolInput.file_path ?? toolInput.notebook_path);
+    if (typeof raw !== 'string' || !raw) return { deny: false };
+    if (typeof projectRoot !== 'string' || !projectRoot) return { deny: false };
+
+    // Canonicalize BOTH root and target with the same function so an aliased
+    // target (firmlink/symlink/case) can't slip a real canonical write past a
+    // lexical relative() (Codex S4 finding 1). Default = identity (lexical).
+    const canon = typeof canonicalize === 'function' ? canonicalize : (x) => x;
+    const abs = isAbsolute(raw) ? raw : resolve(cwd || projectRoot, raw);
+    const rel = relative(canon(projectRoot), canon(abs));
+    // Outside the repo (empty, parent-relative, or still absolute) → not our canon.
+    if (!rel || rel.startsWith('..') || isAbsolute(rel)) return { deny: false };
+    // Normalize Windows separators defensively so registry patterns (forward-slash) match.
+    const relPosix = rel.split(/[\\/]/).join('/');
+
+    const entry = matchEntry(relPosix, { featuresDir, point: 'hook' });
+    if (!entry) return { deny: false };
+
+    // Classification only — this function stays pure. The atomic claim happens
+    // in the hook wrapper, because a destructive callback here would make the
+    // verdict depend on how many times it was evaluated.
+    const overrideEligible = entry.overrideEligible !== false;
+    const tools = entry.tools.join(', ');
+    // COMP-COVERAGE-GATE C4: canon_override_grant is now denied to restricted
+    // profiles, so pointing one at it would loop it against its own tool gate.
+    const restricted = profile === 'implementer' || profile === 'reviewer';
+    const escape = !overrideEligible
+      ? `This path is the override's own governance state, so it cannot be overridden: a bypass `
+        + `must not be able to authorise rewriting its own record.`
+      : restricted
+        ? `A canon override exists, but canon_override_grant is not available to the '${profile}' `
+          + `profile — the session subject to canon enforcement cannot exempt itself from it. `
+          + `Escalate: report what you need to write and why, and let the orchestrator decide.`
+        : `To do it deliberately anyway, mint a single-use grant with canon_override_grant `
+          + `({ path, reason, operation }) — the bypass is recorded before the grant exists.`;
+
+    return {
+      deny: true,
+      path: relPosix,
+      overrideEligible,
+      reason:
+        `${relPosix} is tool-owned canon (COMP-CANON-GUARD). A direct ${toolName} is blocked — `
+        + `write it through one of: ${tools}. These tools stamp provenance and regenerate the `
+        + `projections from records; a hand-edit is unattributed and overwritten on the next regen. `
+        + `${escape}`,
+    };
+  } catch {
+    return { deny: false }; // fail open — never wedge the session
+  }
+}
+
+// ── settings.json registration ───────────────────────────────────────────────
+
+function clone(obj) {
+  return obj == null ? {} : structuredClone(obj);
+}
+
+/** Our canonical PreToolUse group. */
+function ourGroup() {
+  return { matcher: HOOK_MATCHER, hooks: [{ type: 'command', command: HOOK_COMMAND }] };
+}
+
+/**
+ * Remove OUR hook ENTRIES from each group, preserving sibling hooks that happen
+ * to share the group, and dropping only groups left empty. Operates at the hook
+ * level, not the group level (Codex S4 finding 2 — a group-level "any child is
+ * ours → delete the group" wiped unrelated sibling hooks).
+ *
+ * @returns {Array<object>} the pruned groups
+ */
+function pruneOurHooks(groups) {
+  const out = [];
+  for (const g of groups) {
+    if (!Array.isArray(g.hooks)) { out.push(g); continue; }
+    const kept = g.hooks.filter((h) => !isOurHookEntry(h));
+    if (kept.length === 0) continue;              // group had only our hook → drop it
+    if (kept.length === g.hooks.length) { out.push(g); continue; } // nothing of ours here
+    out.push({ ...g, hooks: kept });              // keep siblings, our entry removed
+  }
+  return out;
+}
+
+/**
+ * Ensure our hook is registered with the current matcher + command in its own
+ * dedicated group, preserving every other hook. Idempotent.
+ *
+ * @returns {{settings: object, changed: boolean}}
+ */
+export function installGuardHook(settings) {
+  const s = clone(settings);
+  s.hooks = s.hooks ?? {};
+  const before = Array.isArray(s.hooks.PreToolUse) ? JSON.stringify(s.hooks.PreToolUse) : null;
+  const existing = Array.isArray(s.hooks.PreToolUse) ? s.hooks.PreToolUse.map((g) => structuredClone(g)) : [];
+
+  // Strip any prior copy of our hook (from anywhere, incl. mixed groups), then
+  // append one clean dedicated group. Siblings in mixed groups are preserved.
+  const next = pruneOurHooks(existing);
+  next.push(ourGroup());
+  s.hooks.PreToolUse = next;
+
+  const changed = before !== JSON.stringify(next);
+  return { settings: s, changed };
+}
+
+/**
+ * Remove our hook registration, preserving sibling hooks, pruning emptied
+ * groups and an emptied PreToolUse array. Idempotent.
+ *
+ * @returns {{settings: object, changed: boolean}}
+ */
+export function uninstallGuardHook(settings) {
+  const s = clone(settings);
+  if (!s.hooks || !Array.isArray(s.hooks.PreToolUse)) return { settings: s, changed: false };
+  const before = JSON.stringify(s.hooks.PreToolUse);
+  const next = pruneOurHooks(s.hooks.PreToolUse.map((g) => structuredClone(g)));
+  if (next.length === 0) delete s.hooks.PreToolUse;
+  else s.hooks.PreToolUse = next;
+  const after = s.hooks.PreToolUse ? JSON.stringify(s.hooks.PreToolUse) : null;
+  return { settings: s, changed: before !== after };
+}
+
+/**
+ * Report the guard hook's registration state.
+ * @returns {{state: 'installed'|'stale'|'absent'}}
+ */
+export function guardHookStatus(settings) {
+  const groups = settings?.hooks?.PreToolUse;
+  if (!Array.isArray(groups)) return { state: 'absent' };
+  const ours = groups.filter((g) => Array.isArray(g.hooks) && g.hooks.some(isOurHookEntry));
+  if (ours.length === 0) return { state: 'absent' };
+  const current = ours.some(
+    (g) => g.matcher === HOOK_MATCHER && g.hooks.length === 1 && g.hooks[0].command === HOOK_COMMAND,
+  );
+  return { state: current && ours.length === 1 ? 'installed' : 'stale' };
+}

package/lib/canon-override.js

@@ -0,0 +1,196 @@
+/**
+ * canon-override.js — the canon override: grant-then-write, ledger-first.
+ *
+ * COMP-CANON-OVERRIDE S2, implementing COMP-CANON-GUARD Decision 4.
+ *
+ * WHAT THIS IS: audit and careless-drift tooling. It makes the cooperative
+ * path logged and the accidental path hard. It is NOT enforcement and must
+ * never be described as such — `Bash` and Codex writes never reach the hook,
+ * and every piece of state here lives in the workspace the agent can write.
+ * A determined actor who forges a token AND its ledger row AND the baseline
+ * passes. See design.md, "The in-workspace ceiling".
+ *
+ * ORDERING IS THE ATOMICITY ANSWER. The bypass row and the attest baseline are
+ * written BEFORE the token is minted, so the failure mode is over-recording,
+ * never under-recording: a token cannot exist without its row. If the write
+ * that follows never happens, a bypass entry exists for a write that did not
+ * occur — deliberately the safe direction.
+ *
+ * SINGLE-USE IS A RENAME, NOT A LOCK. Each grant is its own file, claimed by
+ * renaming it into `consumed/`. Exactly one caller can rename a given path;
+ * every loser gets ENOENT. An earlier draft used one shared JSON file with
+ * temp-write-plus-rename, which gives atomic *publication* but not mutual
+ * exclusion — two readers could each drop the token from their own snapshot
+ * and both succeed.
+ */
+import {
+  mkdirSync, writeFileSync, readFileSync, renameSync, readdirSync, existsSync, appendFileSync,
+} from 'node:fs';
+import { join, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { isOverrideEligible } from './canon-registry.js';
+import { baselineFor } from './append-integrity.js';
+
+export const LEDGER_REL = '.compose/canon-overrides.jsonl';
+export const ATTEST_REL = '.compose/canon-overrides-attest.json';
+export const GRANTS_REL = '.compose/data/canon-grants';
+const CONSUMED_SUBDIR = 'consumed';
+
+/** 5 minutes: long enough for a grant-then-write round trip through an agent
+ *  turn, short enough that a forgotten grant is not a standing hole. */
+export const GRANT_TTL_MS = 5 * 60 * 1000;
+
+function typedError(code, message) {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+}
+
+function ensureDir(path) {
+  mkdirSync(path, { recursive: true });
+}
+
+/** Read the bypass ledger as parsed rows. Malformed lines are skipped rather
+ *  than thrown on — a corrupt row must not make every claim fail open. */
+export function readOverrideLedger(cwd) {
+  const path = join(cwd, LEDGER_REL);
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch (err) {
+    if (err?.code === 'ENOENT') return [];
+    throw err;
+  }
+  const rows = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    try { rows.push(JSON.parse(line)); } catch { /* skip a corrupt row */ }
+  }
+  return rows;
+}
+
+/**
+ * Mint a single-use, path-scoped grant.
+ *
+ * @param {string} cwd workspace root
+ * @param {{path:string, reason:string, operation?:string, featuresDir?:string}} args
+ *   `actor` is deliberately NOT accepted — it is stamped here per Decision 3.
+ * @returns {{token_id:string, path:string, expires_at:string}}
+ */
+export function mintGrant(cwd, { path, reason, operation, featuresDir = 'docs/features' } = {}) {
+  if (typeof reason !== 'string' || reason.trim() === '') {
+    throw typedError(
+      'CANON_OVERRIDE_REASON',
+      'canon_override_grant: a non-empty reason is required — the bypass row is the whole point',
+    );
+  }
+  if (typeof path !== 'string' || path.trim() === '') {
+    throw typedError('CANON_OVERRIDE_PATH', 'canon_override_grant: path is required');
+  }
+  if (!isOverrideEligible(path, { featuresDir, point: 'hook' })) {
+    throw typedError(
+      'CANON_OVERRIDE_INELIGIBLE',
+      `canon_override_grant: ${path} is not override-eligible. Either it is not guarded at the `
+      + 'write-time hook (nothing is blocking it), or it is the override\'s own governance state, '
+      + 'which is deliberately ungrantable so a bypass cannot authorise rewriting its own record.',
+    );
+  }
+
+  const now = new Date();
+  const tokenId = randomUUID();
+  const row = {
+    ts: now.toISOString(),
+    actor: 'agent',                       // stamped here; never caller-supplied
+    path,
+    reason: reason.trim(),
+    operation: typeof operation === 'string' ? operation : null,
+    token_id: tokenId,
+  };
+
+  // ── Ledger and baseline FIRST ──────────────────────────────────────────────
+  const ledgerPath = join(cwd, LEDGER_REL);
+  ensureDir(dirname(ledgerPath));
+  appendFileSync(ledgerPath, `${JSON.stringify(row)}\n`);
+  writeAttestBaseline(cwd);
+
+  // ── Then the token ─────────────────────────────────────────────────────────
+  const grantsDir = join(cwd, GRANTS_REL);
+  ensureDir(grantsDir);
+  const expiresAt = new Date(now.getTime() + GRANT_TTL_MS).toISOString();
+  writeFileSync(
+    join(grantsDir, `${tokenId}.json`),
+    `${JSON.stringify({
+      token_id: tokenId,
+      path,
+      actor: 'agent',
+      operation: row.operation,
+      issued_at: now.toISOString(),
+      expires_at: expiresAt,
+    }, null, 2)}\n`,
+    { flag: 'wx' },                       // exclusive create: mint is serialized too
+  );
+
+  return { token_id: tokenId, path, expires_at: expiresAt };
+}
+
+/** Re-attest the bypass ledger. Called only from the append path — never as a
+ *  standalone "fix", which would be the laundering step (S5 R1). */
+function writeAttestBaseline(cwd) {
+  const ledgerPath = join(cwd, LEDGER_REL);
+  const bytes = existsSync(ledgerPath) ? readFileSync(ledgerPath) : Buffer.alloc(0);
+  const attestPath = join(cwd, ATTEST_REL);
+  ensureDir(dirname(attestPath));
+  writeFileSync(attestPath, `${JSON.stringify(baselineFor(bytes), null, 2)}\n`);
+}
+
+/**
+ * Claim a live grant for exactly `path`. Returns true if the write may proceed.
+ *
+ * Never throws: the hook's policy is fail-open, and a claim that explodes must
+ * not wedge the session. A false return means "no grant" and the caller denies
+ * on its own terms.
+ */
+export function claimGrant(cwd, path) {
+  try {
+    const grantsDir = join(cwd, GRANTS_REL);
+    if (!existsSync(grantsDir)) return false;
+
+    // A token is only honoured if its row is in the ledger. This is what stops
+    // a raw-written token file from being consumable — the Bash-forgery case.
+    // It binds the two artifacts without pretending to be crypto: an actor who
+    // writes BOTH still passes, which is the documented ceiling.
+    const ledgerTokenIds = new Set(
+      readOverrideLedger(cwd).filter((r) => r?.path === path).map((r) => r?.token_id),
+    );
+    if (ledgerTokenIds.size === 0) return false;
+
+    const now = Date.now();
+    for (const entry of readdirSync(grantsDir, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+      const tokenPath = join(grantsDir, entry.name);
+
+      let token;
+      try { token = JSON.parse(readFileSync(tokenPath, 'utf8')); } catch { continue; }
+      if (token?.path !== path) continue;
+      if (!ledgerTokenIds.has(token?.token_id)) continue;
+
+      // Expiry from the immutable stamp, NOT mtime: a checkout gives a file a
+      // fresh mtime, which would revive a mistakenly committed token.
+      const expiresAt = Date.parse(token?.expires_at ?? '');
+      if (!Number.isFinite(expiresAt) || expiresAt <= now) continue;
+
+      // The claim. Exactly one caller can rename a given path; losers get ENOENT.
+      const consumedDir = join(grantsDir, CONSUMED_SUBDIR);
+      ensureDir(consumedDir);
+      try {
+        renameSync(tokenPath, join(consumedDir, entry.name));
+        return true;
+      } catch {
+        continue;                        // another process won; try the next token
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}