@forgezero/runtime 0.1.0

package/dist/compliance.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Screening — the stage that already has a seat.
+ *
+ * `@forgezero/runtime/finance/transfers` reserved position zero and has been running a
+ * pass-everything placeholder there since before this file existed. That
+ * ordering is the whole reason this is a drop-in: nothing about deposits or
+ * withdrawals changes, and the audit trail already records the stage running.
+ *
+ * ## Screening is a DECISION RECORD, not a boolean
+ *
+ * The value of compliance work six months later is being able to say why a
+ * transfer was allowed — not just that it was. A screen that returns true or
+ * false gives an auditor nothing, so every check produces a verdict with the
+ * rules that fired, the risk it scored and the list version it was screened
+ * against. That record is the deliverable; the refusal is a side effect.
+ *
+ * ## Fail CLOSED on an unavailable list, and say so
+ *
+ * A sanctions list that cannot be reached is not "no hits". Treating an
+ * unreachable provider as a pass is how sanctioned money moves during an
+ * outage, and it is invisible afterwards because the trail says allowed. So an
+ * unavailable list refuses with a retryable status — the transfer waits rather
+ * than proceeding unscreened.
+ *
+ * ## What this deliberately does NOT do
+ *
+ * No list is bundled. A sanctions list embedded in a package is out of date the
+ * day it publishes, and being out of date is the only failure mode that
+ * matters. The provider is injected, and `staticList` exists for tests and for
+ * an operator's own denylist — never as the primary source.
+ */
+export declare class ComplianceError extends Error {
+    readonly code: 'LIST_UNAVAILABLE' | 'BAD_SUBJECT';
+    constructor(code: 'LIST_UNAVAILABLE' | 'BAD_SUBJECT', message: string);
+}
+export declare const RISK_LEVELS: readonly ["low", "medium", "high", "prohibited"];
+export type RiskLevel = (typeof RISK_LEVELS)[number];
+export declare const VERIFICATION_TIERS: readonly ["none", "basic", "verified", "enhanced"];
+export type VerificationTier = (typeof VERIFICATION_TIERS)[number];
+export interface Subject {
+    /** The account being screened. */
+    owner: string;
+    /** Counterparty address, for a transfer. */
+    address?: string;
+    network?: string;
+    /** Value in USD, so a threshold rule can fire. */
+    usdValue?: number;
+    direction?: 'deposit' | 'withdrawal';
+    /** How far the account has verified. Drives the tier rules. */
+    tier?: VerificationTier;
+    /** Anything a rule wants — country, name, date of birth. */
+    attributes?: Record<string, string>;
+}
+export interface ListEntry {
+    /** Address, name or identifier this entry matches. */
+    value: string;
+    kind: 'address' | 'name' | 'country';
+    /** Which list it came from — OFAC, an internal denylist, a chain analytics feed. */
+    source: string;
+    reason?: string;
+}
+export interface ScreeningList {
+    /** Bumped whenever the list content changes. Recorded on every verdict. */
+    readonly version: string;
+    /** Throws `ComplianceError('LIST_UNAVAILABLE')` rather than returning empty. */
+    match(subject: Subject): Promise<ListEntry[]>;
+}
+export interface RuleHit {
+    rule: string;
+    risk: RiskLevel;
+    detail: string;
+}
+export interface Rule {
+    name: string;
+    /** Returns a hit, or undefined when the rule does not fire. */
+    check(subject: Subject): RuleHit | undefined | Promise<RuleHit | undefined>;
+}
+/**
+ * A transfer above a threshold for the tier the account has reached.
+ *
+ * Tiered rather than one global limit, because the whole point of verification
+ * is that it raises what an account may move. A single threshold means either
+ * verified accounts are throttled or unverified ones are not.
+ */
+export declare const tierLimitRule: (limits: Partial<Record<VerificationTier, number>>) => Rule;
+/** A jurisdiction the platform will not serve. */
+export declare const countryRule: (prohibited: readonly string[]) => Rule;
+/**
+ * A deposit from an address that has never been seen, above a threshold.
+ *
+ * Weak on its own and useful in combination — it is the kind of signal that
+ * raises a transfer to review rather than refusing it, which is why it scores
+ * `medium` and not higher.
+ */
+export declare const newCounterpartyRule: (args: {
+    aboveUsd: number;
+    isKnown: (address: string) => boolean | Promise<boolean>;
+}) => Rule;
+export interface Verdict {
+    decision: 'allow' | 'review' | 'refuse';
+    risk: RiskLevel;
+    hits: RuleHit[];
+    listMatches: ListEntry[];
+    /** Which list version this was screened against. The auditable part. */
+    listVersion: string;
+    screenedAtMs: number;
+    subject: Subject;
+}
+export interface ScreenOptions {
+    list?: ScreeningList;
+    rules?: readonly Rule[];
+    /** At or above this, the transfer is held for a human rather than refused. */
+    reviewAt?: RiskLevel;
+    now?: () => number;
+}
+/**
+ * Screen a subject and produce a verdict.
+ *
+ * A list match is always `prohibited` — that is what a sanctions list means,
+ * and softening it to "high risk, review it" is the decision nobody should be
+ * able to make quietly in a config file. Rules can only ever raise the level
+ * arrived at, never lower it.
+ */
+export declare function screen(subject: Subject, options?: ScreenOptions): Promise<Verdict>;
+export interface StageOptions extends ScreenOptions {
+    /** Called for every verdict, allowed or not. The case record. */
+    record?: (verdict: Verdict) => void | Promise<void>;
+    /** Whether a `review` verdict has already been approved by a human. */
+    isApproved?: (subject: Subject) => boolean | Promise<boolean>;
+}
+/**
+ * The screening stage, shaped for `@forgezero/runtime/finance/transfers`.
+ *
+ * Drops into the seat that was reserved at order zero. Nothing else changes —
+ * which was the entire point of building the pipeline before the policy.
+ *
+ * EVERY verdict is recorded, including allowances. A trail of refusals answers
+ * "what did we stop" and not "what did we decide", and the second question is
+ * the one an auditor asks.
+ */
+export declare function screeningStage(options?: StageOptions): {
+    name: string;
+    order: number;
+    run(transfer: {
+        owner: string;
+        direction: "deposit" | "withdrawal";
+        address?: string;
+        network?: string;
+        amount: {
+            units: bigint;
+            asset: string;
+        };
+        context?: Record<string, unknown>;
+    }): Promise<{
+        screenedAtMs: number;
+        risk: "low" | "medium" | "high" | "prohibited";
+        listVersion: string;
+    }>;
+};
+/**
+ * A list held in memory.
+ *
+ * For tests, and for an operator's own denylist alongside a real feed — never
+ * as the primary source. A sanctions list bundled into a package is out of date
+ * the day it publishes, and being out of date is the only failure mode that
+ * matters here.
+ */
+export declare function staticList(entries: readonly ListEntry[], version?: string): ScreeningList;
+/** Combine several lists. Any one being unavailable fails the whole screen. */
+export declare function combineLists(...lists: readonly ScreeningList[]): ScreeningList;
+/** A list that is not configured yet. Refuses, so nothing runs unscreened by accident. */
+export declare const unavailableList: (reason: string) => ScreeningList;

