approval-md 0.0.1 → 0.2.0

package/dist/src/cli/token.js

@@ -0,0 +1,274 @@
+/**
+ * The token verbs: `approval token` (status) and `approval consume` (plumbing).
+ *
+ * As everywhere else in this CLI, **no logic lives here.** Minting, verification,
+ * the death conditions, and the append are all `core/token.ts`; this file
+ * resolves paths and identity, chooses an exit code, and formats output.
+ *
+ * ## `approval token` reports status; it does not print the token
+ *
+ * SPEC.md §10.1 lists `approval token <action-key>  # print single-use execution
+ * token if granted`. Under the settled hash-only design (2026-08-06) the log
+ * carries `sha256(token)` and the raw token is returned by the grant call and
+ * kept nowhere else — so there is nothing for this verb to fetch. It would have
+ * to *store* the secret to print it, which is precisely the property the design
+ * exists to avoid.
+ *
+ * The honest reading, and the one implemented here: the token is printed **by
+ * `approval grant`**, once; `approval token` answers "is a live, unspent token
+ * outstanding for this action, and what is its digest?". That interpretation is
+ * flagged in the task notes for human review — it is a reading of the spec, not
+ * a silent amendment of it, and §10.4's normative sentence (adapters MUST
+ * require a valid, unexpired, single-use token bound to the idempotency key) is
+ * unaffected either way.
+ *
+ * ## `approval consume` is internal
+ *
+ * It is the seam APRV-18's `approval run` will wrap: verify, append
+ * `execution.started`, hand control to the command. It ships now so the token
+ * boundary is testable end to end and so an adapter integration can be driven by
+ * hand, and its help text says INTERNAL in the first line.
+ *
+ * Exit codes are the frozen table, mapped exactly as the gate verbs map them: a
+ * refusal ("that token will not execute") is 1, because the command was
+ * well-formed and the answer is no; only filesystem facts are 4 and only a
+ * crashed write is 3.
+ */
+import { isAbsolute, resolve as resolvePathSegments } from "node:path";
+import { HUMAN_ACTOR_ENV, resolveHumanActor } from "../core/attest.js";
+import { normalizeUsd } from "../core/money.js";
+import { isPayloadHash } from "../core/payload.js";
+import { readVerifiedRecords } from "../core/state.js";
+import { consumeToken, humanOnlyClassRefusal, tokenPolicy, tokenStatus, } from "../core/token.js";
+import { boolFlag, parseFlags, stringFlag } from "./args.js";
+import { EXIT_INTEGRITY, EXIT_IO, EXIT_OK, EXIT_TORN_TAIL, EXIT_USAGE, } from "./exit-codes.js";
+import { CONSUME_HELP, TOKEN_HELP } from "./help.js";
+import { DEFAULT_LOG_PATH, resolvePath } from "./paths.js";
+import { refusal as renderRefusal, style } from "./style.js";
+import { usageErrorText } from "./usage.js";
+/** Identity accepted by `consume`: a person or an agent, never the runtime. */
+const PRINCIPAL_ACTOR = /^(human|agent):.+/u;
+const COMMON_FLAGS = {
+    "--log": "string",
+    "--json": "boolean",
+    "--help": "boolean",
+    "-h": "boolean",
+    "--policy": "string",
+    "--dir": "string",
+};
+function absolute(value, cwd) {
+    return isAbsolute(value) ? value : resolvePathSegments(cwd, value);
+}
+function usageError(streams, json, message, helpText) {
+    if (json)
+        streams.err(`${JSON.stringify({ error: { code: "usage", message } })}\n`);
+    else
+        streams.err(usageErrorText(message, helpText));
+    return EXIT_USAGE;
+}
+/** The same split the gate verbs draw: integrity unless the filesystem spoke. */
+function refusalExitCode(refusal) {
+    switch (refusal.code) {
+        case "log-unreadable":
+            return EXIT_IO;
+        case "log-torn-tail":
+            return EXIT_TORN_TAIL;
+        case "append-failed":
+            switch (refusal.append?.code) {
+                case "corrupt-tail":
+                    return EXIT_TORN_TAIL;
+                case "io":
+                case "lock-timeout":
+                    return EXIT_IO;
+                default:
+                    return EXIT_INTEGRITY;
+            }
+        default:
+            return EXIT_INTEGRITY;
+    }
+}
+function emitRefusal(streams, json, refusal) {
+    if (json) {
+        const error = { code: refusal.code, message: refusal.message };
+        if (refusal.state !== undefined)
+            error["state"] = refusal.state;
+        if (refusal.seq !== undefined)
+            error["seq"] = refusal.seq;
+        streams.err(`${JSON.stringify({ ok: false, error })}\n`);
+    }
+    else {
+        streams.err(`${renderRefusal(style({ json }), refusal.code, refusal.message)}\n`);
+    }
+    return refusalExitCode(refusal);
+}
+function emitJson(streams, value) {
+    streams.out(`${JSON.stringify(value)}\n`);
+}
+/** Where policy lives, from `--policy` / `--dir`, with the CLI's cwd default. */
+function tokenOptions(flags, cwd) {
+    const policyFlag = stringFlag(flags, "--policy");
+    const dirFlag = stringFlag(flags, "--dir");
+    if (policyFlag !== null)
+        return { policyFile: absolute(policyFlag, cwd) };
+    return { policyDir: dirFlag === null ? cwd : absolute(dirFlag, cwd) };
+}
+/** The clock is read here, at the edge, and handed to core. */
+function now() {
+    return new Date().toISOString();
+}
+function front(argv, spec, helpText, streams, cwd) {
+    const json = argv.includes("--json");
+    const parsed = parseFlags(argv, spec);
+    if (!parsed.ok) {
+        return { kind: "handled", code: usageError(streams, json, parsed.message, helpText) };
+    }
+    if (boolFlag(parsed.flags, "--help") || boolFlag(parsed.flags, "-h")) {
+        streams.out(`${helpText}\n`);
+        return { kind: "handled", code: EXIT_OK };
+    }
+    return {
+        kind: "run",
+        flags: parsed.flags,
+        positionals: parsed.positionals,
+        json,
+        logPath: resolvePath(stringFlag(parsed.flags, "--log"), DEFAULT_LOG_PATH, cwd),
+    };
+}
+/** `<action-key>` and nothing else. */
+function actionKeyOf(positionals, streams, json, helpText) {
+    const actionKey = positionals[0];
+    if (actionKey === undefined) {
+        return { ok: false, code: usageError(streams, json, "missing <action-key> argument", helpText) };
+    }
+    const extra = positionals[1];
+    if (extra !== undefined) {
+        return {
+            ok: false,
+            code: usageError(streams, json, `unexpected argument ${JSON.stringify(extra)}`, helpText),
+        };
+    }
+    return { ok: true, actionKey };
+}
+// ---------------------------------------------------------------------------
+// token
+// ---------------------------------------------------------------------------
+export function commandToken(argv, streams, cwd) {
+    const outcome = front(argv, COMMON_FLAGS, TOKEN_HELP, streams, cwd);
+    if (outcome.kind === "handled")
+        return outcome.code;
+    const { flags, positionals, json, logPath } = outcome;
+    const key = actionKeyOf(positionals, streams, json, TOKEN_HELP);
+    if (!key.ok)
+        return key.code;
+    const read = readVerifiedRecords(logPath);
+    if (!read.ok) {
+        return emitRefusal(streams, json, {
+            ok: false,
+            // The read refusal's code is already one of this command's codes
+            // (`log-unreadable`, `log-torn-tail`, `log-corrupt`); it is surfaced
+            // unchanged so a corrupt log is reported as corruption, not as I/O.
+            code: read.code,
+            message: read.message,
+        });
+    }
+    const options = tokenOptions(flags, cwd);
+    const load = tokenPolicy(options);
+    const status = tokenStatus(read.records, key.actionKey, now(), load.ok ? load.durations.approvalTtlMs : null);
+    if (!status.ok) {
+        // APRV-106. `token` is the verb an operator runs to ask "is there a key for
+        // this?", and for a harness-executed grant the answer is a fact rather than
+        // a fault: the human decided, and the decision was a permission answer to a
+        // process that runs the command itself. Said in one line, above the refusal,
+        // so nobody goes looking for a token that was deliberately never minted.
+        if (status.code === "harness-executed" && !json) {
+            streams.out(`${key.actionKey}: none minted: harness-executed\n`);
+        }
+        return emitRefusal(streams, json, status);
+    }
+    // APRV-185. The grant is intact and the token is unspent, and the class it
+    // authorizes is one the policy now reserves to human hands — so `live: true`
+    // would be a true sentence about the log and a false one about the world.
+    // This verb exists to answer "can this be spent?", and the honest answer for
+    // a class raised to `human-only` after its grant is no. `core/token.ts`
+    // refuses the spend itself with the same code and the same words.
+    const reserved = humanOnlyClassRefusal(load, status.class, `the token for action ${status.actionKey}, granted at seq ${status.grantSeq}, is unspent and unspendable`);
+    if (reserved !== null)
+        return emitRefusal(streams, json, reserved);
+    if (json) {
+        emitJson(streams, {
+            ok: true,
+            action_key: status.actionKey,
+            state: "granted",
+            live: true,
+            token_sha256: status.tokenSha256,
+            grant_seq: status.grantSeq,
+            class: status.class,
+            est_cost_usd: status.est_cost_usd,
+            payload_hash: status.payloadHash,
+            task: status.task,
+        });
+    }
+    else {
+        streams.out(`${status.actionKey}: granted at seq ${status.grantSeq}, token live and unspent\n` +
+            `token_sha256: ${status.tokenSha256}\n` +
+            `The raw token was printed once by \`approval grant\` and is stored nowhere — ` +
+            `if it was lost, revoke the grant and request the action again.\n`);
+    }
+    return EXIT_OK;
+}
+// ---------------------------------------------------------------------------
+// consume
+// ---------------------------------------------------------------------------
+export function commandConsume(argv, streams, cwd) {
+    const outcome = front(argv, { ...COMMON_FLAGS, "--token": "string", "--as": "string", "--payload-hash": "string" }, CONSUME_HELP, streams, cwd);
+    if (outcome.kind === "handled")
+        return outcome.code;
+    const { flags, positionals, json, logPath } = outcome;
+    const key = actionKeyOf(positionals, streams, json, CONSUME_HELP);
+    if (!key.ok)
+        return key.code;
+    const token = stringFlag(flags, "--token");
+    if (token === null) {
+        return usageError(streams, json, "missing --token <t>", CONSUME_HELP);
+    }
+    const asFlag = stringFlag(flags, "--as");
+    const actor = asFlag === null ? resolveHumanActor() : asFlag;
+    if (actor === null || !PRINCIPAL_ACTOR.test(actor)) {
+        if (asFlag !== null) {
+            return usageError(streams, json, `--as expects human:<id> or agent:<id>, got ${JSON.stringify(asFlag)}`, CONSUME_HELP);
+        }
+        return usageError(streams, json, `no identity: set ${HUMAN_ACTOR_ENV}=human:<id> or pass --as human:<id> | agent:<id>`, CONSUME_HELP);
+    }
+    const payloadHash = stringFlag(flags, "--payload-hash");
+    if (payloadHash !== null && !isPayloadHash(payloadHash)) {
+        return usageError(streams, json, `--payload-hash expects 64 lowercase hex characters (SHA-256 over the RFC 8785 canonical serialization of the payload), got ${JSON.stringify(payloadHash)}`, CONSUME_HELP);
+    }
+    const result = consumeToken(logPath, key.actionKey, token, actor, {
+        ...tokenOptions(flags, cwd),
+        ...(payloadHash === null ? {} : { presentedPayloadHash: payloadHash }),
+    });
+    if (!result.ok)
+        return emitRefusal(streams, json, result);
+    const payload = (result.record.payload ?? {});
+    if (json) {
+        emitJson(streams, {
+            ok: true,
+            action_key: key.actionKey,
+            event: "execution.started",
+            seq: result.record.seq,
+            token_sha256: result.tokenSha256,
+            grant_seq: result.grantSeq,
+            class: payload["class"] ?? null,
+            // Reported exactly as the record spells it (APRV-121): the `--json`
+            // surface is the log in JSON, so the canonical decimal string travels
+            // through unparsed.
+            est_cost_usd: normalizeUsd(payload["est_cost_usd"]),
+            payload_hash: payload["payload_hash"] ?? null,
+        });
+    }
+    else {
+        streams.out(`consumed ${key.actionKey}: execution.started at seq ${result.record.seq} by ${actor} (token minted at seq ${result.grantSeq})\n`);
+    }
+    return EXIT_OK;
+}
+//# sourceMappingURL=token.js.map

