@mandateops/audit 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,532 @@
+/**
+ * Thin client of a `mandateops session` host. It carries declarations and
+ * readings; the host owns the deployment, faults and effect records, and the
+ * Rust checker alone decides results.
+ *
+ * Uses Node's standard modules only, so `auditRun` runs under Node or Bun and
+ * any test runner on them. `./bun` adds `auditTest` for Bun's own runner.
+ */
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { parseCapacityReading, parseHistoryReading, requireHistoryFits, } from "./reading.js";
+export { bridge, circleMint, adyen, airwallex, checkout, dwolla, fireblocks, flutterwave, modernTreasury, molliePayouts, paypal, paystack, peach, razorpayx, revolut, stitch, stripePayouts, stripeTransfers, wise, } from "./providers/index.js";
+export { parseCapacityReading, parseHistoryReading, ReadingError, requireHistoryFits, } from "./reading.js";
+const MINOR_UNITS = /^[1-9][0-9]*$/;
+/**
+ * The largest amount the stand-in holds, the audit core's `u128` maximum.
+ * `fixtures/wire/vectors.json` pins it for every reader.
+ */
+export const SYNTHETIC_MAX_MINOR_UNITS = 340282366920938463463374607431768211455n;
+const MESSAGE_LIMIT_CHARS = 2000;
+/** How long an aborted body may take to stop, unless the config says. */
+const DEFAULT_ABORT_GRACE_MS = 1000;
+/** Integer minor units as a decimal string, so no language loses precision. */
+export function minorUnits(value) {
+    if (!MINOR_UNITS.test(value)) {
+        throw new TypeError("amountMinor must be a canonical decimal string");
+    }
+    if (BigInt(value) > SYNTHETIC_MAX_MINOR_UNITS) {
+        throw new RangeError("amountMinor is more than the provider can hold");
+    }
+    return value;
+}
+const PROPERTIES = [
+    "instruction_binding",
+    "commitment_retention",
+    "retry_identity",
+    "effect_within_authorisation",
+    "reconciliation_consistency",
+    "external_outcome",
+];
+const PROPERTY_RESULTS = [
+    "satisfied",
+    "violated",
+    "inconclusive",
+    "not_applicable",
+];
+const ASSURANCES = [
+    "backend_and_provider",
+    "backend_and_provider_commitments_not_checked",
+    "money_out_only_commitments_not_checked",
+    "no_assurance",
+];
+export const defineAdapter = (adapter) => adapter;
+export const defineConfig = (config) => config;
+/** The test body failed. The run is sealed and `result` records it. */
+export class AuditTestFailure extends Error {
+    result;
+    cause;
+    constructor(result, cause) {
+        super(`test body failed in ${result.run_id}: ${String(cause)}`);
+        this.result = result;
+        this.cause = cause;
+    }
+}
+/** The SDK was used against its contract; the message says how to correct it. */
+export class AuditUsageError extends Error {
+    name = "AuditUsageError";
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * The session protocol this SDK speaks. The host announces its own when
+ * ready; the two must match, as they do for an SDK shipped with its CLI.
+ */
+export const SESSION_PROTOCOL = 2;
+/** Why a host of another protocol is refused, and how to fix it. */
+export function protocolMismatch(announced) {
+    const host = announced === undefined
+        ? "an older protocol"
+        : `protocol ${String(announced)}`;
+    return `the mandateops CLI speaks ${host} and this SDK speaks protocol ${String(SESSION_PROTOCOL)}: add the SDK shipped with your CLI (sdk/mandateops-audit-VERSION.tgz in its install) with \`bun add\``;
+}
+/** A line from the host, or `undefined` for one this client cannot trust. */
+function parseReply(line) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(value))
+        return undefined;
+    const { id, ok, error, ready, backend, credentials, protocol } = value;
+    const limit = value["reply_limit_ms"];
+    const recovery = value["recover_command"];
+    const terminal = value["terminal"];
+    const typed = (id === undefined || typeof id === "number") &&
+        (ok === undefined || typeof ok === "boolean") &&
+        (error === undefined || typeof error === "string") &&
+        (ready === undefined || typeof ready === "boolean") &&
+        (protocol === undefined || isPositiveInteger(protocol)) &&
+        (backend === undefined || typeof backend === "string") &&
+        (credentials === undefined || isCredentials(credentials)) &&
+        (limit === undefined || isPositiveInteger(limit)) &&
+        (recovery === undefined || typeof recovery === "string") &&
+        (terminal === undefined || typeof terminal === "boolean");
+    return typed ? value : undefined;
+}
+const isPositiveInteger = (value) => Number.isSafeInteger(value) && value > 0;
+const isCredentials = (value) => isRecord(value) &&
+    ["client", "operator", "viewer"].every((name) => typeof value[name] === "string" && value[name] !== "");
+const isOneOf = (allowed, value) => typeof value === "string" && allowed.includes(value);
+const isDecision = (value) => isRecord(value) &&
+    isOneOf(PROPERTIES, value["property"]) &&
+    isOneOf(PROPERTY_RESULTS, value["result"]) &&
+    typeof value["required"] === "boolean";
+const isFinding = (value) => isRecord(value) && typeof value["rule"] === "string";
+const isVerdict = (value) => isRecord(value) &&
+    typeof value["verdict"] === "string" &&
+    (value["findings"] === undefined ||
+        (Array.isArray(value["findings"]) && value["findings"].every(isFinding))) &&
+    (value["reasons"] === undefined || Array.isArray(value["reasons"]));
+/** A sealed result, checked before anything reads it. */
+export function parseResult(value) {
+    const valid = isRecord(value) &&
+        typeof value["run_id"] === "string" &&
+        typeof value["ci_passed"] === "boolean" &&
+        isOneOf(ASSURANCES, value["assurance"]) &&
+        (value["assumption"] === undefined ||
+            typeof value["assumption"] === "string") &&
+        Array.isArray(value["properties"]) &&
+        value["properties"].every(isDecision) &&
+        isVerdict(value["verdict"]) &&
+        typeof value["record_published"] === "boolean";
+    if (!valid)
+        throw new TypeError("audit host sealed a result this SDK cannot read; the @mandateops/audit package and the mandateops CLI are probably different versions: add the SDK shipped with your CLI (its sdk/mandateops-audit-VERSION.tgz)");
+    return value;
+}
+/** A line protocol client; one request in flight at a time per caller. */
+class Channel {
+    host;
+    buffered = "";
+    nextId = 1;
+    waiting = new Map();
+    announced;
+    /** The host announces it; nothing is sent before it has. */
+    replyLimitMs = 0;
+    /** The first reply ending the channel: after it, nothing more will answer. */
+    terminal;
+    ready;
+    constructor(host) {
+        this.host = host;
+        // A host that dies mid-write ends stdout too, and `read` reports that.
+        host.stdin.on("error", () => { });
+        this.ready = new Promise((settle) => {
+            this.announced = settle;
+        });
+        // A program that never started has no stream to read.
+        this.read().catch(() => {
+            this.settleAll({ ok: false, error: "host_stopped" });
+        });
+    }
+    settleAll(reply) {
+        this.terminal ??= reply;
+        this.announced?.(reply);
+        for (const settle of this.waiting.values())
+            settle(reply);
+    }
+    accept(line) {
+        const reply = parseReply(line);
+        if (!reply) {
+            this.settleAll({ ok: false, error: "unreadable_reply" });
+            return;
+        }
+        if (reply.ready) {
+            this.replyLimitMs = reply.reply_limit_ms ?? 0;
+            this.announced?.(reply);
+        }
+        else if (reply.id !== undefined)
+            this.waiting.get(reply.id)?.(reply);
+        else if (reply.terminal)
+            this.settleAll(reply);
+        // Refused one unreadable message: its caller stops, the channel stays open.
+        else
+            for (const settle of this.waiting.values())
+                settle(reply);
+    }
+    async read() {
+        const decoder = new TextDecoder();
+        for await (const chunk of this.host.stdout) {
+            this.buffered += decoder.decode(chunk, { stream: true });
+            for (;;) {
+                const end = this.buffered.indexOf("\n");
+                if (end < 0)
+                    break;
+                const line = this.buffered.slice(0, end);
+                this.buffered = this.buffered.slice(end + 1);
+                this.accept(line);
+            }
+        }
+        this.settleAll({ ok: false, error: "host_stopped" });
+    }
+    async send(message) {
+        if (this.terminal)
+            throw new Error(`audit host refused: ${String(this.terminal.error)}`);
+        const id = this.nextId;
+        this.nextId += 1;
+        let timer;
+        const answered = new Promise((settle) => {
+            this.waiting.set(id, settle);
+            timer = setTimeout(() => {
+                settle({ ok: false, error: "reply_timed_out" });
+            }, this.replyLimitMs);
+        });
+        this.host.stdin.write(`${JSON.stringify({ id, ...message })}\n`);
+        const reply = await answered;
+        clearTimeout(timer);
+        this.waiting.delete(id);
+        if (!reply.ok)
+            throw new Error(`audit host refused: ${String(reply.error)}`);
+        return reply.body;
+    }
+}
+/**
+ * The whole run, for a test runner's own timeout: startup, the body, closing
+ * work on either side of the longest wait, and teardown, which may take as
+ * long as startup. The host enforces each bound; this only stays above them.
+ */
+export const runLimit = (config) => config.system.startupTimeoutS * 2000 +
+    config.testBudgetMs +
+    Math.max(config.drainBoundMs, config.system.faultDeadlineMs) * 2;
+/** Profiles judged on backend readings; the other is on provider records alone. */
+const readingProfile = (config) => config.financialProfile === "payout-effects-only"
+    ? undefined
+    : config.financialProfile;
+/**
+ * Refuses, before anything starts, a run that could only end inconclusive.
+ *
+ * @throws {AuditUsageError} when the profile and adapter do not go together.
+ */
+export function requireRunnable(config) {
+    const profile = readingProfile(config);
+    if (profile === undefined && config.adapter) {
+        throw new AuditUsageError("payout-effects-only is judged on provider records alone: remove the adapter");
+    }
+    if (profile !== undefined && !config.adapter) {
+        throw new AuditUsageError(`${profile} needs an adapter with history and capacity readings ` +
+            "(contracts/history-reading.md). A backend without reservations or " +
+            "capacity cannot use it; use payout-effects-only");
+    }
+}
+function spawnHost(config, runId, systemFile) {
+    const compose = resolve(config.system.compose);
+    const system = {
+        ...config.system,
+        compose,
+        projectDirectory: resolve(config.system.projectDirectory ?? dirname(compose)),
+    };
+    // A file only its owner reads: declared values stay out of process listings.
+    writeFileSync(systemFile, JSON.stringify(system), { mode: 0o600 });
+    const [command, ...leading] = hostProgram(config);
+    return spawn(command, [
+        ...leading,
+        "session",
+        "--system-file",
+        systemFile,
+        "--run-id",
+        runId,
+        "--runs-dir",
+        runsDirectoryOf(config),
+        "--financial-profile",
+        config.financialProfile,
+        "--drain-ms",
+        String(config.drainMs),
+        "--drain-bound-ms",
+        String(config.drainBoundMs),
+        "--host-program",
+        JSON.stringify(hostProgram(config)),
+        "--provider",
+        config.provider,
+    ], { stdio: ["pipe", "pipe", "inherit"] });
+}
+/** Settles when the host is gone, including one that never started. */
+const hostGone = (host) => new Promise((settle) => {
+    host.once("error", () => {
+        settle(null);
+    });
+    host.once("close", (code) => {
+        settle(code);
+    });
+});
+export function wireInstruction(expected) {
+    const { reference, amountMinor, outcome: _declared, ...scope } = expected;
+    return { payment: reference, ...scope, amount: minorUnits(amountMinor) };
+}
+const FAULT_STAGE_MEANS = {
+    none: "no fault is armed; call loseResponseAfterCommit first",
+    armed: "a fault is already armed; release it first",
+    established: "a fault is already armed; release it first",
+    released: "the fault was already released; arm another first",
+};
+/**
+ * Run one audited test and return the recorded result without judging it. A
+ * body that fails still seals the run, then rejects with [`AuditTestFailure`].
+ */
+export async function auditRun(config, body, runId = `sdk-${randomUUID().slice(0, 18)}`) {
+    requireRunnable(config);
+    const declared = mkdtempSync(join(tmpdir(), "audit-system-"));
+    const host = spawnHost(config, runId, join(declared, "system.json"));
+    const gone = hostGone(host);
+    const channel = new Channel(host);
+    try {
+        const announced = await channel.ready;
+        if (announced.ready && announced.protocol !== SESSION_PROTOCOL) {
+            throw new Error(protocolMismatch(announced.protocol));
+        }
+        if (!announced.backend ||
+            !announced.credentials ||
+            !announced.reply_limit_ms ||
+            !announced.recover_command) {
+            throw new Error(`audit host did not start: ${announced.error ?? "incomplete_announcement"}`);
+        }
+        const result = await session(config, body, channel, announced.backend, announced.credentials);
+        return afterTeardown(result, await gone, announced.recover_command);
+    }
+    finally {
+        // End of input: a host that has not sealed recovers what it has.
+        host.stdin.end();
+        await gone;
+        rmSync(declared, { recursive: true, force: true });
+    }
+}
+/** Where runs are written: the config, else `MANDATEOPS_RUNS_DIR` (set by the
+ * GitHub Action), else `runs` in the working directory. */
+const runsDirectoryOf = (config) => resolve(config.runsDirectory ?? (process.env["MANDATEOPS_RUNS_DIR"] || "runs"));
+/** What this config runs as the host, ahead of a subcommand. */
+const hostProgram = (config) => {
+    const [command = "mandateops", ...leading] = config.hostCommand ?? [];
+    return [command, ...leading];
+};
+/** A seal precedes teardown, so a pass stands only if the host then exits clean. */
+const afterTeardown = (result, exit, recoverCommand) => result.ci_passed && exit !== 0
+    ? {
+        ...result,
+        ci_passed: false,
+        assurance: "no_assurance",
+        teardown_failure: { recover_command: recoverCommand },
+    }
+    : result;
+async function session(config, body, channel, backend, credentials) {
+    const viewerCredential = credentials.viewer;
+    const profile = readingProfile(config);
+    let providerPayment;
+    let authorised;
+    let fault = "none";
+    const problems = [];
+    /** Closed when the body ends: a timed-out body cannot speak during capture. */
+    let bodyOpen = true;
+    const fromBody = async (message) => {
+        if (!bodyOpen)
+            throw new Error("the test body already ended");
+        return channel.send(message);
+    };
+    const reading = async (slot, read) => {
+        let taken;
+        try {
+            taken = await read();
+        }
+        catch (error) {
+            const reason = String(error).slice(0, MESSAGE_LIMIT_CHARS);
+            problems.push({ slot, reason });
+            console.error(`audit reading ${slot} refused: ${reason}`);
+            await channel.send({ type: "reading_failed", slot, reason });
+            return;
+        }
+        await channel.send({ type: "reading", slot, body: taken });
+    };
+    const context = () => providerPayment === undefined
+        ? undefined
+        : { backend, viewerCredential, providerPayment };
+    const readHistory = async (slot) => {
+        const read = context();
+        if (config.adapter && profile && read && authorised) {
+            const { history } = config.adapter;
+            const reference = authorised.expected.reference;
+            await reading(slot, async () => {
+                const taken = parseHistoryReading(await history(read));
+                requireHistoryFits(taken, reference, profile);
+                return taken;
+            });
+        }
+    };
+    const readCapacity = async (slot) => {
+        const read = context();
+        const capacity = config.adapter?.capacity;
+        if (capacity && read) {
+            await reading(slot, async () => parseCapacityReading(await capacity(read)));
+        }
+    };
+    const requireBound = (doing) => {
+        if (profile && authorised && providerPayment === undefined) {
+            throw new AuditUsageError(`${doing} under ${profile} needs bindProviderPayment first: adapters read by that identifier`);
+        }
+    };
+    const requireFault = (doing, stages) => {
+        if (!bodyOpen)
+            throw new Error("the test body already ended");
+        if (!stages.includes(fault)) {
+            throw new AuditUsageError(`${doing}: ${FAULT_STAGE_MEANS[fault]}`);
+        }
+    };
+    const budgetSpent = new AbortController();
+    const fixture = {
+        signal: budgetSpent.signal,
+        app: backend,
+        credentials,
+        provider: {
+            expectPayment: async (expected) => {
+                await fromBody({
+                    type: "authorise",
+                    authorisation: {
+                        instruction: wireInstruction(expected),
+                        capacity_limit: minorUnits(config.capacityLimitMinor),
+                        provider: {
+                            account: config.system.providerTerms.account,
+                            operation: config.system.providerTerms.operation,
+                            idempotency_scope: config.system.providerTerms.idempotencyScope,
+                        },
+                        ...(expected.outcome ? { expected_outcome: expected.outcome } : {}),
+                    },
+                });
+                authorised = {
+                    expected,
+                    bindProviderPayment: async (payment) => {
+                        await fromBody({ type: "bind_provider_payment", payment });
+                        providerPayment = payment;
+                    },
+                };
+                return authorised;
+            },
+        },
+        faults: {
+            loseResponseAfterCommit: async ({ payment, mode }) => {
+                requireFault("loseResponseAfterCommit", ["none", "released"]);
+                if (payment !== authorised) {
+                    throw new AuditUsageError("loseResponseAfterCommit: payment must be what expectPayment returned");
+                }
+                await fromBody({ type: "arm_fault", kind: mode });
+                fault = "armed";
+            },
+            established: async () => {
+                requireFault("established", ["armed", "established"]);
+                await fromBody({ type: "await_fault" });
+                fault = "established";
+            },
+            release: async () => {
+                requireFault("release", ["armed", "established"]);
+                await fromBody({ type: "release_fault" });
+                fault = "released";
+            },
+            refuseNext: async () => {
+                await fromBody({ type: "refuse_next" });
+            },
+        },
+        inspect: async () => {
+            if (!bodyOpen)
+                throw new Error("the test body already ended");
+            requireBound("inspect");
+            await readHistory("inspect_history");
+            await readCapacity("inspect_capacity");
+            await readHistory("reinspect_history");
+        },
+    };
+    let status = "passed";
+    let failure;
+    let timer;
+    const running = body(fixture).then(() => {
+        requireBound("a test");
+    });
+    try {
+        await Promise.race([
+            running,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    status = "timed_out";
+                    budgetSpent.abort();
+                    reject(new Error("test budget exceeded"));
+                }, config.testBudgetMs);
+            }),
+        ]);
+    }
+    catch (error) {
+        if (status === "passed")
+            status = "threw";
+        failure = error;
+    }
+    finally {
+        clearTimeout(timer);
+        bodyOpen = false;
+    }
+    if (status === "timed_out") {
+        await Promise.race([
+            running.catch(() => { }),
+            sleep(config.abortGraceMs ?? DEFAULT_ABORT_GRACE_MS, undefined, {
+                ref: false,
+            }),
+        ]);
+    }
+    await channel.send({
+        type: "test_ended",
+        status,
+        ...(status === "passed"
+            ? {}
+            : { message: String(failure).slice(0, MESSAGE_LIMIT_CHARS) }),
+    });
+    await channel.send({ type: "drain" });
+    await readHistory("capture_history");
+    await readCapacity("capture_capacity");
+    await channel.send({ type: "read_effects" });
+    await readHistory("recapture_history");
+    const result = {
+        ...parseResult(await channel.send({ type: "seal" })),
+        reading_problems: problems,
+    };
+    if (status !== "passed")
+        throw new AuditTestFailure(result, failure);
+    return result;
+}

