@silmaril-security/sdk 0.7.5 → 0.7.7

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## Unreleased
+
+## 0.7.7
+
+- Preserve optional governance response evidence for the canonical resource,
+  identity revision, and open-ended decision reason when supplied by the
+  serving runtime.
+
+## 0.7.6
+
+- Send typed governance resources in the runtime's top-level `resource` and
+  aligned `resources` fields, preserving compatibility attribution metadata.
+- Reject invalid canonical resource references before submitting a request.
+  Caller-supplied agent metadata remains attribution, not authenticated identity.
+
 All notable changes to the Silmaril Firewall TypeScript SDK are documented here.
 
 ## 0.7.5 - 2026-10-12

package/README.md

@@ -34,10 +34,10 @@ This SDK is distributed as an npm package.
 npm install @silmaril-security/sdk
 ```
 
-For reproducible installs, pin the current tagged release:
+After publication, pin version 0.7.7 for reproducible installs:
 
 ```sh
-npm install @silmaril-security/sdk@0.7.5
+npm install @silmaril-security/sdk@0.7.7
 ```
 
 Requires Node 20 or later.
@@ -397,6 +397,13 @@ returns the server action, policy version, and optional rule ID. A malicious
 prediction or explicit governance block is blocked in Block mode; legacy
 responses without governance remain valid.
 
+When supported by the serving runtime, `BlockResult.governance` can also
+include optional decision evidence: the canonical `resource` (`kind`, `id`,
+and `parentId` for MCP tools), `identityRevision`, and `reason`. Older runtimes
+may omit these fields, and reason strings are open-ended so callers should
+preserve unknown values. This response evidence does not establish request
+identity and does not change enforcement behavior.
+
 ## Errors
 
 - `SilmarilApiError`: thrown when native `fetch` returns a non-2xx response to
@@ -637,3 +644,15 @@ npm publish --access public
 
 This SDK is distributed under the license terms in [LICENSE](LICENSE). It is not
 permissive open source.
+
+## Governance resource requests
+
+Typed governance resources are sent in the classify request's top-level
+`resource` field or aligned nullable `resources` array for batch calls. Resource
+IDs must be non-empty; MCP tools also require their canonical server parent ID.
+The compatibility metadata copy remains attribution only. Caller agent metadata
+does not supply an authenticated principal.
+
+This source prepares version 0.7.7. Its registry install command becomes
+available after the authorized main-branch release workflow publishes the package.
+Confirm registry publication before installing this version.

package/dist/adapters/deepagents.d.cts

@@ -12,7 +12,7 @@ import * as _langchain_core_utils_types from '@langchain/core/utils/types';
 import * as langchain from 'langchain';
 import { CreateAgentParams } from 'langchain';
 import * as _langchain_core_tools from '@langchain/core/tools';
-import { h as FirewallMode, b as ClassifyEvent, e as Firewall } from '../firewall-g3ZLF0xp.cjs';
+import { h as FirewallMode, b as ClassifyEvent, e as Firewall } from '../firewall-CueYday8.cjs';
 
 declare const SAFE_TOOL_MESSAGE = "Silmaril Firewall blocked this tool interaction. Choose a different safe action.";
 declare const SAFE_FINAL_MESSAGE = "Silmaril Firewall stopped this request after repeated unsafe actions.";

package/dist/adapters/deepagents.d.ts

@@ -12,7 +12,7 @@ import * as _langchain_core_utils_types from '@langchain/core/utils/types';
 import * as langchain from 'langchain';
 import { CreateAgentParams } from 'langchain';
 import * as _langchain_core_tools from '@langchain/core/tools';
-import { h as FirewallMode, b as ClassifyEvent, e as Firewall } from '../firewall-g3ZLF0xp.js';
+import { h as FirewallMode, b as ClassifyEvent, e as Firewall } from '../firewall-CueYday8.js';
 
 declare const SAFE_TOOL_MESSAGE = "Silmaril Firewall blocked this tool interaction. Choose a different safe action.";
 declare const SAFE_FINAL_MESSAGE = "Silmaril Firewall stopped this request after repeated unsafe actions.";

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-g3ZLF0xp.cjs';
+import { e as Firewall, L as LangChainAdapterOptions } from '../firewall-CueYday8.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-g3ZLF0xp.js';
+import { e as Firewall, L as LangChainAdapterOptions } from '../firewall-CueYday8.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-g3ZLF0xp.cjs';
+export { g as FirewallMiddleware, Q as createMiddleware } from '../firewall-CueYday8.cjs';

package/dist/adapters/vercel.d.ts

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

package/dist/{firewall-g3ZLF0xp.d.cts → firewall-CueYday8.d.cts}

@@ -74,11 +74,15 @@ type Prediction = "BENIGN" | "MALICIOUS";
 type FirewallMode = "shadow" | "warn" | "block";
 type GovernanceAction = "allow" | "block";
 type GovernanceResourceKind = "agent" | "tool" | "mcp_server" | "mcp_tool" | "plugin" | "skill" | "extension";
-interface GovernanceResource {
-    readonly kind: GovernanceResourceKind;
-    readonly id?: string;
-    readonly parentId?: string;
-}
+type GovernanceResource = {
+    readonly kind: "mcp_tool";
+    readonly id: string;
+    readonly parentId: string;
+} | {
+    readonly kind: Exclude<GovernanceResourceKind, "mcp_tool">;
+    readonly id: string;
+    readonly parentId?: never;
+};
 interface GovernanceContext {
     readonly agent?: string;
     readonly resource?: GovernanceResource;
@@ -87,6 +91,9 @@ interface GovernanceDecision {
     readonly action: GovernanceAction;
     readonly ruleId?: string;
     readonly policyVersion: string;
+    readonly resource?: GovernanceResource;
+    readonly identityRevision?: string;
+    readonly reason?: string;
 }
 interface BlockResult {
     readonly prediction: Prediction;

package/dist/{firewall-g3ZLF0xp.d.ts → firewall-CueYday8.d.ts}

@@ -74,11 +74,15 @@ type Prediction = "BENIGN" | "MALICIOUS";
 type FirewallMode = "shadow" | "warn" | "block";
 type GovernanceAction = "allow" | "block";
 type GovernanceResourceKind = "agent" | "tool" | "mcp_server" | "mcp_tool" | "plugin" | "skill" | "extension";
-interface GovernanceResource {
-    readonly kind: GovernanceResourceKind;
-    readonly id?: string;
-    readonly parentId?: string;
-}
+type GovernanceResource = {
+    readonly kind: "mcp_tool";
+    readonly id: string;
+    readonly parentId: string;
+} | {
+    readonly kind: Exclude<GovernanceResourceKind, "mcp_tool">;
+    readonly id: string;
+    readonly parentId?: never;
+};
 interface GovernanceContext {
     readonly agent?: string;
     readonly resource?: GovernanceResource;
@@ -87,6 +91,9 @@ interface GovernanceDecision {
     readonly action: GovernanceAction;
     readonly ruleId?: string;
     readonly policyVersion: string;
+    readonly resource?: GovernanceResource;
+    readonly identityRevision?: string;
+    readonly reason?: string;
 }
 interface BlockResult {
     readonly prediction: Prediction;

package/dist/index.cjs

@@ -818,7 +818,7 @@ function sanitizeText(text) {
 }
 
 // src/firewall.ts
-var SDK_VERSION = "0.7.5";
+var SDK_VERSION = "0.7.7";
 var DEFAULT_TIMEOUT_MS = 1e4;
 var DEFAULT_MAX_RETRIES = 5;
 var MAX_BACKOFF_SECONDS = 30;
@@ -870,7 +870,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,15 +894,75 @@ 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 (!isGovernanceResourceKind(resource.kind)) {
+    throw new Error("Firewall: invalid governance resource kind");
+  }
+  if (typeof resource.id !== "string" || !resource.id.trim()) {
+    throw new Error("Firewall: governance resource id must be a non-empty string");
+  }
+  if (resource.kind === "mcp_tool") {
+    if (typeof resource.parentId !== "string" || !resource.parentId.trim()) {
+      throw new Error("Firewall: mcp_tool resource requires a non-empty parentId");
+    }
+  } else if (resource.parentId !== void 0) {
+    throw new Error("Firewall: parentId is valid only for mcp_tool resources");
+  }
+  return {
+    kind: resource.kind,
+    id: resource.id,
+    ...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 },
     ...context.resource === void 0 ? {} : {
-      resource: {
-        kind: context.resource.kind,
-        ...context.resource.id === void 0 ? {} : { id: context.resource.id },
-        ...context.resource.parentId === void 0 ? {} : { parent_id: context.resource.parentId }
-      }
+      resource: governanceResourceToWire(context.resource)
     }
   };
 }
@@ -916,13 +976,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) {
@@ -1122,6 +1194,11 @@ var Firewall = class {
         ...options.governance?.[index] === void 0 ? {} : { governance: options.governance[index] }
       })
     );
+    if (options.governance !== void 0) {
+      payload.resources = options.governance.map(
+        (context) => context?.resource === void 0 ? null : governanceResourceToWire(context.resource)
+      );
+    }
     const data = await this.postWithRetry(payload, options.signal);
     if (!Array.isArray(data.predictions)) {
       throw new Error("Firewall: response predictions must be an array");
@@ -1190,6 +1267,9 @@ var Firewall = class {
     if (options.toolName !== void 0) {
       payload.tool_name = options.toolName;
     }
+    if (options.governance?.resource !== void 0) {
+      payload.resource = governanceResourceToWire(options.governance.resource);
+    }
     payload.metadata = withSdkMetadata(options.metadata, {
       ...metadataInfo,
       ...options.governance === void 0 ? {} : { governance: options.governance }