@mandateops/audit 0.0.0-stage → 0.2.0

package/dist/providers/types.d.ts

@@ -0,0 +1,122 @@
+/** Terms a provider's request does not carry, declared once per test suite. */
+export type LedgerTerms = Readonly<{
+    tenant: string;
+    agent: string;
+    delegation: string;
+    account: string;
+    asset: string;
+    network: string;
+}>;
+/** For a format whose request names the paying account. */
+export type SourcedTerms = Omit<LedgerTerms, "account">;
+/** For a format that names no destination in its request. */
+export type OwnAccountTerms = LedgerTerms & Readonly<{
+    destination: string;
+}>;
+/** Bridge's request names the paying customer, the asset and the rail. */
+export type BridgeTerms = Omit<LedgerTerms, "account" | "asset" | "network">;
+/** Checkout names the paying entity but no currency. */
+export type CheckoutTerms = Omit<CurrencyTerms, "account">;
+/** Fireblocks' request names its asset and vault; the asset implies the network. */
+export type FireblocksTerms = Omit<LedgerTerms, "account" | "asset">;
+/** Mollie may leave out the amount, meaning the whole balance in `currency`. */
+export type MollieTerms = OwnAccountTerms & Readonly<{
+    currency: string;
+    wholeBalance: string;
+}>;
+/** For a format that names no currency in its request. */
+export type CurrencyTerms = LedgerTerms & Readonly<{
+    currency: string;
+}>;
+/** Wise's calls name the profile and target currency. */
+export type WiseTerms = Omit<LedgerTerms, "account" | "asset">;
+/** Terms a request may omit, and what absence means there. */
+export type TermDefaults = Readonly<Record<string, string>>;
+export type Reply = Readonly<{
+    status: number;
+    body: unknown;
+    headers?: Readonly<Record<string, string>>;
+}>;
+/** How a request body is encoded. */
+export type WireEncoding = "json" | "form";
+/** What a repeated key receives. */
+export type WireReplay = "same_reply" | "duplicate_reply";
+/** How a request proves its credential. */
+export type WireCredential = Readonly<{
+    header: string;
+    prefix: string;
+} | {
+    basic: true;
+} | {
+    signedJwt: true;
+    maxAgeSeconds?: number;
+}>;
+/** A narrower form a format requires of its key. */
+export type WireKeyShape = "uuid_v4" | "lowercase_slug";
+/** Where a request carries its idempotency key. */
+export type WireKey = Readonly<{
+    header: string;
+    maxLength?: number;
+} | {
+    field: string;
+    maxLength?: number;
+    optional?: boolean;
+    shape?: WireKeyShape;
+}>;
+/** A second amount field and the field naming what it is counted in. */
+export type WireAlternateAmount = Readonly<{
+    path: string;
+    currency: string;
+}>;
+/** How a decimal amount becomes minor units. */
+export type WireAmount = Readonly<{
+    minorDigits: number;
+} | {
+    scaleTerm: string;
+    scales: Readonly<Record<string, number>>;
+    networks?: Readonly<Record<string, readonly string[]>>;
+    /** Each token's EIP-55 contract, keyed `asset@network`. */
+    contracts?: Readonly<Record<string, string>>;
+    evmNetworks?: readonly string[];
+}>;
+/** Whether a declined key may be tried again, or its refusal stands. */
+export type WireRefusals = "retryable" | "final";
+/** The stand-in's declaration; `contracts/synthetic-provider.md` defines it. */
+export type ProviderWire = Readonly<{
+    path: string;
+    encoding?: WireEncoding;
+    jsonType?: string;
+    credential?: WireCredential;
+    key: WireKey;
+    fields: Readonly<Record<string, string>>;
+    joined?: Readonly<Record<string, readonly string[]>>;
+    defaults?: TermDefaults;
+    fixed: Readonly<Record<string, string>>;
+    urlFields?: Readonly<Record<string, string>>;
+    singleEntry?: readonly string[];
+    amount?: WireAmount;
+    amountDefault?: string;
+    alternateAmount?: WireAlternateAmount;
+    pegged?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    replay?: WireReplay;
+    refusals?: WireRefusals;
+    replies: Readonly<{
+        paid: Reply;
+        declined: Reply;
+        conflict: Reply;
+        duplicate?: Reply;
+    }>;
+}>;
+/** A format of several calls, which the stand-in holds as its own flow. */
+export type StagedWire = Readonly<{
+    flow: "wise";
+    fixed: WiseTerms;
+    scales: Readonly<Record<string, number>>;
+    routes: WiseRoutes;
+}>;
+/** Where Wise's three calls sit; a client with a dated base overrides them. */
+export type WiseRoutes = Readonly<{
+    quotes: string;
+    transfers: string;
+    fund: string;
+}>;

