approval-md 0.0.1 → 0.2.0

package/dist/src/core/vault.d.ts

@@ -0,0 +1,291 @@
+/**
+ * The reference credential vault (SPEC.md §10.4, §11; APRV-68).
+ *
+ * SPEC.md §10.4 states the hard boundary in one sentence: adapters "hold the
+ * actual credentials in an encrypted vault and MUST require a valid, unexpired,
+ * single-use execution token bound to the action's `idempotency_key` … an agent
+ * that bypasses the CLI still cannot send, spend, or delete, because the
+ * credentials only answer to tokens." APRV-67 built the token half of that
+ * sentence (`adapters/contract.ts`: a credential provider that is live only
+ * inside the verified-token window). This module is the other half: the place
+ * the values actually sit when nobody is executing.
+ *
+ * ## What it is
+ *
+ * One file, `.approval/vault.enc`, beside the log's home in the same way
+ * `.approval/payloads/` is. It holds a JSON map from credential NAME to
+ * credential string, encrypted with AES-256-GCM under a key derived by scrypt
+ * from an operator passphrase. The passphrase is read from an environment
+ * variable whose NAME the policy declares (`vault.passphrase_env`, default
+ * {@link DEFAULT_PASSPHRASE_ENV}), which is the convention SPEC.md §5.1 already
+ * uses for `channels.telegram.token_env` and §5.2 for
+ * `audit.sampling_secret_env`: the policy file an agent may read carries a
+ * variable name, never a value.
+ *
+ * ## Threat model, stated plainly (SPEC.md §11)
+ *
+ * **What the vault defends.** Credentials at rest: a repository, a backup, or a
+ * synced folder that ends up somewhere it should not be carries ciphertext and
+ * a KDF header, not an SMTP password. And casual reads by an agent with file
+ * access: an agent that can `cat` every file in the working tree learns the
+ * NAMES of nothing and the values of nothing, because the names live inside the
+ * ciphertext too.
+ *
+ * **What it does not defend.** A compromised host. An agent that can read the
+ * passphrase environment variable — such an agent can decrypt the file at
+ * leisure, and no arrangement of this module changes that, which is why the
+ * passphrase belongs in an operator-held environment (a keychain-populated
+ * shell, a systemd credential) and outside every agent-readable path. Nor does
+ * it defend against an operator who exports the passphrase into the same
+ * process an agent drives. This is the same boundary SPEC.md §11 already draws
+ * for the sampling secret and for human identity: the trust boundary is the
+ * local machine, and anyone who can set that configuration is inside it. The
+ * vault raises the cost of a credential leak from "read a file" to "own the
+ * session"; it is not a claim of secrecy against the session's owner.
+ *
+ * ## Invariant 3 is the whole module
+ *
+ * SPEC.md §11.1 invariant 3 — raw secrets never appear in the log — is extended
+ * here to every surface this module touches. No credential VALUE appears in a
+ * return value except {@link getCredential}'s, in no message, no error, no
+ * refusal, and nothing here writes to the log at all. {@link listCredentials}
+ * returns names and a count. `set` and `remove` return counts. That asymmetry is
+ * deliberate and is pinned by a test: the module has exactly one function that
+ * can hand back a credential, and the adapter contract is what decides when it
+ * may be called.
+ *
+ * ## Determinism, and the one place it stops
+ *
+ * Reads are pure functions of the file bytes and the passphrase. Writes are not:
+ * every write draws a fresh 96-bit nonce and (on creation) a fresh 128-bit salt,
+ * so two writes of the same map produce different files. That is required, not
+ * incidental — GCM is catastrophically broken by nonce reuse under one key, and
+ * a deterministic file would also leak "nothing changed" to an observer who only
+ * sees the ciphertext.
+ *
+ * Nothing here throws. Every failure is a `{ ok: false, code, message }` from
+ * the frozen union {@link VAULT_REFUSAL_CODES}.
+ */
+import type { PolicyLoadResult } from "./policy-load.js";
+/** The vault's filename, beside the log's home: `.approval/vault.enc`. */
+export declare const VAULT_FILENAME = "vault.enc";
+/**
+ * The environment variable the passphrase is read from when the policy declares
+ * no `vault.passphrase_env`.
+ *
+ * A default rather than a hard requirement, because a runtime with no policy at
+ * all (or with an unparseable one) must still be able to open a vault an
+ * operator created: the variable name is not a permission, and treating it as
+ * one would mean an unrelated policy typo locked the credentials.
+ */
+export declare const DEFAULT_PASSPHRASE_ENV = "APPROVAL_VAULT_PASSPHRASE";
+/**
+ * The vault file for a given log path — the convention every caller uses.
+ *
+ * Derived exactly as `payloadStoreDirFor` derives the payload store, so the
+ * vault, the store, and the log stay together under one home: SPEC.md §9 fixes
+ * the log at `<home>/log/events.jsonl`, so the vault is `<home>/vault.enc`, a
+ * sibling of the log DIRECTORY and never inside it. Pointing `--log` at some
+ * other layout puts the vault beside that file instead.
+ */
+export declare function vaultPathFor(logPath: string): string;
+/**
+ * The NAME of the environment variable this policy says the passphrase lives in.
+ *
+ * The name only, in both directions: a policy that carried a passphrase would be
+ * a passphrase in a file agents may read, which is the thing the vault exists to
+ * avoid. A policy that failed to load names nothing, so the default applies.
+ */
+export declare function passphraseEnvFor(load: PolicyLoadResult): string;
+/** Is there a vault file at this path? Says nothing about whether it opens. */
+export declare function vaultExists(vaultPath: string): boolean;
+/**
+ * Everything this module can refuse. Frozen public API, per SPEC.md §11.1(6).
+ *
+ * Each code names a different repair, which is the test of whether a code earns
+ * its place. Note the one deliberate *conflation*: {@link "vault-unreadable"}
+ * covers both a wrong passphrase and an altered file, and the message says so
+ * rather than choosing. Distinguishing them would publish an oracle — a caller
+ * who could tell "your passphrase is wrong" from "these bytes were tampered
+ * with" could confirm a guessed passphrase against a file they had modified, and
+ * GCM's authentication tag cannot tell the two apart anyway without first
+ * trusting one of them.
+ */
+export declare const VAULT_REFUSAL_CODES: readonly [
+/** No vault file exists. The repair is `approval vault set <name>`. */
+"vault-absent", 
+/** The named environment variable is unset or empty in this process. */
+"passphrase-unset", 
+/** The file could not be read or written. A filesystem fact, not a secret. */
+"vault-io", 
+/** The file is not the JSON envelope this module writes, or its header lies. */
+"vault-malformed", 
+/** The file declares a format version this build does not implement. */
+"vault-version-unsupported", 
+/**
+ * The ciphertext did not authenticate: the passphrase is wrong OR the file
+ * was altered. Deliberately not distinguished — see the union's own doc.
+ */
+"vault-unreadable", 
+/** The vault opened and holds no credential under that name. */
+"credential-absent", 
+/** The credential name is empty or not a usable name. */
+"invalid-name", 
+/** The credential value is empty. An empty secret is a configuration error. */
+"empty-value", 
+/** The re-encrypted file could not be put in place. Nothing was changed. */
+"vault-write-failed"];
+export type VaultRefusalCode = (typeof VAULT_REFUSAL_CODES)[number];
+/** Every failure of this module. Nothing here throws. */
+export interface VaultRefusal {
+    ok: false;
+    code: VaultRefusalCode;
+    message: string;
+    /** The file the refusal is about, so a caller need not reconstruct it. */
+    path: string;
+}
+/**
+ * The only format version this build writes or reads.
+ *
+ * Versioned from the first byte so that a future scheme (a different AEAD, an
+ * Argon2 KDF, a hardware-backed key) is a migration with two readers rather than
+ * a silent reinterpretation of old bytes. A file declaring anything else is
+ * refused {@link "vault-version-unsupported"} and left untouched: guessing at an
+ * unknown layout is how a decryption bug becomes a corrupted vault.
+ */
+export declare const VAULT_FORMAT_VERSION = 1;
+/**
+ * scrypt cost parameters, written into every file and read back from it.
+ *
+ * `N = 16384, r = 8, p = 1` is the classic interactive tuning: about 16 MiB of
+ * memory (128·N·r) and something on the order of 100 ms on a laptop, which is a
+ * meaningful brute-force cost against a human-typed passphrase while staying
+ * fast enough for a CLI verb a human runs interactively. `keylen` is 32 bytes,
+ * because AES-256-GCM takes a 256-bit key.
+ *
+ * The parameters live in the FILE rather than only in this constant so that a
+ * vault written under one tuning still opens after the tuning changes. They are
+ * bounded on read ({@link readKdf}) rather than trusted: a header claiming
+ * `N = 2^40` would otherwise be a denial-of-service delivered as a config file.
+ */
+export declare const SCRYPT_PARAMS: {
+    readonly N: 16384;
+    readonly r: 8;
+    readonly p: 1;
+    readonly keylen: 32;
+};
+/** What every mutating operation reports. Counts and names, never values. */
+export interface VaultWriteResult {
+    ok: true;
+    path: string;
+    name: string;
+    /** How many credentials the vault holds after the operation. */
+    count: number;
+    /** True when this call added a name the vault did not already hold. */
+    created: boolean;
+}
+/**
+ * Store `value` under `name`, creating the vault when it does not exist.
+ *
+ * The whole map is decrypted, amended, and re-encrypted under a fresh nonce:
+ * there is no partial update, because an AEAD over the whole document is what
+ * makes a partial edit detectable in the first place.
+ *
+ * `value` is a parameter and nothing else — never logged, never echoed, never
+ * placed in a message, including in the refusals this can return.
+ */
+export declare function setCredential(vaultPath: string, passphrase: string, name: string, value: string): VaultWriteResult | VaultRefusal;
+/**
+ * Delete `name`. A name the vault does not hold refuses `credential-absent`
+ * rather than reporting success: an operator removing a credential wants to know
+ * whether they removed the one they meant.
+ */
+export declare function removeCredential(vaultPath: string, passphrase: string, name: string): VaultWriteResult | VaultRefusal;
+/** What the vault holds, by name. There is no shape here that carries a value. */
+export interface VaultListing {
+    ok: true;
+    path: string;
+    /** Sorted credential names. */
+    names: string[];
+    count: number;
+}
+/**
+ * The names in the vault, sorted, and how many there are.
+ *
+ * Names and nothing else, on every path including the error ones. Sorted so two
+ * listings of the same vault are byte-identical, which is what lets a test and
+ * an operator compare them.
+ */
+export declare function listCredentials(vaultPath: string, passphrase: string): VaultListing | VaultRefusal;
+/** The one shape in this module that carries a credential value. */
+export interface VaultCredential {
+    ok: true;
+    path: string;
+    name: string;
+    value: string;
+}
+/**
+ * The value stored under `name`.
+ *
+ * **The only function here that returns a credential**, which is the module's
+ * structural rule and is pinned by `tests/vault.test.ts`. There is no
+ * `approval vault get`, because a verb that printed a credential would put it
+ * in a terminal, a scrollback buffer, a CI log, and a shell history, and would
+ * do so on a machine where the whole point is that the value only ever travels
+ * from this file into the use it was stored for.
+ *
+ * **Two sanctioned callers** (flagged by APRV-220, decided by APRV-257):
+ *
+ * 1. `adapters/vault-provider.ts`, whose provider `executeThroughAdapter`
+ *    scopes to the verified-token window.
+ * 2. `cli/checkpoint-tap.ts`, which reads `approval.checkpoint.key` and hands
+ *    it to `core/checkpoint.ts`'s signer — the one custody decision for every
+ *    surface that can take a checkpoint.
+ *
+ * The rule this list keeps is not "one caller". It is that a credential's value
+ * goes from this file into a USE and never onto a SURFACE, and both callers
+ * obey it: the second takes a private key into an Ed25519 signature and hands
+ * back a signature and a fingerprint of the PUBLIC half.
+ *
+ * The alternative — move the checkpoint key somewhere else and keep this list
+ * at one name — was considered and rejected, because it would have made the key
+ * weaker rather than the module cleaner. The OS keystore has no equivalent of
+ * the passphrase variable `core/child-env.ts` strips from every child
+ * (APRV-205), and a file beside the log has no encryption at all. A checkpoint
+ * key is the one secret whose entire value is that a process an agent launched
+ * cannot reach it, so it belongs in the strictest store this runtime has. What
+ * that costs is a second name in this comment.
+ */
+export declare function getCredential(vaultPath: string, passphrase: string, name: string): VaultCredential | VaultRefusal;
+/**
+ * Does this passphrase open the vault, and how many credentials does it hold?
+ *
+ * The diagnostic form, for `approval doctor`: a yes/no plus a count, with no
+ * name and no value in either the success or the failure. Distinct from
+ * {@link listCredentials} because a health check has no business learning which
+ * credentials an operator keeps.
+ */
+export declare function checkVault(vaultPath: string, passphrase: string): {
+    ok: true;
+    path: string;
+    count: number;
+} | VaultRefusal;
+/**
+ * Read the passphrase from the environment variable named by `envName`.
+ *
+ * Returns the value, or `null` when it is unset or empty. A separate function
+ * so that every caller reads the passphrase the same way and so that no caller
+ * is tempted to accept one as a flag: a passphrase on a command line is a
+ * passphrase in the shell history, in `ps`, and in the parent process's
+ * environment.
+ */
+export declare function passphraseFrom(envName: string, env?: NodeJS.ProcessEnv): string | null;
+/**
+ * Constant-time equality for two secrets, exported for callers that must
+ * compare one without leaking its length-prefix through timing.
+ *
+ * Not used by the vault's own paths (nothing here compares credentials), but the
+ * alternative — a caller writing `a === b` over a secret — is the kind of thing
+ * that gets written once and copied five times.
+ */
+export declare function secretsEqual(left: string, right: string): boolean;