approval-md 0.2.0 → 0.4.0

package/dist/src/serve/arguments.js

@@ -0,0 +1,228 @@
+/**
+ * What a caller on this transport may say: nothing about the filesystem
+ * outside the store, and nothing shaped like a flag where a value belongs
+ * (APRV-421, review findings 3 and 1).
+ *
+ * ## The two holes this closes
+ *
+ * **A published path flag is a filesystem oracle.** `approval mcp serve`
+ * publishes `--log`, `--dir` and `--policy` on the verbs that accept them and
+ * injects the operator's pins only where the operator passed any. On a pipe
+ * the operator handed the server that is harmless: the party at the other end
+ * is the party who started it. Over HTTP the party at the other end is a
+ * sandboxed harness on another machine, and the same flag answers questions
+ * about files it cannot see.
+ *
+ * **A positional is a flag if it starts with a dash.** `buildArgv` emits
+ * positionals FIRST and verbatim, and `parseFlags` reads any token beginning
+ * with `-` as a flag. So a caller refused `{"flags":{"--payload":"…"}}` could
+ * write `{"positionals":["--payload","/tmp/secret","t1"]}` and reach the same
+ * flag through the front door — including the `--payload=/tmp/secret`
+ * spelling, which `parseFlags` splits on `=`. Positionals are VALUES. One that
+ * looks like a flag is refused rather than escaped, because escaping is a
+ * thing to get subtly wrong once and lose.
+ *
+ * `trailing` needs no such rule and deliberately does not get one. `buildArgv`
+ * always emits `--` before it, and `parseFlags` STOPS at `--`, pushing the
+ * remainder into positionals without reading a single token as a flag. A
+ * blanket refusal of dash-leading trailing elements would instead break the
+ * one agent verb that needs them: `hook classify -- git push -f` classifies a
+ * command line, and command lines have flags. The invariant that makes this
+ * safe is pinned by a test rather than assumed here.
+ *
+ * ## The rule, by scope
+ *
+ * **Both scopes.** No positional may begin with `-`. `--dir`, `--log` and
+ * `--policy` are appended to every call from the launch configuration and are
+ * refused from a caller even when the value is correct: one process serves one
+ * store, and a caller restating it is a caller that believes it can choose.
+ *
+ * **Agent scope.** Every path-typed flag is refused OUTRIGHT rather than
+ * confined: a sandboxed harness has no files on the daemon's machine, so a
+ * path it names is either useless or somebody else's. Payload bytes reach the
+ * gate for such a harness through the hook route, which builds the envelope
+ * from the tool call itself. On top of that, only the flags named in
+ * {@link AGENT_FLAGS} are accepted at all, per verb, so a flag added to one of
+ * the seven agent verbs tomorrow is refused until somebody decides otherwise.
+ *
+ * **Tenant scope.** Every path-typed flag is CONFINED to the store, and which
+ * flags those are comes from the registry ({@link pathFlagsOf}) rather than
+ * from a list kept here, so a flag declared `"path"` tomorrow is confined on
+ * the day it appears. Positionals that name files are confined the same way.
+ */
+import { realpathSync } from "node:fs";
+import { dirname, isAbsolute, resolve, sep } from "node:path";
+import { pathFlagsOf, verbLabel } from "../cli/verb-registry.js";
+/**
+ * The three the server pins itself, refused from any caller in any scope.
+ *
+ * They ARE the store. Everything else this module decides is about values
+ * inside it.
+ */
+export const PINNED_FLAGS = ["--dir", "--log", "--policy"];
+/**
+ * What each AGENT verb may be given, flag by flag.
+ *
+ * A positive list per verb, and short on purpose. The agent surface is seven
+ * verbs; between them they need an action key, a decision deadline, a note,
+ * a proposal's class, key, summary and inline payload, and `--json`. Everything else on those verbs is either the store (pinned), the
+ * identity (`--as`, refused by the argv builder both transports share), a path
+ * (refused below), or something nobody has decided a sandboxed harness should
+ * have.
+ *
+ * `--help` is absent deliberately: a help page over a transport whose client
+ * is a program is an odd thing to serve, and `instructions` is the verb for
+ * that.
+ */
+export const AGENT_FLAGS = new Map([
+    ["instructions", new Set(["--schemas", "--json"])],
+    ["hook classify", new Set(["--json"])],
+    ["request", new Set(["--action", "--json"])],
+    ["wait", new Set(["--timeout", "--interval", "--withdraw-on-timeout", "--json"])],
+    ["withdraw", new Set(["--action", "--reason", "--note", "--json"])],
+    // APRV-445. The payload travels as a string VALUE, which is the whole reason
+    // these two verbs exist on this surface: a path would name the host's file.
+    ["propose", new Set(["--class", "--key", "--summary", "--payload-json", "--json"])],
+    ["start", new Set(["--action", "--payload-json", "--json"])],
+]);
+/**
+ * Verbs whose POSITIONAL argument names a file, by registry label.
+ *
+ * Read off the registry's own positional titles: each declares a `file` or a
+ * `task-file`. None is on the agent surface any more, and the confinement
+ * still runs for the tenant, because one process serves one store whoever is
+ * asking.
+ */
+const PATH_POSITIONAL_VERBS = new Map([
+    ["payload hash", 0],
+    ["register", 0],
+    ["import agents-md", 0],
+]);
+const OUTSIDE = "serve-path-outside-store";
+const PINNED = "serve-path-pinned";
+const DASH = "serve-positional-flag";
+const UNSUPPORTED = "serve-flag-not-permitted";
+/**
+ * Is `candidate` inside `root`?
+ *
+ * Resolved through `realpath` on the deepest existing ancestor, so a symlink
+ * in the middle of the path cannot walk out of the store and back in on paper.
+ * A path that does not exist is judged by where it WOULD be, which is the
+ * right answer for a verb that is about to create it.
+ */
+function insideStore(root, candidate) {
+    const real = (path) => {
+        let current = path;
+        const tail = [];
+        for (;;) {
+            try {
+                return resolve(realpathSync(current), ...tail.reverse());
+            }
+            catch {
+                const parent = dirname(current);
+                if (parent === current)
+                    return resolve(path);
+                tail.push(current.slice(parent.length + 1));
+                current = parent;
+            }
+        }
+    };
+    const realRoot = real(root);
+    const realCandidate = real(candidate);
+    return realCandidate === realRoot || realCandidate.startsWith(`${realRoot}${sep}`);
+}
+function confine(root, cwd, label, value) {
+    // `-` is stdin and is refused by the argv builder both transports share.
+    if (value === "-")
+        return { ok: true };
+    const absolute = isAbsolute(value) ? value : resolve(cwd, value);
+    if (insideStore(root, absolute))
+        return { ok: true };
+    return {
+        ok: false,
+        code: OUTSIDE,
+        message: `${label} names ${JSON.stringify(value)}, which is outside the store this server was started for. This transport serves ONE store and reads no path beyond it: a path argument that reached the host filesystem would answer questions about files the caller cannot see and did not put there`,
+    };
+}
+/**
+ * Check one verb call's arguments before an argv is built from them.
+ *
+ * Runs for EVERY scope. The tenant credential is the operator's and is trusted
+ * with far more than the agent's, and that is still not a reason to let one
+ * process serve two stores: the pins are the launch configuration's, and a
+ * second store reached through an argument would be a second gate with no
+ * attestation, no daemon id, and no record of which one answered.
+ */
+export function checkVerbArguments(spec, rawArgs, storeRoot, cwd, scope) {
+    const args = (rawArgs ?? {});
+    if (typeof args !== "object" || Array.isArray(args))
+        return { ok: true };
+    const label = verbLabel(spec);
+    // A POSITIONAL THAT LOOKS LIKE A FLAG IS A FLAG. Checked first and in both
+    // scopes, because it is the route around every other rule in this file.
+    const positionals = args["positionals"];
+    if (Array.isArray(positionals)) {
+        for (const value of positionals) {
+            if (typeof value !== "string" || !value.startsWith("-"))
+                continue;
+            return {
+                ok: false,
+                code: DASH,
+                message: `positional ${JSON.stringify(value)} begins with a dash. Positionals on this surface are VALUES, passed to the verb verbatim, and the verb reads anything starting with \`-\` as a flag: a value spelled this way reaches the flag parser through the front door. Send flags in \`flags\``,
+            };
+        }
+    }
+    const pathFlags = new Set(pathFlagsOf(spec));
+    const permitted = AGENT_FLAGS.get(label);
+    const flags = args["flags"];
+    if (typeof flags === "object" && flags !== null && !Array.isArray(flags)) {
+        for (const [flag, value] of Object.entries(flags)) {
+            if (PINNED_FLAGS.includes(flag)) {
+                return {
+                    ok: false,
+                    code: PINNED,
+                    message: `${flag} is not accepted from a caller. This server serves the one store it was started for, and ${PINNED_FLAGS.join(", ")} are appended to every verb call from its launch configuration; a call that could restate them could point this process at another tenant's log, at another tenant's policy, or at the host's filesystem`,
+                };
+            }
+            if (scope === "agent") {
+                // `--as` is not this module's to refuse. The argv builder both
+                // transports share owns identity and refuses it with
+                // `mcp-identity-fixed`, whose message is the whole reason this surface
+                // is safe to run; catching it here first would replace that with a
+                // vaguer code and leave the rule stated in two places.
+                if (flag === "--as")
+                    continue;
+                if (pathFlags.has(flag)) {
+                    return {
+                        ok: false,
+                        code: UNSUPPORTED,
+                        message: `${flag} names a file on the machine this server runs on, and the agent credential never names one. A harness reached through this transport has no files there; payload bytes reach the gate through \`POST /hook/<harness>\`, which builds the envelope from the tool call itself`,
+                    };
+                }
+                if (permitted !== undefined && !permitted.has(flag)) {
+                    return {
+                        ok: false,
+                        code: UNSUPPORTED,
+                        message: `${flag} is not accepted on \`approval ${label}\` from the agent credential, which takes ${[...permitted].sort().join(", ")} on this verb and nothing else. A flag added to it later is refused until somebody decides a harness under oversight should have it`,
+                    };
+                }
+                continue;
+            }
+            if (!pathFlags.has(flag) || typeof value !== "string")
+                continue;
+            const checked = confine(storeRoot, cwd, flag, value);
+            if (!checked.ok)
+                return checked;
+        }
+    }
+    const index = PATH_POSITIONAL_VERBS.get(label);
+    if (index === undefined)
+        return { ok: true };
+    if (!Array.isArray(positionals))
+        return { ok: true };
+    const value = positionals[index];
+    if (typeof value !== "string")
+        return { ok: true };
+    return confine(storeRoot, cwd, `\`approval ${label}\`'s file argument`, value);
+}
+//# sourceMappingURL=arguments.js.map

