@silmaril-security/sdk 0.1.2 → 0.3.0

package/dist/index.js

@@ -9,6 +9,22 @@ var __export = (target, all) => {
 };
 
 // src/exceptions.ts
+function parseErrorBody(body) {
+  try {
+    const parsed = JSON.parse(body);
+    if (!parsed || typeof parsed !== "object") {
+      return { details: void 0, error: void 0, apiMessage: void 0 };
+    }
+    const data = parsed;
+    return {
+      details: data.details && typeof data.details === "object" ? data.details : void 0,
+      error: typeof data.error === "string" ? data.error : void 0,
+      apiMessage: typeof data.message === "string" ? data.message : void 0
+    };
+  } catch {
+    return { details: void 0, error: void 0, apiMessage: void 0 };
+  }
+}
 var MAX_PROMPT_DISPLAY_LEN, PromptBlockedException, SilmarilApiError;
 var init_exceptions = __esm({
   "src/exceptions.ts"() {
@@ -37,12 +53,20 @@ var init_exceptions = __esm({
       status;
       statusText;
       body;
+      details;
+      error;
+      apiMessage;
       constructor(params) {
-        super(`Silmaril API error ${params.status} ${params.statusText}: ${params.body}`);
+        const statusText = params.statusText ? ` ${params.statusText}` : "";
+        super(`Silmaril API error ${params.status}${statusText}`);
         this.name = "SilmarilApiError";
         this.status = params.status;
         this.statusText = params.statusText;
         this.body = params.body;
+        const parsed = parseErrorBody(params.body);
+        this.details = params.details ?? parsed.details;
+        this.error = params.error ?? parsed.error;
+        this.apiMessage = params.apiMessage ?? parsed.apiMessage;
         Object.setPrototypeOf(this, _SilmarilApiError.prototype);
       }
     };
@@ -78,7 +102,7 @@ function prependToolName(text, toolName) {
   }
   return `[TOOL:${toolName}] ${text}`;
 }
-var HookLabel, FirewallHook, DEFAULT_HOOKS, INPUT_HOOKS, OUTPUT_HOOKS, ALL_HOOKS, FIREWALL_HOOK_TO_LABEL, DEFAULT_HOOK_THRESHOLDS, FIREWALL_HOOK_VALUES;
+var HookLabel, FirewallHook, DEFAULT_HOOKS, INPUT_HOOKS, OUTPUT_HOOKS, ALL_HOOKS, FIREWALL_HOOK_TO_LABEL, FIREWALL_HOOK_VALUES;
 var init_hooks = __esm({
   "src/hooks.ts"() {
     "use strict";
@@ -127,14 +151,6 @@ var init_hooks = __esm({
       [FirewallHook.RETRIEVER_END]: HookLabel.TOOL_RESPONSE,
       [FirewallHook.LLM_END]: HookLabel.LLM_OUTPUT
     };
-    DEFAULT_HOOK_THRESHOLDS = {
-      [HookLabel.USER_INPUT]: 0.5,
-      [HookLabel.SYSTEM_PROMPT]: 0.3,
-      [HookLabel.TOOL_CALL]: 0.4,
-      [HookLabel.TOOL_RESPONSE]: 0.3,
-      [HookLabel.LLM_OUTPUT]: 0.4,
-      [HookLabel.UNKNOWN]: 0.5
-    };
     FIREWALL_HOOK_VALUES = new Set(Object.values(FirewallHook));
   }
 });
@@ -221,40 +237,49 @@ async function createLangChainHandler(firewall, options = {}) {
   const logger = options.logger ?? ((message, error) => {
     console.warn(`silmaril.firewall: ${message}`, error);
   });
-  const overrideThreshold = options.threshold;
-  const overrideHookThresholds = options.hookThresholds ?? {};
-  const effectiveThreshold = (label) => {
-    if (overrideHookThresholds[label] !== void 0) {
-      return overrideHookThresholds[label];
+  const shadowMode = options.shadowMode ?? firewall.shadowMode;
+  const onClassify = options.onClassify;
+  const fireOnClassify = (hookLabel, text, result, blocked, toolName) => {
+    if (!onClassify) {
+      return;
     }
-    if (firewall.hookThresholds[label] !== void 0) {
-      return firewall.hookThresholds[label];
+    try {
+      onClassify({
+        hook: hookLabel,
+        ...toolName !== void 0 ? { toolName } : {},
+        text,
+        result,
+        blocked,
+        shadowMode
+      });
+    } catch (err) {
+      logger("onClassify callback threw", err);
     }
-    return overrideThreshold ?? firewall.threshold;
   };
   const classify = async (text, hookLabel, runId, toolName) => {
+    let result;
     try {
-      const result = await firewall.classify(text, {
+      result = await firewall.classify(text, {
         hook: hookLabel,
         ...toolName !== void 0 ? { toolName } : {}
       });
-      const threshold = effectiveThreshold(hookLabel);
-      if (result.score >= threshold) {
-        throw new PromptBlockedException({
-          score: result.score,
-          threshold,
-          promptText: text,
-          runId
-        });
-      }
     } catch (err) {
-      if (err instanceof PromptBlockedException) {
-        throw err;
-      }
       if (!failOpen) {
         throw err;
       }
       logger("classification failed, allowing prompt through", err);
+      return;
+    }
+    const threshold = result.threshold;
+    const blocked = result.score >= threshold;
+    fireOnClassify(hookLabel, text, result, blocked, toolName);
+    if (blocked && !shadowMode) {
+      throw new PromptBlockedException({
+        score: result.score,
+        threshold,
+        promptText: text,
+        runId
+      });
     }
   };
   class SilmarilFirewallHandler extends BaseCallbackHandler {
@@ -301,8 +326,7 @@ async function createLangChainHandler(firewall, options = {}) {
         return;
       }
       const toolName = tool?.name;
-      const prefixed = prependToolName(text, toolName);
-      await classify(prefixed, FIREWALL_HOOK_TO_LABEL[FirewallHook.TOOL_START], runId, toolName);
+      await classify(text, FIREWALL_HOOK_TO_LABEL[FirewallHook.TOOL_START], runId, toolName);
     }
     async handleRetrieverStart(_retriever, query, runId) {
       if (!enabledHooks.has(FirewallHook.RETRIEVER_START)) {
@@ -333,8 +357,7 @@ async function createLangChainHandler(firewall, options = {}) {
         return;
       }
       const toolName = _kwargs?.name;
-      const prefixed = prependToolName(text, toolName);
-      await classify(prefixed, FIREWALL_HOOK_TO_LABEL[FirewallHook.TOOL_END], runId, toolName);
+      await classify(text, FIREWALL_HOOK_TO_LABEL[FirewallHook.TOOL_END], runId, toolName);
     }
     async handleRetrieverEnd(documents, runId) {
       if (!enabledHooks.has(FirewallHook.RETRIEVER_END)) {
@@ -420,17 +443,7 @@ function findLastUserMessage(messages) {
 function createMiddleware(firewall, options = {}) {
   const scanInput = options.scanInput ?? true;
   const scanOutput = options.scanOutput ?? false;
-  const overrideThreshold = options.threshold;
-  const overrideHookThresholds = options.hookThresholds ?? {};
-  const effectiveThreshold = (label) => {
-    if (overrideHookThresholds[label] !== void 0) {
-      return overrideHookThresholds[label];
-    }
-    if (firewall.hookThresholds[label] !== void 0) {
-      return firewall.hookThresholds[label];
-    }
-    return overrideThreshold ?? firewall.threshold;
-  };
+  const shadowMode = options.shadowMode ?? firewall.shadowMode;
   const classifyOrBlock = async (text, hook, toolName) => {
     if (!text.trim()) {
       return;
@@ -439,16 +452,17 @@ function createMiddleware(firewall, options = {}) {
       text,
       toolName !== void 0 ? { hook, toolName } : { hook }
     );
-    const threshold = effectiveThreshold(hook);
+    const threshold = result.threshold;
     const blocked = result.score >= threshold;
     options.onClassify?.({
       hook,
       ...toolName !== void 0 ? { toolName } : {},
       text,
       result,
-      blocked
+      blocked,
+      shadowMode
     });
-    if (blocked) {
+    if (blocked && !shadowMode) {
       const err = new PromptBlockedException({
         score: result.score,
         threshold,
@@ -561,7 +575,45 @@ var MAX_INPUT_CHARS = MAX_INPUT_TOKENS * CHARS_PER_TOKEN;
 var CHUNK_WINDOW_CHARS = CHUNK_WINDOW * CHARS_PER_TOKEN;
 var CHUNK_OVERLAP_CHARS = CHUNK_OVERLAP * CHARS_PER_TOKEN;
 var CHUNK_STRIDE_CHARS = CHUNK_WINDOW_CHARS - CHUNK_OVERLAP_CHARS;
+function isHighSurrogate(code) {
+  return code >= 55296 && code <= 56319;
+}
+function isLowSurrogate(code) {
+  return code >= 56320 && code <= 57343;
+}
+function sanitizeText(text) {
+  let out = "";
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (isHighSurrogate(code)) {
+      if (i + 1 < text.length && isLowSurrogate(text.charCodeAt(i + 1))) {
+        out += text[i];
+        out += text[i + 1];
+        i++;
+      }
+      continue;
+    }
+    if (isLowSurrogate(code)) {
+      continue;
+    }
+    out += text[i];
+  }
+  return out;
+}
+function safeChunkStart(text, start) {
+  if (start > 0 && start < text.length && isLowSurrogate(text.charCodeAt(start)) && isHighSurrogate(text.charCodeAt(start - 1))) {
+    return start + 1;
+  }
+  return start;
+}
+function safeChunkEnd(text, end) {
+  if (end > 0 && end < text.length && isHighSurrogate(text.charCodeAt(end - 1)) && isLowSurrogate(text.charCodeAt(end))) {
+    return end - 1;
+  }
+  return end;
+}
 function chunkText(text) {
+  text = sanitizeText(text);
   const n = text.length;
   if (n > MAX_INPUT_CHARS) {
     throw new Error(
@@ -573,8 +625,12 @@ function chunkText(text) {
   }
   const chunks = [];
   for (let start = 0; start < n; start += CHUNK_STRIDE_CHARS) {
-    const end = start + CHUNK_WINDOW_CHARS;
-    chunks.push(text.slice(start, end));
+    const safeStart = safeChunkStart(text, start);
+    if (safeStart >= n) {
+      break;
+    }
+    const end = safeChunkEnd(text, safeStart + CHUNK_WINDOW_CHARS);
+    chunks.push(text.slice(safeStart, end));
     if (end >= n) {
       break;
     }
@@ -584,16 +640,122 @@ function chunkText(text) {
 
 // src/firewall.ts
 init_exceptions();
-var DEFAULT_THRESHOLD = 0.5;
+var BASE_THRESHOLD = 0.5;
+var TARGET_SEQUENCE_FPR = 0.01;
+var MAX_ADAPTIVE_THRESHOLD = 0.9;
 var DEFAULT_TIMEOUT_MS = 1e4;
+var DEFAULT_CHUNK_CONCURRENCY = 8;
 var DEFAULT_MAX_RETRIES = 5;
 var MAX_BACKOFF_SECONDS = 30;
+var MAX_ERROR_BODY_BYTES = 1 << 16;
+function adaptiveThreshold(scoringOpportunityCount) {
+  if (!Number.isInteger(scoringOpportunityCount) || scoringOpportunityCount < 1) {
+    throw new Error(
+      `Firewall: scoringOpportunityCount must be an integer >= 1, got ${scoringOpportunityCount}`
+    );
+  }
+  if (scoringOpportunityCount === 1) {
+    return BASE_THRESHOLD;
+  }
+  const targetChunkFpr = 1 - Math.pow(1 - TARGET_SEQUENCE_FPR, 1 / scoringOpportunityCount);
+  const oddsRatio = TARGET_SEQUENCE_FPR / targetChunkFpr;
+  const rawThreshold = oddsRatio / (1 + oddsRatio);
+  return Math.min(rawThreshold, MAX_ADAPTIVE_THRESHOLD);
+}
+function blockResultFromResponse(data, threshold) {
+  const result = {
+    prediction: data.prediction,
+    score: Number(data.score),
+    threshold
+  };
+  if (data.primary_outcome !== void 0) {
+    result.primaryOutcome = data.primary_outcome;
+  }
+  if (data.outcome_scores !== void 0) {
+    result.outcomeScores = Object.freeze(
+      Object.fromEntries(Object.entries(data.outcome_scores).map(([k, v]) => [k, Number(v)]))
+    );
+  }
+  if (data.detector_scores !== void 0) {
+    result.detectorScores = Object.freeze(
+      Object.fromEntries(Object.entries(data.detector_scores).map(([k, v]) => [k, Number(v)]))
+    );
+  }
+  if (data.detector_counts !== void 0) {
+    result.detectorCounts = Object.freeze(
+      Object.fromEntries(Object.entries(data.detector_counts).map(([k, v]) => [k, Number(v)]))
+    );
+  }
+  return Object.freeze(result);
+}
+async function readCappedErrorBody(response) {
+  if (!response.body) {
+    return response.text().then((body2) => body2.slice(0, MAX_ERROR_BODY_BYTES)).catch(() => "");
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let remaining = MAX_ERROR_BODY_BYTES;
+  try {
+    while (remaining > 0) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      if (!value) {
+        continue;
+      }
+      const chunk = value.byteLength > remaining ? value.slice(0, remaining) : value;
+      chunks.push(chunk);
+      remaining -= chunk.byteLength;
+      if (chunk.byteLength < value.byteLength) {
+        break;
+      }
+    }
+  } catch {
+    return "";
+  } finally {
+    await reader.cancel().catch(() => void 0);
+  }
+  const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+  const body = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(body);
+}
+async function mapWithConcurrency(items, concurrency, task) {
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  let firstError;
+  const workerCount = Math.min(concurrency, items.length);
+  async function worker() {
+    for (; ; ) {
+      const index = nextIndex;
+      nextIndex += 1;
+      if (index >= items.length) {
+        return;
+      }
+      try {
+        results[index] = await task(items[index], index);
+      } catch (err) {
+        firstError ??= err;
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: workerCount }, () => worker()));
+  if (firstError !== void 0) {
+    throw firstError;
+  }
+  return results;
+}
 var Firewall = class {
   apiKey;
   apiUrl;
-  threshold;
   timeoutMs;
-  hookThresholds;
+  chunkConcurrency;
+  shadowMode;
   headers;
   constructor(options) {
     if (!options.apiKey) {
@@ -604,9 +766,17 @@ var Firewall = class {
     }
     this.apiKey = options.apiKey;
     this.apiUrl = options.apiUrl;
-    this.threshold = options.threshold ?? DEFAULT_THRESHOLD;
     this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    this.hookThresholds = options.hookThresholds ?? {};
+    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}`);
+    }
+    this.chunkConcurrency = options.chunkConcurrency ?? DEFAULT_CHUNK_CONCURRENCY;
+    if (!Number.isInteger(this.chunkConcurrency) || this.chunkConcurrency < 1) {
+      throw new Error(
+        `Firewall: chunkConcurrency must be an integer >= 1, got ${this.chunkConcurrency}`
+      );
+    }
+    this.shadowMode = options.shadowMode ?? false;
     this.headers = Object.freeze({
       "x-api-key": this.apiKey,
       "content-type": "application/json"
@@ -614,39 +784,52 @@ var Firewall = class {
   }
   async classify(text, options = {}) {
     const chunks = chunkText(text);
+    const threshold = adaptiveThreshold(chunks.length);
     if (chunks.length === 1) {
-      const payload = { text: chunks[0] };
-      if (options.hook !== void 0) {
-        payload.hook = options.hook;
-      }
-      if (options.toolName !== void 0) {
-        payload.tool_name = options.toolName;
-      }
-      const data = await this.postWithRetry(payload);
-      return Object.freeze({ prediction: data.prediction, score: Number(data.score) });
-    }
-    const batchOpts = {};
-    if (options.hook !== void 0) {
-      batchOpts.hooks = chunks.map(() => options.hook);
+      return this.classifySingleChunk(chunks[0], options, threshold);
     }
-    if (options.toolName !== void 0) {
-      batchOpts.toolNames = chunks.map(() => options.toolName);
-    }
-    const results = await this.classifyBatch(chunks, batchOpts);
+    const results = await mapWithConcurrency(
+      chunks,
+      this.chunkConcurrency,
+      (chunk) => this.classifySingleChunk(chunk, options, threshold)
+    );
     return results.reduce((best, r) => r.score > best.score ? r : best);
   }
   async classifyBatch(texts, options = {}) {
-    const payload = { texts };
+    if (texts.length === 0) {
+      throw new Error("Firewall: texts must not be empty");
+    }
+    if (options.hooks !== void 0 && options.hooks.length !== texts.length) {
+      throw new Error(
+        `Firewall: hooks length ${options.hooks.length} does not match texts length ${texts.length}`
+      );
+    }
+    if (options.toolNames !== void 0 && options.toolNames.length !== texts.length) {
+      throw new Error(
+        `Firewall: toolNames length ${options.toolNames.length} does not match texts length ${texts.length}`
+      );
+    }
+    if (options.metadata !== void 0 && options.metadata.length !== texts.length) {
+      throw new Error(
+        `Firewall: metadata length ${options.metadata.length} does not match texts length ${texts.length}`
+      );
+    }
+    const threshold = adaptiveThreshold(texts.length);
+    const payload = {
+      texts: texts.map((text) => sanitizeText(text)),
+      threshold
+    };
     if (options.hooks && options.hooks.length > 0) {
       payload.hooks = options.hooks.map((h) => String(h));
     }
     if (options.toolNames && options.toolNames.length > 0) {
       payload.tool_names = options.toolNames.map((t) => t === void 0 ? null : t);
     }
+    if (options.metadata && options.metadata.length > 0) {
+      payload.metadata = options.metadata.map((m) => m === void 0 ? null : m);
+    }
     const data = await this.postWithRetry(payload);
-    return data.predictions.map(
-      (p) => Object.freeze({ prediction: p.prediction, score: Number(p.score) })
-    );
+    return data.predictions.map((p) => blockResultFromResponse(p, threshold));
   }
   asLangChainHandler(options = {}) {
     return Promise.resolve().then(() => (init_langchain(), langchain_exports)).then((m) => m.createLangChainHandler(this, options));
@@ -654,23 +837,18 @@ var Firewall = class {
   asMiddleware(options = {}) {
     return createMiddleware(this, options);
   }
-  effectiveThreshold(hook) {
-    if (hook === void 0) {
-      return this.threshold;
-    }
-    return this.hookThresholds[hook] ?? this.threshold;
-  }
   async postWithRetry(payload, maxRetries = DEFAULT_MAX_RETRIES) {
     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 response.text().catch(() => "");
+          const body = await readCappedErrorBody(response);
           throw new SilmarilApiError({
             status: response.status,
             statusText: response.statusText,
@@ -684,6 +862,20 @@ var Firewall = class {
     }
     throw new Error("Firewall: exhausted retries (unreachable)");
   }
+  async classifySingleChunk(text, options, threshold) {
+    const payload = { text, threshold };
+    if (options.hook !== void 0) {
+      payload.hook = options.hook;
+    }
+    if (options.toolName !== void 0) {
+      payload.tool_name = options.toolName;
+    }
+    if (options.metadata !== void 0) {
+      payload.metadata = options.metadata;
+    }
+    const data = await this.postWithRetry(payload);
+    return blockResultFromResponse(data, threshold);
+  }
 };
 
 // src/index.ts
@@ -695,9 +887,8 @@ export {
   CHUNK_OVERLAP_CHARS,
   CHUNK_WINDOW,
   CHUNK_WINDOW_CHARS,
+  DEFAULT_CHUNK_CONCURRENCY,
   DEFAULT_HOOKS,
-  DEFAULT_HOOK_THRESHOLDS,
-  DEFAULT_THRESHOLD,
   DEFAULT_TIMEOUT_MS,
   FIREWALL_HOOK_TO_LABEL,
   Firewall,
@@ -712,6 +903,7 @@ export {
   chunkText,
   prependHook,
   prependToolName,
-  resolveHooks
+  resolveHooks,
+  sanitizeText
 };
 //# sourceMappingURL=index.js.map