@juspay/neurolink 13.8.16 → 13.8.18

package/dist/proxy/inboundAuth.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Inbound trust for the proxy listeners and the SDK-mounted proxy routes.
+ *
+ * Both pool engines spend the operator's subscriptions on behalf of whoever
+ * reaches the port. On loopback that is the operator; anywhere else it is
+ * anyone. This module holds the three decisions that keep that honest:
+ *
+ * - **Bind policy.** A listener may bind off-loopback only when something
+ *   authenticates callers: the share gate, an inbound token, or the operator's
+ *   explicit `--allow-unauthenticated`.
+ * - **Inbound token.** `NEUROLINK_PROXY_INBOUND_TOKEN` (or `--inbound-token`)
+ *   is a bearer every caller must present, compared in constant time. A share
+ *   token is an alternative credential, judged by the share gate.
+ * - **Operator-only surfaces.** `/accounts`, `/limits` and `/status` name the
+ *   pool's accounts; they are refused to borrowers and, when a token is
+ *   configured, to anyone without it.
+ *
+ * @module proxy/inboundAuth
+ */
+import type { ProxyBindPolicyDecision, ProxyBindPolicyInput, ProxyInboundAuthOptions, ProxyShareRefusalResponse } from "../types/index.js";
+/** Dedicated header, so the inbound token never collides with a client credential. */
+export declare const INBOUND_TOKEN_HEADER = "x-neurolink-inbound-token";
+/** Set on every refusal so a client can tell "token required" from "bad request". */
+export declare const INBOUND_AUTH_HEADER = "x-neurolink-inbound-auth";
+export declare const INBOUND_TOKEN_ENV = "NEUROLINK_PROXY_INBOUND_TOKEN";
+export declare const ALLOW_UNAUTHENTICATED_ENV = "NEUROLINK_PROXY_ALLOW_UNAUTHENTICATED";
+/**
+ * Compare two secrets without leaking where they diverge. Hand-rolled rather
+ * than `crypto.timingSafeEqual` so the proxy routes stay loadable from a build
+ * whose `node:crypto` stub does not carry it.
+ */
+export declare function secretsMatch(expected: string, presented: string): boolean;
+/** The inbound token in force: an explicit value wins over the environment. */
+export declare function resolveInboundToken(explicit?: string): string | undefined;
+/** `NEUROLINK_PROXY_ALLOW_UNAUTHENTICATED` as a boolean. */
+export declare function isUnauthenticatedBindAllowedByEnv(): boolean;
+/** Loopback addresses in every spelling a bind flag accepts. */
+export declare function isLoopbackHost(host: string): boolean;
+/**
+ * May the proxy bind to `host`?
+ *
+ * Loopback always may. Anything else needs the share gate, an inbound token,
+ * or the operator's explicit acknowledgement — and the acknowledgement still
+ * earns a warning, because the subscriptions are then one port scan away.
+ */
+export declare function evaluateProxyBindPolicy(input: ProxyBindPolicyInput): ProxyBindPolicyDecision;
+/** True when the request presents the configured inbound token. */
+export declare function hasValidInboundToken(headers: Record<string, string | undefined>, token: string | undefined): boolean;
+/** The 401 an unauthenticated caller receives, in the Anthropic error shape. */
+export declare function buildInboundAuthRefusal(): ProxyShareRefusalResponse;
+/**
+ * Decide an inbound request against the configured token.
+ *
+ * A request carrying a share token is handed to the share gate instead: a
+ * borrower holds a grant, not the operator's token, and the gate is what
+ * judges a grant. Everything else must present the token.
+ */
+export declare function authorizeInboundRequest(headers: Record<string, string | undefined>, token: string | undefined): {
+    ok: true;
+} | {
+    ok: false;
+    response: ProxyShareRefusalResponse;
+};
+/** `Response` form of the refusal, for route factories whose adapters pass one through. */
+export declare function inboundAuthRefusalResponse(): Response;
+/**
+ * Say, loudly and once per engine, that a proxy route group was mounted with
+ * nothing authenticating its callers. `logger.always` on purpose: the ordinary
+ * warn level is invisible outside debug runs, and an open proxy is exactly the
+ * thing an operator must not be able to miss. Suppressed when the caller
+ * recorded the decision (`allowUnauthenticated`), which the CLI does after its
+ * own bind check.
+ */
+export declare function warnIfProxyRoutesUnauthenticated(engine: string, options: ProxyInboundAuthOptions | undefined, token: string | undefined): void;
+/** Test isolation only. */
+export declare function resetInboundAuthWarningsForTests(): void;
+/** Paths that stay open on an authenticated listener: liveness and self-authenticating peers. */
+export declare function isInboundAuthExemptPath(path: string): boolean;
+/**
+ * How many pooled accounts one inbound request may be tried against.
+ *
+ * Without a cap a single request fans out to every account in the pool — N
+ * upstream posts, N× quota — on any rotation trigger. Default 3;
+ * `NEUROLINK_PROXY_MAX_ACCOUNTS_PER_REQUEST=0` restores the unbounded
+ * behaviour.
+ */
+export declare const MAX_ACCOUNTS_PER_REQUEST_ENV = "NEUROLINK_PROXY_MAX_ACCOUNTS_PER_REQUEST";
+export declare const DEFAULT_MAX_ACCOUNTS_PER_REQUEST = 3;
+export declare function resolveMaxAccountsPerRequest(): number;

