vaultkeeper 0.4.0 → 1.0.0

package/dist/index.d.cts

@@ -134,6 +134,21 @@ declare class IdentityMismatchError extends VaultError {
     readonly currentHash: string;
     constructor(message: string, previousHash: string, currentHash: string);
 }
+/**
+ * Thrown when a caller requests a signing/verification algorithm that is not
+ * in the allowed set (e.g. `'md5'`).
+ */
+declare class InvalidAlgorithmError extends VaultError {
+    /**
+     * The algorithm that was requested.
+     */
+    readonly algorithm: string;
+    /**
+     * The set of algorithms that are allowed.
+     */
+    readonly allowed: string[];
+    constructor(message: string, algorithm: string, allowed: string[]);
+}
 /**
  * Thrown during initialization when a required system dependency (e.g. OpenSSL
  * or a native credential helper) is missing or incompatible.
@@ -377,6 +392,8 @@ interface BackendConfig {
     plugin?: boolean | undefined;
     /** Filesystem path used by file-based backends. */
     path?: string | undefined;
+    /** Backend-specific options collected during interactive setup. */
+    options?: Record<string, string> | undefined;
 }
 
 /**
@@ -449,6 +466,47 @@ interface ListableBackend extends SecretBackend {
  */
 declare function isListableBackend(backend: SecretBackend): backend is ListableBackend;
 
+/**
+ * Types for the backend setup protocol.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A question yielded by a backend setup generator.
+ * @public
+ */
+interface SetupQuestion {
+    /** Machine key for BackendConfig.options */
+    readonly key: string;
+    /** Human-readable prompt */
+    readonly prompt: string;
+    /** Present for selection questions; when absent, the answer is a free-form string. */
+    readonly choices?: readonly SetupChoice[];
+}
+/**
+ * A choice within a setup question.
+ * @public
+ */
+interface SetupChoice {
+    /** Persisted value */
+    readonly value: string;
+    /** Display label */
+    readonly label: string;
+}
+/**
+ * Result returned when a backend setup generator completes.
+ * @public
+ */
+interface SetupResult {
+    /** Merge into BackendConfig.options */
+    readonly options: Record<string, string>;
+}
+/**
+ * Factory that creates a backend setup generator.
+ * @public
+ */
+type BackendSetupFactory = () => AsyncGenerator<SetupQuestion, SetupResult, string>;
+
 /**
  * Registry for secret backend implementations.
  *
@@ -469,6 +527,7 @@ declare function isListableBackend(backend: SecretBackend): backend is ListableB
  */
 declare class BackendRegistry {
     private static backends;
+    private static setups;
     /**
      * Register a backend factory.
      * @param type - Backend type identifier
@@ -479,7 +538,7 @@ declare class BackendRegistry {
      * Create a backend instance by type.
      * @param type - Backend type identifier
      * @returns A SecretBackend instance
-     * @throws Error if the backend type is not registered
+     * @throws {@link BackendUnavailableError} if the backend type is not registered
      */
     static create(type: string): SecretBackend;
     /**
@@ -500,6 +559,36 @@ declare class BackendRegistry {
      * @public
      */
     static getAvailableTypes(): Promise<string[]>;
+    /**
+     * Register a setup factory for a backend type.
+     * @param type - Backend type identifier
+     * @param factory - Factory function that creates a setup generator
+     */
+    static registerSetup(type: string, factory: BackendSetupFactory): void;
+    /**
+     * Get the setup factory for a backend type, if one is registered.
+     * @param type - Backend type identifier
+     * @returns The setup factory, or `undefined` if none is registered
+     */
+    static getSetup(type: string): BackendSetupFactory | undefined;
+    /**
+     * Check whether a setup factory is registered for the given backend type.
+     * @param type - Backend type identifier
+     * @returns `true` if a setup factory is registered
+     */
+    static hasSetup(type: string): boolean;
+    /**
+     * Clear all registered backend factories.
+     * Intended for use in tests only.
+     * @internal
+     */
+    static clearBackends(): void;
+    /**
+     * Clear all registered setup factories.
+     * Intended for use in tests only.
+     * @internal
+     */
+    static clearSetups(): void;
 }
 
 /**
@@ -645,6 +734,8 @@ declare class VaultKeeper {
      *   with the vault metadata (`vaultResponse`).
      * @throws {VaultError} If `token` is invalid or was not created by this
      *   vault instance.
+     * @throws {InvalidAlgorithmError} If `request.algorithm` is not in the
+     *   allowed set (e.g. `'md5'`).
      */
     sign(token: CapabilityToken, request: SignRequest): Promise<{
         result: SignResult;
@@ -657,8 +748,11 @@ declare class VaultKeeper {
      * capability tokens are required. It is safe to call from CI or any
      * context that has access to public key material.
      *
-     * Never throws. Returns `false` for invalid key material, malformed
-     * signatures, or any verification failure.
+     * Returns `false` for invalid key material, malformed signatures, or
+     * any verification failure (except disallowed algorithms, which throw).
+     *
+     * @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.
@@ -700,4 +794,4 @@ declare class VaultKeeper {
     setDevelopmentMode(executablePath: string, enabled: boolean): Promise<void>;
 }
 
-export { AuthorizationDeniedError, type BackendConfig, type BackendFactory, BackendLockedError, BackendRegistry, BackendUnavailableError, CapabilityToken, DeviceNotPresentError, type ExecRequest, type ExecResult, type FetchRequest, FilesystemError, IdentityMismatchError, KeyRevokedError, KeyRotatedError, type KeyStatus, type ListableBackend, PluginNotFoundError, type PreflightCheck, type PreflightCheckStatus, type PreflightResult, RotationInProgressError, type SecretAccessor, type SecretBackend, SecretNotFoundError, SetupError, type SetupOptions, type SignRequest, type SignResult, TokenExpiredError, TokenRevokedError, type TrustTier, UsageLimitExceededError, type VaultConfig, VaultError, VaultKeeper, type VaultKeeperOptions, type VaultResponse, type VerifyRequest, isListableBackend };
+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, PluginNotFoundError, type PreflightCheck, type PreflightCheckStatus, type PreflightResult, RotationInProgressError, 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 };

package/dist/index.d.ts

@@ -134,6 +134,21 @@ declare class IdentityMismatchError extends VaultError {
     readonly currentHash: string;
     constructor(message: string, previousHash: string, currentHash: string);
 }
+/**
+ * Thrown when a caller requests a signing/verification algorithm that is not
+ * in the allowed set (e.g. `'md5'`).
+ */
+declare class InvalidAlgorithmError extends VaultError {
+    /**
+     * The algorithm that was requested.
+     */
+    readonly algorithm: string;
+    /**
+     * The set of algorithms that are allowed.
+     */
+    readonly allowed: string[];
+    constructor(message: string, algorithm: string, allowed: string[]);
+}
 /**
  * Thrown during initialization when a required system dependency (e.g. OpenSSL
  * or a native credential helper) is missing or incompatible.
@@ -377,6 +392,8 @@ interface BackendConfig {
     plugin?: boolean | undefined;
     /** Filesystem path used by file-based backends. */
     path?: string | undefined;
+    /** Backend-specific options collected during interactive setup. */
+    options?: Record<string, string> | undefined;
 }
 
 /**
@@ -449,6 +466,47 @@ interface ListableBackend extends SecretBackend {
  */
 declare function isListableBackend(backend: SecretBackend): backend is ListableBackend;
 
