@juspay/neurolink 13.8.17 → 13.8.19

package/dist/types/server.d.ts

@@ -9,7 +9,7 @@ import type { MCPToolRegistry } from "../mcp/toolRegistry.js";
 import type { NeuroLink } from "../neurolink.js";
 import type { JsonObject, JsonValue } from "./common.js";
 import type { ExternalMCPServerStatus } from "./externalMcp.js";
-import type { ProxyRuntimeConfigProvider } from "./proxy.js";
+import type { ProxyInboundAuthOptions, ProxyRuntimeConfigProvider } from "./proxy.js";
 import type { TTSAudioFormat } from "./tts.js";
 import type { STTCorrectionOptions, STTDecisionRecord, STTDictionaryEntry, STTEngineInfo, STTFallbackOptions, STTOutputOptions, STTOutputRendering, STTRoutingOptions, STTStreamingOptions, TranscribeTimings } from "./transcribe.js";
 /**
@@ -18,7 +18,12 @@ import type { STTCorrectionOptions, STTDecisionRecord, STTDictionaryEntry, STTEn
 export type ServerAdapterConfig = {
     /** Server port (default: 3000) */
     port?: number;
-    /** Server host (default: "0.0.0.0") */
+    /**
+     * Interface to bind (default: `"127.0.0.1"`, loopback only). Pass
+     * `"0.0.0.0"` or `"::"` to listen on every interface; a server reachable from
+     * the network should register authentication middleware first, since the
+     * tool, MCP and memory routes act on this host.
+     */
     host?: string;
     /** Base path for all routes (default: "/api") */
     basePath?: string;
@@ -140,10 +145,33 @@ export type RateLimitConfig = {
     maxRequests?: number;
     /** Custom error message */
     message?: string;
-    /** Skip rate limiting for certain paths */
+    /**
+     * Skip rate limiting for certain paths. An entry matches the path itself and
+     * everything under it at a segment boundary: `/api/health` matches
+     * `/api/health` and `/api/health/live`, never `/api/healthz`.
+     */
     skipPaths?: string[];
-    /** Custom key generator function */
+    /**
+     * Custom key generator function. Without one, requests are counted per
+     * client address: the TCP peer, or, with `trustProxy`, the client address a
+     * trusted reverse proxy reports in `X-Forwarded-For`.
+     */
     keyGenerator?: (ctx: ServerContext) => string;
+    /**
+     * Read the client address from `X-Forwarded-For` (default: `false`). Off,
+     * the header is ignored and every request is counted against the TCP peer,
+     * so a client cannot pick its own bucket by sending the header. Turn it on
+     * only behind a reverse proxy that overwrites or appends to the header.
+     */
+    trustProxy?: boolean;
+    /**
+     * Addresses of the reverse proxies in front of this server, consulted with
+     * `trustProxy`. Hops listed here are skipped from the right of
+     * `X-Forwarded-For`, so the key is the last hop no trusted proxy added, i.e.
+     * the client the outermost trusted proxy saw. Empty (the default) takes the
+     * rightmost entry, the one the nearest proxy appended.
+     */
+    trustedProxies?: string[];
 };
 /**
  * Required rate limit configuration
@@ -155,6 +183,8 @@ export type RequiredRateLimitConfig = {
     message: string;
     skipPaths?: string[];
     keyGenerator?: (ctx: ServerContext) => string;
+    trustProxy: boolean;
+    trustedProxies: string[];
 };
 /**
  * Body parser configuration
@@ -311,6 +341,12 @@ export type ServerContext = {
     params: Record<string, string>;
     /** Request body (parsed) */
     body?: unknown;
+    /**
+     * The TCP peer's address, as the runtime reports it (`undefined` when the
+     * runtime does not expose it). Never read from a header, so a client cannot
+     * choose it; the rate limiters key on it.
+     */
+    remoteAddress?: string;
     /** NeuroLink SDK instance */
     neurolink: NeuroLink;
     /** Tool registry instance */
