/**
 * @fileoverview Canonical Middleware type definitions for the Vorion Platform.
 *
 * This file provides the authoritative definitions for middleware-related types
 * including rate limiting, CORS, error responses, and security headers.
 * These types unify various implementations across the codebase into a single
 * source of truth.
 *
 * @module @vorion/contracts/canonical/middleware
 */
import { z } from 'zod';
/**
 * Configuration for rate limiting middleware.
 *
 * Defines the parameters for controlling request frequency.
 */
export interface RateLimitConfig {
    /** Maximum requests per window */
    readonly limit: number;
    /** Window size in milliseconds */
    readonly windowMs: number;
    /** Optional key generator function identifier */
    readonly keyGenerator?: string;
    /** Whether to skip rate limiting for successful requests */
    readonly skipSuccessfulRequests?: boolean;
    /** Whether to skip rate limiting for failed requests */
    readonly skipFailedRequests?: boolean;
    /** Custom message when rate limit is exceeded */
    readonly message?: string;
    /** HTTP status code when rate limit is exceeded (default: 429) */
    readonly statusCode?: number;
    /** Headers to include in rate limit responses */
    readonly headers?: boolean;
}
/**
 * Zod schema for RateLimitConfig validation.
 */
export declare const rateLimitConfigSchema: z.ZodObject<{
    limit: z.ZodNumber;
    windowMs: z.ZodNumber;
    keyGenerator: z.ZodOptional<z.ZodString>;
    skipSuccessfulRequests: z.ZodOptional<z.ZodBoolean>;
    skipFailedRequests: z.ZodOptional<z.ZodBoolean>;
    message: z.ZodOptional<z.ZodString>;
    statusCode: z.ZodOptional<z.ZodNumber>;
    headers: z.ZodOptional<z.ZodBoolean>;
}, "strip", z.ZodTypeAny, {
    limit: number;
    windowMs: number;
    message?: string | undefined;
    keyGenerator?: string | undefined;
    skipSuccessfulRequests?: boolean | undefined;
    skipFailedRequests?: boolean | undefined;
    statusCode?: number | undefined;
    headers?: boolean | undefined;
}, {
    limit: number;
    windowMs: number;
    message?: string | undefined;
    keyGenerator?: string | undefined;
    skipSuccessfulRequests?: boolean | undefined;
    skipFailedRequests?: boolean | undefined;
    statusCode?: number | undefined;
    headers?: boolean | undefined;
}>;
/**
 * Result of a rate limit check.
 */
export interface RateLimitResult {
    /** Whether the request is allowed */
    readonly allowed: boolean;
    /** Current request count in the window */
    readonly current: number;
    /** Maximum requests allowed */
    readonly limit: number;
    /** Remaining requests in the window */
    readonly remaining: number;
    /** When the window resets (Unix timestamp in seconds) */
    readonly resetAt: number;
    /** Time until reset in seconds */
    readonly retryAfter?: number;
}
/**
 * Zod schema for RateLimitResult validation.
 */
export declare const rateLimitResultSchema: z.ZodObject<{
    allowed: z.ZodBoolean;
    current: z.ZodNumber;
    limit: z.ZodNumber;
    remaining: z.ZodNumber;
    resetAt: z.ZodNumber;
    retryAfter: z.ZodOptional<z.ZodNumber>;
}, "strip", z.ZodTypeAny, {
    allowed: boolean;
    limit: number;
    current: number;
    remaining: number;
    resetAt: number;
    retryAfter?: number | undefined;
}, {
    allowed: boolean;
    limit: number;
    current: number;
    remaining: number;
    resetAt: number;
    retryAfter?: number | undefined;
}>;
/**
 * Rate limit headers included in responses.
 */
export interface RateLimitHeaders {
    /** Maximum requests allowed in the window */
    readonly 'X-RateLimit-Limit': string;
    /** Remaining requests in the window */
    readonly 'X-RateLimit-Remaining': string;
    /** When the window resets (Unix timestamp) */
    readonly 'X-RateLimit-Reset': string;
    /** Seconds until retry is allowed (when rate limited) */
    readonly 'Retry-After'?: string;
}
/**
 * Tenant-specific rate limit configuration.
 */
export interface TenantRateLimitConfig extends RateLimitConfig {
    /** Tenant identifier */
    readonly tenantId: string;
    /** Whether this is a premium/elevated tier */
    readonly isPremium?: boolean;
    /** Multiplier for premium tier (default: 1) */
    readonly premiumMultiplier?: number;
}
/**
 * Zod schema for TenantRateLimitConfig validation.
 */
