@dailephd/my-dev-kit-lab 0.2.0

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

@@ -0,0 +1,294 @@
+import { spawn } from "node:child_process";
+import { buildCliCommand } from "./adversarialCliConfig.js";
+import { makeFinding, runAdversarialCheck } from "./runAdversarialCheck.js";
+import { createTempWorkspace, diffSnapshots, snapshotDir } from "./tempWorkspace.js";
+// ---------------------------------------------------------------------------
+// Source read-only boundary checks
+// ---------------------------------------------------------------------------
+/**
+ * Checks that running the CLI does not modify any files in the --root directory.
+ * All source files must have the same content before and after the CLI run.
+ */
+export async function checkSourceFilesNotModified(target) {
+    const workspace = createTempWorkspace("p4-ro-");
+    try {
+        const beforeSource = snapshotDir(workspace.sourceDir);
+        const { command, args } = buildCliCommand(target, [
+            "--root",
+            workspace.sourceDir,
+            "--out",
+            workspace.outputDir,
+        ]);
+        return await runAdversarialCheck({
+            id: "source-files-not-modified",
+            name: "Source files are not modified during CLI run",
+            category: "cli-adversarial",
+            severity: "blocker",
+            command,
+            args,
+            cwd: workspace.root,
+            timeoutMs: target.timeoutMs,
+            evaluate: () => {
+                const afterSource = snapshotDir(workspace.sourceDir);
+                const diff = diffSnapshots(beforeSource, afterSource);
+                const problems = [
+                    ...diff.modified.map((f) => `modified: ${f}`),
+                    ...diff.removed.map((f) => `removed: ${f}`),
+                ];
+                if (problems.length > 0) {
+                    return [
+                        makeFinding({
+                            id: "source-modified",
+                            title: "Source files were modified by CLI",
+                            severity: "blocker",
+                            category: "cli-adversarial",
+                            description: `CLI modified or deleted source files: ${problems.join(", ")}`,
+                            affectedFiles: [...diff.modified, ...diff.removed],
+                            recommendation: "CLI must treat --root as read-only. No writes should go to the source directory.",
+                        }),
+                    ];
+                }
+                return [];
+            },
+        });
+    }
+    finally {
+        await workspace.cleanup();
+    }
+}
+/**
+ * Checks that all writes by the CLI are confined to the declared --out directory.
+ * No new files should appear in the source directory or outside the workspace.
+ */
+export async function checkWritesLimitedToOutput(target) {
+    const workspace = createTempWorkspace("p4-wlt-");
+    try {
+        const beforeSource = snapshotDir(workspace.sourceDir);
+        const beforeOutside = snapshotDir(workspace.outsideDir);
+        const { command, args } = buildCliCommand(target, [
+            "--root",
+            workspace.sourceDir,
+            "--out",
+            workspace.outputDir,
+        ]);
+        return await runAdversarialCheck({
+            id: "writes-limited-to-output",
+            name: "All CLI writes are confined to the declared output directory",
+            category: "cli-adversarial",
+            severity: "blocker",
+            command,
+            args,
+            cwd: workspace.root,
+            timeoutMs: target.timeoutMs,
+            evaluate: () => {
+                const findings = [];
+                // Check source dir: no new files, no modifications.
+                const afterSource = snapshotDir(workspace.sourceDir);
+                const sourceDiff = diffSnapshots(beforeSource, afterSource);
+                const sourceProblems = [
+                    ...sourceDiff.added.map((f) => `added: ${f}`),
+                    ...sourceDiff.modified.map((f) => `modified: ${f}`),
+                ];
+                if (sourceProblems.length > 0) {
+                    findings.push(makeFinding({
+                        id: "write-in-source-dir",
+                        title: "CLI wrote files into the source directory",
+                        severity: "blocker",
+                        category: "cli-adversarial",
+                        description: `Unexpected writes in source dir: ${sourceProblems.join(", ")}`,
+                        affectedFiles: [...sourceDiff.added, ...sourceDiff.modified],
+                        recommendation: "CLI writes must never go to --root source directory.",
+                    }));
+                }
+                // Check outside dir: nothing should appear there.
+                const afterOutside = snapshotDir(workspace.outsideDir);
+                const outsideDiff = diffSnapshots(beforeOutside, afterOutside);
+                const outsideProblems = [
+                    ...outsideDiff.added.map((f) => `added: ${f}`),
+                    ...outsideDiff.modified.map((f) => `modified: ${f}`),
+                ];
+                if (outsideProblems.length > 0) {
+                    findings.push(makeFinding({
+                        id: "write-outside-workspace",
+                        title: "CLI wrote files outside the workspace",
+                        severity: "blocker",
+                        category: "cli-adversarial",
+                        description: `Unexpected writes outside workspace: ${outsideProblems.join(", ")}`,
+                        affectedFiles: [...outsideDiff.added, ...outsideDiff.modified],
+                        recommendation: "CLI must confine all writes to explicitly declared artifact directories.",
+                    }));
+                }
+                return findings;
+            },
+        });
+    }
+    finally {
+        await workspace.cleanup();
+    }
+}
+/**
+ * Checks that running the CLI with --index does not modify source files
+ * and does confine writes to the index directory.
+ */
+export async function checkIndexWriteContainment(target) {
+    const workspace = createTempWorkspace("p4-idx-ro-");
+    try {
+        const beforeSource = snapshotDir(workspace.sourceDir);
+        const beforeOutside = snapshotDir(workspace.outsideDir);
+        const { command, args } = buildCliCommand(target, [
+            "--root",
+            workspace.sourceDir,
+            "--index",
+            workspace.indexDir,
+        ]);
+        return await runAdversarialCheck({
+            id: "index-write-containment",
+            name: "CLI index writes are confined to the declared index directory",
+            category: "cli-adversarial",
+            severity: "blocker",
+            command,
+            args,
+            cwd: workspace.root,
+            timeoutMs: target.timeoutMs,
+            evaluate: () => {
+                const findings = [];
+                const afterSource = snapshotDir(workspace.sourceDir);
+                const sourceDiff = diffSnapshots(beforeSource, afterSource);
+                const sourceWrites = [...sourceDiff.added, ...sourceDiff.modified];
+                if (sourceWrites.length > 0) {
+                    findings.push(makeFinding({
+                        id: "index-write-in-source",
+                        title: "Index operation modified source files",
+                        severity: "blocker",
+                        category: "cli-adversarial",
+                        description: `Source files modified: ${sourceWrites.join(", ")}`,
+                        affectedFiles: sourceWrites,
+                        recommendation: "Index operation must never write to the source root directory.",
+                    }));
+                }
+                const afterOutside = snapshotDir(workspace.outsideDir);
+                const outsideDiff = diffSnapshots(beforeOutside, afterOutside);
+                const outsideWrites = [...outsideDiff.added, ...outsideDiff.modified];
+                if (outsideWrites.length > 0) {
+                    findings.push(makeFinding({
+                        id: "index-write-outside",
+                        title: "Index operation wrote outside the workspace",
+                        severity: "blocker",
+                        category: "cli-adversarial",
+                        description: `Writes outside workspace: ${outsideWrites.join(", ")}`,
+                        affectedFiles: outsideWrites,
+                        recommendation: "Index writes must be confined to the declared --index path.",
+                    }));
+                }
+                return findings;
+            },
+        });
+    }
+    finally {
+        await workspace.cleanup();
+    }
+}
+/**
+ * Checks that a simulated artifact refresh/re-index does not delete user source files.
+ * Runs the CLI twice and verifies source files survive both runs unchanged.
+ */
+export async function checkArtifactCleanupSafe(target) {
+    const workspace = createTempWorkspace("p4-cleanup-");
+    try {
+        // First run — populate output directory.
+        const { command: cmd1, args: args1 } = buildCliCommand(target, [
+            "--root",
+            workspace.sourceDir,
+            "--out",
+            workspace.outputDir,
+        ]);
+        await spawnAndWait(cmd1, args1, workspace.root);
+        // Snapshot source AFTER first run (baseline for cleanup test).
+        const beforeSource = snapshotDir(workspace.sourceDir);
+        const beforeOutside = snapshotDir(workspace.outsideDir);
+        // Second run — simulates artifact refresh.
+        const { command, args } = buildCliCommand(target, [
+            "--root",
+            workspace.sourceDir,
+            "--out",
+            workspace.outputDir,
+        ]);
+        return await runAdversarialCheck({
+            id: "generated-cleanup-user-files",
+            name: "Generated artifact refresh does not delete user source files",
+            category: "artifact-safety",
+            severity: "blocker",
+            command,
+            args,
+            cwd: workspace.root,
+            timeoutMs: target.timeoutMs,
+            evaluate: () => {
+                const findings = [];
+                const afterSource = snapshotDir(workspace.sourceDir);
+                const sourceDiff = diffSnapshots(beforeSource, afterSource);
+                const deletedSource = sourceDiff.removed;
+                if (deletedSource.length > 0) {
+                    findings.push(makeFinding({
+                        id: "cleanup-deleted-source",
+                        title: "Artifact refresh deleted user source files",
+                        severity: "blocker",
+                        category: "artifact-safety",
+                        description: `Source files deleted during refresh: ${deletedSource.join(", ")}`,
+                        affectedFiles: deletedSource,
+                        recommendation: "Generated artifact cleanup must be scoped to the declared output/index path only.",
+                    }));
+                }
+                const modifiedSource = sourceDiff.modified;
+                if (modifiedSource.length > 0) {
+                    findings.push(makeFinding({
+                        id: "cleanup-modified-source",
+                        title: "Artifact refresh modified user source files",
+                        severity: "blocker",
+                        category: "artifact-safety",
+                        description: `Source files modified during refresh: ${modifiedSource.join(", ")}`,
+                        affectedFiles: modifiedSource,
+                        recommendation: "Artifact refresh must never write to the source directory.",
+                    }));
+                }
+                const afterOutside = snapshotDir(workspace.outsideDir);
+                const outsideDiff = diffSnapshots(beforeOutside, afterOutside);
+                if (outsideDiff.modified.length > 0 || outsideDiff.removed.length > 0) {
+                    findings.push(makeFinding({
+                        id: "cleanup-outside-impact",
+                        title: "Artifact refresh affected files outside workspace",
+                        severity: "blocker",
+                        category: "artifact-safety",
+                        description: `Files outside workspace were affected during refresh: ${[...outsideDiff.modified, ...outsideDiff.removed].join(", ")}`,
+                        recommendation: "Refresh cleanup must be strictly scoped to output directories.",
+                    }));
+                }
+                return findings;
+            },
+        });
+    }
+    finally {
+        await workspace.cleanup();
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function spawnAndWait(command, args, cwd) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(command, args, {
+                cwd,
+                shell: false,
+                stdio: ["ignore", "ignore", "ignore"],
+                env: { ...process.env },
+            });
+        }
+        catch {
+            resolve();
+            return;
+        }
+        child.on("close", () => resolve());
+        child.on("error", () => resolve());
+    });
+}

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

