ribaunt 0.2.3 → 0.2.4

package/dist/cjs/risk.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Ribaunt Risk Engine — programmable risk-assessment subsystem.
+ *
+ * This module is intentionally small, stateless, and caller-driven.
+ * All incoming signals are caller-supplied and treated as untrusted
+ * inputs. The default scorer is a transparent, deterministic heuristic
+ * (not an ML/fraud probability model) that can be inspected and replaced.
+ *
+ * Scoring is CPU-only, O(1) over the small set of known signals, and
+ * performs no I/O.
+ */
+import type { ClientCalibration, Workload, WorkloadBounds } from './index.js';
+export interface RiskSignals {
+    ip?: string;
+    userAgent?: string;
+    accountAgeSeconds?: number;
+    requestVelocity?: number;
+    [key: string]: unknown;
+}
+export interface RiskScorer {
+    score(signals: RiskSignals): number | Promise<number>;
+}
+export interface RiskThresholds {
+    challenge: number;
+    block: number;
+}
+export interface AssessWorkloadOptions extends WorkloadBounds {
+    targetDurationMs?: number;
+    calibration?: ClientCalibration;
+}
+export interface AssessOptions {
+    signals: RiskSignals;
+    scorer?: RiskScorer;
+    thresholds?: RiskThresholds;
+    workload?: AssessWorkloadOptions;
+}
+export interface RiskAssessment {
+    risk: number;
+    action: 'allow' | 'challenge' | 'block';
+    workload?: Workload;
+}
+export declare const DEFAULT_RISK_THRESHOLDS: RiskThresholds;
+/**
+ * Validate thresholds. Throws if invalid rather than silently repairing.
+ * Requires 0 <= challenge < block <= 100
+ */
+export declare function validateRiskThresholds(thresholds: RiskThresholds): void;
+/**
+ * Validate scorer output. Custom scorers must return a finite number
+ * between 0 and 100 inclusive. Do not silently clamp — reject as a
+ * configuration/programming error so broken policies are visible.
+ */
+export declare function validateScorerOutput(value: unknown): number;
+export declare function clampRisk(value: number): number;
+/**
+ * Normalize account age to a bounded risk contribution (0..30).
+ *
+ * Younger accounts contribute more risk than older accounts.
+ * - Negative ages are invalid/ignored (0)
+ * - NaN / Infinity are ignored (0)
+ * - Very large values saturate to 0 rather than overflow (no dominance)
+ *
+ * Buckets are documented and deterministic:
+ *   < 60s        -> 30
+ *   < 1h         -> 25
+ *   < 1d         -> 20
+ *   < 7d         -> 15
+ *   < 30d        -> 10
+ *   < 90d        -> 5
+ *   >= 90d       -> 0
+ */
+export declare function normalizeAccountAge(value: unknown): number;
+/**
+ * Normalize caller-derived request velocity to a bounded contribution (0..40).
+ *
+ * Higher velocity contributes more risk.
+ * - Negative values are invalid/ignored
+ * - Non-finite values are ignored
+ * - Saturates rather than growing without bound
+ *
+ * Buckets:
+ *   < 1          -> 0
+ *   < 5          -> 10
+ *   < 20         -> 20
+ *   < 60         -> 30
+ *   < 200        -> 35
+ *   >= 200       -> 40
+ *
+ * The caller-derived velocity is not assumed to be authoritative; it is
+ * a weak heuristic contributed to the total score.
+ */
+export declare function normalizeRequestVelocity(value: unknown): number;
+/**
+ * Inspect user-agent signal as a weak signal only.
+ *
+ * - Missing or non-string UA -> 0 (not treated as strong signal)
+ * - Empty / whitespace-only UA -> 5
+ * - Very short UA (<10 chars) -> 10
+ * - Otherwise -> 0
+ *
+ * No fragile substring bans (e.g. `ua.includes('bot')`) are used.
+ * UA classification is not treated as trustworthy.
+ */
+export declare function scoreUserAgent(value: unknown): number;
+/**
+ * IP is accepted for custom scorers but the default scorer does not
+ * pretend to know whether an IP is malicious. The safest v1 choice is
+ * to return 0 and let custom scorers handle IP reputation if needed.
+ */
+export declare function scoreIp(_value: unknown): number;
+/**
+ * Deterministic default scorer. Transparent heuristic:
+ *   signals -> normalizeAccountAge + normalizeRequestVelocity + scoreUserAgent + scoreIp -> clamp 0..100
+ *
+ * Unknown properties on RiskSignals are ignored by the default scorer;
+ * custom scorers may use them.
+ *
+ * This scorer is synchronous internally but exposed as async via the
+ * RiskScorer interface so callers can supply remote/model-based scorers
+ * without changing the API.
+ */
+export declare function defaultScore(signals: RiskSignals): number;
+export declare const defaultScorer: RiskScorer;
+//# sourceMappingURL=risk.d.ts.map

