@silmaril-security/sdk 0.6.2 → 0.6.3

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to the Silmaril Firewall TypeScript SDK are documented here.
 
+## 0.6.3 - 2026-09-24
+
+- Add an optional `signal` option to `classify()` and `classifyBatch()`.
+  Aborting stops the in-flight request or the 429 retry wait, rejects with the
+  signal's reason, and leaves sibling calls on the same client unaffected. An
+  already-aborted signal rejects without sending a request.
+- Combine the caller signal with the existing per-attempt `timeoutMs` without
+  changing timeout behavior, and release the abort listener and timer once an
+  attempt finishes.
+- Discard a retried 429 response body before backing off so a retry does not
+  leak the connection.
+- Serialize each request payload once before retries, so mutating the objects
+  passed to a call can no longer change an in-flight logical event.
+- Reject a `timeoutMs` above 2147483647 ms in the constructor instead of
+  letting a timer silently collapse it to an immediate abort.
+- Document that `Firewall` state is immutable and one client is reusable for
+  concurrent promises within a runtime, while each worker thread owns its own
+  client.
+
 ## 0.6.2 - 2026-08-24
 
 - Align the runtime `sdk_version` metadata with the published package version.

package/README.md

@@ -40,7 +40,7 @@ For reproducible installs, pin a tagged release:
 npm install @silmaril-security/sdk@0.6.2
 ```
 
-Requires Node 18 or later.
+Requires Node 20 or later.
 
 The package name and SDK import path are both `@silmaril-security/sdk`, so call
 sites use `Firewall`, `HookLabel`, and `FirewallBlockedException` from that
@@ -117,6 +117,47 @@ internally applied threshold. Direct calls do not throw on malicious verdicts.
 The Vercel AI SDK and LangChain.js adapters use `result.threshold` and throw
 `FirewallBlockedException` when enforcement is enabled.
 
+## Concurrency and Cancellation
+
+A `Firewall` instance holds no per-request state, so one client can serve any
+number of concurrent calls in a runtime. Responses are matched to their own
+promise regardless of completion order:
+
+```ts
+const [userResult, toolResult] = await Promise.all([
+  fw.classify(userInput, { hook: HookLabel.USER_INPUT }),
+  fw.classify(toolOutput, { hook: HookLabel.TOOL_RESPONSE, toolName: "read_file" }),
+]);
+```
+
+Pass a `signal` to cancel one call without touching its siblings:
+
+```ts
+const controller = new AbortController();
+request.on("close", () => controller.abort());
+
+try {
+  const result = await fw.classify(userInput, {
+    hook: HookLabel.USER_INPUT,
+    signal: controller.signal,
+  });
+  return result;
+} catch (err) {
+  if (controller.signal.aborted) {
+    return; // caller went away
+  }
+  throw err;
+}
+```
+
+Aborting stops the in-flight request or the 429 backoff wait and rejects with
+the signal's reason. An already-aborted signal rejects without sending a
+request. `signal` composes with `timeoutMs`, which still applies per attempt.
+`classifyBatch()` accepts the same option.
+
+Each worker thread owns its own client: construct a `Firewall` inside the
+thread instead of sharing one instance across `worker_threads` boundaries.
+
 ## Handle Outcomes
 
 Direct calls expose typed outcome labels so applications can choose different
@@ -183,14 +224,15 @@ Outcome taxonomy:
 interface FirewallOptions {
   apiKey: string;                                     // required
   apiUrl: string;                                     // required
-  timeoutMs?: number;                                 // default: 10000 ms
+  timeoutMs?: number;                                 // default: 10000 ms, max 2147483647
   mode?: "shadow" | "warn" | "block";                // omitted uses backend configuration
   shadowMode?: boolean;                               // deprecated legacy mapping
 }
 ```
 
