@safeaccess/inline 0.1.1

package/src/security/forbidden-keys.ts

@@ -0,0 +1,81 @@
+/**
+ * Stream-wrapper and protocol URI schemes blocked by prefix matching in JavaScript environments.
+ *
+ * Entries include the delimiter (`://` or `:`) so that legitimate keys sharing
+ * the same word prefix (e.g. `node_modules`) are not blocked.
+ *
+ * PHP-specific wrappers (`phar://`, `php://`, `expect://`, `glob://`, `zlib://`,
+ * `ogg://`, `rar://`, `zip://`, `ssh2.tunnel://`) are intentionally absent — they
+ * have no meaning in a JavaScript/Node.js runtime.
+ *
+ * `data:` uses a single-colon delimiter (matching the browser RFC 2397 format
+ * `data:mimeType,...`) rather than `data://` (which is the PHP stream-wrapper
+ * syntax). Using `data:` as the prefix subsumes `data://` and also catches
+ * `data:text/html,<script>...</script>` XSS vectors, consistent with how
+ * `javascript:` is handled.
+ *
+ * @internal
+ */
+export const STREAM_WRAPPER_PREFIXES: readonly string[] = [
+    'file://',
+    'http://',
+    'https://',
+    'ftp://',
+    'data:',
+    'javascript:',
+    'blob:',
+    'ws://',
+    'wss://',
+    'node:',
+];
+
+/**
+ * Default forbidden keys for JavaScript/TypeScript environments.
+ *
+ * Stored lowercase for case-insensitive `__*` key lookup. Covers:
+ * – prototype pollution vectors (`__proto__`, `constructor`, `prototype`)
+ * – legacy prototype manipulation methods (`__defineGetter__` family, stored lowercase)
+ * – `hasOwnProperty` shadow (overriding it can bypass guard checks)
+ * – JS-relevant stream wrapper / protocol scheme strings as exact-match defence-in-depth
+ *
+ * PHP magic methods and PHP superglobals are deliberately absent — they are not
+ * meaningful in a JavaScript runtime and belong in the PHP package's SecurityGuard only.
+ *
+ * @internal
+ */
+export const DEFAULT_FORBIDDEN_KEYS: ReadonlySet<string> = new Set([
+    // Prototype pollution vectors (stored lowercase; __* keys normalised before lookup)
+    '__proto__',
+    'constructor',
+    'prototype',
+    // JavaScript legacy prototype manipulation (stored lowercase)
+    '__definegetter__',
+    '__definesetter__',
+    '__lookupgetter__',
+    '__lookupsetter__',
+    // Object.prototype shadow key — overriding it can break hasOwnProperty-based guards
+    'hasOwnProperty',
+    // Node.js module-scope path globals — should never appear as data keys to
+    // prevent path-injection risks in code that reads them via dynamic property access
+    '__dirname',
+    '__filename',
+    // Stream wrapper and protocol exact entries — also caught by STREAM_WRAPPER_PREFIXES prefix matching.
+    // The Set entries below are intentional defence-in-depth: they allow O(1) exact-key
+    // lookup before the O(n) prefix loop runs.
+    'file://',
+    'http://',
+    'https://',
+    'ftp://',
+    // 'data:' blocks browser RFC 2397 data URIs (data:mimeType,...) which can carry
+    // executable HTML/JS payloads (e.g. data:text/html,<script>alert(1)</script>).
+    // 'data://' is kept for exact-match parity with the PHP SecurityGuard that uses
+    // the PHP stream-wrapper notation; 'data:' prefix in STREAM_WRAPPER_PREFIXES
+    // already subsumes it for prefix-based lookups.
+    'data:',
+    'data://',
+    'javascript:',
+    'blob:',
+    'ws://',
+    'wss://',
+    'node:',
+]);

package/src/security/security-guard.ts

