@mandateops/cli-linux-x64 0.0.0-stage → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/LICENSE +55 -0
  2. package/README.md +175 -2
  3. package/audit-lab/README.md +194 -0
  4. package/audit-lab/bin/mandateops +0 -0
  5. package/audit-lab/contracts/contact-plain-text.vectors.json +85 -0
  6. package/audit-lab/contracts/history-reading.md +185 -0
  7. package/audit-lab/contracts/history-reading.vectors.json +284 -0
  8. package/audit-lab/contracts/profiles.md +161 -0
  9. package/audit-lab/contracts/properties.md +512 -0
  10. package/audit-lab/contracts/sdk-config.md +155 -0
  11. package/audit-lab/contracts/system-under-test.md +385 -0
  12. package/audit-lab/contracts/test-provider.md +350 -0
  13. package/audit-lab/lab/compose.audit.yml +181 -0
  14. package/audit-lab/lab/config/fault-control.json +14 -0
  15. package/audit-lab/lab/examples/agents/Dockerfile +28 -0
  16. package/audit-lab/lab/examples/agents/codeloc.cjs +199 -0
  17. package/audit-lab/lab/examples/agents/load.cjs +9 -0
  18. package/audit-lab/lab/examples/agents/package-lock.json +2840 -0
  19. package/audit-lab/lab/examples/agents/package.json +9 -0
  20. package/audit-lab/lab/examples/agents/python/mandateops_codeloc.py +271 -0
  21. package/audit-lab/lab/examples/agents/python/sitecustomize.py +51 -0
  22. package/audit-lab/lab/examples/agents/requirements-python.txt +522 -0
  23. package/audit-lab/lab/examples/agents/telemetry-router.cjs +272 -0
  24. package/audit-lab/lab/examples/test-provider/.dockerignore +4 -0
  25. package/audit-lab/lab/examples/test-provider/Dockerfile +28 -0
  26. package/audit-lab/lab/examples/test-provider/bun.lock +405 -0
  27. package/audit-lab/lab/examples/test-provider/package.json +42 -0
  28. package/audit-lab/lab/examples/test-provider/src/amount.ts +32 -0
  29. package/audit-lab/lab/examples/test-provider/src/app.ts +538 -0
  30. package/audit-lab/lab/examples/test-provider/src/auth.ts +30 -0
  31. package/audit-lab/lab/examples/test-provider/src/barrier.ts +262 -0
  32. package/audit-lab/lab/examples/test-provider/src/codeloc.ts +27 -0
  33. package/audit-lab/lab/examples/test-provider/src/config.ts +311 -0
  34. package/audit-lab/lab/examples/test-provider/src/connect.ts +204 -0
  35. package/audit-lab/lab/examples/test-provider/src/declaration.ts +270 -0
  36. package/audit-lab/lab/examples/test-provider/src/declared.ts +198 -0
  37. package/audit-lab/lab/examples/test-provider/src/domain.ts +193 -0
  38. package/audit-lab/lab/examples/test-provider/src/egress.ts +396 -0
  39. package/audit-lab/lab/examples/test-provider/src/flow.ts +263 -0
  40. package/audit-lab/lab/examples/test-provider/src/gate.ts +301 -0
  41. package/audit-lab/lab/examples/test-provider/src/main.ts +31 -0
  42. package/audit-lab/lab/examples/test-provider/src/notify.ts +157 -0
  43. package/audit-lab/lab/examples/test-provider/src/owner.ts +60 -0
  44. package/audit-lab/lab/examples/test-provider/src/payment.ts +103 -0
  45. package/audit-lab/lab/examples/test-provider/src/profile.ts +417 -0
  46. package/audit-lab/lab/examples/test-provider/src/request.ts +201 -0
  47. package/audit-lab/lab/examples/test-provider/src/rows.ts +173 -0
  48. package/audit-lab/lab/examples/test-provider/src/schema.ts +114 -0
  49. package/audit-lab/lab/examples/test-provider/src/signature.ts +86 -0
  50. package/audit-lab/lab/examples/test-provider/src/staged.ts +318 -0
  51. package/audit-lab/lab/examples/test-provider/src/store.ts +432 -0
  52. package/audit-lab/lab/examples/test-provider/src/traffic.ts +50 -0
  53. package/audit-lab/lab/examples/test-provider/src/webauthn.d.ts +11 -0
  54. package/audit-lab/lab/examples/test-provider/src/wire.ts +153 -0
  55. package/audit-lab/lab/examples/test-provider/tsconfig.build.json +9 -0
  56. package/audit-lab/lab/examples/test-provider/tsconfig.json +24 -0
  57. package/audit-lab/lab/images/capture/Dockerfile +15 -0
  58. package/audit-lab/lab/images/capture/LICENSE +201 -0
  59. package/audit-lab/lab/images/fault-control/Dockerfile +13 -0
  60. package/audit-lab/lab/images/fault-control/LICENSE +21 -0
  61. package/audit-lab/lab/images/provider-store/Dockerfile +4 -0
  62. package/audit-lab/lab/images/provider-store/LICENSE +23 -0
  63. package/audit-lab/lab/images/telemetry/Dockerfile +14 -0
  64. package/audit-lab/lab/images/telemetry/LICENSE +201 -0
  65. package/audit-lab/lab/scripts/compose-down.sh +143 -0
  66. package/audit-lab/lab/scripts/compose-lib.sh +632 -0
  67. package/audit-lab/lab/scripts/compose-up.sh +240 -0
  68. package/package.json +16 -4