package/dist/compliance.js

@@ -0,0 +1,168 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/compliance.ts
+import { Refusal } from "@forgezero/access";
+
+class ComplianceError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "ComplianceError";
+  }
+}
+var RISK_LEVELS = ["low", "medium", "high", "prohibited"];
+var VERIFICATION_TIERS = ["none", "basic", "verified", "enhanced"];
+var tierLimitRule = (limits) => ({
+  name: "tier.limit",
+  check(subject) {
+    const tier = subject.tier ?? "none";
+    const limit = limits[tier];
+    if (limit === undefined || subject.usdValue === undefined)
+      return;
+    if (subject.usdValue <= limit)
+      return;
+    return {
+      rule: "tier.limit",
+      risk: "high",
+      detail: `$${subject.usdValue} exceeds the $${limit} limit for a ${tier} account.`
+    };
+  }
+});
+var countryRule = (prohibited) => ({
+  name: "country.prohibited",
+  check(subject) {
+    const country = subject.attributes?.country?.toUpperCase();
+    if (!country || !prohibited.includes(country))
+      return;
+    return {
+      rule: "country.prohibited",
+      risk: "prohibited",
+      detail: `${country} is not served.`
+    };
+  }
+});
+var newCounterpartyRule = (args) => ({
+  name: "counterparty.new",
+  async check(subject) {
+    if (!subject.address || (subject.usdValue ?? 0) < args.aboveUsd)
+      return;
+    if (await args.isKnown(subject.address))
+      return;
+    return {
+      rule: "counterparty.new",
+      risk: "medium",
+      detail: `First transfer with ${subject.address.slice(0, 10)}… above $${args.aboveUsd}.`
+    };
+  }
+});
+var ORDER = { low: 0, medium: 1, high: 2, prohibited: 3 };
+var highest = (levels) => levels.reduce((worst, level) => ORDER[level] > ORDER[worst] ? level : worst, "low");
+async function screen(subject, options = {}) {
+  const now = options.now ?? Date.now;
+  if (!subject.owner) {
+    throw new ComplianceError("BAD_SUBJECT", "A subject needs an owner to screen.");
+  }
+  let listMatches = [];
+  let listVersion = "none";
+  if (options.list) {
+    listVersion = options.list.version;
+    listMatches = await options.list.match(subject);
+  }
+  const hits = [];
+  for (const rule of options.rules ?? []) {
+    const hit = await rule.check(subject);
+    if (hit)
+      hits.push(hit);
+  }
+  const risk = highest([
+    ...listMatches.length > 0 ? ["prohibited"] : [],
+    ...hits.map((hit) => hit.risk)
+  ]);
+  const reviewAt = options.reviewAt ?? "high";
+  const decision = risk === "prohibited" ? "refuse" : ORDER[risk] >= ORDER[reviewAt] ? "review" : "allow";
+  return { decision, risk, hits, listMatches, listVersion, screenedAtMs: now(), subject };
+}
+function screeningStage(options = {}) {
+  return {
+    name: "aml.screening",
+    order: 0,
+    async run(transfer) {
+      const subject = {
+        owner: transfer.owner,
+        address: transfer.address,
+        network: transfer.network,
+        direction: transfer.direction,
+        usdValue: Number(transfer.context?.usdValue ?? 0),
+        tier: transfer.context?.tier ?? "none",
+        attributes: transfer.context?.attributes
+      };
+      let verdict;
+      try {
+        verdict = await screen(subject, options);
+      } catch (cause) {
+        if (cause instanceof ComplianceError && cause.code === "LIST_UNAVAILABLE") {
+          throw new Refusal(503, "SCREENING_UNAVAILABLE", "Screening could not be completed. The transfer has not been processed.", {}, true);
+        }
+        throw cause;
+      }
+      await options.record?.(verdict);
+      if (verdict.decision === "refuse") {
+        throw new Refusal(451, "SCREENING_REFUSED", "This transfer cannot be processed.", {
+          risk: verdict.risk,
+          rules: verdict.hits.map((hit) => hit.rule).join(",")
+        });
+      }
+      if (verdict.decision === "review" && !await options.isApproved?.(subject)) {
+        throw new Refusal(409, "SCREENING_REVIEW", "This transfer is held for review.", { risk: verdict.risk }, true);
+      }
+      return { screenedAtMs: verdict.screenedAtMs, risk: verdict.risk, listVersion: verdict.listVersion };
+    }
+  };
+}
+function staticList(entries, version = "static-1") {
+  const byValue = new Map(entries.map((entry) => [entry.value.toLowerCase(), entry]));
+  return {
+    version,
+    async match(subject) {
+      const candidates = [subject.address, subject.attributes?.name, subject.attributes?.country].filter((value) => Boolean(value)).map((value) => value.toLowerCase());
+      return candidates.map((value) => byValue.get(value)).filter((entry) => entry !== undefined);
+    }
+  };
+}
+function combineLists(...lists) {
+  return {
+    version: lists.map((list) => list.version).join("+"),
+    async match(subject) {
+      const all = [];
+      for (const list of lists)
+        all.push(...await list.match(subject));
+      return all;
+    }
+  };
+}
+var unavailableList = (reason) => ({
+  version: "unavailable",
+  async match() {
+    throw new ComplianceError("LIST_UNAVAILABLE", reason);
+  }
+});
+export {
+  unavailableList,
+  tierLimitRule,
+  staticList,
+  screeningStage,
+  screen,
+  newCounterpartyRule,
+  countryRule,
+  combineLists,
+  VERIFICATION_TIERS,
+  RISK_LEVELS,
+  ComplianceError
+};

