@mandateops/audit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,55 @@
+Apache License
+
+Version 2.0, January 2004
+
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# @mandateops/audit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The test library for the audit lab. It starts `mandateops`, runs your test body against your
+deployed service, and returns the recorded result. It needs `mandateops` from an `audit-lab` package
+and has no runtime dependencies. `auditRun` runs under Node 22 or later, or Bun, with any test
+runner. Only `@mandateops/audit/bun` needs Bun 1.4.4 or later.
+
+Install it from npm, alongside the `mandateops` CLI it drives:
+
+```bash
+bun add --dev @mandateops/audit  # or: npm install --save-dev @mandateops/audit
+```
+
+The SDK and the CLI speak a numbered session protocol. A pair from different releases is refused
+before any scenario runs, with the fix named. An `audit-lab` install also carries the SDK of its own
+build at `sdk/mandateops-audit-VERSION.tgz`, for working against a CLI built from source:
+`bun add ./mandateops-audit-VERSION.tgz`.
+
+The package ships compiled JavaScript and declarations. TypeScript users of
+`@mandateops/audit/bun`, which wraps `bun:test`, also need `@types/bun`.
+
+```ts
+import { auditRun, defineConfig, runLimit } from "@mandateops/audit";
+import { auditTest } from "@mandateops/audit/bun";
+```
+
+`auditTest` registers one test that fails when the run fails CI. `auditRun` returns the result
+for your own assertions, and `runLimit` gives the matching test timeout.
+
+Runs are written to the config's `runsDirectory`, else to `MANDATEOPS_RUNS_DIR` (the GitHub Action
+sets it), else to `runs/` in the working directory.
+
+The `audit-lab` README covers the first run, the provider contract, profiles, fault order and
+limits.

package/dist/bun.d.ts

@@ -0,0 +1,13 @@
+/** `auditTest` for Bun's runner; other runners wrap `auditRun` the same way. */
+import { test } from "bun:test";
+import type { AuditConfig, AuditResult, Fixture } from "./index.js";
+export declare function explain(result: AuditResult): string;
+export type AuditTestOptions = Readonly<{
+    timeoutMs?: number;
+    /** The runner's `test`, or a variant such as `test.failing`. */
+    register?: typeof test;
+    /** Sees the recorded result, before CI's decision fails the test. */
+    onResult?: (result: AuditResult) => void;
+}>;
+/** One test in the customer's suite: a failed body or CI's decision fails it. */
+export declare function auditTest(name: string, config: AuditConfig, body: (fixture: Fixture) => Promise<void>, options?: AuditTestOptions): void;

package/dist/bun.js

@@ -0,0 +1,28 @@
+/** `auditTest` for Bun's runner; other runners wrap `auditRun` the same way. */
+import { test } from "bun:test";
+import { auditRun, runLimit } from "./index.js";
+export function explain(result) {
+    if (result.teardown_failure)
+        return `audit failed for ${result.run_id}: its deployment may still be running, so the pass is withdrawn; run \`${result.teardown_failure.recover_command}\``;
+    const unresolved = result.properties
+        .filter((found) => found.required && found.result !== "satisfied")
+        .map((found) => `${found.property}: ${found.result}`);
+    const detail = unresolved.length
+        ? unresolved.join(", ")
+        : `verdict ${result.verdict.verdict}, record published: ${String(result.record_published)}`;
+    const refused = result.reading_problems.map((found) => `\n  ${found.slot}: ${found.reason}`);
+    return `audit failed for ${result.run_id}: ${detail}${refused.join("")}`;
+}
+/** One test in the customer's suite: a failed body or CI's decision fails it. */
+export function auditTest(name, config, body, options = {}) {
+    const { timeoutMs = runLimit(config), register = test, onResult } = options;
+    register(name, async () => {
+        const result = await auditRun(config, body);
+        onResult?.(result);
+        if (result.assurance !== "backend_and_provider") {
+            console.log(`${result.run_id}: ${result.assurance}`);
+        }
+        if (!result.ci_passed)
+            throw new Error(explain(result));
+    }, timeoutMs);
+}

