guardian-risk 0.1.0 → 0.2.1

package/README.md

@@ -6,8 +6,6 @@ Configurable risk decision engine for TypeScript. Evaluate signals against rules
 
 ```bash
 npm install guardian-risk
-# or
-pnpm add guardian-risk
 ```
 
 ## Usage
@@ -36,12 +34,80 @@ console.log(report.score); // 35
 console.log(report.level); // MEDIUM
 ```
 
+## Official plugins
+
+Install **core first**, then add only the plugins you need:
+
+| Package | Install | Purpose |
+|---------|---------|---------|
+| **guardian-risk** (this) | `npm i guardian-risk` | Core engine |
+| guardian-risk-express | `npm i guardian-risk-express` | Express request signals |
+| guardian-risk-browser | `npm i guardian-risk-browser` | Browser behavioral signals |
+| guardian-risk-redis | `npm i guardian-risk-redis` | Redis session counters |
+| guardian-risk-vpn | `npm i guardian-risk-vpn` | VPN / proxy / Tor detection |
+| guardian-risk-logger | `npm i guardian-risk-logger` | Audit logging |
+
+```bash
+# Example: Express + VPN + Logger stack
+npm install guardian-risk guardian-risk-express guardian-risk-vpn guardian-risk-logger
+```
+
+```typescript
+import { Guardian } from 'guardian-risk';
+import { expressPlugin } from 'guardian-risk-express';
+import { vpnPlugin } from 'guardian-risk-vpn';
+import { loggerPlugin, analyzeAndLog } from 'guardian-risk-logger';
+
+const guardian = new Guardian()
+  .use(expressPlugin())
+  .use(vpnPlugin())
+  .use(loggerPlugin());
+
+analyzeAndLog(guardian);
+```
+
+> Plugin packages are early stubs — APIs may change before `1.0.0`.
+
+## Plugins API
+
+```typescript
+import type { Plugin } from 'guardian-risk';
+
+const myPlugin: Plugin = {
+  name: 'my-plugin',
+  install(guardian) {
+    guardian.rule({ name: 'Custom', when: () => true, score: 10 });
+  },
+};
+
+new Guardian().use(myPlugin);
+```
+
 ## API
 
-- `guardian.signal(key, value)` — add a signal
-- `guardian.rule({ name, when, score, reason? })` — register a rule
-- `guardian.analyze()` — run evaluation, returns `RiskReport`
-- `guardian.reset()` — clear signals (rules persist)
+| Method | Description |
+|--------|-------------|
+| `guardian.signal(key, value)` | Add a signal |
+| `guardian.rule({ name, when, score, reason? })` | Register a rule |
+| `guardian.use(plugin)` | Install a plugin (once per name) |
+| `guardian.analyze()` | Run evaluation, returns `RiskReport` |
+| `guardian.reset()` | Clear signals (rules + plugins persist) |
+| `guardian.getInstalledPlugins()` | List installed plugin names |
+
+## Security
+
+- **Zero runtime dependencies** — minimal supply chain risk
+- **No install scripts** — nothing runs on `npm install`
+- Prototype pollution protection on signal keys
+- Rule `when()` errors isolated — engine stays stable
+- Score bounds: ±10,000 per rule, ±1,000,000 total
+- Plugin `install()` failures throw `PluginInstallError` without registering
+- See [SECURITY.md](SECURITY.md) for vulnerability reporting
+
+## Links
+
+- [GitHub monorepo](https://github.com/himanshu6306singh/guardian-risk)
+- [All packages guide](https://github.com/himanshu6306singh/guardian-risk/blob/main/ECOSYSTEM.md)
 
 ## License
 

package/dist/index.cjs

@@ -10,6 +10,18 @@ var DEFAULT_RISK_LEVELS = [
   { max: Infinity, level: "CRITICAL" }
 ];
 
+// src/constants/security.ts
+var MAX_RULES = 1e3;
+var MAX_SIGNALS = 1e3;
+var MAX_KEY_LENGTH = 256;
+var MAX_RULE_SCORE = 1e4;
+var MAX_TOTAL_SCORE = 1e6;
+var BLOCKED_SIGNAL_KEYS = /* @__PURE__ */ new Set([
+  "__proto__",
+  "constructor",
+  "prototype"
+]);
+
 // src/utils/resolveLevel.ts
 function resolveLevel(score, thresholds = DEFAULT_RISK_LEVELS) {
   for (const threshold of thresholds) {
@@ -49,7 +61,13 @@ var RuleEvaluator = class {
   evaluate(rules, signals) {
     const matched = [];
     for (const rule of rules) {
-      if (rule.when(signals)) {
+      let isMatched = false;
+      try {
+        isMatched = rule.when(signals);
+      } catch {
+        isMatched = false;
+      }
+      if (isMatched) {
         matched.push({
           id: rule.id,
           name: rule.name,
@@ -65,10 +83,20 @@ var RuleEvaluator = class {
 // src/score/ScoreCalculator.ts
 var ScoreCalculator = class {
   /**
-   * Sum scores from all matched rules.
+   * Sum scores from all matched rules, clamped to a safe maximum.
    */
   calculate(matchedRules) {
-    return matchedRules.reduce((total, rule) => total + rule.score, 0);
+    const total = matchedRules.reduce((sum, rule) => sum + rule.score, 0);
+    if (!Number.isFinite(total)) {
+      return 0;
+    }
+    if (total > MAX_TOTAL_SCORE) {
+      return MAX_TOTAL_SCORE;
+    }
+    if (total < -MAX_TOTAL_SCORE) {
+      return -MAX_TOTAL_SCORE;
+    }
+    return total;
   }
 };
 function validateSignalValue(value) {
@@ -78,6 +106,74 @@ function validateSignalValue(value) {
   const type = typeof value;
   return type === "string" || type === "number" || type === "boolean";
 }
+function validateSignalKey(key) {
+  if (typeof key !== "string" || key.length === 0) {
+    throw new TypeError("Signal key must be a non-empty string");
+  }
+  if (key.length > MAX_KEY_LENGTH) {
+    throw new TypeError(`Signal key exceeds maximum length of ${MAX_KEY_LENGTH}`);
+  }
+  if (BLOCKED_SIGNAL_KEYS.has(key)) {
+    throw new TypeError(`Signal key "${key}" is not allowed`);
+  }
+}
+function validateRuleInput(input) {
+  if (typeof input.name !== "string" || input.name.trim().length === 0) {
+    throw new TypeError("Rule name must be a non-empty string");
+  }
+  if (input.name.length > MAX_KEY_LENGTH) {
+    throw new TypeError(`Rule name exceeds maximum length of ${MAX_KEY_LENGTH}`);
+  }
+  if (typeof input.when !== "function") {
+    throw new TypeError("Rule when must be a function");
+  }
+  if (typeof input.score !== "number" || !Number.isFinite(input.score)) {
+    throw new TypeError("Rule score must be a finite number");
+  }
+  if (Math.abs(input.score) > MAX_RULE_SCORE) {
+    throw new TypeError(`Rule score must be between -${MAX_RULE_SCORE} and ${MAX_RULE_SCORE}`);
+  }
+  if (input.reason !== void 0) {
+    if (typeof input.reason !== "string") {
+      throw new TypeError("Rule reason must be a string");
+    }
+    if (input.reason.length > MAX_KEY_LENGTH) {
+      throw new TypeError(`Rule reason exceeds maximum length of ${MAX_KEY_LENGTH}`);
+    }
+  }
+  if (input.description !== void 0) {
+    if (typeof input.description !== "string") {
+      throw new TypeError("Rule description must be a string");
+    }
+    if (input.description.length > MAX_KEY_LENGTH) {
+      throw new TypeError(`Rule description exceeds maximum length of ${MAX_KEY_LENGTH}`);
+    }
+  }
+}
+function validatePlugin(plugin) {
+  if (typeof plugin.name !== "string" || plugin.name.trim().length === 0) {
+    throw new TypeError("Plugin name must be a non-empty string");
+  }
+  if (plugin.name.length > MAX_KEY_LENGTH) {
+    throw new TypeError(`Plugin name exceeds maximum length of ${MAX_KEY_LENGTH}`);
+  }
+  if (typeof plugin.install !== "function") {
+    throw new TypeError("Plugin install must be a function");
+  }
+}
+function validateRiskLevels(levels) {
+  if (levels.length === 0) {
+    throw new TypeError("Risk levels must contain at least one threshold");
+  }
+  for (const threshold of levels) {
+    if (typeof threshold.level !== "string" || threshold.level.trim().length === 0) {
+      throw new TypeError("Risk level label must be a non-empty string");
+    }
+    if (typeof threshold.max !== "number" || !Number.isFinite(threshold.max) && threshold.max !== Infinity) {
+      throw new TypeError("Risk level max must be a finite number or Infinity");
+    }
+  }
+}
 function generateId() {
   return crypto.randomUUID();
 }
@@ -89,11 +185,15 @@ var SignalStore = class {
    * Set a signal value. Overwrites any existing value for the key.
    */
   set(key, value) {
+    validateSignalKey(key);
     if (!validateSignalValue(value)) {
       throw new TypeError(
         `Invalid signal value for "${key}": signals must be string, number, boolean, or null`
       );
     }
+    if (!this.signals.has(key) && this.signals.size >= MAX_SIGNALS) {
+      throw new RangeError(`Cannot exceed maximum of ${MAX_SIGNALS} signals`);
+    }
     this.signals.set(key, value);
     return this;
   }
@@ -113,7 +213,7 @@ var SignalStore = class {
    * Returns a frozen snapshot of all signals.
    */
   getAll() {
-    const snapshot = {};
+    const snapshot = /* @__PURE__ */ Object.create(null);
     for (const [key, value] of this.signals) {
       snapshot[key] = value;
     }
@@ -140,6 +240,9 @@ var RiskEngine = class {
    * Register a rule for evaluation.
    */
   addRule(rule) {
+    if (this.rules.length >= MAX_RULES) {
+      throw new RangeError(`Cannot exceed maximum of ${MAX_RULES} rules`);
+    }
     this.rules.push(rule);
   }
   /**
@@ -165,6 +268,7 @@ var RuleBuilder = class {
    * Create a new rule from input configuration.
    */
   static create(input) {
+    validateRuleInput(input);
     const rule = {
       id: generateId(),
       name: input.name,
@@ -177,12 +281,62 @@ var RuleBuilder = class {
   }
 };
 
+// src/plugins/PluginRegistry.ts
+var PluginInstallError = class extends Error {
+  constructor(pluginName, cause) {
+    const message = cause instanceof Error ? cause.message : "Unknown plugin install error";
+    super(`Plugin "${pluginName}" failed to install: ${message}`);
+    this.name = "PluginInstallError";
+  }
+};
+var PluginAlreadyInstalledError = class extends Error {
+  constructor(pluginName) {
+    super(`Plugin "${pluginName}" is already installed`);
+    this.name = "PluginAlreadyInstalledError";
+  }
+};
+var PluginRegistry = class {
+  installed = /* @__PURE__ */ new Set();
+  /**
+   * Install a plugin on the given Guardian instance.
+   * Each plugin name may only be installed once per Guardian instance.
+   */
+  install(plugin, guardian) {
+    validatePlugin(plugin);
+    if (this.installed.has(plugin.name)) {
+      throw new PluginAlreadyInstalledError(plugin.name);
+    }
+    try {
+      plugin.install(guardian);
+    } catch (error) {
+      throw new PluginInstallError(plugin.name, error);
+    }
+    this.installed.add(plugin.name);
+  }
+  /**
+   * Check if a plugin is installed by name.
+   */
+  has(name) {
+    return this.installed.has(name);
+  }
+  /**
+   * Get names of all installed plugins in registration order.
+   */
+  getInstalled() {
+    return [...this.installed];
+  }
+};
+
 // src/engine/Guardian.ts
 var Guardian = class {
   signalStore;
   riskEngine;
+  pluginRegistry = new PluginRegistry();
   constructor(config = {}) {
     const thresholds = config.levels ?? DEFAULT_RISK_LEVELS;
+    if (config.levels !== void 0) {
+      validateRiskLevels(config.levels);
+    }
     this.signalStore = new SignalStore();
     const deps = {
       signalStore: this.signalStore,
@@ -207,6 +361,19 @@ var Guardian = class {
     this.riskEngine.addRule(rule);
     return this;
   }
+  /**
+   * Install a plugin. Each plugin name may only be registered once.
+   */
+  use(plugin) {
+    this.pluginRegistry.install(plugin, this);
+    return this;
+  }
+  /**
+   * Returns names of installed plugins.
+   */
+  getInstalledPlugins() {
+    return this.pluginRegistry.getInstalled();
+  }
   /**
    * Run risk analysis and return an immutable report.
    */
@@ -214,7 +381,7 @@ var Guardian = class {
     return this.riskEngine.analyze();
   }
   /**
-   * Clear all signals. Rules persist across resets.
+   * Clear all signals. Rules and installed plugins persist across resets.
    */
   reset() {
     this.signalStore.clear();
@@ -224,11 +391,12 @@ var Guardian = class {
 
 exports.DEFAULT_RISK_LEVELS = DEFAULT_RISK_LEVELS;
 exports.Guardian = Guardian;
+exports.PluginAlreadyInstalledError = PluginAlreadyInstalledError;
+exports.PluginInstallError = PluginInstallError;
+exports.PluginRegistry = PluginRegistry;
 exports.RiskEngine = RiskEngine;
 exports.RuleBuilder = RuleBuilder;
 exports.RuleEvaluator = RuleEvaluator;
 exports.ScoreCalculator = ScoreCalculator;
 exports.SignalStore = SignalStore;
 exports.resolveLevel = resolveLevel;
-//# sourceMappingURL=index.cjs.map
-//# sourceMappingURL=index.cjs.map

package/dist/index.d.cts

@@ -1,3 +1,14 @@
+/**
+ * Extension point for adding capabilities to Guardian without modifying core.
+ * Plugins may register signals, rules, or helpers during installation.
+ */
+interface Plugin {
+    readonly name: string;
+    install(guardian: Guardian): void;
+}
+/** Public alias for {@link Plugin}. */
+type GuardianPlugin = Plugin;
+
 /** Primitive signal value types supported by Guardian. */
 type SignalValue = string | number | boolean | null;
 /** Read-only map of signal key to value. */
@@ -58,6 +69,7 @@ interface GuardianConfig {
 declare class Guardian {
     private readonly signalStore;
     private readonly riskEngine;
+    private readonly pluginRegistry;
     constructor(config?: GuardianConfig);
     /**
      * Add a signal value for risk evaluation.
@@ -67,12 +79,20 @@ declare class Guardian {
      * Register a rule. ID is auto-generated.
      */
     rule(input: CreateRuleInput): this;
+    /**
+     * Install a plugin. Each plugin name may only be registered once.
+     */
+    use(plugin: Plugin): this;
+    /**
+     * Returns names of installed plugins.
+     */
+    getInstalledPlugins(): readonly string[];
     /**
      * Run risk analysis and return an immutable report.
      */
     analyze(): RiskReport;
     /**
-     * Clear all signals. Rules persist across resets.
+     * Clear all signals. Rules and installed plugins persist across resets.
      */
     reset(): this;
 }
@@ -103,7 +123,7 @@ declare class RuleEvaluator {
  */
 declare class ScoreCalculator {
     /**
-     * Sum scores from all matched rules.
+     * Sum scores from all matched rules, clamped to a safe maximum.
      */
     calculate(matchedRules: readonly MatchedRule[]): number;
 }
@@ -164,6 +184,38 @@ declare class RiskEngine {
     analyze(): RiskReport;
 }
 
+/**
+ * Thrown when a plugin's install() callback fails.
+ */
+declare class PluginInstallError extends Error {
+    constructor(pluginName: string, cause: unknown);
+}
+/**
+ * Thrown when attempting to register a plugin that is already installed.
+ */
+declare class PluginAlreadyInstalledError extends Error {
+    constructor(pluginName: string);
+}
+/**
+ * Manages plugin lifecycle: register once, track installed plugins.
+ */
+declare class PluginRegistry {
+    private readonly installed;
+    /**
+     * Install a plugin on the given Guardian instance.
+     * Each plugin name may only be installed once per Guardian instance.
+     */
+    install(plugin: Plugin, guardian: Guardian): void;
+    /**
+     * Check if a plugin is installed by name.
+     */
+    has(name: string): boolean;
+    /**
+     * Get names of all installed plugins in registration order.
+     */
+    getInstalled(): readonly string[];
+}
+
 /**
  * Builds immutable rule definitions with auto-generated IDs.
  */
@@ -183,4 +235,4 @@ declare function resolveLevel(score: number, thresholds?: readonly RiskLevelThre
 /** Default risk level thresholds used when none are configured. */
 declare const DEFAULT_RISK_LEVELS: readonly RiskLevelThreshold[];
 
-export { type CreateRuleInput, DEFAULT_RISK_LEVELS, Guardian, type GuardianConfig, type MatchedRule, RiskEngine, type RiskEngineDependencies, type RiskLevelThreshold, type RiskReport, type Rule, RuleBuilder, RuleEvaluator, ScoreCalculator, type SignalDefinition, type SignalMap, SignalStore, type SignalValue, resolveLevel };
+export { type CreateRuleInput, DEFAULT_RISK_LEVELS, Guardian, type GuardianConfig, type GuardianPlugin, type MatchedRule, type Plugin, PluginAlreadyInstalledError, PluginInstallError, PluginRegistry, RiskEngine, type RiskEngineDependencies, type RiskLevelThreshold, type RiskReport, type Rule, RuleBuilder, RuleEvaluator, ScoreCalculator, type SignalDefinition, type SignalMap, SignalStore, type SignalValue, resolveLevel };

package/dist/index.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Extension point for adding capabilities to Guardian without modifying core.
+ * Plugins may register signals, rules, or helpers during installation.
+ */
+interface Plugin {
+    readonly name: string;
+    install(guardian: Guardian): void;
+}
+/** Public alias for {@link Plugin}. */
+type GuardianPlugin = Plugin;
+
 /** Primitive signal value types supported by Guardian. */
 type SignalValue = string | number | boolean | null;
 /** Read-only map of signal key to value. */
@@ -58,6 +69,7 @@ interface GuardianConfig {
 declare class Guardian {
     private readonly signalStore;
     private readonly riskEngine;
+    private readonly pluginRegistry;
     constructor(config?: GuardianConfig);
     /**
      * Add a signal value for risk evaluation.
@@ -67,12 +79,20 @@ declare class Guardian {
      * Register a rule. ID is auto-generated.
      */
     rule(input: CreateRuleInput): this;
+    /**
+     * Install a plugin. Each plugin name may only be registered once.
+     */
+    use(plugin: Plugin): this;
+    /**
+     * Returns names of installed plugins.
+     */
+    getInstalledPlugins(): readonly string[];
     /**
      * Run risk analysis and return an immutable report.
      */
     analyze(): RiskReport;
     /**
-     * Clear all signals. Rules persist across resets.
+     * Clear all signals. Rules and installed plugins persist across resets.
      */
     reset(): this;
 }
@@ -103,7 +123,7 @@ declare class RuleEvaluator {
  */
 declare class ScoreCalculator {
     /**
-     * Sum scores from all matched rules.
+     * Sum scores from all matched rules, clamped to a safe maximum.
      */
     calculate(matchedRules: readonly MatchedRule[]): number;
 }
@@ -164,6 +184,38 @@ declare class RiskEngine {
     analyze(): RiskReport;
 }
 
+/**
+ * Thrown when a plugin's install() callback fails.
+ */
+declare class PluginInstallError extends Error {
+    constructor(pluginName: string, cause: unknown);
+}
+/**
+ * Thrown when attempting to register a plugin that is already installed.
+ */
+declare class PluginAlreadyInstalledError extends Error {
+    constructor(pluginName: string);
+}
+/**
+ * Manages plugin lifecycle: register once, track installed plugins.
+ */
+declare class PluginRegistry {
+    private readonly installed;
+    /**
+     * Install a plugin on the given Guardian instance.
+     * Each plugin name may only be installed once per Guardian instance.
+     */
+    install(plugin: Plugin, guardian: Guardian): void;
+    /**
+     * Check if a plugin is installed by name.
+     */
+    has(name: string): boolean;
+    /**
+     * Get names of all installed plugins in registration order.
+     */
+    getInstalled(): readonly string[];
+}
+
 /**
  * Builds immutable rule definitions with auto-generated IDs.
  */
@@ -183,4 +235,4 @@ declare function resolveLevel(score: number, thresholds?: readonly RiskLevelThre
 /** Default risk level thresholds used when none are configured. */
 declare const DEFAULT_RISK_LEVELS: readonly RiskLevelThreshold[];
 
-export { type CreateRuleInput, DEFAULT_RISK_LEVELS, Guardian, type GuardianConfig, type MatchedRule, RiskEngine, type RiskEngineDependencies, type RiskLevelThreshold, type RiskReport, type Rule, RuleBuilder, RuleEvaluator, ScoreCalculator, type SignalDefinition, type SignalMap, SignalStore, type SignalValue, resolveLevel };
+export { type CreateRuleInput, DEFAULT_RISK_LEVELS, Guardian, type GuardianConfig, type GuardianPlugin, type MatchedRule, type Plugin, PluginAlreadyInstalledError, PluginInstallError, PluginRegistry, RiskEngine, type RiskEngineDependencies, type RiskLevelThreshold, type RiskReport, type Rule, RuleBuilder, RuleEvaluator, ScoreCalculator, type SignalDefinition, type SignalMap, SignalStore, type SignalValue, resolveLevel };

package/dist/index.js

@@ -8,6 +8,18 @@ var DEFAULT_RISK_LEVELS = [
   { max: Infinity, level: "CRITICAL" }
 ];
 
+// src/constants/security.ts
+var MAX_RULES = 1e3;
+var MAX_SIGNALS = 1e3;
+var MAX_KEY_LENGTH = 256;
+var MAX_RULE_SCORE = 1e4;
+var MAX_TOTAL_SCORE = 1e6;
+var BLOCKED_SIGNAL_KEYS = /* @__PURE__ */ new Set([
+  "__proto__",
+  "constructor",
+  "prototype"
+]);
+
 // src/utils/resolveLevel.ts
 function resolveLevel(score, thresholds = DEFAULT_RISK_LEVELS) {
   for (const threshold of thresholds) {
@@ -47,7 +59,13 @@ var RuleEvaluator = class {
   evaluate(rules, signals) {
     const matched = [];
     for (const rule of rules) {
-      if (rule.when(signals)) {
+      let isMatched = false;
+      try {
+        isMatched = rule.when(signals);
+      } catch {
+        isMatched = false;
+      }
+      if (isMatched) {
         matched.push({
           id: rule.id,
           name: rule.name,
@@ -63,10 +81,20 @@ var RuleEvaluator = class {
 // src/score/ScoreCalculator.ts
 var ScoreCalculator = class {
   /**
-   * Sum scores from all matched rules.
+   * Sum scores from all matched rules, clamped to a safe maximum.
    */
   calculate(matchedRules) {
-    return matchedRules.reduce((total, rule) => total + rule.score, 0);
+    const total = matchedRules.reduce((sum, rule) => sum + rule.score, 0);
+    if (!Number.isFinite(total)) {
+      return 0;
+    }
+    if (total > MAX_TOTAL_SCORE) {
+      return MAX_TOTAL_SCORE;
+    }
+    if (total < -MAX_TOTAL_SCORE) {
+      return -MAX_TOTAL_SCORE;
+    }
+    return total;
   }
 };
 function validateSignalValue(value) {
@@ -76,6 +104,74 @@ function validateSignalValue(value) {
   const type = typeof value;
   return type === "string" || type === "number" || type === "boolean";
 }
+function validateSignalKey(key) {
+  if (typeof key !== "string" || key.length === 0) {
+    throw new TypeError("Signal key must be a non-empty string");
+  }
+  if (key.length > MAX_KEY_LENGTH) {
+    throw new TypeError(`Signal key exceeds maximum length of ${MAX_KEY_LENGTH}`);
+  }
+  if (BLOCKED_SIGNAL_KEYS.has(key)) {
+    throw new TypeError(`Signal key "${key}" is not allowed`);
+  }
+}
+function validateRuleInput(input) {
+  if (typeof input.name !== "string" || input.name.trim().length === 0) {
+    throw new TypeError("Rule name must be a non-empty string");
+  }
+  if (input.name.length > MAX_KEY_LENGTH) {
+    throw new TypeError(`Rule name exceeds maximum length of ${MAX_KEY_LENGTH}`);
+  }
+  if (typeof input.when !== "function") {
+    throw new TypeError("Rule when must be a function");
+  }
+  if (typeof input.score !== "number" || !Number.isFinite(input.score)) {
+    throw new TypeError("Rule score must be a finite number");
+  }
+  if (Math.abs(input.score) > MAX_RULE_SCORE) {
+    throw new TypeError(`Rule score must be between -${MAX_RULE_SCORE} and ${MAX_RULE_SCORE}`);
+  }
+  if (input.reason !== void 0) {
+    if (typeof input.reason !== "string") {
+      throw new TypeError("Rule reason must be a string");
+    }
+    if (input.reason.length > MAX_KEY_LENGTH) {
+      throw new TypeError(`Rule reason exceeds maximum length of ${MAX_KEY_LENGTH}`);
+    }
+  }
+  if (input.description !== void 0) {
+    if (typeof input.description !== "string") {
+      throw new TypeError("Rule description must be a string");
+    }
+    if (input.description.length > MAX_KEY_LENGTH) {
+      throw new TypeError(`Rule description exceeds maximum length of ${MAX_KEY_LENGTH}`);
+    }
+  }
+}
+function validatePlugin(plugin) {
+  if (typeof plugin.name !== "string" || plugin.name.trim().length === 0) {
+    throw new TypeError("Plugin name must be a non-empty string");
+  }
+  if (plugin.name.length > MAX_KEY_LENGTH) {
+    throw new TypeError(`Plugin name exceeds maximum length of ${MAX_KEY_LENGTH}`);
+  }
+  if (typeof plugin.install !== "function") {
+    throw new TypeError("Plugin install must be a function");
+  }
+}
+function validateRiskLevels(levels) {
+  if (levels.length === 0) {
+    throw new TypeError("Risk levels must contain at least one threshold");
+  }
+  for (const threshold of levels) {
+    if (typeof threshold.level !== "string" || threshold.level.trim().length === 0) {
+      throw new TypeError("Risk level label must be a non-empty string");
+    }
+    if (typeof threshold.max !== "number" || !Number.isFinite(threshold.max) && threshold.max !== Infinity) {
+      throw new TypeError("Risk level max must be a finite number or Infinity");
+    }
+  }
+}
 function generateId() {
   return randomUUID();
 }
@@ -87,11 +183,15 @@ var SignalStore = class {
    * Set a signal value. Overwrites any existing value for the key.
    */
   set(key, value) {
+    validateSignalKey(key);
     if (!validateSignalValue(value)) {
       throw new TypeError(
         `Invalid signal value for "${key}": signals must be string, number, boolean, or null`
       );
     }
+    if (!this.signals.has(key) && this.signals.size >= MAX_SIGNALS) {
+      throw new RangeError(`Cannot exceed maximum of ${MAX_SIGNALS} signals`);
+    }
     this.signals.set(key, value);
     return this;
   }
@@ -111,7 +211,7 @@ var SignalStore = class {
    * Returns a frozen snapshot of all signals.
    */
   getAll() {
-    const snapshot = {};
+    const snapshot = /* @__PURE__ */ Object.create(null);
     for (const [key, value] of this.signals) {
       snapshot[key] = value;
     }
@@ -138,6 +238,9 @@ var RiskEngine = class {
    * Register a rule for evaluation.
    */
   addRule(rule) {
+    if (this.rules.length >= MAX_RULES) {
+      throw new RangeError(`Cannot exceed maximum of ${MAX_RULES} rules`);
+    }
     this.rules.push(rule);
   }
   /**
@@ -163,6 +266,7 @@ var RuleBuilder = class {
    * Create a new rule from input configuration.
    */
   static create(input) {
+    validateRuleInput(input);
     const rule = {
       id: generateId(),
       name: input.name,
@@ -175,12 +279,62 @@ var RuleBuilder = class {
   }
 };
 
+// src/plugins/PluginRegistry.ts
+var PluginInstallError = class extends Error {
+  constructor(pluginName, cause) {
+    const message = cause instanceof Error ? cause.message : "Unknown plugin install error";
+    super(`Plugin "${pluginName}" failed to install: ${message}`);
+    this.name = "PluginInstallError";
+  }
+};
+var PluginAlreadyInstalledError = class extends Error {
+  constructor(pluginName) {
+    super(`Plugin "${pluginName}" is already installed`);
+    this.name = "PluginAlreadyInstalledError";
+  }
+};
+var PluginRegistry = class {
+  installed = /* @__PURE__ */ new Set();
+  /**
+   * Install a plugin on the given Guardian instance.
+   * Each plugin name may only be installed once per Guardian instance.
+   */
+  install(plugin, guardian) {
+    validatePlugin(plugin);
+    if (this.installed.has(plugin.name)) {
+      throw new PluginAlreadyInstalledError(plugin.name);
+    }
+    try {
+      plugin.install(guardian);
+    } catch (error) {
+      throw new PluginInstallError(plugin.name, error);
+    }
+    this.installed.add(plugin.name);
+  }
+  /**
+   * Check if a plugin is installed by name.
+   */
+  has(name) {
+    return this.installed.has(name);
+  }
+  /**
+   * Get names of all installed plugins in registration order.
+   */
+  getInstalled() {
+    return [...this.installed];
+  }
+};
+
 // src/engine/Guardian.ts
 var Guardian = class {
   signalStore;
   riskEngine;
+  pluginRegistry = new PluginRegistry();
   constructor(config = {}) {
     const thresholds = config.levels ?? DEFAULT_RISK_LEVELS;
+    if (config.levels !== void 0) {
+      validateRiskLevels(config.levels);
+    }
     this.signalStore = new SignalStore();
     const deps = {
       signalStore: this.signalStore,
@@ -205,6 +359,19 @@ var Guardian = class {
     this.riskEngine.addRule(rule);
     return this;
   }
+  /**
+   * Install a plugin. Each plugin name may only be registered once.
+   */
+  use(plugin) {
+    this.pluginRegistry.install(plugin, this);
+    return this;
+  }
+  /**
+   * Returns names of installed plugins.
+   */
+  getInstalledPlugins() {
+    return this.pluginRegistry.getInstalled();
+  }
   /**
    * Run risk analysis and return an immutable report.
    */
@@ -212,7 +379,7 @@ var Guardian = class {
     return this.riskEngine.analyze();
   }
   /**
-   * Clear all signals. Rules persist across resets.
+   * Clear all signals. Rules and installed plugins persist across resets.
    */
   reset() {
     this.signalStore.clear();
@@ -220,6 +387,4 @@ var Guardian = class {
   }
 };
 
-export { DEFAULT_RISK_LEVELS, Guardian, RiskEngine, RuleBuilder, RuleEvaluator, ScoreCalculator, SignalStore, resolveLevel };
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map
+export { DEFAULT_RISK_LEVELS, Guardian, PluginAlreadyInstalledError, PluginInstallError, PluginRegistry, RiskEngine, RuleBuilder, RuleEvaluator, ScoreCalculator, SignalStore, resolveLevel };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "guardian-risk",
-  "version": "0.1.0",
-  "description": "Configurable risk decision engine using signals, rules, and scoring",
+  "version": "0.2.1",
+  "description": "Configurable risk decision engine using signals, rules, and scoring. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -20,7 +20,10 @@
   },
   "sideEffects": false,
   "files": [
-    "dist",
+    "dist/index.js",
+    "dist/index.cjs",
+    "dist/index.d.ts",
+    "dist/index.d.cts",
     "README.md",
     "LICENSE"
   ],
@@ -28,6 +31,7 @@
     "node": ">=20"
   },
   "keywords": [
+    "guardian-risk",
     "risk",
     "risk-scoring",
     "rules-engine",
@@ -36,14 +40,27 @@
     "security",
     "typescript"
   ],
+  "author": "himanshuusinghh",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/himanshu6306singh/guardian-risk.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/himanshu6306singh/guardian-risk#readme",
+  "bugs": {
+    "url": "https://github.com/himanshu6306singh/guardian-risk/issues"
+  },
+  "security": "https://github.com/himanshu6306singh/guardian-risk/security/policy",
+  "funding": "https://github.com/sponsors/himanshu6306singh",
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.9",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
+    "vitest": "^4.1.9"
   },
   "scripts": {
     "build": "tsup",

package/dist/index.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/constants/defaults.ts","../src/utils/resolveLevel.ts","../src/report/Report.ts","../src/rules/RuleEvaluator.ts","../src/score/ScoreCalculator.ts","../src/utils/validation.ts","../src/signals/SignalStore.ts","../src/engine/RiskEngine.ts","../src/rules/RuleBuilder.ts","../src/engine/Guardian.ts"],"names":["randomUUID"],"mappings":"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","file":"index.cjs","sourcesContent":["import type { RiskLevelThreshold } from '../types/report.js';\n\n/** Default risk level thresholds used when none are configured. */\nexport const DEFAULT_RISK_LEVELS: readonly RiskLevelThreshold[] = [\n  { max: 20, level: 'LOW' },\n  { max: 40, level: 'MEDIUM' },\n  { max: 60, level: 'HIGH' },\n  { max: Infinity, level: 'CRITICAL' },\n] as const;\n","import type { RiskLevelThreshold } from '../types/report.js';\nimport { DEFAULT_RISK_LEVELS } from '../constants/defaults.js';\n\n/**\n * Resolves a risk level label from a score using configured thresholds.\n * Thresholds are evaluated in order; the first threshold where score <= max wins.\n */\nexport function resolveLevel(\n  score: number,\n  thresholds: readonly RiskLevelThreshold[] = DEFAULT_RISK_LEVELS,\n): string {\n  for (const threshold of thresholds) {\n    if (score <= threshold.max) {\n      return threshold.level;\n    }\n  }\n\n  const last = thresholds[thresholds.length - 1];\n  return last?.level ?? 'UNKNOWN';\n}\n","import type { MatchedRule } from '../types/rules.js';\nimport type { RiskReport } from '../types/report.js';\nimport { resolveLevel } from '../utils/resolveLevel.js';\nimport type { RiskLevelThreshold } from '../types/report.js';\n\n/**\n * Builds immutable risk reports.\n */\nexport class ReportBuilder {\n  /**\n   * Build a frozen risk report from evaluation results.\n   */\n  build(\n    score: number,\n    matchedRules: readonly MatchedRule[],\n    thresholds: readonly RiskLevelThreshold[],\n    analyzedAt: string = new Date().toISOString(),\n  ): RiskReport {\n    const reasons = matchedRules.map((rule) => rule.reason);\n    const level = resolveLevel(score, thresholds);\n\n    const report: RiskReport = {\n      score,\n      level,\n      reasons: Object.freeze([...reasons]),\n      matchedRules: Object.freeze([...matchedRules]),\n      analyzedAt,\n    };\n\n    return Object.freeze(report);\n  }\n}\n","import type { MatchedRule, Rule } from '../types/rules.js';\nimport type { SignalMap } from '../types/signals.js';\n\n/**\n * Evaluates rules against a signal map and returns matched rules.\n */\nexport class RuleEvaluator {\n  /**\n   * Evaluate all rules against the given signals.\n   * Rules are evaluated in registration order (exhaustive, no short-circuit).\n   */\n  evaluate<TSignals extends SignalMap>(\n    rules: readonly Rule<TSignals>[],\n    signals: TSignals,\n  ): MatchedRule[] {\n    const matched: MatchedRule[] = [];\n\n    for (const rule of rules) {\n      if (rule.when(signals)) {\n        matched.push({\n          id: rule.id,\n          name: rule.name,\n          score: rule.score,\n          reason: rule.reason ?? rule.name,\n        });\n      }\n    }\n\n    return matched;\n  }\n}\n","import type { MatchedRule } from '../types/rules.js';\n\n/**\n * Calculates risk score from matched rules.\n */\nexport class ScoreCalculator {\n  /**\n   * Sum scores from all matched rules.\n   */\n  calculate(matchedRules: readonly MatchedRule[]): number {\n    return matchedRules.reduce((total, rule) => total + rule.score, 0);\n  }\n}\n","import { randomUUID } from 'node:crypto';\nimport type { SignalValue } from '../types/signals.js';\n\n/**\n * Validates that a value is an allowed signal primitive.\n * Signals must be string, number, boolean, or null — not objects or arrays.\n */\nexport function validateSignalValue(value: unknown): value is SignalValue {\n  if (value === null) {\n    return true;\n  }\n\n  const type = typeof value;\n  return type === 'string' || type === 'number' || type === 'boolean';\n}\n\n/**\n * Generates a unique identifier for rules.\n */\nexport function generateId(): string {\n  return randomUUID();\n}\n","import type { SignalMap, SignalValue } from '../types/signals.js';\nimport { validateSignalValue } from '../utils/validation.js';\n\n/**\n * Stores and retrieves signal values for risk evaluation.\n */\nexport class SignalStore {\n  private readonly signals = new Map<string, SignalValue>();\n\n  /**\n   * Set a signal value. Overwrites any existing value for the key.\n   */\n  set(key: string, value: SignalValue): this {\n    if (!validateSignalValue(value)) {\n      throw new TypeError(\n        `Invalid signal value for \"${key}\": signals must be string, number, boolean, or null`,\n      );\n    }\n\n    this.signals.set(key, value);\n    return this;\n  }\n\n  /**\n   * Get a signal value by key.\n   */\n  get(key: string): SignalValue | undefined {\n    return this.signals.get(key);\n  }\n\n  /**\n   * Check if a signal exists.\n   */\n  has(key: string): boolean {\n    return this.signals.has(key);\n  }\n\n  /**\n   * Returns a frozen snapshot of all signals.\n   */\n  getAll(): SignalMap {\n    const snapshot: Record<string, SignalValue> = {};\n    for (const [key, value] of this.signals) {\n      snapshot[key] = value;\n    }\n    return Object.freeze(snapshot);\n  }\n\n  /**\n   * Clear all signals.\n   */\n  clear(): void {\n    this.signals.clear();\n  }\n}\n","import { DEFAULT_RISK_LEVELS } from '../constants/defaults.js';\nimport { ReportBuilder } from '../report/Report.js';\nimport { RuleEvaluator } from '../rules/RuleEvaluator.js';\nimport { ScoreCalculator } from '../score/ScoreCalculator.js';\nimport { SignalStore } from '../signals/SignalStore.js';\nimport type { Rule } from '../types/rules.js';\nimport type { RiskReport, RiskLevelThreshold } from '../types/report.js';\nimport type { SignalMap } from '../types/signals.js';\n\n/** Dependencies injected into RiskEngine. */\nexport interface RiskEngineDependencies {\n  readonly signalStore: SignalStore;\n  readonly ruleEvaluator: RuleEvaluator;\n  readonly scoreCalculator: ScoreCalculator;\n  readonly reportBuilder: ReportBuilder;\n}\n\n/**\n * Orchestrates signal evaluation, scoring, and report generation.\n */\nexport class RiskEngine {\n  private readonly rules: Rule<SignalMap>[] = [];\n  private readonly thresholds: readonly RiskLevelThreshold[];\n\n  constructor(\n    private readonly deps: RiskEngineDependencies,\n    thresholds: readonly RiskLevelThreshold[] = DEFAULT_RISK_LEVELS,\n  ) {\n    this.thresholds = thresholds;\n  }\n\n  /**\n   * Register a rule for evaluation.\n   */\n  addRule(rule: Rule<SignalMap>): void {\n    this.rules.push(rule);\n  }\n\n  /**\n   * Get all registered rules.\n   */\n  getRules(): readonly Rule<SignalMap>[] {\n    return this.rules;\n  }\n\n  /**\n   * Run the full risk analysis pipeline.\n   */\n  analyze(): RiskReport {\n    const signals = this.deps.signalStore.getAll();\n    const matchedRules = this.deps.ruleEvaluator.evaluate(this.rules, signals);\n    const score = this.deps.scoreCalculator.calculate(matchedRules);\n\n    return this.deps.reportBuilder.build(score, matchedRules, this.thresholds);\n  }\n}\n","import type { CreateRuleInput, Rule } from '../types/rules.js';\nimport type { SignalMap } from '../types/signals.js';\nimport { generateId } from '../utils/validation.js';\n\n/**\n * Builds immutable rule definitions with auto-generated IDs.\n */\nexport class RuleBuilder {\n  /**\n   * Create a new rule from input configuration.\n   */\n  static create<TSignals extends SignalMap = SignalMap>(\n    input: CreateRuleInput<TSignals>,\n  ): Rule<TSignals> {\n    const rule: Rule<TSignals> = {\n      id: generateId(),\n      name: input.name,\n      score: input.score,\n      when: input.when,\n      ...(input.description !== undefined ? { description: input.description } : {}),\n      ...(input.reason !== undefined ? { reason: input.reason } : {}),\n    };\n\n    return rule;\n  }\n}\n","import { DEFAULT_RISK_LEVELS } from '../constants/defaults.js';\nimport { RiskEngine, type RiskEngineDependencies } from './RiskEngine.js';\nimport { ReportBuilder } from '../report/Report.js';\nimport { RuleBuilder } from '../rules/RuleBuilder.js';\nimport { RuleEvaluator } from '../rules/RuleEvaluator.js';\nimport { ScoreCalculator } from '../score/ScoreCalculator.js';\nimport { SignalStore } from '../signals/SignalStore.js';\nimport type { CreateRuleInput } from '../types/rules.js';\nimport type { GuardianConfig, RiskReport } from '../types/report.js';\nimport type { SignalValue } from '../types/signals.js';\n\n/**\n * Fluent public API for risk analysis.\n * Collects signals and rules, then produces an immutable report.\n */\nexport class Guardian {\n  private readonly signalStore: SignalStore;\n  private readonly riskEngine: RiskEngine;\n\n  constructor(config: GuardianConfig = {}) {\n    const thresholds = config.levels ?? DEFAULT_RISK_LEVELS;\n    this.signalStore = new SignalStore();\n\n    const deps: RiskEngineDependencies = {\n      signalStore: this.signalStore,\n      ruleEvaluator: new RuleEvaluator(),\n      scoreCalculator: new ScoreCalculator(),\n      reportBuilder: new ReportBuilder(),\n    };\n\n    this.riskEngine = new RiskEngine(deps, thresholds);\n  }\n\n  /**\n   * Add a signal value for risk evaluation.\n   */\n  signal(key: string, value: SignalValue): this {\n    this.signalStore.set(key, value);\n    return this;\n  }\n\n  /**\n   * Register a rule. ID is auto-generated.\n   */\n  rule(input: CreateRuleInput): this {\n    const rule = RuleBuilder.create(input);\n    this.riskEngine.addRule(rule);\n    return this;\n  }\n\n  /**\n   * Run risk analysis and return an immutable report.\n   */\n  analyze(): RiskReport {\n    return this.riskEngine.analyze();\n  }\n\n  /**\n   * Clear all signals. Rules persist across resets.\n   */\n  reset(): this {\n    this.signalStore.clear();\n    return this;\n  }\n}\n"]}

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/constants/defaults.ts","../src/utils/resolveLevel.ts","../src/report/Report.ts","../src/rules/RuleEvaluator.ts","../src/score/ScoreCalculator.ts","../src/utils/validation.ts","../src/signals/SignalStore.ts","../src/engine/RiskEngine.ts","../src/rules/RuleBuilder.ts","../src/engine/Guardian.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { RiskLevelThreshold } from '../types/report.js';\n\n/** Default risk level thresholds used when none are configured. */\nexport const DEFAULT_RISK_LEVELS: readonly RiskLevelThreshold[] = [\n  { max: 20, level: 'LOW' },\n  { max: 40, level: 'MEDIUM' },\n  { max: 60, level: 'HIGH' },\n  { max: Infinity, level: 'CRITICAL' },\n] as const;\n","import type { RiskLevelThreshold } from '../types/report.js';\nimport { DEFAULT_RISK_LEVELS } from '../constants/defaults.js';\n\n/**\n * Resolves a risk level label from a score using configured thresholds.\n * Thresholds are evaluated in order; the first threshold where score <= max wins.\n */\nexport function resolveLevel(\n  score: number,\n  thresholds: readonly RiskLevelThreshold[] = DEFAULT_RISK_LEVELS,\n): string {\n  for (const threshold of thresholds) {\n    if (score <= threshold.max) {\n      return threshold.level;\n    }\n  }\n\n  const last = thresholds[thresholds.length - 1];\n  return last?.level ?? 'UNKNOWN';\n}\n","import type { MatchedRule } from '../types/rules.js';\nimport type { RiskReport } from '../types/report.js';\nimport { resolveLevel } from '../utils/resolveLevel.js';\nimport type { RiskLevelThreshold } from '../types/report.js';\n\n/**\n * Builds immutable risk reports.\n */\nexport class ReportBuilder {\n  /**\n   * Build a frozen risk report from evaluation results.\n   */\n  build(\n    score: number,\n    matchedRules: readonly MatchedRule[],\n    thresholds: readonly RiskLevelThreshold[],\n    analyzedAt: string = new Date().toISOString(),\n  ): RiskReport {\n    const reasons = matchedRules.map((rule) => rule.reason);\n    const level = resolveLevel(score, thresholds);\n\n    const report: RiskReport = {\n      score,\n      level,\n      reasons: Object.freeze([...reasons]),\n      matchedRules: Object.freeze([...matchedRules]),\n      analyzedAt,\n    };\n\n    return Object.freeze(report);\n  }\n}\n","import type { MatchedRule, Rule } from '../types/rules.js';\nimport type { SignalMap } from '../types/signals.js';\n\n/**\n * Evaluates rules against a signal map and returns matched rules.\n */\nexport class RuleEvaluator {\n  /**\n   * Evaluate all rules against the given signals.\n   * Rules are evaluated in registration order (exhaustive, no short-circuit).\n   */\n  evaluate<TSignals extends SignalMap>(\n    rules: readonly Rule<TSignals>[],\n    signals: TSignals,\n  ): MatchedRule[] {\n    const matched: MatchedRule[] = [];\n\n    for (const rule of rules) {\n      if (rule.when(signals)) {\n        matched.push({\n          id: rule.id,\n          name: rule.name,\n          score: rule.score,\n          reason: rule.reason ?? rule.name,\n        });\n      }\n    }\n\n    return matched;\n  }\n}\n","import type { MatchedRule } from '../types/rules.js';\n\n/**\n * Calculates risk score from matched rules.\n */\nexport class ScoreCalculator {\n  /**\n   * Sum scores from all matched rules.\n   */\n  calculate(matchedRules: readonly MatchedRule[]): number {\n    return matchedRules.reduce((total, rule) => total + rule.score, 0);\n  }\n}\n","import { randomUUID } from 'node:crypto';\nimport type { SignalValue } from '../types/signals.js';\n\n/**\n * Validates that a value is an allowed signal primitive.\n * Signals must be string, number, boolean, or null — not objects or arrays.\n */\nexport function validateSignalValue(value: unknown): value is SignalValue {\n  if (value === null) {\n    return true;\n  }\n\n  const type = typeof value;\n  return type === 'string' || type === 'number' || type === 'boolean';\n}\n\n/**\n * Generates a unique identifier for rules.\n */\nexport function generateId(): string {\n  return randomUUID();\n}\n","import type { SignalMap, SignalValue } from '../types/signals.js';\nimport { validateSignalValue } from '../utils/validation.js';\n\n/**\n * Stores and retrieves signal values for risk evaluation.\n */\nexport class SignalStore {\n  private readonly signals = new Map<string, SignalValue>();\n\n  /**\n   * Set a signal value. Overwrites any existing value for the key.\n   */\n  set(key: string, value: SignalValue): this {\n    if (!validateSignalValue(value)) {\n      throw new TypeError(\n        `Invalid signal value for \"${key}\": signals must be string, number, boolean, or null`,\n      );\n    }\n\n    this.signals.set(key, value);\n    return this;\n  }\n\n  /**\n   * Get a signal value by key.\n   */\n  get(key: string): SignalValue | undefined {\n    return this.signals.get(key);\n  }\n\n  /**\n   * Check if a signal exists.\n   */\n  has(key: string): boolean {\n    return this.signals.has(key);\n  }\n\n  /**\n   * Returns a frozen snapshot of all signals.\n   */\n  getAll(): SignalMap {\n    const snapshot: Record<string, SignalValue> = {};\n    for (const [key, value] of this.signals) {\n      snapshot[key] = value;\n    }\n    return Object.freeze(snapshot);\n  }\n\n  /**\n   * Clear all signals.\n   */\n  clear(): void {\n    this.signals.clear();\n  }\n}\n","import { DEFAULT_RISK_LEVELS } from '../constants/defaults.js';\nimport { ReportBuilder } from '../report/Report.js';\nimport { RuleEvaluator } from '../rules/RuleEvaluator.js';\nimport { ScoreCalculator } from '../score/ScoreCalculator.js';\nimport { SignalStore } from '../signals/SignalStore.js';\nimport type { Rule } from '../types/rules.js';\nimport type { RiskReport, RiskLevelThreshold } from '../types/report.js';\nimport type { SignalMap } from '../types/signals.js';\n\n/** Dependencies injected into RiskEngine. */\nexport interface RiskEngineDependencies {\n  readonly signalStore: SignalStore;\n  readonly ruleEvaluator: RuleEvaluator;\n  readonly scoreCalculator: ScoreCalculator;\n  readonly reportBuilder: ReportBuilder;\n}\n\n/**\n * Orchestrates signal evaluation, scoring, and report generation.\n */\nexport class RiskEngine {\n  private readonly rules: Rule<SignalMap>[] = [];\n  private readonly thresholds: readonly RiskLevelThreshold[];\n\n  constructor(\n    private readonly deps: RiskEngineDependencies,\n    thresholds: readonly RiskLevelThreshold[] = DEFAULT_RISK_LEVELS,\n  ) {\n    this.thresholds = thresholds;\n  }\n\n  /**\n   * Register a rule for evaluation.\n   */\n  addRule(rule: Rule<SignalMap>): void {\n    this.rules.push(rule);\n  }\n\n  /**\n   * Get all registered rules.\n   */\n  getRules(): readonly Rule<SignalMap>[] {\n    return this.rules;\n  }\n\n  /**\n   * Run the full risk analysis pipeline.\n   */\n  analyze(): RiskReport {\n    const signals = this.deps.signalStore.getAll();\n    const matchedRules = this.deps.ruleEvaluator.evaluate(this.rules, signals);\n    const score = this.deps.scoreCalculator.calculate(matchedRules);\n\n    return this.deps.reportBuilder.build(score, matchedRules, this.thresholds);\n  }\n}\n","import type { CreateRuleInput, Rule } from '../types/rules.js';\nimport type { SignalMap } from '../types/signals.js';\nimport { generateId } from '../utils/validation.js';\n\n/**\n * Builds immutable rule definitions with auto-generated IDs.\n */\nexport class RuleBuilder {\n  /**\n   * Create a new rule from input configuration.\n   */\n  static create<TSignals extends SignalMap = SignalMap>(\n    input: CreateRuleInput<TSignals>,\n  ): Rule<TSignals> {\n    const rule: Rule<TSignals> = {\n      id: generateId(),\n      name: input.name,\n      score: input.score,\n      when: input.when,\n      ...(input.description !== undefined ? { description: input.description } : {}),\n      ...(input.reason !== undefined ? { reason: input.reason } : {}),\n    };\n\n    return rule;\n  }\n}\n","import { DEFAULT_RISK_LEVELS } from '../constants/defaults.js';\nimport { RiskEngine, type RiskEngineDependencies } from './RiskEngine.js';\nimport { ReportBuilder } from '../report/Report.js';\nimport { RuleBuilder } from '../rules/RuleBuilder.js';\nimport { RuleEvaluator } from '../rules/RuleEvaluator.js';\nimport { ScoreCalculator } from '../score/ScoreCalculator.js';\nimport { SignalStore } from '../signals/SignalStore.js';\nimport type { CreateRuleInput } from '../types/rules.js';\nimport type { GuardianConfig, RiskReport } from '../types/report.js';\nimport type { SignalValue } from '../types/signals.js';\n\n/**\n * Fluent public API for risk analysis.\n * Collects signals and rules, then produces an immutable report.\n */\nexport class Guardian {\n  private readonly signalStore: SignalStore;\n  private readonly riskEngine: RiskEngine;\n\n  constructor(config: GuardianConfig = {}) {\n    const thresholds = config.levels ?? DEFAULT_RISK_LEVELS;\n    this.signalStore = new SignalStore();\n\n    const deps: RiskEngineDependencies = {\n      signalStore: this.signalStore,\n      ruleEvaluator: new RuleEvaluator(),\n      scoreCalculator: new ScoreCalculator(),\n      reportBuilder: new ReportBuilder(),\n    };\n\n    this.riskEngine = new RiskEngine(deps, thresholds);\n  }\n\n  /**\n   * Add a signal value for risk evaluation.\n   */\n  signal(key: string, value: SignalValue): this {\n    this.signalStore.set(key, value);\n    return this;\n  }\n\n  /**\n   * Register a rule. ID is auto-generated.\n   */\n  rule(input: CreateRuleInput): this {\n    const rule = RuleBuilder.create(input);\n    this.riskEngine.addRule(rule);\n    return this;\n  }\n\n  /**\n   * Run risk analysis and return an immutable report.\n   */\n  analyze(): RiskReport {\n    return this.riskEngine.analyze();\n  }\n\n  /**\n   * Clear all signals. Rules persist across resets.\n   */\n  reset(): this {\n    this.signalStore.clear();\n    return this;\n  }\n}\n"]}