@dailephd/my-dev-kit-lab 0.9.3 → 0.9.5

package/dist/src/securityValidation/attackScenarios/boundedSourceScan.js

@@ -1,14 +1,13 @@
 import fs from "node:fs";
-import { collectFilesForGlobs } from "../../core/fileGlobs.js";
+import path from "node:path";
 // ---------------------------------------------------------------------------
 // v0.2.2 Batch 4 — shared bounded, deterministic source-file scan helper.
 //
 // Reused by secretLeakageScenario and networkAssumptionScenario. Both need
 // "read a bounded, deterministic set of source-ish files, skip large/binary
-// content" and nothing more — collectFilesForGlobs() already provides
-// deterministic ordering and standard exclusions (node_modules, dist, build,
-// coverage, .git, lab-output, .my-dev-kit); this layer adds a size cap and a
-// small file-content allowlist filter for scenario-specific exclusions.
+// content". Discovery here must refuse links BEFORE traversal or content reads;
+// the general fileGlobs walker follows a linked glob base. Preserve its standard
+// directory/temp exclusions, with a size cap and synthetic-fixture exclusion.
 // ---------------------------------------------------------------------------
 // Default bounded glob set: project manifests/config plus first-party source
 // and scripts. Deliberately excludes tests/, benchmarks/, examples/ — those
@@ -37,28 +36,108 @@ const MAX_SCANNABLE_FILE_BYTES = 1_000_000;
 // Built via fromCharCode rather than a "\0" string escape to avoid any
 // literal control byte ending up in this source file.
 const NUL_CHAR = String.fromCharCode(0);
+const EXCLUDED_SOURCE_DIRECTORIES = new Set([
+    "node_modules", "dist", "build", "coverage", ".git", "lab-output",
+    ".my-dev-kit", ".my-dev-kit-v1", ".my-dev-kit-lab", "__pycache__"
+]);
+const samePhysicalPath = (a, b) => process.platform === "win32"
+    ? a.toLowerCase() === b.toLowerCase() : a === b;
 // Returns file contents for the bounded glob set, skipping known synthetic
 // fixtures, oversized files, and anything unreadable as UTF-8 text (treated
 // as binary and skipped, not an error). Stable, deterministic order.
