@intentius/chant 0.124.12 → 0.124.14

package/dist/discovery/sandbox/policy-run.js

@@ -0,0 +1,142 @@
+import { realpathSync, rmSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { bundleDriver } from "./bundle.js";
+import { generatePolicyDriverSource } from "./driver.js";
+import { forkSandboxed } from "./fork.js";
+import { encodePolicyBuildResult, formatPolicyWireOffenders, } from "./policy-wire.js";
+import { ENV_VAR } from "../../env.js";
+/**
+ * chant #1131 — runs a project's `lint.policies` checks inside a sandboxed
+ * child, over the build result the parent has already merged and serialized,
+ * and brings back plain `PostSynthDiagnostic`s.
+ *
+ * This closes the last residual chant #1093 and #1113 documented. `--sandbox`
+ * isolated project *source* (#1045), then project *fold-time* code (#1093),
+ * then the project's `chant.config.ts` (#1113) — but `chant build` still
+ * imported every `lint.policies` module and called its `check` function in the
+ * CLI's own process, after discovery, with the CLI's full filesystem, network,
+ * environment and process-spawn access. The config crossing as data did not
+ * take the policies with it: they are declared in it as *paths*.
+ *
+ * ## Why a second child rather than the first one
+ *
+ * A policy is a callback over the *whole* resolved build, and no such thing
+ * exists inside the #1045 discovery child. That child sees only the
+ * run-fallback subset — folded files are collected in the parent, the merge
+ * happens in the parent, and serialization (which is what most policies
+ * actually read) happens later still. Running policies there would hand them a
+ * partial, unserialized view and call it the same check. So the boundary moves
+ * to where the complete result exists: after the merge, in a child of its own.
+ *
+ * Deliberately the same machinery, not a parallel one — the same three modules
+ * `./config-run.ts` reuses:
+ *  - `./bundle.ts` bundles the generated driver (`./driver.ts`'s
+ *    `generatePolicyDriverSource`) with esbuild, so the child needs no runtime
+ *    module resolution and no TypeScript loader.
+ *  - `./fork.ts` spawns it with the identical `--permission` profile the
+ *    run-fallback and config children get — one function, so the three cannot
+ *    drift.
+ *  - `./child-errors.ts` (inside the driver) classifies whatever it throws, so
+ *    a permission denial names the policy file instead of leaking
+ *    `ERR_ACCESS_DENIED`.
+ *
+ * The one addition is direction: the policy child receives its input over the
+ * same IPC channel it answers on (`SandboxForkOptions.send`). See that field's
+ * doc for why sending before the child boots is safe.
+ *
+ * ## What the child can and cannot do
+ *
+ * Exactly what a run-fallback file can: read the bundle directory and the
+ * project directory, nothing else; no writes, no spawning, no worker threads;
+ * an environment of `PATH` plus `CHANT_ENV` when set. That last one matches
+ * `./config-run.ts` for the same reason — `--env` is a value the user typed on
+ * the command line, and a policy that branches on the environment is the
+ * documented pattern (`ctx.env` carries it too, so this is belt-and-braces for
+ * a policy reading `process.env.CHANT_ENV` directly rather than a new
+ * capability).
+ *
+ * A policy that writes a report file, shells out to a scanner, or reads
+ * `~/.aws/credentials` therefore now FAILS, loudly, naming the file and the
+ * operation. That is the point of the flag, and it is a real behavior change
+ * for such a policy under `--sandbox` — see `docs/.../architecture/sandbox.mdx`.
+ */
+/** A policy child is one bundle, one import per policy module, and a pass over data. Generous relative to that, tight enough that a hung policy is reported rather than waited on. */
+const POLICY_CHILD_TIMEOUT_MS = 120000;
+/**
+ * chant #1148 — `[policy:<module-basename>]`, joined when a project declares
+ * more than one policy module (all of them share the one child — see the
+ * module doc above). One policy module is the only shape this repo's own
+ * corpus exercises (`lexicons/k8s/examples/org-policy`), so this is the
+ * common case, not a hypothetical.
+ */
+function policyOutputPrefix(policyPaths) {
+    return `[policy:${policyPaths.map((p) => basename(p)).join(",")}]`;
+}
+function isPolicyChildResponse(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.kind === "chant-policy" &&
+        typeof value.ok === "boolean");
+}
+/**
+ * Evaluate `policyPaths` against `buildResult` inside a sandboxed child.
+ *
+ * Throws — rather than degrading to an in-process run — when the policies
+ * cannot be evaluated inside the boundary or their diagnostics cannot cross it
+ * as JSON. Under `--sandbox` a policy pack that "almost" ran is not a safe
+ * thing to proceed with, and quietly falling back would give away the property
+ * the flag exists to provide.
+ */
+export async function runPoliciesSandboxed(options) {
+    const { policyPaths, buildResult, env, projectRoot } = options;
+    // Encoded FIRST, in the parent, before anything is bundled or spawned: this
+    // is where a build result that cannot cross is rejected by name (a
+    // `nestedStack()` child project, a serializer output that isn't data), and
+    // there is no point paying for a bundle to find that out.
+    const payload = {
+        kind: "chant-policy-request",
+        buildResult: encodePolicyBuildResult(buildResult),
+        env: env ?? null,
+    };
+    const payloadBytes = Buffer.byteLength(JSON.stringify(payload), "utf-8");
+    const driverSource = generatePolicyDriverSource(policyPaths);
+    const { bundlePath, bundleDir, externalReadPaths, durationMs, bytes } = await bundleDriver(driverSource);
+    try {
+        let projectRealpath;
+        try {
+            projectRealpath = realpathSync(resolve(projectRoot));
+        }
+        catch {
+            projectRealpath = resolve(projectRoot);
+        }
+        const childEnv = { PATH: process.env.PATH ?? "" };
+        const activeEnv = process.env[ENV_VAR];
+        if (activeEnv)
+            childEnv[ENV_VAR] = activeEnv;
+        const response = await forkSandboxed({
+            bundlePath,
+            bundleDir,
+            projectRealpath,
+            externalReadPaths,
+            env: childEnv,
+            timeoutMs: POLICY_CHILD_TIMEOUT_MS,
+            label: `sandboxed evaluation of lint.policies (${policyPaths.length} module(s))`,
+            send: payload,
+            // chant #1148 — a policy's own console.log/error no longer goes
+            // nowhere; see `./fork.ts`'s `outputPrefix` doc.
+            outputPrefix: policyOutputPrefix(policyPaths),
+        }, isPolicyChildResponse);
+        if (!response.ok) {
+            if (response.offenders && response.offenders.length > 0) {
+                throw new Error(formatPolicyWireOffenders("a policy check's return value", response.offenders));
+            }
+            throw new Error(response.error?.message
+                ? `Failed to run lint.policies inside the --sandbox boundary: ${response.error.message}`
+                : `Failed to run lint.policies inside the --sandbox boundary`);
+        }
+        return { diagnostics: response.diagnostics ?? [], bundleMs: durationMs, bundleBytes: bytes, payloadBytes };
+    }
+    finally {
+        rmSync(bundleDir, { recursive: true, force: true });
+    }
+}