package/dist/finance/binance.d.ts

@@ -0,0 +1,27 @@
+import { VenueError, type VenueAdapter, type MarketType, type OrderStatus } from './venues';
+export interface BinanceCredentials {
+    apiKey: string;
+    apiSecret: string;
+}
+export interface BinanceOptions {
+    credentials: BinanceCredentials;
+    /** Override for testnet, or for a test. */
+    hosts?: Partial<Record<MarketType, string>>;
+    fetch?: typeof globalThis.fetch;
+    /**
+     * How far a request may be delayed before Binance refuses it.
+     *
+     * 5s rather than the 60s maximum. A signed order that arrives a minute late
+     * is an order placed into a market that has moved, and accepting it is worse
+     * than being told to retry.
+     */
+    recvWindowMs?: number;
+    now?: () => number;
+}
+/** Binance spells `BTC/USDT` as `BTCUSDT`. Denormalised here and nowhere else. */
+export declare const binanceSymbol: (symbol: string) => string;
+/** Binance statuses → ours. An unknown one is `rejected`, never silently `accepted`. */
+export declare function toOrderStatus(status: string): OrderStatus;
+export declare function createBinanceAdapter(options: BinanceOptions): VenueAdapter;
+/** Turn a Binance error into something that names the actual cause. */
+export declare function readBinanceError(error: unknown): VenueError | undefined;