@juspay/neurolink 13.8.17 → 13.8.18

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

package/dist/server/websocket/transcribeWebSocket.js

@@ -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
@@ -40,10 +47,11 @@ import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { logger } from "../../utils/logger.js";
 import { timingSafeEqualString } from "../voice/tokenCompare.js";
+import { canonicalAddress, isLoopbackAddress } from "../utils/clientAddress.js";
 import { TranscribeOutputControlSchema, TranscribeStreamConfigSchema, TranscribeSubscribeSchema, } from "../utils/validation.js";
 import { fileModeStreamOptions } from "../../voice/transcribe.js";
 import { TranscriptionSession } from "../../voice/session/transcriptionSession.js";
-import { FrameQueue } from "./frameQueue.js";
+import { FrameQueue, totalQueuedFrameBytes } from "./frameQueue.js";
 import { resolveRealtimeProfiles, serveRealtimeTranscription, } from "./realtimeTranscription.js";
 const DEFAULT_PATH = "/v1/audio/transcriptions/stream";
 const DEFAULT_REALTIME_PATH = "/v1/realtime";
@@ -51,6 +59,21 @@ const DEFAULT_REALTIME_PATH = "/v1/realtime";
 const MAX_QUEUED_BYTES = 16 * 1024 * 1024;
 /** In file mode the whole recording may be queued at once: 512 MB is about 4.5 hours of 16 kHz PCM. */
 const MAX_QUEUED_BYTES_FILE = 512 * 1024 * 1024;
