approval-md 0.0.1 → 0.2.0

package/dist/src/cli/vault.js

@@ -0,0 +1,362 @@
+/**
+ * `approval vault` — the human-only credential verbs (SPEC.md §10.4; APRV-68).
+ *
+ * Three subcommands, and note which one is missing:
+ *
+ * - `vault set <name>` stores a credential, creating the vault if absent;
+ * - `vault list` prints the NAMES the vault holds, a count, and the file path;
+ * - `vault remove <name>` deletes one.
+ *
+ * **There is no `vault get`, and there will not be one.** A verb that printed a
+ * credential would put it in a terminal, a scrollback buffer, a `script`
+ * capture, a CI log, and — through the shell that invoked it — quite possibly a
+ * history file. The value's only sanctioned journey is from `.approval/vault.enc`
+ * into an adapter's request, inside the verified execution window the adapter
+ * contract holds open (`src/adapters/vault-provider.ts`). Reading it any other
+ * way is a thing an operator can do with their own passphrase and their own
+ * code; it is not a thing this CLI will do for them, because the moment it
+ * exists it becomes the convenient path.
+ *
+ * For the same reason `set` takes no `--value`. A secret on a command line is a
+ * secret in the shell history, in `ps` output for the length of the call, and in
+ * the environment of anything that inspects the process table. The value comes
+ * from stdin (a pipe, a heredoc, an interactive paste) or from `--value-env
+ * <VAR>`, which names a variable exactly as the policy names the passphrase's.
+ *
+ * **Human-only, by attest's rules.** `--as human:<id>`, else `APPROVAL_HUMAN`;
+ * an `agent:` or `system:` actor is a usage error at exit 2 with the rule
+ * quoted. Identity here is declared, not proved (SPEC.md §11: the trust boundary
+ * is the local machine), and the check is worth having anyway: it is what stops
+ * an agent's tooling from storing or deleting a credential as a side effect of
+ * some other task it was asked to do.
+ *
+ * **Nothing here appends to the log.** Not the set, not the removal, not a
+ * "credential rotated" breadcrumb. The log is the record of actions the gate
+ * authorized; a credential's existence is configuration, and a log line naming
+ * the credentials an operator holds would be a map of the machine's reach
+ * published in the one file this project promises never to rewrite.
+ *
+ * As everywhere else in this CLI, the logic is not here: the cipher, the KDF,
+ * the atomic write, and the refusal vocabulary are `core/vault.ts`. This file
+ * resolves paths and identity, reads bytes at the edge, and maps a core result
+ * onto the frozen exit table.
+ */
+import { readFileSync } from "node:fs";
+import { isAbsolute, resolve as resolvePathSegments } from "node:path";
+import { HUMAN_ACTOR_ENV, resolveHumanActor } from "../core/attest.js";
+import { loadPolicy } from "../core/policy-load.js";
+import { listCredentials, passphraseEnvFor, passphraseFrom, removeCredential, setCredential, vaultExists, vaultPathFor, } from "../core/vault.js";
+import { boolFlag, parseFlags, stringFlag } from "./args.js";
+import { EXIT_INTEGRITY, EXIT_IO, EXIT_OK, EXIT_USAGE } from "./exit-codes.js";
+import { VAULT_HELP, VAULT_LIST_HELP, VAULT_REMOVE_HELP, VAULT_SET_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";
+const COMMON_FLAGS = {
+    "--log": "string",
+    "--vault": "string",
+    "--policy": "string",
+    "--dir": "string",
+    "--as": "string",
+    "--json": "boolean",
+    "--help": "boolean",
+    "-h": "boolean",
+};
+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;
+}
+function emitJson(streams, value) {
+    streams.out(`${JSON.stringify(value)}\n`);
+}
+/**
+ * A vault refusal onto the frozen exit table, by the split every other verb
+ * draws: a filesystem fact is 4, and everything the runtime itself decided —
+ * a wrong passphrase, an absent name, a header it will not act on — is 1. The
+ * command was well-formed; the answer is no.
+ */
+function refusalExitCode(refusal) {
+    switch (refusal.code) {
+        case "vault-io":
+        case "vault-write-failed":
+            return EXIT_IO;
+        default:
+            return EXIT_INTEGRITY;
+    }
+}
+function emitRefusal(streams, json, refusal) {
+    if (json) {
+        streams.err(`${JSON.stringify({ ok: false, error: { code: refusal.code, message: refusal.message, path: refusal.path } })}\n`);
+    }
+    else {
+        streams.err(`${renderRefusal(style({ json }), refusal.code, refusal.message)}\n`);
+    }
+    return refusalExitCode(refusal);
+}
+/**
+ * Flags, `--help`, the vault path, and the passphrase variable's name.
+ *
+ * The policy is consulted for one thing only — `vault.passphrase_env` — and an
+ * unloadable policy does not stop the verb: the variable's NAME is not a
+ * permission, and an operator locked out of their own credentials by an
+ * unrelated schema typo would be a fail-closed rule applied where nothing is
+ * being authorized. `passphraseEnvFor` returns the default in that case.
+ */
+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 };
+    }
+    const vaultFlag = stringFlag(parsed.flags, "--vault");
+    const logPath = resolvePath(stringFlag(parsed.flags, "--log"), DEFAULT_LOG_PATH, cwd);
+    const vaultPath = vaultFlag === null ? vaultPathFor(logPath) : absolute(vaultFlag, cwd);
+    const policyFlag = stringFlag(parsed.flags, "--policy");
+    const dirFlag = stringFlag(parsed.flags, "--dir");
+    const passphraseEnv = passphraseEnvFor(loadPolicy(policyFlag !== null
+        ? { file: absolute(policyFlag, cwd) }
+        : { dir: dirFlag === null ? cwd : absolute(dirFlag, cwd) }));
+    return {
+        kind: "run",
+        flags: parsed.flags,
+        positionals: parsed.positionals,
+        json,
+        vaultPath,
+        passphraseEnv,
+    };
+}
+/** The human-only rule, spelled exactly as `policy attest` spells it. */
+function requireHuman(flags, streams, json, helpText, verb) {
+    const asFlag = stringFlag(flags, "--as");
+    const actor = resolveHumanActor(asFlag === null ? {} : { actor: asFlag });
+    if (actor !== null)
+        return { ok: true, actor };
+    return {
+        ok: false,
+        code: usageError(streams, json, asFlag === null
+            ? `no human identity: set ${HUMAN_ACTOR_ENV}=human:<id> or pass --as human:<id>`
+            : `--as expects a human identity matching human:<id>, got ${JSON.stringify(asFlag)}; \`approval vault ${verb}\` is human-only and an agent: or system: actor cannot perform it`, helpText),
+    };
+}
+/** The passphrase, or a usage error naming the variable it should be in. */
+function requirePassphrase(passphraseEnv, streams, json, helpText) {
+    const passphrase = passphraseFrom(passphraseEnv);
+    if (passphrase !== null)
+        return { ok: true, passphrase };
+    return {
+        ok: false,
+        code: usageError(streams, json, `${passphraseEnv} is unset or empty: the vault passphrase is read from that environment variable and from nowhere else. The policy names the variable (vault.passphrase_env) and never the value, and there is no --passphrase flag, because a passphrase on a command line is a passphrase in the shell history.`, helpText),
+    };
+}
+// ===========================================================================
+// approval vault set
+// ===========================================================================
+/**
+ * The credential value: `--value-env <VAR>`, else stdin.
+ *
+ * One trailing newline is stripped and nothing else is touched. A here-doc, an
+ * `echo`, and a password manager's `--raw` output all arrive with exactly one,
+ * and an operator who genuinely needs a trailing newline inside a credential can
+ * pass it through `--value-env`. Interior whitespace is preserved: some tokens
+ * legitimately contain it, and silently trimming a credential produces an
+ * authentication failure at the far end with no local evidence of why.
+ */
+function readValue(flags, streams, json) {
+    const valueEnv = stringFlag(flags, "--value-env");
+    if (valueEnv !== null) {
+        const value = process.env[valueEnv];
+        if (typeof value !== "string" || value.length === 0) {
+            return {
+                ok: false,
+                code: usageError(streams, json, `--value-env names ${valueEnv}, which is unset or empty in this process; nothing was stored`, VAULT_SET_HELP),
+            };
+        }
+        return { ok: true, value };
+    }
+    let raw;
+    try {
+        raw = readFileSync(0, "utf8");
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            code: usageError(streams, json, `the credential value could not be read from stdin (${cause instanceof Error ? cause.message : String(cause)}); pipe it in, or name a variable with --value-env <VAR>`, VAULT_SET_HELP),
+        };
+    }
+    const value = raw.endsWith("\n") ? raw.slice(0, -1) : raw;
+    if (value.length === 0) {
+        return {
+            ok: false,
+            code: usageError(streams, json, "stdin carried no credential value; pipe the secret in (`… | approval vault set <name>`) or name a variable with --value-env <VAR>. There is deliberately no --value flag: a secret on a command line is a secret in the shell history.", VAULT_SET_HELP),
+        };
+    }
+    return { ok: true, value };
+}
+/** `approval vault set <name>` — store a credential. HUMAN-ONLY. */
+export function commandVaultSet(argv, streams, cwd) {
+    const outcome = front(argv, { ...COMMON_FLAGS, "--value-env": "string" }, VAULT_SET_HELP, streams, cwd);
+    if (outcome.kind === "handled")
+        return outcome.code;
+    const { flags, positionals, json, vaultPath, passphraseEnv } = outcome;
+    const name = positionals[0];
+    if (name === undefined) {
+        return usageError(streams, json, "missing <name> argument", VAULT_SET_HELP);
+    }
+    const extra = positionals[1];
+    if (extra !== undefined) {
+        return usageError(streams, json, 
+        // The argument is NOT echoed, unlike everywhere else in this CLI. The
+        // likeliest thing a second positional here is, is the credential itself,
+        // and a runtime that quoted it back would publish the secret into the
+        // terminal and the CI log of the very operator who was being told not to
+        // put it on a command line.
+        "unexpected second argument (not echoed, in case it is the credential) — the VALUE is never a command-line argument; it comes from stdin or --value-env <VAR>, because a secret on a command line is a secret in the shell history", VAULT_SET_HELP);
+    }
+    const human = requireHuman(flags, streams, json, VAULT_SET_HELP, "set");
+    if (!human.ok)
+        return human.code;
+    const pass = requirePassphrase(passphraseEnv, streams, json, VAULT_SET_HELP);
+    if (!pass.ok)
+        return pass.code;
+    const value = readValue(flags, streams, json);
+    if (!value.ok)
+        return value.code;
+    const result = setCredential(vaultPath, pass.passphrase, name, value.value);
+    if (!result.ok)
+        return emitRefusal(streams, json, result);
+    if (json) {
+        emitJson(streams, {
+            ok: true,
+            name: result.name,
+            created: result.created,
+            count: result.count,
+            path: result.path,
+        });
+    }
+    else {
+        streams.out(`${result.created ? "stored" : "replaced"} ${result.name} in ${result.path} (${String(result.count)} credential(s); the value is not printed anywhere)\n`);
+    }
+    return EXIT_OK;
+}
+// ===========================================================================
+// approval vault list
+// ===========================================================================
+/**
+ * `approval vault list` — the NAMES, the count, and the path. HUMAN-ONLY.
+ *
+ * A vault that does not exist is reported and exits 0. Nobody has created one,
+ * which is a state and not a fault: a runtime driven entirely by `approval run`
+ * and the CLI channel never needs a credential, exactly as a runtime with no
+ * Telegram configuration is healthy without one.
+ */
+export function commandVaultList(argv, streams, cwd) {
+    const outcome = front(argv, COMMON_FLAGS, VAULT_LIST_HELP, streams, cwd);
+    if (outcome.kind === "handled")
+        return outcome.code;
+    const { flags, positionals, json, vaultPath, passphraseEnv } = outcome;
+    const extra = positionals[0];
+    if (extra !== undefined) {
+        return usageError(streams, json, `unexpected argument ${JSON.stringify(extra)}`, VAULT_LIST_HELP);
+    }
+    const human = requireHuman(flags, streams, json, VAULT_LIST_HELP, "list");
+    if (!human.ok)
+        return human.code;
+    if (!vaultExists(vaultPath)) {
+        if (json) {
+            emitJson(streams, { ok: true, present: false, path: vaultPath, count: 0, names: [] });
+        }
+        else {
+            streams.out(`no vault at ${vaultPath} — nobody has created one, which is a state and not a fault; \`approval vault set <name>\` creates it\n`);
+        }
+        return EXIT_OK;
+    }
+    const pass = requirePassphrase(passphraseEnv, streams, json, VAULT_LIST_HELP);
+    if (!pass.ok)
+        return pass.code;
+    const result = listCredentials(vaultPath, pass.passphrase);
+    if (!result.ok)
+        return emitRefusal(streams, json, result);
+    if (json) {
+        emitJson(streams, {
+            ok: true,
+            present: true,
+            path: result.path,
+            count: result.count,
+            names: result.names,
+        });
+    }
+    else {
+        streams.out(`${result.path}: ${String(result.count)} credential(s)\n`);
+        for (const name of result.names)
+            streams.out(`${name}\n`);
+    }
+    return EXIT_OK;
+}
+// ===========================================================================
+// approval vault remove
+// ===========================================================================
+/** `approval vault remove <name>` — delete a credential. HUMAN-ONLY. */
+export function commandVaultRemove(argv, streams, cwd) {
+    const outcome = front(argv, COMMON_FLAGS, VAULT_REMOVE_HELP, streams, cwd);
+    if (outcome.kind === "handled")
+        return outcome.code;
+    const { flags, positionals, json, vaultPath, passphraseEnv } = outcome;
+    const name = positionals[0];
+    if (name === undefined) {
+        return usageError(streams, json, "missing <name> argument", VAULT_REMOVE_HELP);
+    }
+    const extra = positionals[1];
+    if (extra !== undefined) {
+        return usageError(streams, json, `unexpected argument ${JSON.stringify(extra)}`, VAULT_REMOVE_HELP);
+    }
+    const human = requireHuman(flags, streams, json, VAULT_REMOVE_HELP, "remove");
+    if (!human.ok)
+        return human.code;
+    const pass = requirePassphrase(passphraseEnv, streams, json, VAULT_REMOVE_HELP);
+    if (!pass.ok)
+        return pass.code;
+    const result = removeCredential(vaultPath, pass.passphrase, name);
+    if (!result.ok)
+        return emitRefusal(streams, json, result);
+    if (json) {
+        emitJson(streams, { ok: true, name: result.name, count: result.count, path: result.path });
+    }
+    else {
+        streams.out(`removed ${result.name} from ${result.path} (${String(result.count)} credential(s) remain)\n`);
+    }
+    return EXIT_OK;
+}
+/** `approval vault <subcommand>` — `set`, `list`, `remove`. */
+export function commandVault(argv, streams, cwd) {
+    const sub = argv[0];
+    const rest = argv.slice(1);
+    const json = argv.includes("--json");
+    if (sub === undefined) {
+        return usageError(streams, json, "missing subcommand for `approval vault`", VAULT_HELP);
+    }
+    if (sub === "--help" || sub === "-h" || sub === "help") {
+        streams.out(`${VAULT_HELP}\n`);
+        return EXIT_OK;
+    }
+    if (sub === "set")
+        return commandVaultSet(rest, streams, cwd);
+    if (sub === "list")
+        return commandVaultList(rest, streams, cwd);
+    if (sub === "remove")
+        return commandVaultRemove(rest, streams, cwd);
+    if (sub === "get") {
+        return usageError(streams, json, "there is no `approval vault get`, and it is not an oversight: a verb that printed a credential would put it in a terminal, a scrollback buffer, a CI log and a shell history. A credential's only sanctioned journey is from the vault into an adapter, inside the verified execution window. Use `approval vault list` to see the names.", VAULT_HELP);
+    }
+    return usageError(streams, json, `unknown subcommand ${JSON.stringify(sub)} for \`approval vault\``, VAULT_HELP);
+}
+//# sourceMappingURL=vault.js.map

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

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

