approval-md 0.0.1 → 0.1.0

package/dist/src/adapters/vault-provider.js

@@ -0,0 +1,161 @@
+/**
+ * The vault as a {@link CredentialProvider} (SPEC.md §10.4; APRV-68).
+ *
+ * `adapters/contract.ts` left one seam open and named the task that would fill
+ * it: "No vault. {@link CredentialProvider} is the seam a real vault implements
+ * (APRV-68)." This module is that implementation, and it is deliberately thin.
+ * Everything about *when* a credential may be read belongs to the contract;
+ * everything about *how* the bytes are stored belongs to `core/vault.ts`. What
+ * is left here is the translation between the two vocabularies.
+ *
+ * ## The structural rule
+ *
+ * A provider built here is only ever handed to
+ * {@link executeThroughAdapter} through {@link AdapterExecuteOptions.credentials}.
+ * The contract wraps it in a window that closes the instant `act` returns, so
+ * every read is inside a verified, consumed, single-use token — which is what
+ * SPEC.md §10.4 means by "the credentials only answer to tokens". Three things
+ * hold that rule up, and none of them is a convention:
+ *
+ * 1. `core/vault.ts` exports exactly one function that returns a credential
+ *    value (`getCredential`), and this module is its only caller in the
+ *    repository. `tests/vault.test.ts` pins both halves.
+ * 2. There is no CLI verb that prints a value. `approval vault` can set, list
+ *    (names), and remove; it cannot show. See `src/cli/vault.ts`.
+ * 3. The contract scans everything an adapter returns for the values the
+ *    provider handed out and redacts them, so a leak by a careless adapter is
+ *    caught mechanically rather than reviewed for.
+ *
+ * ## What this defends, and what it does not
+ *
+ * Exactly what the vault module's own threat model says, restated because a
+ * reader arriving from the adapter side deserves it here too. **Defended:**
+ * credentials at rest, and casual reads by an agent that can read files in the
+ * working tree — the ciphertext hides the names as well as the values.
+ * **Not defended (SPEC.md §11, plainly):** a compromised host, and an agent that
+ * can read the passphrase environment variable. Such an agent does not need this
+ * provider; it can decrypt the file directly. The vault raises the cost of a
+ * leak from reading a file to owning the session, and claims nothing beyond
+ * that.
+ *
+ * Total and synchronous, as {@link CredentialProvider} requires: nothing here
+ * throws, nothing blocks on a human, and every failure is one of the three
+ * {@link CREDENTIAL_REFUSAL_CODES}.
+ */
+import { defaultSourceRunner } from "../core/env-file.js";
+import { getCredential, passphraseFrom, vaultPathFor, } from "../core/vault.js";
+import { passphraseUnderGrant } from "./env-passphrase.js";
+/**
+ * How a vault refusal is reported to an adapter.
+ *
+ * The contract's union has three members and they answer three different
+ * questions, so the mapping is by *repair* rather than by severity:
+ *
+ * - **`credential-unavailable`** — nothing is configured yet. No vault, no such
+ *   name, no passphrase in the environment. The operator has something to do.
+ * - **`credential-refused`** — the vault exists and would not open: a wrong
+ *   passphrase, an altered file, a format this build does not read, an
+ *   unreadable path. SPEC.md's phrase for this branch is "a locked vault", and
+ *   it is distinct because the repair is investigation, not configuration.
+ * - **`credential-window-closed`** — never produced here. It is the contract's
+ *   own verdict about *when* the question was asked, and this module has no way
+ *   to know that.
+ */
+function mapRefusal(code) {
+    switch (code) {
+        case "vault-absent":
+        case "passphrase-unset":
+        case "credential-absent":
+        case "invalid-name":
+            return "credential-unavailable";
+        case "vault-io":
+        case "vault-malformed":
+        case "vault-version-unsupported":
+        case "vault-unreadable":
+        case "empty-value":
+        case "vault-write-failed":
+            return "credential-refused";
+    }
+}
+/**
+ * A provider that answers from the encrypted vault.
+ *
+ * **Lazy, and cached for the life of the provider.** The vault is not opened
+ * until an adapter actually asks for something, so an execution that needs no
+ * credential pays no scrypt cost and touches no ciphertext. Once opened, the
+ * derived value for a name is remembered, because a provider's life *is* one
+ * `act` call: the contract closes it when `act` returns, so the cache cannot
+ * outlive the token window it was built for, and the alternative — a fresh
+ * ~100 ms key derivation per credential — would put a visible tax on an adapter
+ * that needs two.
+ *
+ * The passphrase is read from the environment on every open rather than
+ * captured at construction, so a provider built before the operator exported the
+ * variable is not permanently poisoned.
+ *
+ * **The scoped fallback (APRV-168).** When {@link VaultProviderOptions.envFilePath}
+ * is supplied AND the contract has told this provider it is inside a token
+ * window, a passphrase absent from the environment is resolved from the
+ * instance's `.approval/env` instead. That is the one narrowing of
+ * `core/env-file.ts`'s "no verb reads this file" rule, and the whole argument
+ * for it lives in `adapters/env-passphrase.ts`. The short form: the authority is
+ * the token, and a human tapped Approve for exactly this action. The value is
+ * used to derive one key and reaches no environment, no argv, no log, and no
+ * message; the cache is dropped when the window closes, so a passphrase resolved
+ * under one grant opens nothing under the next.
+ *
+ * Messages name the environment VARIABLE and the credential NAME, and never a
+ * value: an adapter's failure message is one of the strings the contract hands
+ * back to a caller, and a diagnostic that quoted the secret would defeat the
+ * redaction guard by putting the secret in the one place the guard cannot know
+ * to look for it.
+ */
+export function vaultCredentialProvider(location, options) {
+    const vaultPath = "vaultPath" in location ? location.vaultPath : vaultPathFor(location.logPath);
+    const { passphraseEnv } = options;
+    const cache = new Map();
+    // The live grant, set by the contract when the credential window opens and
+    // cleared when it closes. Never read except by the fallback below, and the
+    // fallback is unreachable while it is null.
+    let live = null;
+    return {
+        grant(grant) {
+            live = grant;
+            // A cached credential was derived under the previous window's authority.
+            // Dropping the cache with the grant means the next window pays for its
+            // own passphrase rather than inheriting one.
+            if (grant === null)
+                cache.clear();
+        },
+        get(name) {
+            const cached = cache.get(name);
+            if (cached !== undefined)
+                return { ok: true, value: cached };
+            const passphrase = passphraseFrom(passphraseEnv, options.env ?? process.env) ??
+                // APRV-168. Only inside a window the contract opened against a token a
+                // human's grant minted, and only for the one variable the policy names.
+                // The value goes straight into the key derivation below: it is not
+                // exported, not cached on its own, and it appears in no message on
+                // either branch.
+                (options.envFilePath === undefined
+                    ? null
+                    : passphraseUnderGrant(live, options.envFilePath, passphraseEnv, options.sourceRunner ?? defaultSourceRunner));
+            if (passphrase === null) {
+                return {
+                    ok: false,
+                    code: "credential-unavailable",
+                    message: `credential ${JSON.stringify(name)} lives in the vault at ${vaultPath}, and the passphrase variable ${passphraseEnv} is unset or empty in this process${options.envFilePath === undefined
+                        ? ""
+                        : `, and it did not resolve from ${options.envFilePath} either`}. The policy names the variable and never the value (SPEC.md §5.2, §10.4); export it in the environment that runs the adapter, or give it a line in the environment source map.`,
+                };
+            }
+            const result = getCredential(vaultPath, passphrase, name);
+            if (result.ok) {
+                cache.set(name, result.value);
+                return { ok: true, value: result.value };
+            }
+            return { ok: false, code: mapRefusal(result.code), message: result.message };
+        },
+    };
+}
+//# sourceMappingURL=vault-provider.js.map

