vaultkeeper 0.5.3 → 0.6.0

package/dist/index.cjs

@@ -164,6 +164,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.
@@ -495,7 +518,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);
+      }
     });
   });
 }
@@ -1835,40 +1868,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;
@@ -1983,6 +2016,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) => {
@@ -2008,7 +2047,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
+          )
+        );
+      }
     });
   });
 }
@@ -2027,7 +2081,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");
@@ -2301,16 +2355,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 {
@@ -2397,21 +2450,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;
@@ -2456,7 +2542,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);
@@ -2476,13 +2565,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.
@@ -2650,6 +2739,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) {
@@ -2708,15 +2802,18 @@ var VaultKeeper = class _VaultKeeper {
   }
 };
 
+exports.AccessorConsumedError = AccessorConsumedError;
 exports.AuthorizationDeniedError = AuthorizationDeniedError;
 exports.BackendLockedError = BackendLockedError;
 exports.BackendRegistry = BackendRegistry;
 exports.BackendUnavailableError = BackendUnavailableError;
 exports.CapabilityToken = CapabilityToken;
 exports.DeviceNotPresentError = DeviceNotPresentError;
+exports.ExecError = ExecError;
 exports.FilesystemError = FilesystemError;
 exports.IdentityMismatchError = IdentityMismatchError;
 exports.InvalidAlgorithmError = InvalidAlgorithmError;
+exports.InvalidTokenError = InvalidTokenError;
 exports.KeyRevokedError = KeyRevokedError;
 exports.KeyRotatedError = KeyRotatedError;
 exports.PluginNotFoundError = PluginNotFoundError;