@silmaril-security/sdk 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to the Silmaril Firewall TypeScript SDK are documented here.
 
+## 0.4.2 - 2026-06-02
+
+- Add typed firewall outcome constants, ordered outcome lists, descriptions,
+  type guards, and response normalizers.
+- Type `BlockResult.primaryOutcome`, `outcomeScores`, `detectorScores`, and
+  `detectorCounts` around the canonical outcome taxonomy.
+- Document simple outcome routing examples for direct `classify()` results.
+
 ## 0.4.1 - 2026-05-24
 
 - Recover the `0.4.x` npm release by moving to `0.4.1`. The `v0.4.0` Git tag

package/README.md

@@ -37,7 +37,7 @@ npm install @silmaril-security/sdk
 For reproducible installs, pin a tagged release:
 
 ```sh
-npm install @silmaril-security/sdk@0.4.1
+npm install @silmaril-security/sdk@0.4.2
 ```
 
 Requires Node 18 or later.
@@ -117,6 +117,52 @@ internally applied threshold. Direct calls do not throw on malicious verdicts.
 The Vercel AI SDK and LangChain.js adapters use `result.threshold` and throw
 `FirewallBlockedException` when enforcement is enabled.
 
+## Handle Outcomes
+
+Direct calls expose typed outcome labels so applications can choose different
+responses for different firewall decisions:
+
+```ts
+import { Firewall, HookLabel, Outcome } from "@silmaril-security/sdk";
+
+const result = await fw.classify(userInput, {
+  hook: HookLabel.USER_INPUT,
+});
+
+if (result.score < result.threshold) {
+  continueNormally();
+} else {
+  switch (result.primaryOutcome) {
+    case Outcome.SecretExposure:
+      redactAndSuppress(result);
+      break;
+    case Outcome.InformationDisclosure:
+      requireReview(result);
+      break;
+    case Outcome.ControlAbuse:
+      denyAndAskForConfirmation(result);
+      break;
+    case Outcome.SystemCompromise:
+      blockAndEscalate(result);
+      break;
+    case Outcome.ServiceDisruption:
+      blockDisruptiveAction(result);
+      break;
+    default:
+      blockByDefault(result);
+  }
+}
+```
+
+Outcome taxonomy:
+
+- `benign`: no harmful firewall outcome detected.
+- `information_disclosure`: private data, documents, internal context, logs, traces, customer data, SQL rows, topology, or similar non-secret sensitive information.
+- `secret_exposure`: credentials, tokens, API keys, cookies, passwords, signing keys, OAuth secrets, session material, or webhook secrets.
+- `control_abuse`: misuse of authorized tools or user privileges to send, change, approve, delete, operate, or bypass policy/RBAC without a stronger outcome.
+- `system_compromise`: privilege escalation, account takeover, hostile integration/plugin takeover, persistence, lateral movement, attacker webhook registration, or code/plugin execution.
+- `service_disruption`: downtime, lockout, degradation, alert suppression, destructive loops, resource exhaustion, cost spikes, or hidden outage evidence.
+
 ## Options
 
 ```ts

package/dist/adapters/langchain.d.cts

@@ -1,5 +1,5 @@
 import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
-import { f as Firewall, L as LangChainAdapterOptions } from '../firewall-CEV5hItA.cjs';
+import { f as Firewall, L as LangChainAdapterOptions } from '../firewall-DfZCCDU6.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 { f as Firewall, L as LangChainAdapterOptions } from '../firewall-CEV5hItA.js';
+import { f as Firewall, L as LangChainAdapterOptions } from '../firewall-DfZCCDU6.js';
 
 declare function createLangChainHandler(firewall: Firewall, options?: LangChainAdapterOptions): Promise<BaseCallbackHandler>;
 

package/dist/adapters/vercel.d.cts

@@ -1 +1 @@
-export { h as FirewallMiddleware, l as createMiddleware } from '../firewall-CEV5hItA.cjs';
+export { h as FirewallMiddleware, z as createMiddleware } from '../firewall-DfZCCDU6.cjs';

package/dist/adapters/vercel.d.ts

@@ -1 +1 @@
-export { h as FirewallMiddleware, l as createMiddleware } from '../firewall-CEV5hItA.js';
+export { h as FirewallMiddleware, z as createMiddleware } from '../firewall-DfZCCDU6.js';

package/dist/{firewall-CEV5hItA.d.cts → firewall-DfZCCDU6.d.cts}

@@ -26,15 +26,47 @@ declare function resolveHooks(hooks: Iterable<FirewallHook | string> | undefined
 declare function prependHook(text: string, hook: HookLabel | string | undefined | null): string;
 declare function prependToolName(text: string, toolName: string | undefined | null): string;
 
+declare const Outcome: {
+    readonly Benign: "benign";
+    readonly InformationDisclosure: "information_disclosure";
+    readonly SecretExposure: "secret_exposure";
+    readonly ControlAbuse: "control_abuse";
+    readonly SystemCompromise: "system_compromise";
+    readonly ServiceDisruption: "service_disruption";
+};
+declare const unknownOutcomeBrand: unique symbol;
+type KnownPrimaryOutcome = (typeof Outcome)[keyof typeof Outcome];
+type KnownHarmfulOutcome = Exclude<KnownPrimaryOutcome, typeof Outcome.Benign>;
+type UnknownOutcome = string & {
+    readonly [unknownOutcomeBrand]: "UnknownOutcome";
+};
+type PrimaryOutcome = KnownPrimaryOutcome | UnknownOutcome;
+type HarmfulOutcome = KnownHarmfulOutcome | UnknownOutcome;
+declare const PRIMARY_OUTCOMES: readonly ["benign", "information_disclosure", "secret_exposure", "control_abuse", "system_compromise", "service_disruption"];
+declare const HARMFUL_OUTCOMES: readonly ["information_disclosure", "secret_exposure", "control_abuse", "system_compromise", "service_disruption"];
+declare const OUTCOME_DESCRIPTIONS: {
+    readonly benign: "No harmful firewall outcome detected.";
+    readonly information_disclosure: "Exposes private data, documents, internal context, logs, traces, customer data, SQL rows, topology, or similar non-secret sensitive information.";
+    readonly secret_exposure: "Exposes credentials, tokens, API keys, cookies, passwords, signing keys, OAuth secrets, session material, or webhook secrets.";
+    readonly control_abuse: "Misuses authorized tools or user privileges to send, change, approve, delete, operate, or bypass policy/RBAC without a stronger outcome.";
+    readonly system_compromise: "Enables privilege escalation, account takeover, hostile integration or plugin takeover, persistence, lateral movement, attacker webhook registration, or code/plugin execution.";
+    readonly service_disruption: "Causes downtime, lockout, degradation, alert suppression, destructive loops, resource exhaustion, cost spikes, or hidden outage evidence.";
+};
+declare function isPrimaryOutcome(value: unknown): value is KnownPrimaryOutcome;
+declare function isHarmfulOutcome(value: unknown): value is KnownHarmfulOutcome;
+declare function normalizePrimaryOutcome(value: unknown, fieldName?: string): PrimaryOutcome;
+declare function normalizeHarmfulOutcome(value: unknown, fieldName?: string): HarmfulOutcome;
+declare function normalizeHarmfulOutcomeMap(values: unknown, fieldName: string): Readonly<Partial<Record<HarmfulOutcome, number>>> | undefined;
+
 type Prediction = "BENIGN" | "MALICIOUS";
 interface BlockResult {
     readonly prediction: Prediction;
     readonly score: number;
     readonly threshold: number;
-    readonly primaryOutcome?: string;
-    readonly outcomeScores?: Readonly<Record<string, number>>;
-    readonly detectorScores?: Readonly<Record<string, number>>;
-    readonly detectorCounts?: Readonly<Record<string, number>>;
+    readonly primaryOutcome?: PrimaryOutcome;
+    readonly outcomeScores?: Readonly<Partial<Record<HarmfulOutcome, number>>>;
+    readonly detectorScores?: Readonly<Partial<Record<HarmfulOutcome, number>>>;
+    readonly detectorCounts?: Readonly<Partial<Record<HarmfulOutcome, number>>>;
 }
 interface FirewallOptions {
     apiKey: string;
@@ -162,4 +194,4 @@ declare class Firewall {
     private classifySingleChunk;
 }
 
-export { ALL_HOOKS as A, type BlockResult as B, type ClassificationMetadata as C, DEFAULT_CHUNK_CONCURRENCY as D, FIREWALL_HOOK_TO_LABEL as F, HookLabel as H, INPUT_HOOKS as I, type LangChainAdapterOptions as L, type MiddlewareOptions as M, OUTPUT_HOOKS as O, type Prediction as P, type ClassifyBatchOptions as a, type ClassifyEvent as b, type ClassifyOptions as c, DEFAULT_HOOKS as d, DEFAULT_TIMEOUT_MS as e, Firewall as f, FirewallHook as g, type FirewallMiddleware as h, type FirewallOptions as i, type LangChainFirewallHandler as j, prependToolName as k, createMiddleware as l, prependHook as p, resolveHooks as r };
+export { ALL_HOOKS as A, type BlockResult as B, type ClassificationMetadata as C, DEFAULT_CHUNK_CONCURRENCY as D, FIREWALL_HOOK_TO_LABEL as F, HookLabel as H, INPUT_HOOKS as I, type KnownHarmfulOutcome as K, type LangChainAdapterOptions as L, type MiddlewareOptions as M, OUTCOME_DESCRIPTIONS as O, PRIMARY_OUTCOMES as P, type UnknownOutcome as U, type ClassifyBatchOptions as a, type ClassifyEvent as b, type ClassifyOptions as c, DEFAULT_HOOKS as d, DEFAULT_TIMEOUT_MS as e, Firewall as f, FirewallHook as g, type FirewallMiddleware as h, type FirewallOptions as i, HARMFUL_OUTCOMES as j, type HarmfulOutcome as k, type KnownPrimaryOutcome as l, type LangChainFirewallHandler as m, OUTPUT_HOOKS as n, Outcome as o, type Prediction as p, type PrimaryOutcome as q, isHarmfulOutcome as r, isPrimaryOutcome as s, normalizeHarmfulOutcome as t, normalizeHarmfulOutcomeMap as u, normalizePrimaryOutcome as v, prependHook as w, prependToolName as x, resolveHooks as y, createMiddleware as z };

package/dist/{firewall-CEV5hItA.d.ts → firewall-DfZCCDU6.d.ts}

@@ -26,15 +26,47 @@ declare function resolveHooks(hooks: Iterable<FirewallHook | string> | undefined
 declare function prependHook(text: string, hook: HookLabel | string | undefined | null): string;
 declare function prependToolName(text: string, toolName: string | undefined | null): string;
 
+declare const Outcome: {
+    readonly Benign: "benign";
+    readonly InformationDisclosure: "information_disclosure";
+    readonly SecretExposure: "secret_exposure";
+    readonly ControlAbuse: "control_abuse";
+    readonly SystemCompromise: "system_compromise";
+    readonly ServiceDisruption: "service_disruption";
+};
+declare const unknownOutcomeBrand: unique symbol;
+type KnownPrimaryOutcome = (typeof Outcome)[keyof typeof Outcome];
+type KnownHarmfulOutcome = Exclude<KnownPrimaryOutcome, typeof Outcome.Benign>;
+type UnknownOutcome = string & {
+    readonly [unknownOutcomeBrand]: "UnknownOutcome";
+};
+type PrimaryOutcome = KnownPrimaryOutcome | UnknownOutcome;
+type HarmfulOutcome = KnownHarmfulOutcome | UnknownOutcome;
+declare const PRIMARY_OUTCOMES: readonly ["benign", "information_disclosure", "secret_exposure", "control_abuse", "system_compromise", "service_disruption"];
+declare const HARMFUL_OUTCOMES: readonly ["information_disclosure", "secret_exposure", "control_abuse", "system_compromise", "service_disruption"];
+declare const OUTCOME_DESCRIPTIONS: {
+    readonly benign: "No harmful firewall outcome detected.";
+    readonly information_disclosure: "Exposes private data, documents, internal context, logs, traces, customer data, SQL rows, topology, or similar non-secret sensitive information.";
+    readonly secret_exposure: "Exposes credentials, tokens, API keys, cookies, passwords, signing keys, OAuth secrets, session material, or webhook secrets.";
+    readonly control_abuse: "Misuses authorized tools or user privileges to send, change, approve, delete, operate, or bypass policy/RBAC without a stronger outcome.";
+    readonly system_compromise: "Enables privilege escalation, account takeover, hostile integration or plugin takeover, persistence, lateral movement, attacker webhook registration, or code/plugin execution.";
+    readonly service_disruption: "Causes downtime, lockout, degradation, alert suppression, destructive loops, resource exhaustion, cost spikes, or hidden outage evidence.";
+};
+declare function isPrimaryOutcome(value: unknown): value is KnownPrimaryOutcome;
+declare function isHarmfulOutcome(value: unknown): value is KnownHarmfulOutcome;
+declare function normalizePrimaryOutcome(value: unknown, fieldName?: string): PrimaryOutcome;
+declare function normalizeHarmfulOutcome(value: unknown, fieldName?: string): HarmfulOutcome;
+declare function normalizeHarmfulOutcomeMap(values: unknown, fieldName: string): Readonly<Partial<Record<HarmfulOutcome, number>>> | undefined;
+
 type Prediction = "BENIGN" | "MALICIOUS";
 interface BlockResult {
     readonly prediction: Prediction;
     readonly score: number;
     readonly threshold: number;
-    readonly primaryOutcome?: string;
-    readonly outcomeScores?: Readonly<Record<string, number>>;
-    readonly detectorScores?: Readonly<Record<string, number>>;
-    readonly detectorCounts?: Readonly<Record<string, number>>;
+    readonly primaryOutcome?: PrimaryOutcome;
+    readonly outcomeScores?: Readonly<Partial<Record<HarmfulOutcome, number>>>;
+    readonly detectorScores?: Readonly<Partial<Record<HarmfulOutcome, number>>>;
+    readonly detectorCounts?: Readonly<Partial<Record<HarmfulOutcome, number>>>;
 }
 interface FirewallOptions {
     apiKey: string;
@@ -162,4 +194,4 @@ declare class Firewall {
     private classifySingleChunk;
 }
 
-export { ALL_HOOKS as A, type BlockResult as B, type ClassificationMetadata as C, DEFAULT_CHUNK_CONCURRENCY as D, FIREWALL_HOOK_TO_LABEL as F, HookLabel as H, INPUT_HOOKS as I, type LangChainAdapterOptions as L, type MiddlewareOptions as M, OUTPUT_HOOKS as O, type Prediction as P, type ClassifyBatchOptions as a, type ClassifyEvent as b, type ClassifyOptions as c, DEFAULT_HOOKS as d, DEFAULT_TIMEOUT_MS as e, Firewall as f, FirewallHook as g, type FirewallMiddleware as h, type FirewallOptions as i, type LangChainFirewallHandler as j, prependToolName as k, createMiddleware as l, prependHook as p, resolveHooks as r };
+export { ALL_HOOKS as A, type BlockResult as B, type ClassificationMetadata as C, DEFAULT_CHUNK_CONCURRENCY as D, FIREWALL_HOOK_TO_LABEL as F, HookLabel as H, INPUT_HOOKS as I, type KnownHarmfulOutcome as K, type LangChainAdapterOptions as L, type MiddlewareOptions as M, OUTCOME_DESCRIPTIONS as O, PRIMARY_OUTCOMES as P, type UnknownOutcome as U, type ClassifyBatchOptions as a, type ClassifyEvent as b, type ClassifyOptions as c, DEFAULT_HOOKS as d, DEFAULT_TIMEOUT_MS as e, Firewall as f, FirewallHook as g, type FirewallMiddleware as h, type FirewallOptions as i, HARMFUL_OUTCOMES as j, type HarmfulOutcome as k, type KnownPrimaryOutcome as l, type LangChainFirewallHandler as m, OUTPUT_HOOKS as n, Outcome as o, type Prediction as p, type PrimaryOutcome as q, isHarmfulOutcome as r, isPrimaryOutcome as s, normalizeHarmfulOutcome as t, normalizeHarmfulOutcomeMap as u, normalizePrimaryOutcome as v, prependHook as w, prependToolName as x, resolveHooks as y, createMiddleware as z };

package/dist/index.cjs

@@ -437,14 +437,23 @@ __export(src_exports, {
   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,
@@ -744,7 +753,79 @@ function chunkText(text) {
 
 // src/firewall.ts
 init_exceptions();
-var SDK_VERSION = "0.4.1";
+
+// 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;
@@ -757,22 +838,25 @@ function blockResultFromResponse(data) {
     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);
 }
@@ -1017,14 +1101,23 @@ init_hooks();
   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,