@silmaril-security/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,711 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/exceptions.ts
+var MAX_PROMPT_DISPLAY_LEN, PromptBlockedException, SilmarilApiError;
+var init_exceptions = __esm({
+  "src/exceptions.ts"() {
+    "use strict";
+    MAX_PROMPT_DISPLAY_LEN = 100;
+    PromptBlockedException = class _PromptBlockedException extends Error {
+      score;
+      threshold;
+      promptText;
+      runId;
+      constructor(params) {
+        super(_PromptBlockedException.formatMessage(params));
+        this.name = "PromptBlockedException";
+        this.score = params.score;
+        this.threshold = params.threshold;
+        this.promptText = params.promptText;
+        this.runId = params.runId;
+        Object.setPrototypeOf(this, _PromptBlockedException.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}'`;
+      }
+    };
+    SilmarilApiError = class _SilmarilApiError extends Error {
+      status;
+      statusText;
+      body;
+      constructor(params) {
+        super(`Silmaril API error ${params.status} ${params.statusText}: ${params.body}`);
+        this.name = "SilmarilApiError";
+        this.status = params.status;
+        this.statusText = params.statusText;
+        this.body = params.body;
+        Object.setPrototypeOf(this, _SilmarilApiError.prototype);
+      }
+    };
+  }
+});
+
+// src/hooks.ts
+function resolveHooks(hooks) {
+  if (hooks === void 0) {
+    return DEFAULT_HOOKS;
+  }
+  const resolved = /* @__PURE__ */ new Set();
+  for (const h of hooks) {
+    if (!FIREWALL_HOOK_VALUES.has(h)) {
+      throw new Error(`Invalid FirewallHook value: ${String(h)}`);
+    }
+    resolved.add(h);
+  }
+  return resolved;
+}
+function prependHook(text, hook) {
+  if (hook === void 0 || hook === null) {
+    return text;
+  }
+  if (hook === HookLabel.UNKNOWN) {
+    return text;
+  }
+  return `[HOOK:${hook}] ${text}`;
+}
+function prependToolName(text, toolName) {
+  if (toolName === void 0 || toolName === null) {
+    return text;
+  }
+  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 init_hooks = __esm({
+  "src/hooks.ts"() {
+    "use strict";
+    HookLabel = {
+      USER_INPUT: "user_input",
+      SYSTEM_PROMPT: "system_prompt",
+      TOOL_CALL: "tool_call",
+      TOOL_RESPONSE: "tool_response",
+      LLM_OUTPUT: "llm_output",
+      UNKNOWN: "unknown"
+    };
+    FirewallHook = {
+      LLM_START: "on_llm_start",
+      CHAT_MODEL_START: "on_chat_model_start",
+      TOOL_START: "on_tool_start",
+      RETRIEVER_START: "on_retriever_start",
+      LLM_END: "on_llm_end",
+      TOOL_END: "on_tool_end",
+      RETRIEVER_END: "on_retriever_end"
+    };
+    DEFAULT_HOOKS = /* @__PURE__ */ new Set([
+      FirewallHook.LLM_START,
+      FirewallHook.CHAT_MODEL_START
+    ]);
+    INPUT_HOOKS = /* @__PURE__ */ new Set([
+      FirewallHook.LLM_START,
+      FirewallHook.CHAT_MODEL_START,
+      FirewallHook.TOOL_START,
+      FirewallHook.RETRIEVER_START
+    ]);
+    OUTPUT_HOOKS = /* @__PURE__ */ new Set([
+      FirewallHook.LLM_END,
+      FirewallHook.TOOL_END,
+      FirewallHook.RETRIEVER_END
+    ]);
+    ALL_HOOKS = /* @__PURE__ */ new Set([
+      ...INPUT_HOOKS,
+      ...OUTPUT_HOOKS
+    ]);
+    FIREWALL_HOOK_TO_LABEL = {
+      [FirewallHook.CHAT_MODEL_START]: HookLabel.USER_INPUT,
+      [FirewallHook.LLM_START]: HookLabel.USER_INPUT,
+      [FirewallHook.TOOL_START]: HookLabel.TOOL_CALL,
+      [FirewallHook.TOOL_END]: HookLabel.TOOL_RESPONSE,
+      [FirewallHook.RETRIEVER_START]: HookLabel.TOOL_CALL,
+      [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));
+  }
+});
+
+// src/utils/extract.ts
+function extractTextFromPrompts(prompts) {
+  return prompts.map((p) => p.trim()).filter((p) => p.length > 0).join("\n");
+}
+function extractTextFromToolInput(inputStr) {
+  return inputStr.trim();
+}
+function extractTextFromLLMResult(response) {
+  const parts = [];
+  for (const genList of response.generations ?? []) {
+    for (const gen of genList) {
+      const text = (gen.text ?? "").trim();
+      if (text) {
+        parts.push(text);
+      }
+    }
+  }
+  return parts.join("\n");
+}
+function extractTextFromDocuments(documents) {
+  const parts = [];
+  for (const doc of documents) {
+    const text = (doc.pageContent ?? "").trim();
+    if (text) {
+      parts.push(text);
+    }
+  }
+  return parts.join("\n");
+}
+var init_extract = __esm({
+  "src/utils/extract.ts"() {
+    "use strict";
+  }
+});
+
+// src/adapters/langchain.ts
+var langchain_exports = {};
+__export(langchain_exports, {
+  createLangChainHandler: () => createLangChainHandler
+});
+function getMessageRole(message) {
+  if (typeof message.role === "string") {
+    return message.role.toLowerCase();
+  }
+  if (typeof message.type === "string") {
+    return message.type.toLowerCase();
+  }
+  return "";
+}
+function extractMessageText(content) {
+  if (content === void 0) {
+    return "";
+  }
+  if (typeof content === "string") {
+    return content;
+  }
+  const parts = [];
+  for (const block of content) {
+    if (typeof block === "string") {
+      parts.push(block);
+    } else if (block && block.type === "text") {
+      parts.push(block.text ?? "");
+    }
+  }
+  return parts.join(" ");
+}
+function findLastUserMessage2(messages) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (USER_ROLES.has(getMessageRole(msg))) {
+      return msg;
+    }
+  }
+  return void 0;
+}
+async function createLangChainHandler(firewall, options = {}) {
+  const { BaseCallbackHandler } = await import("@langchain/core/callbacks/base");
+  const enabledHooks = resolveHooks(options.hooks);
+  const failOpen = options.failOpen ?? true;
+  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];
+    }
+    if (firewall.hookThresholds[label] !== void 0) {
+      return firewall.hookThresholds[label];
+    }
+    return overrideThreshold ?? firewall.threshold;
+  };
+  const classify = async (text, hookLabel, runId, toolName) => {
+    try {
+      const 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);
+    }
+  };
+  class SilmarilFirewallHandler extends BaseCallbackHandler {
+    name = "silmaril_firewall_handler";
+    raiseError = true;
+    awaitHandlers = true;
+    async handleChatModelStart(_llm, messages, runId) {
+      if (!enabledHooks.has(FirewallHook.CHAT_MODEL_START)) {
+        return;
+      }
+      const batches = messages;
+      const flat = [];
+      for (const batch of batches) {
+        for (const m of batch) {
+          flat.push(m);
+        }
+      }
+      const lastUser = findLastUserMessage2(flat);
+      if (!lastUser) {
+        return;
+      }
+      const text = extractMessageText(lastUser.content).trim();
+      if (!text) {
+        return;
+      }
+      await classify(text, FIREWALL_HOOK_TO_LABEL[FirewallHook.CHAT_MODEL_START], runId);
+    }
+    async handleLLMStart(_llm, prompts, runId) {
+      if (!enabledHooks.has(FirewallHook.LLM_START)) {
+        return;
+      }
+      const text = extractTextFromPrompts(prompts);
+      if (!text) {
+        return;
+      }
+      await classify(text, FIREWALL_HOOK_TO_LABEL[FirewallHook.LLM_START], runId);
+    }
+    async handleToolStart(tool, inputStr, runId) {
+      if (!enabledHooks.has(FirewallHook.TOOL_START)) {
+        return;
+      }
+      const text = extractTextFromToolInput(inputStr);
+      if (!text) {
+        return;
+      }
+      const toolName = tool?.name;
+      const prefixed = prependToolName(text, toolName);
+      await classify(prefixed, FIREWALL_HOOK_TO_LABEL[FirewallHook.TOOL_START], runId, toolName);
+    }
+    async handleRetrieverStart(_retriever, query, runId) {
+      if (!enabledHooks.has(FirewallHook.RETRIEVER_START)) {
+        return;
+      }
+      const text = query.trim();
+      if (!text) {
+        return;
+      }
+      await classify(text, FIREWALL_HOOK_TO_LABEL[FirewallHook.RETRIEVER_START], runId);
+    }
+    async handleLLMEnd(output, runId) {
+      if (!enabledHooks.has(FirewallHook.LLM_END)) {
+        return;
+      }
+      const text = extractTextFromLLMResult(output);
+      if (!text) {
+        return;
+      }
+      await classify(text, FIREWALL_HOOK_TO_LABEL[FirewallHook.LLM_END], runId);
+    }
+    async handleToolEnd(output, runId, _parentRunId, _tags, _kwargs) {
+      if (!enabledHooks.has(FirewallHook.TOOL_END)) {
+        return;
+      }
+      const text = String(output).trim();
+      if (!text) {
+        return;
+      }
+      const toolName = _kwargs?.name;
+      const prefixed = prependToolName(text, toolName);
+      await classify(prefixed, FIREWALL_HOOK_TO_LABEL[FirewallHook.TOOL_END], runId, toolName);
+    }
+    async handleRetrieverEnd(documents, runId) {
+      if (!enabledHooks.has(FirewallHook.RETRIEVER_END)) {
+        return;
+      }
+      const text = extractTextFromDocuments(documents);
+      if (!text) {
+        return;
+      }
+      await classify(text, FIREWALL_HOOK_TO_LABEL[FirewallHook.RETRIEVER_END], runId);
+    }
+  }
+  return new SilmarilFirewallHandler();
+}
+var USER_ROLES;
+var init_langchain = __esm({
+  "src/adapters/langchain.ts"() {
+    "use strict";
+    init_exceptions();
+    init_hooks();
+    init_extract();
+    USER_ROLES = /* @__PURE__ */ new Set(["human", "user"]);
+  }
+});
+
+// src/adapters/vercel.ts
+init_exceptions();
+init_hooks();
+function stringifyToolValue(value) {
+  if (value === null || value === void 0) {
+    return "";
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+function extractContentText(content) {
+  if (typeof content === "string") {
+    return content;
+  }
+  const parts = [];
+  for (const block of content) {
+    if (typeof block === "string") {
+      parts.push(block);
+    } else if (block && block.type === "text") {
+      parts.push(block.text ?? "");
+    }
+  }
+  return parts.join(" ");
+}
+function iterateToolResultParts(message) {
+  if (typeof message.content === "string") {
+    return [];
+  }
+  const out = [];
+  for (const part of message.content) {
+    if (typeof part === "string") {
+      continue;
+    }
+    if (part.type === "tool-result") {
+      const text = stringifyToolValue(part.result);
+      if (text.trim()) {
+        out.push({ text, toolName: part.toolName });
+      }
+    }
+  }
+  return out;
+}
+function findLastUserMessage(messages) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg.role.toLowerCase() === "user") {
+      return msg;
+    }
+  }
+  return void 0;
+}
+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 classifyOrBlock = async (text, hook, toolName) => {
+    if (!text.trim()) {
+      return;
+    }
+    const result = await firewall.classify(
+      text,
+      toolName !== void 0 ? { hook, toolName } : { hook }
+    );
+    const threshold = effectiveThreshold(hook);
+    const blocked = result.score >= threshold;
+    options.onClassify?.({
+      hook,
+      ...toolName !== void 0 ? { toolName } : {},
+      text,
+      result,
+      blocked
+    });
+    if (blocked) {
+      const err = new PromptBlockedException({
+        score: result.score,
+        threshold,
+        promptText: text
+      });
+      options.onBlocked?.(err);
+      throw err;
+    }
+  };
+  const scanPrompt = async (prompt) => {
+    if (prompt.length === 0) {
+      return;
+    }
+    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);
+      }
+      return;
+    }
+    const lastUser = findLastUserMessage(prompt);
+    if (!lastUser) {
+      return;
+    }
+    const text = extractContentText(lastUser.content).trim();
+    if (!text) {
+      return;
+    }
+    await classifyOrBlock(text, HookLabel.USER_INPUT);
+  };
+  const scanGenerateResult = async (result) => {
+    if (scanOutput && typeof result.text === "string" && result.text.length > 0) {
+      await classifyOrBlock(result.text, HookLabel.LLM_OUTPUT);
+    }
+    if (options.scanToolCalls && Array.isArray(result.toolCalls)) {
+      for (const call of result.toolCalls) {
+        if (!call || typeof call !== "object") {
+          continue;
+        }
+        const args = typeof call.args === "string" ? call.args : stringifyToolValue(call.args);
+        const toolName = typeof call.toolName === "string" ? call.toolName : void 0;
+        if (args.trim()) {
+          await classifyOrBlock(args, HookLabel.TOOL_CALL, toolName);
+        }
+      }
+    }
+  };
+  return {
+    async wrapGenerate({ params, doGenerate }) {
+      if (scanInput) {
+        await scanPrompt(params.prompt);
+      }
+      const result = await doGenerate();
+      await scanGenerateResult(result);
+      return result;
+    },
+    async wrapStream({ params, doStream }) {
+      if (scanInput) {
+        await scanPrompt(params.prompt);
+      }
+      const { stream, ...rest } = await doStream();
+      if (!scanOutput) {
+        return { stream, ...rest };
+      }
+      let buffered = "";
+      const transformed = stream.pipeThrough(
+        new TransformStream({
+          transform(chunk, controller) {
+            const part = chunk;
+            if (part && part.type === "text-delta") {
+              const delta = part.textDelta ?? part.delta ?? "";
+              buffered += delta;
+            }
+            controller.enqueue(chunk);
+          },
+          async flush(controller) {
+            if (!buffered.trim()) {
+              return;
+            }
+            try {
+              await classifyOrBlock(buffered, HookLabel.LLM_OUTPUT);
+            } catch (err) {
+              if (err instanceof PromptBlockedException) {
+                controller.enqueue({ type: "error", error: err });
+                return;
+              }
+              throw err;
+            }
+          }
+        })
+      );
+      return { stream: transformed, ...rest };
+    }
+  };
+}
+
+// src/chunking.ts
+var CHARS_PER_TOKEN = 4;
+var MAX_INPUT_TOKENS = 10240;
+var CHUNK_WINDOW = 400;
+var CHUNK_OVERLAP = 64;
+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 chunkText(text) {
+  const n = text.length;
+  if (n > MAX_INPUT_CHARS) {
+    throw new Error(
+      `Input has ~${Math.floor(n / CHARS_PER_TOKEN)} tokens (${n} chars); max is ${MAX_INPUT_TOKENS} tokens (${MAX_INPUT_CHARS} chars)`
+    );
+  }
+  if (n <= CHUNK_WINDOW_CHARS) {
+    return [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));
+    if (end >= n) {
+      break;
+    }
+  }
+  return chunks;
+}
+
+// src/firewall.ts
+init_exceptions();
+var DEFAULT_THRESHOLD = 0.5;
+var DEFAULT_TIMEOUT_MS = 1e4;
+var DEFAULT_MAX_RETRIES = 5;
+var MAX_BACKOFF_SECONDS = 30;
+var Firewall = class {
+  apiKey;
+  apiUrl;
+  threshold;
+  timeoutMs;
+  hookThresholds;
+  headers;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error("Firewall: apiKey is required");
+    }
+    if (!options.apiUrl) {
+      throw new Error("Firewall: apiUrl is required");
+    }
+    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 ?? {};
+    this.headers = Object.freeze({
+      "x-api-key": this.apiKey,
+      "content-type": "application/json"
+    });
+  }
+  async classify(text, options = {}) {
+    const chunks = chunkText(text);
+    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);
+    }
+    if (options.toolName !== void 0) {
+      batchOpts.toolNames = chunks.map(() => options.toolName);
+    }
+    const results = await this.classifyBatch(chunks, batchOpts);
+    return results.reduce((best, r) => r.score > best.score ? r : best);
+  }
+  async classifyBatch(texts, options = {}) {
+    const payload = { texts };
+    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);
+    }
+    const data = await this.postWithRetry(payload);
+    return data.predictions.map(
+      (p) => Object.freeze({ prediction: p.prediction, score: Number(p.score) })
+    );
+  }
+  asLangChainHandler(options = {}) {
+    return Promise.resolve().then(() => (init_langchain(), langchain_exports)).then((m) => m.createLangChainHandler(this, options));
+  }
+  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),
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+      if (response.status !== 429 || attempt === maxRetries) {
+        if (!response.ok) {
+          const body = await response.text().catch(() => "");
+          throw new SilmarilApiError({
+            status: response.status,
+            statusText: response.statusText,
+            body
+          });
+        }
+        return await response.json();
+      }
+      const waitSeconds = Math.min(2 ** attempt, MAX_BACKOFF_SECONDS);
+      await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1e3));
+    }
+    throw new Error("Firewall: exhausted retries (unreachable)");
+  }
+};
+
+// src/index.ts
+init_exceptions();
+init_hooks();
+export {
+  ALL_HOOKS,
+  CHUNK_OVERLAP,
+  CHUNK_OVERLAP_CHARS,
+  CHUNK_WINDOW,
+  CHUNK_WINDOW_CHARS,
+  DEFAULT_HOOKS,
+  DEFAULT_HOOK_THRESHOLDS,
+  DEFAULT_THRESHOLD,
+  DEFAULT_TIMEOUT_MS,
+  FIREWALL_HOOK_TO_LABEL,
+  Firewall,
+  FirewallHook,
+  HookLabel,
+  INPUT_HOOKS,
+  MAX_INPUT_CHARS,
+  MAX_INPUT_TOKENS,
+  OUTPUT_HOOKS,
+  PromptBlockedException,
+  SilmarilApiError,
+  chunkText,
+  prependHook,
+  prependToolName,
+  resolveHooks
+};
+//# sourceMappingURL=index.js.map