/** * API Key Manager — Validation & Hashing * * Validates API keys using multiple strategies: * - Static key set (in-memory) * - SHA-256 hash comparison (for safe storage) * - Async validator function (database lookup) * * All comparisons use timing-safe operations to prevent timing attacks. * * @example * ```ts * import { ApiKeyManager } from '@mcpfusion/api-key'; * * // Static keys * const manager = new ApiKeyManager({ * keys: ['sk_live_abc123', 'sk_live_def456'], * }); * * // Hash-based (for DB storage) * const hash = ApiKeyManager.hashKey('sk_live_abc123'); * const manager = new ApiKeyManager({ hashedKeys: [hash] }); * * // Async validator (DB lookup) * const manager = new ApiKeyManager({ * validator: async (key) => { * const record = await db.apiKeys.findByKey(key); * return record ? { valid: true, metadata: { userId: record.userId } } : { valid: false }; * }, * }); * ``` */ export interface ApiKeyManagerConfig { /** Static set of valid API keys (plaintext). */ readonly keys?: readonly string[]; /** Set of pre-hashed keys (SHA-256 hex). Use `ApiKeyManager.hashKey()` to generate. */ readonly hashedKeys?: readonly string[]; /** * Async validator function for dynamic key lookup (e.g., database). * Takes priority over `keys` and `hashedKeys` when provided. */ readonly validator?: (key: string) => Promise; /** Prefix required on API keys (e.g., 'sk_live_'). Optional. */ readonly prefix?: string; /** Minimum key length. Default: 16 */ readonly minLength?: number; } export interface ApiKeyValidationResult { /** Whether the key is valid. */ readonly valid: boolean; /** Optional metadata about the key owner (userId, scopes, etc.). */ readonly metadata?: Record; /** Reason for rejection (only when valid is false). */ readonly reason?: string; } export declare class ApiKeyManager { private readonly _config; private readonly _minLength; private readonly _keyHashes; constructor(config: ApiKeyManagerConfig); /** * Validate an API key. * * @param key - Raw API key string * @returns Validation result with optional metadata */ validate(key: string): Promise; /** * Quick boolean check without detailed result. */ isValid(key: string): Promise; /** * Hash an API key using SHA-256 for safe storage. * * @param rawKey - Plaintext API key * @returns Hex-encoded SHA-256 hash */ static hashKey(rawKey: string): string; /** * Compare a raw key against a stored hash using timing-safe comparison. * * @param rawKey - Plaintext API key * @param storedHash - SHA-256 hex hash to compare against * @returns Whether the key matches the hash */ static matchKey(rawKey: string, storedHash: string): boolean; /** * Generate a random API key with optional prefix. * * @param options - Generation options * @returns Random API key string */ static generateKey(options?: { prefix?: string; length?: number; }): string; /** * Check if a hash exists in the pre-computed set using timing-safe comparison. * @internal */ private _isHashInSet; /** * Timing-safe string comparison to prevent timing attacks. * @internal */ private static _timingSafeCompare; } //# sourceMappingURL=ApiKeyManager.d.ts.map