@arcis/node 1.0.0 → 1.2.0

package/package.json

@@ -1,109 +1,114 @@
-{
-  "name": "@arcis/node",
-  "version": "1.0.0",
-  "description": "One-line security middleware for Node.js apps.",
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
-    },
-    "./core": {
-      "types": "./dist/core/index.d.ts",
-      "import": "./dist/core/index.mjs",
-      "require": "./dist/core/index.js"
-    },
-    "./sanitizers": {
-      "types": "./dist/sanitizers/index.d.ts",
-      "import": "./dist/sanitizers/index.mjs",
-      "require": "./dist/sanitizers/index.js"
-    },
-    "./middleware": {
-      "types": "./dist/middleware/index.d.ts",
-      "import": "./dist/middleware/index.mjs",
-      "require": "./dist/middleware/index.js"
-    },
-    "./validation": {
-      "types": "./dist/validation/index.d.ts",
-      "import": "./dist/validation/index.mjs",
-      "require": "./dist/validation/index.js"
-    },
-    "./logging": {
-      "types": "./dist/logging/index.d.ts",
-      "import": "./dist/logging/index.mjs",
-      "require": "./dist/logging/index.js"
-    },
-    "./stores": {
-      "types": "./dist/stores/index.d.ts",
-      "import": "./dist/stores/index.mjs",
-      "require": "./dist/stores/index.js"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "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",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "security",
-    "express",
-    "middleware",
-    "xss",
-    "sql-injection",
-    "nosql-injection",
-    "rate-limit",
-    "sanitize",
-    "validation",
-    "csrf",
-    "helmet",
-    "nodejs",
-    "arcis",
-    "ssrf",
-    "open-redirect",
-    "cors",
-    "prototype-pollution",
-    "command-injection",
-    "path-traversal",
-    "security-headers",
-    "input-validation",
-    "web-security"
-  ],
-  "author": "Gagan CM",
-  "license": "MIT",
-  "peerDependencies": {
-    "express": ">=4.0.0"
-  },
-  "devDependencies": {
-    "@types/express": "^5.0.6",
-    "@types/node": "^25.5.0",
-    "eslint": "^8.55.0",
-    "express": "^5.2.1",
-    "tsup": "^8.0.1",
-    "typescript": "^5.3.2",
-    "vitest": "^4.1.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/GagancM/arcis"
-  },
-  "bugs": {
-    "url": "https://github.com/GagancM/arcis/issues"
-  },
-  "homepage": "https://github.com/GagancM/arcis#readme",
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "@arcis/node",
+  "version": "1.2.0",
+  "description": "One-line security middleware for Node.js apps.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.mjs",
+      "require": "./dist/core/index.js"
+    },
+    "./sanitizers": {
+      "types": "./dist/sanitizers/index.d.ts",
+      "import": "./dist/sanitizers/index.mjs",
+      "require": "./dist/sanitizers/index.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware/index.d.ts",
+      "import": "./dist/middleware/index.mjs",
+      "require": "./dist/middleware/index.js"
+    },
+    "./validation": {
+      "types": "./dist/validation/index.d.ts",
+      "import": "./dist/validation/index.mjs",
+      "require": "./dist/validation/index.js"
+    },
+    "./logging": {
+      "types": "./dist/logging/index.d.ts",
+      "import": "./dist/logging/index.mjs",
+      "require": "./dist/logging/index.js"
+    },
+    "./stores": {
+      "types": "./dist/stores/index.d.ts",
+      "import": "./dist/stores/index.mjs",
+      "require": "./dist/stores/index.js"
+    },
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "import": "./dist/utils/index.mjs",
+      "require": "./dist/utils/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "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",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "security",
+    "express",
+    "middleware",
+    "xss",
+    "sql-injection",
+    "nosql-injection",
+    "rate-limit",
+    "sanitize",
+    "validation",
+    "csrf",
+    "helmet",
+    "nodejs",
+    "arcis",
+    "ssrf",
+    "open-redirect",
+    "cors",
+    "prototype-pollution",
+    "command-injection",
+    "path-traversal",
+    "security-headers",
+    "input-validation",
+    "web-security"
+  ],
+  "author": "Gagan CM",
+  "license": "MIT",
+  "peerDependencies": {
+    "express": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.5.0",
+    "eslint": "^8.55.0",
+    "express": "^5.2.1",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.2",
+    "vitest": "^4.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GagancM/arcis"
+  },
+  "bugs": {
+    "url": "https://github.com/GagancM/arcis/issues"
+  },
+  "homepage": "https://github.com/GagancM/arcis#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/dist/index-BgHPM7LC.d.ts

