/**
 * API Key Enforcement Middleware
 *
 * Fastify plugin that integrates API key authentication with the existing
 * JWT-based auth flow. Provides configurable route-level authentication
 * strategies and enforces rate limiting from API keys.
 *
 * Authentication Strategies:
 * - JWT only: Traditional token-based auth (default for browser clients)
 * - API key only: Machine-to-machine communication
 * - JWT OR API key: Routes that accept either method
 * - API key with specific scopes: Scope-restricted API key access
 *
 * @packageDocumentation
 */
import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
import { apiKeyMiddleware, requireScopes, getApiKey, hasApiKey, getApiKeyTenantId } from '../../security/api-keys/middleware.js';
import { type ApiKeyScope } from '../../security/api-keys/types.js';
import { type ApiKeyService } from '../../security/api-keys/service.js';
/**
 * Authentication method
 */
export type AuthMethod = 'jwt' | 'api_key' | 'jwt_or_api_key' | 'none';
/**
 * Route authentication configuration
 */
export interface RouteAuthConfig {
    /** Authentication method for this route */
    method: AuthMethod;
    /** Required API key scopes (only for api_key or jwt_or_api_key) */
    requiredScopes?: ApiKeyScope[];
    /** Require all scopes (AND) or any scope (OR). Default: true (AND) */
    requireAllScopes?: boolean;
    /** Custom skip condition */
    skip?: (request: FastifyRequest) => boolean;
}
/**
 * Route pattern with auth configuration
 */
export interface RoutePattern {
    /** HTTP method (GET, POST, etc.) or '*' for all methods */
    method: string | '*';
    /** URL pattern (exact match or with wildcards) */
    pattern: string;
    /** Auth configuration */
    auth: RouteAuthConfig;
}
/**
 * API Key Enforcement Plugin Options
 */
export interface ApiKeyEnforcementOptions {
    /** API key service instance */
    apiKeyService?: ApiKeyService;
    /** Default authentication method for unspecified routes */
    defaultAuth?: AuthMethod;
    /** Default required scopes for API key auth */
    defaultScopes?: ApiKeyScope[];
    /** Route-specific auth configurations */
    routeConfigs?: RoutePattern[];
    /** Paths to skip all auth (e.g., /health, /ready) */
    skipPaths?: string[];
    /** Enforce API key rate limits */
    enforceRateLimit?: boolean;
    /** Log authentication decisions */
    logAuthDecisions?: boolean;
}
/**
 * Extended request with auth context
 */
declare module 'fastify' {
    interface FastifyRequest {
        /** Unified auth context (JWT or API key) */
        authMethod?: 'jwt' | 'api_key' | 'none';
        /** Tenant ID from auth (JWT or API key) */
        authTenantId?: string;
        /** User/key ID from auth */
        authSubject?: string;
    }
}
/**
 * Async hook handler type (2 args, returns Promise)
 * This matches the actual implementation of apiKeyMiddleware which is async
 */
type AsyncHookHandler = (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
/**
 * API Key Enforcement Plugin
 *
 * Registers API key authentication alongside existing JWT auth.
 *
 * @example
 * ```typescript
 * await fastify.register(apiKeyEnforcementPlugin, {
 *   defaultAuth: 'jwt_or_api_key',
 *   enforceRateLimit: true,
 *   routeConfigs: [
 *     { method: 'POST', pattern: '/api/v1/webhooks', auth: { method: 'api_key', requiredScopes: ['webhook'] } },
 *   ],
 * });
 * ```
 */
export declare const apiKeyEnforcementPlugin: (fastify: FastifyInstance, options: ApiKeyEnforcementOptions) => Promise<void>;
/**
 * Create a route-specific auth config
 */
export declare function createRouteAuth(method: AuthMethod, options?: {
    requiredScopes?: ApiKeyScope[];
    requireAllScopes?: boolean;
    skip?: (request: FastifyRequest) => boolean;
}): RouteAuthConfig;
/**
 * Create a preHandler hook for specific auth requirements
 *
 * Use this for per-route auth configuration when registered at the route level.
 *
 * @example
 * ```typescript
 * fastify.post('/api/v1/sensitive', {
 *   preHandler: requireApiKeyAuth(['admin']),
 * }, handler);
 * ```
 */
export declare function requireApiKeyAuth(requiredScopes?: ApiKeyScope[], options?: {
    requireAll?: boolean;
}): AsyncHookHandler;
/**
 * Create a preHandler that accepts either JWT or API key
 */
export declare function requireJwtOrApiKey(apiKeyScopes?: ApiKeyScope[]): AsyncHookHandler;
export { apiKeyMiddleware, requireScopes, getApiKey, hasApiKey, getApiKeyTenantId, };
export default apiKeyEnforcementPlugin;
//# sourceMappingURL=api-key-enforcement.d.ts.map