@mandateops/cli-linux-arm64 0.0.0-stage → 0.7.2
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.
- package/LICENSE +55 -0
- package/README.md +181 -2
- package/audit-lab/README.md +194 -0
- package/audit-lab/bin/mandateops +0 -0
- package/audit-lab/contracts/contact-plain-text.vectors.json +85 -0
- package/audit-lab/contracts/history-reading.md +185 -0
- package/audit-lab/contracts/history-reading.vectors.json +284 -0
- package/audit-lab/contracts/profiles.md +161 -0
- package/audit-lab/contracts/properties.md +512 -0
- package/audit-lab/contracts/sdk-config.md +155 -0
- package/audit-lab/contracts/system-under-test.md +385 -0
- package/audit-lab/contracts/test-provider.md +350 -0
- package/audit-lab/lab/compose.audit.yml +181 -0
- package/audit-lab/lab/config/fault-control.json +14 -0
- package/audit-lab/lab/examples/agents/Dockerfile +28 -0
- package/audit-lab/lab/examples/agents/codeloc.cjs +199 -0
- package/audit-lab/lab/examples/agents/load.cjs +9 -0
- package/audit-lab/lab/examples/agents/package-lock.json +2840 -0
- package/audit-lab/lab/examples/agents/package.json +9 -0
- package/audit-lab/lab/examples/agents/python/mandateops_codeloc.py +271 -0
- package/audit-lab/lab/examples/agents/python/sitecustomize.py +51 -0
- package/audit-lab/lab/examples/agents/requirements-python.txt +522 -0
- package/audit-lab/lab/examples/agents/telemetry-router.cjs +272 -0
- package/audit-lab/lab/examples/test-provider/.dockerignore +4 -0
- package/audit-lab/lab/examples/test-provider/Dockerfile +28 -0
- package/audit-lab/lab/examples/test-provider/bun.lock +405 -0
- package/audit-lab/lab/examples/test-provider/package.json +42 -0
- package/audit-lab/lab/examples/test-provider/src/amount.ts +32 -0
- package/audit-lab/lab/examples/test-provider/src/app.ts +538 -0
- package/audit-lab/lab/examples/test-provider/src/auth.ts +30 -0
- package/audit-lab/lab/examples/test-provider/src/barrier.ts +262 -0
- package/audit-lab/lab/examples/test-provider/src/codeloc.ts +27 -0
- package/audit-lab/lab/examples/test-provider/src/config.ts +311 -0
- package/audit-lab/lab/examples/test-provider/src/connect.ts +204 -0
- package/audit-lab/lab/examples/test-provider/src/declaration.ts +270 -0
- package/audit-lab/lab/examples/test-provider/src/declared.ts +198 -0
- package/audit-lab/lab/examples/test-provider/src/domain.ts +193 -0
- package/audit-lab/lab/examples/test-provider/src/egress.ts +396 -0
- package/audit-lab/lab/examples/test-provider/src/flow.ts +263 -0
- package/audit-lab/lab/examples/test-provider/src/gate.ts +301 -0
- package/audit-lab/lab/examples/test-provider/src/main.ts +31 -0
- package/audit-lab/lab/examples/test-provider/src/notify.ts +157 -0
- package/audit-lab/lab/examples/test-provider/src/owner.ts +60 -0
- package/audit-lab/lab/examples/test-provider/src/payment.ts +103 -0
- package/audit-lab/lab/examples/test-provider/src/profile.ts +417 -0
- package/audit-lab/lab/examples/test-provider/src/request.ts +201 -0
- package/audit-lab/lab/examples/test-provider/src/rows.ts +173 -0
- package/audit-lab/lab/examples/test-provider/src/schema.ts +114 -0
- package/audit-lab/lab/examples/test-provider/src/signature.ts +86 -0
- package/audit-lab/lab/examples/test-provider/src/staged.ts +318 -0
- package/audit-lab/lab/examples/test-provider/src/store.ts +432 -0
- package/audit-lab/lab/examples/test-provider/src/traffic.ts +50 -0
- package/audit-lab/lab/examples/test-provider/src/webauthn.d.ts +11 -0
- package/audit-lab/lab/examples/test-provider/src/wire.ts +153 -0
- package/audit-lab/lab/examples/test-provider/tsconfig.build.json +9 -0
- package/audit-lab/lab/examples/test-provider/tsconfig.json +24 -0
- package/audit-lab/lab/images/capture/Dockerfile +15 -0
- package/audit-lab/lab/images/capture/LICENSE +201 -0
- package/audit-lab/lab/images/fault-control/Dockerfile +13 -0
- package/audit-lab/lab/images/fault-control/LICENSE +21 -0
- package/audit-lab/lab/images/provider-store/Dockerfile +4 -0
- package/audit-lab/lab/images/provider-store/LICENSE +23 -0
- package/audit-lab/lab/images/telemetry/Dockerfile +14 -0
- package/audit-lab/lab/images/telemetry/LICENSE +201 -0
- package/audit-lab/lab/scripts/compose-down.sh +148 -0
- package/audit-lab/lab/scripts/compose-lib.sh +663 -0
- package/audit-lab/lab/scripts/compose-up.sh +240 -0
- 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,182 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @mandateops/cli
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
// The test's name is also the run's label on the dashboard.
|
|
113
|
+
const name = "a retry after a lost response makes one payout";
|
|
114
|
+
|
|
115
|
+
test(
|
|
116
|
+
name,
|
|
117
|
+
async () => {
|
|
118
|
+
const result = await auditRun(
|
|
119
|
+
{ ...config, label: name },
|
|
120
|
+
retryAfterLostResponse,
|
|
121
|
+
);
|
|
122
|
+
expect(result.ci_passed).toBe(true);
|
|
123
|
+
},
|
|
124
|
+
runLimit(config),
|
|
125
|
+
);
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Run it with `bun test --timeout 300000`. The first run builds and pulls images, so it takes a few minutes.
|
|
129
|
+
|
|
130
|
+
## After the first green run: check your backend's own record
|
|
131
|
+
|
|
132
|
+
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:
|
|
133
|
+
|
|
134
|
+
```ts
|
|
135
|
+
import { defineAdapter, type PayoutState } from "@mandateops/audit";
|
|
136
|
+
|
|
137
|
+
/** Your backend's own record of a payout, mapped to the adapter's states. */
|
|
138
|
+
type BackendPayout = { state: PayoutState };
|
|
139
|
+
|
|
140
|
+
const statusAdapter = defineAdapter({
|
|
141
|
+
status: async ({ backend, viewerCredential, providerPayment }) => {
|
|
142
|
+
const url = new URL(`/payouts/${providerPayment}`, backend);
|
|
143
|
+
const response = await fetch(url, {
|
|
144
|
+
headers: { authorization: `Bearer ${viewerCredential}` },
|
|
145
|
+
});
|
|
146
|
+
const payout = (await response.json()) as BackendPayout;
|
|
147
|
+
return { source: "adapter", payment: providerPayment, state: payout.state };
|
|
148
|
+
},
|
|
149
|
+
});
|
|
150
|
+
|
|
151
|
+
const checked = defineConfig({
|
|
152
|
+
...config,
|
|
153
|
+
adapter: statusAdapter,
|
|
154
|
+
requiredChecks: ["provider-outcome", "backend-outcome"],
|
|
155
|
+
system: {
|
|
156
|
+
...config.system,
|
|
157
|
+
credentialEnv: { viewer: "VIEWER_KEY" },
|
|
158
|
+
},
|
|
159
|
+
});
|
|
160
|
+
|
|
161
|
+
test(
|
|
162
|
+
"the backend reports the payout it made",
|
|
163
|
+
async () => {
|
|
164
|
+
const result = await auditRun(checked, retryAfterLostResponse);
|
|
165
|
+
expect(result.ci_passed).toBe(true);
|
|
166
|
+
},
|
|
167
|
+
runLimit(checked),
|
|
168
|
+
);
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
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.
|
|
172
|
+
|
|
173
|
+
The `@mandateops/audit` page documents every configuration field, its default, the checks, the result and the exit codes.
|
|
174
|
+
|
|
175
|
+
## Limitations
|
|
176
|
+
|
|
177
|
+
- Test environment: no real money moves; real provider settlement is not covered. A pass says nothing about a real provider's idempotency.
|
|
178
|
+
- A run observes effects only within its drain window; a later payout is not seen.
|
|
179
|
+
- A sealed record detects accidental and partial edits, not forgery by someone who can rewrite the run directory.
|
|
180
|
+
- A test checks the scenarios it declares. It does not show the absence of other defects and is not a certification.
|
|
181
|
+
|
|
182
|
+
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
|
+
}
|