nextjs-secure 0.5.0 → 0.7.0

package/dist/audit.d.cts

@@ -0,0 +1,679 @@
+import { NextRequest } from 'next/server';
+
+/**
+ * Log severity levels
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'critical';
+/**
+ * Security event types
+ */
+type SecurityEventType = 'auth.login' | 'auth.logout' | 'auth.failed' | 'auth.token_expired' | 'auth.token_invalid' | 'auth.permission_denied' | 'ratelimit.exceeded' | 'ratelimit.warning' | 'csrf.invalid' | 'csrf.missing' | 'xss.detected' | 'sqli.detected' | 'validation.failed' | 'file.rejected' | 'ip.blocked' | 'ip.suspicious' | 'request.malformed' | 'request.timeout' | 'error.unhandled' | 'error.internal' | 'custom';
+/**
+ * Log entry base
+ */
+interface LogEntry {
+    id: string;
+    timestamp: Date;
+    level: LogLevel;
+    message: string;
+    category?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Request log entry
+ */
+interface RequestLogEntry extends LogEntry {
+    type: 'request';
+    request: {
+        id: string;
+        method: string;
+        url: string;
+        path: string;
+        query?: Record<string, string>;
+        headers?: Record<string, string>;
+        ip?: string;
+        userAgent?: string;
+        contentType?: string;
+        contentLength?: number;
+    };
+    response?: {
+        status: number;
+        headers?: Record<string, string>;
+        duration: number;
+        contentLength?: number;
+    };
+    user?: {
+        id?: string;
+        email?: string;
+        role?: string;
+    };
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+}
+/**
+ * Security event entry
+ */
+interface SecurityEventEntry extends LogEntry {
+    type: 'security';
+    event: SecurityEventType;
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    source: {
+        ip?: string;
+        userAgent?: string;
+        userId?: string;
+    };
+    target?: {
+        resource?: string;
+        action?: string;
+        userId?: string;
+    };
+    details?: Record<string, unknown>;
+    mitigated?: boolean;
+}
+/**
+ * Audit log entry (union type)
+ */
+type AuditLogEntry = RequestLogEntry | SecurityEventEntry;
+/**
+ * Log store interface
+ */
+interface LogStore {
+    write(entry: AuditLogEntry): Promise<void>;
+    query?(options: LogQueryOptions): Promise<AuditLogEntry[]>;
+    flush?(): Promise<void>;
+    close?(): Promise<void>;
+}
+/**
+ * Log query options
+ */
+interface LogQueryOptions {
+    level?: LogLevel | LogLevel[];
+    type?: 'request' | 'security';
+    event?: SecurityEventType | SecurityEventType[];
+    startTime?: Date;
+    endTime?: Date;
+    ip?: string;
+    userId?: string;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Log formatter interface
+ */
+interface LogFormatter {
+    format(entry: AuditLogEntry): string;
+}
+/**
+ * PII field configuration
+ */
+interface PIIConfig {
+    fields: string[];
+    mode: 'mask' | 'hash' | 'remove';
+    maskChar?: string;
+    maskLength?: number;
+    preserveLength?: boolean;
+    customRedactor?: (value: string, field: string) => string;
+}
+/**
+ * Audit middleware configuration
+ */
+interface AuditConfig {
+    enabled?: boolean;
+    store: LogStore;
+    formatter?: LogFormatter;
+    level?: LogLevel;
+    include?: {
+        ip?: boolean;
+        userAgent?: boolean;
+        headers?: boolean | string[];
+        query?: boolean;
+        body?: boolean | string[];
+        response?: boolean;
+        responseBody?: boolean;
+        duration?: boolean;
+        user?: boolean;
+    };
+    exclude?: {
+        paths?: string[];
+        methods?: string[];
+        statusCodes?: number[];
+    };
+    pii?: PIIConfig;
+    getUser?: (req: NextRequest) => Promise<{
+        id?: string;
+        email?: string;
+        role?: string;
+    } | null>;
+    requestIdHeader?: string;
+    generateRequestId?: () => string;
+    onError?: (error: Error, entry: Partial<AuditLogEntry>) => void;
+    skip?: (req: NextRequest) => boolean | Promise<boolean>;
+}
+/**
+ * Security event configuration
+ */
+interface SecurityEventConfig {
+    store: LogStore;
+    formatter?: LogFormatter;
+    defaultSeverity?: 'low' | 'medium' | 'high' | 'critical';
+    onEvent?: (event: SecurityEventEntry) => void | Promise<void>;
+}
+/**
+ * Console store options
+ */
+interface ConsoleStoreOptions {
+    colorize?: boolean;
+    timestamp?: boolean;
+    pretty?: boolean;
+    level?: LogLevel;
+}
+/**
+ * File store options
+ */
+interface FileStoreOptions {
+    path: string;
+    maxSize?: number;
+    maxFiles?: number;
+    compress?: boolean;
+    rotationInterval?: 'hourly' | 'daily' | 'weekly';
+}
+/**
+ * Memory store options
+ */
+interface MemoryStoreOptions {
+    maxEntries?: number;
+    ttl?: number;
+}
+/**
+ * External service store options
+ */
+interface ExternalStoreOptions {
+    endpoint: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    batchSize?: number;
+    flushInterval?: number;
+    retryAttempts?: number;
+    timeout?: number;
+}
+
+/**
+ * In-memory log store with LRU eviction
+ * Useful for development and testing
+ */
+declare class MemoryStore implements LogStore {
+    private entries;
+    private readonly maxEntries;
+    private readonly ttl;
+    constructor(options?: MemoryStoreOptions);
+    write(entry: AuditLogEntry): Promise<void>;
+    query(options?: LogQueryOptions): Promise<AuditLogEntry[]>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Get all entries (for testing)
+     */
+    getEntries(): AuditLogEntry[];
+    /**
+     * Clear all entries
+     */
+    clear(): void;
+    /**
+     * Get entry count
+     */
+    size(): number;
+    /**
+     * Clean expired entries
+     */
+    private cleanExpired;
+}
+/**
+ * Create a memory store
+ */
+declare function createMemoryStore(options?: MemoryStoreOptions): MemoryStore;
+
+/**
+ * Console log store
+ * Outputs formatted logs to console
+ */
+declare class ConsoleStore implements LogStore {
+    private readonly colorize;
+    private readonly showTimestamp;
+    private readonly pretty;
+    private readonly minLevel;
+    constructor(options?: ConsoleStoreOptions);
+    write(entry: AuditLogEntry): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Format entry in compact single-line format
+     */
+    private formatCompact;
+    /**
+     * Format entry in pretty multi-line format
+     */
+    private formatPretty;
+    /**
+     * Apply color if enabled
+     */
+    private color;
+    /**
+     * Color log level
+     */
+    private colorLevel;
+    /**
+     * Color HTTP status
+     */
+    private colorStatus;
+    /**
+     * Color severity
+     */
+    private colorSeverity;
+}
+/**
+ * Create a console store
+ */
+declare function createConsoleStore(options?: ConsoleStoreOptions): ConsoleStore;
+
+/**
+ * External HTTP log store
+ * Sends logs to external services (Datadog, Sentry, custom endpoints)
+ */
+declare class ExternalStore implements LogStore {
+    private readonly endpoint;
+    private readonly headers;
+    private readonly batchSize;
+    private readonly flushInterval;
+    private readonly retryAttempts;
+    private readonly timeout;
+    private buffer;
+    private flushTimer;
+    private isFlushing;
+    constructor(options: ExternalStoreOptions);
+    write(entry: AuditLogEntry): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Send entries to external endpoint
+     */
+    private send;
+    /**
+     * Serialize entry for transmission
+     */
+    private serialize;
+    /**
+     * Sleep helper
+     */
+    private sleep;
+    /**
+     * Get buffer size (for monitoring)
+     */
+    getBufferSize(): number;
+}
+/**
+ * Create an external store
+ */
+declare function createExternalStore(options: ExternalStoreOptions): ExternalStore;
+/**
+ * Create a Datadog store
+ */
+declare function createDatadogStore(options: {
+    apiKey: string;
+    site?: 'datadoghq.com' | 'datadoghq.eu' | 'us3.datadoghq.com' | 'us5.datadoghq.com';
+    service?: string;
+    source?: string;
+    tags?: string[];
+    batchSize?: number;
+    flushInterval?: number;
+}): ExternalStore;
+/**
+ * Create a multi-store that writes to multiple stores
+ */
+declare class MultiStore implements LogStore {
+    private stores;
+    constructor(stores: LogStore[]);
+    write(entry: AuditLogEntry): Promise<void>;
+    query(options: Parameters<NonNullable<LogStore['query']>>[0]): Promise<AuditLogEntry[]>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * Create a multi-store
+ */
+declare function createMultiStore(stores: LogStore[]): MultiStore;
+
+/**
+ * JSON formatter - outputs logs as JSON strings
+ */
+declare class JSONFormatter implements LogFormatter {
+    private readonly pretty;
+    private readonly includeTimestamp;
+    constructor(options?: {
+        pretty?: boolean;
+        includeTimestamp?: boolean;
+    });
+    format(entry: AuditLogEntry): string;
+}
+/**
+ * Text formatter - outputs logs as human-readable text
+ */
+declare class TextFormatter implements LogFormatter {
+    private readonly template;
+    private readonly dateFormat;
+    constructor(options?: {
+        template?: string;
+        dateFormat?: 'iso' | 'utc' | 'local';
+    });
+    format(entry: AuditLogEntry): string;
+    private formatDate;
+}
+/**
+ * CLF (Common Log Format) formatter
+ * Apache/Nginx style: host ident authuser date request status bytes
+ */
+declare class CLFFormatter implements LogFormatter {
+    format(entry: AuditLogEntry): string;
+    private formatCLFDate;
+}
+/**
+ * Structured formatter for ELK/Splunk
+ * Outputs key=value pairs
+ */
+declare class StructuredFormatter implements LogFormatter {
+    private readonly delimiter;
+    private readonly kvSeparator;
+    constructor(options?: {
+        delimiter?: string;
+        kvSeparator?: string;
+    });
+    format(entry: AuditLogEntry): string;
+    private pair;
+    private escape;
+}
+/**
+ * Create a JSON formatter
+ */
+declare function createJSONFormatter(options?: {
+    pretty?: boolean;
+}): JSONFormatter;
+/**
+ * Create a text formatter
+ */
+declare function createTextFormatter(options?: {
+    template?: string;
+    dateFormat?: 'iso' | 'utc' | 'local';
+}): TextFormatter;
+/**
+ * Create a CLF formatter
+ */
+declare function createCLFFormatter(): CLFFormatter;
+/**
+ * Create a structured formatter
+ */
+declare function createStructuredFormatter(options?: {
+    delimiter?: string;
+    kvSeparator?: string;
+}): StructuredFormatter;
+
+/**
+ * Default PII fields to redact
+ */
+declare const DEFAULT_PII_FIELDS: string[];
+/**
+ * Mask a value with asterisks
+ */
+declare function mask(value: string, options?: {
+    char?: string;
+    preserveLength?: boolean;
+    showFirst?: number;
+    showLast?: number;
+}): string;
+/**
+ * Simple hash function for Edge Runtime compatibility
+ * Uses a fast, deterministic string hash (not cryptographic)
+ */
+declare function hash(value: string, salt?: string): string;
+/**
+ * Redact a single value
+ */
+declare function redactValue(value: unknown, field: string, config: PIIConfig): unknown;
+/**
+ * Redact PII from an object recursively
+ */
+declare function redactObject<T>(obj: T, config: PIIConfig, path?: string): T;
+/**
+ * Create a redactor function with preset config
+ */
+declare function createRedactor(config?: Partial<PIIConfig>): <T>(obj: T) => T;
+/**
+ * Redact sensitive headers
+ */
+declare function redactHeaders(headers: Record<string, string>, sensitiveHeaders?: string[]): Record<string, string>;
+/**
+ * Redact query parameters
+ */
+declare function redactQuery(query: Record<string, string>, sensitiveParams?: string[]): Record<string, string>;
+/**
+ * Redact email (show only domain)
+ */
+declare function redactEmail(email: string): string;
+/**
+ * Redact credit card number (show last 4 digits)
+ */
+declare function redactCreditCard(cardNumber: string): string;
+/**
+ * Redact phone number
+ */
+declare function redactPhone(phone: string): string;
+/**
+ * Redact IP address (show only first two octets for IPv4)
+ */
+declare function redactIP(ip: string): string;
+
+/**
+ * Security event tracker
+ */
+declare class SecurityEventTracker {
+    private store;
+    private defaultSeverity;
+    private onEvent?;
+    constructor(config: SecurityEventConfig);
+    /**
+     * Track a security event
+     */
+    track(options: {
+        event: SecurityEventType;
+        message: string;
+        severity?: 'low' | 'medium' | 'high' | 'critical';
+        source?: {
+            ip?: string;
+            userAgent?: string;
+            userId?: string;
+        };
+        target?: {
+            resource?: string;
+            action?: string;
+            userId?: string;
+        };
+        details?: Record<string, unknown>;
+        mitigated?: boolean;
+        metadata?: Record<string, unknown>;
+    }): Promise<SecurityEventEntry>;
+    /**
+     * Track failed authentication
+     */
+    authFailed(options: {
+        ip?: string;
+        userAgent?: string;
+        email?: string;
+        reason?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<SecurityEventEntry>;
+    /**
+     * Track successful login
+     */
+    authLogin(options: {
+        userId: string;
+        ip?: string;
+        userAgent?: string;
+        method?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<SecurityEventEntry>;
+    /**
+     * Track logout
+     */
+    authLogout(options: {
+        userId: string;
+        ip?: string;
+        reason?: 'user' | 'timeout' | 'forced';
+        metadata?: Record<string, unknown>;
+    }): Promise<SecurityEventEntry>;
+    /**
+     * Track permission denied
+     */
+    permissionDenied(options: {
+        userId?: string;
+        ip?: string;
+        resource: string;
+        action: string;
+        requiredRole?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<SecurityEventEntry>;
+    /**
+     * Track rate limit exceeded
+     */
+    rateLimitExceeded(options: {
+        ip?: string;
+        userId?: string;
+        endpoint: string;
+        limit: number;
+        window: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<SecurityEventEntry>;
+    /**
+     * Track CSRF validation failure
+     */
+    csrfInvalid(options: {
+        ip?: string;
+        userId?: string;
+        endpoint: string;
+        reason?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<SecurityEventEntry>;
+    /**
+     * Track XSS detection
+     */
+    xssDetected(options: {
+        ip?: string;
+        userId?: string;
+        field: string;
+        payload?: string;
+        endpoint: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<SecurityEventEntry>;
+    /**
+     * Track SQL injection detection
+     */
+    sqliDetected(options: {
+        ip?: string;
+        userId?: string;
+        field: string;
+        pattern: string;
+        severity?: 'low' | 'medium' | 'high';
+        endpoint: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<SecurityEventEntry>;
+    /**
+     * Track IP block
+     */
+    ipBlocked(options: {
+        ip: string;
+        reason: string;
+        duration?: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<SecurityEventEntry>;
+    /**
+     * Track suspicious activity
+     */
+    suspicious(options: {
+        ip?: string;
+        userId?: string;
+        activity: string;
+        severity?: 'low' | 'medium' | 'high' | 'critical';
+        details?: Record<string, unknown>;
+        metadata?: Record<string, unknown>;
+    }): Promise<SecurityEventEntry>;
+    /**
+     * Track custom event
+     */
+    custom(options: {
+        message: string;
+        severity?: 'low' | 'medium' | 'high' | 'critical';
+        source?: {
+            ip?: string;
+            userAgent?: string;
+            userId?: string;
+        };
+        target?: {
+            resource?: string;
+            action?: string;
+        };
+        details?: Record<string, unknown>;
+        metadata?: Record<string, unknown>;
+    }): Promise<SecurityEventEntry>;
+}
+/**
+ * Create a security event tracker
+ */
+declare function createSecurityTracker(config: SecurityEventConfig): SecurityEventTracker;
+/**
+ * Standalone function to track security events
+ */
+declare function trackSecurityEvent(store: LogStore, options: {
+    event: SecurityEventType;
+    message: string;
+    severity?: 'low' | 'medium' | 'high' | 'critical';
+    source?: {
+        ip?: string;
+        userAgent?: string;
+        userId?: string;
+    };
+    target?: {
+        resource?: string;
+        action?: string;
+        userId?: string;
+    };
+    details?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}): Promise<SecurityEventEntry>;
+
+type RouteHandler = (req: NextRequest) => Response | Promise<Response>;
+/**
+ * Audit logging middleware
+ */
+declare function withAuditLog(handler: RouteHandler, config: AuditConfig): RouteHandler;
+/**
+ * Create audit middleware with default console logging
+ */
+declare function createAuditMiddleware(config: Partial<AuditConfig> & {
+    store: AuditConfig['store'];
+}): (handler: RouteHandler) => RouteHandler;
+/**
+ * Request logger that adds request ID to response headers
+ */
+declare function withRequestId(handler: RouteHandler, options?: {
+    headerName?: string;
+    generateId?: () => string;
+}): RouteHandler;
+/**
+ * Simple request timing middleware
+ */
+declare function withTiming(handler: RouteHandler, options?: {
+    headerName?: string;
+    log?: boolean;
+}): RouteHandler;
+
+export { type AuditConfig, type AuditLogEntry, CLFFormatter, ConsoleStore, type ConsoleStoreOptions, DEFAULT_PII_FIELDS, ExternalStore, type ExternalStoreOptions, type FileStoreOptions, JSONFormatter, type LogEntry, type LogFormatter, type LogLevel, type LogQueryOptions, type LogStore, MemoryStore, type MemoryStoreOptions, MultiStore, type PIIConfig, type RequestLogEntry, type SecurityEventConfig, type SecurityEventEntry, SecurityEventTracker, type SecurityEventType, StructuredFormatter, TextFormatter, createAuditMiddleware, createCLFFormatter, createConsoleStore, createDatadogStore, createExternalStore, createJSONFormatter, createMemoryStore, createMultiStore, createRedactor, createSecurityTracker, createStructuredFormatter, createTextFormatter, hash, mask, redactCreditCard, redactEmail, redactHeaders, redactIP, redactObject, redactPhone, redactQuery, redactValue, trackSecurityEvent, withAuditLog, withRequestId, withTiming };