/** * API Key Auth Middleware — requireApiKey() * * MCP Fusion middleware that ensures requests carry a valid API key. * Extracts the key, validates it via ApiKeyManager, and rejects * invalid/missing keys with self-healing error responses. * * @example * ```ts * import { requireApiKey } from '@mcpfusion/api-key'; * * const projects = createTool('projects') * .use(requireApiKey({ keys: ['sk_live_abc123'] })) * .action({ name: 'list', handler: async (ctx) => { ... } }); * ``` */ import type { ToolResponse } from '@mcpfusion/core'; import type { ApiKeyManagerConfig } from './ApiKeyManager.js'; export interface RequireApiKeyOptions extends ApiKeyManagerConfig { /** * Custom function to extract the API key from the context. * Default: checks `ctx.apiKey`, `ctx.headers['x-api-key']`, * `ctx.headers.authorization` (ApiKey/Bearer prefix). */ readonly extractKey?: (ctx: unknown) => string | null | undefined; /** * Callback invoked after successful validation. * Use this to inject key metadata into the context. */ readonly onValidated?: (ctx: unknown, metadata?: Record) => void; /** Error code for toolError response. Default: 'APIKEY_INVALID' */ readonly errorCode?: string; /** Recovery hint for the LLM. Default: 'Provide a valid API key' */ readonly recoveryHint?: string; /** Recovery action name. Default: 'auth' */ readonly recoveryAction?: string; /** * Optional callback invoked on authentication failure. * Use this to log failed attempts, emit telemetry events, or trigger alerts. * * @example * ```ts * requireApiKey({ * keys: ['sk_live_abc123'], * onAuthFailure: (event) => telemetryBus.emit(event), * }); * ``` */ readonly onAuthFailure?: (event: { type: string; method: string; reason: string; timestamp: number; }) => void; } /** * Creates a MCP Fusion middleware that validates API keys. * * Returns `toolError('APIKEY_INVALID')` with self-healing hints * when no valid key is found. */ export declare function requireApiKey(options: RequireApiKeyOptions): (ctx: unknown, _args: Record, next: () => Promise) => Promise; //# sourceMappingURL=middleware.d.ts.map