guardian-risk 0.2.1 → 0.3.0

package/dist/index.d.cts

@@ -27,6 +27,7 @@ interface Rule<TSignals extends SignalMap = SignalMap> {
     readonly score: number;
     readonly when: (signals: TSignals) => boolean;
     readonly reason?: string;
+    readonly group?: string;
 }
 /** Input for creating a new rule (id is auto-generated). */
 interface CreateRuleInput<TSignals extends SignalMap = SignalMap> {
@@ -35,6 +36,7 @@ interface CreateRuleInput<TSignals extends SignalMap = SignalMap> {
     readonly score: number;
     readonly when: (signals: TSignals) => boolean;
     readonly reason?: string;
+    readonly group?: string;
 }
 /** A rule that matched during evaluation. */
 interface MatchedRule {
@@ -42,6 +44,18 @@ interface MatchedRule {
     readonly name: string;
     readonly score: number;
     readonly reason: string;
+    readonly group?: string;
+}
+/** Cap applied to the sum of matched rules in a named group. */
+interface RuleGroupCap {
+    readonly name: string;
+    readonly maxScore: number;
+}
+/** Input for registering a group of related rules with an optional score cap. */
+interface RuleGroupInput<TSignals extends SignalMap = SignalMap> {
+    readonly name: string;
+    readonly maxScore?: number;
+    readonly rules: readonly CreateRuleInput<TSignals>[];
 }
 
 /** Immutable risk analysis report. */
@@ -62,40 +76,137 @@ interface GuardianConfig {
     readonly levels?: readonly RiskLevelThreshold[];
 }
 
+/** Context passed to analyze lifecycle hooks. */
+interface AnalyzeContext<TContext = unknown> {
+    /** Caller-provided context (e.g. Express `req`). */
+    readonly data: TContext;
+    /** Guardian instance being analyzed. */
+    readonly guardian: Guardian;
+}
+/** Context passed to afterAnalyze hooks. */
+interface AfterAnalyzeContext<TContext = unknown> extends AnalyzeContext<TContext> {
+    readonly report: RiskReport;
+}
+/** Runs before signals are evaluated. May be sync or async. */
+type BeforeAnalyzeHook<TContext = unknown> = (context: AnalyzeContext<TContext>) => void | Promise<void>;
+/** Runs after the risk report is built. May be sync or async. */
+type AfterAnalyzeHook<TContext = unknown> = (context: AfterAnalyzeContext<TContext>) => void | Promise<void>;
+
 /**
  * Fluent public API for risk analysis.
  * Collects signals and rules, then produces an immutable report.
+ *
+ * For concurrent workloads (e.g. HTTP), configure one template instance
+ * and call {@link fork} per request.
  */
 declare class Guardian {
     private readonly signalStore;
     private readonly riskEngine;
     private readonly pluginRegistry;
+    private readonly plugins;
+    private readonly beforeHooks;
+    private readonly afterHooks;
+    private readonly thresholds;
+    private analyzing;
     constructor(config?: GuardianConfig);
     /**
      * Add a signal value for risk evaluation.
      */
     signal(key: string, value: SignalValue): this;
+    /**
+     * Read a signal value without modifying state.
+     */
+    getSignal(key: string): SignalValue | undefined;
     /**
      * Register a rule. ID is auto-generated.
      */
     rule(input: CreateRuleInput): this;
+    /**
+     * Register a named group of rules with an optional combined score cap.
+     */
+    ruleGroup(input: RuleGroupInput): this;
     /**
      * Install a plugin. Each plugin name may only be registered once.
      */
     use(plugin: Plugin): this;
+    /**
+     * Register a hook that runs before rule evaluation.
+     * Use for loading signals from requests, Redis, IP lookups, etc.
+     */
+    beforeAnalyze<TContext = unknown>(hook: BeforeAnalyzeHook<TContext>): this;
+    /**
+     * Register a hook that runs after the report is built.
+     * Use for audit logging, metrics, or blocking responses.
+     */
+    afterAnalyze<TContext = unknown>(hook: AfterAnalyzeHook<TContext>): this;
     /**
      * Returns names of installed plugins.
      */
     getInstalledPlugins(): readonly string[];
     /**
-     * Run risk analysis and return an immutable report.
+     * Run risk analysis synchronously (skips lifecycle hooks).
+     * Prefer {@link analyzeAsync} when hooks are registered.
      */
     analyze(): RiskReport;
     /**
-     * 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`).
+     */
+    analyzeAsync<TContext = unknown>(context?: TContext): Promise<RiskReport>;
+    /**
+     * Create an isolated copy sharing rules, plugins, and hooks.
+     * Each fork has its own signal store for safe concurrent use.
+     */
+    fork(): Guardian;
+    /**
+     * Clear all signals. Rules, plugins, and hooks persist across resets.
      */
     reset(): this;
+    private assertNotAnalyzing;
+}
+
+/** Guardian with typed signal keys and rule predicates. */
+type TypedGuardian<TSignals extends SignalMap> = Guardian & {
+    signal<K extends keyof TSignals & string>(key: K, value: TSignals[K]): TypedGuardian<TSignals>;
+    rule(input: CreateRuleInput<TSignals>): TypedGuardian<TSignals>;
+};
+/**
+ * Define a typed signal schema for compile-time key/value checking.
+ *
+ * @example
+ * ```typescript
+ * const botSignals = defineSignals<{
+ *   mouseLinearity: number;
+ *   headlessUA: boolean;
+ * }>();
+ *
+ * const guardian = botSignals.create()
+ *   .signal('mouseLinearity', 0.95) // typed
+ *   .rule({ name: 'Linear', when: (s) => s.mouseLinearity > 0.9, score: 20 });
+ * ```
+ */
+declare function defineSignals<TSignals extends SignalMap>(): {
+    create(config?: GuardianConfig): TypedGuardian<TSignals>;
+};
+
+/**
+ * Register a list of preset rules on a Guardian instance.
+ */
+declare function applyRules<TSignals extends SignalMap = SignalMap>(guardian: Guardian, rules: readonly CreateRuleInput<TSignals>[]): Guardian;
+
+/** Common bot-detection signal keys. */
+interface BotDetectionSignals extends Record<string, SignalValue> {
+    mouseLinearity: number;
+    requestBurst: number;
+    headlessUA: boolean;
+    sessionAgeSeconds: number;
+    requestsPerMinute: number;
 }
+/** Ready-to-use bot detection rules (customize scores for your app). */
+declare const botDetectionRules: readonly CreateRuleInput<BotDetectionSignals>[];
+/** Login brute-force rules — use with redis plugin signals. */
+declare const loginProtectionRules: readonly CreateRuleInput[];
 
 /**
  * Builds immutable risk reports.
@@ -119,13 +230,13 @@ declare class RuleEvaluator {
 }
 
 /**
- * Calculates risk score from matched rules.
+ * Calculates risk score from matched rules with optional per-group caps.
  */
 declare class ScoreCalculator {
     /**
-     * Sum scores from all matched rules, clamped to a safe maximum.
+     * Sum scores from matched rules, applying group caps when configured.
      */
-    calculate(matchedRules: readonly MatchedRule[]): number;
+    calculate(matchedRules: readonly MatchedRule[], groupCaps?: readonly RuleGroupCap[]): number;
 }
 
 /**
@@ -168,6 +279,7 @@ interface RiskEngineDependencies {
 declare class RiskEngine {
     private readonly deps;
     private readonly rules;
+    private readonly groupCaps;
     private readonly thresholds;
     constructor(deps: RiskEngineDependencies, thresholds?: readonly RiskLevelThreshold[]);
     /**
@@ -178,6 +290,14 @@ declare class RiskEngine {
      * Get all registered rules.
      */
     getRules(): readonly Rule<SignalMap>[];
+    /**
+     * Get configured per-group score caps.
+     */
+    getGroupCaps(): readonly RuleGroupCap[];
+    /**
+     * Cap the combined score of matched rules in a group.
+     */
+    setGroupCap(name: string, maxScore: number): void;
     /**
      * Run the full risk analysis pipeline.
      */
@@ -210,6 +330,11 @@ declare class PluginRegistry {
      * Check if a plugin is installed by name.
      */
     has(name: string): boolean;
+    /**
+     * Copy installed plugin names from a template (used by Guardian.fork).
+     * Does not call install() — rules and hooks are copied separately.
+     */
+    adoptInstalled(names: readonly string[]): void;
     /**
      * Get names of all installed plugins in registration order.
      */
@@ -232,7 +357,25 @@ declare class RuleBuilder {
  */
 declare function resolveLevel(score: number, thresholds?: readonly RiskLevelThreshold[]): string;
 
+/**
+ * Parse and validate an IP address (v4 or v6). Returns null if invalid.
+ */
+declare function parseIpAddress(value: string): string | null;
+/**
+ * Whether an IP is private, loopback, link-local, or CGNAT (skip external lookup).
+ */
+declare function isPrivateIp(ip: string): boolean;
+/**
+ * Validate a session identifier (length + charset).
+ */
+declare function sanitizeSessionId(value: string): string | null;
+
+/** Maximum length for string signal values. */
+declare const MAX_SIGNAL_STRING_LENGTH = 4096;
+/** Default timeout for analyze lifecycle hooks (ms). */
+declare const HOOK_TIMEOUT_MS = 10000;
+
 /** 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 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 };
+export { type AfterAnalyzeContext, type AfterAnalyzeHook, type AnalyzeContext, type BeforeAnalyzeHook, type BotDetectionSignals, type CreateRuleInput, DEFAULT_RISK_LEVELS, Guardian, type GuardianConfig, type GuardianPlugin, HOOK_TIMEOUT_MS, MAX_SIGNAL_STRING_LENGTH, type MatchedRule, type Plugin, PluginAlreadyInstalledError, PluginInstallError, PluginRegistry, RiskEngine, type RiskEngineDependencies, type RiskLevelThreshold, type RiskReport, type Rule, RuleBuilder, RuleEvaluator, type RuleGroupCap, type RuleGroupInput, ScoreCalculator, type SignalDefinition, type SignalMap, SignalStore, type SignalValue, type TypedGuardian, applyRules, botDetectionRules, defineSignals, isPrivateIp, loginProtectionRules, parseIpAddress, resolveLevel, sanitizeSessionId };

package/dist/index.d.ts

@@ -27,6 +27,7 @@ interface Rule<TSignals extends SignalMap = SignalMap> {
     readonly score: number;
     readonly when: (signals: TSignals) => boolean;
     readonly reason?: string;
+    readonly group?: string;
 }
 /** Input for creating a new rule (id is auto-generated). */
 interface CreateRuleInput<TSignals extends SignalMap = SignalMap> {
@@ -35,6 +36,7 @@ interface CreateRuleInput<TSignals extends SignalMap = SignalMap> {
     readonly score: number;
     readonly when: (signals: TSignals) => boolean;
     readonly reason?: string;
+    readonly group?: string;
 }
 /** A rule that matched during evaluation. */
 interface MatchedRule {
@@ -42,6 +44,18 @@ interface MatchedRule {
     readonly name: string;
     readonly score: number;
     readonly reason: string;
+    readonly group?: string;
+}
+/** Cap applied to the sum of matched rules in a named group. */
+interface RuleGroupCap {
+    readonly name: string;
+    readonly maxScore: number;
+}
+/** Input for registering a group of related rules with an optional score cap. */
+interface RuleGroupInput<TSignals extends SignalMap = SignalMap> {
+    readonly name: string;
+    readonly maxScore?: number;
+    readonly rules: readonly CreateRuleInput<TSignals>[];
 }
 
 /** Immutable risk analysis report. */
@@ -62,40 +76,137 @@ interface GuardianConfig {
     readonly levels?: readonly RiskLevelThreshold[];
 }
 
+/** Context passed to analyze lifecycle hooks. */
+interface AnalyzeContext<TContext = unknown> {
+    /** Caller-provided context (e.g. Express `req`). */
+    readonly data: TContext;
+    /** Guardian instance being analyzed. */
+    readonly guardian: Guardian;
+}
+/** Context passed to afterAnalyze hooks. */
+interface AfterAnalyzeContext<TContext = unknown> extends AnalyzeContext<TContext> {
+    readonly report: RiskReport;
+}
+/** Runs before signals are evaluated. May be sync or async. */
+type BeforeAnalyzeHook<TContext = unknown> = (context: AnalyzeContext<TContext>) => void | Promise<void>;
+/** Runs after the risk report is built. May be sync or async. */
+type AfterAnalyzeHook<TContext = unknown> = (context: AfterAnalyzeContext<TContext>) => void | Promise<void>;
+
 /**
  * Fluent public API for risk analysis.
  * Collects signals and rules, then produces an immutable report.
+ *
+ * For concurrent workloads (e.g. HTTP), configure one template instance
+ * and call {@link fork} per request.
  */
 declare class Guardian {
     private readonly signalStore;
     private readonly riskEngine;
     private readonly pluginRegistry;
+    private readonly plugins;
+    private readonly beforeHooks;
+    private readonly afterHooks;
+    private readonly thresholds;
+    private analyzing;
     constructor(config?: GuardianConfig);
     /**
      * Add a signal value for risk evaluation.
      */
     signal(key: string, value: SignalValue): this;
+    /**
+     * Read a signal value without modifying state.
+     */
+    getSignal(key: string): SignalValue | undefined;
     /**
      * Register a rule. ID is auto-generated.
      */
     rule(input: CreateRuleInput): this;
+    /**
+     * Register a named group of rules with an optional combined score cap.
+     */
+    ruleGroup(input: RuleGroupInput): this;
     /**
      * Install a plugin. Each plugin name may only be registered once.
      */
     use(plugin: Plugin): this;
+    /**
+     * Register a hook that runs before rule evaluation.
+     * Use for loading signals from requests, Redis, IP lookups, etc.
+     */
+    beforeAnalyze<TContext = unknown>(hook: BeforeAnalyzeHook<TContext>): this;
+    /**
+     * Register a hook that runs after the report is built.
+     * Use for audit logging, metrics, or blocking responses.
+     */
+    afterAnalyze<TContext = unknown>(hook: AfterAnalyzeHook<TContext>): this;
     /**
      * Returns names of installed plugins.
      */
     getInstalledPlugins(): readonly string[];
     /**
-     * Run risk analysis and return an immutable report.
+     * Run risk analysis synchronously (skips lifecycle hooks).
+     * Prefer {@link analyzeAsync} when hooks are registered.
      */
     analyze(): RiskReport;
     /**
-     * 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`).
+     */
+    analyzeAsync<TContext = unknown>(context?: TContext): Promise<RiskReport>;
+    /**
+     * Create an isolated copy sharing rules, plugins, and hooks.
+     * Each fork has its own signal store for safe concurrent use.
+     */
+    fork(): Guardian;
+    /**
+     * Clear all signals. Rules, plugins, and hooks persist across resets.
      */
     reset(): this;
+    private assertNotAnalyzing;
+}
+
+/** Guardian with typed signal keys and rule predicates. */
+type TypedGuardian<TSignals extends SignalMap> = Guardian & {
+    signal<K extends keyof TSignals & string>(key: K, value: TSignals[K]): TypedGuardian<TSignals>;
+    rule(input: CreateRuleInput<TSignals>): TypedGuardian<TSignals>;
+};
+/**
+ * Define a typed signal schema for compile-time key/value checking.
+ *
+ * @example
+ * ```typescript
+ * const botSignals = defineSignals<{
+ *   mouseLinearity: number;
+ *   headlessUA: boolean;
+ * }>();
+ *
+ * const guardian = botSignals.create()
+ *   .signal('mouseLinearity', 0.95) // typed
+ *   .rule({ name: 'Linear', when: (s) => s.mouseLinearity > 0.9, score: 20 });
+ * ```
+ */
+declare function defineSignals<TSignals extends SignalMap>(): {
+    create(config?: GuardianConfig): TypedGuardian<TSignals>;
+};
+
+/**
+ * Register a list of preset rules on a Guardian instance.
+ */
+declare function applyRules<TSignals extends SignalMap = SignalMap>(guardian: Guardian, rules: readonly CreateRuleInput<TSignals>[]): Guardian;
+
+/** Common bot-detection signal keys. */
+interface BotDetectionSignals extends Record<string, SignalValue> {
+    mouseLinearity: number;
+    requestBurst: number;
+    headlessUA: boolean;
+    sessionAgeSeconds: number;
+    requestsPerMinute: number;
 }
+/** Ready-to-use bot detection rules (customize scores for your app). */
+declare const botDetectionRules: readonly CreateRuleInput<BotDetectionSignals>[];
+/** Login brute-force rules — use with redis plugin signals. */
+declare const loginProtectionRules: readonly CreateRuleInput[];
 
 /**
  * Builds immutable risk reports.
@@ -119,13 +230,13 @@ declare class RuleEvaluator {
 }
 
 /**
- * Calculates risk score from matched rules.
+ * Calculates risk score from matched rules with optional per-group caps.
  */
 declare class ScoreCalculator {
     /**
-     * Sum scores from all matched rules, clamped to a safe maximum.
+     * Sum scores from matched rules, applying group caps when configured.
      */
-    calculate(matchedRules: readonly MatchedRule[]): number;
+    calculate(matchedRules: readonly MatchedRule[], groupCaps?: readonly RuleGroupCap[]): number;
 }
 
 /**
@@ -168,6 +279,7 @@ interface RiskEngineDependencies {
 declare class RiskEngine {
     private readonly deps;
     private readonly rules;
+    private readonly groupCaps;
     private readonly thresholds;
     constructor(deps: RiskEngineDependencies, thresholds?: readonly RiskLevelThreshold[]);
     /**
@@ -178,6 +290,14 @@ declare class RiskEngine {
      * Get all registered rules.
      */
     getRules(): readonly Rule<SignalMap>[];
+    /**
+     * Get configured per-group score caps.
+     */
+    getGroupCaps(): readonly RuleGroupCap[];
+    /**
+     * Cap the combined score of matched rules in a group.
+     */
+    setGroupCap(name: string, maxScore: number): void;
     /**
      * Run the full risk analysis pipeline.
      */
@@ -210,6 +330,11 @@ declare class PluginRegistry {
      * Check if a plugin is installed by name.
      */
     has(name: string): boolean;
+    /**
+     * Copy installed plugin names from a template (used by Guardian.fork).
+     * Does not call install() — rules and hooks are copied separately.
+     */
+    adoptInstalled(names: readonly string[]): void;
     /**
      * Get names of all installed plugins in registration order.
      */
@@ -232,7 +357,25 @@ declare class RuleBuilder {
  */
 declare function resolveLevel(score: number, thresholds?: readonly RiskLevelThreshold[]): string;
 
+/**
+ * Parse and validate an IP address (v4 or v6). Returns null if invalid.
+ */
+declare function parseIpAddress(value: string): string | null;
+/**
+ * Whether an IP is private, loopback, link-local, or CGNAT (skip external lookup).
+ */
+declare function isPrivateIp(ip: string): boolean;
+/**
+ * Validate a session identifier (length + charset).
+ */
+declare function sanitizeSessionId(value: string): string | null;
+
+/** Maximum length for string signal values. */
+declare const MAX_SIGNAL_STRING_LENGTH = 4096;
+/** Default timeout for analyze lifecycle hooks (ms). */
+declare const HOOK_TIMEOUT_MS = 10000;
+
 /** 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 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 };
+export { type AfterAnalyzeContext, type AfterAnalyzeHook, type AnalyzeContext, type BeforeAnalyzeHook, type BotDetectionSignals, type CreateRuleInput, DEFAULT_RISK_LEVELS, Guardian, type GuardianConfig, type GuardianPlugin, HOOK_TIMEOUT_MS, MAX_SIGNAL_STRING_LENGTH, type MatchedRule, type Plugin, PluginAlreadyInstalledError, PluginInstallError, PluginRegistry, RiskEngine, type RiskEngineDependencies, type RiskLevelThreshold, type RiskReport, type Rule, RuleBuilder, RuleEvaluator, type RuleGroupCap, type RuleGroupInput, ScoreCalculator, type SignalDefinition, type SignalMap, SignalStore, type SignalValue, type TypedGuardian, applyRules, botDetectionRules, defineSignals, isPrivateIp, loginProtectionRules, parseIpAddress, resolveLevel, sanitizeSessionId };