@@ -1,129 +0,0 @@
-import { RequestHandler } from 'express';
-import { n as ValidationSchema } from './types-BOdL3ZWo.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/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-BpT7flAQ.d.ts

@@ -1,255 +0,0 @@
-import { b as ArcisOptions, o as ArcisMiddlewareStack, A as ArcisFunction, e as RateLimitOptions, h as RateLimiterMiddleware, H as HeaderOptions, E as ErrorHandlerOptions } from './types-BOdL3ZWo.js';
-import { RequestHandler, Request, Response, NextFunction } from 'express';
-
-/**
- * @module @arcis/node/middleware/main
- * Main arcis() middleware factory
- */
-
-/**
- * Create Arcis middleware with all protections enabled.
- *
- * @param options - Configuration options
- * @returns Array of Express middleware
- *
- * @example
- * // Full protection (recommended)
- * app.use(arcis());
- *
- * @example
- * // Custom configuration
- * app.use(arcis({
- *   rateLimit: { max: 50 },
- *   headers: { frameOptions: 'SAMEORIGIN' }
- * }));
- *
- * @example
- * // Disable specific features
- * app.use(arcis({
- *   rateLimit: false,
- *   sanitize: { sql: false }
- * }));
- *
- * @example
- * // Cleanup on shutdown
- * const middleware = arcis();
- * app.use(middleware);
- * process.on('SIGTERM', () => middleware.close());
- */
-declare function arcis(options?: ArcisOptions): ArcisMiddlewareStack;
-declare const arcisWithMethods: ArcisFunction;
-
-/**
- * @module @arcis/node/middleware/rate-limit
- * Rate limiting middleware
- */
-
-/**
- * Create Express middleware for rate limiting.
- *
- * @param options - Rate limit configuration
- * @returns Express middleware with cleanup method
- *
- * @example
- * app.use(createRateLimiter({ max: 100, windowMs: 60000 }));
- *
- * @example
- * // Skip rate limiting for certain routes
- * app.use(createRateLimiter({
- *   max: 50,
- *   skip: (req) => req.path === '/health'
- * }));
- *
- * @example
- * // Cleanup on shutdown
- * const limiter = createRateLimiter();
- * app.use(limiter);
- * process.on('SIGTERM', () => limiter.close());
- */
-declare function createRateLimiter(options?: RateLimitOptions): RateLimiterMiddleware;
-/**
- * Alias for createRateLimiter
- * @see createRateLimiter
- */
-declare const rateLimit: typeof createRateLimiter;
-
-/**
- * @module @arcis/node/middleware/headers
- * Security headers middleware
- */
-
-/**
- * Create Express middleware for security headers.
- * Sets CSP, HSTS, X-Frame-Options, and other security headers.
- *
- * @param options - Header configuration
- * @returns Express middleware
- *
- * @example
- * app.use(createHeaders());
- *
- * @example
- * app.use(createHeaders({
- *   frameOptions: 'SAMEORIGIN',
- *   contentSecurityPolicy: "default-src 'self'"
- * }));
- */
-declare function createHeaders(options?: HeaderOptions): RequestHandler;
-/**
- * Alias for createHeaders
- * @see createHeaders
- */
-declare const securityHeaders: typeof createHeaders;
-
-/**
- * @module @arcis/node/middleware/error-handler
- * Production-safe error handler middleware
- */
-
-/**
- * Create Express error handler that hides sensitive details in production.
- *
- * Prevents information leakage by:
- * - Hiding stack traces in production
- * - Hiding error messages unless explicitly exposed
- * - Scrubbing database errors, connection strings, and internal IPs
- *
- * @param options - Error handler configuration (or boolean for isDev)
- * @returns Express error handling middleware
- *
- * @example
- * // Production mode (default) - hides error details
- * app.use(errorHandler());
- *
- * @example
- * // Development mode - shows error details and stack traces
- * app.use(errorHandler({ isDev: true }));
- *
- * @example
- * // With custom logger
- * app.use(errorHandler({
- *   isDev: false,
- *   logger: arcis.logger()
- * }));
- */
-declare function errorHandler(options?: ErrorHandlerOptions | boolean): (err: Error, req: Request, res: Response, next: NextFunction) => void;
-/**
- * Alias for errorHandler
- * @see errorHandler
- */
-declare const createErrorHandler: typeof errorHandler;
-
-/**
- * @module @arcis/node/middleware/cors
- * Safe CORS middleware with secure defaults
- */
-
-/** CORS configuration options */
-interface CorsOptions {
-    /**
-     * Allowed origins. Can be:
-     * - A string: exact match (e.g., 'https://example.com')
-     * - An array: whitelist of allowed origins
-     * - A RegExp: pattern match (use with care)
-     * - A function: custom validation `(origin) => boolean`
-     * - `true`: reflect the request origin (DANGEROUS — only for dev)
-     *
-     * Default: none (no origin allowed). You must explicitly set this.
-     */
-    origin: string | string[] | RegExp | ((origin: string) => boolean) | true;
-    /** Allowed HTTP methods. Default: ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE'] */
-    methods?: string[];
-    /** Allowed headers. Default: ['Content-Type', 'Authorization'] */
-    allowedHeaders?: string[];
-    /** Headers exposed to the browser. Default: [] */
-    exposedHeaders?: string[];
-    /** Allow credentials (cookies, authorization headers). Default: false */
-    credentials?: boolean;
-    /** Preflight cache duration in seconds. Default: 600 (10 minutes) */
-    maxAge?: number;
-    /** Respond to preflight with 204 (no content). Default: true */
-    preflightContinue?: boolean;
-}
-/**
- * Create safe CORS middleware.
- *
- * Unlike permissive CORS libraries, this enforces secure defaults:
- * - No wildcard `*` when credentials are enabled
- * - `null` origin is always blocked
- * - `Vary: Origin` is always set for proper caching
- * - You must explicitly configure allowed origins
- *
- * @param options - CORS configuration
- * @returns Express middleware
- *
- * @example
- * // Allow a single origin
- * app.use(safeCors({ origin: 'https://myapp.com' }));
- *
- * @example
- * // Allow multiple origins with credentials
- * app.use(safeCors({
- *   origin: ['https://myapp.com', 'https://admin.myapp.com'],
- *   credentials: true,
- * }));
- *
- * @example
- * // Development: allow all (NOT for production)
- * app.use(safeCors({ origin: true }));
- */
-declare function safeCors(options: CorsOptions): RequestHandler;
-/**
- * Alias for safeCors
- * @see safeCors
- */
-declare const createCors: typeof safeCors;
-
-/**
- * @module @arcis/node/middleware/cookies
- * Secure cookie defaults middleware
- */
-
-/** Cookie security configuration */
-interface SecureCookieOptions {
-    /** Force HttpOnly on all cookies. Default: true */
-    httpOnly?: boolean;
-    /** Force Secure flag (HTTPS only). Default: true in production, false in dev */
-    secure?: boolean;
-    /** SameSite attribute. Default: 'Lax' */
-    sameSite?: 'Strict' | 'Lax' | 'None' | false;
-    /** Override Path attribute. Default: undefined (keep original) */
-    path?: string;
-}
-/**
- * Enforce secure defaults on a Set-Cookie header value.
- */
-declare function enforceSecureCookie(cookieStr: string, options: Required<Omit<SecureCookieOptions, 'path'>> & {
-    path?: string;
-}): string;
-/**
- * Create middleware that enforces secure cookie defaults.
- *
- * Intercepts Set-Cookie headers and adds missing security attributes:
- * - HttpOnly: prevents JavaScript access (XSS cookie theft)
- * - Secure: cookies only sent over HTTPS
- * - SameSite: CSRF protection
- *
- * @param options - Cookie security configuration
- * @returns Express middleware
- *
- * @example
- * // Enforce defaults on all cookies
- * app.use(secureCookieDefaults());
- *
- * @example
- * // Strict SameSite for sensitive apps
- * app.use(secureCookieDefaults({ sameSite: 'Strict' }));
- */
-declare function secureCookieDefaults(options?: SecureCookieOptions): RequestHandler;
-/**
- * Alias for secureCookieDefaults
- * @see secureCookieDefaults
- */
-declare const createSecureCookies: typeof secureCookieDefaults;
-
-export { type CorsOptions as C, type SecureCookieOptions as S, arcis as a, arcisWithMethods as b, createCors as c, createErrorHandler as d, createHeaders as e, createRateLimiter as f, createSecureCookies as g, enforceSecureCookie as h, errorHandler as i, secureCookieDefaults as j, securityHeaders as k, rateLimit as r, safeCors as s };