package/dist/proxy/inboundAuth.js

@@ -0,0 +1,219 @@
+/**
+ * Inbound trust for the proxy listeners and the SDK-mounted proxy routes.
+ *
+ * Both pool engines spend the operator's subscriptions on behalf of whoever
+ * reaches the port. On loopback that is the operator; anywhere else it is
+ * anyone. This module holds the three decisions that keep that honest:
+ *
+ * - **Bind policy.** A listener may bind off-loopback only when something
+ *   authenticates callers: the share gate, an inbound token, or the operator's
+ *   explicit `--allow-unauthenticated`.
+ * - **Inbound token.** `NEUROLINK_PROXY_INBOUND_TOKEN` (or `--inbound-token`)
+ *   is a bearer every caller must present, compared in constant time. A share
+ *   token is an alternative credential, judged by the share gate.
+ * - **Operator-only surfaces.** `/accounts`, `/limits` and `/status` name the
+ *   pool's accounts; they are refused to borrowers and, when a token is
+ *   configured, to anyone without it.
+ *
+ * @module proxy/inboundAuth
+ */
+import { logger } from "../utils/logger.js";
+import { extractShareToken } from "./shareGate.js";
+/** Dedicated header, so the inbound token never collides with a client credential. */
+export const INBOUND_TOKEN_HEADER = "x-neurolink-inbound-token";
+/** Set on every refusal so a client can tell "token required" from "bad request". */
+export const INBOUND_AUTH_HEADER = "x-neurolink-inbound-auth";
+export const INBOUND_TOKEN_ENV = "NEUROLINK_PROXY_INBOUND_TOKEN";
+export const ALLOW_UNAUTHENTICATED_ENV = "NEUROLINK_PROXY_ALLOW_UNAUTHENTICATED";
+/**
+ * Compare two secrets without leaking where they diverge. Hand-rolled rather
+ * than `crypto.timingSafeEqual` so the proxy routes stay loadable from a build
+ * whose `node:crypto` stub does not carry it.
+ */
+export function secretsMatch(expected, presented) {
+    if (expected.length !== presented.length || expected.length === 0) {
+        return false;
+    }
+    let difference = 0;
+    for (let index = 0; index < expected.length; index += 1) {
+        difference |= expected.charCodeAt(index) ^ presented.charCodeAt(index);
+    }
+    return difference === 0;
+}
+function envFlagIsOn(name) {
+    const raw = (process.env[name] ?? "").trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "on" || raw === "yes";
+}
+/** The inbound token in force: an explicit value wins over the environment. */
+export function resolveInboundToken(explicit) {
+    const candidate = explicit?.trim() || process.env[INBOUND_TOKEN_ENV]?.trim();
+    return candidate ? candidate : undefined;
+}
+/** `NEUROLINK_PROXY_ALLOW_UNAUTHENTICATED` as a boolean. */
+export function isUnauthenticatedBindAllowedByEnv() {
+    return envFlagIsOn(ALLOW_UNAUTHENTICATED_ENV);
+}
+/** Loopback addresses in every spelling a bind flag accepts. */
+export function isLoopbackHost(host) {
+    const trimmed = host
+        .trim()
+        .toLowerCase()
+        .replace(/^\[|\]$/g, "");
+    if (trimmed === "localhost" || trimmed === "::1") {
+        return true;
+    }
+    if (/^0{1,4}(:0{1,4}){6}:0{0,3}1$/.test(trimmed)) {
+        return true;
+    }
+    if (trimmed.startsWith("::ffff:")) {
+        return isLoopbackHost(trimmed.slice("::ffff:".length));
+    }
+    const octets = trimmed.split(".");
+    return (octets.length === 4 &&
+        octets[0] === "127" &&
+        octets.every((octet) => /^\d{1,3}$/.test(octet) && Number(octet) <= 255));
+}
+/**
+ * May the proxy bind to `host`?
+ *
+ * Loopback always may. Anything else needs the share gate, an inbound token,
+ * or the operator's explicit acknowledgement — and the acknowledgement still
+ * earns a warning, because the subscriptions are then one port scan away.
+ */
+export function evaluateProxyBindPolicy(input) {
+    if (isLoopbackHost(input.host)) {
+        return { allowed: true };
+    }
+    if (input.inboundToken || input.requireGrant) {
+        return { allowed: true };
+    }
+    if (input.allowUnauthenticated) {
+        return {
+            allowed: true,
+            warning: `Binding ${input.host} with no inbound authentication: anyone who reaches ` +
+                `this port can spend every pooled subscription. --allow-unauthenticated ` +
+                `acknowledges that; put an authenticating reverse proxy in front.`,
+        };
+    }
+    return {
+        allowed: false,
+        reason: `Refusing to bind ${input.host}: it is not a loopback address and nothing ` +
+            `would authenticate inbound callers. Set ${INBOUND_TOKEN_ENV} (or pass ` +
+            `--inbound-token <secret>), gate the port with NEUROLINK_PROXY_REQUIRE_GRANT=1, ` +
+            `or pass --allow-unauthenticated to accept an open proxy.`,
+    };
+}
+function presentedInboundToken(headers) {
+    const dedicated = headers[INBOUND_TOKEN_HEADER];
+    if (dedicated?.trim()) {
+        return dedicated.trim();
+    }
+    const authorization = headers.authorization ?? headers.Authorization;
+    if (!authorization) {
+        return undefined;
+    }
+    const trimmed = authorization.trim();
+    return trimmed.toLowerCase().startsWith("bearer ")
+        ? trimmed.slice("bearer ".length).trim()
+        : undefined;
+}
+/** True when the request presents the configured inbound token. */
+export function hasValidInboundToken(headers, token) {
+    if (!token) {
+        return false;
+    }
+    const presented = presentedInboundToken(headers);
+    return presented !== undefined && secretsMatch(token, presented);
+}
+/** The 401 an unauthenticated caller receives, in the Anthropic error shape. */
+export function buildInboundAuthRefusal() {
+    return {
+        status: 401,
+        headers: { [INBOUND_AUTH_HEADER]: "required" },
+        body: {
+            type: "error",
+            error: {
+                type: "authentication_error",
+                message: "This proxy requires an inbound token. Send it as " +
+                    `${INBOUND_TOKEN_HEADER} or as Authorization: Bearer <token>.`,
+            },
+        },
+    };
+}
+/**
+ * Decide an inbound request against the configured token.
+ *
+ * A request carrying a share token is handed to the share gate instead: a
+ * borrower holds a grant, not the operator's token, and the gate is what
+ * judges a grant. Everything else must present the token.
+ */
+export function authorizeInboundRequest(headers, token) {
+    if (!token) {
+        return { ok: true };
+    }
+    if (hasValidInboundToken(headers, token)) {
+        return { ok: true };
+    }
+    if (extractShareToken(headers) !== undefined) {
+        return { ok: true };
+    }
+    return { ok: false, response: buildInboundAuthRefusal() };
+}
+/** `Response` form of the refusal, for route factories whose adapters pass one through. */
+export function inboundAuthRefusalResponse() {
+    const refusal = buildInboundAuthRefusal();
+    return new Response(JSON.stringify(refusal.body), {
+        status: refusal.status,
+        headers: { "content-type": "application/json", ...refusal.headers },
+    });
+}
+const warnedEngines = new Set();
+/**
+ * Say, loudly and once per engine, that a proxy route group was mounted with
+ * nothing authenticating its callers. `logger.always` on purpose: the ordinary
+ * warn level is invisible outside debug runs, and an open proxy is exactly the
+ * thing an operator must not be able to miss. Suppressed when the caller
+ * recorded the decision (`allowUnauthenticated`), which the CLI does after its
+ * own bind check.
+ */
+export function warnIfProxyRoutesUnauthenticated(engine, options, token) {
+    if (token || options?.allowUnauthenticated || warnedEngines.has(engine)) {
+        return;
+    }
+    warnedEngines.add(engine);
+    logger.always(`[proxy] SECURITY: the ${engine} proxy routes were mounted with no inbound ` +
+        `authentication. Anyone who can reach them spends the pooled subscriptions. ` +
+        `Set ${INBOUND_TOKEN_ENV}, pass inboundAuth.token, or bind loopback only ` +
+        `and set inboundAuth.allowUnauthenticated to acknowledge this.`);
+}
+/** Test isolation only. */
+export function resetInboundAuthWarningsForTests() {
+    warnedEngines.clear();
+}
+/** Paths that stay open on an authenticated listener: liveness and self-authenticating peers. */
+export function isInboundAuthExemptPath(path) {
+    return (path === "/health" ||
+        path === "/internal/update-control" ||
+        path.startsWith("/peer/"));
+}
+/**
+ * How many pooled accounts one inbound request may be tried against.
+ *
+ * Without a cap a single request fans out to every account in the pool — N
+ * upstream posts, N× quota — on any rotation trigger. Default 3;
+ * `NEUROLINK_PROXY_MAX_ACCOUNTS_PER_REQUEST=0` restores the unbounded
+ * behaviour.
+ */
+export const MAX_ACCOUNTS_PER_REQUEST_ENV = "NEUROLINK_PROXY_MAX_ACCOUNTS_PER_REQUEST";
+export const DEFAULT_MAX_ACCOUNTS_PER_REQUEST = 3;
+export function resolveMaxAccountsPerRequest() {
+    const raw = process.env[MAX_ACCOUNTS_PER_REQUEST_ENV]?.trim();
+    if (raw === undefined || raw === "") {
+        return DEFAULT_MAX_ACCOUNTS_PER_REQUEST;
+    }
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        return DEFAULT_MAX_ACCOUNTS_PER_REQUEST;
+    }
+    return parsed === 0 ? Number.POSITIVE_INFINITY : Math.floor(parsed);
+}