package/dist/discovery/sandbox/policy-wire.js

@@ -0,0 +1,152 @@
+import { decodeEntitySet, encodeEntitySet } from "../entity-wire-codec.js";
+import { scanValueWireSafety } from "./config-wire.js";
+/**
+ * Encode a merged, serialized build result for the policy child.
+ *
+ * Runs in the PARENT. Throws — never drops — when the result holds something
+ * the wire cannot represent: `encodeEntitySet`'s own refusals (a `nestedStack()`
+ * child project, an `AttrRef` that never got a logical name) propagate, and the
+ * finished payload is walked by `./config-wire.ts`'s scan so a serializer that
+ * somehow produced a non-data output is named by key path rather than silently
+ * mangled by `JSON.stringify`.
+ */
+export function encodePolicyBuildResult(result) {
+    const wire = {
+        entities: encodeEntitySet(result.entities),
+        outputs: [...result.outputs].map(([name, output]) => [name, encodeOutput(output)]),
+        warnings: [...result.warnings],
+        errors: result.errors.map((err) => typeof err.toJSON === "function"
+            ? err.toJSON()
+            : { name: err.name, message: err.message }),
+        sourceFileCount: result.sourceFileCount,
+        dependencies: result.dependencies ? [...result.dependencies].map(([name, deps]) => [name, [...deps]]) : [],
+    };
+    if (result.manifest !== undefined)
+        wire.manifest = result.manifest;
+    if (result.foldDecisions !== undefined)
+        wire.foldDecisions = result.foldDecisions;
+    if (result.buildParams !== undefined)
+        wire.buildParams = result.buildParams;
+    const offenders = scanValueWireSafety(wire, "buildResult");
+    if (offenders.length > 0) {
+        throw new Error(formatPolicyWireOffenders("the build result", offenders));
+    }
+    return wire;
+}
+function encodeOutput(output) {
+    if (typeof output === "string")
+        return output;
+    const encoded = { primary: output.primary };
+    if (output.files !== undefined)
+        encoded.files = { ...output.files };
+    if (output.warnings !== undefined)
+        encoded.warnings = [...output.warnings];
+    return encoded;
+}
+/**
+ * Rebuild the `PostSynthContext["buildResult"]` a check expects, from the wire.
+ *
+ * Runs INSIDE the child. The maps and the live entity graph are reconstructed
+ * here (`decodeEntitySet`), so a check sees the same kind of object it sees
+ * in-process — `ctx.entities` is a real `Map`, its values are real
+ * `Declarable`s, and an `AttrRef` between two of them is a real `AttrRef`
+ * carrying its resolved logical name.
+ */
+export function decodePolicyBuildResult(wire) {
+    const decoded = {
+        outputs: new Map(wire.outputs),
+        entities: decodeEntitySet(wire.entities),
+        warnings: wire.warnings ?? [],
+        errors: (wire.errors ?? []),
+        sourceFileCount: wire.sourceFileCount ?? 0,
+        dependencies: new Map((wire.dependencies ?? []).map(([n, d]) => [n, new Set(d)])),
+        manifest: wire.manifest,
+        foldDecisions: wire.foldDecisions ?? [],
+        buildParams: wire.buildParams ?? [],
+    };
+    return decoded;
+}
+/**
+ * Validate what one policy module's checks returned, INSIDE the child, before
+ * it goes anywhere near the IPC channel.
+ *
+ * Two separate questions, both answered here rather than by hoping
+ * `JSON.stringify` behaves:
+ *
+ *  1. Is it data? A `PostSynthDiagnostic` is declared as five plain fields, but
+ *     a check is arbitrary project code and can return anything. A function, a
+ *     `Date`, a class instance, a circular reference — `JSON.stringify` would
+ *     drop or rewrite each of them without a word, and the CLI would print a
+ *     diagnostic that is not the one the policy produced.
+ *  2. Is it a diagnostic? A missing `checkId`, or a `severity` outside
+ *     `error`/`warning`/`info`, is reported here instead of turning into an
+ *     undefined-shaped line in the build's error list.
+ */
+export function scanPolicyDiagnostics(diagnostics, policyPath) {
+    const out = [];
+    if (!Array.isArray(diagnostics)) {
+        out.push({ policy: policyPath, path: "<return value>", found: describeShape(diagnostics) });
+        return out;
+    }
+    for (const offender of scanValueWireSafety(diagnostics, "")) {
+        out.push({ policy: policyPath, ...offender });
+    }
+    if (out.length > 0)
+        return out;
+    const severities = new Set(["error", "warning", "info"]);
+    diagnostics.forEach((diag, i) => {
+        const d = diag;
+        if (d === null || typeof d !== "object" || Array.isArray(d)) {
+            out.push({ policy: policyPath, path: `[${i}]`, found: describeShape(diag) });
+            return;
+        }
+        if (typeof d.checkId !== "string" || d.checkId.length === 0) {
+            out.push({ policy: policyPath, path: `[${i}].checkId`, found: "not a non-empty string" });
+        }
+        if (typeof d.message !== "string") {
+            out.push({ policy: policyPath, path: `[${i}].message`, found: "not a string" });
+        }
+        if (typeof d.severity !== "string" || !severities.has(d.severity)) {
+            out.push({ policy: policyPath, path: `[${i}].severity`, found: `not one of "error", "warning", "info"` });
+        }
+    });
+    return out;
+}
+/**
+ * Thrown INSIDE the child by the per-check wrapper `./driver.ts` generates,
+ * when a check returns something that cannot cross back. Carries the offenders
+ * so the driver can report them as data rather than as a message string it
+ * would then have to parse.
+ *
+ * A class rather than a tagged object because the driver tests it with
+ * `instanceof`: both halves come from this one module, bundled once, so there
+ * is exactly one class identity inside the child.
+ */
+export class PolicyWireError extends Error {
+    constructor(offenders) {
+        super(formatPolicyWireOffenders("a policy check's return value", offenders));
+        this.name = "PolicyWireError";
+        this.offenders = offenders;
+    }
+}
+function describeShape(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    if (value === undefined)
+        return "undefined";
+    return `a ${typeof value}`;
+}
+/** Render offenders as the body of a build error — one line each, naming the policy module. */
+export function formatPolicyWireOffenders(subject, offenders) {
+    const lines = offenders.map((o) => {
+        const where = o.policy ? `${o.policy}${o.path ? ` ${o.path}` : ""}` : o.path || "<root>";
+        return `  ${where}: ${o.found}`;
+    });
+    return [
+        `Cannot run lint.policies inside the --sandbox boundary: ${subject} holds values that are not data.`,
+        ...lines,
+        `Under --sandbox a policy check runs in an isolated child process and only JSON crosses back, so every value a check returns must be a string, number, boolean, null, array or plain object, and every diagnostic must have a string checkId, a string message, and a severity of "error", "warning" or "info". Return plain diagnostics, or drop --sandbox for this build.`,
+    ].join("\n");
+}

