@wasit-dev/cli 0.1.0 → 0.1.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.
- package/README.md +144 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# @wasit-dev/cli
|
|
2
|
+
|
|
3
|
+
Protocol-compliance testing for **x402** and **MPP** on Stellar, from your terminal.
|
|
4
|
+
|
|
5
|
+
`wasit` runs the real payment flow against a live service and verifies the settlement independently — via Stellar RPC and the token contract's own on-chain transfer event, not by trusting the response the service returns. It is not a schema validator: a response can have every field in the right place and still take money without settling it.
|
|
6
|
+
|
|
7
|
+
**Testnet only.** Several checks settle real transactions — do not point this at pubnet or use production keys.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
# run once, no install
|
|
13
|
+
npx @wasit-dev/cli test --target <your-service-url>
|
|
14
|
+
|
|
15
|
+
# or install globally
|
|
16
|
+
npm install -g @wasit-dev/cli
|
|
17
|
+
wasit test --target <your-service-url>
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Requires Node.js `>=24`.
|
|
21
|
+
|
|
22
|
+
## Quick start
|
|
23
|
+
|
|
24
|
+
The default posture costs nothing — no keys required:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
wasit test --target https://your-service.example.com/paid --read-only
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
That runs the read-only x402 checks (`X402-01`–`05`): whether the service issues a well-formed 402 challenge. Drop `--read-only` and set `STELLAR_PRIVATE_KEY` to also exercise the payment flow — `X402-06`/`07` settle a real testnet payment.
|
|
31
|
+
|
|
32
|
+
## Commands
|
|
33
|
+
|
|
34
|
+
### `wasit test` — x402
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
wasit test --target <url> [options]
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
| Option | Default | Notes |
|
|
41
|
+
|---|---|---|
|
|
42
|
+
| `--target <url>` | required | Must include the scheme |
|
|
43
|
+
| `--network <id>` | `stellar:testnet` | CAIP-2 network id |
|
|
44
|
+
| `--payer-key <key>` | `STELLAR_PRIVATE_KEY` | Testnet secret key, `S...` |
|
|
45
|
+
| `--method <verb>` | `GET` | HTTP method the paid endpoint uses |
|
|
46
|
+
| `--body <json>` | — | Request body; implies `Content-Type: application/json` |
|
|
47
|
+
| `--header <name:value>` | — | Extra request header, repeatable |
|
|
48
|
+
| `--read-only` | off | Restricts the run to `X402-01`–`05` (no payment) |
|
|
49
|
+
|
|
50
|
+
Without a payer key, the payment checks are skipped automatically. When they run: **`X402-06` settles a real payment, `X402-07` attempts one with a corrupted signature** — testnet funds move on every call.
|
|
51
|
+
|
|
52
|
+
### `wasit mpp-charge` — MPP, charge mode
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
wasit mpp-charge --target <url> [options]
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
| Option | Default | Notes |
|
|
59
|
+
|---|---|---|
|
|
60
|
+
| `--target <url>` | required | The paid resource |
|
|
61
|
+
| `--payer-key <key>` | `MPP_PAYER_SECRET` | Secret key, `S...` |
|
|
62
|
+
| `--network <id>` | `MPP_STELLAR_NETWORK` | CAIP-2 |
|
|
63
|
+
| `--rpc-url <url>` | testnet default | Required for pubnet |
|
|
64
|
+
|
|
65
|
+
**Every run settles a real payment.** Charge mode has no dry run — a settlement that never happened cannot be verified on-chain.
|
|
66
|
+
|
|
67
|
+
### `wasit mpp-channel` — MPP, channel mode
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
wasit mpp-channel --target <url> [options]
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
| Option | Default | Notes |
|
|
74
|
+
|---|---|---|
|
|
75
|
+
| `--target <url>` | required | The paid resource |
|
|
76
|
+
| `--commitment-key <hex>` | `COMMITMENT_SECRET_HEX` | Raw ed25519 seed, hex — not an `S...` key |
|
|
77
|
+
| `--network <id>` | `MPP_STELLAR_NETWORK` | CAIP-2 |
|
|
78
|
+
| `--rpc-url <url>` | testnet default | Soroban RPC |
|
|
79
|
+
| `--channel <address>` | `CHANNEL_CONTRACT` | Asserts the expected channel; a mismatch fails `MPP-10` |
|
|
80
|
+
| `--expect-token <address>` | — | `MPP-10` parameter check |
|
|
81
|
+
| `--expect-from <address>` | — | `MPP-10` parameter check |
|
|
82
|
+
| `--expect-to <address>` | — | `MPP-10` parameter check |
|
|
83
|
+
| `--expect-refund-period <ledgers>` | — | `MPP-10` parameter check |
|
|
84
|
+
| `--allow-destructive` | off | Enables `MPP-13` (closes the channel — permanent) |
|
|
85
|
+
| `--destructive-channel <address>` | `CHANNEL_CONTRACT_DISPOSABLE` | Channel `MPP-13` is permitted to close |
|
|
86
|
+
|
|
87
|
+
`MPP-10`–`12` and `MPP-14` cost nothing. `MPP-13` is skipped unless `--allow-destructive` and a named disposable channel are both given — it permanently ends a channel and cannot be undone.
|
|
88
|
+
|
|
89
|
+
`--channel` **asserts**, it does not select: the channel under test is resolved from the target's own 402 challenge, so every check in a run reports on the same contract. When `--channel` differs from what the target advertises, `MPP-10` fails and inspects nothing.
|
|
90
|
+
|
|
91
|
+
## Reading output
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
PASS X402-01 402 Response Status
|
|
95
|
+
Server responded with 402 as required.
|
|
96
|
+
|
|
97
|
+
FAIL X402-01 402 Response Status
|
|
98
|
+
Expected status 402, got 404.
|
|
99
|
+
|
|
100
|
+
SKIP X402-02 Payment Header Present
|
|
101
|
+
Skipped: the target answered 404 rather than 402, so it issued no
|
|
102
|
+
payment challenge to inspect.
|
|
103
|
+
|
|
104
|
+
7 passed.
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
`PREFLIGHT` appears in place of the checks when the target URL or network identifier itself is invalid — both are wrong for every check in the suite, so it's reported once rather than repeated identically.
|
|
108
|
+
|
|
109
|
+
## Exit codes
|
|
110
|
+
|
|
111
|
+
| Code | Meaning |
|
|
112
|
+
|---|---|
|
|
113
|
+
| `0` | Every check that ran conformed |
|
|
114
|
+
| `1` | At least one conformance failure |
|
|
115
|
+
| `2` | At least one check produced no verdict (unreachable target, bad config) |
|
|
116
|
+
|
|
117
|
+
A run with both a failure and an error exits `1` — a real finding outranks a missing one. Skipped checks never affect the exit code.
|
|
118
|
+
|
|
119
|
+
## Configuration
|
|
120
|
+
|
|
121
|
+
| Env var | Used by |
|
|
122
|
+
|---|---|
|
|
123
|
+
| `STELLAR_PRIVATE_KEY` | `test` (x402 payment checks) |
|
|
124
|
+
| `MPP_PAYER_SECRET` | `mpp-charge` |
|
|
125
|
+
| `MPP_STELLAR_NETWORK` | `mpp-charge`, `mpp-channel` |
|
|
126
|
+
| `COMMITMENT_SECRET_HEX` | `mpp-channel` |
|
|
127
|
+
| `CHANNEL_CONTRACT` | `mpp-channel` (optional assertion) |
|
|
128
|
+
| `CHANNEL_CONTRACT_DISPOSABLE` | `mpp-channel --allow-destructive` |
|
|
129
|
+
|
|
130
|
+
All keys are **testnet only**. `wasit` also reads a `.env` file in the current working directory — pass `--payer-key` / `--commitment-key` directly to override it for a single run.
|
|
131
|
+
|
|
132
|
+
## What's checked
|
|
133
|
+
|
|
134
|
+
Thirteen checks across x402 and MPP, each traced to a written spec clause — the full catalogue, with pass criteria and spec references, is in [`docs/CHECKS.md`](https://github.com/dzakwannajmi/wasit/blob/main/docs/CHECKS.md).
|
|
135
|
+
|
|
136
|
+
## Related
|
|
137
|
+
|
|
138
|
+
- [`@wasit-dev/core`](https://www.npmjs.com/package/@wasit-dev/core) — the check suite this CLI runs, if you're building your own tooling on top
|
|
139
|
+
- [`@wasit-dev/server`](https://www.npmjs.com/package/@wasit-dev/server) — the same checks as MCP tools, for Claude Code and other agents
|
|
140
|
+
- [Full documentation](https://github.com/dzakwannajmi/wasit) — CLI guide, MCP guide, configuration, design notes
|
|
141
|
+
|
|
142
|
+
## License
|
|
143
|
+
|
|
144
|
+
Apache-2.0 — see [LICENSE](https://github.com/dzakwannajmi/wasit/blob/main/LICENSE).
|
package/package.json
CHANGED