-The SDK uses native `fetch`, `AbortSignal.timeout`, and JSON request bodies with
-`x-api-key` and `content-type` headers.
+The SDK uses native `fetch`, an abort signal per request attempt, and JSON
+request bodies with `x-api-key` and `content-type` headers. `timeoutMs` applies
+to each attempt and is combined with any caller-supplied `signal`.
 
 ## Backend Thresholding
 
@@ -439,9 +481,11 @@ const handler = await createLangChainHandler(fw);
 ## Retries
 
 HTTP 429 responses are retried with exponential backoff capped at 30s, up to 5
-times. Redirects are rejected rather than followed. Other non-2xx responses are
-surfaced as `SilmarilApiError`, and transport or timeout failures are surfaced
-unchanged.
+times. The retried response body is discarded before the wait, and each request
+payload is serialized once so every attempt sends the same logical event.
+Redirects are rejected rather than followed. Other non-2xx responses are
+surfaced as `SilmarilApiError`, and transport, timeout, or cancellation failures
+are surfaced unchanged.
 
 ## Development
 

package/dist/adapters/langchain.d.cts

@@ -1,5 +1,5 @@
 import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
-import { e as Firewall, L as LangChainAdapterOptions } from '../firewall-Cdnk_UWY.cjs';
+import { e as Firewall, L as LangChainAdapterOptions } from '../firewall-DkArls03.cjs';
 
 declare function createLangChainHandler(firewall: Firewall, options?: LangChainAdapterOptions): Promise<BaseCallbackHandler>;
 

package/dist/adapters/langchain.d.ts

@@ -1,5 +1,5 @@
 import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
-import { e as Firewall, L as LangChainAdapterOptions } from '../firewall-Cdnk_UWY.js';
+import { e as Firewall, L as LangChainAdapterOptions } from '../firewall-DkArls03.js';
 
 declare function createLangChainHandler(firewall: Firewall, options?: LangChainAdapterOptions): Promise<BaseCallbackHandler>;
 

package/dist/adapters/vercel.d.cts

@@ -1 +1 @@
-export { g as FirewallMiddleware, Q as createMiddleware } from '../firewall-Cdnk_UWY.cjs';
+export { g as FirewallMiddleware, Q as createMiddleware } from '../firewall-DkArls03.cjs';

package/dist/adapters/vercel.d.ts

@@ -1 +1 @@
-export { g as FirewallMiddleware, Q as createMiddleware } from '../firewall-Cdnk_UWY.js';
+export { g as FirewallMiddleware, Q as createMiddleware } from '../firewall-DkArls03.js';

package/dist/{firewall-Cdnk_UWY.d.cts → firewall-DkArls03.d.cts}

