@juspay/neurolink 13.8.16 → 13.8.18

package/dist/server/routes/transcribeRoutes.js

@@ -17,6 +17,7 @@ import { withSpan } from "../../telemetry/withSpan.js";
 import { tracers } from "../../telemetry/tracers.js";
 import { logger } from "../../utils/logger.js";
 import { MAX_AUDIO_BYTES } from "../../utils/sizeGuard.js";
+import { clientFacingError, logClientFacingError, PROVIDER_NOT_CONFIGURED_MESSAGE, } from "../utils/clientError.js";
 import { RawBodyTooLargeError } from "../utils/rawBody.js";
 import { getSTTProviderDescriptor, listConfiguredSTTProviders, resolveDefaultSTTProvider, resolveSTTEndpoints, } from "../../factories/sttDescriptors.js";
 import { STTProcessor } from "../../utils/sttProcessor.js";
@@ -170,7 +171,15 @@ async function resolveAudio(request, options, limit) {
             });
         }
         catch (error) {
-            throw new TranscribeRequestError(`could not download audioUrl: ${error instanceof Error ? error.message : String(error)}`, 400, "VALIDATION_ERROR");
+            // The guard's reason can name the address a host resolved to, which
+            // would let a caller map the server's network one URL at a time. The
+            // caller gets a fixed message; the operator gets the reason in the log,
+            // with the URL itself redacted (as agentInput.ts does).
+            const reason = error instanceof Error ? error.message : String(error);
+            logger.warn("[transcribeRoutes] refused an audioUrl", {
+                reason: reason.replaceAll(request.audioUrl, "<url>"),
+            });
+            throw new TranscribeRequestError("audioUrl could not be fetched (it must be a public https URL, answer without a redirect and fit the size limit)", 400, "VALIDATION_ERROR");
         }
         return {
             audio,
@@ -213,7 +222,14 @@ function toTranscribeOptions(config, audio, format, maxAudioBytes) {
         ...(config.timeoutMs !== undefined ? { timeoutMs: config.timeoutMs } : {}),
     };
 }