@@ -0,0 +1,149 @@
+import { spawn } from "node:child_process";
+export async function runAdversarialCheck(input) {
+    const startedAt = new Date().toISOString();
+    const started = Date.now();
+    const cmdResult = await spawnAdversarialCommand({
+        command: input.command,
+        args: input.args,
+        cwd: input.cwd,
+        timeoutMs: input.timeoutMs,
+    });
+    const findings = input.evaluate(cmdResult);
+    const finishedAt = new Date().toISOString();
+    const durationMs = Date.now() - started;
+    const status = findings.length > 0
+        ? (findings.some((f) => f.severity === "blocker" || f.severity === "major") ? "failed" : "warning")
+        : "passed";
+    return {
+        id: input.id,
+        name: input.name,
+        category: input.category,
+        status,
+        severity: input.severity,
+        startedAt,
+        finishedAt,
+        durationMs,
+        findings,
+        command: [input.command, ...input.args].join(" "),
+    };
+}
+export function skippedCheck(options) {
+    const now = new Date().toISOString();
+    return {
+        id: options.id,
+        name: options.name,
+        category: options.category,
+        status: "skipped",
+        severity: "skipped",
+        startedAt: now,
+        finishedAt: now,
+        durationMs: 0,
+        findings: [],
+        skippedReason: options.reason,
+    };
+}
+// ---------------------------------------------------------------------------
+// Finding helpers
+// ---------------------------------------------------------------------------
+export function makeFinding(options) {
+    return {
+        id: options.id,
+        title: options.title,
+        severity: options.severity,
+        category: options.category,
+        description: options.description,
+        evidence: options.evidence,
+        affectedFiles: options.affectedFiles,
+        recommendation: options.recommendation,
+        releaseImpact: options.severity === "blocker" || options.severity === "major"
+            ? "Must be resolved before release"
+            : "Review before release",
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal command runner (no shell interpolation)
+// ---------------------------------------------------------------------------
+async function spawnAdversarialCommand(options) {
+    const started = Date.now();
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let settled = false;
+        let timeout;
+        let child;
+        try {
+            child = spawn(options.command, options.args, {
+                cwd: options.cwd,
+                shell: false,
+                stdio: ["ignore", "pipe", "pipe"],
+                env: { ...process.env },
+            });
+        }
+        catch (err) {
+            resolve({
+                command: options.command,
+                args: options.args,
+                cwd: options.cwd,
+                exitCode: null,
+                stdout: "",
+                stderr: "",
+                durationMs: Date.now() - started,
+                timedOut: false,
+                spawnError: err instanceof Error ? err.message : String(err),
+            });
+            return;
+        }
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        if (options.timeoutMs > 0) {
+            timeout = setTimeout(() => {
+                timedOut = true;
+                try {
+                    child.kill("SIGTERM");
+                }
+                catch {
+                    // Already exited.
+                }
+            }, options.timeoutMs);
+        }
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeout)
+                clearTimeout(timeout);
+            resolve({
+                command: options.command,
+                args: options.args,
+                cwd: options.cwd,
+                exitCode: null,
+                stdout,
+                stderr: err.message,
+                durationMs: Date.now() - started,
+                timedOut,
+            });
+        });
+        child.on("close", (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeout)
+                clearTimeout(timeout);
+            resolve({
+                command: options.command,
+                args: options.args,
+                cwd: options.cwd,
+                exitCode,
+                stdout,
+                stderr,
+                durationMs: Date.now() - started,
+                timedOut,
+            });
+        });
+    });
+}

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