package/LICENSE ADDED
@@ -0,0 +1,55 @@
1
+ Apache License
2
+
3
+ Version 2.0, January 2004
4
+
5
+ http://www.apache.org/licenses/
6
+
7
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
8
+
9
+ 1. Definitions.
10
+
11
+ "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
14
+
15
+ "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.
16
+
17
+ "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
18
+
19
+ "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
20
+
21
+ "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.
22
+
23
+ "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).
24
+
25
+ "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.
26
+
27
+ "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."
28
+
29
+ "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.
30
+
31
+ 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.
32
+
33
+ 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.
34
+
35
+ 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:
36
+
37
+ You must give any other recipients of the Work or Derivative Works a copy of this License; and
38
+
39
+ You must cause any modified files to carry prominent notices stating that You changed the files; and
40
+
41
+ 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
42
+
43
+ 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.
44
+
45
+ 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.
46
+
47
+ 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.
48
+
49
+ 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.
50
+
51
+ 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.
52
+
53
+ 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.
54
+
55
+ END OF TERMS AND CONDITIONS
package/README.md CHANGED
@@ -1,3 +1,176 @@
1
- # Temporary Holding Version
1
+ # @mandateops/cli
2
2
 
3
- 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.
3
+ The `mandateops` command that `@mandateops/audit` tests drive. It runs your payout service in containers against the MandateOps test provider, injects the failures a test declares and seals a record of what money left. It moves no real money.
4
+
5
+ ## Install
6
+
7
+ Install it with the SDK, at the same version:
8
+
9
+ ```bash
10
+ npm install --save-dev @mandateops/audit @mandateops/cli
11
+ ```
12
+
13
+ With Bun or pnpm:
14
+
15
+ ```bash
16
+ bun add -d @mandateops/audit @mandateops/cli
17
+ pnpm add -D @mandateops/audit @mandateops/cli
18
+ ```
19
+
20
+ npm installs only the build for your machine. Check the install:
21
+
22
+ ```bash
23
+ npx mandateops version
24
+ ```
25
+
26
+ ## Requirements
27
+
28
+ - A container engine with Compose v2, running.
29
+ - Node 22 or later, or Bun 1.4.4 or later. `@mandateops/audit/bun` needs Bun.
30
+ - A containerised test deployment with a health check, and a provider base URL your service reads from an environment variable.
31
+ - Builds of the CLI exist for `darwin-arm64`, `linux-x64` and `linux-arm64`.
32
+
33
+ ## First payout test
34
+
35
+ This test runs your existing Compose deployment against the MandateOps test provider, loses the provider's reply after it commits the payout, and lets your client retry. It passes when exactly one payout leaves.
36
+
37
+ ```ts
38
+ import { expect, test } from "bun:test";
39
+ import {
40
+ auditRun,
41
+ defineConfig,
42
+ runLimit,
43
+ type Fixture,
44
+ } from "@mandateops/audit";
45
+
46
+ // Your deployment as it already is: its Compose file, service and port.
47
+ const config = defineConfig({
48
+ financialProfile: "payout-effects-only",
49
+ system: {
50
+ compose: "test-stack.yml",
51
+ service: "payments",
52
+ port: 8080,
53
+ // Longest wait between two attempts of one payout; 0: it never retries.
54
+ retryDelayMs: 0,
55
+ // Longest claim a worker holds on an attempt; 0: no leases.
56
+ leaseMs: 0,
57
+ // How long anything may still act on a settled payout.
58
+ quiescenceMs: 1000,
59
+ providerTerms: {
60
+ account: "first-run",
61
+ operation: "payout",
62
+ idempotencyScope: "merchant",
63
+ },
64
+ // Each provider your backend calls: the variables it reads, not their values.
65
+ providers: [
66
+ { name: "bank", urlEnv: "BANK_URL", credentialEnv: "BANK_KEY" },
67
+ ],
68
+ environment: { KEY_MODE: "stable" },
69
+ },
70
+ });
71
+
72
+ // The payout your backend is asked to make, in minor units.
73
+ const order = {
74
+ payment: "order-1",
75
+ tenant: "shop",
76
+ agent: "checkout",
77
+ delegation: "weekly-run",
78
+ account: "main",
79
+ destination: "supplier-9",
80
+ currency: "ZAR",
81
+ asset: "zar",
82
+ network: "bank",
83
+ amount: "2500",
84
+ };
85
+
86
+ const submit = (app: string) =>
87
+ fetch(new URL("/payouts", app), {
88
+ method: "POST",
89
+ body: JSON.stringify(order),
90
+ });
91
+
92
+ // The provider commits, its reply is lost, and your client retries.
93
+ async function retryAfterLostResponse({ app, faults, provider }: Fixture) {
94
+ const { payment: reference, amount: amountMinor, ...scope } = order;
95
+ const authorised = await provider.expectPayment({
96
+ ...scope,
97
+ reference,
98
+ amountMinor,
99
+ outcome: "exactly_one_effect",
100
+ });
101
+ // The reference your backend sends the provider for this payment.
102
+ await authorised.bindProviderPayment(reference);
103
+ await faults.loseResponseAfterCommit({
104
+ payment: authorised,
105
+ mode: "cut_connection",
106
+ });
107
+ await submit(app);
108
+ await faults.release();
109
+ await submit(app);
110
+ }
111
+
112
+ test(
113
+ "a retry after a lost response makes one payout",
114
+ async () => {
115
+ const result = await auditRun(config, retryAfterLostResponse);
116
+ expect(result.ci_passed).toBe(true);
117
+ },
118
+ runLimit(config),
119
+ );
120
+ ```
121
+
122
+ Run it with `bun test --timeout 300000`. The first run builds and pulls images, so it takes a few minutes.
123
+
124
+ ## After the first green run: check your backend's own record
125
+
126
+ A `payout-effects-only` pass checks only the money that left. A backend that records a paid payout as failed still passes. Add a status adapter and require `backend-outcome`, so the run also compares your backend's reported state with the provider's records:
127
+
128
+ ```ts
129
+ import { defineAdapter, type PayoutState } from "@mandateops/audit";
130
+
131
+ /** Your backend's own record of a payout, mapped to the adapter's states. */
132
+ type BackendPayout = { state: PayoutState };
133
+
134
+ const statusAdapter = defineAdapter({
135
+ status: async ({ backend, viewerCredential, providerPayment }) => {
136
+ const url = new URL(`/payouts/${providerPayment}`, backend);
137
+ const response = await fetch(url, {
138
+ headers: { authorization: `Bearer ${viewerCredential}` },
139
+ });
140
+ const payout = (await response.json()) as BackendPayout;
141
+ return { source: "adapter", payment: providerPayment, state: payout.state };
142
+ },
143
+ });
144
+
145
+ const checked = defineConfig({
146
+ ...config,
147
+ adapter: statusAdapter,
148
+ requiredChecks: ["provider-outcome", "backend-outcome"],
149
+ system: {
150
+ ...config.system,
151
+ credentialEnv: { viewer: "VIEWER_KEY" },
152
+ },
153
+ });
154
+
155
+ test(
156
+ "the backend reports the payout it made",
157
+ async () => {
158
+ const result = await auditRun(checked, retryAfterLostResponse);
159
+ expect(result.ci_passed).toBe(true);
160
+ },
161
+ runLimit(checked),
162
+ );
163
+ ```
164
+
165
+ The adapter maps your backend's record to one of `reserved`, `executing`, `unknown`, `needs_review`, `failed` or `confirmed`. A run where the provider paid but your backend reports `failed` then fails CI.
166
+
167
+ The `@mandateops/audit` page documents every configuration field, its default, the checks, the result and the exit codes.
168
+
169
+ ## Limitations
170
+
171
+ - Test environment: no real money moves; real provider settlement is not covered. A pass says nothing about a real provider's idempotency.
172
+ - A run observes effects only within its drain window; a later payout is not seen.
173
+ - A sealed record detects accidental and partial edits, not forgery by someone who can rewrite the run directory.
174
+ - A test checks the scenarios it declares. It does not show the absence of other defects and is not a certification.
175
+
176
+ Guide: https://getmandateops.com/getting-started.md
@@ -0,0 +1,194 @@
1
+ # audit-lab quick start
2
+
3
+ The lab runs your payment service in Docker against the MandateOps test provider, loses responses on
4
+ purpose, and reports what money left. It is a test tool under development, and it moves no real
5
+ money.
6
+
7
+ Contents: `bin/mandateops` (the host program), `lab/` (the provider, proxy and scripts it runs),
8
+ `sdk/` and `examples/first-run/` (in a source build only), `contracts/` (the reference documents).
9
+
10
+ ## Requirements
11
+
12
+ - Docker Engine with Compose v2, running.
13
+ - Node 22 or later, or Bun 1.4.4 or later. The first run's two-test suite and `auditTest` use Bun;
14
+ `auditRun` works under either, as `node node-run.mjs` shows.
15
+ - bash, and python3 or jq.
16
+
17
+ ## Install
18
+
19
+ ```bash
20
+ npm install --save-dev @mandateops/audit @mandateops/cli
21
+ ```
22
+
23
+ npm installs the build for your machine: `darwin-arm64`, `linux-x64` or `linux-arm64`. The binary
24
+ is stamped with the digest of `lab/` and refuses any other tree, so do not edit `lab/`. The
25
+ `@mandateops/cli` page shows a complete first test and the status adapter to add after its first
26
+ green run.
27
+
28
+ ## First run from a source build
29
+
30
+ A build from `make package` also carries `examples/first-run/` and the SDK it was built with:
31
+
32
+ ```bash
33
+ cd audit-lab/examples/first-run
34
+ bun install
35
+ bun test --timeout 300000
36
+ ```
37
+
38
+ Two tests run. Both lose the provider's response after it commits a payment, and the caller then
39
+ retries. With a stable idempotency key there is one payment and the run passes. With a fresh key
40
+ per attempt there are two, and the run fails CI; the test asserts that failure. Expect a few
41
+ minutes the first time, as Docker pulls and builds images.
42
+
43
+ Each run writes `runs/<id>/` with `ci-result.json` and a report. Read `assurance` before calling a
44
+ run audited: this example passes as `money_out_only_commitments_not_checked`.
45
+
46
+ ## What your service must do
47
+
48
+ Your service runs from your own Compose file. Copy `examples/first-run/` and change the config.
49
+
50
+ - Declare a Compose healthcheck on the service. The lab checks your resolved Compose file against
51
+ an allow-list and refuses any key it does not list, including host networking, privileged mode,
52
+ engine sockets, extra networks and bind mounts outside the project. The refusal names the key.
53
+ - Mounting the whole project (`.:/app`) is refused while `runs/` sits inside it, as a container
54
+ could rewrite the evidence. Set `runsDirectory` in the config to a path outside the project.
55
+ - A built service runs under a tag of the run, so an `image:` on it leaves your own tag alone.
56
+ - The lab activates no Compose profile, so the declared service must not have `profiles`.
57
+ - Your images build before the lab starts. Builds keep normal network access, so review what your
58
+ Dockerfile runs; only running containers are isolated.
59
+ - To run nothing of yours during startup, declare each service as `image: name@sha256:...` with no
60
+ `build:`, and set `system.requirePrebuiltImages: true`. The lab then refuses a `build:` key or a
61
+ tag and says what to change. An image already on the machine is used as it is; otherwise Docker
62
+ pulls it. `docker image inspect --format '{{.RepoDigests}}' IMAGE` prints the digest. The classic
63
+ image store gives one only after a push, so push the image first or use the containerd store.
64
+ The refusal of a tag says the same.
65
+ - Each service's declared image, image ID and digests are in the report and bound to the run, and
66
+ `mandateops recheck` refuses a `provenance.json` that disagrees.
67
+ - Declare the three backend timings, `retryDelayMs`, `leaseMs` and `quiescenceMs`, each in
68
+ milliseconds or as `"unknown"`. Operational bounds such as `system.startupTimeoutS` and
69
+ `drainBoundMs` are optional; the `@mandateops/audit` page lists each default.
70
+ - Read each provider's base URL and credential from environment variables, and name them in that
71
+ provider's entry of `providers`, as `urlEnv` and `credentialEnv`. The lab replaces their values.
72
+ One provider is a one-entry list; several run in the same session and money is counted across them.
73
+ - Send `POST {base}/payouts` with `authorization: Bearer <credential>`, `idempotency-key: <key>`,
74
+ `content-type: application/json`, and the instruction as the body: `payment`, `tenant`, `agent`,
75
+ `delegation`, `account`, `destination`, `currency`, `asset`, `network`, and `amount` as a decimal
76
+ string of integer minor units.
77
+ - Same key and same instruction returns the same effect. Same key with a different instruction is
78
+ a 422. A new key is a new effect. A 200 returns `{ "instruction": ..., "effectId": ... }`.
79
+ - If a service besides `system.service` calls the provider, list every service that does in
80
+ `providerClients`, with `system.service` among them if it calls the provider too. Only those
81
+ services get the provider URLs and credentials. `system.service` alone gets the `client`,
82
+ `operator` and `viewer` credentials.
83
+ - Do not name the lab's tokens in your Compose file: `${MANDATEOPS_PROVIDER_TOKEN}` resolves empty, and
84
+ `${MANDATEOPS_PROVIDER_TOKEN:?}` stops the run. Declare the variable in `providers[].credentialEnv` instead.
85
+
86
+ If your provider has its own format, keep your provider client as it is and declare the format:
87
+ `format: paystack({ tenant, agent, delegation, account, asset, network })` in its `providers` entry. The test provider then
88
+ answers that call's shape, and the bullets above on `/payouts` do not apply. It imitates the shape
89
+ only, so a pass does not show how that provider behaves. Declarations exist for Paystack, Stripe
90
+ payouts and transfers, Flutterwave, Adyen, Checkout.com, PayPal, RazorpayX, Mollie payouts, Peach,
91
+ Stitch, Revolut, Modern Treasury, Airwallex, Dwolla and Wise (quote, transfer, fund); each states what is unverified in
92
+ `sdk/typescript/src/providers/`, and only the Paystack, Wise and Bridge shapes and the Stripe, Fireblocks and Circle SDKs have run live. Your
93
+ client must be able to reach the lab's URL: some SDKs fix their host, and need a custom HTTP client.
94
+ OAuth token calls are not imitated. For a provider without a declaration,
95
+ write one as [contracts/test-provider.md](contracts/test-provider.md) describes. The full contract is [contracts/test-provider.md](contracts/test-provider.md), and
96
+ [contracts/system-under-test.md](contracts/system-under-test.md) covers declared timings and
97
+ isolation.
98
+
99
+ Crypto formats are listed in [contracts/test-provider.md](contracts/test-provider.md). Only the providers, assets and networks named there are supported, and direct on-chain sending is not.
100
+
101
+ ## Financial profiles
102
+
103
+ `financialProfile` sets which properties must hold. An unresolved required property fails CI.
104
+
105
+ | Profile | Needs | Pass means | Pick it when |
106
+ | --------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
107
+ | `payout-effects-only` | No adapter; the test declares `exactly_one_effect` or `no_effect` | Money out matched, from provider records alone. Your records and commitments were not checked | You are starting, or cannot expose your ledger |
108
+ | `payout-effects` | Adapter with `history` and `capacity` | Your records agree with the provider's. Commitment retention is not checked | You reserve before sending but have no fixed capacity model |
109
+ | `payout-commitment` | Adapter with `history` and `capacity`, with readings while an attempt is unresolved | Every property holds, including holding capacity while the outcome is unknown | You reserve funds against a limit |
110
+
111
+ A backend without reservations must use `payout-effects-only`: both other profiles model a backend
112
+ that holds the amount before it sends anything. Adapter readings are specified in
113
+ [contracts/history-reading.md](contracts/history-reading.md), with examples in
114
+ [contracts/history-reading.vectors.json](contracts/history-reading.vectors.json).
115
+
116
+ Scenario profiles (`controlled-payout`, `native-worker`) belong to adapters in the lab's own
117
+ matrix, and a test through this SDK does not choose one. See
118
+ [contracts/profiles.md](contracts/profiles.md) and [contracts/properties.md](contracts/properties.md).
119
+
120
+ ## Fault order
121
+
122
+ Inside a test body, in this order:
123
+
124
+ 1. `const payment = await provider.expectPayment({...})` declares what is authorised.
125
+ 2. `await faults.loseResponseAfterCommit({ payment, mode })` arms the fault, before the call that
126
+ pays. `mode` is `cut_connection`, `hold_response`, or `crash_process` (which needs
127
+ `processService`).
128
+ 3. Call your service.
129
+ 4. `await faults.established()` if the test must wait until the effect has committed.
130
+ 5. `await faults.release()`, then retry however your service retries.
131
+
132
+ `faults.refuseNext()` has the provider decline the authorised payment's next request instead.
133
+
134
+ **Provider notifications.** Declare `notifyPath` in the system (for example `/webhooks/provider`)
135
+ and the provider tells your service a payment was paid with a JSON POST there, signed in
136
+ `x-provider-signature` as `sha256=` and the hex HMAC-SHA256 of the exact body under a signing
137
+ secret the host generates for that session alone. Name the variable your service reads it from in
138
+ `credentialEnv.notify`; it is never a token and never logged. Once the provider holds the payment's effect, `faults.notify()` sends one notification; call
139
+ it twice for a repeat, pass `{ copies: 2 }` to send two at once, or `{ hold: true }` to hold one back
140
+ until `faults.releaseNotifications()`, so it arrives after any sent meanwhile. Report each credit,
141
+ fulfilment or payout a notification causes in the history reading's `effects`, citing the
142
+ notification's `deliveryId` and `effectId`: the run then checks your service acted once per paid
143
+ payment. A reading without `effects` leaves that check inconclusive, never passed.
144
+ Call `inspect()` while an attempt is unresolved to take adapter readings. Faults armed after the
145
+ call never fire, and a fault that never fires is recorded as not exercised rather than passed.
146
+
147
+ ### Concurrent submissions
148
+
149
+ `concurrency.race(parties, submit)` runs `parties` submissions at once through a gate the host opens in front of your service: each `submit(url, party)` sends its request to `url` instead of `app`. The gate holds each party's first request until every party's request has arrived, then writes them all to your service before reading any reply, so they meet at your reservation boundary together. It records whether they did. A race whose requests were not all in flight at once seals with `reason: "overlap_not_established"` and does not pass, so a sequential replay never reads as a concurrency pass. The gate never drops a request: a party that arrives alone is forwarded once the fault deadline passes.
150
+
151
+ - **The same payment from two workers.** Declare it with `expectPayment` and race the submission of that one payment. The usual properties then judge it: exactly one provider effect, and accounting that agrees with it.
152
+ - **Payments competing for capacity.** Declare them together with `provider.expectCompetingPayments([first, second], { fundingBalance, limits: [{ currency, asset, limitMinor }] })` instead of `expectPayment`; `fundingBalance` names the balance they all draw on, whatever approval or delegation each carries, and each limit is its capacity in one currency and asset (a payment in a currency with no limit leaves the check inconclusive, and amounts in different currencies are never added together), while `capacityLimitMinor` stays the limit of one payout's own capacity readings. Race their submissions with `concurrency.race`, bind each one your service accepted, and call `recordRefused()` on each one it refused or queued without holding capacity. Those calls are hints: after your test ends, the SDK reads your adapter's `history` for every bound payment by its own provider reference, so the shared capacity check (P8) takes each admission from your service's own record of it or from the provider's records, and each refusal from your balance reading's payout count when it matches the payments already shown admitted. A hint those records do not bear out leaves the check inconclusive, and a history that cannot be read is reported in `reading_problems`. It counts every accepted payment until it is paid or finally refused. The first bound is the payout judged; any effect of another competitor counts against it. The result's `competition` field is P8's result in plain words, and the run passes only when it is satisfied or not applicable: accepted competitors whose amounts together exceed the limit seal with `reason: "capacity_exceeded"`, a race not shown in flight together with `reason: "overlap_not_established"`, and admissions your service's records do not settle with `reason: "shared_capacity_inconclusive"`. For a service with no cap the payments share, declare `{ cap: "none" }` instead of `{ fundingBalance, limits }`: the check is then `not_applicable` and does not stop a pass. Declare one or the other: a competition that says nothing about its cap seals with `reason: "concurrency_cap_undeclared"` and does not pass.
153
+
154
+ ## Go, Python and other services
155
+
156
+ Only the test is TypeScript. The service under test is any container, as `app.py` in the first run
157
+ shows. Keep one small `audit/` folder beside the service with a `package.json`, the config and a
158
+ test that drives your API with `fetch`, and run `bun test` from it in CI. There is no native Go or
159
+ Python test library. `mandateops session` speaks JSON lines on stdin and stdout, but that protocol
160
+ is internal to the SDK and may change.
161
+
162
+ ## Limits
163
+
164
+ - Late effects: observation ends after a declared drain window. A payment made after the window
165
+ is not seen, and `ci-result.json` states this assumption. `drainMs` defaults to `quiescenceMs`,
166
+ which must cover `retryDelayMs + leaseMs`.
167
+ - Sibling fake bank: a container in your own Compose project counts as your system. A payment to a
168
+ fake bank inside your stack leaves no evidence and cannot be detected.
169
+ - Local operator: digests detect accidents and partial edits, not forgery. Anyone who can rewrite a
170
+ run directory can regenerate a consistent one, and anyone with local Docker access can read
171
+ container environments. Treat a result as evidence from your own machine, not as an attestation.
172
+ - Test environment: no real money moves; real provider settlement is not covered. A pass says nothing about a real provider's idempotency.
173
+ - Each run removes the images it built, unless `system.keepImages` is `true`. Kept images are named
174
+ after the run, so they stay until you remove them, and every run still does its own build.
175
+
176
+ ## After a run
177
+
178
+ Teardown removes `runs/<id>/settings.env`, which holds your declared values. `compose.log` is
179
+ cut at 16 MiB per Compose project; `system.logLimitBytes` changes that.
180
+ If the host is killed, remove what it left with
181
+ `mandateops recover --run-id ID --runs-dir DIR`. This writes `host-lost.json`, gives no verdict and
182
+ drops the logs.
183
+
184
+ ## Code-location preloads
185
+
186
+ `examples/agents/codeloc.cjs` (Node via `NODE_OPTIONS=--require`, Bun via
187
+ `BUN_OPTIONS=--preload`) and `examples/agents/python/mandateops_codeloc.py`
188
+ (imported by the same directory's `sitecustomize.py` on `PYTHONPATH`) ship in
189
+ the agents image every telemetry-enabled lab run mounts read-only, and are
190
+ embedded in the CLI for `mandateops run -- <command>`. Both have no
191
+ dependencies. They tag only requests to `MANDATEOPS_PROVIDER_ORIGINS` with
192
+ `x-mandateops-call`, record project-relative frames only, never read bodies or
193
+ header values, and make no network calls. Java, .NET, Go and Rust backends get
194
+ no location yet; their calls show the reason instead.
Binary file
@@ -0,0 +1,85 @@
1
+ {
2
+ "description": "Plain-text rule shared by the contact form and the API: after trimming, a value may hold no < or > and no Unicode control character (general category Cc: U+0000 to U+001F, U+007F, U+0080 to U+009F), except line feed and carriage return in multi-line fields. Both apps/audit-api/src/contact/checks.rs and apps/audit-landing/src/contactForm.ts test against these cases.",
3
+ "cases": [
4
+ {
5
+ "text": "Ada Lovelace",
6
+ "multiline": false,
7
+ "allowed": true
8
+ },
9
+ {
10
+ "text": "caf\u00e9 \u00fcn\u00efcode \u2013 dash",
11
+ "multiline": false,
12
+ "allowed": true
13
+ },
14
+ {
15
+ "text": "<b>",
16
+ "multiline": false,
17
+ "allowed": false
18
+ },
19
+ {
20
+ "text": "a>b",
21
+ "multiline": true,
22
+ "allowed": false
23
+ },
24
+ {
25
+ "text": "line\nline",
26
+ "multiline": false,
27
+ "allowed": false
28
+ },
29
+ {
30
+ "text": "line\nline",
31
+ "multiline": true,
32
+ "allowed": true
33
+ },
34
+ {
35
+ "text": "line\r\nline",
36
+ "multiline": true,
37
+ "allowed": true
38
+ },
39
+ {
40
+ "text": "tab\there",
41
+ "multiline": true,
42
+ "allowed": false
43
+ },
44
+ {
45
+ "text": "bell\u0007end",
46
+ "multiline": true,
47
+ "allowed": false
48
+ },
49
+ {
50
+ "text": "nul\u0000end",
51
+ "multiline": false,
52
+ "allowed": false
53
+ },
54
+ {
55
+ "text": "del\u007fend",
56
+ "multiline": true,
57
+ "allowed": false
58
+ },
59
+ {
60
+ "text": "c1\u0085end",
61
+ "multiline": true,
62
+ "allowed": false
63
+ },
64
+ {
65
+ "text": "c1\u009fend",
66
+ "multiline": false,
67
+ "allowed": false
68
+ },
69
+ {
70
+ "text": "nbsp\u00a0ok",
71
+ "multiline": false,
72
+ "allowed": true
73
+ },
74
+ {
75
+ "text": "zero\u200bwidth",
76
+ "multiline": false,
77
+ "allowed": true
78
+ },
79
+ {
80
+ "text": " padded ",
81
+ "multiline": false,
82
+ "allowed": true
83
+ }
84
+ ]
85
+ }