-/** Status and code for an error thrown by `transcribe()` or by this file. */
+/**
+ * Status, code and the message the client may see for an error thrown by
+ * `transcribe()` or by this file. The exception's own text is passed through
+ * only when this file composed it or when it describes the request (an empty
+ * or malformed recording); a missing engine is named by category, never by
+ * the variable that would configure it, and anything else is reduced to a
+ * fixed message. The detail is logged by the caller.
+ */
 function classifyError(error) {
     const message = error instanceof Error ? error.message : String(error);
     if (error instanceof TranscribeRequestError) {
@@ -222,10 +238,26 @@ function classifyError(error) {
     const code = typeof error === "object" && error !== null && "code" in error
         ? String(error.code)
         : undefined;
+    if (code === "STT_PROVIDER_NOT_CONFIGURED") {
+        return {
+            status: 503,
+            code: "PROVIDER_NOT_CONFIGURED",
+            message: PROVIDER_NOT_CONFIGURED_MESSAGE,
+        };
+    }
     if (code && CLIENT_ERROR_CODES.has(code)) {
         return { status: 400, code: "VALIDATION_ERROR", message };
     }
-    return { status: 500, code: "EXECUTION_FAILED", message };
+    const shaped = clientFacingError(error);
+    return shaped.status === 500
+        ? { ...shaped, code: "EXECUTION_FAILED" }
+        : shaped;
+}
+/** `classifyError` plus the server-side log the client-facing message leaves out. */
+function classifyAndLog(ctx, route, error) {
+    const classified = classifyError(error);
+    logClientFacingError(`transcribeRoutes ${route}`, ctx.requestId, error, classified);
+    return classified;
 }
 async function runTranscription(ctx, route, options) {
     return withSpan({
@@ -420,11 +452,7 @@ async function handleOpenAITranscription(ctx, options, limit, route) {
         result = await runTranscription(ctx, route, toTranscribeOptions(parsed.data, audio, format, limit));
     }
     catch (error) {
-        const classified = classifyError(error);
-        logger.warn("[transcribeRoutes] OpenAI-compatible transcription failed", {
-            requestId: ctx.requestId,
-            error: classified.message,
-        });
+        const classified = classifyAndLog(ctx, route, error);
         return openAIError(classified.status, classified.message);
     }
     if (responseFormat === "text") {
@@ -541,7 +569,17 @@ export function createTranscribeRoutes(basePath = "/api", options = {}) {
     const nativePath = `${basePath}/agent/transcribe`;
     const openaiPath = `${options.openaiBasePath ?? ""}/v1/audio/transcriptions`;
     const evalPath = `${options.openaiBasePath ?? ""}/v1/evals/stt`;
-    const evalStore = options.evals === false ? undefined : new STTEvalStore(options.evals);
+    // The collector keeps every transcript it is sent and reads them back to
+    // whoever asks, so it is mounted only when the operator asks for it: an
+    // options object, or NEUROLINK_STT_EVAL_ENABLED=1. It used to be on by
+    // default.
+    const evalStore = options.evals === false
+        ? undefined
+        : options.evals !== undefined
+            ? new STTEvalStore(options.evals)
+            : process.env.NEUROLINK_STT_EVAL_ENABLED?.trim() === "1"
+                ? new STTEvalStore()
+                : undefined;
     return {
         // Empty prefix: the two routes live under different roots, and every
         // route path already starts with "", so the adapters add nothing.
@@ -561,7 +599,7 @@ export function createTranscribeRoutes(basePath = "/api", options = {}) {
                         return await runTranscription(ctx, nativePath, toTranscribeOptions(request, audio, format, limit));
                     }
                     catch (error) {
-                        const classified = classifyError(error);
+                        const classified = classifyAndLog(ctx, nativePath, error);
                         return createErrorResponse(classified.code, classified.message, undefined, ctx.requestId, classified.status);
                     }
                 },
@@ -593,6 +631,11 @@ export function createTranscribeRoutes(basePath = "/api", options = {}) {
  * apart they were per speaker.
  */
 function createEvalRoutes(evalPath, store) {
+    // A person the server identified owns the calls they post and sees only
+    // those; a shared key names no person, so its calls are visible to every
+    // holder, as before. The handler sees ctx.user only when the server carries
+    // middleware state (see ServerAdapterConfig.carryMiddlewareState).
+    const ownerOf = (ctx) => ctx.user && ctx.user.shared !== true ? ctx.user.id : undefined;
     return [
         {
             method: "POST",
@@ -603,7 +646,9 @@ function createEvalRoutes(evalPath, store) {
                     return validation.error;
                 }
                 const batch = validation.data;
-                return store.accept(batch);
+                const accepted = await store.accept(batch, ownerOf(ctx));
+                return (accepted ??
+                    createErrorResponse("FORBIDDEN", "This call belongs to another caller", undefined, ctx.requestId, 403));
             },
             description: "Accept a batch of one call's segments from two STTs (primary shown, shadow for evaluation); a resent segment id replaces the earlier one",
             tags: ["transcribe", "evaluation"],
@@ -611,7 +656,9 @@ function createEvalRoutes(evalPath, store) {
         {
             method: "GET",
             path: evalPath,
-            handler: async () => ({ calls: await store.list() }),
+            handler: async (ctx) => ({
+                calls: await store.list(ownerOf(ctx)),
+            }),
             description: "Calls collected for STT evaluation, most recent first",
             tags: ["transcribe", "evaluation"],
         },
@@ -622,7 +669,7 @@ function createEvalRoutes(evalPath, store) {
                 // Adapters already decode path params; decoding again would turn a
                 // literal "%" in an id into something else, or throw on "%E0%A4%A".
                 const callId = ctx.params.callId ?? "";
-                const report = await store.report(callId, ctx.query.segments === "true");
+                const report = await store.report(callId, ctx.query.segments === "true", ownerOf(ctx));
                 return (report ??
                     createErrorResponse("NOT_FOUND", `No STT evaluation for call ${callId}`, undefined, ctx.requestId, 404));
             },

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

@@ -0,0 +1,23 @@
+/**
+ * The address a request is counted against.
+ *
+ * The TCP peer is the only address a client cannot choose, so it is the
+ * default. `X-Forwarded-For` is read only when the operator says a reverse
+ * proxy stands in front of the server (`trustProxy`), and then from the right:
+ * the hops of the listed proxies are skipped and the first other entry is the
+ * client, because a proxy appends the address it saw and anything a client put
+ * in the header itself sits further left.
+ *
+ * @module server/utils/clientAddress
+ */
+import type { ServerClientAddressInput } from "../../types/index.js";
+/** Strip an IPv4-mapped IPv6 prefix and a port, so one client has one key. */
+export declare function canonicalAddress(address: string): string | undefined;
+/**
+ * The client's address, or `undefined` when the runtime reports no peer and
+ * no trusted header names one. The result is always a bare IP, so a header
+ * holding anything else cannot become a counter key.
+ */
+export declare function resolveClientAddress(input: ServerClientAddressInput): string | undefined;
+/** `true` for an address only this host can reach: 127/8, `::1`, or their mapped forms. */
+export declare function isLoopbackAddress(address: string | undefined): boolean;

package/dist/server/utils/clientAddress.js

@@ -0,0 +1,65 @@
+/**
+ * The address a request is counted against.
+ *
+ * The TCP peer is the only address a client cannot choose, so it is the
+ * default. `X-Forwarded-For` is read only when the operator says a reverse
+ * proxy stands in front of the server (`trustProxy`), and then from the right:
+ * the hops of the listed proxies are skipped and the first other entry is the
+ * client, because a proxy appends the address it saw and anything a client put
+ * in the header itself sits further left.
+ *
+ * @module server/utils/clientAddress
+ */
+import { isIP } from "node:net";
+/** Strip an IPv4-mapped IPv6 prefix and a port, so one client has one key. */
+export function canonicalAddress(address) {
+    let value = address.trim();
+    if (value.startsWith("[")) {
+        const end = value.indexOf("]");
+        value = end === -1 ? value.slice(1) : value.slice(1, end);
+    }
+    else if (/^\d{1,3}(\.\d{1,3}){3}:\d+$/.test(value) ||
+        /^[^:]+:\d+$/.test(value)) {
+        value = value.slice(0, value.lastIndexOf(":"));
+    }
+    if (value.toLowerCase().startsWith("::ffff:") && isIP(value.slice(7)) === 4) {
+        value = value.slice(7);
+    }
+    return isIP(value) ? value : undefined;
+}
+/**
+ * The client's address, or `undefined` when the runtime reports no peer and
+ * no trusted header names one. The result is always a bare IP, so a header
+ * holding anything else cannot become a counter key.
+ */
+export function resolveClientAddress(input) {
+    const peer = input.remoteAddress
+        ? canonicalAddress(input.remoteAddress)
+        : undefined;
+    if (!input.trustProxy || !input.forwardedFor) {
+        return peer;
+    }
+    const trusted = new Set(input.trustedProxies
+        .map(canonicalAddress)
+        .filter((value) => value !== undefined));
+    const hops = input.forwardedFor
+        .split(",")
+        .map(canonicalAddress)
+        .filter((value) => value !== undefined);
+    for (let index = hops.length - 1; index >= 0; index--) {
+        if (!trusted.has(hops[index])) {
+            return hops[index];
+        }
+    }
+    return peer;
+}
+/** `true` for an address only this host can reach: 127/8, `::1`, or their mapped forms. */
+export function isLoopbackAddress(address) {
+    if (!address) {
+        return false;
+    }
+    const value = canonicalAddress(address) ?? address.trim().toLowerCase();
+    return (value === "::1" ||
+        value === "localhost" ||
+        /^127\.\d+\.\d+\.\d+$/.test(value));
+}

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

@@ -0,0 +1,35 @@
+/**
+ * What a failed request may tell the client.
+ *
+ * An exception's text names environment variables, provider wiring, file
+ * paths and upstream response bodies; none of that belongs in a response to
+ * an unknown caller. A route therefore answers with one of a few fixed
+ * messages plus the request id, and the detail goes to the server log under
+ * that id, where the operator can find it. The pattern is the one the OpenAI
+ * proxy route already followed.
+ *
+ * What is passed through: a `ServerAdapterError` below 500, whose message
+ * this server composed (a validation failure, a missing route), and the
+ * category of a provider that is missing credentials, without saying which
+ * credential.
+ *
+ * @module server/utils/clientError
+ */
+import type { ServerClientFacingError } from "../../types/index.js";
+export declare const GENERIC_ERROR_MESSAGE = "An internal error occurred";
+export declare const PROVIDER_NOT_CONFIGURED_MESSAGE = "The requested provider is not configured on this server";
+export declare const UPSTREAM_RATE_LIMITED_MESSAGE = "The upstream provider is rate limiting this server; retry later";
+export declare const REQUEST_TIMEOUT_MESSAGE = "The request timed out";
+/**
+ * The response for `error`. Never the exception's own text unless this
+ * server wrote it (a `ServerAdapterError` below 500).
+ */
+export declare function clientFacingError(error: unknown): ServerClientFacingError;
+/**
+ * Log the detail the client does not get, under the request id the client
+ * does get. A client error is routine traffic and logs as one line; anything
+ * else keeps its stack.
+ */
+export declare function logClientFacingError(source: string, requestId: string | undefined, error: unknown, shaped: ServerClientFacingError): void;
+/** {@link clientFacingError} and {@link logClientFacingError} in one step. */
+export declare function shapeRouteError(source: string, requestId: string | undefined, error: unknown): ServerClientFacingError;

package/dist/server/utils/clientError.js

@@ -0,0 +1,129 @@
+/**
+ * What a failed request may tell the client.
+ *
+ * An exception's text names environment variables, provider wiring, file
+ * paths and upstream response bodies; none of that belongs in a response to
+ * an unknown caller. A route therefore answers with one of a few fixed
+ * messages plus the request id, and the detail goes to the server log under
+ * that id, where the operator can find it. The pattern is the one the OpenAI
+ * proxy route already followed.
+ *
+ * What is passed through: a `ServerAdapterError` below 500, whose message
+ * this server composed (a validation failure, a missing route), and the
+ * category of a provider that is missing credentials, without saying which
+ * credential.
+ *
+ * @module server/utils/clientError
+ */
+import { AuthenticationError as ProviderAuthenticationError, RateLimitError as ProviderRateLimitError, } from "../../types/index.js";
+import { logger } from "../../utils/logger.js";
+import { ServerAdapterError } from "../errors.js";
+export const GENERIC_ERROR_MESSAGE = "An internal error occurred";
+export const PROVIDER_NOT_CONFIGURED_MESSAGE = "The requested provider is not configured on this server";
+export const UPSTREAM_RATE_LIMITED_MESSAGE = "The upstream provider is rate limiting this server; retry later";
+export const REQUEST_TIMEOUT_MESSAGE = "The request timed out";
+/** Signs that a provider refused the server's own credentials, or has none. */
+const PROVIDER_CONFIGURATION_PATTERN = /api[ _-]?key|credential|not configured|no (?:ai )?provider|authenticat|unauthori[sz]ed|forbidden|permission denied|invalid[ _-]?(?:key|token)|missing (?:required )?(?:environment|env|key|token)|environment variable/i;
+/** Names the SDK's own error classes and codes use for the same thing. */
+const PROVIDER_CONFIGURATION_CODES = new Set([
+    "AUTHENTICATION_ERROR",
+    "AUTHENTICATION_FAILED",
+    "AUTH_ERROR",
+    "INVALID_API_KEY",
+    "MISSING_API_KEY",
+    "PROVIDER_NOT_CONFIGURED",
+    "CONFIGURATION_ERROR",
+    "NO_PROVIDER",
+    "STT_PROVIDER_NOT_CONFIGURED",
+]);
+function codeOf(error) {
+    if (typeof error !== "object" || error === null) {
+        return undefined;
+    }
+    const code = error.code;
+    return typeof code === "string" ? code : undefined;
+}
+function isAbortError(error) {
+    return (error instanceof Error &&
+        (error.name === "AbortError" || error.name === "TimeoutError"));
+}
+/**
+ * The response for `error`. Never the exception's own text unless this
+ * server wrote it (a `ServerAdapterError` below 500).
+ */
+export function clientFacingError(error) {
+    if (error instanceof ServerAdapterError) {
+        // The request timeout is the server's deadline, not the client's slowness
+        // (the TIMEOUT code maps to 408 for the latter), so it answers 504.
+        if (error.name === "ServerTimeoutError") {
+            return {
+                code: "REQUEST_TIMEOUT",
+                message: REQUEST_TIMEOUT_MESSAGE,
+                status: 504,
+            };
+        }
+        const status = error.getHttpStatus();
+        if (status < 500) {
+            return { code: error.code, message: error.message, status };
+        }
+        return { code: "INTERNAL_ERROR", message: GENERIC_ERROR_MESSAGE, status };
+    }
+    if (isAbortError(error)) {
+        return {
+            code: "REQUEST_TIMEOUT",
+            message: REQUEST_TIMEOUT_MESSAGE,
+            status: 504,
+        };
+    }
+    if (error instanceof ProviderRateLimitError) {
+        return {
+            code: "UPSTREAM_RATE_LIMITED",
+            message: UPSTREAM_RATE_LIMITED_MESSAGE,
+            status: 503,
+        };
+    }
+    const code = codeOf(error);
+    const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof ProviderAuthenticationError ||
+        (code !== undefined && PROVIDER_CONFIGURATION_CODES.has(code)) ||
+        PROVIDER_CONFIGURATION_PATTERN.test(message)) {
+        return {
+            code: "PROVIDER_NOT_CONFIGURED",
+            message: PROVIDER_NOT_CONFIGURED_MESSAGE,
+            status: 503,
+        };
+    }
+    return {
+        code: "INTERNAL_ERROR",
+        message: GENERIC_ERROR_MESSAGE,
+        status: 500,
+    };
+}
+/**
+ * Log the detail the client does not get, under the request id the client
+ * does get. A client error is routine traffic and logs as one line; anything
+ * else keeps its stack.
+ */
+export function logClientFacingError(source, requestId, error, shaped) {
+    const detail = error instanceof Error ? error.message : String(error);
+    if (shaped.status < 500) {
+        logger.warn(`[${source}] Request rejected`, {
+            requestId,
+            code: shaped.code,
+            error: detail,
+        });
+        return;
+    }
+    logger.error(`[${source}] Request failed`, {
+        requestId,
+        code: shaped.code,
+        error: detail,
+        stack: error instanceof Error ? error.stack : undefined,
+    });
+}
+/** {@link clientFacingError} and {@link logClientFacingError} in one step. */
+export function shapeRouteError(source, requestId, error) {
+    const shaped = clientFacingError(error);
+    logClientFacingError(source, requestId, error, shaped);
+    return shaped;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * 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 type { ServerNodeMiddleware } from "../../types/index.js";
+/**
+ * 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 declare function createBoundedBodyParser(parser: ServerNodeMiddleware, limit: string | number | undefined): ServerNodeMiddleware;