approval-md 0.0.1 → 0.2.0

package/dist/src/core/sandbox.d.ts

@@ -0,0 +1,290 @@
+/**
+ * The egress sandbox (APRV-193): the room an allowed command runs in.
+ *
+ * ## What this is for
+ *
+ * Arbitrary code execution is capability-complete. The gate classifies a
+ * command by its TEXT, and `npm test` runs whatever the agent wrote a minute
+ * ago, so for laundered exec the text has stopped describing the effect. No
+ * classifier over shell strings can close that, and `core/child-env.ts`
+ * (APRV-205) closed only half of it: the child no longer inherits the session's
+ * credentials, and it still inherits the session's network.
+ *
+ * This module removes the network. It does not try to predict what the code
+ * will do; it takes away what the code would need. Where APRV-205 starves the
+ * child of secrets, this starves it of a place to send them.
+ *
+ * ## The shape, and why it is this shape
+ *
+ * A NETWORK-ONLY sandbox, with one filesystem exception. The filesystem is left
+ * alone because the gate's own IPC is a FILE: `src/daemon/` opens no socket, it
+ * polls `.approval/log/events.jsonl`. So denying egress costs the gate nothing
+ * and needs no plumbing to stay reachable, and the "one door" other agent
+ * sandboxes build an egress proxy for already exists as an append to a file.
+ * That is the single largest simplification available here, and it is why the
+ * default profile denies the network, denies reads of the credential material
+ * beside the log, and touches nothing else.
+ *
+ * Loopback is denied WITH the rest. There is no gate socket to except: the
+ * daemon is a file reader. The one thing loopback costs is a test suite that
+ * starts its own localhost server, which is what {@link EgressAllowance.loopback}
+ * is for, and that allowance is an operator's decision recorded where it is
+ * used (`docs/sandboxed-exec.md` has the survey).
+ *
+ * ## The mechanism, and what is verified rather than assumed
+ *
+ * macOS only in this build: `/usr/bin/sandbox-exec` with a Sandbox Profile
+ * Language (SBPL) profile. It ships with every macOS, needs no privilege and no
+ * daemon, and every macOS agent sandbox in the field uses it. Linux
+ * (`bwrap --unshare-net`, `unshare --net`) is a stated follow-up rather than a
+ * silent omission: {@link detectSandbox} reports `supported: false` there and
+ * says so, and `docs/sandboxed-exec.md` carries the gap.
+ *
+ * Three Seatbelt behaviours are measured, not assumed. Each of them, got wrong,
+ * ships a profile that silently protects nothing, which is the worst artifact
+ * this design could produce:
+ *
+ * 1. `network-outbound` covers AF_UNIX connects as well as AF_INET. A bare
+ *    `(deny network-outbound)` kills local IPC — DNS's mDNSResponder socket
+ *    included — and the process dies before it can do anything. The unix
+ *    exception is mandatory.
+ * 2. `subpath` and `literal` filters match the kernel's RESOLVED path. On macOS
+ *    `/tmp` is a symlink to `/private/tmp`, so a profile naming `/tmp/x` denies
+ *    NOTHING. Every path is realpath-resolved before it is written into a
+ *    profile, and `tests/sandbox.test.ts` pins the unresolved spelling as the
+ *    no-op it is.
+ * 3. `sandbox-exec` execs through `execvp`, so a PATH lookup still happens
+ *    inside the wrapper — but a lookup that FAILS exits 71 (EX_OSERR), which
+ *    would be recorded as the child's own exit code. So {@link resolveExecutable}
+ *    does the lookup first and a command that cannot be found is never wrapped:
+ *    it reaches `spawnSync` unwrapped and fails as ENOENT exactly as it does
+ *    today.
+ *
+ * ## What it does not claim
+ *
+ * A sandboxed child can still WRITE files, including files a later unsandboxed
+ * process will run. That is the same laundering one step removed, and it is why
+ * `APPROVAL_HOOK_REQUIRE_SANDBOX` (which makes the hook insist that every
+ * code-running command wear the room) matters more than any single wrapper. It
+ * would be closed properly by running the whole SESSION under the profile,
+ * which this build cannot do: an agent harness needs the model API, and denying
+ * egress denies exactly that. A session-wide sandbox needs an allowlist
+ * reaching one host, which Seatbelt cannot express by hostname and which the
+ * prior art solves with a local proxy.
+ *
+ * Inbound sockets are not denied, so a child could in principle bind a port and
+ * wait to be contacted; that needs a peer that can reach this machine and is
+ * recorded here as a stated limit rather than an oversight. And the sandbox is
+ * not isolation: it is one capability removed from a process that otherwise has
+ * the ordinary powers of the session.
+ */
+/**
+ * The mechanisms this build knows. One, today.
+ *
+ * A union rather than a string so the Linux follow-up (APRV-193g) is an
+ * addition the compiler finds every site of, rather than a value that quietly
+ * flows through code written for Seatbelt.
+ */
+export declare const SANDBOX_MECHANISMS: readonly ["sandbox-exec"];
+export type SandboxMechanism = (typeof SANDBOX_MECHANISMS)[number];
+/**
+ * What an execution's record says about the room it ran in.
+ *
+ * Written to `execution.started` as `sandbox`, and it is a fact about the
+ * runtime's own behaviour rather than anything a caller asserted: three of the
+ * four values are computed here, and the fourth (`opted-out`) is a flag the
+ * operator typed, which is exactly why it is RECORDED — an opt-out nobody can
+ * see afterwards is an opt-out that costs nothing to take.
+ */
+export declare const SANDBOX_STATES: readonly [
+/** The child ran with outbound network denied. */
+"egress-denied", 
+/** `--no-sandbox` was passed. The child ran with the session's own network. */
+"opted-out", 
+/**
+ * The manual path: a human granted these exact bytes and the grant is the
+ * authority to reach the world. `approval run` on a token is the one door,
+ * and a door that denied egress would not be a door.
+ */
+"granted-egress", 
+/**
+ * This platform has no mechanism in this build (anything but macOS today).
+ * Recorded on every execution so an auditor can see exactly which runs were
+ * unprotected, rather than inferring it from the absence of a field.
+ */
+"unsupported"];
+export type SandboxState = (typeof SANDBOX_STATES)[number];
+/** What the machine can do, probed rather than inferred. */
+export interface SandboxDetection {
+    /** Can a command be run egress-denied here, right now? */
+    readonly available: boolean;
+    /** The mechanism that would be used, or `null`. */
+    readonly mechanism: SandboxMechanism | null;
+    /**
+     * Does this build have a mechanism for this platform AT ALL?
+     *
+     * The distinction from {@link available} is load-bearing and it is the one
+     * place this module is deliberately not maximally strict. `supported: false`
+     * means "nothing was ever written for this platform", which is a known gap
+     * with a follow-up task and a docs row. `supported: true, available: false`
+     * means "the mechanism that should be here did not work", which is a broken
+     * promise, and the callers treat the two differently: the first proceeds and
+     * records `unsupported`, the second refuses to run the command at all.
+     */
+    readonly supported: boolean;
+    /** Can loopback be carved back in? (Seatbelt yes; a Linux netns cannot.) */
+    readonly loopback: boolean;
+    /** Why, when {@link available} is false. Empty otherwise. */
+    readonly reason: string;
+}
+/** What the profile lets through. Everything absent here is denied. */
+export interface EgressAllowance {
+    /**
+     * Allow connections to `localhost:*`.
+     *
+     * Off by default. The gate needs nothing: its IPC is a file. This exists for
+     * the one legitimate case the survey found, a test suite that starts its own
+     * server, and it is a real widening — a loopback port is a port, and anything
+     * listening on one is reachable from inside.
+     */
+    readonly loopback: boolean;
+    /**
+     * Absolute paths whose CONTENTS the child may not read. Resolved before they
+     * reach the profile. Directories deny their whole subtree.
+     */
+    readonly denyRead: readonly string[];
+}
+/** The default: nothing allowed, nothing denied beyond the network. */
+export declare const DENY_ALL_EGRESS: EgressAllowance;
+/**
+ * The files beside a log that hold credential material, for the profile's
+ * `denyRead`.
+ *
+ * Named individually rather than by denying the whole approval home. The home
+ * also holds the log, the payload store and the queue, and a child that could
+ * not read the log could not read the decision that authorized it. What is
+ * denied is what a laundering script would want: the vault's ciphertext, the
+ * environment source map that says where the secrets come from, and the
+ * per-request private keys that seal tokens.
+ *
+ * This is defence in depth over material that is already encrypted or already
+ * useless without the passphrase — the load-bearing custody control is that
+ * the passphrase is not in the child's environment at all (APRV-205). It is
+ * worth having on the one platform where it costs nothing.
+ */
+export declare function credentialPathsFor(logPath: string): string[];
+/**
+ * Forces the unavailable branch. A STRICTNESS increase in every caller — the
+ * run path refuses and the session launcher refuses — so a forged value cannot
+ * widen anything, which is what keeps it clear of SPEC.md §11.1 invariant 4.
+ */
+export declare const FORCE_UNAVAILABLE_ENV = "APPROVAL_SANDBOX_FORCE_UNAVAILABLE";
+/**
+ * Treat an unsupported platform as a broken promise rather than a known gap:
+ * with this set, a machine with no mechanism refuses instead of proceeding.
+ * The same one-way property holds — it can only ever refuse more.
+ */
+export declare const REQUIRE_SANDBOX_ENV = "APPROVAL_SANDBOX_REQUIRED";
+export interface DetectOptions {
+    readonly platform?: NodeJS.Platform;
+    readonly env?: NodeJS.ProcessEnv;
+}
+/**
+ * What this machine can do. Cached for the default call, because every verb
+ * that asks would otherwise spawn a probe per invocation, and the answer cannot
+ * change inside one process.
+ */
+export declare function detectSandbox(options?: DetectOptions): SandboxDetection;
+/** Testing seam: forget the cached probe. Never called by the runtime. */
+export declare function resetSandboxDetection(): void;
+/**
+ * A path as the KERNEL will see it.
+ *
+ * A path that does not exist yet cannot be resolved, so its directory is
+ * resolved and the name re-joined. A profile naming an unresolved path denies
+ * nothing at all and reports no error, which is the failure this function
+ * exists to prevent.
+ */
+export declare function resolveForProfile(path: string): string;
+/**
+ * The SBPL profile.
+ *
+ * `(allow default)` first, then the denial: SBPL takes the LAST matching rule,
+ * so exceptions are written after the deny. This is deliberately a deny-LIST
+ * and not the `(deny default)` posture a true isolation sandbox takes. The
+ * property being enforced is egress, and a deny-default profile spends itself
+ * re-allowing dyld, `/dev/urandom`, the process's own binary and every
+ * temporary directory, which is a different task with a different failure mode
+ * (and a much larger chance of breaking ordinary development, which is how a
+ * control gets switched off).
+ */
+export declare function seatbeltProfile(allowance: EgressAllowance): string;
+/** The argv to spawn, and the temporary directory the caller must remove. */
+export interface WrappedSpawn {
+    readonly command: string;
+    readonly args: string[];
+    /** A directory holding the profile file; remove it once the child is gone. */
+    readonly cleanup: string;
+    /** What the caller records. */
+    readonly mechanism: SandboxMechanism;
+}
+/**
+ * Resolve a command the way `execvp` would, and say when it cannot be found.
+ *
+ * Done HERE rather than left to the wrapper for the reason in the header: an
+ * execvp failure inside `sandbox-exec` exits 71, and 71 recorded as the child's
+ * exit code is a lie about a command that never ran. A command that does not
+ * resolve is returned as `null`, and the caller spawns it unwrapped so the
+ * ENOENT surfaces exactly as it does with no sandbox in the picture.
+ */
+export declare function resolveExecutable(command: string, env?: NodeJS.ProcessEnv): string | null;
+/**
+ * Build the wrapped spawn for `argv`.
+ *
+ * Writes the profile to a fresh 0600 file under a private directory: the
+ * profile names the paths whose reads are denied, which is not secret, but a
+ * world-writable profile would be a profile another process could rewrite
+ * between this write and the exec.
+ */
+export declare function wrapForSandbox(mechanism: SandboxMechanism, command: string, args: readonly string[], allowance?: EgressAllowance): WrappedSpawn;
+export interface PostureInput {
+    /** `--no-sandbox` was passed. */
+    readonly optedOut: boolean;
+    /**
+     * A human's grant over these exact bytes is in the caller's hand (the manual
+     * path presented a token). The grant IS the authority to reach the world.
+     *
+     * Not a self-report that widens anything: a token that does not verify runs
+     * no command at all, so the loosening is reachable only by holding something
+     * a human minted. SPEC.md §11.1 invariant 4 is about a declaration the
+     * executing party authors; this is a secret it cannot author.
+     */
+    readonly granted: boolean;
+    /** The machine's capability. */
+    readonly detection: SandboxDetection;
+    /** `APPROVAL_SANDBOX_REQUIRED=1` promotes an unsupported platform to a refusal. */
+    readonly requireSupported?: boolean;
+}
+export type SandboxPosture = {
+    readonly kind: "apply";
+    readonly state: "egress-denied";
+    readonly mechanism: SandboxMechanism;
+} | {
+    readonly kind: "skip";
+    readonly state: Exclude<SandboxState, "egress-denied">;
+} | {
+    readonly kind: "refuse";
+    readonly reason: string;
+};
+/**
+ * What to do about the sandbox for one execution.
+ *
+ * Total, pure, and exhaustively testable: it reads a detection and two booleans
+ * and returns one of three answers. The ORDER of the branches is the policy —
+ * a broken mechanism refuses before an opt-out is considered, so `--no-sandbox`
+ * on a machine whose sandbox is broken is still a refusal rather than a way to
+ * turn the noise off.
+ */
+export declare function sandboxPosture(input: PostureInput): SandboxPosture;
+/** Is `APPROVAL_SANDBOX_REQUIRED` set on this environment? */
+export declare function sandboxRequired(env?: NodeJS.ProcessEnv): boolean;