guardian-risk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guardian Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# guardian-risk
+
+Configurable risk decision engine for TypeScript. Evaluate signals against rules and get an explainable risk score.
+
+## Install
+
+```bash
+npm install guardian-risk
+# or
+pnpm add guardian-risk
+```
+
+## Usage
+
+```typescript
+import { Guardian } from 'guardian-risk';
+
+const guardian = new Guardian();
+
+const report = guardian
+  .signal('postsPerMinute', 50)
+  .signal('emailVerified', false)
+  .rule({
+    name: 'HighPosting',
+    when: (s) => (s.postsPerMinute as number) > 20,
+    score: 20,
+  })
+  .rule({
+    name: 'UnverifiedEmail',
+    when: (s) => s.emailVerified === false,
+    score: 15,
+  })
+  .analyze();
+
+console.log(report.score); // 35
+console.log(report.level); // MEDIUM
+```
+
+## 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)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,234 @@
+'use strict';
+
+var crypto = require('crypto');
+
+// src/constants/defaults.ts
+var DEFAULT_RISK_LEVELS = [
+  { max: 20, level: "LOW" },
+  { max: 40, level: "MEDIUM" },
+  { max: 60, level: "HIGH" },
+  { max: Infinity, level: "CRITICAL" }
+];
+
+// src/utils/resolveLevel.ts
+function resolveLevel(score, thresholds = DEFAULT_RISK_LEVELS) {
+  for (const threshold of thresholds) {
+    if (score <= threshold.max) {
+      return threshold.level;
+    }
+  }
+  const last = thresholds[thresholds.length - 1];
+  return last?.level ?? "UNKNOWN";
+}
+
+// src/report/Report.ts
+var ReportBuilder = class {
+  /**
+   * Build a frozen risk report from evaluation results.
+   */
+  build(score, matchedRules, thresholds, analyzedAt = (/* @__PURE__ */ new Date()).toISOString()) {
+    const reasons = matchedRules.map((rule) => rule.reason);
+    const level = resolveLevel(score, thresholds);
+    const report = {
+      score,
+      level,
+      reasons: Object.freeze([...reasons]),
+      matchedRules: Object.freeze([...matchedRules]),
+      analyzedAt
+    };
+    return Object.freeze(report);
+  }
+};
+
+// src/rules/RuleEvaluator.ts
+var RuleEvaluator = class {
+  /**
+   * Evaluate all rules against the given signals.
+   * Rules are evaluated in registration order (exhaustive, no short-circuit).
+   */
+  evaluate(rules, signals) {
+    const matched = [];
+    for (const rule of rules) {
+      if (rule.when(signals)) {
+        matched.push({
+          id: rule.id,
+          name: rule.name,
+          score: rule.score,
+          reason: rule.reason ?? rule.name
+        });
+      }
+    }
+    return matched;
+  }
+};
+
+// src/score/ScoreCalculator.ts
+var ScoreCalculator = class {
+  /**
+   * Sum scores from all matched rules.
+   */
+  calculate(matchedRules) {
+    return matchedRules.reduce((total, rule) => total + rule.score, 0);
+  }
+};
+function validateSignalValue(value) {
+  if (value === null) {
+    return true;
+  }
+  const type = typeof value;
+  return type === "string" || type === "number" || type === "boolean";
+}
+function generateId() {
+  return crypto.randomUUID();
+}
+
+// src/signals/SignalStore.ts
+var SignalStore = class {
+  signals = /* @__PURE__ */ new Map();
+  /**
+   * Set a signal value. Overwrites any existing value for the key.
+   */
+  set(key, value) {
+    if (!validateSignalValue(value)) {
+      throw new TypeError(
+        `Invalid signal value for "${key}": signals must be string, number, boolean, or null`
+      );
+    }
+    this.signals.set(key, value);
+    return this;
+  }
+  /**
+   * Get a signal value by key.
+   */
+  get(key) {
+    return this.signals.get(key);
+  }
+  /**
+   * Check if a signal exists.
+   */
+  has(key) {
+    return this.signals.has(key);
+  }
+  /**
+   * Returns a frozen snapshot of all signals.
+   */
+  getAll() {
+    const snapshot = {};
+    for (const [key, value] of this.signals) {
+      snapshot[key] = value;
+    }
+    return Object.freeze(snapshot);
+  }
+  /**
+   * Clear all signals.
+   */
+  clear() {
+    this.signals.clear();
+  }
+};
+
+// src/engine/RiskEngine.ts
+var RiskEngine = class {
+  constructor(deps, thresholds = DEFAULT_RISK_LEVELS) {
+    this.deps = deps;
+    this.thresholds = thresholds;
+  }
+  deps;
+  rules = [];
+  thresholds;
+  /**
+   * Register a rule for evaluation.
+   */
+  addRule(rule) {
+    this.rules.push(rule);
+  }
+  /**
+   * Get all registered rules.
+   */
+  getRules() {
+    return this.rules;
+  }
+  /**
+   * 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);
+    return this.deps.reportBuilder.build(score, matchedRules, this.thresholds);
+  }
+};
+
+// src/rules/RuleBuilder.ts
+var RuleBuilder = class {
+  /**
+   * Create a new rule from input configuration.
+   */
+  static create(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 } : {}
+    };
+    return rule;
+  }
+};
+
+// src/engine/Guardian.ts
+var Guardian = class {
+  signalStore;
+  riskEngine;
+  constructor(config = {}) {
+    const thresholds = config.levels ?? DEFAULT_RISK_LEVELS;
+    this.signalStore = new SignalStore();
+    const deps = {
+      signalStore: this.signalStore,
+      ruleEvaluator: new RuleEvaluator(),
+      scoreCalculator: new ScoreCalculator(),
+      reportBuilder: new ReportBuilder()
+    };
+    this.riskEngine = new RiskEngine(deps, thresholds);
+  }
+  /**
+   * Add a signal value for risk evaluation.
+   */
+  signal(key, value) {
+    this.signalStore.set(key, value);
+    return this;
+  }
+  /**
+   * Register a rule. ID is auto-generated.
+   */
+  rule(input) {
+    const rule = RuleBuilder.create(input);
+    this.riskEngine.addRule(rule);
+    return this;
+  }
+  /**
+   * Run risk analysis and return an immutable report.
+   */
+  analyze() {
+    return this.riskEngine.analyze();
+  }
+  /**
+   * Clear all signals. Rules persist across resets.
+   */
+  reset() {
+    this.signalStore.clear();
+    return this;
+  }
+};
+
+exports.DEFAULT_RISK_LEVELS = DEFAULT_RISK_LEVELS;
+exports.Guardian = Guardian;
+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.cjs.map