package/dist/discovery/sandbox/run.js

@@ -0,0 +1,77 @@
+import { realpathSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+import { DiscoveryError } from "../../errors.js";
+import { decodeEntitySet } from "../entity-wire-codec.js";
+import { bundleDriver } from "./bundle.js";
+import { classifyChildError } from "./child-errors.js";
+import { generateDriverSource } from "./driver.js";
+import { forkSandboxed } from "./fork.js";
+/** How long to wait for the sandboxed child to report back before treating it as hung and killing it. Generous: bundling+import+collect for a whole build's run-fallback set should be a small multiple of what the equivalent in-process run takes. */
+const CHILD_TIMEOUT_MS = 120000;
+function isChildResponse(value) {
+    return typeof value === "object" && value !== null && "entitySet" in value && "errors" in value;
+}
+/**
+ * Run `files` (already decided "run" by `discover()`'s fold/taint pass)
+ * together, isolated, in one sandboxed child process. Returns the same
+ * `{ entities, errors }` shape the parent's own `collectEntities` +
+ * `resolveAttrRefs` would have — see `../index.ts`'s `discover()`, which
+ * merges this result into the entities it collected from folded files.
+ *
+ * @param files - Absolute paths to run-fallback files.
+ * @param buildRoot - The directory `discover()` was pointed at — threaded to
+ *   `collectEntities` inside the child (stack-prefix disambiguation, #932)
+ *   and used to compute the project-directory read allowance.
+ */
+export async function runFallbackFilesSandboxed(files, buildRoot) {
+    if (files.length === 0) {
+        return { entities: new Map(), errors: [], bundleMs: 0, bundleBytes: 0, provenanceByName: {} };
+    }
+    const driverSource = generateDriverSource({ files, buildRoot });
+    const { bundlePath, bundleDir, externalReadPaths, durationMs, bytes } = await bundleDriver(driverSource);
+    try {
+        let projectRealpath;
+        try {
+            projectRealpath = realpathSync(resolve(buildRoot));
+        }
+        catch {
+            projectRealpath = resolve(buildRoot);
+        }
+        const response = await forkSandboxed({
+            bundlePath,
+            bundleDir,
+            projectRealpath,
+            externalReadPaths,
+            // chant #1045 Phase 2 — Node's Permission Model does not gate
+            // `process.env`; scrubbing it at spawn is the only way to keep the
+            // ambient environment out of untrusted project source's reach. `PATH`
+            // is kept only because some platforms' module resolution/dynamic
+            // linking consults it; it carries no project secrets.
+            env: { PATH: process.env.PATH ?? "" },
+            timeoutMs: CHILD_TIMEOUT_MS,
+            label: "sandboxed run",
+            // chant #1148 — a run-fallback file's own console.log/error no
+            // longer goes nowhere; see `./fork.ts`'s `outputPrefix` doc.
+            outputPrefix: "[sandbox:run]",
+        }, isChildResponse);
+        const errors = (response.errors ?? []).map((e) => new DiscoveryError(e.file, e.message, e.type));
+        const provenanceByName = response.provenanceByName ?? {};
+        if (response.fatal) {
+            return { entities: new Map(), errors, bundleMs: durationMs, bundleBytes: bytes, provenanceByName };
+        }
+        const entities = decodeEntitySet(response.entitySet ?? { entities: [] });
+        return { entities, errors, bundleMs: durationMs, bundleBytes: bytes, provenanceByName };
+    }
+    catch (err) {
+        return {
+            entities: new Map(),
+            errors: [classifyChildError("", err, "import")],
+            provenanceByName: {},
+            bundleMs: durationMs,
+            bundleBytes: bytes,
+        };
+    }
+    finally {
+        rmSync(bundleDir, { recursive: true, force: true });
+    }
+}