export declare const tenantRateLimitConfigSchema: z.ZodObject<{
    limit: z.ZodNumber;
    windowMs: z.ZodNumber;
    keyGenerator: z.ZodOptional<z.ZodString>;
    skipSuccessfulRequests: z.ZodOptional<z.ZodBoolean>;
    skipFailedRequests: z.ZodOptional<z.ZodBoolean>;
    message: z.ZodOptional<z.ZodString>;
    statusCode: z.ZodOptional<z.ZodNumber>;
    headers: z.ZodOptional<z.ZodBoolean>;
} & {
    tenantId: z.ZodString;
    isPremium: z.ZodOptional<z.ZodBoolean>;
    premiumMultiplier: z.ZodOptional<z.ZodNumber>;
}, "strip", z.ZodTypeAny, {
    tenantId: string;
    limit: number;
    windowMs: number;
    message?: string | undefined;
    keyGenerator?: string | undefined;
    skipSuccessfulRequests?: boolean | undefined;
    skipFailedRequests?: boolean | undefined;
    statusCode?: number | undefined;
    headers?: boolean | undefined;
    isPremium?: boolean | undefined;
    premiumMultiplier?: number | undefined;
}, {
    tenantId: string;
    limit: number;
    windowMs: number;
    message?: string | undefined;
    keyGenerator?: string | undefined;
    skipSuccessfulRequests?: boolean | undefined;
    skipFailedRequests?: boolean | undefined;
    statusCode?: number | undefined;
    headers?: boolean | undefined;
    isPremium?: boolean | undefined;
    premiumMultiplier?: number | undefined;
}>;
/**
 * CORS (Cross-Origin Resource Sharing) configuration.
 */
export interface CorsConfig {
    /** Allowed origins (use '*' for all, or array of specific origins) */
    readonly origin: string | readonly string[];
    /** Allowed HTTP methods */
    readonly methods?: readonly string[];
    /** Allowed request headers */
    readonly headers?: readonly string[];
    /** Headers to expose to the client */
    readonly exposedHeaders?: readonly string[];
    /** Whether to allow credentials (cookies, authorization headers) */
    readonly credentials?: boolean;
    /** Max age for preflight cache in seconds */
    readonly maxAge?: number;
    /** Whether to pass preflight response to the next handler */
    readonly preflightContinue?: boolean;
    /** Status code for successful OPTIONS requests */
    readonly optionsSuccessStatus?: number;
}
/**
 * Zod schema for CorsConfig validation.
 */
export declare const corsConfigSchema: z.ZodObject<{
    origin: z.ZodUnion<[z.ZodString, z.ZodReadonly<z.ZodArray<z.ZodString, "many">>]>;
    methods: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
    headers: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
    exposedHeaders: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
    credentials: z.ZodOptional<z.ZodBoolean>;
    maxAge: z.ZodOptional<z.ZodNumber>;
    preflightContinue: z.ZodOptional<z.ZodBoolean>;
    optionsSuccessStatus: z.ZodOptional<z.ZodNumber>;
}, "strip", z.ZodTypeAny, {
    origin: string | readonly string[];
    headers?: readonly string[] | undefined;
    methods?: readonly string[] | undefined;
    exposedHeaders?: readonly string[] | undefined;
    credentials?: boolean | undefined;
    maxAge?: number | undefined;
    preflightContinue?: boolean | undefined;
    optionsSuccessStatus?: number | undefined;
}, {
    origin: string | readonly string[];
    headers?: readonly string[] | undefined;
    methods?: readonly string[] | undefined;
    exposedHeaders?: readonly string[] | undefined;
    credentials?: boolean | undefined;
    maxAge?: number | undefined;
    preflightContinue?: boolean | undefined;
    optionsSuccessStatus?: number | undefined;
}>;
/**
 * Standard error response structure.
 *
 * Provides a consistent format for API error responses across the platform.
 */
export interface ErrorResponse {
    readonly error: {
        /** Error code (e.g., 'VALIDATION_ERROR', 'NOT_FOUND') */
        readonly code: string;
        /** Human-readable error message */
        readonly message: string;
        /** Additional error details */
        readonly details?: Readonly<Record<string, unknown>>;
        /** Request ID for tracing */
        readonly requestId?: string;
        /** Timestamp of the error */
        readonly timestamp?: string;
        /** Path that generated the error */
        readonly path?: string;
    };
}
/**
 * Zod schema for ErrorResponse validation.
 */