package/dist/src/cli/verb-registry.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The verb registry: ONE structured description of the CLI surface, for every
+ * machine that has to consume it.
+ *
+ * SPEC.md §10.1 makes the CLI the primary interface for humans and agents, and
+ * §10.5 gives the optional MCP wrapper "the same verbs as tools", sharing the
+ * CLI's code paths. Two surfaces publishing the same contract from two hand-kept
+ * lists is two surfaces that drift, so both read this one: `approval
+ * instructions --schemas` prints it verbatim, and an MCP server maps it into
+ * tool descriptions and input schemas without re-deriving anything.
+ *
+ * **This file restates; it does not replace.** Each `purpose` is a one-paragraph
+ * agent-facing summary of what the verb's own `--help` says at length, and
+ * `src/cli/help.ts` remains the authority on prose. A verb whose help text and
+ * whose registry entry disagree is a defect in this file.
+ *
+ * **The schemas are the frozen shapes, written down.** The `--json` outputs are
+ * frozen public API (see `exit-codes.ts` and every `--help`), and the existing
+ * CLI suites pin them with `deepEqual` on whole objects. `output` here is the
+ * same commitment in JSON Schema form, and `tests/cli-instructions.test.ts`
+ * pins it in both directions: every schema must compile under the repo's Ajv
+ * setup, and real `--json` output captured from a live CLI run must validate
+ * against it. A shape change without a schema change fails there; a schema
+ * change without a shape change fails the `deepEqual` suites.
+ *
+ * **`human_only` is a safety marker, not a convenience flag.** It means: this
+ * verb records or establishes a human's authority, and an MCP wrapper MUST NOT
+ * publish it as a tool an agent can call. The runtime enforces the human-only
+ * verbs itself (in the CLI layer, again in core, again in the event schema);
+ * this marker exists so a wrapper does not offer an agent a door the runtime
+ * will only slam.
+ */
+/** A JSON Schema document, carried opaquely. Validated by Ajv, never by us. */
+export type JsonSchema = {
+    readonly [key: string]: unknown;
+};
+/** One exit code and what it means for this verb. */
+export interface ExitCodeMeaning {
+    readonly code: number;
+    readonly meaning: string;
+}
+/** Everything a machine needs to call one verb and read its answer. */
+export interface VerbSpec {
+    /** The top-level verb, exactly as it appears in `main.ts`'s dispatch. */
+    readonly name: string;
+    /** The subcommand path under it, when there is one ("verify", "telegram listen"). */
+    readonly subcommand?: string;
+    /** One paragraph, agent-facing: what this verb is for and what it does not do. */
+    readonly purpose: string;
+    /**
+     * True when the verb records or establishes a human's authority. An MCP
+     * wrapper MUST NOT expose these as agent-callable tools.
+     */
+    readonly human_only: boolean;
+    /** Why, for the cases where the answer needed an argument rather than a lookup. */
+    readonly human_only_note?: string;
+    /** Positional arguments, flags, and (where a verb takes one) the trailing argv. */
+    readonly input: JsonSchema;
+    /** The `--json` SUCCESS shape, or null for a verb that emits no single object. */
+    readonly output: JsonSchema | null;
+    /** The `--json` failure shape. Shared: every verb answers failures the same way. */
+    readonly error: JsonSchema;
+    /** The exit codes this verb can produce, with this verb's meaning for each. */
+    readonly exit_codes: readonly ExitCodeMeaning[];
+}
+/**
+ * The shared failure shape. Usage and I/O failures print
+ * `{"error":{"code","message"}}`; a gate refusal prints the same object with
+ * `ok:false` beside it and refusal-specific detail inside `error`. Both forms
+ * go to stderr, and both are one object per invocation.
+ */
+export declare const ERROR_SCHEMA: JsonSchema;
+/** The registry. Order is the order the verb table prints in. */
+export declare const VERB_REGISTRY: readonly VerbSpec[];
+/** `<name>` or `<name> <subcommand>` — how a verb is written on a command line. */
+export declare function verbLabel(spec: VerbSpec): string;