@juspay/neurolink 13.8.16 → 13.8.18

package/dist/server/utils/expressBody.js

@@ -0,0 +1,353 @@
+/**
+ * Bounded JSON and form body reads for the Express adapter.
+ *
+ * `express.json()` and `express.urlencoded()` (body-parser) refuse a body over
+ * their limit with a 413, but only after the whole request has been taken off
+ * the socket: a declared Content-Length over the limit is seen at once and the
+ * body is still drained, and a chunked body is read to its end. Nothing has
+ * authenticated the request at that point, so a client could make the server
+ * receive any amount of data for the price of one 413.
+ *
+ * `createBoundedBodyParser` wraps a body-parser middleware so the bytes are
+ * read here, up to the limit, and handed to that same middleware to parse. Which
+ * requests are parsed, charset handling, strict JSON, the qs options and the
+ * error each failure carries all stay body-parser's, because body-parser still
+ * makes those decisions: it is asked first, from the headers alone, whether it
+ * would read the request, and then parses the bytes it is given. What changes is
+ * who reads the socket and what happens at the limit. A body over the limit is
+ * refused without reading it (declared Content-Length) or at the limit (chunked,
+ * or a compressed body that inflates past it), and the connection is closed so
+ * the client stops sending.
+ *
+ * `express.raw()` (uploads) is not wrapped.
+ *
+ * @module server/utils/expressBody
+ */
+import { Readable } from "node:stream";
+import * as zlib from "node:zlib";
+import { tryParseByteLimit } from "./rawBody.js";
+const noop = () => undefined;
+/** The error body-parser raises for an over-limit body, which the adapter's error handler answers 413. */
+function bodyParserError(status, message, type, details = {}) {
+    return Object.assign(new Error(message), {
+        status,
+        statusCode: status,
+        expose: status < 500,
+        type,
+        ...details,
+    });
+}
+const entityTooLarge = (limit, received) => bodyParserError(413, "request entity too large", "entity.too.large", {
+    limit,
+    ...(received === undefined ? {} : { received }),
+});
+/** A Content-Encoding body-parser inflates, and nothing else. */
+function decompressorFor(encoding) {
+    switch (encoding) {
+        case "gzip":
+            return zlib.createGunzip;
+        case "deflate":
+            return zlib.createInflate;
+        case "br":
+            return zlib.createBrotliDecompress;
+        case "zstd":
+            // Node 22.15 and later.
+            return typeof zlib.createZstdDecompress === "function"
+                ? zlib.createZstdDecompress
+                : undefined;
+        default:
+            return undefined;
+    }
+}
+/** body-parser's own "already handled" test: the request has been read off, or cannot be. */
+const isRequestFinished = (req) => ("upgrade" in req && req.upgrade === true) ||
+    !req.socket?.readable ||
+    (req.complete && !req.readable);
+/** A request that is already in memory, to hand a body-parser middleware in place of the socket. */
+function bufferedRequest(headers, bytes, body) {
+    let pushed = false;
+    const stream = new Readable({
+        read() {
+            if (!pushed) {
+                pushed = true;
+                if (bytes.length > 0) {
+                    this.push(bytes);
+                }
+                this.push(null);
+            }
+        },
+    });
+    return Object.assign(stream, { headers, body });
+}
+/**
+ * Ask a body-parser middleware what it would do with this request, without
+ * giving it a body. It is run on an empty one: what it decides from the headers
+ * (not a body, not its type, a charset it refuses) comes back as it would
+ * have, and so does what it only finds out when it starts to read (a charset
+ * the decoder lacks). The Content-Encoding is left off because inflating is
+ * done here, and the Content-Length is zeroed so the declared size, which is
+ * checked here, does not stand in the way.
+ */
+function askParser(parser, req, res) {
+    const headers = { ...req.headers };
+    delete headers["content-encoding"];
+    delete headers["transfer-encoding"];
+    if (req.headers["transfer-encoding"] !== undefined ||
+        req.headers["content-length"] !== undefined) {
+        headers["content-length"] = "0";
+    }
+    const before = "body" in req ? req.body : undefined;
+    const probe = bufferedRequest(headers, Buffer.alloc(0), before);
+    return new Promise((resolve) => {
+        let synchronous = true;
+        parser(probe, res, (error) => {
+            if (error !== undefined) {
+                resolve({ kind: "reject", error, beforeRead: synchronous });
+            }
+            else if (probe.body !== before) {
+                resolve({ kind: "parse" });
+            }
+            else {
+                resolve({ kind: "skip", body: probe.body });
+            }
+        });
+        synchronous = false;
+    });
+}
+/**
+ * How far past the limit the raw bytes of a compressed body may run. The limit
+ * is on what a body inflates to, but the bytes on the wire are capped too:
+ * empty gzip members inflate to nothing, and so do the zeros Node lets follow a
+ * complete gzip stream, so without a cap a stream of either is read until the
+ * client stops. The slack covers the framing a real encoder adds (deflate's
+ * stored blocks carry 5 bytes per 64 KiB).
+ */
+const COMPRESSED_WIRE_SLACK = 64 * 1024;
+/**
+ * Read a request body, refusing more than `maxBytes` (of what is inflated, when
+ * the request is compressed, with the raw bytes capped at `maxBytes` plus
+ * {@link COMPRESSED_WIRE_SLACK}). Reading stops at the limit and the request is
+ * left paused, not drained. Events rather than `for await`: leaving an async
+ * iterator early destroys the request, and its socket with it, before an answer
+ * can be sent.
+ */
+function readBounded(req, maxBytes, decompressor) {
+    return new Promise((resolve, reject) => {
+        const source = decompressor ?? req;
+        const chunks = [];
+        const wireCap = maxBytes + COMPRESSED_WIRE_SLACK;
+        let received = 0;
+        let wire = 0;
+        // A compressed body is complete; the rest of the request is being read off.
+        let draining = false;
+        let settled = false;
+        const release = () => {
+            source.off("data", onData);
+            source.off("end", onEnd);
+            source.off("error", onFail);
+            req.off("data", onWire);
+            req.off("end", onRequestEnd);
+            req.off("error", onFail);
+            req.off("close", onClose);
+        };
+        const detachDecompressor = () => {
+            if (decompressor) {
+                req.unpipe(decompressor);
+                decompressor.on("error", noop);
+                decompressor.destroy();
+            }
+        };
+        const stop = () => {
+            detachDecompressor();
+            req.pause();
+        };
+        const settle = (outcome) => {
+            if (!settled) {
+                settled = true;
+                release();
+                outcome();
+            }
+        };
+        const finish = (closeConnection) => {
+            settle(() => resolve({ bytes: Buffer.concat(chunks), closeConnection }));
+        };
+        const aborted = () => bodyParserError(400, "request aborted", "request.aborted", {
+            code: "ECONNABORTED",
+            received,
+        });
+        function onData(chunk) {
+            const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+            received += buffer.length;
+            if (received > maxBytes) {
+                settle(() => {
+                    stop();
+                    reject(entityTooLarge(maxBytes, received));
+                });
+                return;
+            }
+            chunks.push(buffer);
+        }
+        function onWire(chunk) {
+            wire += chunk.length;
+            if (wire <= wireCap) {
+                return;
+            }
+            if (draining) {
+                // The body is whole; what keeps arriving is not part of it.
+                req.pause();
+                finish(true);
+                return;
+            }
+            settle(() => {
+                stop();
+                reject(entityTooLarge(maxBytes, wire));
+            });
+        }
+        function onEnd() {
+            if (!decompressor) {
+                finish(false);
+                return;
+            }
+            // The rest of the request, if any, is not part of the body: read it off
+            // up to the cap, so the connection can be kept.
+            detachDecompressor();
+            if (req.complete) {
+                req.resume();
+                finish(false);
+                return;
+            }
+            draining = true;
+            source.off("data", onData);
+            source.off("end", onEnd);
+            source.off("error", onFail);
+            req.on("end", onRequestEnd);
+            req.resume();
+        }
+        function onRequestEnd() {
+            finish(false);
+        }
+        function onFail(error) {
+            if (draining) {
+                finish(true);
+                return;
+            }
+            settle(() => {
+                stop();
+                reject(error);
+            });
+        }
+        function onClose() {
+            // A request that arrived whole closes once it has been read, which for a
+            // compressed one can be before the inflating has finished.
+            if (req.complete) {
+                return;
+            }
+            if (draining) {
+                finish(true);
+                return;
+            }
+            settle(() => {
+                stop();
+                reject(aborted());
+            });
+        }
+        if (req.destroyed && !req.complete) {
+            settle(() => reject(aborted()));
+            return;
+        }
+        source.on("data", onData);
+        source.on("end", onEnd);
+        source.on("error", onFail);
+        req.on("close", onClose);
+        if (decompressor) {
+            req.on("error", onFail);
+            req.on("data", onWire);
+            req.pipe(decompressor);
+        }
+    });
+}
+/** Answer the request with `error` and close the connection, so a client still sending stops. */
+function refuse(res, next, error) {
+    if (!res.headersSent) {
+        res.setHeader("Connection", "close");
+    }
+    next(error);
+}
+async function parseBounded(parser, maxBytes, req, res, next) {
+    try {
+        if (isRequestFinished(req)) {
+            next();
+            return;
+        }
+        const verdict = await askParser(parser, req, res);
+        if (verdict.kind === "skip") {
+            req.body = verdict.body;
+            next();
+            return;
+        }
+        if (verdict.kind === "reject" && verdict.beforeRead) {
+            refuse(res, next, verdict.error);
+            return;
+        }
+        const encoding = (req.headers["content-encoding"] || "identity").toLowerCase();
+        const inflate = encoding === "identity" ? undefined : decompressorFor(encoding);
+        if (encoding !== "identity" && !inflate) {
+            refuse(res, next, bodyParserError(415, `unsupported content encoding "${encoding}"`, "encoding.unsupported", { encoding }));
+            return;
+        }
+        // Compressed, the declared length is the compressed size, which says
+        // nothing about the body.
+        const declared = Number.parseInt(String(req.headers["content-length"]), 10);
+        if (!inflate && declared > maxBytes) {
+            refuse(res, next, entityTooLarge(maxBytes));
+            return;
+        }
+        if (verdict.kind === "reject") {
+            refuse(res, next, verdict.error);
+            return;
+        }
+        const before = "body" in req ? req.body : undefined;
+        let read;
+        try {
+            read = await readBounded(req, maxBytes, inflate?.());
+        }
+        catch (error) {
+            refuse(res, next, error);
+            return;
+        }
+        if (read.closeConnection && !res.headersSent) {
+            res.setHeader("Connection", "close");
+        }
+        const { bytes } = read;
+        const headers = { ...req.headers, "content-length": String(bytes.length) };
+        delete headers["content-encoding"];
+        delete headers["transfer-encoding"];
+        const replay = bufferedRequest(headers, bytes, before);
+        parser(replay, res, (error) => {
+            if (error !== undefined) {
+                next(error);
+                return;
+            }
+            req.body = replay.body;
+            next();
+        });
+    }
+    catch (error) {
+        next(error);
+    }
+}
+/**
+ * Wrap a body-parser middleware (`express.json()`, `express.urlencoded()`) so a
+ * body is read only as far as `limit`. `limit` is the one the middleware was
+ * built with. A limit that cannot be read as a byte count here is left to the
+ * middleware alone.
+ */
+export function createBoundedBodyParser(parser, limit) {
+    const maxBytes = tryParseByteLimit(limit);
+    if (maxBytes === undefined) {
+        return parser;
+    }
+    return (req, res, next) => {
+        void parseBounded(parser, maxBytes, req, res, next);
+    };
+}