package/dist/providers/types.js

@@ -0,0 +1 @@
+export {};

package/dist/reading.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The adapter readings of a run, and the one place they are checked. The
+ * shape is `contracts/history-reading.md`; the host's mapping reads the same
+ * shape, and `contracts/history-reading.vectors.json` holds both to it.
+ */
+declare const STATES: readonly ["reserved", "executing", "unknown", "needs_review", "failed", "confirmed"];
+declare const RESULTS: readonly ["confirmed", "rejected", "unknown"];
+declare const ENDS: readonly ["response", "timeout", "connection_lost", "error_status", "invalid_response"];
+declare const INSTRUCTION_NAMES: readonly ["payment", "tenant", "agent", "delegation", "account", "destination", "currency", "asset", "network"];
+export type PayoutState = (typeof STATES)[number];
+export type AttemptResult = (typeof RESULTS)[number];
+export type AttemptEnd = (typeof ENDS)[number];
+/** Integer minor units as a decimal string, so no language loses precision. */
+export type MinorUnits = string;
+/** The payout's terms; `amount` is at least 1. */
+export type Instruction = Readonly<Record<(typeof INSTRUCTION_NAMES)[number], string> & {
+    amount: MinorUnits;
+}>;
+/** One movement of the payout's amount. */
+export type Flow = Readonly<{
+    amount: MinorUnits;
+    account: string;
+}>;
+export type HistoryEvent = Readonly<{
+    kind: "reserved";
+    flow: Flow;
+}> | Readonly<{
+    kind: "submitted";
+    attempt?: string | null;
+    key: string;
+    terms?: Instruction | null;
+}> | Readonly<{
+    kind: "outcome";
+    attempt?: string | null;
+    result: AttemptResult;
+    endedBy?: AttemptEnd | null;
+    effectId?: string | null;
+}> | Readonly<{
+    kind: "consumed";
+    effectId?: string | null;
+    flow: Flow;
+}> | Readonly<{
+    kind: "released";
+    flow: Flow;
+}> | Readonly<{
+    kind: "recovered";
+    attempt?: string | null;
+}> | Readonly<{
+    kind: "late_outcome";
+    attempt?: string | null;
+    effectId?: string | null;
+}>;
+export type Payout = Readonly<{
+    /** With the run's reference as `payment`. */
+    instruction: Instruction;
+    /** What the backend sends the provider as `payment`. */
+    providerPayment: string;
+    state: PayoutState;
+    /** Absent unless the backend reports it apart from the lifecycle. */
+    committed?: boolean | null;
+    attempts: number;
+    effectId?: string | null;
+}>;
+/** The order a history was read in. */
+export type HistoryConsistency = "commit_order" | "logging_order";
+/** Whether a capacity reading was taken at one instant. */
+export type CapacityConsistency = "atomic" | "non_atomic";
+/** A reading in commit order or stating otherwise; only commit order is usable. */
+export type HistoryReading = Readonly<{
+    source: "adapter";
+    units: "minor";
+    consistency: HistoryConsistency;
+    complete: boolean;
+    payout: Payout;
+    events: readonly HistoryEvent[];
+}>;
+export type CapacityReading = Readonly<{
+    source: "adapter";
+    units: "minor";
+    consistency: CapacityConsistency;
+    payoutsInScope: number;
+    available: MinorUnits;
+    committed: MinorUnits;
+    consumed: MinorUnits;
+}>;
+/** The profiles an adapter reading is taken under. */
+export type ReadingProfile = "payout-effects" | "payout-commitment";
+/**
+ * A reading the host could not interpret. `field` is its path in the reading
+ * and `expected` what belongs there. The value found is described by type
+ * only, since a reading may hold customer data.
+ */
+export declare class ReadingError extends TypeError {
+    readonly field: string;
+    readonly expected: string;
+    constructor(field: string, expected: string, found?: string);
+}
+/**
+ * Check an untrusted history reading against the contract.
+ *
+ * @throws {ReadingError} naming the first field that cannot be interpreted.
+ */
+export declare function parseHistoryReading(value: unknown): HistoryReading;
+/**
+ * Check an untrusted capacity reading against the contract.
+ *
+ * @throws {ReadingError} naming the first field that cannot be interpreted.
+ */
+export declare function parseCapacityReading(value: unknown): CapacityReading;
+/**
+ * Check a well-formed reading against its run: it is of `reference`, and a
+ * commitment was held before anything was sent, which `profile` models.
+ *
+ * @throws {ReadingError} when it does not fit.
+ */
+export declare function requireHistoryFits(reading: HistoryReading, reference: string, profile: ReadingProfile): void;
+export {};

