vaultkeeper 0.5.3 → 0.7.0

package/dist/index.js

@@ -1,13 +1,14 @@
-import * as fs from 'fs/promises';
-import * as path3 from 'path';
+import * as fs3 from 'fs/promises';
+import * as path2 from 'path';
 import { join, dirname, resolve } from 'path';
-import * as os4 from 'os';
-import * as crypto from 'crypto';
+import * as os from 'os';
+import * as crypto2 from 'crypto';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
-import * as fs4 from 'fs';
+import * as fs6 from 'fs';
 import { existsSync, readFileSync } from 'fs';
-import { CompactEncrypt, compactDecrypt } from 'jose';
+import { CompactEncrypt, importSPKI, flattenedVerify, compactDecrypt } from 'jose';
+import { Buffer as Buffer$1 } from 'buffer';
 
 // src/errors.ts
 var VaultError = class extends Error {
@@ -46,6 +47,42 @@ var AuthorizationDeniedError = class extends VaultError {
     this.name = "AuthorizationDeniedError";
   }
 };
+var NotCapableError = class extends VaultError {
+  /** The `type` identifier of the active backend that lacked the capability. */
+  backendType;
+  /**
+   * The machine-readable capability key that was required but not advertised
+   * (e.g. `'presencePerUse'`).
+   */
+  capability;
+  constructor(message, backendType, capability) {
+    super(message);
+    this.name = "NotCapableError";
+    this.backendType = backendType;
+    this.capability = capability;
+  }
+};
+var PresenceDeclinedError = class extends VaultError {
+  /** The `type` identifier of the backend that requested the presence action. */
+  backendType;
+  constructor(message, backendType) {
+    super(message);
+    this.name = "PresenceDeclinedError";
+    this.backendType = backendType;
+  }
+};
+var PresenceTimeoutError = class extends VaultError {
+  /** The `type` identifier of the backend that requested the presence action. */
+  backendType;
+  /** How long (in milliseconds) the operation waited for the presence action. */
+  timeoutMs;
+  constructor(message, backendType, timeoutMs) {
+    super(message);
+    this.name = "PresenceTimeoutError";
+    this.backendType = backendType;
+    this.timeoutMs = timeoutMs;
+  }
+};
 var BackendUnavailableError = class extends VaultError {
   /**
    * Machine-readable reason code describing why the backend is unavailable
@@ -139,6 +176,46 @@ var IdentityMismatchError = class extends VaultError {
     this.currentHash = currentHash;
   }
 };
+var ExecutableTrustRequiredError = class 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`.
+   */
+  reason;
+  constructor(message, reason) {
+    super(message);
+    this.name = "ExecutableTrustRequiredError";
+    this.reason = reason;
+  }
+};
+var ExecError = class extends VaultError {
+  /**
+   * The command that failed to execute.
+   */
+  command;
+  constructor(message, command) {
+    super(message);
+    this.name = "ExecError";
+    this.command = command;
+  }
+};
+var InvalidTokenError = class extends VaultError {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidTokenError";
+  }
+};
+var AccessorConsumedError = class extends VaultError {
+  constructor(message) {
+    super(message);
+    this.name = "AccessorConsumedError";
+  }
+};
 var InvalidAlgorithmError = class extends VaultError {
   /**
    * The algorithm that was requested.
@@ -155,6 +232,139 @@ var InvalidAlgorithmError = class extends VaultError {
     this.allowed = allowed;
   }
 };
+var InvalidKeyMaterialError = class extends VaultError {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidKeyMaterialError";
+  }
+};
+var SigningKeyNotFoundError = class extends VaultError {
+  /**
+   * The signing-key name that was requested (the caller-facing `--name`, not
+   * the internal namespaced identifier).
+   */
+  keyName;
+  constructor(message, keyName) {
+    super(message);
+    this.name = "SigningKeyNotFoundError";
+    this.keyName = keyName;
+  }
+};
+var SigningKeyAlreadyExistsError = class extends VaultError {
+  /**
+   * The signing-key name that already exists (the caller-facing `--name`, not
+   * the internal namespaced identifier).
+   */
+  keyName;
+  constructor(message, keyName) {
+    super(message);
+    this.name = "SigningKeyAlreadyExistsError";
+    this.keyName = keyName;
+  }
+};
+var SigningNotSupportedError = class extends VaultError {
+  /** The type identifier of the active backend that cannot sign. */
+  backendType;
+  /**
+   * 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.
+   */
+  builtInSigningBackends;
+  constructor(message, backendType, builtInSigningBackends) {
+    super(message);
+    this.name = "SigningNotSupportedError";
+    this.backendType = backendType;
+    this.builtInSigningBackends = builtInSigningBackends;
+  }
+};
+var DecryptionError = class extends VaultError {
+  /**
+   * The path of the encrypted entry that failed to decrypt.
+   */
+  path;
+  constructor(message, path9) {
+    super(message);
+    this.name = "DecryptionError";
+    this.path = path9;
+  }
+};
+var FetchError = class 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.
+   */
+  url;
+  constructor(message, url) {
+    super(message);
+    this.name = "FetchError";
+    this.url = url;
+  }
+};
+var ConfigValidationError = class extends VaultError {
+  /**
+   * The dotted/bracketed path to the offending config field (e.g.
+   * `'backends[0].path'`).
+   */
+  field;
+  /**
+   * 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`).
+   */
+  configFilePath;
+  constructor(message, field, configFilePath) {
+    super(message);
+    this.name = "ConfigValidationError";
+    this.field = field;
+    this.configFilePath = configFilePath;
+  }
+};
+var UnknownBackendTypeError = class extends ConfigValidationError {
+  /** The unregistered backend type named in the config. */
+  backendType;
+  /**
+   * The backend type identifiers that were registered when validation ran —
+   * the valid options to offer in remediation.
+   */
+  knownTypes;
+  constructor(message, field, backendType, knownTypes, configFilePath) {
+    super(message, field, configFilePath);
+    this.name = "UnknownBackendTypeError";
+    this.backendType = backendType;
+    this.knownTypes = knownTypes;
+  }
+};
+var ConfigParseError = class 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`).
+   */
+  path;
+  /**
+   * A human-readable parse location (e.g. `'line 3, column 12'`), when one
+   * could be derived from the underlying `SyntaxError`.
+   */
+  location;
+  constructor(message, path9, location) {
+    super(message);
+    this.name = "ConfigParseError";
+    this.path = path9;
+    this.location = location;
+  }
+};
 var SetupError = class extends VaultError {
   /**
    * The name of the dependency that caused the setup failure.
@@ -168,24 +378,73 @@ var SetupError = class extends VaultError {
 };
 var FilesystemError = class 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`.
    */
   path;
   /**
-   * 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.
    */
   permission;
