@safeaccess/inline 0.1.1

package/src/parser/xml-parser.ts

@@ -0,0 +1,334 @@
+import { InvalidFormatException } from '../exceptions/invalid-format-exception.js';
+import { SecurityException } from '../exceptions/security-exception.js';
+
+/**
+ * Internal XML-to-object parser for XmlAccessor.
+ *
+ * Provides both a browser path (DOMParser) and a minimal manual parser
+ * for Node.js environments. Does not depend on external XML libraries.
+ *
+ * @internal
+ */
+export class XmlParser {
+    private readonly maxDepth: number;
+    private readonly maxElements: number;
+
+    /**
+     * @param maxDepth - Maximum structural depth allowed.
+     * @param maxElements - Maximum number of opening-tag occurrences allowed in the
+     *   Node.js manual-parser path before parsing is aborted. Acts as a complexity
+     *   bound and defence-in-depth against document-bombing. Defaults to 10 000
+     *   (matches `SecurityParser.maxKeys`). Non-positive, non-finite, or `NaN` values
+     *   are clamped to 10 000 to prevent accidental guard disablement.
+     */
+    constructor(maxDepth: number, maxElements: number = 10_000) {
+        this.maxDepth = maxDepth;
+        this.maxElements = Number.isFinite(maxElements) && maxElements >= 1
+            ? maxElements
+            : 10_000;
+    }
+
+    /**
+     * Parse an XML body into a plain object using the best available parser.
+     *
+     * @param xml - Raw XML content (must not contain DOCTYPE).
+     * @returns Parsed data structure.
+     * @throws {InvalidFormatException} When XML is malformed.
+     * @throws {SecurityException} When structural depth exceeds limit.
+     *
+     * @example
+     * new XmlParser(10).parse('<root><key>value</key></root>'); // { key: 'value' }
+     */
+    parse(xml: string): Record<string, unknown> {
+        if (typeof DOMParser !== 'undefined') {
+            return this.parseBrowserXml(xml);
+        }
+
+        return this.parseXmlManual(xml);
+    }
+
+    private parseBrowserXml(xml: string): Record<string, unknown> {
+        const parser = new DOMParser();
+        const doc = parser.parseFromString(xml, 'application/xml');
+
+        const parserError = doc.querySelector('parsererror');
+        if (parserError !== null) {
+            throw new InvalidFormatException(
+                `XmlAccessor failed to parse XML: ${parserError.textContent ?? 'Unknown error'}`,
+            );
+        }
+
+        const root = doc.documentElement;
+        if (root === null) {
+            return {};
+        }
+
+        return this.elementToRecord(root, 0);
+    }
+
+    private elementToRecord(element: Element, depth: number): Record<string, unknown> {
+        if (depth > this.maxDepth) {
+            throw new SecurityException(
+                `XML structural depth ${depth} exceeds maximum of ${this.maxDepth}.`,
+            );
+        }
+
+        const result: Record<string, unknown> = {};
+
+        for (const attr of Array.from(element.attributes)) {
+            if (attr !== undefined) {
+                result[`@${attr.name}`] = attr.value;
+            }
+        }
+
+        for (const child of Array.from(element.childNodes)) {
+            if (child === undefined) continue;
+
+            if (child.nodeType === 3) {
+                const text = child.textContent?.trim() ?? '';
+                if (text !== '') {
+                    result['#text'] = text;
+                }
+            } else if (child.nodeType === 1) {
+                const childEl = child as Element;
+                const name = childEl.nodeName;
+                const childData = this.elementToRecord(childEl, depth + 1);
+
+                if (Object.prototype.hasOwnProperty.call(result, name)) {
+                    const existing = result[name];
+                    if (Array.isArray(existing)) {
+                        existing.push(childData);
+                    } else {
+                        result[name] = [existing, childData];
+                    }
+                } else {
+                    result[name] = childData;
+                }
+            }
+        }
+
+        return result;
+    }
+
+    private parseXmlManual(xml: string): Record<string, unknown> {
+        const stripped = xml.replace(/<\?xml[^?]*\?>/i, '').trim();
+
+        // Bound parser complexity before the linear inner-content scan: count opening
+        // tags as a document-complexity proxy. This is a defence-in-depth limit —
+        // the linear scanner below is already O(n), but bounding element count also
+        // caps the total number of recursive parseXmlChildren calls.
+        // Browser environments (DOMParser) are unaffected.
+        const elementCount = (stripped.match(/<[a-zA-Z_]/g) ?? []).length;
+        if (elementCount > this.maxElements) {
+            throw new SecurityException(
+                `XML element count ${elementCount} exceeds maximum of ${this.maxElements}.`,
+            );
+        }
+
+        return this.extractRootContent(stripped);
+    }
+
+    /**
+     * Extract root element inner content using an indexOf-based O(n) scan.
+     *
+     * Replaces the previous backreference regex to guarantee O(n) time regardless
+     * of document structure. The closing-tag match is verified by scanning
+     * backwards from the final `>` character of the trimmed document.
+     */
+    private extractRootContent(doc: string): Record<string, unknown> {
+        if (doc.length < 2 || doc[0] !== '<' || !/[a-zA-Z_]/.test(doc[1] as string)) {
+            throw new InvalidFormatException('XmlAccessor failed to parse XML string.');
+        }
+
+        // Scan root tag name: [a-zA-Z_][\w.-]*
+        let nameEnd = 2;
+        while (nameEnd < doc.length && /[\w.-]/.test(doc[nameEnd] as string)) {
+            nameEnd++;
+        }
+        const tagName = doc.slice(1, nameEnd);
+
+        // Locate the '>' that closes the root opening tag (attributes may not contain '>').
+        const openGt = doc.indexOf('>', nameEnd);
+        if (openGt === -1) {
+            throw new InvalidFormatException('XmlAccessor failed to parse XML string.');
+        }
+
+        // Self-closing element: opening tag body ends with '/'.
+        if (doc.slice(nameEnd, openGt).trimEnd().endsWith('/')) {
+            // Self-closing tag must occupy the whole document.
+            if (openGt !== doc.length - 1) {
+                throw new InvalidFormatException('XmlAccessor failed to parse XML string.');
+            }
+            return {};
+        }
+
+        // The trimmed document must end with '>'.
+        if (doc[doc.length - 1] !== '>') {
+            throw new InvalidFormatException('XmlAccessor failed to parse XML string.');
+        }
+
+        // Walk backward from the final '>' to locate the closing tag for this root element.
+        // This is O(tagNameLen) — the tag name is typically short and always bounded.
+        let pos = doc.length - 2;
+        while (pos >= 0 && (doc[pos] === ' ' || doc[pos] === '\t' || doc[pos] === '\n' || doc[pos] === '\r')) {
+            pos--;
+        }
+
+        // pos must point to the last char of the root tag name.
+        const nameStart = pos - tagName.length + 1;
+        if (nameStart < 2 || doc.slice(nameStart, pos + 1) !== tagName) {
+            throw new InvalidFormatException('XmlAccessor failed to parse XML string.');
+        }
+
+        // The two chars before the tag name must be '</'.
+        if (doc[nameStart - 1] !== '/' || doc[nameStart - 2] !== '<') {
+            throw new InvalidFormatException('XmlAccessor failed to parse XML string.');
+        }
+
+        const closeTagStart = nameStart - 2;
+        if (closeTagStart <= openGt) {
+            throw new InvalidFormatException('XmlAccessor failed to parse XML string.');
+        }
+
+        const innerContent = doc.slice(openGt + 1, closeTagStart);
+        return this.parseXmlChildren(innerContent, 0);
+    }
+
+    private parseXmlChildren(content: string, depth: number): Record<string, unknown> {
+        if (depth > this.maxDepth) {
+            throw new SecurityException(
+                `XML structural depth ${depth} exceeds maximum of ${this.maxDepth}.`,
+            );
+        }
+
+        const result: Record<string, unknown> = {};
+        let i = 0;
+        let hasElements = false;
+
+        while (i < content.length) {
+            const lt = content.indexOf('<', i);
+            if (lt === -1) break;
+
+            const nextChar = content[lt + 1];
+            if (nextChar === undefined) break;
+
+            // Skip closing tags, comments, and processing instructions
+            if (nextChar === '/' || nextChar === '!' || nextChar === '?') {
+                const gt = content.indexOf('>', lt);
+                i = gt === -1 ? content.length : gt + 1;
+                continue;
+            }
+
+            // Tag name must start with a valid XML name-start character
+            if (!/[a-zA-Z_]/.test(nextChar)) {
+                i = lt + 1;
+                continue;
+            }
+
+            // Extract tag name: [a-zA-Z_][\w.-]*
+            let nameEnd = lt + 2;
+            while (nameEnd < content.length && /[\w.-]/.test(content[nameEnd] as string)) {
+                nameEnd++;
+            }
+            const tagName = content.slice(lt + 1, nameEnd);
+
+            const gt = content.indexOf('>', nameEnd);
+            if (gt === -1) break;
+
+            // Self-closing tag e.g. <tag/> or <tag attr="v"/>
+            if (content.slice(nameEnd, gt).trimEnd().endsWith('/')) {
+                hasElements = true;
+                this.addChild(result, tagName, '');
+                i = gt + 1;
+                continue;
+            }
+
+            // Locate the matching closing </tagName> using a nesting counter.
+            // This avoids regex backreferences and runs in O(n) time.
+            const closeTag = `</${tagName}`;
+            const openPrefix = `<${tagName}`;
+            let nestDepth = 1;
+            let pos = gt + 1;
+            let innerEnd = -1;
+            let afterClose = content.length;
+
+            while (pos < content.length && nestDepth > 0) {
+                const nextLt = content.indexOf('<', pos);
+                if (nextLt === -1) break;
+
+                if (content.startsWith(closeTag, nextLt)) {
+                    const c = content[nextLt + closeTag.length];
+                    if (c === '>' || c === ' ' || c === '\t' || c === '\n' || c === '\r' || c === undefined) {
+                        nestDepth--;
+                        if (nestDepth === 0) {
+                            innerEnd = nextLt;
+                            const cgt = content.indexOf('>', nextLt + closeTag.length);
+                            afterClose = cgt === -1 ? content.length : cgt + 1;
+                            break;
+                        }
+                        pos = nextLt + closeTag.length;
+                        continue;
+                    }
+                }
+
+                if (content.startsWith(openPrefix, nextLt)) {
+                    const c = content[nextLt + openPrefix.length];
+                    if (c === '>' || c === ' ' || c === '\t' || c === '\n' || c === '\r' || c === '/') {
+                        const ogt = content.indexOf('>', nextLt + openPrefix.length);
+                        if (ogt !== -1 && !content.slice(nextLt + openPrefix.length, ogt).trimEnd().endsWith('/')) {
+                            nestDepth++;
+                        }
+                    }
+                }
+
+                pos = nextLt + 1;
+            }
+
+            if (innerEnd === -1) {
+                // Unclosed or malformed tag — skip past the opening tag
+                i = gt + 1;
+                continue;
+            }
+
+            const inner = content.slice(gt + 1, innerEnd);
+            const trimmedInner = inner.trim();
+            let value: unknown;
+
+            if (trimmedInner !== '' && /<[a-zA-Z]/.test(trimmedInner)) {
+                const childResult = this.parseXmlChildren(trimmedInner, depth + 1);
+                value =
+                    Object.keys(childResult).length === 1 && '#text' in childResult
+                        ? childResult['#text']
+                        : childResult;
+            } else {
+                value = trimmedInner;
+            }
+
+            hasElements = true;
+            this.addChild(result, tagName, value);
+            i = afterClose;
+        }
+
+        if (!hasElements) {
+            const text = content.trim();
+            if (text !== '') {
+                result['#text'] = text;
+            }
+        }
+
+        return result;
+    }
+
+    private addChild(result: Record<string, unknown>, tagName: string, value: unknown): void {
+        if (Object.prototype.hasOwnProperty.call(result, tagName)) {
+            const existing = result[tagName];
+            if (Array.isArray(existing)) {
+                existing.push(value);
+            } else {
+                result[tagName] = [existing, value];
+            }
+        } else {
+            result[tagName] = value;
+        }
+    }
+}