+/** Queued audio per socket above which the socket is paused until the engine catches up. */
+const DEFAULT_HIGH_WATER_MARK = 8 * 1024 * 1024;
+/** Queued audio across every socket of the process. */
+const DEFAULT_MAX_TOTAL_QUEUED_BYTES = 512 * 1024 * 1024;
+const DEFAULT_MAX_CONNECTIONS = 100;
+const DEFAULT_MAX_CONNECTIONS_PER_ADDRESS = 16;
+/** Subprotocol carrying the server's API key for a browser, next to `neurolink`. */
+const SUBPROTOCOL_KEY_PREFIX = "neurolink-api-key.";
+/** OpenAI's browser SDK sends the key as this subprotocol; honoured on the realtime path. */
+const OPENAI_SUBPROTOCOL_KEY_PREFIX = "openai-insecure-api-key.";
+/** Answer an upgrade before the handshake, with a status the client can read. */
+function refuseUpgrade(socket, status, reason) {
+    socket.write(`HTTP/1.1 ${status} ${reason}\r\nConnection: close\r\n\r\n`);
+    socket.destroy();
+}
 /**
  * `true` when the upgrade's `Origin` is on the allow-list, the list allows
  * any origin, or the request carries no `Origin` (not a browser).
@@ -66,8 +89,26 @@ function isOriginAllowed(req, allowed) {
     const wanted = origin.trim().toLowerCase();
     return allowed.some((o) => o.trim().toLowerCase() === wanted);
 }
-function isAuthorized(req, token, allowSubprotocolKey = false) {
-    const tokens = (typeof token === "string" ? [token] : (token ?? [])).filter((t) => t.length > 0);
+/** The configured token(s), empty when the stream is open. */
+function configuredTokens(token) {
+    return (typeof token === "string" ? [token] : (token ?? [])).filter((t) => t.length > 0);
+}
+/** The subprotocols the client offered, trimmed. */
+function offeredProtocols(req) {
+    return String(req.headers["sec-websocket-protocol"] ?? "")
+        .split(",")
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0);
+}
+/**
+ * Whether the upgrade carries one of `tokens`. A browser cannot set headers,
+ * so besides `Authorization: Bearer` the key may ride in the subprotocol list
+ * as `neurolink-api-key.<key>` (and, on the realtime path, as OpenAI's
+ * `openai-insecure-api-key.<key>`). `?token=` in the URL is accepted only when
+ * the operator allows it: a URL is written to access logs and `Referer`
+ * headers, so a key there leaks.
+ */
+function isAuthorized(req, tokens, options) {
     if (tokens.length === 0) {
         return true;
     }
@@ -76,26 +117,37 @@ function isAuthorized(req, token, allowSubprotocolKey = false) {
         ? header.slice(7)
         : undefined;
     let urlToken;
+    if (options.allowQueryToken) {
+        try {
+            urlToken =
+                new URL(req.url ?? "/", "http://localhost").searchParams.get("token") ??
+                    undefined;
+        }
+        catch {
+            urlToken = undefined;
+        }
+    }
+    const protocols = offeredProtocols(req);
+    const protocolToken = protocols
+        .find((p) => p.startsWith(SUBPROTOCOL_KEY_PREFIX))
+        ?.slice(SUBPROTOCOL_KEY_PREFIX.length) ??
+        (options.allowOpenAISubprotocolKey
+            ? protocols
+                .find((p) => p.startsWith(OPENAI_SUBPROTOCOL_KEY_PREFIX))
+                ?.slice(OPENAI_SUBPROTOCOL_KEY_PREFIX.length)
+            : undefined);
+    const provided = headerToken ?? protocolToken ?? urlToken;
+    return (provided !== undefined &&
+        tokens.some((t) => timingSafeEqualString(provided, t)));
+}
+/** `true` when the upgrade's URL carries a `?token=`, whether or not it is honoured. */
+function carriesQueryToken(req) {
     try {
-        urlToken =
-            new URL(req.url ?? "/", "http://localhost").searchParams.get("token") ??
-                undefined;
+        return new URL(req.url ?? "/", "http://localhost").searchParams.has("token");
     }
     catch {
-        urlToken = undefined;
+        return false;
     }
-    // OpenAI's browser SDK cannot set headers, so it sends the key as the
-    // subprotocol "openai-insecure-api-key.<key>"; honoured on the realtime path.
-    const protocolToken = allowSubprotocolKey
-        ? String(req.headers["sec-websocket-protocol"] ?? "")
-            .split(",")
-            .map((p) => p.trim())
-            .find((p) => p.startsWith("openai-insecure-api-key."))
-            ?.slice("openai-insecure-api-key.".length)
-        : undefined;
-    const provided = headerToken ?? urlToken ?? protocolToken;
-    return (provided !== undefined &&
-        tokens.some((t) => timingSafeEqualString(provided, t)));
 }
 function pathOf(req) {
     try {
@@ -150,20 +202,51 @@ export async function attachTranscribeWebSocket(server, neurolink, options = {})
         ? undefined
         : (options.realtimePath ?? DEFAULT_REALTIME_PATH);
     const realtimeProfiles = resolveRealtimeProfiles(options.realtimeProfiles);
+    const tokens = configuredTokens(options.authToken);
+    const allowQueryToken = options.allowQueryToken === true;
+    const maxConnections = options.maxConnections ?? DEFAULT_MAX_CONNECTIONS;
+    const maxPerAddress = options.maxConnectionsPerAddress ?? DEFAULT_MAX_CONNECTIONS_PER_ADDRESS;
+    const highWaterMark = options.highWaterMark ?? DEFAULT_HIGH_WATER_MARK;
+    const maxTotalQueued = options.maxTotalQueuedBytes ?? DEFAULT_MAX_TOTAL_QUEUED_BYTES;
     const wss = new WebSocketServer({
         noServer: true,
         maxPayload: options.maxPayload ?? 1_048_576,
-        // OpenAI's browser SDK offers "realtime" alongside its key subprotocol.
-        handleProtocols: (protocols) => protocols.has("realtime") ? "realtime" : false,
+        // OpenAI's browser SDK offers "realtime" alongside its key subprotocol;
+        // a browser on the stream path offers "neurolink" alongside
+        // "neurolink-api-key.<key>". The key-bearing protocol is never selected.
+        handleProtocols: (protocols) => protocols.has("realtime")
+            ? "realtime"
+            : protocols.has("neurolink")
+                ? "neurolink"
+                : false,
     });
-    // Sessions by id, alive while a speaker or a listener holds them.
+    // Sessions by id, alive while a speaker or a listener holds them. A session
+    // whose first speaker set `?secret=` admits only joins that present it.
     const sessions = new Map();
-    const acquire = (id) => {
-        const entry = sessions.get(id) ?? {
+    /**
+     * Join `id` with `secret`, or the reason a join is refused: a session with a
+     * secret and a join without the same one, or (with `requireSessionSecret`) a
+     * new session that sets none.
+     */
+    const admit = (id, secret) => {
+        const existing = sessions.get(id);
+        if (existing) {
+            if (existing.secret !== undefined &&
+                (secret === undefined ||
+                    !timingSafeEqualString(secret, existing.secret))) {
+                return "secret-mismatch";
+            }
+            existing.refs++;
+            return existing.session;
+        }
+        if (options.requireSessionSecret && !secret) {
+            return "secret-required";
+        }
+        const entry = {
             session: new TranscriptionSession(neurolink, { id }),
-            refs: 0,
+            refs: 1,
+            secret,
         };
-        entry.refs++;
         sessions.set(id, entry);
         return entry.session;
     };
@@ -178,6 +261,20 @@ export async function attachTranscribeWebSocket(server, neurolink, options = {})
             sessions.delete(id);
         }
     };
+    const sessionRefusal = (verdict) => verdict === "secret-mismatch"
+        ? "This session requires its secret (?secret=)"
+        : "A new session must set ?secret=<value> on this server";
+    // Open sockets, in all and per remote address, counted from the upgrade so
+    // a flood of handshakes is refused before any engine is started. The raw
+    // socket's close releases the count whether or not the handshake completed.
+    let openConnections = 0;
+    const perAddress = new Map();
+    const serverIsLoopback = () => {
+        const address = server.address();
+        return (typeof address === "object" &&
+            address !== null &&
+            isLoopbackAddress(address.address));
+    };
     const onUpgrade = (req, socket, head) => {
         const requested = pathOf(req);
         if (requested !== path &&
@@ -186,15 +283,46 @@ export async function attachTranscribeWebSocket(server, neurolink, options = {})
             return; // Someone else's upgrade.
         }
         if (!isOriginAllowed(req, options.allowedOrigins)) {
-            socket.write("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
-            socket.destroy();
+            refuseUpgrade(socket, 403, "Forbidden");
             return;
         }
-        if (!isAuthorized(req, options.authToken, requested === realtimePath)) {
-            socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
-            socket.destroy();
+        if (!isAuthorized(req, tokens, {
+            allowQueryToken,
+            allowOpenAISubprotocolKey: requested === realtimePath,
+        })) {
+            if (tokens.length > 0 && !allowQueryToken && carriesQueryToken(req)) {
+                logger.warn("[TranscribeWebSocket] refused an upgrade that carried the key in ?token= (allowQueryToken is off)");
+            }
+            refuseUpgrade(socket, 401, "Unauthorized");
             return;
         }
+        const peer = canonicalAddress(req.socket.remoteAddress ?? "") ?? "unknown";
+        const fromPeer = perAddress.get(peer) ?? 0;
+        if (openConnections >= maxConnections || fromPeer >= maxPerAddress) {
+            logger.warn("[TranscribeWebSocket] refused an upgrade: connection cap", {
+                open: openConnections,
+                fromPeer,
+            });
+            refuseUpgrade(socket, 503, "Service Unavailable");
+            return;
+        }
+        openConnections++;
+        perAddress.set(peer, fromPeer + 1);
+        let released = false;
+        socket.once("close", () => {
+            if (released) {
+                return;
+            }
+            released = true;
+            openConnections--;
+            const left = (perAddress.get(peer) ?? 1) - 1;
+            if (left <= 0) {
+                perAddress.delete(peer);
+            }
+            else {
+                perAddress.set(peer, left);
+            }
+        });
         wss.handleUpgrade(req, socket, head, (client) => {
             wss.emit("connection", client, req);
         });
@@ -212,7 +340,17 @@ export async function attachTranscribeWebSocket(server, neurolink, options = {})
             client.close(1008, "session required");
             return;
         }
-        const session = acquire(id);
+        const admitted = admit(id, queryParam(req, "secret"));
+        if (typeof admitted === "string") {
+            client.send(JSON.stringify({
+                type: "error",
+                message: sessionRefusal(admitted),
+                recoverable: false,
+            }));
+            client.close(1008, "session refused");
+            return;
+        }
+        const session = admitted;
         let subscription;
         const deliver = (event) => {
             if (client.readyState === WebSocket.OPEN) {
@@ -269,6 +407,20 @@ export async function attachTranscribeWebSocket(server, neurolink, options = {})
         const queue = new FrameQueue();
         let started = false;
         let fileMode = false;
+        // Backpressure: above the high-water mark the socket stops reading until
+        // the engine has taken enough of the backlog (half the mark), so a fast
+        // sender is slowed by TCP instead of buffered without bound.
+        let paused = false;
+        queue.setLevelListener((level) => {
+            if (!paused && level > highWaterMark) {
+                paused = true;
+                client.pause();
+            }
+            else if (paused && level <= highWaterMark / 2) {
+                paused = false;
+                client.resume();
+            }
+        });
         // Debugging: `NEUROLINK_STT_RECORD_DIR` keeps every session's config,
         // audio (PCM16LE) and events on disk, so a live session can be replayed
         // and compared against another engine. Off unless set.
@@ -291,6 +443,7 @@ export async function attachTranscribeWebSocket(server, neurolink, options = {})
         // Output languages, changeable mid-stream by control frames.
         let liveLanguages = [];
         const sessionId = subscribePath ? queryParam(req, "session") : undefined;
+        const sessionSecret = queryParam(req, "secret");
         // No name: the session assigns a unique one (speaker-1, speaker-2, …).
         const speaker = queryParam(req, "speaker") ?? "";
         const send = (event) => {
@@ -315,7 +468,16 @@ export async function attachTranscribeWebSocket(server, neurolink, options = {})
             }
             // A session speaker: events go to the session's listeners and back to
             // this socket. The session is held until this speaker's audio ends.
-            const session = acquire(sessionId);
+            const admitted = admit(sessionId, sessionSecret);
+            if (typeof admitted === "string") {
+                const refusal = new Error(sessionRefusal(admitted));
+                return {
+                    [Symbol.asyncIterator]: () => ({
+                        next: () => Promise.reject(refusal),
+                    }),
+                };
+            }
+            const session = admitted;
             const buffered = [];
             let wake;
             let finished = false;
@@ -415,12 +577,39 @@ export async function attachTranscribeWebSocket(server, neurolink, options = {})
                 started = true;
                 const { mode, ...rest } = config.data;
                 fileMode = mode === "file";
+                // File mode buffers a whole recording (up to 512 MiB) for a
+                // caller; on a listener the network can reach, only a caller the
+                // server authenticated gets that, unless the operator opts out.
+                if (fileMode &&
+                    tokens.length === 0 &&
+                    options.allowUnauthenticatedFileMode !== true &&
+                    !serverIsLoopback()) {
+                    send({
+                        type: "error",
+                        message: 'mode "file" needs authentication on this server; stream live audio instead',
+                        recoverable: false,
+                    });
+                    client.close(1008, "file mode requires authentication");
+                    return;
+                }
                 liveLanguages = rest.output?.languages ?? [];
                 record("config.json", JSON.stringify(config.data, null, 1), false);
                 void run(fileMode ? fileModeStreamOptions(rest) : rest);
                 return;
             }
             if (isBinary) {
+                // The process-wide budget is checked before the frame is taken:
+                // one socket's burst must not take the others down with it.
+                if (totalQueuedFrameBytes() + frame.length > maxTotalQueued) {
+                    send({
+                        type: "error",
+                        message: "The server is holding too much audio right now; try again later",
+                        recoverable: false,
+                    });
+                    queue.end();
+                    client.close(1013, "server busy");
+                    return;
+                }
                 record("audio.pcm", frame);
                 queue.push(frame);
                 if (queue.queuedBytes >

package/dist/skills/skillStores.js

@@ -11,6 +11,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import yaml from "js-yaml";
 import { logger } from "../utils/logger.js";
+import { assertSafeStoreId } from "../utils/safeStoreId.js";
 import { toSkillIndexItem } from "./skillMatcher.js";
 import { S3SkillStore } from "./skillStoreS3.js";
 import { RedisSkillStore } from "./skillStoreRedis.js";
@@ -220,12 +221,16 @@ export class FileSystemSkillStore {
         }
     }
     async put(skill) {
+        // The id becomes a file name under `baseDir`; refuse anything that could
+        // leave it (a separator, a traversal segment) before the join.
+        assertSafeStoreId(skill.id, "skill id");
         fs.mkdirSync(this.baseDir, { recursive: true });
         const filePath = path.join(this.baseDir, `${skill.id}.json`);
         fs.writeFileSync(filePath, JSON.stringify(normalizeSkill(skill), null, 2), "utf-8");
         this.invalidate();
     }
     async delete(id) {
+        assertSafeStoreId(id, "skill id");
         const filePath = path.join(this.baseDir, `${id}.json`);
         try {
             fs.unlinkSync(filePath);

package/dist/tasks/store/fileTaskStore.d.ts

@@ -28,6 +28,8 @@ export declare class FileTaskStore implements TaskStore {
     }): Promise<Task[]>;
     update(taskId: string, updates: Partial<Task>): Promise<Task>;
     delete(taskId: string): Promise<void>;
+    /** `{logsPath}/{taskId}.jsonl`, after refusing an id that is not a file name. */
+    private runLogPath;
     appendRun(taskId: string, run: TaskRunResult): Promise<void>;
     getRuns(taskId: string, options?: {
         limit?: number;

package/dist/tasks/store/fileTaskStore.js

@@ -11,6 +11,7 @@ import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { appendFile, readFile, rename, unlink, writeFile, } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { logger } from "../../utils/logger.js";
+import { assertSafeStoreId } from "../../utils/safeStoreId.js";
 import { TaskError } from "../errors.js";
 import { TASK_DEFAULTS, } from "../../types/index.js";
 export class FileTaskStore {
@@ -91,8 +92,9 @@ export class FileTaskStore {
     async delete(taskId) {
         this.tasks.delete(taskId);
         this.history.delete(taskId);
-        // Delete run log file
-        const logPath = join(this.logsPath, `${taskId}.jsonl`);
+        // Delete run log file. The id becomes a file name under `logsPath`;
+        // nanoid ids always pass, anything that could leave the directory does not.
+        const logPath = this.runLogPath(taskId);
         try {
             await unlink(logPath);
         }
@@ -102,14 +104,19 @@ export class FileTaskStore {
         await this.flush();
     }
     // ── Run Logs ──────────────────────────────────────────
+    /** `{logsPath}/{taskId}.jsonl`, after refusing an id that is not a file name. */
+    runLogPath(taskId) {
+        assertSafeStoreId(taskId, "task id");
+        return join(this.logsPath, `${taskId}.jsonl`);
+    }
     async appendRun(taskId, run) {
-        const logPath = join(this.logsPath, `${taskId}.jsonl`);
+        const logPath = this.runLogPath(taskId);
         mkdirSync(dirname(logPath), { recursive: true });
         await appendFile(logPath, JSON.stringify(run) + "\n", "utf-8");
         await this.pruneRunLog(logPath);
     }
     async getRuns(taskId, options) {
-        const logPath = join(this.logsPath, `${taskId}.jsonl`);
+        const logPath = this.runLogPath(taskId);
         if (!existsSync(logPath)) {
             return [];
         }

package/dist/types/attachments.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Attachment ingestion policy — the SDK-level counterpart of the server's
+ * default-deny path roots and SSRF guard.
+ *
+ * Every loader that turns a caller-supplied string into bytes (image URLs and
+ * paths in `input.images`, entries of `input.files`, `rag.files`,
+ * `transcribe({ audio })`, Director Mode segment images, `WebLoader`) reads
+ * its limits from one {@link AttachmentPolicy}. The policy is resolved once
+ * per `NeuroLink` instance from {@link AttachmentsConfig} and the
+ * `NEUROLINK_ATTACHMENT_*` environment variables, then stamped onto each
+ * call's options so the loaders several hops down see the same answer.
+ *
+ * Runtime helpers live in `src/lib/utils/attachmentPolicy.ts`.
+ */
+/**
+ * `new NeuroLink({ attachments })` — what an instance may read or fetch on a
+ * caller's behalf.
+ *
+ * Every field also has an environment variable for deployments that cannot
+ * change constructor arguments (the CLI, containers). An explicit field wins
+ * over its variable.
+ *
+ * | Field | Environment variable | Default |
+ * | --- | --- | --- |
+ * | `allowedRoots` | `NEUROLINK_ATTACHMENT_ROOTS` (path-list, `:`/`;` separated) | unrestricted (warns once) |
+ * | `allowInsecureUrls` | `NEUROLINK_ATTACHMENT_ALLOW_INSECURE_URLS=1` | `false` |
+ * | `allowPrivateNetwork` | `NEUROLINK_ATTACHMENT_ALLOW_PRIVATE_NETWORK=1` | `false` |
+ * | `followRedirects` | `NEUROLINK_ATTACHMENT_FOLLOW_REDIRECTS=0` | `true` |
+ * | `maxBytes` | `NEUROLINK_ATTACHMENT_MAX_BYTES` | each loader's own cap |
+ */
+export type AttachmentsConfig = {
+    /**
+     * Directories a local file path may resolve into. Containment is checked on
+     * the real (symlink-resolved) path of both the root and the target, and the
+     * file is opened `O_NOFOLLOW` on that real path, so a symlink planted under
+     * a root cannot reach outside it. Unset means any readable file — the
+     * pre-hardening behaviour — and the SDK warns once per process when it
+     * reads a path without roots. A host that forwards strings from untrusted
+     * callers must set this.
+     */
+    allowedRoots?: string[];
+    /**
+     * Accept `http://` attachment URLs. Default `false`: plain HTTP carries the
+     * bytes — and any credentials on the request — in the clear, and is the
+     * transport every loopback and link-local target answers on.
+     */
+    allowInsecureUrls?: boolean;
+    /**
+     * Fetch URLs whose host is, or resolves to, a loopback, RFC 1918,
+     * link-local, CGNAT, multicast or cloud-metadata address. Default `false`.
+     * The connection is still pinned to the resolved addresses.
+     */
+    allowPrivateNetwork?: boolean;
+    /**
+     * Follow HTTP redirects (up to five hops). Default `true`. Every hop is
+     * re-validated against the same URL policy, and caller-supplied headers
+     * (`authHeaders`) are never sent to a redirect target.
+     */
+    followRedirects?: boolean;
+    /**
+     * Upper bound, in bytes, for any single attachment read or download. A
+     * loader's own cap still applies when it is lower.
+     */
+    maxBytes?: number;
+};
+/**
+ * The resolved, immutable form of {@link AttachmentsConfig} that the loaders
+ * consume. `allowedRoots` holds absolute paths; `undefined` means unrestricted.
+ */
+export type AttachmentPolicy = {
+    readonly kind: "neurolink-attachment-policy";
+    readonly allowedRoots: readonly string[] | undefined;
+    readonly allowInsecureUrls: boolean;
+    readonly allowPrivateNetwork: boolean;
+    readonly followRedirects: boolean;
+    readonly maxBytes: number | undefined;
+};
+/** Options for `downloadAttachment()`. */
+export type AttachmentDownloadOptions = {
+    /** Policy to apply; the environment-derived default when omitted. */
+    policy?: AttachmentPolicy;
+    /** Hard cap on the response body in bytes (the policy's `maxBytes` lowers it). */
+    maxBytes: number;
+    /** Short label for error messages, e.g. `"image URL"`. */
+    label: string;
+    /**
+     * Headers for the first request only. They are dropped on every redirect
+     * hop so a credential meant for one host never reaches another.
+     */
+    headers?: Record<string, string>;
+    /** Transfer timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Caller cancellation. */
+    signal?: AbortSignal;
+    /** `HEAD` fetches headers only and returns an empty body. */
+    method?: "GET" | "HEAD";
+};
+/** Options for `readAttachmentFile()`. */
+export type AttachmentReadOptions = {
+    /** Policy to apply; the environment-derived default when omitted. */
+    policy?: AttachmentPolicy;
+    /** Hard cap on the file size in bytes (the policy's `maxBytes` lowers it). */
+    maxBytes: number;
+    /** Short label for error messages, e.g. `"image file"`. */
+    label: string;
+};
+/** What `readAttachmentFile()` returns. */
+export type AttachmentReadResult = {
+    buffer: Buffer;
+    /** The symlink-resolved path that was actually opened. */
+    realPath: string;
+};
+/**
+ * Machine-readable reasons an attachment was refused. Carried as `code` on the
+ * thrown error so callers can map them without parsing messages.
+ */
+export type AttachmentRefusalCode = "ATTACHMENT_OUTSIDE_ROOTS" | "ATTACHMENT_NOT_A_FILE" | "ATTACHMENT_TOO_LARGE" | "ATTACHMENT_URL_REFUSED";

package/dist/types/attachments.js

@@ -0,0 +1,15 @@
+/**
+ * Attachment ingestion policy — the SDK-level counterpart of the server's
+ * default-deny path roots and SSRF guard.
+ *
+ * Every loader that turns a caller-supplied string into bytes (image URLs and
+ * paths in `input.images`, entries of `input.files`, `rag.files`,
+ * `transcribe({ audio })`, Director Mode segment images, `WebLoader`) reads
+ * its limits from one {@link AttachmentPolicy}. The policy is resolved once
+ * per `NeuroLink` instance from {@link AttachmentsConfig} and the
+ * `NEUROLINK_ATTACHMENT_*` environment variables, then stamped onto each
+ * call's options so the loaders several hops down see the same answer.
+ *
+ * Runtime helpers live in `src/lib/utils/attachmentPolicy.ts`.
+ */
+export {};

package/dist/types/auth.d.ts

@@ -55,6 +55,12 @@ export type TokenStorageData = {
     /** Tokens indexed by provider name */
     providers: Record<string, StoredProviderTokens>;
 };
+/** Owner record written into the token store's cross-process lock file. */
+export type TokenStoreLockOwner = {
+    pid: number;
+    token: string;
+    acquiredAt: number;
+};
 /**
  * Per-provider token storage structure
  */

package/dist/types/cli.d.ts

@@ -805,6 +805,10 @@ export type ProxyStartArgs = {
     envFile?: string;
     passthrough?: boolean;
     dev?: boolean;
+    /** Bearer every inbound caller must present; also `NEUROLINK_PROXY_INBOUND_TOKEN`. */
+    inboundToken?: string;
+    /** Operator's explicit choice to bind off-loopback with no inbound auth. */
+    allowUnauthenticated?: boolean;
 };
 /** Arguments accepted by `neurolink proxy status` */
 export type ProxyStatusArgs = {