@arcis/node 1.3.0 → 1.4.0

package/dist/validation/file.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @module @arcis/node/validation/file
+ * File upload validation and filename sanitization
+ */
+/** File upload validation options */
+export 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 */
+export 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 */
+export 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'
+ */
+export 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 });
+ */
+export 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
+ */
+export declare function isDangerousExtension(filename: string): boolean;
+//# sourceMappingURL=file.d.ts.map

package/dist/validation/file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../src/validation/file.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuDH,qCAAqC;AACrC,MAAM,WAAW,mBAAmB;IAClC,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,sEAAsE;IACtE,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kEAAkE;IAClE,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,mCAAmC;AACnC,MAAM,WAAW,SAAS;IACxB,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,6BAA6B;AAC7B,MAAM,WAAW,kBAAkB;IACjC,yCAAyC;IACzC,KAAK,EAAE,OAAO,CAAC;IACf,yCAAyC;IACzC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,4CAA4C;IAC5C,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAYD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAqCzD;AAmDD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,SAAS,EACf,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CA6DpB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG9D"}

package/dist/validation/index.d.ts

@@ -1,3 +1,10 @@
-export { g as createValidator, i as isDangerousExtension, h as isRedirectSafe, j as isUrlSafe, k as isValidEmailSyntax, s as sanitizeFilename, v as validate, l as validateEmail, m as validateFile, n as validateRedirect, o as validateUrl, p as verifyEmailMx } from '../index-BGNKspqH.js';
-import 'express';
-import '../types-BOkx5YJc.js';
+/**
+ * @module @arcis/node/validation
+ * Request validation for Arcis
+ */
+export { validate, createValidator } from './schema';
+export { validateFile, sanitizeFilename, isDangerousExtension } from './file';
+export { validateUrl, isUrlSafe } from './url';
+export { validateRedirect, isRedirectSafe } from './redirect';
+export { validateEmail, verifyEmailMx, isValidEmailSyntax } from './email';
+//# sourceMappingURL=index.d.ts.map

package/dist/validation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9E,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC"}

package/dist/validation/redirect.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @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 */
+export 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 */
+export 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
+ */
+export 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
+ */
+export declare function isRedirectSafe(url: string, options?: ValidateRedirectOptions): boolean;
+//# sourceMappingURL=redirect.d.ts.map

package/dist/validation/redirect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redirect.d.ts","sourceRoot":"","sources":["../../src/validation/redirect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,sCAAsC;AACtC,MAAM,WAAW,uBAAuB;IACtC,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,mEAAmE;IACnE,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,oCAAoC;AACpC,MAAM,WAAW,sBAAsB;IACrC,uCAAuC;IACvC,IAAI,EAAE,OAAO,CAAC;IACd,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAQD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAqExB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,uBAA4B,GAAG,OAAO,CAE1F"}

package/dist/validation/schema.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @module @arcis/node/validation/schema
+ * Request validation middleware
+ */
+import type { RequestHandler } from 'express';
+import type { ValidationSchema } from '../core/types';
+/**
+ * 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);
+ */
+export declare function validate(schema: ValidationSchema, source?: 'body' | 'query' | 'params'): RequestHandler;
+/**
+ * Alias for validate
+ * @see validate
+ */
+export declare const createValidator: typeof validate;
+//# sourceMappingURL=schema.d.ts.map

package/dist/validation/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/validation/schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAmC,cAAc,EAAE,MAAM,SAAS,CAAC;AAE/E,OAAO,KAAK,EAAE,gBAAgB,EAAkB,MAAM,eAAe,CAAC;AAGtE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,gBAAgB,EACxB,MAAM,GAAE,MAAM,GAAG,OAAO,GAAG,QAAiB,GAC3C,cAAc,CA0BhB;AAoKD;;;GAGG;AACH,eAAO,MAAM,eAAe,iBAAW,CAAC"}

package/dist/validation/url.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @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 */
+export 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 */
+export 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
+ */
+export 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
+ */
+export declare function isUrlSafe(url: string, options?: ValidateUrlOptions): boolean;
+//# sourceMappingURL=url.d.ts.map

package/dist/validation/url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../src/validation/url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,iCAAiC;AACjC,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iDAAiD;IACjD,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,+BAA+B;AAC/B,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,IAAI,EAAE,OAAO,CAAC;IACd,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,iBAAiB,CAuF5F;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAEhF"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arcis/node",
-  "version": "1.3.0",
-  "description": "One-line security middleware for Node.js apps.",
+  "version": "1.4.0",
+  "description": "One line of code protects your Node.js app against 45+ security flaws at runtime — XSS, SQL injection, CSRF, SSRF, HPP, rate limiting, bot detection, and more. Zero dependencies. Supply chain attack scanner included.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -51,14 +51,14 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && tsc --emitDeclarationOnly --declaration --declarationMap",
     "dev": "tsup --watch",
     "test": "vitest",
     "test:unit": "vitest run tests/index.test.ts",
     "test:integration": "vitest run tests/integration.test.ts",
     "test:conformance": "vitest run tests/conformance.test.ts",
     "test:coverage": "vitest --coverage",
-    "lint": "eslint src --ext .ts",
+    "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build"
   },
@@ -94,10 +94,12 @@
   "devDependencies": {
     "@types/express": "^5.0.6",
     "@types/node": "^25.5.0",
-    "eslint": "^8.55.0",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
+    "eslint": "^10.1.0",
     "express": "^5.2.1",
     "tsup": "^8.0.1",
-    "typescript": "^5.3.2",
+    "typescript": "^6.0.2",
     "vitest": "^4.1.0"
   },
   "repository": {