@oka-core/reason 0.2.15 → 0.2.16

package/dist/validation.js

@@ -0,0 +1,236 @@
+/**
+ * Input validation and path security — pure domain layer.
+ *
+ * ZERO external dependencies. Inspired by Claude Code's hardened
+ * validation patterns for MCP tool inputs.
+ *
+ * @module validation
+ */
+import { ValidationError, PathSecurityError, ContentTooLargeError, } from "./errors.js";
+// ─── Constants ──────────────────────────────────────────────────────
+/** Control characters to reject (excludes \t, \n, \r which are common whitespace). */
+const CONTROL_CHAR_RE = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/;
+/** URL-encoded traversal sequences (case-insensitive). */
+const URL_ENCODED_TRAVERSAL_RE = /(%2e%2e|%2f|%5c)/i;
+/** Dangerous device paths on Unix systems. */
+const BLOCKED_DEVICE_PREFIXES = ["/dev/", "/proc/self/fd/", "/sys/"];
+/** Exact blocked device paths. */
+const BLOCKED_DEVICE_EXACT = new Set([
+    "/dev/zero",
+    "/dev/null",
+    "/dev/stdin",
+    "/dev/stdout",
+    "/dev/stderr",
+    "/dev/random",
+    "/dev/urandom",
+    "/dev/tty",
+]);
+/** Filenames and directory names considered dangerous for write operations. */
+const DANGEROUS_FILES = new Set([
+    ".gitconfig",
+    ".git-credentials",
+    ".bashrc",
+    ".bash_profile",
+    ".bash_login",
+    ".profile",
+    ".zshrc",
+    ".zprofile",
+    ".zshenv",
+    ".env",
+    ".env.local",
+    ".env.production",
+    ".env.development",
+    "credentials.json",
+    "service-account.json",
+    ".mcp.json",
+    ".npmrc",
+    ".yarnrc",
+    ".pypirc",
+    "id_rsa",
+    "id_ed25519",
+    "id_ecdsa",
+    "id_dsa",
+    "known_hosts",
+    "authorized_keys",
+    "config",
+    ".netrc",
+    ".pgpass",
+    ".my.cnf",
+    ".docker/config.json",
+    "kubeconfig",
+    ".kube/config",
+]);
+/** Directory names that are dangerous to traverse into. */
+const DANGEROUS_DIRS = new Set([
+    ".ssh",
+    ".gnupg",
+    ".aws",
+    ".azure",
+    ".gcloud",
+    ".config",
+    ".docker",
+    ".kube",
+]);
+// ─── Input Validation ───────────────────────────────────────────────
+/**
+ * Validate and sanitize a free-text input string.
+ *
+ * Rejects null bytes, control characters (except \t, \n, \r),
+ * and inputs exceeding `maxLength`. Returns the trimmed string.
+ *
+ * @param input - Raw input string
+ * @param maxLength - Maximum allowed length (after trim)
+ * @returns Trimmed, validated input
+ * @throws {ValidationError} On invalid input
+ */
+export function validateInput(input, maxLength) {
+    if (input == null) {
+        throw new ValidationError("Input must not be null or undefined");
+    }
+    // Null byte check (explicit for clarity — also caught by control char regex)
+    if (input.includes("\0")) {
+        throw new ValidationError("Input contains null bytes");
+    }
+    // Control character check (allow \t \n \r)
+    if (CONTROL_CHAR_RE.test(input)) {
+        throw new ValidationError("Input contains disallowed control characters");
+    }
+    const trimmed = input.trim();
+    if (trimmed.length === 0) {
+        throw new ValidationError("Input must not be empty");
+    }
+    if (trimmed.length > maxLength) {
+        throw new ValidationError(`Input exceeds maximum length of ${maxLength} characters`);
+    }
+    return trimmed;
+}
+// ─── Path Security ──────────────────────────────────────────────────
+/**
+ * Validate a file path against security constraints and allowed prefixes.
+ *
+ * Checks for:
+ * - Null bytes
+ * - URL-encoded traversal sequences (`%2e%2e`, `%2f`, `%5c`)
+ * - NFKC normalization attacks (path changes after normalization)
+ * - `..` path components (directory traversal)
+ * - Prefix boundary enforcement (`/allowed` must not match `/allowed-evil`)
+ *
+ * @param path - The file path to validate
+ * @param allowedPrefixes - Array of allowed path prefixes
+ * @returns The validated, normalized path
+ * @throws {PathSecurityError} On any security violation
+ */
+export function validatePath(path, allowedPrefixes) {
+    if (!path || typeof path !== "string") {
+        throw new PathSecurityError("Path must be a non-empty string");
+    }
+    // Null byte injection
+    if (path.includes("\0")) {
+        throw new PathSecurityError("Path contains null bytes");
+    }
+    // URL-encoded traversal detection (before any decoding)
+    if (URL_ENCODED_TRAVERSAL_RE.test(path)) {
+        throw new PathSecurityError("Path contains URL-encoded traversal sequences");
+    }
+    // NFKC normalization attack: normalize and compare.
+    // Attackers use Unicode lookalikes (e.g. fullwidth dots) that normalize
+    // to traversal sequences.
+    const normalized = path.normalize("NFKC");
+    if (normalized !== path) {
+        throw new PathSecurityError("Path changes under NFKC normalization — possible Unicode attack");
+    }
+    // Split on both forward and back slashes for cross-platform safety
+    const segments = path.split(/[/\\]/);
+    for (const segment of segments) {
+        if (segment === "..") {
+            throw new PathSecurityError("Path contains directory traversal component (..)");
+        }
+    }
+    // Prefix boundary check: the path must start with an allowed prefix
+    // followed by either end-of-string or a path separator.
+    const matchesPrefix = allowedPrefixes.some((prefix) => {
+        if (path === prefix)
+            return true;
+        // Ensure boundary: prefix "/allowed" must not match "/allowed-evil"
+        const withSep = prefix.endsWith("/") ? prefix : `${prefix}/`;
+        return path.startsWith(withSep);
+    });
+    if (!matchesPrefix) {
+        throw new PathSecurityError("Path is outside allowed prefixes");
+    }
+    return path;
+}
+// ─── Device Path Blocking ───────────────────────────────────────────
+/**
+ * Check whether a path refers to a blocked device or virtual filesystem.
+ *
+ * Blocks `/dev/*`, `/proc/self/fd/*`, `/sys/*` and specific device nodes.
+ *
+ * @param path - The path to check
+ * @returns `true` if the path is a blocked device path
+ */
+export function isBlockedDevicePath(path) {
+    if (!path)
+        return false;
+    const lower = path.toLowerCase();
+    if (BLOCKED_DEVICE_EXACT.has(lower))
+        return true;
+    for (const prefix of BLOCKED_DEVICE_PREFIXES) {
+        if (lower.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+// ─── Dangerous File Detection ───────────────────────────────────────
+/**
+ * Check whether a filename (or path) refers to a sensitive/dangerous file.
+ *
+ * Detects config files (`.gitconfig`, `.bashrc`, `.env`), credential files
+ * (`credentials.json`, SSH keys), and sensitive directories (`.ssh/`, `.aws/`).
+ *
+ * @param filename - Filename or path to check (basename is extracted)
+ * @returns `true` if the file is considered dangerous
+ */
+export function isDangerousFile(filename) {
+    if (!filename)
+        return false;
+    // Extract basename — handle both / and \ separators
+    const segments = filename.split(/[/\\]/).filter(Boolean);
+    // Check if any directory component is a dangerous dir
+    for (const segment of segments) {
+        if (DANGEROUS_DIRS.has(segment))
+            return true;
+    }
+    // Check the final filename
+    const basename = segments[segments.length - 1];
+    if (!basename)
+        return false;
+    if (DANGEROUS_FILES.has(basename))
+        return true;
+    // Catch .env.* variants
+    if (basename.startsWith(".env."))
+        return true;
+    // Catch SSH private key patterns
+    if (basename.startsWith("id_") && !basename.includes(".pub"))
+        return true;
+    return false;
+}
+// ─── File Size Validation ───────────────────────────────────────────
+/**
+ * Validate that a file size is within acceptable bounds.
+ *
+ * @param bytes - Actual size in bytes
+ * @param maxBytes - Maximum allowed size in bytes
+ * @throws {ContentTooLargeError} If size exceeds the limit
+ */
+export function validateFileSize(bytes, maxBytes) {
+    if (bytes < 0) {
+        throw new ValidationError("File size must not be negative");
+    }
+    if (maxBytes < 0) {
+        throw new ValidationError("Max size must not be negative");
+    }
+    if (bytes > maxBytes) {
+        throw new ContentTooLargeError(bytes, maxBytes);
+    }
+}

package/dist/with-resolvers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Polyfill for Promise.withResolvers() (ES2024, Node 22+).
+ *
+ * Inspired by Claude Code's `src/utils/withResolvers.ts`.
+ */
+export type Deferred<T> = {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: unknown) => void;
+};
+export declare function withResolvers<T>(): Deferred<T>;
+//# sourceMappingURL=with-resolvers.d.ts.map

package/dist/with-resolvers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-resolvers.d.ts","sourceRoot":"","sources":["../src/with-resolvers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;IACxB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC7C,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC,CAAC;AAEF,wBAAgB,aAAa,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAQ9C"}

package/dist/with-resolvers.js

@@ -0,0 +1,14 @@
+/**
+ * Polyfill for Promise.withResolvers() (ES2024, Node 22+).
+ *
+ * Inspired by Claude Code's `src/utils/withResolvers.ts`.
+ */
+export function withResolvers() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}

package/dist/xml-escape.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Escape XML/HTML special characters for safe interpolation into element
+ * text content (between tags). Use when untrusted strings (process stdout,
+ * user input, external data) go inside `<tag>${here}</tag>`.
+ */
+export declare function escapeXml(s: string): string;
+/**
+ * Escape for interpolation into a double- or single-quoted attribute value:
+ * `<tag attr="${here}">`. Escapes quotes in addition to `& < >`.
+ */
+export declare function escapeXmlAttr(s: string): string;
+//# sourceMappingURL=xml-escape.d.ts.map

package/dist/xml-escape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml-escape.d.ts","sourceRoot":"","sources":["../src/xml-escape.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/C"}

package/dist/xml-escape.js

@@ -0,0 +1,15 @@
+/**
+ * Escape XML/HTML special characters for safe interpolation into element
+ * text content (between tags). Use when untrusted strings (process stdout,
+ * user input, external data) go inside `<tag>${here}</tag>`.
+ */
+export function escapeXml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+/**
+ * Escape for interpolation into a double- or single-quoted attribute value:
+ * `<tag attr="${here}">`. Escapes quotes in addition to `& < >`.
+ */
+export function escapeXmlAttr(s) {
+    return escapeXml(s).replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oka-core/reason",
-  "version": "0.2.15",
+  "version": "0.2.16",
   "description": "MCP server for institutional knowledge capture, semantic search, and consolidation",
   "private": false,
   "publishConfig": {