javi-forge 1.29.0 → 1.30.0

package/dist/lib/secure-fs-transaction.js

@@ -0,0 +1,239 @@
+/**
+ * Platform-agnostic transactional file-write core for the SkillGuard Claude
+ * PreToolUse installer (Slice 3a). This module owns all irreversible I/O behind
+ * a single `PlatformSecureFs` adapter interface: it NEVER spawns a process and
+ * NEVER branches on `process.platform`. Every ownership/identity/ACL/exclusive
+ * decision is delegated to the injected adapter, so the engine is reviewed once
+ * (platform-free) and exercised by a synchronous in-memory fake in tests.
+ *
+ * WU-2 defines the interface + result types here so the POSIX adapter can
+ * implement them; WU-3 grows this file with `runTransaction` + `TransactionDeps`.
+ */
+import { createHash } from "node:crypto";
+import path from "node:path";
+/** Bounded nonce retries for an exclusive backup create. */
+const BACKUP_NONCE_CANDIDATES = 8;
+class TxAbort extends Error {
+    step;
+    detail;
+    constructor(step, detail) {
+        super(`${step}${detail ? `: ${detail}` : ""}`);
+        this.step = step;
+        this.detail = detail;
+    }
+}
+function must(step, res) {
+    if (!res.ok)
+        throw new TxAbort(step, res.detail ?? res.refusal);
+    return res.value;
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/** Compact ISO-ms stamp: 2026-08-16T19:00:00.123Z -> 20260816T190000123Z. */
+function timestamp(clock) {
+    return clock().toISOString().replace(/[-:.]/g, "");
+}
+function backupName(base, clock, nonce) {
+    return `${base}.javi-forge.bak.${timestamp(clock)}.${nonce}`;
+}
+function tempName(base, nonce) {
+    return `${base}.javi-forge.tmp.${process.pid}.${nonce}`;
+}
+/** Existing directory chain from the filesystem root through `leaf`, root first. */
+function ancestorChain(leaf) {
+    const chain = [];
+    let current = leaf;
+    while (true) {
+        chain.push(current);
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return chain.reverse();
+}
+/**
+ * Run the staged, two-target transaction. Preflight gates the private parent
+ * chain, creates `.claude`/`.claude/hooks` one exclusive `0o700` segment at a
+ * time, captures prior bytes (+ a forced-only persistent backup), stages each
+ * new byte set into a same-directory `0o600` temp, re-proves the full gate
+ * immediately before the first rename (JD-007), then commits asset-first and
+ * settings-second via same-directory rename + parent fsync. A failure after a
+ * commit triggers guarded reverse-order rollback from the in-memory captured
+ * bytes; lost proof or a post-write hash drift STOPS cleanup and returns
+ * manual-recovery guidance (never clobbers a concurrent change).
+ */
+export async function runTransaction(input) {
+    const { secureFs, clock, nonce, projectDir } = input;
+    const claudeDir = path.join(projectDir, ".claude");
+    const hooksDir = path.join(claudeDir, "hooks");
+    const heldByPath = new Map();
+    const heldOrder = [];
+    const createdDirs = [];
+    const staged = [];
+    const committed = [];
+    const backups = [];
+    const needsWrite = (c) => c.desired !== null;
+    const anyWrite = needsWrite(input.asset) || needsWrite(input.settings);
+    async function gate(dirPath, handle) {
+        must(`ownership ${dirPath}`, await secureFs.proveOwnershipAndMode(dirPath));
+        must(`acl ${dirPath}`, await secureFs.proveNoExtendedAcl(dirPath));
+        heldByPath.set(dirPath, handle);
+        heldOrder.push(handle);
+    }
+    async function ensureDir(parent, fullPath) {
+        const opened = await secureFs.openDirNoFollow(fullPath);
+        if (opened.ok && opened.value) {
+            await gate(fullPath, opened.value);
+            return opened.value;
+        }
+        const created = must(`create ${fullPath}`, await secureFs.createDirExclusive(parent, path.basename(fullPath), 0o700));
+        // Post-create identity revalidation + full gate on the new segment.
+        must(`revalidate-created ${fullPath}`, await secureFs.revalidateIdentity(fullPath, created.identity));
+        createdDirs.push(created);
+        await gate(fullPath, created);
+        return created;
+    }
+    async function gateStillValid() {
+        for (const handle of heldOrder) {
+            const id = await secureFs.revalidateIdentity(handle.path, handle.identity);
+            if (!id.ok)
+                return false;
+            if (!(await secureFs.proveOwnershipAndMode(handle.path)).ok)
+                return false;
+            if (!(await secureFs.proveNoExtendedAcl(handle.path)).ok)
+                return false;
+        }
+        return true;
+    }
+    try {
+        // --- PREFLIGHT: gate the existing chain root..projectDir ---
+        for (const dirPath of ancestorChain(projectDir)) {
+            const handle = must(`openDir ${dirPath}`, await secureFs.openDirNoFollow(dirPath));
+            await gate(dirPath, handle);
+        }
+        // --- SEGMENT CREATION: .claude then .claude/hooks, one at a time ---
+        if (anyWrite) {
+            const projectHandle = heldByPath.get(projectDir);
+            const claudeHandle = await ensureDir(projectHandle, claudeDir);
+            if (needsWrite(input.asset))
+                await ensureDir(claudeHandle, hooksDir);
+        }
+        // --- CAPTURE + (FORCED) BACKUP + STAGE, asset then settings ---
+        for (const component of [input.asset, input.settings]) {
+            if (!needsWrite(component))
+                continue;
+            const parentPath = path.dirname(component.path);
+            const dir = heldByPath.get(parentPath);
+            const base = path.basename(component.path);
+            must(`revalidate ${parentPath}`, await secureFs.revalidateIdentity(dir.path, dir.identity));
+            let prior = null;
+            if (component.capturePrior || component.forceBackup) {
+                prior = must(`capture ${component.path}`, await secureFs.captureFile(component.path));
+                must(`source-acl ${component.path}`, await secureFs.proveNoExtendedAcl(component.path));
+                if (component.forceBackup) {
+                    backups.push(await writeBackup(dir, base, prior));
+                }
+            }
+            const tName = tempName(base, nonce());
+            must(`stage ${tName}`, await secureFs.writeExclusive(dir, tName, component.desired, 0o600));
+            must(`stage-mode ${tName}`, await secureFs.applyExactMode(path.join(dir.path, tName), prior ? prior.mode : 0o600));
+            // Identity revalidation after each writeExclusive (JD-B-005).
+            must(`revalidate-staged ${parentPath}`, await secureFs.revalidateIdentity(dir.path, dir.identity));
+            staged.push({ dir, tempName: tName, target: component, prior });
+        }
+        // --- PRE-FIRST-RENAME FULL-GATE RE-PROVE (JD-007) ---
+        for (const handle of heldOrder) {
+            must(`recheck-id ${handle.path}`, await secureFs.revalidateIdentity(handle.path, handle.identity));
+            must(`recheck-own ${handle.path}`, await secureFs.proveOwnershipAndMode(handle.path));
+            must(`recheck-acl ${handle.path}`, await secureFs.proveNoExtendedAcl(handle.path));
+        }
+        // --- COMMIT: asset first, settings second ---
+        for (const entry of staged) {
+            const base = path.basename(entry.target.path);
+            must(`pre-rename ${entry.dir.path}`, await secureFs.revalidateIdentity(entry.dir.path, entry.dir.identity));
+            const wroteHash = sha256(entry.target.desired);
+            must(`rename ${base}`, await secureFs.renameInDir(entry.dir, entry.tempName, base));
+            must(`post-rename ${entry.dir.path}`, await secureFs.revalidateIdentity(entry.dir.path, entry.dir.identity));
+            committed.push({
+                path: entry.target.path,
+                dir: entry.dir,
+                wroteHash,
+                wasAbsent: entry.target.wasAbsent,
+                prior: entry.prior,
+            });
+        }
+        return {
+            ok: true,
+            committed: committed.map((c) => c.path),
+            backups,
+            errors: [],
+        };
+    }
+    catch (error) {
+        const errors = [
+            error instanceof TxAbort ? error.message : String(error),
+        ];
+        await rollback(committed, createdDirs, errors);
+        return {
+            ok: false,
+            committed: committed.map((c) => c.path),
+            backups,
+            errors,
+        };
+    }
+    finally {
+        for (const handle of [...createdDirs, ...heldOrder]) {
+            await handle.close().catch(() => { });
+        }
+    }
+    async function writeBackup(dir, base, prior) {
+        for (let attempt = 0; attempt < BACKUP_NONCE_CANDIDATES; attempt++) {
+            const name = backupName(base, clock, nonce());
+            const written = await secureFs.writeExclusive(dir, name, prior.bytes, 0o600);
+            if (!written.ok)
+                continue; // collision or transient — retry with a fresh nonce
+            must(`backup-mode ${name}`, await secureFs.applyExactMode(path.join(dir.path, name), prior.mode));
+            must(`backup-revalidate ${dir.path}`, await secureFs.revalidateIdentity(dir.path, dir.identity));
+            return path.join(dir.path, name);
+        }
+        throw new TxAbort("backup", `no exclusive backup name after ${BACKUP_NONCE_CANDIDATES}`);
+    }
+    async function rollback(done, created, errors) {
+        for (const entry of [...done].reverse()) {
+            if (!(await gateStillValid())) {
+                errors.push(`STOP: lost parent-chain proof; manual recovery at ${entry.path}`);
+                return;
+            }
+            const current = await secureFs.captureFile(entry.path);
+            if (!current.ok || !current.value) {
+                errors.push(`STOP: cannot re-read ${entry.path}; manual recovery`);
+                return;
+            }
+            if (current.value.sha256 !== entry.wroteHash) {
+                errors.push(`STOP: ${entry.path} changed after commit; manual recovery (concurrent edit)`);
+                return;
+            }
+            const base = path.basename(entry.path);
+            if (entry.wasAbsent) {
+                await secureFs.unlinkIfIdentity(entry.dir, base, current.value.identity);
+            }
+            else if (entry.prior) {
+                const rName = tempName(base, nonce());
+                const wrote = await secureFs.writeExclusive(entry.dir, rName, entry.prior.bytes, 0o600);
+                if (!wrote.ok) {
+                    errors.push(`STOP: cannot stage rollback for ${entry.path}`);
+                    return;
+                }
+                await secureFs.applyExactMode(path.join(entry.dir.path, rName), entry.prior.mode);
+                await secureFs.renameInDir(entry.dir, rName, base);
+            }
+        }
+        // Remove only tx-created, identity-matched, still-empty segments, child-first.
+        for (const handle of [...created].reverse()) {
+            await secureFs.rmdirIfIdentityEmpty(handle);
+        }
+    }
+}
+//# sourceMappingURL=secure-fs-transaction.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "javi-forge",
-	"version": "1.29.0",
+	"version": "1.30.0",
 	"description": "Project scaffolding and AI-ready CI bootstrap",
 	"type": "module",
 	"bin": {