approval-md 0.0.1 → 0.2.0

package/dist/src/daemon/prune.js

@@ -0,0 +1,376 @@
+/**
+ * Payload retention pruning — the enforcement half of amended SPEC.md §5.2
+ * (APRV-38's vocabulary, APRV-41's daemon).
+ *
+ * > "A payload is prunable once the action it is bound to has been in a terminal
+ * > state (`executed`, `rejected`, `expired`, `revoked`) for longer than the
+ * > duration. A payload whose action is not terminal is never prunable, at any
+ * > age […]. Orphaned payloads (bytes with no recorded binding) are prunable
+ * > regardless of the key. […] Pruning is performed by the daemon and by nothing
+ * > else, and each removal appends a `payload.pruned` event, so a log states what
+ * > its store no longer holds."
+ *
+ * ## Write-ahead, always in that order
+ *
+ * For every file this module removes, the `payload.pruned` event lands in the
+ * log **first** and the `unlink` follows. The ordering is the whole design: a
+ * crash between the two leaves a file on disk that the log already says is gone,
+ * which the next tick completes by unlinking it and appending nothing further
+ * ({@link PrunePlan.completions}). The opposite order would leave the other
+ * failure — bytes deleted with no record of the deletion — which is the one
+ * outcome a store holding the material evidence of what a human approved cannot
+ * afford. Deleting evidence is acceptable; deleting it silently is not.
+ *
+ * Idempotence needs no remembered state: a hash that already carries a
+ * `payload.pruned` event is never given a second one, and the plan is re-derived
+ * from the verified log on every tick.
+ *
+ * ## Terminal time comes from the log, never from the filesystem
+ *
+ * The clock that decides whether retention has elapsed reads the timestamp of the
+ * event that made the action terminal (`execution.completed`, `approval.rejected`,
+ * `approval.revoked`, `approval.expired`). File mtimes are not evidence: they are
+ * rewritten by a copy, a checkout, a backup restore, or an `rsync`, and pruning on
+ * them would let a routine filesystem operation decide when approval evidence
+ * disappears.
+ *
+ * A **lazily** expired request (the TTL has arithmetically lapsed but no
+ * `approval.expired` record exists) is deliberately not terminal here. The
+ * daemon's own TTL sweep appends that event on the same tick; the payload becomes
+ * prunable once the log says so, and retention is then measured from the recorded
+ * moment rather than from one this module computed for itself.
+ *
+ * `execution.failed` is likewise not terminal: a failed action may be retried
+ * against the very bytes in question, and loop escalation (SPEC.md §10.2) exists
+ * precisely because failures recur.
+ *
+ * ## The orphan rule, resolved conservatively (flagged for review)
+ *
+ * §5.2 says orphaned payloads are "prunable regardless of the key", which reads
+ * as though orphans could be swept even with `payload_retention` absent. APRV-41's
+ * acceptance criteria say the absent key means no pruning at all. This module
+ * takes the strictest reading that satisfies both:
+ *
+ * - **`payload_retention` absent: the pruning subsystem does not run.** Nothing is
+ *   deleted, orphan or not, and no `payload.pruned` is appended. Retention is an
+ *   operator's explicit choice to forget, and an operator who never made it never
+ *   asked this runtime to delete anything.
+ * - **`payload_retention` present: orphans are prunable at any age**, which is
+ *   what "regardless of the key" then means — the duration governs bound payloads
+ *   and does not gate residue nothing ever bound.
+ *
+ * An orphan is a file whose hash appears in **no** log record other than a
+ * `payload.pruned` (head-moved residue: the gate stored the bytes, its append was
+ * refused, and no request ever declared them). A hash mentioned by any other
+ * record is bound, and a binding this module cannot attribute to an action key is
+ * treated as live rather than as an orphan — fail closed in both directions.
+ *
+ * ## Nothing else here decides anything
+ *
+ * Which hashes the log already binds, and which it already says are pruned, is
+ * `core/payload-census.ts`'s — the same computation the reporting surfaces read,
+ * so what a reader is shown and what this module would delete can never drift
+ * apart. Approval state per action is `core/state.ts`'s `requestState`; the append is
+ * `core/log.ts`'s `appendEvent` with `expectedHead` (compare-and-append, SPEC.md
+ * §11.1 invariant 5); the unlink is `core/payload-store.ts`'s. The timestamp on
+ * every `payload.pruned` is the runtime's, read from the injected clock at the
+ * write boundary, and the actor is `system:daemon` — a party under oversight must
+ * never be able to author either.
+ */
+import { tick as readClock } from "../core/clock.js";
+import { appendEvent } from "../core/log.js";
+import { isPayloadHash } from "../core/payload.js";
+import { bindingsOf, prunedHashes } from "../core/payload-census.js";
+import { listStoredPayloadHashes, payloadStoreDirFor, removeStoredPayload, } from "../core/payload-store.js";
+import { loadPolicy, parseDuration } from "../core/policy-load.js";
+import { readVerifiedRecords, requestState } from "../core/state.js";
+/**
+ * SPEC.md §8 and `event.schema.json`: `payload.pruned` carries a `system:` actor.
+ * Declared here rather than imported from `daemon.ts` so the pruner has no
+ * dependency on the loop that calls it.
+ */
+export const PRUNE_ACTOR = "system:daemon";
+/** A fresh empty plan each time: a shared one could be mutated by a caller. */
+function emptyPlan() {
+    return { candidates: [], completions: [] };
+}
+/**
+ * When (and whether) `actionKey` became terminal, per the log alone.
+ *
+ * `ttlMs` is passed as `null` to `requestState` on purpose: lazy expiry is
+ * arithmetic this module refuses to prune on (see the module header), so the only
+ * expiry that counts is one `approval.expired` recorded.
+ *
+ * A key whose request is live (`requested`) is never terminal, even when an older
+ * execution completed: a fresh request binds to those bytes again and the earlier
+ * outcome does not release them.
+ */
+function terminalOf(records, actionKey, nowIso) {
+    const derived = requestState(records, actionKey, nowIso, null);
+    // A live request binds the bytes, whatever else the key's history holds.
+    if (derived.state === "requested")
+        return null;
+    // `none` is not itself terminal: an action that was registered and never
+    // requested still declares these bytes, and a request may yet be made for it.
+    // It becomes terminal only by executing (the autonomous path, which requests
+    // nothing), which the `execution.completed` branch below picks up.
+    const seen = [];
+    const decision = derived.decision;
+    if (decision === "rejected" || decision === "revoked") {
+        if (derived.decisionTs !== null)
+            seen.push({ state: decision, ts: derived.decisionTs });
+    }
+    if (decision === "expired" && derived.expiredByEvent && derived.decisionTs !== null) {
+        seen.push({ state: "expired", ts: derived.decisionTs });
+    }
+    if (derived.execution.completed !== null) {
+        const completed = records.find((record) => record.seq === derived.execution.completed);
+        if (completed !== undefined)
+            seen.push({ state: "executed", ts: completed.ts });
+    }
+    let terminal = null;
+    for (const entry of seen) {
+        const at = Date.parse(entry.ts);
+        if (Number.isNaN(at))
+            continue;
+        if (terminal === null || at > Date.parse(terminal.ts))
+            terminal = entry;
+    }
+    return terminal;
+}
+/**
+ * What may be pruned right now. Pure: no I/O, no clock, no policy loading.
+ *
+ * `retentionMs` is `null` when the policy declares no `payload_retention` — or
+ * when the policy could not be loaded at all, which fails closed to the same
+ * answer. Either way the plan is empty: the subsystem does not run.
+ *
+ * `nowIso` is the evaluation moment, injected. A pruner that read the clock
+ * itself could not be replayed, and retention arithmetic that cannot be replayed
+ * cannot be audited.
+ */
+export function planPrune(records, presentHashes, nowIso, retentionMs) {
+    if (retentionMs === null)
+        return emptyPlan();
+    const now = Date.parse(nowIso);
+    // An unparseable evaluation moment cannot be compared against anything, so
+    // nothing is old enough for anything.
+    if (Number.isNaN(now))
+        return emptyPlan();
+    const pruned = prunedHashes(records);
+    const bindings = bindingsOf(records);
+    const candidates = [];
+    const completions = [];
+    for (const hash of [...presentHashes].sort()) {
+        if (!isPayloadHash(hash))
+            continue;
+        if (pruned.has(hash)) {
+            completions.push(hash);
+            continue;
+        }
+        const binding = bindings.get(hash);
+        if (binding === undefined) {
+            candidates.push({
+                hash,
+                reason: "orphaned",
+                actionKey: null,
+                task: null,
+                terminalState: null,
+                terminalTs: null,
+            });
+            continue;
+        }
+        // A binding nobody can attribute to an action key has no derivable terminal
+        // state, so it is treated as live forever.
+        if (binding.unattributed || binding.actionKeys.size === 0)
+            continue;
+        // EVERY action bound to these bytes must have released them. One live
+        // request among ten settled ones keeps the payload.
+        let latest = null;
+        let latestKey = null;
+        let live = false;
+        for (const key of [...binding.actionKeys].sort()) {
+            const terminal = terminalOf(records, key, nowIso);
+            if (terminal === null) {
+                live = true;
+                break;
+            }
+            if (latest === null || Date.parse(terminal.ts) > Date.parse(latest.ts)) {
+                latest = terminal;
+                latestKey = key;
+            }
+        }
+        if (live || latest === null || latestKey === null)
+            continue;
+        if (!(now - Date.parse(latest.ts) > retentionMs))
+            continue;
+        candidates.push({
+            hash,
+            reason: "payload_retention",
+            actionKey: latestKey,
+            task: taskOf(records, latestKey),
+            terminalState: latest.state,
+            terminalTs: latest.ts,
+        });
+    }
+    return { candidates, completions };
+}
+/** The task an action key was last seen under, for the event's `task` field. */
+function taskOf(records, actionKey) {
+    let task = null;
+    for (const record of records) {
+        if (record.action_key === actionKey && typeof record.task === "string")
+            task = record.task;
+    }
+    return task;
+}
+/**
+ * Read `payload_retention` from the policy in force right now.
+ *
+ * Fails closed to `null` exactly as the daemon's TTL read does: a policy that
+ * cannot be loaded declares no retention, so nothing is pruned on its behalf. An
+ * unparseable duration is likewise `null` — the schema's duration pattern makes
+ * that unreachable through a validated policy, and a retention rule this module
+ * cannot read is not one it may guess at.
+ */
+export function retentionMsOf(policy, schemaDir) {
+    const where = policy.file !== undefined ? { file: policy.file } : { dir: policy.dir ?? process.cwd() };
+    if (schemaDir !== undefined)
+        where.schemaDir = schemaDir;
+    const load = loadPolicy(where);
+    if (!load.ok)
+        return null;
+    const text = load.policy.payload_retention;
+    if (text === undefined)
+        return null;
+    return parseDuration(text);
+}
+/**
+ * One pruning pass: plan, append, unlink, repeat.
+ *
+ * The log is re-read before each append rather than once for the pass, because
+ * each append moves the head the next one is compared against and because a CLI
+ * verb may have appended in between. `expectedHead` therefore always names the
+ * head the decision was made from; a `head-moved` refusal drops the candidate and
+ * the next tick re-derives it.
+ *
+ * Nothing is retried in place, and no state survives the call.
+ */
+export function prunePayloads(options) {
+    const retentionMs = retentionMsOf(options.policy, options.schemaDir);
+    const report = {
+        retentionMs,
+        appended: [],
+        pruned: [],
+        removed: [],
+        completed: [],
+        warnings: [],
+    };
+    if (retentionMs === null)
+        return report;
+    const storeDir = options.storeDir ?? payloadStoreDirFor(options.logPath);
+    const readOptions = options.schemaDir === undefined ? {} : { schemaDir: options.schemaDir };
+    const clockOptions = options.clock === undefined ? {} : { clock: options.clock };
+    // Hashes this pass has already acted on, so a plan re-derived after an append
+    // cannot hand the same file back twice within one call.
+    const handled = new Set();
+    for (;;) {
+        const read = readVerifiedRecords(options.logPath, readOptions);
+        if (!read.ok) {
+            // A log that does not verify stops the *daemon* (its own tick refuses to
+            // continue); here it simply means this pass plans nothing. Pruning never
+            // appends onto a chain it could not read.
+            report.warnings.push({ code: "log-unreadable", message: read.message });
+            return report;
+        }
+        const now = readClock(clockOptions);
+        const plan = planPrune(read.records, listStoredPayloadHashes(storeDir), now, retentionMs);
+        // Crash-window completions first: they append nothing, so they cannot move
+        // the head out from under the candidate below.
+        for (const hash of plan.completions) {
+            if (handled.has(hash))
+                continue;
+            handled.add(hash);
+            const removal = removeStoredPayload(storeDir, hash);
+            if (!removal.ok) {
+                report.warnings.push({ code: "unlink-failed", message: removal.message });
+                continue;
+            }
+            report.completed.push(hash);
+            if (removal.existed)
+                report.removed.push(hash);
+        }
+        const candidate = plan.candidates.find((entry) => !handled.has(entry.hash));
+        if (candidate === undefined)
+            return report;
+        handled.add(candidate.hash);
+        const payload = {
+            payload_hash: candidate.hash,
+            reason: candidate.reason,
+        };
+        if (candidate.reason === "payload_retention") {
+            payload["retention"] = durationText(retentionMs);
+            if (candidate.terminalState !== null)
+                payload["terminal_state"] = candidate.terminalState;
+            if (candidate.terminalTs !== null)
+                payload["terminal_ts"] = candidate.terminalTs;
+        }
+        const input = {
+            ts: now,
+            event: "payload.pruned",
+            actor: PRUNE_ACTOR,
+            payload,
+        };
+        if (candidate.task !== null)
+            input.task = candidate.task;
+        if (candidate.actionKey !== null)
+            input.action_key = candidate.actionKey;
+        const appended = appendEvent(options.logPath, input, {
+            ...readOptions,
+            expectedHead: read.head,
+        });
+        if (!appended.ok) {
+            // WRITE-AHEAD: the file stays. An unlogged deletion is the one outcome
+            // this module exists to prevent, so a refused append prunes nothing.
+            report.warnings.push({
+                code: "append-refused",
+                message: `payload.pruned for ${candidate.hash} was not appended (${appended.error.code}): ${appended.error.message}; the file was left in place`,
+            });
+            continue;
+        }
+        report.appended.push(candidate);
+        const removal = removeStoredPayload(storeDir, candidate.hash);
+        if (!removal.ok) {
+            // The event is in the log and the bytes are still on disk: the log is
+            // ahead of the store, which is the safe direction. The next tick sees the
+            // file as a completion and unlinks it without a second event.
+            report.warnings.push({ code: "unlink-failed", message: removal.message });
+            continue;
+        }
+        report.removed.push(candidate.hash);
+        report.pruned.push({ candidate, seq: appended.record.seq });
+    }
+}
+/**
+ * The retention duration as the policy would have written it, for the event.
+ *
+ * Reconstructed from milliseconds rather than carried through from the policy
+ * text so the value recorded is the one the arithmetic used: a log that says
+ * `30d` when the code compared against something else would be worse than a log
+ * that says nothing.
+ */
+function durationText(ms) {
+    const units = [
+        [604_800_000, "w"],
+        [86_400_000, "d"],
+        [3_600_000, "h"],
+        [60_000, "m"],
+        [1_000, "s"],
+    ];
+    for (const [scale, unit] of units) {
+        if (ms % scale === 0 && ms >= scale)
+            return `${String(ms / scale)}${unit}`;
+    }
+    return `${String(ms)}ms`;
+}
+//# sourceMappingURL=prune.js.map