@@ -0,0 +1 @@
+{"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.d.cts

@@ -0,0 +1,186 @@
+/** Primitive signal value types supported by Guardian. */
+type SignalValue = string | number | boolean | null;
+/** Read-only map of signal key to value. */
+type SignalMap = Readonly<Record<string, SignalValue>>;
+/** Definition of a single signal. */
+interface SignalDefinition<T extends SignalValue = SignalValue> {
+    readonly key: string;
+    readonly value: T;
+}
+
+/** A rule that evaluates signals and contributes risk when matched. */
+interface Rule<TSignals extends SignalMap = SignalMap> {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly score: number;
+    readonly when: (signals: TSignals) => boolean;
+    readonly reason?: string;
+}
+/** Input for creating a new rule (id is auto-generated). */
+interface CreateRuleInput<TSignals extends SignalMap = SignalMap> {
+    readonly name: string;
+    readonly description?: string;
+    readonly score: number;
+    readonly when: (signals: TSignals) => boolean;
+    readonly reason?: string;
+}
+/** A rule that matched during evaluation. */
+interface MatchedRule {
+    readonly id: string;
+    readonly name: string;
+    readonly score: number;
+    readonly reason: string;
+}
+
+/** Immutable risk analysis report. */
+interface RiskReport {
+    readonly score: number;
+    readonly level: string;
+    readonly reasons: readonly string[];
+    readonly matchedRules: readonly MatchedRule[];
+    readonly analyzedAt: string;
+}
+/** Threshold mapping a maximum score to a risk level label. */
+interface RiskLevelThreshold {
+    readonly max: number;
+    readonly level: string;
+}
+/** Configuration options for Guardian. */
+interface GuardianConfig {
+    readonly levels?: readonly RiskLevelThreshold[];
+}
+
+/**
+ * Fluent public API for risk analysis.
+ * Collects signals and rules, then produces an immutable report.
+ */
+declare class Guardian {
+    private readonly signalStore;
+    private readonly riskEngine;
+    constructor(config?: GuardianConfig);
+    /**
+     * Add a signal value for risk evaluation.
+     */
+    signal(key: string, value: SignalValue): this;
+    /**
+     * Register a rule. ID is auto-generated.
+     */
+    rule(input: CreateRuleInput): this;
+    /**
+     * Run risk analysis and return an immutable report.
+     */
+    analyze(): RiskReport;
+    /**
+     * Clear all signals. Rules persist across resets.
+     */
+    reset(): this;
+}
+
+/**
+ * Builds immutable risk reports.
+ */
+declare class ReportBuilder {
+    /**
+     * Build a frozen risk report from evaluation results.
+     */
+    build(score: number, matchedRules: readonly MatchedRule[], thresholds: readonly RiskLevelThreshold[], analyzedAt?: string): RiskReport;
+}
+
+/**
+ * Evaluates rules against a signal map and returns matched rules.
+ */
+declare class RuleEvaluator {
+    /**
+     * Evaluate all rules against the given signals.
+     * Rules are evaluated in registration order (exhaustive, no short-circuit).
+     */
+    evaluate<TSignals extends SignalMap>(rules: readonly Rule<TSignals>[], signals: TSignals): MatchedRule[];
+}
+
+/**
+ * Calculates risk score from matched rules.
+ */
+declare class ScoreCalculator {
+    /**
+     * Sum scores from all matched rules.
+     */
+    calculate(matchedRules: readonly MatchedRule[]): number;
+}
+
+/**
+ * Stores and retrieves signal values for risk evaluation.
+ */
+declare class SignalStore {
+    private readonly signals;
+    /**
+     * Set a signal value. Overwrites any existing value for the key.
+     */
+    set(key: string, value: SignalValue): this;
+    /**
+     * Get a signal value by key.
+     */
+    get(key: string): SignalValue | undefined;
+    /**
+     * Check if a signal exists.
+     */
+    has(key: string): boolean;
+    /**
+     * Returns a frozen snapshot of all signals.
+     */
+    getAll(): SignalMap;
+    /**
+     * Clear all signals.
+     */
+    clear(): void;
+}
+
+/** Dependencies injected into RiskEngine. */
+interface RiskEngineDependencies {
+    readonly signalStore: SignalStore;
+    readonly ruleEvaluator: RuleEvaluator;
+    readonly scoreCalculator: ScoreCalculator;
+    readonly reportBuilder: ReportBuilder;
+}
+/**
+ * Orchestrates signal evaluation, scoring, and report generation.
+ */
+declare class RiskEngine {
+    private readonly deps;
+    private readonly rules;
+    private readonly thresholds;
+    constructor(deps: RiskEngineDependencies, thresholds?: readonly RiskLevelThreshold[]);
+    /**
+     * Register a rule for evaluation.
+     */
+    addRule(rule: Rule<SignalMap>): void;
+    /**
+     * Get all registered rules.
+     */
+    getRules(): readonly Rule<SignalMap>[];
+    /**
+     * Run the full risk analysis pipeline.
+     */
+    analyze(): RiskReport;
+}
+
+/**
+ * Builds immutable rule definitions with auto-generated IDs.
+ */
+declare class RuleBuilder {
+    /**
+     * Create a new rule from input configuration.
+     */
+    static create<TSignals extends SignalMap = SignalMap>(input: CreateRuleInput<TSignals>): Rule<TSignals>;
+}
+
+/**
+ * Resolves a risk level label from a score using configured thresholds.
+ * Thresholds are evaluated in order; the first threshold where score <= max wins.
+ */
+declare function resolveLevel(score: number, thresholds?: readonly RiskLevelThreshold[]): string;
+
+/** 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 };

package/dist/index.d.ts

@@ -0,0 +1,186 @@
+/** Primitive signal value types supported by Guardian. */
+type SignalValue = string | number | boolean | null;
+/** Read-only map of signal key to value. */
+type SignalMap = Readonly<Record<string, SignalValue>>;
+/** Definition of a single signal. */
+interface SignalDefinition<T extends SignalValue = SignalValue> {
+    readonly key: string;
+    readonly value: T;
+}
+
+/** A rule that evaluates signals and contributes risk when matched. */
+interface Rule<TSignals extends SignalMap = SignalMap> {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly score: number;
+    readonly when: (signals: TSignals) => boolean;
+    readonly reason?: string;
+}
+/** Input for creating a new rule (id is auto-generated). */
+interface CreateRuleInput<TSignals extends SignalMap = SignalMap> {
+    readonly name: string;
+    readonly description?: string;
+    readonly score: number;
+    readonly when: (signals: TSignals) => boolean;
+    readonly reason?: string;
+}
+/** A rule that matched during evaluation. */
+interface MatchedRule {
+    readonly id: string;
+    readonly name: string;
+    readonly score: number;
+    readonly reason: string;
+}
+
+/** Immutable risk analysis report. */
+interface RiskReport {
+    readonly score: number;
+    readonly level: string;
+    readonly reasons: readonly string[];
+    readonly matchedRules: readonly MatchedRule[];
+    readonly analyzedAt: string;
+}
+/** Threshold mapping a maximum score to a risk level label. */
+interface RiskLevelThreshold {
+    readonly max: number;
+    readonly level: string;
+}
+/** Configuration options for Guardian. */
+interface GuardianConfig {
+    readonly levels?: readonly RiskLevelThreshold[];
+}
+
+/**
+ * Fluent public API for risk analysis.
+ * Collects signals and rules, then produces an immutable report.
+ */
+declare class Guardian {
+    private readonly signalStore;
+    private readonly riskEngine;
+    constructor(config?: GuardianConfig);
+    /**
+     * Add a signal value for risk evaluation.
+     */
+    signal(key: string, value: SignalValue): this;
+    /**
+     * Register a rule. ID is auto-generated.
+     */
+    rule(input: CreateRuleInput): this;
+    /**
+     * Run risk analysis and return an immutable report.
+     */
+    analyze(): RiskReport;
+    /**
+     * Clear all signals. Rules persist across resets.
+     */
+    reset(): this;
+}
+
+/**
+ * Builds immutable risk reports.
+ */
+declare class ReportBuilder {
+    /**
+     * Build a frozen risk report from evaluation results.
+     */
+    build(score: number, matchedRules: readonly MatchedRule[], thresholds: readonly RiskLevelThreshold[], analyzedAt?: string): RiskReport;
+}
+
+/**
+ * Evaluates rules against a signal map and returns matched rules.
+ */
+declare class RuleEvaluator {
+    /**
+     * Evaluate all rules against the given signals.
+     * Rules are evaluated in registration order (exhaustive, no short-circuit).
+     */
+    evaluate<TSignals extends SignalMap>(rules: readonly Rule<TSignals>[], signals: TSignals): MatchedRule[];
+}
+
+/**
+ * Calculates risk score from matched rules.
+ */
+declare class ScoreCalculator {
+    /**
+     * Sum scores from all matched rules.
+     */
+    calculate(matchedRules: readonly MatchedRule[]): number;
+}
+
+/**
+ * Stores and retrieves signal values for risk evaluation.
+ */
+declare class SignalStore {
+    private readonly signals;
+    /**
+     * Set a signal value. Overwrites any existing value for the key.
+     */
+    set(key: string, value: SignalValue): this;
+    /**
+     * Get a signal value by key.
+     */
+    get(key: string): SignalValue | undefined;
+    /**
+     * Check if a signal exists.
+     */
+    has(key: string): boolean;
+    /**
+     * Returns a frozen snapshot of all signals.
+     */
+    getAll(): SignalMap;
+    /**
+     * Clear all signals.
+     */
+    clear(): void;
+}
+
+/** Dependencies injected into RiskEngine. */
+interface RiskEngineDependencies {
+    readonly signalStore: SignalStore;
+    readonly ruleEvaluator: RuleEvaluator;
+    readonly scoreCalculator: ScoreCalculator;
+    readonly reportBuilder: ReportBuilder;
+}
+/**
+ * Orchestrates signal evaluation, scoring, and report generation.
+ */
+declare class RiskEngine {
+    private readonly deps;
+    private readonly rules;
+    private readonly thresholds;
+    constructor(deps: RiskEngineDependencies, thresholds?: readonly RiskLevelThreshold[]);
+    /**
+     * Register a rule for evaluation.
+     */
+    addRule(rule: Rule<SignalMap>): void;
+    /**
+     * Get all registered rules.
+     */
+    getRules(): readonly Rule<SignalMap>[];
+    /**
+     * Run the full risk analysis pipeline.
+     */
+    analyze(): RiskReport;
+}
+
+/**
+ * Builds immutable rule definitions with auto-generated IDs.
+ */
+declare class RuleBuilder {
+    /**
+     * Create a new rule from input configuration.
+     */
+    static create<TSignals extends SignalMap = SignalMap>(input: CreateRuleInput<TSignals>): Rule<TSignals>;
+}
+
+/**
+ * Resolves a risk level label from a score using configured thresholds.
+ * Thresholds are evaluated in order; the first threshold where score <= max wins.
+ */
+declare function resolveLevel(score: number, thresholds?: readonly RiskLevelThreshold[]): string;
+
+/** 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 };

package/dist/index.js

@@ -0,0 +1,225 @@
+import { randomUUID } from 'crypto';
+
+// src/constants/defaults.ts
+var DEFAULT_RISK_LEVELS = [
+  { max: 20, level: "LOW" },
+  { max: 40, level: "MEDIUM" },
+  { max: 60, level: "HIGH" },
+  { max: Infinity, level: "CRITICAL" }
+];
+
+// src/utils/resolveLevel.ts
+function resolveLevel(score, thresholds = DEFAULT_RISK_LEVELS) {
+  for (const threshold of thresholds) {
+    if (score <= threshold.max) {
+      return threshold.level;
+    }
+  }
+  const last = thresholds[thresholds.length - 1];
+  return last?.level ?? "UNKNOWN";
+}
+
+// src/report/Report.ts
+var ReportBuilder = class {
+  /**
+   * Build a frozen risk report from evaluation results.
+   */
+  build(score, matchedRules, thresholds, analyzedAt = (/* @__PURE__ */ new Date()).toISOString()) {
+    const reasons = matchedRules.map((rule) => rule.reason);
+    const level = resolveLevel(score, thresholds);
+    const report = {
+      score,
+      level,
+      reasons: Object.freeze([...reasons]),
+      matchedRules: Object.freeze([...matchedRules]),
+      analyzedAt
+    };
+    return Object.freeze(report);
+  }
+};
+
+// src/rules/RuleEvaluator.ts
+var RuleEvaluator = class {
+  /**
+   * Evaluate all rules against the given signals.
+   * Rules are evaluated in registration order (exhaustive, no short-circuit).
+   */
+  evaluate(rules, signals) {
+    const matched = [];
+    for (const rule of rules) {
+      if (rule.when(signals)) {
+        matched.push({
+          id: rule.id,
+          name: rule.name,
+          score: rule.score,
+          reason: rule.reason ?? rule.name
+        });
+      }
+    }
+    return matched;
+  }
+};
+
+// src/score/ScoreCalculator.ts
+var ScoreCalculator = class {
+  /**
+   * Sum scores from all matched rules.
+   */
+  calculate(matchedRules) {
+    return matchedRules.reduce((total, rule) => total + rule.score, 0);
+  }
+};
+function validateSignalValue(value) {
+  if (value === null) {
+    return true;
+  }
+  const type = typeof value;
+  return type === "string" || type === "number" || type === "boolean";
+}
+function generateId() {
+  return randomUUID();
+}
+
+// src/signals/SignalStore.ts
+var SignalStore = class {
+  signals = /* @__PURE__ */ new Map();
+  /**
+   * Set a signal value. Overwrites any existing value for the key.
+   */
+  set(key, value) {
+    if (!validateSignalValue(value)) {
+      throw new TypeError(
+        `Invalid signal value for "${key}": signals must be string, number, boolean, or null`
+      );
+    }
+    this.signals.set(key, value);
+    return this;
+  }
+  /**
+   * Get a signal value by key.
+   */
+  get(key) {
+    return this.signals.get(key);
+  }
+  /**
+   * Check if a signal exists.
+   */
+  has(key) {
+    return this.signals.has(key);
+  }
+  /**
+   * Returns a frozen snapshot of all signals.
+   */
+  getAll() {
+    const snapshot = {};
+    for (const [key, value] of this.signals) {
+      snapshot[key] = value;
+    }
+    return Object.freeze(snapshot);
+  }
+  /**
+   * Clear all signals.
+   */
+  clear() {
+    this.signals.clear();
+  }
+};
+
+// src/engine/RiskEngine.ts
+var RiskEngine = class {
+  constructor(deps, thresholds = DEFAULT_RISK_LEVELS) {
+    this.deps = deps;
+    this.thresholds = thresholds;
+  }
+  deps;
+  rules = [];
+  thresholds;
+  /**
+   * Register a rule for evaluation.
+   */
+  addRule(rule) {
+    this.rules.push(rule);
+  }
+  /**
+   * Get all registered rules.
+   */
+  getRules() {
+    return this.rules;
+  }
+  /**
+   * 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);
+    return this.deps.reportBuilder.build(score, matchedRules, this.thresholds);
+  }
+};
+
+// src/rules/RuleBuilder.ts
+var RuleBuilder = class {
+  /**
+   * Create a new rule from input configuration.
+   */
+  static create(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 } : {}
+    };
+    return rule;
+  }
+};
+
+// src/engine/Guardian.ts
+var Guardian = class {
+  signalStore;
+  riskEngine;
+  constructor(config = {}) {
+    const thresholds = config.levels ?? DEFAULT_RISK_LEVELS;
+    this.signalStore = new SignalStore();
+    const deps = {
+      signalStore: this.signalStore,
+      ruleEvaluator: new RuleEvaluator(),
+      scoreCalculator: new ScoreCalculator(),
+      reportBuilder: new ReportBuilder()
+    };
+    this.riskEngine = new RiskEngine(deps, thresholds);
+  }
+  /**
+   * Add a signal value for risk evaluation.
+   */
+  signal(key, value) {
+    this.signalStore.set(key, value);
+    return this;
+  }
+  /**
+   * Register a rule. ID is auto-generated.
+   */
+  rule(input) {
+    const rule = RuleBuilder.create(input);
+    this.riskEngine.addRule(rule);
+    return this;
+  }
+  /**
+   * Run risk analysis and return an immutable report.
+   */
+  analyze() {
+    return this.riskEngine.analyze();
+  }
+  /**
+   * Clear all signals. Rules persist across resets.
+   */
+  reset() {
+    this.signalStore.clear();
+    return this;
+  }
+};
+
+export { DEFAULT_RISK_LEVELS, Guardian, RiskEngine, RuleBuilder, RuleEvaluator, ScoreCalculator, SignalStore, resolveLevel };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"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"]}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "guardian-risk",
+  "version": "0.1.0",
+  "description": "Configurable risk decision engine using signals, rules, and scoring",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "risk",
+    "risk-scoring",
+    "rules-engine",
+    "fraud-detection",
+    "bot-detection",
+    "security",
+    "typescript"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}