@safeaccess/inline 0.1.1 → 0.1.3

package/src/path-query/segment-path-resolver.ts

@@ -0,0 +1,521 @@
+import type { FilterEvaluatorInterface } from '../contracts/filter-evaluator-interface.js';
+import { SecurityException } from '../exceptions/security-exception.js';
+import { SegmentType } from './segment-type.js';
+import type { Segment, FilterExpression, ProjectionField } from './segment-type.js';
+
+/**
+ * Resolve typed path segments against nested data structures.
+ *
+ * Traverses data using segment arrays produced by {@link SegmentParser},
+ * dispatching to segment-type-specific handlers for key, wildcard,
+ * descent, filter, slice, multi-key/index, and projection operations.
+ *
+ * @internal
+ *
+ * @see SegmentParser           Produces the segment arrays this resolver consumes.
+ * @see SegmentType             Enum governing which handler is dispatched.
+ * @see FilterEvaluatorInterface  Delegate for filter predicate evaluation.
+ * @see DotNotationParser       Invokes this resolver for path queries.
+ */
+export class SegmentPathResolver {
+    /**
+     * Create a resolver with a filter evaluator.
+     *
+     * @param segmentFilterParser - Delegate for filter evaluation.
+     */
+    constructor(private readonly segmentFilterParser: FilterEvaluatorInterface) {}
+
+    /**
+     * Resolve a value by walking segments starting at the given index.
+     *
+     * @param current - Current data node.
+     * @param segments - Typed segment array from {@link SegmentParser}.
+     * @param index - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth - Maximum recursion depth.
+     * @returns Resolved value or the default.
+     *
+     * @throws {SecurityException} When recursion depth exceeds the limit.
+     */
+    resolve(
+        current: unknown,
+        segments: ReadonlyArray<Segment>,
+        index: number,
+        defaultValue: unknown,
+        maxDepth: number,
+    ): unknown {
+        if (index > maxDepth) {
+            throw new SecurityException(`Recursion depth ${index} exceeds maximum of ${maxDepth}.`);
+        }
+
+        if (index >= segments.length) {
+            return current;
+        }
+
+        const segment = segments[index];
+
+        switch (segment.type) {
+            case SegmentType.Descent:
+                return this.segmentDescent(current, segments, index, defaultValue, maxDepth);
+            case SegmentType.DescentMulti:
+                return this.segmentDescentMulti(current, segments, index, defaultValue, maxDepth);
+            case SegmentType.Wildcard:
+                return this.segmentWildcard(current, segments, index, defaultValue, maxDepth);
+            case SegmentType.Filter:
+                return this.segmentFilter(current, segments, index, defaultValue, maxDepth);
+            case SegmentType.MultiKey:
+                return this.segmentMultiKey(current, segments, index, defaultValue, maxDepth);
+            case SegmentType.MultiIndex:
+                return this.segmentMultiIndex(current, segments, index, defaultValue, maxDepth);
+            case SegmentType.Slice:
+                return this.segmentSlice(current, segments, index, defaultValue, maxDepth);
+            case SegmentType.Projection:
+                return this.segmentProjection(current, segments, index, defaultValue, maxDepth);
+            default:
+                return this.segmentAny(current, segments, index, defaultValue, maxDepth);
+        }
+    }
+
+    /**
+     * Resolve a simple key/index segment.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Resolved value or the default.
+     */
+    private segmentAny(
+        current: unknown,
+        segments: ReadonlyArray<Segment>,
+        index: number,
+        defaultValue: unknown,
+        maxDepth: number,
+    ): unknown {
+        const segment = segments[index];
+        const keyValue = 'value' in segment ? (segment as { value: string }).value : '';
+
+        if (
+            typeof current === 'object' &&
+            current !== null &&
+            Object.prototype.hasOwnProperty.call(current, keyValue)
+        ) {
+            return this.resolve(
+                (current as Record<string, unknown>)[keyValue],
+                segments,
+                index + 1,
+                defaultValue,
+                maxDepth,
+            );
+        }
+
+        return defaultValue;
+    }
+
+    /**
+     * Resolve a recursive descent segment for a single key.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of all values matching the descent key.
+     */
+    private segmentDescent(
+        current: unknown,
+        segments: ReadonlyArray<Segment>,
+        index: number,
+        defaultValue: unknown,
+        maxDepth: number,
+    ): unknown[] {
+        const results: unknown[] = [];
+        const segment = segments[index] as { type: SegmentType.Descent; key: string };
+        const descentKey = segment.key;
+        this.collectDescent(
+            current,
+            descentKey,
+            segments,
+            index + 1,
+            defaultValue,
+            results,
+            maxDepth,
+        );
+        return results;
+    }
+
+    /**
+     * Resolve a recursive descent segment for multiple keys.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of all values matching any of the descent keys.
+     */
+    private segmentDescentMulti(
+        current: unknown,
+        segments: ReadonlyArray<Segment>,
+        index: number,
+        defaultValue: unknown,
+        maxDepth: number,
+    ): unknown {
+        const segment = segments[index] as {
+            type: SegmentType.DescentMulti;
+            keys: ReadonlyArray<string>;
+        };
+        const descentKeys = segment.keys;
+        const results: unknown[] = [];
+
+        for (const dk of descentKeys) {
+            this.collectDescent(current, dk, segments, index + 1, defaultValue, results, maxDepth);
+        }
+
+        return results.length > 0 ? results : defaultValue;
+    }
+
+    /**
+     * Resolve a wildcard segment, expanding all children.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of resolved values for all children.
+     */
+    private segmentWildcard(
+        current: unknown,
+        segments: ReadonlyArray<Segment>,
+        index: number,
+        defaultValue: unknown,
+        maxDepth: number,
+    ): unknown {
+        if (typeof current !== 'object' || current === null) {
+            return defaultValue;
+        }
+
+        const items = Array.isArray(current)
+            ? current
+            : Object.values(current as Record<string, unknown>);
+
+        const nextIndex = index + 1;
+
+        return items.map((item) => this.resolve(item, segments, nextIndex, defaultValue, maxDepth));
+    }
+
+    /**
+     * Resolve a filter segment, applying predicates to array items.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of items passing the filter predicate.
+     */
+    private segmentFilter(
+        current: unknown,
+        segments: ReadonlyArray<Segment>,
+        index: number,
+        defaultValue: unknown,
+        maxDepth: number,
+    ): unknown {
+        if (typeof current !== 'object' || current === null) {
+            return defaultValue;
+        }
+
+        const segment = segments[index] as {
+            type: SegmentType.Filter;
+            expression: FilterExpression;
+        };
+        const filterExpr = segment.expression;
+
+        const items = Array.isArray(current)
+            ? current
+            : Object.values(current as Record<string, unknown>);
+
+        const filtered: unknown[] = [];
+        for (const item of items) {
+            if (typeof item === 'object' && item !== null) {
+                if (
+                    this.segmentFilterParser.evaluate(item as Record<string, unknown>, filterExpr)
+                ) {
+                    filtered.push(item);
+                }
+            }
+        }
+
+        const nextIndex = index + 1;
+
+        return filtered.map((item) =>
+            this.resolve(item, segments, nextIndex, defaultValue, maxDepth),
+        );
+    }
+
+    /**
+     * Resolve a multi-key segment, selecting values by multiple keys.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of resolved values for each key.
+     */
+    private segmentMultiKey(
+        current: unknown,
+        segments: ReadonlyArray<Segment>,
+        index: number,
+        defaultValue: unknown,
+        maxDepth: number,
+    ): unknown {
+        if (typeof current !== 'object' || current === null) {
+            return defaultValue;
+        }
+
+        const nextIndex = index + 1;
+        const segment = segments[index] as {
+            type: SegmentType.MultiKey;
+            keys: ReadonlyArray<string>;
+        };
+        const multiKeys = segment.keys;
+        const obj = current as Record<string, unknown>;
+
+        return multiKeys.map((k) => {
+            const val = Object.prototype.hasOwnProperty.call(obj, k) ? obj[k] : defaultValue;
+            return this.resolve(val, segments, nextIndex, defaultValue, maxDepth);
+        });
+    }
+
+    /**
+     * Resolve a multi-index segment, selecting values by multiple indices.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of resolved values for each index.
+     */
+    private segmentMultiIndex(
+        current: unknown,
+        segments: ReadonlyArray<Segment>,
+        index: number,
+        defaultValue: unknown,
+        maxDepth: number,
+    ): unknown {
+        if (typeof current !== 'object' || current === null) {
+            return defaultValue;
+        }
+
+        const nextIndex = index + 1;
+        const segment = segments[index] as {
+            type: SegmentType.MultiIndex;
+            indices: ReadonlyArray<number>;
+        };
+        const indices = segment.indices;
+        const items = Array.isArray(current)
+            ? current
+            : Object.values(current as Record<string, unknown>);
+        const len = items.length;
+
+        return indices.map((idx) => {
+            const resolved = idx < 0 ? (items[len + idx] ?? null) : (items[idx] ?? null);
+            if (resolved === null) {
+                return defaultValue;
+            }
+            return this.resolve(resolved, segments, nextIndex, defaultValue, maxDepth);
+        });
+    }
+
+    /**
+     * Resolve a slice segment on an array (start:end:step).
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of resolved values matching the slice range.
+     */
+    private segmentSlice(
+        current: unknown,
+        segments: ReadonlyArray<Segment>,
+        index: number,
+        defaultValue: unknown,
+        maxDepth: number,
+    ): unknown {
+        if (typeof current !== 'object' || current === null) {
+            return defaultValue;
+        }
+
+        const items = Array.isArray(current)
+            ? current
+            : Object.values(current as Record<string, unknown>);
+        const len = items.length;
+        const segment = segments[index] as {
+            type: SegmentType.Slice;
+            start: number | null;
+            end: number | null;
+            step: number | null;
+        };
+        const step = segment.step ?? 1;
+        let start = segment.start ?? (step > 0 ? 0 : len - 1);
+        let end = segment.end ?? (step > 0 ? len : -len - 1);
+
+        if (start < 0) {
+            start = Math.max(len + start, 0);
+        }
+
+        if (end < 0) {
+            end = len + end;
+        }
+
+        if (start >= len) {
+            start = len;
+        }
+
+        if (end > len) {
+            end = len;
+        }
+
+        const sliced: unknown[] = [];
+        if (step > 0) {
+            for (let si = start; si < end; si += step) {
+                sliced.push(items[si]);
+            }
+        } else {
+            for (let si = start; si > end; si += step) {
+                sliced.push(items[si]);
+            }
+        }
+
+        const nextSliceIndex = index + 1;
+
+        return sliced.map((item) =>
+            this.resolve(item, segments, nextSliceIndex, defaultValue, maxDepth),
+        );
+    }
+
+    /**
+     * Resolve a projection segment, selecting specific fields from items.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Projected item(s) with only the specified fields.
+     */
+    private segmentProjection(
+        current: unknown,
+        segments: ReadonlyArray<Segment>,
+        index: number,
+        defaultValue: unknown,
+        maxDepth: number,
+    ): unknown {
+        const segment = segments[index] as {
+            type: SegmentType.Projection;
+            fields: ReadonlyArray<ProjectionField>;
+        };
+        const fields = segment.fields;
+
+        const projectItem = (item: unknown): Record<string, unknown> => {
+            if (typeof item !== 'object' || item === null) {
+                const result: Record<string, unknown> = {};
+                for (const field of fields) {
+                    result[field.alias] = null;
+                }
+                return result;
+            }
+
+            const obj = item as Record<string, unknown>;
+            const result: Record<string, unknown> = {};
+            for (const field of fields) {
+                result[field.alias] = Object.prototype.hasOwnProperty.call(obj, field.source)
+                    ? obj[field.source]
+                    : null;
+            }
+            return result;
+        };
+
+        const nextProjectionIndex = index + 1;
+
+        if (Array.isArray(current)) {
+            const projected = current.map(projectItem);
+            return projected.map((item) =>
+                this.resolve(item, segments, nextProjectionIndex, defaultValue, maxDepth),
+            );
+        }
+
+        if (typeof current === 'object' && current !== null) {
+            const result = projectItem(current);
+            return this.resolve(result, segments, nextProjectionIndex, defaultValue, maxDepth);
+        }
+
+        return defaultValue;
+    }
+
+    /**
+     * Recursively collect values matching a descent key from nested data.
+     *
+     * @param current - Current data node.
+     * @param key - Key to search for recursively.
+     * @param segments - Typed segment array.
+     * @param nextIndex - Next segment index after the descent.
+     * @param defaultValue - Fallback value.
+     * @param results - Collector array (mutated in place).
+     * @param maxDepth - Maximum recursion depth.
+     */
+    private collectDescent(
+        current: unknown,
+        key: string,
+        segments: ReadonlyArray<Segment>,
+        nextIndex: number,
+        defaultValue: unknown,
+        results: unknown[],
+        maxDepth: number,
+    ): void {
+        if (typeof current !== 'object' || current === null) {
+            return;
+        }
+
+        const obj = current as Record<string, unknown>;
+
+        if (Object.prototype.hasOwnProperty.call(obj, key)) {
+            if (nextIndex >= segments.length) {
+                results.push(obj[key]);
+            } else {
+                const resolved = this.resolve(
+                    obj[key],
+                    segments,
+                    nextIndex,
+                    defaultValue,
+                    maxDepth,
+                );
+                if (Array.isArray(resolved)) {
+                    results.push(...resolved);
+                } else {
+                    results.push(resolved);
+                }
+            }
+        }
+
+        for (const child of Object.values(obj)) {
+            if (typeof child === 'object' && child !== null) {
+                this.collectDescent(
+                    child,
+                    key,
+                    segments,
+                    nextIndex,
+                    defaultValue,
+                    results,
+                    maxDepth,
+                );
+            }
+        }
+    }
+}