package/dist/src/adapters/vault-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault-provider.js","sourceRoot":"","sources":["../../../src/adapters/vault-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EAAE,mBAAmB,EAAqB,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EACL,aAAa,EACb,cAAc,EACd,YAAY,GAEb,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAkC3D;;;;;;;;;;;;;;;GAeG;AACH,SAAS,UAAU,CAAC,IAAsB;IACxC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,cAAc,CAAC;QACpB,KAAK,kBAAkB,CAAC;QACxB,KAAK,mBAAmB,CAAC;QACzB,KAAK,cAAc;YACjB,OAAO,wBAAwB,CAAC;QAClC,KAAK,UAAU,CAAC;QAChB,KAAK,iBAAiB,CAAC;QACvB,KAAK,2BAA2B,CAAC;QACjC,KAAK,kBAAkB,CAAC;QACxB,KAAK,aAAa,CAAC;QACnB,KAAK,oBAAoB;YACvB,OAAO,oBAAoB,CAAC;IAChC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,uBAAuB,CACrC,QAAuB,EACvB,OAA6B;IAE7B,MAAM,SAAS,GAAG,WAAW,IAAI,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAChG,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC;IAClC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,2EAA2E;IAC3E,2EAA2E;IAC3E,4CAA4C;IAC5C,IAAI,IAAI,GAA0B,IAAI,CAAC;IAEvC,OAAO;QACL,KAAK,CAAC,KAA4B;YAChC,IAAI,GAAG,KAAK,CAAC;YACb,yEAAyE;YACzE,uEAAuE;YACvE,6CAA6C;YAC7C,IAAI,KAAK,KAAK,IAAI;gBAAE,KAAK,CAAC,KAAK,EAAE,CAAC;QACpC,CAAC;QAED,GAAG,CAAC,IAAY;YACd,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC/B,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;YAE7D,MAAM,UAAU,GACd,cAAc,CAAC,aAAa,EAAE,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;gBACzD,uEAAuE;gBACvE,wEAAwE;gBACxE,mEAAmE;gBACnE,mEAAmE;gBACnE,iBAAiB;gBACjB,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS;oBAChC,CAAC,CAAC,IAAI;oBACN,CAAC,CAAC,oBAAoB,CAClB,IAAI,EACJ,OAAO,CAAC,WAAW,EACnB,aAAa,EACb,OAAO,CAAC,YAAY,IAAI,mBAAmB,CAC5C,CAAC,CAAC;YACT,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;gBACxB,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,IAAI,EAAE,wBAAwB;oBAC9B,OAAO,EAAE,cAAc,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,0BAA0B,SAAS,iCAAiC,aAAa,qCAC1H,OAAO,CAAC,WAAW,KAAK,SAAS;wBAC/B,CAAC,CAAC,EAAE;wBACJ,CAAC,CAAC,iCAAiC,OAAO,CAAC,WAAW,SAC1D,iLAAiL;iBAClL,CAAC;YACJ,CAAC;YAED,MAAM,MAAM,GAAG,aAAa,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;YAC1D,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;gBACd,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;gBAC9B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;YAC3C,CAAC;YACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;QAC/E,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/channels/batch.js

