@blokjs/runner 0.2.0

package/dist/security/SecretManager.d.ts

@@ -0,0 +1,652 @@
+/**
+ * Secret Management for Blok Framework
+ *
+ * Provides a unified interface for secret management across multiple providers:
+ * - HashiCorp Vault (KV v2 engine via REST API)
+ * - AWS Secrets Manager (via @aws-sdk/client-secrets-manager)
+ * - GCP Secret Manager (via @google-cloud/secret-manager)
+ * - Environment Variables (process.env)
+ * - In-Memory (for testing)
+ *
+ * Features:
+ * - Provider chain: try providers in order, first match wins
+ * - Caching layer with TTL and max size (LRU eviction)
+ * - Audit event emission for secret access tracking
+ * - Template resolution for `${secret:KEY}` patterns
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   SecretManager,
+ *   EnvironmentSecretProvider,
+ *   InMemorySecretProvider,
+ * } from "@blokjs/runner";
+ *
+ * // Simple setup with environment variables
+ * const secrets = new SecretManager({
+ *   providers: [
+ *     { type: "environment", config: { prefix: "BLOK_SECRET_" } },
+ *   ],
+ *   cache: { enabled: true, ttlMs: 60_000, maxSize: 100 },
+ *   auditLog: true,
+ * });
+ *
+ * const dbPassword = await secrets.getSecret("DB_PASSWORD");
+ * const connStr = await secrets.resolveTemplate(
+ *   "postgres://user:${secret:DB_PASSWORD}@host/db"
+ * );
+ * ```
+ */
+import { EventEmitter } from "node:events";
+/**
+ * Metadata associated with a stored secret
+ */
+export interface SecretMetadata {
+    /** Version identifier for the secret */
+    version?: string;
+    /** Unix timestamp (ms) when the secret expires */
+    expiresAt?: number;
+    /** Arbitrary key-value tags */
+    tags?: Record<string, string>;
+    /** Human-readable description of the secret */
+    description?: string;
+}
+/**
+ * Interface that all secret providers must implement
+ */
+export interface SecretProvider {
+    /** Unique name identifying this provider instance */
+    readonly name: string;
+    /**
+     * Retrieve a secret value by key
+     * @param key - The secret key to look up
+     * @returns The secret value, or null if not found
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Store or update a secret value
+     * @param key - The secret key
+     * @param value - The secret value
+     * @param metadata - Optional metadata to associate with the secret
+     */
+    set(key: string, value: string, metadata?: SecretMetadata): Promise<void>;
+    /**
+     * Delete a secret by key
+     * @param key - The secret key to delete
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * List secret keys, optionally filtered by prefix
+     * @param prefix - Optional prefix to filter keys
+     * @returns Array of secret key names
+     */
+    list(prefix?: string): Promise<string[]>;
+    /**
+     * Check whether a secret exists
+     * @param key - The secret key to check
+     * @returns True if the secret exists
+     */
+    exists(key: string): Promise<boolean>;
+}
+/**
+ * Event emitted when a secret is accessed
+ */
+export interface SecretAccessEvent {
+    /** Type of operation */
+    operation: "get" | "set" | "delete" | "list" | "exists";
+    /** Secret key (omitted for list operations) */
+    key?: string;
+    /** Provider that served the request */
+    provider: string;
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Whether the result came from cache */
+    cached: boolean;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Error message if the operation failed */
+    error?: string;
+}
+/**
+ * Configuration for an environment variable secret provider
+ */
+export interface EnvironmentProviderConfig {
+    type: "environment";
+    config?: {
+        /** Prefix prepended to key names when reading env vars (e.g., "BLOK_SECRET_") */
+        prefix?: string;
+        /** Whether key lookups are case-sensitive (default: true) */
+        caseSensitive?: boolean;
+    };
+}
+/**
+ * Configuration for the in-memory secret provider
+ */
+export interface InMemoryProviderConfig {
+    type: "memory";
+    config?: Record<string, never>;
+}
+/**
+ * Configuration for the HashiCorp Vault secret provider
+ */
+export interface VaultProviderConfig {
+    type: "vault";
+    config: {
+        /** Vault server address (e.g., "https://vault.example.com:8200") */
+        address: string;
+        /** Authentication token */
+        token?: string;
+        /** Vault namespace (enterprise feature) */
+        namespace?: string;
+        /** KV mount path (default: "secret") */
+        mountPath?: string;
+        /** API version (default: "v1") */
+        apiVersion?: string;
+    };
+}
+/**
+ * Configuration for the AWS Secrets Manager provider
+ */
+export interface AWSSecretsProviderConfig {
+    type: "aws";
+    config: {
+        /** AWS region (e.g., "us-east-1") */
+        region: string;
+        /** AWS access key ID (falls back to SDK defaults if omitted) */
+        accessKeyId?: string;
+        /** AWS secret access key */
+        secretAccessKey?: string;
+        /** AWS profile name from credentials file */
+        profile?: string;
+    };
+}
+/**
+ * Configuration for the GCP Secret Manager provider
+ */
+export interface GCPSecretProviderConfig {
+    type: "gcp";
+    config: {
+        /** GCP project ID */
+        projectId: string;
+        /** Path to service account key file */
+        keyFile?: string;
+    };
+}
+/**
+ * Union of all supported provider configurations
+ */
+export type SecretProviderConfig = EnvironmentProviderConfig | InMemoryProviderConfig | VaultProviderConfig | AWSSecretsProviderConfig | GCPSecretProviderConfig;
+/**
+ * Cache configuration for the secret manager
+ */
+export interface SecretCacheConfig {
+    /** Whether caching is enabled */
+    enabled: boolean;
+    /** Time-to-live in milliseconds */
+    ttlMs: number;
+    /** Maximum number of cached entries (LRU eviction) */
+    maxSize: number;
+}
+/**
+ * Top-level configuration for SecretManager
+ */
+export interface SecretManagerConfig {
+    /** Ordered list of provider configurations; first match wins */
+    providers: SecretProviderConfig[];
+    /** Optional caching layer */
+    cache?: SecretCacheConfig;
+    /** Whether to emit audit events on secret access (default: false) */
+    auditLog?: boolean;
+}
+/**
+ * Secret provider backed by process.env
+ *
+ * Reads environment variables, optionally with a prefix. Supports
+ * case-insensitive lookups when configured.
+ *
+ * @example
+ * ```typescript
+ * const provider = new EnvironmentSecretProvider({ prefix: "APP_" });
+ * // Reads process.env.APP_DATABASE_URL
+ * const dbUrl = await provider.get("DATABASE_URL");
+ * ```
+ */
+export declare class EnvironmentSecretProvider implements SecretProvider {
+    readonly name = "environment";
+    private prefix;
+    private caseSensitive;
+    constructor(config?: {
+        prefix?: string;
+        caseSensitive?: boolean;
+    });
+    /**
+     * Retrieve an environment variable value
+     * @param key - Variable name (without prefix)
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Set an environment variable (primarily useful for testing)
+     * @param key - Variable name (without prefix)
+     * @param value - Value to set
+     */
+    set(key: string, value: string, _metadata?: SecretMetadata): Promise<void>;
+    /**
+     * Delete an environment variable
+     * @param key - Variable name (without prefix)
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * List environment variable names matching the configured prefix
+     * @param prefix - Additional prefix to filter by (applied after the provider prefix)
+     */
+    list(prefix?: string): Promise<string[]>;
+    /**
+     * Check whether an environment variable exists
+     * @param key - Variable name (without prefix)
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Build the full environment variable name from a logical key
+     */
+    private resolveKey;
+}
+/**
+ * In-memory secret provider for testing and development
+ *
+ * Stores secrets in a Map with full CRUD support. Provides stats
+ * for debugging and verification.
+ *
+ * @example
+ * ```typescript
+ * const provider = new InMemorySecretProvider();
+ * await provider.set("API_KEY", "test-key-123");
+ * const key = await provider.get("API_KEY"); // "test-key-123"
+ * console.log(provider.getStats()); // { size: 1, keys: ["API_KEY"] }
+ * ```
+ */
+export declare class InMemorySecretProvider implements SecretProvider {
+    readonly name = "memory";
+    private store;
+    /**
+     * Retrieve a secret from the in-memory store
+     * @param key - The secret key
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Store a secret in the in-memory store
+     * @param key - The secret key
+     * @param value - The secret value
+     * @param metadata - Optional metadata
+     */
+    set(key: string, value: string, metadata?: SecretMetadata): Promise<void>;
+    /**
+     * Delete a secret from the in-memory store
+     * @param key - The secret key
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * List all secret keys, optionally filtered by prefix
+     * @param prefix - Optional prefix filter
+     */
+    list(prefix?: string): Promise<string[]>;
+    /**
+     * Check whether a secret exists in the store
+     * @param key - The secret key
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Get debug statistics about the in-memory store
+     * @returns Object with size and list of keys
+     */
+    getStats(): {
+        size: number;
+        keys: string[];
+    };
+    /**
+     * Clear all secrets from the store
+     */
+    clear(): void;
+}
+/**
+ * HashiCorp Vault secret provider (KV v2 engine)
+ *
+ * Communicates with Vault via its HTTP REST API using the native `fetch` API.
+ * Supports token-based authentication, namespaces, and configurable mount paths.
+ *
+ * @example
+ * ```typescript
+ * const vault = new VaultSecretProvider({
+ *   address: "https://vault.example.com:8200",
+ *   token: process.env.VAULT_TOKEN,
+ *   mountPath: "secret",
+ * });
+ *
+ * const dbPassword = await vault.get("database/credentials");
+ * ```
+ */
+export declare class VaultSecretProvider implements SecretProvider {
+    readonly name = "vault";
+    private address;
+    private token;
+    private namespace;
+    private mountPath;
+    private apiVersion;
+    constructor(config: {
+        address: string;
+        token?: string;
+        namespace?: string;
+        mountPath?: string;
+        apiVersion?: string;
+    });
+    /**
+     * Read a secret from Vault KV v2
+     * @param key - The secret path within the mount
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Write a secret to Vault KV v2
+     * @param key - The secret path within the mount
+     * @param value - The secret value
+     * @param metadata - Optional metadata (stored as custom_metadata)
+     */
+    set(key: string, value: string, metadata?: SecretMetadata): Promise<void>;
+    /**
+     * Delete a secret from Vault KV v2
+     * @param key - The secret path within the mount
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * List secret keys under a given path prefix
+     * @param prefix - Optional path prefix
+     */
+    list(prefix?: string): Promise<string[]>;
+    /**
+     * Check whether a secret exists in Vault
+     * @param key - The secret path within the mount
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Update the Vault token (e.g., after token renewal)
+     * @param token - The new Vault token
+     */
+    setToken(token: string): void;
+    /**
+     * Build the full URL for a Vault KV v2 API call
+     */
+    private buildUrl;
+    /**
+     * Build common HTTP headers for Vault requests
+     */
+    private buildHeaders;
+    /**
+     * Set custom metadata on a secret in Vault KV v2
+     */
+    private setMetadata;
+}
+/**
+ * AWS Secrets Manager provider
+ *
+ * Uses the `@aws-sdk/client-secrets-manager` SDK, loaded dynamically at
+ * first use to avoid hard dependencies.
+ *
+ * @example
+ * ```typescript
+ * const aws = new AWSSecretsProvider({
+ *   region: "us-east-1",
+ * });
+ *
+ * const apiKey = await aws.get("prod/api-key");
+ * ```
+ */
+export declare class AWSSecretsProvider implements SecretProvider {
+    readonly name = "aws";
+    private region;
+    private accessKeyId;
+    private secretAccessKey;
+    private profile;
+    private client;
+    constructor(config: {
+        region: string;
+        accessKeyId?: string;
+        secretAccessKey?: string;
+        profile?: string;
+    });
+    /**
+     * Retrieve a secret from AWS Secrets Manager
+     * @param key - The secret name or ARN
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Create or update a secret in AWS Secrets Manager
+     * @param key - The secret name
+     * @param value - The secret value
+     * @param metadata - Optional metadata (tags and description supported)
+     */
+    set(key: string, value: string, metadata?: SecretMetadata): Promise<void>;
+    /**
+     * Delete a secret from AWS Secrets Manager
+     * @param key - The secret name or ARN
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * List secrets in AWS Secrets Manager, optionally filtered by name prefix
+     * @param prefix - Optional name prefix filter
+     */
+    list(prefix?: string): Promise<string[]>;
+    /**
+     * Check whether a secret exists in AWS Secrets Manager
+     * @param key - The secret name or ARN
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Lazily initialize and cache the AWS SecretsManager client
+     */
+    private getClient;
+    /**
+     * Dynamically import the AWS Secrets Manager SDK
+     */
+    private getSDK;
+    /**
+     * Type-safe check for AWS SDK error names
+     */
+    private isAWSError;
+}
+/**
+ * Google Cloud Secret Manager provider
+ *
+ * Uses the `@google-cloud/secret-manager` SDK, loaded dynamically at
+ * first use to avoid hard dependencies.
+ *
+ * @example
+ * ```typescript
+ * const gcp = new GCPSecretProvider({
+ *   projectId: "my-project",
+ * });
+ *
+ * const apiKey = await gcp.get("api-key");
+ * ```
+ */
+export declare class GCPSecretProvider implements SecretProvider {
+    readonly name = "gcp";
+    private projectId;
+    private keyFile;
+    private client;
+    constructor(config: {
+        projectId: string;
+        keyFile?: string;
+    });
+    /**
+     * Retrieve the latest version of a secret from GCP Secret Manager
+     * @param key - The secret ID
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Create a secret and add a version, or add a new version to an existing secret
+     * @param key - The secret ID
+     * @param value - The secret value
+     * @param metadata - Optional metadata (tags mapped to GCP labels)
+     */
+    set(key: string, value: string, metadata?: SecretMetadata): Promise<void>;
+    /**
+     * Delete a secret from GCP Secret Manager
+     * @param key - The secret ID
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * List secrets in the GCP project, optionally filtered by prefix
+     * @param prefix - Optional prefix filter applied to secret IDs
+     */
+    list(prefix?: string): Promise<string[]>;
+    /**
+     * Check whether a secret exists in GCP Secret Manager
+     * @param key - The secret ID
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Lazily initialize and cache the GCP Secret Manager client
+     */
+    private getClient;
+    /**
+     * Check for GCP "not found" errors (gRPC status code 5)
+     */
+    private isGCPNotFoundError;
+    /**
+     * Check for specific gRPC error codes from the GCP SDK
+     */
+    private isGCPError;
+}
+/**
+ * Unified Secret Manager for the Blok Framework
+ *
+ * Orchestrates multiple secret providers with a provider chain (first match
+ * wins), optional caching, and audit event emission.
+ *
+ * @example
+ * ```typescript
+ * const manager = new SecretManager({
+ *   providers: [
+ *     { type: "vault", config: { address: "https://vault:8200", token: "s.xxx" } },
+ *     { type: "environment", config: { prefix: "BLOK_" } },
+ *   ],
+ *   cache: { enabled: true, ttlMs: 300_000, maxSize: 500 },
+ *   auditLog: true,
+ * });
+ *
+ * manager.on("secretAccess", (event) => {
+ *   console.log(`[audit] ${event.operation} ${event.key} via ${event.provider}`);
+ * });
+ *
+ * const password = await manager.getSecretOrThrow("DB_PASSWORD");
+ * const connStr = await manager.resolveTemplate(
+ *   "postgres://admin:${secret:DB_PASSWORD}@db:5432/app"
+ * );
+ * ```
+ */
+export declare class SecretManager extends EventEmitter {
+    private providers;
+    private cache;
+    private cacheConfig;
+    private auditLog;
+    private cacheAccessOrder;
+    constructor(config: SecretManagerConfig);
+    /**
+     * Retrieve a secret value by key
+     *
+     * Checks the cache first (if enabled), then queries each provider
+     * in order until a value is found.
+     *
+     * @param key - The secret key
+     * @returns The secret value, or null if not found in any provider
+     */
+    getSecret(key: string): Promise<string | null>;
+    /**
+     * Retrieve a secret or throw if it does not exist
+     *
+     * @param key - The secret key
+     * @returns The secret value
+     * @throws Error if the secret is not found in any provider
+     */
+    getSecretOrThrow(key: string): Promise<string>;
+    /**
+     * Store a secret value in the first writable provider
+     *
+     * @param key - The secret key
+     * @param value - The secret value
+     * @param metadata - Optional metadata to associate with the secret
+     */
+    setSecret(key: string, value: string, metadata?: SecretMetadata): Promise<void>;
+    /**
+     * Delete a secret from all providers that contain it
+     *
+     * @param key - The secret key
+     */
+    deleteSecret(key: string): Promise<void>;
+    /**
+     * List secret keys across all providers, optionally filtered by prefix
+     *
+     * Merges results from all providers and deduplicates.
+     *
+     * @param prefix - Optional prefix filter
+     * @returns Deduplicated array of secret key names
+     */
+    listSecrets(prefix?: string): Promise<string[]>;
+    /**
+     * Check whether a secret exists in any provider
+     *
+     * @param key - The secret key
+     * @returns True if the secret exists in at least one provider
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Resolve `${secret:KEY}` patterns in a template string
+     *
+     * Replaces every occurrence of `${secret:SOME_KEY}` with the actual
+     * secret value from the provider chain. Missing secrets are replaced
+     * with an empty string.
+     *
+     * @param template - The template string with `${secret:...}` placeholders
+     * @returns The resolved string with secret values substituted
+     *
+     * @example
+     * ```typescript
+     * const resolved = await manager.resolveTemplate(
+     *   "mongodb://${secret:MONGO_USER}:${secret:MONGO_PASS}@host/db"
+     * );
+     * ```
+     */
+    resolveTemplate(template: string): Promise<string>;
+    /**
+     * Get the list of configured providers
+     * @returns Array of provider instances
+     */
+    getProviders(): SecretProvider[];
+    /**
+     * Get current cache statistics
+     * @returns Object with cache size and hit information
+     */
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+        enabled: boolean;
+    };
+    /**
+     * Clear the secret cache
+     */
+    clearCache(): void;
+    /**
+     * Create a provider instance from its configuration
+     */
+    private createProvider;
+    /**
+     * Retrieve a value from the cache, returning undefined if not found or expired
+     */
+    private getCached;
+    /**
+     * Store a value in the cache with TTL, evicting LRU entries if at capacity
+     */
+    private setCache;
+    /**
+     * Emit a secret access audit event
+     */
+    private emitAccess;
+}