@@ -454,10 +490,22 @@ export type MiddlewareDefinition = {
     order?: number;
     /** Middleware handler */
     handler: MiddlewareHandler;
-    /** Paths to apply middleware to (default: all) */
+    /**
+     * Paths to apply middleware to (default: all). An entry matches the path
+     * itself and everything under it at a segment boundary (`/api/agent` matches
+     * `/api/agent/execute`, never `/api/agents`).
+     */
     paths?: string[];
-    /** Paths to exclude from middleware */
+    /** Paths to exclude from middleware, matched the same way as `paths`. */
     excludePaths?: string[];
+    /**
+     * `true` when this middleware authenticates requests (sets `ctx.user` or
+     * refuses). `createAuthMiddleware` and `createBearerAuthMiddleware` set it.
+     * The adapter's `hasAuthenticationMiddleware()` reads it, and so the tool
+     * and MCP execution routes decide whether the server is open to anyone who
+     * can reach it. Set it on your own authentication middleware.
+     */
+    authenticates?: boolean;
 };
 /**
  * Middleware handler function
@@ -1301,6 +1349,14 @@ export type CreateRoutesOptions = {
     codexProxy?: boolean;
     /** Enable the Gemini door on its own, for the same reason. */
     geminiProxy?: boolean;
+    /**
+     * Inbound authentication for the Claude and Codex proxy route groups. The
+     * token defaults to `NEUROLINK_PROXY_INBOUND_TOKEN`; `allowUnauthenticated`
+     * falls back to the top-level `allowUnauthenticated`. Mounting a proxy door
+     * with neither logs a loud warning, because anyone who reaches the port can
+     * spend the pooled subscriptions.
+     */
+    proxyAuth?: ProxyInboundAuthOptions;
     /**
      * Runtime config provider for engines that read it (currently: Codex
      * outbound fallback). NOTE: this option alone cannot make the Codex
@@ -1328,6 +1384,31 @@ export type CreateRoutesOptions = {
      * the top-level `perUserAuth`, which is why it is not accepted here.
      */
     agent?: Omit<ServerAgentRouteOptions, "perUserAuth">;
+    /**
+     * `false` leaves the tool routes (`GET/POST <basePath>/tools/*`) out. They
+     * execute whatever the server's registry holds, including the built-in
+     * filesystem tools when those are enabled, so a server that only generates
+     * text has no reason to mount them. Default: mounted.
+     */
+    tools?: boolean;
+    /**
+     * Serve the tool and MCP execution routes to callers the server has not
+     * authenticated. By default those routes answer 403 whenever the server has
+     * no authentication middleware (see `hasAuthentication`), because they run
+     * tools and remove MCP servers on behalf of anyone who can reach the port.
+     * `true` restores the open behaviour for a server that is protected some
+     * other way (a reverse proxy, a private network). The environment variable
+     * `NEUROLINK_SERVER_ALLOW_UNAUTHENTICATED=1` has the same effect.
+     */
+    allowUnauthenticated?: boolean;
+    /**
+     * Tells the tool and MCP execution routes whether the server authenticates
+     * its callers; read on every request. `registerAllRoutes()` supplies one
+     * that asks the adapter for middleware marked `authenticates: true`. With
+     * neither this nor `allowUnauthenticated`, `createAllRoutes()` cannot tell
+     * and leaves those routes open, as before.
+     */
+    hasAuthentication?: () => boolean;
     /**
      * Set to `true` when the authentication middleware identifies individual
      * people (one credential per person). The agent routes then take `userId`
@@ -1365,6 +1446,54 @@ export type CreateRoutesOptions = {
      */
     perUserAuth?: boolean;
 };