@@ -0,0 +1,121 @@
+/**
+ * Batching: one human gesture over many requests, without losing audit
+ * granularity (SPEC.md §10.3, requirement B7).
+ *
+ * > Channels MAY present multiple pending requests as a batch and collect one
+ * > human gesture over the set, and SHOULD for high-volume `record.*` classes.
+ * > The log never batches: each granted or rejected request receives its own
+ * > `approval.granted` or `approval.rejected` event carrying the batch's channel
+ * > delivery id in its payload, so audit granularity survives ergonomic
+ * > grouping. A batch MUST NOT mix `manual` classes with differing
+ * > payload-display requirements in a way that hides any full payload behind the
+ * > fold of another.
+ *
+ * Two halves, and this module is both: {@link assembleBatch} enforces the
+ * forbidden mix *before* anything is delivered, and {@link recordBatchDecisions}
+ * records one gate decision per member afterwards.
+ *
+ * ## The B7 operationalization — FLAGGED FOR HUMAN REVIEW
+ *
+ * "Hides any full payload behind the fold of another" is a sentence about
+ * rendering, and rendering is the one thing the runtime cannot inspect. So B7 is
+ * operationalized here as a property of the *batch material* rather than of the
+ * pixels:
+ *
+ * > A batch MUST carry every member's full payload whole. The forbidden mix is
+ * > any member whose `fullPayload` is absent or truncated while the batch
+ * > contains more than one distinct payload — because with one payload there is
+ * > no "another" to hide behind, and with two or more, a member the channel was
+ * > not given in full is a member the approver cannot have read.
+ *
+ * Concretely, {@link assembleBatch} refuses when the batch holds more than one
+ * distinct `payload_hash` **and** any member's `fullPayload` is `null` or
+ * `truncated`. A single-payload batch (the same bytes requested twice, or one
+ * request) is always assemblable, and a multi-payload batch is assemblable
+ * exactly when every member arrives whole.
+ *
+ * What this deliberately does **not** try to be: a judgment about whether a
+ * particular channel's layout actually put payload #2 below the fold. That is a
+ * per-channel rendering property, and `channels/conformance.ts` checks the
+ * observable half of it (every member's full payload text present in the
+ * rendering, delineated from the claimed summary). The interpretation to
+ * confirm is the reduction of "differing payload-display requirements" to
+ * "distinct payload bytes": it is the reading that makes the rule mechanical,
+ * and it is stricter than the spec's letter in one direction (two whole payloads
+ * are fine only if both are whole) and silent in another (it says nothing about
+ * a channel that renders both whole and then collapses one). A human should
+ * confirm this is the intended reading before APRV-23/25/26 build against it.
+ */
+import { recordChannelDecision, } from "./contract.js";
+export { BATCH_DELIVERY_ID_FIELD, BATCH_DELIVERY_NOTE_PREFIX, batchDeliveryIdOf, batchNote, } from "./contract.js";
+// ---------------------------------------------------------------------------
+// assembleBatch
+// ---------------------------------------------------------------------------
+/** The one way a batch can be refused (SPEC.md §10.3, B7). */
+export const BATCH_REFUSAL_CODE = "batch-forbidden-mix";
+/**
+ * Assemble `requests` into a batch, or refuse the forbidden mix.
+ *
+ * The returned batch carries every member request **whole** — the same
+ * {@link ChannelRequest} objects a channel would receive individually, tags and
+ * full payloads included. A channel therefore has everything it needs to render
+ * each member in full; if it chooses not to, that is a rendering defect the
+ * conformance suite catches, not a gap in the material it was handed.
+ *
+ * `deliveryId` is left unset: it is assigned by the channel at `notify`.
+ */
+export function assembleBatch(requests) {
+    const hashes = new Set(requests.map((request) => request.payload_hash.value));
+    if (hashes.size > 1) {
+        const hidden = requests.filter((request) => {
+            const rendering = request.fullPayload.value;
+            return rendering === null || rendering.truncated;
+        });
+        if (hidden.length > 0) {
+            const keys = hidden.map((request) => request.action_key.value).join(", ");
+            return {
+                ok: false,
+                code: BATCH_REFUSAL_CODE,
+                message: `batch refused: it carries ${hashes.size} distinct payloads and ${hidden.length} member(s) whose full payload is absent or truncated (${keys}). SPEC.md §10.3 forbids a batch that hides any full payload behind the fold of another; a member the channel was never given in full is a member the approver cannot have read, so the set is refused before delivery rather than approved in part.`,
+            };
+        }
+    }
+    return { ok: true, batch: { requests } };
+}
+/**
+ * Record one gate decision per batch member.
+ *
+ * **Unit decisions mean unit outcomes.** The log never batches (SPEC.md §10.3),
+ * so this is a loop over `decide()` and not a transaction: each member is
+ * checked and appended on its own, each carries the batch delivery id in its
+ * payload as the first-class `batch_delivery_id` field (amended SPEC.md §10.3,
+ * APRV-38), and a member that refuses does **not** stop the rest. That is
+ * deliberate and it is the only coherent semantics available — an "all or
+ * nothing" batch would have to un-append events the log forbids un-appending,
+ * and abandoning the remaining members because the third one expired would
+ * discard a human's answer to the other four. So: partial success is a real
+ * outcome, `ok` is false when any member refused, and `results` says exactly
+ * which ones landed. A caller that wants atomicity does not want a batch.
+ *
+ * Ordering: members are recorded in the order given. Each append passes the
+ * gate's compare-and-append precondition against the head *it* read, so a
+ * concurrent writer refuses one member with `append-failed`/`head-moved`
+ * rather than corrupting the set.
+ */
+export function recordBatchDecisions(logPath, decisions, batchDeliveryId, actorOptions, gateOptions = {}) {
+    const results = [];
+    for (const decision of decisions) {
+        const recorded = recordChannelDecision(logPath, { ...decision, batchDeliveryId }, actorOptions, gateOptions);
+        results.push({
+            action_key: decision.action_key,
+            outcome: recorded.outcome,
+            ...(recorded.token === undefined ? {} : { token: recorded.token }),
+        });
+    }
+    return {
+        ok: results.every((entry) => entry.outcome.ok),
+        results,
+        batchDeliveryId,
+    };
+}
+//# sourceMappingURL=batch.js.map

