vaultkeeper 0.5.2 → 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.
  */
@@ -647,10 +720,40 @@ declare class VaultKeeper {
      * Runs doctor checks (unless skipped), loads config, and sets up the key manager.
      */
     static init(options?: VaultKeeperOptions): Promise<VaultKeeper>;
-    /** Run doctor checks without full initialization. */
-    static doctor(): Promise<PreflightResult>;
     /**
-     * Retrieve a secret from the backend and return a JWE token that encapsulates it.
+     * Run doctor checks without full initialization.
+     *
+     * 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
+     */
+    delete(name: string): Promise<void>;
+    /**
+     * 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
@@ -662,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.
@@ -793,31 +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;
-}
-/**
- * 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.
  */
@@ -647,10 +720,40 @@ declare class VaultKeeper {
      * Runs doctor checks (unless skipped), loads config, and sets up the key manager.
      */
     static init(options?: VaultKeeperOptions): Promise<VaultKeeper>;
-    /** Run doctor checks without full initialization. */
-    static doctor(): Promise<PreflightResult>;
     /**
-     * Retrieve a secret from the backend and return a JWE token that encapsulates it.
+     * Run doctor checks without full initialization.
+     *
+     * 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
+     */
+    delete(name: string): Promise<void>;
+    /**
+     * 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
@@ -662,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.
@@ -793,31 +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;
-}
-/**
- * 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 };