@mlx-node/trl 0.0.0

package/dist/utils/path-security.js

@@ -0,0 +1,69 @@
+/**
+ * Path security utilities to prevent directory traversal attacks.
+ *
+ * These utilities ensure that user-provided paths stay within allowed directories,
+ * preventing malicious paths like `../../../etc/` from accessing arbitrary files.
+ */
+import { resolve as resolvePath, normalize, relative, isAbsolute } from 'node:path';
+/**
+ * Error thrown when a path traversal attempt is detected.
+ */
+export class PathTraversalError extends Error {
+    resolvedPath;
+    allowedRoot;
+    constructor(resolvedPath, allowedRoot) {
+        super(`Path traversal detected: "${resolvedPath}" is outside allowed directory "${allowedRoot}"`);
+        this.resolvedPath = resolvedPath;
+        this.allowedRoot = allowedRoot;
+        this.name = 'PathTraversalError';
+    }
+}
+/**
+ * Validates that a resolved path is contained within an allowed root directory.
+ * Prevents path traversal attacks via '../' sequences.
+ *
+ * @param resolvedPath - The fully resolved absolute path to validate
+ * @param allowedRoot - The root directory that paths must be contained within
+ * @throws PathTraversalError if path escapes the allowed root
+ */
+export function validatePathContainment(resolvedPath, allowedRoot) {
+    const normalizedPath = normalize(resolvedPath);
+    const normalizedRoot = normalize(allowedRoot);
+    // Get relative path from root to target
+    const relativePath = relative(normalizedRoot, normalizedPath);
+    // If relative path starts with '..' or is absolute, it's outside the root
+    if (relativePath.startsWith('..') || isAbsolute(relativePath)) {
+        throw new PathTraversalError(resolvedPath, allowedRoot);
+    }
+}
+/**
+ * Resolves a user-provided path and validates it stays within an allowed root.
+ *
+ * @param userPath - The user-provided path (may be relative or absolute)
+ * @param allowedRoot - The root directory that the path must be contained within
+ * @returns The resolved absolute path
+ * @throws PathTraversalError if the resolved path escapes the allowed root
+ */
+export function resolveAndValidatePath(userPath, allowedRoot) {
+    const resolved = resolvePath(allowedRoot, userPath);
+    validatePathContainment(resolved, allowedRoot);
+    return resolved;
+}
+/**
+ * Get the allowed root directory from options or environment.
+ * Checks MLX_NODE_DATA_ROOT environment variable first, then falls back to cwd.
+ *
+ * @param options - Optional validation options
+ * @returns The allowed root directory path
+ */
+export function getAllowedRoot(options) {
+    if (options?.allowedRoot) {
+        return options.allowedRoot;
+    }
+    // Check environment variable for configurable data root
+    const envRoot = process.env['MLX_NODE_DATA_ROOT'];
+    if (envRoot) {
+        return resolvePath(envRoot);
+    }
+    return process.cwd();
+}

package/dist/utils/xml-parser.d.ts

@@ -0,0 +1,6 @@
+import { type XmlParseResult } from '../types';
+export declare function parseXmlCot(content: string): XmlParseResult;
+export declare function extractXmlAnswer(content: string): string | null;
+export declare function extractXmlReasoning(content: string): string | null;
+export declare function extractHashAnswer(text: string): string | null;
+//# sourceMappingURL=xml-parser.d.ts.map

package/dist/utils/xml-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml-parser.d.ts","sourceRoot":"","sources":["../../src/utils/xml-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AA4B/C,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAkK3D;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG/D;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGlE;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM7D"}

package/dist/utils/xml-parser.js