+/**
+ * Types for the backend setup protocol.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A question yielded by a backend setup generator.
+ * @public
+ */
+interface SetupQuestion {
+    /** Machine key for BackendConfig.options */
+    readonly key: string;
+    /** Human-readable prompt */
+    readonly prompt: string;
+    /** Present for selection questions; when absent, the answer is a free-form string. */
+    readonly choices?: readonly SetupChoice[];
+}
+/**
+ * A choice within a setup question.
+ * @public
+ */
+interface SetupChoice {
+    /** Persisted value */
+    readonly value: string;
+    /** Display label */
+    readonly label: string;
+}
+/**
+ * Result returned when a backend setup generator completes.
+ * @public
+ */
+interface SetupResult {
+    /** Merge into BackendConfig.options */
+    readonly options: Record<string, string>;
+}
+/**
+ * Factory that creates a backend setup generator.
+ * @public
+ */
+type BackendSetupFactory = () => AsyncGenerator<SetupQuestion, SetupResult, string>;
+
 /**
  * Registry for secret backend implementations.
  *
@@ -469,6 +527,7 @@ declare function isListableBackend(backend: SecretBackend): backend is ListableB
  */
 declare class BackendRegistry {
     private static backends;
+    private static setups;
     /**
      * Register a backend factory.
      * @param type - Backend type identifier
@@ -479,7 +538,7 @@ declare class BackendRegistry {
      * Create a backend instance by type.
      * @param type - Backend type identifier
      * @returns A SecretBackend instance
-     * @throws Error if the backend type is not registered
+     * @throws {@link BackendUnavailableError} if the backend type is not registered
      */
     static create(type: string): SecretBackend;
     /**
@@ -500,6 +559,36 @@ declare class BackendRegistry {
      * @public
      */
     static getAvailableTypes(): Promise<string[]>;
+    /**
+     * Register a setup factory for a backend type.
+     * @param type - Backend type identifier
+     * @param factory - Factory function that creates a setup generator
+     */
+    static registerSetup(type: string, factory: BackendSetupFactory): void;
+    /**
+     * Get the setup factory for a backend type, if one is registered.
+     * @param type - Backend type identifier
+     * @returns The setup factory, or `undefined` if none is registered
+     */
+    static getSetup(type: string): BackendSetupFactory | undefined;
+    /**
+     * Check whether a setup factory is registered for the given backend type.
+     * @param type - Backend type identifier
+     * @returns `true` if a setup factory is registered
+     */
+    static hasSetup(type: string): boolean;
+    /**
+     * Clear all registered backend factories.
+     * Intended for use in tests only.
+     * @internal
+     */
+    static clearBackends(): void;
+    /**
+     * Clear all registered setup factories.
+     * Intended for use in tests only.
+     * @internal
+     */
+    static clearSetups(): void;
 }
 
 /**
@@ -645,6 +734,8 @@ declare class VaultKeeper {
      *   with the vault metadata (`vaultResponse`).
      * @throws {VaultError} If `token` is invalid or was not created by this
      *   vault instance.
+     * @throws {InvalidAlgorithmError} If `request.algorithm` is not in the
+     *   allowed set (e.g. `'md5'`).
      */
     sign(token: CapabilityToken, request: SignRequest): Promise<{
         result: SignResult;
@@ -657,8 +748,11 @@ declare class VaultKeeper {
      * capability tokens are required. It is safe to call from CI or any
      * context that has access to public key material.
      *
-     * Never throws. Returns `false` for invalid key material, malformed
-     * signatures, or any verification failure.
+     * Returns `false` for invalid key material, malformed signatures, or
+     * any verification failure (except disallowed algorithms, which throw).
+     *
+     * @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.
@@ -700,4 +794,4 @@ declare class VaultKeeper {
     setDevelopmentMode(executablePath: string, enabled: boolean): Promise<void>;
 }
 
-export { AuthorizationDeniedError, type BackendConfig, type BackendFactory, BackendLockedError, BackendRegistry, BackendUnavailableError, CapabilityToken, DeviceNotPresentError, type ExecRequest, type ExecResult, type FetchRequest, FilesystemError, IdentityMismatchError, KeyRevokedError, KeyRotatedError, type KeyStatus, type ListableBackend, PluginNotFoundError, type PreflightCheck, type PreflightCheckStatus, type PreflightResult, RotationInProgressError, type SecretAccessor, type SecretBackend, SecretNotFoundError, SetupError, type SetupOptions, type SignRequest, type SignResult, TokenExpiredError, TokenRevokedError, type TrustTier, UsageLimitExceededError, type VaultConfig, VaultError, VaultKeeper, type VaultKeeperOptions, type VaultResponse, type VerifyRequest, isListableBackend };
+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, PluginNotFoundError, type PreflightCheck, type PreflightCheckStatus, type PreflightResult, RotationInProgressError, 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 };

package/dist/index.js

@@ -3,6 +3,7 @@ import * as fs5 from 'fs/promises';
 import * as path5 from 'path';
 import * as os4 from 'os';
 import * as crypto4 from 'crypto';
+import 'url';
 import * as fs4 from 'fs';
 import { CompactEncrypt, compactDecrypt } from 'jose';
 
@@ -136,6 +137,22 @@ var IdentityMismatchError = class extends VaultError {
     this.currentHash = currentHash;
   }
 };