package/dist/server/utils/pathMatch.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Path matching shared by the adapters' middleware `paths` / `excludePaths`
+ * and the rate limiters' `skipPaths`.
+ *
+ * Every match is at a segment boundary: a pattern names the path itself and
+ * what lies under it as a directory would, so `/api/health` covers
+ * `/api/health` and `/api/health/live` but not `/api/healthz`. The plain
+ * prefix test the adapters used to run let the second be exempted by the
+ * first.
+ *
+ * @module server/utils/pathMatch
+ */
+/** The request path without its query string or fragment. */
+export declare function stripQuery(path: string): string;
+/**
+ * `true` when `path` is `prefix`, or lies under `prefix` at a segment
+ * boundary. `"*"`, `""` and `"/"` match every path.
+ */
+export declare function pathStartsWithSegment(path: string, prefix: string): boolean;
+/** `true` when any of `prefixes` matches `path` (see {@link pathStartsWithSegment}). */
+export declare function pathMatchesAny(path: string, prefixes: readonly string[] | undefined): boolean;

package/dist/server/utils/pathMatch.js

@@ -0,0 +1,41 @@
+/**
+ * Path matching shared by the adapters' middleware `paths` / `excludePaths`
+ * and the rate limiters' `skipPaths`.
+ *
+ * Every match is at a segment boundary: a pattern names the path itself and
+ * what lies under it as a directory would, so `/api/health` covers
+ * `/api/health` and `/api/health/live` but not `/api/healthz`. The plain
+ * prefix test the adapters used to run let the second be exempted by the
+ * first.
+ *
+ * @module server/utils/pathMatch
+ */
+/** The request path without its query string or fragment. */
+export function stripQuery(path) {
+    const cut = path.search(/[?#]/);
+    return cut === -1 ? path : path.slice(0, cut);
+}
+/** Collapse repeated slashes and drop a trailing one, keeping the root `/`. */
+function normalize(path) {
+    const collapsed = path.replace(/\/{2,}/g, "/");
+    return collapsed.length > 1 ? collapsed.replace(/\/+$/, "") : collapsed;
+}
+/**
+ * `true` when `path` is `prefix`, or lies under `prefix` at a segment
+ * boundary. `"*"`, `""` and `"/"` match every path.
+ */
+export function pathStartsWithSegment(path, prefix) {
+    if (prefix === "*" || prefix === "" || prefix === "/") {
+        return true;
+    }
+    const target = normalize(stripQuery(path));
+    const base = normalize(prefix);
+    return target === base || target.startsWith(`${base}/`);
+}
+/** `true` when any of `prefixes` matches `path` (see {@link pathStartsWithSegment}). */
+export function pathMatchesAny(path, prefixes) {
+    if (!prefixes || prefixes.length === 0) {
+        return false;
+    }
+    return prefixes.some((prefix) => pathStartsWithSegment(path, prefix));
+}

package/dist/server/utils/validation.d.ts

@@ -57,6 +57,15 @@ export declare const WebSocketAgentRequestSchema: z.ZodObject<{
         maxSteps: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/**
+ * WebSocket `tool_call` message payload schema: a tool name the registry can
+ * look up and a JSON object of arguments. The payload used to reach
+ * `executeTool` unchecked.
+ */
+export declare const WebSocketToolCallSchema: z.ZodObject<{
+    toolName: z.ZodString;
+    args: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strip>;
 /**
  * Tool execute request schema
  */

package/dist/server/utils/validation.js

@@ -55,6 +55,15 @@ export const WebSocketAgentRequestSchema = z.object({
     prompt: z.string().min(1, "Prompt is required"),
     options: WebSocketAgentOptionsSchema.optional(),
 });
+/**
+ * WebSocket `tool_call` message payload schema: a tool name the registry can
+ * look up and a JSON object of arguments. The payload used to reach
+ * `executeTool` unchecked.
+ */
+export const WebSocketToolCallSchema = z.object({
+    toolName: z.string().min(1, "toolName is required").max(256),
+    args: z.record(z.string(), z.unknown()).optional().default({}),
+});
 /**
  * Tool execute request schema
  */

package/dist/server/websocket/WebSocketHandler.js

@@ -6,7 +6,7 @@
  */
 import { WebSocketError, WebSocketConnectionError } from "../errors.js";
 import { logger } from "../../utils/logger.js";
-import { WebSocketAgentRequestSchema } from "../utils/validation.js";
+import { WebSocketAgentRequestSchema, WebSocketToolCallSchema, } from "../utils/validation.js";
 /**
  * Default WebSocket configuration
  */
@@ -36,7 +36,20 @@ export class WebSocketConnectionManager {
     pingIntervals = new Map();
     handlers = new Map();
     constructor(config = {}) {
-        this.config = { ...DEFAULT_CONFIG, ...config };
+        // A strategy other than "none" means the deployer wants callers
+        // identified, so `required` defaults to true with it: a config that named
+        // a strategy and forgot `required` used to get an open socket.
+        const strategy = config.auth?.strategy ?? DEFAULT_CONFIG.auth.strategy;
+        this.config = {
+            ...DEFAULT_CONFIG,
+            ...config,
+            auth: {
+                ...DEFAULT_CONFIG.auth,
+                ...config.auth,
+                strategy,
+                required: config.auth?.required ?? strategy !== "none",
+            },
+        };
     }
     /**
      * Register a handler for a path
@@ -498,7 +511,13 @@ export function createAgentWebSocketHandler(neurolink) {
         return clientPresent ? { type: "stream_complete" } : undefined;
     });
     router.route("tool_call", async (connection, payload) => {
-        const { toolName, args } = payload;
+        const parsed = WebSocketToolCallSchema.safeParse(payload);
+        if (!parsed.success) {
+            throw new WebSocketError(`Invalid tool_call payload: ${parsed.error.issues
+                .map((issue) => `${issue.path.join(".") || "payload"} ${issue.message}`)
+                .join("; ")}`, undefined, connection.id);
+        }
+        const { toolName, args } = parsed.data;
         const result = await neurolink.executeTool(toolName, args);
         return { type: "tool_result", toolName, result };
     });

package/dist/server/websocket/frameQueue.d.ts

@@ -2,15 +2,34 @@
  * Push-driven async iterable shared by the transcription sockets: socket
  * frames are pushed in, `transcribeStream()` pulls them out.
  *
+ * The queue reports its level to whoever feeds it, so a socket can be paused
+ * when audio arrives faster than the engine takes it and resumed once the
+ * backlog drains (TCP backpressure, instead of buffering the whole burst).
+ * Every queue also charges its bytes to one process-wide budget, so a burst
+ * of uploads across many sockets cannot exhaust the process.
+ *
  * @module server/websocket/frameQueue
  */
+/** What every queue in the process holds right now, for caps and tests. */
+export declare function totalQueuedFrameBytes(): number;
 /** Push-driven async iterable: socket frames in, `transcribeStream()` pulls. */
 export declare class FrameQueue implements AsyncIterable<Buffer> {
     private readonly frames;
     private waiting;
     private ended;
+    private onLevel;
     queuedBytes: number;
+    /** Called after every change of `queuedBytes`, with the new level. */
+    setLevelListener(listener: ((queuedBytes: number) => void) | undefined): void;
     push(frame: Buffer): void;
+    /**
+     * No more frames will arrive; the ones already queued are still handed
+     * out, so a recording whose `end` frame followed its audio is transcribed
+     * whole. The consumer's `return()` (see below) is what discards.
+     */
     end(): void;
+    /** The consumer is gone: whatever it did not pull leaves the process budget. */
+    private discard;
+    private charge;
     [Symbol.asyncIterator](): AsyncIterator<Buffer>;
 }

package/dist/server/websocket/frameQueue.js

@@ -2,14 +2,31 @@
  * Push-driven async iterable shared by the transcription sockets: socket
  * frames are pushed in, `transcribeStream()` pulls them out.
  *
+ * The queue reports its level to whoever feeds it, so a socket can be paused
+ * when audio arrives faster than the engine takes it and resumed once the
+ * backlog drains (TCP backpressure, instead of buffering the whole burst).
+ * Every queue also charges its bytes to one process-wide budget, so a burst
+ * of uploads across many sockets cannot exhaust the process.
+ *
  * @module server/websocket/frameQueue
  */
+/** Queued bytes across every `FrameQueue` of this process. */
+let processQueuedBytes = 0;
+/** What every queue in the process holds right now, for caps and tests. */
+export function totalQueuedFrameBytes() {
+    return processQueuedBytes;
+}
 /** Push-driven async iterable: socket frames in, `transcribeStream()` pulls. */
 export class FrameQueue {
     frames = [];
     waiting;
     ended = false;
+    onLevel;
     queuedBytes = 0;
+    /** Called after every change of `queuedBytes`, with the new level. */
+    setLevelListener(listener) {
+        this.onLevel = listener;
+    }
     push(frame) {
         if (this.ended) {
             return;
@@ -21,9 +38,17 @@ export class FrameQueue {
             return;
         }
         this.frames.push(frame);
-        this.queuedBytes += frame.length;
+        this.charge(frame.length);
     }
+    /**
+     * No more frames will arrive; the ones already queued are still handed
+     * out, so a recording whose `end` frame followed its audio is transcribed
+     * whole. The consumer's `return()` (see below) is what discards.
+     */
     end() {
+        if (this.ended) {
+            return;
+        }
         this.ended = true;
         if (this.waiting) {
             const resolve = this.waiting;
@@ -31,12 +56,25 @@ export class FrameQueue {
             resolve({ value: undefined, done: true });
         }
     }
+    /** The consumer is gone: whatever it did not pull leaves the process budget. */
+    discard() {
+        this.end();
+        if (this.queuedBytes > 0) {
+            this.charge(-this.queuedBytes);
+        }
+        this.frames.length = 0;
+    }
+    charge(delta) {
+        this.queuedBytes += delta;
+        processQueuedBytes = Math.max(0, processQueuedBytes + delta);
+        this.onLevel?.(this.queuedBytes);
+    }
     [Symbol.asyncIterator]() {
         return {
             next: () => {
                 const frame = this.frames.shift();
                 if (frame) {
-                    this.queuedBytes -= frame.length;
+                    this.charge(-frame.length);
                     return Promise.resolve({ value: frame, done: false });
                 }
                 if (this.ended) {
@@ -47,7 +85,7 @@ export class FrameQueue {
                 });
             },
             return: () => {
-                this.end();
+                this.discard();
                 return Promise.resolve({ value: undefined, done: true });
             },
         };

package/dist/server/websocket/transcribeWebSocket.d.ts

@@ -24,7 +24,14 @@
  * to change them. Listeners receive every event of the speakers they follow,
  * tagged with `speaker`, and only the `output` events of their languages; a
  * session renders each utterance once into the union of its listeners'
- * languages. A session lives while a speaker or a listener is connected.
+ * languages. A session lives while a speaker or a listener is connected. The
+ * speaker that opens a session may add `&secret=<value>`; every later speaker
+ * and listener must then present the same secret, so a session id alone does
+ * not admit a stranger (`requireSessionSecret` makes the secret mandatory).
+ *
+ * Limits: sockets are capped in all and per remote address (503 before the
+ * handshake), a socket that sends faster than the engine takes is paused at a
+ * high-water mark, and queued audio is budgeted across the process.
  *
  * OpenAI Realtime transcription (default path `/v1/realtime`,
  * `?intent=transcription`): the same pipeline behind OpenAI's protocol, for