package/dist/providers/common.d.ts

@@ -0,0 +1,9 @@
+import type { Reply } from "./types.js";
+/**
+ * An empty body marks a failure whose body the provider does not document, and
+ * its status is then the conservative choice. OAuth token calls are not
+ * imitated: a client of such a provider must hold its bearer token directly.
+ */
+export declare const undocumented: (status: number) => Reply;
+export declare const CREATED_AT = "2026-01-01T00:00:00Z";
+export declare const CREATED_UNIX = 1767225600;

package/dist/providers/common.js

@@ -0,0 +1,8 @@
+/**
+ * An empty body marks a failure whose body the provider does not document, and
+ * its status is then the conservative choice. OAuth token calls are not
+ * imitated: a client of such a provider must hold its bearer token directly.
+ */
+export const undocumented = (status) => ({ status, body: {} });
+export const CREATED_AT = "2026-01-01T00:00:00Z";
+export const CREATED_UNIX = 1_767_225_600;

package/dist/providers/crypto.d.ts

@@ -0,0 +1,36 @@
+import type { BridgeTerms, FireblocksTerms, LedgerTerms, ProviderWire } from "./types.js";
+/**
+ * `POST /v0/transfers`, USDC out on the rail the request names. `amount` is in
+ * the source currency if fiat, else the fiat it pegs, so a USDC source reads at
+ * USD scale while staying its own term; `destination.amount` is in the destination currency, with the term
+ * written `usdc-from-eur` so what funds it stays bound, and giving both is
+ * refused. The source currencies listed are unverified. A new transfer
+ * starts `awaiting_funds`; later states are not imitated. Bridge replays the
+ * original for a key for 24 hours and errors on a changed body; that error's
+ * status and body are unverified, and 400 is the listed status that fits.
+ * `client_reference_id` is optional, so the payment then takes the key.
+ */
+export declare const bridge: (terms: BridgeTerms) => ProviderWire;
+/**
+ * `POST /v1/businessAccount/transfers`, USDC only, written as currency `USD`.
+ * The destination is a registered address id, whose chain Circle looks up, so
+ * asset and network are declared. `source.id` names the paying wallet;
+ * `account` is what its absence means. The reply's `{ data }` wrapper is
+ * documented, and a failure is a 201 with `status: failed`. The key must be a
+ * UUID v4. The repeat-key reply, behaviour on a changed body and the scale of
+ * six are unverified.
+ */
+export declare const circleMint: ({ account, ...terms }: LedgerTerms) => ProviderWire;
+/**
+ * `POST /v1/transactions`, USDC and ETH to a one-time address from a vault,
+ * signed per request. Fireblocks keys transactions on `externalTxId` and
+ * refuses a reused one with 400, so a retrying client must read that as already
+ * sent. A refused id stays refused. The network is declared and must be the one
+ * the asset implies; only the assets listed are supported. A
+ * reply of `SUBMITTED` is not completion. A create answers 200. Failure bodies
+ * follow the documented `{ message, code }`; their messages are unverified.
+ * Sources disagree on whether `externalTxId` is mandatory: the official SDK
+ * marks it optional, so a call without one has no idempotency and is its own
+ * payment. It is at most 255 characters.
+ */
+export declare const fireblocks: (terms: FireblocksTerms) => ProviderWire;