package/src/path-query/segment-type.ts

@@ -0,0 +1,82 @@
+/**
+ * Enumerate all segment types produced by the path parser.
+ *
+ * Each case represents a distinct addressing mode within a dot-notation
+ * path expression. The {@link SegmentPathResolver} dispatches resolution
+ * logic based on the segment type.
+ *
+ * @internal
+ *
+ * @see SegmentParser        Parses path strings into typed segment arrays.
+ * @see SegmentPathResolver  Resolves data values from typed segments.
+ */
+export enum SegmentType {
+    /** Simple key or index access (e.g. `foo`, `0`). */
+    Key = 'key',
+
+    /** Numeric index access (e.g. `[0]`). */
+    Index = 'index',
+
+    /** Wildcard expansion over all children (e.g. `*`, `[*]`). */
+    Wildcard = 'wildcard',
+
+    /** Recursive descent into a single key (e.g. `..name`). */
+    Descent = 'descent',
+
+    /** Recursive descent into multiple keys (e.g. `..["a","b"]`). */
+    DescentMulti = 'descent-multi',
+
+    /** Multi-index selection (e.g. `[0,1,2]`). */
+    MultiIndex = 'multi-index',
+
+    /** Multi-key selection (e.g. `['a','b']`). */
+    MultiKey = 'multi-key',
+
+    /** Filter predicate expression (e.g. `[?age>18]`). */
+    Filter = 'filter',
+
+    /** Array slice notation (e.g. `[0:5]`, `[::2]`). */
+    Slice = 'slice',
+
+    /** Field projection (e.g. `.{name, age}`). */
+    Projection = 'projection',
+}
+
+/** Parsed filter expression structure. */
+export interface FilterExpression {
+    readonly conditions: ReadonlyArray<FilterCondition>;
+    readonly logicals: ReadonlyArray<string>;
+}
+
+/** A single parsed filter condition. */
+export interface FilterCondition {
+    readonly field: string;
+    readonly operator: string;
+    readonly value: boolean | null | number | string;
+    readonly func?: string;
+    readonly funcArgs?: ReadonlyArray<string>;
+}
+
+/** Projection field mapping. */
+export interface ProjectionField {
+    readonly alias: string;
+    readonly source: string;
+}
+
+/** Discriminated union of all possible segment shapes. */
+export type Segment =
+    | { readonly type: SegmentType.Key; readonly value: string }
+    | { readonly type: SegmentType.Index; readonly value: string }
+    | { readonly type: SegmentType.Wildcard }
+    | { readonly type: SegmentType.Descent; readonly key: string }
+    | { readonly type: SegmentType.DescentMulti; readonly keys: ReadonlyArray<string> }
+    | { readonly type: SegmentType.MultiIndex; readonly indices: ReadonlyArray<number> }
+    | { readonly type: SegmentType.MultiKey; readonly keys: ReadonlyArray<string> }
+    | { readonly type: SegmentType.Filter; readonly expression: FilterExpression }
+    | {
+          readonly type: SegmentType.Slice;
+          readonly start: number | null;
+          readonly end: number | null;
+          readonly step: number | null;
+      }
+    | { readonly type: SegmentType.Projection; readonly fields: ReadonlyArray<ProjectionField> };

