toolroll 0.5.0

package/dist/container-state.d.ts

@@ -0,0 +1,5 @@
+export type ContainerEmptiness = "empty" | "populated" | "unknown";
+export declare function captureCgroupIdentity(container: string): string;
+export declare function parseCgroupEvents(events: string): ContainerEmptiness;
+export declare function cgroupEmptiness(container: string, identity: string | null | undefined): ContainerEmptiness;
+export declare function containerEmptiness(backend: string, container: string, platform?: NodeJS.Platform, identity?: string | null): ContainerEmptiness;

package/dist/container-state.js

@@ -0,0 +1,62 @@
+/** Read-only kernel evidence. Recorded names never authorize signals. */
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { readFileSync, readlinkSync, realpathSync, statfsSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, normalize } from "node:path";
+const CGROUP2_MAGIC = 0x63677270;
+function parentIdentity(container) {
+    if (!isAbsolute(container) || normalize(container) !== container || !/^so-[A-Za-z0-9._-]+-[a-f0-9]{12}$/.test(basename(container)))
+        throw new Error("invalid cgroup custody path");
+    const parent = dirname(container);
+    if (realpathSync(parent) !== parent || statfsSync(parent).type !== CGROUP2_MAGIC)
+        throw new Error("custody parent is not the original cgroup v2 mount");
+    const stat = statSync(parent);
+    return { version: 1, namespace: readlinkSync("/proc/self/ns/cgroup"), parentDevice: stat.dev, parentInode: stat.ino };
+}
+export function captureCgroupIdentity(container) {
+    const parent = parentIdentity(container);
+    if (realpathSync(container) !== container || statfsSync(container).type !== CGROUP2_MAGIC)
+        throw new Error("custody object is not a cgroup v2 directory");
+    return JSON.stringify({ ...parent, inode: statSync(container).ino });
+}
+export function parseCgroupEvents(events) {
+    const rows = events.split("\n").filter(line => line.startsWith("populated"));
+    return rows.length !== 1 ? "unknown" : rows[0] === "populated 0" ? "empty" : rows[0] === "populated 1" ? "populated" : "unknown";
+}
+export function cgroupEmptiness(container, identity) {
+    if (!identity)
+        return "unknown";
+    try {
+        const saved = JSON.parse(identity);
+        const current = parentIdentity(container);
+        if (saved.version !== 1 || saved.namespace !== current.namespace || saved.parentDevice !== current.parentDevice || saved.parentInode !== current.parentInode || !Number.isSafeInteger(saved.inode))
+            return "unknown";
+        try {
+            if (realpathSync(container) !== container || statSync(container).ino !== saved.inode || statfsSync(container).type !== CGROUP2_MAGIC)
+                return "unknown";
+        }
+        catch (error) {
+            // Only the original, still-mounted parent may prove removal. Linux
+            // refuses rmdir while a cgroup has members; an unmounted hierarchy,
+            // another namespace, a replaced directory or an ordinary file cannot.
+            return error.code === "ENOENT" ? "empty" : "unknown";
+        }
+        return parseCgroupEvents(readFileSync(join(container, "cgroup.events"), "utf8"));
+    }
+    catch {
+        return "unknown";
+    }
+}
+export function containerEmptiness(backend, container, platform = process.platform, identity) {
+    if (backend === "cgroup2" && platform === "linux")
+        return cgroupEmptiness(container, identity);
+    if (backend === "job-object" && platform === "win32" && process.platform === "win32" && identity === "job-object-v1" && /^Global\\so-[A-Za-z0-9._-]+-[a-f0-9]{64}$/.test(container)) {
+        const systemRoot = process.env["SystemRoot"] ?? "C:\\Windows";
+        const shell = join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+        const result = spawnSync(shell, ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File", fileURLToPath(new URL("./job-object-helper.ps1", import.meta.url)), "-QueryName", container], { encoding: "utf8", timeout: 5000, maxBuffer: 4096, windowsHide: true });
+        const evidence = result.stdout?.trim();
+        if (result.status === 0 && (evidence === "empty" || evidence === "populated"))
+            return evidence;
+    }
+    return "unknown";
+}

package/dist/containment.d.ts

@@ -0,0 +1,197 @@
+/**
+ * OS process containment (docs/PROCESS_CONTAINMENT_PLAN.md).
+ *
+ * The stop contract before this module was OBSERVATIONAL: a provider's
+ * tree is scanned every 500 ms, and a double fork can reparent between
+ * scans. This module adds an OS boundary where the OS has one, and says
+ * exactly what it has where it has none:
+ *
+ *   linux   a delegated cgroup v2 directory per spawn. The target is
+ *           placed in it BEFORE it executes (the `sh` prelude below writes
+ *           its own pid, then execs the target with argv verbatim), so a
+ *           setsid/double-fork helper is born inside and dies with
+ *           `cgroup.kill`. Emptiness is the kernel's own `cgroup.events`
+ *           populated flag — never a transport exit. A detached janitor
+ *           kills the cgroup when this worker dies.
+ *   win32   a Job Object with kill-on-close and no breakaway, owned by a
+ *           PowerShell helper OUTSIDE the job that creates the target
+ *           suspended, assigns it, then resumes it. The helper's death —
+ *           including this worker's death, which closes its stdin — closes
+ *           the handle and the job kills everything in it.
+ *   darwin  nothing. There is no supported cgroup/Job Object equivalent;
+ *           NOTE_TRACK/NOTE_CHILD have been unsupported since 10.5 and
+ *           launchd's AbandonProcessGroup only covers a process group. The
+ *           observational mode stays, is reported as exactly that, and a
+ *           REQUIRED policy refuses before any target executes.
+ *
+ * Three policies: `observed` (the behaviour every existing installation
+ * has), `preferred` (native when this machine can, observed — and said
+ * so — when it cannot), `required` (native or a refusal; never a silent
+ * downgrade). The policy is decided ONCE per controller process from the
+ * operator's flag or environment and pinned; nothing a child supplies and
+ * no corrupt value can weaken a pinned requirement.
+ */
+import { type ChildProcess } from "node:child_process";
+export declare const CONTAINMENT_POLICIES: readonly ["observed", "preferred", "required"];
+export type ContainmentPolicy = (typeof CONTAINMENT_POLICIES)[number];
+export type ContainmentBackendId = "cgroup2" | "job-object";
+/** The environment name the controller reads when no flag names a policy. */
+export declare const CONTAINMENT_ENV = "TOOLROLL_CONTAINMENT";
+export type PolicyParse = {
+    ok: true;
+    policy: ContainmentPolicy;
+    source: "default" | "explicit";
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * Parse an operator's policy word. Absent means `observed` — every
+ * existing installation keeps its behaviour. Anything present must be
+ * one of the three words exactly: a corrupt value is a refusal, never a
+ * quiet fall back to observed (which would turn a requirement off).
+ */
+export declare function parseContainmentPolicy(raw: string | undefined | null): PolicyParse;
+export type ContainmentCapability = {
+    platform: NodeJS.Platform;
+    backend: ContainmentBackendId | null;
+    available: boolean;
+    /** Why, in words an operator can act on. */
+    detail: string;
+    /** cgroup2: the delegated cgroup directory this process may create children in. */
+    cgroupRoot?: string;
+    /** cgroup2: whether the kernel offers the required atomic cgroup.kill (5.14+). */
+    cgroupKill?: boolean;
+    /** job-object: the helper and the shell that runs it. */
+    helper?: string;
+    powershell?: string;
+};
+export type CapabilityProbeOptions = {
+    platform?: NodeJS.Platform;
+    /** Tests: the mounted cgroup2 root (default /sys/fs/cgroup). */
+    cgroupMount?: string;
+    /** Tests: this process's /proc/self/cgroup text. */
+    selfCgroup?: string;
+    /** Tests: where the Windows helper would be. */
+    helperPath?: string;
+    /** Tests: the PowerShell executable. */
+    powershellPath?: string;
+};
+/** The cgroup path of this process from /proc/self/cgroup (`0::/path`). */
+export declare function ownCgroupPath(selfCgroup: string): string | null;
+/**
+ * What this machine can do, established by DOING it: on Linux, a child
+ * cgroup is created and removed inside this process's own cgroup; a
+ * mount that is not v2, a cgroup that is not delegated to this user, or
+ * an unreadable /proc all answer unavailable with the reason. Nothing
+ * here can be overridden by an environment variable into a claim the OS
+ * did not make.
+ */
+export declare function probeContainmentCapability(options?: CapabilityProbeOptions): ContainmentCapability;
+export declare function jobObjectHelperPath(): string;
+export type EffectiveContainment = {
+    policy: ContainmentPolicy;
+    capability: ContainmentCapability;
+    /** What spawns actually get. */
+    mode: "observed" | "native";
+    /** `preferred` on a machine that cannot: observed, and reported. */
+    downgraded: boolean;
+    /** `required` on a machine that cannot: every containable spawn refuses with these words, before any target executes. */
+    refusal: string | null;
+};
+/** The truthful composition of what was asked and what the OS offers. */
+export declare function effectiveContainment(policy: ContainmentPolicy, capability: ContainmentCapability): EffectiveContainment;
+/** One-line status words for `daemon status`, `up`, and the certificate. */
+export declare function describeContainment(effective: EffectiveContainment): string;
+/** The status envelope's shape: no paths a person did not already know, no secrets. */
+export declare function containmentStatus(effective: EffectiveContainment): Record<string, unknown>;
+/**
+ * Pin this process's containment ONCE, from the operator's own word. A
+ * second pin may only tighten: once `required` stands nothing pins it
+ * weaker — the only way down is a new process started with a new word.
+ */
+export declare function pinContainment(effective: EffectiveContainment): EffectiveContainment;
+/**
+ * Resolve the policy from a flag word, then the environment, then the
+ * default, and pin it. A corrupt word is a refusal to start, never a
+ * default: the caller reports `problem` and exits.
+ */
+export declare function resolveContainment(flagWord: string | undefined, env?: NodeJS.ProcessEnv): {
+    ok: true;
+    effective: EffectiveContainment;
+} | {
+    ok: false;
+    problem: string;
+};
+/** What every containable spawn consults. Unpinned = observed, exactly as before this module. */
+export declare function currentContainment(): EffectiveContainment;
+/** Tests only. */
+export declare function resetContainmentForTests(): void;
+export type AttachOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    detail: string;
+};
+/** How to spawn so the target is inside the OS object before it executes. */
+export type ContainedLaunch = {
+    file: string;
+    args: string[];
+    /** Extra stdio slots after stdin/stdout/stderr (the cgroup2 prelude confirms on fd 3). */
+    extraStdio: ("pipe" | "ignore")[];
+    /** Settles once the prelude has joined (before the target exec) or has failed (the target never ran). */
+    attach(child: ChildProcess): Promise<AttachOutcome>;
+};
+export type Container = {
+    backend: ContainmentBackendId;
+    /** The exact-run custody handle: cgroup directory or job name. */
+    id: string;
+    /** Kernel namespace/mount provenance for read-only recovery. */
+    identity?: string;
+    launch(file: string, args: readonly string[]): ContainedLaunch;
+    /** SIGKILL every member and wait for the OS to report the object empty. */
+    kill(timeoutMs?: number): Promise<boolean>;
+    /** true = members remain; false = proven empty; null = cannot be established right now. */
+    populated(): boolean | null;
+    waitEmpty(timeoutMs: number): Promise<boolean>;
+    /** Remove the OS object (only an empty one can go) and dismiss the janitor. */
+    release(): void;
+};
+export type ContainerFactory = (effective: EffectiveContainment, label: string) => Container;
+/** Tests: substitute the OS object (a scripted or file-backed stand-in). */
+export declare function overrideContainerFactoryForTests(factory: ContainerFactory | null): void;
+/**
+ * Make the OS object for one spawn, or say why not. `null` when the
+ * effective mode is observed; a `refused` when native containment was
+ * demanded and this spawn cannot have it — the caller must not spawn.
+ */
+export declare function createContainer(effective: EffectiveContainment, label: string): {
+    container: Container;
+} | {
+    container: null;
+} | {
+    refused: string;
+};
+/**
+ * The cgroup2 prelude: join, confirm on fd 3, close it, exec the target
+ * with argv exactly as given (positional parameters, never re-parsed).
+ * A join that fails exits 126 before the target can run.
+ */
+export declare const CGROUP2_PRELUDE = "echo \"$$\" > \"$1/cgroup.procs\" || exit 126\nprintf \"attached\\n\" >&3 || exit 126\nIFS= read -r permit <&3 || exit 126\n[ \"$permit\" = go ] || exit 126\nexec 3>&-\nshift\nexec \"$@\"";
+/** The janitor: waits for this worker's pipe to close, then kills and removes the cgroup. */
+export declare const CGROUP2_JANITOR: string;
+export declare function safeContainerLabel(label: string): string;
+/** A cgroup v2 leaf under the delegated root. Exported for the native test's direct use. */
+export declare function cgroup2Container(capability: ContainmentCapability, label: string, mountOverride?: string): Container;
+/**
+ * A Windows Job Object owned by a PowerShell helper outside the job. The
+ * helper connects to a named pipe this process listens on and reports
+ * `attached` only after CreateProcess(CREATE_SUSPENDED) + AssignProcess
+ * ToJobObject + ResumeThread; `failed <detail>` means the target never
+ * ran. `kill` asks for TerminateJobObject over the same pipe and waits
+ * for the helper's `empty` reply. Physical Windows is where this runs;
+ * the CI windows job exercises it.
+ */
+export declare function jobObjectContainer(capability: ContainmentCapability, label: string): Container;
+/** Where the Windows helper lives beside this module (dist or src). */
+export declare function containmentModuleDir(): string;