+var InvalidAlgorithmError = class extends VaultError {
+  /**
+   * The algorithm that was requested.
+   */
+  algorithm;
+  /**
+   * The set of algorithms that are allowed.
+   */
+  allowed;
+  constructor(message, algorithm, allowed) {
+    super(message);
+    this.name = "InvalidAlgorithmError";
+    this.algorithm = algorithm;
+    this.allowed = allowed;
+  }
+};
 var SetupError = class extends VaultError {
   /**
    * The name of the dependency that caused the setup failure.
@@ -179,6 +196,7 @@ function isListableBackend(backend) {
 // src/backend/registry.ts
 var BackendRegistry = class {
   static backends = /* @__PURE__ */ new Map();
+  static setups = /* @__PURE__ */ new Map();
   /**
    * Register a backend factory.
    * @param type - Backend type identifier
@@ -191,7 +209,7 @@ var BackendRegistry = class {
    * Create a backend instance by type.
    * @param type - Backend type identifier
    * @returns A SecretBackend instance
-   * @throws Error if the backend type is not registered
+   * @throws {@link BackendUnavailableError} if the backend type is not registered
    */
   static create(type) {
     const factory = this.backends.get(type);
@@ -238,6 +256,46 @@ var BackendRegistry = class {
     );
     return results.filter((type) => type !== null);
   }
+  /**
+   * Register a setup factory for a backend type.
+   * @param type - Backend type identifier
+   * @param factory - Factory function that creates a setup generator
+   */
+  static registerSetup(type, factory) {
+    this.setups.set(type, factory);
+  }
+  /**
+   * Get the setup factory for a backend type, if one is registered.
+   * @param type - Backend type identifier
+   * @returns The setup factory, or `undefined` if none is registered
+   */
+  static getSetup(type) {
+    return this.setups.get(type);
+  }
+  /**
+   * Check whether a setup factory is registered for the given backend type.
+   * @param type - Backend type identifier
+   * @returns `true` if a setup factory is registered
+   */
+  static hasSetup(type) {
+    return this.setups.has(type);
+  }
+  /**
+   * Clear all registered backend factories.
+   * Intended for use in tests only.
+   * @internal
+   */
+  static clearBackends() {
+    this.backends.clear();
+  }
+  /**
+   * Clear all registered setup factories.
+   * Intended for use in tests only.
+   * @internal
+   */
+  static clearSetups() {
+    this.setups.clear();
+  }
 };
 async function execCommand(command, args, options) {
   const result = await execCommandFull(command, args);
@@ -487,6 +545,21 @@ function validateBackendEntry(entry, index) {
     }
     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) {
@@ -997,10 +1070,12 @@ function resolveAlgorithmForKey(key, override) {
   if (keyType === "ed25519" || keyType === "ed448") {
     return { signAlg: null, label: keyType };
   }
-  const alg = override ?? "sha256";
+  const alg = (override ?? "sha256").toLowerCase();
   if (!ALLOWED_ALGORITHMS.has(alg)) {
-    throw new VaultError(
-      `Unsupported signing algorithm '${alg}'. Allowed: ${[...ALLOWED_ALGORITHMS].join(", ")}`
+    throw new InvalidAlgorithmError(
+      `Unsupported algorithm '${alg}'. Allowed: ${[...ALLOWED_ALGORITHMS].join(", ")}`,
+      alg,
+      [...ALLOWED_ALGORITHMS]
     );
   }
   return { signAlg: alg, label: alg };
@@ -1024,6 +1099,9 @@ function delegatedVerify(request) {
   } catch {
     return false;
   }
+  if (typeof request.publicKey === "string" && request.publicKey.includes("PRIVATE KEY")) {
+    return false;
+  }
   const { signAlg } = resolveAlgorithmForKey(key, request.algorithm);
   const sig = Buffer.from(request.signature, "base64");
   try {
@@ -1405,6 +1483,8 @@ var VaultKeeper = class _VaultKeeper {
    *   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) {
     const claims = validateCapabilityToken(token);
@@ -1422,8 +1502,11 @@ var VaultKeeper = class _VaultKeeper {
    * capability tokens are required. It is safe to call from CI or any
    * context that has access to public key material.
    *
-   * Never throws. Returns `false` for invalid key material, malformed
-   * signatures, or any verification failure.
+   * Returns `false` for invalid key material, malformed signatures, or
+   * any verification failure (except disallowed algorithms, which throw).
+   *
+   * @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.
@@ -1548,6 +1631,6 @@ var VaultKeeper = class _VaultKeeper {
   }
 };
 
-export { AuthorizationDeniedError, BackendLockedError, BackendRegistry, BackendUnavailableError, CapabilityToken, DeviceNotPresentError, FilesystemError, IdentityMismatchError, KeyRevokedError, KeyRotatedError, PluginNotFoundError, RotationInProgressError, SecretNotFoundError, SetupError, TokenExpiredError, TokenRevokedError, UsageLimitExceededError, VaultError, VaultKeeper, isListableBackend };
+export { AuthorizationDeniedError, BackendLockedError, BackendRegistry, BackendUnavailableError, CapabilityToken, DeviceNotPresentError, FilesystemError, IdentityMismatchError, InvalidAlgorithmError, KeyRevokedError, KeyRotatedError, PluginNotFoundError, RotationInProgressError, SecretNotFoundError, SetupError, TokenExpiredError, TokenRevokedError, UsageLimitExceededError, VaultError, VaultKeeper, isListableBackend };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map