export declare const errorResponseSchema: z.ZodObject<{
    error: z.ZodObject<{
        code: z.ZodString;
        message: z.ZodString;
        details: z.ZodOptional<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
        requestId: z.ZodOptional<z.ZodString>;
        timestamp: z.ZodOptional<z.ZodString>;
        path: z.ZodOptional<z.ZodString>;
    }, "strip", z.ZodTypeAny, {
        code: string;
        message: string;
        path?: string | undefined;
        details?: Readonly<Record<string, unknown>> | undefined;
        timestamp?: string | undefined;
        requestId?: string | undefined;
    }, {
        code: string;
        message: string;
        path?: string | undefined;
        details?: Readonly<Record<string, unknown>> | undefined;
        timestamp?: string | undefined;
        requestId?: string | undefined;
    }>;
}, "strip", z.ZodTypeAny, {
    error: {
        code: string;
        message: string;
        path?: string | undefined;
        details?: Readonly<Record<string, unknown>> | undefined;
        timestamp?: string | undefined;
        requestId?: string | undefined;
    };
}, {
    error: {
        code: string;
        message: string;
        path?: string | undefined;
        details?: Readonly<Record<string, unknown>> | undefined;
        timestamp?: string | undefined;
        requestId?: string | undefined;
    };
}>;
/**
 * Error category for classification.
 */
export type ErrorCategory = 'validation' | 'authentication' | 'authorization' | 'not_found' | 'conflict' | 'rate_limit' | 'internal' | 'external' | 'timeout' | 'unavailable';
/**
 * Zod schema for ErrorCategory validation.
 */
export declare const errorCategorySchema: z.ZodEnum<["validation", "authentication", "authorization", "not_found", "conflict", "rate_limit", "internal", "external", "timeout", "unavailable"]>;
/**
 * Security headers configuration.
 */
export interface SecurityHeadersConfig {
    /** X-Content-Type-Options header value */
    readonly contentTypeOptions?: string;
    /** X-Frame-Options header value */
    readonly frameOptions?: string;
    /** X-XSS-Protection header value */
    readonly xssProtection?: string;
    /** Referrer-Policy header value */
    readonly referrerPolicy?: string;
    /** Permissions-Policy header value */
    readonly permissionsPolicy?: string;
}
/**
 * Zod schema for SecurityHeadersConfig validation.
 */
export declare const securityHeadersConfigSchema: z.ZodObject<{
    contentTypeOptions: z.ZodOptional<z.ZodString>;
    frameOptions: z.ZodOptional<z.ZodString>;
    xssProtection: z.ZodOptional<z.ZodString>;
    referrerPolicy: z.ZodOptional<z.ZodString>;
    permissionsPolicy: z.ZodOptional<z.ZodString>;
}, "strip", z.ZodTypeAny, {
    contentTypeOptions?: string | undefined;
    frameOptions?: string | undefined;
    xssProtection?: string | undefined;
    referrerPolicy?: string | undefined;
    permissionsPolicy?: string | undefined;
}, {
    contentTypeOptions?: string | undefined;
    frameOptions?: string | undefined;
    xssProtection?: string | undefined;
    referrerPolicy?: string | undefined;
    permissionsPolicy?: string | undefined;
}>;
/**
 * Content Security Policy (CSP) configuration.
 */
export interface CspConfig {
    /** Default source directive */
    readonly defaultSrc?: readonly string[];
    /** Script source directive */
    readonly scriptSrc?: readonly string[];
    /** Style source directive */
    readonly styleSrc?: readonly string[];
    /** Image source directive */
    readonly imgSrc?: readonly string[];
    /** Font source directive */
    readonly fontSrc?: readonly string[];
    /** Connect source directive */
    readonly connectSrc?: readonly string[];
    /** Frame source directive */
    readonly frameSrc?: readonly string[];
    /** Object source directive */
    readonly objectSrc?: readonly string[];
    /** Media source directive */
    readonly mediaSrc?: readonly string[];
    /** Whether to report violations only */
    readonly reportOnly?: boolean;
    /** Report URI for violations */
    readonly reportUri?: string;
}
/**
 * Zod schema for CspConfig validation.
 */