@@ -0,0 +1,214 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { buildCliCommand } from "./adversarialCliConfig.js";
+import { makeFinding } from "./runAdversarialCheck.js";
+import { createTempWorkspace, diffSnapshots, snapshotDir } from "./tempWorkspace.js";
+function runAndCapture(command, args, cwd, timeoutMs) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(command, args, {
+                cwd,
+                shell: false,
+                stdio: ["ignore", "pipe", "pipe"],
+                env: { ...process.env },
+            });
+        }
+        catch {
+            resolve({ exitCode: 1, stdout: "", stderr: "" });
+            return;
+        }
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        child.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
+        child.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+        const timer = setTimeout(() => {
+            try {
+                child.kill();
+            }
+            catch {
+                // ignore
+            }
+            resolve({
+                exitCode: 1,
+                stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+                stderr: Buffer.concat(stderrChunks).toString("utf8"),
+            });
+        }, timeoutMs);
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({
+                exitCode: code ?? 1,
+                stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+                stderr: Buffer.concat(stderrChunks).toString("utf8"),
+            });
+        });
+        child.on("error", () => {
+            clearTimeout(timer);
+            resolve({
+                exitCode: 1,
+                stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+                stderr: Buffer.concat(stderrChunks).toString("utf8"),
+            });
+        });
+    });
+}
+// Metacharacters that would be interpreted by a shell if the CLI used shell:true.
+const METACHAR_PATHS = [
+    { value: `path;echo injected`, label: "semicolon" },
+    { value: `path&echo injected`, label: "ampersand" },
+    { value: `path$(echo injected)`, label: "command substitution" },
+    { value: `path\`echo injected\``, label: "backtick substitution" },
+];
+/**
+ * Checks that paths with shell metacharacters are passed as literal strings
+ * and do not trigger command injection via the CLI invocation.
+ *
+ * The harness invokes the CLI with shell:false, so metacharacters in the
+ * path argument array are always literal. This check verifies that the CLI
+ * itself does not re-interpret path arguments through a shell.
+ */
+export async function checkSubprocessNoShellInterpolation(target) {
+    const started = new Date();
+    const workspace = createTempWorkspace("p5-shell-");
+    try {
+        const findings = [];
+        for (const { value: metacharPath, label } of METACHAR_PATHS) {
+            const beforeOutside = snapshotDir(workspace.outsideDir);
+            // Use the metachar path as the --root argument.
+            // Since the path likely doesn't exist, the CLI may exit non-zero.
+            // What matters is: no shell side effects (no "injected" written anywhere).
+            const injectedFile = path.join(workspace.root, "injected");
+            const { command, args } = buildCliCommand(target, [
+                "--root",
+                path.join(workspace.sourceDir, metacharPath),
+                "--out",
+                workspace.outputDir,
+            ]);
+            await runAndCapture(command, args, workspace.root, target.timeoutMs);
+            // If shell injection worked, "injected" might be created.
+            const { existsSync } = await import("node:fs");
+            if (existsSync(injectedFile)) {
+                findings.push(makeFinding({
+                    id: `shell-injection-${label.replace(/\s+/g, "-")}`,
+                    title: `Shell injection via ${label} in --root`,
+                    severity: "blocker",
+                    category: "cli-adversarial",
+                    description: `Shell injection via ${label}: file 'injected' was created, suggesting shell interpolation occurred.`,
+                    affectedFiles: [injectedFile],
+                    recommendation: "CLI must never pass path arguments through a shell. Use spawn argument arrays only.",
+                }));
+            }
+            // Also check that outsideDir was not affected.
+            const afterOutside = snapshotDir(workspace.outsideDir);
+            const outsideDiff = diffSnapshots(beforeOutside, afterOutside);
+            if (outsideDiff.added.length > 0 || outsideDiff.modified.length > 0) {
+                findings.push(makeFinding({
+                    id: `shell-injection-outside-${label.replace(/\s+/g, "-")}`,
+                    title: `Unexpected writes outside workspace for ${label} path`,
+                    severity: "major",
+                    category: "cli-adversarial",
+                    description: `${label} in --root caused writes outside the workspace.`,
+                    recommendation: "Path arguments with metacharacters must be treated as literal strings.",
+                }));
+            }
+        }
+        const finished = new Date();
+        return {
+            id: "subprocess-no-shell-interpolation",
+            name: "Subprocess calls avoid shell-string interpolation for metachar paths",
+            category: "cli-adversarial",
+            severity: "blocker",
+            status: findings.some((f) => f.severity === "blocker" || f.severity === "major")
+                ? "failed"
+                : findings.length > 0
+                    ? "warning"
+                    : "passed",
+            findings,
+            startedAt: started.toISOString(),
+            finishedAt: finished.toISOString(),
+            durationMs: finished.getTime() - started.getTime(),
+        };
+    }
+    finally {
+        await workspace.cleanup();
+    }
+}
+/**
+ * DOT label escaping test cases.
+ * Each case is a node name that would produce broken DOT syntax if unescaped.
+ */
+export const DOT_LABEL_TEST_CASES = [
+    { id: "double-quote", value: 'foo"bar', description: 'Double quote in label' },
+    { id: "backslash", value: "foo\\bar", description: "Backslash in label" },
+    { id: "angle-brackets", value: "foo<bar>", description: "Angle brackets in label" },
+    { id: "curly-braces", value: "foo{bar}", description: "Curly braces in label" },
+    { id: "pipe", value: "foo|bar", description: "Pipe character in label" },
+    { id: "newline", value: "foo\nbar", description: "Newline in label" },
+];
+/**
+ * Generates a minimal DOT-safe label from a raw string.
+ * This mirrors what a correct DOT label escaper should do.
+ */
+export function escapeDotLabel(raw) {
+    return raw
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, "\\n")
+        .replace(/\r/g, "\\r")
+        .replace(/[<>{}|]/g, (c) => `\\${c}`);
+}
+/**
+ * Checks that DOT label escaping handles all special characters correctly.
+ * This is a pure logic check — does not invoke the CLI.
+ */
+export async function checkDotLabelEscaping() {
+    const started = new Date();
+    const findings = [];
+    for (const { id, value, description } of DOT_LABEL_TEST_CASES) {
+        const escaped = escapeDotLabel(value);
+        // A valid escaped label must not contain unescaped special chars.
+        // We verify the escaper produces output that differs from the input for problematic chars.
+        if (value.includes('"') && escaped === value) {
+            findings.push(makeFinding({
+                id: `dot-label-${id}`,
+                title: `DOT label escaper did not escape: ${description}`,
+                severity: "major",
+                category: "cli-adversarial",
+                description: `Label '${value}' was not escaped. This would produce broken DOT syntax.`,
+                recommendation: "All special characters in DOT labels must be properly escaped.",
+            }));
+        }
+        // Verify the escaped label can be safely embedded in a DOT node declaration.
+        const dotSnippet = `"${escaped}"`;
+        // A correct snippet must not have unescaped double-quotes inside (except the wrappers).
+        const inner = dotSnippet.slice(1, -1);
+        const hasUnescapedQuote = inner.replace(/\\"/g, "").includes('"');
+        if (hasUnescapedQuote) {
+            findings.push(makeFinding({
+                id: `dot-label-unescaped-${id}`,
+                title: `DOT label contains unescaped double quote after escaping: ${description}`,
+                severity: "major",
+                category: "cli-adversarial",
+                description: `Escaped value '${escaped}' still contains an unescaped double-quote.`,
+                recommendation: "Double-quotes inside DOT labels must be escaped as \\\".",
+            }));
+        }
+    }
+    const finished = new Date();
+    return {
+        id: "graphviz-label-escaping",
+        name: "Graph labels escape special characters correctly",
+        category: "cli-adversarial",
+        severity: "major",
+        status: findings.some((f) => f.severity === "major" || f.severity === "blocker")
+            ? "failed"
+            : findings.length > 0
+                ? "warning"
+                : "passed",
+        findings,
+        startedAt: started.toISOString(),
+        finishedAt: finished.toISOString(),
+        durationMs: finished.getTime() - started.getTime(),
+    };
+}