approval-md 0.1.0 → 0.2.0

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

@@ -0,0 +1,138 @@
+/**
+ * Write-boundary JSON Schema validation.
+ *
+ * SPEC.md §8: every event and envelope validates against its JSON Schema
+ * before it is written. Validation at the write boundary is itself a control,
+ * so this module fails **closed**: a missing schema directory, an unreadable
+ * or unparseable schema file, an unknown schema id, or an Ajv compile failure
+ * all produce `{ ok: false, errors: [...] }`. Nothing here can return `ok`
+ * for a document it did not actually validate, and nothing throws out to the
+ * caller (a thrown error would be an unhandled write-boundary bypass).
+ *
+ * Determinism: the result is a pure function of (schema files on disk,
+ * document). No network, no clock, no randomness. Every call re-reads every
+ * schema file, so a run never depends on the order or history of previous
+ * calls: edit a schema mid-run and the next call validates against the edit.
+ * Two reuses sit under that rule and neither bends it. {@link prepareValidator}
+ * lets a caller validating many documents against one schema in one pass
+ * compile once and hold the snapshot itself. And since APRV-206 the Ajv
+ * *compile* is reused across calls when the schema bytes just read hash to the
+ * digest the compiled validator was built from — the schema files are still
+ * read every time, so nothing is answered for bytes that were not re-proved;
+ * see {@link compiledValidators} for the argument in full.
+ *
+ * Dialect / import notes (AC #6 — documented, never silently downgraded):
+ *
+ * - Dialect is JSON Schema draft 2020-12 via Ajv's dedicated `Ajv2020` class.
+ *   Ajv 8 ships no `exports` map, so under NodeNext the working ESM import is
+ *   the deep path to the built CJS file:
+ *       import { Ajv2020 } from "ajv/dist/2020.js";
+ *   The named export is used rather than the default because Ajv 8's CJS
+ *   interop default (`module.exports = Ajv2020`) is not typed as a default
+ *   export under `verbatimModuleSyntax` + `esModuleInterop: false`. The named
+ *   binding resolves and type-checks cleanly under NodeNext.
+ * - `ajv-formats` is likewise a deep CJS import: its plugin is exported as
+ *   `module.exports = formatsPlugin`, so the callable value comes from the
+ *   `.default` property of the namespace import under NodeNext.
+ * - Ajv is configured `strict: true`. No strict flag is relaxed. Formats are
+ *   enforced, not annotation-only: `validateFormats: true` plus `ajv-formats`
+ *   registered, so an invalid `date-time` string is a validation error.
+ */
+/** A single validation failure, flattened for logging and CLI output. */
+export interface ValidationError {
+    /** JSON Pointer to the offending location ("" for the document root). */
+    path: string;
+    /** Ajv keyword, or a harness pseudo-keyword such as "schemaLoad". */
+    keyword: string;
+    /** Human-readable reason. */
+    message: string;
+}
+/** Result of a write-boundary validation. Failure always carries a reason. */
+export type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    errors: ValidationError[];
+};
+/** Suffix identifying schema files inside the schema directory. */
+export declare const SCHEMA_FILE_SUFFIX = ".schema.json";
+/** Repo `schema/` directory: default source of truth for all schemas. */
+export declare const DEFAULT_SCHEMA_DIR: string;
+/**
+ * Which boundary a validation is speaking for (APRV-121).
+ *
+ * - `write` — the default, and what SPEC.md §8 means by "validate at the write
+ *   boundary". The schemas as written on disk: a monetary amount is a canonical
+ *   decimal string and nothing else.
+ * - `historical` — the read boundary. The log is append-only, so a verifier
+ *   walking records written before APRV-121 meets JSON-number amounts that were
+ *   valid when they were appended and must stay valid forever. This mode makes
+ *   exactly one substitution, described in {@link WIDENED_DEFS}, and no other.
+ *
+ * The asymmetry is the point: a document only ever gets *more* permissive by a
+ * caller explicitly naming the read boundary, and the callers that do are
+ * pinned: `core/verify.ts` (the log walk), the daemon's envelope scan, and the
+ * `set-state` task-file rewrite — paths that read or preserve claims an earlier
+ * write boundary accepted, never ones that author new claims (APRV-121,
+ * APRV-148).
+ */
+export type ValidationMode = "write" | "historical";
+/** Options accepted by {@link validate}. */
+export interface ValidateOptions {
+    /** Directory to load `*.schema.json` from. Injectable for tests. */
+    schemaDir?: string;
+    /** Which boundary this validation speaks for. Defaults to `"write"`. */
+    mode?: ValidationMode;
+}
+/**
+ * The `$defs` a `historical` validation replaces, as `name -> replacement name`.
+ *
+ * Pinned as a list rather than derived from a naming convention, so widening
+ * the read boundary is always a reviewable diff in this file and never a side
+ * effect of adding a definition to a schema. `usd_amount` is the only entry:
+ * the pre-APRV-121 write boundary typed monetary fields as `{"type": "number",
+ * "minimum": 0}`, and `usd_amount_historical` is exactly that union with the
+ * decimal string.
+ */
+export declare const WIDENED_DEFS: Readonly<Record<string, string>>;
+/**
+ * List schema names (file basename minus `.schema.json`) in a directory.
+ * Sorted, so discovery order is stable across platforms and runs.
+ */
+export declare function listSchemaNames(schemaDir?: string): string[];
+/**
+ * Validate `document` against the schema identified by `schemaId` (the schema
+ * filename minus `.schema.json`, or the schema's `$id`).
+ *
+ * Fails closed: every load, parse, and compile problem is reported as a
+ * validation failure rather than thrown.
+ */
+export declare function validate(schemaId: string, document: unknown, options?: ValidateOptions): ValidationResult;
+/**
+ * A validator compiled once and reusable for many documents.
+ *
+ * `check` is {@link validate} with the schema load and Ajv compile already
+ * paid: same results, same error shapes, on every document. This exists for
+ * the one caller that validates thousands of documents against one schema in
+ * one pass — the log chain walk — where a per-document recompile turns a
+ * subsecond verification into minutes of CPU (APRV-186).
+ *
+ * The determinism stance in the module header is unchanged: nothing is cached
+ * across calls to {@link prepareValidator} itself. A prepared validator is a
+ * snapshot of the schema files as they stood when it was prepared; a caller
+ * that wants fresh schemas prepares again.
+ */
+export interface PreparedValidator {
+    ok: true;
+    check(document: unknown): ValidationResult;
+}
+/**
+ * Load and compile `schemaId` once, for reuse across many documents.
+ *
+ * Fails closed exactly as {@link validate} does: every load, parse, and
+ * compile problem is reported as `{ ok: false, errors }`, never thrown.
+ */
+export declare function prepareValidator(schemaId: string, options?: ValidateOptions): PreparedValidator | {
+    ok: false;
+    errors: ValidationError[];
+};

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