package/src/security/forbidden-keys.ts

@@ -5,7 +5,7 @@
  * 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
+ * `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
@@ -38,7 +38,7 @@ export const STREAM_WRAPPER_PREFIXES: readonly string[] = [
  * – `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
+ * 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
@@ -53,13 +53,13 @@ export const DEFAULT_FORBIDDEN_KEYS: ReadonlySet<string> = new Set([
     '__definesetter__',
     '__lookupgetter__',
     '__lookupsetter__',
-    // Object.prototype shadow key — overriding it can break hasOwnProperty-based guards
+    // 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
+    // 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.
+    // 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://',

package/src/security/security-guard.ts

@@ -18,6 +18,8 @@ import { DEFAULT_FORBIDDEN_KEYS, STREAM_WRAPPER_PREFIXES } from './forbidden-key
  * 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.
  *
+ * @api
+ *
  * @example
  * const guard = new SecurityGuard();
  * guard.assertSafeKey('name'); // OK
@@ -26,6 +28,8 @@ import { DEFAULT_FORBIDDEN_KEYS, STREAM_WRAPPER_PREFIXES } from './forbidden-key
 export class SecurityGuard implements SecurityGuardInterface {
     readonly maxDepth: number;
 
+    readonly extraForbiddenKeys: ReadonlyArray<string>;
+
     private readonly forbiddenKeysMap: ReadonlySet<string>;
 
     /**
@@ -34,8 +38,12 @@ export class SecurityGuard implements SecurityGuardInterface {
      * @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[] = []) {
+    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;
+        this.extraForbiddenKeys = [...extraForbiddenKeys];
 
         /* Stryker disable next-line ConditionalExpression -- equivalent: if (false) still produces the same forbiddenKeysMap for empty arrays since Set(DEFAULT)=DEFAULT */
         if (extraForbiddenKeys.length === 0) {
@@ -64,7 +72,7 @@ export class SecurityGuard implements SecurityGuardInterface {
      * guard.isForbiddenKey('name');      // false
      */
     isForbiddenKey(key: string): boolean {
-        // Normalise __* keys to lowercase — catches case variants such as __PROTO__.
+        // Normalise __* keys to lowercase - catches case variants such as __PROTO__.
         const lookupKey = key.startsWith('__') ? key.toLowerCase() : key;
 
         if (this.forbiddenKeysMap.has(lookupKey)) {