javi-forge 1.28.1 → 1.30.0

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

@@ -0,0 +1,302 @@
+/**
+ * POSIX `PlatformSecureFs` adapters for the SkillGuard transactional installer
+ * (Slice 3a). This is the ONLY place a shell tool runs (`getfacl` on Linux,
+ * `/bin/ls -lde` on macOS) and the ONLY place `os`/`fs` ownership bits are
+ * interpreted. Everything fails closed: a missing/erroring/timed-out ACL tool,
+ * an extended/named/mask/default/inherited ACL entry, a foreign-owned or
+ * group/other-writable directory, or any inconclusive result refuses rather than
+ * degrading to a weaker mode-only write. It never strips an ACL.
+ */
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { constants as FS } from "node:fs";
+import { chmod, lstat, mkdir, open, rename, rmdir, unlink, } from "node:fs/promises";
+import path from "node:path";
+/** Bounded time budget for a single ACL inspection. */
+const ACL_TIMEOUT_MS = 2000;
+/** Read budget for the ACL tool output (defensive; ACLs are tiny). */
+const ACL_MAX_BUFFER = 1024 * 1024;
+// --- result constructors -----------------------------------------------------
+const ok = () => ({ ok: true });
+const okValue = (value) => ({ ok: true, value });
+const refuse = (refusal, detail) => ({ ok: false, refusal, detail });
+function errCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? error.code
+        : undefined;
+}
+// --- default spawn (bounded, LC_ALL=C, argv never a shell string) ------------
+const defaultSpawn = (cmd, args) => new Promise((resolve) => {
+    execFile(cmd, args, {
+        timeout: ACL_TIMEOUT_MS,
+        maxBuffer: ACL_MAX_BUFFER,
+        encoding: "utf8",
+        env: { ...process.env, LC_ALL: "C", LANG: "C" },
+    }, (error, stdout) => {
+        if (!error)
+            return resolve({ code: 0, stdout: stdout ?? "" });
+        const e = error;
+        if (e.code === "ENOENT") {
+            return resolve({ spawnError: true, code: null, stdout: "" });
+        }
+        if (e.killed || e.signal === "SIGTERM") {
+            return resolve({ timedOut: true, code: null, stdout: stdout ?? "" });
+        }
+        const code = typeof e.code === "number" ? e.code : 1;
+        return resolve({ code, stdout: stdout ?? "" });
+    });
+});
+// --- Linux getfacl adapter (Algorithm D) -------------------------------------
+const LINUX_BASE_ENTRY = /^(user|group|other)::/;
+export function createLinuxAclAdapter(spawn = defaultSpawn) {
+    return {
+        async proveClean(target) {
+            const res = await spawn("getfacl", [
+                "--absolute-names",
+                "--numeric",
+                "--omit-header",
+                "--",
+                target,
+            ]);
+            if (res.spawnError)
+                return refuse("unsupported-posix-acl", "getfacl absent");
+            if (res.timedOut)
+                return refuse("unsupported-posix-acl", "getfacl timeout");
+            if (res.code !== 0) {
+                return refuse("unsupported-posix-acl", `getfacl exit ${res.code}`);
+            }
+            for (const raw of res.stdout.split("\n")) {
+                const line = raw.trim();
+                if (line === "" || line.startsWith("#"))
+                    continue;
+                if (LINUX_BASE_ENTRY.test(line))
+                    continue;
+                return refuse("unsupported-posix-acl", "extended ACL entry");
+            }
+            return ok();
+        },
+    };
+}
+// --- macOS /bin/ls -lde adapter (Algorithm E) --------------------------------
+const MACOS_ACE_LINE = /^\s*\d+:\s/;
+export function createMacosAclAdapter(spawn = defaultSpawn) {
+    return {
+        async proveClean(target) {
+            const res = await spawn("/bin/ls", ["-lde", "--", target]);
+            if (res.spawnError)
+                return refuse("unsupported-posix-acl", "/bin/ls absent");
+            if (res.timedOut)
+                return refuse("unsupported-posix-acl", "ls timeout");
+            if (res.code !== 0) {
+                return refuse("unsupported-posix-acl", `ls exit ${res.code}`);
+            }
+            const lines = res.stdout.split("\n");
+            const modeLine = lines[0] ?? "";
+            if (modeLine[10] === "+") {
+                return refuse("unsupported-posix-acl", "ACL present (+ flag)");
+            }
+            if (lines.some((line) => MACOS_ACE_LINE.test(line))) {
+                return refuse("unsupported-posix-acl", "ACE listed");
+            }
+            return ok();
+        },
+    };
+}
+// --- the POSIX secure filesystem --------------------------------------------
+const DIR_FLAGS = FS.O_DIRECTORY | FS.O_NOFOLLOW | FS.O_RDONLY;
+const CAPTURE_FLAGS = FS.O_NOFOLLOW | FS.O_RDONLY;
+const EXCLUSIVE_FLAGS = FS.O_CREAT | FS.O_EXCL | FS.O_WRONLY | FS.O_NOFOLLOW;
+function identityOf(stats) {
+    return { dev: stats.dev, ino: stats.ino };
+}
+function ownershipTrusted(uid) {
+    const euid = typeof process.geteuid === "function" ? process.geteuid() : -1;
+    return uid === euid || uid === 0;
+}
+export function createPosixSecureFs(acl) {
+    async function fsyncDir(dirPath) {
+        const handle = await open(dirPath, DIR_FLAGS);
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    const secureFs = {
+        async openDirNoFollow(dirPath) {
+            try {
+                const handle = await open(dirPath, DIR_FLAGS);
+                try {
+                    const stats = await handle.stat();
+                    const identity = identityOf(stats);
+                    return okValue({
+                        path: dirPath,
+                        identity,
+                        close: () => handle.close(),
+                    });
+                }
+                catch (error) {
+                    await handle.close();
+                    throw error;
+                }
+            }
+            catch (error) {
+                return refuse("unsafe-parent-chain", `openDir ${dirPath}: ${errCode(error) ?? "error"}`);
+            }
+        },
+        async revalidateIdentity(target, held) {
+            try {
+                const stats = await lstat(target);
+                if (stats.dev === held.dev && stats.ino === held.ino)
+                    return ok();
+                return refuse("unsafe-parent-chain", `identity drift at ${target}`);
+            }
+            catch (error) {
+                return refuse("unsafe-parent-chain", `revalidate ${target}: ${errCode(error) ?? "error"}`);
+            }
+        },
+        async proveOwnershipAndMode(dirPath) {
+            try {
+                const stats = await lstat(dirPath);
+                if (!ownershipTrusted(stats.uid)) {
+                    return refuse("unsafe-parent-chain", `foreign owner at ${dirPath}`);
+                }
+                if ((stats.mode & 0o022) !== 0) {
+                    return refuse("unsafe-parent-chain", `group/other-writable ${dirPath}`);
+                }
+                return ok();
+            }
+            catch (error) {
+                return refuse("unsafe-parent-chain", `ownership ${dirPath}: ${errCode(error) ?? "error"}`);
+            }
+        },
+        proveNoExtendedAcl(target) {
+            return acl.proveClean(target);
+        },
+        async createDirExclusive(parent, name, mode) {
+            const full = path.join(parent.path, name);
+            try {
+                await mkdir(full, { mode }); // fails EEXIST if it already exists
+                await chmod(full, mode); // defeat umask masking of mkdir mode
+            }
+            catch (error) {
+                return refuse("unsafe-parent-chain", `mkdir ${full}: ${errCode(error) ?? "error"}`);
+            }
+            const opened = await secureFs.openDirNoFollow(full);
+            if (!opened.ok || !opened.value)
+                return opened;
+            const owned = await secureFs.proveOwnershipAndMode(full);
+            if (!owned.ok) {
+                await opened.value.close();
+                return refuse("unsafe-parent-chain", owned.detail ?? full);
+            }
+            return opened;
+        },
+        async captureFile(target) {
+            try {
+                const handle = await open(target, CAPTURE_FLAGS);
+                try {
+                    const stats = await handle.stat();
+                    const bytes = await handle.readFile();
+                    const sha256 = createHash("sha256").update(bytes).digest("hex");
+                    return okValue({
+                        bytes,
+                        mode: stats.mode & 0o7777,
+                        identity: identityOf(stats),
+                        sha256,
+                    });
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            catch (error) {
+                return refuse("unsafe-parent-chain", `capture ${target}: ${errCode(error) ?? "error"}`);
+            }
+        },
+        async writeExclusive(dir, name, bytes, mode) {
+            const full = path.join(dir.path, name);
+            let handle;
+            try {
+                handle = await open(full, EXCLUSIVE_FLAGS, mode);
+                await handle.writeFile(bytes);
+                await handle.sync();
+                return ok();
+            }
+            catch (error) {
+                return refuse("unsafe-parent-chain", `writeExclusive ${full}: ${errCode(error) ?? "error"}`);
+            }
+            finally {
+                await handle?.close().catch(() => { });
+            }
+        },
+        async applyExactMode(target, mode) {
+            try {
+                await chmod(target, mode);
+                const stats = await lstat(target);
+                if ((stats.mode & 0o7777) !== mode) {
+                    return refuse("unsafe-parent-chain", `mode mismatch ${target}`);
+                }
+            }
+            catch (error) {
+                return refuse("unsafe-parent-chain", `applyMode ${target}: ${errCode(error) ?? "error"}`);
+            }
+            return acl.proveClean(target);
+        },
+        async renameInDir(dir, from, to) {
+            try {
+                await rename(path.join(dir.path, from), path.join(dir.path, to));
+                await fsyncDir(dir.path);
+                return ok();
+            }
+            catch (error) {
+                return refuse("unsafe-parent-chain", `rename ${from}->${to}: ${errCode(error) ?? "error"}`);
+            }
+        },
+        async unlinkIfIdentity(dir, name, held) {
+            const full = path.join(dir.path, name);
+            try {
+                const stats = await lstat(full);
+                if (stats.dev !== held.dev || stats.ino !== held.ino) {
+                    return refuse("unsafe-parent-chain", `identity mismatch ${full}`);
+                }
+                await unlink(full);
+                await fsyncDir(dir.path);
+                return ok();
+            }
+            catch (error) {
+                return refuse("unsafe-parent-chain", `unlink ${full}: ${errCode(error) ?? "error"}`);
+            }
+        },
+        async rmdirIfIdentityEmpty(handle) {
+            try {
+                const stats = await lstat(handle.path);
+                if (stats.dev !== handle.identity.dev ||
+                    stats.ino !== handle.identity.ino) {
+                    return refuse("unsafe-parent-chain", `identity mismatch ${handle.path}`);
+                }
+                await rmdir(handle.path); // ENOTEMPTY if non-empty → refuse, no escalation
+                return ok();
+            }
+            catch (error) {
+                return refuse("unsafe-parent-chain", `rmdir ${handle.path}: ${errCode(error) ?? "error"}`);
+            }
+        },
+    };
+    return secureFs;
+}
+/**
+ * Select the POSIX secure filesystem for the host platform. Linux uses the
+ * `getfacl` adapter, macOS uses `/bin/ls -lde`; Windows and every other platform
+ * return `null` so the manager refuses with `windows-secure-object-unavailable`
+ * and mutates nothing (Slice 3b implements Windows).
+ */
+export function selectSecureFs(platform = process.platform) {
+    if (platform === "linux")
+        return createPosixSecureFs(createLinuxAclAdapter());
+    if (platform === "darwin")
+        return createPosixSecureFs(createMacosAclAdapter());
+    return null;
+}
+//# sourceMappingURL=secure-fs-posix.js.map

package/dist/lib/secure-fs-transaction.d.ts

@@ -0,0 +1,126 @@
+/**
+ * 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`.
+ */
+/** Identity of an opened directory/file, captured from its handle. */
+export interface SecureIdentity {
+    dev: number;
+    ino: number;
+}
+/** A held, no-follow directory handle plus its captured identity and path. */
+export interface SecureDirHandle {
+    readonly path: string;
+    readonly identity: SecureIdentity;
+    close(): Promise<void>;
+}
+/** Captured prior state of a target file, taken through the validated gate. */
+export interface CapturedFile {
+    bytes: Buffer;
+    mode: number;
+    identity: SecureIdentity;
+    sha256: string;
+}
+export type SecureRefusal = "unsafe-parent-chain" | "unsupported-posix-acl" | "windows-secure-object-unavailable";
+export interface SecureResult<T> {
+    ok: boolean;
+    value?: T;
+    refusal?: SecureRefusal;
+    detail?: string;
+}
+/**
+ * The whole platform boundary. Every host-dependent operation is a method here;
+ * the transaction core talks only to this interface. POSIX now, Windows stub in
+ * Slice 3b, a synchronous fake in tests.
+ */
+export interface PlatformSecureFs {
+    /** Open an existing directory no-follow (O_DIRECTORY|O_NOFOLLOW) and capture dev+ino. */
+    openDirNoFollow(dirPath: string): Promise<SecureResult<SecureDirHandle>>;
+    /** Reopen a path and confirm its identity equals a previously held one. */
+    revalidateIdentity(target: string, held: SecureIdentity): Promise<SecureResult<void>>;
+    /** Prove owner == effective uid or root AND no group/other write bits. */
+    proveOwnershipAndMode(dirPath: string): Promise<SecureResult<void>>;
+    /** Prove no extended/named/mask/default/inherited ACL on the path. */
+    proveNoExtendedAcl(target: string): Promise<SecureResult<void>>;
+    /** Create ONE child directory exclusively at mode, reopen+verify, return its handle. */
+    createDirExclusive(parent: SecureDirHandle, name: string, mode: number): Promise<SecureResult<SecureDirHandle>>;
+    /**
+     * Capture a regular file's bytes+mode+identity+sha through the validated gate.
+     * MUST open the target with `O_NOFOLLOW|O_RDONLY` (never a plain path read): a
+     * symlink swapped in at the target name must fail the open, not be
+     * dereferenced. This is a security boundary (JD-B-003) — the capture is the
+     * source of both the persistent backup and the in-memory rollback bytes.
+     */
+    captureFile(target: string): Promise<SecureResult<CapturedFile>>;
+    /**
+     * Create <name> in dir with O_CREAT|O_EXCL|O_WRONLY|O_NOFOLLOW at mode; write
+     * bytes; `handle.sync()` (fsync) the file before close. The write and the
+     * fsync are one method so an fsync fault is an injectable fault point of
+     * `writeExclusive` itself (JD-B-004): a fake can succeed the write and fail
+     * the sync to drive that branch.
+     */
+    writeExclusive(dir: SecureDirHandle, name: string, bytes: Buffer, mode: number): Promise<SecureResult<void>>;
+    /** Apply an exact mode to an existing staged file and re-verify mode + ACL absence. */
+    applyExactMode(target: string, mode: number): Promise<SecureResult<void>>;
+    /** Same-directory rename from -> to, then fsync the directory. */
+    renameInDir(dir: SecureDirHandle, from: string, to: string): Promise<SecureResult<void>>;
+    /** Unlink an identity-matched file (rollback of a newly created target). */
+    unlinkIfIdentity(dir: SecureDirHandle, name: string, held: SecureIdentity): Promise<SecureResult<void>>;
+    /** Remove an identity-matched EMPTY directory (rollback of a created segment). */
+    rmdirIfIdentityEmpty(handle: SecureDirHandle): Promise<SecureResult<void>>;
+}
+/** Injected seams making the engine deterministic and host-independent. */
+export interface TransactionDeps {
+    secureFs: PlatformSecureFs;
+    clock: () => Date;
+    nonce: () => string;
+}
+/**
+ * One target of the transaction (asset or settings). All Claude-specific state
+ * is collapsed to explicit flags so the engine stays agent-agnostic.
+ */
+export interface TransactionComponent {
+    /** Absolute target path. */
+    path: string;
+    /** Bytes to write, or null to skip this component (no-op / already current). */
+    desired: Buffer | null;
+    /** Capture prior bytes for in-memory rollback (existing managed/legacy content). */
+    capturePrior: boolean;
+    /** Create a persistent backup — forced edited-managed only (Decision 5). */
+    forceBackup: boolean;
+    /** True when the target did not exist before this op (rollback = unlink). */
+    wasAbsent: boolean;
+}
+export interface RunTransactionInput extends TransactionDeps {
+    /** Existing project directory; `.claude` / `.claude/hooks` are created under it. */
+    projectDir: string;
+    /** Committed first. */
+    asset: TransactionComponent;
+    /** Committed second. */
+    settings: TransactionComponent;
+}
+export interface TransactionOutcome {
+    ok: boolean;
+    committed: string[];
+    backups: string[];
+    errors: string[];
+}
+/**
+ * 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 declare function runTransaction(input: RunTransactionInput): Promise<TransactionOutcome>;
+//# sourceMappingURL=secure-fs-transaction.d.ts.map

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.28.1",
+	"version": "1.30.0",
 	"description": "Project scaffolding and AI-ready CI bootstrap",
 	"type": "module",
 	"bin": {