-  constructor(message, filePath, permission) {
+  /**
+   * 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.
+   */
+  code;
+  /**
+   * @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, filePath, permission, cause) {
     super(message);
     this.name = "FilesystemError";
     this.path = filePath;
     this.permission = permission;
+    this.code = hasErrnoCode(cause) ? cause.code : void 0;
+    if (cause !== void 0) {
+      Object.defineProperty(this, "cause", {
+        value: cause,
+        writable: true,
+        enumerable: false,
+        configurable: true
+      });
+    }
   }
 };
+function hasErrnoCode(err) {
+  return err instanceof Error && "code" in err && typeof err.code === "string";
+}
+function toFilesystemError(err, resourceLabel, filePath, permission) {
+  const detail = err instanceof Error ? err.message : String(err);
+  return new FilesystemError(
+    `Failed to ${permission} ${resourceLabel} at ${filePath}: ${detail}`,
+    filePath,
+    permission,
+    err
+  );
+}
 var RotationInProgressError = class extends VaultError {
   constructor(message) {
-    super(message);
+    const trimmed = message.trim();
+    const nextSteps = "Either wait for the current grace period to elapse before rotating again, or run 'vaultkeeper revoke-key' (or call revokeKey()) to invalidate the previous key immediately and clear the grace period.";
+    const prefix = trimmed.length === 0 ? "" : `${trimmed}${/[.!?]$/.test(trimmed) ? "" : "."} `;
+    super(`${prefix}${nextSteps}`);
     this.name = "RotationInProgressError";
   }
 };
@@ -206,10 +465,12 @@ var BackendRegistry = class {
    * 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, config) {
+  static create(type, config, configDir) {
     const factory = this.backends.get(type);
     if (factory === void 0) {
       throw new BackendUnavailableError(
@@ -218,7 +479,7 @@ var BackendRegistry = class {
         Array.from(this.backends.keys())
       );
     }
-    return factory(config);
+    return factory(config, configDir);
   }
   /**
    * Get all registered backend type identifiers.
@@ -295,161 +556,643 @@ var BackendRegistry = class {
     this.setups.clear();
   }
 };
-var STORAGE_DIR_NAME = path3.join(".vaultkeeper", "file");
-var KEY_FILE = ".key";
 var GCM_IV_BYTES = 12;
 var GCM_KEY_BYTES = 32;
-var GCM_TAG_LENGTH = 128;
-function getStorageDir() {
-  return path3.join(os4.homedir(), STORAGE_DIR_NAME);
+var GCM_TAG_LENGTH_BITS = 128;
+function encryptGcm(key, plaintext) {
+  const iv = crypto2.randomBytes(GCM_IV_BYTES);
+  const cipher = crypto2.createCipheriv("aes-256-gcm", key, iv, {
+    authTagLength: GCM_TAG_LENGTH_BITS / 8
+  });
+  const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+  return [iv.toString("base64"), authTag.toString("base64"), encrypted.toString("base64")].join(":");
 }
-function getEntryPath(storageDir, id) {
-  const safeId = Buffer.from(id, "utf8").toString("hex");
-  return path3.join(storageDir, `${safeId}.enc`);
+function decryptGcm(key, encoded, path9 = "") {
+  const parts = encoded.split(":");
+  if (parts.length !== 3) {
+    throw new DecryptionError("Invalid encrypted envelope: expected iv:authTag:ciphertext", path9);
+  }
+  const [ivB64, authTagB64, ciphertextB64] = parts;
+  if (ivB64 === void 0 || authTagB64 === void 0 || ciphertextB64 === void 0) {
+    throw new DecryptionError("Invalid encrypted envelope: missing part", path9);
+  }
+  const iv = Buffer.from(ivB64, "base64");
+  const authTag = Buffer.from(authTagB64, "base64");
+  const ciphertext = Buffer.from(ciphertextB64, "base64");
+  try {
+    const decipher = crypto2.createDecipheriv("aes-256-gcm", key, iv, {
+      authTagLength: GCM_TAG_LENGTH_BITS / 8
+    });
+    decipher.setAuthTag(authTag);
+    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return decrypted.toString("utf8");
+  } catch (err) {
+    throw new DecryptionError(
+      `Failed to decrypt envelope: ${err instanceof Error ? err.message : String(err)}`,
+      path9
+    );
+  }
 }
-async function ensureStorageDir(storageDir) {
+async function getOrCreateWrapKey(keyPath) {
+  let existing;
   try {
-    await fs.mkdir(storageDir, { recursive: true, mode: 448 });
+    existing = await fs3.readFile(keyPath);
   } catch (err) {
-    if (err instanceof Error && "code" in err && err.code !== "EEXIST") {
-      throw new FilesystemError(
-        `Failed to create storage directory: ${storageDir}`,
-        storageDir,
-        "rwx"
+    if (!(err instanceof Error && "code" in err && err.code === "ENOENT")) {
+      throw toFilesystemError(err, "wrapping key file", keyPath, "read");
+    }
+  }
+  if (existing?.byteLength === GCM_KEY_BYTES) {
+    return existing;
+  }
+  const key = crypto2.randomBytes(GCM_KEY_BYTES);
+  try {
+    await fs3.writeFile(keyPath, key, { mode: 384 });
+  } catch (err) {
+    throw toFilesystemError(err, "wrapping key file", keyPath, "write");
+  }
+  return key;
+}
+var CONFIG_REMEDIATION_HINT = `Fix the file \u2014 either install @vaultkeeper/cli and run 'vaultkeeper config init --force' to overwrite it with a valid config, or repair/replace it programmatically via this library (pass an explicit \`config\` or \`configDir\`, or write a valid config.json yourself).`;
+function hasErrorCode(err, code) {
+  return err instanceof Error && "code" in err && err.code === code;
+}
+function describeError(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function describeJsonSyntaxLocation(err, raw) {
+  const message = describeError(err);
+  const lineColMatch = /line (\d+) column (\d+)/.exec(message);
+  if (lineColMatch) {
+    return `line ${lineColMatch[1] ?? ""}, column ${lineColMatch[2] ?? ""}`;
+  }
+  const positionMatch = /position (\d+)/.exec(message);
+  if (positionMatch) {
+    const posStr = positionMatch[1];
+    const pos = posStr !== void 0 ? Number(posStr) : NaN;
+    if (!Number.isNaN(pos) && pos >= 0 && pos <= raw.length) {
+      const upToPos = raw.slice(0, pos);
+      const line = upToPos.split("\n").length;
+      const column = pos - upToPos.lastIndexOf("\n");
+      return `line ${String(line)}, column ${String(column)}`;
+    }
+  }
+  return void 0;
+}
+function getPlatformDefaultConfigDir() {
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA;
+    if (appData !== void 0) {
+      return path2.join(appData, "vaultkeeper");
+    }
+    return path2.join(os.homedir(), "AppData", "Roaming", "vaultkeeper");
+  }
+  return path2.join(os.homedir(), ".config", "vaultkeeper");
+}
+function getDefaultConfigDir() {
+  const envOverride = process.env.VAULTKEEPER_CONFIG_DIR;
+  if (envOverride !== void 0 && envOverride !== "") {
+    return envOverride;
+  }
+  return getPlatformDefaultConfigDir();
+}
+function defaultBackendType() {
+  return "file";
+}
+function platformNativeBackendType() {
+  if (process.platform === "darwin") {
+    return "keychain";
+  }
+  if (process.platform === "win32") {
+    return "dpapi";
+  }
+  if (process.platform === "linux") {
+    return "secret-tool";
+  }
+  return "file";
+}
+function defaultConfig() {
+  return {
+    version: 1,
+    backends: [{ type: defaultBackendType(), enabled: true }],
+    keyRotation: { gracePeriodDays: 7 },
+    defaults: { ttlMinutes: 60, trustTier: 3 }
+  };
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateBackendEntry(entry, index) {
+  const base = `backends[${String(index)}]`;
+  if (!isObject(entry)) {
+    throw new ConfigValidationError(`${base} must be an object`, base);
+  }
+  if (typeof entry.type !== "string" || entry.type.trim() === "") {
+    throw new ConfigValidationError(`${base}.type must be a non-empty string`, `${base}.type`);
+  }
+  const knownTypes = BackendRegistry.getTypes();
+  if (knownTypes.length > 0 && !knownTypes.includes(entry.type)) {
+    throw new UnknownBackendTypeError(
+      `${base}.type is an unknown backend type: "${entry.type}". Available types: ${knownTypes.join(", ")}`,
+      `${base}.type`,
+      entry.type,
+      knownTypes
+    );
+  }
+  if (typeof entry.enabled !== "boolean") {
+    throw new ConfigValidationError(`${base}.enabled must be a boolean`, `${base}.enabled`);
+  }
+  const result = {
+    type: entry.type,
+    enabled: entry.enabled
+  };
+  if (entry.plugin !== void 0) {
+    if (typeof entry.plugin !== "boolean") {
+      throw new ConfigValidationError(`${base}.plugin must be a boolean`, `${base}.plugin`);
+    }
+    result.plugin = entry.plugin;
+  }
+  if (entry.path !== void 0) {
+    if (typeof entry.path !== "string") {
+      throw new ConfigValidationError(`${base}.path must be a string`, `${base}.path`);
+    }
+    if (entry.path.trim() === "") {
+      throw new ConfigValidationError(
+        `${base}.path must not be empty or whitespace-only`,
+        `${base}.path`
       );
     }
+    result.path = entry.path;
+  }
+  if (entry.options !== void 0) {
+    if (!isObject(entry.options)) {
+      throw new ConfigValidationError(`${base}.options must be an object`, `${base}.options`);
+    }
+    const opts = {};
+    for (const [k, v] of Object.entries(entry.options)) {
+      if (typeof v !== "string") {
+        const quotedKey = JSON.stringify(k);
+        throw new ConfigValidationError(
+          `${base}.options[${quotedKey}] must be a string`,
+          `${base}.options[${quotedKey}]`
+        );
+      }
+      opts[k] = v;
+    }
+    result.options = opts;
   }
+  return result;
 }
-async function getOrCreateKey(storageDir) {
-  const keyPath = path3.join(storageDir, KEY_FILE);
+function validateConfig(config) {
+  if (!isObject(config)) {
+    throw new ConfigValidationError("Config must be an object", "config");
+  }
+  if (typeof config.version !== "number" || config.version !== 1) {
+    throw new ConfigValidationError("Config version must be 1", "version");
+  }
+  if (!Array.isArray(config.backends) || config.backends.length === 0) {
+    throw new ConfigValidationError("Config must have at least one backend", "backends");
+  }
+  const backends = config.backends.map(
+    (entry, i) => validateBackendEntry(entry, i)
+  );
+  if (!isObject(config.keyRotation)) {
+    throw new ConfigValidationError("Config keyRotation must be an object", "keyRotation");
+  }
+  if (typeof config.keyRotation.gracePeriodDays !== "number" || config.keyRotation.gracePeriodDays <= 0) {
+    throw new ConfigValidationError(
+      "Config keyRotation.gracePeriodDays must be a positive number",
+      "keyRotation.gracePeriodDays"
+    );
+  }
+  if (!isObject(config.defaults)) {
+    throw new ConfigValidationError("Config defaults must be an object", "defaults");
+  }
+  if (typeof config.defaults.ttlMinutes !== "number" || config.defaults.ttlMinutes <= 0) {
+    throw new ConfigValidationError(
+      "Config defaults.ttlMinutes must be a positive number",
+      "defaults.ttlMinutes"
+    );
+  }
+  let tier = config.defaults.trustTier;
+  if (typeof tier === "string") {
+    const parsed = Number(tier);
+    if (!Number.isNaN(parsed)) {
+      tier = parsed;
+    }
+  }
+  if (tier !== 1 && tier !== 2 && tier !== 3) {
+    throw new ConfigValidationError(
+      "Config defaults.trustTier must be 1, 2, or 3",
+      "defaults.trustTier"
+    );
+  }
+  const result = {
+    version: 1,
+    backends,
+    keyRotation: {
+      gracePeriodDays: config.keyRotation.gracePeriodDays
+    },
+    defaults: {
+      ttlMinutes: config.defaults.ttlMinutes,
+      trustTier: tier
+    }
+  };
+  if (config.developmentMode !== void 0) {
+    if (!isObject(config.developmentMode)) {
+      throw new ConfigValidationError("Config developmentMode must be an object", "developmentMode");
+    }
+    if (!Array.isArray(config.developmentMode.executables)) {
+      throw new ConfigValidationError(
+        "Config developmentMode.executables must be an array",
+        "developmentMode.executables"
+      );
+    }
+    const executables = [];
+    for (const [i, exe] of Array.from(config.developmentMode.executables).entries()) {
+      if (typeof exe !== "string") {
+        throw new ConfigValidationError(
+          `Config developmentMode.executables[${String(i)}] must be a string`,
+          `developmentMode.executables[${String(i)}]`
+        );
+      }
+      executables.push(exe);
+    }
+    result.developmentMode = { executables };
+  }
+  return result;
+}
+async function loadConfig(configDir) {
+  const dir = configDir ?? getDefaultConfigDir();
+  const configPath = path2.join(dir, "config.json");
+  let raw;
+  try {
+    raw = await fs3.readFile(configPath, "utf-8");
+  } catch (err) {
+    if (hasErrorCode(err, "ENOENT")) {
+      return defaultConfig();
+    }
+    throw new FilesystemError(
+      `Cannot read config file at ${configPath}: ${describeError(err)}. ${CONFIG_REMEDIATION_HINT}`,
+      configPath,
+      "read",
+      err
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    const location = describeJsonSyntaxLocation(err, raw);
+    const locationSuffix = location !== void 0 ? ` at ${location}` : "";
+    throw new ConfigParseError(
+      `Failed to parse config file at ${configPath}${locationSuffix}: ${describeError(err)}. ` + CONFIG_REMEDIATION_HINT,
+      configPath,
+      location
+    );
+  }
   try {
-    const data = await fs.readFile(keyPath);
-    return data;
+    return validateConfig(parsed);
   } catch (err) {
-    if (err instanceof Error && "code" in err && err.code === "ENOENT") {
-      const key = crypto.randomBytes(GCM_KEY_BYTES);
-      await fs.writeFile(keyPath, key, { mode: 384 });
-      return key;
+    if (err instanceof UnknownBackendTypeError) {
+      throw new UnknownBackendTypeError(
+        `Invalid config at ${configPath}: ${err.message}. ${CONFIG_REMEDIATION_HINT}`,
+        err.field,
+        err.backendType,
+        err.knownTypes,
+        configPath
+      );
+    }
+    if (err instanceof ConfigValidationError) {
+      throw new ConfigValidationError(
+        `Invalid config at ${configPath}: ${err.message}. ${CONFIG_REMEDIATION_HINT}`,
+        err.field,
+        configPath
+      );
     }
     throw err;
   }
 }
-function encryptGcm(key, plaintext) {
-  const iv = crypto.randomBytes(GCM_IV_BYTES);
-  const cipher = crypto.createCipheriv("aes-256-gcm", key, iv, {
-    authTagLength: GCM_TAG_LENGTH / 8
-  });
-  const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
-  const authTag = cipher.getAuthTag();
-  return [iv.toString("base64"), authTag.toString("base64"), encrypted.toString("base64")].join(":");
+
+// src/backend/file-backend.ts
+var STORAGE_DIR_NAME = "file";
+var KEY_FILE = ".key";
+var SIGNING_DIR_NAME = "signing-keys";
+var SIGNING_KEY_PREFIX = "signing-key:";
+var SUPPORTED_SIGNING_ALGORITHMS = ["EdDSA"];
+function computeKid(spkiDer) {
+  return crypto2.createHash("sha256").update(spkiDer).digest("base64url");
 }
-function decryptGcm(key, encoded) {
-  const parts = encoded.split(":");
-  if (parts.length !== 3) {
-    throw new Error("Invalid encrypted file format: expected iv:authTag:ciphertext");
+function displayKeyName(id) {
+  return id.startsWith(SIGNING_KEY_PREFIX) ? id.slice(SIGNING_KEY_PREFIX.length) : id;
+}
+function legacyStorageDir() {
+  return path2.join(os.homedir(), ".vaultkeeper", "file");
+}
+function resolveStorageDir(configuredPath, configDir) {
+  if (configuredPath !== void 0) {
+    return configuredPath;
   }
-  const [ivB64, authTagB64, ciphertextB64] = parts;
-  if (ivB64 === void 0 || authTagB64 === void 0 || ciphertextB64 === void 0) {
-    throw new Error("Invalid encrypted file format: missing part");
+  return path2.join(configDir ?? getDefaultConfigDir(), STORAGE_DIR_NAME);
+}
+function getEntryPath(storageDir, id) {
+  const safeId = Buffer.from(id, "utf8").toString("hex");
+  return path2.join(storageDir, `${safeId}.enc`);
+}
+async function ensureStorageDir(storageDir) {
+  try {
+    await fs3.mkdir(storageDir, { recursive: true, mode: 448 });
+  } catch (err) {
+    throw new FilesystemError(
+      `Failed to create storage directory: ${storageDir}`,
+      storageDir,
+      "rwx",
+      err
+    );
   }
-  const iv = Buffer.from(ivB64, "base64");
-  const authTag = Buffer.from(authTagB64, "base64");
-  const ciphertext = Buffer.from(ciphertextB64, "base64");
-  const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv, {
-    authTagLength: GCM_TAG_LENGTH / 8
-  });
-  decipher.setAuthTag(authTag);
-  const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
-  return decrypted.toString("utf8");
 }
-var FileBackend = class {
+async function getOrCreateKey(storageDir) {
+  return getOrCreateWrapKey(path2.join(storageDir, KEY_FILE));
+}
+var FileBackend = class _FileBackend {
   type = "file";
   displayName = "Encrypted File Store";
+  #storageDir;
+  /** Directory holding encrypted signing-key private material. */
+  #signingDir;
+  /**
+   * Pre-#99 default storage directory, consulted as a read-only fallback
+   * when `storageDir` was not explicitly configured. `undefined` when an
+   * explicit `storageDir` was given — an explicit path never falls back.
+   */
+  #legacyStorageDir;
+  /**
+   * @param storageDir - Directory in which encrypted secrets are stored.
+   *   Sourced from `BackendConfig.path`. Defaults to `<configDir>/file`.
+   * @param configDir - Resolved config directory, used to compute the
+   *   default `storageDir` when one is not explicitly provided. Ignored when
+   *   `storageDir` is given. Defaults to `getDefaultConfigDir()`.
+   */
+  constructor(storageDir, configDir) {
+    this.#storageDir = resolveStorageDir(storageDir, configDir);
+    this.#legacyStorageDir = storageDir === void 0 ? legacyStorageDir() : void 0;
+    this.#signingDir = path2.join(this.#storageDir, SIGNING_DIR_NAME);
+  }
   async isAvailable() {
     try {
-      const storageDir = getStorageDir();
-      await ensureStorageDir(storageDir);
+      await ensureStorageDir(this.#storageDir);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async store(id, secret) {
+    const storageDir = this.#storageDir;
+    await ensureStorageDir(storageDir);
+    const key = await getOrCreateKey(storageDir);
+    const entryPath = getEntryPath(storageDir, id);
+    const encrypted = encryptGcm(key, secret);
+    try {
+      await fs3.writeFile(entryPath, encrypted, { mode: 384 });
+    } catch (err) {
+      throw toFilesystemError(err, "secret file", entryPath, "write");
+    }
+  }
+  /**
+   * Attempt to read and decrypt the entry for `id` from `storageDir`.
+   * Returns `undefined` (rather than throwing) when the entry does not
+   * exist in `storageDir`, so callers can probe a fallback location.
+   */
+  async #tryRetrieveFrom(storageDir, id) {
+    const entryPath = getEntryPath(storageDir, id);
+    let encoded;
+    try {
+      encoded = await fs3.readFile(entryPath, "utf8");
+    } catch (err) {
+      if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+        return void 0;
+      }
+      throw toFilesystemError(err, "secret file", entryPath, "read");
+    }
+    const key = await getOrCreateKey(storageDir);
+    try {
+      return decryptGcm(key, encoded, entryPath);
+    } catch (err) {
+      throw new DecryptionError(
+        `Failed to decrypt secret: ${err instanceof Error ? err.message : String(err)}`,
+        entryPath
+      );
+    }
+  }
+  async retrieve(id) {
+    const fromPrimary = await this.#tryRetrieveFrom(this.#storageDir, id);
+    if (fromPrimary !== void 0) {
+      return fromPrimary;
+    }
+    if (this.#legacyStorageDir !== void 0) {
+      const fromLegacy = await this.#tryRetrieveFrom(this.#legacyStorageDir, id);
+      if (fromLegacy !== void 0) {
+        return fromLegacy;
+      }
+    }
+    throw new SecretNotFoundError(`Secret not found in file store: ${id}`);
+  }
+  async delete(id) {
+    const entryPath = getEntryPath(this.#storageDir, id);
+    try {
+      await fs3.unlink(entryPath);
+      return;
+    } catch (err) {
+      if (!(err instanceof Error && "code" in err && err.code === "ENOENT")) {
+        throw toFilesystemError(err, "secret file", entryPath, "delete");
+      }
+    }
+    if (this.#legacyStorageDir !== void 0) {
+      const legacyEntryPath = getEntryPath(this.#legacyStorageDir, id);
+      try {
+        await fs3.unlink(legacyEntryPath);
+        return;
+      } catch (err) {
+        if (!(err instanceof Error && "code" in err && err.code === "ENOENT")) {
+          throw toFilesystemError(err, "secret file", legacyEntryPath, "delete");
+        }
+      }
+    }
+    throw new SecretNotFoundError(`Secret not found in file store: ${id}`);
+  }
+  async exists(id) {
+    if (await _FileBackend.#entryExists(this.#storageDir, id)) {
+      return true;
+    }
+    if (this.#legacyStorageDir !== void 0) {
+      return _FileBackend.#entryExists(this.#legacyStorageDir, id);
+    }
+    return false;
+  }
+  static async #entryExists(storageDir, id) {
+    try {
+      await fs3.access(getEntryPath(storageDir, id));
       return true;
     } catch {
       return false;
     }
   }
-  async store(id, secret) {
-    const storageDir = getStorageDir();
-    await ensureStorageDir(storageDir);
-    const key = await getOrCreateKey(storageDir);
-    const entryPath = getEntryPath(storageDir, id);
-    const encrypted = encryptGcm(key, secret);
-    await fs.writeFile(entryPath, encrypted, { mode: 384 });
+  async list() {
+    const ids = /* @__PURE__ */ new Set();
+    for (const storageDir of [this.#storageDir, this.#legacyStorageDir].filter(
+      (dir) => dir !== void 0
+    )) {
+      for (const id of await _FileBackend.#listEntries(storageDir)) {
+        ids.add(id);
+      }
+    }
+    return Array.from(ids);
   }
-  async retrieve(id) {
-    const storageDir = getStorageDir();
-    const entryPath = getEntryPath(storageDir, id);
+  static async #listEntries(storageDir) {
+    let entries;
+    try {
+      entries = await fs3.readdir(storageDir);
+    } catch {
+      return [];
+    }
+    return entries.filter((f) => f.endsWith(".enc")).map((f) => Buffer.from(f.slice(0, -4), "hex").toString("utf8"));
+  }
+  // --- Signing contract (SigningBackend) ---
+  /** On-disk path of the encrypted private key for a signing-key id. */
+  #signingKeyPath(id) {
+    const safeId = Buffer.from(id, "utf8").toString("hex");
+    return path2.join(this.#signingDir, `${safeId}.pem.enc`);
+  }
+  /**
+   * Load and decrypt the PKCS#8 private key PEM for `id`, or throw
+   * {@link SigningKeyNotFoundError} when no signing key exists under `id`.
+   */
+  async #loadSigningKeyPem(id) {
+    const keyPath = this.#signingKeyPath(id);
     let encoded;
     try {
-      encoded = await fs.readFile(entryPath, "utf8");
+      encoded = await fs3.readFile(keyPath, "utf8");
     } catch (err) {
       if (err instanceof Error && "code" in err && err.code === "ENOENT") {
-        throw new SecretNotFoundError(`Secret not found in file store: ${id}`);
+        throw new SigningKeyNotFoundError(
+          `Signing key not found: ${displayKeyName(id)}`,
+          displayKeyName(id)
+        );
       }
-      throw err;
+      throw toFilesystemError(err, "signing key", keyPath, "read");
     }
-    const key = await getOrCreateKey(storageDir);
+    const wrapKey = await getOrCreateKey(this.#storageDir);
     try {
-      return decryptGcm(key, encoded);
+      return decryptGcm(wrapKey, encoded);
     } catch (err) {
-      throw new Error(
-        `Failed to decrypt secret: ${err instanceof Error ? err.message : String(err)}`
+      throw new DecryptionError(
+        `Failed to decrypt signing key: ${err instanceof Error ? err.message : String(err)}`,
+        keyPath
       );
     }
   }
-  async delete(id) {
-    const storageDir = getStorageDir();
-    const entryPath = getEntryPath(storageDir, id);
+  async generateSigningKey(id, algorithm) {
+    if (!SUPPORTED_SIGNING_ALGORITHMS.includes(algorithm)) {
+      throw new InvalidAlgorithmError(
+        `Unsupported signing algorithm '${algorithm}'. Supported: ${SUPPORTED_SIGNING_ALGORITHMS.join(", ")}.`,
+        algorithm,
+        [...SUPPORTED_SIGNING_ALGORITHMS]
+      );
+    }
+    await ensureStorageDir(this.#storageDir);
     try {
-      await fs.unlink(entryPath);
+      await fs3.mkdir(this.#signingDir, { recursive: true, mode: 448 });
     } catch (err) {
-      if (err instanceof Error && "code" in err && err.code === "ENOENT") {
-        throw new SecretNotFoundError(`Secret not found in file store: ${id}`);
+      if (err instanceof Error && "code" in err && err.code !== "EEXIST") {
+        throw toFilesystemError(err, "signing-key directory", this.#signingDir, "create");
       }
-      throw err;
     }
-  }
-  async exists(id) {
-    const storageDir = getStorageDir();
-    const entryPath = getEntryPath(storageDir, id);
+    const keyPath = this.#signingKeyPath(id);
+    let keyExists = false;
     try {
-      await fs.access(entryPath);
-      return true;
-    } catch {
-      return false;
+      await fs3.access(keyPath);
+      keyExists = true;
+    } catch (err) {
+      if (!(err instanceof Error && "code" in err && err.code === "ENOENT")) {
+        throw toFilesystemError(err, "signing key", keyPath, "read");
+      }
+    }
+    if (keyExists) {
+      throw new SigningKeyAlreadyExistsError(
+        `Signing key already exists: ${displayKeyName(id)}`,
+        displayKeyName(id)
+      );
+    }
+    const { privateKey } = crypto2.generateKeyPairSync("ed25519");
+    const pkcs8Pem = privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+    const wrapKey = await getOrCreateKey(this.#storageDir);
+    const encrypted = encryptGcm(wrapKey, pkcs8Pem);
+    try {
+      await fs3.writeFile(keyPath, encrypted, { mode: 384, flag: "wx" });
+    } catch (err) {
+      if (err instanceof Error && "code" in err && err.code === "EEXIST") {
+        throw new SigningKeyAlreadyExistsError(
+          `Signing key already exists: ${displayKeyName(id)}`,
+          displayKeyName(id)
+        );
+      }
+      throw toFilesystemError(err, "signing key", keyPath, "write");
     }
   }
-  async list() {
-    const storageDir = getStorageDir();
-    let entries;
+  /**
+   * Load, decrypt, and parse the private key for `id` into a `KeyObject`.
+   *
+   * A parse failure means the decrypted-at-rest material is corrupt or tampered
+   * (it decrypted cleanly but is not a valid PKCS#8 private key). It is
+   * translated into a typed {@link InvalidKeyMaterialError} — never allowed to
+   * surface as a raw Node crypto exception — and the message never echoes any
+   * part of the key material.
+   */
+  async #loadSigningKeyObject(id) {
+    const pkcs8Pem = await this.#loadSigningKeyPem(id);
     try {
-      entries = await fs.readdir(storageDir);
+      return crypto2.createPrivateKey(pkcs8Pem);
     } catch {
-      return [];
+      throw new InvalidKeyMaterialError(
+        `The stored signing key for "${displayKeyName(id)}" is not valid private key material (it may be corrupt or tampered).`
+      );
     }
-    return entries.filter((f) => f.endsWith(".enc")).map((f) => Buffer.from(f.slice(0, -4), "hex").toString("utf8"));
+  }
+  async getPublicKey(id) {
+    const privateKey = await this.#loadSigningKeyObject(id);
+    const publicKey = crypto2.createPublicKey(privateKey);
+    const publicKeyPem = publicKey.export({ type: "spki", format: "pem" }).toString();
+    const spkiDer = publicKey.export({ type: "spki", format: "der" });
+    return {
+      publicKeyPem,
+      algorithm: "EdDSA",
+      kid: computeKid(spkiDer)
+    };
+  }
+  async signWithKey(id, data) {
+    const privateKey = await this.#loadSigningKeyObject(id);
+    return crypto2.sign(null, data, privateKey);
   }
 };
 async function execCommand(command, args, options) {
   const result = await execCommandFull(command, args, options);
   if (result.exitCode !== 0) {
-    throw new Error(`Command failed with exit code ${String(result.exitCode)}: ${result.stderr}`);
+    throw new ExecError(
+      `Command failed with exit code ${String(result.exitCode)}: ${result.stderr}`,
+      command
+    );
   }
   return result.stdout.trim();
 }
 function execCommandFull(command, args, options) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const proc = spawn(command, args, {
       stdio: [options?.stdin !== void 0 ? "pipe" : "ignore", "pipe", "pipe"]
     });
     let stdout = "";
     let stderr = "";
+    let timeoutHandle;
     proc.stdout?.on("data", (data) => {
       stdout += data.toString();
     });
@@ -461,16 +1204,33 @@ function execCommandFull(command, args, options) {
       proc.stdin.end();
     }
     if (options?.timeoutMs !== void 0) {
-      setTimeout(() => {
+      timeoutHandle = setTimeout(() => {
+        timeoutHandle = void 0;
         proc.kill("SIGTERM");
-        reject(new Error(`Command timed out after ${String(options.timeoutMs)}ms`));
+        reject(new ExecError(`Command timed out after ${String(options.timeoutMs)}ms`, command));
       }, options.timeoutMs);
     }
     proc.on("close", (code) => {
-      resolve2({ stdout, stderr, exitCode: code ?? 1 });
+      if (timeoutHandle !== void 0) {
+        clearTimeout(timeoutHandle);
+      }
+      resolve3({ stdout, stderr, exitCode: code ?? 1 });
     });
     proc.on("error", (error) => {
-      reject(error);
+      if (timeoutHandle !== void 0) {
+        clearTimeout(timeoutHandle);
+      }
+      if ("code" in error && error.code === "ENOENT") {
+        reject(
+          new PluginNotFoundError(
+            `'${command}' is not installed or not found in PATH`,
+            command,
+            ""
+          )
+        );
+      } else {
+        reject(new ExecError(`Failed to spawn '${command}': ${error.message}`, command));
+      }
     });
   });
 }
@@ -495,13 +1255,7 @@ var KeychainBackend = class {
   async store(id, secret) {
     const service = `${SERVICE_PREFIX}${id}`;
     const encoded = Buffer.from(secret, "utf8").toString("base64");
-    await execCommandFull("security", [
-      "delete-generic-password",
-      "-a",
-      ACCOUNT,
-      "-s",
-      service
-    ]);
+    await execCommandFull("security", ["delete-generic-password", "-a", ACCOUNT, "-s", service]);
     await execCommand("security", [
       "add-generic-password",
       "-a",
@@ -553,9 +1307,7 @@ var KeychainBackend = class {
     return result.exitCode === 0;
   }
   async list() {
-    const result = await execCommandFull("security", [
-      "dump-keychain"
-    ]);
+    const result = await execCommandFull("security", ["dump-keychain"]);
     if (result.exitCode !== 0) {
       return [];
     }
@@ -572,16 +1324,27 @@ var KeychainBackend = class {
     return ids;
   }
 };
-function getStoragePath() {
-  return path3.join(os4.homedir(), ".vaultkeeper", "dpapi");
+function resolveStorageDir2(configuredPath) {
+  if (configuredPath !== void 0) {
+    return configuredPath;
+  }
+  return path2.join(os.homedir(), ".vaultkeeper", "dpapi");
 }
 function getEntryPath2(storageDir, id) {
   const safeId = Buffer.from(id, "utf8").toString("hex");
-  return path3.join(storageDir, `${safeId}.enc`);
+  return path2.join(storageDir, `${safeId}.enc`);
 }
 var DpapiBackend = class {
   type = "dpapi";
   displayName = "Windows DPAPI";
+  #storageDir;
+  /**
+   * @param storageDir - Directory in which encrypted blobs are stored.
+   *   Sourced from `BackendConfig.path`. Defaults to `$HOME/.vaultkeeper/dpapi`.
+   */
+  constructor(storageDir) {
+    this.#storageDir = resolveStorageDir2(storageDir);
+  }
   async isAvailable() {
     if (process.platform !== "win32") {
       return false;
@@ -598,8 +1361,8 @@ var DpapiBackend = class {
     }
   }
   async store(id, secret) {
-    const storageDir = getStoragePath();
-    await fs.mkdir(storageDir, { recursive: true });
+    const storageDir = this.#storageDir;
+    await fs3.mkdir(storageDir, { recursive: true });
     const entryPath = getEntryPath2(storageDir, id);
     const script = [
       "Add-Type -AssemblyName System.Security",
@@ -612,10 +1375,10 @@ var DpapiBackend = class {
     await execCommand("powershell", ["-NoProfile", "-Command", script]);
   }
   async retrieve(id) {
-    const storageDir = getStoragePath();
+    const storageDir = this.#storageDir;
     const entryPath = getEntryPath2(storageDir, id);
     try {
-      await fs.access(entryPath);
+      await fs3.access(entryPath);
     } catch {
       throw new SecretNotFoundError(`Secret not found in Windows DPAPI store: ${id}`);
     }
@@ -630,32 +1393,32 @@ var DpapiBackend = class {
     return execCommand("powershell", ["-NoProfile", "-Command", script]);
   }
   async delete(id) {
-    const storageDir = getStoragePath();
+    const storageDir = this.#storageDir;
     const entryPath = getEntryPath2(storageDir, id);
     try {
-      await fs.unlink(entryPath);
+      await fs3.unlink(entryPath);
     } catch (err) {
       if (err instanceof Error && "code" in err && err.code === "ENOENT") {
         throw new SecretNotFoundError(`Secret not found in Windows DPAPI store: ${id}`);
       }
-      throw err;
+      throw toFilesystemError(err, "secret file", entryPath, "delete");
     }
   }
   async exists(id) {
-    const storageDir = getStoragePath();
+    const storageDir = this.#storageDir;
     const entryPath = getEntryPath2(storageDir, id);
     try {
-      await fs.access(entryPath);
+      await fs3.access(entryPath);
       return true;
     } catch {
       return false;
     }
   }
   async list() {
-    const storageDir = getStoragePath();
+    const storageDir = this.#storageDir;
     let entries;
     try {
-      entries = await fs.readdir(storageDir);
+      entries = await fs3.readdir(storageDir);
     } catch {
       return [];
     }
@@ -682,11 +1445,9 @@ var SecretToolBackend = class {
   }
   async store(id, secret) {
     const label = `${LABEL_PREFIX}${id}`;
-    await execCommand(
-      "secret-tool",
-      ["store", "--label", label, ATTRIBUTE_KEY, id],
-      { stdin: secret }
-    );
+    await execCommand("secret-tool", ["store", "--label", label, ATTRIBUTE_KEY, id], {
+      stdin: secret
+    });
   }
   async retrieve(id) {
     const result = await execCommandFull("secret-tool", ["lookup", ATTRIBUTE_KEY, id]);
@@ -706,11 +1467,7 @@ var SecretToolBackend = class {
     return result.exitCode === 0 && result.stdout.trim() !== "";
   }
   async list() {
-    const result = await execCommandFull("secret-tool", [
-      "search",
-      ATTRIBUTE_KEY,
-      ""
-    ]);
+    const result = await execCommandFull("secret-tool", ["search", ATTRIBUTE_KEY, ""]);
     if (result.exitCode !== 0) {
       return [];
     }
@@ -727,15 +1484,95 @@ var SecretToolBackend = class {
     return ids;
   }
 };
+
+// src/backend/one-password-item-ops.ts
+var TAG = "vaultkeeper";
+var PASSWORD_FIELD_TITLE = "password";
+async function findItemOverviewByTitle(client, vaultId, title) {
+  const overviews = await client.items.list(vaultId);
+  for (const overview of overviews) {
+    if (overview.title === title && overview.tags.includes(TAG)) {
+      return overview;
+    }
+  }
+  return void 0;
+}
+async function findItemByTitle(client, vaultId, title) {
+  const overview = await findItemOverviewByTitle(client, vaultId, title);
+  if (overview === void 0) return void 0;
+  return client.items.get(vaultId, overview.id);
+}
+function extractPasswordField(item) {
+  for (const field of item.fields) {
+    if (field.title === PASSWORD_FIELD_TITLE) {
+      return field.value;
+    }
+  }
+  return void 0;
+}
+async function storeSecretItem(client, vaultId, title, secret, passwordCategory, concealedFieldType) {
+  const existing = await findItemByTitle(client, vaultId, title);
+  if (existing !== void 0) {
+    const hasPasswordField = existing.fields.some((f) => f.title === PASSWORD_FIELD_TITLE);
+    const updatedFields = hasPasswordField ? existing.fields.map((f) => f.title === PASSWORD_FIELD_TITLE ? { ...f, value: secret } : f) : [
+      ...existing.fields,
+      {
+        id: "password",
+        title: PASSWORD_FIELD_TITLE,
+        fieldType: concealedFieldType,
+        value: secret
+      }
+    ];
+    await client.items.put({ ...existing, fields: updatedFields });
+  } else {
+    await client.items.create({
+      category: passwordCategory,
+      vaultId,
+      title,
+      tags: [TAG],
+      fields: [
+        {
+          id: "password",
+          title: PASSWORD_FIELD_TITLE,
+          fieldType: concealedFieldType,
+          value: secret
+        }
+      ]
+    });
+  }
+}
+async function deleteSecretItem(client, vaultId, title) {
+  const overview = await findItemOverviewByTitle(client, vaultId, title);
+  if (overview === void 0) return false;
+  await client.items.delete(vaultId, overview.id);
+  return true;
+}
 var INTEGRATION_NAME = "vaultkeeper";
+var SDK_PACKAGE = "@1password/sdk";
+var SDK_INSTALL_URL = "https://developer.1password.com/docs/sdks/";
+var SDK_NOT_INSTALLED_MESSAGE = `1Password SDK (${SDK_PACKAGE}) is not installed. Install it to use the 1Password backend.`;
+var PRESENCE_WRITE_TIMEOUT_MS = 3e4;
+function isModuleNotFoundError(error) {
+  const hasNotFoundCode = (value) => {
+    if (value === null || typeof value !== "object" || !("code" in value)) {
+      return false;
+    }
+    const { code } = value;
+    return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
+  };
+  if (hasNotFoundCode(error)) {
+    return true;
+  }
+  if (error !== null && typeof error === "object" && "cause" in error) {
+    return hasNotFoundCode(error.cause);
+  }
+  return false;
+}
 var cachedVersion;
 function getIntegrationVersion() {
   if (cachedVersion !== void 0) return cachedVersion;
   const dir = dirname(fileURLToPath(import.meta.url));
-  const candidates = [
-    resolve(dir, "..", "..", "package.json"),
-    resolve(dir, "..", "package.json")
-  ];
+  const candidates = [resolve(dir, "..", "..", "package.json"), resolve(dir, "..", "package.json")];
   for (const candidate of candidates) {
     if (!existsSync(candidate)) continue;
     const raw = JSON.parse(readFileSync(candidate, "utf8"));
@@ -744,15 +1581,13 @@ function getIntegrationVersion() {
       return cachedVersion;
     }
   }
-  throw new Error(
-    `Could not read version from vaultkeeper package.json. Tried paths: ${candidates.join(", ")}`
+  throw new SetupError(
+    `Could not read version from vaultkeeper package.json. Tried paths: ${candidates.join(", ")}`,
+    "vaultkeeper package.json"
   );
 }
 
 // src/backend/one-password-backend.ts
-var SDK_INSTALL_URL = "https://developer.1password.com/docs/sdks/";
-var TAG = "vaultkeeper";
-var PASSWORD_FIELD_TITLE = "password";
 var SESSION_TIMEOUT_MS = 3e4;
 function isWorkerSuccess(res) {
   return "value" in res;
@@ -764,6 +1599,17 @@ function isWorkerResponse(value) {
     return true;
   return false;
 }
+function isWorkerWriteSuccess(res) {
+  const record = { ...res };
+  return record.ok === true;
+}
+function isWorkerWriteResponse(value) {
+  if (value === null || typeof value !== "object") return false;
+  if ("ok" in value && value.ok === true) return true;
+  if ("error" in value && typeof value.error === "string" && "code" in value && typeof value.code === "string")
+    return true;
+  return false;
+}
 var OnePasswordBackend = class {
   type = "1password";
   displayName = "1Password";
@@ -776,13 +1622,15 @@ var OnePasswordBackend = class {
   clientPromise;
   constructor(options) {
     if (options.accessMode === "per-access" && options.serviceAccountToken !== void 0) {
-      throw new Error(
-        "per-access mode requires desktop biometric authentication and cannot be used with a service account token"
+      throw new ConfigValidationError(
+        "per-access mode requires desktop biometric authentication and cannot be used with a service account token",
+        "options.accessMode"
       );
     }
     if (options.account !== void 0 && options.serviceAccountToken !== void 0) {
-      throw new Error(
-        "account and serviceAccountToken are mutually exclusive \u2014 provide one or the other, not both"
+      throw new ConfigValidationError(
+        "account and serviceAccountToken are mutually exclusive \u2014 provide one or the other, not both",
+        "options.serviceAccountToken"
       );
     }
     this.vaultId = options.vault;
@@ -799,10 +1647,50 @@ var OnePasswordBackend = class {
     const sdk = await this.tryLoadSdk();
     return sdk !== null;
   }
+  /**
+   * Report this instance's capabilities.
+   *
+   * @remarks
+   * `presencePerUse` is `true` only in `per-access` mode, where every keyed
+   * operation (`retrieve()`, `store()`, `delete()`) spawns a fresh worker
+   * process that creates a new SDK client and triggers a per-operation
+   * biometric approval that cannot be satisfied from the cached session
+   * client. In the default `session` mode a single client is cached for all
+   * operations, so operations ride one earlier unlock — that mode reports
+   * `false`.
+   *
+   * **Operation coverage:** the per-access biometric path gates `retrieve()`,
+   * `store()`, and `delete()` — every keyed operation reachable from
+   * `presenceEnforcedOperations`. `exists()`/`list()` are read-only probes,
+   * not keyed operations the presence contract covers, so they continue to
+   * use the cached session client. This reports
+   * `presenceEnforcedOperations: ['read', 'store', 'delete']` (issue #211
+   * closed the earlier `store`/`delete` gap — see
+   * {@link https://github.com/mike-north/vaultkeeper/issues/211}).
+   *
+   * **Truth-basis / cached-OS-unlock caveat:** even for a covered operation
+   * the fresh action is "a fresh SDK client plus whatever the OS enforces at
+   * that moment" — a "fresh process/SDK client" is **not** the same as a
+   * guaranteed fresh hardware action. A per-access call can still ride a
+   * cached OS-level Touch ID / Windows Hello unlock if the OS does not
+   * re-prompt. The strongest per-use hardware guarantee comes from a touch
+   * device (YubiKey / gpg smartcard).
+   */
+  getCapabilities() {
+    if (this.accessMode === "per-access") {
+      return Promise.resolve({
+        presencePerUse: true,
+        presenceEnforcedOperations: ["read", "store", "delete"]
+      });
+    }
+    return Promise.resolve({ presencePerUse: false });
+  }
   // ---- Session client management ----
   /**
    * Dynamically import the SDK. Returns `null` if the SDK is not installed or
-   * the native library cannot be loaded.
+   * the native library cannot be loaded. Used by {@link isAvailable}, which
+   * only needs a yes/no answer; call {@link loadSdkOrThrow} on paths that must
+   * report *why* the SDK could not be loaded.
    */
   async tryLoadSdk() {
     try {
@@ -812,6 +1700,23 @@ var OnePasswordBackend = class {
       return null;
     }
   }
+  /**
+   * Dynamically import the SDK, throwing a typed {@link PluginNotFoundError}
+   * only when the module cannot be resolved (the optional peer is not
+   * installed). A present-but-broken SDK (native binding failure, init throw,
+   * incompatible Node) surfaces its real error instead of a misleading
+   * "not installed" message.
+   */
+  async loadSdkOrThrow() {
+    try {
+      return await import('@1password/sdk');
+    } catch (error) {
+      if (isModuleNotFoundError(error)) {
+        throw new PluginNotFoundError(SDK_NOT_INSTALLED_MESSAGE, SDK_PACKAGE, SDK_INSTALL_URL);
+      }
+      throw error;
+    }
+  }
   /**
    * Acquire (or create) a cached SDK client.
    * Wraps `createClient` with a configurable timeout (default 30 s) to handle
@@ -825,19 +1730,14 @@ var OnePasswordBackend = class {
     return this.clientPromise;
   }
   async createClientInternal() {
-    const sdk = await this.tryLoadSdk();
-    if (sdk === null) {
-      throw new PluginNotFoundError(
-        "1Password SDK (@1password/sdk) is not available. Install it to use this backend.",
-        "@1password/sdk",
-        SDK_INSTALL_URL
-      );
-    }
+    const sdk = await this.loadSdkOrThrow();
     const auth = this.buildAuth(sdk);
     let timerId;
     const timeoutPromise = new Promise((_resolve, reject) => {
       timerId = setTimeout(() => {
-        reject(new BackendLockedError("1Password session timed out waiting for authentication", true));
+        reject(
+          new BackendLockedError("1Password session timed out waiting for authentication", true)
+        );
       }, this.sessionTimeoutMs);
     });
     try {
@@ -855,14 +1755,9 @@ var OnePasswordBackend = class {
         throw err;
       }
       if (err instanceof sdk.DesktopSessionExpiredError) {
-        throw new BackendLockedError(
-          "1Password session has expired. Please unlock the app.",
-          true
-        );
+        throw new BackendLockedError("1Password session has expired. Please unlock the app.", true);
       }
-      throw new AuthorizationDeniedError(
-        `1Password authentication failed: ${String(err)}`
-      );
+      throw new AuthorizationDeniedError(`1Password authentication failed: ${String(err)}`);
     } finally {
       if (timerId !== void 0) {
         clearTimeout(timerId);
@@ -876,79 +1771,21 @@ var OnePasswordBackend = class {
     const accountName = this.account ?? "";
     return new sdk.DesktopAuth(accountName);
   }
-  // ---- Helpers for item lookup by title ----
-  /**
-   * List all items in the vault tagged "vaultkeeper" and find one with the
-   * matching title (= secret ID). Returns `undefined` if not found.
-   */
-  async findItemOverview(client, id) {
-    const overviews = await client.items.list(this.vaultId);
-    for (const overview of overviews) {
-      if (overview.title === id && overview.tags.includes(TAG)) {
-        return overview;
-      }
-    }
-    return void 0;
-  }
-  /**
-   * Fetch the full item for a given secret id. Returns `undefined` if not found.
-   */
-  async findItem(client, id) {
-    const overview = await this.findItemOverview(client, id);
-    if (overview === void 0) return void 0;
-    return client.items.get(this.vaultId, overview.id);
-  }
-  /**
-   * Extract the concealed password field value from an item.
-   */
-  extractSecret(item, id) {
-    for (const field of item.fields) {
-      if (field.title === PASSWORD_FIELD_TITLE) {
-        return field.value;
-      }
-    }
-    throw new SecretNotFoundError(
-      `Secret found in 1Password but missing password field: ${id}`
-    );
-  }
   // ---- SecretBackend / ListableBackend implementation ----
   async store(id, secret) {
+    if (this.accessMode === "per-access") {
+      return this.writeViaWorker("store", id, secret);
+    }
     const { ItemCategory, ItemFieldType } = await this.requireSdk();
     const client = await this.acquireClient();
-    const existing = await this.findItem(client, id);
-    if (existing !== void 0) {
-      const hasPasswordField = existing.fields.some((f) => f.title === PASSWORD_FIELD_TITLE);
-      const updatedFields = hasPasswordField ? existing.fields.map((f) => {
-        if (f.title === PASSWORD_FIELD_TITLE) {
-          return { ...f, value: secret };
-        }
-        return f;
-      }) : [
-        ...existing.fields,
-        {
-          id: "password",
-          title: PASSWORD_FIELD_TITLE,
-          fieldType: ItemFieldType.Concealed,
-          value: secret
-        }
-      ];
-      await client.items.put({ ...existing, fields: updatedFields });
-    } else {
-      await client.items.create({
-        category: ItemCategory.Password,
-        vaultId: this.vaultId,
-        title: id,
-        tags: [TAG],
-        fields: [
-          {
-            id: "password",
-            title: PASSWORD_FIELD_TITLE,
-            fieldType: ItemFieldType.Concealed,
-            value: secret
-          }
-        ]
-      });
-    }
+    await storeSecretItem(
+      client,
+      this.vaultId,
+      id,
+      secret,
+      ItemCategory.Password,
+      ItemFieldType.Concealed
+    );
   }
   async retrieve(id) {
     if (this.accessMode === "per-access") {
@@ -958,28 +1795,27 @@ var OnePasswordBackend = class {
   }
   async retrieveViaSession(id) {
     const client = await this.acquireClient();
-    const item = await this.findItem(client, id);
+    const item = await findItemByTitle(client, this.vaultId, id);
     if (item === void 0) {
       throw new SecretNotFoundError(`Secret not found in 1Password: ${id}`);
     }
-    return this.extractSecret(item, id);
+    const value = extractPasswordField(item);
+    if (value === void 0) {
+      throw new SecretNotFoundError(`Secret found in 1Password but missing password field: ${id}`);
+    }
+    return value;
   }
   /**
    * Spawn the per-access worker script that triggers a fresh biometric prompt
    * for each retrieval, then returns the secret from its stdout.
    */
   retrieveViaWorker(id) {
-    return new Promise((resolve2, reject) => {
-      const workerPath = join(
-        dirname(fileURLToPath(import.meta.url)),
-        "one-password-worker.js"
-      );
+    return new Promise((resolve3, reject) => {
+      const workerPath = join(dirname(fileURLToPath(import.meta.url)), "one-password-worker.js");
       const accountArg = this.account ?? "";
-      const child = spawn(
-        process.execPath,
-        [workerPath, accountArg, this.vaultId, id],
-        { stdio: ["ignore", "pipe", "pipe"] }
-      );
+      const child = spawn(process.execPath, [workerPath, accountArg, this.vaultId, id], {
+        stdio: ["ignore", "pipe", "pipe"]
+      });
       const stdoutChunks = [];
       const stderrChunks = [];
       child.stdout.on("data", (chunk) => {
@@ -988,12 +1824,19 @@ var OnePasswordBackend = class {
       child.stderr.on("data", (chunk) => {
         stderrChunks.push(chunk);
       });
-      child.on("close", (code) => {
+      child.on("close", (code, signal) => {
         const raw = Buffer.concat(stdoutChunks).toString("utf8").trim();
         if (raw === "") {
           const stderr = Buffer.concat(stderrChunks).toString("utf8").trim();
-          const detail = stderr !== "" ? stderr : `exit code ${String(code)}`;
-          reject(new Error(`1Password per-access worker crashed for secret ${id}: ${detail}`));
+          const exitDescription = typeof signal === "string" ? `terminated by signal ${signal}` : `exit code ${String(code)}`;
+          const detail = stderr !== "" ? stderr : exitDescription;
+          reject(
+            new BackendUnavailableError(
+              `1Password per-access worker crashed for secret ${id}: ${detail}`,
+              "worker-crashed",
+              ["1password"]
+            )
+          );
           return;
         }
         let parsed;
@@ -1004,13 +1847,20 @@ var OnePasswordBackend = class {
           return;
         }
         if (!isWorkerResponse(parsed)) {
-          reject(new SecretNotFoundError(`Worker returned unexpected response shape for secret: ${id}`));
+          reject(
+            new SecretNotFoundError(`Worker returned unexpected response shape for secret: ${id}`)
+          );
           return;
         }
         if (isWorkerSuccess(parsed)) {
-          resolve2(parsed.value);
+          resolve3(parsed.value);
         } else {
           switch (parsed.code) {
+            case "PLUGIN_NOT_FOUND":
+              reject(
+                new PluginNotFoundError(SDK_NOT_INSTALLED_MESSAGE, SDK_PACKAGE, SDK_INSTALL_URL)
+              );
+              break;
             case "NOT_FOUND":
               reject(new SecretNotFoundError(`Secret not found in 1Password: ${id}`));
               break;
@@ -1020,29 +1870,175 @@ var OnePasswordBackend = class {
             case "LOCKED":
               reject(new BackendLockedError("1Password is locked. Please unlock and retry.", true));
               break;
+            case "INTERNAL":
+              reject(
+                new BackendUnavailableError(
+                  `1Password per-access worker failed for secret ${id}: ${parsed.error}`,
+                  "worker-internal-error",
+                  ["1password"]
+                )
+              );
+              break;
             default:
               reject(new SecretNotFoundError(`Worker failed for secret ${id}: ${parsed.error}`));
           }
         }
       });
       child.on("error", (err) => {
-        reject(new Error(
-          `Failed to spawn 1Password per-access worker at ${workerPath}: ${String(err)}`
-        ));
+        reject(
+          new BackendUnavailableError(
+            `Failed to spawn 1Password per-access worker at ${workerPath}: ${String(err)}`,
+            "worker-spawn-failed",
+            ["1password"]
+          )
+        );
+      });
+    });
+  }
+  /**
+   * Spawn the per-access worker script to perform a `store` or `delete`,
+   * triggering a fresh biometric prompt for this single write (issue #211).
+   *
+   * @remarks
+   * For `store`, `secret` is delivered to the worker over **stdin**, never
+   * argv — it must never appear in a process listing, shell history, or log.
+   * `delete` needs no payload, so no stdin is written and the worker's stdin
+   * is left `'ignore'`d, mirroring the retrieve path's spawn options.
+   */
+  writeViaWorker(op, id, secret) {
+    return new Promise((resolve3, reject) => {
+      const workerPath = join(dirname(fileURLToPath(import.meta.url)), "one-password-worker.js");
+      const accountArg = this.account ?? "";
+      const needsStdin = secret !== void 0;
+      const child = spawn(process.execPath, [workerPath, accountArg, this.vaultId, id, op], {
+        stdio: [needsStdin ? "pipe" : "ignore", "pipe", "pipe"]
+      });
+      if (needsStdin && child.stdin !== null) {
+        child.stdin.on("error", () => {
+        });
+        child.stdin.write(secret, "utf8");
+        child.stdin.end();
+      }
+      const stdoutChunks = [];
+      const stderrChunks = [];
+      child.stdout?.on("data", (chunk) => {
+        stdoutChunks.push(chunk);
+      });
+      child.stderr?.on("data", (chunk) => {
+        stderrChunks.push(chunk);
+      });
+      child.on("close", (code, signal) => {
+        const raw = Buffer.concat(stdoutChunks).toString("utf8").trim();
+        if (raw === "") {
+          const stderr = Buffer.concat(stderrChunks).toString("utf8").trim();
+          const exitDescription = typeof signal === "string" ? `terminated by signal ${signal}` : `exit code ${String(code)}`;
+          const detail = stderr !== "" ? stderr : exitDescription;
+          reject(
+            new BackendUnavailableError(
+              `1Password per-access worker crashed during ${op} of secret ${id}: ${detail}`,
+              "worker-crashed",
+              ["1password"]
+            )
+          );
+          return;
+        }
+        let parsed;
+        try {
+          parsed = JSON.parse(raw);
+        } catch {
+          reject(
+            new BackendUnavailableError(
+              `Worker returned unparseable output during ${op} of secret ${id}`,
+              "worker-internal-error",
+              ["1password"]
+            )
+          );
+          return;
+        }
+        if (!isWorkerWriteResponse(parsed)) {
+          reject(
+            new BackendUnavailableError(
+              `Worker returned unexpected response shape during ${op} of secret ${id}`,
+              "worker-internal-error",
+              ["1password"]
+            )
+          );
+          return;
+        }
+        if (isWorkerWriteSuccess(parsed)) {
+          resolve3();
+          return;
+        }
+        switch (parsed.code) {
+          case "PLUGIN_NOT_FOUND":
+            reject(new PluginNotFoundError(SDK_NOT_INSTALLED_MESSAGE, SDK_PACKAGE, SDK_INSTALL_URL));
+            break;
+          case "NOT_FOUND":
+            reject(new SecretNotFoundError(`Secret not found in 1Password: ${id}`));
+            break;
+          case "LOCKED":
+            reject(new BackendLockedError("1Password is locked. Please unlock and retry.", true));
+            break;
+          case "PRESENCE_DECLINED":
+            reject(
+              new PresenceDeclinedError(
+                `1Password ${op} presence action was declined for secret ${id}`,
+                "1password"
+              )
+            );
+            break;
+          case "PRESENCE_TIMEOUT":
+            reject(
+              new PresenceTimeoutError(
+                `1Password ${op} presence action timed out for secret ${id}`,
+                "1password",
+                PRESENCE_WRITE_TIMEOUT_MS
+              )
+            );
+            break;
+          case "INTERNAL":
+            reject(
+              new BackendUnavailableError(
+                `1Password per-access worker failed during ${op} of secret ${id}: ${parsed.error}`,
+                "worker-internal-error",
+                ["1password"]
+              )
+            );
+            break;
+          default:
+            reject(
+              new BackendUnavailableError(
+                `Worker failed during ${op} of secret ${id}: ${parsed.error}`,
+                "worker-internal-error",
+                ["1password"]
+              )
+            );
+        }
+      });
+      child.on("error", (err) => {
+        reject(
+          new BackendUnavailableError(
+            `Failed to spawn 1Password per-access worker at ${workerPath}: ${String(err)}`,
+            "worker-spawn-failed",
+            ["1password"]
+          )
+        );
       });
     });
   }
   async delete(id) {
+    if (this.accessMode === "per-access") {
+      return this.writeViaWorker("delete", id);
+    }
     const client = await this.acquireClient();
-    const overview = await this.findItemOverview(client, id);
-    if (overview === void 0) {
+    const deleted = await deleteSecretItem(client, this.vaultId, id);
+    if (!deleted) {
       throw new SecretNotFoundError(`Secret not found in 1Password: ${id}`);
     }
-    await client.items.delete(this.vaultId, overview.id);
   }
   async exists(id) {
     const client = await this.acquireClient();
-    const overview = await this.findItemOverview(client, id);
+    const overview = await findItemOverviewByTitle(client, this.vaultId, id);
     return overview !== void 0;
   }
   async list() {
@@ -1057,33 +2053,31 @@ var OnePasswordBackend = class {
     return ids;
   }
   // ---- Private helpers ----
-  /** Load SDK and throw PluginNotFoundError if unavailable. */
-  async requireSdk() {
-    const sdk = await this.tryLoadSdk();
-    if (sdk === null) {
-      throw new PluginNotFoundError(
-        "1Password SDK (@1password/sdk) is not available.",
-        "@1password/sdk",
-        SDK_INSTALL_URL
-      );
-    }
-    return sdk;
+  /**
+   * Load SDK, throwing a typed {@link PluginNotFoundError} when it is not
+   * installed and surfacing the real error when it is present but broken.
+   */
+  requireSdk() {
+    return this.loadSdkOrThrow();
   }
 };
 var YKMAN_INSTALL_URL = "https://developers.yubico.com/yubikey-manager/";
-var STORAGE_DIR_NAME2 = path3.join(".vaultkeeper", "yubikey");
+var STORAGE_DIR_NAME2 = path2.join(".vaultkeeper", "yubikey");
 var METADATA_FILE = "metadata.json";
 var DEVICE_TIMEOUT_MS = 5e3;
 var GCM_IV_BYTES2 = 12;
 var GCM_KEY_BYTES2 = 32;
-var GCM_TAG_LENGTH_BITS = 128;
+var GCM_TAG_LENGTH_BITS2 = 128;
 var FORMAT_VERSION = "1";
-function getStorageDir2() {
-  return path3.join(os4.homedir(), STORAGE_DIR_NAME2);
+function resolveStorageDir3(configuredPath) {
+  if (configuredPath !== void 0) {
+    return configuredPath;
+  }
+  return path2.join(os.homedir(), STORAGE_DIR_NAME2);
 }
 function getEntryPath3(storageDir, id) {
   const safeId = Buffer.from(id, "utf8").toString("hex");
-  return path3.join(storageDir, `${safeId}.enc`);
+  return path2.join(storageDir, `${safeId}.enc`);
 }
 function isStringRecord(value) {
   if (value === null || typeof value !== "object") {
@@ -1092,9 +2086,9 @@ function isStringRecord(value) {
   return Object.values(value).every((v) => typeof v === "string");
 }
 async function loadMetadata(storageDir) {
-  const metaPath = path3.join(storageDir, METADATA_FILE);
+  const metaPath = path2.join(storageDir, METADATA_FILE);
   try {
-    const raw = await fs.readFile(metaPath, "utf8");
+    const raw = await fs3.readFile(metaPath, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed !== null && typeof parsed === "object" && "entries" in parsed && isStringRecord(parsed.entries)) {
       return { entries: parsed.entries };
@@ -1105,30 +2099,31 @@ async function loadMetadata(storageDir) {
   }
 }
 async function saveMetadata(storageDir, metadata) {
-  const metaPath = path3.join(storageDir, METADATA_FILE);
-  await fs.writeFile(metaPath, JSON.stringify(metadata, null, 2), { mode: 384 });
+  const metaPath = path2.join(storageDir, METADATA_FILE);
+  await fs3.writeFile(metaPath, JSON.stringify(metadata, null, 2), { mode: 384 });
 }
 var HMAC_RESPONSE_HEX_LENGTH = 40;
 var HMAC_RESPONSE_RE = /^[0-9a-fA-F]{40}$/;
 function deriveKey(hmacResponse, id) {
   const trimmed = hmacResponse.trim();
   if (!HMAC_RESPONSE_RE.test(trimmed)) {
-    throw new Error(
-      `Invalid YubiKey HMAC response: expected exactly ${String(HMAC_RESPONSE_HEX_LENGTH)} hex characters (20 bytes), got ${String(trimmed.length)} characters`
+    throw new SetupError(
+      `Invalid YubiKey HMAC response: expected exactly ${String(HMAC_RESPONSE_HEX_LENGTH)} hex characters (20 bytes), got ${String(trimmed.length)} characters`,
+      "ykman"
     );
   }
   const ikm = Buffer.from(trimmed, "hex");
   const info = Buffer.from(`vaultkeeper-yubikey:${id}`, "utf8");
-  const keyMaterial = crypto.hkdfSync("sha256", ikm, Buffer.alloc(0), info, GCM_KEY_BYTES2);
+  const keyMaterial = crypto2.hkdfSync("sha256", ikm, Buffer.alloc(0), info, GCM_KEY_BYTES2);
   return Buffer.from(keyMaterial);
 }
 function encryptGcm2(key, plaintext) {
-  const iv = crypto.randomBytes(GCM_IV_BYTES2);
+  const iv = crypto2.randomBytes(GCM_IV_BYTES2);
   let encrypted;
   let authTag;
   try {
-    const cipher = crypto.createCipheriv("aes-256-gcm", key, iv, {
-      authTagLength: GCM_TAG_LENGTH_BITS / 8
+    const cipher = crypto2.createCipheriv("aes-256-gcm", key, iv, {
+      authTagLength: GCM_TAG_LENGTH_BITS2 / 8
     });
     encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
     authTag = cipher.getAuthTag();
@@ -1145,48 +2140,52 @@ function encryptGcm2(key, plaintext) {
     authTag?.fill(0);
   }
 }
-function decryptGcm2(key, encoded) {
+function decryptGcm2(key, encoded, path9) {
   const parts = encoded.split(":");
   const versionSegment = parts[0] ?? "";
   const parsedVersion = parseInt(versionSegment, 10);
   const isNumericVersion = String(parsedVersion) === versionSegment && !Number.isNaN(parsedVersion);
   if (!isNumericVersion) {
     key.fill(0);
-    throw new Error(
-      "Encrypted file uses a legacy format (AES-256-CBC). Delete the secret and re-store it to migrate to AES-256-GCM."
+    throw new DecryptionError(
+      "Encrypted file uses a legacy format (AES-256-CBC). Delete the secret and re-store it to migrate to AES-256-GCM.",
+      path9
     );
   }
   if (versionSegment !== FORMAT_VERSION) {
     key.fill(0);
-    throw new Error(
-      `Unsupported encrypted file version: ${versionSegment}. This vaultkeeper build only supports version ${FORMAT_VERSION}. Upgrade vaultkeeper to read this secret.`
+    throw new DecryptionError(
+      `Unsupported encrypted file version: ${versionSegment}. This vaultkeeper build only supports version ${FORMAT_VERSION}. Upgrade vaultkeeper to read this secret.`,
+      path9
     );
   }
   if (parts.length !== 4) {
     key.fill(0);
-    throw new Error(
-      `Invalid encrypted file format: expected ${FORMAT_VERSION}:iv:authTag:ciphertext`
+    throw new DecryptionError(
+      `Invalid encrypted file format: expected ${FORMAT_VERSION}:iv:authTag:ciphertext`,
+      path9
     );
   }
   const [_version, ivB64, authTagB64, ciphertextB64] = parts;
   if (ivB64 === void 0 || authTagB64 === void 0 || ciphertextB64 === void 0) {
     key.fill(0);
-    throw new Error("Invalid encrypted file format: missing part");
+    throw new DecryptionError("Invalid encrypted file format: missing part", path9);
   }
   let decrypted;
   try {
     const iv = Buffer.from(ivB64, "base64");
     const authTag = Buffer.from(authTagB64, "base64");
     const ciphertext = Buffer.from(ciphertextB64, "base64");
-    const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv, {
-      authTagLength: GCM_TAG_LENGTH_BITS / 8
-    });
-    decipher.setAuthTag(authTag);
     try {
+      const decipher = crypto2.createDecipheriv("aes-256-gcm", key, iv, {
+        authTagLength: GCM_TAG_LENGTH_BITS2 / 8
+      });
+      decipher.setAuthTag(authTag);
       decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
     } catch (err) {
-      throw new Error(
-        `GCM authentication failed \u2014 ciphertext may be tampered: ${err instanceof Error ? err.message : String(err)}`
+      throw new DecryptionError(
+        `GCM authentication failed \u2014 ciphertext may be tampered or corrupt: ${err instanceof Error ? err.message : String(err)}`,
+        path9
       );
     }
     const plaintext = decrypted.toString("utf8");
@@ -1199,6 +2198,45 @@ function decryptGcm2(key, encoded) {
 var YubikeyBackend = class {
   type = "yubikey";
   displayName = "YubiKey";
+  #storageDir;
+  /**
+   * Whether the configured challenge-response slot enforces a touch for every
+   * operation. When `true`, each `store`/`retrieve`/`delete` requires a fresh
+   * physical tap (see {@link YubikeyBackend.getCapabilities}). Sourced from
+   * configuration, not hardcoded by type — a slot without a touch policy
+   * reports `false`.
+   */
+  #requireTouch;
+  /**
+   * @param storageDir - Directory in which encrypted secrets and metadata are
+   *   stored. Sourced from `BackendConfig.path`. Defaults to
+   *   `$HOME/.vaultkeeper/yubikey`.
+   * @param requireTouch - Whether the configured challenge-response slot
+   *   enforces a touch-per-operation policy. Defaults to `false`. Sourced from
+   *   the operator's configuration and must match the physical slot's policy
+   *   (verify with `ykman otp info`); it governs the value reported by
+   *   {@link YubikeyBackend.getCapabilities}.
+   */
+  constructor(storageDir, requireTouch = false) {
+    this.#storageDir = resolveStorageDir3(storageDir);
+    this.#requireTouch = requireTouch;
+  }
+  /**
+   * Report this instance's capabilities.
+   *
+   * @remarks
+   * `presencePerUse` is `true` only when the configured slot enforces a
+   * touch-per-operation policy (`requireTouch`), in which case every
+   * challenge-response — and therefore every `store`/`retrieve`/`delete` — forces
+   * a fresh physical tap that cannot be satisfied from any cached state. A slot
+   * without a touch policy reports `false`; the answer is never derived from the
+   * backend `type` alone. Truth-basis: the reported value comes from the
+   * operator-declared `touchPolicy` configuration; confirm it matches the
+   * physical slot with `ykman otp info` (a manual verification).
+   */
+  getCapabilities() {
+    return Promise.resolve({ presencePerUse: this.#requireTouch });
+  }
   async isAvailable() {
     try {
       const result = await execCommandFull("ykman", ["--version"]);
@@ -1232,43 +2270,43 @@ var YubikeyBackend = class {
     const challenge = Buffer.from(`vaultkeeper:${id}`, "utf8").toString("hex");
     const responseResult = await execCommandFull("ykman", ["otp", "calculate", "2", challenge]);
     if (responseResult.exitCode !== 0) {
-      throw new Error(`YubiKey challenge-response failed: ${responseResult.stderr}`);
+      throw new ExecError(`YubiKey challenge-response failed: ${responseResult.stderr}`, "ykman");
     }
     return responseResult.stdout.trim();
   }
   async store(id, secret) {
     await this.requireDevice();
-    const storageDir = getStorageDir2();
-    await fs.mkdir(storageDir, { recursive: true, mode: 448 });
+    const storageDir = this.#storageDir;
+    await fs3.mkdir(storageDir, { recursive: true, mode: 448 });
     const hmacResponse = await this.challengeResponse(id);
     const key = deriveKey(hmacResponse, id);
     const encrypted = encryptGcm2(key, secret);
     const entryPath = getEntryPath3(storageDir, id);
-    await fs.writeFile(entryPath, encrypted, { mode: 384 });
+    await fs3.writeFile(entryPath, encrypted, { mode: 384 });
     const metadata = await loadMetadata(storageDir);
     metadata.entries[id] = entryPath;
     await saveMetadata(storageDir, metadata);
   }
   async retrieve(id) {
     await this.requireDevice();
-    const storageDir = getStorageDir2();
+    const storageDir = this.#storageDir;
     const entryPath = getEntryPath3(storageDir, id);
     try {
-      await fs.access(entryPath);
+      await fs3.access(entryPath);
     } catch {
       throw new SecretNotFoundError(`Secret not found in YubiKey store: ${id}`);
     }
-    const encoded = await fs.readFile(entryPath, "utf8");
+    const encoded = await fs3.readFile(entryPath, "utf8");
     const hmacResponse = await this.challengeResponse(id);
     const key = deriveKey(hmacResponse, id);
-    return decryptGcm2(key, encoded);
+    return decryptGcm2(key, encoded, entryPath);
   }
   async delete(id) {
     await this.requireDevice();
-    const storageDir = getStorageDir2();
+    const storageDir = this.#storageDir;
     const entryPath = getEntryPath3(storageDir, id);
     try {
-      await fs.unlink(entryPath);
+      await fs3.unlink(entryPath);
     } catch (err) {
       if (err instanceof Error && "code" in err && err.code === "ENOENT") {
         throw new SecretNotFoundError(`Secret not found in YubiKey store: ${id}`);
@@ -1280,17 +2318,17 @@ var YubikeyBackend = class {
     await saveMetadata(storageDir, metadata);
   }
   async exists(id) {
-    const storageDir = getStorageDir2();
+    const storageDir = this.#storageDir;
     const entryPath = getEntryPath3(storageDir, id);
     try {
-      await fs.access(entryPath);
+      await fs3.access(entryPath);
       return true;
     } catch {
       return false;
     }
   }
   async list() {
-    const storageDir = getStorageDir2();
+    const storageDir = this.#storageDir;
     const metadata = await loadMetadata(storageDir);
     return Object.keys(metadata.entries);
   }
@@ -1298,9 +2336,12 @@ var YubikeyBackend = class {
 
 // src/backend/register-builtins.ts
 function registerBuiltinBackends() {
-  BackendRegistry.register("file", () => new FileBackend());
+  BackendRegistry.register(
+    "file",
+    (config, configDir) => new FileBackend(config?.path, configDir)
+  );
   BackendRegistry.register("keychain", () => new KeychainBackend());
-  BackendRegistry.register("dpapi", () => new DpapiBackend());
+  BackendRegistry.register("dpapi", (config) => new DpapiBackend(config?.path));
   BackendRegistry.register("secret-tool", () => new SecretToolBackend());
   BackendRegistry.register("1password", (config) => {
     const opts = config?.options;
@@ -1320,7 +2361,17 @@ function registerBuiltinBackends() {
     }
     return new OnePasswordBackend(opOptions);
   });
-  BackendRegistry.register("yubikey", () => new YubikeyBackend());
+  BackendRegistry.register(
+    "yubikey",
+    (config) => (
+      // `touchPolicy: 'required'` in the backend options declares that the
+      // configured challenge-response slot enforces a touch per operation, which
+      // is what makes the instance presence-per-use capable (see
+      // YubikeyBackend.getCapabilities). Any other value (or absent) reports
+      // false — presence is never assumed from the backend type alone.
+      new YubikeyBackend(config?.path, config?.options?.touchPolicy === "required")
+    )
+  );
 }
 registerBuiltinBackends();
 
@@ -1328,18 +2379,37 @@ registerBuiltinBackends();
 function isListableBackend(backend) {
   return "list" in backend && typeof backend.list === "function";
 }
+function isPresenceCapableBackend(backend) {
+  return "getCapabilities" in backend && typeof backend.getCapabilities === "function";
+}
+async function getBackendCapabilities(backend) {
+  if (isPresenceCapableBackend(backend)) {
+    return backend.getCapabilities();
+  }
+  return { presencePerUse: false };
+}
+function isSigningBackend(backend) {
+  return "generateSigningKey" in backend && typeof backend.generateSigningKey === "function" && "getPublicKey" in backend && typeof backend.getPublicKey === "function" && "signWithKey" in backend && typeof backend.signWithKey === "function";
+}
 function hashExecutable(filePath) {
-  return new Promise((resolve2, reject) => {
-    const hash = crypto.createHash("sha256");
-    const stream = fs4.createReadStream(filePath);
+  return new Promise((resolve3, reject) => {
+    const hash = crypto2.createHash("sha256");
+    const stream = fs6.createReadStream(filePath);
     stream.on("data", (chunk) => {
       hash.update(chunk);
     });
     stream.on("end", () => {
-      resolve2(hash.digest("hex"));
+      resolve3(hash.digest("hex"));
     });
     stream.on("error", (err) => {
-      reject(err);
+      reject(
+        new FilesystemError(
+          `Cannot read executable at ${filePath}: ${err.message}`,
+          filePath,
+          "read",
+          err
+        )
+      );
     });
   });
 }
@@ -1347,7 +2417,8 @@ var MANIFEST_FILENAME = "trust-manifest.json";
 function isRawManifest(value) {
   if (typeof value !== "object" || value === null) return false;
   if (!("version" in value) || typeof value.version !== "number") return false;
-  if (!("entries" in value) || typeof value.entries !== "object" || value.entries === null) return false;
+  if (!("entries" in value) || typeof value.entries !== "object" || value.entries === null)
+    return false;
   return true;
 }
 function isTrustManifestEntry(value) {
@@ -1359,17 +2430,34 @@ function isTrustManifestEntry(value) {
   return true;
 }
 async function loadManifest(configDir) {
-  const manifestPath = path3.join(configDir, MANIFEST_FILENAME);
+  const manifestPath = path2.join(configDir, MANIFEST_FILENAME);
   let rawText;
   try {
-    rawText = await fs.readFile(manifestPath, "utf8");
+    rawText = await fs3.readFile(manifestPath, "utf8");
   } catch (err) {
     if (typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT") {
       return /* @__PURE__ */ new Map();
     }
-    throw err;
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new FilesystemError(
+      `Cannot read trust manifest at ${manifestPath}: ${detail}`,
+      manifestPath,
+      "read",
+      err
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(rawText);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new FilesystemError(
+      `Trust manifest at ${manifestPath} is not valid JSON: ${detail}`,
+      manifestPath,
+      "read",
+      err
+    );
   }
-  const parsed = JSON.parse(rawText);
   if (!isRawManifest(parsed)) {
     return /* @__PURE__ */ new Map();
   }
@@ -1382,14 +2470,28 @@ async function loadManifest(configDir) {
   return manifest;
 }
 async function saveManifest(configDir, manifest) {
-  await fs.mkdir(configDir, { recursive: true });
+  const manifestPath = path2.join(configDir, MANIFEST_FILENAME);
+  try {
+    await fs3.mkdir(configDir, { recursive: true });
+  } catch (err) {
+    throw toFilesystemError(err, "trust-manifest directory", configDir, "create");
+  }
   const entries = {};
   for (const [namespace, entry] of manifest) {
     entries[namespace] = entry;
   }
   const raw = { version: 1, entries };
-  const manifestPath = path3.join(configDir, MANIFEST_FILENAME);
-  await fs.writeFile(manifestPath, JSON.stringify(raw, null, 2), "utf8");
+  try {
+    await fs3.writeFile(manifestPath, JSON.stringify(raw, null, 2), "utf8");
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new FilesystemError(
+      `Cannot write trust manifest at ${manifestPath}: ${detail}`,
+      manifestPath,
+      "write",
+      err
+    );
+  }
 }
 function addTrustedHash(manifest, namespace, hash) {
   const next = new Map(manifest);
@@ -1423,27 +2525,32 @@ async function trySigstore(execPath) {
     return false;
   }
 }
-async function verifyTrust(execPath, options) {
+async function verifyTrustPending(execPath, options) {
+  const configDir = options?.configDir ?? ".vaultkeeper";
   if (execPath === "dev") {
     return {
       identity: { hash: "dev", trustTier: 3, verified: false },
       tofuConflict: false,
-      reason: "Dev mode \u2014 hash verification skipped"
+      approvedHashes: [],
+      reason: "Dev mode \u2014 hash verification skipped",
+      pendingWrite: void 0,
+      configDir
     };
   }
-  const configDir = options?.configDir ?? ".vaultkeeper";
   const namespace = options?.namespace ?? execPath;
   const currentHash = await hashExecutable(execPath);
   const manifest = await loadManifest(configDir);
+  const approvedHashes = manifest.get(namespace)?.hashes ?? [];
   if (options?.skipSigstore !== true) {
     const sigstoreVerified = await trySigstore(execPath);
     if (sigstoreVerified) {
-      const updated2 = addTrustedHash(manifest, namespace, currentHash);
-      await saveManifest(configDir, updated2);
       return {
         identity: { hash: currentHash, trustTier: 1, verified: true },
         tofuConflict: false,
-        reason: "Sigstore bundle verified"
+        approvedHashes,
+        reason: "Sigstore bundle verified",
+        pendingWrite: { namespace, hash: currentHash },
+        configDir
       };
     }
   }
@@ -1451,7 +2558,10 @@ async function verifyTrust(execPath, options) {
     return {
       identity: { hash: currentHash, trustTier: 2, verified: true },
       tofuConflict: false,
-      reason: "Hash found in trust manifest"
+      approvedHashes,
+      reason: "Hash found in trust manifest",
+      pendingWrite: void 0,
+      configDir
     };
   }
   const existing = manifest.get(namespace);
@@ -1459,17 +2569,42 @@ async function verifyTrust(execPath, options) {
     return {
       identity: { hash: currentHash, trustTier: 3, verified: false },
       tofuConflict: true,
-      reason: `Hash changed from a previously approved value \u2014 re-approval required`
+      approvedHashes,
+      reason: `Hash changed from a previously approved value \u2014 re-approval required`,
+      pendingWrite: void 0,
+      configDir
     };
   }
-  const updated = addTrustedHash(manifest, namespace, currentHash);
-  await saveManifest(configDir, updated);
   return {
     identity: { hash: currentHash, trustTier: 3, verified: false },
     tofuConflict: false,
-    reason: "First encounter \u2014 hash recorded via TOFU"
+    approvedHashes,
+    reason: "First encounter \u2014 hash staged for TOFU recording",
+    pendingWrite: { namespace, hash: currentHash },
+    configDir
   };
 }
+async function commitTrust(pending) {
+  if (pending.pendingWrite === void 0) {
+    return;
+  }
+  const { namespace, hash } = pending.pendingWrite;
+  const current = await loadManifest(pending.configDir);
+  const existing = current.get(namespace);
+  if (existing?.hashes.includes(hash) === true) {
+    return;
+  }
+  if (existing !== void 0 && existing.hashes.length > 0) {
+    const previousHash = existing.hashes.at(-1) ?? hash;
+    throw new IdentityMismatchError(
+      "Executable hash changed \u2014 re-approval required",
+      previousHash,
+      hash
+    );
+  }
+  const merged = addTrustedHash(current, namespace, hash);
+  await saveManifest(pending.configDir, merged);
+}
 
 // src/identity/session.ts
 var CapabilityToken = class {
@@ -1492,6 +2627,11 @@ function createCapabilityToken(claims) {
   claimsStore.set(token, claims);
   return token;
 }
+function createSigningCapabilityToken(claims) {
+  const token = new CapabilityToken();
+  claimsStore.set(token, claims);
+  return token;
+}
 function validateCapabilityToken(token) {
   const claims = claimsStore.get(token);
   if (claims === void 0) {
@@ -1499,166 +2639,22 @@ function validateCapabilityToken(token) {
   }
   return claims;
 }
-function getDefaultConfigDir() {
-  const envOverride = process.env.VAULTKEEPER_CONFIG_DIR;
-  if (envOverride !== void 0 && envOverride !== "") {
-    return envOverride;
-  }
-  if (process.platform === "win32") {
-    const appData = process.env.APPDATA;
-    if (appData !== void 0) {
-      return path3.join(appData, "vaultkeeper");
-    }
-    return path3.join(os4.homedir(), "AppData", "Roaming", "vaultkeeper");
-  }
-  return path3.join(os4.homedir(), ".config", "vaultkeeper");
-}
-function defaultConfig() {
-  return {
-    version: 1,
-    backends: [{ type: "file", enabled: true }],
-    keyRotation: { gracePeriodDays: 7 },
-    defaults: { ttlMinutes: 60, trustTier: 3 }
-  };
-}
-function isObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function validateBackendEntry(entry, index) {
-  if (!isObject(entry)) {
-    throw new Error(`backends[${String(index)}] must be an object`);
-  }
-  if (typeof entry.type !== "string" || entry.type.trim() === "") {
-    throw new Error(`backends[${String(index)}].type must be a non-empty string`);
-  }
-  if (typeof entry.enabled !== "boolean") {
-    throw new Error(`backends[${String(index)}].enabled must be a boolean`);
-  }
-  const result = {
-    type: entry.type,
-    enabled: entry.enabled
-  };
-  if (entry.plugin !== void 0) {
-    if (typeof entry.plugin !== "boolean") {
-      throw new Error(`backends[${String(index)}].plugin must be a boolean`);
-    }
-    result.plugin = entry.plugin;
-  }
-  if (entry.path !== void 0) {
-    if (typeof entry.path !== "string") {
-      throw new Error(`backends[${String(index)}].path must be a string`);
-    }
-    result.path = entry.path;
-  }
-  if (entry.options !== void 0) {
-    if (!isObject(entry.options)) {
-      throw new Error(`backends[${String(index)}].options must be an object`);
-    }
-    const opts = {};
-    for (const [k, v] of Object.entries(entry.options)) {
-      if (typeof v !== "string") {
-        throw new Error(
-          `backends[${String(index)}].options["${k}"] must be a string`
-        );
-      }
-      opts[k] = v;
-    }
-    result.options = opts;
-  }
-  return result;
-}
-function validateConfig(config) {
-  if (!isObject(config)) {
-    throw new Error("Config must be an object");
-  }
-  if (typeof config.version !== "number" || config.version !== 1) {
-    throw new Error("Config version must be 1");
-  }
-  if (!Array.isArray(config.backends) || config.backends.length === 0) {
-    throw new Error("Config must have at least one backend");
-  }
-  const backends = config.backends.map(
-    (entry, i) => validateBackendEntry(entry, i)
-  );
-  if (!isObject(config.keyRotation)) {
-    throw new Error("Config keyRotation must be an object");
-  }
-  if (typeof config.keyRotation.gracePeriodDays !== "number" || config.keyRotation.gracePeriodDays <= 0) {
-    throw new Error("Config keyRotation.gracePeriodDays must be a positive number");
-  }
-  if (!isObject(config.defaults)) {
-    throw new Error("Config defaults must be an object");
-  }
-  if (typeof config.defaults.ttlMinutes !== "number" || config.defaults.ttlMinutes <= 0) {
-    throw new Error("Config defaults.ttlMinutes must be a positive number");
-  }
-  let tier = config.defaults.trustTier;
-  if (typeof tier === "string") {
-    const parsed = Number(tier);
-    if (!Number.isNaN(parsed)) {
-      tier = parsed;
-    }
-  }
-  if (tier !== 1 && tier !== 2 && tier !== 3) {
-    throw new Error("Config defaults.trustTier must be 1, 2, or 3");
-  }
-  const result = {
-    version: 1,
-    backends,
-    keyRotation: {
-      gracePeriodDays: config.keyRotation.gracePeriodDays
-    },
-    defaults: {
-      ttlMinutes: config.defaults.ttlMinutes,
-      trustTier: tier
-    }
-  };
-  if (config.developmentMode !== void 0) {
-    if (!isObject(config.developmentMode)) {
-      throw new Error("Config developmentMode must be an object");
-    }
-    if (!Array.isArray(config.developmentMode.executables)) {
-      throw new Error("Config developmentMode.executables must be an array");
-    }
-    const executables = [];
-    for (const [i, exe] of Array.from(config.developmentMode.executables).entries()) {
-      if (typeof exe !== "string") {
-        throw new Error(`Config developmentMode.executables[${String(i)}] must be a string`);
-      }
-      executables.push(exe);
-    }
-    result.developmentMode = { executables };
-  }
-  return result;
-}
-async function loadConfig(configDir) {
-  const dir = configDir ?? getDefaultConfigDir();
-  const configPath = path3.join(dir, "config.json");
-  let raw;
-  try {
-    raw = await fs.readFile(configPath, "utf-8");
-  } catch {
-    return defaultConfig();
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    throw new Error(`Failed to parse config file at ${configPath}`);
-  }
-  return validateConfig(parsed);
+function isSigningClaims(claims) {
+  const record = { ...claims };
+  const kid = record.kid;
+  const backendRef = record.backendRef;
+  return record.keyType === "signing-key" && typeof kid === "string" && kid.length > 0 && typeof backendRef === "string" && backendRef.length > 0 && !("val" in record);
 }
 var KeyManager = class {
   #state = void 0;
   #gracePeriodTimer = void 0;
   #gracePeriodExpiresAt = void 0;
-  #rotating = false;
   /** Generate a new 32-byte key with a timestamp-based id. */
   generateKey() {
-    const randomSuffix = crypto.randomBytes(4).toString("hex");
+    const randomSuffix = crypto2.randomBytes(4).toString("hex");
     return {
       id: `k-${String(Date.now())}-${randomSuffix}`,
-      key: new Uint8Array(crypto.randomBytes(32)),
+      key: new Uint8Array(crypto2.randomBytes(32)),
       createdAt: /* @__PURE__ */ new Date()
     };
   }
@@ -1672,6 +2668,43 @@ var KeyManager = class {
     }
     return Promise.resolve();
   }
+  /**
+   * Replace the in-memory state with a persisted snapshot.
+   *
+   * An expired grace period in the snapshot is dropped: the previous key is
+   * discarded and no grace period is restored. When the grace period is still
+   * active, a fresh timer is armed for the remaining duration so the previous
+   * key is eventually freed in long-running processes; correctness never depends
+   * on that timer (grace is always re-checked against the wall clock).
+   * @internal
+   */
+  hydrate(snapshot) {
+    this.#clearGracePeriodTimer();
+    if (snapshot.previous !== void 0 && snapshot.gracePeriodExpiresAt !== void 0 && Date.now() < snapshot.gracePeriodExpiresAt) {
+      this.#state = { current: snapshot.current, previous: snapshot.previous };
+      this.#gracePeriodExpiresAt = snapshot.gracePeriodExpiresAt;
+      this.#armGracePeriodTimer(snapshot.gracePeriodExpiresAt - Date.now());
+    } else {
+      this.#state = { current: snapshot.current };
+      this.#gracePeriodExpiresAt = void 0;
+    }
+  }
+  /**
+   * Capture the current state as a serializable snapshot for persistence.
+   * The previous key and grace expiry are included only while the grace period
+   * is still active.
+   * @internal
+   */
+  snapshot() {
+    const state = this.#requireState();
+    const result = { current: state.current };
+    const previous = this.getPreviousKey();
+    if (previous !== void 0 && this.#gracePeriodExpiresAt !== void 0) {
+      result.previous = previous;
+      result.gracePeriodExpiresAt = this.#gracePeriodExpiresAt;
+    }
+    return result;
+  }
   /** Return the current (encryption) key. Throws if not initialized. */
   getCurrentKey() {
     const state = this.#requireState();
@@ -1683,6 +2716,9 @@ var KeyManager = class {
    */
   getPreviousKey() {
     const state = this.#requireState();
+    if (!this.isInGracePeriod()) {
+      return void 0;
+    }
     return state.previous;
   }
   /**
@@ -1695,7 +2731,7 @@ var KeyManager = class {
     if (state.current.id === kid) {
       return state.current;
     }
-    const { previous } = state;
+    const previous = this.getPreviousKey();
     if (previous?.id === kid) {
       return previous;
     }
@@ -1706,29 +2742,19 @@ var KeyManager = class {
    * becomes current. A grace-period timer is started; when it fires the
    * previous key is cleared automatically.
    *
-   * @throws {RotationInProgressError} if a rotation is already underway.
+   * @throws {RotationInProgressError} if a rotation is already underway (i.e. a
+   *   previous key is still within its grace period).
    */
   rotateKey(gracePeriodMs) {
-    if (this.#rotating) {
+    const state = this.#requireState();
+    if (this.isInGracePeriod()) {
       throw new RotationInProgressError("A key rotation is already in progress");
     }
-    const state = this.#requireState();
-    this.#rotating = true;
     this.#clearGracePeriodTimer();
     const newKey = this.generateKey();
     this.#state = { current: newKey, previous: state.current };
     this.#gracePeriodExpiresAt = Date.now() + gracePeriodMs;
-    this.#gracePeriodTimer = setTimeout(() => {
-      if (this.#state !== void 0) {
-        this.#state = { current: this.#state.current };
-      }
-      this.#gracePeriodExpiresAt = void 0;
-      this.#gracePeriodTimer = void 0;
-      this.#rotating = false;
-    }, gracePeriodMs);
-    if (typeof this.#gracePeriodTimer.unref === "function") {
-      this.#gracePeriodTimer.unref();
-    }
+    this.#armGracePeriodTimer(gracePeriodMs);
   }
   /**
    * Emergency revocation: immediately clear the previous key and generate
@@ -1736,7 +2762,6 @@ var KeyManager = class {
    */
   revokeKey() {
     this.#clearGracePeriodTimer();
-    this.#rotating = false;
     this.#gracePeriodExpiresAt = void 0;
     const newKey = this.generateKey();
     this.#state = { current: newKey };
@@ -1756,13 +2781,22 @@ var KeyManager = class {
   // ---------------------------------------------------------------------------
   #requireState() {
     if (this.#state === void 0) {
-      throw new SetupError(
-        "KeyManager has not been initialized \u2014 call init() first",
-        "KeyManager"
-      );
+      throw new SetupError("KeyManager has not been initialized \u2014 call init() first", "KeyManager");
     }
     return this.#state;
   }
+  #armGracePeriodTimer(delayMs) {
+    this.#gracePeriodTimer = setTimeout(() => {
+      if (this.#state !== void 0) {
+        this.#state = { current: this.#state.current };
+      }
+      this.#gracePeriodExpiresAt = void 0;
+      this.#gracePeriodTimer = void 0;
+    }, delayMs);
+    if (typeof this.#gracePeriodTimer.unref === "function") {
+      this.#gracePeriodTimer.unref();
+    }
+  }
   #clearGracePeriodTimer() {
     if (this.#gracePeriodTimer !== void 0) {
       clearTimeout(this.#gracePeriodTimer);
@@ -1770,6 +2804,111 @@ var KeyManager = class {
     }
   }
 };
+var KEY_STATE_FILE = "keys.enc";
+var KEY_WRAP_FILE = ".keys.wrap";
+function serializeKey(key) {
+  return {
+    id: key.id,
+    key: Buffer.from(key.key).toString("base64"),
+    createdAt: key.createdAt.toISOString()
+  };
+}
+function isRawKeyMaterial(value) {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("id" in value) || typeof value.id !== "string" || value.id === "") return false;
+  if (!("key" in value) || typeof value.key !== "string" || value.key === "") return false;
+  if (!("createdAt" in value) || typeof value.createdAt !== "string") return false;
+  return true;
+}
+function deserializeKey(raw) {
+  const bytes = Buffer.from(raw.key, "base64");
+  if (bytes.byteLength !== 32) return void 0;
+  const createdAt = new Date(raw.createdAt);
+  if (Number.isNaN(createdAt.getTime())) return void 0;
+  return { id: raw.id, key: new Uint8Array(bytes), createdAt };
+}
+function isRawKeyState(value) {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("version" in value) || typeof value.version !== "number") return false;
+  if (!("current" in value) || !isRawKeyMaterial(value.current)) return false;
+  if ("previous" in value && value.previous !== void 0 && !isRawKeyMaterial(value.previous)) {
+    return false;
+  }
+  if ("gracePeriodExpiresAt" in value && value.gracePeriodExpiresAt !== void 0 && typeof value.gracePeriodExpiresAt !== "number") {
+    return false;
+  }
+  return true;
+}
+async function loadKeyState(configDir) {
+  const statePath = path2.join(configDir, KEY_STATE_FILE);
+  let envelope;
+  try {
+    envelope = await fs3.readFile(statePath, "utf8");
+  } catch {
+    return void 0;
+  }
+  const wrapKey = await getOrCreateWrapKey(path2.join(configDir, KEY_WRAP_FILE));
+  let json;
+  try {
+    json = decryptGcm(wrapKey, envelope, statePath);
+  } catch {
+    return void 0;
+  } finally {
+    wrapKey.fill(0);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return void 0;
+  }
+  if (!isRawKeyState(parsed)) return void 0;
+  const current = deserializeKey(parsed.current);
+  if (current === void 0) return void 0;
+  const snapshot = { current };
+  if (parsed.previous !== void 0 && parsed.gracePeriodExpiresAt !== void 0) {
+    const previous = deserializeKey(parsed.previous);
+    if (previous !== void 0 && Date.now() < parsed.gracePeriodExpiresAt) {
+      snapshot.previous = previous;
+      snapshot.gracePeriodExpiresAt = parsed.gracePeriodExpiresAt;
+    }
+  }
+  return snapshot;
+}
+async function saveKeyState(configDir, snapshot) {
+  try {
+    await fs3.mkdir(configDir, { recursive: true, mode: 448 });
+  } catch (err) {
+    throw toFilesystemError(err, "config directory", configDir, "create");
+  }
+  const raw = {
+    version: 1,
+    current: serializeKey(snapshot.current)
+  };
+  if (snapshot.previous !== void 0 && snapshot.gracePeriodExpiresAt !== void 0) {
+    raw.previous = serializeKey(snapshot.previous);
+    raw.gracePeriodExpiresAt = snapshot.gracePeriodExpiresAt;
+  }
+  const wrapKey = await getOrCreateWrapKey(path2.join(configDir, KEY_WRAP_FILE));
+  let envelope;
+  try {
+    envelope = encryptGcm(wrapKey, JSON.stringify(raw));
+  } finally {
+    wrapKey.fill(0);
+  }
+  const statePath = path2.join(configDir, KEY_STATE_FILE);
+  const tmpPath = `${statePath}.${String(process.pid)}.tmp`;
+  try {
+    await fs3.writeFile(tmpPath, envelope, { encoding: "utf8", mode: 384 });
+  } catch (err) {
+    throw toFilesystemError(err, "key state file", tmpPath, "write");
+  }
+  try {
+    await fs3.rename(tmpPath, statePath);
+  } catch (err) {
+    throw toFilesystemError(err, "key state file", statePath, "write");
+  }
+}
 var ALGORITHM = "dir";
 var ENCRYPTION = "A256GCM";
 async function createToken(key, claims, options) {
@@ -1810,40 +2949,40 @@ async function decryptToken(key, jwe) {
     plaintext = result.plaintext;
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    throw new VaultError(`JWE decryption failed: ${message}`);
+    throw new InvalidTokenError(`JWE decryption failed: ${message}`);
   }
   let parsed;
   try {
     parsed = JSON.parse(new TextDecoder().decode(plaintext));
   } catch {
-    throw new VaultError("JWE payload is not valid JSON");
+    throw new InvalidTokenError("JWE payload is not valid JSON");
   }
   const claims = parseVaultClaims(parsed);
   if (claims === void 0) {
-    throw new VaultError("JWE payload does not match VaultClaims schema");
+    throw new InvalidTokenError("JWE payload does not match VaultClaims schema");
   }
   return claims;
 }
 function extractKid(jwe) {
   const parts = jwe.split(".");
   if (parts.length !== 5) {
-    throw new VaultError("Invalid JWE compact serialization: expected 5 parts");
+    throw new InvalidTokenError("Invalid JWE compact serialization: expected 5 parts");
   }
   const headerSegment = parts[0];
   if (headerSegment === void 0 || headerSegment === "") {
-    throw new VaultError("Invalid JWE compact serialization: missing header segment");
+    throw new InvalidTokenError("Invalid JWE compact serialization: missing header segment");
   }
   let headerJson;
   try {
     headerJson = Buffer.from(headerSegment, "base64url").toString("utf-8");
   } catch {
-    throw new VaultError("Invalid JWE compact serialization: header is not valid Base64URL");
+    throw new InvalidTokenError("Invalid JWE compact serialization: header is not valid Base64URL");
   }
   let header;
   try {
     header = JSON.parse(headerJson);
   } catch {
-    throw new VaultError("Invalid JWE compact serialization: header is not valid JSON");
+    throw new InvalidTokenError("Invalid JWE compact serialization: header is not valid JSON");
   }
   if (!isObject2(header)) {
     return void 0;
@@ -1918,22 +3057,50 @@ function validateClaims(claims, usedCount = 0) {
   }
 }
 
-// src/access/delegated-fetch.ts
+// src/access/placeholder.ts
 var PLACEHOLDER = "{{secret}}";
-function replacePlaceholder(value, secret) {
-  return value.replaceAll(PLACEHOLDER, secret);
+var NAMED_PLACEHOLDER_RE = /\{\{secret:([^}]+)\}\}/g;
+var ANY_PLACEHOLDER_RE = /\{\{secret(?::[^}]+)?\}\}/;
+function resolvePlaceholders(value, secrets) {
+  if (typeof secrets === "string") {
+    return value.replaceAll(PLACEHOLDER, secrets);
+  }
+  return value.replace(NAMED_PLACEHOLDER_RE, (_match, name) => {
+    const secret = secrets[name];
+    if (secret === void 0) {
+      const available = Object.keys(secrets).join(", ");
+      throw new VaultError(
+        `Unknown secret name in placeholder: {{secret:${name}}}. Available names: ${available}`
+      );
+    }
+    return secret;
+  });
 }
-function replaceInRecord(record, secret) {
+function resolvePlaceholdersInRecord(record, secrets) {
   const result = {};
   for (const [key, value] of Object.entries(record)) {
-    result[key] = replacePlaceholder(value, secret);
+    result[key] = resolvePlaceholders(value, secrets);
   }
   return result;
 }
-async function delegatedFetch(secret, request) {
-  const url = replacePlaceholder(request.url, secret);
-  const headers = request.headers !== void 0 ? replaceInRecord(request.headers, secret) : void 0;
-  const body = request.body !== void 0 ? replacePlaceholder(request.body, secret) : void 0;
+
+// src/access/delegated-fetch.ts
+function redactSecretMaterial(detail, resolvedUrl, urlTemplate, secretValues) {
+  let out = detail;
+  if (resolvedUrl !== urlTemplate) {
+    out = out.split(resolvedUrl).join(urlTemplate);
+  }
+  for (const value of secretValues) {
+    if (value.length > 0) {
+      out = out.split(value).join("[REDACTED]");
+    }
+  }
+  return out;
+}
+async function delegatedFetch(secrets, request) {
+  const url = resolvePlaceholders(request.url, secrets);
+  const headers = request.headers !== void 0 ? resolvePlaceholdersInRecord(request.headers, secrets) : void 0;
+  const body = request.body !== void 0 ? resolvePlaceholders(request.body, secrets) : void 0;
   const init = {};
   if (request.method !== void 0) {
     init.method = request.method;
@@ -1944,23 +3111,57 @@ async function delegatedFetch(secret, request) {
   if (body !== void 0) {
     init.body = body;
   }
-  return fetch(url, init);
-}
-var PLACEHOLDER2 = "{{secret}}";
-function replacePlaceholder2(value, secret) {
-  return value.replaceAll(PLACEHOLDER2, secret);
+  try {
+    return await fetch(url, init);
+  } catch (error) {
+    const rawDetail = error instanceof Error ? error.message : String(error);
+    const secretValues = typeof secrets === "string" ? [secrets] : Object.values(secrets);
+    const detail = redactSecretMaterial(rawDetail, url, request.url, secretValues);
+    throw new FetchError(`Fetch failed for ${request.url}: ${detail}`, request.url);
+  }
 }
-function replaceInRecord2(record, secret) {
-  const result = {};
-  for (const [key, value] of Object.entries(record)) {
-    result[key] = replacePlaceholder2(value, secret);
+
+// src/access/redact.ts
+var REDACTED = "[REDACTED]";
+function redactSecrets(text, secrets, replacement = REDACTED) {
+  const ordered = [...new Set(secrets)].filter((secret) => secret.trim().length > 0).sort((a, b) => b.length - a.length);
+  const literalReplacement = replacement.replaceAll("$", "$$$$");
+  let result = text;
+  for (const secret of ordered) {
+    result = result.replaceAll(secret, literalReplacement);
   }
   return result;
 }
-function delegatedExec(secret, request) {
-  const args = (request.args ?? []).map((arg) => replacePlaceholder2(arg, secret));
-  const env = request.env !== void 0 ? replaceInRecord2(request.env, secret) : void 0;
-  return new Promise((resolve2, reject) => {
+
+// src/access/delegated-exec.ts
+async function delegatedExec(secrets, request) {
+  if (ANY_PLACEHOLDER_RE.test(request.command)) {
+    throw new ExecError(
+      `Secret placeholders are not supported in the command field. Use env instead.`,
+      request.command
+    );
+  }
+  const args = request.args ?? [];
+  for (const arg of args) {
+    if (ANY_PLACEHOLDER_RE.test(arg)) {
+      throw new ExecError(
+        `Secret placeholders are not supported in the args field \u2014 process arguments are visible to other processes via ps. Use env instead.`,
+        request.command
+      );
+    }
+  }
+  const secretValues = typeof secrets === "string" ? [secrets] : Object.values(secrets);
+  const shouldRedact = request.redact !== false;
+  let env;
+  try {
+    env = request.env !== void 0 ? resolvePlaceholdersInRecord(request.env, secrets) : void 0;
+  } catch (error) {
+    if (error instanceof VaultError) {
+      throw new ExecError(error.message, request.command);
+    }
+    throw error;
+  }
+  return new Promise((resolve3, reject) => {
     const spawnOptions = {
       stdio: ["ignore", "pipe", "pipe"]
     };
@@ -1980,10 +3181,29 @@ function delegatedExec(secret, request) {
       stderr += data.toString();
     });
     proc.on("close", (code) => {
-      resolve2({ stdout, stderr, exitCode: code ?? 1 });
+      resolve3({
+        stdout: shouldRedact ? redactSecrets(stdout, secretValues) : stdout,
+        stderr: shouldRedact ? redactSecrets(stderr, secretValues) : stderr,
+        exitCode: code ?? 1
+      });
     });
     proc.on("error", (error) => {
-      reject(error);
+      const isEnoent = error instanceof Error && "code" in error && error.code === "ENOENT";
+      if (isEnoent) {
+        reject(
+          new ExecError(
+            `Command not found: ${request.command}. Verify the command exists and is in PATH.`,
+            request.command
+          )
+        );
+      } else {
+        reject(
+          new ExecError(
+            `Failed to execute command: ${request.command}. ${error instanceof Error ? error.message : String(error)}`,
+            request.command
+          )
+        );
+      }
     });
   });
 }
@@ -2002,12 +3222,14 @@ function createSecretAccessor(secretValue) {
   let consumed = false;
   function readImpl(callback) {
     if (consumed) {
-      throw new Error("SecretAccessor has already been consumed \u2014 call getSecret() again to obtain a new accessor");
+      throw new AccessorConsumedError(
+        "SecretAccessor has already been consumed \u2014 call getSecret() again to obtain a new accessor"
+      );
     }
     consumed = true;
     const buf = Buffer.from(secretValue, "utf8");
     try {
-      callback(buf);
+      return callback(buf);
     } finally {
       buf.fill(0);
     }
@@ -2069,51 +3291,65 @@ function createSecretAccessor(secretValue) {
   };
   return new Proxy(target, handler);
 }
-
-// src/access/sign-util.ts
-var ALLOWED_ALGORITHMS = /* @__PURE__ */ new Set(["sha256", "sha384", "sha512"]);
-function resolveAlgorithmForKey(key, override) {
-  const keyType = key.asymmetricKeyType;
-  if (keyType === "ed25519" || keyType === "ed448") {
-    return { signAlg: null, label: keyType };
-  }
-  const alg = (override ?? "sha256").toLowerCase();
-  if (!ALLOWED_ALGORITHMS.has(alg)) {
-    throw new InvalidAlgorithmError(
-      `Unsupported algorithm '${alg}'. Allowed: ${[...ALLOWED_ALGORITHMS].join(", ")}`,
-      alg,
-      [...ALLOWED_ALGORITHMS]
-    );
-  }
-  return { signAlg: alg, label: alg };
+var JWS_ALG = "EdDSA";
+function toBytes(data) {
+  return Buffer$1.isBuffer(data) ? data : Buffer$1.from(data, "utf8");
 }
-
-// src/access/delegated-sign.ts
-function delegatedSign(secretPem, request) {
-  const key = crypto.createPrivateKey(secretPem);
-  const { signAlg, label } = resolveAlgorithmForKey(key, request.algorithm);
-  const data = Buffer.isBuffer(request.data) ? request.data : Buffer.from(request.data);
-  const signature = crypto.sign(signAlg, data, key);
-  return {
-    signature: signature.toString("base64"),
-    algorithm: label
-  };
+function signingInput(protectedB64, payload) {
+  return Buffer$1.concat([Buffer$1.from(`${protectedB64}.`, "ascii"), payload]);
 }
-function delegatedVerify(request) {
-  let key;
+async function createDetachedJws(kid, payload, sign2) {
+  const header = { alg: JWS_ALG, b64: false, crit: ["b64"], kid };
+  const protectedB64 = Buffer$1.from(JSON.stringify(header), "utf8").toString("base64url");
+  const signature = await sign2(signingInput(protectedB64, toBytes(payload)));
+  return `${protectedB64}..${signature.toString("base64url")}`;
+}
+function hasExpectedHeader(header) {
+  if (typeof header !== "object" || header === null) {
+    return false;
+  }
+  const record = { ...header };
+  const crit = record.crit;
+  return record.alg === JWS_ALG && record.b64 === false && Array.isArray(crit) && crit.length === 1 && crit[0] === "b64";
+}
+async function verifyDetachedJws(request) {
+  const parts = request.jws.trim().split(".");
+  if (parts.length !== 3) {
+    return false;
+  }
+  const [protectedB64, middle, signatureB64] = parts;
+  if (protectedB64 === void 0 || signatureB64 === void 0 || middle !== "") {
+    return false;
+  }
+  let header;
   try {
-    key = crypto.createPublicKey(request.publicKey);
+    header = JSON.parse(Buffer$1.from(protectedB64, "base64url").toString("utf8"));
   } catch {
     return false;
   }
-  if (typeof request.publicKey === "string" && request.publicKey.includes("PRIVATE KEY")) {
+  if (!hasExpectedHeader(header)) {
     return false;
   }
-  const { signAlg } = resolveAlgorithmForKey(key, request.algorithm);
-  const sig = Buffer.from(request.signature, "base64");
+  if (request.publicKey.includes("PRIVATE KEY")) {
+    throw new InvalidKeyMaterialError(
+      "A private key was supplied where an SPKI public key is required."
+    );
+  }
+  let key;
+  try {
+    key = await importSPKI(request.publicKey, JWS_ALG);
+  } catch {
+    throw new InvalidKeyMaterialError(
+      "The supplied public key is not an SPKI PEM EdDSA public key."
+    );
+  }
   try {
-    const data = Buffer.isBuffer(request.data) ? request.data : Buffer.from(request.data);
-    return crypto.verify(signAlg, data, key, sig);
+    await flattenedVerify(
+      { protected: protectedB64, payload: toBytes(request.payload), signature: signatureB64 },
+      key,
+      { algorithms: [JWS_ALG] }
+    );
+    return true;
   } catch {
     return false;
   }
@@ -2172,10 +3408,7 @@ async function checkBash() {
 async function checkPowershell() {
   const name = "powershell";
   try {
-    const output = await execCommand("powershell", [
-      "-Command",
-      "$PSVersionTable.PSVersion"
-    ]);
+    const output = await execCommand("powershell", ["-Command", "$PSVersionTable.PSVersion"]);
     const version = output.trim();
     return { name, status: "ok", version };
   } catch {
@@ -2245,7 +3478,7 @@ function currentPlatform() {
   if (p === "darwin" || p === "win32" || p === "linux") {
     return p;
   }
-  throw new Error(`Unsupported platform: ${p}`);
+  throw new SetupError(`Unsupported platform: ${p}`, "platform");
 }
 
 // src/doctor/runner.ts
@@ -2261,7 +3494,25 @@ async function runDoctor(options) {
       nextSteps: ["Unsupported platform. vaultkeeper supports macOS, Linux, and Windows."]
     };
   }
-  const enabledTypes = enabledBackendTypes(options?.backends);
+  let backends = options?.backends;
+  let configCheck;
+  if (backends === void 0 && options?.configDir !== void 0) {
+    const configPath = path2.join(options.configDir, "config.json");
+    try {
+      const config = await loadConfig(options.configDir);
+      backends = config.backends;
+      configCheck = { name: "config", status: "ok", version: configPath, required: true };
+    } catch (err) {
+      configCheck = {
+        name: "config",
+        status: "invalid",
+        reason: err instanceof Error ? err.message : String(err),
+        error: toPreflightConfigError(err, configPath),
+        required: true
+      };
+    }
+  }
+  const enabledTypes = enabledBackendTypes(backends);
   const entries = buildCheckList(platform, enabledTypes);
   const resolved = await Promise.all(
     entries.map(async ({ check, required }) => {
@@ -2269,23 +3520,26 @@ async function runDoctor(options) {
       return { required, result };
     })
   );
-  const ready = resolved.every(({ required, result }) => {
+  const configReady = configCheck === void 0 || configCheck.status === "ok";
+  const ready = configReady && resolved.every(({ required, result }) => {
     if (!required) return true;
     return result.status === "ok";
   });
   const warnings = [];
   const nextSteps = [];
+  if (configCheck !== void 0 && configCheck.status !== "ok") {
+    nextSteps.push(configCheck.reason ?? "Config file is invalid.");
+  }
   for (const { required, result } of resolved) {
+    const reasonSuffix = result.reason !== void 0 ? ` \u2014 ${result.reason}` : "";
     if (result.status === "missing") {
       if (required) {
-        nextSteps.push(`Install missing required dependency: ${result.name}`);
+        nextSteps.push(`Install missing required dependency: ${result.name}${reasonSuffix}`);
       } else {
-        warnings.push(
-          `Optional dependency not found: ${result.name}${result.reason !== void 0 ? ` \u2014 ${result.reason}` : ""}`
-        );
+        warnings.push(`Optional dependency not found: ${result.name}${reasonSuffix}`);
       }
     } else if (result.status === "version-unsupported") {
-      const msg = `${result.name} version is unsupported${result.reason !== void 0 ? `: ${result.reason}` : ""}`;
+      const msg = `${result.name} version is unsupported${reasonSuffix}`;
       if (required) {
         nextSteps.push(`Upgrade required dependency: ${msg}`);
       } else {
@@ -2293,9 +3547,37 @@ async function runDoctor(options) {
       }
     }
   }
-  const checks = resolved.map(({ result }) => result);
+  const checks = [
+    ...configCheck !== void 0 ? [configCheck] : [],
+    ...resolved.map(({ required, result }) => ({ ...result, required }))
+  ];
   return { checks, ready, warnings, nextSteps };
 }
+function toPreflightConfigError(err, configPath) {
+  if (err instanceof ConfigParseError) {
+    return { kind: "config-parse", configPath: err.path, location: err.location };
+  }
+  if (err instanceof UnknownBackendTypeError) {
+    return {
+      kind: "config-unknown-backend",
+      configPath: err.configFilePath ?? configPath,
+      field: err.field,
+      backendType: err.backendType,
+      knownBackendTypes: err.knownTypes
+    };
+  }
+  if (err instanceof ConfigValidationError) {
+    return {
+      kind: "config-validation",
+      configPath: err.configFilePath ?? configPath,
+      field: err.field
+    };
+  }
+  if (err instanceof FilesystemError) {
+    return { kind: "config-read", configPath: err.path, code: err.code };
+  }
+  return void 0;
+}
 function enabledBackendTypes(backends) {
   if (backends === void 0) return null;
   const types = /* @__PURE__ */ new Set();
@@ -2336,83 +3618,290 @@ function buildCheckList(platform, enabledTypes) {
 }
 
 // src/vault.ts
+function createDefaultInjectedBackendConfig() {
+  return {
+    version: 1,
+    backends: [],
+    keyRotation: { gracePeriodDays: 7 },
+    defaults: { ttlMinutes: 60, trustTier: 3 }
+  };
+}
+var BUILTIN_SIGNING_BACKENDS = ["file"];
+var PRESENCE_PER_USE_QUALIFYING_BACKENDS = "A qualifying backend forces a distinct, fresh human action per operation \u2014 e.g. a YubiKey slot with a touch-per-operation policy or a gpg smartcard with touch-to-sign (both cover every operation), or 1Password in per-access mode (which enforces presence for reads only today, not writes). Switch to (or reconfigure) such a backend, or drop the presence requirement.";
 var usageCounts = /* @__PURE__ */ new Map();
 var USAGE_MAP_MAX_SIZE = 1e4;
 var VaultKeeper = class _VaultKeeper {
   #config;
   #keyManager;
   #configDir;
+  /**
+   * Whether key material is persisted to (and reloaded from) `#configDir`.
+   * Enabled only when the vault operates against a real on-disk config — i.e.
+   * neither `config` nor `backend` was injected in-process (see
+   * {@link VaultKeeper.init}). Injected-config/backend instances keep keys
+   * purely in memory so tests and embedders stay hermetic.
+   */
+  #persistKeys;
   #backend;
-  constructor(config, keyManager, configDir) {
+  /**
+   * Whether {@link #backend} was injected via `init({ backend })` rather than
+   * lazily resolved from `#config.backends`. Distinguishes the two so that
+   * {@link activeBackendType} reports the injected instance directly instead of
+   * consulting the (empty) config backend list. Stays correct after a lazy
+   * resolution populates {@link #backend} in the config-driven path.
+   */
+  #backendInjected;
+  constructor(config, keyManager, configDir, persistKeys, backend) {
     this.#config = config;
     this.#keyManager = keyManager;
     this.#configDir = configDir;
+    this.#persistKeys = persistKeys;
+    this.#backend = backend;
+    this.#backendInjected = backend !== void 0;
   }
   /**
    * 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 async init(options) {
     const configDir = options?.configDir ?? getDefaultConfigDir();
-    const config = options?.config ?? await loadConfig(configDir);
+    const config = options?.config ?? (options?.backend !== void 0 ? createDefaultInjectedBackendConfig() : await loadConfig(configDir));
     if (options?.skipDoctor !== true) {
       const doctorResult = await runDoctor({ backends: config.backends });
       if (!doctorResult.ready) {
-        throw new VaultError(
-          `System not ready: ${doctorResult.nextSteps.join("; ")}`
-        );
+        throw new VaultError(`System not ready: ${doctorResult.nextSteps.join("; ")}`);
       }
     }
+    const persistKeys = options?.config === void 0 && options?.backend === void 0;
     const keyManager = new KeyManager();
-    await keyManager.init();
-    const vault = new _VaultKeeper(config, keyManager, configDir);
-    vault.#backend = vault.#resolveBackend();
-    return vault;
+    if (persistKeys) {
+      const loaded = await loadKeyState(configDir);
+      if (loaded !== void 0) {
+        keyManager.hydrate(loaded);
+      } else {
+        await keyManager.init();
+        await saveKeyState(configDir, keyManager.snapshot());
+      }
+    } else {
+      await keyManager.init();
+    }
+    return new _VaultKeeper(config, keyManager, configDir, persistKeys, options?.backend);
   }
   /**
    * 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 async doctor() {
-    return runDoctor();
+  static async doctor(options) {
+    return runDoctor(options);
   }
   /**
-   * 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).
    *
-   * @param secretName - Identifier for the secret
-   * @param options - Setup options
+   * @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.
+   *
+   * 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() {
+    if (this.#backendInjected && this.#backend !== void 0) {
+      return _VaultKeeper.#resolveBackendTypeHint(this.#backend);
+    }
+    const firstEnabled = this.#config.backends.find((b) => b.enabled);
+    if (firstEnabled === void 0) {
+      throw new BackendUnavailableError(
+        "No enabled backends configured",
+        "none-enabled",
+        this.#config.backends.map((b) => b.type)
+      );
+    }
+    return firstEnabled.type;
+  }
+  /**
+   * 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
+   */
+  async getActiveBackendCapabilities() {
+    const backend = this.#requireBackend();
+    return getBackendCapabilities(backend);
+  }
+  /**
+   * 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
+   */
+  async store(name, value, options) {
+    _VaultKeeper.#validateName(name, "secret");
+    const backend = this.#requireBackend();
+    await this.#enforcePresenceRequirement(backend, "store", options?.requirePresencePerUse);
+    await backend.store(name, value);
+  }
+  /**
+   * 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
+   */
+  async delete(name, options) {
+    _VaultKeeper.#validateName(name, "secret", false);
+    const backend = this.#requireBackend();
+    await this.#enforcePresenceRequirement(backend, "delete", options?.requirePresencePerUse);
+    await backend.delete(name);
+  }
+  /**
+   * 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
+   */
+  async secretExists(name) {
+    _VaultKeeper.#validateName(name, "secret", false);
+    const backend = this.#requireBackend();
+    return backend.exists(name);
+  }
+  /**
+   * 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.
    */
   async setup(secretName, options) {
+    _VaultKeeper.#validateName(secretName, "secret");
     const backend = this.#requireBackend();
-    const backendType = options?.backendType ?? backend.type;
-    const ttlMinutes = options?.ttlMinutes ?? this.#config.defaults.ttlMinutes;
-    const trustTier = options?.trustTier ?? this.#config.defaults.trustTier;
-    const useLimit = options?.useLimit ?? null;
-    const executablePath = options?.executablePath ?? "dev";
+    const { exeIdentity, commit: commitExecutableTrust } = await this.#resolveExecutableIdentity(options);
+    await this.#enforcePresenceRequirement(backend, "read", options.requirePresencePerUse);
+    const backendType = _VaultKeeper.#resolveBackendTypeHint(backend, options.backendType);
+    const ttlMinutes = options.ttlMinutes ?? this.#config.defaults.ttlMinutes;
+    const trustTier = options.trustTier ?? this.#config.defaults.trustTier;
+    const useLimit = options.useLimit ?? null;
     const secretValue = await backend.retrieve(secretName);
-    let exeIdentity;
-    if (executablePath === "dev" || this.#isDevModeExecutable(executablePath)) {
-      exeIdentity = "dev";
-    } else {
-      const trustResult = await verifyTrust(executablePath, {
-        configDir: this.#configDir
-      });
-      if (trustResult.tofuConflict) {
-        throw new IdentityMismatchError(
-          "Executable hash changed \u2014 re-approval required",
-          "previously-approved",
-          trustResult.identity.hash
-        );
-      }
-      exeIdentity = trustResult.identity.hash;
-    }
     const now = Math.floor(Date.now() / 1e3);
     const claims = {
-      jti: crypto.randomUUID(),
+      jti: crypto2.randomUUID(),
       exp: now + ttlMinutes * 60,
       iat: now,
       sub: secretName,
@@ -2424,14 +3913,19 @@ var VaultKeeper = class _VaultKeeper {
       ref: secretName
     };
     const currentKey = this.#keyManager.getCurrentKey();
-    return createToken(currentKey.key, claims, { kid: currentKey.id });
+    const token = createToken(currentKey.key, claims, { kid: currentKey.id });
+    await commitExecutableTrust();
+    return token;
   }
   /**
    * 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.
    */
   async authorize(jwe) {
     const kid = extractKid(jwe);
@@ -2451,55 +3945,80 @@ var VaultKeeper = class _VaultKeeper {
       }
     }
     const token = createCapabilityToken(claims);
-    const response = { keyStatus };
+    const vaultResponse = { keyStatus };
     if (keyStatus === "previous") {
       const currentKey = this.#keyManager.getCurrentKey();
       const rotatedJwt = await createToken(currentKey.key, claims, { kid: currentKey.id });
-      response.rotatedJwt = rotatedJwt;
+      vaultResponse.rotatedJwt = rotatedJwt;
     }
-    return { token, response };
+    return { token, 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.
    */
   async fetch(token, request) {
-    const claims = validateCapabilityToken(token);
-    const response = await delegatedFetch(claims.val, request);
+    const secrets = _VaultKeeper.#resolveSecrets(token);
+    const response = await delegatedFetch(secrets, request);
     return {
       response,
       vaultResponse: { keyStatus: "current" }
     };
   }
   /**
-   * 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.
    */
   async exec(token, request) {
-    const claims = validateCapabilityToken(token);
-    const result = await delegatedExec(claims.val, request);
+    const secrets = _VaultKeeper.#resolveSecrets(token);
+    const result = await delegatedExec(secrets, request);
     return {
       result,
       vaultResponse: { keyStatus: "current" }
@@ -2514,58 +4033,218 @@ var VaultKeeper = 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) {
     const claims = validateCapabilityToken(token);
+    if (isSigningClaims(claims)) {
+      throw new AuthorizationDeniedError(
+        "This capability token authorizes a signing key, not a secret \u2014 it cannot be read with getSecret(). Use sign() instead."
+      );
+    }
     return createSecretAccessor(claims.val);
   }
   /**
-   * 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'`).
-   */
-  async sign(token, request) {
+   * @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
+   */
+  async createSigningKey(name, algorithm) {
+    _VaultKeeper.#validateName(name, "signing key");
+    const backend = this.#requireSigningBackend();
+    const id = _VaultKeeper.#signingKeyId(name);
+    await backend.generateSigningKey(id, algorithm);
+    return backend.getPublicKey(id);
+  }
+  /**
+   * 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
+   */
+  async exportPublicKey(name) {
+    _VaultKeeper.#validateName(name, "signing key");
+    const backend = this.#requireSigningBackend();
+    return backend.getPublicKey(_VaultKeeper.#signingKeyId(name));
+  }
+  /**
+   * 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
+   */
+  async authorizeSigningKey(name) {
+    _VaultKeeper.#validateName(name, "signing key");
+    const backend = this.#requireSigningBackend();
+    const id = _VaultKeeper.#signingKeyId(name);
+    const pub = await backend.getPublicKey(id);
+    return createSigningCapabilityToken({ keyType: "signing-key", kid: pub.kid, backendRef: id });
+  }
+  /**
+   * 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
+   */
+  async sign(token, request, options) {
     const claims = validateCapabilityToken(token);
-    const result = delegatedSign(claims.val, request);
-    await Promise.resolve();
+    if (!isSigningClaims(claims)) {
+      throw new AuthorizationDeniedError(
+        "sign() requires a signing-key capability token from authorizeSigningKey() \u2014 an ordinary secret token cannot be used to sign."
+      );
+    }
+    const backend = this.#requireSigningBackend();
+    await this.#enforcePresenceRequirement(backend, "sign", options?.requirePresencePerUse);
+    const jws = await createDetachedJws(
+      claims.kid,
+      request.payload,
+      (data) => backend.signWithKey(claims.backendRef, data)
+    );
     return {
-      result,
+      result: { jws },
       vaultResponse: { keyStatus: "current" }
     };
   }
   /**
-   * Verify a signature using a public key.
+   * Verify a detached-payload Compact JWS against a public key — fully offline.
    *
-   * 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.
+   * 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.
    *
-   * Returns `false` for invalid key material, malformed signatures, or
-   * any verification failure (except disallowed algorithms, which throw).
+   * 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.
    *
-   * @throws {InvalidAlgorithmError} If `request.algorithm` is not in the
-   *   allowed set (e.g. `'md5'`).
-   *
-   * @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 async verify(request) {
+    return verifyDetachedJws(request);
+  }
+  /**
+   * Resolve the active backend and assert it implements the signing contract.
+   * @throws {SigningNotSupportedError} If the active backend cannot sign.
+   */
+  #requireSigningBackend() {
+    const backend = this.#requireBackend();
+    if (!isSigningBackend(backend)) {
+      throw new SigningNotSupportedError(
+        `The active backend ('${backend.type}') does not implement the signing contract. The built-in '${BUILTIN_SIGNING_BACKENDS.join("', '")}' backend does, and a custom backend may implement SigningBackend.`,
+        backend.type,
+        [...BUILTIN_SIGNING_BACKENDS]
+      );
+    }
+    return backend;
+  }
+  /**
+   * Shared enforcement for a presence-per-use requirement, called at the top of
+   * every backend-touching access path ({@link VaultKeeper.store},
+   * {@link VaultKeeper.delete}, {@link VaultKeeper.setup}, {@link VaultKeeper.sign}).
+   *
+   * @remarks
+   * This is the single, non-bypassable point of enforcement — deliberately not
+   * duplicated per CLI command. When `require` is not `true` it is a no-op.
+   * Otherwise it queries the backend's capabilities **fresh on every call**
+   * (never cached across operations, so a prior satisfied call can never
+   * satisfy a later one) and throws {@link NotCapableError} — before the caller
+   * performs any credential/session/device operation — when the configured
+   * instance does not advertise {@link BackendCapabilities.presencePerUse}, **or**
+   * advertises it but does not force a fresh action for **this** `operation` (see
+   * {@link BackendCapabilities.presenceEnforcedOperations}). The latter makes
+   * enforcement operation-aware and fail-closed: e.g. 1Password `per-access`
+   * forces presence for reads but not `store`/`delete`, so a flagged write is
+   * refused here rather than silently passing through the cached session client.
+   *
+   * When the backend *is* capable for this operation, this returns and the
+   * caller proceeds to the backend's ordinary operation, which by the meaning of
+   * the capability forces a distinct fresh human action for this specific call.
+   * The presence action itself (and any {@link PresenceDeclinedError}/
+   * {@link PresenceTimeoutError}) therefore surfaces from that backend operation,
+   * not from here — so two consecutive required-presence operations each drive
+   * their own backend call and each demand their own fresh action.
+   *
+   * @throws {@link NotCapableError} If `require` is `true` and the backend either
+   *   is not presence-per-use capable or does not force presence for `operation`.
    */
-  static verify(request) {
-    return delegatedVerify(request);
+  async #enforcePresenceRequirement(backend, operation, require2) {
+    if (require2 !== true) {
+      return;
+    }
+    const capabilities = await getBackendCapabilities(backend);
+    if (!capabilities.presencePerUse) {
+      throw new NotCapableError(
+        `This operation required presence-per-use, but the active backend ('${backend.type}') cannot guarantee it. ${PRESENCE_PER_USE_QUALIFYING_BACKENDS}`,
+        backend.type,
+        "presencePerUse"
+      );
+    }
+    const enforced = capabilities.presenceEnforcedOperations;
+    if (enforced !== void 0 && !enforced.includes(operation)) {
+      throw new NotCapableError(
+        `This '${operation}' operation required presence-per-use, but the active backend ('${backend.type}') only enforces a fresh per-use action for [${enforced.join(", ")}] \u2014 not '${operation}'. ${PRESENCE_PER_USE_QUALIFYING_BACKENDS}`,
+        backend.type,
+        "presencePerUse"
+      );
+    }
+  }
+  /** Map a caller-facing signing key name to its namespaced backend id. */
+  static #signingKeyId(name) {
+    return `signing-key:${name}`;
   }
   /**
    * Rotate the current encryption key.
@@ -2581,7 +4260,7 @@ var VaultKeeper = class _VaultKeeper {
   async rotateKey() {
     const gracePeriodMs = this.#config.keyRotation.gracePeriodDays * 24 * 60 * 60 * 1e3;
     this.#keyManager.rotateKey(gracePeriodMs);
-    await Promise.resolve();
+    await this.#persistKeyState();
   }
   /**
    * Emergency key revocation — invalidates the previous key immediately.
@@ -2592,7 +4271,17 @@ var VaultKeeper = class _VaultKeeper {
    */
   async revokeKey() {
     this.#keyManager.revokeKey();
-    await Promise.resolve();
+    await this.#persistKeyState();
+  }
+  /**
+   * Persist the current key state to the config dir when persistence is
+   * enabled. A no-op for injected-config/backend instances (in-memory keys).
+   */
+  async #persistKeyState() {
+    if (!this.#persistKeys) {
+      return;
+    }
+    await saveKeyState(this.#configDir, this.#keyManager.snapshot());
   }
   /**
    * Add or remove an executable from the development-mode whitelist.
@@ -2622,9 +4311,135 @@ var VaultKeeper = class _VaultKeeper {
     }
     await Promise.resolve();
   }
+  /**
+   * 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
+   */
+  async approveExecutable(executablePath) {
+    const resolved = path2.resolve(executablePath);
+    const hash = await hashExecutable(resolved);
+    const manifest = await loadManifest(this.#configDir);
+    const updated = addTrustedHash(manifest, resolved, hash);
+    await saveManifest(this.#configDir, updated);
+    return {
+      trusted: true,
+      hash,
+      hashMismatch: false,
+      approvedHashes: updated.get(resolved)?.hashes ?? [hash],
+      reason: "Hash recorded in trust manifest"
+    };
+  }
+  /**
+   * 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
+   */
+  async checkExecutableTrust(executablePath) {
+    const resolved = path2.resolve(executablePath);
+    const hash = await hashExecutable(resolved);
+    const manifest = await loadManifest(this.#configDir);
+    const approvedHashes = manifest.get(resolved)?.hashes ?? [];
+    if (isTrusted(manifest, resolved, hash)) {
+      return {
+        trusted: true,
+        hash,
+        hashMismatch: false,
+        approvedHashes,
+        reason: "Hash found in trust manifest"
+      };
+    }
+    const hashMismatch = approvedHashes.length > 0;
+    return {
+      trusted: false,
+      hash,
+      hashMismatch,
+      approvedHashes,
+      reason: hashMismatch ? "Executable hash changed from a previously approved value \u2014 re-approval required" : "Executable not yet approved"
+    };
+  }
   // ---------------------------------------------------------------------------
   // Private helpers
   // ---------------------------------------------------------------------------
+  static #resolveSecrets(token) {
+    if (token instanceof CapabilityToken) {
+      return _VaultKeeper.#requireSecretClaims(token).val;
+    }
+    const result = {};
+    for (const [name, t] of Object.entries(token)) {
+      if (!(t instanceof CapabilityToken)) {
+        throw new AuthorizationDeniedError(
+          `Invalid capability token for secret "${name}" \u2014 expected a CapabilityToken from authorize()`
+        );
+      }
+      result[name] = _VaultKeeper.#requireSecretClaims(t).val;
+    }
+    return result;
+  }
+  /**
+   * Resolve a token to its secret claims, rejecting a signing-key token.
+   *
+   * Defense in depth: a signing-key capability must never be injectable as a
+   * secret through `fetch()`/`exec()`.
+   */
+  static #requireSecretClaims(token) {
+    const claims = validateCapabilityToken(token);
+    if (isSigningClaims(claims)) {
+      throw new AuthorizationDeniedError(
+        "This capability token authorizes a signing key, not a secret \u2014 it cannot be injected into fetch() or exec()."
+      );
+    }
+    return claims;
+  }
+  /**
+   * Validate a caller-supplied resource name. `kind` names the resource in the
+   * error so a signing-key caller is not told about a "secret".
+   *
+   * When `enforceReserved` is true (the default, used by name-creating/binding
+   * paths — `store`/`setup` and every signing-key operation), the name may not
+   * contain `':'`. The `signing-key:<name>` prefix is a reserved internal
+   * namespace, so forbidding `':'` at creation time is what actually enforces
+   * the documented guarantee that a secret and a signing key can never collide
+   * under one name — the CLI's name pattern already forbids `':'`, and this
+   * closes the same hole for direct library callers. Read/delete/existence
+   * paths pass `false` so a legacy secret whose name contains `':'` (stored
+   * before this rule, or seeded directly through a backend) stays reachable for
+   * inspection and cleanup.
+   */
+  static #validateName(name, kind, enforceReserved = true) {
+    const noun = kind === "secret" ? "Secret" : "Signing key";
+    if (name.trim() === "") {
+      throw new VaultError(`${noun} name must not be empty`);
+    }
+    if (enforceReserved && name.includes(":")) {
+      throw new VaultError(
+        `${noun} name must not contain ':'. The 'signing-key:' prefix is a reserved internal namespace, so a secret and a signing key can never collide under one name.`
+      );
+    }
+  }
   #resolveBackend() {
     const enabledBackends = this.#config.backends.filter((b) => b.enabled);
     if (enabledBackends.length === 0) {
@@ -2636,18 +4451,32 @@ var VaultKeeper = class _VaultKeeper {
     }
     const firstEnabled = enabledBackends[0];
     if (firstEnabled === void 0) {
-      throw new BackendUnavailableError(
-        "No enabled backends configured",
-        "none-enabled",
-        []
-      );
+      throw new BackendUnavailableError("No enabled backends configured", "none-enabled", []);
     }
-    return BackendRegistry.create(firstEnabled.type, firstEnabled);
+    return BackendRegistry.create(firstEnabled.type, firstEnabled, this.#configDir);
   }
-  #requireBackend() {
-    if (this.#backend === void 0) {
-      throw new VaultError("VaultKeeper backend not initialized");
+  /**
+   * Resolve the backend-type hint used both for introspection
+   * ({@link activeBackendType}) and for the `bkd` claim minted by
+   * {@link setup}. A non-blank `override` wins (trimmed); an empty or
+   * whitespace-only override is treated the same as no override, since
+   * honoring it would mint a token with a blank `bkd` claim. Otherwise the
+   * backend's declared `type` is used (trimmed), and a backend that declares
+   * an empty or whitespace-only type — permitted for injected backends —
+   * falls back to the stable `'custom'` sentinel. Centralizing this keeps
+   * both paths in sync so no route ever mints a token with an empty `bkd`
+   * claim (which {@link validateClaims} rejects, making the token unusable).
+   */
+  static #resolveBackendTypeHint(backend, override) {
+    const trimmedOverride = override?.trim();
+    if (trimmedOverride !== void 0 && trimmedOverride !== "") {
+      return trimmedOverride;
     }
+    const declared = backend.type.trim();
+    return declared === "" ? "custom" : declared;
+  }
+  #requireBackend() {
+    this.#backend ??= this.#resolveBackend();
     return this.#backend;
   }
   #isDevModeExecutable(executablePath) {
@@ -2656,6 +4485,69 @@ var VaultKeeper = class _VaultKeeper {
     }
     return this.#config.developmentMode.executables.includes(executablePath);
   }
+  /**
+   * Resolve the executable identity to embed in a minted token, enforcing that
+   * the caller made an explicit trust decision.
+   *
+   * Returns the sentinel `'dev'` (no executable binding) when trust is
+   * deliberately skipped or the path is on the development-mode allowlist;
+   * otherwise runs TOFU *verification only* and returns the verified hash
+   * together with a `commit` callback. Verification never writes to the trust
+   * manifest by itself — `commit` stages that write, and the caller
+   * ({@link VaultKeeper.setup}) must invoke it only after the operation trust
+   * was gating has actually succeeded. This is the fail-fast/defer-write split
+   * from issue #148: shape validation (missing/conflicting/legacy-sentinel)
+   * still throws immediately here, before any backend read, but a
+   * first-encounter or Sigstore hash is not durably recorded until `commit`
+   * runs.
+   *
+   * @throws {ExecutableTrustRequiredError} If neither `executablePath` nor
+   *   `skipTrust: true` is provided, if both are, or if `executablePath` is the
+   *   retired legacy `'dev'` opt-out sentinel.
+   * @throws {IdentityMismatchError} On a TOFU hash conflict. Conflicts never
+   *   stage a manifest write regardless of whether `commit` is later called.
+   */
+  async #resolveExecutableIdentity(options) {
+    const executablePath = options?.executablePath;
+    const skipTrust = options?.skipTrust === true;
+    const noCommit = () => Promise.resolve();
+    if (skipTrust && executablePath !== void 0) {
+      throw new ExecutableTrustRequiredError(
+        "VaultKeeper.setup() received both options.executablePath and options.skipTrust: true, which are mutually exclusive. Pass options.executablePath to verify the calling executable, or options.skipTrust: true to skip verification (development only) \u2014 not both.",
+        "conflicting-choice"
+      );
+    }
+    if (skipTrust) {
+      return { exeIdentity: "dev", commit: noCommit };
+    }
+    if (executablePath === void 0) {
+      throw new ExecutableTrustRequiredError(
+        "VaultKeeper.setup() requires an explicit executable-trust choice and no longer defaults to skipping verification. Either pass options.executablePath set to the calling executable's real path (runs trust-on-first-use verification), or set options.skipTrust: true to deliberately skip verification (development only).",
+        "missing-choice"
+      );
+    }
+    if (executablePath === "dev") {
+      throw new ExecutableTrustRequiredError(
+        "VaultKeeper.setup() no longer supports the legacy options.executablePath: 'dev' sentinel for skipping trust verification. Set options.skipTrust: true to deliberately skip verification (development only), or pass options.executablePath set to the calling executable's real path to verify it.",
+        "legacy-dev-sentinel"
+      );
+    }
+    if (this.#isDevModeExecutable(executablePath)) {
+      return { exeIdentity: "dev", commit: noCommit };
+    }
+    const pending = await verifyTrustPending(path2.resolve(executablePath), {
+      configDir: this.#configDir
+    });
+    if (pending.tofuConflict) {
+      const previousHash = pending.approvedHashes.at(-1) ?? pending.identity.hash;
+      throw new IdentityMismatchError(
+        "Executable hash changed \u2014 re-approval required",
+        previousHash,
+        pending.identity.hash
+      );
+    }
+    return { exeIdentity: pending.identity.hash, commit: () => commitTrust(pending) };
+  }
   async #decryptWithKeyResolution(jwe, kid) {
     if (kid !== void 0) {
       const key = this.#keyManager.findKeyById(kid);
@@ -2683,6 +4575,6 @@ var VaultKeeper = class _VaultKeeper {
   }
 };
 
-export { AuthorizationDeniedError, BackendLockedError, BackendRegistry, BackendUnavailableError, CapabilityToken, DeviceNotPresentError, FilesystemError, IdentityMismatchError, InvalidAlgorithmError, KeyRevokedError, KeyRotatedError, PluginNotFoundError, RotationInProgressError, SecretNotFoundError, SetupError, TokenExpiredError, TokenRevokedError, UsageLimitExceededError, VaultError, VaultKeeper, isListableBackend, runDoctor };
+export { AccessorConsumedError, AuthorizationDeniedError, BackendLockedError, BackendRegistry, BackendUnavailableError, CapabilityToken, ConfigParseError, ConfigValidationError, DecryptionError, DeviceNotPresentError, ExecError, ExecutableTrustRequiredError, FetchError, FilesystemError, IdentityMismatchError, InvalidAlgorithmError, InvalidKeyMaterialError, InvalidTokenError, KeyRevokedError, KeyRotatedError, NotCapableError, PluginNotFoundError, PresenceDeclinedError, PresenceTimeoutError, REDACTED, RotationInProgressError, SecretNotFoundError, SetupError, SigningKeyAlreadyExistsError, SigningKeyNotFoundError, SigningNotSupportedError, TokenExpiredError, TokenRevokedError, UnknownBackendTypeError, UsageLimitExceededError, VaultError, VaultKeeper, defaultBackendType, getBackendCapabilities, getDefaultConfigDir, getPlatformDefaultConfigDir, isListableBackend, isPresenceCapableBackend, isSigningBackend, loadConfig, platformNativeBackendType, redactSecrets, runDoctor };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map