@fonderie/risk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fonderie, Inc.
+
+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,60 @@
+# @fonderie/risk
+
+A generic **signal → meaning → decision** engine. Assess an action — a trial
+start, a login, a registration, a promo redemption — against weak signals and a
+tunable ruleset, and get back a graded **verdict with reasons**. What to *do*
+with a verdict is your application's call.
+
+> **Decides, never enforces.** The engine is pure and synchronous: it reads
+> signals and returns a verdict. It never calls Stripe, sends an email, or
+> cancels anything. Every side effect — deny, challenge, step-up MFA, revoke,
+> alert — lives in your app, which has the context to do it right. This is what
+> keeps the brick sound and reusable across subjects.
+
+Status: **experimental** (0.x — API may move).
+
+## Use it
+
+```ts
+import { RiskEngine, DEFAULT_RULESETS } from '@fonderie/risk';
+import { getMigrationsPath } from '@fonderie/risk/migrations';
+// run getMigrationsPath()'s SQL with your store's migration runner first.
+
+const risk = new RiskEngine(store, {
+  rulesets: DEFAULT_RULESETS,          // ships a 'trial.start' ruleset; add your own
+  pepper: process.env.RISK_PEPPER,     // required in production
+});
+
+const verdict = await risk.assess('trial.start', {
+  actorId: user.id,
+  identifiers: [                        // hashed by the engine — raw values never stored
+    { kind: 'card', value: cardFingerprint },
+    { kind: 'device', value: deviceId },
+    { kind: 'ip', value: ip },
+    { kind: 'email-domain', value: emailDomain },
+  ],
+  attributes: { accountAgeMinutes, disposableEmail },
+});
+
+// The app maps the verdict to an action — the engine never does.
+if (verdict.tier === 'high')   return deny(verdict.reasons);
+if (verdict.tier === 'medium') return challenge();
+await risk.record(verdict.assessmentId, 'allowed');   // makes the identifiers "seen" next time
+```
+
+## Rulesets are data
+
+A ruleset binds a subject to weighted signals and tier thresholds — move
+weights without a deploy. Signals are `reuse` (identifier seen before),
+`velocity` (count in a window), or `attr` (a fact from the context). See the
+shipped `TRIAL_START_RULESET`.
+
+## What it stores
+
+One `risk_events` table of **hashed** identifiers (sha256 + pepper — never raw),
+with short retention and a hard wall against the analytics pipeline. `assess()`
+writes provisional rows; `record()` promotes them to the real outcome;
+`purgeExpired()` (call on a timer) enforces retention.
+
+Peer-depends on `@fonderie/core` and `@fonderie/store`; imports no other brick.
+See `docs/RISK-BRICK-DESIGN.md` for the full design.

package/brain/outcomes.md