package/dist/src/daemon/prune.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prune.js","sourceRoot":"","sources":["../../../src/daemon/prune.ts"],"names":[],"mappings":"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"}

package/dist/src/mcp/http.d.ts

@@ -0,0 +1,113 @@
+/**
+ * `approval mcp serve --http` — the §10.5 wrapper over the MCP streamable-HTTP
+ * transport, one session per connection (APRV-174).
+ *
+ * The stdio server of `./server.ts` serves ONE client through the pipe the
+ * operator handed it: one process, one connection, one identity. This module
+ * changes exactly one thing about that picture, the transport, and it changes it
+ * so that several clients can be served at once. Everything else is the same
+ * code: the tool list is still {@link createApprovalMcpServer}'s, a tool call
+ * still builds an argv and calls the function the CLI dispatches to, and a
+ * refusal is still the CLI's refusal.
+ *
+ * ## One `Server` + one transport per session
+ *
+ * The SDK's `StreamableHTTPServerTransport` is stateful per session: it mints an
+ * `mcp-session-id` at `initialize`, stamps it on every response, and expects the
+ * client to send it back. This module owns one `node:http` listener and a map
+ * from that id to the `{ Server, transport, actor }` triple it belongs to. An
+ * initialize POST with no session header opens a triple; every later request is
+ * routed by the header; the triple is dropped when its transport closes (a
+ * DELETE, or the socket going away).
+ *
+ * ## Identity is minted BEFORE the transport exists, per session
+ *
+ * `cli/mcp.ts` settles identity before it constructs the stdio transport,
+ * because "a server that connected first and refused later would be a server a
+ * client had already spoken to". That property is preserved verbatim here, once
+ * per session: {@link mintSessionActor} runs before the `Server`/transport pair
+ * is built, and its result is the `actor` that pair closes over for its whole
+ * life.
+ *
+ * **Nothing a client sends reaches that actor.** There is no code path from a
+ * header, a URL, an `initialize` payload's `clientInfo`, or a tool argument into
+ * the identity a session runs as. `clientInfo.name` is a label a client chose
+ * for itself, and SPEC.md §11 says a self-reported field never reduces scrutiny;
+ * an identity a caller could name would be an identity a caller could escalate,
+ * so the server names it:
+ *
+ * - plain `--http`: every session runs as the operator's own `--as` /
+ *   `APPROVAL_AGENT` actor, which is the stdio behavior with more connections;
+ * - `--guest`: every session mints its own `agent:guest-<6 hex>`, so the log,
+ *   the budgets and the refusals see one stranger per connection rather than one
+ *   crowd. That is the whole reason this scheme exists — an actor a limit can be
+ *   keyed on.
+ *
+ * ## Loopback, caps, and no authentication whatsoever
+ *
+ * This listener authenticates nobody, exactly like `channels/web.ts`. It binds
+ * `127.0.0.1` unless the operator writes another host out in full, and the CLI
+ * prints a loud banner when they do; the deployment this was built for
+ * (SPEC.md §10.5, the crowd demo) is a tunnel in front of a loopback bind, where
+ * the tunnel is the thing that faces the network.
+ *
+ * Two caps bound what a stranger can spend: {@link MAX_CONCURRENT_SESSIONS} live
+ * at once and {@link MAX_LIFETIME_SESSIONS} over the process's life. Over either
+ * one, an initialize is refused with a plain HTTP 503 naming the reason, before
+ * a session exists.
+ */
+import { type ServerPaths } from "./server.js";
+/** Live sessions this listener will hold at once. */
+export declare const MAX_CONCURRENT_SESSIONS = 20;
+/** Sessions this listener will open over the life of the process. */
+export declare const MAX_LIFETIME_SESSIONS = 200;
+/** Largest request body accepted, in bytes. A tool call is small. */
+export declare const MAX_BODY_BYTES: number;
+/** The prefix every guest session's actor carries. */
+export declare const GUEST_ACTOR_PREFIX = "agent:guest-";
+/**
+ * Mint one session's actor.
+ *
+ * `used` is the set of actors this listener has already handed out, for the life
+ * of the process rather than of the live map: two sessions that shared an actor
+ * would share a budget and a refusal history, which is the one thing this scheme
+ * exists to keep apart. Six hex digits is short enough to read out loud in a
+ * demo, so the collision check is not decoration.
+ */
+export declare function mintSessionActor(used: ReadonlySet<string>): string;
+export interface HttpServeOptions extends ServerPaths {
+    /**
+     * The actor every session runs as, or `null` under {@link guest}, where each
+     * session mints its own. Already validated by `resolveAgentActor`.
+     */
+    actor: string | null;
+    /**
+     * Guest mode: per-session identity (APRV-174), plus the narrowed tool list,
+     * the `mcp-guest-restricted` call-time refusal and the `wait` clamp that
+     * `./server.ts` applies (APRV-175).
+     */
+    guest: boolean;
+    /** Interface to bind. Defaults to `127.0.0.1`; the CLI owns the widening decision. */
+    host?: string;
+    /** TCP port. `0` asks the kernel for an ephemeral one, which is what tests use. */
+    port: number;
+    /** Session lifecycle lines. The CLI passes stderr; stdout is never written to. */
+    notice?: (text: string) => void;
+}
+export interface McpHttpServer {
+    /** The interface actually bound. */
+    readonly host: string;
+    /** The port actually bound, resolved after an ephemeral request. */
+    readonly port: number;
+    /** Actors of the live sessions, in open order. Diagnostics and tests. */
+    sessionActors(): string[];
+    /** How many sessions this listener has opened, ever. */
+    lifetimeSessions(): number;
+    /** Close every session and the listener. Idempotent. */
+    close(): Promise<void>;
+}
+/**
+ * Start the HTTP MCP listener. Resolves once it is bound and its real port is
+ * known; rejects when the bind fails, so the CLI can report it and exit.
+ */
+export declare function serveApprovalMcpHttp(options: HttpServeOptions): Promise<McpHttpServer>;