vaultkeeper 0.5.3 → 0.6.0

package/dist/index.d.cts

@@ -134,9 +134,43 @@ declare class IdentityMismatchError extends VaultError {
     readonly currentHash: string;
     constructor(message: string, previousHash: string, currentHash: string);
 }
+/**
+ * Thrown when a delegated `exec()` call fails due to a process-level error
+ * (e.g. the command binary is not found or cannot be spawned).
+ *
+ * @public
+ */
+declare class ExecError extends VaultError {
+    /**
+     * The command that failed to execute.
+     */
+    readonly command: string;
+    constructor(message: string, command: string);
+}
+/**
+ * Thrown when a JWE string cannot be parsed because it is structurally
+ * malformed (e.g. wrong number of segments, invalid Base64URL header,
+ * or unparseable JSON header).
+ *
+ * @public
+ */
+declare class InvalidTokenError extends VaultError {
+    constructor(message: string);
+}
+/**
+ * Thrown when `SecretAccessor.read()` is called after the accessor has
+ * already been consumed.
+ *
+ * @public
+ */
+declare class AccessorConsumedError extends VaultError {
+    constructor(message: string);
+}
 /**
  * Thrown when a caller requests a signing/verification algorithm that is not
  * in the allowed set (e.g. `'md5'`).
+ *
+ * @public
  */
 declare class InvalidAlgorithmError extends VaultError {
     /**
@@ -609,6 +643,45 @@ declare class CapabilityToken {
     toString(): string;
 }
 
+/**
+ * Platform detection utilities.
+ */
+/**
+ * The OS platform identifier used for platform-specific behavior.
+ * @public
+ */
+type Platform = 'darwin' | 'win32' | 'linux';
+
+/**
+ * Doctor runner: orchestrates platform-appropriate checks and aggregates results.
+ */
+
+/**
+ * Options for running the doctor.
+ * @public
+ */
+interface RunDoctorOptions {
+    /** Override the platform detection (useful for testing). */
+    platform?: Platform;
+    /**
+     * When provided, doctor checks are scoped to the given backends.
+     * Platform-native dependency checks (e.g. `secret-tool`, `security`,
+     * `powershell`) are demoted from required to optional when the
+     * corresponding backend is not enabled. Plugin tool checks (`op`,
+     * `ykman`) are promoted from optional to required when their backend
+     * (`1password`, `yubikey`) is explicitly enabled.
+     *
+     * When omitted, all platform-default checks are treated as required
+     * (backward-compatible behavior).
+     */
+    backends?: BackendConfig[];
+}
+/**
+ * Run all platform-appropriate preflight checks and aggregate the results.
+ * @public
+ */
+declare function runDoctor(options?: RunDoctorOptions): Promise<PreflightResult>;
+
 /**
  * VaultKeeper main class — wires together all vaultkeeper subsystems.
  */
@@ -650,13 +723,37 @@ declare class VaultKeeper {
     /**
      * Run doctor checks without full initialization.
      *
-     * Uses conservative platform defaults — all platform-native dependency
-     * checks are treated as required regardless of any backend configuration.
-     * For config-aware scoping, call `runDoctor({ backends })` directly.
+     * When called without arguments, uses conservative platform defaults —
+     * all platform-native dependency checks are treated as required. Pass
+     * `{ backends }` to scope checks to only the backends you plan to use.
+     *
+     * @param options - Optional doctor options (e.g. `{ backends }` to scope checks).
+     */
+    static doctor(options?: RunDoctorOptions): Promise<PreflightResult>;
+    /**
+     * 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.
+     * @param value - The secret value to store.
+     * @public
+     */
+    store(name: string, value: string): Promise<void>;
+    /**
+     * Delete a secret from the configured backend.
+     *
+     * This is a convenience method that delegates to the active backend's
+     * `delete()` method.
+     *
+     * @param name - Identifier for the secret to delete.
+     * @public
      */
-    static doctor(): Promise<PreflightResult>;
+    delete(name: string): Promise<void>;
     /**
-     * Retrieve a secret from the backend and return a JWE token that encapsulates it.
+     * Read a stored secret from the backend and mint a JWE token that encapsulates it.
      *
      * @param secretName - Identifier for the secret
      * @param options - Setup options
@@ -668,11 +765,14 @@ declare class VaultKeeper {
      * an opaque CapabilityToken.
      *
      * @param jwe - Compact JWE string from setup()
-     * @returns Opaque capability token for use with fetch/exec/getSecret
+     * @returns Object containing an opaque {@link CapabilityToken} for use with
+     *   fetch/exec/getSecret, and a {@link VaultResponse} describing key status.
+     *   When the JWE was decrypted with a non-current key,
+     *   `vaultResponse.rotatedJwt` contains a re-encrypted JWE for the current key.
      */
     authorize(jwe: string): Promise<{
         token: CapabilityToken;
-        response: VaultResponse;
+        vaultResponse: VaultResponse;
     }>;
     /**
      * Execute a delegated HTTP fetch, injecting the secret from the token.
@@ -799,43 +899,4 @@ declare class VaultKeeper {
     setDevelopmentMode(executablePath: string, enabled: boolean): Promise<void>;
 }
 
-/**
- * Platform detection utilities.
- */
-/**
- * The OS platform identifier used for platform-specific behavior.
- * @public
- */
-type Platform = 'darwin' | 'win32' | 'linux';
-
-/**
- * Doctor runner: orchestrates platform-appropriate checks and aggregates results.
- */
-
-/**
- * Options for running the doctor.
- * @public
- */
-interface RunDoctorOptions {
-    /** Override the platform detection (useful for testing). */
-    platform?: Platform;
-    /**
-     * When provided, doctor checks are scoped to the given backends.
-     * Platform-native dependency checks (e.g. `secret-tool`, `security`,
-     * `powershell`) are demoted from required to optional when the
-     * corresponding backend is not enabled. Plugin tool checks (`op`,
-     * `ykman`) are promoted from optional to required when their backend
-     * (`1password`, `yubikey`) is explicitly enabled.
-     *
-     * When omitted, all platform-default checks are treated as required
-     * (backward-compatible behavior).
-     */
-    backends?: BackendConfig[];
-}
-/**
- * Run all platform-appropriate preflight checks and aggregate the results.
- * @public
- */
-declare function runDoctor(options?: RunDoctorOptions): Promise<PreflightResult>;
-
-export { AuthorizationDeniedError, type BackendConfig, type BackendFactory, BackendLockedError, BackendRegistry, type BackendSetupFactory, BackendUnavailableError, CapabilityToken, DeviceNotPresentError, type ExecRequest, type ExecResult, type FetchRequest, FilesystemError, IdentityMismatchError, InvalidAlgorithmError, KeyRevokedError, KeyRotatedError, type KeyStatus, type ListableBackend, type Platform, PluginNotFoundError, type PreflightCheck, type PreflightCheckStatus, type PreflightResult, RotationInProgressError, type RunDoctorOptions, type SecretAccessor, type SecretBackend, SecretNotFoundError, type SetupChoice, SetupError, type SetupOptions, type SetupQuestion, type SetupResult, type SignRequest, type SignResult, TokenExpiredError, TokenRevokedError, type TrustTier, UsageLimitExceededError, type VaultConfig, VaultError, VaultKeeper, type VaultKeeperOptions, type VaultResponse, type VerifyRequest, isListableBackend, runDoctor };
+export { AccessorConsumedError, AuthorizationDeniedError, type BackendConfig, type BackendFactory, BackendLockedError, BackendRegistry, type BackendSetupFactory, BackendUnavailableError, CapabilityToken, DeviceNotPresentError, ExecError, type ExecRequest, type ExecResult, type FetchRequest, FilesystemError, IdentityMismatchError, InvalidAlgorithmError, InvalidTokenError, KeyRevokedError, KeyRotatedError, type KeyStatus, type ListableBackend, type Platform, PluginNotFoundError, type PreflightCheck, type PreflightCheckStatus, type PreflightResult, RotationInProgressError, type RunDoctorOptions, type SecretAccessor, type SecretBackend, SecretNotFoundError, type SetupChoice, SetupError, type SetupOptions, type SetupQuestion, type SetupResult, type SignRequest, type SignResult, TokenExpiredError, TokenRevokedError, type TrustTier, UsageLimitExceededError, type VaultConfig, VaultError, VaultKeeper, type VaultKeeperOptions, type VaultResponse, type VerifyRequest, isListableBackend, runDoctor };

package/dist/index.d.ts

@@ -134,9 +134,43 @@ declare class IdentityMismatchError extends VaultError {
     readonly currentHash: string;
     constructor(message: string, previousHash: string, currentHash: string);
 }
+/**
+ * Thrown when a delegated `exec()` call fails due to a process-level error
+ * (e.g. the command binary is not found or cannot be spawned).
+ *
+ * @public
+ */
+declare class ExecError extends VaultError {
+    /**
+     * The command that failed to execute.
+     */
+    readonly command: string;
+    constructor(message: string, command: string);
+}
+/**
+ * Thrown when a JWE string cannot be parsed because it is structurally
+ * malformed (e.g. wrong number of segments, invalid Base64URL header,
+ * or unparseable JSON header).
+ *
+ * @public
+ */
+declare class InvalidTokenError extends VaultError {
+    constructor(message: string);
+}
+/**
+ * Thrown when `SecretAccessor.read()` is called after the accessor has
+ * already been consumed.
+ *
+ * @public
+ */
+declare class AccessorConsumedError extends VaultError {
+    constructor(message: string);
+}
 /**
  * Thrown when a caller requests a signing/verification algorithm that is not
  * in the allowed set (e.g. `'md5'`).
+ *
+ * @public
  */
 declare class InvalidAlgorithmError extends VaultError {
     /**
@@ -609,6 +643,45 @@ declare class CapabilityToken {
     toString(): string;
 }
 
+/**
+ * Platform detection utilities.
+ */
+/**
+ * The OS platform identifier used for platform-specific behavior.
+ * @public
+ */
+type Platform = 'darwin' | 'win32' | 'linux';
+
+/**
+ * Doctor runner: orchestrates platform-appropriate checks and aggregates results.
+ */
+
+/**
+ * Options for running the doctor.
+ * @public
+ */
+interface RunDoctorOptions {
+    /** Override the platform detection (useful for testing). */
+    platform?: Platform;
+    /**
+     * When provided, doctor checks are scoped to the given backends.
+     * Platform-native dependency checks (e.g. `secret-tool`, `security`,
+     * `powershell`) are demoted from required to optional when the
+     * corresponding backend is not enabled. Plugin tool checks (`op`,
+     * `ykman`) are promoted from optional to required when their backend
+     * (`1password`, `yubikey`) is explicitly enabled.
+     *
+     * When omitted, all platform-default checks are treated as required
+     * (backward-compatible behavior).
+     */
+    backends?: BackendConfig[];
+}
+/**
+ * Run all platform-appropriate preflight checks and aggregate the results.
+ * @public
+ */
+declare function runDoctor(options?: RunDoctorOptions): Promise<PreflightResult>;
+
 /**
  * VaultKeeper main class — wires together all vaultkeeper subsystems.
  */
@@ -650,13 +723,37 @@ declare class VaultKeeper {
     /**
      * Run doctor checks without full initialization.
      *
-     * Uses conservative platform defaults — all platform-native dependency
-     * checks are treated as required regardless of any backend configuration.
-     * For config-aware scoping, call `runDoctor({ backends })` directly.
+     * When called without arguments, uses conservative platform defaults —
+     * all platform-native dependency checks are treated as required. Pass
+     * `{ backends }` to scope checks to only the backends you plan to use.
+     *
+     * @param options - Optional doctor options (e.g. `{ backends }` to scope checks).
+     */
+    static doctor(options?: RunDoctorOptions): Promise<PreflightResult>;
+    /**
+     * 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.
+     * @param value - The secret value to store.
+     * @public
+     */
+    store(name: string, value: string): Promise<void>;
+    /**
+     * Delete a secret from the configured backend.
+     *
+     * This is a convenience method that delegates to the active backend's
+     * `delete()` method.
+     *
+     * @param name - Identifier for the secret to delete.
+     * @public
      */
-    static doctor(): Promise<PreflightResult>;
+    delete(name: string): Promise<void>;
     /**
-     * Retrieve a secret from the backend and return a JWE token that encapsulates it.
+     * Read a stored secret from the backend and mint a JWE token that encapsulates it.
      *
      * @param secretName - Identifier for the secret
      * @param options - Setup options
@@ -668,11 +765,14 @@ declare class VaultKeeper {
      * an opaque CapabilityToken.
      *
      * @param jwe - Compact JWE string from setup()
-     * @returns Opaque capability token for use with fetch/exec/getSecret
+     * @returns Object containing an opaque {@link CapabilityToken} for use with
+     *   fetch/exec/getSecret, and a {@link VaultResponse} describing key status.
+     *   When the JWE was decrypted with a non-current key,
+     *   `vaultResponse.rotatedJwt` contains a re-encrypted JWE for the current key.
      */
     authorize(jwe: string): Promise<{
         token: CapabilityToken;
-        response: VaultResponse;
+        vaultResponse: VaultResponse;
     }>;
     /**
      * Execute a delegated HTTP fetch, injecting the secret from the token.
@@ -799,43 +899,4 @@ declare class VaultKeeper {
     setDevelopmentMode(executablePath: string, enabled: boolean): Promise<void>;
 }
 
-/**
- * Platform detection utilities.
- */
-/**
- * The OS platform identifier used for platform-specific behavior.
- * @public
- */
-type Platform = 'darwin' | 'win32' | 'linux';
-
-/**
- * Doctor runner: orchestrates platform-appropriate checks and aggregates results.
- */
-
-/**
- * Options for running the doctor.
- * @public
- */
-interface RunDoctorOptions {
-    /** Override the platform detection (useful for testing). */
-    platform?: Platform;
-    /**
-     * When provided, doctor checks are scoped to the given backends.
-     * Platform-native dependency checks (e.g. `secret-tool`, `security`,
-     * `powershell`) are demoted from required to optional when the
-     * corresponding backend is not enabled. Plugin tool checks (`op`,
-     * `ykman`) are promoted from optional to required when their backend
-     * (`1password`, `yubikey`) is explicitly enabled.
-     *
-     * When omitted, all platform-default checks are treated as required
-     * (backward-compatible behavior).
-     */
-    backends?: BackendConfig[];
-}
-/**
- * Run all platform-appropriate preflight checks and aggregate the results.
- * @public
- */
-declare function runDoctor(options?: RunDoctorOptions): Promise<PreflightResult>;
-
-export { AuthorizationDeniedError, type BackendConfig, type BackendFactory, BackendLockedError, BackendRegistry, type BackendSetupFactory, BackendUnavailableError, CapabilityToken, DeviceNotPresentError, type ExecRequest, type ExecResult, type FetchRequest, FilesystemError, IdentityMismatchError, InvalidAlgorithmError, KeyRevokedError, KeyRotatedError, type KeyStatus, type ListableBackend, type Platform, PluginNotFoundError, type PreflightCheck, type PreflightCheckStatus, type PreflightResult, RotationInProgressError, type RunDoctorOptions, type SecretAccessor, type SecretBackend, SecretNotFoundError, type SetupChoice, SetupError, type SetupOptions, type SetupQuestion, type SetupResult, type SignRequest, type SignResult, TokenExpiredError, TokenRevokedError, type TrustTier, UsageLimitExceededError, type VaultConfig, VaultError, VaultKeeper, type VaultKeeperOptions, type VaultResponse, type VerifyRequest, isListableBackend, runDoctor };
+export { AccessorConsumedError, AuthorizationDeniedError, type BackendConfig, type BackendFactory, BackendLockedError, BackendRegistry, type BackendSetupFactory, BackendUnavailableError, CapabilityToken, DeviceNotPresentError, ExecError, type ExecRequest, type ExecResult, type FetchRequest, FilesystemError, IdentityMismatchError, InvalidAlgorithmError, InvalidTokenError, KeyRevokedError, KeyRotatedError, type KeyStatus, type ListableBackend, type Platform, PluginNotFoundError, type PreflightCheck, type PreflightCheckStatus, type PreflightResult, RotationInProgressError, type RunDoctorOptions, type SecretAccessor, type SecretBackend, SecretNotFoundError, type SetupChoice, SetupError, type SetupOptions, type SetupQuestion, type SetupResult, type SignRequest, type SignResult, TokenExpiredError, TokenRevokedError, type TrustTier, UsageLimitExceededError, type VaultConfig, VaultError, VaultKeeper, type VaultKeeperOptions, type VaultResponse, type VerifyRequest, isListableBackend, runDoctor };

package/dist/index.js

@@ -139,6 +139,29 @@ var IdentityMismatchError = class extends VaultError {
     this.currentHash = currentHash;
   }
 };
+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.
@@ -470,7 +493,17 @@ function execCommandFull(command, args, options) {
       resolve2({ stdout, stderr, exitCode: code ?? 1 });
     });
     proc.on("error", (error) => {
-      reject(error);
+      if ("code" in error && error.code === "ENOENT") {
+        reject(
+          new PluginNotFoundError(
+            `'${command}' is not installed or not found in PATH`,
+            command,
+            ""
+          )
+        );
+      } else {
+        reject(error);
+      }
     });
   });
 }