package/dist/cjs/risk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk.d.ts","sourceRoot":"","sources":["../../src/risk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAI9E,MAAM,WAAW,WAAW;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC3D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,WAAW,CAAC;IACrB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,GAAG,WAAW,GAAG,OAAO,CAAC;IACxC,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAmBD,eAAO,MAAM,uBAAuB,EAAE,cAAyC,CAAC;AAIhF;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,cAAc,GAAG,IAAI,CAsBvE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAW3D;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAG/C;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAW1D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAU/D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMrD;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAE/C;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAOzD;AAED,eAAO,MAAM,aAAa,EAAE,UAI3B,CAAC"}

package/dist/cjs/risk.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Ribaunt Risk Engine — programmable risk-assessment subsystem.
+ *
+ * This module is intentionally small, stateless, and caller-driven.
+ * All incoming signals are caller-supplied and treated as untrusted
+ * inputs. The default scorer is a transparent, deterministic heuristic
+ * (not an ML/fraud probability model) that can be inspected and replaced.
+ *
+ * Scoring is CPU-only, O(1) over the small set of known signals, and
+ * performs no I/O.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultScorer = exports.DEFAULT_RISK_THRESHOLDS = void 0;
+exports.validateRiskThresholds = validateRiskThresholds;
+exports.validateScorerOutput = validateScorerOutput;
+exports.clampRisk = clampRisk;
+exports.normalizeAccountAge = normalizeAccountAge;
+exports.normalizeRequestVelocity = normalizeRequestVelocity;
+exports.scoreUserAgent = scoreUserAgent;
+exports.scoreIp = scoreIp;
+exports.defaultScore = defaultScore;
+// ── Default policy values ──────────────────────────────────────────────────
+/**
+ * Sensible v1 defaults. These numbers are policy defaults, not claims
+ * about a statistically calibrated fraud model. Consumers should tune
+ * them to their application.
+ *
+ * Semantics:
+ *   risk < challenge               -> allow
+ *   challenge <= risk < block      -> challenge
+ *   risk >= block                 -> block
+ */
+const _DEFAULT_RISK_THRESHOLDS = Object.freeze({
+    challenge: 40,
+    block: 80,
+});
+exports.DEFAULT_RISK_THRESHOLDS = _DEFAULT_RISK_THRESHOLDS;
+// ── Validation helpers ─────────────────────────────────────────────────────
+/**
+ * Validate thresholds. Throws if invalid rather than silently repairing.
+ * Requires 0 <= challenge < block <= 100
+ */
+function validateRiskThresholds(thresholds) {
+    if (!thresholds || typeof thresholds !== 'object' || Array.isArray(thresholds)) {
+        throw new Error('Risk thresholds must be an object');
+    }
+    const c = thresholds.challenge;
+    const b = thresholds.block;
+    if (typeof c !== 'number' || !Number.isFinite(c)) {
+        throw new Error('Challenge threshold must be a finite number');
+    }
+    if (typeof b !== 'number' || !Number.isFinite(b)) {
+        throw new Error('Block threshold must be a finite number');
+    }
+    if (c < 0 || c > 100) {
+        throw new Error('Challenge threshold must be between 0 and 100');
+    }
+    if (b < 0 || b > 100) {
+        throw new Error('Block threshold must be between 0 and 100');
+    }
+    if (c >= b) {
+        throw new Error('Challenge threshold must be less than block threshold');
+    }
+}
+/**
+ * Validate scorer output. Custom scorers must return a finite number
+ * between 0 and 100 inclusive. Do not silently clamp — reject as a
+ * configuration/programming error so broken policies are visible.
+ */
+function validateScorerOutput(value) {
+    if (typeof value !== 'number') {
+        throw new Error('Scorer must return a finite number between 0 and 100');
+    }
+    if (!Number.isFinite(value)) {
+        throw new Error('Scorer must return a finite number between 0 and 100');
+    }
+    if (value < 0 || value > 100) {
+        throw new Error('Scorer must return a number between 0 and 100');
+    }
+    return value;
+}
+function clampRisk(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.max(0, Math.min(100, Math.round(value)));
+}
+// ── Normalizer / rule helpers (default scorer pipeline) ───────────────────
+/**
+ * Normalize account age to a bounded risk contribution (0..30).
+ *
+ * Younger accounts contribute more risk than older accounts.
+ * - Negative ages are invalid/ignored (0)
+ * - NaN / Infinity are ignored (0)
+ * - Very large values saturate to 0 rather than overflow (no dominance)
+ *
+ * Buckets are documented and deterministic:
+ *   < 60s        -> 30
+ *   < 1h         -> 25
+ *   < 1d         -> 20
+ *   < 7d         -> 15
+ *   < 30d        -> 10
+ *   < 90d        -> 5
+ *   >= 90d       -> 0
+ */
+function normalizeAccountAge(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+        return 0;
+    }
+    if (value < 60)
+        return 30;
+    if (value < 3600)
+        return 25;
+    if (value < 86400)
+        return 20;
+    if (value < 604800)
+        return 15;
+    if (value < 2592000)
+        return 10;
+    if (value < 7776000)
+        return 5;
+    return 0;
+}
+/**
+ * Normalize caller-derived request velocity to a bounded contribution (0..40).
+ *
+ * Higher velocity contributes more risk.
+ * - Negative values are invalid/ignored
+ * - Non-finite values are ignored
+ * - Saturates rather than growing without bound
+ *
+ * Buckets:
+ *   < 1          -> 0
+ *   < 5          -> 10
+ *   < 20         -> 20
+ *   < 60         -> 30
+ *   < 200        -> 35
+ *   >= 200       -> 40
+ *
+ * The caller-derived velocity is not assumed to be authoritative; it is
+ * a weak heuristic contributed to the total score.
+ */
+function normalizeRequestVelocity(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+        return 0;
+    }
+    if (value < 1)
+        return 0;
+    if (value < 5)
+        return 10;
+    if (value < 20)
+        return 20;
+    if (value < 60)
+        return 30;
+    if (value < 200)
+        return 35;
+    return 40;
+}
+/**
+ * Inspect user-agent signal as a weak signal only.
+ *
+ * - Missing or non-string UA -> 0 (not treated as strong signal)
+ * - Empty / whitespace-only UA -> 5
+ * - Very short UA (<10 chars) -> 10
+ * - Otherwise -> 0
+ *
+ * No fragile substring bans (e.g. `ua.includes('bot')`) are used.
+ * UA classification is not treated as trustworthy.
+ */
+function scoreUserAgent(value) {
+    if (typeof value !== 'string')
+        return 0;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return 5;
+    if (trimmed.length < 10)
+        return 10;
+    return 0;
+}
+/**
+ * IP is accepted for custom scorers but the default scorer does not
+ * pretend to know whether an IP is malicious. The safest v1 choice is
+ * to return 0 and let custom scorers handle IP reputation if needed.
+ */
+function scoreIp(_value) {
+    return 0;
+}
+// ── Default scorer ─────────────────────────────────────────────────────────
+/**
+ * Deterministic default scorer. Transparent heuristic:
+ *   signals -> normalizeAccountAge + normalizeRequestVelocity + scoreUserAgent + scoreIp -> clamp 0..100
+ *
+ * Unknown properties on RiskSignals are ignored by the default scorer;
+ * custom scorers may use them.
+ *
+ * This scorer is synchronous internally but exposed as async via the
+ * RiskScorer interface so callers can supply remote/model-based scorers
+ * without changing the API.
+ */
+function defaultScore(signals) {
+    const age = normalizeAccountAge(signals.accountAgeSeconds);
+    const velocity = normalizeRequestVelocity(signals.requestVelocity);
+    const ua = scoreUserAgent(signals.userAgent);
+    const ip = scoreIp(signals.ip);
+    const raw = age + velocity + ua + ip;
+    return clampRisk(raw);
+}
+exports.defaultScorer = {
+    async score(signals) {
+        return defaultScore(signals);
+    },
+};
+//# sourceMappingURL=risk.js.map

