@arcis/node 1.2.0 → 1.4.0

package/dist/index-Co5kPRZz.d.ts

@@ -1,340 +0,0 @@
-import { RequestHandler } from 'express';
-import { n as ValidationSchema } from './types-CsOFHoD9.js';
-
-/**
- * @module @arcis/node/validation/schema
- * Request validation middleware
- */
-
-/**
- * Create Express middleware for request validation.
- * Prevents mass assignment by only allowing fields defined in the schema.
- *
- * @param schema - Validation schema defining expected fields
- * @param source - Request property to validate ('body', 'query', or 'params')
- * @returns Express middleware
- *
- * @example
- * app.post('/users', validate({
- *   email: { type: 'email', required: true },
- *   name: { type: 'string', min: 2, max: 50 },
- *   age: { type: 'number', min: 0, max: 150 },
- *   role: { type: 'string', enum: ['user', 'admin'] }
- * }), handler);
- *
- * @example
- * // Validate query params
- * app.get('/search', validate({
- *   q: { type: 'string', required: true, min: 1 },
- *   page: { type: 'number', min: 1 }
- * }, 'query'), handler);
- */
-declare function validate(schema: ValidationSchema, source?: 'body' | 'query' | 'params'): RequestHandler;
-/**
- * Alias for validate
- * @see validate
- */
-declare const createValidator: typeof validate;
-
-/**
- * @module @arcis/node/validation/url
- * SSRF (Server-Side Request Forgery) prevention
- *
- * Validates URLs to ensure they don't target private/internal networks,
- * localhost, cloud metadata endpoints, or use dangerous protocols.
- *
- * @example
- * import { validateUrl } from '@arcis/node';
- *
- * // Block SSRF attempts
- * validateUrl('http://169.254.169.254/latest/meta-data/')  // { safe: false, reason: 'link-local address' }
- * validateUrl('http://10.0.0.1/admin')                     // { safe: false, reason: 'private address (10.0.0.0/8)' }
- * validateUrl('http://localhost/secret')                    // { safe: false, reason: 'loopback address' }
- * validateUrl('file:///etc/passwd')                         // { safe: false, reason: 'disallowed protocol: file:' }
- *
- * // Allow safe URLs
- * validateUrl('https://api.example.com/data')               // { safe: true }
- */
-/** Options for URL validation */
-interface ValidateUrlOptions {
-    /** Allowed protocols. Default: ['http:', 'https:'] */
-    allowedProtocols?: string[];
-    /** Additional hostnames to block (e.g., internal service names) */
-    blockedHosts?: string[];
-    /** Additional hostnames to always allow (bypass IP checks) */
-    allowedHosts?: string[];
-    /** Allow localhost/loopback. Default: false */
-    allowLocalhost?: boolean;
-    /** Allow private/internal IPs. Default: false */
-    allowPrivate?: boolean;
-}
-/** Result of URL validation */
-interface ValidateUrlResult {
-    /** Whether the URL is safe to fetch */
-    safe: boolean;
-    /** Reason the URL was blocked (only set when safe=false) */
-    reason?: string;
-}
-/**
- * Validate a URL for SSRF safety.
- *
- * Checks:
- * 1. Valid URL format
- * 2. Allowed protocol (default: http, https only)
- * 3. Not localhost/loopback (127.x.x.x, ::1, localhost)
- * 4. Not private IP (10.x, 172.16-31.x, 192.168.x)
- * 5. Not link-local (169.254.x.x — includes AWS/GCP/Azure metadata)
- * 6. Not blocked hostname
- * 7. No credentials in URL (user:pass@host)
- *
- * @param url - The URL string to validate
- * @param options - Validation options
- * @returns Validation result with safe flag and optional reason
- */
-declare function validateUrl(url: string, options?: ValidateUrlOptions): ValidateUrlResult;
-/**
- * Convenience wrapper that returns true/false.
- *
- * @param url - The URL to check
- * @param options - Validation options
- * @returns true if the URL is safe to fetch
- */
-declare function isUrlSafe(url: string, options?: ValidateUrlOptions): boolean;
-
-/**
- * @module @arcis/node/validation/redirect
- * Open Redirect prevention
- *
- * Prevents attackers from using your app to redirect users to malicious sites
- * via manipulated query parameters like ?returnUrl=http://evil.com
- *
- * @example
- * import { validateRedirect, isRedirectSafe } from '@arcis/node';
- *
- * // Block open redirects
- * validateRedirect('http://evil.com')                    // { safe: false, reason: 'absolute URL not in allowed hosts' }
- * validateRedirect('//evil.com')                         // { safe: false, reason: 'protocol-relative URL not in allowed hosts' }
- * validateRedirect('javascript:alert(1)')                // { safe: false, reason: 'dangerous protocol: javascript:' }
- *
- * // Allow safe redirects
- * validateRedirect('/dashboard')                         // { safe: true }
- * validateRedirect('/users?page=2')                      // { safe: true }
- * validateRedirect('https://myapp.com/home', { allowedHosts: ['myapp.com'] })  // { safe: true }
- */
-/** Options for redirect validation */
-interface ValidateRedirectOptions {
-    /** Hostnames that are allowed for absolute URL redirects */
-    allowedHosts?: string[];
-    /** Allow protocol-relative URLs (//example.com). Default: false */
-    allowProtocolRelative?: boolean;
-    /** Allowed protocols for absolute URLs. Default: ['http:', 'https:'] */
-    allowedProtocols?: string[];
-}
-/** Result of redirect validation */
-interface ValidateRedirectResult {
-    /** Whether the redirect URL is safe */
-    safe: boolean;
-    /** Reason the redirect was blocked (only set when safe=false) */
-    reason?: string;
-}
-/**
- * Validate a redirect URL to prevent open redirect attacks.
- *
- * Safe redirects:
- * - Relative paths: /dashboard, /users?page=2, ../settings
- * - Absolute URLs to allowed hosts (when configured)
- *
- * Blocked redirects:
- * - Absolute URLs to unknown hosts
- * - Protocol-relative URLs (//evil.com)
- * - javascript:, data:, vbscript:, blob: protocols
- * - Backslash-prefixed paths (\\evil.com — browser treats as //)
- * - URLs with control characters that could disguise the target
- *
- * @param url - The redirect target URL to validate
- * @param options - Validation options
- * @returns Validation result with safe flag and optional reason
- */
-declare function validateRedirect(url: string, options?: ValidateRedirectOptions): ValidateRedirectResult;
-/**
- * Convenience wrapper that returns true/false.
- *
- * @param url - The redirect URL to check
- * @param options - Validation options
- * @returns true if the redirect is safe
- */
-declare function isRedirectSafe(url: string, options?: ValidateRedirectOptions): boolean;
-
-/**
- * @module @arcis/node/validation/file
- * File upload validation and filename sanitization
- */
-/** File upload validation options */
-interface ValidateFileOptions {
-    /** Maximum file size in bytes. Default: 5MB */
-    maxSize?: number;
-    /** Allowed MIME types (e.g., ['image/jpeg', 'image/png']) */
-    allowedTypes?: string[];
-    /** Allowed file extensions (e.g., ['.jpg', '.png']). Includes dot. */
-    allowedExtensions?: string[];
-    /** Block dangerous/executable extensions. Default: true */
-    blockExecutables?: boolean;
-    /** Validate magic bytes match the claimed MIME type. Default: true */
-    validateMagicBytes?: boolean;
-    /** Block files with no extension. Default: true */
-    blockNoExtension?: boolean;
-    /** Block double extensions (e.g., file.php.jpg). Default: true */
-    blockDoubleExtensions?: boolean;
-}
-/** File metadata for validation */
-interface FileInput {
-    /** Original filename */
-    filename: string;
-    /** MIME type (as claimed by client) */
-    mimetype: string;
-    /** File size in bytes */
-    size: number;
-    /** File content buffer (for magic byte validation) */
-    buffer?: Buffer;
-}
-/** File validation result */
-interface ValidateFileResult {
-    /** Whether the file passed validation */
-    valid: boolean;
-    /** Validation errors (empty if valid) */
-    errors: string[];
-    /** Sanitized filename (safe for storage) */
-    sanitizedFilename: string;
-}
-/**
- * Sanitize a filename for safe storage.
- *
- * Strips path traversal, null bytes, control characters, and special characters.
- * Preserves the extension and converts to a filesystem-safe name.
- *
- * @param filename - The original filename
- * @returns A sanitized filename safe for storage
- *
- * @example
- * sanitizeFilename('../../etc/passwd')          // 'etc_passwd'
- * sanitizeFilename('file<name>.jpg')            // 'filename.jpg'
- * sanitizeFilename('photo (1).jpg')             // 'photo_1.jpg'
- * sanitizeFilename('.htaccess')                 // 'htaccess'
- */
-declare function sanitizeFilename(filename: string): string;
-/**
- * Validate a file upload for security.
- *
- * Checks file size, MIME type, extension, magic bytes, and dangerous patterns.
- * Returns a result with validation errors and a sanitized filename.
- *
- * @param file - File metadata and optional content
- * @param options - Validation options
- * @returns Validation result
- *
- * @example
- * const result = validateFile(
- *   { filename: 'photo.jpg', mimetype: 'image/jpeg', size: 1024, buffer },
- *   { allowedTypes: ['image/jpeg', 'image/png'], maxSize: 2 * 1024 * 1024 }
- * );
- * if (!result.valid) {
- *   return res.status(400).json({ errors: result.errors });
- * }
- * // Use result.sanitizedFilename for storage
- *
- * @example
- * // Block executables only (no whitelist)
- * const result = validateFile(file, { blockExecutables: true });
- */
-declare function validateFile(file: FileInput, options?: ValidateFileOptions): ValidateFileResult;
-/**
- * Check if a file extension is considered dangerous/executable.
- *
- * @param filename - Filename or extension to check
- * @returns true if the extension is dangerous
- */
-declare function isDangerousExtension(filename: string): boolean;
-
-/**
- * @module @arcis/node/validation/email
- * Advanced email validation with disposable detection and typo suggestions.
- *
- * Three levels of validation:
- * 1. Syntax — RFC-compliant format checking
- * 2. Domain intelligence — disposable/free provider detection, typo correction
- * 3. MX verification — DNS MX record lookup (async, optional)
- *
- * @example
- * const result = validateEmail('user@tempmail.com');
- * // { valid: false, reason: 'disposable' }
- *
- * const result = validateEmail('user@gmial.com');
- * // { valid: true, reason: 'typo', suggestion: 'user@gmail.com' }
- */
-interface EmailValidationOptions {
-    /** Check for disposable email providers. Default: true */
-    checkDisposable?: boolean;
-    /** Suggest corrections for typos. Default: true */
-    suggestTypoFix?: boolean;
-    /** Verify MX records via DNS. Default: false */
-    checkMx?: boolean;
-    /** Additional blocked domains */
-    blockedDomains?: string[];
-    /** Additional allowed domains (bypasses disposable check) */
-    allowedDomains?: string[];
-}
-interface EmailValidationResult {
-    /** Whether the email is valid */
-    valid: boolean;
-    /** Reason for the result */
-    reason: 'valid' | 'invalid_syntax' | 'disposable' | 'no_mx' | 'blocked' | 'typo';
-    /** Suggested correction if a typo was detected */
-    suggestion: string | null;
-    /** Whether the domain is a free email provider */
-    isFree: boolean;
-    /** Whether the domain is a disposable email provider */
-    isDisposable: boolean;
-    /** The normalized email address */
-    normalized: string;
-}
-/**
- * Validate an email address with syntax checking, disposable detection,
- * and typo suggestions.
- *
- * @param email - Email address to validate
- * @param options - Validation options
- * @returns Validation result
- *
- * @example
- * validateEmail('user@gmail.com')
- * // { valid: true, reason: 'valid', isFree: true }
- *
- * validateEmail('user@tempmail.com')
- * // { valid: false, reason: 'disposable' }
- *
- * validateEmail('user@gmial.com')
- * // { valid: true, reason: 'typo', suggestion: 'user@gmail.com' }
- */
-declare function validateEmail(email: string, options?: EmailValidationOptions): EmailValidationResult;
-/**
- * Verify that the email domain has MX records (can receive email).
- *
- * This performs a DNS lookup and requires network access.
- * Use for registration flows where you need high confidence.
- *
- * @param email - Email address to verify
- * @returns True if the domain has MX records
- *
- * @example
- * if (await verifyEmailMx('user@example.com')) {
- *   // Domain can receive email
- * }
- */
-declare function verifyEmailMx(email: string): Promise<boolean>;
-/**
- * Quick check if an email address has valid syntax.
- * Faster than validateEmail() — just syntax, no domain intelligence.
- */
-declare function isValidEmailSyntax(email: string): boolean;
-
-export { type EmailValidationOptions as E, type FileInput as F, type ValidateFileOptions as V, type EmailValidationResult as a, type ValidateFileResult as b, type ValidateRedirectOptions as c, type ValidateRedirectResult as d, type ValidateUrlOptions as e, type ValidateUrlResult as f, createValidator as g, isRedirectSafe as h, isDangerousExtension as i, isUrlSafe as j, isValidEmailSyntax as k, validateEmail as l, validateFile as m, validateRedirect as n, validateUrl as o, verifyEmailMx as p, sanitizeFilename as s, validate as v };