@@ -1810,40 +1843,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;
@@ -1958,6 +1991,12 @@ function replaceInRecord2(record, secret) {
   return result;
 }
 function delegatedExec(secret, request) {
+  if (request.command.includes(PLACEHOLDER2)) {
+    throw new ExecError(
+      `The {{secret}} placeholder is not supported in the command field. Use args or env instead.`,
+      request.command
+    );
+  }
   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) => {
@@ -1983,7 +2022,22 @@ function delegatedExec(secret, request) {
       resolve2({ stdout, 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,7 +2056,7 @@ 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");
@@ -2276,16 +2330,15 @@ async function runDoctor(options) {
   const warnings = [];
   const nextSteps = [];
   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 {
@@ -2372,21 +2425,54 @@ var VaultKeeper = class _VaultKeeper {
   /**
    * Run doctor checks without full initialization.
    *
-   * Uses conservative platform defaults — all platform-native dependency
-   * checks are treated as required regardless of any backend configuration.
-   * For config-aware scoping, call `runDoctor({ backends })` directly.
+   * When called without arguments, uses conservative platform defaults —
+   * all platform-native dependency checks are treated as required. Pass
+   * `{ backends }` to scope checks to only the backends you plan to use.
+   *
+   * @param options - Optional doctor options (e.g. `{ backends }` to scope checks).
+   */
+  static async doctor(options) {
+    return runDoctor(options);
+  }
+  /**
+   * 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.
+   * @param value - The secret value to store.
+   * @public
+   */
+  async store(name, value) {
+    _VaultKeeper.#validateSecretName(name);
+    const backend = this.#requireBackend();
+    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.
+   * @public
    */
-  static async doctor() {
-    return runDoctor();
+  async delete(name) {
+    _VaultKeeper.#validateSecretName(name);
+    const backend = this.#requireBackend();
+    await backend.delete(name);
   }
   /**
-   * Retrieve a secret from the backend and return a JWE token that encapsulates it.
+   * Read a stored secret from the backend and mint a JWE token that encapsulates it.
    *
    * @param secretName - Identifier for the secret
    * @param options - Setup options
    * @returns Compact JWE string
    */
   async setup(secretName, options) {
+    _VaultKeeper.#validateSecretName(secretName);
     const backend = this.#requireBackend();
     const backendType = options?.backendType ?? backend.type;
     const ttlMinutes = options?.ttlMinutes ?? this.#config.defaults.ttlMinutes;
@@ -2431,7 +2517,10 @@ var VaultKeeper = class _VaultKeeper {
    * 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,13 +2540,13 @@ 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.
@@ -2625,6 +2714,11 @@ var VaultKeeper = class _VaultKeeper {
   // ---------------------------------------------------------------------------
   // Private helpers
   // ---------------------------------------------------------------------------
+  static #validateSecretName(name) {
+    if (name.trim() === "") {
+      throw new VaultError("Secret name must not be empty");
+    }
+  }
   #resolveBackend() {
     const enabledBackends = this.#config.backends.filter((b) => b.enabled);
     if (enabledBackends.length === 0) {
@@ -2683,6 +2777,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, DeviceNotPresentError, ExecError, FilesystemError, IdentityMismatchError, InvalidAlgorithmError, InvalidTokenError, KeyRevokedError, KeyRotatedError, PluginNotFoundError, RotationInProgressError, SecretNotFoundError, SetupError, TokenExpiredError, TokenRevokedError, UsageLimitExceededError, VaultError, VaultKeeper, isListableBackend, runDoctor };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map