@@ -0,0 +1,184 @@
+const REASONING_OPEN = '<reasoning>';
+const REASONING_CLOSE = '</reasoning>';
+const ANSWER_OPEN = '<answer>';
+const ANSWER_CLOSE = '</answer>';
+function isWhitespace(char) {
+    return char === ' ' || char === '\n' || char === '\r' || char === '\t' || char === '\f' || char === '\v';
+}
+function sliceWithTag(text, openTag, closeTag) {
+    const openIndex = text.indexOf(openTag);
+    if (openIndex === -1)
+        return null;
+    const start = openIndex + openTag.length;
+    const closeIndex = text.indexOf(closeTag, start);
+    if (closeIndex === -1)
+        return null;
+    return text.slice(start, closeIndex).trim();
+}
+export function parseXmlCot(content) {
+    const text = content ?? '';
+    const errors = [];
+    let state = 'searchReasoningOpen';
+    let index = 0;
+    const length = text.length;
+    let reasoning = null;
+    let answer = null;
+    let reasoningFound = false;
+    let answerFound = false;
+    let reasoningClosed = false;
+    let answerClosed = false;
+    let hasLeadingText = false;
+    let hasBetweenText = false;
+    let hasTrailingText = false;
+    let usedFallbackReasoning = false;
+    let usedFallbackAnswer = false;
+    while (state !== 'done') {
+        switch (state) {
+            case 'searchReasoningOpen': {
+                while (index < length) {
+                    const char = text[index];
+                    if (isWhitespace(char)) {
+                        index += 1;
+                        continue;
+                    }
+                    if (text.startsWith(REASONING_OPEN, index)) {
+                        reasoningFound = true;
+                        index += REASONING_OPEN.length;
+                        state = 'readReasoning';
+                        break;
+                    }
+                    hasLeadingText = true;
+                    index += 1;
+                }
+                if (state === 'searchReasoningOpen') {
+                    state = 'done';
+                }
+                break;
+            }
+            case 'readReasoning': {
+                const closingIndex = text.indexOf(REASONING_CLOSE, index);
+                if (closingIndex === -1) {
+                    reasoning = text.slice(index).trim() || null;
+                    errors.push('Unterminated <reasoning>...</reasoning> section.');
+                    state = 'done';
+                    break;
+                }
+                reasoning = text.slice(index, closingIndex).trim();
+                reasoningClosed = true;
+                index = closingIndex + REASONING_CLOSE.length;
+                state = 'searchAnswerOpen';
+                break;
+            }
+            case 'searchAnswerOpen': {
+                while (index < length) {
+                    const char = text[index];
+                    if (isWhitespace(char)) {
+                        index += 1;
+                        continue;
+                    }
+                    if (text.startsWith(ANSWER_OPEN, index)) {
+                        answerFound = true;
+                        index += ANSWER_OPEN.length;
+                        state = 'readAnswer';
+                        break;
+                    }
+                    hasBetweenText = true;
+                    index += 1;
+                }
+                if (state === 'searchAnswerOpen') {
+                    state = 'done';
+                }
+                break;
+            }
+            case 'readAnswer': {
+                const closingIndex = text.indexOf(ANSWER_CLOSE, index);
+                if (closingIndex === -1) {
+                    answer = text.slice(index).trim() || null;
+                    errors.push('Unterminated <answer>...</answer> section.');
+                    state = 'done';
+                    break;
+                }
+                answer = text.slice(index, closingIndex).trim();
+                answerClosed = true;
+                index = closingIndex + ANSWER_CLOSE.length;
+                state = 'consumeTrailing';
+                break;
+            }
+            case 'consumeTrailing': {
+                while (index < length) {
+                    const char = text[index];
+                    if (!isWhitespace(char)) {
+                        hasTrailingText = true;
+                    }
+                    index += 1;
+                }
+                state = 'done';
+                break;
+            }
+        }
+    }
+    if (!reasoningFound) {
+        const fallback = sliceWithTag(text, REASONING_OPEN, REASONING_CLOSE);
+        if (fallback !== null) {
+            reasoning = fallback;
+            reasoningFound = true;
+            reasoningClosed = true;
+            usedFallbackReasoning = true;
+        }
+    }
+    if (!answerFound) {
+        const fallback = sliceWithTag(text, ANSWER_OPEN, ANSWER_CLOSE);
+        if (fallback !== null) {
+            answer = fallback;
+            answerFound = true;
+            answerClosed = true;
+            usedFallbackAnswer = true;
+        }
+    }
+    if (!reasoningFound) {
+        errors.push('Missing <reasoning>...</reasoning> section.');
+    }
+    if (!answerFound) {
+        errors.push('Missing <answer>...</answer> section.');
+    }
+    if (hasLeadingText) {
+        errors.push('XML format contains extra characters before <reasoning> section.');
+    }
+    if (hasBetweenText) {
+        errors.push('XML format contains extra characters between reasoning and answer sections.');
+    }
+    if (hasTrailingText) {
+        errors.push('XML format contains extra characters after </answer> section.');
+    }
+    const isSoftMatch = reasoningFound && answerFound && reasoningClosed && answerClosed;
+    const isStrictMatch = isSoftMatch &&
+        !hasLeadingText &&
+        !hasBetweenText &&
+        !hasTrailingText &&
+        !usedFallbackReasoning &&
+        !usedFallbackAnswer;
+    return {
+        reasoning: reasoning ?? null,
+        answer: answer ?? null,
+        isStrictMatch,
+        isSoftMatch,
+        errors,
+    };
+}
+export function extractXmlAnswer(content) {
+    const { answer } = parseXmlCot(content);
+    return answer;
+}
+export function extractXmlReasoning(content) {
+    const { reasoning } = parseXmlCot(content);
+    return reasoning;
+}
+export function extractHashAnswer(text) {
+    if (!text)
+        return null;
+    const separator = text.indexOf('####');
+    if (separator === -1)
+        return null;
+    const extracted = text.slice(separator + 4).trim();
+    return extracted.length ? extracted : null;
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@mlx-node/trl",
+  "version": "0.0.0",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vite test run",
+    "test:trainer": "TEST_TRAINER=1 vite test run"
+  },
+  "dependencies": {
+    "@mlx-node/core": "0.0.0",
+    "@mlx-node/lm": "0.0.0",
+    "@std/toml": "npm:@jsr/std__toml@^1.0.11"
+  },
+  "devDependencies": {
+    "@huggingface/hub": "^2.7.1"
+  }
+}