vaultkeeper 0.3.0 → 0.5.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.
@@ -287,6 +302,59 @@ interface SecretAccessor {
      */
     read(callback: (buf: Buffer) => void): void;
 }
+/**
+ * Request for delegated signing.
+ *
+ * The `data` field is the payload to sign. Strings are UTF-8-encoded
+ * before signing.
+ */
+interface SignRequest {
+    /** The data to sign. Strings are treated as UTF-8. */
+    data: string | Buffer;
+    /**
+     * Override the hash algorithm (`'sha256'`, `'sha384'`, or `'sha512'`).
+     * Ignored for Ed25519/Ed448 keys where the algorithm is implicit.
+     * Non-Edwards keys (RSA, EC) default to `'sha256'` when omitted.
+     * Weak algorithms (e.g. `'md5'`, `'sha1'`) are rejected.
+     */
+    algorithm?: string | undefined;
+}
+/** Result from a delegated signing operation. */
+interface SignResult {
+    /** Base64-encoded signature. */
+    signature: string;
+    /**
+     * Algorithm label describing how the signature was produced.
+     * For Edwards keys this is the key type (e.g. `'ed25519'`).
+     * For other keys this matches the `algorithm` field from the request
+     * (or the default `'sha256'`).
+     */
+    algorithm: string;
+}
+/**
+ * Request for signature verification.
+ *
+ * This is a static operation that only requires public key material —
+ * no VaultKeeper instance or capability token is needed.
+ */
+interface VerifyRequest {
+    /** The original data that was signed. Strings are treated as UTF-8. */
+    data: string | Buffer;
+    /** Base64-encoded signature to verify. */
+    signature: string;
+    /**
+     * PEM-encoded public key (SPKI format) as a string.
+     *
+     * Other `KeyLike` formats supported by `crypto.createPublicKey()` are not
+     * accepted by this interface.
+     */
+    publicKey: string;
+    /**
+     * Override the hash algorithm. Ignored for Ed25519/Ed448 keys.
+     * Non-Edwards keys default to `'sha256'` when omitted.
+     */
+    algorithm?: string | undefined;
+}
 /** Vaultkeeper configuration file structure. */
 interface VaultConfig {
     /** Config schema version. Currently must be `1`. */
@@ -324,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;
 }
 
 /**
@@ -331,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.
  *
@@ -397,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.
@@ -416,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
@@ -425,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
@@ -447,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;
 }
 
 /**
@@ -578,6 +719,45 @@ declare class VaultKeeper {
      *   instance.
      */
     getSecret(token: CapabilityToken): SecretAccessor;
+    /**
+     * Sign data using the private key embedded in a capability token.
+     *
+     * 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.
+     *
+     * @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'`).
+     */
+    sign(token: CapabilityToken, request: SignRequest): Promise<{
+        result: SignResult;
+        vaultResponse: VaultResponse;
+    }>;
+    /**
+     * Verify a signature using a public key.
+     *
+     * 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.
+     *
+     * 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.
+     * @returns `true` if the signature is valid, `false` otherwise.
+     */
+    static verify(request: VerifyRequest): boolean;
     /**
      * Rotate the current encryption key.
      *
@@ -613,4 +793,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, TokenExpiredError, TokenRevokedError, type TrustTier, UsageLimitExceededError, type VaultConfig, VaultError, VaultKeeper, type VaultKeeperOptions, type VaultResponse, 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.
@@ -287,6 +302,59 @@ interface SecretAccessor {
      */
     read(callback: (buf: Buffer) => void): void;
 }
+/**
+ * Request for delegated signing.
+ *
+ * The `data` field is the payload to sign. Strings are UTF-8-encoded
+ * before signing.
+ */
+interface SignRequest {
+    /** The data to sign. Strings are treated as UTF-8. */
+    data: string | Buffer;
+    /**
+     * Override the hash algorithm (`'sha256'`, `'sha384'`, or `'sha512'`).
+     * Ignored for Ed25519/Ed448 keys where the algorithm is implicit.
+     * Non-Edwards keys (RSA, EC) default to `'sha256'` when omitted.
+     * Weak algorithms (e.g. `'md5'`, `'sha1'`) are rejected.
+     */
+    algorithm?: string | undefined;
+}
+/** Result from a delegated signing operation. */
+interface SignResult {
+    /** Base64-encoded signature. */
+    signature: string;
+    /**
+     * Algorithm label describing how the signature was produced.
+     * For Edwards keys this is the key type (e.g. `'ed25519'`).
+     * For other keys this matches the `algorithm` field from the request
+     * (or the default `'sha256'`).
+     */
+    algorithm: string;
+}
+/**
+ * Request for signature verification.
+ *
+ * This is a static operation that only requires public key material —
+ * no VaultKeeper instance or capability token is needed.
+ */
+interface VerifyRequest {
+    /** The original data that was signed. Strings are treated as UTF-8. */
+    data: string | Buffer;
+    /** Base64-encoded signature to verify. */
+    signature: string;
+    /**
+     * PEM-encoded public key (SPKI format) as a string.
+     *
+     * Other `KeyLike` formats supported by `crypto.createPublicKey()` are not
+     * accepted by this interface.
+     */
+    publicKey: string;
+    /**
+     * Override the hash algorithm. Ignored for Ed25519/Ed448 keys.
+     * Non-Edwards keys default to `'sha256'` when omitted.
+     */
+    algorithm?: string | undefined;
+}
 /** Vaultkeeper configuration file structure. */
 interface VaultConfig {
     /** Config schema version. Currently must be `1`. */
@@ -324,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;
 }
 
 /**
@@ -331,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.
  *
@@ -397,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.
@@ -416,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
@@ -425,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
@@ -447,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;
 }
 
 /**
@@ -578,6 +719,45 @@ declare class VaultKeeper {
      *   instance.
      */
     getSecret(token: CapabilityToken): SecretAccessor;
+    /**
+     * Sign data using the private key embedded in a capability token.
+     *
+     * 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.
+     *
+     * @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'`).
+     */
+    sign(token: CapabilityToken, request: SignRequest): Promise<{
+        result: SignResult;
+        vaultResponse: VaultResponse;
+    }>;
+    /**
+     * Verify a signature using a public key.
+     *
+     * 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.
+     *
+     * 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.
+     * @returns `true` if the signature is valid, `false` otherwise.
+     */
+    static verify(request: VerifyRequest): boolean;
     /**
      * Rotate the current encryption key.
      *
@@ -613,4 +793,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, TokenExpiredError, TokenRevokedError, type TrustTier, UsageLimitExceededError, type VaultConfig, VaultError, VaultKeeper, type VaultKeeperOptions, type VaultResponse, 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 };