vaultkeeper 0.5.3 → 0.7.0

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+/// <reference types="node" />
+import { Buffer } from 'node:buffer';
+
 /**
  * Error hierarchy for vaultkeeper.
  */
@@ -37,6 +40,69 @@ declare class DeviceNotPresentError extends VaultError {
 declare class AuthorizationDeniedError extends VaultError {
     constructor(message: string);
 }
+/**
+ * Thrown when an operation requires a backend capability (e.g.
+ * presence-per-use) that the active backend cannot provide.
+ *
+ * @remarks
+ * This is a configuration/backend mismatch, not a runtime authorization
+ * failure: the requirement was asserted against a backend whose configured
+ * instance does not advertise the capability, so no credential, session, or
+ * device is ever touched before this is thrown. It is fixable by switching to
+ * (or reconfiguring) a backend that provides the capability — inspect
+ * {@link NotCapableError.capability} for which one was required and
+ * {@link NotCapableError.backendType} for the backend that lacked it. Distinct
+ * from {@link AuthorizationDeniedError} (a human/token rejection) and
+ * {@link PresenceDeclinedError} (a human declined a fresh action).
+ *
+ * @public
+ */
+declare class NotCapableError extends VaultError {
+    /** The `type` identifier of the active backend that lacked the capability. */
+    readonly backendType: string;
+    /**
+     * The machine-readable capability key that was required but not advertised
+     * (e.g. `'presencePerUse'`).
+     */
+    readonly capability: string;
+    constructor(message: string, backendType: string, capability: string);
+}
+/**
+ * Thrown when a required fresh, per-use human presence action was explicitly
+ * declined by the human (e.g. a biometric or touch prompt was cancelled).
+ *
+ * @remarks
+ * Distinct from {@link AuthorizationDeniedError}, which signals a token or
+ * capability rejection, and from {@link PresenceTimeoutError}, which signals the
+ * device was present but no action happened in time. A declined presence action
+ * means the human was asked and said no.
+ *
+ * @public
+ */
+declare class PresenceDeclinedError extends VaultError {
+    /** The `type` identifier of the backend that requested the presence action. */
+    readonly backendType: string;
+    constructor(message: string, backendType: string);
+}
+/**
+ * Thrown when a required fresh, per-use human presence action did not happen
+ * within the allotted time — the device was present and ready, but no touch,
+ * tap, or biometric approval was performed before the timeout elapsed.
+ *
+ * @remarks
+ * Distinct from {@link DeviceNotPresentError} (the device itself was absent) and
+ * from {@link PresenceDeclinedError} (the human actively declined). Inspect
+ * {@link PresenceTimeoutError.timeoutMs} for how long the operation waited.
+ *
+ * @public
+ */
+declare class PresenceTimeoutError extends VaultError {
+    /** The `type` identifier of the backend that requested the presence action. */
+    readonly backendType: string;
+    /** How long (in milliseconds) the operation waited for the presence action. */
+    readonly timeoutMs: number;
+    constructor(message: string, backendType: string, timeoutMs: number);
+}
 /**
  * Thrown when no configured backend is available or reachable.
  * Inspect `reason` for a machine-readable cause and `attempted` for the list
@@ -135,8 +201,80 @@ declare class IdentityMismatchError extends VaultError {
     constructor(message: string, previousHash: string, currentHash: string);
 }
 /**
- * Thrown when a caller requests a signing/verification algorithm that is not
- * in the allowed set (e.g. `'md5'`).
+ * Thrown by {@link VaultKeeper.setup} when the caller does not make an
+ * unambiguous executable-trust decision.
+ *
+ * `setup()` deliberately has no default trust behaviour: the caller must either
+ * pass a real `executablePath` (which runs trust-on-first-use verification) or
+ * explicitly opt out with `skipTrust: true` (a development-only escape hatch).
+ * Supplying neither — or both at once — throws this error rather than silently
+ * skipping verification. Passing the retired `'dev'` sentinel as `executablePath`
+ * also throws this error. Inspect {@link ExecutableTrustRequiredError.reason} to
+ * distinguish the cases.
+ *
+ * @public
+ */
+declare class ExecutableTrustRequiredError extends VaultError {
+    /**
+     * Machine-readable discriminator for why the trust choice was rejected.
+     * `'missing-choice'` means neither `executablePath` nor `skipTrust: true`
+     * was provided, so no trust decision was expressed. `'conflicting-choice'`
+     * means both `executablePath` and `skipTrust: true` were provided, which
+     * are mutually exclusive intents. `'legacy-dev-sentinel'` means
+     * `executablePath` was the retired literal `'dev'` opt-out sentinel, which is
+     * no longer supported and must be replaced with `skipTrust: true`.
+     */
+    readonly reason: 'missing-choice' | 'conflicting-choice' | 'legacy-dev-sentinel';
+    constructor(message: string, reason: 'missing-choice' | 'conflicting-choice' | 'legacy-dev-sentinel');
+}
+/**
+ * Thrown when spawning or running a subprocess fails.
+ *
+ * This covers a delegated `exec()` call failing due to an invalid request
+ * (e.g. a `{{secret}}` placeholder in the `command` field) or a
+ * process-level error (e.g. the command binary is not found or cannot be
+ * spawned) — and also vaultkeeper's own internal tool invocations (doctor
+ * version probes, the keychain/secret-tool/dpapi/yubikey credential helpers),
+ * which run through the same subprocess utility. Callers that need to handle
+ * only delegated-exec failures should scope their `catch` to the code paths
+ * that call `exec()`, not discriminate on this type alone.
+ *
+ * @public
+ */
+declare class ExecError extends VaultError {
+    /**
+     * The command that failed to execute.
+     */
+    readonly command: string;
+    constructor(message: string, command: string);
+}
+/**
+ * Thrown when a JWE string is invalid or cannot be processed — for example,
+ * it is structurally malformed (wrong number of segments, invalid
+ * Base64URL), decryption fails (wrong key, tampered ciphertext), or the
+ * decrypted payload does not match the expected claims schema.
+ *
+ * @public
+ */
+declare class InvalidTokenError extends VaultError {
+    constructor(message: string);
+}
+/**
+ * Thrown when `SecretAccessor.read()` is called after the accessor has
+ * already been consumed.
+ *
+ * @public
+ */
+declare class AccessorConsumedError extends VaultError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a caller requests a signing key algorithm that is not a
+ * supported JOSE algorithm identifier. The signing algorithm registry uses
+ * strict JOSE identifiers (currently `'EdDSA'`); an unrecognized value is
+ * rejected rather than defaulted.
+ *
+ * @public
  */
 declare class InvalidAlgorithmError extends VaultError {
     /**
@@ -149,6 +287,183 @@ declare class InvalidAlgorithmError extends VaultError {
     readonly allowed: string[];
     constructor(message: string, algorithm: string, allowed: string[]);
 }
+/**
+ * Thrown when signing-key material cannot be parsed. Two paths raise it. During
+ * verification, the supplied public key is not a structurally parseable SPKI PEM
+ * public key (or a private key was passed where a public key is required); this
+ * is an operational fault distinct from a signature that simply does not verify,
+ * which returns `false`. During key use, a stored signing key decrypts cleanly
+ * but is not valid private key material — corrupt or tampered on disk — when
+ * exporting its public half or signing with it (`getPublicKey`/`signWithKey`).
+ * The message never echoes any part of the key material.
+ *
+ * @public
+ */
+declare class InvalidKeyMaterialError extends VaultError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a named signing key does not exist in the active backend — for
+ * example `key export` or `sign` is asked for a name that was never enrolled
+ * with `key create`. This is distinct from {@link SecretNotFoundError}: signing
+ * keys occupy their own namespace and are never returned as ordinary secrets.
+ *
+ * @public
+ */
+declare class SigningKeyNotFoundError extends VaultError {
+    /**
+     * The signing-key name that was requested (the caller-facing `--name`, not
+     * the internal namespaced identifier).
+     */
+    readonly keyName: string;
+    constructor(message: string, keyName: string);
+}
+/**
+ * Thrown when `key create` (or `createSigningKey`) is asked to enroll a signing
+ * key under a name that already exists. Enrollment never silently overwrites an
+ * existing key, because a regenerated keypair would invalidate every public key
+ * that was previously exported and pinned by a verifier.
+ *
+ * @public
+ */
+declare class SigningKeyAlreadyExistsError extends VaultError {
+    /**
+     * The signing-key name that already exists (the caller-facing `--name`, not
+     * the internal namespaced identifier).
+     */
+    readonly keyName: string;
+    constructor(message: string, keyName: string);
+}
+/**
+ * Thrown when a signing operation (`key create`, `key export`, `sign`) is
+ * requested against a backend that does not implement the signing contract.
+ * Signing is never silently emulated on a backend that cannot perform it in a
+ * key-stays-backend-side manner; inspect {@link SigningNotSupportedError.builtInSigningBackends}
+ * for the built-in backend types that do.
+ *
+ * @public
+ */
+declare class SigningNotSupportedError extends VaultError {
+    /** The type identifier of the active backend that cannot sign. */
+    readonly backendType: string;
+    /**
+     * The **built-in** backend type identifiers known to implement the signing
+     * contract (currently just the `file` backend). This is deliberately a
+     * static list of built-ins, not a live capability survey: a consumer that
+     * registers its own {@link SigningBackend} is not enumerated here, because
+     * discovering that would require instantiating every registered backend —
+     * a side effect that must not happen on an error path. A caller can still
+     * point a user at a working built-in, and custom backends may implement the
+     * contract independently.
+     */
+    readonly builtInSigningBackends: string[];
+    constructor(message: string, backendType: string, builtInSigningBackends: string[]);
+}
+/**
+ * Thrown when an encrypted-at-rest secret entry cannot be decrypted — e.g.
+ * the stored ciphertext is truncated/corrupted or the AES-GCM auth tag fails
+ * to verify. The message never echoes any part of the secret or key
+ * material.
+ *
+ * @public
+ */
+declare class DecryptionError extends VaultError {
+    /**
+     * The path of the encrypted entry that failed to decrypt.
+     */
+    readonly path: string;
+    constructor(message: string, path: string);
+}
+/**
+ * Thrown when a delegated `fetch()` call fails before a `Response` can be
+ * produced — for example the URL is malformed or the underlying network
+ * request fails (DNS failure, connection refused, TLS error).
+ *
+ * @public
+ */
+declare class FetchError extends VaultError {
+    /**
+     * The unresolved URL template that fetch failed to request, with
+     * `{{secret}}`/`{{secret:name}}` placeholders left intact. The
+     * placeholder-resolved URL is deliberately never stored here, so an
+     * injected secret is never exposed.
+     */
+    readonly url: string;
+    constructor(message: string, url: string);
+}
+/**
+ * Thrown when a config value fails structural or semantic validation (e.g. a
+ * whitespace-only `BackendConfig.path`).
+ */
+declare class ConfigValidationError extends VaultError {
+    /**
+     * The dotted/bracketed path to the offending config field (e.g.
+     * `'backends[0].path'`).
+     */
+    readonly field: string;
+    /**
+     * The path of the config file that failed validation, when the error
+     * originated from loading a file on disk (via `loadConfig`) rather than
+     * from validating an in-memory value directly. This is `configDir` joined
+     * with `config.json` exactly as provided to `loadConfig` — it is not
+     * guaranteed to be absolute (`loadConfig` does not resolve a relative
+     * `configDir`).
+     */
+    readonly configFilePath: string | undefined;
+    constructor(message: string, field: string, configFilePath?: string);
+}
+/**
+ * Thrown when a config's `backends[].type` names a backend that is not
+ * registered with the {@link BackendRegistry}.
+ *
+ * A specialization of {@link ConfigValidationError}: an unknown backend type is
+ * a semantic schema failure (the config parses and is structurally valid, but
+ * names a backend that cannot be created), so it fails config validation the
+ * same way `version !== 1` does. It carries the offending `backendType` and the
+ * set of `knownTypes` so a consumer — notably `doctor` — can give the same
+ * "Available types: …" guidance the runtime {@link BackendUnavailableError}
+ * gives, without parsing the human-readable message. This closes the gap where
+ * a config with an unknown backend type parsed as valid JSON and passed
+ * `doctor` with a false "System ready.", only for the next real command to
+ * throw {@link BackendUnavailableError} (issue #215).
+ */
+declare class UnknownBackendTypeError extends ConfigValidationError {
+    /** The unregistered backend type named in the config. */
+    readonly backendType: string;
+    /**
+     * The backend type identifiers that were registered when validation ran —
+     * the valid options to offer in remediation.
+     */
+    readonly knownTypes: string[];
+    constructor(message: string, field: string, backendType: string, knownTypes: string[], configFilePath?: string);
+}
+/**
+ * Thrown when a config file's contents cannot be parsed as JSON.
+ *
+ * The `message` already embeds the file path, the parse location (when the
+ * underlying `SyntaxError` exposes one), and a remediation hint that either
+ * points at `vaultkeeper config init` (via the separate `@vaultkeeper/cli`
+ * package — this library ships no CLI of its own) or at repairing/replacing
+ * the config directly through this library's JS API — see issues #68, #100.
+ * `path` and `location` are also exposed individually for callers (e.g.
+ * `doctor`) that want to report them as structured fields rather than
+ * re-parsing the message.
+ */
+declare class ConfigParseError extends VaultError {
+    /**
+     * The path of the config file that failed to parse. This is `configDir`
+     * joined with `config.json` exactly as provided to `loadConfig` — it is
+     * not guaranteed to be absolute (`loadConfig` does not resolve a relative
+     * `configDir`).
+     */
+    readonly path: string;
+    /**
+     * A human-readable parse location (e.g. `'line 3, column 12'`), when one
+     * could be derived from the underlying `SyntaxError`.
+     */
+    readonly location: string | undefined;
+    constructor(message: string, path: string, location: string | undefined);
+}
 /**
  * Thrown during initialization when a required system dependency (e.g. OpenSSL
  * or a native credential helper) is missing or incompatible.
@@ -161,20 +476,49 @@ declare class SetupError extends VaultError {
     constructor(message: string, dependency: string);
 }
 /**
- * Thrown when a filesystem operation fails due to a permission or access
- * problem (e.g. the config directory is not writable).
+ * Thrown when a filesystem operation fails. Common causes include a
+ * permission or access problem, for example the config directory is not
+ * writable, but the underlying failure may be any Node.js errno condition,
+ * for example the disk is full or a file was expected but a directory was
+ * found. Inspect the code property for the specific errno code when one is
+ * available.
  */
 declare class FilesystemError extends VaultError {
     /**
-     * The absolute path of the file or directory that caused the error.
+     * The path of the file or directory that caused the error, as provided by
+     * the caller. Not guaranteed to be absolute — e.g. `loadConfig` throws this
+     * with `configDir` joined with `config.json` exactly as given, without
+     * resolving a relative `configDir`.
      */
     readonly path: string;
     /**
-     * The permission level that was required but not available
-     * (e.g. `'read'`, `'write'`, `'execute'`).
+     * The file operation or access mode that was being attempted when the
+     * failure occurred, for example 'read', 'write', 'delete', or 'rwx' for a
+     * directory create/access check. Despite the field name, this does not
+     * imply the failure was itself a permission problem — it names the
+     * attempted operation regardless of the underlying errno, which may be a
+     * non-permission code such as ENOSPC or EISDIR.
      */
     readonly permission: string;
-    constructor(message: string, filePath: string, permission: string);
+    /**
+     * The Node.js errno code from the underlying filesystem failure, for
+     * example EACCES, EPERM, ENOSPC, or EISDIR. Undefined when the error was
+     * constructed without an underlying cause, or when that cause did not
+     * expose a string errno code. Prefer this over parsing the message text,
+     * which is not a contractual format.
+     */
+    readonly code: string | undefined;
+    /**
+     * @param message - Human-readable description of the failure.
+     * @param filePath - The path of the file or directory that caused the error.
+     * @param permission - The file operation or access mode being attempted,
+     * for example 'read', 'write', 'delete', or 'rwx'. See the `permission`
+     * property for why this need not indicate an actual permission problem.
+     * @param cause - The underlying error that was caught, if any. Recorded as
+     * the standard `Error.cause` and used to populate `code` when it exposes a
+     * string errno code.
+     */
+    constructor(message: string, filePath: string, permission: string, cause?: unknown);
 }
 /**
  * Thrown when a key rotation is requested while a previous rotation is still
@@ -187,12 +531,91 @@ declare class RotationInProgressError extends VaultError {
 /**
  * Shared types and interfaces for vaultkeeper.
  */
+
 /** Trust tier for executable identity verification. */
 type TrustTier = 1 | 2 | 3;
 /** Key status in the rotation lifecycle. */
 type KeyStatus = 'current' | 'previous' | 'deprecated';
-/** Status of a preflight check. */
-type PreflightCheckStatus = 'ok' | 'missing' | 'version-unsupported';
+/**
+ * Status of a preflight check.
+ *
+ * `'invalid'` applies specifically to the `config` check: the config file
+ * exists but fails to parse or fails schema validation (see issue #68).
+ */
+type PreflightCheckStatus = 'ok' | 'missing' | 'version-unsupported' | 'invalid';
+/**
+ * The kind of error that made a preflight check fail, as a stable
+ * machine-readable discriminant. `'config-parse'` means the config file
+ * could not be parsed as JSON; `'config-validation'` means it parsed but
+ * failed schema validation; `'config-unknown-backend'` is a specific
+ * validation failure where `backends[].type` names a backend that is not
+ * registered, carrying the offending type and the valid options;
+ * `'config-read'` means the config file could not be read at all (for example
+ * a permission failure on the file or its parent directory) — a different
+ * remediation from parse/validation, since overwriting the file with
+ * `config init --force` cannot fix a read-permission problem.
+ */
+type PreflightCheckErrorKind = 'config-parse' | 'config-validation' | 'config-unknown-backend' | 'config-read';
+/**
+ * Structured, remediation-free error context for a failed preflight check.
+ *
+ * This carries the machine-readable facts a caller needs to build its own
+ * audience-appropriate remediation message, so a consumer never has to parse
+ * the human-readable `reason` prose. It is currently populated only for the
+ * `config` check when the config file is present but invalid.
+ *
+ * The `reason` field intentionally keeps the library's own remediation text
+ * (which points a library consumer at installing the CLI); a consumer that
+ * ships its own CLI should read this structured field instead and phrase the
+ * remediation itself.
+ */
+interface PreflightCheckError {
+    /** The kind of failure, as a stable machine-readable discriminant. */
+    kind: PreflightCheckErrorKind;
+    /**
+     * Path to the config file that failed to parse or validate, as derived from
+     * the doctor call's `configDir`. Not guaranteed to be absolute — it is
+     * `configDir` joined with `config.json` exactly as given, so it is relative
+     * when `configDir` is relative.
+     */
+    configPath: string;
+    /**
+     * Human-readable parse location within the config file (for example
+     * `line 3, column 12`), present only for a `'config-parse'` failure.
+     */
+    location?: string | undefined;
+    /**
+     * The dotted/bracketed path to the offending config field (for example
+     * `backends` or `backends[0].path`), present for a `'config-validation'` or
+     * `'config-unknown-backend'` failure. This is the validation analogue of
+     * `location`: it lets a consumer point the user at exactly which field
+     * failed schema validation, the way `location` points at a parse position,
+     * without reusing the human-readable `reason` prose (which carries the
+     * library's own "install @vaultkeeper/cli" remediation).
+     */
+    field?: string | undefined;
+    /**
+     * The unregistered backend type named in `backends[].type`, present only for
+     * a `'config-unknown-backend'` failure. Lets a consumer echo the offending
+     * type in its remediation without parsing the `reason` prose.
+     */
+    backendType?: string | undefined;
+    /**
+     * The backend type identifiers that were registered when validation ran —
+     * the valid options — present only for a `'config-unknown-backend'` failure.
+     * Lets a consumer offer the same "Available types: …" guidance the runtime
+     * `BackendUnavailableError` gives.
+     */
+    knownBackendTypes?: readonly string[] | undefined;
+    /**
+     * The Node.js errno code (for example `EACCES`, `EPERM`, `EISDIR`) from the
+     * underlying filesystem failure, present only for a `'config-read'` failure
+     * and only when the cause exposed a string errno code. Lets a consumer
+     * distinguish a permission problem from another read failure when phrasing
+     * the remediation.
+     */
+    code?: string | undefined;
+}
 /** Result of a preflight check for a single dependency. */
 interface PreflightCheck {
     /** Human-readable name of the dependency being checked. */
@@ -203,11 +626,30 @@ interface PreflightCheck {
     version?: string | undefined;
     /** Human-readable explanation of why the status is not `'ok'`. */
     reason?: string | undefined;
+    /**
+     * Structured, remediation-free error context when this check failed with a
+     * recognized error, so a caller can build its own remediation message
+     * instead of parsing the `reason` prose. Populated only for the `config`
+     * check when the config file is present but invalid.
+     */
+    error?: PreflightCheckError | undefined;
+}
+/**
+ * A {@link PreflightCheck} scoped by whether its dependency is required for
+ * the active/configured backend(s). Plugin-backend checks (`op`, `ykman`)
+ * are `required: false` when their backend isn't enabled — a non-`'ok'`
+ * status there is informational, not a system-readiness blocker (issue
+ * #116). They are promoted to `required: true` when their backend is
+ * explicitly enabled (e.g. `--backend yubikey` requires `ykman`).
+ */
+interface ScopedPreflightCheck extends PreflightCheck {
+    /** Whether this dependency is required by the active/configured backend(s). */
+    required: boolean;
 }
 /** Aggregated result from all preflight checks. */
 interface PreflightResult {
     /** Individual check results, one per dependency inspected. */
-    checks: PreflightCheck[];
+    checks: ScopedPreflightCheck[];
     /** `true` if all required checks passed and the system is ready. */
     ready: boolean;
     /** Non-fatal advisory messages about optional missing dependencies. */
@@ -226,51 +668,69 @@ interface VaultResponse {
  * Request for delegated HTTP fetch.
  *
  * String values in `url`, `headers`, and `body` may include the placeholder
- * `{{secret}}`, which is replaced with the actual secret value immediately
- * before the request is sent.
+ * `{{secret}}` (single-token mode) or `{{secret:name}}` (multi-token mode),
+ * which are replaced with actual secret values immediately before the request
+ * is sent.
  */
 interface FetchRequest {
     /**
-     * The target URL. May contain `{{secret}}` which is replaced with the secret
-     * value before the fetch is executed (e.g. for API-key-in-URL patterns).
+     * The target URL. May contain `{{secret}}` or `{{secret:name}}` which is
+     * replaced with the secret value before the fetch is executed.
      */
     url: string;
     /** HTTP method (defaults to `'GET'` when omitted). */
     method?: string | undefined;
     /**
-     * Request headers. Any header value may contain `{{secret}}`, which is
-     * replaced with the secret value before the request is sent.
+     * Request headers. Any header value may contain `{{secret}}` or
+     * `{{secret:name}}`, which is replaced with the secret value before
+     * the request is sent.
      */
     headers?: Record<string, string> | undefined;
     /**
-     * Request body. May contain `{{secret}}`, which is replaced with the secret
-     * value before the request is sent.
+     * Request body. May contain `{{secret}}` or `{{secret:name}}`, which is
+     * replaced with the secret value before the request is sent.
      */
     body?: string | undefined;
 }
 /**
  * Request for delegated command execution.
  *
- * String values in `args` and `env` may include the placeholder `{{secret}}`,
- * which is replaced with the actual secret value immediately before the command
- * is spawned.
+ * String values in `env` may include the placeholder `{{secret}}`
+ * (single-token mode) or `{{secret:name}}` (multi-token mode), which are
+ * replaced with actual secret values immediately before the command is
+ * spawned. Placeholders are **not** supported in `command` or `args` —
+ * `VaultKeeper.exec()` throws `ExecError` if one appears there.
  */
 interface ExecRequest {
     /** The command (binary) to execute. */
     command: string;
     /**
-     * Command-line arguments. Any argument may contain `{{secret}}`, which is
-     * replaced with the secret value before the command is spawned.
+     * Command-line arguments. Secret placeholders (`{{secret}}` or
+     * `{{secret:name}}`) are **not** supported here — process arguments are
+     * visible to other processes via `ps` and often collected in logs and
+     * telemetry. `VaultKeeper.exec()` throws `ExecError` if a placeholder
+     * appears in any argument. Use `env` to inject secrets instead.
      */
     args?: string[] | undefined;
     /**
      * Additional environment variables to merge into the child process
-     * environment. Any value may contain `{{secret}}`, which is replaced with
-     * the secret value before the command is spawned.
+     * environment. Any value may contain `{{secret}}` or `{{secret:name}}`,
+     * which is replaced with the secret value before the command is spawned.
      */
     env?: Record<string, string> | undefined;
     /** Working directory for the spawned process. */
     cwd?: string | undefined;
+    /**
+     * Whether to redact injected secret values from the captured `stdout` and
+     * `stderr` before they are returned. Defaults to `true`: every occurrence of
+     * an injected secret value in the captured output is replaced with
+     * `[REDACTED]`, so the raw secret never appears in {@link ExecResult} even
+     * when the spawned command echoes it. Set to `false` to receive the raw,
+     * unredacted output — only for callers that genuinely need it (for example
+     * output that legitimately contains the secret and must be preserved), since
+     * doing so forfeits the redaction guarantee.
+     */
+    redact?: boolean | undefined;
 }
 /** Result from delegated command execution. */
 interface ExecResult {
@@ -284,10 +744,11 @@ interface ExecResult {
 /**
  * Callback-based secret accessor with auto-zeroing.
  *
- * The accessor is backed by a revocable Proxy. Calling `read()` passes a
- * `Buffer` containing the secret to the callback, then zeroes the buffer after
- * the callback returns. The accessor can only be read once; a second call
- * throws.
+ * The accessor is backed by a Proxy and is single-use via an internal
+ * consumed flag. Calling `read()` passes a `Buffer` containing the secret to
+ * the callback, then zeroes the buffer after the callback returns and passes
+ * the callback's return value through. The accessor can only be read once; a
+ * second call throws.
  */
 interface SecretAccessor {
     /**
@@ -297,51 +758,81 @@ interface SecretAccessor {
      * as UTF-8. The buffer is zeroed immediately after the callback returns, so
      * callers must not store a reference to it beyond the callback scope.
      *
-     * @param callback - Function that receives the secret buffer.
+     * The callback's return value is passed through, so a caller-derived result
+     * (for example `buf.toString()` or a hash) flows out of `read()`:
+     * `const digest = accessor.read((buf) => sha256(buf))`. To preserve the
+     * zero-copy, auto-zeroing contract, derive a new value inside the callback —
+     * never return the raw `buf` itself, which is zeroed before `read()` returns.
+     *
+     * @param callback - Function that receives the secret buffer and returns a
+     *   caller-derived value.
+     * @returns Whatever the callback returns.
      * @throws {Error} If the accessor has already been consumed.
      */
-    read(callback: (buf: Buffer) => void): void;
+    read<T>(callback: (buf: Buffer) => T): T;
 }
 /**
- * Request for delegated signing.
+ * A signing algorithm identifier from the strict JOSE registry (RFC 7518).
  *
- * The `data` field is the payload to sign. Strings are UTF-8-encoded
- * before signing.
+ * Only `'EdDSA'` (Ed25519) is supported today; the identifier is intentionally
+ * a strict JOSE `alg` value so future algorithms (`'ES256'`, `'RS256'`, …) each
+ * bind to their proper curve/key type rather than an ambiguous label.
  */
-interface SignRequest {
-    /** The data to sign. Strings are treated as UTF-8. */
-    data: string | Buffer;
+type SigningAlgorithm = 'EdDSA';
+/**
+ * The public half of an enrolled signing key.
+ *
+ * Returned by `key create` / `key export` and used to verify detached
+ * signatures independently of vaultkeeper.
+ */
+interface SigningPublicKey {
+    /** SPKI (SubjectPublicKeyInfo) PEM encoding of the public key. */
+    publicKeyPem: string;
+    /** The JOSE algorithm this key signs with. */
+    algorithm: SigningAlgorithm;
     /**
-     * Override the hash algorithm (`'sha256'`, `'sha384'`, or `'sha512'`).
-     * Ignored for Ed25519/Ed448 keys where the algorithm is implicit.
-     * Non-Edwards keys (RSA, EC) default to `'sha256'` when omitted.
-     * Weak algorithms (e.g. `'md5'`, `'sha1'`) are rejected.
+     * Stable key identifier: the base64url-encoded SHA-256 of the SPKI DER. Used
+     * as the JWS `kid` protected-header value so a verifier can select the key.
      */
-    algorithm?: string | undefined;
+    kid: string;
 }
-/** Result from a delegated signing operation. */
+/**
+ * Request to sign a caller-supplied payload with a named signing key.
+ *
+ * The `payload` is arbitrary bytes to be signed with detachment (RFC 7797) —
+ * it is never stored and never treated as a secret. Strings are UTF-8-encoded
+ * before signing.
+ */
+interface SignRequest {
+    /** The payload bytes to sign. Strings are treated as UTF-8. */
+    payload: string | Buffer;
+}
+/**
+ * Result of a signing operation.
+ *
+ * The signature is a detached-payload Compact JWS (RFC 7515 §7.2.2 + RFC 7797
+ * `b64:false`, `crit:["b64"]`): `<protected>..<signature>`, with the payload
+ * omitted. Any standards-compliant JOSE library can verify it given the
+ * detached payload and the public key.
+ */
 interface SignResult {
-    /** Base64-encoded signature. */
-    signature: string;
-    /**
-     * Algorithm label describing how the signature was produced.
-     * For Edwards keys this is the key type (e.g. `'ed25519'`).
-     * For other keys this matches the `algorithm` field from the request
-     * (or the default `'sha256'`).
-     */
-    algorithm: string;
+    /** The detached-payload compact JWS (`<protected>..<signature>`). */
+    jws: string;
 }
 /**
- * Request for signature verification.
+ * Request for detached-signature verification.
  *
- * This is a static operation that only requires public key material —
- * no VaultKeeper instance or capability token is needed.
+ * This is a fully offline operation that only requires public key material —
+ * no VaultKeeper instance, backend, config, or capability token is needed.
  */
 interface VerifyRequest {
-    /** The original data that was signed. Strings are treated as UTF-8. */
-    data: string | Buffer;
-    /** Base64-encoded signature to verify. */
-    signature: string;
+    /** The detached payload bytes that were signed. Strings are treated as UTF-8. */
+    payload: string | Buffer;
+    /**
+     * The detached-payload compact JWS produced by {@link SignResult.jws}
+     * (`<protected>..<signature>`).
+     */
+    jws: string;
     /**
      * PEM-encoded public key (SPKI format) as a string.
      *
@@ -349,11 +840,6 @@ interface VerifyRequest {
      * accepted by this interface.
      */
     publicKey: string;
-    /**
-     * Override the hash algorithm. Ignored for Ed25519/Ed448 keys.
-     * Non-Edwards keys default to `'sha256'` when omitted.
-     */
-    algorithm?: string | undefined;
 }
 /** Vaultkeeper configuration file structure. */
 interface VaultConfig {
@@ -396,20 +882,19 @@ interface BackendConfig {
     options?: Record<string, string> | undefined;
 }
 
-/**
- * Backend abstraction layer types for vaultkeeper.
- */
 /**
  * Factory function for creating a SecretBackend instance.
  *
  * @remarks
  * Factories may optionally accept a {@link BackendConfig} to configure the
- * backend from the user's vaultkeeper config file. Factories that do not need
- * configuration can ignore the parameter.
+ * backend from the user's vaultkeeper config file, and the resolved config
+ * directory (the same directory config and key material are read from) so
+ * file-based backends can default their storage under it. Factories that do
+ * not need either can ignore the parameters.
  *
  * @public
  */
-type BackendFactory = (config?: BackendConfig) => SecretBackend;
+type BackendFactory = (config?: BackendConfig, configDir?: string) => SecretBackend;
 /**
  * Abstraction interface for all secret storage backends.
  *
@@ -471,6 +956,170 @@ interface ListableBackend extends SecretBackend {
  * @public
  */
 declare function isListableBackend(backend: SecretBackend): backend is ListableBackend;
+/**
+ * A keyed backend operation that a presence-per-use requirement can gate.
+ *
+ * @remarks
+ * Used by {@link BackendCapabilities.presenceEnforcedOperations} to express that
+ * an instance forces a fresh per-use action for only *some* operations. `'read'`
+ * covers the secret read behind `setup`/`exec`; `'store'`, `'delete'`, and
+ * `'sign'` are the write, removal, and signing paths.
+ *
+ * @public
+ */
+type PresenceOperation = 'read' | 'store' | 'delete' | 'sign';
+/**
+ * The set of security capabilities a configured backend instance advertises.
+ *
+ * @remarks
+ * Capabilities describe what a **specific configured instance** guarantees, not
+ * what its backend *type* is generally able to do. Two instances of the same
+ * backend type can report different capabilities depending on their
+ * configuration (e.g. a YubiKey slot with a touch policy vs. one without, or
+ * 1Password in `per-access` vs. `session` mode). Never derive a capability from
+ * the backend's `type` alone.
+ *
+ * The shape is intentionally open to extension: new capability flags may be
+ * added over time, so consumers should read only the fields they understand and
+ * treat a missing/unknown field as absent.
+ *
+ * @public
+ */
+interface BackendCapabilities {
+    /**
+     * `true` when this configured instance can force a distinct, fresh physical
+     * human action (e.g. a YubiKey touch, a gpg-smartcard tap, or a 1Password
+     * per-use biometric approval) — a deliberate action taken *for this operation,
+     * right now*, not merely "a vault was unlocked at some point."
+     *
+     * The guarantee is **operation-scoped**, not blanket: when `presencePerUse` is
+     * `true`, that fresh action is available and **non-bypassably enforced** for
+     * exactly the operations listed in
+     * {@link BackendCapabilities.presenceEnforcedOperations} (all keyed operations
+     * when that field is omitted). For a covered operation, a
+     * {@link https://github.com/mike-north/vaultkeeper/issues/122 | `--require-presence-per-use`}
+     * request drives a fresh action that cannot be satisfied from a cached or
+     * session-unlocked state. For an operation **outside** that set, the request is
+     * **refused** with a `NotCapableError` — it is never silently satisfied from a
+     * cached unlock. A backend that only caches an unlock, or that is
+     * encryption-only with no per-use action, reports `false`.
+     *
+     * Backends that do not implement {@link PresenceCapableBackend} are treated as
+     * `false` by {@link getBackendCapabilities} — an unknown backend never
+     * silently claims presence.
+     */
+    readonly presencePerUse: boolean;
+    /**
+     * The keyed operations for which this instance actually forces a fresh per-use
+     * human action. When **omitted**, a `presencePerUse: true` instance is taken
+     * to force presence for **all** keyed operations — the default for a touch
+     * device (e.g. a YubiKey whose challenge-response touch fires on every
+     * `store`/`retrieve`/`delete`).
+     *
+     * A backend that can force presence for only *some* operations must list
+     * exactly those, so a `--require-presence-per-use` request for an **uncovered**
+     * operation fails closed with a `NotCapableError` rather than silently passing
+     * without a fresh action. For example, 1Password `per-access` forces a fresh
+     * biometric on reads (`setup`/`exec`) but routes `store`/`delete` through the
+     * cached session client, so it reports `['read']` — a flagged `store`/`delete`
+     * is then correctly refused.
+     *
+     * Ignored when {@link BackendCapabilities.presencePerUse} is `false`.
+     */
+    readonly presenceEnforcedOperations?: readonly PresenceOperation[];
+}
+/**
+ * Backend that can report its security {@link BackendCapabilities} for its
+ * configured instance.
+ *
+ * @remarks
+ * This is an optional extension interface, mirroring {@link ListableBackend} and
+ * {@link SigningBackend}: it is **not** a required member of
+ * {@link SecretBackend}. Prefer {@link getBackendCapabilities} over calling
+ * {@link PresenceCapableBackend.getCapabilities} directly, so a backend that
+ * does not implement the interface safely defaults to no capabilities rather
+ * than being assumed to have them.
+ *
+ * {@link PresenceCapableBackend.getCapabilities} is asynchronous and describes
+ * the **current configured/live state** of the instance — it must reflect
+ * configuration (or a live device/session probe) rather than a hardcoded
+ * per-type answer, and must not itself trigger a human-presence prompt.
+ *
+ * @public
+ */
+interface PresenceCapableBackend extends SecretBackend {
+    /**
+     * Report the capabilities of this configured instance.
+     * @returns The instance's {@link BackendCapabilities}.
+     */
+    getCapabilities(): Promise<BackendCapabilities>;
+}
+/**
+ * Type guard for backends that implement the capability-reporting contract.
+ * @public
+ */
+declare function isPresenceCapableBackend(backend: SecretBackend): backend is PresenceCapableBackend;
+/**
+ * Resolve a backend's {@link BackendCapabilities}, defaulting safely for
+ * backends that do not implement {@link PresenceCapableBackend}.
+ *
+ * @remarks
+ * A backend without the capability interface reports `{ presencePerUse: false }`
+ * — an unknown backend never silently claims a security guarantee it cannot
+ * prove. This is the only supported way to query capabilities; callers must not
+ * assume a capability from a backend's `type`.
+ *
+ * @param backend - The backend instance to query.
+ * @returns The instance's capabilities, or the safe default for a backend that
+ *   does not implement {@link PresenceCapableBackend}.
+ * @public
+ */
+declare function getBackendCapabilities(backend: SecretBackend): Promise<BackendCapabilities>;
+/**
+ * Backend that can enroll and use signing keys entirely on its own side.
+ *
+ * @remarks
+ * Signing keys are a distinct resource from secrets: a private key must never
+ * flow through {@link SecretBackend.store}/{@link SecretBackend.retrieve} or a
+ * capability token's claims. A signing backend generates the keypair, exposes
+ * only the public half, and performs the signature itself — the private key
+ * never leaves the backend. This is what keeps a key out of any JWE claims
+ * token and lets a presence-per-use backend enforce its guarantee for signing.
+ *
+ * Implementations must keep signing keys in a namespace that cannot collide
+ * with or be read as ordinary secrets.
+ *
+ * @public
+ */
+interface SigningBackend extends SecretBackend {
+    /**
+     * Enroll a new signing keypair under `id`.
+     * @param id - Namespaced signing-key identifier.
+     * @param algorithm - The JOSE algorithm to generate a key for.
+     * @throws If a signing key already exists under `id`, or `algorithm` is not
+     *   supported by this backend.
+     */
+    generateSigningKey(id: string, algorithm: SigningAlgorithm): Promise<void>;
+    /**
+     * Return the public half of the signing key stored under `id`.
+     * @param id - Namespaced signing-key identifier.
+     * @throws A `SigningKeyNotFoundError` if no signing key exists under `id`.
+     */
+    getPublicKey(id: string): Promise<SigningPublicKey>;
+    /**
+     * Sign `data` with the private key stored under `id`, returning the raw
+     * signature bytes. The private key never leaves the backend.
+     * @param id - Namespaced signing-key identifier.
+     * @param data - The exact bytes to sign (e.g. a JWS signing input).
+     * @throws A `SigningKeyNotFoundError` if no signing key exists under `id`.
+     */
+    signWithKey(id: string, data: Buffer): Promise<Buffer>;
+}
+/**
+ * Type guard for backends that implement the signing contract.
+ * @public
+ */
+declare function isSigningBackend(backend: SecretBackend): backend is SigningBackend;
 
 /**
  * Types for the backend setup protocol.
@@ -536,10 +1185,12 @@ declare class BackendRegistry {
      * Create a backend instance by type.
      * @param type - Backend type identifier
      * @param config - Optional backend configuration forwarded to the factory
+     * @param configDir - Optional resolved config directory forwarded to the
+     *   factory, so file-based backends can default their storage under it
      * @returns A SecretBackend instance
      * @throws {@link BackendUnavailableError} if the backend type is not registered
      */
-    static create(type: string, config?: BackendConfig): SecretBackend;
+    static create(type: string, config?: BackendConfig, configDir?: string): SecretBackend;
     /**
      * Get all registered backend type identifiers.
      * @returns Array of backend type identifiers
@@ -598,7 +1249,23 @@ declare class BackendRegistry {
  * class fields enforce that no property on the token object leaks data.
  */
 
-/** Opaque capability token. Claims are inaccessible without `validateCapabilityToken`. */
+/**
+ * An opaque handle to authorized secret claims.
+ *
+ * A `CapabilityToken` is produced by {@link VaultKeeper.authorize} and
+ * deliberately exposes no readable data. The underlying claims — including the
+ * secret value — are held in a module-private `WeakMap` that this class does
+ * not reference, and its private fields keep any property from leaking them
+ * (`toString()` returns only a debug identifier). There is intentionally no
+ * public API for reading the claims directly.
+ *
+ * To use the secret, pass the token to a {@link VaultKeeper} access method —
+ * {@link VaultKeeper.getSecret}, {@link VaultKeeper.fetch},
+ * {@link VaultKeeper.exec}, or {@link VaultKeeper.sign} — which resolve the
+ * claims internally.
+ *
+ * @public
+ */
 declare class CapabilityToken {
     #private;
     constructor();
@@ -609,32 +1276,256 @@ declare class CapabilityToken {
     toString(): string;
 }
 
+/**
+ * Platform detection utilities.
+ */
+/**
+ * The OS platform identifier used for platform-specific behavior.
+ * @public
+ */
+type Platform = 'darwin' | 'win32' | 'linux';
+
+/**
+ * Doctor runner: orchestrates platform-appropriate checks and aggregates results.
+ */
+
+/**
+ * Options for running the doctor.
+ * @public
+ */
+interface RunDoctorOptions {
+    /** Override the platform detection (useful for testing). */
+    platform?: Platform;
+    /**
+     * When provided, doctor checks are scoped to the given backends.
+     * Platform-native dependency checks (e.g. `secret-tool`, `security`,
+     * `powershell`) are demoted from required to optional when the
+     * corresponding backend is not enabled. Plugin tool checks (`op`,
+     * `ykman`) are promoted from optional to required when their backend
+     * (`1password`, `yubikey`) is explicitly enabled.
+     *
+     * When omitted, all platform-default checks are treated as required
+     * (backward-compatible behavior).
+     */
+    backends?: BackendConfig[];
+    /**
+     * When provided (and `backends` is not explicitly given), doctor loads and
+     * validates the config file under this directory, adding a `config`
+     * preflight check to the result. A present-but-invalid config file (parse
+     * or schema failure) becomes a failing, required check — with the
+     * underlying error's message (file path, parse location, remediation hint)
+     * as `reason` — so an invalid config is visible in `doctor`'s output and
+     * fails the overall `ready` result (issue #68). A missing config file is
+     * not an error: `loadConfig` resolves platform defaults and the check
+     * reports `ok`.
+     */
+    configDir?: string;
+}
+/**
+ * Run all platform-appropriate preflight checks and aggregate the results.
+ * @public
+ */
+declare function runDoctor(options?: RunDoctorOptions): Promise<PreflightResult>;
+
 /**
  * VaultKeeper main class — wires together all vaultkeeper subsystems.
  */
 
-/** Options for initializing VaultKeeper. */
+/**
+ * Map of named secrets to their capability tokens.
+ *
+ * Use with `exec()` or `fetch()` to inject multiple secrets into a single
+ * request. Each key becomes the name referenced in `{{secret:name}}`
+ * placeholders.
+ *
+ * @example
+ * ```ts
+ * const { token: apiToken } = await vault.authorize(apiJwe)
+ * const { token: dbToken } = await vault.authorize(dbJwe)
+ *
+ * await vault.exec(
+ *   { apiKey: apiToken, dbPass: dbToken },
+ *   { command: 'deploy', env: { API_KEY: '{{secret:apiKey}}', DB: '{{secret:dbPass}}' } },
+ * )
+ * ```
+ *
+ * @public
+ */
+type SecretTokenMap = Record<string, CapabilityToken>;
+/**
+ * Options for initializing VaultKeeper.
+ *
+ * @remarks
+ * When neither `config` nor a config file (at `configDir`) is present, and
+ * {@link VaultKeeperOptions.backend} is not set, the active backend falls back
+ * to the safe zero-config default resolved by {@link defaultBackendType} — the
+ * `file` backend, on every platform, so a missing config never silently
+ * targets the real OS credential store. Inspect
+ * {@link VaultKeeper.activeBackendType} after `init()` to confirm which backend
+ * a given instance resolved to. To use the OS-native store instead, opt in via
+ * an explicit config, or `vaultkeeper config init --backend <type>` from the
+ * separate `@vaultkeeper/cli` package (see {@link platformNativeBackendType}).
+ * When `backend` is set instead, see that option's own JSDoc for the fallback
+ * config used in its place.
+ */
 interface VaultKeeperOptions {
     /** Override the config directory. */
     configDir?: string | undefined;
     /** Supply config directly, skipping file load. */
     config?: VaultConfig | undefined;
+    /**
+     * Inject a {@link SecretBackend} instance directly, bypassing the global
+     * {@link BackendRegistry} and `config.backends` resolution entirely.
+     *
+     * This is the primary hook for tests and embedders that want to store and
+     * retrieve secrets without registering a backend globally or hand
+     * assembling a full {@link VaultConfig}. When set, this backend instance is
+     * used for every `store()`/`retrieve()`/`setup()` call.
+     *
+     * **Precedence with `config`/`configDir`:**
+     * - `backend` always wins over the backend that `config.backends` (or the
+     *   config loaded from `configDir`) would otherwise resolve — the
+     *   `backends` array is never consulted when `backend` is set.
+     * - Other config fields (`keyRotation`, `defaults`, `developmentMode`)
+     *   still come from `config`, or from the config loaded from `configDir`,
+     *   when either is provided.
+     * - If `backend` is set and `config` is omitted, a minimal built-in
+     *   default config is used instead of loading one from `configDir` — so a
+     *   caller that only needs an injected backend never has to construct a
+     *   {@link VaultConfig} or touch `configDir` at all.
+     */
+    backend?: SecretBackend | undefined;
     /** Skip the doctor preflight check. */
     skipDoctor?: boolean | undefined;
 }
-/** Options for the setup operation. */
-interface SetupOptions {
+/**
+ * Options common to every backend-touching operation that can be gated on a
+ * fresh, per-use human presence action.
+ *
+ * @remarks
+ * When `requirePresencePerUse` is `true`, the operation refuses — with a
+ * {@link NotCapableError}, before any credential, session, or device is touched
+ * — unless the active backend's configured instance advertises
+ * {@link BackendCapabilities.presencePerUse}. When the backend is capable, the
+ * operation proceeds through the backend's ordinary path, which (by the meaning
+ * of the capability) forces a distinct fresh human action for this specific
+ * call; a cached or session-unlocked state can never satisfy it. Capabilities
+ * are queried fresh on every call and never cached across operations.
+ *
+ * @public
+ */
+interface PresenceRequirementOptions {
+    /**
+     * Require the active backend to force a fresh, per-use human presence action
+     * for this operation. Defaults to `false` (no presence requirement).
+     */
+    requirePresencePerUse?: boolean | undefined;
+}
+/**
+ * Options for {@link VaultKeeper.setup} that are independent of the mandatory
+ * executable-trust choice. Intersected with that choice to form
+ * {@link SetupOptions}.
+ *
+ * @public
+ */
+interface SetupOptionsBase extends PresenceRequirementOptions {
     /** TTL in minutes for the JWE. */
     ttlMinutes?: number | undefined;
     /** Usage limit (null for unlimited). */
     useLimit?: number | null | undefined;
-    /** Executable path for identity binding. Use "dev" for dev mode. */
-    executablePath?: string | undefined;
     /** Trust tier override. */
     trustTier?: TrustTier | undefined;
     /** Backend type to use. */
     backendType?: string | undefined;
 }
+/**
+ * Options for the setup operation.
+ *
+ * @remarks
+ * The executable-trust choice is **mandatory and mutually exclusive**, and the
+ * type system enforces it: `SetupOptions` is {@link SetupOptionsBase}
+ * intersected with a choice of **exactly one** of `executablePath` (run
+ * trust-on-first-use verification — the production choice) or `skipTrust: true`
+ * (deliberately skip verification — development only). An options object with
+ * **neither** field, or with **both**, fails to typecheck; and because
+ * {@link VaultKeeper.setup}'s options argument is required, `vault.setup('NAME')`
+ * and `vault.setup('NAME', {})` are compile-time type errors rather than
+ * runtime-only failures. {@link ExecutableTrustRequiredError} remains a runtime
+ * backstop for callers without static typing (e.g. plain JavaScript), and is
+ * still thrown if `executablePath` is the retired legacy `'dev'` sentinel.
+ *
+ * @public
+ */
+type SetupOptions = SetupOptionsBase & ({
+    /**
+     * Path to the calling executable, used to bind the minted token to that
+     * executable's identity. `setup()` runs trust-on-first-use (TOFU)
+     * verification: the file is hashed (SHA-256) and checked against the
+     * local trust manifest. This is the safe, production choice.
+     *
+     * A path registered via `setDevelopmentMode` is still exempted from
+     * hashing (the established development-mode allowlist); any other path
+     * is verified. Mutually exclusive with `skipTrust`.
+     *
+     * **Rebuild caveat:** for a compiled or bundled entry point the file's
+     * hash changes on every rebuild, so binding to a dev build target (e.g.
+     * `process.argv[1]`) makes the next `setup()` after a recompile throw
+     * `IdentityMismatchError`. In production point this at a **stable**
+     * artifact — a released binary, or `process.execPath` to trust the Node
+     * runtime; for a frequently-rebuilt local caller you want to keep
+     * verifying, use `setDevelopmentMode` instead.
+     */
+    executablePath: string;
+    skipTrust?: never;
+} | {
+    /**
+     * Development-only escape hatch: skip executable-trust (TOFU)
+     * verification. The minted token carries no executable identity binding.
+     *
+     * **Security warning:** a token minted with `skipTrust: true` is not
+     * bound to any calling executable, so any process that obtains the JWE
+     * can redeem it. Use this only in local development or tests — never in
+     * production. Prefer `executablePath` so executable trust is actually
+     * enforced. Mutually exclusive with `executablePath`.
+     */
+    skipTrust: true;
+    executablePath?: never;
+});
+/**
+ * Trust status of an executable, as recorded in the trust-on-first-use (TOFU)
+ * trust manifest.
+ *
+ * Returned by {@link VaultKeeper.approveExecutable} and
+ * {@link VaultKeeper.checkExecutableTrust}.
+ *
+ * @public
+ */
+interface ExecutableTrustStatus {
+    /**
+     * Whether the executable's current hash is approved in the trust manifest.
+     * When `false`, callers must obtain approval (e.g. an interactive prompt)
+     * before granting secret access.
+     */
+    trusted: boolean;
+    /** SHA-256 hex digest of the executable's current contents. */
+    hash: string;
+    /**
+     * `true` when the executable is already known to the manifest but its
+     * current hash does not match any approved value — a TOFU conflict. A
+     * conflicting executable is never trusted; callers must re-approve or deny.
+     */
+    hashMismatch: boolean;
+    /**
+     * Hashes recorded as approved for this executable in the trust manifest, in
+     * approval order (empty when the executable has never been approved). When
+     * {@link ExecutableTrustStatus.hashMismatch} is `true`, these are the prior
+     * approved values that {@link ExecutableTrustStatus.hash} no longer matches;
+     * the last element is the most recently approved hash.
+     */
+    approvedHashes: readonly string[];
+    /** Human-readable description of how trust was (or was not) established. */
+    reason: string;
+}
 /**
  * Main entry point for vaultkeeper. Orchestrates backends, keys, JWE tokens,
  * identity verification, and access patterns.
@@ -645,70 +1536,253 @@ declare class VaultKeeper {
     /**
      * Initialize a new VaultKeeper instance.
      * Runs doctor checks (unless skipped), loads config, and sets up the key manager.
+     *
+     * The configured secret backend is resolved lazily on first use, not during
+     * `init()`. Trust-only operations (e.g. {@link VaultKeeper.approveExecutable},
+     * {@link VaultKeeper.checkExecutableTrust}) therefore succeed even when the
+     * configured backend or plugin is unavailable or unregistered; a
+     * misconfigured backend surfaces only when a secret operation is invoked.
      */
     static init(options?: VaultKeeperOptions): Promise<VaultKeeper>;
     /**
      * Run doctor checks without full initialization.
      *
-     * Uses conservative platform defaults — all platform-native dependency
-     * checks are treated as required regardless of any backend configuration.
-     * For config-aware scoping, call `runDoctor({ backends })` directly.
+     * When called without arguments, uses conservative platform defaults —
+     * all platform-native dependency checks are treated as required. Pass
+     * `{ backends }` to scope checks to only the backends you plan to use.
+     *
+     * @param options - Optional doctor options (e.g. `{ backends }` to scope checks).
      */
-    static doctor(): Promise<PreflightResult>;
+    static doctor(options?: RunDoctorOptions): Promise<PreflightResult>;
     /**
-     * Retrieve a secret from the backend and return a JWE token that encapsulates it.
+     * The type identifier of the active backend — the first enabled backend in
+     * the resolved configuration (the one `store()`, `delete()`, and `setup()`
+     * operate on).
+     *
+     * @remarks
+     * This is a pure, side-effect-free view of the resolved configuration: it
+     * reads the type of the first enabled backend without instantiating the
+     * backend or requiring it to be registered or healthy. Reading it therefore
+     * never throws for an unavailable or unregistered backend — unlike a secret
+     * operation — so it is safe to call purely to introspect an instance.
+     *
+     * When a backend was injected via `init({ backend })`, config-based
+     * resolution is bypassed entirely and this reports the injected instance's
+     * declared `type` (see {@link SecretBackend}) — or the stable sentinel
+     * `'custom'` if it declares an empty type. It never throws in the injected
+     * path.
      *
-     * @param secretName - Identifier for the secret
-     * @param options - Setup options
+     * Use it to confirm which backend an instance resolved to, especially when
+     * no config file exists and the safe zero-config default applies (see
+     * {@link defaultBackendType}). With no config this reads `file` on every
+     * platform, so secret operations never silently target the real OS
+     * credential store; opt into the native store (see
+     * {@link platformNativeBackendType}) via explicit config to change this.
+     *
+     * @throws A {@link BackendUnavailableError} only when the configuration has
+     * no enabled backend at all (a configuration error, not a backend fault).
+     * This can only happen in the config-driven path; an injected backend never
+     * throws here.
+     *
+     * @public
+     */
+    get activeBackendType(): string;
+    /**
+     * Report the {@link BackendCapabilities} of the active backend's configured
+     * instance — the same backend {@link VaultKeeper.store}, {@link VaultKeeper.setup},
+     * and {@link VaultKeeper.sign} operate on.
+     *
+     * @remarks
+     * Unlike the pure {@link VaultKeeper.activeBackendType} getter, this resolves
+     * (instantiates) the backend, because capabilities are a property of the
+     * configured instance, not of the type. The answer reflects configured/live
+     * state — e.g. a YubiKey slot's touch policy or 1Password's access mode — and
+     * a backend that does not implement {@link PresenceCapableBackend} reports the
+     * safe default (`{ presencePerUse: false }`) via {@link getBackendCapabilities}.
+     * Reading this never triggers a human-presence prompt.
+     *
+     * @returns The active backend instance's capabilities.
+     * @throws A {@link BackendUnavailableError} if no backend is enabled or the
+     *   configured backend cannot be built.
+     * @public
+     */
+    getActiveBackendCapabilities(): Promise<BackendCapabilities>;
+    /**
+     * Store a secret in the configured backend.
+     *
+     * This is a convenience method that delegates to the active backend's
+     * `store()` method. If a secret with the same name already exists, it is
+     * overwritten.
+     *
+     * @param name - Identifier for the secret. Must not contain `':'` — that
+     *   character is reserved for the internal `signing-key:` namespace, so a
+     *   secret name can never collide with a signing key.
+     * @param value - The secret value to store.
+     * @param options - Optional {@link PresenceRequirementOptions}. When
+     *   `requirePresencePerUse` is set, the store is refused with a
+     *   {@link NotCapableError} before the backend is touched unless the active
+     *   backend forces a fresh per-use human action.
+     * @throws {VaultError} If `name` is empty or contains `':'`.
+     * @throws {@link NotCapableError} If `options.requirePresencePerUse` is set
+     *   and the active backend is not presence-per-use capable.
+     * @public
+     */
+    store(name: string, value: string, options?: PresenceRequirementOptions): Promise<void>;
+    /**
+     * Delete a secret from the configured backend.
+     *
+     * This is a convenience method that delegates to the active backend's
+     * `delete()` method.
+     *
+     * @param name - Identifier for the secret to delete.
+     * @param options - Optional {@link PresenceRequirementOptions}. When
+     *   `requirePresencePerUse` is set, the delete is refused with a
+     *   {@link NotCapableError} before the backend is touched unless the active
+     *   backend forces a fresh per-use human action.
+     * @throws {@link NotCapableError} If `options.requirePresencePerUse` is set
+     *   and the active backend is not presence-per-use capable.
+     * @public
+     */
+    delete(name: string, options?: PresenceRequirementOptions): Promise<void>;
+    /**
+     * Check whether a secret exists in the active backend, without retrieving
+     * its value, minting a token, or touching the TOFU trust manifest.
+     *
+     * @remarks
+     * This is a lightweight precondition check intended to run before any
+     * interactive or trust-gating logic (e.g. `exec`'s caller-approval prompt),
+     * so a nonexistent secret is reported immediately and unambiguously instead
+     * of being masked by an unrelated approval failure — see issue #69.
+     *
+     * @param name - Identifier for the secret.
+     * @returns `true` if the secret exists, `false` otherwise.
+     * @public
+     */
+    secretExists(name: string): Promise<boolean>;
+    /**
+     * Read a stored secret from the backend and mint a JWE token that encapsulates it.
+     *
+     * @remarks
+     * `setup()` requires an explicit executable-trust decision — it has no
+     * default and never silently skips verification. Pass `executablePath` (the
+     * calling executable's real path) to run trust-on-first-use verification, or
+     * `skipTrust: true` to deliberately skip it in development. The {@link SetupOptions}
+     * type enforces this choice at compile time (exactly one, and the options
+     * argument is required); {@link ExecutableTrustRequiredError} is the runtime
+     * backstop for untyped callers.
+     *
+     * **Seeing a compile error here?** A bare `vault.setup('NAME')` or
+     * `vault.setup('NAME', {})` fails to typecheck (e.g. TS2554 "Expected 2
+     * arguments, but got 1" or TS2345 "Argument … is not assignable") precisely
+     * because the mandatory trust choice is missing. The fix is to add **exactly
+     * one** of `executablePath: '<path>'` (verify the caller — production) or
+     * `skipTrust: true` (skip verification — development only). Supplying both
+     * fails to typecheck for the same reason.
+     *
+     * @example
+     * ```ts
+     * // Production: bind the token to a STABLE executable so a swapped binary is
+     * // rejected. Point executablePath at a released binary, or process.execPath
+     * // to trust the Node runtime. Do NOT use process.argv[1] for a compiled entry
+     * // point — its hash changes on every rebuild, so the next setup() after a
+     * // recompile throws IdentityMismatchError (use setDevelopmentMode or
+     * // skipTrust for a frequently-rebuilt local caller).
+     * const jwe = await vault.setup('MY_API_KEY', { executablePath: '/usr/local/bin/my-tool' })
+     *
+     * // Local development: skip verification so rebuilds don't reject the caller.
+     * const devJwe = await vault.setup('MY_API_KEY', { skipTrust: true })
+     * ```
+     *
+     * @param secretName - Identifier for the secret. Must not contain `':'` (the
+     *   reserved `signing-key:` namespace separator).
+     * @param options - Setup options; must carry exactly one of `executablePath`
+     *   or `skipTrust: true`
      * @returns Compact JWE string
+     * @throws {VaultError} If `secretName` is empty or contains `':'`.
+     * @throws {@link ExecutableTrustRequiredError} If neither `executablePath`
+     *   nor `skipTrust: true` is provided, if both are, or if `executablePath` is
+     *   the retired legacy `'dev'` opt-out sentinel (use `skipTrust: true`).
+     * @throws {@link IdentityMismatchError} If `executablePath`'s current hash no
+     *   longer matches a previously approved value (TOFU conflict).
+     * @throws {@link FilesystemError} If `executablePath` cannot be read or hashed
+     *   for verification, or the trust manifest cannot be read or written while
+     *   recording the executable.
      */
-    setup(secretName: string, options?: SetupOptions): Promise<string>;
+    setup(secretName: string, options: SetupOptions): Promise<string>;
     /**
      * Decrypt a JWE, validate claims, verify executable identity, and return
      * an opaque CapabilityToken.
      *
      * @param jwe - Compact JWE string from setup()
-     * @returns Opaque capability token for use with fetch/exec/getSecret
+     * @returns Object containing an opaque {@link CapabilityToken} for use with
+     *   fetch/exec/getSecret, and a {@link VaultResponse} describing key status.
+     *   When the JWE was decrypted with a non-current key,
+     *   `vaultResponse.rotatedJwt` contains a re-encrypted JWE for the current key.
      */
     authorize(jwe: string): Promise<{
         token: CapabilityToken;
-        response: VaultResponse;
+        vaultResponse: VaultResponse;
     }>;
     /**
-     * Execute a delegated HTTP fetch, injecting the secret from the token.
+     * Execute a delegated HTTP fetch, injecting secrets from the token(s).
      *
-     * The secret value is substituted for every `{{secret}}` placeholder found
-     * in `request.url`, `request.headers`, and `request.body` before the fetch
-     * is executed. The raw secret is never exposed in the return value.
+     * **Single token:** every `{{secret}}` placeholder in `request.url`,
+     * `request.headers`, and `request.body` is replaced with the secret value.
      *
-     * @param token - A `CapabilityToken` obtained from `authorize()`.
-     * @param request - The fetch request template. Use `{{secret}}` as a
-     *   placeholder wherever the secret value should be injected.
+     * **Token map ({@link SecretTokenMap}):** every `{{secret:name}}` placeholder
+     * is replaced with the secret from the corresponding named token.
+     *
+     * The raw secret is never exposed in the return value.
+     *
+     * @param token - A single `CapabilityToken` or a `SecretTokenMap` mapping
+     *   names to tokens obtained from `authorize()`.
+     * @param request - The fetch request template with placeholders.
      * @returns The `Response` from the underlying `fetch()` call, together with
      *   the vault metadata (`vaultResponse`).
-     * @throws {Error} If `token` is invalid or was not created by this vault
-     *   instance.
+     * @throws {AuthorizationDeniedError} If any token is invalid or was not
+     *   created by this vault instance.
+     * @throws {VaultError} If a named placeholder references an unknown
+     *   secret name.
+     * @throws {FetchError} If the URL is malformed or the underlying network
+     *   request fails.
      */
-    fetch(token: CapabilityToken, request: FetchRequest): Promise<{
+    fetch(token: CapabilityToken | SecretTokenMap, request: FetchRequest): Promise<{
         response: Response;
         vaultResponse: VaultResponse;
     }>;
     /**
-     * Execute a delegated command, injecting the secret from the token.
+     * Execute a delegated command, injecting secrets from the token(s).
      *
-     * The secret value is substituted for every `{{secret}}` placeholder found
-     * in `request.args` and `request.env` values before the process is spawned.
-     * The raw secret is never exposed in the return value.
+     * **Single token:** every `{{secret}}` placeholder in `request.env` values
+     * is replaced with the secret value.
      *
-     * @param token - A `CapabilityToken` obtained from `authorize()`.
-     * @param request - The exec request template. Use `{{secret}}` as a
-     *   placeholder wherever the secret value should be injected.
+     * **Token map ({@link SecretTokenMap}):** every `{{secret:name}}` placeholder
+     * is replaced with the secret from the corresponding named token.
+     *
+     * Secret placeholders are not supported in `request.command` or
+     * `request.args` — process arguments are visible to other processes via
+     * `ps` and often collected in logs and telemetry.
+     *
+     * The raw secret is never exposed in the return value: by default the
+     * captured `stdout`/`stderr` is scrubbed of every injected secret value
+     * (replaced with `[REDACTED]`), so a command that echoes the secret does not
+     * leak it back. Pass `request.redact = false` to receive raw, unredacted
+     * output — only when a caller genuinely needs it, since that forfeits the
+     * guarantee.
+     *
+     * @param token - A single `CapabilityToken` or a `SecretTokenMap` mapping
+     *   names to tokens obtained from `authorize()`.
+     * @param request - The exec request template with placeholders. Set
+     *   `redact: false` to opt out of output redaction.
      * @returns The command result (`stdout`, `stderr`, `exitCode`) together with
      *   the vault metadata (`vaultResponse`).
-     * @throws {Error} If `token` is invalid or was not created by this vault
-     *   instance.
+     * @throws {AuthorizationDeniedError} If any token is invalid or was not
+     *   created by this vault instance.
+     * @throws {ExecError} If the command cannot be started (e.g. ENOENT),
+     *   a placeholder references an unknown secret name, or a secret
+     *   placeholder appears in the `command` or `args` field.
      */
-    exec(token: CapabilityToken, request: ExecRequest): Promise<{
+    exec(token: CapabilityToken | SecretTokenMap, request: ExecRequest): Promise<{
         result: ExecResult;
         vaultResponse: VaultResponse;
     }>;
@@ -721,49 +1795,108 @@ declare class VaultKeeper {
      *
      * @param token - A `CapabilityToken` obtained from `authorize()`.
      * @returns A `SecretAccessor` that can be read exactly once.
-     * @throws {Error} If `token` is invalid or was not created by this vault
-     *   instance.
+     * @throws {AuthorizationDeniedError} If `token` is invalid or was not created
+     *   by this vault instance, or if it is a signing-key token — a signing key
+     *   carries no secret and cannot be read through `getSecret()` (use `sign()`).
      */
     getSecret(token: CapabilityToken): SecretAccessor;
     /**
-     * Sign data using the private key embedded in a capability token.
+     * Enroll a new signing keypair under `name` in the active backend.
      *
-     * The signing key is extracted from the token's encrypted claims, used
-     * for a single `crypto.sign()` call, and never exposed to the caller.
-     * The algorithm is auto-detected from the key type unless overridden
-     * in the request.
+     * The keypair is generated and stored entirely backend-side (see
+     * {@link SigningBackend}); the private key never enters vault claims, a
+     * capability token, or the caller's process. Signing keys occupy a namespace
+     * distinct from secrets, so a signing key and a secret can share a name
+     * without colliding, and a signing key can never be read as a secret.
      *
-     * @param token - A `CapabilityToken` obtained from `authorize()`.
-     * @param request - The data to sign and optional algorithm override.
-     * @returns The base64-encoded signature and algorithm label, together
-     *   with the vault metadata (`vaultResponse`).
-     * @throws {VaultError} If `token` is invalid or was not created by this
-     *   vault instance.
-     * @throws {InvalidAlgorithmError} If `request.algorithm` is not in the
-     *   allowed set (e.g. `'md5'`).
-     */
-    sign(token: CapabilityToken, request: SignRequest): Promise<{
+     * @param name - Caller-facing signing key name. Must not contain `':'` (the
+     *   `signing-key:` namespace separator).
+     * @param algorithm - The JOSE signing algorithm (currently only `'EdDSA'`).
+     * @returns The public half of the newly enrolled key.
+     * @throws {SigningNotSupportedError} If the active backend cannot sign.
+     * @throws {InvalidAlgorithmError} If `algorithm` is not supported.
+     * @throws {SigningKeyAlreadyExistsError} If a signing key already exists under `name`.
+     * @throws {VaultError} If `name` is empty or contains `':'`.
+     * @public
+     */
+    createSigningKey(name: string, algorithm: SigningAlgorithm): Promise<SigningPublicKey>;
+    /**
+     * Export the SPKI PEM public key for the signing key named `name`.
+     *
+     * @param name - Caller-facing signing key name. Must not contain `':'`.
+     * @returns The public key material (SPKI PEM, algorithm, kid).
+     * @throws {SigningNotSupportedError} If the active backend cannot sign.
+     * @throws {SigningKeyNotFoundError} If no signing key exists under `name`.
+     * @throws {VaultError} If `name` is empty or contains `':'`.
+     * @public
+     */
+    exportPublicKey(name: string): Promise<SigningPublicKey>;
+    /**
+     * Mint a signing-key capability token for the key named `name`.
+     *
+     * The returned token carries only `{ kid, backendRef, keyType: 'signing-key' }`
+     * — never any key material — and is accepted only by {@link VaultKeeper.sign}.
+     * Passing it to `getSecret`/`fetch`/`exec` is rejected.
+     *
+     * @param name - Caller-facing signing key name. Must not contain `':'`.
+     * @returns An opaque {@link CapabilityToken} usable with `sign()`.
+     * @throws {SigningNotSupportedError} If the active backend cannot sign.
+     * @throws {SigningKeyNotFoundError} If no signing key exists under `name`.
+     * @throws {VaultError} If `name` is empty or contains `':'`.
+     * @public
+     */
+    authorizeSigningKey(name: string): Promise<CapabilityToken>;
+    /**
+     * Sign a caller-supplied payload with a signing-key capability token.
+     *
+     * The signature is produced backend-side via {@link SigningBackend.signWithKey}
+     * — the private key never leaves the backend and never appears in the token,
+     * the claims, or this process. The result is a detached-payload Compact JWS
+     * (RFC 7515 §7.2.2 + RFC 7797 `b64:false`, `crit:["b64"]`, `alg:EdDSA`) that
+     * any standards-compliant JOSE library can verify given the payload and the
+     * public key.
+     *
+     * @param token - A signing-key `CapabilityToken` from {@link VaultKeeper.authorizeSigningKey}.
+     * @param request - The payload to sign.
+     * @param options - Optional {@link PresenceRequirementOptions}. When
+     *   `requirePresencePerUse` is set, the signature is refused with a
+     *   {@link NotCapableError} before the backend is touched unless the active
+     *   backend forces a fresh per-use human action. When capable, a fresh
+     *   backend `signWithKey` round-trip is performed for this call — no cached
+     *   key material can satisfy it (the private key never leaves the backend).
+     * @returns The detached compact JWS and vault metadata.
+     * @throws {AuthorizationDeniedError} If `token` is invalid or is not a
+     *   signing-key token (e.g. an ordinary secret token).
+     * @throws {SigningNotSupportedError} If the active backend cannot sign.
+     * @throws {SigningKeyNotFoundError} If the referenced key no longer exists.
+     * @throws {@link NotCapableError} If `options.requirePresencePerUse` is set
+     *   and the active backend is not presence-per-use capable.
+     * @public
+     */
+    sign(token: CapabilityToken, request: SignRequest, options?: PresenceRequirementOptions): Promise<{
         result: SignResult;
         vaultResponse: VaultResponse;
     }>;
     /**
-     * Verify a signature using a public key.
-     *
-     * This is a static method — no VaultKeeper instance, secrets, or
-     * capability tokens are required. It is safe to call from CI or any
-     * context that has access to public key material.
+     * Verify a detached-payload Compact JWS against a public key — fully offline.
      *
-     * Returns `false` for invalid key material, malformed signatures, or
-     * any verification failure (except disallowed algorithms, which throw).
+     * This is a static, asynchronous method: no VaultKeeper instance, backend,
+     * config, or capability token is required, so it is safe to call in CI or any
+     * context holding only public material.
      *
-     * @throws {InvalidAlgorithmError} If `request.algorithm` is not in the
-     *   allowed set (e.g. `'md5'`).
+     * Returns `false` for a signature that does not verify — a tampered payload,
+     * the wrong key, or a structurally malformed JWS. It throws
+     * {@link InvalidKeyMaterialError} only when the public key itself is not
+     * parseable (or a private key was supplied) — an operational fault distinct
+     * from a bad signature.
      *
-     * @param request - The data, signature, public key, and optional
-     *   algorithm override.
+     * @param request - The detached payload, the JWS, and the SPKI PEM public key.
      * @returns `true` if the signature is valid, `false` otherwise.
+     * @throws {InvalidKeyMaterialError} If `request.publicKey` is not parseable
+     *   SPKI public key material.
+     * @public
      */
-    static verify(request: VerifyRequest): boolean;
+    static verify(request: VerifyRequest): Promise<boolean>;
     /**
      * Rotate the current encryption key.
      *
@@ -797,45 +1930,202 @@ declare class VaultKeeper {
      *   to remove it.
      */
     setDevelopmentMode(executablePath: string, enabled: boolean): Promise<void>;
+    /**
+     * Approve an executable for trust-on-first-use by recording its current
+     * SHA-256 hash in the trust manifest.
+     *
+     * After approval, {@link VaultKeeper.setup} and
+     * {@link VaultKeeper.checkExecutableTrust} recognize the executable (matched
+     * by its resolved absolute path and content hash) as trusted, so callers can
+     * skip an interactive approval prompt.
+     *
+     * The operation is idempotent: approving the same, unchanged executable more
+     * than once leaves a single manifest entry.
+     *
+     * @param executablePath - Path to the executable to approve. Resolved to an
+     *   absolute path before hashing and recording.
+     * @returns The recorded trust status (always `trusted: true`).
+     * @throws {FilesystemError} If the executable does not exist or cannot be read.
+     * @public
+     */
+    approveExecutable(executablePath: string): Promise<ExecutableTrustStatus>;
+    /**
+     * Check whether an executable is trusted according to the trust manifest,
+     * without modifying the manifest.
+     *
+     * This is a read-only probe. Unlike {@link VaultKeeper.setup}, it never
+     * records a hash, so it can be used to decide whether an interactive approval
+     * prompt is required before proceeding.
+     *
+     * @param executablePath - Path to the executable to check. Resolved to an
+     *   absolute path before hashing and lookup.
+     * @returns The current trust status. `trusted` is `true` only when the
+     *   executable's current hash matches an approved manifest entry.
+     * @throws {FilesystemError} If the executable does not exist or cannot be read.
+     * @public
+     */
+    checkExecutableTrust(executablePath: string): Promise<ExecutableTrustStatus>;
 }
 
 /**
- * Platform detection utilities.
+ * Secret redaction for captured process output.
+ *
+ * The single source of truth for how an injected secret value is scrubbed from
+ * text. Both the library's delegated `exec()` (which buffers full output) and
+ * the CLI's streaming `RedactingStream` (which redacts live) route their
+ * substitution through {@link redactSecrets}, so the redaction behavior can
+ * never drift between the two surfaces.
  */
 /**
- * The OS platform identifier used for platform-specific behavior.
+ * The token substituted for a redacted secret value.
+ *
  * @public
  */
-type Platform = 'darwin' | 'win32' | 'linux';
+declare const REDACTED = "[REDACTED]";
+/**
+ * Replace every occurrence of each secret value in `text` with `replacement`.
+ *
+ * This is used to scrub captured child-process `stdout`/`stderr` so a secret
+ * injected into a delegated command never surfaces in the returned output.
+ *
+ * Before redacting, the secret set is normalized so masking is complete and
+ * order-independent:
+ *
+ * - **Empty/whitespace-only values are dropped.** An empty string matches
+ *   between every character, and a whitespace-only value matches ubiquitous
+ *   whitespace, so redacting either would blank the text rather than a secret.
+ * - **Duplicates are removed** so each distinct value is processed once.
+ * - **Longer values are redacted first.** If one secret is a substring or
+ *   prefix of another — common for keys that share a prefix — redacting the
+ *   shorter one first would leave the longer secret's remaining suffix visible
+ *   (redacting `"abc"` before `"abc123"` yields `"[REDACTED]123"`, leaking
+ *   `"123"`). Sorting by length descending guarantees each longer value is
+ *   fully masked before any shorter substring pass runs.
+ *
+ * Both arguments are treated fully literally: the secret is matched as a
+ * plain substring (never as a regular expression), and `replacement` is
+ * inserted verbatim — `String.prototype.replaceAll`'s `$`-substitution
+ * patterns are disabled, since a replacement containing `$&` would otherwise
+ * re-expand to the matched secret and silently defeat the redaction.
+ *
+ * @param text - The text to scrub.
+ * @param secrets - The secret values to redact. Every non-empty, non-whitespace
+ *   value has all of its occurrences replaced.
+ * @param replacement - The token to substitute for each occurrence, inserted
+ *   literally. Defaults to {@link REDACTED}.
+ * @returns `text` with every occurrence of each redactable secret replaced.
+ *
+ * @public
+ */
+declare function redactSecrets(text: string, secrets: readonly string[], replacement?: string): string;
 
 /**
- * Doctor runner: orchestrates platform-appropriate checks and aggregates results.
+ * Configuration loading, validation, and defaults for vaultkeeper.
  */
 
 /**
- * Options for running the doctor.
+ * Return the platform-appropriate default config directory, ignoring the
+ * `VAULTKEEPER_CONFIG_DIR` environment variable.
+ *
+ * This is the location vaultkeeper falls back to when neither a CLI
+ * `--config-dir` flag nor the `VAULTKEEPER_CONFIG_DIR` environment variable
+ * is set: `%APPDATA%/vaultkeeper` on Windows, `~/.config/vaultkeeper`
+ * elsewhere.
+ *
+ * Unlike `getDefaultConfigDir`, this deliberately does not consult
+ * `VAULTKEEPER_CONFIG_DIR`, so a caller can tell whether an active config
+ * directory differs from the machine default even when that difference came
+ * from the environment variable — for example, to decide whether a printed
+ * remediation command must carry an explicit `--config-dir` so it still
+ * targets the right file in a fresh shell that does not have the environment
+ * variable set.
+ *
  * @public
  */
-interface RunDoctorOptions {
-    /** Override the platform detection (useful for testing). */
-    platform?: Platform;
-    /**
-     * When provided, doctor checks are scoped to the given backends.
-     * Platform-native dependency checks (e.g. `secret-tool`, `security`,
-     * `powershell`) are demoted from required to optional when the
-     * corresponding backend is not enabled. Plugin tool checks (`op`,
-     * `ykman`) are promoted from optional to required when their backend
-     * (`1password`, `yubikey`) is explicitly enabled.
-     *
-     * When omitted, all platform-default checks are treated as required
-     * (backward-compatible behavior).
-     */
-    backends?: BackendConfig[];
-}
+declare function getPlatformDefaultConfigDir(): string;
 /**
- * Run all platform-appropriate preflight checks and aggregate the results.
+ * Return the platform-appropriate default config directory.
+ *
+ * Resolution order: the `VAULTKEEPER_CONFIG_DIR` environment variable, then
+ * the platform default (see `getPlatformDefaultConfigDir`). Consumers that
+ * also support a higher-precedence override (e.g. a CLI flag) should check
+ * that first and only fall back to this function when no override was
+ * supplied.
+ *
  * @public
  */
-declare function runDoctor(options?: RunDoctorOptions): Promise<PreflightResult>;
+declare function getDefaultConfigDir(): string;
+/**
+ * The backend type vaultkeeper uses by default when no backend is explicitly
+ * configured — the **`file`** backend, on every platform.
+ *
+ * @remarks
+ * The zero-config default is deliberately the portable, self-contained
+ * AES-256-GCM encrypted file backend rather than the platform-native OS
+ * credential store. This guarantees that a bare {@link VaultKeeper.init} — or a
+ * `vaultkeeper config init` (run via the separate `@vaultkeeper/cli` package)
+ * with no `--backend` flag — can never silently write a secret into the
+ * user's real login keychain (or Windows DPAPI store) before they have
+ * chosen to. It also matches the WASM SDK, which always uses the file
+ * backend.
+ *
+ * The OS-native store is still available as an explicit opt-in: pass
+ * `--backend keychain` (macOS) / `--backend dpapi` (Windows) to
+ * `vaultkeeper config init` (via `@vaultkeeper/cli`), or set
+ * `{ type: 'keychain' | 'dpapi' }` directly in a config object/file. Use
+ * {@link platformNativeBackendType} to discover which native store the current
+ * platform offers.
+ *
+ * @returns The zero-config default backend type identifier (`'file'`).
+ * @public
+ */
+declare function defaultBackendType(): string;
+/**
+ * Resolve the OS-native credential store type for the current platform.
+ *
+ * @remarks
+ * This is **not** the zero-config default — {@link defaultBackendType} (always
+ * `'file'`) is. This function reports which platform-native store a user can
+ * explicitly opt into (e.g. via `vaultkeeper config init --backend keychain`
+ * from the separate `@vaultkeeper/cli` package, or `{ type: 'keychain' }` in
+ * a config object/file passed directly to this library):
+ *
+ * - **macOS** → `keychain` (macOS Keychain)
+ * - **Windows** → `dpapi` (Windows DPAPI)
+ * - **Linux** → `secret-tool` (Secret Service via `libsecret`; opting in
+ *   requires the `libsecret-tools` package)
+ * - **any other platform** → `file` (no built-in native store integration, so
+ *   the portable AES-256-GCM encrypted file backend is the only option)
+ *
+ * Use it to tell the user which native store is available on their platform, or
+ * to label the opt-in. It never affects what an unconfigured vault resolves to
+ * — that is always {@link defaultBackendType} (`file`).
+ *
+ * @returns The OS-native backend type identifier for the current platform.
+ * @public
+ */
+declare function platformNativeBackendType(): string;
+/**
+ * Load the vaultkeeper config from disk, falling back to platform defaults
+ * only when the config file is missing (`ENOENT`).
+ *
+ * Any other read failure (e.g. `EACCES`, `EISDIR`) is a genuinely broken or
+ * unreadable config and is rethrown as a {@link FilesystemError} rather than
+ * silently defaulted — silently defaulting on a permissions error would hide
+ * the problem from `doctor` and `config show` (issue #68). A present file
+ * that fails to parse as JSON throws {@link ConfigParseError}; a present file
+ * that parses but fails schema validation throws {@link ConfigValidationError}.
+ * All three error messages include the config file path and a remediation
+ * hint naming `vaultkeeper config init --force` (via the separate
+ * `@vaultkeeper/cli` package) as well as the JS-API alternative of repairing
+ * or replacing the config directly — the supported recovery paths for an
+ * existing-but-broken config (issues #97, #100).
+ *
+ * @param configDir - Directory containing config.json. Defaults to
+ * `getDefaultConfigDir()`, which itself honors `VAULTKEEPER_CONFIG_DIR`
+ * before falling back to the platform-appropriate path.
+ * @public
+ */
+declare function loadConfig(configDir?: string): Promise<VaultConfig>;
 
-export { AuthorizationDeniedError, type BackendConfig, type BackendFactory, BackendLockedError, BackendRegistry, type BackendSetupFactory, BackendUnavailableError, CapabilityToken, DeviceNotPresentError, type ExecRequest, type ExecResult, type FetchRequest, FilesystemError, IdentityMismatchError, InvalidAlgorithmError, KeyRevokedError, KeyRotatedError, type KeyStatus, type ListableBackend, type Platform, PluginNotFoundError, type PreflightCheck, type PreflightCheckStatus, type PreflightResult, RotationInProgressError, type RunDoctorOptions, type SecretAccessor, type SecretBackend, SecretNotFoundError, type SetupChoice, SetupError, type SetupOptions, type SetupQuestion, type SetupResult, type SignRequest, type SignResult, TokenExpiredError, TokenRevokedError, type TrustTier, UsageLimitExceededError, type VaultConfig, VaultError, VaultKeeper, type VaultKeeperOptions, type VaultResponse, type VerifyRequest, isListableBackend, runDoctor };
+export { AccessorConsumedError, AuthorizationDeniedError, type BackendCapabilities, type BackendConfig, type BackendFactory, BackendLockedError, BackendRegistry, type BackendSetupFactory, BackendUnavailableError, CapabilityToken, ConfigParseError, ConfigValidationError, DecryptionError, DeviceNotPresentError, ExecError, type ExecRequest, type ExecResult, ExecutableTrustRequiredError, type ExecutableTrustStatus, FetchError, type FetchRequest, FilesystemError, IdentityMismatchError, InvalidAlgorithmError, InvalidKeyMaterialError, InvalidTokenError, KeyRevokedError, KeyRotatedError, type KeyStatus, type ListableBackend, NotCapableError, type Platform, PluginNotFoundError, type PreflightCheck, type PreflightCheckError, type PreflightCheckErrorKind, type PreflightCheckStatus, type PreflightResult, type PresenceCapableBackend, PresenceDeclinedError, type PresenceOperation, type PresenceRequirementOptions, PresenceTimeoutError, REDACTED, RotationInProgressError, type RunDoctorOptions, type ScopedPreflightCheck, type SecretAccessor, type SecretBackend, SecretNotFoundError, type SecretTokenMap, type SetupChoice, SetupError, type SetupOptions, type SetupOptionsBase, type SetupQuestion, type SetupResult, type SignRequest, type SignResult, type SigningAlgorithm, type SigningBackend, SigningKeyAlreadyExistsError, SigningKeyNotFoundError, SigningNotSupportedError, type SigningPublicKey, TokenExpiredError, TokenRevokedError, type TrustTier, UnknownBackendTypeError, UsageLimitExceededError, type VaultConfig, VaultError, VaultKeeper, type VaultKeeperOptions, type VaultResponse, type VerifyRequest, defaultBackendType, getBackendCapabilities, getDefaultConfigDir, getPlatformDefaultConfigDir, isListableBackend, isPresenceCapableBackend, isSigningBackend, loadConfig, platformNativeBackendType, redactSecrets, runDoctor };