package/dist/src/serve/arguments.js.map

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

package/dist/src/serve/credentials.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The two bearer credentials `approval serve` reads from its launch
+ * environment, and the scope each one buys (APRV-421).
+ *
+ * ## Two credentials, because there are two parties
+ *
+ * SPEC.md §11 names the agent the untrusted policy and the human the trusted
+ * overseer, and a hosted deployment adds a third fact: the log and the policy
+ * belong to the TENANT, while the harness that is judged by them runs
+ * somewhere else entirely (design/hosted-daemon-identity.md, §1). So this
+ * server has two doors and never one.
+ *
+ * - The **agent credential** ({@link AGENT_TOKEN_ENV}) reaches the
+ *   agent-facing verb surface and the harness hook. It is the credential a
+ *   sandbox holds, and the sandbox is the party under oversight.
+ * - The **tenant credential** ({@link TENANT_TOKEN_ENV}) reaches the log, the
+ *   export and the status report. It is the credential the tenant's own tools
+ *   hold.
+ *
+ * **The agent credential must never read the log it is judged by.** That is
+ * the sentence the split exists for. An agent that can stream the verified log
+ * can read every decision made about it, every other action in the tenant's
+ * store, and the shape of the oversight it is under; an agent that can export
+ * the store can carry all of it away. Neither is a thing the gate would ever
+ * grant, so neither is reachable with the credential the gate hands the
+ * harness. The refusal is a scope refusal and not a not-found, because a
+ * caller that guessed a path deserves to learn that the door exists and is not
+ * theirs, rather than to probe for one that answers differently.
+ *
+ * ## Why the environment
+ *
+ * SPEC.md §11.1 invariant 7: configuration is never loaded implicitly from the
+ * working tree. A credential in a file this process discovered would be a
+ * credential anything able to write that file could rotate. The host that
+ * launches one process per tenant is the party that sets these, exactly as it
+ * sets the bot token, the sampling secret and the vault passphrase
+ * (design/hosted-daemon-identity.md §1.2).
+ *
+ * ## What comparison costs
+ *
+ * Both values are compared as SHA-256 digests under `timingSafeEqual`, so the
+ * comparison is constant-time AND length-independent: `timingSafeEqual` throws
+ * on a length mismatch, which would itself be an oracle for the length of the
+ * real credential. Nothing here logs, prints, or returns either value, and the
+ * server never puts one in a record, a message or a header.
+ */
+/** The environment variable naming the credential a sandboxed harness holds. */
+export declare const AGENT_TOKEN_ENV = "APPROVAL_SERVE_AGENT_TOKEN";
+/** The environment variable naming the credential the tenant's own tools hold. */
+export declare const TENANT_TOKEN_ENV = "APPROVAL_SERVE_TENANT_TOKEN";
+/**
+ * The shortest credential this server will start with.
+ *
+ * Not a password policy: a floor under the one mistake that makes the split
+ * meaningless, which is a memorable value somebody typed. The credential is
+ * generated by the host, never by a person, so the floor costs nothing.
+ */
+export declare const MIN_TOKEN_LENGTH = 24;
+/** Which of the two parties a request is acting as. */
+export type ServeScope = "agent" | "tenant";
+/**
+ * The frozen refusal vocabulary of the credential layer (SPEC.md §11.1
+ * invariant 6). Distinct codes, because the repairs are distinct: one is a
+ * missing or wrong credential, and the other two are the right credential at
+ * the wrong door, in each direction.
+ */
+export declare const SERVE_CREDENTIAL_REFUSAL_CODES: readonly ["serve-unauthorized", "serve-agent-forbidden", "serve-tenant-forbidden"];
+export type ServeCredentialRefusalCode = (typeof SERVE_CREDENTIAL_REFUSAL_CODES)[number];
+/** Hold the digests, never the values. */
+export interface ServeCredentials {
+    /** Which scope this bearer value belongs to, or `null` for neither. */
+    identify(bearer: string): ServeScope | null;
+}
+export type CredentialResolution = {
+    ok: true;
+    credentials: ServeCredentials;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Resolve both credentials, or say why the server may not start.
+ *
+ * Every failure is a STARTUP failure. A server that began listening and then
+ * discovered it had no tenant credential would be a server something had
+ * already spoken to, which is the rule `cli/mcp.ts` states for identity and
+ * this file inherits for authority.
+ */
+export declare function resolveServeCredentials(env?: NodeJS.ProcessEnv): CredentialResolution;
+/** The bearer value of an `Authorization` header, or null. */
+export declare function bearerOf(header: string | string[] | undefined): string | null;

package/dist/src/serve/credentials.js

@@ -0,0 +1,143 @@
+/**
+ * The two bearer credentials `approval serve` reads from its launch
+ * environment, and the scope each one buys (APRV-421).
+ *
+ * ## Two credentials, because there are two parties
+ *
+ * SPEC.md §11 names the agent the untrusted policy and the human the trusted
+ * overseer, and a hosted deployment adds a third fact: the log and the policy
+ * belong to the TENANT, while the harness that is judged by them runs
+ * somewhere else entirely (design/hosted-daemon-identity.md, §1). So this
+ * server has two doors and never one.
+ *
+ * - The **agent credential** ({@link AGENT_TOKEN_ENV}) reaches the
+ *   agent-facing verb surface and the harness hook. It is the credential a
+ *   sandbox holds, and the sandbox is the party under oversight.
+ * - The **tenant credential** ({@link TENANT_TOKEN_ENV}) reaches the log, the
+ *   export and the status report. It is the credential the tenant's own tools
+ *   hold.
+ *
+ * **The agent credential must never read the log it is judged by.** That is
+ * the sentence the split exists for. An agent that can stream the verified log
+ * can read every decision made about it, every other action in the tenant's
+ * store, and the shape of the oversight it is under; an agent that can export
+ * the store can carry all of it away. Neither is a thing the gate would ever
+ * grant, so neither is reachable with the credential the gate hands the
+ * harness. The refusal is a scope refusal and not a not-found, because a
+ * caller that guessed a path deserves to learn that the door exists and is not
+ * theirs, rather than to probe for one that answers differently.
+ *
+ * ## Why the environment
+ *
+ * SPEC.md §11.1 invariant 7: configuration is never loaded implicitly from the
+ * working tree. A credential in a file this process discovered would be a
+ * credential anything able to write that file could rotate. The host that
+ * launches one process per tenant is the party that sets these, exactly as it
+ * sets the bot token, the sampling secret and the vault passphrase
+ * (design/hosted-daemon-identity.md §1.2).
+ *
+ * ## What comparison costs
+ *
+ * Both values are compared as SHA-256 digests under `timingSafeEqual`, so the
+ * comparison is constant-time AND length-independent: `timingSafeEqual` throws
+ * on a length mismatch, which would itself be an oracle for the length of the
+ * real credential. Nothing here logs, prints, or returns either value, and the
+ * server never puts one in a record, a message or a header.
+ */
+import { createHash, timingSafeEqual } from "node:crypto";
+/** The environment variable naming the credential a sandboxed harness holds. */
+export const AGENT_TOKEN_ENV = "APPROVAL_SERVE_AGENT_TOKEN";
+/** The environment variable naming the credential the tenant's own tools hold. */
+export const TENANT_TOKEN_ENV = "APPROVAL_SERVE_TENANT_TOKEN";
+/**
+ * The shortest credential this server will start with.
+ *
+ * Not a password policy: a floor under the one mistake that makes the split
+ * meaningless, which is a memorable value somebody typed. The credential is
+ * generated by the host, never by a person, so the floor costs nothing.
+ */
+export const MIN_TOKEN_LENGTH = 24;
+/**
+ * The frozen refusal vocabulary of the credential layer (SPEC.md §11.1
+ * invariant 6). Distinct codes, because the repairs are distinct: one is a
+ * missing or wrong credential, and the other two are the right credential at
+ * the wrong door, in each direction.
+ */
+export const SERVE_CREDENTIAL_REFUSAL_CODES = [
+    "serve-unauthorized",
+    "serve-agent-forbidden",
+    "serve-tenant-forbidden",
+];
+function digest(value) {
+    return createHash("sha256").update(value, "utf8").digest();
+}
+function sameDigest(left, right) {
+    // Equal by construction (two SHA-256 digests), so `timingSafeEqual` can never
+    // throw here and the comparison leaks nothing about the length of either
+    // input.
+    return timingSafeEqual(left, right);
+}
+/**
+ * Resolve both credentials, or say why the server may not start.
+ *
+ * Every failure is a STARTUP failure. A server that began listening and then
+ * discovered it had no tenant credential would be a server something had
+ * already spoken to, which is the rule `cli/mcp.ts` states for identity and
+ * this file inherits for authority.
+ */
+export function resolveServeCredentials(env = process.env) {
+    const agent = env[AGENT_TOKEN_ENV] ?? "";
+    const tenant = env[TENANT_TOKEN_ENV] ?? "";
+    for (const [name, value] of [
+        [AGENT_TOKEN_ENV, agent],
+        [TENANT_TOKEN_ENV, tenant],
+    ]) {
+        if (value.length === 0) {
+            return {
+                ok: false,
+                message: `no ${name} in the environment: this server has two doors and starts only when the host has named both. The agent credential reaches the verbs and the hook; the tenant credential reaches the log, the export and status`,
+            };
+        }
+        if (value.length < MIN_TOKEN_LENGTH) {
+            return {
+                ok: false,
+                message: `${name} is shorter than ${String(MIN_TOKEN_LENGTH)} characters. Generate it (\`openssl rand -hex 32\`) rather than choosing it: this value is the whole of what separates the two parties`,
+            };
+        }
+    }
+    if (sameDigest(digest(agent), digest(tenant))) {
+        return {
+            ok: false,
+            message: `${AGENT_TOKEN_ENV} and ${TENANT_TOKEN_ENV} are the same value, which is the same as having neither: the agent credential would reach the log it is judged by`,
+        };
+    }
+    const agentDigest = digest(agent);
+    const tenantDigest = digest(tenant);
+    return {
+        ok: true,
+        credentials: {
+            identify(bearer) {
+                const offered = digest(bearer);
+                // Both compared, always, in the same order: returning as soon as the
+                // agent digest matched would make an agent credential measurably
+                // faster to present than a tenant one.
+                const isAgent = sameDigest(offered, agentDigest);
+                const isTenant = sameDigest(offered, tenantDigest);
+                if (isAgent)
+                    return "agent";
+                if (isTenant)
+                    return "tenant";
+                return null;
+            },
+        },
+    };
+}
+/** The bearer value of an `Authorization` header, or null. */
+export function bearerOf(header) {
+    const raw = Array.isArray(header) ? header[0] : header;
+    if (raw === undefined)
+        return null;
+    const match = /^Bearer[ \t]+(?<token>\S+)$/iu.exec(raw.trim());
+    return match?.groups?.["token"] ?? null;
+}
+//# sourceMappingURL=credentials.js.map

package/dist/src/serve/credentials.js.map

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

package/dist/src/serve/follow.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `log/follow`, paged (APRV-421).
+ *
+ * `approval log follow` is a foreground stream: it prints verified records as
+ * JSON Lines and stays. Over HTTP that shape is wrong in both directions — a
+ * request has to end, and a tenant behind a sleeping Firecracker host has to
+ * be able to come back tomorrow and resume — so this answers ONE page and
+ * hands back the cursor to ask with next time.
+ *
+ * Everything else is the streaming verb's, unchanged, because it is literally
+ * the same generator: `core/log-subscribe.ts` verifies the chain from genesis
+ * before it emits anything, binds the exclusive `(seq, hash)` cursor to the
+ * prefix the caller says it consumed, and refuses a mismatch as an integrity
+ * failure with `cursor-mismatch` as its reason. Nothing in this file verifies,
+ * parses or re-derives a record; it counts to a limit and stops.
+ *
+ * **At-least-once, and the cursor is the caller's.** This server keeps no
+ * subscription state: a page is a function of the cursor in the request and
+ * the bytes on disk. A caller that performs an external effect persists its
+ * cursor after the effect, exactly as SPEC.md §8 requires of any consumer, and
+ * a restart of this process on either side changes nothing about what the next
+ * page contains. That is what "no in-memory state a restart loses" means here.
+ */
+import type { EventRecord } from "../core/log.js";
+/** Records one page carries when the caller names no limit. */
+export declare const DEFAULT_FOLLOW_LIMIT = 200;
+/** The most any caller may ask for in one page. */
+export declare const MAX_FOLLOW_LIMIT = 1000;
+export interface FollowCursor {
+    /** Exclusive: the caller has consumed through this sequence number. */
+    seq: number;
+    /** The hash of record `seq`, or null when the caller never held one. */
+    hash: string | null;
+}
+export interface FollowPage {
+    records: EventRecord[];
+    /** Where to resume. The caller sends this back verbatim. */
+    cursor: FollowCursor;
+    /**
+     * True when this page exhausted the verified log rather than the limit.
+     *
+     * A caller that gets `false` asks again immediately; one that gets `true`
+     * waits before it does. It is a statement about the snapshot this page was
+     * cut from and never a promise about the next instant.
+     */
+    caught_up: boolean;
+}
+export type FollowResult = {
+    ok: true;
+    page: FollowPage;
+} | {
+    ok: false;
+    /** The CLI's own code for this failure: `integrity`, `torn-tail` or `io`. */
+    code: string;
+    message: string;
+    /** `cursor-mismatch` and the rest of the subscription's own reasons. */
+    reason: string | null;
+};
+/**
+ * The exit code `approval log follow` would have exited with for this failure.
+ *
+ * Carried on the response so a caller reproducing the CLI locally reports the
+ * same thing. The numbers are `cli/exit-codes.ts`'s and are frozen public API;
+ * they are mapped here exactly as `main.ts`'s `commandFollow` maps them.
+ */
+export declare function followFailureExit(code: string): number;
+/**
+ * There is deliberately NO clamp here any more (APRV-421, review).
+ *
+ * A limit outside the range above used to be pulled quietly into it, so
+ * `limit=0` returned two hundred records and a caller paging by a number it
+ * had computed could not tell that the server had answered a different
+ * question than the one it asked. The transport refuses an out-of-range limit
+ * with `serve-invalid-cursor` instead, and `docs/cli-reference.md` states the
+ * range. A silent correction is the failure mode this project exists to
+ * dislike.
+ */
+/**
+ * Read one page of verified records after `cursor`.
+ *
+ * A failure returns NO records at all, including the ones a partial drain had
+ * already produced: SPEC.md §8 says a subscription "MUST emit no record from a
+ * batch that fails verification or its retained cursor binding", and a page
+ * that carried half a batch beside an integrity refusal would be exactly that.
+ */
+export declare function followPage(logPath: string, cursor: FollowCursor, limit: number): Promise<FollowResult>;

package/dist/src/serve/follow.js

@@ -0,0 +1,101 @@
+/**
+ * `log/follow`, paged (APRV-421).
+ *
+ * `approval log follow` is a foreground stream: it prints verified records as
+ * JSON Lines and stays. Over HTTP that shape is wrong in both directions — a
+ * request has to end, and a tenant behind a sleeping Firecracker host has to
+ * be able to come back tomorrow and resume — so this answers ONE page and
+ * hands back the cursor to ask with next time.
+ *
+ * Everything else is the streaming verb's, unchanged, because it is literally
+ * the same generator: `core/log-subscribe.ts` verifies the chain from genesis
+ * before it emits anything, binds the exclusive `(seq, hash)` cursor to the
+ * prefix the caller says it consumed, and refuses a mismatch as an integrity
+ * failure with `cursor-mismatch` as its reason. Nothing in this file verifies,
+ * parses or re-derives a record; it counts to a limit and stops.
+ *
+ * **At-least-once, and the cursor is the caller's.** This server keeps no
+ * subscription state: a page is a function of the cursor in the request and
+ * the bytes on disk. A caller that performs an external effect persists its
+ * cursor after the effect, exactly as SPEC.md §8 requires of any consumer, and
+ * a restart of this process on either side changes nothing about what the next
+ * page contains. That is what "no in-memory state a restart loses" means here.
+ */
+import { LogSubscriptionError, subscribeVerifiedLog } from "../core/log-subscribe.js";
+/** Records one page carries when the caller names no limit. */
+export const DEFAULT_FOLLOW_LIMIT = 200;
+/** The most any caller may ask for in one page. */
+export const MAX_FOLLOW_LIMIT = 1000;
+/**
+ * The exit code `approval log follow` would have exited with for this failure.
+ *
+ * Carried on the response so a caller reproducing the CLI locally reports the
+ * same thing. The numbers are `cli/exit-codes.ts`'s and are frozen public API;
+ * they are mapped here exactly as `main.ts`'s `commandFollow` maps them.
+ */
+export function followFailureExit(code) {
+    if (code === "integrity")
+        return 1;
+    if (code === "torn-tail")
+        return 3;
+    return 4;
+}
+/**
+ * There is deliberately NO clamp here any more (APRV-421, review).
+ *
+ * A limit outside the range above used to be pulled quietly into it, so
+ * `limit=0` returned two hundred records and a caller paging by a number it
+ * had computed could not tell that the server had answered a different
+ * question than the one it asked. The transport refuses an out-of-range limit
+ * with `serve-invalid-cursor` instead, and `docs/cli-reference.md` states the
+ * range. A silent correction is the failure mode this project exists to
+ * dislike.
+ */
+/**
+ * Read one page of verified records after `cursor`.
+ *
+ * A failure returns NO records at all, including the ones a partial drain had
+ * already produced: SPEC.md §8 says a subscription "MUST emit no record from a
+ * batch that fails verification or its retained cursor binding", and a page
+ * that carried half a batch beside an integrity refusal would be exactly that.
+ */
+export async function followPage(logPath, cursor, limit) {
+    const records = [];
+    let caughtUp = true;
+    const options = {
+        from: cursor.seq,
+        once: true,
+        ...(cursor.hash === null ? {} : { expectedHash: cursor.hash }),
+    };
+    try {
+        for await (const record of subscribeVerifiedLog(logPath, options)) {
+            records.push(record);
+            if (records.length >= limit) {
+                // The generator's `finally` runs on this break: the iterator is closed
+                // and nothing is left watching or waiting.
+                caughtUp = false;
+                break;
+            }
+        }
+    }
+    catch (cause) {
+        if (!(cause instanceof LogSubscriptionError))
+            throw cause;
+        return {
+            ok: false,
+            code: cause.kind === "torn-tail" ? "torn-tail" : cause.kind === "io" ? "io" : "integrity",
+            message: cause.message,
+            reason: cause.reason,
+        };
+    }
+    const last = records.at(-1);
+    return {
+        ok: true,
+        page: {
+            records,
+            cursor: last === undefined ? cursor : { seq: last.seq, hash: last.hash },
+            caught_up: caughtUp,
+        },
+    };
+}
+//# sourceMappingURL=follow.js.map