package/dist/cjs/risk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk.js","sourceRoot":"","sources":["../../src/risk.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+import { DEFAULT_RISK_THRESHOLDS } from './risk.js';
+import type { AssessOptions, RiskAssessment } from './risk.js';
+export type { AssessOptions, AssessWorkloadOptions, RiskAssessment, RiskScorer, RiskSignals, RiskThresholds } from './risk.js';
+export { DEFAULT_RISK_THRESHOLDS };
 export type ChallengeToken = string;
 export interface ChallengeSolution {
     nonce: string;
@@ -60,7 +64,7 @@ export interface VerifySolutionOptions {
     rateLimiter?: RateLimiter;
     onEvent?: (event: RibauntEvent) => void;
 }
-export type VerifyFailureReason = 'invalid-token' | 'expired-token' | 'invalid-solution' | 'context-mismatch' | 'replay-detected' | 'configuration-error';
+export type VerifyFailureReason = 'invalid-token' | 'expired-token' | 'invalid-solution' | 'context-mismatch' | 'replay-detected' | 'replay-store-unavailable' | 'configuration-error';
 export type VerifyWarningReason = VerifyFailureReason;
 export interface VerifyWarning {
     reason: VerifyWarningReason;
@@ -99,6 +103,25 @@ export declare class LocalReplayStore implements ReplayStore {
  * Selects bounded proof-of-work using a server-owned risk floor and untrusted timing calibration.
  */
 export declare function selectWorkload(options?: AdaptiveWorkloadOptions): Workload;
+/**
+ * Programmable risk-assessment subsystem.
+ *
+ * All signals are caller-supplied and treated as untrusted inputs.
+ * The default scorer is a transparent heuristic (not an ML model).
+ * The returned `risk` is a bounded heuristic score, not a probability
+ * or identity confidence. The caller is responsible for obtaining
+ * trustworthy inputs.
+ *
+ * Flow:
+ *   validate AssessOptions
+ *     -> resolve scorer (custom or default)
+ *     -> await scorer.score(signals)
+ *     -> validate risk 0..100
+ *     -> resolve thresholds (custom or DEFAULT_RISK_THRESHOLDS)
+ *     -> apply policy (allow / challenge / block)
+ *     -> if challenge, delegate to existing selectWorkload() with riskScore
+ */
+export declare function assess(options: AssessOptions): Promise<RiskAssessment>;
 export declare function calibrateNode(iterations?: number): ClientCalibration;
 export declare const calibrateClient: typeof calibrateNode;
 export declare function createChallenge(difficulty?: number, amount?: number, ttlSeconds?: number): Promise<ChallengeToken[]>;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,5 +1,7 @@
 import crypto from 'crypto';
 import jwt from 'jsonwebtoken';
+import { DEFAULT_RISK_THRESHOLDS, defaultScorer, validateRiskThresholds, validateScorerOutput, } from './risk.js';
+export { DEFAULT_RISK_THRESHOLDS };
 export class RateLimitedError extends Error {
     constructor(message = 'Rate limit exceeded') {
         super(message);
@@ -40,6 +42,9 @@ const DEFAULT_BOUNDS = {
     minAmount: 1,
     maxAmount: 8,
 };
+const MAX_WORKLOAD_DIFFICULTY = 64;
+const MAX_WORKLOAD_AMOUNT = 64;
+const MAX_WORKLOAD_CANDIDATES = 10000;
 function assertFiniteInteger(value, name, minimum) {
     if (!Number.isFinite(value))
         throw new Error(`${name} must be a finite number`);
@@ -72,9 +77,25 @@ function assertRange(value, name, minimum, maximum) {
 }
 function normalizeBounds(options) {
     const minDifficulty = assertFiniteInteger(options.minDifficulty ?? DEFAULT_BOUNDS.minDifficulty, 'Minimum difficulty', 1);
+    if (minDifficulty > MAX_WORKLOAD_DIFFICULTY) {
+        throw new Error(`Minimum difficulty must be at most ${MAX_WORKLOAD_DIFFICULTY}`);
+    }
     const maxDifficulty = assertFiniteInteger(options.maxDifficulty ?? DEFAULT_BOUNDS.maxDifficulty, 'Maximum difficulty', minDifficulty);
+    if (maxDifficulty > MAX_WORKLOAD_DIFFICULTY) {
+        throw new Error(`Maximum difficulty must be at most ${MAX_WORKLOAD_DIFFICULTY}`);
+    }
     const minAmount = assertFiniteInteger(options.minAmount ?? DEFAULT_BOUNDS.minAmount, 'Minimum amount', 1);
+    if (minAmount > MAX_WORKLOAD_AMOUNT) {
+        throw new Error(`Minimum amount must be at most ${MAX_WORKLOAD_AMOUNT}`);
+    }
     const maxAmount = assertFiniteInteger(options.maxAmount ?? DEFAULT_BOUNDS.maxAmount, 'Maximum amount', minAmount);
+    if (maxAmount > MAX_WORKLOAD_AMOUNT) {
+        throw new Error(`Maximum amount must be at most ${MAX_WORKLOAD_AMOUNT}`);
+    }
+    const candidateCount = (maxDifficulty - minDifficulty + 1) * (maxAmount - minAmount + 1);
+    if (candidateCount > MAX_WORKLOAD_CANDIDATES) {
+        throw new Error(`Workload bounds too large: candidate count ${candidateCount} exceeds ${MAX_WORKLOAD_CANDIDATES}`);
+    }
     return { minDifficulty, maxDifficulty, minAmount, maxAmount };
 }
 function closestWorkload(targetAttempts, bounds) {
@@ -112,6 +133,131 @@ export function selectWorkload(options = {}) {
     const maximumAttempts = (16 ** bounds.maxDifficulty) * bounds.maxAmount;
     return closestWorkload(Math.min(targetAttempts, maximumAttempts), bounds);
 }
+function validateAssessWorkloadOptions(workload) {
+    // Reuse same validation messages as normalizeBounds / selectWorkload for regression safety
+    if (workload.minDifficulty !== undefined) {
+        assertFiniteInteger(workload.minDifficulty, 'Minimum difficulty', 1);
+    }
+    if (workload.maxDifficulty !== undefined) {
+        // Need to ensure we validate max >= min (using resolved min)
+        const min = workload.minDifficulty !== undefined ? Math.floor(workload.minDifficulty) : DEFAULT_BOUNDS.minDifficulty;
+        assertFiniteInteger(workload.maxDifficulty, 'Maximum difficulty', min);
+    }
+    else if (workload.minDifficulty !== undefined) {
+        // If only minDifficulty provided, still need to ensure default max >= min
+        if (DEFAULT_BOUNDS.maxDifficulty < Math.floor(workload.minDifficulty)) {
+            throw new Error(`Maximum difficulty must be at least ${Math.floor(workload.minDifficulty)}`);
+        }
+    }
+    if (workload.minAmount !== undefined) {
+        assertFiniteInteger(workload.minAmount, 'Minimum amount', 1);
+    }
+    if (workload.maxAmount !== undefined) {
+        const minAmt = workload.minAmount !== undefined ? Math.floor(workload.minAmount) : DEFAULT_BOUNDS.minAmount;
+        assertFiniteInteger(workload.maxAmount, 'Maximum amount', minAmt);
+    }
+    else if (workload.minAmount !== undefined) {
+        if (DEFAULT_BOUNDS.maxAmount < Math.floor(workload.minAmount)) {
+            throw new Error(`Maximum amount must be at least ${Math.floor(workload.minAmount)}`);
+        }
+    }
+    // Cross-check when both are provided, normalizeBounds already checks but we also check explicit ordering
+    // Also need to handle case where both provided but max < min — already caught above with min as floor.
+    // For completeness, if both undefined, no check needed.
+    // Validate targetDurationMs
+    if (workload.targetDurationMs !== undefined) {
+        assertFiniteInteger(workload.targetDurationMs, 'Target duration', 1);
+    }
+    // Validate calibration
+    if (workload.calibration !== undefined) {
+        if (!workload.calibration || typeof workload.calibration !== 'object' || Array.isArray(workload.calibration)) {
+            throw new Error('Calibration must be an object');
+        }
+        const cal = workload.calibration;
+        assertFiniteInteger(cal.iterations, 'Calibration iterations', 1);
+        assertFiniteInteger(cal.durationMs, 'Calibration duration', 1);
+    }
+    // If any of min/max are provided, also run through normalizeBounds to ensure combined validation matches selectWorkload exactly
+    // This catches edge cases like non-finite values already handled, but ensures parity
+    if (workload.minDifficulty !== undefined ||
+        workload.maxDifficulty !== undefined ||
+        workload.minAmount !== undefined ||
+        workload.maxAmount !== undefined) {
+        normalizeBounds(workload);
+    }
+}
+/**
+ * Programmable risk-assessment subsystem.
+ *
+ * All signals are caller-supplied and treated as untrusted inputs.
+ * The default scorer is a transparent heuristic (not an ML model).
+ * The returned `risk` is a bounded heuristic score, not a probability
+ * or identity confidence. The caller is responsible for obtaining
+ * trustworthy inputs.
+ *
+ * Flow:
+ *   validate AssessOptions
+ *     -> resolve scorer (custom or default)
+ *     -> await scorer.score(signals)
+ *     -> validate risk 0..100
+ *     -> resolve thresholds (custom or DEFAULT_RISK_THRESHOLDS)
+ *     -> apply policy (allow / challenge / block)
+ *     -> if challenge, delegate to existing selectWorkload() with riskScore
+ */
+export async function assess(options) {
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        throw new Error('AssessOptions must be an object');
+    }
+    const { signals, scorer, thresholds, workload } = options;
+    if (!signals || typeof signals !== 'object' || Array.isArray(signals)) {
+        throw new Error('signals must be an object');
+    }
+    if (scorer !== undefined) {
+        if (!scorer || typeof scorer !== 'object' || typeof scorer.score !== 'function') {
+            throw new Error('scorer must be an object with a score function');
+        }
+    }
+    if (thresholds !== undefined) {
+        validateRiskThresholds(thresholds);
+    }
+    // Use a private immutable default via copy so consumer mutation of the exported
+    // DEFAULT_RISK_THRESHOLDS cannot change library behavior
+    const resolvedThresholds = thresholds
+        ? { challenge: thresholds.challenge, block: thresholds.block }
+        : { challenge: DEFAULT_RISK_THRESHOLDS.challenge, block: DEFAULT_RISK_THRESHOLDS.block };
+    // Validate resolved copy as well (defensive)
+    validateRiskThresholds(resolvedThresholds);
+    if (workload !== undefined) {
+        if (!workload || typeof workload !== 'object' || Array.isArray(workload)) {
+            throw new Error('workload must be an object');
+        }
+        validateAssessWorkloadOptions(workload);
+    }
+    const activeScorer = scorer ?? defaultScorer;
+    const rawRisk = await activeScorer.score(signals);
+    const risk = validateScorerOutput(rawRisk);
+    const { challenge, block } = resolvedThresholds;
+    let action;
+    if (risk < challenge)
+        action = 'allow';
+    else if (risk < block)
+        action = 'challenge';
+    else
+        action = 'block';
+    if (action === 'challenge') {
+        // Reuse existing adaptive workload selection. Do not duplicate logic.
+        // Ensure assessed risk overrides any riskScore that might be present in workload (defensive copy).
+        const workloadOptions = {
+            ...workload,
+            riskScore: risk,
+        };
+        // Ensure workload's riskScore is overridden even if spread included one
+        workloadOptions.riskScore = risk;
+        const resultWorkload = selectWorkload(workloadOptions);
+        return { risk, action, workload: resultWorkload };
+    }
+    return { risk, action };
+}
 export function calibrateNode(iterations = 128) {
     if (!Number.isFinite(iterations) || iterations < 1) {
         throw new Error('Calibration iterations must be at least 1');
@@ -138,20 +284,15 @@ function hashContext(context, jti) {
         .update(context, 'utf8')
         .digest('hex');
 }
-let cachedSecret;
 function getSecret() {
     const secret = process.env.RIBAUNT_SECRET;
     if (!secret) {
-        cachedSecret = undefined;
         throw new Error('RIBAUNT_SECRET environment variable is not set!');
     }
     if (Buffer.byteLength(secret, 'utf8') < 32) {
-        cachedSecret = undefined;
         throw new Error('RIBAUNT_SECRET must be at least 32 bytes');
     }
-    if (cachedSecret !== secret)
-        cachedSecret = secret;
-    return cachedSecret;
+    return secret;
 }
 function createSingleChallenge(difficulty, ttlSeconds, context) {
     const jti = crypto.randomUUID();
@@ -357,14 +498,19 @@ export async function verifySolution(token, nonce, options) {
         if (replayStore && jtis.length > 0) {
             const expiresAt = Math.max(...validated.map((payload) => payload.expires));
             let consumed;
-            if (jtis.length > 1) {
-                if (!replayStore.consumeMany) {
-                    return warn('configuration-error', 'A replayStore with consumeMany is required for atomic batch verification', options);
+            try {
+                if (jtis.length > 1) {
+                    if (!replayStore.consumeMany) {
+                        return warn('configuration-error', 'A replayStore with consumeMany is required for atomic batch verification', options);
+                    }
+                    consumed = await replayStore.consumeMany(jtis, expiresAt);
+                }
+                else {
+                    consumed = await replayStore.consume(jtis[0], expiresAt);
                 }
-                consumed = await replayStore.consumeMany(jtis, expiresAt);
             }
-            else {
-                consumed = await replayStore.consume(jtis[0], expiresAt);
+            catch (error) {
+                return warn('replay-store-unavailable', 'verifySolution failed because the replay store could not be reached', options, error);
             }
             if (!consumed)
                 return warn('replay-detected', 'verifySolution rejected a replayed token', options);