package/dist/src/cli/token.js.map

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

package/dist/src/cli/up.d.ts

@@ -0,0 +1,155 @@
+/**
+ * `approval up` — the ambient runtime: one process for the daemon and every
+ * channel the policy configures (SPEC.md §10.2/§10.3, APRV-110).
+ *
+ * Until now a working gate was two foreground processes an operator had to
+ * remember: `approval daemon run` to watch the files and expire what lapsed, and
+ * `approval channel telegram listen` to put requests in front of a human and
+ * collect the answer. Two terminals, two lifetimes, and a system that is half up
+ * whenever one of them is not. This verb runs both, plus the local queue page,
+ * under one supervisor, one set of signal handlers, and one event stream.
+ *
+ * **No logic lives here either.** The loop is still `daemon/daemon.ts`, the
+ * dispatch cycle is still `cli/channel-telegram.ts`'s `dispatchPending`, and the
+ * queue page is still `channel-web.ts`'s `startWebChannel` — which has said
+ * "exported for the tests and for the M5 daemon" since APRV-25. What this file
+ * adds is supervision: which parts to start, what to do when one falls over, and
+ * how to stop them all at once.
+ *
+ * ## Per-part crash isolation
+ *
+ * A channel is a network client and the daemon is not. A Bot API that starts
+ * refusing sends must not stop TTL expiry, write-back or the queue projection —
+ * that inversion is exactly what the split into two processes bought, and it is
+ * what this file has to buy back. So:
+ *
+ * - the DAEMON settles the verb. Its outcome chooses the exit code, exactly as
+ *   `approval daemon run` maps it, and its failure stops everything;
+ * - a CHANNEL that falls over is reported and restarted after a doubling
+ *   backoff, forever. There is no attempt limit for the same reason
+ *   `dispatchPending` has no send limit: giving up would turn an outage into a
+ *   pending request no human ever sees;
+ * - a channel that cannot start AT ALL — a credential the policy names is unset,
+ *   no declared human identity — is not started, and the refusal is reported in
+ *   `approval doctor`'s vocabulary (a `skip`, a detail, a fix). Fail closed, and
+ *   then carry on with the parts that can run: a half-armed runtime that says
+ *   nothing is the failure this project exists to prevent, and a runtime that
+ *   refused to start the daemon because Telegram was unconfigured would be
+ *   withholding the projection over a channel nobody asked for.
+ *
+ * ## The credentials come from the launch environment, and only from there
+ *
+ * SPEC.md §11.1 invariant 7: no verb loads `.approval/env` implicitly. This one
+ * does not either. The bot token, the chat id and the approver identity are read
+ * from `process.env` — the environment the operator launched this process with —
+ * through exactly the same resolvers the separate listener uses. `approval setup
+ * service` writes a unit that names those variables, or runs a wrapper that
+ * evaluates `approval env`, and either way a human wrote the line that does it.
+ *
+ * ## The event stream is an additive union
+ *
+ * `--json` prints one object per line, and every object is one of three kinds:
+ * a `DaemonEvent` verbatim, a listener line verbatim (`notified`, `decision`,
+ * `annotated`, `listening`, `stopped`), or one of this file's own supervision
+ * lines ({@link UpEvent}). Nothing is rewritten and no field is added to a shape
+ * that already existed: the decision object is byte-identical to the one
+ * `channel telegram listen` prints, because it is printed by the same function.
+ * That is what makes the composed test suite an assertion about equivalence
+ * rather than about a new format.
+ *
+ * The one shape that appears twice is `stopped`: the daemon's carries its tick
+ * counters and a channel's carries its delivery counters, and a supervisor that
+ * branches on `event` alone can tell them apart by their fields. Renaming either
+ * would have broken a stream an operator already parses.
+ *
+ * ## What it does not do
+ *
+ * It does not fork, write a pidfile, or manage its own lifecycle, for the reason
+ * `approval daemon run` gives: `launchd` and `systemd` do that better, and
+ * `approval setup service` is the verb that hands them the unit.
+ */
+import type { Streams } from "./main.js";
+import { type PreflightEvent } from "./preflight.js";
+import { type Style } from "./style.js";
+/** The parts one ambient runtime supervises. A closed set at v0.1. */
+export type UpPart = "daemon" | "telegram" | "web";
+/**
+ * One supervision line. **Additive**: these `event` values are new, and no
+ * existing `DaemonEvent` or listener line changes shape because they exist.
+ *
+ * `part_unavailable` deliberately carries `approval doctor`'s four fields —
+ * `check`, `status`, `detail`, `fix` — rather than inventing a vocabulary for
+ * the same fact. An operator who has read one report can read the other.
+ */
+export type UpEvent = {
+    event: "up_started";
+    parts: UpPart[];
+    log: string;
+} | {
+    event: "part_started";
+    part: UpPart;
+    detail: string;
+} | {
+    event: "part_unavailable";
+    part: UpPart;
+    check: string;
+    status: "skip";
+    detail: string;
+    fix: string | null;
+} | {
+    event: "part_failed";
+    part: UpPart;
+    /** Consecutive failures for this part, counting this one. */
+    attempt: number;
+    message: string;
+    /** How long the supervisor waits before starting it again. */
+    restart_in_ms: number;
+} | {
+    event: "part_restarted";
+    part: UpPart;
+    attempt: number;
+} | {
+    event: "part_stopped";
+    part: UpPart;
+    reason: string;
+} | {
+    event: "up_stopped";
+    reason: string;
+}
+/**
+ * The startup preflight's two lines (APRV-215), emitted before anything else
+ * and defined in `cli/preflight.ts` because `approval daemon run` prints the
+ * same pair from a module that cannot import this one.
+ *
+ * ADDITIVE, like every line above them: no field is added to a shape that
+ * already existed, and in particular `up_started` is untouched. The commit the
+ * process ends up running is named on `preflight` rather than there, because a
+ * consumer that already parses `up_started` must not have to learn a new key
+ * to keep working.
+ */
+ | PreflightEvent;
+/** The first backoff after a part falls over. Doubles to {@link UP_RESTART_MAX_MS}. */
+export declare const UP_RESTART_BASE_MS = 1000;
+/** The ceiling the doubling stops at, so a long outage retries once a minute. */
+export declare const UP_RESTART_MAX_MS = 60000;
+/**
+ * How long a part must have been running before a failure is treated as a fresh
+ * one rather than as the next step of a crash loop. A channel that ran for an
+ * hour and then hit a network blip should retry in a second, not in a minute.
+ */
+export declare const UP_STABLE_MS = 60000;
+/**
+ * One supervision line as a human sentence, and where it belongs.
+ *
+ * `st` is injectable for the render tests, exactly as doctor's renderer takes
+ * one; the default asks the process, which is what the verb wants.
+ */
+export declare function describeUpEvent(event: UpEvent, st?: Style): {
+    text: string;
+    stderr: boolean;
+};
+/**
+ * `approval up` (and `approval daemon run --with-channels`, which is the same
+ * function reached from the other spelling).
+ */
+export declare function commandUp(argv: string[], streams: Streams, cwd: string): number | Promise<number>;