@@ -0,0 +1,27 @@
+<!-- GENERATED — do not edit. Regenerate with: npm run docs:signatures -->
+
+# @fonderie/risk — outcomes
+
+What this package does to a running app: tables its migrations create,
+rows it seeds, routes it registers. Generated from the migration SQL and
+route tables in source — trust this file instead of reading `dist/` or
+downloading tarballs.
+
+## Database tables (after all migrations)
+
+### `risk_events`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+assessment_id            UUID NOT NULL
+subject                  TEXT NOT NULL
+actor_id                 UUID
+signal_kind              TEXT NOT NULL
+value_hash               TEXT NOT NULL
+outcome                  TEXT NOT NULL DEFAULT 'pending' CHECK (outcome IN ('pending', 'allowed', 'challenged', 'blocked'))
+score                    INTEGER
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+expires_at               TIMESTAMPTZ NOT NULL
+```
+
+Raw SQL ships in `node_modules/@fonderie/risk/dist/migrations/sql/` — read it there if you must; never download tarballs.

package/brain/signatures.md

@@ -0,0 +1,103 @@
+<!-- GENERATED — do not edit. Regenerate with: npm run docs:signatures -->
+
+# @fonderie/risk — signatures
+
+## @fonderie/risk
+
+Subpath exports: `@fonderie/risk/migrations`
+
+```ts
+new RiskEngine(store: Queryable, opts: RiskEngineOptions): RiskEngine
+  .assess(subject: string, ctx: RiskContext): Promise<RiskVerdict>
+  .record(assessmentId: string, outcome: RiskOutcome): Promise<void>
+  .purgeExpired(): Promise<void>
+
+function scoreFromFired(rs: RuleSet, fired: Iterable<string>): { score: number; reasons: RiskReason[]; }
+
+interface Queryable {
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+}
+
+const DEFAULT_RULESETS: { [x: string]: RuleSet; }
+
+const TRIAL_START_RULESET: RuleSet
+
+function tierFor(score: number, tiers: { medium: number; high: number; }): RiskTier
+
+function attributeFires(sig: AttributeSignal, attributes: Record<string, string | number | boolean> | undefined): boolean
+
+function validateRuleset(rs: RuleSet): void
+
+function hashValue(pepper: string, kind: string, value: string): string
+
+function ipBucket(ip: string): string
+
+function normalizeForKind(kind: string, value: string): string
+
+function resolvePepper(supplied?: string | undefined): string
+
+interface Identifier {
+    kind: string;
+    value: string;
+}
+
+interface RiskContext {
+    actorId?: string | null;
+    identifiers: Identifier[];
+    attributes?: Record<string, string | number | boolean>;
+}
+
+type RiskTier = 'low' | 'medium' | 'high';
+
+interface RiskReason {
+    signal: string;
+    weight: number;
+}
+
+interface RiskVerdict {
+    score: number;
+    tier: RiskTier;
+    reasons: RiskReason[];
+    assessmentId: string;
+}
+
+type RiskOutcome = 'allowed' | 'challenged' | 'blocked';
+
+interface ReuseSignal {
+    weight: number;
+    reuse: string;
+}
+
+interface VelocitySignal {
+    weight: number;
+    velocity: string;
+    window: string;
+    over: number;
+}
+
+interface AttributeSignal {
+    weight: number;
+    attr: string;
+    under?: number;
+    over?: number;
+    equals?: string | number | boolean;
+}
+
+type RuleSignal = ReuseSignal | VelocitySignal | AttributeSignal;
+
+interface RuleSet {
+    subject: string;
+    signals: Record<string, RuleSignal>;
+    tiers: {
+        medium: number;
+        high: number;
+    };
+}
+
+interface RiskEngineOptions {
+    rulesets: Record<string, RuleSet>;
+    pepper?: string;
+    pendingTtl?: string;
+    recordTtl?: string;
+}
+```

package/dist/index.cjs

@@ -0,0 +1,241 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_RULESETS: () => DEFAULT_RULESETS,
+  RiskEngine: () => RiskEngine,
+  TRIAL_START_RULESET: () => TRIAL_START_RULESET,
+  attributeFires: () => attributeFires,
+  hashValue: () => hashValue,
+  ipBucket: () => ipBucket,
+  normalizeForKind: () => normalizeForKind,
+  resolvePepper: () => resolvePepper,
+  scoreFromFired: () => scoreFromFired,
+  tierFor: () => tierFor,
+  validateRuleset: () => validateRuleset
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/engine.ts
+var import_node_crypto2 = require("crypto");
+
+// src/hashing.ts
+var import_node_crypto = require("crypto");
+var PLACEHOLDER_PEPPERS = /* @__PURE__ */ new Set(["change-me", "dev-pepper", "change-me-long-random-string"]);
+function resolvePepper(supplied) {
+  const p = supplied ?? process.env.RISK_PEPPER;
+  if (p && p.length >= 32 && !PLACEHOLDER_PEPPERS.has(p)) return p;
+  if (process.env.NODE_ENV === "production") {
+    throw new Error(
+      "@fonderie/risk: a unique pepper of >=32 chars is required in production (pass RiskEngine({ pepper }) or set RISK_PEPPER) \u2014 without it the hashed risk_events store is dictionary-attackable offline."
+    );
+  }
+  return "fonderie-risk-dev-pepper-not-for-production";
+}
+function hashValue(pepper, kind, value) {
+  return (0, import_node_crypto.createHash)("sha256").update(`${pepper}\0${kind}\0${value}`).digest("hex");
+}
+function ipBucket(ip) {
+  if (!ip.includes(":")) return ip;
+  const [head] = ip.split("%");
+  const v4Mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(head ?? "");
+  if (v4Mapped) return v4Mapped[1];
+  const groups = (head ?? "").split("::");
+  let left = groups[0] ? groups[0].split(":") : [];
+  const right = groups[1] ? groups[1].split(":") : [];
+  if (groups.length === 2) {
+    const fill = 8 - left.length - right.length;
+    left = [...left, ...Array(Math.max(0, fill)).fill("0"), ...right];
+  }
+  return `${left.slice(0, 4).join(":")}::/64`;
+}
+function normalizeForKind(kind, value) {
+  if (kind === "ip") return ipBucket(value.trim());
+  return value.trim().toLowerCase();
+}
+
+// src/rulesets.ts
+var TRIAL_START_RULESET = {
+  subject: "trial.start",
+  signals: {
+    cardReuse: { weight: 75, reuse: "card" },
+    deviceReuse: { weight: 25, reuse: "device" },
+    signupVelocity: { weight: 30, velocity: "device", window: "1 hour", over: 3 },
+    ipTrials: { weight: 10, velocity: "ip", window: "24 hours", over: 2 },
+    disposableEmail: { weight: 20, attr: "disposableEmail" },
+    freshAccount: { weight: 10, attr: "accountAgeMinutes", under: 10 }
+  },
+  tiers: { medium: 30, high: 70 }
+};
+var DEFAULT_RULESETS = {
+  "trial.start": TRIAL_START_RULESET
+};
+function tierFor(score, tiers) {
+  if (score < tiers.medium) return "low";
+  if (score <= tiers.high) return "medium";
+  return "high";
+}
+function isReuse(s) {
+  return "reuse" in s;
+}
+function isVelocity(s) {
+  return "velocity" in s;
+}
+function isAttr(s) {
+  return "attr" in s;
+}
+var WINDOW_RE = /^\d+\s+(second|minute|hour|day|week|month)s?$/;
+function validateRuleset(rs) {
+  if (!rs.subject) throw new Error("ruleset: missing subject");
+  if (!rs.tiers || typeof rs.tiers.medium !== "number" || typeof rs.tiers.high !== "number")
+    throw new Error(`ruleset ${rs.subject}: tiers.medium and tiers.high are required numbers`);
+  for (const [name, sig] of Object.entries(rs.signals)) {
+    if (typeof sig.weight !== "number" || sig.weight <= 0)
+      throw new Error(`ruleset ${rs.subject}.${name}: weight must be a positive number`);
+    const kinds = [isReuse(sig), isVelocity(sig), isAttr(sig)].filter(Boolean).length;
+    if (kinds !== 1)
+      throw new Error(`ruleset ${rs.subject}.${name}: must be exactly one of reuse/velocity/attr`);
+    if (isVelocity(sig)) {
+      if (!WINDOW_RE.test(sig.window))
+        throw new Error(`ruleset ${rs.subject}.${name}: window "${sig.window}" must be a Postgres interval like "1 hour"`);
+      if (typeof sig.over !== "number")
+        throw new Error(`ruleset ${rs.subject}.${name}: velocity signal needs a numeric "over"`);
+    }
+  }
+}
+function attributeFires(sig, attributes) {
+  const v = attributes?.[sig.attr];
+  if (v === void 0) return false;
+  if (sig.equals !== void 0) return v === sig.equals;
+  if (sig.under !== void 0) return typeof v === "number" && v < sig.under;
+  if (sig.over !== void 0) return typeof v === "number" && v > sig.over;
+  return v === true;
+}
+
+// src/engine.ts
+function scoreFromFired(rs, fired) {
+  let score = 0;
+  const reasons = [];
+  for (const name of fired) {
+    const sig = rs.signals[name];
+    if (!sig) continue;
+    score += sig.weight;
+    reasons.push({ signal: name, weight: sig.weight });
+  }
+  return { score, reasons };
+}
+var RiskEngine = class {
+  constructor(store, opts) {
+    this.store = store;
+    this.rulesets = opts.rulesets;
+    for (const rs of Object.values(this.rulesets)) validateRuleset(rs);
+    this.pepper = resolvePepper(opts.pepper);
+    this.pendingTtl = opts.pendingTtl ?? "24 hours";
+    this.recordTtl = opts.recordTtl ?? "90 days";
+  }
+  store;
+  rulesets;
+  pepper;
+  pendingTtl;
+  recordTtl;
+  async assess(subject, ctx) {
+    const rs = this.rulesets[subject];
+    if (!rs) throw new Error(`@fonderie/risk: no ruleset for subject "${subject}"`);
+    const actorId = ctx.actorId ?? null;
+    const hashes = /* @__PURE__ */ new Map();
+    for (const id of ctx.identifiers) {
+      hashes.set(id.kind, hashValue(this.pepper, id.kind, normalizeForKind(id.kind, id.value)));
+    }
+    const fired = /* @__PURE__ */ new Set();
+    for (const [name, sig] of Object.entries(rs.signals)) {
+      if (isReuse(sig)) {
+        const h = hashes.get(sig.reuse);
+        if (h && await this.reuseSeen(subject, sig.reuse, h, actorId)) fired.add(name);
+      } else if (isVelocity(sig)) {
+        const h = hashes.get(sig.velocity);
+        if (h && await this.velocityCount(subject, sig.velocity, h, sig.window) > sig.over)
+          fired.add(name);
+      } else if (isAttr(sig)) {
+        if (attributeFires(sig, ctx.attributes)) fired.add(name);
+      }
+    }
+    const { score, reasons } = scoreFromFired(rs, fired);
+    const tier = tierFor(score, rs.tiers);
+    const assessmentId = (0, import_node_crypto2.randomUUID)();
+    for (const [kind, h] of hashes) {
+      await this.store.query(
+        `INSERT INTO risk_events
+				   (assessment_id, subject, actor_id, signal_kind, value_hash, outcome, score, expires_at)
+				 VALUES ($1, $2, $3, $4, $5, 'pending', $6, now() + $7::interval)`,
+        [assessmentId, subject, actorId, kind, h, score, this.pendingTtl]
+      );
+    }
+    return { score, tier, reasons, assessmentId };
+  }
+  /** Report what the app actually did; flips this assessment's provisional
+   * rows to the terminal outcome and extends their retention. */
+  async record(assessmentId, outcome) {
+    await this.store.query(
+      `UPDATE risk_events SET outcome = $2, expires_at = now() + $3::interval
+			 WHERE assessment_id = $1 AND outcome = 'pending'`,
+      [assessmentId, outcome, this.recordTtl]
+    );
+  }
+  /** Retention purge — call on a timer, not the request path. */
+  async purgeExpired() {
+    await this.store.query("DELETE FROM risk_events WHERE expires_at < now()");
+  }
+  async reuseSeen(subject, kind, valueHash, actorId) {
+    const rows = await this.store.query(
+      `SELECT 1 FROM risk_events
+			 WHERE subject = $1 AND signal_kind = $2 AND value_hash = $3
+			   AND outcome IN ('pending', 'allowed', 'challenged')
+			   AND ($4::uuid IS NULL OR actor_id IS DISTINCT FROM $4::uuid)
+			 LIMIT 1`,
+      [subject, kind, valueHash, actorId]
+    );
+    return rows.length > 0;
+  }
+  async velocityCount(subject, kind, valueHash, window) {
+    const rows = await this.store.query(
+      `SELECT count(DISTINCT assessment_id)::int AS n FROM risk_events
+			 WHERE subject = $1 AND signal_kind = $2 AND value_hash = $3
+			   AND created_at > now() - $4::interval`,
+      [subject, kind, valueHash, window]
+    );
+    return Number(rows[0]?.n ?? 0);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_RULESETS,
+  RiskEngine,
+  TRIAL_START_RULESET,
+  attributeFires,
+  hashValue,
+  ipBucket,
+  normalizeForKind,
+  resolvePepper,
+  scoreFromFired,
+  tierFor,
+  validateRuleset
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/engine.ts","../src/hashing.ts","../src/rulesets.ts"],"sourcesContent":["// @fonderie/risk — a generic signal → meaning → decision engine.\n//\n// It DECIDES, it never ENFORCES: assess() reads signals and returns a graded\n// verdict with reasons; the application maps that verdict to an action (deny,\n// challenge, step-up MFA, cancel, alert) and owns every external side effect.\n// See docs/RISK-BRICK-DESIGN.md.\n\nexport { RiskEngine, scoreFromFired } from './engine.js';\nexport type { Queryable } from './engine.js';\nexport {\n\tDEFAULT_RULESETS,\n\tTRIAL_START_RULESET,\n\ttierFor,\n\tattributeFires,\n\tvalidateRuleset,\n} from './rulesets.js';\nexport {\n\thashValue,\n\tipBucket,\n\tnormalizeForKind,\n\tresolvePepper,\n} from './hashing.js';\nexport type {\n\tIdentifier,\n\tRiskContext,\n\tRiskTier,\n\tRiskReason,\n\tRiskVerdict,\n\tRiskOutcome,\n\tReuseSignal,\n\tVelocitySignal,\n\tAttributeSignal,\n\tRuleSignal,\n\tRuleSet,\n\tRiskEngineOptions,\n} from './types.js';\n","import { randomUUID } from 'node:crypto';\nimport type {\n\tRiskContext,\n\tRiskEngineOptions,\n\tRiskOutcome,\n\tRiskReason,\n\tRiskVerdict,\n\tRuleSet,\n} from './types.js';\nimport { hashValue, normalizeForKind, resolvePepper } from './hashing.js';\nimport {\n\tattributeFires,\n\tisAttr,\n\tisReuse,\n\tisVelocity,\n\ttierFor,\n\tvalidateRuleset,\n} from './rulesets.js';\n\n/** The engine only ever queries — accept the store adapter or a transaction\n * handle, so it composes into an app's own transaction if wanted. */\nexport interface Queryable {\n\tquery<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;\n}\n\n/** Sum the weights of the fired signals into a score + explainable reasons.\n * Pure — the store-backed gathering happens in assess(); this is unit-testable. */\nexport function scoreFromFired(rs: RuleSet, fired: Iterable<string>): { score: number; reasons: RiskReason[] } {\n\tlet score = 0;\n\tconst reasons: RiskReason[] = [];\n\tfor (const name of fired) {\n\t\tconst sig = rs.signals[name];\n\t\tif (!sig) continue;\n\t\tscore += sig.weight;\n\t\treasons.push({ signal: name, weight: sig.weight });\n\t}\n\treturn { score, reasons };\n}\n\n/**\n * The generic risk engine. `assess()` reads the signal store, scores against a\n * subject's ruleset, and returns a graded verdict — it performs NO external\n * side effect (its only write is provisional 'pending' rows in its own\n * risk_events store, so identifiers become \"seen\" for later assessments).\n * `record()` flips those rows to the real outcome the app carried out.\n */\nexport class RiskEngine {\n\tprivate readonly rulesets: Record<string, RuleSet>;\n\tprivate readonly pepper: string;\n\tprivate readonly pendingTtl: string;\n\tprivate readonly recordTtl: string;\n\n\tconstructor(\n\t\tprivate readonly store: Queryable,\n\t\topts: RiskEngineOptions,\n\t) {\n\t\tthis.rulesets = opts.rulesets;\n\t\tfor (const rs of Object.values(this.rulesets)) validateRuleset(rs);\n\t\tthis.pepper = resolvePepper(opts.pepper);\n\t\tthis.pendingTtl = opts.pendingTtl ?? '24 hours';\n\t\tthis.recordTtl = opts.recordTtl ?? '90 days';\n\t}\n\n\tasync assess(subject: string, ctx: RiskContext): Promise<RiskVerdict> {\n\t\tconst rs = this.rulesets[subject];\n\t\tif (!rs) throw new Error(`@fonderie/risk: no ruleset for subject \"${subject}\"`);\n\n\t\tconst actorId = ctx.actorId ?? null;\n\t\t// Hash every identifier once; last value wins per kind.\n\t\tconst hashes = new Map<string, string>();\n\t\tfor (const id of ctx.identifiers) {\n\t\t\thashes.set(id.kind, hashValue(this.pepper, id.kind, normalizeForKind(id.kind, id.value)));\n\t\t}\n\n\t\tconst fired = new Set<string>();\n\t\tfor (const [name, sig] of Object.entries(rs.signals)) {\n\t\t\tif (isReuse(sig)) {\n\t\t\t\tconst h = hashes.get(sig.reuse);\n\t\t\t\tif (h && (await this.reuseSeen(subject, sig.reuse, h, actorId))) fired.add(name);\n\t\t\t} else if (isVelocity(sig)) {\n\t\t\t\tconst h = hashes.get(sig.velocity);\n\t\t\t\tif (h && (await this.velocityCount(subject, sig.velocity, h, sig.window)) > sig.over)\n\t\t\t\t\tfired.add(name);\n\t\t\t} else if (isAttr(sig)) {\n\t\t\t\tif (attributeFires(sig, ctx.attributes)) fired.add(name);\n\t\t\t}\n\t\t}\n\n\t\tconst { score, reasons } = scoreFromFired(rs, fired);\n\t\tconst tier = tierFor(score, rs.tiers);\n\t\tconst assessmentId = randomUUID();\n\n\t\t// Persist the identifiers as provisional rows so this assessment counts\n\t\t// toward future reuse/velocity. record() promotes them to the real outcome.\n\t\tfor (const [kind, h] of hashes) {\n\t\t\tawait this.store.query(\n\t\t\t\t`INSERT INTO risk_events\n\t\t\t\t   (assessment_id, subject, actor_id, signal_kind, value_hash, outcome, score, expires_at)\n\t\t\t\t VALUES ($1, $2, $3, $4, $5, 'pending', $6, now() + $7::interval)`,\n\t\t\t\t[assessmentId, subject, actorId, kind, h, score, this.pendingTtl],\n\t\t\t);\n\t\t}\n\n\t\treturn { score, tier, reasons, assessmentId };\n\t}\n\n\t/** Report what the app actually did; flips this assessment's provisional\n\t * rows to the terminal outcome and extends their retention. */\n\tasync record(assessmentId: string, outcome: RiskOutcome): Promise<void> {\n\t\tawait this.store.query(\n\t\t\t`UPDATE risk_events SET outcome = $2, expires_at = now() + $3::interval\n\t\t\t WHERE assessment_id = $1 AND outcome = 'pending'`,\n\t\t\t[assessmentId, outcome, this.recordTtl],\n\t\t);\n\t}\n\n\t/** Retention purge — call on a timer, not the request path. */\n\tasync purgeExpired(): Promise<void> {\n\t\tawait this.store.query('DELETE FROM risk_events WHERE expires_at < now()');\n\t}\n\n\tprivate async reuseSeen(\n\t\tsubject: string,\n\t\tkind: string,\n\t\tvalueHash: string,\n\t\tactorId: string | null,\n\t): Promise<boolean> {\n\t\tconst rows = await this.store.query(\n\t\t\t`SELECT 1 FROM risk_events\n\t\t\t WHERE subject = $1 AND signal_kind = $2 AND value_hash = $3\n\t\t\t   AND outcome IN ('pending', 'allowed', 'challenged')\n\t\t\t   AND ($4::uuid IS NULL OR actor_id IS DISTINCT FROM $4::uuid)\n\t\t\t LIMIT 1`,\n\t\t\t[subject, kind, valueHash, actorId],\n\t\t);\n\t\treturn rows.length > 0;\n\t}\n\n\tprivate async velocityCount(\n\t\tsubject: string,\n\t\tkind: string,\n\t\tvalueHash: string,\n\t\twindow: string,\n\t): Promise<number> {\n\t\tconst rows = await this.store.query<{ n: number | string }>(\n\t\t\t`SELECT count(DISTINCT assessment_id)::int AS n FROM risk_events\n\t\t\t WHERE subject = $1 AND signal_kind = $2 AND value_hash = $3\n\t\t\t   AND created_at > now() - $4::interval`,\n\t\t\t[subject, kind, valueHash, window],\n\t\t);\n\t\treturn Number(rows[0]?.n ?? 0);\n\t}\n}\n","// The PII firewall in code: every correlating value is peppered-hashed before\n// it touches the store, and IPs are bucketed so per-address rotation can't\n// evade velocity. Nothing here is ever exported to analytics.\nimport { createHash } from 'node:crypto';\n\nconst PLACEHOLDER_PEPPERS = new Set(['change-me', 'dev-pepper', 'change-me-long-random-string']);\n\n/** Resolve the pepper: a caller-supplied value wins; otherwise fall back to a\n * dev pepper OUTSIDE production and throw INSIDE it (a leaked store must not be\n * dictionary-attackable). */\nexport function resolvePepper(supplied?: string): string {\n\tconst p = supplied ?? process.env.RISK_PEPPER;\n\tif (p && p.length >= 32 && !PLACEHOLDER_PEPPERS.has(p)) return p;\n\tif (process.env.NODE_ENV === 'production') {\n\t\tthrow new Error(\n\t\t\t'@fonderie/risk: a unique pepper of >=32 chars is required in production ' +\n\t\t\t\t'(pass RiskEngine({ pepper }) or set RISK_PEPPER) — without it the hashed ' +\n\t\t\t\t'risk_events store is dictionary-attackable offline.',\n\t\t);\n\t}\n\treturn 'fonderie-risk-dev-pepper-not-for-production';\n}\n\n/** sha256(pepper ‖ kind ‖ value) — domain-separated so a card hash can never\n * collide with an ip hash, peppered so a leaked table can't be reversed by\n * hashing candidate values. */\nexport function hashValue(pepper: string, kind: string, value: string): string {\n\treturn createHash('sha256').update(`${pepper}\\0${kind}\\0${value}`).digest('hex');\n}\n\n/** IPv6 collapses to its /64 (the customary end-site prefix — the low 64 bits\n * rotate freely and would defeat per-address velocity); IPv4-mapped IPv6\n * resolves to its embedded IPv4; IPv4 passes through whole. */\nexport function ipBucket(ip: string): string {\n\tif (!ip.includes(':')) return ip;\n\tconst [head] = ip.split('%');\n\tconst v4Mapped = /^::ffff:(\\d{1,3}(?:\\.\\d{1,3}){3})$/i.exec(head ?? '');\n\tif (v4Mapped) return v4Mapped[1] as string;\n\tconst groups = (head ?? '').split('::');\n\tlet left = groups[0] ? groups[0].split(':') : [];\n\tconst right = groups[1] ? groups[1].split(':') : [];\n\tif (groups.length === 2) {\n\t\tconst fill = 8 - left.length - right.length;\n\t\tleft = [...left, ...Array<string>(Math.max(0, fill)).fill('0'), ...right];\n\t}\n\treturn `${left.slice(0, 4).join(':')}::/64`;\n}\n\n/** Normalize a value for hashing by kind: IPs are bucketed, everything else is\n * lower-cased/trimmed so trivial spelling differences collapse. */\nexport function normalizeForKind(kind: string, value: string): string {\n\tif (kind === 'ip') return ipBucket(value.trim());\n\treturn value.trim().toLowerCase();\n}\n","// Rulesets are DATA: weights, windows, and thresholds move without a deploy.\n// The launch ruleset (trial.start) is the trial-abuse scorer, generalized —\n// the app that consumes it maps tiers to actions (the engine never does).\nimport type { RuleSet, RuleSignal, RiskTier } from './types.js';\n\n/** The reference trial-abuse ruleset. Card reuse alone is 'high' (75 > 70):\n * one free trial per physical card. Weights are illustrative and tunable. */\nexport const TRIAL_START_RULESET: RuleSet = {\n\tsubject: 'trial.start',\n\tsignals: {\n\t\tcardReuse: { weight: 75, reuse: 'card' },\n\t\tdeviceReuse: { weight: 25, reuse: 'device' },\n\t\tsignupVelocity: { weight: 30, velocity: 'device', window: '1 hour', over: 3 },\n\t\tipTrials: { weight: 10, velocity: 'ip', window: '24 hours', over: 2 },\n\t\tdisposableEmail: { weight: 20, attr: 'disposableEmail' },\n\t\tfreshAccount: { weight: 10, attr: 'accountAgeMinutes', under: 10 },\n\t},\n\ttiers: { medium: 30, high: 70 },\n};\n\n/** The default ruleset map. Apps pass their own (merged) map to RiskEngine. */\nexport const DEFAULT_RULESETS: Record<string, RuleSet> = {\n\t'trial.start': TRIAL_START_RULESET,\n};\n\n/** `< medium` → low, `<= high` → medium, else high. */\nexport function tierFor(score: number, tiers: RuleSet['tiers']): RiskTier {\n\tif (score < tiers.medium) return 'low';\n\tif (score <= tiers.high) return 'medium';\n\treturn 'high';\n}\n\nfunction isReuse(s: RuleSignal): s is Extract<RuleSignal, { reuse: string }> {\n\treturn 'reuse' in s;\n}\nfunction isVelocity(s: RuleSignal): s is Extract<RuleSignal, { velocity: string }> {\n\treturn 'velocity' in s;\n}\nfunction isAttr(s: RuleSignal): s is Extract<RuleSignal, { attr: string }> {\n\treturn 'attr' in s;\n}\n\nconst WINDOW_RE = /^\\d+\\s+(second|minute|hour|day|week|month)s?$/;\n\n/** Fail fast on a malformed ruleset — a bad window would otherwise reach SQL,\n * and a non-positive weight is almost always a typo. */\nexport function validateRuleset(rs: RuleSet): void {\n\tif (!rs.subject) throw new Error('ruleset: missing subject');\n\tif (!rs.tiers || typeof rs.tiers.medium !== 'number' || typeof rs.tiers.high !== 'number')\n\t\tthrow new Error(`ruleset ${rs.subject}: tiers.medium and tiers.high are required numbers`);\n\tfor (const [name, sig] of Object.entries(rs.signals)) {\n\t\tif (typeof sig.weight !== 'number' || sig.weight <= 0)\n\t\t\tthrow new Error(`ruleset ${rs.subject}.${name}: weight must be a positive number`);\n\t\tconst kinds = [isReuse(sig), isVelocity(sig), isAttr(sig)].filter(Boolean).length;\n\t\tif (kinds !== 1)\n\t\t\tthrow new Error(`ruleset ${rs.subject}.${name}: must be exactly one of reuse/velocity/attr`);\n\t\tif (isVelocity(sig)) {\n\t\t\tif (!WINDOW_RE.test(sig.window))\n\t\t\t\tthrow new Error(`ruleset ${rs.subject}.${name}: window \"${sig.window}\" must be a Postgres interval like \"1 hour\"`);\n\t\t\tif (typeof sig.over !== 'number')\n\t\t\t\tthrow new Error(`ruleset ${rs.subject}.${name}: velocity signal needs a numeric \"over\"`);\n\t\t}\n\t}\n}\n\n/** Does an attribute signal fire against this context's attributes? Pure. */\nexport function attributeFires(\n\tsig: Extract<RuleSignal, { attr: string }>,\n\tattributes: Record<string, string | number | boolean> | undefined,\n): boolean {\n\tconst v = attributes?.[sig.attr];\n\tif (v === undefined) return false;\n\tif (sig.equals !== undefined) return v === sig.equals;\n\tif (sig.under !== undefined) return typeof v === 'number' && v < sig.under;\n\tif (sig.over !== undefined) return typeof v === 'number' && v > sig.over;\n\treturn v === true; // bare boolean attribute\n}\n\nexport { isReuse, isVelocity, isAttr };\n"],"mappings":"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","names":["import_node_crypto"]}