-export function collectBoundedSourceFiles(targetRoot, globs = DEFAULT_SOURCE_SCAN_GLOBS) {
-    // collectFilesForGlobs() throws for the *entire* call if any single glob's
-    // base path doesn't exist (e.g. no .env file, no tsconfig.*.json match) —
-    // resolve each glob independently so one missing/inapplicable glob doesn't
-    // silently zero out results for all the others.
-    const candidateMap = new Map();
-    for (const glob of globs) {
-        let matches;
-        try {
-            matches = collectFilesForGlobs(targetRoot, [glob]);
+export function collectBoundedSourceFiles(targetRoot, globs = DEFAULT_SOURCE_SCAN_GLOBS, provenanceIssues = [], reviewedPaths = []) {
+    const root = path.resolve(targetRoot);
+    const issueMap = new Map();
+    const inspectedPaths = new Map();
+    const relative = (file) => path.relative(root, file).replace(/\\/g, "/") || ".";
+    const refuse = (file, reason) => {
+        issueMap.set(relative(file), reason);
+        return undefined;
+    };
+    // lstat every component, including the scan root, before realpath or reads.
+    // This rejects junctions/symlinks, physical aliases and multiply-linked files.
+    // Rechecking before a read narrows races; it is not a race-free OS sandbox.
+    function inspect(file) {
+        const rel = path.relative(root, file);
+        if (rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+            return refuse(root, "path-outside-scan-root");
         }
-        catch {
-            // This glob's base path doesn't exist for this target — a legitimate
-            // "nothing to scan for this pattern" outcome, not an error.
-            continue;
+        let current = root;
+        let stat;
+        for (const segment of ["", ...rel.split(path.sep).filter(Boolean)]) {
+            if (segment)
+                current = path.join(current, segment);
+            try {
+                stat = fs.lstatSync(current);
+                if (stat.isSymbolicLink())
+                    return refuse(current, "symlink-or-junction");
+                if (!stat.isDirectory() && !stat.isFile())
+                    return refuse(current, "non-regular-path");
+                if (stat.isFile() && stat.nlink > 1)
+                    return refuse(current, "multiply-linked-source");
+                const physical = fs.realpathSync.native(current);
+                if (!samePhysicalPath(physical, current)) {
+                    return refuse(current, "physical-path-alias");
+                }
+                inspectedPaths.set(current, physical);
+            }
+            catch (error) {
+                // Missing optional files are normal for generic external targets.
+                if (error.code !== "ENOENT")
+                    refuse(current, "unreadable-path");
+                return undefined;
+            }
         }
-        for (const m of matches) {
-            candidateMap.set(m.relativePath, m.absolutePath);
+        return stat;
+    }
+    // Absence is normal in unrelated targets; an existing reviewed path that is
+    // not a direct regular file must not disappear into an empty directory scan.
+    for (const reviewed of reviewedPaths) {
+        const file = path.resolve(root, reviewed);
+        const stat = inspect(file);
+        if (stat && !stat.isFile())
+            refuse(file, "non-regular-reviewed-source");
+    }
+    const candidateMap = new Map();
+    for (const glob of globs) {
+        const pattern = glob.replace(/\\/g, "/");
+        const wildcard = pattern.search(/[*?]/);
+        const prefix = wildcard < 0 ? pattern : pattern.slice(0, wildcard);
+        const base = wildcard < 0 ? prefix : prefix.slice(0, prefix.lastIndexOf("/") + 1) || ".";
+        const recursive = pattern.slice(base === "." ? 0 : base.length).includes("/");
+        function visit(file) {
+            const stat = inspect(file);
+            if (!stat)
+                return;
+            const rel = relative(file);
+            if (stat.isDirectory()) {
+                let entries;
+                try {
+                    entries = fs.readdirSync(file).sort();
+                }
+                catch {
+                    refuse(file, "unreadable-directory");
+                    return;
+                }
+                for (const name of entries) {
+                    const child = path.join(file, name);
+                    // Root-level wildcard globs must not traverse unrelated directories.
+                    if (recursive || path.matchesGlob(relative(child), pattern)) {
+                        // Exclusions name generated directories, never ordinary files.
+                        // Inspect first so a link with an excluded name stays reportable.
+                        if (EXCLUDED_SOURCE_DIRECTORIES.has(name) && inspect(child)?.isDirectory())
+                            continue;
+                        visit(child);
+                    }
+                }
+            }
+            else if (path.matchesGlob(rel, pattern) && !/\.(?:tmp|temp|log|pyc)$|~$/.test(rel)) {
+                // Windows identity comparisons may ignore case for containment, but
+                // reviewed trust must use observed spelling, including the glob base.
+                candidateMap.set(relative(inspectedPaths.get(file)), file);
+            }
         }
+        visit(path.resolve(root, base));
     }
     const candidates = [...candidateMap.entries()]
         .sort(([a], [b]) => a.localeCompare(b))
@@ -70,23 +149,31 @@ export function collectBoundedSourceFiles(targetRoot, globs = DEFAULT_SOURCE_SCA
             continue;
         let stat;
         try {
-            stat = fs.statSync(candidate.absolutePath);
+            stat = inspect(candidate.absolutePath);
         }
         catch {
             continue;
         }
-        if (!stat.isFile() || stat.size > MAX_SCANNABLE_FILE_BYTES)
+        if (!stat?.isFile())
             continue;
+        if (stat.size > MAX_SCANNABLE_FILE_BYTES) {
+            refuse(candidate.absolutePath, "oversized-source");
+            continue;
+        }
         try {
             const content = fs.readFileSync(candidate.absolutePath, "utf8");
-            if (content.indexOf(NUL_CHAR) !== -1)
+            if (content.indexOf(NUL_CHAR) !== -1) {
+                refuse(candidate.absolutePath, "binary-source");
                 continue;
+            }
             files.push({ relativePath: normalizedRel, absolutePath: candidate.absolutePath, content });
         }
         catch {
-            continue;
+            refuse(candidate.absolutePath, "unreadable-source");
         }
     }
+    provenanceIssues.push(...[...issueMap.entries()].sort(([a], [b]) => a.localeCompare(b))
+        .map(([relativePath, reason]) => ({ relativePath, reason })));
     return files;
 }
 // Returns the 1-based line number containing `index` within `content`.

package/dist/src/securityValidation/attackScenarios/scenarios/networkAssumptionScenario.js

@@ -1,5 +1,6 @@
 import { makeEvidence } from "../exploitEvidence.js";
 import { collectBoundedSourceFiles, lineNumberAt } from "../boundedSourceScan.js";
+import { createHash } from "node:crypto";
 // ---------------------------------------------------------------------------
 // v0.2.2 Batch 4 — network / local-first assumption scenario.
 //
@@ -31,6 +32,21 @@ const KNOWN_NETWORK_INTENTIONAL_PREFIXES = [
 function isKnownIntentionalPath(relativePath) {
     return KNOWN_NETWORK_INTENTIONAL_PREFIXES.some((p) => relativePath.startsWith(p));
 }
+// Reviewed source identities, not file exemptions. A changed site, extra match,
+// missing dependency, or changed caller precondition invalidates recognition.
+const REVIEWED_LOCAL_HTTP_SITES = [
+    { file: "src/runtime/managedProcess.ts", symbol: "waitForReadiness", sha256: "978dacaf401cac3c3f6fdc96ca92163b766b14bead7f3a7c49b1ca28d8ac3900", dependencies: {} },
+    { file: "src/tutorial/tutorialAssertions.ts", symbol: "http-json-equals / resolveAssertionRequestUrl", sha256: "eba83bd94342d108e1ecc8491e09e584360095823332dffe2df28e49ecf011b3", dependencies: {
+            "src/tutorial/runTutorial.ts": "ded69670f0aec6ad31e714e77c6a8e769abcb28fcdc68b81584fd582e593e298",
+            "src/tutorial/tutorialSession.ts": "08e0317600754a033ebf8022e984e941c60786bbc3c9baafc3fa7be3ccdd90ce",
+            "src/tutorial/targetContractValidation.ts": "da6c51c36827bf3d9b7375cdd71e488d35732f389f989a7dbc462b21063a96a6",
+            "src/tutorial/loadTutorialContracts.ts": "10e17f851febf783076d2d7ad5de70f6e950308819ec30edaecf749ba4b11c7a",
+            "src/tutorial/validationPrimitives.ts": "e49258d33d0a88d051fa783d8e2236827940ed5895fd1ce844b9f58b4ec08cb1"
+        } }
+];
+// Normalize only checkout EOLs for these exact reviewed-content comparisons.
+// The tutorialSession identity is the verified LF form of the reviewed CRLF text.
+const sourceDigest = (content) => createHash("sha256").update(content.replace(/\r\n/g, "\n"), "utf8").digest("hex");
 function scanFileForNetworkApis(relativePath, content) {
     const matches = [];
     const intentional = isKnownIntentionalPath(relativePath);
@@ -58,7 +74,12 @@ export const NETWORK_ASSUMPTION_SCENARIO = {
     expectedSafeBehavior: "No obvious unexpected network API usage is found in the bounded local-first source paths inspected.",
     evidenceRequirements: ["observation"],
     run: async (ctx) => {
-        const files = collectBoundedSourceFiles(ctx.target.targetRoot);
+        const provenanceIssues = [];
+        const reviewedPaths = new Set(REVIEWED_LOCAL_HTTP_SITES.flatMap(site => [site.file, ...Object.keys(site.dependencies)]));
+        const files = collectBoundedSourceFiles(ctx.target.targetRoot, undefined, provenanceIssues, [...reviewedPaths]);
+        // Size/binary exclusions remain bounded-scan policy for ordinary sources;
+        // they can never establish the identity of a reviewed site or precondition.
+        const refusals = provenanceIssues.filter(issue => !["oversized-source", "binary-source"].includes(issue.reason) || reviewedPaths.has(issue.relativePath));
         const isolationCaveat = makeEvidence({
             kind: "observation",
             source: "scope statement",
@@ -66,7 +87,7 @@ export const NETWORK_ASSUMPTION_SCENARIO = {
             expectedBehavior: "This is a bounded static check of local-first source paths only. It does not prove runtime network isolation of subprocess-invoked tools (npm, CodeQL, Semgrep, OSV-Scanner) or any other process spawned during validation.",
             observedBehavior: "Static-source-only claim; no runtime network instrumentation was performed.",
         });
-        if (files.length === 0) {
+        if (files.length === 0 && refusals.length === 0) {
             return {
                 status: "passed",
                 confidence: "low",
@@ -82,10 +103,33 @@ export const NETWORK_ASSUMPTION_SCENARIO = {
                 ],
             };
         }
-        const allMatches = [];
+        const allMatches = refusals.map(issue => ({
+            id: "untrusted-source-provenance", file: issue.relativePath, line: 1,
+            intentional: false, provenanceReason: issue.reason
+        }));
         for (const file of files) {
             allMatches.push(...scanFileForNetworkApis(file.relativePath, file.content));
         }
+        const byPath = new Map(files.map(file => [file.relativePath, file.content]));
+        for (const site of REVIEWED_LOCAL_HTTP_SITES) {
+            const content = byPath.get(site.file);
+            if (content === undefined)
+                continue;
+            const siteMatches = allMatches.filter(match => match.file === site.file);
+            const recognized = sourceDigest(content) === site.sha256 &&
+                siteMatches.length === 1 && siteMatches[0]?.id === "fetch-call" &&
+                Object.entries(site.dependencies).every(([file, sha256]) => {
+                    const dependency = byPath.get(file);
+                    return dependency !== undefined && sourceDigest(dependency) === sha256;
+                });
+            if (recognized) {
+                siteMatches[0].intentional = true;
+                siteMatches[0].reviewedSite = `${site.symbol}; LF-normalized source SHA-256 ${site.sha256}`;
+            }
+            else if (siteMatches.length === 0) {
+                allMatches.push({ id: "reviewed-local-http-source-mismatch", file: site.file, line: 1, intentional: false });
+            }
+        }
         allMatches.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
         const unexpected = allMatches.filter((m) => !m.intentional);
         const intentional = allMatches.filter((m) => m.intentional);
@@ -103,16 +147,24 @@ export const NETWORK_ASSUMPTION_SCENARIO = {
                 source: "known network-using validation commands",
                 confidence: "high",
                 expectedBehavior: "npm audit / npm outdated (deps check) may contact the npm registry; OSV-Scanner may contact the OSV API; Semgrep's npx fallback may contact the npm registry. These are expected when those check groups are selected via --checks and are not local-first source violations.",
-                observedBehavior: `${intentional.length} match(es) found under known network-using paths (${KNOWN_NETWORK_INTENTIONAL_PREFIXES.join(", ")}).`,
+                observedBehavior: `${intentional.filter(m => !m.reviewedSite).length} match(es) found under known network-using paths (${KNOWN_NETWORK_INTENTIONAL_PREFIXES.join(", ")}).`,
             }),
+            ...intentional.filter(m => m.reviewedSite).map(m => makeEvidence({
+                kind: "observation", source: "known-intentional local HTTP use", filePath: m.file, line: m.line,
+                confidence: "medium",
+                expectedBehavior: "Exactly one reviewed fetch-call with unchanged local HTTP guards and caller preconditions. Bounded static findings do not prove full runtime network isolation.",
+                observedBehavior: `Recognized '${m.id}' in ${m.file}:${m.line} (${m.reviewedSite}).`
+            })),
             ...unexpected.slice(0, 20).map((m) => makeEvidence({
                 kind: "observation",
-                source: `pattern '${m.id}'`,
+                source: m.provenanceReason ? "source provenance refusal" : `pattern '${m.id}'`,
                 filePath: m.file,
                 line: m.line,
                 confidence: "medium",
                 expectedBehavior: "No unexpected direct network API usage in local-first source paths.",
-                observedBehavior: `Detected '${m.id}' usage in ${m.file}:${m.line}.`,
+                observedBehavior: m.provenanceReason
+                    ? `Untrusted source path ${m.file}: ${m.provenanceReason}; source content was not accepted.`
+                    : `Detected '${m.id}' usage in ${m.file}:${m.line}.`,
             })),
         ];
         if (unexpected.length > 0) {

package/dist/src/securityValidation/cliAdversarial/pathBoundaryChecks.js

@@ -2,7 +2,8 @@ import { spawn } from "node:child_process";
 import path from "node:path";
 import { buildCliCommand } from "./adversarialCliConfig.js";
 import { makeFinding, runAdversarialCheck, skippedCheck } from "./runAdversarialCheck.js";
-import { createTempWorkspace, diffSnapshots, snapshotDir } from "./tempWorkspace.js";
+import { createTempWorkspace, diffSnapshots, snapshotDir, snapshotTreeStrict } from "./tempWorkspace.js";
+import { classifyTraversalValue, proveContainment } from "./traversalContainment.js";
 // ---------------------------------------------------------------------------
 // Path traversal checks
 // ---------------------------------------------------------------------------
@@ -58,27 +59,68 @@ export async function checkRootPathTraversal(target, testInput) {
         await workspace.cleanup();
     }
 }
-/**
- * Checks that a path traversal input to --out does not write outside the workspace.
- */
-export async function checkOutPathTraversal(target, testInput) {
-    const workspace = createTempWorkspace("p4-out-");
+const OUT_TRAVERSAL = {
+    flag: "--out",
+    workspacePrefix: "p4-out-",
+    idStem: "path-traversal-out",
+    nameStem: "Path traversal via --out",
+    title: "Write escaped workspace via --out traversal",
+    recommendation: "Validate --out argument is within an allowed prefix before writing.",
+    declaredDir: (workspace) => workspace.outputDir,
+};
+const INDEX_TRAVERSAL = {
+    flag: "--index",
+    workspacePrefix: "p4-idx-",
+    idStem: "path-traversal-index",
+    nameStem: "Path traversal via --index",
+    title: "Write escaped workspace via --index traversal",
+    recommendation: "Validate --index argument is within an allowed prefix.",
+    declaredDir: (workspace) => workspace.indexDir,
+};
+function isUnder(relativePath, relativeDir) {
+    return relativePath === relativeDir || relativePath.startsWith(relativeDir + path.sep);
+}
+async function checkContainedTraversal(config, target, testInput) {
+    const id = `${config.idStem}-${testInput.id}`;
+    const name = `${config.nameStem}: ${testInput.description}`;
+    const blocked = (reason) => skippedCheck({
+        id,
+        name,
+        category: "cli-adversarial",
+        reason: `BLOCKED_BEFORE_LAUNCH: ${reason}`,
+    });
+    const plan = classifyTraversalValue(testInput.value);
+    if (plan.kind === "refused")
+        return blocked(plan.reason);
+    const workspace = createTempWorkspace(config.workspacePrefix, { nestDepth: plan.nestDepth });
     try {
-        const beforeOutside = snapshotDir(workspace.outsideDir);
-        // Build an escaped --out path that points outside the workspace.
-        // We use the actual outsideDir path so we can check for writes there.
-        const escapedOut = testInput.value.startsWith("/") || /^[A-Za-z]:\\/.test(testInput.value)
-            ? testInput.value // absolute path given in test input
-            : path.resolve(workspace.outputDir, testInput.value); // resolve relative from output
+        const enclosureDir = workspace.enclosureDir;
+        const declaredDir = config.declaredDir(workspace);
+        const proof = proveContainment({
+            value: testInput.value,
+            baseDir: declaredDir,
+            enclosureDir,
+            declaredDir,
+        });
+        if (!proof.ok)
+            return blocked(proof.reason);
+        let before;
+        try {
+            before = snapshotTreeStrict(enclosureDir);
+        }
+        catch (error) {
+            return blocked(`enclosure is not inspectable before launch: ${error instanceof Error ? error.message : String(error)}`);
+        }
         const { command, args } = buildCliCommand(target, [
             "--root",
             workspace.sourceDir,
-            "--out",
-            escapedOut,
+            config.flag,
+            proof.destination,
         ]);
-        const result = await runAdversarialCheck({
-            id: `path-traversal-out-${testInput.id}`,
-            name: `Path traversal via --out: ${testInput.description}`,
+        const allowedRelative = path.relative(proof.enclosure, proof.declared);
+        return await runAdversarialCheck({
+            id,
+            name,
             category: "cli-adversarial",
             severity: "blocker",
             command,
@@ -87,77 +129,73 @@ export async function checkOutPathTraversal(target, testInput) {
             timeoutMs: target.timeoutMs,
             evaluate: (cmdResult) => {
                 const findings = [];
-                const afterOutside = snapshotDir(workspace.outsideDir);
-                const outsideDiff = diffSnapshots(beforeOutside, afterOutside);
-                if (outsideDiff.added.length > 0 || outsideDiff.modified.length > 0) {
+                // A child that never produced an exit code (and did not time out) did
+                // not execute; the runner reports asynchronous spawn failures this way.
+                if (cmdResult.spawnError || (cmdResult.exitCode === null && !cmdResult.timedOut)) {
                     findings.push(makeFinding({
-                        id: `path-traversal-out-${testInput.id}-escape`,
-                        title: "Write escaped workspace via --out traversal",
+                        id: `${id}-not-executed`,
+                        title: `CLI did not run for ${config.flag} traversal check`,
+                        severity: "major",
+                        category: "cli-adversarial",
+                        description: `Spawn error: ${cmdResult.spawnError ?? cmdResult.stderr.slice(0, 200)}`,
+                        evidence: `${config.flag} value: ${proof.destination}`,
+                        recommendation: "Fix the CLI invocation so the traversal check actually executes.",
+                    }));
+                }
+                let after;
+                try {
+                    after = snapshotTreeStrict(enclosureDir);
+                }
+                catch (error) {
+                    findings.push(makeFinding({
+                        id: `${id}-inspection-lost`,
+                        title: `Cannot inspect enclosure after ${config.flag} traversal`,
                         severity: "blocker",
                         category: "cli-adversarial",
-                        description: `CLI wrote outside workspace: ${outsideDiff.added.join(", ")}`,
-                        evidence: `--out value: ${escapedOut}, stdout: ${cmdResult.stdout.slice(0, 200)}`,
-                        recommendation: "Validate --out argument is within an allowed prefix before writing.",
+                        description: `Post-run snapshot failed: ${error instanceof Error ? error.message : String(error)}`,
+                        evidence: `${config.flag} value: ${proof.destination}`,
+                        recommendation: "Treat the traversal outcome as unknown; investigate before release.",
                     }));
+                    return findings;
                 }
-                return findings;
-            },
-        });
-        return result;
-    }
-    finally {
-        await workspace.cleanup();
-    }
-}
-/**
- * Checks that a path traversal input to --index does not allow writes outside workspace.
- */
-export async function checkIndexPathTraversal(target, testInput) {
-    const workspace = createTempWorkspace("p4-idx-");
-    try {
-        const beforeOutside = snapshotDir(workspace.outsideDir);
-        const escapedIndex = testInput.value.startsWith("/") || /^[A-Za-z]:\\/.test(testInput.value)
-            ? testInput.value
-            : path.resolve(workspace.indexDir, testInput.value);
-        const { command, args } = buildCliCommand(target, [
-            "--root",
-            workspace.sourceDir,
-            "--index",
-            escapedIndex,
-        ]);
-        const result = await runAdversarialCheck({
-            id: `path-traversal-index-${testInput.id}`,
-            name: `Path traversal via --index: ${testInput.description}`,
-            category: "cli-adversarial",
-            severity: "blocker",
-            command,
-            args,
-            cwd: workspace.root,
-            timeoutMs: target.timeoutMs,
-            evaluate: (cmdResult) => {
-                const findings = [];
-                const afterOutside = snapshotDir(workspace.outsideDir);
-                const outsideDiff = diffSnapshots(beforeOutside, afterOutside);
-                if (outsideDiff.added.length > 0 || outsideDiff.modified.length > 0) {
+                const diff = diffSnapshots(before, after);
+                const outside = (list) => list.filter((rel) => !isUnder(rel, allowedRelative));
+                const added = outside(diff.added);
+                const modified = outside(diff.modified);
+                const removed = outside(diff.removed);
+                if (added.length + modified.length + removed.length > 0) {
+                    const changed = [...added, ...modified, ...removed].map((rel) => path.join(proof.enclosure, rel));
                     findings.push(makeFinding({
-                        id: `path-traversal-index-${testInput.id}-escape`,
-                        title: "Write escaped workspace via --index traversal",
+                        id: `${id}-escape`,
+                        title: config.title,
                         severity: "blocker",
                         category: "cli-adversarial",
-                        description: `CLI wrote outside workspace: ${outsideDiff.added.join(", ")}`,
-                        evidence: `--index value: ${escapedIndex}, stdout: ${cmdResult.stdout.slice(0, 200)}`,
-                        recommendation: "Validate --index argument is within an allowed prefix.",
+                        description: `CLI wrote outside workspace: added [${added.join(", ")}], modified [${modified.join(", ")}], removed [${removed.join(", ")}]`,
+                        evidence: `${config.flag} value: ${proof.destination}, stdout: ${cmdResult.stdout.slice(0, 200)}`,
+                        affectedFiles: changed,
+                        recommendation: config.recommendation,
                     }));
                 }
                 return findings;
             },
         });
-        return result;
     }
     finally {
         await workspace.cleanup();
     }
 }
+/**
+ * Checks that a path traversal input to --out does not write outside the declared output directory.
+ */
+export async function checkOutPathTraversal(target, testInput) {
+    return checkContainedTraversal(OUT_TRAVERSAL, target, testInput);
+}
+/**
+ * Checks that a path traversal input to --index does not write outside the declared index directory.
+ */
+export async function checkIndexPathTraversal(target, testInput) {
+    return checkContainedTraversal(INDEX_TRAVERSAL, target, testInput);
+}
 // ---------------------------------------------------------------------------
 // Safe path handling checks
 // ---------------------------------------------------------------------------

package/dist/src/securityValidation/cliAdversarial/tempWorkspace.js

@@ -1,18 +1,28 @@
 import { createHash } from "node:crypto";
-import { mkdirSync, mkdtempSync, readdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
+import { lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, statSync, writeFileSync, } from "node:fs";
 import { rm } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-// ---------------------------------------------------------------------------
-// Workspace creation
-// ---------------------------------------------------------------------------
-export function createTempWorkspace(prefix = "adv-cli-") {
-    const root = mkdtempSync(path.join(os.tmpdir(), prefix));
+export function createTempWorkspace(prefix = "adv-cli-", options = {}) {
+    let enclosureDir;
+    let root;
+    let outsideDir;
+    if (options.nestDepth === undefined) {
+        root = mkdtempSync(path.join(os.tmpdir(), prefix));
+        // Create outside dir as a sibling of root (not inside it).
+        outsideDir = mkdtempSync(path.join(os.tmpdir(), `${prefix}outside-`));
+    }
+    else {
+        enclosureDir = mkdtempSync(path.join(os.tmpdir(), `${prefix}encl-`));
+        const nest = Array.from({ length: options.nestDepth }, (_, i) => `d${i + 1}`);
+        root = path.join(enclosureDir, ...nest, "ws");
+        outsideDir = path.join(enclosureDir, "outside");
+        mkdirSync(root, { recursive: true });
+        mkdirSync(outsideDir, { recursive: true });
+    }
     const sourceDir = path.join(root, "source");
     const outputDir = path.join(root, "output");
     const indexDir = path.join(root, "index");
-    // Create outside dir as a sibling of root (not inside it).
-    const outsideDir = mkdtempSync(path.join(os.tmpdir(), `${prefix}outside-`));
     mkdirSync(sourceDir, { recursive: true });
     mkdirSync(outputDir, { recursive: true });
     mkdirSync(indexDir, { recursive: true });
@@ -28,7 +38,12 @@ export function createTempWorkspace(prefix = "adv-cli-") {
         outputDir,
         indexDir,
         outsideDir,
+        enclosureDir,
         cleanup: async () => {
+            if (enclosureDir) {
+                await rm(enclosureDir, { recursive: true, force: true });
+                return;
+            }
             await Promise.all([
                 rm(root, { recursive: true, force: true }),
                 rm(outsideDir, { recursive: true, force: true }),
@@ -82,6 +97,40 @@ function collectSnapshots(baseDir, currentDir, out) {
         }
     }
 }
+/**
+ * Strict snapshot of a whole tree: records directories and links as well as
+ * files, never follows links, and THROWS when any entry cannot be inspected.
+ * Used where an unreadable tree must not be mistaken for an unchanged one.
+ */
+export function snapshotTreeStrict(dir) {
+    const snapshots = [];
+    collectStrict(dir, dir, snapshots);
+    return snapshots.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+}
+function collectStrict(baseDir, currentDir, out) {
+    for (const entry of readdirSync(currentDir)) {
+        const abs = path.join(currentDir, entry);
+        const stat = lstatSync(abs);
+        const relativePath = path.relative(baseDir, abs);
+        if (stat.isSymbolicLink()) {
+            out.push({ relativePath, absolutePath: abs, contentHash: `<link:${readlinkSync(abs)}>` });
+        }
+        else if (stat.isDirectory()) {
+            out.push({ relativePath, absolutePath: abs, contentHash: "<dir>" });
+            collectStrict(baseDir, abs, out);
+        }
+        else if (stat.isFile()) {
+            out.push({
+                relativePath,
+                absolutePath: abs,
+                contentHash: createHash("sha256").update(readFileSync(abs)).digest("hex"),
+            });
+        }
+        else {
+            out.push({ relativePath, absolutePath: abs, contentHash: "<special>" });
+        }
+    }
+}
 export function diffSnapshots(before, after) {
     const beforeMap = new Map(before.map((s) => [s.relativePath, s.contentHash]));
     const afterMap = new Map(after.map((s) => [s.relativePath, s.contentHash]));