export declare const cspConfigSchema: z.ZodObject<{
    defaultSrc: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
    scriptSrc: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
    styleSrc: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
    imgSrc: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
    fontSrc: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
    connectSrc: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
    frameSrc: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
    objectSrc: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
    mediaSrc: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
    reportOnly: z.ZodOptional<z.ZodBoolean>;
    reportUri: z.ZodOptional<z.ZodString>;
}, "strip", z.ZodTypeAny, {
    defaultSrc?: readonly string[] | undefined;
    scriptSrc?: readonly string[] | undefined;
    styleSrc?: readonly string[] | undefined;
    imgSrc?: readonly string[] | undefined;
    fontSrc?: readonly string[] | undefined;
    connectSrc?: readonly string[] | undefined;
    frameSrc?: readonly string[] | undefined;
    objectSrc?: readonly string[] | undefined;
    mediaSrc?: readonly string[] | undefined;
    reportOnly?: boolean | undefined;
    reportUri?: string | undefined;
}, {
    defaultSrc?: readonly string[] | undefined;
    scriptSrc?: readonly string[] | undefined;
    styleSrc?: readonly string[] | undefined;
    imgSrc?: readonly string[] | undefined;
    fontSrc?: readonly string[] | undefined;
    connectSrc?: readonly string[] | undefined;
    frameSrc?: readonly string[] | undefined;
    objectSrc?: readonly string[] | undefined;
    mediaSrc?: readonly string[] | undefined;
    reportOnly?: boolean | undefined;
    reportUri?: string | undefined;
}>;
/**
 * HTTP Strict Transport Security (HSTS) configuration.
 */
export interface HstsConfig {
    /** Max age in seconds */
    readonly maxAge: number;
    /** Whether to include subdomains */
    readonly includeSubDomains?: boolean;
    /** Whether to enable preload */
    readonly preload?: boolean;
}
/**
 * Zod schema for HstsConfig validation.
 */
export declare const hstsConfigSchema: z.ZodObject<{
    maxAge: z.ZodNumber;
    includeSubDomains: z.ZodOptional<z.ZodBoolean>;
    preload: z.ZodOptional<z.ZodBoolean>;
}, "strip", z.ZodTypeAny, {
    maxAge: number;
    includeSubDomains?: boolean | undefined;
    preload?: boolean | undefined;
}, {
    maxAge: number;
    includeSubDomains?: boolean | undefined;
    preload?: boolean | undefined;
}>;
/**
 * Request logging configuration.
 */
export interface RequestLoggingConfig {
    /** Whether to log request bodies */
    readonly logBody?: boolean;
    /** Whether to log response bodies */
    readonly logResponse?: boolean;
    /** Whether to log headers */
    readonly logHeaders?: boolean;
    /** Headers to redact from logs */
    readonly redactHeaders?: readonly string[];
    /** Maximum body size to log (bytes) */
    readonly maxBodySize?: number;
    /** Log level */
    readonly level?: 'debug' | 'info' | 'warn' | 'error';
}
/**
 * Zod schema for RequestLoggingConfig validation.
 */
export declare const requestLoggingConfigSchema: z.ZodObject<{
    logBody: z.ZodOptional<z.ZodBoolean>;
    logResponse: z.ZodOptional<z.ZodBoolean>;
    logHeaders: z.ZodOptional<z.ZodBoolean>;
    redactHeaders: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
    maxBodySize: z.ZodOptional<z.ZodNumber>;
    level: z.ZodOptional<z.ZodEnum<["debug", "info", "warn", "error"]>>;
}, "strip", z.ZodTypeAny, {
    level?: "debug" | "error" | "info" | "warn" | undefined;
    logBody?: boolean | undefined;
    logResponse?: boolean | undefined;
    logHeaders?: boolean | undefined;
    redactHeaders?: readonly string[] | undefined;
    maxBodySize?: number | undefined;
}, {
    level?: "debug" | "error" | "info" | "warn" | undefined;
    logBody?: boolean | undefined;
    logResponse?: boolean | undefined;
    logHeaders?: boolean | undefined;
    redactHeaders?: readonly string[] | undefined;
    maxBodySize?: number | undefined;
}>;
/**
 * Type guard for RateLimitConfig.
 */
export declare function isRateLimitConfig(value: unknown): value is RateLimitConfig;
/**
 * Type guard for CorsConfig.
 */
export declare function isCorsConfig(value: unknown): value is CorsConfig;
/**
 * Type guard for ErrorResponse.
 */
export declare function isErrorResponse(value: unknown): value is ErrorResponse;
/**
 * Type guard for ErrorCategory.
 */
export declare function isErrorCategory(value: unknown): value is ErrorCategory;
/**
 * Creates a standard error response.
 *
 * @param code - Error code
 * @param message - Human-readable message
 * @param options - Additional options
 * @returns ErrorResponse object
 */
export declare function createErrorResponse(code: string, message: string, options?: {
    details?: Record<string, unknown>;
    requestId?: string;
    path?: string;
}): ErrorResponse;
/**
 * Default rate limit configuration.
 */
export declare const DEFAULT_RATE_LIMIT_CONFIG: RateLimitConfig;
/**
 * Default CORS configuration.
 */
export declare const DEFAULT_CORS_CONFIG: CorsConfig;
/**
 * Default security headers configuration.
 */
export declare const DEFAULT_SECURITY_HEADERS_CONFIG: SecurityHeadersConfig;