package/src/parser/yaml-parser.ts

@@ -0,0 +1,368 @@
+import { YamlParseException } from '../exceptions/yaml-parse-exception.js';
+
+/**
+ * Minimal YAML parser supporting a safe subset of YAML 1.2.
+ *
+ * Parses scalars, maps, sequences, and inline values. Blocks unsafe constructs:
+ * tags (!! and !), anchors (&), aliases (*), and merge keys (<<).
+ *
+ * Does not depend on external YAML libraries, making the package portable.
+ */
+export class YamlParser {
+    /**
+     * Parse a YAML string into a plain object.
+     *
+     * @param yaml - Raw YAML content.
+     * @returns Parsed data structure.
+     * @throws {YamlParseException} When unsafe constructs or syntax errors are found.
+     *
+     * @example
+     * new YamlParser().parse('key: value'); // { key: 'value' }
+     */
+    parse(yaml: string): Record<string, unknown> {
+        const lines = yaml.replace(/\r\n/g, '\n').split('\n');
+        this.assertNoUnsafeConstructs(lines);
+        const result = this.parseLines(lines, 0, 0, lines.length);
+        if (Array.isArray(result)) {
+            return {};
+        }
+        return result as Record<string, unknown>;
+    }
+
+    /**
+     * Reject YAML constructs that are unsafe or unsupported.
+     *
+     * @param lines - Raw YAML lines to scan.
+     * @throws {YamlParseException} When tags, anchors, aliases, or merge keys are found.
+     */
+    private assertNoUnsafeConstructs(lines: string[]): void {
+        for (const [i, rawLine] of lines.entries()) {
+            const trimmed = rawLine.trimStart();
+
+            if (trimmed === '' || trimmed.startsWith('#')) {
+                continue;
+            }
+
+            // Block !! and ! tags (but not inside quotes)
+            if (/(?<!['"!])!{1,2}[\w</]/.test(trimmed)) {
+                throw new YamlParseException(
+                    `Unsupported YAML tag at line ${i + 1}: tags (! and !! syntax) are not supported.`,
+                );
+            }
+
+            if (/(?:^|\s)&\w+/.test(trimmed)) {
+                throw new YamlParseException(`YAML anchors are not supported (line ${i + 1}).`);
+            }
+
+            if (/(?:^|\s)\*\w+/.test(trimmed)) {
+                throw new YamlParseException(`YAML aliases are not supported (line ${i + 1}).`);
+            }
+
+            if (/^(\s*)<<\s*:/.test(rawLine)) {
+                throw new YamlParseException(
+                    `YAML merge keys (<<) are not supported (line ${i + 1}).`,
+                );
+            }
+        }
+    }
+
+    /**
+     * Parse a range of lines into a YAML value (map, sequence, or scalar).
+     *
+     * @param lines - All lines of the YAML document.
+     * @param baseIndent - Indentation level for this block.
+     * @param start - First line index (inclusive).
+     * @param end - Last line index (exclusive).
+     * @returns Parsed value.
+     */
+    private parseLines(lines: string[], baseIndent: number, start: number, end: number): unknown {
+        const mapResult: Record<string, unknown> = {};
+        const arrResult: unknown[] = [];
+        let isSequence = false;
+        let i = start;
+
+        while (i < end) {
+            const line = lines[i] as string;
+            const trimmed = line.trimStart();
+
+            if (trimmed === '' || trimmed.startsWith('#')) {
+                i++;
+                continue;
+            }
+
+            const currentIndent = line.length - trimmed.length;
+
+            /* c8 ignore start */
+            if (currentIndent < baseIndent) {
+                break;
+            }
+            /* c8 ignore stop */
+
+            if (currentIndent > baseIndent) {
+                i++;
+                continue;
+            }
+
+            // Sequence item
+            if (trimmed.startsWith('- ') || trimmed === '-') {
+                isSequence = true;
+                const itemContent = trimmed === '-' ? '' : trimmed.slice(2).trim();
+
+                const match =
+                    itemContent !== '' ? /^([^\s:][^:]*?)\s*:\s*(.*)$/.exec(itemContent) : null;
+                if (match !== null) {
+                    const childIndent = currentIndent + 2;
+                    const childEnd = this.findBlockEnd(lines, childIndent, i + 1, end);
+                    const subMap: Record<string, unknown> = {};
+                    subMap[match[1] as string] = this.resolveValue(
+                        match[2] as string,
+                        lines,
+                        i,
+                        childIndent,
+                        childEnd,
+                    );
+                    this.mergeChildLines(lines, i + 1, childEnd, childIndent, subMap);
+                    arrResult.push(subMap);
+                    i = childEnd;
+                } else if (itemContent === '') {
+                    const childIndent = currentIndent + 2;
+                    const childEnd = this.findBlockEnd(lines, childIndent, i + 1, end);
+                    if (childEnd > i + 1) {
+                        arrResult.push(this.parseLines(lines, childIndent, i + 1, childEnd));
+                        i = childEnd;
+                    } else {
+                        arrResult.push(null);
+                        i++;
+                    }
+                } else {
+                    arrResult.push(this.castScalar(itemContent));
+                    i++;
+                }
+                continue;
+            }
+
+            // Map key: value
+            const mapMatch = /^([^\s:][^:]*?)\s*:\s*(.*)$/.exec(trimmed);
+            if (mapMatch !== null) {
+                const key = mapMatch[1] as string;
+                const rawValue = mapMatch[2] as string;
+                const childIndent = currentIndent + 2;
+                const childEnd = this.findBlockEnd(lines, childIndent, i + 1, end);
+                mapResult[key] = this.resolveValue(rawValue, lines, i, childIndent, childEnd);
+                i = childEnd;
+                continue;
+            }
+
+            i++;
+        }
+
+        if (isSequence) {
+            return arrResult;
+        }
+
+        return mapResult;
+    }
+
+    /**
+     * Merge child key-value lines into an existing map.
+     *
+     * @param lines - All lines of the YAML document.
+     * @param start - First child line index (inclusive).
+     * @param end - Last child line index (exclusive).
+     * @param childIndent - Expected indentation for child lines.
+     * @param map - Map to merge values into.
+     */
+    private mergeChildLines(
+        lines: string[],
+        start: number,
+        end: number,
+        childIndent: number,
+        map: Record<string, unknown>,
+    ): void {
+        let ci = start;
+        while (ci < end) {
+            const childLine = lines[ci] as string;
+            const childTrimmed = childLine.trimStart();
+
+            if (childTrimmed === '' || childTrimmed.startsWith('#')) {
+                ci++;
+                continue;
+            }
+
+            const childCurrentIndent = childLine.length - childTrimmed.length;
+
+            if (childCurrentIndent === childIndent) {
+                const cm = /^([^\s:][^:]*?)\s*:\s*(.*)$/.exec(childTrimmed);
+                if (cm !== null) {
+                    const nextChildEnd = this.findBlockEnd(
+                        lines,
+                        childCurrentIndent + 2,
+                        ci + 1,
+                        end,
+                    );
+                    map[cm[1] as string] = this.resolveValue(
+                        cm[2] as string,
+                        lines,
+                        ci,
+                        childCurrentIndent + 2,
+                        nextChildEnd,
+                    );
+                    ci = nextChildEnd;
+                    continue;
+                }
+            }
+
+            ci++;
+        }
+    }
+
+    /**
+     * Resolve a raw value string into a typed value.
+     *
+     * @param rawValue - The value portion after the colon.
+     * @param lines - All lines of the YAML document.
+     * @param lineIndex - Line where the value was found.
+     * @param childIndent - Expected indentation for child block.
+     * @param childEnd - End index of the child block.
+     * @returns Resolved typed value.
+     */
+    private resolveValue(
+        rawValue: string,
+        lines: string[],
+        lineIndex: number,
+        childIndent: number,
+        childEnd: number,
+    ): unknown {
+        const trimmed = rawValue.trim();
+
+        // Block scalar literal (|) or folded (>)
+        if (trimmed === '|' || trimmed === '>') {
+            return this.parseBlockScalar(
+                lines,
+                lineIndex + 1,
+                childEnd,
+                childIndent,
+                trimmed === '>',
+            );
+        }
+
+        // Inline flow (array or map) starting with [ or {
+        if (trimmed.startsWith('[') || trimmed.startsWith('{')) {
+            return this.parseInlineFlow(trimmed);
+        }
+
+        // Nested block
+        if (trimmed === '' && childEnd > lineIndex + 1) {
+            return this.parseLines(lines, childIndent, lineIndex + 1, childEnd);
+        }
+
+        return this.castScalar(trimmed);
+    }
+
+    /**
+     * Parse a YAML block scalar (literal | or folded >).
+     *
+     * @param lines - All lines of the YAML document.
+     * @param start - First line of the scalar block (inclusive).
+     * @param end - Last line of the scalar block (exclusive).
+     * @param indent - Minimum indentation for scalar lines.
+     * @param folded - Whether to fold lines (> style) or keep literal (| style).
+     * @returns The assembled string.
+     */
+    private parseBlockScalar(
+        lines: string[],
+        start: number,
+        end: number,
+        indent: number,
+        folded: boolean,
+    ): string {
+        const parts: string[] = [];
+        for (let i = start; i < end; i++) {
+            const line = lines[i] as string;
+            const trimmed = line.trimStart();
+            const lineIndent = line.length - trimmed.length;
+            if (lineIndent >= indent || trimmed === '') {
+                parts.push(trimmed);
+            }
+        }
+
+        if (folded) {
+            return parts.join(' ').trim();
+        }
+
+        return parts.join('\n').trimEnd();
+    }
+
+    /**
+     * Parse an inline flow collection (JSON-like array or object).
+     *
+     * @param raw - Raw inline flow string.
+     * @returns Parsed value or the raw string if parsing fails.
+     */
+    private parseInlineFlow(raw: string): unknown {
+        try {
+            // Convert YAML flow to JSON by single-quoting to double-quoting
+            const jsonLike = raw.replace(/'/g, '"').replace(/(\w+)\s*:/g, '"$1":');
+            return JSON.parse(jsonLike);
+        } catch {
+            // Fallback: return raw string
+            return raw;
+        }
+    }
+
+    /**
+     * Cast a scalar string to its native type.
+     *
+     * @param value - Raw scalar string.
+     * @returns Typed value (null, boolean, number, or string).
+     */
+    private castScalar(value: string): unknown {
+        if (value === '' || value === 'null' || value === '~') return null;
+        if (value === 'true') return true;
+        if (value === 'false') return false;
+
+        // Quoted string
+        if (
+            (value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))
+        ) {
+            return value.slice(1, -1);
+        }
+
+        // Integer
+        if (/^-?\d+$/.test(value)) return parseInt(value, 10);
+
+        // Float
+        if (/^-?\d+\.\d+$/.test(value)) return parseFloat(value);
+
+        return value;
+    }
+
+    /**
+     * Find where a child block ends based on indentation.
+     *
+     * @param lines - All lines of the YAML document.
+     * @param minIndent - Minimum indentation to remain in the block.
+     * @param start - First line to check (inclusive).
+     * @param end - Hard end boundary (exclusive).
+     * @returns Index of the first line outside the block.
+     */
+    private findBlockEnd(lines: string[], minIndent: number, start: number, end: number): number {
+        for (let i = start; i < end; i++) {
+            const line = lines[i] as string;
+            const trimmed = line.trimStart();
+
+            if (trimmed === '' || trimmed.startsWith('#')) {
+                continue;
+            }
+
+            const lineIndent = line.length - trimmed.length;
+
+            if (lineIndent < minIndent) {
+                return i;
+            }
+        }
+
+        return end;
+    }
+}