@silmaril-security/sdk 0.3.1 → 0.4.2

package/dist/index.cjs

@@ -47,30 +47,39 @@ function parseErrorBody(body) {
     return { details: void 0, error: void 0, apiMessage: void 0 };
   }
 }
-var MAX_PROMPT_DISPLAY_LEN, PromptBlockedException, SilmarilApiError;
+var MAX_PROMPT_DISPLAY_LEN, FirewallBlockedException, PromptBlockedException, SilmarilApiError;
 var init_exceptions = __esm({
   "src/exceptions.ts"() {
     "use strict";
     MAX_PROMPT_DISPLAY_LEN = 100;
-    PromptBlockedException = class _PromptBlockedException extends Error {
+    FirewallBlockedException = class _FirewallBlockedException extends Error {
       score;
       threshold;
       promptText;
       runId;
+      hook;
+      toolName;
+      toolCallId;
+      result;
       constructor(params) {
-        super(_PromptBlockedException.formatMessage(params));
-        this.name = "PromptBlockedException";
+        super(_FirewallBlockedException.formatMessage(params));
+        this.name = "FirewallBlockedException";
         this.score = params.score;
         this.threshold = params.threshold;
         this.promptText = params.promptText;
         this.runId = params.runId;
-        Object.setPrototypeOf(this, _PromptBlockedException.prototype);
+        this.hook = params.hook;
+        this.toolName = params.toolName;
+        this.toolCallId = params.toolCallId;
+        this.result = params.result;
+        Object.setPrototypeOf(this, _FirewallBlockedException.prototype);
       }
       static formatMessage(params) {
         const truncated = params.promptText.length > MAX_PROMPT_DISPLAY_LEN ? `${params.promptText.slice(0, MAX_PROMPT_DISPLAY_LEN)}...` : params.promptText;
-        return `Prompt blocked by Silmaril Firewall (score=${params.score.toFixed(4)}, threshold=${params.threshold.toFixed(4)}): '${truncated}'`;
+        return `Request blocked by Silmaril Firewall (score=${params.score.toFixed(4)}, threshold=${params.threshold.toFixed(4)}): '${truncated}'`;
       }
     };
+    PromptBlockedException = FirewallBlockedException;
     SilmarilApiError = class _SilmarilApiError extends Error {
       status;
       statusText;
@@ -261,19 +270,12 @@ async function createLangChainHandler(firewall, options = {}) {
   });
   const shadowMode = options.shadowMode ?? firewall.shadowMode;
   const onClassify = options.onClassify;
-  const fireOnClassify = (hookLabel, text, result, blocked, toolName) => {
+  const fireOnClassify = (event) => {
     if (!onClassify) {
       return;
     }
     try {
-      onClassify({
-        hook: hookLabel,
-        ...toolName !== void 0 ? { toolName } : {},
-        text,
-        result,
-        blocked,
-        shadowMode
-      });
+      onClassify(event);
     } catch (err) {
       logger("onClassify callback threw", err);
     }
@@ -294,15 +296,30 @@ async function createLangChainHandler(firewall, options = {}) {
     }
     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
-      });
+    const commonEventFields = {
+      hook: hookLabel,
+      ...toolName !== void 0 ? { toolName } : {},
+      runId,
+      text,
+      result
+    };
+    fireOnClassify({
+      ...commonEventFields,
+      blocked,
+      shadowMode
+    });
+    if (!blocked || shadowMode) {
+      return;
     }
+    throw new FirewallBlockedException({
+      score: result.score,
+      threshold,
+      promptText: text,
+      runId,
+      hook: hookLabel,
+      ...toolName !== void 0 ? { toolName } : {},
+      result
+    });
   };
   class SilmarilFirewallHandler extends BaseCallbackHandler {
     name = "silmaril_firewall_handler";
@@ -406,8 +423,8 @@ var init_langchain = __esm({
 });
 
 // src/index.ts
-var index_exports = {};
-__export(index_exports, {
+var src_exports = {};
+__export(src_exports, {
   ALL_HOOKS: () => ALL_HOOKS,
   CHUNK_OVERLAP: () => CHUNK_OVERLAP,
   CHUNK_OVERLAP_CHARS: () => CHUNK_OVERLAP_CHARS,
@@ -418,21 +435,34 @@ __export(index_exports, {
   DEFAULT_TIMEOUT_MS: () => DEFAULT_TIMEOUT_MS,
   FIREWALL_HOOK_TO_LABEL: () => FIREWALL_HOOK_TO_LABEL,
   Firewall: () => Firewall,
+  FirewallBlockedException: () => FirewallBlockedException,
   FirewallHook: () => FirewallHook,
+  HARMFUL_OUTCOMES: () => HARMFUL_OUTCOMES,
   HookLabel: () => HookLabel,
   INPUT_HOOKS: () => INPUT_HOOKS,
   MAX_INPUT_CHARS: () => MAX_INPUT_CHARS,
   MAX_INPUT_TOKENS: () => MAX_INPUT_TOKENS,
+  OUTCOME_DESCRIPTIONS: () => OUTCOME_DESCRIPTIONS,
   OUTPUT_HOOKS: () => OUTPUT_HOOKS,
+  Outcome: () => Outcome,
+  PRIMARY_OUTCOMES: () => PRIMARY_OUTCOMES,
   PromptBlockedException: () => PromptBlockedException,
   SilmarilApiError: () => SilmarilApiError,
   chunkText: () => chunkText,
+  isHarmfulOutcome: () => isHarmfulOutcome,
+  isPrimaryOutcome: () => isPrimaryOutcome,
+  normalizeHarmfulOutcome: () => normalizeHarmfulOutcome,
+  normalizeHarmfulOutcomeMap: () => normalizeHarmfulOutcomeMap,
+  normalizePrimaryOutcome: () => normalizePrimaryOutcome,
   prependHook: () => prependHook,
   prependToolName: () => prependToolName,
   resolveHooks: () => resolveHooks,
   sanitizeText: () => sanitizeText
 });
-module.exports = __toCommonJS(index_exports);
+module.exports = __toCommonJS(src_exports);
+
+// src/firewall.ts
+var import_node_crypto = require("crypto");
 
 // src/adapters/vercel.ts
 init_exceptions();
@@ -450,6 +480,9 @@ function stringifyToolValue(value) {
     return String(value);
   }
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function extractContentText(content) {
   if (typeof content === "string") {
     return content;
@@ -474,14 +507,29 @@ function iterateToolResultParts(message) {
       continue;
     }
     if (part.type === "tool-result") {
-      const text = stringifyToolValue(part.result);
+      const text = stringifyToolResult(part.result !== void 0 ? part.result : part.output);
       if (text.trim()) {
-        out.push({ text, toolName: part.toolName });
+        out.push({ text, toolName: part.toolName, toolCallId: part.toolCallId });
       }
     }
   }
   return out;
 }
+function stringifyToolResult(value) {
+  if (!isRecord(value)) {
+    return stringifyToolValue(value);
+  }
+  if ((value.type === "text" || value.type === "error-text") && typeof value.value === "string") {
+    return value.value;
+  }
+  if ((value.type === "json" || value.type === "error-json") && value.value !== void 0) {
+    return stringifyToolValue(value.value);
+  }
+  if (value.type === "content" && Array.isArray(value.value)) {
+    return value.value.map((part) => isRecord(part) && part.type === "text" && typeof part.text === "string" ? part.text : "").filter((text) => text.length > 0).join(" ");
+  }
+  return stringifyToolValue(value);
+}
 function findLastUserMessage(messages) {
   for (let i = messages.length - 1; i >= 0; i--) {
     const msg = messages[i];
@@ -495,33 +543,43 @@ function createMiddleware(firewall, options = {}) {
   const scanInput = options.scanInput ?? true;
   const scanOutput = options.scanOutput ?? false;
   const shadowMode = options.shadowMode ?? firewall.shadowMode;
-  const classifyOrBlock = async (text, hook, toolName) => {
+  const classifyOrBlock = async (text, hook, context = { toolName: void 0, toolCallId: void 0 }) => {
     if (!text.trim()) {
       return;
     }
+    const { toolName, toolCallId } = context;
     const result = await firewall.classify(
       text,
       toolName !== void 0 ? { hook, toolName } : { hook }
     );
     const threshold = result.threshold;
     const blocked = result.score >= threshold;
-    options.onClassify?.({
+    const commonEventFields = {
       hook,
       ...toolName !== void 0 ? { toolName } : {},
+      ...toolCallId !== void 0 ? { toolCallId } : {},
       text,
-      result,
+      result
+    };
+    options.onClassify?.({
+      ...commonEventFields,
       blocked,
       shadowMode
     });
-    if (blocked && !shadowMode) {
-      const err = new PromptBlockedException({
-        score: result.score,
-        threshold,
-        promptText: text
-      });
-      options.onBlocked?.(err);
-      throw err;
+    if (!blocked || shadowMode) {
+      return;
     }
+    const err = new FirewallBlockedException({
+      score: result.score,
+      threshold,
+      promptText: text,
+      hook,
+      ...toolName !== void 0 ? { toolName } : {},
+      ...toolCallId !== void 0 ? { toolCallId } : {},
+      result
+    });
+    options.onBlocked?.(err);
+    throw err;
   };
   const scanPrompt = async (prompt) => {
     if (prompt.length === 0) {
@@ -530,8 +588,8 @@ function createMiddleware(firewall, options = {}) {
     const last = prompt[prompt.length - 1];
     const role = last.role.toLowerCase();
     if (role === "tool") {
-      for (const { text: text2, toolName } of iterateToolResultParts(last)) {
-        await classifyOrBlock(text2, HookLabel.TOOL_RESPONSE, toolName);
+      for (const { text: text2, toolName, toolCallId } of iterateToolResultParts(last)) {
+        await classifyOrBlock(text2, HookLabel.TOOL_RESPONSE, { toolName, toolCallId });
       }
       return;
     }
@@ -554,21 +612,25 @@ function createMiddleware(firewall, options = {}) {
         if (!call || typeof call !== "object") {
           continue;
         }
-        const args = typeof call.args === "string" ? call.args : stringifyToolValue(call.args);
+        const toolInput = call.args !== void 0 ? call.args : call.input;
+        const args = typeof toolInput === "string" ? toolInput : stringifyToolValue(toolInput);
         const toolName = typeof call.toolName === "string" ? call.toolName : void 0;
+        const toolCallId = typeof call.toolCallId === "string" ? call.toolCallId : void 0;
         if (args.trim()) {
-          await classifyOrBlock(args, HookLabel.TOOL_CALL, toolName);
+          await classifyOrBlock(args, HookLabel.TOOL_CALL, { toolName, toolCallId });
         }
       }
     }
   };
   return {
+    specificationVersion: "v3",
+    middlewareVersion: "v2",
     async wrapGenerate({
       params,
       doGenerate
     }) {
       if (scanInput) {
-        await scanPrompt(params.prompt);
+        await scanPrompt(params.prompt ?? []);
       }
       const result = await doGenerate();
       await scanGenerateResult(result);
@@ -579,7 +641,7 @@ function createMiddleware(firewall, options = {}) {
       doStream
     }) {
       if (scanInput) {
-        await scanPrompt(params.prompt);
+        await scanPrompt(params.prompt ?? []);
       }
       const { stream, ...rest } = await doStream();
       if (!scanOutput) {
@@ -603,7 +665,7 @@ function createMiddleware(firewall, options = {}) {
             try {
               await classifyOrBlock(buffered, HookLabel.LLM_OUTPUT);
             } catch (err) {
-              if (err instanceof PromptBlockedException) {
+              if (err instanceof FirewallBlockedException) {
                 controller.enqueue({ type: "error", error: err });
                 return;
               }
@@ -691,54 +753,133 @@ function chunkText(text) {
 
 // src/firewall.ts
 init_exceptions();
-var BASE_THRESHOLD = 0.5;
-var TARGET_SEQUENCE_FPR = 0.01;
-var MAX_ADAPTIVE_THRESHOLD = 0.9;
+
+// src/outcomes.ts
+var Outcome = {
+  Benign: "benign",
+  InformationDisclosure: "information_disclosure",
+  SecretExposure: "secret_exposure",
+  ControlAbuse: "control_abuse",
+  SystemCompromise: "system_compromise",
+  ServiceDisruption: "service_disruption"
+};
+var PRIMARY_OUTCOMES = [
+  Outcome.Benign,
+  Outcome.InformationDisclosure,
+  Outcome.SecretExposure,
+  Outcome.ControlAbuse,
+  Outcome.SystemCompromise,
+  Outcome.ServiceDisruption
+];
+var HARMFUL_OUTCOMES = [
+  Outcome.InformationDisclosure,
+  Outcome.SecretExposure,
+  Outcome.ControlAbuse,
+  Outcome.SystemCompromise,
+  Outcome.ServiceDisruption
+];
+var OUTCOME_DESCRIPTIONS = {
+  [Outcome.Benign]: "No harmful firewall outcome detected.",
+  [Outcome.InformationDisclosure]: "Exposes private data, documents, internal context, logs, traces, customer data, SQL rows, topology, or similar non-secret sensitive information.",
+  [Outcome.SecretExposure]: "Exposes credentials, tokens, API keys, cookies, passwords, signing keys, OAuth secrets, session material, or webhook secrets.",
+  [Outcome.ControlAbuse]: "Misuses authorized tools or user privileges to send, change, approve, delete, operate, or bypass policy/RBAC without a stronger outcome.",
+  [Outcome.SystemCompromise]: "Enables privilege escalation, account takeover, hostile integration or plugin takeover, persistence, lateral movement, attacker webhook registration, or code/plugin execution.",
+  [Outcome.ServiceDisruption]: "Causes downtime, lockout, degradation, alert suppression, destructive loops, resource exhaustion, cost spikes, or hidden outage evidence."
+};
+var PRIMARY_OUTCOME_SET = new Set(PRIMARY_OUTCOMES);
+var HARMFUL_OUTCOME_SET = new Set(HARMFUL_OUTCOMES);
+function isPrimaryOutcome(value) {
+  return typeof value === "string" && PRIMARY_OUTCOME_SET.has(value);
+}
+function isHarmfulOutcome(value) {
+  return typeof value === "string" && HARMFUL_OUTCOME_SET.has(value);
+}
+function normalizePrimaryOutcome(value, fieldName = "primary_outcome") {
+  if (typeof value !== "string") {
+    throw new Error(`Firewall: invalid ${fieldName} ${JSON.stringify(value)}`);
+  }
+  return isPrimaryOutcome(value) ? value : value;
+}
+function normalizeHarmfulOutcome(value, fieldName = "outcome") {
+  if (typeof value !== "string" || value === Outcome.Benign) {
+    throw new Error(`Firewall: invalid ${fieldName} ${JSON.stringify(value)}`);
+  }
+  return isHarmfulOutcome(value) ? value : value;
+}
+function normalizeHarmfulOutcomeMap(values, fieldName) {
+  if (values === void 0 || values === null) {
+    return void 0;
+  }
+  if (typeof values !== "object" || Array.isArray(values)) {
+    throw new Error(`Firewall: invalid ${fieldName} ${JSON.stringify(values)}`);
+  }
+  const out = {};
+  for (const [key, value] of Object.entries(values)) {
+    const normalizedKey = normalizeHarmfulOutcome(key, `${fieldName} key`);
+    if (typeof value !== "number") {
+      throw new Error(`Firewall: invalid ${fieldName} value for ${JSON.stringify(key)}`);
+    }
+    out[normalizedKey] = value;
+  }
+  return Object.freeze(out);
+}
+
+// src/firewall.ts
+var SDK_VERSION = "0.4.2";
 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) {
+function blockResultFromResponse(data) {
   const result = {
     prediction: data.prediction,
     score: Number(data.score),
-    threshold
+    threshold: Number(data.threshold)
   };
   if (data.primary_outcome !== void 0) {
-    result.primaryOutcome = data.primary_outcome;
+    result.primaryOutcome = normalizePrimaryOutcome(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)]))
-    );
+    const outcomeScores = normalizeHarmfulOutcomeMap(data.outcome_scores, "outcome_scores");
+    if (outcomeScores !== void 0) {
+      result.outcomeScores = outcomeScores;
+    }
   }
   if (data.detector_scores !== void 0) {
-    result.detectorScores = Object.freeze(
-      Object.fromEntries(Object.entries(data.detector_scores).map(([k, v]) => [k, Number(v)]))
-    );
+    const detectorScores = normalizeHarmfulOutcomeMap(data.detector_scores, "detector_scores");
+    if (detectorScores !== void 0) {
+      result.detectorScores = detectorScores;
+    }
   }
   if (data.detector_counts !== void 0) {
-    result.detectorCounts = Object.freeze(
-      Object.fromEntries(Object.entries(data.detector_counts).map(([k, v]) => [k, Number(v)]))
-    );
+    const detectorCounts = normalizeHarmfulOutcomeMap(data.detector_counts, "detector_counts");
+    if (detectorCounts !== void 0) {
+      result.detectorCounts = detectorCounts;
+    }
   }
   return Object.freeze(result);
 }
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function withSdkMetadata(metadata, info) {
+  const payload = { ...metadata ?? {} };
+  const existing = payload.silmaril;
+  if (existing !== void 0 && !isRecord2(existing)) {
+    throw new Error("Firewall: metadata.silmaril must be an object when provided");
+  }
+  payload.silmaril = {
+    ...isRecord2(existing) ? existing : {},
+    sdk_language: "typescript",
+    sdk_version: SDK_VERSION,
+    request_id: info.requestId,
+    input_index: info.inputIndex,
+    chunk_index: info.chunkIndex,
+    chunk_count: info.chunkCount
+  };
+  return payload;
+}
 async function readCappedErrorBody(response) {
   if (!response.body) {
     return response.text().then((body2) => body2.slice(0, MAX_ERROR_BODY_BYTES)).catch(() => "");
@@ -835,14 +976,24 @@ var Firewall = class {
   }
   async classify(text, options = {}) {
     const chunks = chunkText(text);
-    const threshold = adaptiveThreshold(chunks.length);
+    const requestId = options.requestId ?? (0, import_node_crypto.randomUUID)();
     if (chunks.length === 1) {
-      return this.classifySingleChunk(chunks[0], options, threshold);
+      return this.classifySingleChunk(chunks[0], options, {
+        requestId,
+        inputIndex: 0,
+        chunkIndex: 0,
+        chunkCount: 1
+      });
     }
     const results = await mapWithConcurrency(
       chunks,
       this.chunkConcurrency,
-      (chunk) => this.classifySingleChunk(chunk, options, threshold)
+      (chunk, index) => this.classifySingleChunk(chunk, options, {
+        requestId,
+        inputIndex: 0,
+        chunkIndex: index,
+        chunkCount: chunks.length
+      })
     );
     return results.reduce((best, r) => r.score > best.score ? r : best);
   }
@@ -865,10 +1016,9 @@ var Firewall = class {
         `Firewall: metadata length ${options.metadata.length} does not match texts length ${texts.length}`
       );
     }
-    const threshold = adaptiveThreshold(texts.length);
+    const requestId = options.requestId ?? (0, import_node_crypto.randomUUID)();
     const payload = {
-      texts: texts.map((text) => sanitizeText(text)),
-      threshold
+      texts: texts.map((text) => sanitizeText(text))
     };
     if (options.hooks && options.hooks.length > 0) {
       payload.hooks = options.hooks.map((h) => String(h));
@@ -876,14 +1026,21 @@ var Firewall = class {
     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);
-    }
+    payload.metadata = texts.map(
+      (_, index) => withSdkMetadata(options.metadata?.[index], {
+        requestId,
+        inputIndex: index,
+        chunkIndex: 0,
+        chunkCount: 1
+      })
+    );
     const data = await this.postWithRetry(payload);
-    return data.predictions.map((p) => blockResultFromResponse(p, threshold));
+    return data.predictions.map((p) => blockResultFromResponse(p));
   }
   asLangChainHandler(options = {}) {
-    return Promise.resolve().then(() => (init_langchain(), langchain_exports)).then((m) => m.createLangChainHandler(this, options));
+    return Promise.resolve().then(() => (init_langchain(), langchain_exports)).then(
+      (m) => m.createLangChainHandler(this, options)
+    );
   }
   asMiddleware(options = {}) {
     return createMiddleware(this, options);
@@ -913,19 +1070,17 @@ var Firewall = class {
     }
     throw new Error("Firewall: exhausted retries (unreachable)");
   }
-  async classifySingleChunk(text, options, threshold) {
-    const payload = { text, threshold };
+  async classifySingleChunk(text, options, metadataInfo) {
+    const payload = { text };
     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;
-    }
+    payload.metadata = withSdkMetadata(options.metadata, metadataInfo);
     const data = await this.postWithRetry(payload);
-    return blockResultFromResponse(data, threshold);
+    return blockResultFromResponse(data);
   }
 };
 
@@ -944,15 +1099,25 @@ init_hooks();
   DEFAULT_TIMEOUT_MS,
   FIREWALL_HOOK_TO_LABEL,
   Firewall,
+  FirewallBlockedException,
   FirewallHook,
+  HARMFUL_OUTCOMES,
   HookLabel,
   INPUT_HOOKS,
   MAX_INPUT_CHARS,
   MAX_INPUT_TOKENS,
+  OUTCOME_DESCRIPTIONS,
   OUTPUT_HOOKS,
+  Outcome,
+  PRIMARY_OUTCOMES,
   PromptBlockedException,
   SilmarilApiError,
   chunkText,
+  isHarmfulOutcome,
+  isPrimaryOutcome,
+  normalizeHarmfulOutcome,
+  normalizeHarmfulOutcomeMap,
+  normalizePrimaryOutcome,
   prependHook,
   prependToolName,
   resolveHooks,