safehands-pharos 1.4.0 → 2.6.0

package/dist/lib/price/types.d.ts

@@ -0,0 +1,67 @@
+import type { Abi } from "viem";
+export type PriceFeedProviderKind = "chainlink-push" | "supra-pull";
+export type PriceErrorCode = "PRICE_SOURCE_UNAVAILABLE" | "PRICE_SOURCE_STALE" | "PRICE_SOURCE_INVALID" | "PRICE_SOURCE_RATE_LIMITED" | "PRICE_FEED_NOT_CONFIGURED";
+export interface PriceFeedConfig {
+    pair: string;
+    base: string;
+    quote: "USD";
+    feedAddress: `0x${string}`;
+    decimals: number;
+    heartbeatSeconds: number;
+    provider: PriceFeedProviderKind;
+    docsSource: string;
+}
+export interface ProviderQuote {
+    answer: bigint;
+    updatedAtUnix: number;
+}
+/** Minimal read surface so providers are testable without the global viem client. */
+export interface ContractReader {
+    readContract(args: {
+        address: `0x${string}`;
+        abi: Abi;
+        functionName: string;
+    }): Promise<unknown>;
+}
+export interface PriceProvider {
+    readonly kind: PriceFeedProviderKind;
+    readonly label: string;
+    /** Fetch one raw quote for one feed. May throw raw errors; the resolver classifies them. */
+    fetchQuote(feed: PriceFeedConfig): Promise<ProviderQuote>;
+}
+export interface PriceResolution {
+    token: string;
+    canonicalSymbol: string;
+    pair: string;
+    priceUsd: string;
+    priceUsdNumber: number;
+    provider: PriceFeedProviderKind;
+    source: string;
+    sourceStatus: "ok" | "rpc_degraded_cache";
+    confidence: "high" | "degraded";
+    timestamp: string;
+    updatedAtUnix: number;
+    feedAgeSeconds: number;
+    feedStale: boolean;
+    cached: boolean;
+    cacheAgeSeconds: number | null;
+    feedAddress: `0x${string}`;
+    heartbeatSeconds: number;
+    network: string;
+    chainId: number;
+}
+export interface PriceResolverFailure {
+    code: PriceErrorCode;
+    message: string;
+    retryable: boolean;
+    provider: PriceFeedProviderKind | "none";
+    pair?: string;
+}
+export type PriceResolverResult = {
+    ok: true;
+    resolution: PriceResolution;
+} | {
+    ok: false;
+    error: PriceResolverFailure;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/price/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/price/types.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAEhC,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,GAAG,YAAY,CAAC;AAEpE,MAAM,MAAM,cAAc,GACtB,0BAA0B,GAC1B,oBAAoB,GACpB,sBAAsB,GACtB,2BAA2B,GAC3B,2BAA2B,CAAC;AAEhC,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,qBAAqB,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,qFAAqF;AACrF,MAAM,WAAW,cAAc;IAC7B,YAAY,CAAC,IAAI,EAAE;QACjB,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;QACvB,GAAG,EAAE,GAAG,CAAC;QACT,YAAY,EAAE,MAAM,CAAC;KACtB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4FAA4F;IAC5F,UAAU,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,qBAAqB,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IAGf,YAAY,EAAE,IAAI,GAAG,oBAAoB,CAAC;IAC1C,UAAU,EAAE,MAAM,GAAG,UAAU,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IAIvB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,qBAAqB,GAAG,MAAM,CAAC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,eAAe,CAAA;CAAE,GACzC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,oBAAoB,CAAA;CAAE,CAAC"}

package/dist/lib/price/types.js

@@ -0,0 +1,7 @@
+// ─── Price Oracle Types ────────────────────────────────────────────────
+// Contracts for the provider-based PriceResolver. Price oracle/valuation is
+// separate from swap routing (DODO/FaroSwap stays route/execution-quote only).
+// No I/O in this module.
+// ────────────────────────────────────────────────────────────────────────
+export {};
+//# sourceMappingURL=types.js.map

package/dist/lib/price/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/price/types.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,4EAA4E;AAC5E,+EAA+E;AAC/E,yBAAyB;AACzB,2EAA2E"}

package/dist/lib/productionGuards.d.ts

@@ -0,0 +1,16 @@
+export interface PostureIssue {
+    level: "warn" | "fatal";
+    code: string;
+    message: string;
+}
+/**
+ * Evaluate the production posture. Pure (reads env only, no side effects) so it is
+ * unit-testable. Returns [] outside production. The caller logs/throws.
+ */
+export declare function evaluateProductionPosture(env?: NodeJS.ProcessEnv): PostureIssue[];
+/**
+ * Apply the posture at server startup: log every issue, then throw if any are fatal.
+ * Warnings never block boot; fatals refuse to start (fail-fast).
+ */
+export declare function assertProductionPosture(): void;
+//# sourceMappingURL=productionGuards.d.ts.map

package/dist/lib/productionGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"productionGuards.d.ts","sourceRoot":"","sources":["../../src/lib/productionGuards.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,EAAE,CA4E9F;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAY9C"}

package/dist/lib/productionGuards.js

@@ -0,0 +1,93 @@
+// ─── Production posture guards ─────────────────────────────────────────────
+// Lightweight startup checks that fail-fast (fatal) or warn on unsafe public-
+// hosting configuration. Active only when NODE_ENV=production, evaluated once at
+// server boot. These NEVER remove capability — they protect the Mainnet Production
+// Profile's zero-custody posture and durable state. Every check has an explicit
+// override so intentional self-hosted setups are never blocked silently.
+// ───────────────────────────────────────────────────────────────────────────
+import { safeHandsStateDir } from "./persistentJsonStore.js";
+/**
+ * Evaluate the production posture. Pure (reads env only, no side effects) so it is
+ * unit-testable. Returns [] outside production. The caller logs/throws.
+ */
+export function evaluateProductionPosture(env = process.env) {
+    const issues = [];
+    if (env.NODE_ENV !== "production")
+        return issues;
+    // 1) FATAL — custody landmine: managed execution enabled on a public host.
+    const managed = env.WALLET_MODE === "managed-mainnet";
+    const writeOn = env.WRITE_TOOLS_ENABLED === "true";
+    const allowManagedPublic = env.SAFEHANDS_ALLOW_MANAGED_ON_PUBLIC === "true";
+    if (managed && writeOn && !allowManagedPublic) {
+        issues.push({
+            level: "fatal",
+            code: "MANAGED_EXECUTION_ON_PUBLIC",
+            message: "Refusing to start: WALLET_MODE=managed-mainnet + WRITE_TOOLS_ENABLED=true in production puts a signing key on the host (custody). The public zero-custody profile requires WALLET_MODE=none + WRITE_TOOLS_ENABLED=false. For an intentional self-hosted single-tenant deployment, set SAFEHANDS_ALLOW_MANAGED_ON_PUBLIC=true.",
+        });
+    }
+    // 1b) FATAL — custody landmine: local x402 facilitator key in production.
+    // The standalone x402 server (`npm run start:x402`) signs settlements with
+    // X402_FACILITATOR_PRIVATE_KEY — a hot key on the host. The zero-custody
+    // production path is the Guardian API `/paid/*` gate with an EXTERNAL
+    // facilitator (X402_PAY_TO + X402_FACILITATOR_URL) and no local key.
+    const localFacilitatorKey = Boolean(env.X402_FACILITATOR_PRIVATE_KEY);
+    const allowLocalFacilitator = env.SAFEHANDS_ALLOW_LOCAL_FACILITATOR === "true";
+    if (localFacilitatorKey && !allowLocalFacilitator) {
+        issues.push({
+            level: "fatal",
+            code: "LOCAL_FACILITATOR_KEY_IN_PRODUCTION",
+            message: "Refusing to start: X402_FACILITATOR_PRIVATE_KEY is set in production: the local x402 facilitator signs settlements with a hot key on the host (custody). The zero-custody profile serves paid endpoints through the Guardian API /paid/* gate with an external facilitator (X402_PAY_TO + X402_FACILITATOR_URL) and no local key. For an intentional dev/self-hosted single-tenant deployment, set SAFEHANDS_ALLOW_LOCAL_FACILITATOR=true.",
+        });
+    }
+    // 2) WARN — ephemeral state dir → durability loss on restart.
+    const stateDirSet = Boolean(env.SAFEHANDS_STATE_DIR || env.STATE_DIR);
+    const dir = env.SAFEHANDS_STATE_DIR || env.STATE_DIR || safeHandsStateDir();
+    const looksEphemeral = !stateDirSet || dir === ".safehands" || dir === "." || dir.startsWith("./") || dir.startsWith(".safehands");
+    if (looksEphemeral) {
+        issues.push({
+            level: "warn",
+            code: "EPHEMERAL_STATE_DIR",
+            message: `SAFEHANDS_STATE_DIR resolves to "${dir}"; on an ephemeral host (e.g. Railway without a Volume) prepared transactions, the attestation queue, and the audit trail are LOST on restart. Mount a persistent Volume and set SAFEHANDS_STATE_DIR to its path (e.g. /data).`,
+        });
+    }
+    // 3) WARN — x402 enabled + replay required but Upstash Redis not configured.
+    // x402 counts as configured for EITHER profile: the zero-custody API gate
+    // (X402_FACILITATOR_URL) or the standalone local facilitator (private key).
+    const x402Configured = Boolean(env.X402_PAY_TO && (env.X402_FACILITATOR_URL || env.X402_FACILITATOR_PRIVATE_KEY));
+    const replayRequired = env.SAFEHANDS_X402_REPLAY_REDIS_REQUIRED === "true";
+    const upstash = Boolean((env.UPSTASH_REDIS_REST_URL || env.SAFEHANDS_REDIS_REST_URL) &&
+        (env.UPSTASH_REDIS_REST_TOKEN || env.SAFEHANDS_REDIS_REST_TOKEN));
+    if (x402Configured && replayRequired && !upstash) {
+        issues.push({
+            level: "warn",
+            code: "X402_REPLAY_REDIS_MISSING",
+            message: "x402 is configured and SAFEHANDS_X402_REPLAY_REDIS_REQUIRED=true, but Upstash Redis env (UPSTASH_REDIS_REST_URL/TOKEN) is missing. x402 replay protection will fail closed at runtime. Provision Upstash Redis or unset SAFEHANDS_X402_REPLAY_REDIS_REQUIRED.",
+        });
+    }
+    // 4) WARN — CORS wildcard in production (advisory; fine for the public read tier).
+    const cors = env.SAFEHANDS_CORS_ORIGIN || env.CORS_ORIGIN || env.SAFEHANDS_ALLOWED_ORIGINS;
+    if (!cors || cors === "*") {
+        issues.push({
+            level: "warn",
+            code: "CORS_WILDCARD",
+            message: "CORS is wildcard (*) in production. Acceptable for the public read tier, but tighten CORS_ORIGIN / SAFEHANDS_CORS_ORIGIN for guarded/paid surfaces.",
+        });
+    }
+    return issues;
+}
+/**
+ * Apply the posture at server startup: log every issue, then throw if any are fatal.
+ * Warnings never block boot; fatals refuse to start (fail-fast).
+ */
+export function assertProductionPosture() {
+    const issues = evaluateProductionPosture();
+    for (const i of issues) {
+        const tag = i.level === "fatal" ? "❌ FATAL" : "⚠️  WARNING";
+        console.error(`${tag} [SafeHands posture · ${i.code}] ${i.message}`);
+    }
+    const fatal = issues.filter((i) => i.level === "fatal");
+    if (fatal.length > 0) {
+        throw new Error(`SafeHands refused to start: ${fatal.length} fatal production-posture issue(s); see logs above. This protects the zero-custody Mainnet Production Profile.`);
+    }
+}
+//# sourceMappingURL=productionGuards.js.map

package/dist/lib/productionGuards.js.map

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

package/dist/lib/recipientSafety.d.ts

@@ -0,0 +1,5 @@
+/** Parse the operator-supplied denylist from env (comma-separated). Empty by default. */
+export declare function recipientDenylist(): Set<string>;
+/** True when the address is a valid EVM address present on the operator denylist. */
+export declare function isDenylistedRecipient(address?: string | null): boolean;
+//# sourceMappingURL=recipientSafety.d.ts.map

package/dist/lib/recipientSafety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipientSafety.d.ts","sourceRoot":"","sources":["../../src/lib/recipientSafety.ts"],"names":[],"mappings":"AAeA,yFAAyF;AACzF,wBAAgB,iBAAiB,IAAI,GAAG,CAAC,MAAM,CAAC,CAQ/C;AAED,qFAAqF;AACrF,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAGtE"}

package/dist/lib/recipientSafety.js

@@ -0,0 +1,28 @@
+// ─── Recipient safety — operator-configurable denylist ─────────────────────
+// A sync, keyless, honest guard for the RECIPIENT of a value transfer/approval.
+// The denylist is entirely operator-supplied via env (empty by default) — SafeHands
+// ships NO fabricated scam list, so there is never false "scam protection" confidence.
+// Operators point it at their own known-bad set (drainers, scam addresses, mistyped
+// treasury addresses to hard-block, etc.).
+//
+// NOTE (honest scope): deeper recipient intelligence — address-poisoning detection
+// and first-time-recipient warnings — requires the sender's transfer history, which
+// is too RPC-heavy for the hot path without the Goldsky indexer. That is deferred to
+// the indexer-backed path rather than added as a laggy hot-path scan.
+// ───────────────────────────────────────────────────────────────────────────
+import { isAddress } from "viem";
+/** Parse the operator-supplied denylist from env (comma-separated). Empty by default. */
+export function recipientDenylist() {
+    const raw = process.env.SAFEHANDS_RECIPIENT_DENYLIST || "";
+    return new Set(raw
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter((s) => isAddress(s)));
+}
+/** True when the address is a valid EVM address present on the operator denylist. */
+export function isDenylistedRecipient(address) {
+    if (!address || !isAddress(address))
+        return false;
+    return recipientDenylist().has(address.toLowerCase());
+}
+//# sourceMappingURL=recipientSafety.js.map

package/dist/lib/recipientSafety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipientSafety.js","sourceRoot":"","sources":["../../src/lib/recipientSafety.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,gFAAgF;AAChF,oFAAoF;AACpF,uFAAuF;AACvF,oFAAoF;AACpF,2CAA2C;AAC3C,EAAE;AACF,mFAAmF;AACnF,oFAAoF;AACpF,qFAAqF;AACrF,sEAAsE;AACtE,8EAA8E;AAE9E,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAEjC,yFAAyF;AACzF,MAAM,UAAU,iBAAiB;IAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,4BAA4B,IAAI,EAAE,CAAC;IAC3D,OAAO,IAAI,GAAG,CACZ,GAAG;SACA,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;SAClC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAC/B,CAAC;AACJ,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,qBAAqB,CAAC,OAAuB;IAC3D,IAAI,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IAClD,OAAO,iBAAiB,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;AACxD,CAAC"}

package/dist/lib/riskEngine.d.ts

@@ -1,27 +1,46 @@
-export interface RiskBreakdown {
-    liquidityRisk: number;
-    slippageRisk: number;
-    counterpartyRisk: number;
-    balanceRisk: number;
-    marketConditionRisk: number;
-}
-export type RiskLevel = "low" | "medium" | "high" | "critical";
-export type RiskRecommendation = "proceed" | "caution" | "block";
-export interface RiskAssessment {
-    riskScore: number;
-    riskLevel: RiskLevel;
-    recommendation: RiskRecommendation;
-    breakdown: RiskBreakdown;
-    reasons: string[];
-    suggestion: string;
-}
-export interface RiskInput {
-    action: "swap" | "transfer";
-    tokenIn?: string;
-    tokenOut?: string;
-    amount: string;
-    toAddress?: string;
-    walletAddress: string;
-}
-export declare function assessRisk(input: RiskInput): Promise<RiskAssessment>;
+export interface RiskBreakdown {
+    liquidityRisk: number;
+    slippageRisk: number;
+    counterpartyRisk: number;
+    balanceRisk: number;
+    marketConditionRisk: number;
+}
+export type RiskLevel = "low" | "medium" | "high" | "critical";
+export type RiskRecommendation = "proceed" | "caution" | "block";
+export interface RiskAssessment {
+    riskScore: number;
+    riskLevel: RiskLevel;
+    /**
+     * ADVISORY only — never gates execution. The actionPolicyEngine is the sole
+     * ALLOW/BLOCK decider on write paths (docs/DECISION_CONTRACT.md); this field
+     * exists for reports and the on-chain assessment record.
+     */
+    recommendation: RiskRecommendation;
+    breakdown: RiskBreakdown;
+    reasons: string[];
+    suggestion: string;
+    /**
+     * True when a CRITICAL risk signal could not be evaluated (route/liquidity or
+     * balance fetch failed). Callers must fail-closed on this — never silently
+     * proceed on degraded data. Market-condition gaps are non-critical and do
+     * NOT set this.
+     */
+    degraded: boolean;
+    degradedReasons: string[];
+    /**
+     * Structural (not transient): the swap liquidity provider is not configured/
+     * verified for the active chain (SWAP_LIQUIDITY_NOT_CONFIGURED). Liquidity and
+     * slippage dimensions were scored fail-closed without live route data.
+     */
+    swapProviderNotConfigured?: boolean;
+}
+export interface RiskInput {
+    action: "swap" | "transfer";
+    tokenIn?: string;
+    tokenOut?: string;
+    amount: string;
+    toAddress?: string;
+    walletAddress: string;
+}
+export declare function assessRisk(input: RiskInput): Promise<RiskAssessment>;
 //# sourceMappingURL=riskEngine.d.ts.map

package/dist/lib/riskEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"riskEngine.d.ts","sourceRoot":"","sources":["../../src/lib/riskEngine.ts"],"names":[],"mappings":"AA2BA,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAC/D,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAEjE,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB,cAAc,EAAE,kBAAkB,CAAC;IACnC,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AA2QD,wBAAsB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC,CAgD1E"}
+{"version":3,"file":"riskEngine.d.ts","sourceRoot":"","sources":["../../src/lib/riskEngine.ts"],"names":[],"mappings":"AAoCA,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAC/D,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAEjE,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB;;;;OAIG;IACH,cAAc,EAAE,kBAAkB,CAAC;IACnC,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;OAIG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AA8SD,wBAAsB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC,CAoF1E"}