@@ -116,6 +116,11 @@ interface ClassifyOptions {
     governance?: GovernanceContext;
     metadata?: ClassificationMetadata;
     requestId?: string;
+    /**
+     * Cancels this call only. Aborting stops the in-flight request or retry wait
+     * and rejects with the signal's reason; sibling calls are unaffected.
+     */
+    signal?: AbortSignal;
 }
 interface ClassifyBatchOptions {
     mode?: FirewallMode;
@@ -124,6 +129,11 @@ interface ClassifyBatchOptions {
     governance?: readonly (GovernanceContext | undefined)[];
     metadata?: readonly (ClassificationMetadata | undefined)[];
     requestId?: string;
+    /**
+     * Cancels this batch call only. Aborting stops the in-flight request or retry
+     * wait and rejects with the signal's reason; sibling calls are unaffected.
+     */
+    signal?: AbortSignal;
 }
 interface LangChainAdapterOptions {
     hooks?: ReadonlySet<FirewallHook>;
@@ -219,6 +229,15 @@ interface FirewallMiddleware {
 declare function createMiddleware(firewall: Firewall, options?: MiddlewareOptions): FirewallMiddleware;
 
 declare const DEFAULT_TIMEOUT_MS = 10000;
+/**
+ * Firewall client for the `/classify` API.
+ *
+ * Instance state is set once in the constructor and never mutated by a request,
+ * so one client is safe to share across any number of concurrent `classify()`
+ * and `classifyBatch()` promises within a single JavaScript runtime. Each
+ * worker thread owns its own client: `Firewall` instances are not transferable
+ * across `worker_threads` boundaries.
+ */
 declare class Firewall {
     readonly apiKey: string;
     readonly apiUrl: string;

package/dist/{firewall-Cdnk_UWY.d.ts → firewall-DkArls03.d.ts}

@@ -116,6 +116,11 @@ interface ClassifyOptions {
     governance?: GovernanceContext;
     metadata?: ClassificationMetadata;
     requestId?: string;
+    /**
+     * Cancels this call only. Aborting stops the in-flight request or retry wait
+     * and rejects with the signal's reason; sibling calls are unaffected.
+     */
+    signal?: AbortSignal;
 }
 interface ClassifyBatchOptions {
     mode?: FirewallMode;
@@ -124,6 +129,11 @@ interface ClassifyBatchOptions {
     governance?: readonly (GovernanceContext | undefined)[];
     metadata?: readonly (ClassificationMetadata | undefined)[];
     requestId?: string;
+    /**
+     * Cancels this batch call only. Aborting stops the in-flight request or retry
+     * wait and rejects with the signal's reason; sibling calls are unaffected.
+     */
+    signal?: AbortSignal;
 }
 interface LangChainAdapterOptions {
     hooks?: ReadonlySet<FirewallHook>;
@@ -219,6 +229,15 @@ interface FirewallMiddleware {
 declare function createMiddleware(firewall: Firewall, options?: MiddlewareOptions): FirewallMiddleware;
 
 declare const DEFAULT_TIMEOUT_MS = 10000;
+/**
+ * Firewall client for the `/classify` API.
+ *
+ * Instance state is set once in the constructor and never mutated by a request,
+ * so one client is safe to share across any number of concurrent `classify()`
+ * and `classifyBatch()` promises within a single JavaScript runtime. Each
+ * worker thread owns its own client: `Firewall` instances are not transferable
+ * across `worker_threads` boundaries.
+ */
 declare class Firewall {
     readonly apiKey: string;
     readonly apiUrl: string;

package/dist/index.cjs

@@ -811,11 +811,12 @@ function sanitizeText(text) {
 }
 
 // src/firewall.ts
-var SDK_VERSION = "0.6.2";
+var SDK_VERSION = "0.6.3";
 var DEFAULT_TIMEOUT_MS = 1e4;
 var DEFAULT_MAX_RETRIES = 5;
 var MAX_BACKOFF_SECONDS = 30;
 var MAX_ERROR_BODY_BYTES = 1 << 16;
+var MAX_TIMEOUT_MS = 2147483647;
 function resolveMode(value, requestedMode) {
   let responseMode;
   if (value === "shadow" || value === "warn" || value === "block") {
@@ -954,6 +955,71 @@ async function readCappedErrorBody(response) {
   }
   return new TextDecoder().decode(body);
 }
+async function discardResponseBody(response) {
+  try {
+    if (response.body) {
+      if (!response.body.locked) {
+        await response.body.cancel();
+      }
+      return;
+    }
+    await response.text();
+  } catch {
+  }
+}
+function isAbortLikeError(error) {
+  if (typeof error !== "object" || error === null) {
+    return false;
+  }
+  const name = error.name;
+  return name === "AbortError" || name === "TimeoutError";
+}
+async function readBodyUnderSignal(read, signal) {
+  try {
+    return await read();
+  } catch (error) {
+    if (signal.aborted && isAbortLikeError(error)) {
+      throw signal.reason;
+    }
+    throw error;
+  }
+}
+function createAttemptSignal(timeoutMs, callerSignal) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => {
+    controller.abort(
+      new DOMException("The operation was aborted due to timeout", "TimeoutError")
+    );
+  }, timeoutMs);
+  const onCallerAbort = () => {
+    controller.abort(callerSignal?.reason);
+  };
+  callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      clearTimeout(timer);
+      callerSignal?.removeEventListener("abort", onCallerAbort);
+    }
+  };
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
 var Firewall = class {
   apiKey;
   apiUrl;
@@ -974,6 +1040,11 @@ var Firewall = class {
     if (typeof this.timeoutMs !== "number" || !Number.isFinite(this.timeoutMs) || this.timeoutMs < 0) {
       throw new Error(`Firewall: timeoutMs must be a finite non-negative number, got ${this.timeoutMs}`);
     }
+    if (this.timeoutMs > MAX_TIMEOUT_MS) {
+      throw new Error(
+        `Firewall: timeoutMs must be at most ${MAX_TIMEOUT_MS} ms, got ${this.timeoutMs}`
+      );
+    }
     this.mode = options.mode ?? legacyMode(options.shadowMode);
     this.shadowMode = this.mode === "shadow";
     this.headers = Object.freeze({
@@ -1030,7 +1101,7 @@ var Firewall = class {
         ...options.governance?.[index] === void 0 ? {} : { governance: options.governance[index] }
       })
     );
-    const data = await this.postWithRetry(payload);
+    const data = await this.postWithRetry(payload, options.signal);
     return data.predictions.map((p) => blockResultFromResponse(p, requestedMode));
   }
   asLangChainHandler(options = {}) {
@@ -1041,28 +1112,40 @@ var Firewall = class {
   asMiddleware(options = {}) {
     return createMiddleware(this, options);
   }
-  async postWithRetry(payload, maxRetries = DEFAULT_MAX_RETRIES) {
+  async postWithRetry(payload, callerSignal, maxRetries = DEFAULT_MAX_RETRIES) {
+    callerSignal?.throwIfAborted();
+    const body = JSON.stringify(payload);
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
-      const response = await fetch(this.apiUrl, {
-        method: "POST",
-        headers: this.headers,
-        body: JSON.stringify(payload),
-        redirect: "error",
-        signal: AbortSignal.timeout(this.timeoutMs)
-      });
-      if (response.status !== 429 || attempt === maxRetries) {
-        if (!response.ok) {
-          const body = await readCappedErrorBody(response);
-          throw new SilmarilApiError({
-            status: response.status,
-            statusText: response.statusText,
-            body
-          });
+      callerSignal?.throwIfAborted();
+      const attemptSignal = createAttemptSignal(this.timeoutMs, callerSignal);
+      try {
+        const response = await fetch(this.apiUrl, {
+          method: "POST",
+          headers: this.headers,
+          body,
+          redirect: "error",
+          signal: attemptSignal.signal
+        });
+        if (response.status !== 429 || attempt === maxRetries) {
+          if (!response.ok) {
+            const errorBody = await readCappedErrorBody(response);
+            attemptSignal.signal.throwIfAborted();
+            throw new SilmarilApiError({
+              status: response.status,
+              statusText: response.statusText,
+              body: errorBody
+            });
+          }
+          return await readBodyUnderSignal(
+            () => response.json(),
+            attemptSignal.signal
+          );
         }
-        return await response.json();
+        await discardResponseBody(response);
+      } finally {
+        attemptSignal.dispose();
       }
-      const waitSeconds = Math.min(2 ** attempt, MAX_BACKOFF_SECONDS);
-      await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1e3));
+      await sleep(Math.min(2 ** attempt, MAX_BACKOFF_SECONDS) * 1e3, callerSignal);
     }
     throw new Error("Firewall: exhausted retries (unreachable)");
   }
@@ -1082,7 +1165,7 @@ var Firewall = class {
       ...metadataInfo,
       ...options.governance === void 0 ? {} : { governance: options.governance }
     });
-    const data = await this.postWithRetry(payload);
+    const data = await this.postWithRetry(payload, options.signal);
     return blockResultFromResponse(data, requestedMode);
   }
 };