approval-md 0.1.0 → 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;

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

@@ -0,0 +1,165 @@
+/**
+ * Sealed token delivery (amended SPEC.md §6.3, §10.4, §11.1 — APRV-105).
+ *
+ * The problem this closes is a handover, not an authorization. A token is minted
+ * at exactly one site — the grant path of `core/gate.ts` — and spent at another,
+ * `approval run`. The two are different processes, and until now the only
+ * transport between them was a human with a clipboard: `approval grant` (or the
+ * Telegram listener) printed the raw token on ITS stdout, and `approval wait`,
+ * which reads only the verified log, had nothing to return because the log
+ * carries hashes. On one machine that is a paste. Across two — the listener on a
+ * laptop, the agent elsewhere, the log synced through git — it is a paste that
+ * cannot happen.
+ *
+ * So the requester publishes an ADDRESS. `approval request` mints an ephemeral
+ * X25519 keypair, keeps the private half in a 0600 file beside the log, and puts
+ * the public half on `approval.requested` as `token_recipient_key`. On grant the
+ * mint site seals the raw token to that key and records the ciphertext beside
+ * the digest as `token_sealed`. `approval wait` opens it with the local private
+ * key and hands the token back to the process that asked for it.
+ *
+ * ## The keypair ADDRESSES; it does not AUTHORIZE
+ *
+ * The obvious objection is that the agent creates both halves of the key, so how
+ * does this control the agent? It does not, and it does not need to. The four
+ * properties that make an action human-gated are untouched:
+ *
+ * - a token exists only after a human grant (one mint site);
+ * - it binds to the exact payload bytes;
+ * - it is single-use, and consumption is an `execution.started` in the log;
+ * - credentials answer only to tokens.
+ *
+ * A keypair cannot mint a token, forge a grant, alter the bound payload, or
+ * reuse a spent one. What changes is who can READ a minted token: the requesting
+ * process instead of the human's clipboard, which is where the human was
+ * carrying it anyway. A malicious agent that substitutes a key substitutes it
+ * only in its OWN request, which the approver sees and approves as that agent's
+ * request; identity spoofing is exactly as it was in SPEC.md §11, where the
+ * trust boundary is the machine.
+ *
+ * What is lost, stated plainly: the marginal ability to approve on the phone and
+ * then withhold delivery.
+ *
+ * ## Residual risk, stated plainly
+ *
+ * Someone who steals the private-key file AND reads the log can recover an
+ * unspent token inside its TTL. That window equals the terminal-paste window
+ * today, and it closes at consume or at TTL, whichever comes first — this module
+ * unlinks the key file at both. The ciphertext lives in a public, permanent log,
+ * so the seal must be sound and the token short-lived; it already is.
+ *
+ * ## The construction
+ *
+ * X25519 ECDH to a fresh ephemeral sender key, HKDF-SHA-256 to a 32-byte AEAD
+ * key, AES-256-GCM with a fresh 12-byte nonce. All from `node:crypto`; no
+ * dependency is added. The sender's ephemeral public key travels with the
+ * ciphertext, so the recipient needs nothing but its own private key and the
+ * record. The HKDF `info` binds the ciphertext to this scheme and to the action
+ * it was minted for, so a seal lifted from one grant cannot be replayed as
+ * another's even by someone holding both key files.
+ */
+/** The payload key carrying the requester's public key on `approval.requested`. */
+export declare const RECIPIENT_KEY_FIELD = "token_recipient_key";
+/** The payload key carrying the sealed token on `approval.granted`. */
+export declare const SEALED_TOKEN_FIELD = "token_sealed";
+/**
+ * The payload key on `approval.requested` saying the requester will consume its
+ * own grant in its own process (APRV-211), so the raw token is delivered ONLY
+ * through the seal and is never returned to the granting surface.
+ *
+ * A fact about delivery, recorded where every other delivery fact is recorded.
+ * It authorizes nothing and relaxes nothing: the token is still minted only by
+ * a human's grant, still bound to the payload bytes, still single-use. What it
+ * removes is a reader — a terminal that was being handed a live credential it
+ * had no use for.
+ */
+export declare const SELF_DELIVERY_FIELD = "token_delivery_self";
+/** `.approval/keys/`, the sibling of the log directory the private keys live in. */
+export declare const KEY_STORE_DIRNAME = "keys";
+/** The scheme identifier recorded inside every seal. One value in v0.1. */
+export declare const SEAL_ALG = "x25519-hkdf-sha256/aes-256-gcm";
+/** The key store for a log path, by the same rule the payload store uses. */
+export declare function keyStoreDirFor(logPath: string): string;
+/**
+ * The file one action key's private key lives in.
+ *
+ * The action key is used verbatim wherever it is already a safe file name, and
+ * percent-encoded elsewhere. Percent-encoding is injective, so two distinct
+ * action keys can never name one file — which matters more than readability,
+ * since a collision would hand one action's token to another. The common case
+ * (`task-042:chaser:2026-08-04`) survives unchanged, so the directory listing
+ * still reads as the action keys it holds.
+ */
+export declare function keyPath(keyDir: string, actionKey: string): string;
+/** A freshly minted recipient keypair: the public half travels, the private stays. */
+export interface RecipientKeypair {
+    /** Base64 DER SPKI. What rides on `approval.requested`. */
+    publicKey: string;
+    /** Base64 DER PKCS#8. What is written 0600 and never leaves the machine. */
+    privateKey: string;
+}
+/** Mint an ephemeral X25519 keypair for one request. */
+export declare function mintRecipientKeypair(): RecipientKeypair;
+/** Is this a value that could be a recipient public key? Shape only. */
+export declare function isRecipientKey(value: unknown): value is string;
+export type KeyWriteResult = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Write one private key, atomically and 0600.
+ *
+ * The mode is set by `openSync`'s mode argument on a file created `wx`, so the
+ * key never exists at a wider mode even for an instant — a `chmod` after the
+ * fact would leave a window in which any process on the machine could read it.
+ * The rename is atomic, so a reader either sees the whole key or no file.
+ */
+export declare function writePrivateKey(keyDir: string, actionKey: string, privateKey: string): KeyWriteResult;
+/** The private key for an action, or `null` when this machine holds none. */
+export declare function readPrivateKey(keyDir: string, actionKey: string): string | null;
+/**
+ * Remove one action's private key. Idempotent and never throws.
+ *
+ * Called at every death of the authorization it addresses: consumption, expiry,
+ * revocation. A key that outlived its grant would be a decryption capability for
+ * a ciphertext that is in the log forever, kept for no reason at all.
+ */
+export declare function forgetPrivateKey(keyDir: string, actionKey: string): boolean;
+/** What `approval.granted` carries beside `token_sha256`. */
+export interface SealedToken {
+    /** The scheme. One value in v0.1; present so a reader never has to guess. */
+    alg: string;
+    /** The sender's ephemeral X25519 public key, base64 DER SPKI. */
+    epk: string;
+    /** The AES-GCM nonce, base64. Fresh for every seal. */
+    nonce: string;
+    /** Ciphertext, base64. */
+    ct: string;
+    /** The GCM authentication tag, base64. */
+    tag: string;
+}
+/**
+ * Seal a raw token to a recipient public key.
+ *
+ * Returns `null` for a recipient key that cannot be parsed. A grant is not
+ * refused over an unusable recipient key: the authorization is the human's
+ * decision and stands, the digest still binds it, and the raw token is still
+ * printed once on the granting surface. What fails is the convenience, and a
+ * convenience must never be able to void a human's yes.
+ */
+export declare function sealToken(token: string, recipientPublicKey: string, actionKey: string): SealedToken | null;
+/** Read a `token_sealed` payload value as a {@link SealedToken}, or `null`. */
+export declare function asSealedToken(value: unknown): SealedToken | null;
+/**
+ * Open a sealed token with a recipient private key.
+ *
+ * Returns `null` for anything that does not authenticate: a wrong key, a
+ * tampered ciphertext, a seal minted for a different action key. There is one
+ * failure, deliberately: distinguishing "wrong key" from "wrong ciphertext"
+ * would be an oracle, and the caller's response to either is identical — fall
+ * back to the raw token the granting surface printed.
+ */
+export declare function openSealedToken(sealed: SealedToken, recipientPrivateKey: string, actionKey: string): string | null;