vaultkeeper 0.4.0 → 0.5.1

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;
 }
 
 /**
@@ -384,9 +401,15 @@ interface BackendConfig {
  */
 /**
  * Factory function for creating a SecretBackend instance.
+ *
+ * @remarks
+ * Factories may optionally accept a {@link BackendConfig} to configure the
+ * backend from the user's vaultkeeper config file. Factories that do not need
+ * configuration can ignore the parameter.
+ *
  * @public
  */
-type BackendFactory = () => SecretBackend;
+type BackendFactory = (config?: BackendConfig) => SecretBackend;
 /**
  * Abstraction interface for all secret storage backends.
  *
@@ -450,12 +473,45 @@ interface ListableBackend extends SecretBackend {
 declare function isListableBackend(backend: SecretBackend): backend is ListableBackend;
 
 /**
- * Registry for secret backend implementations.
+ * Types for the backend setup protocol.
  *
- * @remarks
- * The registry maintains a mapping of backend types to factory functions,
- * allowing dynamic creation of backends based on configuration.
+ * @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 +525,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
@@ -478,10 +535,11 @@ declare class BackendRegistry {
     /**
      * Create a backend instance by type.
      * @param type - Backend type identifier
+     * @param config - Optional backend configuration forwarded to the factory
      * @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;
+    static create(type: string, config?: BackendConfig): SecretBackend;
     /**
      * Get all registered backend type identifiers.
      * @returns Array of backend type identifiers
@@ -500,6 +558,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;
 }
 
 /**
@@ -562,7 +650,7 @@ declare class VaultKeeper {
     /** Run doctor checks without full initialization. */
     static doctor(): Promise<PreflightResult>;
     /**
-     * Store a secret and return a JWE token that encapsulates it.
+     * Retrieve a secret from the backend and return a JWE token that encapsulates it.
      *
      * @param secretName - Identifier for the secret
      * @param options - Setup options
@@ -645,6 +733,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 +747,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 +793,31 @@ 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 };
+/**
+ * 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;
+}
+/**
+ * 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 };

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;
 }
 
 /**
@@ -384,9 +401,15 @@ interface BackendConfig {
  */
 /**
  * Factory function for creating a SecretBackend instance.
+ *
+ * @remarks
+ * Factories may optionally accept a {@link BackendConfig} to configure the
+ * backend from the user's vaultkeeper config file. Factories that do not need
+ * configuration can ignore the parameter.
+ *
  * @public
  */
-type BackendFactory = () => SecretBackend;
+type BackendFactory = (config?: BackendConfig) => SecretBackend;
 /**
  * Abstraction interface for all secret storage backends.
  *
@@ -450,12 +473,45 @@ interface ListableBackend extends SecretBackend {
 declare function isListableBackend(backend: SecretBackend): backend is ListableBackend;
 
 /**
- * Registry for secret backend implementations.
+ * Types for the backend setup protocol.
  *
- * @remarks
- * The registry maintains a mapping of backend types to factory functions,
- * allowing dynamic creation of backends based on configuration.
+ * @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 +525,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
@@ -478,10 +535,11 @@ declare class BackendRegistry {
     /**
      * Create a backend instance by type.
      * @param type - Backend type identifier
+     * @param config - Optional backend configuration forwarded to the factory
      * @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;
+    static create(type: string, config?: BackendConfig): SecretBackend;
     /**
      * Get all registered backend type identifiers.
      * @returns Array of backend type identifiers
@@ -500,6 +558,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;
 }
 
 /**
@@ -562,7 +650,7 @@ declare class VaultKeeper {
     /** Run doctor checks without full initialization. */
     static doctor(): Promise<PreflightResult>;
     /**
-     * Store a secret and return a JWE token that encapsulates it.
+     * Retrieve a secret from the backend and return a JWE token that encapsulates it.
      *
      * @param secretName - Identifier for the secret
      * @param options - Setup options
@@ -645,6 +733,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 +747,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 +793,31 @@ 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 };
+/**
+ * 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;
+}
+/**
+ * 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 };