package/dist/index.d.cts

@@ -0,0 +1,146 @@
+/** A correlating value the engine may reason about. Hashed on the way in;
+ * the raw value never touches the store. `kind` is an open set — 'card', 'ip',
+ * 'device', 'email-domain', or anything an app defines. */
+interface Identifier {
+    kind: string;
+    value: string;
+}
+/** The evidence bag for one assessment. */
+interface RiskContext {
+    /** The assessed principal, when known (a user id at login/trial). Used to
+     * exclude an actor's own prior events from "reuse". */
+    actorId?: string | null;
+    /** Correlating identifiers; hashed by the engine before storage/lookup. */
+    identifiers: Identifier[];
+    /** Non-correlating facts a ruleset's attribute signals read (e.g.
+     * accountAgeMinutes, disposableEmail). */
+    attributes?: Record<string, string | number | boolean>;
+}
+type RiskTier = 'low' | 'medium' | 'high';
+/** One weighted reason a verdict scored as it did — explainable, for logs and
+ * appeals. */
+interface RiskReason {
+    signal: string;
+    weight: number;
+}
+interface RiskVerdict {
+    score: number;
+    tier: RiskTier;
+    reasons: RiskReason[];
+    /** Correlates the later record() call to this assessment's stored rows. */
+    assessmentId: string;
+}
+/** The outcome an app reports back via record() — what it actually did. */
+type RiskOutcome = 'allowed' | 'challenged' | 'blocked';
+/** Fires when this identifier kind was seen in a prior (non-blocked)
+ * assessment of the same subject by a different actor. */
+interface ReuseSignal {
+    weight: number;
+    reuse: string;
+}
+/** Fires when the count of distinct assessments for this identifier kind within
+ * `window` exceeds `over`. `window` is a Postgres interval string ('1 hour'). */
+interface VelocitySignal {
+    weight: number;
+    velocity: string;
+    window: string;
+    over: number;
+}
+/** Fires from a ctx attribute: `under`/`over` compare a number; `equals`
+ * compares any value; with none, a truthy attribute fires. */
+interface AttributeSignal {
+    weight: number;
+    attr: string;
+    under?: number;
+    over?: number;
+    equals?: string | number | boolean;
+}
+type RuleSignal = ReuseSignal | VelocitySignal | AttributeSignal;
+interface RuleSet {
+    subject: string;
+    signals: Record<string, RuleSignal>;
+    /** Score thresholds: `< medium` → low, `<= high` → medium, else high. */
+    tiers: {
+        medium: number;
+        high: number;
+    };
+}
+interface RiskEngineOptions {
+    /** Ruleset per subject. Data, not code — tune weights without a deploy. */
+    rulesets: Record<string, RuleSet>;
+    /** HMAC pepper for identifier hashes. REQUIRED in production; a leaked
+     * store is dictionary-attackable without it. */
+    pepper?: string;
+    /** TTL for provisional ('pending') assessment rows (Postgres interval). */
+    pendingTtl?: string;
+    /** TTL for recorded (terminal-outcome) rows (Postgres interval). */
+    recordTtl?: string;
+}
+
+/** The engine only ever queries — accept the store adapter or a transaction
+ * handle, so it composes into an app's own transaction if wanted. */
+interface Queryable {
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+}
+/** Sum the weights of the fired signals into a score + explainable reasons.
+ * Pure — the store-backed gathering happens in assess(); this is unit-testable. */
+declare function scoreFromFired(rs: RuleSet, fired: Iterable<string>): {
+    score: number;
+    reasons: RiskReason[];
+};
+/**
+ * The generic risk engine. `assess()` reads the signal store, scores against a
+ * subject's ruleset, and returns a graded verdict — it performs NO external
+ * side effect (its only write is provisional 'pending' rows in its own
+ * risk_events store, so identifiers become "seen" for later assessments).
+ * `record()` flips those rows to the real outcome the app carried out.
+ */
+declare class RiskEngine {
+    private readonly store;
+    private readonly rulesets;
+    private readonly pepper;
+    private readonly pendingTtl;
+    private readonly recordTtl;
+    constructor(store: Queryable, opts: RiskEngineOptions);
+    assess(subject: string, ctx: RiskContext): Promise<RiskVerdict>;
+    /** Report what the app actually did; flips this assessment's provisional
+     * rows to the terminal outcome and extends their retention. */
+    record(assessmentId: string, outcome: RiskOutcome): Promise<void>;
+    /** Retention purge — call on a timer, not the request path. */
+    purgeExpired(): Promise<void>;
+    private reuseSeen;
+    private velocityCount;
+}
+
+/** The reference trial-abuse ruleset. Card reuse alone is 'high' (75 > 70):
+ * one free trial per physical card. Weights are illustrative and tunable. */
+declare const TRIAL_START_RULESET: RuleSet;
+/** The default ruleset map. Apps pass their own (merged) map to RiskEngine. */
+declare const DEFAULT_RULESETS: Record<string, RuleSet>;
+/** `< medium` → low, `<= high` → medium, else high. */
+declare function tierFor(score: number, tiers: RuleSet['tiers']): RiskTier;
+/** Fail fast on a malformed ruleset — a bad window would otherwise reach SQL,
+ * and a non-positive weight is almost always a typo. */
+declare function validateRuleset(rs: RuleSet): void;
+/** Does an attribute signal fire against this context's attributes? Pure. */
+declare function attributeFires(sig: Extract<RuleSignal, {
+    attr: string;
+}>, attributes: Record<string, string | number | boolean> | undefined): boolean;
+
+/** Resolve the pepper: a caller-supplied value wins; otherwise fall back to a
+ * dev pepper OUTSIDE production and throw INSIDE it (a leaked store must not be
+ * dictionary-attackable). */
+declare function resolvePepper(supplied?: string): string;
+/** sha256(pepper ‖ kind ‖ value) — domain-separated so a card hash can never
+ * collide with an ip hash, peppered so a leaked table can't be reversed by
+ * hashing candidate values. */
+declare function hashValue(pepper: string, kind: string, value: string): string;
+/** IPv6 collapses to its /64 (the customary end-site prefix — the low 64 bits
+ * rotate freely and would defeat per-address velocity); IPv4-mapped IPv6
+ * resolves to its embedded IPv4; IPv4 passes through whole. */
+declare function ipBucket(ip: string): string;
+/** Normalize a value for hashing by kind: IPs are bucketed, everything else is
+ * lower-cased/trimmed so trivial spelling differences collapse. */
+declare function normalizeForKind(kind: string, value: string): string;
+
+export { type AttributeSignal, DEFAULT_RULESETS, type Identifier, type Queryable, type ReuseSignal, type RiskContext, RiskEngine, type RiskEngineOptions, type RiskOutcome, type RiskReason, type RiskTier, type RiskVerdict, type RuleSet, type RuleSignal, TRIAL_START_RULESET, type VelocitySignal, attributeFires, hashValue, ipBucket, normalizeForKind, resolvePepper, scoreFromFired, tierFor, validateRuleset };