package/dist/index.d.ts

@@ -0,0 +1,269 @@
+import type { CapacityReading, HistoryReading, ReadingProfile } from "./reading.js";
+import type { ProviderWire, StagedWire } from "./providers/index.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 type { CheckoutTerms, CurrencyTerms, BridgeTerms, FireblocksTerms, LedgerTerms, MollieTerms, OwnAccountTerms, ProviderWire, SourcedTerms, StagedWire, TermDefaults, WiseRoutes, WiseTerms, } from "./providers/index.js";
+export { parseCapacityReading, parseHistoryReading, ReadingError, requireHistoryFits, } from "./reading.js";
+export type { AttemptEnd, AttemptResult, CapacityReading, Flow, HistoryEvent, HistoryReading, Instruction, MinorUnits, Payout, PayoutState, ReadingProfile, HistoryConsistency, CapacityConsistency, } from "./reading.js";
+/**
+ * The largest amount the stand-in holds, the audit core's `u128` maximum.
+ * `fixtures/wire/vectors.json` pins it for every reader.
+ */
+export declare const SYNTHETIC_MAX_MINOR_UNITS = 340282366920938463463374607431768211455n;
+/** Integer minor units as a decimal string, so no language loses precision. */
+export declare function minorUnits(value: string): string;
+declare const PROPERTIES: readonly ["instruction_binding", "commitment_retention", "retry_identity", "effect_within_authorisation", "reconciliation_consistency", "external_outcome"];
+export type Property = (typeof PROPERTIES)[number];
+declare const PROPERTY_RESULTS: readonly ["satisfied", "violated", "inconclusive", "not_applicable"];
+declare const ASSURANCES: readonly ["backend_and_provider", "backend_and_provider_commitments_not_checked", "money_out_only_commitments_not_checked", "no_assurance"];
+/** What a read-only adapter is given: never an operator or provider credential. */
+export type ReadContext = Readonly<{
+    backend: string;
+    viewerCredential: string;
+    providerPayment: string;
+}>;
+/** Reads the backend, in the shape of `contracts/history-reading.md`. */
+export type Adapter = Readonly<{
+    history: (context: ReadContext) => Promise<HistoryReading>;
+    capacity: (context: ReadContext) => Promise<CapacityReading>;
+}>;
+export declare const defineAdapter: (adapter: Adapter) => Adapter;
+/** The provider identity every effect must carry. */
+export type ProviderTerms = Readonly<{
+    account: string;
+    operation: string;
+    idempotencyScope: string;
+}>;
+/** The roles the audited service itself holds. */
+export type ServiceRole = "client" | "operator" | "viewer";
+/** Every role a credential variable can serve. */
+export type CredentialRole = ServiceRole | "provider";
+/** The customer's own deployment, as it already is. */
+export type System = Readonly<{
+    /** Its Compose file, from the working directory. */
+    compose: string;
+    /** Where its relative paths resolve from; the Compose file's directory if absent. */
+    projectDirectory?: string;
+    service: string;
+    /** The container port it listens on. */
+    port: number;
+    /** After a payout settles, how long anything may still act. */
+    quiescenceMs: number;
+    /** The longest delay between two of its attempts; 0 if it never retries itself. */
+    retryDelayMs: number;
+    /** Its longest claim on an attempt; 0 if it has none. */
+    leaseMs: number;
+    workerDeadlineMs?: number;
+    providerTerms: ProviderTerms;
+    /** The variable it reads its provider's base URL from. */
+    providerUrlEnv?: string;
+    /**
+     * The variables its credentials arrive in. `service` holds client, operator
+     * and viewer; the services that call the provider hold provider.
+     */
+    credentialEnv?: Readonly<Partial<Record<CredentialRole, string>>>;
+    /** The services that call the provider; `service` alone if absent. */
+    providerClients?: readonly string[];
+    /** One of those services, which the host may kill and restart. */
+    processService?: string;
+    /** How long the deployment may take to become healthy. */
+    startupTimeoutS: number;
+    /** How long a fault's target may take to commit. */
+    faultDeadlineMs: number;
+    /** Bound on the host's control and read requests; the host's if absent. */
+    controlTimeoutMs?: number;
+    /** Bound on one Docker command; the host's if absent. */
+    processTimeoutMs?: number;
+    /** How long a stopping container may take; the lab's if absent. */
+    stopTimeoutS?: number;
+    /** How many times a published port is read; the lab's if absent. */
+    portReads?: number;
+    /** Where each Compose project's `compose.log` is cut; the lab's if absent. */
+    logLimitBytes?: number;
+    /** Leaves the images built for the run in place at teardown. */
+    keepImages?: boolean;
+    /**
+     * Refuses any service with a `build` key or an image not pinned as
+     * `name@sha256:...`, so nothing of the customer's runs during startup.
+     */
+    requirePrebuiltImages?: boolean;
+    /** Values its Compose file interpolates. */
+    environment?: Readonly<Record<string, string>>;
+    defectStimulus?: string;
+    providerMapping?: string;
+    /** The provider format the stand-in speaks; the lab's own if absent. */
+    providerWire?: ProviderWire | StagedWire;
+}>;
+/** A reviewed financial profile: a reading profile, or effects with no adapter. */
+export type FinancialProfile = ReadingProfile | "payout-effects-only";
+export type AuditConfig = Readonly<{
+    /** Explicit until a separately qualified provider emulation exists. */
+    provider: "synthetic";
+    /** A reviewed financial profile, chosen at setup. */
+    financialProfile: FinancialProfile;
+    system: System;
+    /** Required by every profile but `payout-effects-only`, which refuses one. */
+    adapter?: Adapter;
+    /**
+     * Bounded observation after the test body, while workers may still act.
+     * At least the deployment's declared window, or the host refuses to start.
+     */
+    drainMs: number;
+    /**
+     * How long a drain goes on when effects keep restarting its window. At
+     * least `drainMs`; still changing at this bound leaves the run unresolved.
+     */
+    drainBoundMs: number;
+    capacityLimitMinor: string;
+    /** Milliseconds one test body may take. */
+    testBudgetMs: number;
+    /** How long an aborted body may take to stop before capture starts anyway. */
+    abortGraceMs?: number;
+    /** Where run directories go, from the working directory; `runs` if absent. */
+    runsDirectory?: string;
+    /** The host program; `mandateops` on the PATH if absent. */
+    hostCommand?: readonly string[];
+}>;
+export declare const defineConfig: (config: AuditConfig) => AuditConfig;
+export type ExpectedPayment = Readonly<{
+    reference: string;
+    tenant: string;
+    agent: string;
+    delegation: string;
+    account: string;
+    destination: string;
+    currency: string;
+    asset: string;
+    network: string;
+    amountMinor: string;
+    /**
+     * What the provider should hold at the end. Required by
+     * `payout-effects-only`, and refused by the host under any other profile.
+     */
+    outcome?: ExpectedOutcome;
+}>;
+export type ExpectedOutcome = "exactly_one_effect" | "no_effect";
+/** A test-declared authorisation: the expectation, not proof of any approval. */
+export type Authorised = Readonly<{
+    expected: ExpectedPayment;
+    /**
+     * Names what the backend sends the provider as `payment`, which is also what
+     * adapters read by. Required before `inspect` and before the body ends under
+     * any profile with an adapter: an unbound run fails with
+     * [`AuditUsageError`]. Optional under `payout-effects-only`, where no
+     * reading depends on it.
+     */
+    bindProviderPayment: (payment: string) => Promise<void>;
+}>;
+export type PropertyDecision = Readonly<{
+    property: Property;
+    result: (typeof PROPERTY_RESULTS)[number];
+    required: boolean;
+}>;
+/** A reading that could not be used, and why, naming the field. */
+export type ReadingProblem = Readonly<{
+    slot: string;
+    reason: string;
+}>;
+/** What the host sealed. */
+export type SealedResult = Readonly<{
+    run_id: string;
+    ci_passed: boolean;
+    /** What a pass covers: read it before calling a run audited. */
+    assurance: (typeof ASSURANCES)[number];
+    /** What the result assumes about effects after observation stopped. */
+    assumption?: string;
+    properties: readonly PropertyDecision[];
+    verdict: Readonly<{
+        verdict: string;
+        findings?: readonly Readonly<{
+            rule: string;
+        }>[];
+        reasons?: readonly unknown[];
+    }>;
+    record_published: boolean;
+}>;
+/** A deployment that may have outlived its run, and what removes it. */
+export type TeardownFailure = Readonly<{
+    recover_command: string;
+}>;
+export type AuditResult = SealedResult & Readonly<{
+    /** Why an adapter reading is missing from the record, if one is. */
+    reading_problems: readonly ReadingProblem[];
+    /** Set when the sealed pass was withdrawn: the deployment outlived the run. */
+    teardown_failure?: TeardownFailure;
+}>;
+/** The test body failed. The run is sealed and `result` records it. */
+export declare class AuditTestFailure extends Error {
+    readonly result: AuditResult;
+    readonly cause: unknown;
+    constructor(result: AuditResult, cause: unknown);
+}
+/** The SDK was used against its contract; the message says how to correct it. */
+export declare class AuditUsageError extends Error {
+    readonly name = "AuditUsageError";
+}
+type Credentials = Readonly<Record<ServiceRole, string>>;
+/**
+ * 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 declare const SESSION_PROTOCOL = 2;
+/** Why a host of another protocol is refused, and how to fix it. */
+export declare function protocolMismatch(announced: number | undefined): string;
+/** A sealed result, checked before anything reads it. */
+export declare function parseResult(value: unknown): SealedResult;
+export type LossMode = "cut_connection" | "hold_response" | "crash_process";
+export type Fixture = Readonly<{
+    /** The deployed service's base URL. Optional convenience for `fetch`. */
+    app: string;
+    /** Generated for this session; a test never holds a provider credential. */
+    credentials: Credentials;
+    provider: Readonly<{
+        expectPayment: (expected: ExpectedPayment) => Promise<Authorised>;
+    }>;
+    faults: Readonly<{
+        /**
+         * Gates the authorised payment's committed response, synchronously. One
+         * fault at a time: arm, optionally `established`, then `release`.
+         */
+        loseResponseAfterCommit: (target: Readonly<{
+            payment: Authorised;
+            mode: LossMode;
+        }>) => Promise<void>;
+        /**
+         * Resolves once the fault took effect; a hold stays held until `release`.
+         * Needs an armed fault that is not yet released.
+         */
+        established: () => Promise<void>;
+        /**
+         * Ends the armed fault. Released before it took effect, it leaves the run
+         * unable to show the stimulus, so the run does not pass.
+         */
+        release: () => Promise<void>;
+        /** Has the stand-in decline the authorised payment's next request. */
+        refuseNext: () => Promise<void>;
+    }>;
+    /** Takes adapter readings while an attempt is unresolved; needs a binding. */
+    inspect: () => Promise<void>;
+    /** Aborted when the test budget runs out: pass it to the customer's calls. */
+    signal: AbortSignal;
+}>;
+/**
+ * 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 declare const runLimit: (config: AuditConfig) => number;
+/**
+ * Refuses, before anything starts, a run that could only end inconclusive.
+ *
+ * @throws {AuditUsageError} when the profile and adapter do not go together.
+ */
+export declare function requireRunnable(config: AuditConfig): void;
+export declare function wireInstruction(expected: ExpectedPayment): Record<string, string>;
+type Body = (fixture: Fixture) => Promise<void>;
+/**
+ * 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 declare function auditRun(config: AuditConfig, body: Body, runId?: string): Promise<AuditResult>;