package/dist/src/channels/batch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.js","sourceRoot":"","sources":["../../../src/channels/batch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAGH,OAAO,EACL,qBAAqB,GAOtB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,iBAAiB,EACjB,SAAS,GAEV,MAAM,eAAe,CAAC;AAEvB,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E,8DAA8D;AAC9D,MAAM,CAAC,MAAM,kBAAkB,GAAG,qBAAqB,CAAC;AAUxD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,QAA0B;IACtD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;IAE9E,IAAI,MAAM,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE;YACzC,MAAM,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC;YAC5C,OAAO,SAAS,KAAK,IAAI,IAAI,SAAS,CAAC,SAAS,CAAC;QACnD,CAAC,CAAC,CAAC;QACH,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC1E,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,kBAAkB;gBACxB,OAAO,EAAE,6BAA6B,MAAM,CAAC,IAAI,0BAA0B,MAAM,CAAC,MAAM,yDAAyD,IAAI,sPAAsP;aAC5Y,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,EAAE,CAAC;AAC3C,CAAC;AAsBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAe,EACf,SAA4B,EAC5B,eAA2B,EAC3B,YAAiC,EACjC,WAAW,GAAkB,EAAE;IAE/B,MAAM,OAAO,GAAwB,EAAE,CAAC;IACxC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,QAAQ,GAAG,qBAAqB,CACpC,OAAO,EACP,EAAE,GAAG,QAAQ,EAAE,eAAe,EAAE,EAChC,YAAY,EACZ,WAAW,CACZ,CAAC;QACF,OAAO,CAAC,IAAI,CAAC;YACX,UAAU,EAAE,QAAQ,CAAC,UAAU;YAC/B,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,GAAG,CAAC,QAAQ,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC;SACnE,CAAC,CAAC;IACL,CAAC;IACD,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9C,OAAO;QACP,eAAe;KAChB,CAAC;AACJ,CAAC"}