@@ -0,0 +1,137 @@
+/**
+ * The values block of `APPROVAL.md` (SPEC.md §5.3), read.
+ *
+ * Everything else in this directory is control: what an agent may do, who
+ * decides, what is sampled. This module reads the other half of the file — the
+ * optional ` ```yaml approval-values ` block in which the operator says what
+ * they value in the work, what they want from the agent, and how they read and
+ * answer. It is the mirror of the journal (SPEC.md §10.1): the journal is the
+ * agent's outlet the gate does not stand in front of, and the values block is
+ * the human's, with the same rule running in both directions, that nothing said
+ * there moves a verdict.
+ *
+ * Three decisions are worth stating here rather than leaving to be inferred.
+ *
+ * **Absence is a declaration, never a default.** A file with no values block is
+ * an operator who has declared no values, which is information. It is not a
+ * missing thing to be repaired, and it is not an invitation to invent a neutral
+ * middle. So the result has three states rather than two: present, absent, and
+ * unreadable, and `ok: true, present: false` is the absent one. Surfaces render
+ * it in the words SPEC.md §5.3 fixes, so a session can tell "nothing was
+ * declared" from "I did not look".
+ *
+ * **Two blocks fail.** One file, at most one values block, exactly as the policy
+ * block is exactly one. Two blocks are two answers to one question, and a reader
+ * that silently took the first would be choosing between two things a human
+ * wrote, on the strength of document order.
+ *
+ * **A values failure never fails the policy.** Enforcement fails closed on the
+ * policy block because an unparseable permission document is one whose author
+ * believes constraints are in force that are not. Nothing about that argument
+ * carries here, because this block is not enforcement: no routing, class match,
+ * sampling draw, budget, token or execution decision reads it (SPEC.md §11.1
+ * invariant 10, pinned by `tests/values-inert.test.ts`). Failing closed on a
+ * malformed values block would convert a typo into an all-manual repository, and
+ * would buy no safety at all in exchange. The two blocks are therefore parsed
+ * and judged independently, on paths that share only the fence splitter, and
+ * this module never calls the policy loader's parse path.
+ *
+ * ## Determinism
+ *
+ * {@link loadValues} is a pure function of the file bytes on disk plus the
+ * schema directory. No clock, no network, no randomness, no cross-call caching,
+ * and no throw: every failure is a result.
+ */
+import { type ValidationError } from "./validate.js";
+/** Info string that marks the OPTIONAL values block (SPEC.md §5.3). */
+export declare const VALUES_INFO_STRING = "yaml approval-values";
+/**
+ * The parsed values block, as `values.schema.json` admits it.
+ *
+ * The key set is closed and small on purpose, and the schema is the authority
+ * on why each key is here and which were rejected. This interface restates the
+ * shape for TypeScript and adds nothing.
+ */
+export interface Values {
+    /** Format version. The only required key; the integer `1` and nothing else. */
+    version: 1;
+    /** What the operator loves, in their own words. */
+    love?: string[];
+    /** What the operator likes. */
+    like?: string[];
+    /** What the operator dislikes. NOT a prohibition: a prohibition is policy. */
+    dislike?: string[];
+    /** What the operator wants FROM the agent, as behaviour rather than taste. */
+    wants?: string[];
+    /** How the operator reads and answers. One sentence or two. */
+    responds?: string;
+}
+/**
+ * Why a values block could not be read.
+ *
+ * Deliberately NOT {@link import("./policy-load.js").PolicyLoadErrorCode}: the
+ * two are different questions with different consequences, and a shared union
+ * would invite a caller to handle one with the other's rules. There is no
+ * `no-block` here, because a file with no values block is not a failure at all.
+ */
+export type ValuesLoadFailureCode = "file-missing" | "multiple-blocks" | "unterminated-fence" | "yaml-error" | "schema-invalid";
+/** Where the values block was read from. */
+export interface ValuesSource {
+    /** Absolute or caller-relative path actually read. */
+    path: string;
+    /** Basename of that path, e.g. `APPROVAL.md`. */
+    filename: string;
+}
+/**
+ * Result of {@link loadValues}: present, absent, or unreadable.
+ *
+ * A not-ok result places no obligation on any enforcement path, because no
+ * enforcement path may be looking. It obligates exactly one thing, of the
+ * surfaces that print it: say the block is there and could not be read, and say
+ * that it grants nothing either way.
+ */
+export type ValuesLoadResult = {
+    ok: true;
+    present: true;
+    values: Values;
+    source: ValuesSource;
+} | {
+    ok: true;
+    present: false;
+    source: ValuesSource;
+} | {
+    ok: false;
+    code: ValuesLoadFailureCode;
+    message: string;
+    errors?: ValidationError[];
+    source?: ValuesSource;
+};
+/** Options accepted by {@link loadValues}. */
+export interface LoadValuesOptions {
+    /** Directory to search for `APPROVAL.md` / `APPROVALS.md`. Default: cwd. */
+    dir?: string;
+    /** Explicit policy file path. Overrides discovery entirely. */
+    file?: string;
+    /** Schema directory passed through to {@link validate}. Injectable for tests. */
+    schemaDir?: string;
+}
+/**
+ * Extract, parse, and validate the values block of an already-read file.
+ *
+ * The bytes-in form of {@link loadValues}, for the caller that has the file in
+ * hand (a doctor run reading it once for several questions) and for the tests
+ * that build a file variant without touching a disk. Nothing here touches the
+ * filesystem, nothing throws, and `path` is used only for messages and for
+ * {@link ValuesSource}.
+ */
+export declare function loadValuesText(path: string, text: string, options?: {
+    schemaDir?: string;
+}): ValuesLoadResult;
+/**
+ * Find `APPROVAL.md`, and read its values block if it has one.
+ *
+ * Discovery plus {@link loadValuesText}. A file that cannot be read at all is
+ * `file-missing`, which is the only failure code here that says nothing about
+ * the block: there was no file to hold one.
+ */
+export declare function loadValues(options?: LoadValuesOptions): ValuesLoadResult;

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;