package/dist/reading.js

@@ -0,0 +1,280 @@
+/**
+ * The adapter readings of a run, and the one place they are checked. The
+ * shape is `contracts/history-reading.md`; the host's mapping reads the same
+ * shape, and `contracts/history-reading.vectors.json` holds both to it.
+ */
+const STATES = [
+    "reserved",
+    "executing",
+    "unknown",
+    "needs_review",
+    "failed",
+    "confirmed",
+];
+const RESULTS = ["confirmed", "rejected", "unknown"];
+const ENDS = [
+    "response",
+    "timeout",
+    "connection_lost",
+    "error_status",
+    "invalid_response",
+];
+const KINDS = [
+    "reserved",
+    "submitted",
+    "outcome",
+    "consumed",
+    "released",
+    "recovered",
+    "late_outcome",
+];
+const INSTRUCTION_NAMES = [
+    "payment",
+    "tenant",
+    "agent",
+    "delegation",
+    "account",
+    "destination",
+    "currency",
+    "asset",
+    "network",
+];
+const MINOR_UNITS = /^(0|[1-9][0-9]*)$/;
+/** The host's amounts are 128 bits wide. */
+const MAX_AMOUNT = 2n ** 128n - 1n;
+const MAX_ATTEMPTS = 2 ** 32 - 1;
+/** How many lifecycle events the host reads from one history. */
+const MAX_EVENTS = 200;
+/**
+ * A reading the host could not interpret. `field` is its path in the reading
+ * and `expected` what belongs there. The value found is described by type
+ * only, since a reading may hold customer data.
+ */
+export class ReadingError extends TypeError {
+    field;
+    expected;
+    constructor(field, expected, found) {
+        super(`${field}: expected ${expected}${found === undefined ? "" : `, found ${found}`}`);
+        this.field = field;
+        this.expected = expected;
+        this.name = "ReadingError";
+    }
+}
+const describe = (value) => {
+    if (value === undefined)
+        return "nothing";
+    if (value === null)
+        return "null";
+    return Array.isArray(value) ? "an array" : `a ${typeof value}`;
+};
+const refuse = (field, expected, value) => {
+    throw new ReadingError(field, expected, describe(value));
+};
+const quoted = (allowed) => `one of ${allowed.map((name) => `"${name}"`).join(", ")}`;
+const at = (parent, name) => parent === "" ? name : `${parent}.${name}`;
+/** `value` as an object holding only `allowed` members. */
+function members(value, field, allowed) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return refuse(field || "reading", `an object`, value);
+    }
+    const unknown = Object.keys(value).find((name) => !allowed.includes(name));
+    if (unknown !== undefined) {
+        throw new ReadingError(at(field, unknown), `no such member: the members here are ${allowed.join(", ")}`);
+    }
+    return value;
+}
+function requireText(value, field) {
+    if (typeof value !== "string")
+        refuse(field, "a string", value);
+}
+function requireOneOf(allowed, value, field) {
+    if (typeof value !== "string" || !allowed.includes(value)) {
+        refuse(field, quoted(allowed), value);
+    }
+}
+function requireExactly(wanted, value, field) {
+    if (value !== wanted)
+        refuse(field, `"${wanted}"`, value);
+}
+function requireUnits(value, field, least) {
+    const expected = `a canonical decimal string of minor units, at least ${String(least)}, such as "10000"`;
+    if (typeof value !== "string" || !MINOR_UNITS.test(value)) {
+        refuse(field, expected, value);
+        return;
+    }
+    const units = BigInt(value);
+    if (units < least || units > MAX_AMOUNT)
+        refuse(field, expected, "a string");
+}
+/** Absent and `null` both mean the backend did not record it. */
+const recorded = (value) => value !== undefined && value !== null;
+function optionalText(value, field) {
+    if (recorded(value) && typeof value !== "string") {
+        refuse(field, "a string, null or nothing", value);
+    }
+}
+function requireInstruction(value, field) {
+    const found = members(value, field, [...INSTRUCTION_NAMES, "amount"]);
+    for (const name of INSTRUCTION_NAMES) {
+        requireText(found[name], at(field, name));
+    }
+    requireUnits(found["amount"], at(field, "amount"), 1n);
+}
+function requireFlow(value, field) {
+    const found = members(value, field, ["amount", "account"]);
+    requireUnits(found["amount"], at(field, "amount"), 0n);
+    requireText(found["account"], at(field, "account"));
+}
+function requirePayout(value) {
+    const found = members(value, "payout", [
+        "instruction",
+        "providerPayment",
+        "state",
+        "committed",
+        "attempts",
+        "effectId",
+    ]);
+    requireInstruction(found["instruction"], "payout.instruction");
+    requireText(found["providerPayment"], "payout.providerPayment");
+    requireOneOf(STATES, found["state"], "payout.state");
+    const { committed, attempts } = found;
+    if (recorded(committed) && typeof committed !== "boolean") {
+        refuse("payout.committed", "a boolean, null or nothing", committed);
+    }
+    if (!Number.isInteger(attempts) ||
+        attempts < 0 ||
+        attempts > MAX_ATTEMPTS) {
+        refuse("payout.attempts", "the number of attempts as an integer", attempts);
+    }
+    optionalText(found["effectId"], "payout.effectId");
+}
+function requireEvent(value, field) {
+    const kind = value?.["kind"];
+    requireOneOf(KINDS, kind, at(field, "kind"));
+    switch (kind) {
+        case "reserved":
+        case "released": {
+            const found = members(value, field, ["kind", "flow"]);
+            requireFlow(found["flow"], at(field, "flow"));
+            return;
+        }
+        case "submitted": {
+            const found = members(value, field, ["kind", "attempt", "key", "terms"]);
+            optionalText(found["attempt"], at(field, "attempt"));
+            requireText(found["key"], at(field, "key"));
+            if (recorded(found["terms"])) {
+                requireInstruction(found["terms"], at(field, "terms"));
+            }
+            return;
+        }
+        case "outcome": {
+            const found = members(value, field, [
+                "kind",
+                "attempt",
+                "result",
+                "endedBy",
+                "effectId",
+            ]);
+            optionalText(found["attempt"], at(field, "attempt"));
+            requireOneOf(RESULTS, found["result"], at(field, "result"));
+            if (recorded(found["endedBy"])) {
+                requireOneOf(ENDS, found["endedBy"], at(field, "endedBy"));
+            }
+            optionalText(found["effectId"], at(field, "effectId"));
+            return;
+        }
+        case "consumed": {
+            const found = members(value, field, ["kind", "effectId", "flow"]);
+            optionalText(found["effectId"], at(field, "effectId"));
+            requireFlow(found["flow"], at(field, "flow"));
+            return;
+        }
+        case "recovered": {
+            const found = members(value, field, ["kind", "attempt"]);
+            optionalText(found["attempt"], at(field, "attempt"));
+            return;
+        }
+        case "late_outcome": {
+            const found = members(value, field, ["kind", "attempt", "effectId"]);
+            optionalText(found["attempt"], at(field, "attempt"));
+            optionalText(found["effectId"], at(field, "effectId"));
+        }
+    }
+}
+/**
+ * Check an untrusted history reading against the contract.
+ *
+ * @throws {ReadingError} naming the first field that cannot be interpreted.
+ */
+export function parseHistoryReading(value) {
+    const found = members(value, "", [
+        "source",
+        "units",
+        "consistency",
+        "complete",
+        "payout",
+        "events",
+    ]);
+    requireExactly("adapter", found["source"], "source");
+    requireExactly("minor", found["units"], "units");
+    requireExactly("commit_order", found["consistency"], "consistency");
+    if (typeof found["complete"] !== "boolean") {
+        refuse("complete", "a boolean", found["complete"]);
+    }
+    requirePayout(found["payout"]);
+    const { events } = found;
+    if (!Array.isArray(events) || events.length > MAX_EVENTS) {
+        return refuse("events", `an array of at most ${String(MAX_EVENTS)} events`, events);
+    }
+    events.forEach((event, position) => {
+        requireEvent(event, `events[${String(position)}]`);
+    });
+    return value;
+}
+/**
+ * Check an untrusted capacity reading against the contract.
+ *
+ * @throws {ReadingError} naming the first field that cannot be interpreted.
+ */
+export function parseCapacityReading(value) {
+    const found = members(value, "", [
+        "source",
+        "units",
+        "consistency",
+        "payoutsInScope",
+        "available",
+        "committed",
+        "consumed",
+    ]);
+    requireExactly("adapter", found["source"], "source");
+    requireExactly("minor", found["units"], "units");
+    requireExactly("atomic", found["consistency"], "consistency");
+    const scope = found["payoutsInScope"];
+    if (!Number.isInteger(scope) ||
+        scope < 0 ||
+        scope > MAX_ATTEMPTS) {
+        refuse("payoutsInScope", "the number of payouts as an integer", scope);
+    }
+    for (const name of ["available", "committed", "consumed"]) {
+        requireUnits(found[name], name, 0n);
+    }
+    return value;
+}
+/**
+ * Check a well-formed reading against its run: it is of `reference`, and a
+ * commitment was held before anything was sent, which `profile` models.
+ *
+ * @throws {ReadingError} when it does not fit.
+ */
+export function requireHistoryFits(reading, reference, profile) {
+    const payment = reading.payout.instruction.payment;
+    if (payment !== reference) {
+        throw new ReadingError("payout.instruction.payment", `the run's reference "${reference}"`, "another payout's");
+    }
+    const kinds = reading.events.map((event) => event.kind);
+    const submitted = kinds.indexOf("submitted");
+    const reserved = kinds.indexOf("reserved");
+    if (submitted >= 0 && (reserved < 0 || reserved > submitted)) {
+        throw new ReadingError("events", `a "reserved" event before the first "submitted": ${profile} cannot be used by a backend without reservations; use payout-effects-only`);
+    }
+}

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@mandateops/audit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Write audit tests that check a payout backend keeps one payment identity, money limits and commitments when a provider commits but the reply is lost. Needs the mandateops CLI.",
+  "license": "Apache-2.0",
+  "homepage": "https://getmandateops.com",
+  "keywords": [
+    "payments",
+    "payouts",
+    "idempotency",
+    "testing",
+    "fault-injection",
+    "audit"
+  ],
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "packageManager": "bun@1.4.4",
+  "engines": {
+    "node": ">=22",
+    "bun": ">=1.4.4"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./bun": {
+      "types": "./dist/bun.d.ts",
+      "default": "./dist/bun.js"
+    }
+  },
+  "peerDependencies": {
+    "@types/bun": ">=1.4.4"
+  },
+  "peerDependenciesMeta": {
+    "@types/bun": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun --bun run tsc --project tsconfig.build.json",
+    "lint": "bun --bun run eslint . --max-warnings 0",
+    "typecheck": "bun --bun run tsc --noEmit",
+    "format:check": "bun --bun run prettier --check .",
+    "test": "bun test ./test/reading.test.ts ./test/session.test.ts ./test/index.test.ts ./test/bun.test.ts ./test/vectors.test.ts ./scripts/gates.test.mjs",
+    "test:audit": "bun test ./audit/remit.audit.test.ts ./audit/settle.audit.test.ts ./audit/effects-only.audit.test.ts ./audit/hostile.audit.test.ts ./audit/paystack.audit.test.ts ./audit/bridge.audit.test.ts ./audit/circle.audit.test.ts ./audit/fireblocks.audit.test.ts ./audit/stripe.audit.test.ts ./audit/wise.audit.test.ts --timeout 400000",
+    "check": "bun run format:check && bun run lint && bun run typecheck && bun run test",
+    "prepublishOnly": "bun run check && bun run build"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.4",
+    "@types/node": "26.6.6",
+    "eslint": "10.14.0",
+    "parse-diff": "0.12.0",
+    "prettier": "3.9.10",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.72.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}