package/dist/proxy/tokenRefresh.d.ts

@@ -1,4 +1,10 @@
 import type { RefreshableAccount, RefreshResult, TokenPersistTarget } from "../types/index.js";
+/**
+ * An upstream refresh error body is logged for diagnosis, never verbatim: a
+ * token endpoint can echo the grant it rejected, and anything that looks like
+ * a credential is masked before the line is written.
+ */
+export declare function redactRefreshErrorBody(body: string): string;
 export declare function needsRefresh(account: RefreshableAccount): boolean;
 export declare function needsBackgroundRefresh(account: RefreshableAccount): boolean;
 export declare function needsInlineRefresh(account: RefreshableAccount): boolean;

package/dist/proxy/tokenRefresh.js

@@ -17,6 +17,18 @@ const SUCCESS_CACHE_MS = 60_000;
 // slow token-store decrypt can never stall (or abort) a live token refresh.
 const PEEK_TOKENS_TIMEOUT_MS = 2_000;
 const refreshesInFlight = new Map();
+/**
+ * An upstream refresh error body is logged for diagnosis, never verbatim: a
+ * token endpoint can echo the grant it rejected, and anything that looks like
+ * a credential is masked before the line is written.
+ */
+export function redactRefreshErrorBody(body) {
+    return body
+        .replace(/("?(?:access_token|refresh_token|id_token|client_secret|code)"?\s*[:=]\s*"?)[^",\s]+/gi, "$1[REDACTED]")
+        .replace(/\bsk-ant-[A-Za-z0-9_-]+/g, "sk-ant-[REDACTED]")
+        .replace(/\b[A-Za-z0-9_-]{64,}\b/g, "[REDACTED]")
+        .slice(0, 300);
+}
 function expiresWithin(account, bufferMs) {
     return !!(account.expiresAt &&
         account.expiresAt <= Date.now() + bufferMs &&
@@ -69,7 +81,7 @@ async function performTokenRefresh(account) {
                 const errorBody = await resp.text();
                 logger.warn(`[token-refresh] failed for ${account.label} at ${redactUrlForError(url)}`, {
                     status: resp.status,
-                    error: errorBody.slice(0, 500),
+                    error: redactRefreshErrorBody(errorBody),
                 });
                 const failure = {
                     success: false,

package/dist/proxy/updateState.js

@@ -7,6 +7,7 @@
  * Suppressed versions expire after 24 hours.
  */
 import fs from "fs";
+import { ensurePrivateDirectorySync } from "../auth/secureFiles.js";
 import os from "os";
 import path from "path";
 import { randomUUID } from "node:crypto";
@@ -39,10 +40,9 @@ function resolveStatePath(overridePath) {
  * Ensure the parent directory of the given file path exists.
  */
 function ensureParentDir(filePath) {
-    const dir = path.dirname(filePath);
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-    }
+    // `~/.neurolink` holds credential material; whoever creates it first must
+    // create it owner-only, and re-assert the mode when it already exists.
+    ensurePrivateDirectorySync(path.dirname(filePath));
 }
 /** Reject malformed persisted failure metadata before it reaches status output. */
 function isValidLastFailure(value) {

package/dist/rag/document/loaders.d.ts

@@ -88,12 +88,6 @@ export declare class PDFLoader implements DocumentLoader {
     private loadPdfParser;
     private parsePageRange;
 }
-/**
- * Web page loader
- *
- * Fetches and extracts content from web pages.
- * Supports basic HTML parsing without external dependencies.
- */
 export declare class WebLoader implements DocumentLoader {
     private defaultUserAgent;
     load(source: string, options?: WebLoaderOptions): Promise<MDocument>;

package/dist/rag/document/loaders.js

@@ -27,6 +27,8 @@ import { existsSync } from "fs";
 import { readFile } from "fs/promises";
 import { basename, extname } from "path";
 import { logger } from "../../utils/logger.js";
+import { downloadAttachment } from "../../utils/attachmentPolicy.js";
+import { redactUrlForError } from "../../utils/logSanitize.js";
 import { decodeHtmlTextEntitiesOnce } from "../../utils/htmlEntities.js";
 import { removeHtmlMarkup } from "../../utils/htmlText.js";
 import { CSVProcessor, stripBom, stripMetadataLine, splitCsvLines, dedupeColumnNames, sanitizeColumnName, } from "../../utils/csvProcessor.js";
@@ -351,6 +353,8 @@ export class PDFLoader {
  * Fetches and extracts content from web pages.
  * Supports basic HTML parsing without external dependencies.
  */
+/** 25 MiB — the default cap on a fetched page. */
+const WEB_LOADER_MAX_BYTES = 25 * 1024 * 1024;
 export class WebLoader {
     defaultUserAgent = "Mozilla/5.0 (compatible; NeuroLink/1.0; +https://github.com/juspay/neurolink)";
     async load(source, options) {
@@ -358,23 +362,25 @@ export class WebLoader {
             throw new Error(`Invalid URL: ${source}`);
         }
         logger.debug("[WebLoader] Fetching URL", {
-            url: source,
+            url: redactUrlForError(source),
             timeout: options?.timeout,
         });
-        const response = await fetch(source, {
-            signal: options?.timeout
-                ? AbortSignal.timeout(options.timeout)
-                : undefined,
+        // Through the attachment policy: HTTPS to a public host unless the policy
+        // says otherwise, DNS-pinned, redirects re-validated per hop with the
+        // caller's headers dropped, and the body bounded while it streams rather
+        // than read whole with `text()`.
+        const downloaded = await downloadAttachment(source, {
+            policy: options?.attachmentPolicy,
+            maxBytes: options?.maxBytes ?? WEB_LOADER_MAX_BYTES,
+            label: "web page",
+            timeoutMs: options?.timeout,
             headers: {
                 "User-Agent": options?.userAgent || this.defaultUserAgent,
                 Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
                 ...options?.headers,
             },
         });
-        if (!response.ok) {
-            throw new Error(`HTTP error ${response.status}: ${response.statusText}`);
-        }
-        const html = await response.text();
+        const html = downloaded.buffer.toString("utf-8");
         let content = html;
         // Extract main content if requested
         if (options?.extractMainContent) {
@@ -388,7 +394,7 @@ export class WebLoader {
                 source,
                 url: source,
                 fetchedAt: new Date().toISOString(),
-                contentType: response.headers.get("content-type") || "text/html",
+                contentType: downloaded.contentType || "text/html",
                 ...options?.metadata,
             },
         });

package/dist/rag/ragIntegration.d.ts

@@ -1,4 +1,4 @@
-import type { RAGConfig, VectorQueryResult, RAGPreparedTool } from "../types/index.js";
+import type { AttachmentPolicy, RAGConfig, VectorQueryResult, RAGPreparedTool } from "../types/index.js";
 /**
  * Generate deterministic embeddings for chunks.
  * Combines character-frequency (40%) with word-level hash features (60%)
@@ -30,5 +30,5 @@ declare function diversifyResults(results: VectorQueryResult[], topK: number): V
  * is the default, and the fallback when a configured embedding provider fails).
  * The returned tool rejects a query over the same length the same way.
  */
-export declare function prepareRAGTool(ragConfig: RAGConfig, fallbackProvider?: string): Promise<RAGPreparedTool>;
+export declare function prepareRAGTool(ragConfig: RAGConfig, fallbackProvider?: string, attachmentPolicy?: AttachmentPolicy): Promise<RAGPreparedTool>;
 export {};

package/dist/rag/ragIntegration.js

@@ -1,4 +1,3 @@
-import { existsSync, readFileSync } from "fs";
 import { extname, resolve } from "path";
 import { z } from "zod";
 import { SpanSerializer, SpanType, SpanStatus, getMetricsAggregator, } from "../observability/index.js";
@@ -6,12 +5,19 @@ import { logger } from "../utils/logger.js";
 import { redactUrlForError } from "../utils/logSanitize.js";
 import { ErrorFactory } from "../utils/errorHandling.js";
 import { ImageProcessor } from "../utils/imageProcessor.js";
+import { readAttachmentFile, resolveAttachmentPath, resolveAttachmentPolicy, } from "../utils/attachmentPolicy.js";
 import { createChunker } from "./ChunkerFactory.js";
 import { createVectorQueryTool, InMemoryVectorStore, } from "./retrieval/vectorQueryTool.js";
 import { ImageLoader } from "./document/imageLoader.js";
 import { IMAGE_EXTENSIONS } from "../processors/config/index.js";
 import { withSpan } from "../telemetry/withSpan.js";
 import { tracers } from "../telemetry/tracers.js";
+/**
+ * Ceiling for one `rag.files` text source: 50 MiB. A file is chunked and
+ * embedded in full, so a larger one is a mistake rather than a document;
+ * `attachments.maxBytes` lowers it.
+ */
+const RAG_FILE_MAX_BYTES = 50 * 1024 * 1024;
 /**
  * Maps file extensions to recommended chunking strategies
  */
@@ -173,7 +179,7 @@ function diversifyResults(results, topK) {
  * is the default, and the fallback when a configured embedding provider fails).
  * The returned tool rejects a query over the same length the same way.
  */
-export async function prepareRAGTool(ragConfig, fallbackProvider) {
+export async function prepareRAGTool(ragConfig, fallbackProvider, attachmentPolicy = resolveAttachmentPolicy()) {
     const span = SpanSerializer.createSpan(SpanType.RAG, "rag.prepare", {
         "rag.operation": "prepare",
         "rag.files_count": ragConfig.files?.length ?? 0,
@@ -182,7 +188,7 @@ export async function prepareRAGTool(ragConfig, fallbackProvider) {
     });
     const startTime = Date.now();
     try {
-        const result = await _prepareRAGToolInner(ragConfig, fallbackProvider);
+        const result = await _prepareRAGToolInner(ragConfig, fallbackProvider, attachmentPolicy);
         span.durationMs = Date.now() - startTime;
         const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
         endedSpan.attributes = {
@@ -202,7 +208,7 @@ export async function prepareRAGTool(ragConfig, fallbackProvider) {
         throw error;
     }
 }
-async function _prepareRAGToolInner(ragConfig, fallbackProvider) {
+async function _prepareRAGToolInner(ragConfig, fallbackProvider, attachmentPolicy) {
     const { files, strategy: userStrategy, chunkSize = 1000, chunkOverlap = 200, topK: userTopK = 5, toolName = "search_knowledge_base", toolDescription = "REQUIRED: Search through pre-loaded local documents to find relevant information. Use this tool FIRST before any web search or other tools. This searches an indexed knowledge base of documents the user has provided.", embeddingProvider, embeddingModel, } = ragConfig;
     if (!files || files.length === 0) {
         throw new Error("RAG config requires at least one file path in 'files'");
@@ -248,10 +254,6 @@ async function _prepareRAGToolInner(ragConfig, fallbackProvider) {
             continue;
         }
         const resolvedPath = resolve(filePath);
-        if (!existsSync(resolvedPath)) {
-            logger.warn(`[RAG] File not found, skipping: ${resolvedPath}`);
-            continue;
-        }
         // Detect image files by extension
         const ext = extname(resolvedPath).toLowerCase();
         if (ext === ".svg") {
@@ -260,15 +262,38 @@ async function _prepareRAGToolInner(ragConfig, fallbackProvider) {
             continue;
         }
         if (IMAGE_EXTENSIONS.includes(ext)) {
-            imageFiles.push({ path: resolvedPath, ext });
+            // The same containment as the text branch below; ImageLoader then reads
+            // the real path this returned. A path outside the roots is skipped with
+            // the same warning as an unreadable one, so the tool keeps working on
+            // the files it may read.
+            try {
+                const real = await resolveAttachmentPath(resolvedPath, attachmentPolicy, "RAG image");
+                imageFiles.push({ path: real, ext });
+            }
+            catch (error) {
+                logger.warn(`[RAG] Failed to read image: ${resolvedPath}: ${error instanceof Error ? error.message : String(error)}`);
+            }
             continue;
         }
         try {
-            const content = readFileSync(resolvedPath, "utf-8");
+            // Roots containment when configured, O_NOFOLLOW open of the real path,
+            // regular files only, and a bounded read — where this was a bare
+            // `readFileSync` of whatever string arrived.
+            const read = await readAttachmentFile(resolvedPath, {
+                policy: attachmentPolicy,
+                maxBytes: RAG_FILE_MAX_BYTES,
+                label: "RAG file",
+            });
+            const content = read.buffer.toString("utf-8");
             const strategy = userStrategy || detectStrategy(resolvedPath);
             fileContents.push({ path: resolvedPath, content, strategy });
         }
         catch (error) {
+            const code = error?.code;
+            if (code === "ENOENT") {
+                logger.warn(`[RAG] File not found, skipping: ${resolvedPath}`);
+                continue;
+            }
             logger.warn(`[RAG] Failed to read file: ${resolvedPath}: ${error instanceof Error ? error.message : String(error)}`);
         }
     }

package/dist/rag/retrieval/vectorQueryTool.d.ts

@@ -39,6 +39,8 @@ export declare function createVectorQueryTool(config: VectorQueryToolConfig, vec
  */
 export declare class InMemoryVectorStore implements VectorStore {
     private vectors;
+    /** Vetted `$regex` patterns: the compiled expression, or null when refused. */
+    private readonly regexFilterCache;
     /**
      * Add vectors to an index
      */
@@ -65,6 +67,11 @@ export declare class InMemoryVectorStore implements VectorStore {
      * Check if metadata matches filter
      */
     private matchesFilter;
+    /**
+     * Evaluate a `$regex` filter operator. Patterns are vetted once per store
+     * and the verdict cached, so a refused pattern costs one analysis.
+     */
+    private matchesRegexFilter;
     /**
      * Calculate cosine similarity between two vectors
      */