@arcis/node 1.0.0

package/dist/index-nAgXexwD.d.mts

@@ -0,0 +1,129 @@
+import { RequestHandler } from 'express';
+import { n as ValidationSchema } from './types-BOdL3ZWo.mjs';
+
+/**
+ * @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/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;
+
+export { type FileInput as F, type ValidateFileOptions as V, type ValidateFileResult as a, validateFile as b, createValidator as c, isDangerousExtension as i, sanitizeFilename as s, validate as v };

package/dist/index.d.mts

@@ -0,0 +1,139 @@
+export { C as CorsOptions, S as SecureCookieOptions, a as arcis, b as arcisFunction, c as createCors, d as createErrorHandler, e as createHeaders, f as createRateLimiter, g as createSecureCookies, b as default, h as enforceSecureCookie, i as errorHandler, r as rateLimit, s as safeCors, j as secureCookieDefaults, k as securityHeaders } from './index-JaFOUKyK.mjs';
+export { c as createSanitizer, d as detectCommandInjection, a as detectHeaderInjection, b as detectNoSqlInjection, e as detectPathTraversal, f as detectPrototypePollution, g as detectSql, h as detectXss, k as isDangerousNoSqlKey, l as isDangerousProtoKey, s as sanitizeCommand, m as sanitizeHeaderValue, n as sanitizeHeaders, o as sanitizeObject, p as sanitizePath, q as sanitizeSql, r as sanitizeString, t as sanitizeXss } from './headers-DBQedhrb.mjs';
+export { F as FileInput, V as ValidateFileOptions, a as ValidateFileResult, c as createValidator, i as isDangerousExtension, s as sanitizeFilename, v as validate, b as validateFile } from './index-nAgXexwD.mjs';
+export { createRedactor, createSafeLogger, safeLog } from './logging/index.mjs';
+export { MemoryStore, RedisClientLike, RedisStore, RedisStoreOptions, createRedisStore } from './stores/index.mjs';
+export { A as ArcisFunction, a as ArcisMiddleware, b as ArcisOptions, E as ErrorHandlerOptions, F as FieldValidator, H as HeaderOptions, c as HstsOptions, d as HttpError, L as LogOptions, R as RateLimitEntry, e as RateLimitOptions, f as RateLimitResult, g as RateLimitStore, h as RateLimiterMiddleware, S as SafeLogger, i as SanitizeOptions, j as SanitizeResult, T as ThreatInfo, k as ThreatType, V as ValidationConfig, l as ValidationError, m as ValidationResult, n as ValidationSchema } from './types-BOdL3ZWo.mjs';
+export { ArcisError, ArcisValidationError, BLOCKED, ERRORS, HEADERS, INPUT, InputTooLargeError, RATE_LIMIT, REDACTION, RateLimitError, SanitizationError, SecurityThreatError, VALIDATION } from './core/index.mjs';
+import 'express';
+
+/**
+ * @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;
+
+export { type ValidateRedirectOptions, type ValidateRedirectResult, type ValidateUrlOptions, type ValidateUrlResult, isRedirectSafe, isUrlSafe, validateRedirect, validateUrl };

package/dist/index.d.ts

@@ -0,0 +1,139 @@
+export { C as CorsOptions, S as SecureCookieOptions, a as arcis, b as arcisFunction, c as createCors, d as createErrorHandler, e as createHeaders, f as createRateLimiter, g as createSecureCookies, b as default, h as enforceSecureCookie, i as errorHandler, r as rateLimit, s as safeCors, j as secureCookieDefaults, k as securityHeaders } from './index-BpT7flAQ.js';
+export { c as createSanitizer, d as detectCommandInjection, a as detectHeaderInjection, b as detectNoSqlInjection, e as detectPathTraversal, f as detectPrototypePollution, g as detectSql, h as detectXss, k as isDangerousNoSqlKey, l as isDangerousProtoKey, s as sanitizeCommand, m as sanitizeHeaderValue, n as sanitizeHeaders, o as sanitizeObject, p as sanitizePath, q as sanitizeSql, r as sanitizeString, t as sanitizeXss } from './headers-BJq2OA0i.js';
+export { F as FileInput, V as ValidateFileOptions, a as ValidateFileResult, c as createValidator, i as isDangerousExtension, s as sanitizeFilename, v as validate, b as validateFile } from './index-BgHPM7LC.js';
+export { createRedactor, createSafeLogger, safeLog } from './logging/index.js';
+export { MemoryStore, RedisClientLike, RedisStore, RedisStoreOptions, createRedisStore } from './stores/index.js';
+export { A as ArcisFunction, a as ArcisMiddleware, b as ArcisOptions, E as ErrorHandlerOptions, F as FieldValidator, H as HeaderOptions, c as HstsOptions, d as HttpError, L as LogOptions, R as RateLimitEntry, e as RateLimitOptions, f as RateLimitResult, g as RateLimitStore, h as RateLimiterMiddleware, S as SafeLogger, i as SanitizeOptions, j as SanitizeResult, T as ThreatInfo, k as ThreatType, V as ValidationConfig, l as ValidationError, m as ValidationResult, n as ValidationSchema } from './types-BOdL3ZWo.js';
+export { ArcisError, ArcisValidationError, BLOCKED, ERRORS, HEADERS, INPUT, InputTooLargeError, RATE_LIMIT, REDACTION, RateLimitError, SanitizationError, SecurityThreatError, VALIDATION } from './core/index.js';
+import 'express';
+
+/**
+ * @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;
+
+export { type ValidateRedirectOptions, type ValidateRedirectResult, type ValidateUrlOptions, type ValidateUrlResult, isRedirectSafe, isUrlSafe, validateRedirect, validateUrl };