@silmaril-security/sdk 0.7.4 → 0.7.6

package/CHANGELOG.md

@@ -1,7 +1,22 @@
 # Changelog
 
+## 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
+
+- Correct the mode documentation for current mode-less Gateway responses and
+  Python/Rust wire contracts: explicit local client, call, and adapter overrides
+  remain authoritative. With no request or response mode, direct TypeScript
+  calls return decisions without local enforcement while the Vercel, LangChain,
+  and Deep Agents adapters retain their existing Block fallback behavior.
+
 ## 0.7.4 - 2026-10-09
 
 - Ship the corrected README with its reproducible install command pinned to

package/README.md

@@ -18,8 +18,8 @@ This SDK provides the low-level TypeScript interface for that workflow:
 - Classify user input, tool calls, tool responses, model output, or system
   prompt content.
 - Preserve hook and tool-name context for more accurate decisions.
-- Honor backend threat and governance decisions and effective Shadow, Warn, or
-  Block behavior in adapters.
+- Honor backend threat and governance decisions while adapters apply their
+  effective Shadow, Warn, or Block behavior.
 - Send each complete sanitized event in one request.
 - On individual `classify()` calls, preserve exact `metadata.conversationId` as sequence identity and add one event ID.
 - Retry API rate-limit responses.
@@ -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.6 for reproducible installs:
 
 ```sh
-npm install @silmaril-security/sdk@0.7.4
+npm install @silmaril-security/sdk@0.7.6
 ```
 
 Requires Node 20 or later.
@@ -241,7 +241,7 @@ interface FirewallOptions {
   apiKey: string;                                     // required
   apiUrl: string;                                     // required
   timeoutMs?: number;                                 // default: 10000 ms, max 2147483647
-  mode?: "shadow" | "warn" | "block";                // omitted uses backend configuration
+  mode?: "shadow" | "warn" | "block";                // explicit local client default
   shadowMode?: boolean;                               // deprecated legacy mapping
 }
 ```
@@ -265,15 +265,31 @@ threshold.
 
 ## Modes
 
-Use `shadow`, `warn`, or `block` only when a request needs to override the
-backend-configured mode. Shadow and Warn preserve the framework flow; Block
-throws `FirewallBlockedException` for a malicious decision. Current backends
-return the effective mode on every result.
-
-During a rolling upgrade, an explicit request mode remains authoritative if a
-legacy or mixed-version backend omits or disagrees about `mode`. When both the
-request and response omit it, `BlockResult.mode` remains unset; adapters retain
-their pre-0.6 default behavior without falsely reporting a backend Block mode.
+Mode controls local SDK and adapter handling; the backend remains authoritative
+for threat decisions and thresholds. Explicitly set `mode: "shadow"` or
+`mode: "warn"` when you want observation without adapter enforcement. Set
+`mode: "block"` when you want Block handling.
+
+A per-call or per-adapter mode takes precedence over the client mode. Any
+explicit mode is locally authoritative even when the response omits `mode` or
+reports a conflicting value. If no explicit mode is requested, a future
+compatible service can supply the result mode. This is forward compatibility,
+not a statement that current Firewall services return mode.
+
+Current Gateway responses omit `mode`, as do the current Python and Rust
+classify wire contracts; callers cannot currently rely on backend mode
+configuration. When a TypeScript request and response both omit mode, direct
+`classify()` and `classifyBatch()` calls return the backend decision without
+enforcing it, and `BlockResult.mode` remains unset. The Vercel middleware and
+LangChain handler retain their existing Block fallback for successful mode-less
+malicious or governance-block decisions. LangChain, Vercel input scanning, and
+Vercel non-streamed output scanning throw `FirewallBlockedException`; Vercel
+streamed-output scanning instead emits an error part carrying that exception in
+the stream. Deep Agents applies its existing Block fallback to a successful
+mode-less decision through its safe replacement and blocked-attempt behavior;
+classification errors remain fail-open by default. In the Python and Go SDKs,
+direct calls retain their existing Block enforcement when both the request and
+response omit mode.
 
 ```ts
 import { wrapLanguageModel, generateText } from "ai";
@@ -621,3 +637,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.6. 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-CRNFqgMa.cjs';
+import { h as FirewallMode, b as ClassifyEvent, e as Firewall } from '../firewall-CRADRBLY.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-CRNFqgMa.js';
+import { h as FirewallMode, b as ClassifyEvent, e as Firewall } from '../firewall-CRADRBLY.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-CRNFqgMa.cjs';
+import { e as Firewall, L as LangChainAdapterOptions } from '../firewall-CRADRBLY.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-CRNFqgMa.js';
+import { e as Firewall, L as LangChainAdapterOptions } from '../firewall-CRADRBLY.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-CRNFqgMa.cjs';
+export { g as FirewallMiddleware, Q as createMiddleware } from '../firewall-CRADRBLY.cjs';

package/dist/adapters/vercel.d.ts

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

