nextjs-secure 0.3.0 → 0.6.0

package/dist/path-BVbunPfR.d.cts

@@ -0,0 +1,534 @@
+import { NextRequest } from 'next/server';
+
+/**
+ * Validation error details
+ */
+interface ValidationError {
+    field: string;
+    message: string;
+    code: string;
+    path?: string[];
+    received?: unknown;
+    expected?: string;
+}
+/**
+ * Validation result
+ */
+interface ValidationResult<T = unknown> {
+    success: boolean;
+    data?: T;
+    errors?: ValidationError[];
+}
+/**
+ * Generic schema interface (Zod-compatible)
+ */
+interface Schema<T = unknown> {
+    parse: (data: unknown) => T;
+    safeParse: (data: unknown) => {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            issues: SchemaIssue[];
+        };
+    };
+}
+interface SchemaIssue {
+    path: (string | number)[];
+    message: string;
+    code: string;
+}
+/**
+ * Built-in field types for schema-less validation
+ */
+type FieldType = 'string' | 'number' | 'boolean' | 'email' | 'url' | 'uuid' | 'date' | 'array' | 'object';
+/**
+ * Field validation rules (without Zod)
+ */
+interface FieldRule {
+    type: FieldType;
+    required?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: RegExp;
+    min?: number;
+    max?: number;
+    integer?: boolean;
+    minItems?: number;
+    maxItems?: number;
+    items?: FieldRule;
+    custom?: (value: unknown) => boolean | string;
+    message?: string;
+}
+/**
+ * Custom schema definition (without Zod)
+ */
+type CustomSchema = Record<string, FieldRule>;
+/**
+ * Validation config for middleware
+ */
+interface ValidationConfig<TBody = unknown, TQuery = unknown, TParams = unknown> {
+    body?: Schema<TBody> | CustomSchema;
+    query?: Schema<TQuery> | CustomSchema;
+    params?: Schema<TParams> | CustomSchema;
+    strict?: boolean;
+    stripUnknown?: boolean;
+    onError?: (req: NextRequest, errors: ValidationError[]) => Response | Promise<Response>;
+}
+/**
+ * Validated request context
+ */
+interface ValidatedContext<TBody = unknown, TQuery = unknown, TParams = unknown> {
+    body: TBody;
+    query: TQuery;
+    params: TParams;
+}
+/**
+ * XSS sanitization modes
+ */
+type SanitizeMode = 'escape' | 'strip' | 'allow-safe';
+/**
+ * XSS sanitization config
+ */
+interface SanitizeConfig {
+    mode?: SanitizeMode;
+    allowedTags?: string[];
+    allowedAttributes?: Record<string, string[]>;
+    allowedProtocols?: string[];
+    maxLength?: number;
+    stripNull?: boolean;
+}
+/**
+ * Sanitization middleware config
+ */
+interface SanitizationMiddlewareConfig {
+    fields?: string[];
+    deep?: boolean;
+    mode?: SanitizeMode;
+    allowedTags?: string[];
+    skip?: (req: NextRequest) => boolean | Promise<boolean>;
+    onSanitized?: (req: NextRequest, changes: SanitizationChange[]) => void;
+}
+interface SanitizationChange {
+    field: string;
+    original: string;
+    sanitized: string;
+}
+/**
+ * SQL injection detection config
+ */
+interface SQLProtectionConfig {
+    fields?: string[];
+    deep?: boolean;
+    mode?: 'detect' | 'block' | 'sanitize';
+    customPatterns?: RegExp[];
+    allowList?: string[];
+    onDetection?: (req: NextRequest, detections: SQLDetection[]) => Response | void | Promise<Response | void>;
+}
+interface SQLDetection {
+    field: string;
+    value: string;
+    pattern: string;
+    severity: 'low' | 'medium' | 'high';
+}
+/**
+ * Path traversal prevention config
+ */
+interface PathValidationConfig {
+    allowAbsolute?: boolean;
+    allowedPrefixes?: string[];
+    allowedExtensions?: string[];
+    blockedExtensions?: string[];
+    maxDepth?: number;
+    maxLength?: number;
+    normalize?: boolean;
+}
+interface PathValidationResult {
+    valid: boolean;
+    sanitized?: string;
+    reason?: string;
+}
+/**
+ * Content-Type validation config
+ */
+interface ContentTypeConfig {
+    allowed: string[];
+    strict?: boolean;
+    charset?: string;
+    onInvalid?: (req: NextRequest, contentType: string | null) => Response | Promise<Response>;
+}
+/**
+ * File validation config
+ */
+interface FileValidationConfig {
+    maxSize?: number;
+    minSize?: number;
+    allowedTypes?: string[];
+    blockedTypes?: string[];
+    allowedExtensions?: string[];
+    blockedExtensions?: string[];
+    maxFiles?: number;
+    validateMagicNumbers?: boolean;
+    sanitizeFilename?: boolean;
+    onInvalid?: (req: NextRequest, errors: FileValidationError[]) => Response | Promise<Response>;
+}
+interface FileValidationError {
+    filename: string;
+    field?: string;
+    code: 'size_exceeded' | 'size_too_small' | 'type_not_allowed' | 'extension_not_allowed' | 'invalid_content' | 'too_many_files';
+    message: string;
+    details?: Record<string, unknown>;
+}
+interface FileInfo {
+    filename: string;
+    size: number;
+    type: string;
+    extension: string;
+    field?: string;
+}
+/**
+ * Magic number signatures for file type validation
+ */
+interface MagicNumber {
+    type: string;
+    extension: string;
+    signature: number[];
+    offset?: number;
+}
+
+type RouteHandler = (req: NextRequest) => Response | Promise<Response>;
+/**
+ * Validation middleware
+ * Validates request body, query, and params against schemas
+ */
+declare function withValidation<TBody = unknown, TQuery = unknown, TParams = unknown>(handler: (req: NextRequest, ctx: {
+    validated: ValidatedContext<TBody, TQuery, TParams>;
+}) => Response | Promise<Response>, config: ValidationConfig<TBody, TQuery, TParams> & {
+    routeParams?: Record<string, string | string[]>;
+}): RouteHandler;
+/**
+ * XSS Sanitization middleware
+ * Sanitizes string values in request body
+ */
+declare function withSanitization(handler: (req: NextRequest, ctx: {
+    sanitized: unknown;
+    changes: SanitizationChange[];
+}) => Response | Promise<Response>, config?: SanitizationMiddlewareConfig): RouteHandler;
+/**
+ * XSS Detection middleware
+ * Blocks requests with potential XSS payloads in body and query parameters
+ */
+declare function withXSSProtection(handler: RouteHandler, config?: {
+    fields?: string[];
+    deep?: boolean;
+    checkQuery?: boolean;
+    onDetection?: (req: NextRequest, field: string, value: string) => Response | void | Promise<Response | void>;
+}): RouteHandler;
+/**
+ * SQL Injection Protection middleware
+ */
+declare function withSQLProtection(handler: RouteHandler, config?: SQLProtectionConfig): RouteHandler;
+/**
+ * Content-Type validation middleware
+ */
+declare function withContentType(handler: RouteHandler, config: ContentTypeConfig): RouteHandler;
+/**
+ * File upload validation middleware
+ */
+declare function withFileValidation(handler: (req: NextRequest, ctx: {
+    files: Map<string, FileInfo[]>;
+}) => Response | Promise<Response>, config?: FileValidationConfig): RouteHandler;
+/**
+ * Combined validation middleware
+ * Combines schema validation, sanitization, and protection
+ */
+declare function withSecureValidation<TBody = unknown, TQuery = unknown, TParams = unknown>(handler: (req: NextRequest, ctx: {
+    validated: ValidatedContext<TBody, TQuery, TParams>;
+    files?: Map<string, FileInfo[]>;
+}) => Response | Promise<Response>, config: {
+    schema?: ValidationConfig<TBody, TQuery, TParams>;
+    routeParams?: Record<string, string | string[]>;
+    contentType?: ContentTypeConfig;
+    files?: FileValidationConfig;
+    sanitize?: SanitizationMiddlewareConfig;
+    xss?: {
+        enabled: boolean;
+        fields?: string[];
+    };
+    sql?: SQLProtectionConfig;
+    onError?: (req: NextRequest, errors: ValidationError[]) => Response | Promise<Response>;
+}): RouteHandler;
+
+/**
+ * Validate data against a schema (Zod or custom)
+ */
+declare function validate<T>(data: unknown, schema: Schema<T> | CustomSchema): ValidationResult<T>;
+/**
+ * Extract and validate request body
+ */
+declare function validateBody<T>(request: NextRequest, schema: Schema<T> | CustomSchema): Promise<ValidationResult<T>>;
+/**
+ * Extract and validate query parameters
+ */
+declare function validateQuery<T>(request: NextRequest, schema: Schema<T> | CustomSchema): ValidationResult<T>;
+/**
+ * Validate path parameters (from URL pattern)
+ */
+declare function validateParams<T>(params: Record<string, string | string[]>, schema: Schema<T> | CustomSchema): ValidationResult<T>;
+/**
+ * Combined request validation
+ */
+declare function validateRequest<TBody = unknown, TQuery = unknown, TParams = unknown>(request: NextRequest, config: {
+    body?: Schema<TBody> | CustomSchema;
+    query?: Schema<TQuery> | CustomSchema;
+    params?: Schema<TParams> | CustomSchema;
+    routeParams?: Record<string, string | string[]>;
+}): Promise<{
+    success: boolean;
+    data?: ValidatedContext<TBody, TQuery, TParams>;
+    errors?: ValidationError[];
+}>;
+/**
+ * Default validation error response
+ */
+declare function defaultValidationErrorResponse(errors: ValidationError[]): Response;
+/**
+ * Create a validation function for a schema
+ */
+declare function createValidator<T>(schema: Schema<T> | CustomSchema): (data: unknown) => ValidationResult<T>;
+/**
+ * Check if all validation results are successful
+ */
+declare function allValid(...results: ValidationResult[]): boolean;
+/**
+ * Merge validation errors from multiple results
+ */
+declare function mergeErrors(...results: ValidationResult[]): ValidationError[];
+
+/**
+ * Common MIME types
+ */
+declare const MIME_TYPES: {
+    readonly TEXT_PLAIN: "text/plain";
+    readonly TEXT_HTML: "text/html";
+    readonly TEXT_CSS: "text/css";
+    readonly TEXT_JAVASCRIPT: "text/javascript";
+    readonly JSON: "application/json";
+    readonly FORM_URLENCODED: "application/x-www-form-urlencoded";
+    readonly MULTIPART_FORM: "multipart/form-data";
+    readonly XML: "application/xml";
+    readonly PDF: "application/pdf";
+    readonly ZIP: "application/zip";
+    readonly GZIP: "application/gzip";
+    readonly OCTET_STREAM: "application/octet-stream";
+    readonly IMAGE_PNG: "image/png";
+    readonly IMAGE_JPEG: "image/jpeg";
+    readonly IMAGE_GIF: "image/gif";
+    readonly IMAGE_WEBP: "image/webp";
+    readonly IMAGE_SVG: "image/svg+xml";
+    readonly AUDIO_MP3: "audio/mpeg";
+    readonly AUDIO_WAV: "audio/wav";
+    readonly AUDIO_OGG: "audio/ogg";
+    readonly VIDEO_MP4: "video/mp4";
+    readonly VIDEO_WEBM: "video/webm";
+};
+/**
+ * Parse Content-Type header
+ */
+declare function parseContentType(header: string | null): {
+    type: string;
+    subtype: string;
+    mediaType: string;
+    charset?: string;
+    boundary?: string;
+    parameters: Record<string, string>;
+};
+/**
+ * Check if Content-Type matches allowed types
+ */
+declare function isAllowedContentType(contentType: string | null, allowedTypes: string[], strict?: boolean): boolean;
+/**
+ * Validate Content-Type header
+ */
+declare function validateContentType(request: NextRequest, config: ContentTypeConfig): {
+    valid: boolean;
+    contentType: string | null;
+    reason?: string;
+};
+/**
+ * Default Content-Type validation error response
+ */
+declare function defaultContentTypeErrorResponse(contentType: string | null, reason: string): Response;
+/**
+ * Check if request has JSON content type
+ */
+declare function isJsonRequest(request: NextRequest): boolean;
+/**
+ * Check if request has form content type
+ */
+declare function isFormRequest(request: NextRequest): boolean;
+/**
+ * Check if request has multipart content type
+ */
+declare function isMultipartRequest(request: NextRequest): boolean;
+/**
+ * Get boundary from multipart Content-Type
+ */
+declare function getMultipartBoundary(request: NextRequest): string | null;
+
+/**
+ * Default file size limits
+ */
+declare const DEFAULT_MAX_FILE_SIZE: number;
+declare const DEFAULT_MAX_FILES = 10;
+/**
+ * Dangerous file extensions to block by default
+ */
+declare const DANGEROUS_EXTENSIONS: string[];
+/**
+ * Check magic number signature
+ */
+declare function checkMagicNumber(bytes: Uint8Array, magicNumber: MagicNumber): boolean;
+/**
+ * Detect file type from magic number
+ */
+declare function detectFileType(bytes: Uint8Array): {
+    type: string;
+    extension: string;
+} | null;
+/**
+ * Validate a single file
+ */
+declare function validateFile(file: File, config?: FileValidationConfig): Promise<{
+    valid: boolean;
+    info: FileInfo;
+    errors: FileValidationError[];
+}>;
+/**
+ * Validate multiple files
+ */
+declare function validateFiles(files: File[], config?: FileValidationConfig): Promise<{
+    valid: boolean;
+    infos: FileInfo[];
+    errors: FileValidationError[];
+}>;
+/**
+ * Extract files from FormData
+ */
+declare function extractFilesFromFormData(formData: FormData): Map<string, File[]>;
+/**
+ * Validate files from a request
+ */
+declare function validateFilesFromRequest(request: NextRequest, config?: FileValidationConfig): Promise<{
+    valid: boolean;
+    files: Map<string, FileInfo[]>;
+    errors: FileValidationError[];
+}>;
+/**
+ * Default file validation error response
+ */
+declare function defaultFileErrorResponse(errors: FileValidationError[]): Response;
+
+/**
+ * Escape HTML special characters
+ */
+declare function escapeHtml(str: string): string;
+/**
+ * Unescape HTML entities
+ */
+declare function unescapeHtml(str: string): string;
+/**
+ * Strip all HTML tags
+ */
+declare function stripHtml(str: string): string;
+/**
+ * Check if a URL is safe
+ */
+declare function isSafeUrl(url: string, allowedProtocols?: string[]): boolean;
+/**
+ * Sanitize HTML with allowed tags
+ */
+declare function sanitizeHtml(str: string, allowedTags?: string[], allowedAttributes?: Record<string, string[]>, allowedProtocols?: string[]): string;
+/**
+ * Detect if string contains potential XSS
+ */
+declare function detectXSS(str: string): boolean;
+/**
+ * Main sanitize function
+ */
+declare function sanitize(input: string, config?: SanitizeConfig): string;
+/**
+ * Sanitize object values recursively
+ */
+declare function sanitizeObject<T>(obj: T, config?: SanitizeConfig): T;
+/**
+ * Sanitize specific fields in an object
+ */
+declare function sanitizeFields<T extends Record<string, unknown>>(obj: T, fields: string[], config?: SanitizeConfig): T;
+
+/**
+ * Detect SQL injection in a string
+ */
+declare function detectSQLInjection(input: string, options?: {
+    customPatterns?: RegExp[];
+    checkEncoded?: boolean;
+    minSeverity?: 'low' | 'medium' | 'high';
+}): SQLDetection[];
+/**
+ * Check if string contains SQL injection (boolean check)
+ */
+declare function hasSQLInjection(input: string, minSeverity?: 'low' | 'medium' | 'high'): boolean;
+/**
+ * Sanitize input to prevent SQL injection
+ * NOTE: This should NOT be a replacement for parameterized queries!
+ */
+declare function sanitizeSQLInput(input: string): string;
+/**
+ * Detect SQL injection in object fields
+ */
+declare function detectSQLInjectionInObject(obj: unknown, options?: {
+    fields?: string[];
+    deep?: boolean;
+    customPatterns?: RegExp[];
+    minSeverity?: 'low' | 'medium' | 'high';
+}): SQLDetection[];
+/**
+ * Check if value is in allowlist (safe values)
+ */
+declare function isAllowedValue(value: string, allowList: string[]): boolean;
+
+/**
+ * Check if path contains traversal patterns
+ */
+declare function hasPathTraversal(path: string): boolean;
+/**
+ * Validate and sanitize a path
+ */
+declare function validatePath(path: string, config?: PathValidationConfig): PathValidationResult;
+/**
+ * Sanitize a path by removing dangerous elements
+ */
+declare function sanitizePath(path: string, config?: PathValidationConfig): string;
+/**
+ * Check if a path is within a base directory (safe containment)
+ */
+declare function isPathContained(path: string, baseDir: string): boolean;
+/**
+ * Get the file extension from a path
+ */
+declare function getExtension(path: string): string;
+/**
+ * Get the filename from a path
+ */
+declare function getFilename(path: string): string;
+/**
+ * Sanitize a filename (remove dangerous characters)
+ */
+declare function sanitizeFilename(filename: string): string;
+/**
+ * Check if path is a hidden file (starts with dot)
+ */
+declare function isHiddenPath(path: string): boolean;
+
+export { defaultFileErrorResponse as $, validateParams as A, validateRequest as B, type CustomSchema as C, createValidator as D, allValid as E, type FieldRule as F, mergeErrors as G, defaultValidationErrorResponse as H, validateContentType as I, parseContentType as J, isAllowedContentType as K, isJsonRequest as L, type MagicNumber as M, isFormRequest as N, isMultipartRequest as O, type PathValidationConfig as P, getMultipartBoundary as Q, defaultContentTypeErrorResponse as R, type Schema as S, MIME_TYPES as T, validateFile as U, type ValidationError as V, validateFiles as W, validateFilesFromRequest as X, extractFilesFromFormData as Y, detectFileType as Z, checkMagicNumber as _, type ValidationResult as a, DEFAULT_MAX_FILE_SIZE as a0, DEFAULT_MAX_FILES as a1, DANGEROUS_EXTENSIONS as a2, sanitize as a3, sanitizeObject as a4, sanitizeFields as a5, escapeHtml as a6, unescapeHtml as a7, stripHtml as a8, sanitizeHtml as a9, detectXSS as aa, isSafeUrl as ab, detectSQLInjection as ac, detectSQLInjectionInObject as ad, hasSQLInjection as ae, sanitizeSQLInput as af, isAllowedValue as ag, validatePath as ah, sanitizePath as ai, hasPathTraversal as aj, isPathContained as ak, getExtension as al, getFilename as am, sanitizeFilename as an, isHiddenPath as ao, type SchemaIssue as b, type FieldType as c, type ValidationConfig as d, type ValidatedContext as e, type SanitizeMode as f, type SanitizeConfig as g, type SanitizationMiddlewareConfig as h, type SanitizationChange as i, type SQLProtectionConfig as j, type SQLDetection as k, type PathValidationResult as l, type ContentTypeConfig as m, type FileValidationConfig as n, type FileValidationError as o, type FileInfo as p, withSanitization as q, withXSSProtection as r, withSQLProtection as s, withContentType as t, withFileValidation as u, withSecureValidation as v, withValidation as w, validate as x, validateBody as y, validateQuery as z };