javi-forge 1.35.0 → 1.36.0

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

@@ -64,23 +64,119 @@ export const ACL_DETAIL = {
 };
 // --- Linux getfacl adapter (Algorithm D) -------------------------------------
 const LINUX_BASE_ENTRY = /^(user|group|other)::/;
-export function createLinuxAclAdapter(spawn = defaultSpawn) {
+// Numeric getfacl entry shapes (LC_ALL=C, --numeric, --omit-header).
+const MASK_PERMS = /^mask::([r-][w-][x-])$/;
+const MASK_ANY = /^mask::/;
+const NAMED_USER = /^user:(\d+):([r-][w-][x-])$/;
+const NAMED_GROUP = /^group:(\d+):([r-][w-][x-])$/;
+const DEFAULT_ENTRY = /^default:/;
+/** Default owner-uid source: an lstat of the target (authoritative carve-out). */
+const defaultStat = async (target) => {
+    const stats = await lstat(target);
+    return { uid: stats.uid };
+};
+/** Run the shared, bounded, LC_ALL=C getfacl spawn and map its fail-closed edges. */
+async function runGetfacl(spawn, target) {
+    const res = await spawn("getfacl", [
+        "--absolute-names",
+        "--numeric",
+        "--omit-header",
+        "--",
+        target,
+    ]);
+    if (res.spawnError)
+        return refuse("unsupported-posix-acl", ACL_DETAIL.getfaclAbsent);
+    if (res.timedOut)
+        return refuse("unsupported-posix-acl", ACL_DETAIL.getfaclTimeout);
+    if (res.code !== 0)
+        return refuse("unsupported-posix-acl", `getfacl exit ${res.code}`);
+    return res;
+}
+function isSpawnOutcome(v) {
+    return "stdout" in v;
+}
+/** Strip an inline `#effective:...` suffix (tab-separated) and trim. */
+function stripEffective(raw) {
+    const hash = raw.indexOf("#");
+    return (hash === -1 ? raw : raw.slice(0, hash)).trim();
+}
+/** Non-empty, non-comment ACL lines with any inline `#effective` suffix removed. */
+function aclEntries(stdout) {
+    const entries = [];
+    for (const raw of stdout.split("\n")) {
+        if (raw.trim() === "" || raw.trimStart().startsWith("#"))
+            continue;
+        const line = stripEffective(raw);
+        if (line === "")
+            continue;
+        entries.push(line);
+    }
+    return entries;
+}
+const hasW = (perm) => perm.includes("w");
+/**
+ * Two-pass path-endangering classifier over numeric getfacl output. Returns
+ * `ok()` when no foreign principal can endanger the on-path node, or a
+ * fail-closed `unsupported-posix-acl` refusal. `trusted` is {ownerUid, 0, euid}.
+ */
+function classifyEndangering(entries, trusted) {
+    // PASS 1 — locate the mask (order-independent). A malformed mask fails closed.
+    let maskPerm = null; // null = no `mask::` entry present
+    for (const line of entries) {
+        const m = MASK_PERMS.exec(line);
+        if (m) {
+            maskPerm = m[1];
+            continue;
+        }
+        if (MASK_ANY.test(line)) {
+            return refuse("unsupported-posix-acl", ACL_DETAIL.extendedAclEntry);
+        }
+    }
+    const checkNamed = (id, raw, isUser) => {
+        if (!hasW(raw))
+            return true; // x-only traverse / r-only read ≠ endanger
+        // raw carries `w`: a named entry with raw `w` REQUIRES a mask to be
+        // effective; POSIX always emits one when a named entry exists. Its absence
+        // is anomalous → fail closed.
+        if (maskPerm === null)
+            return false;
+        if (!hasW(maskPerm))
+            return true; // masked out → effective lacks `w`
+        if (isUser && trusted.has(id))
+            return true; // owner/root/euid carve-out
+        return false; // foreign named-user OR any named-group with effective `w`
+    };
+    // PASS 2 — classify each entry.
+    for (const line of entries) {
+        if (LINUX_BASE_ENTRY.test(line))
+            continue; // base user::/group::/other::
+        if (MASK_ANY.test(line))
+            continue; // mask ceiling (validated in PASS 1)
+        if (DEFAULT_ENTRY.test(line))
+            continue; // inheritance-only; strict backstop
+        const nu = NAMED_USER.exec(line);
+        if (nu) {
+            if (checkNamed(Number(nu[1]), nu[2], true))
+                continue;
+            return refuse("unsupported-posix-acl", ACL_DETAIL.extendedAclEntry);
+        }
+        const ng = NAMED_GROUP.exec(line);
+        if (ng) {
+            if (checkNamed(Number(ng[1]), ng[2], false))
+                continue;
+            return refuse("unsupported-posix-acl", ACL_DETAIL.extendedAclEntry);
+        }
+        // Unrecognized/unparseable shape → fail closed.
+        return refuse("unsupported-posix-acl", ACL_DETAIL.extendedAclEntry);
+    }
+    return ok();
+}
+export function createLinuxAclAdapter(spawn = defaultSpawn, stat = defaultStat) {
     return {
         async proveClean(target) {
-            const res = await spawn("getfacl", [
-                "--absolute-names",
-                "--numeric",
-                "--omit-header",
-                "--",
-                target,
-            ]);
-            if (res.spawnError)
-                return refuse("unsupported-posix-acl", ACL_DETAIL.getfaclAbsent);
-            if (res.timedOut)
-                return refuse("unsupported-posix-acl", ACL_DETAIL.getfaclTimeout);
-            if (res.code !== 0) {
-                return refuse("unsupported-posix-acl", `getfacl exit ${res.code}`);
-            }
+            const res = await runGetfacl(spawn, target);
+            if (!isSpawnOutcome(res))
+                return res;
             for (const raw of res.stdout.split("\n")) {
                 const line = raw.trim();
                 if (line === "" || line.startsWith("#"))
@@ -91,12 +187,31 @@ export function createLinuxAclAdapter(spawn = defaultSpawn) {
             }
             return ok();
         },
+        async proveNoEndangeringAcl(target) {
+            const res = await runGetfacl(spawn, target);
+            if (!isSpawnOutcome(res))
+                return res;
+            // Owner uid is the authoritative carve-out source (proveOwnershipAndMode
+            // has already proven owner ∈ {euid, root}, so this narrows the trusted
+            // set to exactly those principals). An unresolvable lstat cannot prove
+            // the carve-out → fail closed.
+            let ownerUid;
+            try {
+                ownerUid = (await stat(target)).uid;
+            }
+            catch {
+                return refuse("unsupported-posix-acl", "acl owner-stat failed");
+            }
+            const euid = typeof process.geteuid === "function" ? process.geteuid() : -1;
+            const trusted = new Set([ownerUid, 0, euid]);
+            return classifyEndangering(aclEntries(res.stdout), trusted);
+        },
     };
 }
 // --- macOS /bin/ls -lde adapter (Algorithm E) --------------------------------
 const MACOS_ACE_LINE = /^\s*\d+:\s/;
 export function createMacosAclAdapter(spawn = defaultSpawn) {
-    return {
+    const adapter = {
         async proveClean(target) {
             const res = await spawn("/bin/ls", ["-lde", "--", target]);
             if (res.spawnError)
@@ -116,7 +231,15 @@ export function createMacosAclAdapter(spawn = defaultSpawn) {
             }
             return ok();
         },
+        // DEFERRED (user: Linux only): darwin ancestors stay STRICT = status-quo
+        // over-refusal, not the reported Linux bug. `/bin/ls -lde` ACE text carries
+        // no numeric mask to compute effective rights from, so the path-endangering
+        // narrowing is a documented follow-up. Alias to the strict proof.
+        proveNoEndangeringAcl(target) {
+            return adapter.proveClean(target);
+        },
     };
+    return adapter;
 }
 /**
  * Probe the ACL adapter READ-ONLY: it resolves and runs a version/list argv and
@@ -241,6 +364,14 @@ export function createPosixSecureFs(acl) {
         proveNoExtendedAcl(target) {
             return acl.proveClean(target);
         },
+        // Lenient ANCESTOR predicate: refuse only path-endangering foreign ACL
+        // entries. The transaction core calls THIS on ancestor (non-managed)
+        // controlling dirs and keeps `proveNoExtendedAcl`/`proveManagedContainer`
+        // (strict) on the dirs it owns — selection is by the managed-containers set,
+        // never by `process.platform`.
+        proveNoEndangeringAcl(target) {
+            return acl.proveNoEndangeringAcl(target);
+        },
         async createDirExclusive(parent, name, mode) {
             const full = path.join(parent.path, name);
             try {
@@ -353,14 +484,21 @@ export function createPosixSecureFs(acl) {
                 return refuse("unsafe-parent-chain", `rmdir ${handle.path}: ${errCode(error) ?? "error"}`);
             }
         },
-        // On POSIX, permission to ADD a child to a directory IS the directory's
-        // write bit; proveOwnershipAndMode already refuses any group/other write
-        // (stats.mode & 0o022). So the managed-container check is definitionally the
-        // same predicate gate() just ran on this path — idempotent, no new refusal
-        // surface. The seam has teeth only on win32, where Predicate A tolerates
-        // add-child on high ancestors (Round-4 / JDA-401).
-        proveManagedContainer(dirPath) {
-            return secureFs.proveOwnershipAndMode(dirPath);
+        // A MANAGED CONTAINER (`.claude`/`.claude/hooks`) the tool owns must refuse
+        // ANY extended ACL entry — strictly more than the lenient ancestor `gate()`,
+        // which now tolerates benign path-non-endangering entries. Two arms, both
+        // fail-closed: (1) ownership/mode — on POSIX, group/other write IS add-child
+        // on a directory (stats.mode & 0o022); (2) the STRICT any-extended-entry ACL
+        // proof, re-homed here from the ancestor gate so the net managed-container
+        // guarantee stays byte-identical to the pre-narrowing strict-everywhere
+        // behavior. The seam's add-child dimension has teeth only on win32; the
+        // strict ACL arm is what keeps `.claude` from accepting a benign entry an
+        // ancestor now would.
+        async proveManagedContainer(dirPath) {
+            const owned = await secureFs.proveOwnershipAndMode(dirPath);
+            if (!owned.ok)
+                return owned;
+            return acl.proveClean(dirPath);
         },
     };
     return secureFs;

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

@@ -63,8 +63,22 @@ export interface PlatformSecureFs {
     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. */
+    /**
+     * STRICT proof: no extended/named/mask/default/inherited ACL on the path. Used
+     * on managed containers (via `proveManagedContainer`) and leaf source files.
+     */
     proveNoExtendedAcl(target: string): Promise<SecureResult<void>>;
+    /**
+     * LENIENT ancestor proof: refuse only a path-ENDANGERING ACL entry (a foreign
+     * principal that can swap/delete/rename the on-path node) and proceed on benign
+     * ones (a lone mask, an effective-non-write or x-only or trusted named entry, a
+     * `default:*`). Called by the engine on ANCESTOR (non-managed) controlling dirs
+     * only; managed containers keep the strict proof. Selection is by the
+     * managed-containers role, NEVER by `process.platform`. On win32 this mirrors
+     * the ratified Predicate A (already lenient on ancestors); on darwin it is the
+     * strict no-op alias (deferred).
+     */
+    proveNoEndangeringAcl(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>>;
     /**
@@ -125,13 +139,33 @@ export interface TransactionComponent {
     /** True when the target did not exist before this op (rollback = unlink). */
     wasAbsent: boolean;
 }
+/**
+ * Optional non-Claude container topology (Codex adapter, agnostic slice 2). When
+ * present it FULLY REPLACES the default `.claude`/`.claude/hooks` + [asset,settings]
+ * wiring; every proof primitive (ancestor gate, managed-container proof,
+ * capture/stage/commit/rollback) runs unchanged over the supplied dirs/components.
+ * When absent, the transaction behaves byte-identically to before this seam.
+ */
+export interface TransactionLayout {
+    /** Managed containers to ensure/prove/create, ordered PARENT-FIRST (absolute). */
+    containers: string[];
+    /** Ordered write components (captured/staged/committed in array order). */
+    components: TransactionComponent[];
+}
 export interface RunTransactionInput extends TransactionDeps {
-    /** Existing project directory; `.claude` / `.claude/hooks` are created under it. */
+    /**
+     * Existing base directory; the ancestor chain root..projectDir is gated. The
+     * default topology creates `.claude` / `.claude/hooks` under it; a `layout`
+     * (Codex) uses it only as the gated ancestor-chain leaf (its containers are
+     * absolute and supplied directly).
+     */
     projectDir: string;
-    /** Committed first. */
-    asset: TransactionComponent;
-    /** Committed second. */
-    settings: TransactionComponent;
+    /** Committed first (default Claude topology; ignored when `layout` is present). */
+    asset?: TransactionComponent;
+    /** Committed second (default Claude topology; ignored when `layout` is present). */
+    settings?: TransactionComponent;
+    /** Non-Claude container topology; overrides `asset`/`settings` when present. */
+    layout?: TransactionLayout;
 }
 export interface TransactionOutcome {
     ok: boolean;

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

@@ -65,14 +65,34 @@ function ancestorChain(leaf) {
  * manual-recovery guidance (never clobbers a concurrent change).
  */
 export async function runTransaction(input) {
+    // Seam validation (fail-closed): the topology is EITHER a `layout` OR the
+    // default Claude pair [asset, settings]. A caller with neither would deref
+    // `undefined.desired` deep in the engine — refuse up front with a clear error.
+    if (!input.layout && !(input.asset && input.settings)) {
+        throw new TxAbort("validate", "runTransaction requires `layout` or both `asset` and `settings`");
+    }
     const { secureFs, clock, nonce, projectDir } = input;
-    const claudeDir = path.join(projectDir, ".claude");
-    const hooksDir = path.join(claudeDir, "hooks");
+    // Container topology + write components. The default (no `layout`) is the exact
+    // Claude `.claude` → `.claude/hooks` nesting with [asset, settings]; a `layout`
+    // (Codex) supplies absolute containers parent-first and an ordered component
+    // list. Either way the proof primitives below are identical.
+    const containers = input.layout
+        ? input.layout.containers
+        : [
+            path.join(projectDir, ".claude"),
+            path.join(projectDir, ".claude", "hooks"),
+        ];
+    const components = input.layout
+        ? input.layout.components
+        : [
+            input.asset,
+            input.settings,
+        ];
     // The dirs the tool OWNS: their children include the executed asset and the
     // settings it is referenced from. Fixed and known to the core regardless of
     // the per-run write plan; each existing member is proved on EVERY anyWrite run
     // (Round-4/5 / JDA-401 + JDB5-001).
-    const managedContainers = new Set([claudeDir, hooksDir]);
+    const managedContainers = new Set(containers);
     const heldByPath = new Map();
     const heldOrder = [];
     const createdDirs = [];
@@ -80,10 +100,22 @@ export async function runTransaction(input) {
     const committed = [];
     const backups = [];
     const needsWrite = (c) => c.desired !== null;
-    const anyWrite = needsWrite(input.asset) || needsWrite(input.settings);
+    const anyWrite = components.some(needsWrite);
+    // A component writes into `container` when its parent dir IS the container or a
+    // descendant of it — used to decide which absent containers to create.
+    const writesInto = (container) => components.some((c) => needsWrite(c) &&
+        (path.dirname(c.path) === container ||
+            path.dirname(c.path).startsWith(`${container}${path.sep}`)));
+    // The uniform per-held-dir gate. It runs the LENIENT ancestor ACL predicate on
+    // EVERY held dir — including managed containers, which are ALSO proved strict by
+    // `proveManagedContainer` right after they are gated (in ensureManagedContainer)
+    // and re-proved strict pre-commit/rollback. So `.claude`/`.claude/hooks` still
+    // refuse ANY extended entry (lenient-gated THEN strict-managed); only ancestor-
+    // only segments loosen. No `process.platform` here — role is expressed by which
+    // dirs get proveManagedContainer'd (the managedContainers set).
     async function gate(dirPath, handle) {
         must(`ownership ${dirPath}`, await secureFs.proveOwnershipAndMode(dirPath));
-        must(`acl ${dirPath}`, await secureFs.proveNoExtendedAcl(dirPath));
+        must(`acl ${dirPath}`, await secureFs.proveNoEndangeringAcl(dirPath));
         heldByPath.set(dirPath, handle);
         heldOrder.push(handle);
     }
@@ -134,7 +166,9 @@ export async function runTransaction(input) {
                 return false;
             if (!(await secureFs.proveOwnershipAndMode(handle.path)).ok)
                 return false;
-            if (!(await secureFs.proveNoExtendedAcl(handle.path)).ok)
+            // Lenient ancestor predicate — identical to preflight `gate()`, so an ACL
+            // that passed preflight is not spuriously refused at rollback re-prove.
+            if (!(await secureFs.proveNoEndangeringAcl(handle.path)).ok)
                 return false;
             // Re-check the container add/delete-child dimension on the rollback path
             // too, for full symmetry with the pre-commit re-prove (JDB5-002).
@@ -159,23 +193,23 @@ export async function runTransaction(input) {
         // pre-commit); one that is absent is CREATED only when a child is written
         // into it this run, else left alone (nothing to secure).
         if (anyWrite) {
-            const projectHandle = heldByPath.get(projectDir);
-            // .claude always ensured on anyWrite (holds settings; grandparent of
-            // the asset). createIfAbsent=true never returns null (opens, creates, or
-            // throws) → narrow non-null before passing as parent (JDA6-003).
-            const claudeHandle = await ensureManagedContainer(projectHandle, claudeDir, 
-            /* createIfAbsent */ true);
-            if (!claudeHandle) {
-                throw new TxAbort(`container ${claudeDir}`, "unexpected null handle");
+            // Ensure every managed container PARENT-FIRST. Each container's parent is
+            // already held (its dirname was gated in preflight or ensured by an earlier
+            // iteration). A container is CREATED only when a component writes into it
+            // or a descendant container this run; otherwise it is proved IF present,
+            // else left alone (JDB5-001). This generalizes the former hardcoded
+            // `.claude` → `.claude/hooks` pair without changing any proof primitive.
+            for (const container of containers) {
+                const parentHandle = heldByPath.get(path.dirname(container));
+                if (!parentHandle) {
+                    throw new TxAbort(`container ${container}`, "parent chain not held");
+                }
+                await ensureManagedContainer(parentHandle, container, 
+                /* createIfAbsent */ writesInto(container));
             }
-            // .claude/hooks: create when the asset writes into it; otherwise prove
-            // IF it exists (settings-only repair must still secure the hook's
-            // container — JDB5-001).
-            await ensureManagedContainer(claudeHandle, hooksDir, 
-            /* createIfAbsent */ needsWrite(input.asset));
         }
-        // --- CAPTURE + (FORCED) BACKUP + STAGE, asset then settings ---
-        for (const component of [input.asset, input.settings]) {
+        // --- CAPTURE + (FORCED) BACKUP + STAGE, in component order ---
+        for (const component of components) {
             if (!needsWrite(component))
                 continue;
             const parentPath = path.dirname(component.path);
@@ -201,7 +235,11 @@ export async function runTransaction(input) {
         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));
+            // LENIENT ancestor predicate — MUST match preflight `gate()` so an ancestor
+            // ACL accepted at preflight is not refused at commit (spec: predicate is
+            // consistent across preflight and re-prove). Managed containers held here
+            // are ALSO re-proved strict just below via `recheck-container`.
+            must(`recheck-acl ${handle.path}`, await secureFs.proveNoEndangeringAcl(handle.path));
             // Re-prove the managed-container add/delete-child dimension for held
             // handles that ARE managed containers, closing the TOCTOU window between
             // ensure time and commit (JDB7-003; parity with 3a Decision 6 / JD-007).

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

@@ -218,6 +218,13 @@ export function createWindowsSecureFs(transport) {
         async proveNoExtendedAcl(target) {
             return mapVoid(await call({ op: "proveDacl", args: { path: target } }), `acl ${target}`);
         },
+        // win32 already ships the ratified lenient Predicate A on ancestors via
+        // `proveDacl` (managed-container strictness lives in `proveManagedContainer`).
+        // So the lenient ancestor predicate is the SAME `proveDacl` op — ancestor and
+        // managed-container behavior stay byte-identical on Windows.
+        async proveNoEndangeringAcl(target) {
+            return mapVoid(await call({ op: "proveDacl", args: { path: target } }), `acl ${target}`);
+        },
         async proveManagedContainer(dirPath) {
             return mapVoid(await call({ op: "proveContainer", args: { path: dirPath } }), `container ${dirPath}`);
         },

package/package.json

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