/**
 * API Key Middleware for Fastify
 *
 * Provides Fastify middleware for API key authentication:
 * - Extract API key from Authorization header (Bearer) or X-API-Key header
 * - Validate and attach key context to request
 * - Scope enforcement decorator
 * - Rate limit enforcement
 *
 * @packageDocumentation
 */
import type { FastifyInstance, FastifyRequest, preHandlerHookHandler } from 'fastify';
import { type ApiKey, type ApiKeyScope, type ApiKeyContext } from './types.js';
import { ApiKeyService } from './service.js';
/**
 * Middleware options
 */
export interface ApiKeyMiddlewareOptions {
    /** API key service instance */
    service?: ApiKeyService;
    /** Header name for API key (default: X-API-Key) */
    headerName?: string;
    /** Also check Authorization: Bearer header */
    checkBearerHeader?: boolean;
    /** Paths to skip API key validation */
    skipPaths?: string[];
    /** Custom function to skip validation */
    skip?: (request: FastifyRequest) => boolean;
    /** Enforce rate limiting */
    enforceRateLimit?: boolean;
}
/**
 * Scope requirement options
 */
export interface ScopeRequirementOptions {
    /** Require all scopes (AND) or any scope (OR) */
    requireAll?: boolean;
}
/**
 * Fastify middleware function type
 */
export type FastifyMiddleware = preHandlerHookHandler;
declare module 'fastify' {
    interface FastifyRequest {
        /** API key context (present if authenticated via API key) */
        apiKeyContext?: ApiKeyContext;
    }
    interface FastifyInstance {
        /** API key service */
        apiKeyService?: ApiKeyService;
    }
}
/**
 * Create API key authentication middleware
 *
 * Validates API keys and attaches context to requests.
 *
 * @param options - Middleware options
 * @returns Fastify preHandler hook
 *
 * @example
 * ```typescript
 * // Apply to all routes
 * fastify.addHook('preHandler', apiKeyMiddleware({
 *   skipPaths: ['/health', '/docs'],
 *   enforceRateLimit: true,
 * }));
 *
 * // Or apply to specific routes
 * fastify.route({
 *   method: 'GET',
 *   url: '/api/data',
 *   preHandler: [apiKeyMiddleware()],
 *   handler: handleData,
 * });
 * ```
 */
export declare function apiKeyMiddleware(options?: ApiKeyMiddlewareOptions): FastifyMiddleware;
/**
 * Create scope requirement middleware
 *
 * Requires one or more API key scopes.
 *
 * @param requiredScopes - Required scope(s)
 * @param options - Scope requirement options
 * @returns Fastify preHandler hook
 *
 * @example
 * ```typescript
 * // Require write scope
 * fastify.route({
 *   method: 'POST',
 *   url: '/api/data',
 *   preHandler: [apiKeyMiddleware(), requireScopes(['write'])],
 *   handler: handleCreate,
 * });
 *
 * // Require admin OR write scope
 * fastify.route({
 *   method: 'DELETE',
 *   url: '/api/data/:id',
 *   preHandler: [apiKeyMiddleware(), requireScopes(['admin', 'write'], { requireAll: false })],
 *   handler: handleDelete,
 * });
 * ```
 */
export declare function requireScopes(requiredScopes: ApiKeyScope[], options?: ScopeRequirementOptions): FastifyMiddleware;
/**
 * Require read scope
 */
export declare function requireReadScope(): FastifyMiddleware;
/**
 * Require write scope
 */
export declare function requireWriteScope(): FastifyMiddleware;
/**
 * Require admin scope
 */
export declare function requireAdminScope(): FastifyMiddleware;
/**
 * Require webhook scope
 */
export declare function requireWebhookScope(): FastifyMiddleware;
/**
 * Require integration scope
 */
export declare function requireIntegrationScope(): FastifyMiddleware;
/**
 * API Key Plugin Options
 */
export interface ApiKeyPluginOptions extends ApiKeyMiddlewareOptions {
    /** Register as global preHandler */
    global?: boolean;
}
/**
 * Fastify plugin for API key authentication
 *
 * @example
 * ```typescript
 * await fastify.register(apiKeyPlugin, {
 *   skipPaths: ['/health', '/docs'],
 *   enforceRateLimit: true,
 *   global: true,
 * });
 * ```
 */
export declare const apiKeyPlugin: (fastify: FastifyInstance, options: ApiKeyPluginOptions) => Promise<void>;
/**
 * Get API key from request context
 */
export declare function getApiKey(request: FastifyRequest): ApiKey | undefined;
/**
 * Get tenant ID from API key context
 */
export declare function getApiKeyTenantId(request: FastifyRequest): string | undefined;
/**
 * Check if request has a valid API key
 */
export declare function hasApiKey(request: FastifyRequest): boolean;
/**
 * Get API key scopes
 */
export declare function getApiKeyScopes(request: FastifyRequest): ApiKeyScope[];
//# sourceMappingURL=middleware.d.ts.map