approval-md 0.3.0 → 0.4.0

package/dist/src/serve/archive.js

@@ -0,0 +1,354 @@
+/**
+ * The store as an archive (APRV-421): a POSIX ustar tar, gzipped, written here
+ * rather than by a library.
+ *
+ * ## Why a writer and not a dependency
+ *
+ * The repository rule is minimal dependencies, justified per addition, and the
+ * justification for a tar library would have to survive one question: what does
+ * it do that ninety lines here do not? A ustar header is a fixed 512-byte
+ * record with octal fields and a checksum, `node:zlib` already ships the
+ * compression, and the archive this verb produces contains a handful of files
+ * whose paths are short and known. A dependency would add a supply-chain
+ * surface to a process that hands a tenant their own evidence, in exchange for
+ * code this file can state completely.
+ *
+ * ## The contents are a POSITIVE allowlist
+ *
+ * {@link EXPORTED_PATHS} names what goes in. Everything else is out by not
+ * being named, which is the fail-closed direction SPEC.md §11 asks for
+ * everywhere else: `.approval/keys`, `.approval/env`, `.approval/daemon` and
+ * any `vault.enc` are excluded because nothing admits them, not because a
+ * denylist remembered them. A file added to the store next month is absent
+ * from this archive until somebody decides it belongs, and that decision is a
+ * diff here.
+ *
+ * `.approval/payloads/` IS on the list, and it is the entry the reasoning
+ * turns on. The log records a `payload_hash` for every action a human was
+ * shown, and the bytes those hashes name live in that directory. An archive
+ * carrying the hashes without the bytes would hand a tenant a chain of
+ * references to evidence they no longer hold: a receipt for an exit rather
+ * than an exit. Payload bytes are the tenant's own and are not credential
+ * material — the vault, the keys and the environment source map are, and
+ * those are the things excluded below.
+ *
+ * ## What the reader is for
+ *
+ * {@link readTarEntries} exists so that a test, and a conformance reader after
+ * it, can assert what an archive CONTAINS rather than trusting the writer that
+ * produced it. A test that checked the writer against itself would pass on the
+ * day the writer put the vault in.
+ */
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, readdirSync } from "node:fs";
+import { join, posix, relative, sep } from "node:path";
+import { gzipSync } from "node:zlib";
+/** One tar block. The format's unit, and every offset below is inside one. */
+const BLOCK = 512;
+/**
+ * What an export carries, relative to the store root, in archive order.
+ *
+ * A trailing `/` means "this directory, recursively". Everything else is one
+ * file, included when it exists and silently absent when it does not: a store
+ * whose index has never been built is an ordinary store, not a broken one.
+ */
+export const EXPORTED_PATHS = [
+    "APPROVAL.md",
+    ".approval/log/",
+    ".approval/payloads/",
+    ".approval/QUEUE.md",
+    ".approval/index.sqlite",
+];
+/**
+ * Paths an export MUST NOT carry, checked as well as excluded.
+ *
+ * The allowlist above is what decides; this list is what a test asserts
+ * against, so the property "no credential material left the store" is written
+ * down as a property and not merely implied by the absence of an entry.
+ */
+export const EXCLUDED_PREFIXES = [
+    ".approval/keys",
+    ".approval/env",
+    ".approval/daemon",
+];
+/** Any file with this name is credential material, wherever it sits. */
+export const EXCLUDED_BASENAMES = ["vault.enc"];
+function octal(value, width) {
+    // `width - 1` digits and a NUL, which is what every reader accepts and what
+    // GNU tar itself writes for these fields.
+    return value.toString(8).padStart(width - 1, "0").slice(-(width - 1)) + "\0";
+}
+function writeString(block, offset, width, value) {
+    block.write(value.slice(0, width), offset, width, "utf8");
+}
+/**
+ * Split a path into ustar's `prefix` and `name` fields.
+ *
+ * Refused rather than truncated when it does not fit: a truncated path in an
+ * archive is a file restored to the wrong place, which is worse than an export
+ * that says plainly it cannot represent this store.
+ */
+export function splitTarName(path) {
+    if (Buffer.byteLength(path) <= 100)
+        return { name: path, prefix: "" };
+    const cut = path.lastIndexOf("/", path.length - 1);
+    for (let index = cut; index > 0; index -= 1) {
+        if (path[index] !== "/")
+            continue;
+        const prefix = path.slice(0, index);
+        const name = path.slice(index + 1);
+        if (Buffer.byteLength(prefix) <= 155 && Buffer.byteLength(name) <= 100) {
+            return { name, prefix };
+        }
+    }
+    throw new Error(`${path} cannot be written into a ustar archive: the name exceeds the format's 100/155 byte fields`);
+}
+/** One 512-byte ustar header, checksum included. */
+function header(entry) {
+    const block = Buffer.alloc(BLOCK, 0);
+    const { name, prefix } = splitTarName(entry.path);
+    writeString(block, 0, 100, name);
+    writeString(block, 100, 8, octal(0o644, 8));
+    writeString(block, 108, 8, octal(0, 8));
+    writeString(block, 116, 8, octal(0, 8));
+    writeString(block, 124, 12, octal(entry.data.length, 12));
+    writeString(block, 136, 12, octal(Math.floor(entry.mtime), 12));
+    // The checksum field is computed as though it held eight spaces.
+    block.write("        ", 148, 8, "utf8");
+    block.write("0", 156, 1, "utf8"); // typeflag: a regular file
+    block.write("ustar\0", 257, 6, "utf8");
+    block.write("00", 263, 2, "utf8");
+    writeString(block, 345, 155, prefix);
+    let sum = 0;
+    for (const byte of block)
+        sum += byte;
+    // Six octal digits, a NUL and a space: the spelling every reader accepts.
+    block.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148, 8, "utf8");
+    return block;
+}
+function padding(size) {
+    const remainder = size % BLOCK;
+    return remainder === 0 ? Buffer.alloc(0) : Buffer.alloc(BLOCK - remainder, 0);
+}
+/** Write `entries` as an uncompressed ustar archive. */
+export function writeTar(entries) {
+    const parts = [];
+    for (const entry of entries) {
+        parts.push(header(entry), entry.data, padding(entry.data.length));
+    }
+    // Two zero blocks end the archive; a reader that stops at the first one is
+    // still correct, and one that requires both is satisfied.
+    parts.push(Buffer.alloc(BLOCK * 2, 0));
+    return Buffer.concat(parts);
+}
+/**
+ * Read an uncompressed ustar archive back.
+ *
+ * Deliberately strict about the checksum: the point of this function is to be
+ * an independent reader of what {@link writeTar} produced, and a reader that
+ * ignored the field the writer computes would not be independent of it.
+ */
+export function readTarEntries(archive) {
+    const entries = [];
+    let offset = 0;
+    while (offset + BLOCK <= archive.length) {
+        const block = archive.subarray(offset, offset + BLOCK);
+        if (block.every((byte) => byte === 0))
+            break;
+        const declared = Number.parseInt(block.subarray(148, 156).toString("utf8").trim(), 8);
+        let sum = 0;
+        for (const [index, byte] of block.entries()) {
+            sum += index >= 148 && index < 156 ? 0x20 : byte;
+        }
+        if (sum !== declared) {
+            throw new Error(`tar header checksum mismatch at offset ${String(offset)}`);
+        }
+        const trim = (buffer) => {
+            const end = buffer.indexOf(0);
+            return buffer.subarray(0, end === -1 ? buffer.length : end).toString("utf8");
+        };
+        const name = trim(block.subarray(0, 100));
+        const prefix = trim(block.subarray(345, 500));
+        const size = Number.parseInt(trim(block.subarray(124, 136)) || "0", 8);
+        const mtime = Number.parseInt(trim(block.subarray(136, 148)) || "0", 8);
+        offset += BLOCK;
+        entries.push({
+            path: prefix.length === 0 ? name : `${prefix}/${name}`,
+            data: Buffer.from(archive.subarray(offset, offset + size)),
+            mtime,
+        });
+        offset += size + padding(size).length;
+    }
+    return entries;
+}
+/**
+ * Is this store-relative path one an export may never carry?
+ *
+ * `excludedLock` is the ONE lockfile this server itself creates, passed in as
+ * an exact path rather than matched as a class. An earlier pass excluded
+ * `*.lock` by suffix, which quietly deleted a tenant's own
+ * `.approval/payloads/x.lock` from their archive: the tenant's bytes are the
+ * tenant's, and a name this runtime happens to use for its own bookkeeping is
+ * not a reason to drop somebody else's file. Only the path derived from the
+ * log is dropped, and only because the export holds that lock while it walks,
+ * so the file exists for exactly the span of the copy and means nothing but
+ * "somebody was reading when this was made".
+ */
+export function isExcludedPath(path, excludedLock = null) {
+    const base = path.split("/").at(-1) ?? path;
+    if (EXCLUDED_BASENAMES.includes(base))
+        return true;
+    if (excludedLock !== null && path === excludedLock)
+        return true;
+    return EXCLUDED_PREFIXES.some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
+}
+/**
+ * A symlink the export walk reached.
+ *
+ * Thrown rather than returned because it must abort the WHOLE archive from
+ * wherever it is found, and an error is the one control flow that cannot be
+ * accidentally ignored by a caller that forgot to check a return value.
+ */
+export class ExportSymlinkError extends Error {
+    /** The store-relative path of the link itself, never its target. */
+    path;
+    constructor(path) {
+        super(`${path} is a symbolic link. An export copies the tenant's own store and never what a link points at: a link under the store can name credential material inside it (\`.approval/keys\`, \`.approval/env\`, the vault) or any file on the host, and a copy that followed one would put those bytes in the tenant's archive. The whole export is refused rather than the link skipped, because an archive silently missing a file is an archive nobody can tell from a complete one. Replace the link with the file, or move it outside the store.`);
+        this.name = "ExportSymlinkError";
+        this.path = path;
+    }
+}
+/**
+ * A HARD link, which a name-based exclusion cannot see at all (APRV-421,
+ * second review pass).
+ *
+ * `ln .approval/keys/sender.key .approval/log/note.jsonl` produces a second
+ * name for the same inode. There is no link to refuse to follow and no target
+ * to notice: the excluded path and the admitted path ARE one file, and the
+ * admitted name is a perfectly ordinary regular file by every test a walker
+ * can apply to it except one — its link count.
+ *
+ * So `nlink > 1` on a regular file under the store is refused, fail-closed and
+ * whole, exactly as a symlink is. The false positive is a tenant who
+ * deliberately hard-linked something into their own store, which is rare, is
+ * visible in the refusal, and is repaired by copying the file.
+ */
+export class ExportHardLinkError extends Error {
+    /** The store-relative path of the link, which is also the file. */
+    path;
+    /** How many names this inode has. */
+    links;
+    constructor(path, links) {
+        super(`${path} has ${String(links)} names (it is a hard link). A second name for one inode cannot be told from an ordinary file by its path, so an excluded file — a key under \`.approval/keys\`, the environment source map, the vault — can be given an admitted name and copied into the archive with nothing to notice. The whole export is refused rather than the file skipped, for the reason a symbolic link refuses it: an archive silently missing a file is one nobody can tell from a complete one. Replace the link with a copy.`);
+        this.name = "ExportHardLinkError";
+        this.path = path;
+        this.links = links;
+    }
+}
+function walk(root, relativeDir, into, lock) {
+    let names;
+    try {
+        names = readdirSync(join(root, relativeDir)).sort();
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        const relativePath = posix.join(relativeDir, name);
+        collect(root, relativePath, into, lock);
+    }
+}
+function collect(root, relativePath, into, lock) {
+    // Checked on every path rather than only on the roots: the allowlist decides
+    // what is offered and this decides what is accepted, and a nested `vault.enc`
+    // is refused by the second even when the first admitted the directory above
+    // it.
+    if (isExcludedPath(relativePath, lock))
+        return;
+    const absolute = join(root, relativePath);
+    let stats;
+    try {
+        // LSTAT, never stat (APRV-421). `stat` follows the link, so the exclusion
+        // check above would be reading one name while the copy below read another
+        // file entirely: `ln -s .approval/keys/sender.key .approval/log/note.jsonl`
+        // passes every name-based check ever written and hands over the key.
+        stats = lstatSync(absolute);
+    }
+    catch {
+        return;
+    }
+    if (stats.isSymbolicLink())
+        throw new ExportSymlinkError(relativePath);
+    if (stats.isDirectory()) {
+        walk(root, relativePath, into, lock);
+        return;
+    }
+    // Not a regular file: a fifo, a socket or a device. Skipped rather than
+    // refused, because none of them is a way to name another file's bytes, and
+    // a store that happens to hold one is not a store that is lying about what
+    // it contains.
+    if (!stats.isFile())
+        return;
+    // OPEN, then ask the DESCRIPTOR what it is (APRV-421, second review pass).
+    //
+    // `lstat` above and a `readFileSync(path)` below would be two resolutions of
+    // one name with a window between them, and the classic move is to replace a
+    // checked regular file with a symlink to somebody's key inside that window.
+    // `O_NOFOLLOW` refuses to open a symlink at all, and `fstat` describes THE
+    // FILE THAT WAS OPENED rather than whatever the name points at now — so the
+    // regular-file and link-count checks below are about the bytes actually read.
+    const fd = openSync(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const opened = fstatSync(fd);
+        if (!opened.isFile())
+            return;
+        if (opened.nlink > 1)
+            throw new ExportHardLinkError(relativePath, opened.nlink);
+        into.push({
+            path: relativePath,
+            data: readFileSync(fd),
+            mtime: Math.floor(opened.mtimeMs / 1000),
+        });
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            // `readFileSync(fd)` closes it on some paths; a double close is not an
+            // error worth propagating out of an export.
+        }
+    }
+}
+/**
+ * Build the export archive for the store rooted at `root`.
+ *
+ * Reads only; writes nothing anywhere, appends no record, and touches no
+ * credential. A path outside the allowlist cannot be reached from here, because
+ * the walk starts at the allowlist and nowhere else, and no path is followed
+ * through a link.
+ *
+ * Throws {@link ExportSymlinkError} when the walk meets a symbolic link. The
+ * caller turns that into a refusal naming the link's own relative path.
+ */
+export function buildStoreArchive(root, logPath) {
+    // The one file this server's own append lock creates, as an exact path.
+    const lock = storeRelative(root, `${logPath}.lock`);
+    const entries = [];
+    for (const candidate of EXPORTED_PATHS) {
+        const relativePath = candidate.endsWith("/") ? candidate.slice(0, -1) : candidate;
+        collect(root, relativePath, entries, lock);
+    }
+    // Sorted, so two exports of one unchanged store are the same archive: a
+    // tenant comparing two downloads is comparing the store and not the order a
+    // directory happened to be read in.
+    entries.sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0));
+    return {
+        bytes: gzipSync(writeTar(entries), { level: 6 }),
+        paths: entries.map((entry) => entry.path),
+    };
+}
+/** `relative()` in POSIX spelling, for callers that hold absolute paths. */
+export function storeRelative(root, path) {
+    return relative(root, path).split(sep).join("/");
+}
+//# sourceMappingURL=archive.js.map

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

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

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

@@ -0,0 +1,93 @@
+/**
+ * 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 { type VerbSpec } from "../cli/verb-registry.js";
+import type { ServeScope } from "./credentials.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 declare const PINNED_FLAGS: readonly string[];
+/**
+ * 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 declare const AGENT_FLAGS: ReadonlyMap<string, ReadonlySet<string>>;
+export type ArgumentCheck = {
+    ok: true;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * 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 declare function checkVerbArguments(spec: VerbSpec, rawArgs: unknown, storeRoot: string, cwd: string, scope: ServeScope): ArgumentCheck;