@@ -0,0 +1,195 @@
+import type { SecurityGuardInterface } from '../contracts/security-guard-interface.js';
+import { SecurityException } from '../exceptions/security-exception.js';
+import { DEFAULT_FORBIDDEN_KEYS, STREAM_WRAPPER_PREFIXES } from './forbidden-keys.js';
+
+/**
+ * Immutable guard that validates keys against a forbidden-key list.
+ *
+ * Blocks JavaScript prototype pollution vectors (`__proto__`, `constructor`,
+ * `prototype`), legacy prototype manipulation methods (`__defineGetter__` family),
+ * the `hasOwnProperty` shadow key, and JavaScript-relevant stream wrapper /
+ * protocol URIs (`file://`, `javascript:`, `ws://`, etc.) from being used as
+ * data keys. The forbidden list is built at construction time and cannot be
+ * modified afterward.
+ *
+ * `__*` keys are normalised to lowercase before lookup so that case variants
+ * such as `__PROTO__` are also blocked.
+ *
+ * Stream wrapper URIs are matched by prefix so that fully-formed URIs such as
+ * `javascript:alert(1)` are also blocked, not only the bare scheme string.
+ *
+ * @example
+ * const guard = new SecurityGuard();
+ * guard.assertSafeKey('name'); // OK
+ * guard.assertSafeKey('__proto__'); // throws SecurityException
+ */
+export class SecurityGuard implements SecurityGuardInterface {
+    readonly maxDepth: number;
+
+    private readonly forbiddenKeysMap: ReadonlySet<string>;
+
+    /**
+     * Build the guard with default forbidden keys plus any extras.
+     *
+     * @param maxDepth - Maximum recursion depth for recursive key scanning.
+     * @param extraForbiddenKeys - Additional keys to forbid beyond defaults.
+     */
+    constructor(maxDepth: number = 512, /* Stryker disable next-line ArrayDeclaration -- equivalent: default [] produces identical behavior; no extra keys added to Set */ extraForbiddenKeys: string[] = []) {
+        this.maxDepth = Number.isFinite(maxDepth) ? maxDepth : 512;
+
+        /* Stryker disable next-line ConditionalExpression -- equivalent: if (false) still produces the same forbiddenKeysMap for empty arrays since Set(DEFAULT)=DEFAULT */
+        if (extraForbiddenKeys.length === 0) {
+            this.forbiddenKeysMap = DEFAULT_FORBIDDEN_KEYS;
+        } else {
+            const combined = new Set(DEFAULT_FORBIDDEN_KEYS);
+            for (const key of extraForbiddenKeys) {
+                combined.add(key);
+            }
+            this.forbiddenKeysMap = combined;
+        }
+    }
+
+    /**
+     * Check whether a key is in the forbidden list.
+     *
+     * `__*` keys are normalised to lowercase before the map lookup so that
+     * case variants (e.g. `__PROTO__`) are also caught. Stream wrapper and
+     * protocol URIs are matched by prefix.
+     *
+     * @param key - Key name to check.
+     * @returns True if the key is forbidden.
+     *
+     * @example
+     * guard.isForbiddenKey('__proto__'); // true
+     * guard.isForbiddenKey('name');      // false
+     */
+    isForbiddenKey(key: string): boolean {
+        // Normalise __* keys to lowercase — catches case variants such as __PROTO__.
+        const lookupKey = key.startsWith('__') ? key.toLowerCase() : key;
+
+        if (this.forbiddenKeysMap.has(lookupKey)) {
+            return true;
+        }
+
+        const lower = key.toLowerCase();
+        for (const prefix of STREAM_WRAPPER_PREFIXES) {
+            if (lower.startsWith(prefix)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Assert that a single key is safe, throwing on violation.
+     *
+     * @param key - Key name to validate.
+     * @throws {SecurityException} When the key is in the forbidden list.
+     *
+     * @example
+     * guard.assertSafeKey('username'); // OK
+     * guard.assertSafeKey('__proto__'); // throws SecurityException
+     */
+    assertSafeKey(key: string): void {
+        if (this.isForbiddenKey(key)) {
+            throw new SecurityException(`Forbidden key '${key}' detected.`);
+        }
+    }
+
+    /**
+     * Recursively assert that all keys in a data structure are safe.
+     *
+     * @param data - Data to scan for forbidden keys.
+     * @param depth - Current recursion depth.
+     * @throws {SecurityException} When a forbidden key is found or depth exceeds the limit.
+     *
+     * @example
+     * guard.assertSafeKeys({ name: 'Alice', age: 30 }); // OK
+     * guard.assertSafeKeys({ __proto__: 'bad' }); // throws SecurityException
+     */
+    assertSafeKeys(data: unknown, depth: number = 0): void {
+        if (typeof data !== 'object' || data === null) {
+            return;
+        }
+
+        /* Stryker disable next-line EqualityOperator -- boundary: depth > max vs depth >= max; ≥ would throw one level too early */
+        if (depth > this.maxDepth) {
+            throw new SecurityException(
+                `Recursion depth ${depth} exceeds maximum of ${this.maxDepth}.`,
+            );
+        }
+
+        for (const [key, value] of Object.entries(data as Record<string, unknown>)) {
+            this.assertSafeKey(key);
+            this.assertSafeKeys(value, depth + 1);
+        }
+    }
+
+    /**
+     * Remove all forbidden keys from a data structure recursively.
+     *
+     * @param data - Data to sanitize.
+     * @param depth - Current recursion depth.
+     * @returns Sanitized data without forbidden keys.
+     * @throws {SecurityException} When recursion depth exceeds the limit.
+     *
+     * @example
+     * guard.sanitize({ name: 'Alice', __construct: 'bad' });
+     * // => { name: 'Alice' }
+     */
+    sanitize(data: Record<string, unknown>, depth: number = 0): Record<string, unknown> {
+        /* Stryker disable next-line EqualityOperator -- boundary: depth > max vs depth >= max; >= would throw one level too early */
+        if (depth > this.maxDepth) {
+            throw new SecurityException(
+                `Recursion depth ${depth} exceeds maximum of ${this.maxDepth}.`,
+            );
+        }
+
+        const result: Record<string, unknown> = {};
+
+        for (const [key, value] of Object.entries(data)) {
+            if (this.isForbiddenKey(key)) {
+                continue;
+            }
+
+            if (Array.isArray(value)) {
+                result[key] = this.sanitizeArray(value, depth + 1);
+            } else if (typeof value === 'object' && value !== null) {
+                result[key] = this.sanitize(value as Record<string, unknown>, depth + 1);
+            } else {
+                result[key] = value;
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * Recursively sanitize array elements, removing forbidden keys from nested objects.
+     *
+     * @param array - Array to sanitize.
+     * @param depth - Current recursion depth.
+     * @returns Sanitized array with forbidden keys removed from object elements.
+     *
+     * @throws {SecurityException} When recursion depth exceeds the limit.
+     */
+    private sanitizeArray(array: unknown[], depth: number): unknown[] {
+        /* Stryker disable next-line EqualityOperator -- boundary: depth > max vs depth >= max; >= would throw one level too early */
+        if (depth > this.maxDepth) {
+            throw new SecurityException(
+                `Recursion depth ${depth} exceeds maximum of ${this.maxDepth}.`,
+            );
+        }
+
+        return array.map((item) => {
+            if (Array.isArray(item)) {
+                return this.sanitizeArray(item, depth + 1);
+            }
+            if (typeof item === 'object' && item !== null) {
+                return this.sanitize(item as Record<string, unknown>, depth + 1);
+            }
+            return item;
+        });
+    }
+}

package/src/security/security-parser.ts

@@ -0,0 +1,233 @@
+import type { SecurityParserInterface } from '../contracts/security-parser-interface.js';
+import { SecurityException } from '../exceptions/security-exception.js';
+
+/**
+ * Enforce structural security constraints on parsed data.
+ *
+ * Validates payload size, maximum key count, recursion depth, and
+ * structural depth limits.
+ *
+ * @example
+ * const parser = new SecurityParser({ maxDepth: 10, maxKeys: 100 });
+ * parser.assertPayloadSize('{"key":"value"}');
+ */
+export class SecurityParser implements SecurityParserInterface {
+    readonly maxDepth: number;
+    readonly maxPayloadBytes: number;
+    readonly maxKeys: number;
+    readonly maxCountRecursiveDepth: number;
+    readonly maxResolveDepth: number;
+
+    /**
+     * Build security options from configuration values.
+     *
+     * @param options - Configuration overrides.
+     * @param options.maxDepth - Maximum allowed structural nesting depth. Default: 512.
+     * @param options.maxPayloadBytes - Maximum allowed raw payload size in bytes. Default: 10 MB.
+     * @param options.maxKeys - Maximum total number of keys across the entire structure. Default: 10000.
+     *   This value is also passed to `XmlParser` as the element-count cap for the Node.js manual XML
+     *   parser path. Setting it below a document's element count will cause `fromXml()` to throw
+     *   `SecurityException`. Non-positive or non-finite values disable that guard — prefer the default.
+     * @param options.maxCountRecursiveDepth - Maximum recursion depth when counting keys. Default: 100.
+     * @param options.maxResolveDepth - Maximum recursion depth for path resolution. Default: 100.
+     */
+    constructor(
+        options: {
+            maxDepth?: number;
+            maxPayloadBytes?: number;
+            maxKeys?: number;
+            maxCountRecursiveDepth?: number;
+            maxResolveDepth?: number;
+        } = {},
+    ) {
+        this.maxDepth = SecurityParser.clampOption(options.maxDepth, 512);
+        this.maxPayloadBytes = SecurityParser.clampOption(options.maxPayloadBytes, 10 * 1024 * 1024);
+        this.maxKeys = SecurityParser.clampOption(options.maxKeys, 10_000);
+        this.maxCountRecursiveDepth = SecurityParser.clampOption(options.maxCountRecursiveDepth, 100);
+        this.maxResolveDepth = SecurityParser.clampOption(options.maxResolveDepth, 100);
+    }
+
+    /**
+     * Assert that a raw string payload does not exceed the byte limit.
+     *
+     * @param input - Raw input string to measure.
+     * @param maxBytes - Override limit, or undefined to use configured default.
+     * @throws {SecurityException} When the payload exceeds the limit.
+     *
+     * @example
+     * parser.assertPayloadSize('small input'); // OK
+     */
+    assertPayloadSize(input: string, maxBytes?: number): void {
+        const limit = maxBytes ?? this.maxPayloadBytes;
+        const size = new TextEncoder().encode(input).length;
+
+        if (size > limit) {
+            throw new SecurityException(
+                `Payload size ${size} bytes exceeds maximum of ${limit} bytes.`,
+            );
+        }
+    }
+
+    /**
+     * Assert that resolve depth does not exceed the configured limit.
+     *
+     * @param depth - Current depth counter.
+     * @throws {SecurityException} When depth exceeds the maximum.
+     *
+     * @example
+     * parser.assertMaxResolveDepth(5); // OK
+     */
+    assertMaxResolveDepth(depth: number): void {
+        if (depth > this.maxResolveDepth) {
+            throw new SecurityException(
+                `Deep merge exceeded maximum depth of ${this.maxResolveDepth}`,
+            );
+        }
+    }
+
+    /**
+     * Assert that total key count does not exceed the limit.
+     *
+     * @param data - Data to count keys in.
+     * @param maxKeys - Override limit, or undefined to use configured default.
+     * @param maxCountDepth - Override recursion depth limit, or undefined for default.
+     * @throws {SecurityException} When key count exceeds the limit.
+     *
+     * @example
+     * parser.assertMaxKeys({ a: 1, b: 2 }); // OK
+     */
+    assertMaxKeys(data: Record<string, unknown>, maxKeys?: number, maxCountDepth?: number): void {
+        const limit = maxKeys ?? this.maxKeys;
+        const count = this.countKeys(data, 0, maxCountDepth ?? this.maxCountRecursiveDepth);
+
+        if (count > limit) {
+            throw new SecurityException(
+                `Data contains ${count} keys, exceeding maximum of ${limit}.`,
+            );
+        }
+    }
+
+    /**
+     * Assert that current recursion depth does not exceed the limit.
+     *
+     * @param currentDepth - Current depth counter.
+     * @param maxDepth - Override limit, or undefined to use configured default.
+     * @throws {SecurityException} When the depth exceeds the limit.
+     *
+     * @example
+     * parser.assertMaxDepth(3); // OK
+     */
+    assertMaxDepth(currentDepth: number, maxDepth?: number): void {
+        const limit = maxDepth ?? this.maxDepth;
+        if (currentDepth > limit) {
+            throw new SecurityException(
+                `Recursion depth ${currentDepth} exceeds maximum of ${limit}.`,
+            );
+        }
+    }
+
+    /**
+     * Assert that structural nesting depth does not exceed the policy limit.
+     *
+     * @param data - Data to measure structural depth of.
+     * @param maxDepth - Maximum allowed structural depth.
+     * @throws {SecurityException} When structural depth exceeds the limit.
+     *
+     * @example
+     * parser.assertMaxStructuralDepth({ a: { b: 1 } }, 10); // OK
+     */
+    assertMaxStructuralDepth(data: unknown, maxDepth: number): void {
+        const depth = this.measureDepth(data, 0, maxDepth + 1);
+        if (depth > maxDepth) {
+            throw new SecurityException(
+                `Data structural depth ${depth} exceeds policy maximum of ${maxDepth}.`,
+            );
+        }
+    }
+
+    /**
+     * Return the configured maximum structural nesting depth.
+     *
+     * @returns Maximum allowed depth.
+     */
+    getMaxDepth(): number {
+        return this.maxDepth;
+    }
+
+    /**
+     * Return the configured maximum path-resolve recursion depth.
+     *
+     * @returns Maximum allowed resolve depth.
+     */
+    getMaxResolveDepth(): number {
+        return this.maxResolveDepth;
+    }
+
+    /**
+     * Return the configured maximum total key count.
+     *
+     * @returns Maximum allowed key count.
+     */
+    getMaxKeys(): number {
+        return this.maxKeys;
+    }
+
+    /**
+     * Recursively count keys in a data structure.
+     *
+     * @param obj - Data to count keys in.
+     * @param depth - Current recursion depth.
+     * @param maxDepth - Maximum recursion depth for counting.
+     * @returns Total number of keys found.
+     */
+    private countKeys(obj: unknown, depth: number, maxDepth: number): number {
+        if (depth > maxDepth) {
+            return 0;
+        }
+
+        if (typeof obj !== 'object' || obj === null) {
+            return 0;
+        }
+
+        const entries = Object.entries(obj as Record<string, unknown>);
+        let count = entries.length;
+
+        for (const [, value] of entries) {
+            count += this.countKeys(value, depth + 1, maxDepth);
+        }
+
+        return count;
+    }
+
+    /**
+     * Recursively measure the maximum nesting depth of a data structure.
+     *
+     * @param value - Data to measure.
+     * @param current - Current depth counter.
+     * @param maxDepth - Ceiling to stop measuring.
+     * @returns Maximum depth found.
+     */
+    private measureDepth(value: unknown, current: number, maxDepth: number): number {
+        /* Stryker disable next-line ConditionalExpression,EqualityOperator -- equivalent: >= vs > at ceiling; both correctly stop at maxDepth */
+        if (current >= maxDepth || typeof value !== 'object' || value === null) {
+            return current;
+        }
+
+        let max = current;
+
+        for (const child of Object.values(value as Record<string, unknown>)) {
+            const d = this.measureDepth(child, current + 1, maxDepth);
+            /* Stryker disable next-line ConditionalExpression,EqualityOperator -- equivalent: d > max vs d >= max; assigning d when d===max is a no-op */
+            if (d > max) {
+                max = d;
+            }
+        }
+
+        return max;
+    }
+
+    private static clampOption(value: number | undefined, defaultValue: number): number {
+        /* Stryker disable next-line ConditionalExpression -- equivalent: Number.isFinite covers undefined (isFinite(undefined)===false); simplest safe form */
+        return Number.isFinite(value) ? (value as number) : defaultValue;
+    }
+}

package/src/type-format.ts

@@ -0,0 +1,28 @@
+/**
+ * Enumeration of supported data format types.
+ *
+ * Used by {@link Inline.from} to select the appropriate accessor.
+ *
+ * @example
+ * const accessor = Inline.from(TypeFormat.Json, '{"key":"value"}');
+ */
+export enum TypeFormat {
+    /** Plain array or object data. */
+    Array = 'array',
+    /** JavaScript object (class instance or plain). */
+    Object = 'object',
+    /** JSON string. */
+    Json = 'json',
+    /** XML string. */
+    Xml = 'xml',
+    /** YAML string. */
+    Yaml = 'yaml',
+    /** INI configuration string. */
+    Ini = 'ini',
+    /** Dotenv-formatted string. */
+    Env = 'env',
+    /** Newline-delimited JSON string. */
+    Ndjson = 'ndjson',
+    /** Auto-detected format via integration. */
+    Any = 'any',
+}

package/stryker.config.json

@@ -0,0 +1,24 @@
+{
+    "testRunner": "vitest",
+    "mutate": [
+        "src/**/*.ts",
+        "!src/**/*.test.ts",
+        "!src/index.ts",
+        "!src/contracts/**/*.ts",
+        "!src/exceptions/**/*.ts",
+        "!src/security/forbidden-keys.ts",
+        "!src/parser/yaml-parser.ts",
+        "!src/parser/xml-parser.ts"
+    ],
+    "thresholds": {
+        "high": 100,
+        "low": 100,
+        "break": 100
+    },
+    "timeoutMS": 60000,
+    "concurrency": 4,
+    "reporters": ["html", "clear-text", "progress"],
+    "htmlReporter": {
+        "fileName": "reports/stryker/mutation.html"
+    }
+}