package/dist/{firewall-CRNFqgMa.d.cts → firewall-CRADRBLY.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;
@@ -92,7 +96,7 @@ interface BlockResult {
     readonly prediction: Prediction;
     readonly score: number;
     readonly threshold: number;
-    /** Omitted only when a legacy backend did not return mode and no override was requested. */
+    /** Omitted when neither an explicit local override nor the response supplies a mode. */
     readonly mode?: FirewallMode;
     readonly primaryOutcome?: PrimaryOutcome;
     readonly outcomeScores?: Readonly<Partial<Record<HarmfulOutcome, number>>>;
@@ -104,12 +108,14 @@ interface FirewallOptions {
     apiKey: string;
     apiUrl: string;
     timeoutMs?: number;
+    /** Explicit local client default; a per-call or per-adapter mode takes precedence. */
     mode?: FirewallMode;
     /** @deprecated Use mode: "shadow" or mode: "block". */
     shadowMode?: boolean;
 }
 type ClassificationMetadata = Readonly<Record<string, unknown>>;
 interface ClassifyOptions {
+    /** Explicit local per-call override; authoritative over any response mode. */
     mode?: FirewallMode;
     hook?: HookLabel;
     toolName?: string;
@@ -123,6 +129,7 @@ interface ClassifyOptions {
     signal?: AbortSignal;
 }
 interface ClassifyBatchOptions {
+    /** Explicit local per-call override; authoritative over every response mode. */
     mode?: FirewallMode;
     hooks?: readonly HookLabel[];
     toolNames?: readonly (string | undefined)[];
@@ -143,6 +150,7 @@ interface LangChainAdapterOptions {
     includeTool?: boolean;
     failOpen?: boolean;
     logger?: (message: string, error: unknown) => void;
+    /** Explicit local adapter override; takes precedence over the client and response modes. */
     mode?: FirewallMode;
     /** @deprecated Use mode: "shadow" or mode: "block". */
     shadowMode?: boolean;
@@ -175,6 +183,7 @@ interface MiddlewareOptions {
     scanInput?: boolean;
     scanOutput?: boolean;
     scanToolCalls?: boolean;
+    /** Explicit local adapter override; takes precedence over the client and response modes. */
     mode?: FirewallMode;
     /** @deprecated Use mode: "shadow" or mode: "block". */
     shadowMode?: boolean;

package/dist/{firewall-CRNFqgMa.d.ts → firewall-CRADRBLY.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;
@@ -92,7 +96,7 @@ interface BlockResult {
     readonly prediction: Prediction;
     readonly score: number;
     readonly threshold: number;
-    /** Omitted only when a legacy backend did not return mode and no override was requested. */
+    /** Omitted when neither an explicit local override nor the response supplies a mode. */
     readonly mode?: FirewallMode;
     readonly primaryOutcome?: PrimaryOutcome;
     readonly outcomeScores?: Readonly<Partial<Record<HarmfulOutcome, number>>>;
@@ -104,12 +108,14 @@ interface FirewallOptions {
     apiKey: string;
     apiUrl: string;
     timeoutMs?: number;
+    /** Explicit local client default; a per-call or per-adapter mode takes precedence. */
     mode?: FirewallMode;
     /** @deprecated Use mode: "shadow" or mode: "block". */
     shadowMode?: boolean;
 }
 type ClassificationMetadata = Readonly<Record<string, unknown>>;
 interface ClassifyOptions {
+    /** Explicit local per-call override; authoritative over any response mode. */
     mode?: FirewallMode;
     hook?: HookLabel;
     toolName?: string;
@@ -123,6 +129,7 @@ interface ClassifyOptions {
     signal?: AbortSignal;
 }
 interface ClassifyBatchOptions {
+    /** Explicit local per-call override; authoritative over every response mode. */
     mode?: FirewallMode;
     hooks?: readonly HookLabel[];
     toolNames?: readonly (string | undefined)[];
@@ -143,6 +150,7 @@ interface LangChainAdapterOptions {
     includeTool?: boolean;
     failOpen?: boolean;
     logger?: (message: string, error: unknown) => void;
+    /** Explicit local adapter override; takes precedence over the client and response modes. */
     mode?: FirewallMode;
     /** @deprecated Use mode: "shadow" or mode: "block". */
     shadowMode?: boolean;
@@ -175,6 +183,7 @@ interface MiddlewareOptions {
     scanInput?: boolean;
     scanOutput?: boolean;
     scanToolCalls?: boolean;
+    /** Explicit local adapter override; takes precedence over the client and response modes. */
     mode?: FirewallMode;
     /** @deprecated Use mode: "shadow" or mode: "block". */
     shadowMode?: boolean;

package/dist/index.cjs

@@ -818,7 +818,7 @@ function sanitizeText(text) {
 }
 
 // src/firewall.ts
-var SDK_VERSION = "0.7.4";
+var SDK_VERSION = "0.7.6";
 var DEFAULT_TIMEOUT_MS = 1e4;
 var DEFAULT_MAX_RETRIES = 5;
 var MAX_BACKOFF_SECONDS = 30;
@@ -894,15 +894,31 @@ function withSdkMetadata(metadata, info) {
   };
   return payload;
 }
+function governanceResourceToWire(resource) {
+  if (!["agent", "tool", "mcp_server", "mcp_tool", "plugin", "skill", "extension"].includes(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 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)
     }
   };
 }
@@ -1122,6 +1138,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 +1211,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 }