/**
 * Audit Middleware
 *
 * Comprehensive audit logging middleware for API endpoints.
 * Records all mutation operations (POST, PUT, PATCH, DELETE) with
 * before/after state tracking for compliance and forensic analysis.
 *
 * @packageDocumentation
 */
import type { FastifyRequest, FastifyReply, FastifyInstance } from 'fastify';
import { type AuditService } from '../../audit/service.js';
import type { AuditTarget } from '../../audit/types.js';
/**
 * Supported HTTP methods for audit logging
 */
export declare const MUTATION_METHODS: readonly ["POST", "PUT", "PATCH", "DELETE"];
export type MutationMethod = (typeof MUTATION_METHODS)[number];
/**
 * Audit event configuration for a specific route
 */
export interface AuditEventConfig {
    /** The event type to record (e.g., 'policy.created', 'escalation.approved') */
    eventType: string;
    /** The type of resource being modified */
    resourceType: AuditTarget['type'];
    /** Function to extract resource ID from request */
    getResourceId?: (request: FastifyRequest) => string | undefined;
    /** Function to extract custom metadata from request */
    getMetadata?: (request: FastifyRequest, reply: FastifyReply) => Record<string, unknown> | undefined;
    /** Function to get the before state for change tracking */
    getBeforeState?: (request: FastifyRequest) => Promise<Record<string, unknown> | undefined>;
    /** Whether to skip logging for this request */
    shouldSkip?: (request: FastifyRequest) => boolean;
}
/**
 * Audit context attached to request for tracking state
 */
export interface AuditContext {
    /** Configured event for this route */
    eventConfig?: AuditEventConfig;
    /** State before the operation (for change tracking) */
    beforeState?: Record<string, unknown>;
    /** Timestamp when request started */
    startTime: number;
    /** Whether audit logging is enabled for this request */
    enabled: boolean;
}
/**
 * Extended request with audit context
 */
interface AuditableRequest extends FastifyRequest {
    auditContext?: AuditContext;
}
/**
 * Configuration options for the audit middleware
 */
export interface AuditMiddlewareOptions {
    /** Whether to log all mutations automatically (default: false) */
    autoLogMutations?: boolean;
    /** Routes to exclude from automatic logging */
    excludePaths?: string[];
    /** Custom audit service instance (for testing) */
    auditService?: AuditService;
    /** Whether to capture before/after state automatically */
    trackStateChanges?: boolean;
}
/**
 * Create audit middleware hooks for a Fastify instance
 */
export declare function createAuditMiddleware(options?: AuditMiddlewareOptions): {
    auditPreHandler: (request: AuditableRequest, _reply: FastifyReply) => Promise<void>;
    auditOnResponse: (request: AuditableRequest, reply: FastifyReply) => Promise<void>;
    auditService: AuditService;
};
/**
 * Decorator to configure audit logging for a specific route handler
 *
 * @example
 * ```typescript
 * fastify.post('/policies', {
 *   preHandler: withAudit({
 *     eventType: 'policy.created',
 *     resourceType: 'policy',
 *     getResourceId: (req) => (req.body as any)?.id,
 *   }),
 * }, handler);
 * ```
 */
export declare function withAudit(config: AuditEventConfig): (request: AuditableRequest, _reply: FastifyReply) => Promise<void>;
/**
 * Create a pre-handler that captures before state for a resource
 *
 * @example
 * ```typescript
 * fastify.put('/policies/:id', {
 *   preHandler: [
 *     captureBeforeState(async (req) => policyService.findById(req.params.id)),
 *     withAudit({ eventType: 'policy.updated', resourceType: 'policy' }),
 *   ],
 * }, handler);
 * ```
 */
export declare function captureBeforeState(getter: (request: FastifyRequest) => Promise<Record<string, unknown> | undefined>): (request: AuditableRequest, _reply: FastifyReply) => Promise<void>;
/**
 * Manually record an audit event from within a route handler
 *
 * @example
 * ```typescript
 * async function handler(request, reply) {
 *   const result = await service.create(data);
 *   await recordAuditEvent(request, {
 *     eventType: 'policy.created',
 *     resourceType: 'policy',
 *     resourceId: result.id,
 *     afterState: result,
 *   });
 *   return result;
 * }
 * ```
 */
export declare function recordAuditEvent(request: FastifyRequest, event: {
    eventType: string;
    resourceType: AuditTarget['type'];
    resourceId: string;
    beforeState?: Record<string, unknown>;
    afterState?: Record<string, unknown>;
    metadata?: Record<string, unknown>;
    reason?: string;
}, auditService?: AuditService): Promise<void>;
/**
 * Record an access denied audit event
 */
export declare function recordAccessDeniedEvent(request: FastifyRequest, event: {
    requiredRoles: readonly string[];
    userRoles: string[];
    reason: string;
}, auditService?: AuditService): Promise<void>;
/**
 * Fastify plugin for automatic audit logging
 */
export declare const auditMiddlewarePlugin: (fastify: FastifyInstance, options: AuditMiddlewareOptions) => Promise<void>;
declare module 'fastify' {
    interface FastifyRequest {
        auditContext?: AuditContext;
    }
    interface FastifyInstance {
        auditService: AuditService;
    }
}
export {};
//# sourceMappingURL=audit.d.ts.map