@juspay/neurolink 13.8.17 → 13.8.19

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
      */

package/dist/rag/retrieval/vectorQueryTool.js

@@ -10,6 +10,7 @@ import { ProviderFactory } from "../../factories/providerFactory.js";
 import { withSpan } from "../../telemetry/withSpan.js";
 import { tracers } from "../../telemetry/tracers.js";
 import { logger } from "../../utils/logger.js";
+import { vetRegexPattern } from "../../middleware/utils/regexSafety.js";
 import { rerank } from "../reranker/reranker.js";
 /**
  * Creates a vector query tool for semantic search
@@ -132,11 +133,19 @@ export function createVectorQueryTool(config, vectorStore) {
         },
     };
 }
+/** Longest `$regex` filter pattern accepted; a secondary cap behind vetting. */
+const MAX_FILTER_REGEX_LENGTH = 200;
+/** Longest metadata value a `$regex` filter is run against. */
+const MAX_FILTER_REGEX_SUBJECT = 10_000;
+/** Distinct patterns remembered per store before the verdict cache is reset. */
+const MAX_FILTER_REGEX_CACHE = 256;
 /**
  * In-memory vector store implementation for testing and development
  */
 export class InMemoryVectorStore {
     vectors = new Map();
+    /** Vetted `$regex` patterns: the compiled expression, or null when refused. */
+    regexFilterCache = new Map();
     /**
      * Add vectors to an index
      */
@@ -272,23 +281,14 @@ export class InMemoryVectorStore {
                         return false;
                     }
                     if ("$regex" in ops) {
-                        const pattern = ops.$regex;
-                        let regexMatches = false;
-                        // Guard against ReDoS: reject excessively long patterns and limit
-                        // the tested string length to prevent pathological backtracking.
-                        if (pattern.length <= 200) {
-                            try {
-                                const re = new RegExp(pattern);
-                                const testValue = typeof fieldValue === "string"
-                                    ? fieldValue.slice(0, 10_000)
-                                    : "";
-                                regexMatches = re.test(testValue);
-                            }
-                            catch {
-                                // Invalid regex pattern — treat as non-match
-                                regexMatches = false;
-                            }
-                        }
+                        // The pattern is chosen by the model and the value it runs on
+                        // comes from ingested documents, so both halves of a ReDoS are
+                        // attacker-influenced. A length cap alone does not bound
+                        // backtracking (`^(a+)+$` is 7 characters); `vetRegexPattern`
+                        // reads the pattern's structure and refuses the ones that can
+                        // backtrack catastrophically. A refused or invalid pattern is a
+                        // non-match, as an invalid one always was.
+                        const regexMatches = this.matchesRegexFilter(ops.$regex, fieldValue);
                         if (!regexMatches) {
                             return false;
                         }
@@ -304,6 +304,43 @@ export class InMemoryVectorStore {
         }
         return true;
     }
+    /**
+     * Evaluate a `$regex` filter operator. Patterns are vetted once per store
+     * and the verdict cached, so a refused pattern costs one analysis.
+     */
+    matchesRegexFilter(pattern, fieldValue) {
+        if (typeof pattern !== "string" ||
+            pattern.length > MAX_FILTER_REGEX_LENGTH) {
+            return false;
+        }
+        let compiled = this.regexFilterCache.get(pattern);
+        if (compiled === undefined) {
+            const verdict = vetRegexPattern(pattern);
+            if (verdict.safe) {
+                try {
+                    compiled = new RegExp(pattern);
+                }
+                catch {
+                    compiled = null;
+                }
+            }
+            else {
+                logger.debug("[InMemoryVectorStore] Refused a $regex filter pattern that could stall the process", { reason: verdict.reason });
+                compiled = null;
+            }
+            if (this.regexFilterCache.size >= MAX_FILTER_REGEX_CACHE) {
+                this.regexFilterCache.clear();
+            }
+            this.regexFilterCache.set(pattern, compiled);
+        }
+        if (compiled === null) {
+            return false;
+        }
+        const testValue = typeof fieldValue === "string"
+            ? fieldValue.slice(0, MAX_FILTER_REGEX_SUBJECT)
+            : "";
+        return compiled.test(testValue);
+    }
     /**
      * Calculate cosine similarity between two vectors
      */

package/dist/server/abstract/baseServerAdapter.d.ts

@@ -7,6 +7,8 @@ import { EventEmitter } from "events";
 import type { ExternalServerManager } from "../../mcp/externalServerManager.js";
 import type { MCPToolRegistry } from "../../mcp/toolRegistry.js";
 import type { NeuroLink } from "../../neurolink.js";
+/** The interface an adapter binds unless told otherwise: this host only. */
+export declare const DEFAULT_SERVER_HOST = "127.0.0.1";
 import type { MiddlewareDefinition, RedactionConfig, RequiredServerAdapterConfig, RequiredShutdownConfig, RouteDefinition, ServerAdapterConfig, ServerAdapterEvents, ServerCarriedContext, ServerContext, ServerLifecycleState, ServerStatus, TrackedConnection } from "../../types/index.js";
 /**
  * Abstract base class for server adapters
@@ -29,7 +31,47 @@ export declare abstract class BaseServerAdapter extends EventEmitter {
     protected activeConnections: Map<string, TrackedConnection>;
     protected readonly shutdownConfig: RequiredShutdownConfig;
     private carryRequestedByRoutes;
+    private sensitiveRoutesRegistered;
+    private sensitiveRoutesAllowedOpen;
     constructor(neurolink: NeuroLink, config?: ServerAdapterConfig);
+    /**
+     * Whether middleware marked `authenticates: true` is registered (the
+     * built-in authentication middleware marks itself). The tool and MCP
+     * execution routes ask on every request; `registerAllRoutes()` wires them.
+     */
+    hasAuthenticationMiddleware(): boolean;
+    /**
+     * Called by `registerAllRoutes()`: routes that act on the host (tool and
+     * MCP execution) are mounted, so `start()` warns when no authentication
+     * middleware guards them. The check runs at start, when the middleware set
+     * is final, so registering authentication after the routes is fine.
+     */
+    noteSensitiveRoutes(options?: {
+        allowUnauthenticated?: boolean;
+    }): void;
+    /**
+     * The warning promised by `noteSensitiveRoutes()`, always on stderr: a
+     * `logger.warn` is dropped unless debug logging is on, which would hide a
+     * notice meant for the operator who just started the server.
+     */
+    protected warnIfSensitiveRoutesUnauthenticated(): void;
+    /**
+     * Give the handler a way to notice that the client is gone or the request
+     * is over time. The controller is this request's own unless middleware
+     * already attached one that the adapter carried; `applyTimeout` arms the
+     * configured request timeout, which the caller leaves off for a streaming
+     * route (a stream legitimately outlives it, as under Hono's own timeout
+     * middleware). `release()` disarms the timer once the response is written.
+     */
+    protected attachRequestAbort(ctx: ServerContext, options: {
+        onClientClose: (listener: () => void) => void;
+        applyTimeout: boolean;
+    }): {
+        controller: AbortController;
+        deadline: Promise<never> | undefined;
+        timedOut: () => boolean;
+        release: () => void;
+    };
     /**
      * Initialize the underlying server framework
      * May be async: adapters that dynamically import their framework package
@@ -146,6 +188,7 @@ export declare abstract class BaseServerAdapter extends EventEmitter {
         query?: Record<string, string>;
         params?: Record<string, string>;
         body?: unknown;
+        remoteAddress?: string;
     }): ServerContext;
     /**
      * Register built-in middleware

package/dist/server/abstract/baseServerAdapter.js

@@ -6,10 +6,15 @@
 import { EventEmitter } from "events";
 import { getMetricsAggregator, SpanSerializer, SpanStatus, SpanType, } from "../../observability/index.js";
 import { withTimeout } from "../../utils/errorHandling.js";
+import { MAX_TIMER_MS } from "../../constants/timeouts.js";
 import { logger } from "../../utils/logger.js";
 import { markContextCarried } from "../utils/carriedContextMark.js";
+import { isLoopbackAddress } from "../utils/clientAddress.js";
+import { pathStartsWithSegment } from "../utils/pathMatch.js";
 import { tryImport } from "../../utils/tryImport.js";
-import { DrainTimeoutError, InvalidLifecycleStateError, MissingDependencyError, ServerAdapterError, ShutdownTimeoutError, } from "../errors.js";
+import { ConfigurationError, DrainTimeoutError, InvalidLifecycleStateError, MissingDependencyError, ServerAdapterError, ServerTimeoutError, ShutdownTimeoutError, } from "../errors.js";
+/** The interface an adapter binds unless told otherwise: this host only. */
+export const DEFAULT_SERVER_HOST = "127.0.0.1";
 /**
  * Abstract base class for server adapters
  * Provides common functionality and defines the interface for framework-specific implementations
@@ -37,6 +42,9 @@ export class BaseServerAdapter extends EventEmitter {
     // Set by enableMiddlewareStateCarry(); the carryMiddlewareState option is the
     // other way in.
     carryRequestedByRoutes = false;
+    // Set by noteSensitiveRoutes(); read when the server starts.
+    sensitiveRoutesRegistered = false;
+    sensitiveRoutesAllowedOpen = false;
     constructor(neurolink, config = {}) {
         super();
         this.neurolink = neurolink;
@@ -53,7 +61,9 @@ export class BaseServerAdapter extends EventEmitter {
         // Apply defaults
         this.config = {
             port: config.port ?? 3000,
-            host: config.host ?? "0.0.0.0",
+            // Loopback unless the operator names an interface: the routes run tools
+            // and remove MCP servers, so reachability is opt-in.
+            host: config.host ?? DEFAULT_SERVER_HOST,
             basePath: config.basePath ?? "/api",
             cors: {
                 enabled: config.cors?.enabled ?? true,
@@ -85,6 +95,8 @@ export class BaseServerAdapter extends EventEmitter {
                     "Too many requests, please try again later",
                 skipPaths: config.rateLimit?.skipPaths,
                 keyGenerator: config.rateLimit?.keyGenerator,
+                trustProxy: config.rateLimit?.trustProxy ?? false,
+                trustedProxies: config.rateLimit?.trustedProxies ?? [],
             },
             bodyParser: {
                 enabled: config.bodyParser?.enabled ?? true,
@@ -107,6 +119,100 @@ export class BaseServerAdapter extends EventEmitter {
             shutdown: this.shutdownConfig,
             carryMiddlewareState: config.carryMiddlewareState ?? false,
         };
+        // A wildcard origin with credentials is what the CORS specification
+        // forbids and what an adapter reflecting the request's Origin would grant:
+        // any page could make credentialed calls. Refuse it for every adapter.
+        if (this.config.cors.enabled &&
+            this.config.cors.credentials &&
+            this.config.cors.origins.includes("*")) {
+            throw new ConfigurationError('cors.credentials cannot be combined with the wildcard origin "*"; list the origins that may send credentials', { origins: this.config.cors.origins });
+        }
+    }
+    /**
+     * Whether middleware marked `authenticates: true` is registered (the
+     * built-in authentication middleware marks itself). The tool and MCP
+     * execution routes ask on every request; `registerAllRoutes()` wires them.
+     */
+    hasAuthenticationMiddleware() {
+        return this.middlewares.some((middleware) => middleware.authenticates === true);
+    }
+    /**
+     * Called by `registerAllRoutes()`: routes that act on the host (tool and
+     * MCP execution) are mounted, so `start()` warns when no authentication
+     * middleware guards them. The check runs at start, when the middleware set
+     * is final, so registering authentication after the routes is fine.
+     */
+    noteSensitiveRoutes(options) {
+        this.sensitiveRoutesRegistered = true;
+        if (options?.allowUnauthenticated) {
+            this.sensitiveRoutesAllowedOpen = true;
+        }
+    }
+    /**
+     * The warning promised by `noteSensitiveRoutes()`, always on stderr: a
+     * `logger.warn` is dropped unless debug logging is on, which would hide a
+     * notice meant for the operator who just started the server.
+     */
+    warnIfSensitiveRoutesUnauthenticated() {
+        if (!this.sensitiveRoutesRegistered ||
+            this.sensitiveRoutesAllowedOpen ||
+            this.hasAuthenticationMiddleware()) {
+            return;
+        }
+        const where = isLoopbackAddress(this.config.host)
+            ? `loopback only (${this.config.host})`
+            : `${this.config.host}, reachable from the network`;
+        logger.alwaysStderr(`[ServerAdapter] WARNING: no authentication middleware is registered and the server listens on ${where}. ` +
+            "The tool and MCP execution routes answer 403 until authentication middleware (marked authenticates: true) is registered, " +
+            "or allowUnauthenticated: true / NEUROLINK_SERVER_ALLOW_UNAUTHENTICATED=1 opts out of that gate.");
+    }
+    /**
+     * Give the handler a way to notice that the client is gone or the request
+     * is over time. The controller is this request's own unless middleware
+     * already attached one that the adapter carried; `applyTimeout` arms the
+     * configured request timeout, which the caller leaves off for a streaming
+     * route (a stream legitimately outlives it, as under Hono's own timeout
+     * middleware). `release()` disarms the timer once the response is written.
+     */
+    attachRequestAbort(ctx, options) {
+        const controller = ctx.abortController ?? new AbortController();
+        ctx.abortController = controller;
+        ctx.abortSignal = controller.signal;
+        let timedOut = false;
+        let timer;
+        const timeoutMs = this.config.timeout;
+        // Node turns an over-range delay into 1 ms; keep long request budgets
+        // at the timer limit, as the readiness deadline does through withTimeout.
+        const delayMs = timeoutMs > MAX_TIMER_MS ? MAX_TIMER_MS : timeoutMs;
+        const deadline = options.applyTimeout && timeoutMs > 0
+            ? new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    timedOut = true;
+                    const error = new ServerTimeoutError(timeoutMs, `${ctx.method} ${ctx.path}`, ctx.requestId);
+                    controller.abort(error);
+                    reject(error);
+                }, delayMs);
+            })
+            : undefined;
+        // A rejection nobody awaits (the handler won on the race) must not
+        // surface as unhandled.
+        deadline?.catch(() => undefined);
+        options.onClientClose(() => {
+            if (!controller.signal.aborted) {
+                controller.abort(new Error("Client disconnected"));
+            }
+        });
+        return {
+            controller,
+            deadline,
+            timedOut: () => timedOut,
+            release: () => {
+                if (timer) {
+                    clearTimeout(timer);
+                    timer = undefined;
+                }
+            },
+        };
     }
     /**
      * The listening Node `http.Server`, once `start()` has run and the runtime
@@ -237,11 +343,17 @@ export class BaseServerAdapter extends EventEmitter {
             }
         }
         // Register all routes in the group with prefix applied
+        const prefix = this.normalizePath(group.prefix);
+        // The group's root segment ("/api" of "/api/health"): a route whose path
+        // already lives under it is a full path, as every built-in route is.
+        // Testing only the whole prefix put `/api/version`, declared in the health
+        // group, at `/api/health/api/version`.
+        const root = `/${prefix.split("/").filter(Boolean)[0] ?? ""}`;
         for (const route of group.routes) {
-            // Only prepend prefix if route path doesn't already start with it
-            // (route definitions include full paths like /api/agent/execute)
-            const needsPrefix = !route.path.startsWith(group.prefix);
-            const prefixedPath = this.normalizePath(needsPrefix ? `${group.prefix}${route.path}` : route.path);
+            const needsPrefix = prefix !== "/" &&
+                !pathStartsWithSegment(route.path, prefix) &&
+                !pathStartsWithSegment(route.path, root);
+            const prefixedPath = this.normalizePath(needsPrefix ? `${prefix}${route.path}` : route.path);
             const prefixedRoute = {
                 ...route,
                 path: prefixedPath,
@@ -336,6 +448,7 @@ export class BaseServerAdapter extends EventEmitter {
             query: options.query ?? {},
             params: options.params ?? {},
             body: options.body,
+            remoteAddress: options.remoteAddress,
             neurolink: this.neurolink,
             toolRegistry: this.toolRegistry,
             externalServerManager: this.externalServerManager,

package/dist/server/adapters/expressAdapter.d.ts

@@ -13,6 +13,7 @@ export declare class ExpressServerAdapter extends BaseServerAdapter {
     private server?;
     private frameworkInitialized;
     private sockets;
+    private warnedNoClientAddress;
     constructor(neurolink: NeuroLink, config?: ServerAdapterConfig);
     /**
      * Initialize Express framework asynchronously
@@ -22,6 +23,8 @@ export declare class ExpressServerAdapter extends BaseServerAdapter {
      * Initialize Express framework with async imports
      */
     private initializeFrameworkAsync;
+    /** The address a request is counted against; `undefined` when there is none. */
+    private clientKeyFor;
     /**
      * Override initialize to ensure async framework setup
      */