+/**
+ * Options of the route groups that act on the host (tool execution, MCP
+ * server execution and removal). `createAllRoutes` derives them from
+ * `CreateRoutesOptions.allowUnauthenticated` / `hasAuthentication`.
+ */
+export type ServerSensitiveRouteOptions = {
+    /**
+     * Whether the server authenticates its callers, read on every request. When
+     * it answers `false` the execution routes refuse with 403. Omitted, the
+     * routes cannot tell and stay open.
+     */
+    hasAuthentication?: () => boolean;
+    /** Serve the execution routes to unauthenticated callers regardless. */
+    allowUnauthenticated?: boolean;
+};
+/** `neurolink serve` flags that relax its network hardening. */
+export type ServerServeHardeningArgs = {
+    /**
+     * `--allow-unauthenticated`: listen on a non-loopback host without
+     * `NEUROLINK_SERVER_API_KEY`, and serve the tool and MCP execution routes
+     * to anyone who can reach the port.
+     */
+    allowUnauthenticated?: boolean;
+    /**
+     * `--enable-builtin-tools`: keep NeuroLink's built-in tools (file reads and
+     * writes under the server's working directory among them) in the server's
+     * registry. Off by default, so `/tools/execute` and the agent routes cannot
+     * reach the host's filesystem.
+     */
+    enableBuiltinTools?: boolean;
+};
+/** What a route may tell the client about a failure, with the status to send it under. */
+export type ServerClientFacingError = {
+    code: string;
+    message: string;
+    status: number;
+};
+/** What `resolveClientAddress()` needs to name the client of a request. */
+export type ServerClientAddressInput = {
+    /** The TCP peer, as the runtime reports it. */
+    remoteAddress: string | undefined;
+    /** The request's `X-Forwarded-For` header, if any. */
+    forwardedFor: string | undefined;
+    /** Consult `forwardedFor` at all. */
+    trustProxy: boolean;
+    /** Reverse proxies whose hops are skipped from the right of `forwardedFor`. */
+    trustedProxies: readonly string[];
+};
 /** Options for `createTranscribeRoutes()`. */
 /**
  * What `GET /agent/transcribe/providers` reports: the engines this server
@@ -1414,7 +1543,10 @@ export type ServerTranscribeRouteOptions = {
     openaiBasePath?: string;
     /**
      * The STT evaluation collector, `POST <openaiBasePath>/v1/evals/stt`.
-     * On by default; `false` removes its routes.
+     * Off by default: it stores every transcript a caller posts and lets any
+     * caller read them back. Pass an options object (`{}` for the defaults) to
+     * mount it, or set `NEUROLINK_STT_EVAL_ENABLED=1`; `false` keeps it off
+     * whatever the environment says.
      */
     evals?: ServerSTTEvalOptions | false;
 };
@@ -1429,6 +1561,12 @@ export type ServerSTTEvalOptions = {
     maxCalls?: number;
     /** Segments kept per call; later new ids are counted as `ignored`. Default 50,000. */
     maxSegmentsPerCall?: number;
+    /**
+     * Bytes of segment text and metadata held in memory across every call;
+     * when a batch pushes the total over it the least recently updated calls
+     * are evicted (still on disk when `dir` is set). Default 64 MiB.
+     */
+    maxBytes?: number;
 };
 /** One finalized transcript segment, from the STT people saw or the one run alongside it. */
 export type ServerSTTEvalSegment = {
@@ -1461,6 +1599,10 @@ export type ServerSTTEvalBatchRequest = {
     };
     segments: ServerSTTEvalSegment[];
 };
