@arcis/node 1.3.0 → 1.4.0

package/dist/encode-CrQCGlBq.d.mts

@@ -1,484 +0,0 @@
-import { RequestHandler } from 'express';
-import { i as SanitizeOptions, j as SanitizeResult } from './types-BOkx5YJc.mjs';
-
-/**
- * @module @arcis/node/sanitizers/sanitize
- * Main sanitization functions that combine all sanitizers
- */
-
-/**
- * Sanitize a string value against multiple attack vectors.
- *
- * Order matters: We do XSS encoding LAST because:
- * 1. Other sanitizers need to see the original patterns (e.g., SQL keywords)
- * 2. HTML encoding is the final safe output transformation
- * 3. Encoded entities like < shouldn't be treated as SQL/command threats
- *
- * @param value - The string to sanitize
- * @param options - Sanitization options
- * @returns The sanitized string
- *
- * @example
- * sanitizeString("<script>alert('xss')</script>")
- * // Returns: "&lt;script&gt;alert(&#x27;xss&#x27;)&lt;/script&gt;"
- *
- * @example
- * sanitizeString("../../etc/passwd")
- * // Returns: "etc/passwd"
- */
-declare function sanitizeString(value: string, options?: SanitizeOptions): string;
-/**
- * Sanitize an object recursively, including nested objects and arrays.
- * Also removes prototype pollution and NoSQL injection keys.
- *
- * @param obj - The object to sanitize
- * @param options - Sanitization options
- * @returns The sanitized object
- */
-declare function sanitizeObject(obj: unknown, options?: SanitizeOptions): unknown;
-/**
- * Create Express middleware for request sanitization.
- * Sanitizes req.body, req.query, and req.params.
- *
- * @param options - Sanitization options
- * @returns Express middleware
- *
- * @example
- * app.use(createSanitizer());
- *
- * @example
- * app.use(createSanitizer({ xss: true, sql: true, nosql: true }));
- */
-declare function createSanitizer(options?: SanitizeOptions): RequestHandler;
-
-/**
- * @module @arcis/node/sanitizers/xss
- * XSS (Cross-Site Scripting) prevention
- */
-
-/**
- * Sanitizes a string to prevent XSS attacks.
- *
- * Strategy:
- * 1. Remove dangerous patterns (script tags, event handlers, etc.)
- * 2. HTML-encode the remaining content
- *
- * @param input - The string to sanitize
- * @param collectThreats - Whether to collect threat information (default: false for performance)
- * @returns Sanitized string or SanitizeResult if collectThreats is true
- *
- * @example
- * sanitizeXss("<script>alert('xss')</script>")
- * // Returns: "&lt;script&gt;alert(&#x27;xss&#x27;)&lt;/script&gt;"
- *
- * @example
- * sanitizeXss("<img onerror='alert(1)'>")
- * // Returns: "&lt;img&gt;" (event handler removed)
- */
-declare function sanitizeXss(input: string, collectThreats?: false, htmlEncode?: boolean): string;
-declare function sanitizeXss(input: string, collectThreats: true, htmlEncode?: boolean): SanitizeResult;
-/**
- * Checks if a string contains potential XSS patterns.
- * Does not sanitize — use sanitizeXss() for that.
- *
- * @param input - The string to check
- * @returns True if XSS patterns detected
- */
-declare function detectXss(input: string): boolean;
-
-/**
- * @module @arcis/node/sanitizers/sql
- * SQL injection prevention
- */
-
-/**
- * Sanitizes a string to prevent SQL injection attacks.
- * Replaces dangerous SQL patterns with [BLOCKED].
- *
- * @param input - The string to sanitize
- * @param collectThreats - Whether to collect threat information (default: false for performance)
- * @returns Sanitized string or SanitizeResult if collectThreats is true
- *
- * @example
- * sanitizeSql("'; DROP TABLE users; --")
- * // Returns: "';  TABLE users  "
- */
-declare function sanitizeSql(input: string, collectThreats?: false): string;
-declare function sanitizeSql(input: string, collectThreats: true): SanitizeResult;
-/**
- * Checks if a string contains potential SQL injection patterns.
- * Does not sanitize — use sanitizeSql() for that.
- *
- * @param input - The string to check
- * @returns True if SQL injection patterns detected
- */
-declare function detectSql(input: string): boolean;
-
-/**
- * @module @arcis/node/sanitizers/path
- * Path traversal prevention
- */
-
-/**
- * Sanitizes a string to prevent path traversal attacks.
- * Removes ../ and ..\ patterns (including URL-encoded variants).
- *
- * @param input - The string to sanitize
- * @param collectThreats - Whether to collect threat information (default: false for performance)
- * @returns Sanitized string or SanitizeResult if collectThreats is true
- *
- * @example
- * sanitizePath("../../etc/passwd")
- * // Returns: "etc/passwd"
- */
-declare function sanitizePath(input: string, collectThreats?: false): string;
-declare function sanitizePath(input: string, collectThreats: true): SanitizeResult;
-/**
- * Checks if a string contains path traversal patterns.
- * Does not sanitize — use sanitizePath() for that.
- *
- * @param input - The string to check
- * @returns True if path traversal patterns detected
- */
-declare function detectPathTraversal(input: string): boolean;
-
-/**
- * @module @arcis/node/sanitizers/command
- * Command injection prevention
- */
-
-/**
- * Sanitizes a string to prevent command injection attacks.
- * Replaces shell metacharacters and dangerous commands with [BLOCKED].
- *
- * @param input - The string to sanitize
- * @param collectThreats - Whether to collect threat information (default: false for performance)
- * @returns Sanitized string or SanitizeResult if collectThreats is true
- *
- * @example
- * sanitizeCommand("file.txt; rm -rf /")
- * // Returns: "file.txt  rm -rf /"
- */
-declare function sanitizeCommand(input: string, collectThreats?: false): string;
-declare function sanitizeCommand(input: string, collectThreats: true): SanitizeResult;
-/**
- * Checks if a string contains command injection patterns.
- * Does not sanitize — use sanitizeCommand() for that.
- *
- * @param input - The string to check
- * @returns True if command injection patterns detected
- */
-declare function detectCommandInjection(input: string): boolean;
-
-/**
- * @module @arcis/node/sanitizers/ssti
- * Server-Side Template Injection (SSTI) prevention
- */
-
-/**
- * Sanitizes a string to prevent SSTI attacks.
- * Removes template expression syntax.
- */
-declare function sanitizeSsti(input: string, collectThreats?: false): string;
-declare function sanitizeSsti(input: string, collectThreats: true): SanitizeResult;
-/**
- * Checks if a string contains SSTI patterns.
- * Does not sanitize — use sanitizeSsti() for that.
- *
- * @param input - The string to check
- * @returns True if SSTI patterns detected
- */
-declare function detectSsti(input: string): boolean;
-
-/**
- * @module @arcis/node/sanitizers/xxe
- * XML External Entity (XXE) injection prevention
- */
-
-/**
- * Sanitizes a string to prevent XXE attacks.
- * Removes DOCTYPE, ENTITY, and CDATA constructs.
- */
-declare function sanitizeXxe(input: string, collectThreats?: false): string;
-declare function sanitizeXxe(input: string, collectThreats: true): SanitizeResult;
-/**
- * Checks if a string contains XXE patterns.
- * Does not sanitize — use sanitizeXxe() for that.
- *
- * @param input - The string to check
- * @returns True if XXE patterns detected
- */
-declare function detectXxe(input: string): boolean;
-
-/**
- * @module @arcis/node/sanitizers/jsonp
- * JSONP callback sanitization to prevent XSS via callback parameters
- */
-/**
- * Validates and sanitizes a JSONP callback parameter.
- *
- * Returns the callback name if safe, or null if the callback is dangerous.
- * Use this to validate `?callback=` query parameters before wrapping responses.
- *
- * @param callback - The callback parameter value
- * @param maxLength - Maximum allowed length (default: 128)
- * @returns The safe callback name, or null if invalid
- *
- * @example
- * ```ts
- * const cb = sanitizeJsonpCallback(req.query.callback);
- * if (cb) {
- *   res.set('Content-Type', 'application/javascript');
- *   res.send(`${cb}(${JSON.stringify(data)})`);
- * } else {
- *   res.status(400).json({ error: 'Invalid callback' });
- * }
- * ```
- */
-declare function sanitizeJsonpCallback(callback: string, maxLength?: number): string | null;
-/**
- * Checks if a JSONP callback parameter contains potentially dangerous content.
- *
- * @param callback - The callback parameter value
- * @returns True if the callback is dangerous / invalid
- */
-declare function detectJsonpInjection(callback: string): boolean;
-
-/**
- * @module @arcis/node/sanitizers/nosql
- * NoSQL injection prevention (MongoDB operators)
- */
-/**
- * Checks if a key is a dangerous MongoDB operator.
- *
- * @param key - The key to check
- * @returns True if the key is a MongoDB operator
- *
- * @example
- * isDangerousNoSqlKey('$gt') // true
- * isDangerousNoSqlKey('name') // false
- */
-declare function isDangerousNoSqlKey(key: string): boolean;
-/**
- * Recursively checks if an object contains dangerous MongoDB operators.
- *
- * @param obj - The object to check
- * @param maxDepth - Maximum recursion depth (default: 10)
- * @returns True if dangerous operators found
- */
-declare function detectNoSqlInjection(obj: unknown, maxDepth?: number): boolean;
-/**
- * Get list of all MongoDB operators considered dangerous.
- * Useful for documentation or custom validation.
- *
- * @returns Array of dangerous operator strings
- */
-declare function getDangerousOperators(): string[];
-
-/**
- * @module @arcis/node/sanitizers/prototype
- * Prototype pollution prevention
- */
-/**
- * Checks if a key is dangerous for prototype pollution.
- * Case-insensitive — catches __PROTO__, Constructor, etc.
- *
- * @param key - The key to check
- * @returns True if the key could cause prototype pollution
- *
- * @example
- * isDangerousProtoKey('__proto__')   // true
- * isDangerousProtoKey('__PROTO__')   // true
- * isDangerousProtoKey('Constructor') // true
- * isDangerousProtoKey('name')        // false
- */
-declare function isDangerousProtoKey(key: string): boolean;
-/**
- * Recursively checks if an object contains prototype pollution keys.
- *
- * @param obj - The object to check
- * @param maxDepth - Maximum recursion depth (default: 10)
- * @returns True if dangerous keys found
- */
-declare function detectPrototypePollution(obj: unknown, maxDepth?: number): boolean;
-/**
- * Get list of all keys considered dangerous for prototype pollution.
- * Useful for documentation or custom validation.
- *
- * @returns Array of dangerous key strings
- */
-declare function getDangerousProtoKeys(): string[];
-
-/**
- * @module @arcis/node/sanitizers/headers
- * HTTP Header Injection & CRLF Injection prevention
- *
- * Prevents attackers from injecting newline characters (\r\n) into HTTP header
- * values, which can lead to response splitting, session fixation, XSS via
- * injected headers, and cache poisoning.
- */
-
-/**
- * Sanitizes a header value by stripping CRLF sequences, bare CR/LF, and null bytes.
- *
- * @param input - The header value to sanitize
- * @param collectThreats - Whether to collect threat information (default: false)
- * @returns Sanitized string or SanitizeResult if collectThreats is true
- *
- * @example
- * sanitizeHeaderValue("safe-value")
- * // Returns: "safe-value"
- *
- * sanitizeHeaderValue("value\r\nX-Injected: evil")
- * // Returns: "valueX-Injected: evil"
- */
-declare function sanitizeHeaderValue(input: string, collectThreats?: false): string;
-declare function sanitizeHeaderValue(input: string, collectThreats: true): SanitizeResult;
-/**
- * Sanitizes an object of header key-value pairs.
- * Strips CRLF/null bytes from both keys and values.
- *
- * @param headers - Object with header names as keys and header values as values
- * @returns New object with sanitized header names and values
- *
- * @example
- * sanitizeHeaders({ "X-Custom": "safe", "X-Bad\r\n": "value\r\ninjected" })
- * // Returns: { "X-Custom": "safe", "X-Bad": "valueinjected" }
- */
-declare function sanitizeHeaders(headers: Record<string, string>): Record<string, string>;
-/**
- * Checks if a string contains HTTP header injection patterns (CRLF, null bytes).
- * Does not sanitize — use sanitizeHeaderValue() for that.
- *
- * @param input - The string to check
- * @returns True if header injection patterns detected
- */
-declare function detectHeaderInjection(input: string): boolean;
-
-/**
- * @module @arcis/node/sanitizers/pii
- * PII (Personally Identifiable Information) detection and redaction
- *
- * Detects: email addresses, phone numbers, credit card numbers, SSNs, IP addresses
- */
-type PiiType = 'email' | 'phone' | 'credit_card' | 'ssn' | 'ip_address';
-interface PiiMatch {
-    type: PiiType;
-    value: string;
-    start: number;
-    end: number;
-}
-interface PiiScanOptions {
-    /** PII types to scan for. Default: all types */
-    types?: PiiType[];
-}
-interface PiiRedactOptions extends PiiScanOptions {
-    /** Replacement for redacted values. Default: '[REDACTED]' */
-    replacement?: string;
-    /** Use type-specific replacements like '[EMAIL]', '[SSN]'. Default: false */
-    typeLabels?: boolean;
-}
-/**
- * Scan a string for PII and return all matches.
- *
- * @param input - String to scan
- * @param options - Optional scan configuration
- * @returns Array of PII matches with type, value, and position
- *
- * @example
- * scanPii('Call me at 555-123-4567 or email john@example.com')
- * // [
- * //   { type: 'phone', value: '555-123-4567', start: 11, end: 23 },
- * //   { type: 'email', value: 'john@example.com', start: 33, end: 49 }
- * // ]
- */
-declare function scanPii(input: string, options?: PiiScanOptions): PiiMatch[];
-/**
- * Check if a string contains any PII.
- *
- * @param input - String to check
- * @param options - Optional scan configuration
- * @returns true if PII is detected
- */
-declare function detectPii(input: string, options?: PiiScanOptions): boolean;
-/**
- * Redact PII from a string, replacing matches with a placeholder.
- *
- * @param input - String to redact
- * @param options - Redaction options
- * @returns String with PII replaced
- *
- * @example
- * redactPii('Email: john@example.com, SSN: 123-45-6789')
- * // 'Email: [REDACTED], SSN: [REDACTED]'
- *
- * redactPii('Email: john@example.com', { typeLabels: true })
- * // 'Email: [EMAIL]'
- */
-declare function redactPii(input: string, options?: PiiRedactOptions): string;
-/**
- * Scan an object's string values for PII recursively.
- *
- * @param obj - Object to scan
- * @param options - Optional scan configuration
- * @returns Array of PII matches with the field path prepended
- */
-declare function scanObjectPii(obj: Record<string, unknown>, options?: PiiScanOptions, path?: string): (PiiMatch & {
-    field: string;
-})[];
-/**
- * Redact PII from all string values in an object recursively.
- *
- * @param obj - Object to redact
- * @param options - Redaction options
- * @returns New object with PII redacted
- */
-declare function redactObjectPii<T extends Record<string, unknown>>(obj: T, options?: PiiRedactOptions): T;
-
-/**
- * @module @arcis/node/sanitizers/encode
- * Context-aware output encoding for XSS prevention.
- *
- * Wrong-context encoding is the #1 cause of XSS bypasses in "protected" apps.
- * A single sanitize() is not enough when output goes to JS, CSS, or attribute contexts.
- */
-/**
- * Encodes for HTML body context. Entity-encodes & < > " '
- *
- * Use when outputting to HTML element content:
- *   `<p>${encodeForHtml(userInput)}</p>`
- */
-declare function encodeForHtml(value: string): string;
-/**
- * Encodes for HTML attribute context.
- * All non-alphanumeric characters are encoded as `&#xHH;` hex entities.
- *
- * Use when outputting to HTML attributes:
- *   `<div title="${encodeForAttribute(userInput)}">`
- */
-declare function encodeForAttribute(value: string): string;
-/**
- * Encodes for JavaScript string context.
- * Non-alphanumeric characters are escaped as `\xHH` (ASCII) or `\uHHHH` (Unicode).
- *
- * Use when embedding in JS string literals:
- *   `var x = '${encodeForJs(userInput)}';`
- */
-declare function encodeForJs(value: string): string;
-/**
- * Encodes for URL parameter context. Percent-encodes all non-unreserved chars.
- *
- * Use when building query strings:
- *   `?q=${encodeForUrl(userInput)}`
- */
-declare function encodeForUrl(value: string): string;
-/**
- * Encodes for CSS value context.
- * Non-alphanumeric characters are hex-escaped as `\HH ` (trailing space per CSS spec).
- *
- * Use when embedding in CSS values:
- *   `content: '${encodeForCss(userInput)}';`
- */
-declare function encodeForCss(value: string): string;
-
-export { sanitizeJsonpCallback as A, sanitizeObject as B, sanitizePath as C, sanitizeSql as D, sanitizeSsti as E, sanitizeString as F, sanitizeXss as G, sanitizeXxe as H, scanObjectPii as I, scanPii as J, type PiiRedactOptions as K, type PiiScanOptions as L, type PiiType as M, type PiiMatch as P, detectHeaderInjection as a, detectJsonpInjection as b, createSanitizer as c, detectCommandInjection as d, detectNoSqlInjection as e, detectPathTraversal as f, detectPii as g, detectPrototypePollution as h, detectSql as i, detectSsti as j, detectXss as k, detectXxe as l, encodeForAttribute as m, encodeForCss as n, encodeForHtml as o, encodeForJs as p, encodeForUrl as q, getDangerousOperators as r, getDangerousProtoKeys as s, isDangerousNoSqlKey as t, isDangerousProtoKey as u, redactObjectPii as v, redactPii as w, sanitizeCommand as x, sanitizeHeaderValue as y, sanitizeHeaders as z };