javi-forge 1.30.1 → 1.32.0

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

@@ -13,6 +13,14 @@
 export interface SecureIdentity {
     dev: number;
     ino: number;
+    /**
+     * Full-precision, platform-opaque identity token. POSIX leaves this undefined
+     * (identity is `dev`+`ino`). win32 sets `"<volumeSerialHex>:<fileIdHex>"` and
+     * compares ONLY on this — an absent/zero token is a hard refusal there, never
+     * a fallback to the truncated `dev`/`ino` (Decision 1b). Additive: the core
+     * passes it back to the adapter opaquely and never interprets it.
+     */
+    opaque?: string;
 }
 /** A held, no-follow directory handle plus its captured identity and path. */
 export interface SecureDirHandle {
@@ -27,12 +35,21 @@ export interface CapturedFile {
     identity: SecureIdentity;
     sha256: string;
 }
-export type SecureRefusal = "unsafe-parent-chain" | "unsupported-posix-acl" | "windows-secure-object-unavailable";
+export type SecureRefusal = "unsafe-parent-chain" | "unsupported-posix-acl" | "unsafe-windows-dacl" | "windows-secure-object-unavailable";
 export interface SecureResult<T> {
     ok: boolean;
     value?: T;
     refusal?: SecureRefusal;
     detail?: string;
+    /**
+     * Set ONLY by `openDirNoFollow` on a refusal, and ONLY for a GENUINE
+     * not-found (POSIX ENOENT / win32 `ERROR_FILE_NOT_FOUND`|`ERROR_PATH_NOT_FOUND`).
+     * Every other refusal — a reparse point/junction, EACCES, ENOTDIR, a transient
+     * error, or any non-open proof — leaves this absent/false so a managed
+     * container that is PRESENT-but-unopenable fails the transaction closed rather
+     * than being silently skipped (Round-6 / JDA6-001). Additive.
+     */
+    notFound?: boolean;
 }
 /**
  * The whole platform boundary. Every host-dependent operation is a method here;
@@ -74,6 +91,17 @@ export interface PlatformSecureFs {
     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>>;
+    /**
+     * Prove a directory the tool OWNS as a MANAGED CONTAINER (`.claude`,
+     * `.claude/hooks`): refuse ALL foreign add/delete-child rights — strictly more
+     * than the lenient ancestor `gate()`, which tolerates harmless add-child on
+     * high traversal ancestors (Round-4 / JDA-401). The core calls this ONLY on the
+     * dirs it constructs, expressing the managed-container role by WHICH method it
+     * invokes — no `process.platform` ever enters the engine. POSIX delegates to its
+     * existing strict ownership/mode check (group/other write IS add-child on a
+     * directory), so POSIX behavior is unchanged; the seam has teeth only on win32.
+     */
+    proveManagedContainer(dirPath: string): Promise<SecureResult<void>>;
 }
 /** Injected seams making the engine deterministic and host-independent. */
 export interface TransactionDeps {

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

@@ -68,6 +68,11 @@ export async function runTransaction(input) {
     const { secureFs, clock, nonce, projectDir } = input;
     const claudeDir = path.join(projectDir, ".claude");
     const hooksDir = path.join(claudeDir, "hooks");
+    // 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 heldByPath = new Map();
     const heldOrder = [];
     const createdDirs = [];
@@ -82,17 +87,44 @@ export async function runTransaction(input) {
         heldByPath.set(dirPath, handle);
         heldOrder.push(handle);
     }
-    async function ensureDir(parent, fullPath) {
+    /**
+     * Ensure a MANAGED CONTAINER (`.claude`/`.claude/hooks`): an existing one is
+     * ALWAYS gated + proveManagedContainer'd (→ heldOrder → re-proved pre-commit);
+     * an absent one is created Predicate-B strict ONLY when `createIfAbsent` (a
+     * child is written into it this run), else left alone. Four fail-closed
+     * branches (Round-4/5/6 / JDA-401 + JDB5-001 + JDA6-001):
+     *   (1) present + openable    → gate + proveManagedContainer, return handle
+     *   (2) notFound + create     → createDirExclusive + gate + proveManagedContainer
+     *   (3) notFound + !create    → return null (nothing to secure)
+     *   (4) any non-notFound !ok  → FAIL CLOSED explicitly (present-but-unopenable:
+     *                               junction/reparse/EACCES) regardless of create.
+     */
+    async function ensureManagedContainer(parent, fullPath, createIfAbsent) {
         const opened = await secureFs.openDirNoFollow(fullPath);
+        // (1) PRESENT + openable no-follow.
         if (opened.ok && opened.value) {
             await gate(fullPath, opened.value);
+            must(`container ${fullPath}`, await secureFs.proveManagedContainer(fullPath));
             return opened.value;
         }
+        // (4) ANY non-notFound refusal → fail the whole transaction closed,
+        // regardless of createIfAbsent. Refuse EXPLICITLY (JDB7-002): do not rely
+        // on a later must() throwing — propagate the refusal here so a
+        // present-but-unopenable managed container is never silently skipped.
+        if (!opened.notFound) {
+            throw new TxAbort(`container ${fullPath}`, opened.detail ?? opened.refusal ?? "present-but-unopenable");
+        }
+        // GENUINELY ABSENT (notFound === true) — the ONLY safe skip/create path.
+        // (3) absent + no child written this run → nothing to secure.
+        if (!createIfAbsent)
+            return null;
+        // (2) absent + a child IS written into it this run → create + prove.
         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);
+        must(`container ${fullPath}`, await secureFs.proveManagedContainer(fullPath));
         return created;
     }
     async function gateStillValid() {
@@ -104,6 +136,13 @@ export async function runTransaction(input) {
                 return false;
             if (!(await secureFs.proveNoExtendedAcl(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).
+            if (managedContainers.has(handle.path)) {
+                if (!(await secureFs.proveManagedContainer(handle.path)).ok) {
+                    return false;
+                }
+            }
         }
         return true;
     }
@@ -113,12 +152,27 @@ export async function runTransaction(input) {
             const handle = must(`openDir ${dirPath}`, await secureFs.openDirNoFollow(dirPath));
             await gate(dirPath, handle);
         }
-        // --- SEGMENT CREATION: .claude then .claude/hooks, one at a time ---
+        // --- SEGMENT CREATION + MANAGED-CONTAINER PROOF ---
+        // Prove the COMPLETE managed set {claudeDir, hooksDir} on every anyWrite run,
+        // decoupled from which child is written. A managed container that EXISTS is
+        // always gate()d + proveManagedContainer'd (→ heldOrder → re-proved
+        // 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);
-            const claudeHandle = await ensureDir(projectHandle, claudeDir);
-            if (needsWrite(input.asset))
-                await ensureDir(claudeHandle, hooksDir);
+            // .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");
+            }
+            // .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]) {
@@ -148,6 +202,12 @@ export async function runTransaction(input) {
             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));
+            // 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).
+            if (managedContainers.has(handle.path)) {
+                must(`recheck-container ${handle.path}`, await secureFs.proveManagedContainer(handle.path));
+            }
         }
         // --- COMMIT: asset first, settings second ---
         for (const entry of staged) {

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

@@ -0,0 +1,124 @@
+/**
+ * Windows `PlatformSecureFs` adapter for the SkillGuard transactional installer
+ * (Slice 3b). It is the win32 analog of the POSIX adapter: the ONLY place a
+ * Windows security decision is requested, delegated across an injectable
+ * `HelperTransport` seam to a bundled, digest-bound PowerShell helper (Phase 3)
+ * that owns the real OS handles and computes Predicate A/B verdicts.
+ *
+ * This module is host-independent and fully testable on Linux via a fake
+ * transport: `createWindowsSecureFs` builds framed requests and maps framed
+ * responses to `SecureResult`s; it enforces the TS-side invariants the design
+ * pins to the adapter (never the `.ps1`):
+ *   - C1 (Decision 1a): `mode` is a sentinel, NOT POSIX bits. `captureFile`
+ *     returns `WIN32_MODE_SENTINEL`; `applyExactMode` refuses any other mode.
+ *   - C4 (Decision 1b): identity is the full-precision `volumeSerial:FileId`
+ *     `opaque` token; an absent/zero/malformed token is a HARD REFUSAL, never a
+ *     fallback to the truncated `dev`/`ino` (display-only).
+ *   - JDA6-001 (Round-6): `openDir` maps ONLY `ERROR_FILE_NOT_FOUND` (2) /
+ *     `ERROR_PATH_NOT_FOUND` (3) to `notFound:true`; every other failure leaves
+ *     it absent so a present-but-unopenable container fails the transaction closed.
+ *   - JDA7-001 (Round-7): `openDir` asserts `FILE_ATTRIBUTE_DIRECTORY` and
+ *     refuses a non-directory with `notFound:false` (POSIX `O_DIRECTORY` parity).
+ * Every transport error (spawn failure, dead session, bad frame, timeout) maps
+ * to a fail-closed refusal — Windows is never a weaker tier than POSIX.
+ */
+import type { PlatformSecureFs, SecureRefusal } from "./secure-fs-transaction.js";
+/**
+ * The mode `captureFile` returns and `applyExactMode` demands on win32 (C1).
+ * NTFS has no POSIX bits; the value only has to survive the core's opaque
+ * round-trip, and `0o600` is the private-file mode the core already threads.
+ */
+export declare const WIN32_MODE_SENTINEL = 384;
+/** Reject any frame whose declared length exceeds this (hook assets are tiny). */
+export declare const HELPER_FRAME_LIMIT: number;
+/**
+ * R4-001 (Phase-4 hard gate): the per-request / handshake deadline. A timer is
+ * armed when a frame is written to the child (and while awaiting the startup
+ * handshake) and cleared the instant its response arrives. If it fires, the
+ * child is killed and every pending/subsequent op fails closed — a hung or
+ * non-responding `.ps1` can no longer hang the installer transaction forever.
+ */
+export declare const HELPER_OP_TIMEOUT_MS = 30000;
+export type HelperOp = "openDir" | "revalidate" | "proveOwner" | "proveDacl" | "proveContainer" | "createDir" | "capture" | "writeExcl" | "applyMode" | "rename" | "unlink" | "rmdir" | "releaseHandle";
+export interface HelperRequest {
+    op: HelperOp;
+    args: Record<string, unknown>;
+}
+export interface HelperResponse {
+    ok: boolean;
+    value?: unknown;
+    refusal?: SecureRefusal;
+    detail?: string;
+    /** win32 error code on an openDir failure; drives the notFound mapping. */
+    status?: number;
+}
+export interface HelperTransport {
+    /** Strictly serial: exactly one outstanding request at a time. */
+    request(req: HelperRequest): Promise<HelperResponse>;
+    /** Idempotent; kills the child. */
+    close(): Promise<void>;
+}
+/** Encode a JSON body as `[uint32 BE byteLength][UTF-8 JSON]`. */
+export declare function encodeFrame(body: unknown): Buffer;
+/**
+ * Decode as many complete frames as `buf` holds, returning them plus the
+ * unconsumed remainder. Throws on a declared length past `HELPER_FRAME_LIMIT`
+ * (the caller kills the session and fails closed).
+ */
+export declare function decodeFrames(buf: Buffer): {
+    frames: unknown[];
+    rest: Buffer;
+};
+export declare function createWindowsSecureFs(transport: HelperTransport): PlatformSecureFs;
+/**
+ * A transport that refuses EVERY op — used when the `.ps1` digest does not match
+ * the manifest binding (or the binding is absent). No PowerShell is spawned.
+ */
+export declare function refusingTransport(detail: string): HelperTransport;
+/** The subset of a spawned child process this session drives. */
+export interface Ps1Child {
+    stdin: {
+        write(chunk: Buffer): void;
+    };
+    stdout: {
+        on(event: "data", cb: (chunk: Buffer) => void): void;
+    };
+    stderr?: {
+        on(event: "data", cb: (chunk: Buffer) => void): void;
+    };
+    on(event: "exit" | "error", cb: (...args: unknown[]) => void): void;
+    kill(): void;
+    unref?(): void;
+}
+export interface WindowsHelperBinding {
+    name: string;
+    sha256: string;
+}
+export interface WindowsHelperManifest {
+    installerHelpers?: {
+        windowsSecureObject?: WindowsHelperBinding | null;
+    };
+}
+export interface Ps1SessionOptions {
+    assetsDir?: string;
+    manifest?: WindowsHelperManifest | null;
+    readFile?: (filePath: string) => Buffer;
+    spawn?: (cmd: string, args: string[]) => Ps1Child;
+    idleMs?: number;
+    opTimeoutMs?: number;
+    setTimer?: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    clearTimer?: (handle: ReturnType<typeof setTimeout>) => void;
+    registerExitHook?: (fn: () => void) => void;
+}
+/**
+ * The real transport: verify the on-disk `.ps1` sha256 against the manifest
+ * binding BEFORE spawning (tamper-evident, symmetric with the `.mjs`); on a
+ * mismatch/absent binding return `refusingTransport` and spawn nothing. On a
+ * match, spawn `powershell.exe` lazily on the first request, complete the
+ * handshake, and exchange strictly-serial length-prefixed frames. Any oversized
+ * frame, bad handshake, child exit, or session error kills the child and fails
+ * every pending/subsequent op closed. The idle watchdog only arms when ZERO
+ * directory handles are outstanding (W1) so it never kills a live transaction.
+ */
+export declare function createPs1Session(opts?: Ps1SessionOptions): HelperTransport;
+//# sourceMappingURL=secure-fs-windows.d.ts.map