@silmaril-security/sdk 0.7.6 → 0.7.8

package/dist/index.cjs

@@ -36,6 +36,19 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/exceptions.ts
+function isReviewCompatibilityError(error) {
+  if (typeof error !== "object" && typeof error !== "function" || error === null) {
+    return false;
+  }
+  try {
+    return Object.getOwnPropertyDescriptor(
+      error,
+      REVIEW_COMPATIBILITY_ERROR_BRAND
+    )?.value === true;
+  } catch {
+    return false;
+  }
+}
 function parseErrorBody(body) {
   try {
     const parsed = JSON.parse(body);
@@ -52,7 +65,7 @@ function parseErrorBody(body) {
     return { details: void 0, error: void 0, apiMessage: void 0 };
   }
 }
-var MAX_PROMPT_DISPLAY_LEN, FirewallBlockedException, PromptBlockedException, SilmarilApiError;
+var MAX_PROMPT_DISPLAY_LEN, FirewallBlockedException, PromptBlockedException, REVIEW_COMPATIBILITY_ERROR_BRAND, ReviewCompatibilityError, SilmarilApiError;
 var init_exceptions = __esm({
   "src/exceptions.ts"() {
     "use strict";
@@ -88,6 +101,27 @@ var init_exceptions = __esm({
       }
     };
     PromptBlockedException = FirewallBlockedException;
+    REVIEW_COMPATIBILITY_ERROR_BRAND = /* @__PURE__ */ Symbol.for(
+      "@silmaril-security/sdk/ReviewCompatibilityError"
+    );
+    ReviewCompatibilityError = class _ReviewCompatibilityError extends Error {
+      requestedReview;
+      acknowledgedReview;
+      constructor(requestedReview, acknowledgedReview) {
+        const detail = acknowledgedReview === void 0 ? "the response omitted its acknowledgement" : "the response acknowledgement did not match";
+        super(`Silmaril review compatibility error: ${detail} for requested ${requestedReview} review`);
+        this.name = "ReviewCompatibilityError";
+        this.requestedReview = requestedReview;
+        this.acknowledgedReview = acknowledgedReview;
+        Object.defineProperty(this, REVIEW_COMPATIBILITY_ERROR_BRAND, {
+          value: true,
+          enumerable: false,
+          configurable: false,
+          writable: false
+        });
+        Object.setPrototypeOf(this, _ReviewCompatibilityError.prototype);
+      }
+    };
     SilmarilApiError = class _SilmarilApiError extends Error {
       status;
       statusText;
@@ -304,6 +338,9 @@ async function createLangChainHandler(firewall, options = {}) {
         ...toolName !== void 0 ? { toolName } : {}
       });
     } catch (err) {
+      if (isReviewCompatibilityError(err)) {
+        throw err;
+      }
       if (!failOpen) {
         throw err;
       }
@@ -458,6 +495,7 @@ __export(src_exports, {
   Outcome: () => Outcome,
   PRIMARY_OUTCOMES: () => PRIMARY_OUTCOMES,
   PromptBlockedException: () => PromptBlockedException,
+  ReviewCompatibilityError: () => ReviewCompatibilityError,
   SilmarilApiError: () => SilmarilApiError,
   isHarmfulOutcome: () => isHarmfulOutcome,
   isPrimaryOutcome: () => isPrimaryOutcome,
@@ -818,12 +856,32 @@ function sanitizeText(text) {
 }
 
 // src/firewall.ts
-var SDK_VERSION = "0.7.6";
+var SDK_VERSION = "0.7.8";
 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 validateReview(value, name) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (value !== "standard" && value !== "deep") {
+    throw new Error(`Firewall: ${name} must be standard or deep`);
+  }
+  return value;
+}
+function resolveReview(perCallReview, clientReview) {
+  return perCallReview === void 0 ? clientReview : validateReview(perCallReview, "review");
+}
+function verifyReviewAcknowledgement(acknowledgedReview, requestedReview) {
+  if (requestedReview !== void 0 && acknowledgedReview !== requestedReview) {
+    throw new ReviewCompatibilityError(requestedReview, acknowledgedReview);
+  }
+}
+function reviewAcknowledgementFromResponse(response) {
+  return isRecord2(response) ? response.review : void 0;
+}
 function resolveMode(value, requestedMode) {
   let responseMode;
   if (value === "shadow" || value === "warn" || value === "block") {
@@ -836,7 +894,7 @@ function resolveMode(value, requestedMode) {
 function legacyMode(shadowMode) {
   return shadowMode === void 0 ? void 0 : shadowMode ? "shadow" : "block";
 }
-function blockResultFromResponse(data, requestedMode) {
+function blockResultFromResponse(data, requestedMode, requestedReview) {
   if (data.prediction !== "BENIGN" && data.prediction !== "MALICIOUS") {
     throw new Error("Firewall: response prediction must be BENIGN or MALICIOUS");
   }
@@ -845,6 +903,9 @@ function blockResultFromResponse(data, requestedMode) {
     score: Number(data.score),
     threshold: Number(data.threshold)
   };
+  if (requestedReview !== void 0) {
+    result.review = requestedReview;
+  }
   const mode = resolveMode(data.mode, requestedMode);
   if (mode !== void 0) {
     result.mode = mode;
@@ -870,7 +931,7 @@ function blockResultFromResponse(data, requestedMode) {
       result.detectorCounts = detectorCounts;
     }
   }
-  if (data.governance !== void 0) {
+  if (data.governance !== void 0 && data.governance !== null) {
     result.governance = governanceDecisionFromResponse(data.governance);
   }
   return Object.freeze(result);
@@ -894,8 +955,20 @@ function withSdkMetadata(metadata, info) {
   };
   return payload;
 }
+var GOVERNANCE_RESOURCE_KINDS = [
+  "agent",
+  "tool",
+  "mcp_server",
+  "mcp_tool",
+  "plugin",
+  "skill",
+  "extension"
+];
+function isGovernanceResourceKind(value) {
+  return typeof value === "string" && GOVERNANCE_RESOURCE_KINDS.includes(value);
+}
 function governanceResourceToWire(resource) {
-  if (!["agent", "tool", "mcp_server", "mcp_tool", "plugin", "skill", "extension"].includes(resource.kind)) {
+  if (!isGovernanceResourceKind(resource.kind)) {
     throw new Error("Firewall: invalid governance resource kind");
   }
   if (typeof resource.id !== "string" || !resource.id.trim()) {
@@ -914,6 +987,38 @@ function governanceResourceToWire(resource) {
     ...resource.parentId === void 0 ? {} : { parent_id: resource.parentId }
   };
 }
+function governanceResourceFromResponse(value) {
+  if (!isRecord2(value)) {
+    throw new Error("Firewall: response governance resource must be an object");
+  }
+  if (!isGovernanceResourceKind(value.kind)) {
+    throw new Error("Firewall: response governance resource has an invalid kind");
+  }
+  if (typeof value.id !== "string" || !value.id.trim()) {
+    throw new Error("Firewall: response governance resource id must be a non-empty string");
+  }
+  if (value.kind === "mcp_tool") {
+    if (typeof value.parent_id !== "string" || !value.parent_id.trim()) {
+      throw new Error(
+        "Firewall: response governance mcp_tool resource requires a non-empty parent_id"
+      );
+    }
+    return Object.freeze({
+      kind: value.kind,
+      id: value.id,
+      parentId: value.parent_id
+    });
+  }
+  if (value.parent_id !== void 0 && value.parent_id !== null) {
+    throw new Error(
+      "Firewall: response governance parent_id is valid only for mcp_tool resources"
+    );
+  }
+  return Object.freeze({
+    kind: value.kind,
+    id: value.id
+  });
+}
 function governanceContextToWire(context) {
   return {
     ...context.agent === void 0 ? {} : { agent: context.agent },
@@ -932,13 +1037,25 @@ function governanceDecisionFromResponse(value) {
   if (typeof value.policy_version !== "string" || value.policy_version.length === 0) {
     throw new Error("Firewall: response governance policy_version must be a non-empty string");
   }
-  if (value.rule_id !== void 0 && typeof value.rule_id !== "string") {
+  if (value.rule_id !== void 0 && value.rule_id !== null && typeof value.rule_id !== "string") {
     throw new Error("Firewall: response governance rule_id must be a string when provided");
   }
+  if (value.identity_revision !== void 0 && value.identity_revision !== null && typeof value.identity_revision !== "string") {
+    throw new Error(
+      "Firewall: response governance identity_revision must be a string when provided"
+    );
+  }
+  if (value.reason !== void 0 && value.reason !== null && typeof value.reason !== "string") {
+    throw new Error("Firewall: response governance reason must be a string when provided");
+  }
+  const resource = value.resource === void 0 || value.resource === null ? void 0 : governanceResourceFromResponse(value.resource);
   return Object.freeze({
     action: value.action,
-    ...value.rule_id === void 0 ? {} : { ruleId: value.rule_id },
-    policyVersion: value.policy_version
+    ...value.rule_id === void 0 || value.rule_id === null ? {} : { ruleId: value.rule_id },
+    policyVersion: value.policy_version,
+    ...resource === void 0 ? {} : { resource },
+    ...value.identity_revision === void 0 || value.identity_revision === null ? {} : { identityRevision: value.identity_revision },
+    ...value.reason === void 0 || value.reason === null ? {} : { reason: value.reason }
   });
 }
 async function readCappedErrorBody(response) {
@@ -1063,6 +1180,7 @@ var Firewall = class {
   timeoutMs;
   shadowMode;
   mode;
+  review;
   headers;
   constructor(options) {
     if (!options.apiKey) {
@@ -1083,6 +1201,7 @@ var Firewall = class {
       );
     }
     this.mode = options.mode ?? legacyMode(options.shadowMode);
+    this.review = validateReview(options.review, "review");
     this.shadowMode = this.mode === "shadow";
     this.headers = Object.freeze({
       "x-api-key": this.apiKey,
@@ -1122,9 +1241,13 @@ var Firewall = class {
       texts: texts.map((text) => sanitizeText(text))
     };
     const requestedMode = options.mode ?? this.mode;
+    const requestedReview = resolveReview(options.review, this.review);
     if (requestedMode !== void 0) {
       payload.mode = requestedMode;
     }
+    if (requestedReview !== void 0) {
+      payload.review = requestedReview;
+    }
     if (options.hooks && options.hooks.length > 0) {
       payload.hooks = options.hooks.map((h) => String(h));
     }
@@ -1144,6 +1267,7 @@ var Firewall = class {
       );
     }
     const data = await this.postWithRetry(payload, options.signal);
+    verifyReviewAcknowledgement(reviewAcknowledgementFromResponse(data), requestedReview);
     if (!Array.isArray(data.predictions)) {
       throw new Error("Firewall: response predictions must be an array");
     }
@@ -1152,7 +1276,9 @@ var Firewall = class {
         `Firewall: response predictions length ${data.predictions.length} does not match submitted texts length ${payload.texts.length}`
       );
     }
-    return data.predictions.map((p) => blockResultFromResponse(p, requestedMode));
+    return data.predictions.map(
+      (p) => blockResultFromResponse(p, requestedMode, requestedReview)
+    );
   }
   asLangChainHandler(options = {}) {
     return Promise.resolve().then(() => (init_langchain(), langchain_exports)).then(
@@ -1202,9 +1328,13 @@ var Firewall = class {
   async classifySingle(text, options, metadataInfo) {
     const payload = { text };
     const requestedMode = options.mode ?? this.mode;
+    const requestedReview = resolveReview(options.review, this.review);
     if (requestedMode !== void 0) {
       payload.mode = requestedMode;
     }
+    if (requestedReview !== void 0) {
+      payload.review = requestedReview;
+    }
     if (options.hook !== void 0) {
       payload.hook = options.hook;
     }
@@ -1219,7 +1349,8 @@ var Firewall = class {
       ...options.governance === void 0 ? {} : { governance: options.governance }
     });
     const data = await this.postWithRetry(payload, options.signal);
-    return blockResultFromResponse(data, requestedMode);
+    verifyReviewAcknowledgement(reviewAcknowledgementFromResponse(data), requestedReview);
+    return blockResultFromResponse(data, requestedMode, requestedReview);
   }
 };
 
@@ -1243,6 +1374,7 @@ init_hooks();
   Outcome,
   PRIMARY_OUTCOMES,
   PromptBlockedException,
+  ReviewCompatibilityError,
   SilmarilApiError,
   isHarmfulOutcome,
   isPrimaryOutcome,