guardian-risk 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 var crypto = require('crypto');
+var net = require('net');
 
 // src/constants/defaults.ts
 var DEFAULT_RISK_LEVELS = [
@@ -10,6 +11,44 @@ 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 MAX_SIGNAL_STRING_LENGTH = 4096;
+var MAX_SESSION_ID_LENGTH = 128;
+var SESSION_ID_PATTERN = /^[a-zA-Z0-9._-]+$/;
+var HOOK_TIMEOUT_MS = 1e4;
+var BLOCKED_SIGNAL_KEYS = /* @__PURE__ */ new Set([
+  "__proto__",
+  "constructor",
+  "prototype"
+]);
+
+// src/hooks/runHooks.ts
+async function runHooks(hooks, context, timeoutMs = HOOK_TIMEOUT_MS) {
+  for (const hook of hooks) {
+    await runWithTimeout(() => hook(context), timeoutMs);
+  }
+}
+async function runWithTimeout(operation, timeoutMs) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new Error(`Guardian analyze hook timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  try {
+    await Promise.race([Promise.resolve(operation()), timeout]);
+  } finally {
+    if (timer !== void 0) {
+      clearTimeout(timer);
+    }
+  }
+}
+
 // src/utils/resolveLevel.ts
 function resolveLevel(score, thresholds = DEFAULT_RISK_LEVELS) {
   for (const threshold of thresholds) {
@@ -29,11 +68,14 @@ var ReportBuilder = class {
   build(score, matchedRules, thresholds, analyzedAt = (/* @__PURE__ */ new Date()).toISOString()) {
     const reasons = matchedRules.map((rule) => rule.reason);
     const level = resolveLevel(score, thresholds);
+    const frozenRules = matchedRules.map(
+      (rule) => Object.freeze({ ...rule })
+    );
     const report = {
       score,
       level,
       reasons: Object.freeze([...reasons]),
-      matchedRules: Object.freeze([...matchedRules]),
+      matchedRules: Object.freeze(frozenRules),
       analyzedAt
     };
     return Object.freeze(report);
@@ -49,12 +91,19 @@ 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,
           score: rule.score,
-          reason: rule.reason ?? rule.name
+          reason: rule.reason ?? rule.name,
+          ...rule.group !== void 0 ? { group: rule.group } : {}
         });
       }
     }
@@ -65,10 +114,34 @@ var RuleEvaluator = class {
 // src/score/ScoreCalculator.ts
 var ScoreCalculator = class {
   /**
-   * Sum scores from all matched rules.
+   * Sum scores from matched rules, applying group caps when configured.
    */
-  calculate(matchedRules) {
-    return matchedRules.reduce((total, rule) => total + rule.score, 0);
+  calculate(matchedRules, groupCaps = []) {
+    const caps = new Map(groupCaps.map((cap) => [cap.name, cap.maxScore]));
+    const grouped = /* @__PURE__ */ new Map();
+    let ungroupedTotal = 0;
+    for (const rule of matchedRules) {
+      if (rule.group !== void 0) {
+        grouped.set(rule.group, (grouped.get(rule.group) ?? 0) + rule.score);
+      } else {
+        ungroupedTotal += rule.score;
+      }
+    }
+    let total = ungroupedTotal;
+    for (const [groupName, groupScore] of grouped) {
+      const cap = caps.get(groupName);
+      total += cap !== void 0 ? Math.min(groupScore, cap) : groupScore;
+    }
+    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,7 +149,105 @@ function validateSignalValue(value) {
     return true;
   }
   const type = typeof value;
-  return type === "string" || type === "number" || type === "boolean";
+  if (type === "string") {
+    return value.length <= MAX_SIGNAL_STRING_LENGTH;
+  }
+  if (type === "number") {
+    return Number.isFinite(value);
+  }
+  return 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}`);
+    }
+  }
+  if (input.group !== void 0) {
+    if (typeof input.group !== "string" || input.group.trim().length === 0) {
+      throw new TypeError("Rule group must be a non-empty string");
+    }
+    if (input.group.length > MAX_KEY_LENGTH) {
+      throw new TypeError(`Rule group 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 validateRuleGroupInput(input) {
+  if (typeof input.name !== "string" || input.name.trim().length === 0) {
+    throw new TypeError("Rule group name must be a non-empty string");
+  }
+  if (input.name.length > MAX_KEY_LENGTH) {
+    throw new TypeError(`Rule group name exceeds maximum length of ${MAX_KEY_LENGTH}`);
+  }
+  if (input.maxScore !== void 0) {
+    if (typeof input.maxScore !== "number" || !Number.isFinite(input.maxScore) || input.maxScore < 0) {
+      throw new TypeError("Rule group maxScore must be a non-negative finite number");
+    }
+  }
+  if (!Array.isArray(input.rules) || input.rules.length === 0) {
+    throw new TypeError("Rule group must contain at least one rule");
+  }
 }
 function generateId() {
   return crypto.randomUUID();
@@ -89,11 +260,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 +288,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;
     }
@@ -135,11 +310,15 @@ var RiskEngine = class {
   }
   deps;
   rules = [];
+  groupCaps = [];
   thresholds;
   /**
    * 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);
   }
   /**
@@ -148,13 +327,30 @@ var RiskEngine = class {
   getRules() {
     return this.rules;
   }
+  /**
+   * Get configured per-group score caps.
+   */
+  getGroupCaps() {
+    return this.groupCaps;
+  }
+  /**
+   * Cap the combined score of matched rules in a group.
+   */
+  setGroupCap(name, maxScore) {
+    const existing = this.groupCaps.findIndex((cap) => cap.name === name);
+    if (existing >= 0) {
+      this.groupCaps[existing] = { name, maxScore };
+      return;
+    }
+    this.groupCaps.push({ name, maxScore });
+  }
   /**
    * Run the full risk analysis pipeline.
    */
   analyze() {
     const signals = this.deps.signalStore.getAll();
     const matchedRules = this.deps.ruleEvaluator.evaluate(this.rules, signals);
-    const score = this.deps.scoreCalculator.calculate(matchedRules);
+    const score = this.deps.scoreCalculator.calculate(matchedRules, this.groupCaps);
     return this.deps.reportBuilder.build(score, matchedRules, this.thresholds);
   }
 };
@@ -165,19 +361,28 @@ var RuleBuilder = class {
    * Create a new rule from input configuration.
    */
   static create(input) {
+    validateRuleInput(input);
     const rule = {
       id: generateId(),
       name: input.name,
       score: input.score,
       when: input.when,
       ...input.description !== void 0 ? { description: input.description } : {},
-      ...input.reason !== void 0 ? { reason: input.reason } : {}
+      ...input.reason !== void 0 ? { reason: input.reason } : {},
+      ...input.group !== void 0 ? { group: input.group } : {}
     };
     return rule;
   }
 };
 
 // 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`);
@@ -191,10 +396,15 @@ var PluginRegistry = class {
    * 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);
     }
-    plugin.install(guardian);
+    try {
+      plugin.install(guardian);
+    } catch (error) {
+      throw new PluginInstallError(plugin.name, error);
+    }
     this.installed.add(plugin.name);
   }
   /**
@@ -203,6 +413,15 @@ var PluginRegistry = class {
   has(name) {
     return this.installed.has(name);
   }
+  /**
+   * Copy installed plugin names from a template (used by Guardian.fork).
+   * Does not call install() — rules and hooks are copied separately.
+   */
+  adoptInstalled(names) {
+    for (const name of names) {
+      this.installed.add(name);
+    }
+  }
   /**
    * Get names of all installed plugins in registration order.
    */
