vaultkeeper 0.0.0 → 0.3.0

package/dist/index.d.cts

@@ -0,0 +1,616 @@
+/**
+ * Error hierarchy for vaultkeeper.
+ */
+/** Base error for all vaultkeeper errors. */
+declare class VaultError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when the backend keychain or credential store is locked and requires
+ * user interaction (e.g. biometric prompt or password entry) before access can
+ * be granted.
+ */
+declare class BackendLockedError extends VaultError {
+    /**
+     * Whether the lock can be resolved through an interactive user prompt.
+     * When `true`, callers may retry after prompting the user.
+     */
+    readonly interactive: boolean;
+    constructor(message: string, interactive: boolean);
+}
+/**
+ * Thrown when a hardware device (e.g. YubiKey or smart card) required for
+ * authentication is not currently connected.
+ */
+declare class DeviceNotPresentError extends VaultError {
+    /**
+     * How long (in milliseconds) the operation waited for the device before
+     * giving up.
+     */
+    readonly timeoutMs: number;
+    constructor(message: string, timeoutMs: number);
+}
+/**
+ * Thrown when the user explicitly denies an authorization request for a
+ * secret access operation (e.g. cancels an OS permission dialog).
+ */
+declare class AuthorizationDeniedError extends VaultError {
+    constructor(message: string);
+}
+/**
+ * Thrown when no configured backend is available or reachable.
+ * Inspect `reason` for a machine-readable cause and `attempted` for the list
+ * of backend types that were tried.
+ */
+declare class BackendUnavailableError extends VaultError {
+    /**
+     * Machine-readable reason code describing why the backend is unavailable
+     * (e.g. `'none-enabled'`, `'all-failed'`).
+     */
+    readonly reason: string;
+    /**
+     * The backend type identifiers that were attempted before this error was
+     * thrown.
+     */
+    readonly attempted: string[];
+    constructor(message: string, reason: string, attempted: string[]);
+}
+/**
+ * Thrown when a required backend plugin (e.g. a third-party credential
+ * manager) is not installed on the current system.
+ */
+declare class PluginNotFoundError extends VaultError {
+    /**
+     * The plugin package or binary name that was not found.
+     */
+    readonly plugin: string;
+    /**
+     * A URL pointing to installation instructions for the missing plugin.
+     */
+    readonly installUrl: string;
+    constructor(message: string, plugin: string, installUrl: string);
+}
+/**
+ * Thrown when a requested secret does not exist in the backend store.
+ */
+declare class SecretNotFoundError extends VaultError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a JWE token has passed its expiration time (`exp` claim).
+ */
+declare class TokenExpiredError extends VaultError {
+    /**
+     * Whether the token can be refreshed by calling `setup()` again.
+     * When `true`, the secret still exists in the backend and a new token can be
+     * issued.
+     */
+    readonly canRefresh: boolean;
+    constructor(message: string, canRefresh: boolean);
+}
+/**
+ * Thrown when the encryption key that was used to create a JWE has since been
+ * rotated out of the grace period and can no longer be used for decryption.
+ */
+declare class KeyRotatedError extends VaultError {
+    constructor(message: string);
+}
+/**
+ * Thrown when the encryption key referenced by a JWE's `kid` header has been
+ * explicitly revoked and is no longer available for decryption.
+ */
+declare class KeyRevokedError extends VaultError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a JWE token has been explicitly blocked (e.g. after a single-use
+ * token has already been consumed).
+ */
+declare class TokenRevokedError extends VaultError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a token with a finite `use` limit has been presented more times
+ * than the limit allows.
+ */
+declare class UsageLimitExceededError extends VaultError {
+    constructor(message: string);
+}
+/**
+ * Thrown when the hash of an executable no longer matches the previously
+ * approved hash stored in the trust manifest (TOFU conflict).
+ *
+ * Callers must re-approve the executable before a new token can be issued for
+ * it.
+ */
+declare class IdentityMismatchError extends VaultError {
+    /**
+     * The hash that was recorded in the trust manifest at approval time.
+     */
+    readonly previousHash: string;
+    /**
+     * The hash computed from the executable at the current moment.
+     */
+    readonly currentHash: string;
+    constructor(message: string, previousHash: string, currentHash: string);
+}
+/**
+ * Thrown during initialization when a required system dependency (e.g. OpenSSL
+ * or a native credential helper) is missing or incompatible.
+ */
+declare class SetupError extends VaultError {
+    /**
+     * The name of the dependency that caused the setup failure.
+     */
+    readonly dependency: string;
+    constructor(message: string, dependency: string);
+}
+/**
+ * Thrown when a filesystem operation fails due to a permission or access
+ * problem (e.g. the config directory is not writable).
+ */
+declare class FilesystemError extends VaultError {
+    /**
+     * The absolute path of the file or directory that caused the error.
+     */
+    readonly path: string;
+    /**
+     * The permission level that was required but not available
+     * (e.g. `'read'`, `'write'`, `'execute'`).
+     */
+    readonly permission: string;
+    constructor(message: string, filePath: string, permission: string);
+}
+/**
+ * Thrown when a key rotation is requested while a previous rotation is still
+ * within its grace period (i.e. the previous key has not yet been retired).
+ */
+declare class RotationInProgressError extends VaultError {
+    constructor(message: string);
+}
+
+/**
+ * Shared types and interfaces for vaultkeeper.
+ */
+/** Trust tier for executable identity verification. */
+type TrustTier = 1 | 2 | 3;
+/** Key status in the rotation lifecycle. */
+type KeyStatus = 'current' | 'previous' | 'deprecated';
+/** Status of a preflight check. */
+type PreflightCheckStatus = 'ok' | 'missing' | 'version-unsupported';
+/** Result of a preflight check for a single dependency. */
+interface PreflightCheck {
+    /** Human-readable name of the dependency being checked. */
+    name: string;
+    /** Whether the dependency was found and is a supported version. */
+    status: PreflightCheckStatus;
+    /** The detected version string, if the dependency was found. */
+    version?: string | undefined;
+    /** Human-readable explanation of why the status is not `'ok'`. */
+    reason?: string | undefined;
+}
+/** Aggregated result from all preflight checks. */
+interface PreflightResult {
+    /** Individual check results, one per dependency inspected. */
+    checks: PreflightCheck[];
+    /** `true` if all required checks passed and the system is ready. */
+    ready: boolean;
+    /** Non-fatal advisory messages about optional missing dependencies. */
+    warnings: string[];
+    /** Action items the user should complete before vaultkeeper will work. */
+    nextSteps: string[];
+}
+/** Response from a vault access operation. */
+interface VaultResponse {
+    /** Replacement JWE if key was rotated */
+    rotatedJwt?: string | undefined;
+    /** Current key status */
+    keyStatus: KeyStatus;
+}
+/**
+ * Request for delegated HTTP fetch.
+ *
+ * String values in `url`, `headers`, and `body` may include the placeholder
+ * `{{secret}}`, which is replaced with the actual secret value immediately
+ * before the request is sent.
+ */
+interface FetchRequest {
+    /**
+     * The target URL. May contain `{{secret}}` which is replaced with the secret
+     * value before the fetch is executed (e.g. for API-key-in-URL patterns).
+     */
+    url: string;
+    /** HTTP method (defaults to `'GET'` when omitted). */
+    method?: string | undefined;
+    /**
+     * Request headers. Any header value may contain `{{secret}}`, which is
+     * replaced with the secret value before the request is sent.
+     */
+    headers?: Record<string, string> | undefined;
+    /**
+     * Request body. May contain `{{secret}}`, which is replaced with the secret
+     * value before the request is sent.
+     */
+    body?: string | undefined;
+}
+/**
+ * Request for delegated command execution.
+ *
+ * String values in `args` and `env` may include the placeholder `{{secret}}`,
+ * which is replaced with the actual secret value immediately before the command
+ * is spawned.
+ */
+interface ExecRequest {
+    /** The command (binary) to execute. */
+    command: string;
+    /**
+     * Command-line arguments. Any argument may contain `{{secret}}`, which is
+     * replaced with the secret value before the command is spawned.
+     */
+    args?: string[] | undefined;
+    /**
+     * Additional environment variables to merge into the child process
+     * environment. Any value may contain `{{secret}}`, which is replaced with
+     * the secret value before the command is spawned.
+     */
+    env?: Record<string, string> | undefined;
+    /** Working directory for the spawned process. */
+    cwd?: string | undefined;
+}
+/** Result from delegated command execution. */
+interface ExecResult {
+    /** Captured standard output from the process. */
+    stdout: string;
+    /** Captured standard error from the process. */
+    stderr: string;
+    /** Process exit code. */
+    exitCode: number;
+}
+/**
+ * Callback-based secret accessor with auto-zeroing.
+ *
+ * The accessor is backed by a revocable Proxy. Calling `read()` passes a
+ * `Buffer` containing the secret to the callback, then zeroes the buffer after
+ * the callback returns. The accessor can only be read once; a second call
+ * throws.
+ */
+interface SecretAccessor {
+    /**
+     * Read the secret value via a callback.
+     *
+     * The `buf` argument is a temporary `Buffer` containing the secret encoded
+     * as UTF-8. The buffer is zeroed immediately after the callback returns, so
+     * callers must not store a reference to it beyond the callback scope.
+     *
+     * @param callback - Function that receives the secret buffer.
+     * @throws {Error} If the accessor has already been consumed.
+     */
+    read(callback: (buf: Buffer) => void): void;
+}
+/** Vaultkeeper configuration file structure. */
+interface VaultConfig {
+    /** Config schema version. Currently must be `1`. */
+    version: number;
+    /** Ordered list of backend configurations. The first enabled backend is used. */
+    backends: BackendConfig[];
+    /** Key rotation policy. */
+    keyRotation: {
+        /**
+         * Number of days the previous key remains valid for decryption after a
+         * rotation event.
+         */
+        gracePeriodDays: number;
+    };
+    /** Default values applied to `setup()` when options are not explicitly provided. */
+    defaults: {
+        /** Default JWE time-to-live in minutes. */
+        ttlMinutes: number;
+        /** Default trust tier for executable identity verification. */
+        trustTier: TrustTier;
+    };
+    /** Development mode configuration. When present, identity checks are relaxed for listed executables. */
+    developmentMode?: {
+        /** Paths of executables that bypass identity verification in development mode. */
+        executables: string[];
+    } | undefined;
+}
+/** Configuration for a single backend. */
+interface BackendConfig {
+    /** Backend type identifier (e.g. `'keychain'`, `'file'`, `'1password'`). */
+    type: string;
+    /** Whether this backend is active. Only enabled backends are considered during initialization. */
+    enabled: boolean;
+    /** Whether this backend is provided by an external plugin rather than built in. */
+    plugin?: boolean | undefined;
+    /** Filesystem path used by file-based backends. */
+    path?: string | undefined;
+}
+
+/**
+ * Backend abstraction layer types for vaultkeeper.
+ */
+/**
+ * Factory function for creating a SecretBackend instance.
+ * @public
+ */
+type BackendFactory = () => SecretBackend;
+/**
+ * Abstraction interface for all secret storage backends.
+ *
+ * @remarks
+ * Each backend implementation must handle its own availability check and
+ * secret lifecycle (store, retrieve, delete, exists).
+ *
+ * @public
+ */
+interface SecretBackend {
+    /** Unique type identifier for this backend. */
+    readonly type: string;
+    /** Human-readable display name for this backend. */
+    readonly displayName: string;
+    /**
+     * Check whether this backend is available on the current system.
+     * @returns true if the backend can be used, false otherwise
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Store a secret under the given id.
+     * @param id - Unique identifier for the secret
+     * @param secret - The secret value to store
+     */
+    store(id: string, secret: string): Promise<void>;
+    /**
+     * Retrieve a secret by id.
+     * @param id - Unique identifier for the secret
+     * @returns The stored secret value
+     * @throws SecretNotFoundError if the secret does not exist
+     */
+    retrieve(id: string): Promise<string>;
+    /**
+     * Delete a secret by id.
+     * @param id - Unique identifier for the secret
+     * @throws SecretNotFoundError if the secret does not exist
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Check whether a secret exists for the given id.
+     * @param id - Unique identifier for the secret
+     * @returns true if the secret exists, false otherwise
+     */
+    exists(id: string): Promise<boolean>;
+}
+/**
+ * Backend that can enumerate stored secret IDs.
+ * @public
+ */
+interface ListableBackend extends SecretBackend {
+    /**
+     * List IDs of all secrets managed by this backend.
+     * @returns Array of secret identifiers
+     */
+    list(): Promise<string[]>;
+}
+/**
+ * Type guard for backends that support listing.
+ * @public
+ */
+declare function isListableBackend(backend: SecretBackend): backend is ListableBackend;
+
+/**
+ * Registry for secret backend implementations.
+ *
+ * @remarks
+ * The registry maintains a mapping of backend types to factory functions,
+ * allowing dynamic creation of backends based on configuration.
+ */
+
+/**
+ * Registry for secret backend implementations.
+ *
+ * @remarks
+ * The registry allows registration of custom backends and provides
+ * a factory method to create backend instances from a type string.
+ *
+ * Note: This class is used as a namespace for static methods.
+ * @public
+ */
+declare class BackendRegistry {
+    private static backends;
+    /**
+     * Register a backend factory.
+     * @param type - Backend type identifier
+     * @param factory - Factory function to create backend instances
+     */
+    static register(type: string, factory: BackendFactory): void;
+    /**
+     * Create a backend instance by type.
+     * @param type - Backend type identifier
+     * @returns A SecretBackend instance
+     * @throws Error if the backend type is not registered
+     */
+    static create(type: string): SecretBackend;
+    /**
+     * Get all registered backend type identifiers.
+     * @returns Array of backend type identifiers
+     */
+    static getTypes(): string[];
+    /**
+     * Returns backend types that are available on the current system.
+     *
+     * @remarks
+     * Creates each registered backend via its factory, calls `isAvailable()`,
+     * and returns only the type identifiers whose backend reports availability.
+     * If a backend's `isAvailable()` call throws, that backend is excluded from
+     * the result rather than propagating the error.
+     *
+     * @returns Promise resolving to an array of available backend type identifiers
+     * @public
+     */
+    static getAvailableTypes(): Promise<string[]>;
+}
+
+/**
+ * Capability token management.
+ *
+ * Tokens are backed by a `WeakMap` whose keys are `CapabilityToken` instances,
+ * so the actual claims are never reachable from outside this module. Private
+ * class fields enforce that no property on the token object leaks data.
+ */
+
+/** Opaque capability token. Claims are inaccessible without `validateCapabilityToken`. */
+declare class CapabilityToken {
+    #private;
+    constructor();
+    /**
+     * Return a non-enumerable identifier for debugging purposes only.
+     * Does NOT expose claims.
+     */
+    toString(): string;
+}
+
+/**
+ * VaultKeeper main class — wires together all vaultkeeper subsystems.
+ */
+
+/** Options for initializing VaultKeeper. */
+interface VaultKeeperOptions {
+    /** Override the config directory. */
+    configDir?: string | undefined;
+    /** Supply config directly, skipping file load. */
+    config?: VaultConfig | undefined;
+    /** Skip the doctor preflight check. */
+    skipDoctor?: boolean | undefined;
+}
+/** Options for the setup operation. */
+interface SetupOptions {
+    /** TTL in minutes for the JWE. */
+    ttlMinutes?: number | undefined;
+    /** Usage limit (null for unlimited). */
+    useLimit?: number | null | undefined;
+    /** Executable path for identity binding. Use "dev" for dev mode. */
+    executablePath?: string | undefined;
+    /** Trust tier override. */
+    trustTier?: TrustTier | undefined;
+    /** Backend type to use. */
+    backendType?: string | undefined;
+}
+/**
+ * Main entry point for vaultkeeper. Orchestrates backends, keys, JWE tokens,
+ * identity verification, and access patterns.
+ */
+declare class VaultKeeper {
+    #private;
+    private constructor();
+    /**
+     * Initialize a new VaultKeeper instance.
+     * 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>;
+    /**
+     * Store a secret and return a JWE token that encapsulates it.
+     *
+     * @param secretName - Identifier for the secret
+     * @param options - Setup options
+     * @returns Compact JWE string
+     */
+    setup(secretName: string, options?: SetupOptions): Promise<string>;
+    /**
+     * Decrypt a JWE, validate claims, verify executable identity, and return
+     * an opaque CapabilityToken.
+     *
+     * @param jwe - Compact JWE string from setup()
+     * @returns Opaque capability token for use with fetch/exec/getSecret
+     */
+    authorize(jwe: string): Promise<{
+        token: CapabilityToken;
+        response: VaultResponse;
+    }>;
+    /**
+     * Execute a delegated HTTP fetch, injecting the secret from the token.
+     *
+     * The secret value is substituted for every `{{secret}}` placeholder found
+     * in `request.url`, `request.headers`, and `request.body` before the fetch
+     * is executed. The raw secret is never exposed in the return value.
+     *
+     * @param token - A `CapabilityToken` obtained from `authorize()`.
+     * @param request - The fetch request template. Use `{{secret}}` as a
+     *   placeholder wherever the secret value should be injected.
+     * @returns The `Response` from the underlying `fetch()` call, together with
+     *   the vault metadata (`vaultResponse`).
+     * @throws {Error} If `token` is invalid or was not created by this vault
+     *   instance.
+     */
+    fetch(token: CapabilityToken, request: FetchRequest): Promise<{
+        response: Response;
+        vaultResponse: VaultResponse;
+    }>;
+    /**
+     * Execute a delegated command, injecting the secret from the token.
+     *
+     * The secret value is substituted for every `{{secret}}` placeholder found
+     * in `request.args` and `request.env` values before the process is spawned.
+     * The raw secret is never exposed in the return value.
+     *
+     * @param token - A `CapabilityToken` obtained from `authorize()`.
+     * @param request - The exec request template. Use `{{secret}}` as a
+     *   placeholder wherever the secret value should be injected.
+     * @returns The command result (`stdout`, `stderr`, `exitCode`) together with
+     *   the vault metadata (`vaultResponse`).
+     * @throws {Error} If `token` is invalid or was not created by this vault
+     *   instance.
+     */
+    exec(token: CapabilityToken, request: ExecRequest): Promise<{
+        result: ExecResult;
+        vaultResponse: VaultResponse;
+    }>;
+    /**
+     * Create a controlled-direct `SecretAccessor` from a capability token.
+     *
+     * The accessor wraps the secret in a single-use, auto-zeroing `Buffer`. The
+     * secret is accessible only through the `read()` callback and is zeroed
+     * immediately after the callback returns.
+     *
+     * @param token - A `CapabilityToken` obtained from `authorize()`.
+     * @returns A `SecretAccessor` that can be read exactly once.
+     * @throws {Error} If `token` is invalid or was not created by this vault
+     *   instance.
+     */
+    getSecret(token: CapabilityToken): SecretAccessor;
+    /**
+     * Rotate the current encryption key.
+     *
+     * The previous key remains valid for decryption during the grace period
+     * configured in `keyRotation.gracePeriodDays`. JWEs presented during the
+     * grace period return a `rotatedJwt` in the `VaultResponse` so callers can
+     * persist the updated token.
+     *
+     * @throws {RotationInProgressError} If a rotation is already in progress
+     *   (i.e. a previous key is still within its grace period).
+     */
+    rotateKey(): Promise<void>;
+    /**
+     * Emergency key revocation — invalidates the previous key immediately.
+     *
+     * After revocation, any JWE that was encrypted with the revoked key will
+     * be permanently unreadable. A new encryption key is generated automatically
+     * so that `setup()` can be called immediately after revocation.
+     */
+    revokeKey(): Promise<void>;
+    /**
+     * Add or remove an executable from the development-mode whitelist.
+     *
+     * When an executable is in the development-mode list, identity verification
+     * (TOFU hash checking) is skipped for that executable during `setup()`. This
+     * is intended for local development workflows where the binary changes
+     * frequently.
+     *
+     * @param executablePath - Absolute path to the executable to add or remove.
+     * @param enabled - Pass `true` to add the executable to the list, `false`
+     *   to remove it.
+     */
+    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 };