package/dist/index.d.ts

@@ -0,0 +1,146 @@
+/** A correlating value the engine may reason about. Hashed on the way in;
+ * the raw value never touches the store. `kind` is an open set — 'card', 'ip',
+ * 'device', 'email-domain', or anything an app defines. */
+interface Identifier {
+    kind: string;
+    value: string;
+}
+/** The evidence bag for one assessment. */
+interface RiskContext {
+    /** The assessed principal, when known (a user id at login/trial). Used to
+     * exclude an actor's own prior events from "reuse". */
+    actorId?: string | null;
+    /** Correlating identifiers; hashed by the engine before storage/lookup. */
+    identifiers: Identifier[];
+    /** Non-correlating facts a ruleset's attribute signals read (e.g.
+     * accountAgeMinutes, disposableEmail). */
+    attributes?: Record<string, string | number | boolean>;
+}
+type RiskTier = 'low' | 'medium' | 'high';
+/** One weighted reason a verdict scored as it did — explainable, for logs and
+ * appeals. */
+interface RiskReason {
+    signal: string;
+    weight: number;
+}
+interface RiskVerdict {
+    score: number;
+    tier: RiskTier;
+    reasons: RiskReason[];
+    /** Correlates the later record() call to this assessment's stored rows. */
+    assessmentId: string;
+}
+/** The outcome an app reports back via record() — what it actually did. */
+type RiskOutcome = 'allowed' | 'challenged' | 'blocked';
+/** Fires when this identifier kind was seen in a prior (non-blocked)
+ * assessment of the same subject by a different actor. */
+interface ReuseSignal {
+    weight: number;
+    reuse: string;
+}
+/** Fires when the count of distinct assessments for this identifier kind within
+ * `window` exceeds `over`. `window` is a Postgres interval string ('1 hour'). */
+interface VelocitySignal {
+    weight: number;
+    velocity: string;
+    window: string;
+    over: number;
+}
+/** Fires from a ctx attribute: `under`/`over` compare a number; `equals`
+ * compares any value; with none, a truthy attribute fires. */
+interface AttributeSignal {
+    weight: number;
+    attr: string;
+    under?: number;
+    over?: number;
+    equals?: string | number | boolean;
+}
+type RuleSignal = ReuseSignal | VelocitySignal | AttributeSignal;
+interface RuleSet {
+    subject: string;
+    signals: Record<string, RuleSignal>;
+    /** Score thresholds: `< medium` → low, `<= high` → medium, else high. */
+    tiers: {
+        medium: number;
+        high: number;
+    };
+}
+interface RiskEngineOptions {
+    /** Ruleset per subject. Data, not code — tune weights without a deploy. */
+    rulesets: Record<string, RuleSet>;
+    /** HMAC pepper for identifier hashes. REQUIRED in production; a leaked
+     * store is dictionary-attackable without it. */
+    pepper?: string;
+    /** TTL for provisional ('pending') assessment rows (Postgres interval). */
+    pendingTtl?: string;
+    /** TTL for recorded (terminal-outcome) rows (Postgres interval). */
+    recordTtl?: string;
+}
+
+/** The engine only ever queries — accept the store adapter or a transaction
+ * handle, so it composes into an app's own transaction if wanted. */
+interface Queryable {
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+}
+/** Sum the weights of the fired signals into a score + explainable reasons.
+ * Pure — the store-backed gathering happens in assess(); this is unit-testable. */
+declare function scoreFromFired(rs: RuleSet, fired: Iterable<string>): {
+    score: number;
+    reasons: RiskReason[];
+};
+/**
+ * The generic risk engine. `assess()` reads the signal store, scores against a
+ * subject's ruleset, and returns a graded verdict — it performs NO external
+ * side effect (its only write is provisional 'pending' rows in its own
+ * risk_events store, so identifiers become "seen" for later assessments).
+ * `record()` flips those rows to the real outcome the app carried out.
+ */
+declare class RiskEngine {
+    private readonly store;
+    private readonly rulesets;
+    private readonly pepper;
+    private readonly pendingTtl;
+    private readonly recordTtl;
+    constructor(store: Queryable, opts: RiskEngineOptions);
+    assess(subject: string, ctx: RiskContext): Promise<RiskVerdict>;
+    /** Report what the app actually did; flips this assessment's provisional
+     * rows to the terminal outcome and extends their retention. */
+    record(assessmentId: string, outcome: RiskOutcome): Promise<void>;
+    /** Retention purge — call on a timer, not the request path. */
+    purgeExpired(): Promise<void>;
+    private reuseSeen;
+    private velocityCount;
+}
+
+/** The reference trial-abuse ruleset. Card reuse alone is 'high' (75 > 70):
+ * one free trial per physical card. Weights are illustrative and tunable. */
+declare const TRIAL_START_RULESET: RuleSet;
+/** The default ruleset map. Apps pass their own (merged) map to RiskEngine. */
+declare const DEFAULT_RULESETS: Record<string, RuleSet>;
+/** `< medium` → low, `<= high` → medium, else high. */
+declare function tierFor(score: number, tiers: RuleSet['tiers']): RiskTier;
+/** Fail fast on a malformed ruleset — a bad window would otherwise reach SQL,
+ * and a non-positive weight is almost always a typo. */
+declare function validateRuleset(rs: RuleSet): void;
+/** Does an attribute signal fire against this context's attributes? Pure. */
+declare function attributeFires(sig: Extract<RuleSignal, {
+    attr: string;
+}>, attributes: Record<string, string | number | boolean> | undefined): boolean;
+
+/** Resolve the pepper: a caller-supplied value wins; otherwise fall back to a
+ * dev pepper OUTSIDE production and throw INSIDE it (a leaked store must not be
+ * dictionary-attackable). */
+declare function resolvePepper(supplied?: string): string;
+/** sha256(pepper ‖ kind ‖ value) — domain-separated so a card hash can never
+ * collide with an ip hash, peppered so a leaked table can't be reversed by
+ * hashing candidate values. */
+declare function hashValue(pepper: string, kind: string, value: string): string;
+/** IPv6 collapses to its /64 (the customary end-site prefix — the low 64 bits
+ * rotate freely and would defeat per-address velocity); IPv4-mapped IPv6
+ * resolves to its embedded IPv4; IPv4 passes through whole. */
+declare function ipBucket(ip: string): string;
+/** Normalize a value for hashing by kind: IPs are bucketed, everything else is
+ * lower-cased/trimmed so trivial spelling differences collapse. */
+declare function normalizeForKind(kind: string, value: string): string;
+
+export { type AttributeSignal, DEFAULT_RULESETS, type Identifier, type Queryable, type ReuseSignal, type RiskContext, RiskEngine, type RiskEngineOptions, type RiskOutcome, type RiskReason, type RiskTier, type RiskVerdict, type RuleSet, type RuleSignal, TRIAL_START_RULESET, type VelocitySignal, attributeFires, hashValue, ipBucket, normalizeForKind, resolvePepper, scoreFromFired, tierFor, validateRuleset };