@@ -212,12 +431,20 @@ var PluginRegistry = class {
 };
 
 // src/engine/Guardian.ts
-var Guardian = class {
+var Guardian = class _Guardian {
   signalStore;
   riskEngine;
   pluginRegistry = new PluginRegistry();
+  plugins = [];
+  beforeHooks = [];
+  afterHooks = [];
+  thresholds;
+  analyzing = false;
   constructor(config = {}) {
-    const thresholds = config.levels ?? DEFAULT_RISK_LEVELS;
+    this.thresholds = config.levels !== void 0 ? [...config.levels] : DEFAULT_RISK_LEVELS;
+    if (config.levels !== void 0) {
+      validateRiskLevels(config.levels);
+    }
     this.signalStore = new SignalStore();
     const deps = {
       signalStore: this.signalStore,
@@ -225,7 +452,7 @@ var Guardian = class {
       scoreCalculator: new ScoreCalculator(),
       reportBuilder: new ReportBuilder()
     };
-    this.riskEngine = new RiskEngine(deps, thresholds);
+    this.riskEngine = new RiskEngine(deps, this.thresholds);
   }
   /**
    * Add a signal value for risk evaluation.
@@ -234,21 +461,60 @@ var Guardian = class {
     this.signalStore.set(key, value);
     return this;
   }
+  /**
+   * Read a signal value without modifying state.
+   */
+  getSignal(key) {
+    return this.signalStore.get(key);
+  }
   /**
    * Register a rule. ID is auto-generated.
    */
   rule(input) {
+    this.assertNotAnalyzing("register rules");
     const rule = RuleBuilder.create(input);
     this.riskEngine.addRule(rule);
     return this;
   }
+  /**
+   * Register a named group of rules with an optional combined score cap.
+   */
+  ruleGroup(input) {
+    this.assertNotAnalyzing("register rule groups");
+    validateRuleGroupInput(input);
+    for (const ruleInput of input.rules) {
+      this.rule({ ...ruleInput, group: input.name });
+    }
+    if (input.maxScore !== void 0) {
+      this.riskEngine.setGroupCap(input.name, input.maxScore);
+    }
+    return this;
+  }
   /**
    * Install a plugin. Each plugin name may only be registered once.
    */
   use(plugin) {
+    this.assertNotAnalyzing("install plugins");
+    this.plugins.push(plugin);
     this.pluginRegistry.install(plugin, this);
     return this;
   }
+  /**
+   * Register a hook that runs before rule evaluation.
+   * Use for loading signals from requests, Redis, IP lookups, etc.
+   */
+  beforeAnalyze(hook) {
+    this.beforeHooks.push(hook);
+    return this;
+  }
+  /**
+   * Register a hook that runs after the report is built.
+   * Use for audit logging, metrics, or blocking responses.
+   */
+  afterAnalyze(hook) {
+    this.afterHooks.push(hook);
+    return this;
+  }
   /**
    * Returns names of installed plugins.
    */
@@ -256,29 +522,204 @@ var Guardian = class {
     return this.pluginRegistry.getInstalled();
   }
   /**
-   * Run risk analysis and return an immutable report.
+   * Run risk analysis synchronously (skips lifecycle hooks).
+   * Prefer {@link analyzeAsync} when hooks are registered.
    */
   analyze() {
+    if (this.beforeHooks.length > 0 || this.afterHooks.length > 0) {
+      throw new Error(
+        "Guardian has analyze hooks registered. Use analyzeAsync() instead of analyze()."
+      );
+    }
     return this.riskEngine.analyze();
   }
   /**
-   * Clear all signals. Rules and installed plugins persist across resets.
+   * Run lifecycle hooks, evaluate rules, and return an immutable report.
+   *
+   * @param context Optional caller context passed to hooks (e.g. Express `req`).
+   */
+  async analyzeAsync(context) {
+    this.analyzing = true;
+    try {
+      const analyzeContext = {
+        data: context,
+        guardian: this
+      };
+      await runHooks(this.beforeHooks, analyzeContext);
+      const report = this.riskEngine.analyze();
+      const afterContext = {
+        ...analyzeContext,
+        report
+      };
+      await runHooks(this.afterHooks, afterContext);
+      return report;
+    } finally {
+      this.analyzing = false;
+    }
+  }
+  /**
+   * Create an isolated copy sharing rules, plugins, and hooks.
+   * Each fork has its own signal store for safe concurrent use.
+   */
+  fork() {
+    const child = new _Guardian({ levels: [...this.thresholds] });
+    for (const rule of this.riskEngine.getRules()) {
+      child.riskEngine.addRule(rule);
+    }
+    for (const cap of this.riskEngine.getGroupCaps()) {
+      child.riskEngine.setGroupCap(cap.name, cap.maxScore);
+    }
+    child.plugins.push(...this.plugins);
+    child.pluginRegistry.adoptInstalled(this.pluginRegistry.getInstalled());
+    for (const hook of this.beforeHooks) {
+      child.beforeHooks.push(hook);
+    }
+    for (const hook of this.afterHooks) {
+      child.afterHooks.push(hook);
+    }
+    return child;
+  }
+  /**
+   * Clear all signals. Rules, plugins, and hooks persist across resets.
    */
   reset() {
     this.signalStore.clear();
     return this;
   }
+  assertNotAnalyzing(action) {
+    if (this.analyzing) {
+      throw new Error(`Cannot ${action} while analysis is in progress`);
+    }
+  }
 };
 
+// src/guardian/defineSignals.ts
+function defineSignals() {
+  return {
+    create(config) {
+      return new Guardian(config);
+    }
+  };
+}
+
+// src/presets/applyRules.ts
+function applyRules(guardian, rules) {
+  for (const rule of rules) {
+    guardian.rule(rule);
+  }
+  return guardian;
+}
+
+// src/presets/botDetection.ts
+var botDetectionRules = [
+  {
+    name: "LinearMouseMovement",
+    reason: "Mouse movement is unnaturally linear",
+    when: (s) => s.mouseLinearity > 0.9,
+    score: 25
+  },
+  {
+    name: "RequestBurst",
+    reason: "Unusually high request rate in short window",
+    when: (s) => s.requestBurst > 50,
+    score: 30
+  },
+  {
+    name: "HeadlessBrowser",
+    reason: "User agent indicates headless browser",
+    when: (s) => s.headlessUA === true,
+    score: 40
+  },
+  {
+    name: "NewSession",
+    reason: "Session is very new",
+    when: (s) => s.sessionAgeSeconds < 10,
+    score: 10
+  },
+  {
+    name: "HighRequestRate",
+    reason: "Too many requests per minute",
+    when: (s) => s.requestsPerMinute > 30,
+    score: 35
+  }
+];
+var loginProtectionRules = [
+  {
+    name: "BruteForceAttempts",
+    reason: "Multiple failed login attempts",
+    when: (s) => s.loginAttempts > 5,
+    score: 45,
+    group: "login"
+  },
+  {
+    name: "RapidLoginBurst",
+    reason: "Login attempts in rapid succession",
+    when: (s) => s.requestsPerMinute > 10,
+    score: 25,
+    group: "login"
+  }
+];
+function parseIpAddress(value) {
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed.length > 45) {
+    return null;
+  }
+  return net.isIP(trimmed) === 0 ? null : trimmed;
+}
+function isPrivateIp(ip) {
+  const parsed = parseIpAddress(ip);
+  if (!parsed) {
+    return true;
+  }
+  if (net.isIP(parsed) === 4) {
+    if (parsed.startsWith("10.") || parsed.startsWith("127.") || parsed.startsWith("192.168.") || parsed.startsWith("169.254.") || parsed.startsWith("0.")) {
+      return true;
+    }
+    if (parsed.startsWith("172.")) {
+      const second = Number(parsed.split(".")[1]);
+      if (second >= 16 && second <= 31) {
+        return true;
+      }
+    }
+    if (parsed.startsWith("100.")) {
+      const second = Number(parsed.split(".")[1]);
+      if (second >= 64 && second <= 127) {
+        return true;
+      }
+    }
+    return false;
+  }
+  const lower = parsed.toLowerCase();
+  return lower === "::1" || lower.startsWith("fc") || lower.startsWith("fd") || lower.startsWith("fe80");
+}
+function sanitizeSessionId(value) {
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed.length > MAX_SESSION_ID_LENGTH) {
+    return null;
+  }
+  if (!SESSION_ID_PATTERN.test(trimmed)) {
+    return null;
+  }
+  return trimmed;
+}
+
 exports.DEFAULT_RISK_LEVELS = DEFAULT_RISK_LEVELS;
 exports.Guardian = Guardian;
+exports.HOOK_TIMEOUT_MS = HOOK_TIMEOUT_MS;
+exports.MAX_SIGNAL_STRING_LENGTH = MAX_SIGNAL_STRING_LENGTH;
 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.applyRules = applyRules;
+exports.botDetectionRules = botDetectionRules;
+exports.defineSignals = defineSignals;
+exports.isPrivateIp = isPrivateIp;
+exports.loginProtectionRules = loginProtectionRules;
+exports.parseIpAddress = parseIpAddress;
 exports.resolveLevel = resolveLevel;
-//# sourceMappingURL=index.cjs.map
-//# sourceMappingURL=index.cjs.map
+exports.sanitizeSessionId = sanitizeSessionId;