approval-md 0.3.0 → 0.4.1

package/dist/src/muse/server.js

@@ -0,0 +1,238 @@
+/** Local synthetic Muse consumer facade. No native Muse protocol is claimed. */
+import { createHash, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { buildPendingQueue } from "../channels/tagging.js";
+import { readGateRecords, register, registeredAction, request } from "../core/gate.js";
+import { payloadHash } from "../core/payload.js";
+import { loadPolicy } from "../core/policy-load.js";
+import { requestState } from "../core/state.js";
+import { canonicalRender } from "../core/wysiwys.js";
+export const MUSE_TOKEN_MIN_LENGTH = 24;
+const MAX_BODY = 64 * 1024;
+const KEY = /^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,159}$/u;
+/** Facade-local refusals. Core gate/tagger codes pass through separately. */
+export const MUSE_LOCAL_REFUSAL_CODES = [
+    "unauthorized", "scope-forbidden", "unsupported-query", "not-found",
+    "invalid-registration", "invalid-request", "invalid-lookup", "invalid-payload",
+    "payload-mismatch", "not-awaiting", "policy-unavailable", "sensitive-payload",
+    "body-too-large", "malformed-body", "internal-error",
+];
+class MuseBodyError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+export function validMuseOptions(o) {
+    return KEY.test(o.tenant) && /^agent:[A-Za-z0-9][A-Za-z0-9_.:/-]{0,159}$/u.test(o.actor)
+        && o.readToken.length >= MUSE_TOKEN_MIN_LENGTH && o.proposeToken.length >= MUSE_TOKEN_MIN_LENGTH
+        && o.readToken !== o.proposeToken && Number.isInteger(o.port) && o.port >= 0 && o.port <= 65535;
+}
+function equalToken(a, b) {
+    const left = createHash("sha256").update(a).digest();
+    const right = createHash("sha256").update(b).digest();
+    return timingSafeEqual(left, right);
+}
+function respond(res, status, value) {
+    const bytes = JSON.stringify(value);
+    res.writeHead(status, {
+        "content-type": "application/json; charset=utf-8",
+        "cache-control": "no-store",
+        "content-security-policy": "default-src 'none'",
+        "x-content-type-options": "nosniff",
+    });
+    res.end(bytes);
+}
+function fail(res, status, code) {
+    respond(res, status, { ok: false, error: { code } });
+}
+function object(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function exact(value, fields) {
+    return Object.keys(value).every((name) => fields.includes(name));
+}
+async function body(req) {
+    const parts = [];
+    let size = 0;
+    for await (const part of req) {
+        const chunk = Buffer.isBuffer(part) ? part : Buffer.from(part);
+        size += chunk.length;
+        if (size > MAX_BODY)
+            throw new MuseBodyError("body-too-large");
+        parts.push(chunk);
+    }
+    try {
+        return JSON.parse(Buffer.concat(parts).toString("utf8"));
+    }
+    catch {
+        throw new MuseBodyError("malformed-body");
+    }
+}
+/** No caller-supplied object may smuggle bearer values into a durable payload. */
+function secretLike(value) {
+    if (typeof value === "string")
+        return /(?:\bbearer\s+[A-Za-z0-9._~+/-]{12,}|\b(?:sk|ghp|xox[baprs])-\S{12,}|-----BEGIN [A-Z ]*PRIVATE KEY-----)/iu.test(value);
+    if (Array.isArray(value))
+        return value.some(secretLike);
+    if (object(value))
+        return Object.entries(value).some(([key, item]) => /(?:secret|password|credential|api[_-]?key|access[_-]?token|refresh[_-]?token|private[_-]?key)/iu.test(key) || secretLike(item));
+    return false;
+}
+function sensitive(value, o) {
+    if (secretLike(value))
+        return true;
+    if (typeof value === "string")
+        return value.includes(o.readToken) || value.includes(o.proposeToken);
+    if (Array.isArray(value))
+        return value.some((item) => sensitive(item, o));
+    if (object(value))
+        return Object.entries(value).some(([key, item]) => key.includes(o.readToken) || key.includes(o.proposeToken) || sensitive(item, o));
+    return false;
+}
+function safeRequest(item, detail) {
+    const canonical = item.fullPayload.value === null ? null : canonicalRender(item.fullPayload.value.value, item.class.value);
+    const result = {
+        task: item.task.value,
+        action_key: item.action_key.value,
+        class: item.class.value,
+        autonomy: item.autonomy.value,
+        state: item.state.value,
+        payload_hash: item.payload_hash.value,
+        display_hash: canonical?.display_hash ?? null,
+        requested_ts: item.requested_ts.value,
+        ttl_remaining_ms: item.ttl_remaining_ms.value,
+        chain_seq: item.chain.value.seq,
+        decision_channel: "telegram",
+        telegram_delivery_observed: false,
+        native_human_confirmation: false,
+    };
+    if (detail) {
+        // A canonical block is returned only on the read scope, and only when the
+        // verified payload store produced it. Never return claimed summaries or
+        // free-form gate errors, which may echo caller-supplied sensitive text.
+        result["canonical_rendering"] = canonical?.text ?? null;
+    }
+    return result;
+}
+function identity(req, o) {
+    let authorizationCount = 0;
+    for (let i = 0; i < req.rawHeaders.length; i += 2) {
+        if (req.rawHeaders[i]?.toLowerCase() === "authorization")
+            authorizationCount += 1;
+    }
+    if (authorizationCount !== 1)
+        return null;
+    const header = req.headers.authorization;
+    if (typeof header !== "string" || !header.startsWith("Bearer "))
+        return null;
+    const token = header.slice(7);
+    if (equalToken(token, o.readToken))
+        return "read";
+    if (equalToken(token, o.proposeToken))
+        return "propose";
+    return null;
+}
+export function createMuseServer(o) {
+    if (!validMuseOptions(o))
+        throw new Error("invalid Muse launch configuration");
+    return createServer((req, res) => {
+        void (async () => {
+            const role = identity(req, o);
+            if (role === null)
+                return fail(res, 401, "unauthorized");
+            const url = new URL(req.url ?? "/", "http://localhost");
+            if (url.search !== "" || url.hash !== "")
+                return fail(res, 400, "unsupported-query");
+            if (req.method === "GET" && url.pathname === "/v1/pending") {
+                if (role !== "read")
+                    return fail(res, 403, "scope-forbidden");
+                const queue = buildPendingQueue(o.log, { policy: { dir: o.root } }, new Date().toISOString());
+                if (!queue.ok)
+                    return fail(res, 409, queue.code);
+                const visible = queue.requests.filter((item) => !sensitive(item.fullPayload.value?.value, o));
+                return respond(res, 200, { ok: true, tenant: o.tenant, requests: visible.map((item) => safeRequest(item, false)), skipped: [...queue.skipped.map((item) => ({ action_key: item.action_key, code: item.code })), ...queue.requests.filter((item) => sensitive(item.fullPayload.value?.value, o)).map((item) => ({ action_key: item.action_key.value, code: "sensitive-payload" }))] });
+            }
+            if (req.method === "POST" && url.pathname === "/v1/registrations") {
+                if (role !== "propose")
+                    return fail(res, 403, "scope-forbidden");
+                const input = await body(req);
+                if (!object(input) || !exact(input, ["task", "envelope"]) || typeof input["task"] !== "string" || !KEY.test(input["task"]) || !object(input["envelope"]) || sensitive(input, o))
+                    return fail(res, 400, "invalid-registration");
+                const result = register(o.log, { task: input["task"], envelope: input["envelope"] }, o.actor);
+                if (!result.ok)
+                    return fail(res, 409, result.code);
+                return respond(res, 201, { ok: true, tenant: o.tenant, task: result.task, seq: result.record.seq });
+            }
+            if (req.method === "POST" && url.pathname === "/v1/requests") {
+                if (role !== "propose")
+                    return fail(res, 403, "scope-forbidden");
+                const input = await body(req);
+                if (!object(input) || !exact(input, ["task", "action_key", "payload"]) || typeof input["task"] !== "string" || !KEY.test(input["task"]) || typeof input["action_key"] !== "string" || !KEY.test(input["action_key"]) || !("payload" in input) || sensitive(input["payload"], o))
+                    return fail(res, 400, "invalid-request");
+                let hash;
+                try {
+                    hash = payloadHash(input["payload"]);
+                }
+                catch {
+                    return fail(res, 400, "invalid-payload");
+                }
+                const read = readGateRecords(o.log);
+                if (!read.ok)
+                    return fail(res, 409, read.code);
+                const declared = registeredAction(read.records, input["task"], input["action_key"]);
+                if (!declared.ok)
+                    return fail(res, 409, declared.code);
+                if (declared.action.payload_hash !== hash)
+                    return fail(res, 409, "payload-mismatch");
+                const result = request(o.log, {
+                    task: input["task"], actionKey: input["action_key"], cls: declared.action.class,
+                    ...(declared.action.est_cost_usd === undefined ? {} : { est_cost_usd: declared.action.est_cost_usd }),
+                    ...(declared.action.reversible === undefined ? {} : { reversible: declared.action.reversible }),
+                    ...(declared.action.summary === undefined ? {} : { summary: declared.action.summary }),
+                    payload: { value: input["payload"] },
+                }, o.actor, { policy: { dir: o.root } });
+                if (!result.ok)
+                    return fail(res, 409, result.code);
+                return respond(res, 200, { ok: true, tenant: o.tenant, task: input["task"], action_key: input["action_key"], payload_hash: hash, autonomy: result.autonomy, requested: result.record !== null, seq: result.record?.seq ?? null, decision_channel: "telegram", telegram_delivery_observed: false, native_human_confirmation: false });
+            }
+            if (req.method === "POST" && (url.pathname === "/v1/status" || url.pathname === "/v1/request-detail")) {
+                if (role !== "read")
+                    return fail(res, 403, "scope-forbidden");
+                const input = await body(req);
+                if (!object(input) || !exact(input, ["task", "action_key"]) || typeof input["task"] !== "string" || !KEY.test(input["task"]) || typeof input["action_key"] !== "string" || !KEY.test(input["action_key"]))
+                    return fail(res, 400, "invalid-lookup");
+                const read = readGateRecords(o.log);
+                if (!read.ok)
+                    return fail(res, 409, read.code);
+                const declared = registeredAction(read.records, input["task"], input["action_key"]);
+                if (!declared.ok)
+                    return fail(res, 404, "not-found");
+                const load = loadPolicy({ dir: o.root });
+                if (!load.ok)
+                    return fail(res, 409, "policy-unavailable");
+                const state = requestState(read.records, input["action_key"], new Date().toISOString(), load.ok ? load.durations.approvalTtlMs : null);
+                if (url.pathname === "/v1/status")
+                    return respond(res, 200, { ok: true, tenant: o.tenant, task: input["task"], action_key: input["action_key"], payload_hash: declared.action.payload_hash ?? null, state: state.state, decision_channel: "telegram", telegram_delivery_observed: false });
+                const queue = buildPendingQueue(o.log, { policy: { dir: o.root } }, new Date().toISOString());
+                if (!queue.ok)
+                    return fail(res, 409, queue.code);
+                const item = queue.requests.find((entry) => entry.task.value === input["task"] && entry.action_key.value === input["action_key"]);
+                if (item === undefined)
+                    return fail(res, 409, "not-awaiting");
+                if (sensitive(item.fullPayload.value?.value, o))
+                    return fail(res, 409, "sensitive-payload");
+                return respond(res, 200, { ok: true, tenant: o.tenant, request: safeRequest(item, true) });
+            }
+            return fail(res, 404, "not-found");
+        })().catch((cause) => {
+            if (res.headersSent)
+                return;
+            if (cause instanceof MuseBodyError)
+                return fail(res, cause.code === "body-too-large" ? 413 : 400, cause.code);
+            return fail(res, 500, "internal-error");
+        });
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/src/muse/server.js.map

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

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

@@ -0,0 +1,166 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare const EXPORTED_PATHS: readonly string[];
+/**
+ * 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 declare const EXCLUDED_PREFIXES: readonly string[];
+/** Any file with this name is credential material, wherever it sits. */
+export declare const EXCLUDED_BASENAMES: readonly string[];
+export interface TarEntry {
+    /** POSIX path inside the archive, relative to the store root. */
+    path: string;
+    /** File contents. */
+    data: Buffer;
+    /** Modification time, seconds since the epoch. */
+    mtime: number;
+}
+type NameSplit = {
+    name: string;
+    prefix: string;
+};
+/**
+ * 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 declare function splitTarName(path: string): NameSplit;
+/** Write `entries` as an uncompressed ustar archive. */
+export declare function writeTar(entries: readonly TarEntry[]): Buffer;
+/**
+ * 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 declare function readTarEntries(archive: Buffer): TarEntry[];
+/**
+ * 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".
+ *
+ * The same holds for the names the lock's reclaim derives from that exact path
+ * (APRV-479), every one `<lockfile>.<something>`: the claim on a dead holder's
+ * lockfile (`.stale.<pid>.<ms>`) and a taker's own lockfile before its rename
+ * (`.take.<pid>.<nonce>`), which a writer killed part way leaves behind. They
+ * are the lock's bookkeeping, they carry the writing machine's hostname and
+ * boot id (which the log itself deliberately does not), and nothing in them is
+ * the tenant's.
+ */
+export declare function isExcludedPath(path: string, excludedLock?: string | null): boolean;
+/**
+ * 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 declare class ExportSymlinkError extends Error {
+    /** The store-relative path of the link itself, never its target. */
+    readonly path: string;
+    constructor(path: string);
+}
+/**
+ * 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 declare class ExportHardLinkError extends Error {
+    /** The store-relative path of the link, which is also the file. */
+    readonly path: string;
+    /** How many names this inode has. */
+    readonly links: number;
+    constructor(path: string, links: number);
+}
+export interface StoreArchive {
+    /** The gzipped ustar bytes. */
+    bytes: Buffer;
+    /** The paths it carries, in archive order. Reported, and asserted by tests. */
+    paths: string[];
+}
+/**
+ * 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 declare function buildStoreArchive(root: string, logPath: string): StoreArchive;
+/** `relative()` in POSIX spelling, for callers that hold absolute paths. */
+export declare function storeRelative(root: string, path: string): string;
+export {};