+/** One line of a call's JSON-lines file: the batch as sent, plus who sent it when the server knew. */
+export type ServerSTTEvalStoredBatch = ServerSTTEvalBatchRequest & {
+    owner?: string;
+};
 /** Answer to `POST /v1/evals/stt`. */
 export type ServerSTTEvalBatchResponse = {
     call_id: string;
@@ -1555,6 +1697,14 @@ export type ServerSTTEvalCallRecord = {
     batches: Set<number>;
     segments: Map<string, ServerSTTEvalSegment>;
     updatedAt: number;
+    /** Approximate bytes the call's segments take in memory; what `maxBytes` budgets. */
+    bytes: number;
+    /**
+     * The authenticated caller that created the call, when the server identified
+     * one; the call is then listed and readable only by that caller. `undefined`
+     * for a call made under no authentication or a shared key.
+     */
+    owner?: string;
 };
 /** Word edit distance between two readings, and the reference's word count. */
 export type ServerSTTEvalAlignment = {
@@ -1652,11 +1802,57 @@ export type ServerTranscribeWebSocketOptions = {
     /** Upgrade path. Default `/v1/audio/transcriptions/stream`. */
     path?: string;
     /**
-     * Token(s) required on the upgrade (`Authorization: Bearer` header or
-     * `?token=`). `neurolink serve` passes the same keys as its HTTP routes
-     * (`NEUROLINK_SERVER_API_KEY`, comma-separated), so one setting guards both.
+     * Token(s) required on the upgrade, as `Authorization: Bearer <token>` or,
+     * for a browser (which cannot set headers), as the subprotocol
+     * `neurolink-api-key.<token>` offered next to `neurolink` in
+     * `Sec-WebSocket-Protocol` (the realtime path also takes OpenAI's
+     * `openai-insecure-api-key.<token>`). `neurolink serve` passes the same keys
+     * as its HTTP routes (`NEUROLINK_SERVER_API_KEY`, comma-separated), so one
+     * setting guards both.
      */
     authToken?: string | readonly string[];
+    /**
+     * Also accept the token as `?token=<token>` in the upgrade URL (default:
+     * `false`). A URL is written to access logs, proxies and `Referer` headers,
+     * so a key carried there leaks; prefer the subprotocol carrier.
+     */
+    allowQueryToken?: boolean;
+    /**
+     * Most sockets open at once across every path this attaches (default 100).
+     * A further upgrade is answered `503 Service Unavailable` before the
+     * handshake, so it costs no transcription engine.
+     */
+    maxConnections?: number;
+    /** Most sockets open at once from one remote address (default 16); the next is answered 503. */
+    maxConnectionsPerAddress?: number;
+    /**
+     * Queued audio bytes per socket above which the socket is paused until the
+     * engine catches up (TCP backpressure; default 8 MiB). Audio beyond
+     * `maxQueuedBytes` (16 MiB live, 512 MiB in file mode) still closes the
+     * socket with 1009.
+     */
+    highWaterMark?: number;
+    /**
+     * Queued audio bytes across every socket of this process (default 512 MiB).
+     * A socket whose frame would push the total past it is closed with 1013
+     * (try again later), so one burst of uploads cannot take the process down.
+     */
+    maxTotalQueuedBytes?: number;
+    /**
+     * Serve `mode: "file"` (whole recordings, buffered up to 512 MiB a socket)
+     * to callers the server has not authenticated while it listens on a
+     * non-loopback address (default: `false`, such a request is refused with
+     * 1008). With `authToken` set, or on a loopback listener, file mode is open.
+     */
+    allowUnauthenticatedFileMode?: boolean;
+    /**
+     * Require a session secret (default: `false`). A speaker that opens a
+     * session may pass `?secret=<value>`; from then on every speaker and
+     * listener joining that `?session=` must present the same secret, or is
+     * refused with 1008. `true` refuses a new session that sets no secret, so
+     * no session can be joined by guessing its id.
+     */
+    requireSessionSecret?: boolean;
     /**
      * Browser origins allowed to upgrade. A browser always sends `Origin` on a
      * WebSocket upgrade, and an upgrade whose `Origin` is not listed is refused

package/dist/types/tools.d.ts

@@ -447,6 +447,63 @@ export type AllToolsMap = {
     writeFile: Tool;
     executeBashCommand?: Tool;
 };
+/**
+ * Outcome of evaluating a `calculateMath` expression with the built-in
+ * arithmetic parser (no dynamic code). A result that is not a finite number
+ * is reported as an error rather than as `Infinity`/`NaN`.
+ */
+export type ArithmeticEvaluation = {
+    ok: true;
+    value: number;
+} | {
+    ok: false;
+    error: string;
+};
+/** One lexical token of a `calculateMath` expression (`at` is its offset). */
+export type ArithmeticToken = {
+    kind: "number";
+    value: number;
+    at: number;
+} | {
+    kind: "identifier";
+    name: string;
+    at: number;
+} | {
+    kind: "operator";
+    value: "+" | "-" | "*" | "/" | "%" | "**";
+    at: number;
+} | {
+    kind: "paren";
+    value: "(" | ")";
+    at: number;
+} | {
+    kind: "comma";
+    at: number;
+} | {
+    kind: "end";
+    at: number;
+};
+/** A JSON Schema node as the JSON-Schema-to-Zod converter walks it. */
+export type SchemaConversionNode = Record<string, unknown>;
+/** State threaded through one JSON-Schema-to-Zod conversion. */
+export type SchemaConversionContext = {
+    /** The document root, for resolving local `$ref`s. */
+    root: SchemaConversionNode;
+    /** `$ref` targets on the current path, so a self-referential schema terminates. */
+    refStack: Set<string>;
+    /** Called for each `pattern` the converter refused to compile. */
+    onRegexDrop: (drop: SchemaRegexDrop) => void;
+};
+/**
+ * One regular expression removed from a JSON Schema before the schema is
+ * compiled, because `vetRegexPattern` judged it able to stall the process.
+ * `path` is the JSON-pointer-like location of the keyword (`properties/name/pattern`).
+ */
+export type SchemaRegexDrop = {
+    path: string;
+    pattern: string;
+    reason: string;
+};
 /**
  * Tool registry entry
  */

package/dist/types/transcribe.d.ts

@@ -29,6 +29,7 @@
 import type { ZodUnknownSchema } from "./aliases.js";
 import type { TTSAudioFormat } from "./tts.js";
 import type { STTHandler, STTOptions, STTResult, TranscriptionSegment, WordTiming } from "./stt.js";
+import type { AttachmentPolicy } from "./attachments.js";
 /**
  * Audio for `transcribe()`: bytes, a path or `file://` / `http(s)://` URL, or
  * an async stream of PCM16LE frames (see `STTStreamingOptions.sampleRate`).
@@ -781,6 +782,11 @@ export type TranscribeDeps = STTCorrectionDeps & {
     /** Resolves `undefined`, `""` or an alias to a registered provider name, or throws a typed error. */
     resolveProvider: (name?: string) => string;
     getHandler: (name: string) => STTHandler | undefined;
+    /**
+     * Attachment policy applied when `audio` is a path or URL. The
+     * environment-derived default applies when absent.
+     */
+    attachmentPolicy?: AttachmentPolicy;
 };
 /** Resolved endpointer tuning: `STTStreamingOptions` with every default applied, plus the input rate. */
 export type STTEndpointerConfig = {

package/dist/utils/attachmentPolicy.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Attachment policy — one answer for every SDK loader that turns a
+ * caller-supplied string into bytes.
+ *
+ * Two primitives, both policy-aware:
+ *
+ *   - {@link readAttachmentFile}: realpath containment in `allowedRoots`
+ *     (when configured), `O_NOFOLLOW` open on the real path, regular files
+ *     only, size-capped read that notices a file growing under it.
+ *   - {@link downloadAttachment}: `safeDownloadWithMeta` with the policy's
+ *     URL switches — HTTPS-only and public hosts by default, redirects
+ *     re-validated per hop, caller headers never replayed across one.
+ *
+ * The policy itself is resolved by {@link resolveAttachmentPolicy} from the
+ * constructor's `attachments` config and the `NEUROLINK_ATTACHMENT_*`
+ * variables, and travels on the per-call options (`attachmentPolicy`). A
+ * loader that is reached without one — a host calling `WebLoader` directly, a
+ * processor used on its own — falls back to the environment-derived default,
+ * so the operator switches apply everywhere.
+ *
+ * @module utils/attachmentPolicy
+ */
+import type { AttachmentDownloadOptions, AttachmentPolicy, AttachmentReadOptions, AttachmentReadResult, AttachmentRefusalCode, AttachmentsConfig, SafeDownloadResult } from "../types/index.js";
+/**
+ * An error the loaders throw when the policy refuses an attachment. Carries a
+ * stable `code`; the message names the option that would allow the read.
+ */
+export declare class AttachmentRefusedError extends Error {
+    readonly code: AttachmentRefusalCode;
+    constructor(code: AttachmentRefusalCode, message: string, cause?: unknown);
+}
+/**
+ * Resolve the policy an instance runs under. An explicit config field wins
+ * over its environment variable; the defaults are the safe ones.
+ */
+export declare function resolveAttachmentPolicy(config?: AttachmentsConfig): AttachmentPolicy;
+/** Runtime guard for a policy that travelled on an untyped options bag. */
+export declare function isAttachmentPolicy(value: unknown): value is AttachmentPolicy;
+/**
+ * The policy stamped on a call's options, or the environment-derived default.
+ * Accepts any options bag so loaders deep in the file pipeline can read it off
+ * whatever reached them.
+ */
+export declare function getAttachmentPolicy(carrier: {
+    attachmentPolicy?: unknown;
+} | undefined | null): AttachmentPolicy;
+/** The lower of a loader's own cap and the policy's global cap. */
+export declare function effectiveAttachmentCap(policy: AttachmentPolicy, loaderCap: number): number;
+/**
+ * Check `filePath` against the policy's roots and return the real path to
+ * open. Without roots the real path is still resolved (so the later
+ * `O_NOFOLLOW` open behaves identically for a symlinked input), and the
+ * one-time warning fires.
+ *
+ * @throws {AttachmentRefusedError} `ATTACHMENT_OUTSIDE_ROOTS`
+ */
+export declare function resolveAttachmentPath(filePath: string, policy: AttachmentPolicy, label: string): Promise<string>;
+/**
+ * Read a local attachment under the policy.
+ *
+ * Containment is judged on the real path (see {@link resolveAttachmentPath});
+ * the open is `O_NOFOLLOW | O_NONBLOCK` on that real path so a symlink swapped
+ * in after the check is refused by the kernel and a FIFO cannot park a worker;
+ * the descriptor is then stat'd (regular files only, size under the cap) and
+ * drained under the same cap.
+ *
+ * @throws {AttachmentRefusedError} with `ATTACHMENT_OUTSIDE_ROOTS`,
+ *   `ATTACHMENT_NOT_A_FILE` or `ATTACHMENT_TOO_LARGE`; other file-system
+ *   errors (ENOENT, EACCES, ELOOP, …) propagate unchanged.
+ */
+export declare function readAttachmentFile(filePath: string, options: AttachmentReadOptions): Promise<AttachmentReadResult>;
+/**
+ * Quick scheme check that names the switch, so a refused `http://` URL tells
+ * the caller what to set rather than only that HTTPS is required.
+ *
+ * @throws {AttachmentRefusedError} `ATTACHMENT_URL_REFUSED`
+ */
+export declare function assertAttachmentUrlScheme(url: string, policy: AttachmentPolicy, label: string): void;
+/**
+ * Download a caller-supplied URL under the policy. Builds on
+ * `safeDownloadWithMeta`: DNS-pinned connection, bounded body, redirects only
+ * when the policy allows and then re-validated per hop with the caller's
+ * headers dropped.
+ *
+ * @throws {AttachmentRefusedError} `ATTACHMENT_URL_REFUSED` when the URL is
+ *   refused by the policy or the SSRF guard; transport and HTTP errors
+ *   propagate as plain errors from `safeDownloadWithMeta`.
+ */
+export declare function downloadAttachment(url: string, options: AttachmentDownloadOptions): Promise<SafeDownloadResult>;