package/dist/index.js

@@ -0,0 +1,204 @@
+// src/engine.ts
+import { randomUUID } from "crypto";
+
+// src/hashing.ts
+import { createHash } from "crypto";
+var PLACEHOLDER_PEPPERS = /* @__PURE__ */ new Set(["change-me", "dev-pepper", "change-me-long-random-string"]);
+function resolvePepper(supplied) {
+  const p = supplied ?? process.env.RISK_PEPPER;
+  if (p && p.length >= 32 && !PLACEHOLDER_PEPPERS.has(p)) return p;
+  if (process.env.NODE_ENV === "production") {
+    throw new Error(
+      "@fonderie/risk: a unique pepper of >=32 chars is required in production (pass RiskEngine({ pepper }) or set RISK_PEPPER) \u2014 without it the hashed risk_events store is dictionary-attackable offline."
+    );
+  }
+  return "fonderie-risk-dev-pepper-not-for-production";
+}
+function hashValue(pepper, kind, value) {
+  return createHash("sha256").update(`${pepper}\0${kind}\0${value}`).digest("hex");
+}
+function ipBucket(ip) {
+  if (!ip.includes(":")) return ip;
+  const [head] = ip.split("%");
+  const v4Mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(head ?? "");
+  if (v4Mapped) return v4Mapped[1];
+  const groups = (head ?? "").split("::");
+  let left = groups[0] ? groups[0].split(":") : [];
+  const right = groups[1] ? groups[1].split(":") : [];
+  if (groups.length === 2) {
+    const fill = 8 - left.length - right.length;
+    left = [...left, ...Array(Math.max(0, fill)).fill("0"), ...right];
+  }
+  return `${left.slice(0, 4).join(":")}::/64`;
+}
+function normalizeForKind(kind, value) {
+  if (kind === "ip") return ipBucket(value.trim());
+  return value.trim().toLowerCase();
+}
+
+// src/rulesets.ts
+var TRIAL_START_RULESET = {
+  subject: "trial.start",
+  signals: {
+    cardReuse: { weight: 75, reuse: "card" },
+    deviceReuse: { weight: 25, reuse: "device" },
+    signupVelocity: { weight: 30, velocity: "device", window: "1 hour", over: 3 },
+    ipTrials: { weight: 10, velocity: "ip", window: "24 hours", over: 2 },
+    disposableEmail: { weight: 20, attr: "disposableEmail" },
+    freshAccount: { weight: 10, attr: "accountAgeMinutes", under: 10 }
+  },
+  tiers: { medium: 30, high: 70 }
+};
+var DEFAULT_RULESETS = {
+  "trial.start": TRIAL_START_RULESET
+};
+function tierFor(score, tiers) {
+  if (score < tiers.medium) return "low";
+  if (score <= tiers.high) return "medium";
+  return "high";
+}
+function isReuse(s) {
+  return "reuse" in s;
+}
+function isVelocity(s) {
+  return "velocity" in s;
+}
+function isAttr(s) {
+  return "attr" in s;
+}
+var WINDOW_RE = /^\d+\s+(second|minute|hour|day|week|month)s?$/;
+function validateRuleset(rs) {
+  if (!rs.subject) throw new Error("ruleset: missing subject");
+  if (!rs.tiers || typeof rs.tiers.medium !== "number" || typeof rs.tiers.high !== "number")
+    throw new Error(`ruleset ${rs.subject}: tiers.medium and tiers.high are required numbers`);
+  for (const [name, sig] of Object.entries(rs.signals)) {
+    if (typeof sig.weight !== "number" || sig.weight <= 0)
+      throw new Error(`ruleset ${rs.subject}.${name}: weight must be a positive number`);
+    const kinds = [isReuse(sig), isVelocity(sig), isAttr(sig)].filter(Boolean).length;
+    if (kinds !== 1)
+      throw new Error(`ruleset ${rs.subject}.${name}: must be exactly one of reuse/velocity/attr`);
+    if (isVelocity(sig)) {
+      if (!WINDOW_RE.test(sig.window))
+        throw new Error(`ruleset ${rs.subject}.${name}: window "${sig.window}" must be a Postgres interval like "1 hour"`);
+      if (typeof sig.over !== "number")
+        throw new Error(`ruleset ${rs.subject}.${name}: velocity signal needs a numeric "over"`);
+    }
+  }
+}
+function attributeFires(sig, attributes) {
+  const v = attributes?.[sig.attr];
+  if (v === void 0) return false;
+  if (sig.equals !== void 0) return v === sig.equals;
+  if (sig.under !== void 0) return typeof v === "number" && v < sig.under;
+  if (sig.over !== void 0) return typeof v === "number" && v > sig.over;
+  return v === true;
+}
+
+// src/engine.ts
+function scoreFromFired(rs, fired) {
+  let score = 0;
+  const reasons = [];
+  for (const name of fired) {
+    const sig = rs.signals[name];
+    if (!sig) continue;
+    score += sig.weight;
+    reasons.push({ signal: name, weight: sig.weight });
+  }
+  return { score, reasons };
+}
+var RiskEngine = class {
+  constructor(store, opts) {
+    this.store = store;
+    this.rulesets = opts.rulesets;
+    for (const rs of Object.values(this.rulesets)) validateRuleset(rs);
+    this.pepper = resolvePepper(opts.pepper);
+    this.pendingTtl = opts.pendingTtl ?? "24 hours";
+    this.recordTtl = opts.recordTtl ?? "90 days";
+  }
+  store;
+  rulesets;
+  pepper;
+  pendingTtl;
+  recordTtl;
+  async assess(subject, ctx) {
+    const rs = this.rulesets[subject];
+    if (!rs) throw new Error(`@fonderie/risk: no ruleset for subject "${subject}"`);
+    const actorId = ctx.actorId ?? null;
+    const hashes = /* @__PURE__ */ new Map();
+    for (const id of ctx.identifiers) {
+      hashes.set(id.kind, hashValue(this.pepper, id.kind, normalizeForKind(id.kind, id.value)));
+    }
+    const fired = /* @__PURE__ */ new Set();
+    for (const [name, sig] of Object.entries(rs.signals)) {
+      if (isReuse(sig)) {
+        const h = hashes.get(sig.reuse);
+        if (h && await this.reuseSeen(subject, sig.reuse, h, actorId)) fired.add(name);
+      } else if (isVelocity(sig)) {
+        const h = hashes.get(sig.velocity);
+        if (h && await this.velocityCount(subject, sig.velocity, h, sig.window) > sig.over)
+          fired.add(name);
+      } else if (isAttr(sig)) {
+        if (attributeFires(sig, ctx.attributes)) fired.add(name);
+      }
+    }
+    const { score, reasons } = scoreFromFired(rs, fired);
+    const tier = tierFor(score, rs.tiers);
+    const assessmentId = randomUUID();
+    for (const [kind, h] of hashes) {
+      await this.store.query(
+        `INSERT INTO risk_events
+				   (assessment_id, subject, actor_id, signal_kind, value_hash, outcome, score, expires_at)
+				 VALUES ($1, $2, $3, $4, $5, 'pending', $6, now() + $7::interval)`,
+        [assessmentId, subject, actorId, kind, h, score, this.pendingTtl]
+      );
+    }
+    return { score, tier, reasons, assessmentId };
+  }
+  /** Report what the app actually did; flips this assessment's provisional
+   * rows to the terminal outcome and extends their retention. */
+  async record(assessmentId, outcome) {
+    await this.store.query(
+      `UPDATE risk_events SET outcome = $2, expires_at = now() + $3::interval
+			 WHERE assessment_id = $1 AND outcome = 'pending'`,
+      [assessmentId, outcome, this.recordTtl]
+    );
+  }
+  /** Retention purge — call on a timer, not the request path. */
+  async purgeExpired() {
+    await this.store.query("DELETE FROM risk_events WHERE expires_at < now()");
+  }
+  async reuseSeen(subject, kind, valueHash, actorId) {
+    const rows = await this.store.query(
+      `SELECT 1 FROM risk_events
+			 WHERE subject = $1 AND signal_kind = $2 AND value_hash = $3
+			   AND outcome IN ('pending', 'allowed', 'challenged')
+			   AND ($4::uuid IS NULL OR actor_id IS DISTINCT FROM $4::uuid)
+			 LIMIT 1`,
+      [subject, kind, valueHash, actorId]
+    );
+    return rows.length > 0;
+  }
+  async velocityCount(subject, kind, valueHash, window) {
+    const rows = await this.store.query(
+      `SELECT count(DISTINCT assessment_id)::int AS n FROM risk_events
+			 WHERE subject = $1 AND signal_kind = $2 AND value_hash = $3
+			   AND created_at > now() - $4::interval`,
+      [subject, kind, valueHash, window]
+    );
+    return Number(rows[0]?.n ?? 0);
+  }
+};
+export {
+  DEFAULT_RULESETS,
+  RiskEngine,
+  TRIAL_START_RULESET,
+  attributeFires,
+  hashValue,
+  ipBucket,
+  normalizeForKind,
+  resolvePepper,
+  scoreFromFired,
+  tierFor,
+  validateRuleset
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/engine.ts","../src/hashing.ts","../src/rulesets.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\nimport type {\n\tRiskContext,\n\tRiskEngineOptions,\n\tRiskOutcome,\n\tRiskReason,\n\tRiskVerdict,\n\tRuleSet,\n} from './types.js';\nimport { hashValue, normalizeForKind, resolvePepper } from './hashing.js';\nimport {\n\tattributeFires,\n\tisAttr,\n\tisReuse,\n\tisVelocity,\n\ttierFor,\n\tvalidateRuleset,\n} from './rulesets.js';\n\n/** The engine only ever queries — accept the store adapter or a transaction\n * handle, so it composes into an app's own transaction if wanted. */\nexport interface Queryable {\n\tquery<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;\n}\n\n/** Sum the weights of the fired signals into a score + explainable reasons.\n * Pure — the store-backed gathering happens in assess(); this is unit-testable. */\nexport function scoreFromFired(rs: RuleSet, fired: Iterable<string>): { score: number; reasons: RiskReason[] } {\n\tlet score = 0;\n\tconst reasons: RiskReason[] = [];\n\tfor (const name of fired) {\n\t\tconst sig = rs.signals[name];\n\t\tif (!sig) continue;\n\t\tscore += sig.weight;\n\t\treasons.push({ signal: name, weight: sig.weight });\n\t}\n\treturn { score, reasons };\n}\n\n/**\n * The generic risk engine. `assess()` reads the signal store, scores against a\n * subject's ruleset, and returns a graded verdict — it performs NO external\n * side effect (its only write is provisional 'pending' rows in its own\n * risk_events store, so identifiers become \"seen\" for later assessments).\n * `record()` flips those rows to the real outcome the app carried out.\n */\nexport class RiskEngine {\n\tprivate readonly rulesets: Record<string, RuleSet>;\n\tprivate readonly pepper: string;\n\tprivate readonly pendingTtl: string;\n\tprivate readonly recordTtl: string;\n\n\tconstructor(\n\t\tprivate readonly store: Queryable,\n\t\topts: RiskEngineOptions,\n\t) {\n\t\tthis.rulesets = opts.rulesets;\n\t\tfor (const rs of Object.values(this.rulesets)) validateRuleset(rs);\n\t\tthis.pepper = resolvePepper(opts.pepper);\n\t\tthis.pendingTtl = opts.pendingTtl ?? '24 hours';\n\t\tthis.recordTtl = opts.recordTtl ?? '90 days';\n\t}\n\n\tasync assess(subject: string, ctx: RiskContext): Promise<RiskVerdict> {\n\t\tconst rs = this.rulesets[subject];\n\t\tif (!rs) throw new Error(`@fonderie/risk: no ruleset for subject \"${subject}\"`);\n\n\t\tconst actorId = ctx.actorId ?? null;\n\t\t// Hash every identifier once; last value wins per kind.\n\t\tconst hashes = new Map<string, string>();\n\t\tfor (const id of ctx.identifiers) {\n\t\t\thashes.set(id.kind, hashValue(this.pepper, id.kind, normalizeForKind(id.kind, id.value)));\n\t\t}\n\n\t\tconst fired = new Set<string>();\n\t\tfor (const [name, sig] of Object.entries(rs.signals)) {\n\t\t\tif (isReuse(sig)) {\n\t\t\t\tconst h = hashes.get(sig.reuse);\n\t\t\t\tif (h && (await this.reuseSeen(subject, sig.reuse, h, actorId))) fired.add(name);\n\t\t\t} else if (isVelocity(sig)) {\n\t\t\t\tconst h = hashes.get(sig.velocity);\n\t\t\t\tif (h && (await this.velocityCount(subject, sig.velocity, h, sig.window)) > sig.over)\n\t\t\t\t\tfired.add(name);\n\t\t\t} else if (isAttr(sig)) {\n\t\t\t\tif (attributeFires(sig, ctx.attributes)) fired.add(name);\n\t\t\t}\n\t\t}\n\n\t\tconst { score, reasons } = scoreFromFired(rs, fired);\n\t\tconst tier = tierFor(score, rs.tiers);\n\t\tconst assessmentId = randomUUID();\n\n\t\t// Persist the identifiers as provisional rows so this assessment counts\n\t\t// toward future reuse/velocity. record() promotes them to the real outcome.\n\t\tfor (const [kind, h] of hashes) {\n\t\t\tawait this.store.query(\n\t\t\t\t`INSERT INTO risk_events\n\t\t\t\t   (assessment_id, subject, actor_id, signal_kind, value_hash, outcome, score, expires_at)\n\t\t\t\t VALUES ($1, $2, $3, $4, $5, 'pending', $6, now() + $7::interval)`,\n\t\t\t\t[assessmentId, subject, actorId, kind, h, score, this.pendingTtl],\n\t\t\t);\n\t\t}\n\n\t\treturn { score, tier, reasons, assessmentId };\n\t}\n\n\t/** Report what the app actually did; flips this assessment's provisional\n\t * rows to the terminal outcome and extends their retention. */\n\tasync record(assessmentId: string, outcome: RiskOutcome): Promise<void> {\n\t\tawait this.store.query(\n\t\t\t`UPDATE risk_events SET outcome = $2, expires_at = now() + $3::interval\n\t\t\t WHERE assessment_id = $1 AND outcome = 'pending'`,\n\t\t\t[assessmentId, outcome, this.recordTtl],\n\t\t);\n\t}\n\n\t/** Retention purge — call on a timer, not the request path. */\n\tasync purgeExpired(): Promise<void> {\n\t\tawait this.store.query('DELETE FROM risk_events WHERE expires_at < now()');\n\t}\n\n\tprivate async reuseSeen(\n\t\tsubject: string,\n\t\tkind: string,\n\t\tvalueHash: string,\n\t\tactorId: string | null,\n\t): Promise<boolean> {\n\t\tconst rows = await this.store.query(\n\t\t\t`SELECT 1 FROM risk_events\n\t\t\t WHERE subject = $1 AND signal_kind = $2 AND value_hash = $3\n\t\t\t   AND outcome IN ('pending', 'allowed', 'challenged')\n\t\t\t   AND ($4::uuid IS NULL OR actor_id IS DISTINCT FROM $4::uuid)\n\t\t\t LIMIT 1`,\n\t\t\t[subject, kind, valueHash, actorId],\n\t\t);\n\t\treturn rows.length > 0;\n\t}\n\n\tprivate async velocityCount(\n\t\tsubject: string,\n\t\tkind: string,\n\t\tvalueHash: string,\n\t\twindow: string,\n\t): Promise<number> {\n\t\tconst rows = await this.store.query<{ n: number | string }>(\n\t\t\t`SELECT count(DISTINCT assessment_id)::int AS n FROM risk_events\n\t\t\t WHERE subject = $1 AND signal_kind = $2 AND value_hash = $3\n\t\t\t   AND created_at > now() - $4::interval`,\n\t\t\t[subject, kind, valueHash, window],\n\t\t);\n\t\treturn Number(rows[0]?.n ?? 0);\n\t}\n}\n","// The PII firewall in code: every correlating value is peppered-hashed before\n// it touches the store, and IPs are bucketed so per-address rotation can't\n// evade velocity. Nothing here is ever exported to analytics.\nimport { createHash } from 'node:crypto';\n\nconst PLACEHOLDER_PEPPERS = new Set(['change-me', 'dev-pepper', 'change-me-long-random-string']);\n\n/** Resolve the pepper: a caller-supplied value wins; otherwise fall back to a\n * dev pepper OUTSIDE production and throw INSIDE it (a leaked store must not be\n * dictionary-attackable). */\nexport function resolvePepper(supplied?: string): string {\n\tconst p = supplied ?? process.env.RISK_PEPPER;\n\tif (p && p.length >= 32 && !PLACEHOLDER_PEPPERS.has(p)) return p;\n\tif (process.env.NODE_ENV === 'production') {\n\t\tthrow new Error(\n\t\t\t'@fonderie/risk: a unique pepper of >=32 chars is required in production ' +\n\t\t\t\t'(pass RiskEngine({ pepper }) or set RISK_PEPPER) — without it the hashed ' +\n\t\t\t\t'risk_events store is dictionary-attackable offline.',\n\t\t);\n\t}\n\treturn 'fonderie-risk-dev-pepper-not-for-production';\n}\n\n/** sha256(pepper ‖ kind ‖ value) — domain-separated so a card hash can never\n * collide with an ip hash, peppered so a leaked table can't be reversed by\n * hashing candidate values. */\nexport function hashValue(pepper: string, kind: string, value: string): string {\n\treturn createHash('sha256').update(`${pepper}\\0${kind}\\0${value}`).digest('hex');\n}\n\n/** IPv6 collapses to its /64 (the customary end-site prefix — the low 64 bits\n * rotate freely and would defeat per-address velocity); IPv4-mapped IPv6\n * resolves to its embedded IPv4; IPv4 passes through whole. */\nexport function ipBucket(ip: string): string {\n\tif (!ip.includes(':')) return ip;\n\tconst [head] = ip.split('%');\n\tconst v4Mapped = /^::ffff:(\\d{1,3}(?:\\.\\d{1,3}){3})$/i.exec(head ?? '');\n\tif (v4Mapped) return v4Mapped[1] as string;\n\tconst groups = (head ?? '').split('::');\n\tlet left = groups[0] ? groups[0].split(':') : [];\n\tconst right = groups[1] ? groups[1].split(':') : [];\n\tif (groups.length === 2) {\n\t\tconst fill = 8 - left.length - right.length;\n\t\tleft = [...left, ...Array<string>(Math.max(0, fill)).fill('0'), ...right];\n\t}\n\treturn `${left.slice(0, 4).join(':')}::/64`;\n}\n\n/** Normalize a value for hashing by kind: IPs are bucketed, everything else is\n * lower-cased/trimmed so trivial spelling differences collapse. */\nexport function normalizeForKind(kind: string, value: string): string {\n\tif (kind === 'ip') return ipBucket(value.trim());\n\treturn value.trim().toLowerCase();\n}\n","// Rulesets are DATA: weights, windows, and thresholds move without a deploy.\n// The launch ruleset (trial.start) is the trial-abuse scorer, generalized —\n// the app that consumes it maps tiers to actions (the engine never does).\nimport type { RuleSet, RuleSignal, RiskTier } from './types.js';\n\n/** The reference trial-abuse ruleset. Card reuse alone is 'high' (75 > 70):\n * one free trial per physical card. Weights are illustrative and tunable. */\nexport const TRIAL_START_RULESET: RuleSet = {\n\tsubject: 'trial.start',\n\tsignals: {\n\t\tcardReuse: { weight: 75, reuse: 'card' },\n\t\tdeviceReuse: { weight: 25, reuse: 'device' },\n\t\tsignupVelocity: { weight: 30, velocity: 'device', window: '1 hour', over: 3 },\n\t\tipTrials: { weight: 10, velocity: 'ip', window: '24 hours', over: 2 },\n\t\tdisposableEmail: { weight: 20, attr: 'disposableEmail' },\n\t\tfreshAccount: { weight: 10, attr: 'accountAgeMinutes', under: 10 },\n\t},\n\ttiers: { medium: 30, high: 70 },\n};\n\n/** The default ruleset map. Apps pass their own (merged) map to RiskEngine. */\nexport const DEFAULT_RULESETS: Record<string, RuleSet> = {\n\t'trial.start': TRIAL_START_RULESET,\n};\n\n/** `< medium` → low, `<= high` → medium, else high. */\nexport function tierFor(score: number, tiers: RuleSet['tiers']): RiskTier {\n\tif (score < tiers.medium) return 'low';\n\tif (score <= tiers.high) return 'medium';\n\treturn 'high';\n}\n\nfunction isReuse(s: RuleSignal): s is Extract<RuleSignal, { reuse: string }> {\n\treturn 'reuse' in s;\n}\nfunction isVelocity(s: RuleSignal): s is Extract<RuleSignal, { velocity: string }> {\n\treturn 'velocity' in s;\n}\nfunction isAttr(s: RuleSignal): s is Extract<RuleSignal, { attr: string }> {\n\treturn 'attr' in s;\n}\n\nconst WINDOW_RE = /^\\d+\\s+(second|minute|hour|day|week|month)s?$/;\n\n/** Fail fast on a malformed ruleset — a bad window would otherwise reach SQL,\n * and a non-positive weight is almost always a typo. */\nexport function validateRuleset(rs: RuleSet): void {\n\tif (!rs.subject) throw new Error('ruleset: missing subject');\n\tif (!rs.tiers || typeof rs.tiers.medium !== 'number' || typeof rs.tiers.high !== 'number')\n\t\tthrow new Error(`ruleset ${rs.subject}: tiers.medium and tiers.high are required numbers`);\n\tfor (const [name, sig] of Object.entries(rs.signals)) {\n\t\tif (typeof sig.weight !== 'number' || sig.weight <= 0)\n\t\t\tthrow new Error(`ruleset ${rs.subject}.${name}: weight must be a positive number`);\n\t\tconst kinds = [isReuse(sig), isVelocity(sig), isAttr(sig)].filter(Boolean).length;\n\t\tif (kinds !== 1)\n\t\t\tthrow new Error(`ruleset ${rs.subject}.${name}: must be exactly one of reuse/velocity/attr`);\n\t\tif (isVelocity(sig)) {\n\t\t\tif (!WINDOW_RE.test(sig.window))\n\t\t\t\tthrow new Error(`ruleset ${rs.subject}.${name}: window \"${sig.window}\" must be a Postgres interval like \"1 hour\"`);\n\t\t\tif (typeof sig.over !== 'number')\n\t\t\t\tthrow new Error(`ruleset ${rs.subject}.${name}: velocity signal needs a numeric \"over\"`);\n\t\t}\n\t}\n}\n\n/** Does an attribute signal fire against this context's attributes? Pure. */\nexport function attributeFires(\n\tsig: Extract<RuleSignal, { attr: string }>,\n\tattributes: Record<string, string | number | boolean> | undefined,\n): boolean {\n\tconst v = attributes?.[sig.attr];\n\tif (v === undefined) return false;\n\tif (sig.equals !== undefined) return v === sig.equals;\n\tif (sig.under !== undefined) return typeof v === 'number' && v < sig.under;\n\tif (sig.over !== undefined) return typeof v === 'number' && v > sig.over;\n\treturn v === true; // bare boolean attribute\n}\n\nexport { isReuse, isVelocity, isAttr };\n"],"mappings":"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","names":[]}

package/dist/migrations/index.d.ts

@@ -0,0 +1,3 @@
+declare const getMigrationsPath: () => string;
+
+export { getMigrationsPath };

package/dist/migrations/index.js

@@ -0,0 +1,7 @@
+// src/migrations/index.ts
+import { createMigrationsPath } from "@fonderie/store";
+var getMigrationsPath = () => createMigrationsPath(import.meta.url);
+export {
+  getMigrationsPath
+};
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/migrations/index.ts"],"sourcesContent":["import { createMigrationsPath } from '@fonderie/store';\n\nexport const getMigrationsPath = (): string => createMigrationsPath(import.meta.url);\n"],"mappings":";AAAA,SAAS,4BAA4B;AAE9B,IAAM,oBAAoB,MAAc,qBAAqB,YAAY,GAAG;","names":[]}

package/dist/migrations/sql/001_risk_events.sql

@@ -0,0 +1,38 @@
+-- ----------------------------------------------------------------------------
+-- 001_risk_events
+-- ----------------------------------------------------------------------------
+-- The engine's hashed-identity memory. One row per (assessment, signal
+-- identifier): an assess() call writes a 'pending' row for each identifier it
+-- was given; record() flips that assessment's rows to the real outcome. Reuse
+-- and velocity signals are answered by querying (subject, signal_kind,
+-- value_hash) against these rows.
+--
+-- PII firewall: every correlating value is stored as sha256(pepper ‖ kind ‖
+-- value) — NEVER raw. Rows expire (expires_at, purged on a timer). Legal basis
+-- is legitimate interest (fraud prevention); nothing here may flow into the
+-- pseudonymous analytics/telemetry pipeline.
+-- ----------------------------------------------------------------------------
+
+CREATE TABLE IF NOT EXISTS risk_events (
+	id             UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+	assessment_id  UUID NOT NULL,        -- groups one assess() call's identifiers
+	subject        TEXT NOT NULL,        -- 'trial.start' | 'auth.login' | …
+	actor_id       UUID,                 -- the assessed principal, when known
+	signal_kind    TEXT NOT NULL,        -- 'card' | 'ip' | 'device' | 'email-domain' | …
+	value_hash     TEXT NOT NULL,        -- sha256(pepper ‖ kind ‖ value) — never raw
+	outcome        TEXT NOT NULL DEFAULT 'pending'
+		CHECK (outcome IN ('pending', 'allowed', 'challenged', 'blocked')),
+	score          INTEGER,
+	created_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
+	expires_at     TIMESTAMPTZ NOT NULL
+);
+
+-- The reuse/velocity lookup: "seen this identifier in this subject before?"
+CREATE INDEX IF NOT EXISTS idx_risk_events_lookup
+	ON risk_events (subject, signal_kind, value_hash);
+-- record() resolves an assessment's rows by id.
+CREATE INDEX IF NOT EXISTS idx_risk_events_assessment
+	ON risk_events (assessment_id);
+-- Retention purge.
+CREATE INDEX IF NOT EXISTS idx_risk_events_expires
+	ON risk_events (expires_at);

package/package.json

@@ -0,0 +1,75 @@
+{
+	"name": "@fonderie/risk",
+	"version": "0.1.0",
+	"fonderie": { "stability": "experimental" },
+	"description": "Generic signal → meaning → decision engine — assess an action (trial start, login, registration, promo) against weak signals and a tunable ruleset, and return a graded verdict with reasons. Decides, never enforces: the app owns every side effect.",
+	"keywords": [
+		"fonderiejs",
+		"risk",
+		"fraud",
+		"abuse",
+		"trial-abuse",
+		"signals",
+		"scoring",
+		"saas",
+		"typescript"
+	],
+	"license": "MIT",
+	"type": "module",
+	"engines": {
+		"node": ">=20"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		},
+		"./migrations": {
+			"types": "./dist/migrations/index.d.ts",
+			"import": "./dist/migrations/index.js"
+		}
+	},
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsup && tsup --config tsup.migrations.ts",
+		"dev": "tsup --watch",
+		"typecheck": "tsc --noEmit",
+		"test": "tsx --test src/__tests__/*.test.ts",
+		"lint": "biome lint src",
+		"format": "biome format --write src",
+		"check": "biome check --write src"
+	},
+	"peerDependencies": {
+		"@fonderie/core": "^0.10.0",
+		"@fonderie/store": "^0.3.0"
+	},
+	"devDependencies": {
+		"@fonderie/core": "../core",
+		"@fonderie/store": "../store",
+		"@types/node": "^26.4.1",
+		"tsup": "^8.5.1",
+		"tsx": "^4.23.13",
+		"typescript": "^6.0.3"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist",
+		"brain",
+		"LICENSE",
+		"README.md"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/fonderiejs/fonderie.git",
+		"directory": "packages/risk"
+	},
+	"homepage": "https://github.com/fonderiejs/fonderie/tree/main/packages/risk#readme",
+	"bugs": {
+		"url": "https://github.com/fonderiejs/fonderie/issues"
+	}
+}