@arcis/node 1.0.0

package/README.md

@@ -0,0 +1,222 @@
+# Arcis
+
+arcis One-line security middleware for Node.js, Python, and Go.
+
+Arcis protects your code like how Dependabot protects your dependencies.
+
+
+**15 attack vectors handled so far.**
+
+| Category | What it stops |
+|----------|--------------|
+| XSS | Script injection, event handlers, `javascript:` URIs, SVG/iframe payloads |
+| SQL Injection | Keywords, boolean logic, comments, time-based blind (`SLEEP`, `BENCHMARK`) |
+| NoSQL Injection | MongoDB operators (`$gt`, `$where`, `$regex`, 25+ blocked operators) |
+| Command Injection | Shell metacharacters, dangerous commands, redirections |
+| Path Traversal | `../`, encoded variants (`%2e%2e`), null byte injection |
+| Prototype Pollution | `__proto__`, `constructor`, `__defineGetter__`, 7 keys blocked (case-insensitive) |
+| HTTP Header Injection | CRLF injection, response splitting, null bytes |
+| SSRF | Private IPs, loopback, link-local, cloud metadata, dangerous protocols |
+| Open Redirect | Absolute URLs, `javascript:`, protocol-relative, backslash/control char bypass |
+| Error Leakage | Stack traces, DB errors, connection strings, internal IPs scrubbed in production |
+| CORS Misconfiguration | Whitelist-based origins, `null` origin blocked, `Vary: Origin` enforced |
+| Cookie Security | HttpOnly, Secure, SameSite enforced on all cookies |
+| Rate Limiting | Per-IP, in-memory or Redis, `X-RateLimit-*` headers |
+| Security Headers | CSP, HSTS, X-Frame-Options, 10 headers out of the box |
+| Input Validation | Type checking, ranges, enums, mass assignment prevention, safe logging |
+
+**1040+ tests** across Node.js (613) and Python (430).
+
+## Install
+
+```bash
+npm install @arcis/node          # Node.js
+pip install arcis                # Python
+go get github.com/GagancM/arcis  # Go
+```
+
+**Install directly from GitHub:**
+
+```bash
+# Node.js
+npm install github:Gagancm/arcis#main --install-strategy=nested
+
+# Python
+pip install git+https://github.com/Gagancm/arcis.git#subdirectory=packages/arcis-python
+
+# Go
+go get github.com/Gagancm/arcis
+```
+
+## Quick Start
+
+### Node.js
+
+Arcis has two layers: **framework-agnostic core functions** that work anywhere, and **middleware adapters** for specific frameworks.
+
+#### With Express (built-in adapter)
+
+```js
+import { arcis } from '@arcis/node';
+
+app.use(arcis());
+// That's it. Sanitization, rate limiting, and security headers are on.
+```
+
+#### With any framework (Fastify, Koa, Hono, etc.)
+
+The core sanitization, validation, and logging functions have zero framework dependencies. Use them directly in any Node.js project:
+
+```js
+import {
+  sanitizeString,
+  sanitizeObject,
+  detectXss,
+  detectSql,
+  detectCommandInjection,
+  detectPathTraversal,
+  createSafeLogger,
+  createRedactor,
+} from '@arcis/node';
+
+// Sanitize user input — works anywhere
+const clean = sanitizeString(userInput);
+const cleanBody = sanitizeObject(requestBody);
+
+// Detect threats without sanitizing
+if (detectXss(value)) { /* reject */ }
+if (detectSql(value)) { /* reject */ }
+
+// Safe logging — no framework needed
+const logger = createSafeLogger();
+logger.info('User login', { email, password: 'will-be-redacted' });
+```
+
+**Writing your own middleware is straightforward.** Here's a Fastify example:
+
+```js
+import { sanitizeObject } from '@arcis/node';
+
+fastify.addHook('preHandler', async (request, reply) => {
+  if (request.body) request.body = sanitizeObject(request.body);
+  if (request.query) request.query = sanitizeObject(request.query);
+});
+```
+
+Koa:
+
+```js
+import { sanitizeObject } from '@arcis/node';
+
+app.use(async (ctx, next) => {
+  if (ctx.request.body) ctx.request.body = sanitizeObject(ctx.request.body);
+  if (ctx.query) ctx.query = sanitizeObject(ctx.query);
+  await next();
+});
+```
+
+Hono:
+
+```js
+import { sanitizeObject } from '@arcis/node';
+
+app.use('*', async (c, next) => {
+  const body = await c.req.json().catch(() => null);
+  if (body) c.set('sanitizedBody', sanitizeObject(body));
+  await next();
+});
+```
+
+> Built-in adapters for Fastify, Koa, and Hono are on the roadmap. The core functions work today.
+
+### Python
+
+```python
+# Flask
+from arcis import Arcis
+Arcis(app)
+
+# FastAPI
+from arcis import ArcisMiddleware
+app.add_middleware(ArcisMiddleware)
+
+# Django — add to MIDDLEWARE in settings.py
+'arcis.django.ArcisMiddleware'
+```
+
+### Go
+
+```go
+// Gin
+r.Use(arcisgin.Middleware())
+
+// Echo
+e.Use(arcisecho.Middleware())
+```
+
+## What It Does
+
+One `app.use(arcis())` gives you all 15 categories above. Or use individual functions for fine-grained control:
+
+- **Sanitize** — `sanitizeString()`, `sanitizeObject()` strip dangerous patterns
+- **Detect** — `detectXss()`, `detectSql()`, `detectHeaderInjection()` flag threats without modifying input
+- **Validate** — `validateUrl()` blocks SSRF, `validateRedirect()` blocks open redirects
+- **Protect** — rate limiting, security headers, safe logging, error handling
+
+## Architecture
+
+Arcis separates **core security logic** from **framework adapters**:
+
+```
+@arcis/node
+├── Core (framework-agnostic)
+│   ├── sanitizeString / sanitizeObject   — clean any input
+│   ├── detectXss / detectSql / ...       — threat detection
+│   ├── createSafeLogger / createRedactor — safe logging
+│   ├── MemoryStore / RedisStore          — rate limit backends
+│   └── Error classes and constants
+│
+└── Adapters (framework-specific)
+    └── Express middleware (arcis(), arcis.sanitize(), arcis.rateLimit(), ...)
+```
+
+The core functions are pure — no `req`, `res`, or `next`. They take values in and return values out. This means they work with Express, Fastify, Koa, Hono, Nest, raw `http.createServer`, Bun, Deno, serverless functions, or anything else.
+
+Subpath imports are available for tree-shaking:
+
+```js
+import { sanitizeString } from '@arcis/node/sanitizers';
+import { createSafeLogger } from '@arcis/node/logging';
+import { MemoryStore } from '@arcis/node/stores';
+```
+
+## Supported Frameworks
+
+| SDK | Built-in Adapters | Core Functions | Status |
+|-----|-------------------|----------------|--------|
+| Node.js | Express | Work with any framework | Stable |
+| Python | Flask, FastAPI, Django | Work standalone | Stable |
+| Go | net/http, Gin, Echo | Work standalone | Stable |
+| Java | Spring Boot | — | Planned |
+| C# | ASP.NET Core | — | Planned |
+
+**Node.js roadmap:** Built-in adapters for Fastify, Koa, and Hono are planned. The core functions already work with these frameworks — you just wire a short middleware wrapper (see examples above).
+
+
+## How It Works
+
+All SDKs load security patterns from a shared `patterns.json` at runtime. A shared spec (`API_SPEC.md`) and test vectors (`TEST_VECTORS.json`) enforce identical behavior across languages.
+
+## Documentation
+
+Detailed configuration, API reference, Redis setup, granular middleware usage, and architecture docs are in the [Wiki](https://github.com/Gagancm/arcis/wiki).
+
+## Contributing
+
+1. All changes must pass existing tests
+2. New features require test cases aligned with `spec/TEST_VECTORS.json`
+3. Pattern changes in `packages/core/patterns.json` must be reflected in all SDKs
+
+## License
+
+MIT

package/dist/core/index.d.mts

@@ -0,0 +1,170 @@
+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';
+import 'express';
+
+/**
+ * @module @arcis/node/core/errors
+ * Custom error classes for Arcis
+ */
+/**
+ * Base class for all Arcis errors
+ */
+declare class ArcisError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    /** Whether the error message is safe to expose to API clients. */
+    readonly expose: boolean;
+    constructor(message: string, statusCode?: number, code?: string);
+}
+/**
+ * Error thrown when input validation fails
+ */
+declare class ValidationError extends ArcisError {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+
+/**
+ * Error thrown when rate limit is exceeded
+ */
+declare class RateLimitError extends ArcisError {
+    readonly retryAfter: number;
+    constructor(message: string, retryAfter: number);
+}
+/**
+ * Error thrown when input is too large
+ */
+declare class InputTooLargeError extends ArcisError {
+    readonly maxSize: number;
+    readonly actualSize: number;
+    constructor(maxSize: number, actualSize: number);
+}
+/**
+ * Error thrown when security threat is detected
+ */
+declare class SecurityThreatError extends ArcisError {
+    readonly threatType: string;
+    readonly pattern: string;
+    constructor(threatType: string, pattern: string);
+}
+/**
+ * Error thrown when sanitization fails
+ */
+declare class SanitizationError extends ArcisError {
+    constructor(message: string);
+}
+
+/**
+ * @module @arcis/node/core/constants
+ * Named constants for Arcis - no magic numbers
+ */
+declare const INPUT: {
+    /** Default maximum input size (1MB) */
+    readonly DEFAULT_MAX_SIZE: 1000000;
+    /** Maximum recursion depth for nested objects */
+    readonly MAX_RECURSION_DEPTH: 10;
+};
+declare const RATE_LIMIT: {
+    /** Default window size (1 minute) */
+    readonly DEFAULT_WINDOW_MS: 60000;
+    /** Default max requests per window */
+    readonly DEFAULT_MAX_REQUESTS: 100;
+    /** Default HTTP status code for rate limited responses */
+    readonly DEFAULT_STATUS_CODE: 429;
+    /** Default error message */
+    readonly DEFAULT_MESSAGE: "Too many requests, please try again later.";
+    /** Minimum window size (1 second) */
+    readonly MIN_WINDOW_MS: 1000;
+    /** Maximum window size (24 hours) */
+    readonly MAX_WINDOW_MS: 86400000;
+};
+declare const HEADERS: {
+    /** Default Content Security Policy */
+    readonly DEFAULT_CSP: string;
+    /** Default HSTS max age (1 year in seconds) */
+    readonly HSTS_MAX_AGE: 31536000;
+    /** Default X-Frame-Options value */
+    readonly FRAME_OPTIONS: "DENY";
+    /** Default X-Content-Type-Options value */
+    readonly CONTENT_TYPE_OPTIONS: "nosniff";
+    /** Default Referrer-Policy value */
+    readonly REFERRER_POLICY: "strict-origin-when-cross-origin";
+    /** Default Permissions-Policy value */
+    readonly PERMISSIONS_POLICY: "geolocation=(), microphone=(), camera=()";
+    /** Default Cache-Control value for security */
+    readonly CACHE_CONTROL: "no-store, no-cache, must-revalidate, proxy-revalidate";
+};
+/**
+ * Detection patterns — used to flag whether a string contains XSS payloads.
+ * Must stay in sync with XSS_REMOVE_PATTERNS below.
+ */
+declare const XSS_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
+declare const SQL_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
+declare const PATH_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
+declare const COMMAND_PATTERNS: readonly [RegExp, RegExp];
+/**
+ * Prototype pollution keys to block.
+ * Stored lowercase — always compare with key.toLowerCase().
+ *
+ * Includes:
+ * - __proto__: direct prototype assignment
+ * - constructor: access to constructor.prototype chain
+ * - prototype: direct prototype property
+ * - __defineGetter__/__defineSetter__: legacy property definition (can override getters/setters)
+ * - __lookupGetter__/__lookupSetter__: legacy property introspection
+ */
+declare const DANGEROUS_PROTO_KEYS: Set<string>;
+/** MongoDB operators to block */
+declare const NOSQL_DANGEROUS_KEYS: Set<string>;
+declare const REDACTION: {
+    /** Replacement text for redacted values */
+    readonly REPLACEMENT: "[REDACTED]";
+    /** Truncation indicator */
+    readonly TRUNCATED: "[TRUNCATED]";
+    /** Max depth indicator */
+    readonly MAX_DEPTH: "[MAX_DEPTH]";
+    /** Default max message length */
+    readonly DEFAULT_MAX_LENGTH: 10000;
+    /** Default sensitive keys to redact */
+    readonly SENSITIVE_KEYS: Set<string>;
+};
+declare const VALIDATION: {
+    /**
+     * Email regex pattern.
+     * Rejects consecutive dots in local part (e.g. test..foo@example.com),
+     * leading/trailing dots, and other common invalid forms.
+     */
+    readonly EMAIL: RegExp;
+    /**
+     * URL regex pattern.
+     * Only allows http:// and https:// — explicitly rejects javascript:,
+     * data:, vbscript:, and other dangerous URI schemes.
+     */
+    readonly URL: RegExp;
+    /** UUID regex pattern (v4) */
+    readonly UUID: RegExp;
+};
+declare const ERRORS: {
+    /** Generic error message (production) */
+    readonly INTERNAL_SERVER_ERROR: "Internal Server Error";
+    /** Input too large error */
+    readonly INPUT_TOO_LARGE: (maxSize: number) => string;
+    /** Validation error messages */
+    readonly VALIDATION: {
+        readonly REQUIRED: (field: string) => string;
+        readonly INVALID_TYPE: (field: string, type: string) => string;
+        readonly MIN_LENGTH: (field: string, min: number) => string;
+        readonly MAX_LENGTH: (field: string, max: number) => string;
+        readonly MIN_VALUE: (field: string, min: number) => string;
+        readonly MAX_VALUE: (field: string, max: number) => string;
+        readonly INVALID_FORMAT: (field: string) => string;
+        readonly INVALID_EMAIL: (field: string) => string;
+        readonly INVALID_URL: (field: string) => string;
+        readonly INVALID_UUID: (field: string) => string;
+        readonly INVALID_ENUM: (field: string, values: unknown[]) => string;
+        readonly MIN_ITEMS: (field: string, min: number) => string;
+        readonly MAX_ITEMS: (field: string, max: number) => string;
+    };
+};
+declare const BLOCKED: "[BLOCKED]";
+
+export { ArcisError, ValidationError as ArcisValidationError, BLOCKED, COMMAND_PATTERNS, DANGEROUS_PROTO_KEYS, ERRORS, HEADERS, INPUT, InputTooLargeError, NOSQL_DANGEROUS_KEYS, PATH_PATTERNS, RATE_LIMIT, REDACTION, RateLimitError, SQL_PATTERNS, SanitizationError, SecurityThreatError, VALIDATION, XSS_PATTERNS };

package/dist/core/index.d.ts

@@ -0,0 +1,170 @@
+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';
+import 'express';
+
+/**
+ * @module @arcis/node/core/errors
+ * Custom error classes for Arcis
+ */
+/**
+ * Base class for all Arcis errors
+ */
+declare class ArcisError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    /** Whether the error message is safe to expose to API clients. */
+    readonly expose: boolean;
+    constructor(message: string, statusCode?: number, code?: string);
+}
+/**
+ * Error thrown when input validation fails
+ */
+declare class ValidationError extends ArcisError {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+
+/**
+ * Error thrown when rate limit is exceeded
+ */
+declare class RateLimitError extends ArcisError {
+    readonly retryAfter: number;
+    constructor(message: string, retryAfter: number);
+}
+/**
+ * Error thrown when input is too large
+ */
+declare class InputTooLargeError extends ArcisError {
+    readonly maxSize: number;
+    readonly actualSize: number;
+    constructor(maxSize: number, actualSize: number);
+}
+/**
+ * Error thrown when security threat is detected
+ */
+declare class SecurityThreatError extends ArcisError {
+    readonly threatType: string;
+    readonly pattern: string;
+    constructor(threatType: string, pattern: string);
+}
+/**
+ * Error thrown when sanitization fails
+ */
+declare class SanitizationError extends ArcisError {
+    constructor(message: string);
+}
+
+/**
+ * @module @arcis/node/core/constants
+ * Named constants for Arcis - no magic numbers
+ */
+declare const INPUT: {
+    /** Default maximum input size (1MB) */
+    readonly DEFAULT_MAX_SIZE: 1000000;
+    /** Maximum recursion depth for nested objects */
+    readonly MAX_RECURSION_DEPTH: 10;
+};
+declare const RATE_LIMIT: {
+    /** Default window size (1 minute) */
+    readonly DEFAULT_WINDOW_MS: 60000;
+    /** Default max requests per window */
+    readonly DEFAULT_MAX_REQUESTS: 100;
+    /** Default HTTP status code for rate limited responses */
+    readonly DEFAULT_STATUS_CODE: 429;
+    /** Default error message */
+    readonly DEFAULT_MESSAGE: "Too many requests, please try again later.";
+    /** Minimum window size (1 second) */
+    readonly MIN_WINDOW_MS: 1000;
+    /** Maximum window size (24 hours) */
+    readonly MAX_WINDOW_MS: 86400000;
+};
+declare const HEADERS: {
+    /** Default Content Security Policy */
+    readonly DEFAULT_CSP: string;
+    /** Default HSTS max age (1 year in seconds) */
+    readonly HSTS_MAX_AGE: 31536000;
+    /** Default X-Frame-Options value */
+    readonly FRAME_OPTIONS: "DENY";
+    /** Default X-Content-Type-Options value */
+    readonly CONTENT_TYPE_OPTIONS: "nosniff";
+    /** Default Referrer-Policy value */
+    readonly REFERRER_POLICY: "strict-origin-when-cross-origin";
+    /** Default Permissions-Policy value */
+    readonly PERMISSIONS_POLICY: "geolocation=(), microphone=(), camera=()";
+    /** Default Cache-Control value for security */
+    readonly CACHE_CONTROL: "no-store, no-cache, must-revalidate, proxy-revalidate";
+};
+/**
+ * Detection patterns — used to flag whether a string contains XSS payloads.
+ * Must stay in sync with XSS_REMOVE_PATTERNS below.
+ */
+declare const XSS_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
+declare const SQL_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
+declare const PATH_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
+declare const COMMAND_PATTERNS: readonly [RegExp, RegExp];
+/**
+ * Prototype pollution keys to block.
+ * Stored lowercase — always compare with key.toLowerCase().
+ *
+ * Includes:
+ * - __proto__: direct prototype assignment
+ * - constructor: access to constructor.prototype chain
+ * - prototype: direct prototype property
+ * - __defineGetter__/__defineSetter__: legacy property definition (can override getters/setters)
+ * - __lookupGetter__/__lookupSetter__: legacy property introspection
+ */
+declare const DANGEROUS_PROTO_KEYS: Set<string>;
+/** MongoDB operators to block */
+declare const NOSQL_DANGEROUS_KEYS: Set<string>;
+declare const REDACTION: {
+    /** Replacement text for redacted values */
+    readonly REPLACEMENT: "[REDACTED]";
+    /** Truncation indicator */
+    readonly TRUNCATED: "[TRUNCATED]";
+    /** Max depth indicator */
+    readonly MAX_DEPTH: "[MAX_DEPTH]";
+    /** Default max message length */
+    readonly DEFAULT_MAX_LENGTH: 10000;
+    /** Default sensitive keys to redact */
+    readonly SENSITIVE_KEYS: Set<string>;
+};
+declare const VALIDATION: {
+    /**
+     * Email regex pattern.
+     * Rejects consecutive dots in local part (e.g. test..foo@example.com),
+     * leading/trailing dots, and other common invalid forms.
+     */
+    readonly EMAIL: RegExp;
+    /**
+     * URL regex pattern.
+     * Only allows http:// and https:// — explicitly rejects javascript:,
+     * data:, vbscript:, and other dangerous URI schemes.
+     */
+    readonly URL: RegExp;
+    /** UUID regex pattern (v4) */
+    readonly UUID: RegExp;
+};
+declare const ERRORS: {
+    /** Generic error message (production) */
+    readonly INTERNAL_SERVER_ERROR: "Internal Server Error";
+    /** Input too large error */
+    readonly INPUT_TOO_LARGE: (maxSize: number) => string;
+    /** Validation error messages */
+    readonly VALIDATION: {
+        readonly REQUIRED: (field: string) => string;
+        readonly INVALID_TYPE: (field: string, type: string) => string;
+        readonly MIN_LENGTH: (field: string, min: number) => string;
+        readonly MAX_LENGTH: (field: string, max: number) => string;
+        readonly MIN_VALUE: (field: string, min: number) => string;
+        readonly MAX_VALUE: (field: string, max: number) => string;
+        readonly INVALID_FORMAT: (field: string) => string;
+        readonly INVALID_EMAIL: (field: string) => string;
+        readonly INVALID_URL: (field: string) => string;
+        readonly INVALID_UUID: (field: string) => string;
+        readonly INVALID_ENUM: (field: string, values: unknown[]) => string;
+        readonly MIN_ITEMS: (field: string, min: number) => string;
+        readonly MAX_ITEMS: (field: string, max: number) => string;
+    };
+};
+declare const BLOCKED: "[BLOCKED]";
+
+export { ArcisError, ValidationError as ArcisValidationError, BLOCKED, COMMAND_PATTERNS, DANGEROUS_PROTO_KEYS, ERRORS, HEADERS, INPUT, InputTooLargeError, NOSQL_DANGEROUS_KEYS, PATH_PATTERNS, RATE_LIMIT, REDACTION, RateLimitError, SQL_PATTERNS, SanitizationError, SecurityThreatError, VALIDATION, XSS_PATTERNS };