@deftai/directive-core 0.99.0 → 0.100.0

package/dist/authz/actions.d.ts

@@ -39,6 +39,12 @@ export interface MintGrantInput {
     readonly now?: Date;
     /** When true, pin grant id into state.activeGrantIds. */
     readonly pinActive?: boolean;
+    /** SHA-256 hex of exact draft bytes for scope.decompose.apply.structural (#3239). */
+    readonly contentDigest?: string | null;
+    /** Project-relative parent artifact path (#3239). */
+    readonly parentPath?: string | null;
+    /** Project-relative draft/target path (#3239). */
+    readonly targetPath?: string | null;
 }
 export declare function mintHumanOriginGrant(input: MintGrantInput): HumanOriginGrant;
 export interface RevokeGrantInput {

package/dist/authz/actions.js

@@ -78,6 +78,9 @@ export function mintHumanOriginGrant(input) {
             storyIds: input.storyIds ?? [],
             issueIds: input.issueIds ?? [],
             cohortId: input.cohortId ?? null,
+            contentDigest: input.contentDigest ?? null,
+            parentPath: input.parentPath ?? null,
+            targetPath: input.targetPath ?? null,
         },
         semantics: {
             expiresAt: input.expiresAt ?? null,

package/dist/authz/classify.js

@@ -180,7 +180,7 @@ const POLICY_AUTHORITY_MUTATORS = new Set([
 const KILL_SWITCH_BASENAMES = [".deft-directive-disable", ".no-deft-directive"];
 /**
  * Downloaders / decoders / remote-copy tools that can plant files without shell
- * redirects (#3206 / #3213). Not in INDIRECT_WRITE_BINS: those feed hasWriteShape
+ * redirects (#3206 / #3213 / #3245). Not in INDIRECT_WRITE_BINS: those feed hasWriteShape
  * and would classify bare `curl $URL` as a store write via opaque-expansion heuristics.
  */
 const DOWNLOADER_DECODER_BINS = new Set([
@@ -192,11 +192,42 @@ const DOWNLOADER_DECODER_BINS = new Set([
     "scp",
     "aria2c",
     "certutil",
+    // #3245 residual after #3213: archive extractors + further alt downloaders.
+    "tar",
+    "bsdtar",
+    "unzip",
+    "7z",
+    "7za",
+    "7zr",
+    "rclone",
+    "axel",
+    "fetch",
+    "socat",
+    "lftp",
+]);
+/**
+ * Archive extractors / alt writers that can plant via pathish operands without
+ * shell redirects (#3245). Used for pathish authz/kill scans (prefer deny) and
+ * write-shape residual under UAT — not bare curl-class URL fetches.
+ */
+const ARCHIVE_ALT_WRITE_BINS = new Set([
+    "tar",
+    "bsdtar",
+    "unzip",
+    "7z",
+    "7za",
+    "7zr",
+    "rclone",
+    "axel",
+    "fetch",
+    "socat",
+    "lftp",
 ]);
 /**
  * File destination flags for downloaders/decoders (#3206).
  * normalizeToken lowercases, so wget `-O` and curl `-o` share `-o`.
  * scp: `-o` is an SSH option — excluded in isDownloaderDestFlag.
+ * 7z: `-oDIR` is attached-only (no separate value token).
  */
 const DOWNLOADER_FILE_DEST_FLAGS = new Set([
     "-o",
@@ -209,11 +240,28 @@ const DOWNLOADER_FILE_DEST_FLAGS = new Set([
 const CURL_DIR_DEST_FLAGS = new Set(["--output-dir"]);
 const WGET_DIR_DEST_FLAGS = new Set(["-p", "--directory-prefix"]);
 const ARIA2C_DIR_DEST_FLAGS = new Set(["-d", "--dir"]);
+/**
+ * tar/bsdtar extract directory (#3245).
+ * Case-sensitive: POSIX tar uses capital `-C` for chdir; lower `-c` is create and is NOT dest.
+ */
+const TAR_DIR_DEST_FLAGS_EXACT = new Set(["-C"]);
+const TAR_DIR_DEST_FLAGS_LOWER = new Set(["--directory"]);
+/** unzip extract directory (#3245). */
+const UNZIP_DIR_DEST_FLAGS = new Set(["-d"]);
 /**
  * Symlink / hard-link plant bins (#3213). Absent from prior killWriteBins →
  * `ln -sf … .deft-directive-disable` classified empty → UAT fail-open.
  */
 const SYMLINK_PLANT_BINS = new Set(["ln", "link", "mklink"]);
+/** socat address prefixes that open a write target (#3245). */
+const SOCAT_WRITE_ADDR_PREFIXES = [
+    "open:",
+    "create:",
+    "creat:",
+    "append:",
+    "owronly:",
+    "oappend:",
+];
 /** Final path segment of a token (path-qualified bins / .exe). */
 function binBareName(token) {
     const pathish = token.replace(/['"]/g, "").toLowerCase().replace(/\\/g, "/");
@@ -227,10 +275,19 @@ function isDownloaderDecoderBin(token) {
         return false;
     return DOWNLOADER_DECODER_BINS.has(binBareName(token));
 }
-function isDownloaderDestFlag(flag, bin) {
+/**
+ * True when `flag` (normalized lower) or `rawFlag` (original token) is a dest flag for `bin`.
+ * tar `-C` must use raw case: lowercased `-c` is create-archive, not chdir (#3245).
+ * 7z uses attached `-oDIR` only — separate `-o PATH` is not a 7z dest form (handled elsewhere).
+ */
+function isDownloaderDestFlag(flag, bin, rawFlag) {
     // scp: `-o` is OpenSSH option (ProxyCommand, …), not a file dest flag.
     if (bin === "scp")
         return false;
+    // 7z family: only attached `-oDIR` (parsed in attached-short branch), not separate `-o PATH`.
+    if (bin === "7z" || bin === "7za" || bin === "7zr") {
+        return false;
+    }
     if (DOWNLOADER_FILE_DEST_FLAGS.has(flag))
         return true;
     if (bin === "curl" && CURL_DIR_DEST_FLAGS.has(flag))
@@ -239,6 +296,18 @@ function isDownloaderDestFlag(flag, bin) {
         return true;
     if (bin === "aria2c" && ARIA2C_DIR_DEST_FLAGS.has(flag))
         return true;
+    if (bin === "tar" || bin === "bsdtar") {
+        if (rawFlag !== undefined && TAR_DIR_DEST_FLAGS_EXACT.has(rawFlag))
+            return true;
+        if (TAR_DIR_DEST_FLAGS_LOWER.has(flag))
+            return true;
+        // Exact match on raw when normalize collapsed case for long flags only.
+        if (rawFlag !== undefined && TAR_DIR_DEST_FLAGS_LOWER.has(normalizeToken(rawFlag)))
+            return true;
+        return false;
+    }
+    if (bin === "unzip" && UNZIP_DIR_DEST_FLAGS.has(flag))
+        return true;
     return false;
 }
 /**
@@ -292,7 +361,8 @@ function firstUnquotedShellOpIndex(raw) {
 /**
  * Destinations from curl/wget/xxd/openssl/scp/aria2c/certutil via -o/--output/-O/-out/
  * --output-dir/-P/-d/--dir (separate, =value, or attached short form), xxd -r path-like
- * write positionals (#3206), and positional dests for scp/certutil (#3213).
+ * write positionals (#3206), positional dests for scp/certutil (#3213), and #3245 residual
+ * archive/alt bins (tar -C, unzip -d, 7z -oDIR, rclone positionals, socat OPEN:, axel/fetch -o).
  * openssl uses flags only (no positional dests — avoids treating -in paths as writes).
  * Segment stops at shell operators so compound `scp …authz…; echo` cannot overwrite dests.
  * O(n) token walk — no nested-quantifier regex on untrusted input.
@@ -309,13 +379,24 @@ function downloaderDecoderDestinations(tokens) {
         i++;
         // xxd reverse mode writes; without -r, path positionals are dump inputs (read).
         let xxdReverse = false;
-        // scp / certutil: collect pathish operands in this segment (#3213).
+        // scp / certutil / rclone / archive extractors: collect pathish operands in this segment.
         // Fail-closed under UAT: any pathish mentioning protected store/kill paths is a dest
         // candidate (scp source-or-dest of `.deft/authz` is treated as settings — prefer deny
         // over source/dest thrash). Last pathish remains the ordinary write dest.
         // Segment breaks (`;`/`\n`/glued ops) prevent following-command overwrite.
         let lastPositionalPath = null;
         const protectedPathish = [];
+        const collectsProtectedPositionals = bin === "scp" ||
+            bin === "certutil" ||
+            bin === "rclone" ||
+            bin === "tar" ||
+            bin === "bsdtar" ||
+            bin === "unzip" ||
+            bin === "7z" ||
+            bin === "7za" ||
+            bin === "7zr" ||
+            bin === "socat" ||
+            bin === "lftp";
         while (i < tokens.length) {
             const raw = tokens[i];
             const n = normalizeToken(raw);
@@ -361,10 +442,12 @@ function downloaderDecoderDestinations(tokens) {
                 continue;
             }
             // --flag=value (and rare -out=value); scp -oOption=Value attached form also lands here.
+            // tar --directory=PATH also lands here.
             if (n.includes("=") && (n.startsWith("-") || n.startsWith("--"))) {
                 const eq = raw.indexOf("=");
-                const flag = normalizeToken(raw.slice(0, eq));
-                if (isDownloaderDestFlag(flag, bin)) {
+                const flagRaw = raw.slice(0, eq);
+                const flag = normalizeToken(flagRaw);
+                if (isDownloaderDestFlag(flag, bin, flagRaw)) {
                     dests.push(pathishToken(raw.slice(eq + 1)));
                 }
                 // scp attached -oProxyCommand=… is not a file dest — skip without recording.
@@ -373,6 +456,7 @@ function downloaderDecoderDestinations(tokens) {
             }
             // Attached short: -oPATH / -OPATH (after lowercasing both are -opath…)
             // Skip for scp (OpenSSH -oOption=Value attached forms are not file dests).
+            // 7z requires attached -oDIR (#3245).
             if (bin !== "scp" && n.startsWith("-") && !n.startsWith("--") && n.length > 2) {
                 if (n.startsWith("-out") && n.length > 4 && !n.startsWith("-output")) {
                     dests.push(pathishToken(raw.slice(4)));
@@ -396,9 +480,21 @@ function downloaderDecoderDestinations(tokens) {
                     i++;
                     continue;
                 }
+                // unzip attached -dDIR (#3245)
+                if (bin === "unzip" && n.startsWith("-d") && n.length > 2) {
+                    dests.push(pathishToken(raw.slice(2)));
+                    i++;
+                    continue;
+                }
+                // tar attached -CDIR (rare; capital C required)
+                if ((bin === "tar" || bin === "bsdtar") && raw.startsWith("-C") && raw.length > 2) {
+                    dests.push(pathishToken(raw.slice(2)));
+                    i++;
+                    continue;
+                }
             }
-            // Separate value: -o PATH / --output PATH / -out PATH / --output-dir / -P / -d
-            if (isDownloaderDestFlag(n, bin)) {
+            // Separate value: -o PATH / --output PATH / -out PATH / --output-dir / -P / -d / -C DIR
+            if (isDownloaderDestFlag(n, bin, raw)) {
                 const next = tokens[i + 1];
                 if (next !== undefined && !String(next).startsWith("-") && !isShellSegmentBreak(next)) {
                     dests.push(pathishToken(next));
@@ -418,16 +514,32 @@ function downloaderDecoderDestinations(tokens) {
                     dests.push(p);
                 }
             }
-            // scp / certutil: pathish operands (quote-aware glued-op cut).
-            // certutil under UAT: any `.deft/authz` / kill-switch pathish is fail-closed settings
-            // (read vs write thrash deferred — prefer deny over dest-parser perfection; #3213).
-            if ((bin === "scp" || bin === "certutil") && !n.startsWith("-")) {
+            // socat write address forms: OPEN:path, CREATE:path, APPEND:path (#3245).
+            if (bin === "socat" && !n.startsWith("-")) {
+                const p = pathishToken(raw);
+                for (const prefix of SOCAT_WRITE_ADDR_PREFIXES) {
+                    if (p.startsWith(prefix) && p.length > prefix.length) {
+                        const dest = p.slice(prefix.length);
+                        dests.push(dest);
+                        if (dest.includes(".deft/authz") ||
+                            dest.includes(".deft-directive-disable") ||
+                            dest.includes(".no-deft-directive")) {
+                            protectedPathish.push(dest);
+                        }
+                        break;
+                    }
+                }
+            }
+            // scp / certutil / rclone / archive extractors: pathish operands (quote-aware glued-op cut).
+            // Under UAT: any `.deft/authz` / kill-switch pathish is fail-closed settings
+            // (read vs write thrash deferred — prefer deny over dest-parser perfection; #3213 / #3245).
+            if (collectsProtectedPositionals && !n.startsWith("-")) {
                 const cut = firstUnquotedShellOpIndex(raw);
                 const cleaned = cut >= 0 ? raw.slice(0, cut) : raw;
                 const p = pathishToken(cleaned);
                 if (p.length > 0) {
                     lastPositionalPath = p;
-                    // Fail-closed: protected store/kill basenames anywhere in scp/certutil pathish.
+                    // Fail-closed: protected store/kill basenames anywhere in pathish.
                     if (p.includes(".deft/authz") ||
                         p.includes(".deft-directive-disable") ||
                         p.includes(".no-deft-directive")) {
@@ -589,10 +701,12 @@ function hasKillSwitchShellWrite(command, tokens) {
         if (pathishMentionsKillSwitch(dest))
             return true;
     }
-    // Write/destructive + symlink plant bins with a kill-switch path argument (#3213: ln/link/mklink).
+    // Write/destructive + symlink plant + archive/alt-write bins with a kill-switch path
+    // argument (#3213 ln/link/mklink; #3245 tar/axel/rclone/socat residual).
     const killWriteBins = new Set([
         ...INDIRECT_WRITE_BINS,
         ...SYMLINK_PLANT_BINS,
+        ...ARCHIVE_ALT_WRITE_BINS,
         "touch",
         "new-item",
         "ni",
@@ -606,8 +720,15 @@ function hasKillSwitchShellWrite(command, tokens) {
         if (!killWriteBins.has(binTok) && !killWriteBins.has(bare))
             continue;
         for (let tj = ti + 1; tj < tokens.length; tj++) {
-            if (pathishMentionsKillSwitch(pathishToken(tokens[tj])))
+            const p = pathishToken(tokens[tj]);
+            if (pathishMentionsKillSwitch(p))
                 return true;
+            // socat OPEN:.deft-directive-disable — path after address prefix (#3245).
+            for (const prefix of SOCAT_WRITE_ADDR_PREFIXES) {
+                if (p.startsWith(prefix) && pathishMentionsKillSwitch(p.slice(prefix.length))) {
+                    return true;
+                }
+            }
         }
     }
     // Bare `touch .deft-directive-disable` / `ln -sf x .deft-directive-disable` — path later.
@@ -833,24 +954,32 @@ function hasAuthzDirShellWrite(command, tokens) {
                 return true;
         }
     }
-    // Write/destructive + symlink plant bins with an authz path argument (pathish =
-    // quote-strip resistant). Always run — do not gate on contiguous `.deft/authz`
-    // in the raw command (#3213). SYMLINK_PLANT_BINS: `ln -s forged .deft/authz/grants/x`
-    // must not fail-open as unclassifiable (SLizard residual).
+    // Write/destructive + symlink plant + archive/alt-write bins with an authz path argument
+    // (pathish = quote-strip resistant). Always run — do not gate on contiguous `.deft/authz`
+    // in the raw command (#3213 / #3245). SYMLINK_PLANT_BINS: `ln -s forged .deft/authz/grants/x`
+    // must not fail-open as unclassifiable (SLizard residual). ARCHIVE_ALT_WRITE_BINS: tar/rclone
+    // residual pathish without dest-flag perfection thrash.
     for (let ti = 0; ti < tokens.length; ti++) {
         const bare = binBareName(tokens[ti]);
         const n = normalizeToken(tokens[ti]);
         if (!INDIRECT_WRITE_BINS.has(n) &&
             !INDIRECT_WRITE_BINS.has(bare) &&
-            !SYMLINK_PLANT_BINS.has(bare)) {
+            !SYMLINK_PLANT_BINS.has(bare) &&
+            !ARCHIVE_ALT_WRITE_BINS.has(bare)) {
             continue;
         }
         for (let tj = ti + 1; tj < tokens.length; tj++) {
-            if (pathishIsAuthzDir(pathishToken(tokens[tj])))
+            const p = pathishToken(tokens[tj]);
+            if (pathishIsAuthzDir(p))
                 return true;
+            for (const prefix of SOCAT_WRITE_ADDR_PREFIXES) {
+                if (p.startsWith(prefix) && pathishIsAuthzDir(p.slice(prefix.length))) {
+                    return true;
+                }
+            }
         }
     }
-    // Downloader/decoder destinations under .deft/authz (#3206 / #3213 scp/aria2c/certutil).
+    // Downloader/decoder destinations under .deft/authz (#3206 / #3213 / #3245 archive+alt).
     for (const dest of downloaderDecoderDestinations(tokens)) {
         if (pathishIsAuthzDir(dest))
             return true;
@@ -932,7 +1061,12 @@ function hasWriteShape(command, tokens) {
     if (command.includes(">"))
         return true;
     for (const t of tokens) {
-        if (INDIRECT_WRITE_BINS.has(normalizeToken(t)))
+        const bare = binBareName(t);
+        if (INDIRECT_WRITE_BINS.has(normalizeToken(t)) || INDIRECT_WRITE_BINS.has(bare))
+            return true;
+        // #3245: archive extractors / alt downloaders are write-shaped (defense-in-depth for
+        // unclassifiable plant paths under UAT — not bare curl $URL which stays non-write-shaped).
+        if (ARCHIVE_ALT_WRITE_BINS.has(bare))
             return true;
     }
     return false;

package/dist/authz/decompose-apply.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Human-origin structural apply gate for scope:decompose (#3239 / epic #3237 Q2).
+ *
+ * Apply requires a human-origin grant bound to:
+ *   project root identity (worktree and/or repo), parent path, draft/target path,
+ *   SHA-256 of exact draft bytes, and op scope.decompose.apply.structural.
+ *
+ * --check stays ungated (caller responsibility). Missing / expired / mismatched /
+ * agent-origin grants fail closed before any child story writes.
+ */
+import { type AuthzDecisionCode, type HumanOriginGrant } from "./types.js";
+export type DecomposeApplyDecisionCode = AuthzDecisionCode | "authz-grant-digest-mismatch" | "authz-grant-parent-mismatch" | "authz-grant-target-mismatch" | "authz-grant-project-mismatch" | "authz-grant-binding-incomplete";
+export interface DecomposeApplyDecision {
+    readonly allowed: boolean;
+    readonly code: DecomposeApplyDecisionCode;
+    readonly reason: string;
+    readonly humanApprovalRef: string | null;
+    readonly draftDigest: string;
+}
+export interface EvaluateDecomposeStructuralApplyInput {
+    readonly projectRoot: string;
+    /** Absolute or project-relative parent artifact path. */
+    readonly parentPath: string;
+    /** Absolute or project-relative draft path whose bytes were digested. */
+    readonly draftPath: string;
+    /** SHA-256 hex of the exact draft file bytes about to be applied. */
+    readonly draftDigest: string;
+    readonly grants?: readonly HumanOriginGrant[];
+    /** Optional GitHub-style repo identity (owner/name); compared when grant pins repo. */
+    readonly repo?: string | null;
+    readonly now?: Date;
+}
+/** SHA-256 hex of a buffer or utf8 string. */
+export declare function sha256Hex(data: Buffer | string): string;
+/** SHA-256 hex of file bytes at path (exact on-disk digest). */
+export declare function sha256FileHex(path: string): string;
+/**
+ * Normalize a path to project-relative POSIX form for grant binding compare.
+ * Returns null when the path escapes the project root.
+ */
+export declare function toProjectRelativePosix(projectRoot: string, path: string): string | null;
+/**
+ * Evaluate whether a human-origin grant covers structural decompose apply for
+ * the exact draft digest + parent + target + project identity.
+ */
+export declare function evaluateDecomposeStructuralApply(input: EvaluateDecomposeStructuralApplyInput): DecomposeApplyDecision;
+export interface MintDecomposeStructuralApplyGrantInput {
+    readonly projectRoot: string;
+    readonly parentPath: string;
+    readonly draftPath: string;
+    /** When omitted, digest is computed from draftPath on-disk bytes. */
+    readonly contentDigest?: string;
+    readonly actor?: string;
+    readonly repo?: string | null;
+    readonly expiresAt?: string | null;
+    readonly singleUse?: boolean;
+    readonly grantId?: string;
+    readonly now?: Date;
+    readonly pinActive?: boolean;
+    readonly eventRef?: string | null;
+}
+/**
+ * Operator mint helper: human-origin grant bound to exact draft bytes + paths.
+ * Sole mint path remains mintHumanOriginGrant (operator-cli origin).
+ */
+export declare function mintDecomposeStructuralApplyGrant(input: MintDecomposeStructuralApplyGrantInput): HumanOriginGrant;
+//# sourceMappingURL=decompose-apply.d.ts.map