botsrated 0.2.1__tar.gz → 0.3.1__tar.gz
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.
- {botsrated-0.2.1 → botsrated-0.3.1}/PKG-INFO +49 -16
- {botsrated-0.2.1 → botsrated-0.3.1}/README.md +48 -15
- {botsrated-0.2.1 → botsrated-0.3.1}/pyproject.toml +1 -1
- {botsrated-0.2.1 → botsrated-0.3.1}/src/botsrated/__init__.py +2 -0
- {botsrated-0.2.1 → botsrated-0.3.1}/src/botsrated/client.py +6 -2
- {botsrated-0.2.1 → botsrated-0.3.1}/src/botsrated/guard.py +45 -3
- {botsrated-0.2.1 → botsrated-0.3.1}/src/botsrated/payment_guard.py +270 -4
- {botsrated-0.2.1 → botsrated-0.3.1}/src/botsrated/util.py +1 -1
- botsrated-0.3.1/tests/test_remote_policy.py +301 -0
- {botsrated-0.2.1 → botsrated-0.3.1}/.gitignore +0 -0
- {botsrated-0.2.1 → botsrated-0.3.1}/LICENSE +0 -0
- {botsrated-0.2.1 → botsrated-0.3.1}/src/botsrated/onchain.py +0 -0
- {botsrated-0.2.1 → botsrated-0.3.1}/src/botsrated/py.typed +0 -0
- {botsrated-0.2.1 → botsrated-0.3.1}/tests/conftest.py +0 -0
- {botsrated-0.2.1 → botsrated-0.3.1}/tests/test_c1_no_repay.py +0 -0
- {botsrated-0.2.1 → botsrated-0.3.1}/tests/test_guard.py +0 -0
- {botsrated-0.2.1 → botsrated-0.3.1}/tests/test_onchain.py +0 -0
- {botsrated-0.2.1 → botsrated-0.3.1}/tests/test_payment_guard.py +0 -0
- {botsrated-0.2.1 → botsrated-0.3.1}/tests/test_x402_sdk.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: botsrated
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.3.1
|
|
4
4
|
Summary: Payment guard for x402 agents: checks facts BotsRated measured about a seller before paying (advice-only by default), adds a payment-identifier retry key where supported, and checks on chain, read-only, whether a payment settled once. Not affiliated with Coinbase or the x402 Foundation.
|
|
5
5
|
Project-URL: Homepage, https://botsrated.com
|
|
6
6
|
Project-URL: Repository, https://github.com/botsrated/botsrated
|
|
@@ -19,6 +19,19 @@ Description-Content-Type: text/markdown
|
|
|
19
19
|
|
|
20
20
|
# botsrated (Python)
|
|
21
21
|
|
|
22
|
+
## Install in 3 steps
|
|
23
|
+
|
|
24
|
+
1. Install: `pip install "botsrated[x402]"` (PyPI 0.3.1).
|
|
25
|
+
2. Attach to your x402 client:
|
|
26
|
+
```python
|
|
27
|
+
from botsrated import PaymentGuard
|
|
28
|
+
guard = PaymentGuard(preset="carefulBuyer")
|
|
29
|
+
guard.install(client)
|
|
30
|
+
```
|
|
31
|
+
3. Pick `preset` (omit it, or call `PaymentGuard()`, for advice only; `carefulBuyer` / `strict` stop an unobserved payTo). Omit `fail_mode` inside `remote_policy` to stay open. `"closed"` stops the payment when BotsRated or your policy cannot answer. A missing decision is never a pass. A remote pass never clears a local block. Wrap the paying call with `guard.wrap_get` / `guard.wrap_async_get` so the guard knows the paid URL.
|
|
32
|
+
|
|
33
|
+
`BOTSRATED_TOKEN` is optional. Framework attaches read it when `token` is omitted and send it only as `remote_policy` on botsrated 0.3.0 and later, never as a bare string. A configured token on a core without `parse_remote_policy` raises and is not dropped. The policy decision is not signed. Get a token in [Desk](https://botsrated.com/desk). Nothing defaults you to closed.
|
|
34
|
+
|
|
22
35
|
The BotsRated **payment guard** for x402 clients, plus a simpler pre-payment check.
|
|
23
36
|
|
|
24
37
|
- **Before your agent signs**, it looks up facts [BotsRated](https://botsrated.com) measured about the seller's host
|
|
@@ -30,12 +43,11 @@ The BotsRated **payment guard** for x402 clients, plus a simpler pre-payment che
|
|
|
30
43
|
|
|
31
44
|
It lowers the chance of paying the wrong address or paying twice; it can't rule either out.
|
|
32
45
|
|
|
33
|
-
**Status: 0.
|
|
34
|
-
[`botsrated` 0.1.6](https://pypi.org/project/botsrated/), which does not include the payment guard.**
|
|
46
|
+
**Status: published on PyPI as [`botsrated` 0.3.1](https://pypi.org/project/botsrated/)** (this release; includes `remote_policy`).
|
|
35
47
|
|
|
36
48
|
**What this does and doesn't do.** This package checks facts BotsRated measured about a seller before your agent signs, adds a retry key to the payment request, and reads the blockchain to see whether a payment already settled. It can't promise that a payment is right, that a seller will deliver, or that you'll never pay twice: a retry key only stops a second charge if the seller supports the x402 `payment-identifier` extension, and on-chain reads can be late or fail. You choose the rules that stop a payment, and you remain responsible for what your agent pays. Provided under the MIT license, "as is", without warranty.
|
|
37
49
|
|
|
38
|
-
**Hosted checks.** By default (`hosted=True`) this package calls BotsRated's
|
|
50
|
+
**Hosted checks.** By default (`hosted=True`) this package calls BotsRated's preflight (`https://botsrated.com/v1/preflight`; free, no key, rate limits) and sends it **only the seller's host name** (never the path, query, wallet, amount, nonce, payment header or request body). Those calls are covered by the BotsRated Terms (https://botsrated.com/terms) and Privacy Policy (https://botsrated.com/privacy), not by the MIT license. `hosted=False` turns hosted checks off: nothing is then sent to botsrated.com, and only the local checks, the retry key and the on-chain check (which goes only to the RPCs you set) run.
|
|
39
51
|
|
|
40
52
|
## Install
|
|
41
53
|
|
|
@@ -49,7 +61,7 @@ uses the hook and extension points of the x402 client you pass in.
|
|
|
49
61
|
## Payment Guard: Pick A Preset
|
|
50
62
|
|
|
51
63
|
You set the thresholds. The guard compares the payment with facts BotsRated measured and, when the preflight included
|
|
52
|
-
one, a receipt link.
|
|
64
|
+
one, a receipt link.
|
|
53
65
|
|
|
54
66
|
Pick a named preset. The zero-config call (`PaymentGuard()`) is `warn`: advice only, it never stops a payment.
|
|
55
67
|
Dry-run is optional: it logs `would_block` and still never stops a payment.
|
|
@@ -128,7 +140,7 @@ never echoed except a parsed host name.
|
|
|
128
140
|
|
|
129
141
|
### Facts Bundle
|
|
130
142
|
|
|
131
|
-
`decision.facts` is the bundle the guard compared. It is measurements plus a receipt link.
|
|
143
|
+
`decision.facts` is the bundle the guard compared. It is measurements plus a receipt link.
|
|
132
144
|
|
|
133
145
|
| Field | What it is |
|
|
134
146
|
|---|---|
|
|
@@ -146,7 +158,7 @@ https://botsrated.com/disputes. `would_block` is true when a rule's effect is `b
|
|
|
146
158
|
`action` stays `allow`.
|
|
147
159
|
|
|
148
160
|
The hosted preflight body is larger (see the MCP facts bundle in the repository README). The guard keeps this
|
|
149
|
-
smaller local bundle and does not
|
|
161
|
+
smaller local bundle and does not add a summary number, because the response has none.
|
|
150
162
|
|
|
151
163
|
### Options
|
|
152
164
|
|
|
@@ -162,6 +174,7 @@ smaller local bundle and does not copy a score out of it, because the response h
|
|
|
162
174
|
| `timeout` / `cache_ttl` | 3 s / 5 min | Hosted lookup timeout and per-host cache |
|
|
163
175
|
| `preflight` | hosted call | Your own lookup `(host) -> (found, body)` |
|
|
164
176
|
| `on_decision` | none | Receives every decision (errors in it are ignored) |
|
|
177
|
+
| `remote_policy` | unset | Private policy check. See below. Unset: local presets only |
|
|
165
178
|
|
|
166
179
|
### Fail-Open Or Fail-Closed
|
|
167
180
|
|
|
@@ -172,16 +185,36 @@ smaller local bundle and does not copy a score out of it, because the response h
|
|
|
172
185
|
for you than a missed call.
|
|
173
186
|
- Local checks (`resource_host_mismatch`, `payto_invalid`) and the on-chain check never depend on botsrated.com.
|
|
174
187
|
|
|
188
|
+
### Remote Policy
|
|
189
|
+
|
|
190
|
+
Optional. Set `remote_policy` to ask your private policy on BotsRated before a payment. The guard merges that answer with the local rules. A remote block stops the payment. A remote pass does not clear a local block. `PrePaymentGuard(..., remote_policy=...)` uses the same check.
|
|
191
|
+
|
|
192
|
+
This is the path that makes `BOTSRATED_TOKEN` work in framework attaches. The token is optional. The guard defaults to advice-only with no key, so anyone can install it as a default. The client enforces. BotsRated holds no funds, signs nothing, and has no escrow.
|
|
193
|
+
|
|
194
|
+
```python
|
|
195
|
+
guard = PaymentGuard(
|
|
196
|
+
preset="carefulBuyer",
|
|
197
|
+
remote_policy={"token": "<bearer>", "fail_mode": "open"}, # omit fail_mode for open; "closed" is opt-in
|
|
198
|
+
)
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
`fail_mode` is yours: `open` or `closed`. Omit it and the check stays open. Nothing defaults you to closed. `"closed"` stops the payment when BotsRated or your policy cannot answer. The guard `POST`s `/v1/policy/check` with the seller host and the quote (`payTo`, `amount`, `asset`, `network`). On HTTP 503, HTTP 404, or `"decision": null`, it applies `fail_mode` (`open`: an info reason, payment continues unless a local rule stops it; `closed`: the payment stops). A missing decision is never a pass. A remote pass never clears a local block. Server fields are kept when the server sends them. The last `policy_version` is remembered on the guard. The policy decision is not signed. Leave `remote_policy` unset and local presets behave as before.
|
|
202
|
+
|
|
203
|
+
`BOTSRATED_TOKEN` is optional. Framework attaches read it when `token` is omitted and send it only as `remote_policy` on botsrated 0.3.0 and later. A configured token on a core without `parse_remote_policy` raises and is not dropped. Get a token in [Desk](https://botsrated.com/desk).
|
|
204
|
+
|
|
175
205
|
### What The Guard Sends, And To Whom
|
|
176
206
|
|
|
177
|
-
- **botsrated.com:** `GET /v1/preflight?url=<host name>` with `User-Agent: botsrated-python/<version>`.
|
|
207
|
+
- **botsrated.com (preflight):** `GET /v1/preflight?url=<host name>` with `User-Agent: botsrated-python/<version>`.
|
|
178
208
|
Never the path, query, wallet, amount, nonce, tx hash, payment header or request body. No install id. Covered by
|
|
179
209
|
the [Terms](https://botsrated.com/terms) and [Privacy Policy](https://botsrated.com/privacy). Turn it off with
|
|
180
210
|
`hosted=False`.
|
|
211
|
+
- **botsrated.com (only when `remote_policy` is set):** `POST /v1/policy/check` with the host, the quote
|
|
212
|
+
(`payTo`, `amount`, `asset`, `network`) and your bearer token. Not the path, query, payer wallet, nonce or a
|
|
213
|
+
payment header. The decision is not signed. `hosted=False` does not turn this off.
|
|
181
214
|
- **Base RPCs (only when you call `payment_state`; nothing calls them automatically):** JSON-RPC reads that include
|
|
182
215
|
the payer address and the payment's nonce, sent straight from your machine to the RPCs, never to BotsRated.
|
|
183
216
|
See the privacy note under "Did It Settle Once?".
|
|
184
|
-
- No
|
|
217
|
+
- No feature flags or auto-update: behavior changes only with a new package version, or with `remote_policy` when you set it.
|
|
185
218
|
|
|
186
219
|
### Retry Key (`payment-identifier`)
|
|
187
220
|
|
|
@@ -206,7 +239,7 @@ state = guard.payment_state(rec) # or: await guard.apayment_state(rec). Re
|
|
|
206
239
|
|
|
207
240
|
There are three answers only:
|
|
208
241
|
|
|
209
|
-
- `settled`: two RPCs on different hosts (or two of three, see below) show the EIP-3009 authorization used at Base's
|
|
242
|
+
- `settled`: two RPCs on different hosts (or two of three, see below) show the EIP-3009 authorization used at Base's default confirmation tag,
|
|
210
243
|
the chain id is 8453, and the transaction receipt has `AuthorizationUsed(from, nonce)` and
|
|
211
244
|
`Transfer(from, payTo, amount)` emitted by the pinned USDC contract `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`.
|
|
212
245
|
- `unknown` (`payment_state_unknown`) with `wait_until`: not settled yet, the RPCs disagree or failed, the blocks
|
|
@@ -214,7 +247,7 @@ There are three answers only:
|
|
|
214
247
|
checked. **Do not sign a new payment for that purchase before `wait_until`** (the signed authorization stays
|
|
215
248
|
valid until its `validBefore`, plus a margin of at least 30 s).
|
|
216
249
|
- `expired_unsettled`: `validBefore` plus the margin has passed on the clock **and** in the chain: both RPCs show
|
|
217
|
-
the authorization unused at a block (Base's
|
|
250
|
+
the authorization unused at a block (Base's default confirmation tag) whose timestamp is at or after `validBefore`
|
|
218
251
|
plus the margin. USDC accepts an authorization in any block before `validBefore`, so "unused" only counts in a
|
|
219
252
|
later block. With the default 60 s margin this is usually 1 to 3 minutes after expiry. Only then is a fresh
|
|
220
253
|
payment free of a double-charge risk from the first one.
|
|
@@ -225,7 +258,7 @@ It is clamped, not rejected: a value below 30 (including negative values and `-i
|
|
|
225
258
|
`expiry_tag="finalized"` waits for a finalized block past expiry instead (more conservative, usually 20+ minutes).
|
|
226
259
|
|
|
227
260
|
The guard never retries on `unknown`. botsrated.com is never asked; a tx hash the seller reports is only a hint
|
|
228
|
-
that is
|
|
261
|
+
that is checked on chain.
|
|
229
262
|
|
|
230
263
|
**Default RPCs** (two operators; both must answer and agree):
|
|
231
264
|
|
|
@@ -320,8 +353,8 @@ botsrated = BotsRatedClient(budget_usd="0.05", x402_client=client) # signs onl
|
|
|
320
353
|
guard = PrePaymentGuard(botsrated, paid_check_at_or_above_usd=0.25)
|
|
321
354
|
client.on_before_payment_creation(guard.x402_hook)
|
|
322
355
|
|
|
323
|
-
botsrated.check("seller.example") # $0.001 (first 25 per UTC day free)
|
|
324
|
-
botsrated.report("seller.example") # $0.002 (first 3 per UTC day free)
|
|
356
|
+
botsrated.check("seller.example") # $0.001 (first 25 per client IP per UTC day free)
|
|
357
|
+
botsrated.report("seller.example") # $0.002 (first 3 per client IP per UTC day free)
|
|
325
358
|
botsrated.best("web search") # $0.01
|
|
326
359
|
```
|
|
327
360
|
|
|
@@ -333,11 +366,11 @@ the allowlisted fields only (scheme, network, asset, amount, payTo, maxTimeoutSe
|
|
|
333
366
|
itself, so register the guard on the same x402 client so the re-served 402 is checked again before signing.
|
|
334
367
|
|
|
335
368
|
How paid calls work:
|
|
336
|
-
- Free daily quota (`FREE_DAILY_QUOTA`): the first 25 `/v1/check` and 3 `/v1/report` calls per client per UTC day are
|
|
369
|
+
- Free daily quota (`FREE_DAILY_QUOTA`): the first 25 `/v1/check` and 3 `/v1/report` calls per client IP per UTC day are
|
|
337
370
|
served free (200 with `charged: false` and a `free_quota` block). The client asks unpaid first, so
|
|
338
371
|
inside the quota nothing is paid and the budget is untouched; `check()`/`report()` also work without
|
|
339
372
|
a budget until the quota is used up (then `paid_disabled`). `client.last_free_quota` shows what is left.
|
|
340
|
-
`/v1/best` has no free quota. Preflight stays free
|
|
373
|
+
`/v1/best` has no free quota. Preflight stays free, no key, rate limits.
|
|
341
374
|
- Otherwise the client reads the 402 quote unpaid first. It accepts the quote only if **every** option is `exact` USDC on Base to BotsRated's payTo
|
|
342
375
|
`0x7F936f42F46B6c4Cbd3242cF8A1759dfe829E349`, at or below the published price.
|
|
343
376
|
- The amount is reserved from the budget before paying. If the paid call fails or raises, it stays counted
|
|
@@ -1,5 +1,18 @@
|
|
|
1
1
|
# botsrated (Python)
|
|
2
2
|
|
|
3
|
+
## Install in 3 steps
|
|
4
|
+
|
|
5
|
+
1. Install: `pip install "botsrated[x402]"` (PyPI 0.3.1).
|
|
6
|
+
2. Attach to your x402 client:
|
|
7
|
+
```python
|
|
8
|
+
from botsrated import PaymentGuard
|
|
9
|
+
guard = PaymentGuard(preset="carefulBuyer")
|
|
10
|
+
guard.install(client)
|
|
11
|
+
```
|
|
12
|
+
3. Pick `preset` (omit it, or call `PaymentGuard()`, for advice only; `carefulBuyer` / `strict` stop an unobserved payTo). Omit `fail_mode` inside `remote_policy` to stay open. `"closed"` stops the payment when BotsRated or your policy cannot answer. A missing decision is never a pass. A remote pass never clears a local block. Wrap the paying call with `guard.wrap_get` / `guard.wrap_async_get` so the guard knows the paid URL.
|
|
13
|
+
|
|
14
|
+
`BOTSRATED_TOKEN` is optional. Framework attaches read it when `token` is omitted and send it only as `remote_policy` on botsrated 0.3.0 and later, never as a bare string. A configured token on a core without `parse_remote_policy` raises and is not dropped. The policy decision is not signed. Get a token in [Desk](https://botsrated.com/desk). Nothing defaults you to closed.
|
|
15
|
+
|
|
3
16
|
The BotsRated **payment guard** for x402 clients, plus a simpler pre-payment check.
|
|
4
17
|
|
|
5
18
|
- **Before your agent signs**, it looks up facts [BotsRated](https://botsrated.com) measured about the seller's host
|
|
@@ -11,12 +24,11 @@ The BotsRated **payment guard** for x402 clients, plus a simpler pre-payment che
|
|
|
11
24
|
|
|
12
25
|
It lowers the chance of paying the wrong address or paying twice; it can't rule either out.
|
|
13
26
|
|
|
14
|
-
**Status: 0.
|
|
15
|
-
[`botsrated` 0.1.6](https://pypi.org/project/botsrated/), which does not include the payment guard.**
|
|
27
|
+
**Status: published on PyPI as [`botsrated` 0.3.1](https://pypi.org/project/botsrated/)** (this release; includes `remote_policy`).
|
|
16
28
|
|
|
17
29
|
**What this does and doesn't do.** This package checks facts BotsRated measured about a seller before your agent signs, adds a retry key to the payment request, and reads the blockchain to see whether a payment already settled. It can't promise that a payment is right, that a seller will deliver, or that you'll never pay twice: a retry key only stops a second charge if the seller supports the x402 `payment-identifier` extension, and on-chain reads can be late or fail. You choose the rules that stop a payment, and you remain responsible for what your agent pays. Provided under the MIT license, "as is", without warranty.
|
|
18
30
|
|
|
19
|
-
**Hosted checks.** By default (`hosted=True`) this package calls BotsRated's
|
|
31
|
+
**Hosted checks.** By default (`hosted=True`) this package calls BotsRated's preflight (`https://botsrated.com/v1/preflight`; free, no key, rate limits) and sends it **only the seller's host name** (never the path, query, wallet, amount, nonce, payment header or request body). Those calls are covered by the BotsRated Terms (https://botsrated.com/terms) and Privacy Policy (https://botsrated.com/privacy), not by the MIT license. `hosted=False` turns hosted checks off: nothing is then sent to botsrated.com, and only the local checks, the retry key and the on-chain check (which goes only to the RPCs you set) run.
|
|
20
32
|
|
|
21
33
|
## Install
|
|
22
34
|
|
|
@@ -30,7 +42,7 @@ uses the hook and extension points of the x402 client you pass in.
|
|
|
30
42
|
## Payment Guard: Pick A Preset
|
|
31
43
|
|
|
32
44
|
You set the thresholds. The guard compares the payment with facts BotsRated measured and, when the preflight included
|
|
33
|
-
one, a receipt link.
|
|
45
|
+
one, a receipt link.
|
|
34
46
|
|
|
35
47
|
Pick a named preset. The zero-config call (`PaymentGuard()`) is `warn`: advice only, it never stops a payment.
|
|
36
48
|
Dry-run is optional: it logs `would_block` and still never stops a payment.
|
|
@@ -109,7 +121,7 @@ never echoed except a parsed host name.
|
|
|
109
121
|
|
|
110
122
|
### Facts Bundle
|
|
111
123
|
|
|
112
|
-
`decision.facts` is the bundle the guard compared. It is measurements plus a receipt link.
|
|
124
|
+
`decision.facts` is the bundle the guard compared. It is measurements plus a receipt link.
|
|
113
125
|
|
|
114
126
|
| Field | What it is |
|
|
115
127
|
|---|---|
|
|
@@ -127,7 +139,7 @@ https://botsrated.com/disputes. `would_block` is true when a rule's effect is `b
|
|
|
127
139
|
`action` stays `allow`.
|
|
128
140
|
|
|
129
141
|
The hosted preflight body is larger (see the MCP facts bundle in the repository README). The guard keeps this
|
|
130
|
-
smaller local bundle and does not
|
|
142
|
+
smaller local bundle and does not add a summary number, because the response has none.
|
|
131
143
|
|
|
132
144
|
### Options
|
|
133
145
|
|
|
@@ -143,6 +155,7 @@ smaller local bundle and does not copy a score out of it, because the response h
|
|
|
143
155
|
| `timeout` / `cache_ttl` | 3 s / 5 min | Hosted lookup timeout and per-host cache |
|
|
144
156
|
| `preflight` | hosted call | Your own lookup `(host) -> (found, body)` |
|
|
145
157
|
| `on_decision` | none | Receives every decision (errors in it are ignored) |
|
|
158
|
+
| `remote_policy` | unset | Private policy check. See below. Unset: local presets only |
|
|
146
159
|
|
|
147
160
|
### Fail-Open Or Fail-Closed
|
|
148
161
|
|
|
@@ -153,16 +166,36 @@ smaller local bundle and does not copy a score out of it, because the response h
|
|
|
153
166
|
for you than a missed call.
|
|
154
167
|
- Local checks (`resource_host_mismatch`, `payto_invalid`) and the on-chain check never depend on botsrated.com.
|
|
155
168
|
|
|
169
|
+
### Remote Policy
|
|
170
|
+
|
|
171
|
+
Optional. Set `remote_policy` to ask your private policy on BotsRated before a payment. The guard merges that answer with the local rules. A remote block stops the payment. A remote pass does not clear a local block. `PrePaymentGuard(..., remote_policy=...)` uses the same check.
|
|
172
|
+
|
|
173
|
+
This is the path that makes `BOTSRATED_TOKEN` work in framework attaches. The token is optional. The guard defaults to advice-only with no key, so anyone can install it as a default. The client enforces. BotsRated holds no funds, signs nothing, and has no escrow.
|
|
174
|
+
|
|
175
|
+
```python
|
|
176
|
+
guard = PaymentGuard(
|
|
177
|
+
preset="carefulBuyer",
|
|
178
|
+
remote_policy={"token": "<bearer>", "fail_mode": "open"}, # omit fail_mode for open; "closed" is opt-in
|
|
179
|
+
)
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
`fail_mode` is yours: `open` or `closed`. Omit it and the check stays open. Nothing defaults you to closed. `"closed"` stops the payment when BotsRated or your policy cannot answer. The guard `POST`s `/v1/policy/check` with the seller host and the quote (`payTo`, `amount`, `asset`, `network`). On HTTP 503, HTTP 404, or `"decision": null`, it applies `fail_mode` (`open`: an info reason, payment continues unless a local rule stops it; `closed`: the payment stops). A missing decision is never a pass. A remote pass never clears a local block. Server fields are kept when the server sends them. The last `policy_version` is remembered on the guard. The policy decision is not signed. Leave `remote_policy` unset and local presets behave as before.
|
|
183
|
+
|
|
184
|
+
`BOTSRATED_TOKEN` is optional. Framework attaches read it when `token` is omitted and send it only as `remote_policy` on botsrated 0.3.0 and later. A configured token on a core without `parse_remote_policy` raises and is not dropped. Get a token in [Desk](https://botsrated.com/desk).
|
|
185
|
+
|
|
156
186
|
### What The Guard Sends, And To Whom
|
|
157
187
|
|
|
158
|
-
- **botsrated.com:** `GET /v1/preflight?url=<host name>` with `User-Agent: botsrated-python/<version>`.
|
|
188
|
+
- **botsrated.com (preflight):** `GET /v1/preflight?url=<host name>` with `User-Agent: botsrated-python/<version>`.
|
|
159
189
|
Never the path, query, wallet, amount, nonce, tx hash, payment header or request body. No install id. Covered by
|
|
160
190
|
the [Terms](https://botsrated.com/terms) and [Privacy Policy](https://botsrated.com/privacy). Turn it off with
|
|
161
191
|
`hosted=False`.
|
|
192
|
+
- **botsrated.com (only when `remote_policy` is set):** `POST /v1/policy/check` with the host, the quote
|
|
193
|
+
(`payTo`, `amount`, `asset`, `network`) and your bearer token. Not the path, query, payer wallet, nonce or a
|
|
194
|
+
payment header. The decision is not signed. `hosted=False` does not turn this off.
|
|
162
195
|
- **Base RPCs (only when you call `payment_state`; nothing calls them automatically):** JSON-RPC reads that include
|
|
163
196
|
the payer address and the payment's nonce, sent straight from your machine to the RPCs, never to BotsRated.
|
|
164
197
|
See the privacy note under "Did It Settle Once?".
|
|
165
|
-
- No
|
|
198
|
+
- No feature flags or auto-update: behavior changes only with a new package version, or with `remote_policy` when you set it.
|
|
166
199
|
|
|
167
200
|
### Retry Key (`payment-identifier`)
|
|
168
201
|
|
|
@@ -187,7 +220,7 @@ state = guard.payment_state(rec) # or: await guard.apayment_state(rec). Re
|
|
|
187
220
|
|
|
188
221
|
There are three answers only:
|
|
189
222
|
|
|
190
|
-
- `settled`: two RPCs on different hosts (or two of three, see below) show the EIP-3009 authorization used at Base's
|
|
223
|
+
- `settled`: two RPCs on different hosts (or two of three, see below) show the EIP-3009 authorization used at Base's default confirmation tag,
|
|
191
224
|
the chain id is 8453, and the transaction receipt has `AuthorizationUsed(from, nonce)` and
|
|
192
225
|
`Transfer(from, payTo, amount)` emitted by the pinned USDC contract `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`.
|
|
193
226
|
- `unknown` (`payment_state_unknown`) with `wait_until`: not settled yet, the RPCs disagree or failed, the blocks
|
|
@@ -195,7 +228,7 @@ There are three answers only:
|
|
|
195
228
|
checked. **Do not sign a new payment for that purchase before `wait_until`** (the signed authorization stays
|
|
196
229
|
valid until its `validBefore`, plus a margin of at least 30 s).
|
|
197
230
|
- `expired_unsettled`: `validBefore` plus the margin has passed on the clock **and** in the chain: both RPCs show
|
|
198
|
-
the authorization unused at a block (Base's
|
|
231
|
+
the authorization unused at a block (Base's default confirmation tag) whose timestamp is at or after `validBefore`
|
|
199
232
|
plus the margin. USDC accepts an authorization in any block before `validBefore`, so "unused" only counts in a
|
|
200
233
|
later block. With the default 60 s margin this is usually 1 to 3 minutes after expiry. Only then is a fresh
|
|
201
234
|
payment free of a double-charge risk from the first one.
|
|
@@ -206,7 +239,7 @@ It is clamped, not rejected: a value below 30 (including negative values and `-i
|
|
|
206
239
|
`expiry_tag="finalized"` waits for a finalized block past expiry instead (more conservative, usually 20+ minutes).
|
|
207
240
|
|
|
208
241
|
The guard never retries on `unknown`. botsrated.com is never asked; a tx hash the seller reports is only a hint
|
|
209
|
-
that is
|
|
242
|
+
that is checked on chain.
|
|
210
243
|
|
|
211
244
|
**Default RPCs** (two operators; both must answer and agree):
|
|
212
245
|
|
|
@@ -301,8 +334,8 @@ botsrated = BotsRatedClient(budget_usd="0.05", x402_client=client) # signs onl
|
|
|
301
334
|
guard = PrePaymentGuard(botsrated, paid_check_at_or_above_usd=0.25)
|
|
302
335
|
client.on_before_payment_creation(guard.x402_hook)
|
|
303
336
|
|
|
304
|
-
botsrated.check("seller.example") # $0.001 (first 25 per UTC day free)
|
|
305
|
-
botsrated.report("seller.example") # $0.002 (first 3 per UTC day free)
|
|
337
|
+
botsrated.check("seller.example") # $0.001 (first 25 per client IP per UTC day free)
|
|
338
|
+
botsrated.report("seller.example") # $0.002 (first 3 per client IP per UTC day free)
|
|
306
339
|
botsrated.best("web search") # $0.01
|
|
307
340
|
```
|
|
308
341
|
|
|
@@ -314,11 +347,11 @@ the allowlisted fields only (scheme, network, asset, amount, payTo, maxTimeoutSe
|
|
|
314
347
|
itself, so register the guard on the same x402 client so the re-served 402 is checked again before signing.
|
|
315
348
|
|
|
316
349
|
How paid calls work:
|
|
317
|
-
- Free daily quota (`FREE_DAILY_QUOTA`): the first 25 `/v1/check` and 3 `/v1/report` calls per client per UTC day are
|
|
350
|
+
- Free daily quota (`FREE_DAILY_QUOTA`): the first 25 `/v1/check` and 3 `/v1/report` calls per client IP per UTC day are
|
|
318
351
|
served free (200 with `charged: false` and a `free_quota` block). The client asks unpaid first, so
|
|
319
352
|
inside the quota nothing is paid and the budget is untouched; `check()`/`report()` also work without
|
|
320
353
|
a budget until the quota is used up (then `paid_disabled`). `client.last_free_quota` shows what is left.
|
|
321
|
-
`/v1/best` has no free quota. Preflight stays free
|
|
354
|
+
`/v1/best` has no free quota. Preflight stays free, no key, rate limits.
|
|
322
355
|
- Otherwise the client reads the 402 quote unpaid first. It accepts the quote only if **every** option is `exact` USDC on Base to BotsRated's payTo
|
|
323
356
|
`0x7F936f42F46B6c4Cbd3242cF8A1759dfe829E349`, at or below the published price.
|
|
324
357
|
- The amount is reserved from the budget before paying. If the paid call fails or raises, it stays counted
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "botsrated"
|
|
3
|
-
version = "0.
|
|
3
|
+
version = "0.3.1"
|
|
4
4
|
description = "Payment guard for x402 agents: checks facts BotsRated measured about a seller before paying (advice-only by default), adds a payment-identifier retry key where supported, and checks on chain, read-only, whether a payment settled once. Not affiliated with Coinbase or the x402 Foundation."
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
license = "MIT"
|
|
@@ -20,6 +20,7 @@ from botsrated.payment_guard import (
|
|
|
20
20
|
GuardReason,
|
|
21
21
|
PaymentGuard,
|
|
22
22
|
PaymentGuardPolicy,
|
|
23
|
+
RemotePolicy,
|
|
23
24
|
dry_run_only,
|
|
24
25
|
)
|
|
25
26
|
from botsrated.util import (
|
|
@@ -133,6 +134,7 @@ __all__ = [
|
|
|
133
134
|
"PrePaymentGuard",
|
|
134
135
|
"PreflightResult",
|
|
135
136
|
"Reason",
|
|
137
|
+
"RemotePolicy",
|
|
136
138
|
"SellerFacts",
|
|
137
139
|
"acheck_payment_state",
|
|
138
140
|
"check_payment_state",
|
|
@@ -226,6 +226,10 @@ class BotsRatedClient:
|
|
|
226
226
|
except httpx.HTTPError as e:
|
|
227
227
|
raise BotsRatedError(f"BotsRated unreachable: {clean_text(e, 80)}", "unreachable") from e
|
|
228
228
|
|
|
229
|
+
def unpaid_http(self) -> httpx.Client:
|
|
230
|
+
"""HTTP client for unpaid calls. A remote policy check uses this and does not create a payment."""
|
|
231
|
+
return self._http
|
|
232
|
+
|
|
229
233
|
def preflight(self, url_or_host: str) -> PreflightResult:
|
|
230
234
|
"""Free. Latest stored probe for a seller; ``found=False`` when the host is not covered.
|
|
231
235
|
|
|
@@ -254,11 +258,11 @@ class BotsRatedClient:
|
|
|
254
258
|
return result
|
|
255
259
|
|
|
256
260
|
def check(self, url_or_host: str) -> dict[str, Any]:
|
|
257
|
-
"""Paid ($0.001; first 25 per UTC day free). Facts, paid test-buys and recent receipts for one host."""
|
|
261
|
+
"""Paid ($0.001; first 25 per client IP per UTC day free). Facts, paid test-buys and recent receipts for one host."""
|
|
258
262
|
return self._paid(f"/v1/check?host={quote(host_of(url_or_host), safe='')}", "check")
|
|
259
263
|
|
|
260
264
|
def report(self, url_or_host: str) -> dict[str, Any]:
|
|
261
|
-
"""Paid ($0.002; first 3 per UTC day free). Full receipt history for one host."""
|
|
265
|
+
"""Paid ($0.002; first 3 per client IP per UTC day free). Full receipt history for one host."""
|
|
262
266
|
return self._paid(f"/v1/report/{quote(host_of(url_or_host), safe='')}", "report")
|
|
263
267
|
|
|
264
268
|
def best(self, task: str, sort: str | None = None, max_price_usd: float | None = None) -> dict[str, Any]:
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
from __future__ import annotations
|
|
4
4
|
|
|
5
|
-
from collections.abc import Awaitable, Callable
|
|
5
|
+
from collections.abc import Awaitable, Callable, Mapping
|
|
6
6
|
from dataclasses import dataclass, field
|
|
7
7
|
from typing import Any, Literal, TypeVar
|
|
8
8
|
from urllib.parse import urlsplit
|
|
@@ -15,6 +15,12 @@ from botsrated.client import (
|
|
|
15
15
|
paying_request,
|
|
16
16
|
usd_to_atomic,
|
|
17
17
|
)
|
|
18
|
+
from botsrated.payment_guard import (
|
|
19
|
+
RemotePolicy,
|
|
20
|
+
fetch_remote_policy,
|
|
21
|
+
interpret_policy_body,
|
|
22
|
+
parse_remote_policy,
|
|
23
|
+
)
|
|
18
24
|
from botsrated.util import (
|
|
19
25
|
DISPUTE_URL,
|
|
20
26
|
clean_text,
|
|
@@ -62,6 +68,11 @@ class Decision:
|
|
|
62
68
|
reasons: list[Reason]
|
|
63
69
|
facts: SellerFacts | None = None
|
|
64
70
|
dispute_url: str = DISPUTE_URL
|
|
71
|
+
# Set when a remote policy check ran. ``remote_decision`` stays None when the server sent none.
|
|
72
|
+
decided_by: str | None = None
|
|
73
|
+
not_a_botsrated_rating: bool | None = None
|
|
74
|
+
policy_version: str | None = None
|
|
75
|
+
remote_decision: Literal["pass", "warn", "block"] | None = None
|
|
65
76
|
|
|
66
77
|
def summary(self) -> str:
|
|
67
78
|
"""Fact-only text with the dispute link. Seller text is never echoed beyond a parsed host name."""
|
|
@@ -223,6 +234,10 @@ class PrePaymentGuard:
|
|
|
223
234
|
paid_check_at_or_above_usd: Run a check for payments at or above this: free within the daily quota
|
|
224
235
|
(25 per UTC day), then a $0.001 paid check with a paid-enabled client (skipped otherwise).
|
|
225
236
|
on_decision: Called with every decision.
|
|
237
|
+
remote_policy: Optional private policy check (``token``, ``fail_mode`` ``open`` or ``closed``, optional
|
|
238
|
+
``base_url``). Before paying, ``POST /v1/policy/check`` with the host and quote. A remote block stops
|
|
239
|
+
the payment. HTTP 503, 404 or ``decision: null`` follows ``fail_mode`` and is never read as a pass.
|
|
240
|
+
The last ``policy_version`` is kept on ``remote_policy_version``. Unset: local rules only.
|
|
226
241
|
"""
|
|
227
242
|
|
|
228
243
|
def __init__(
|
|
@@ -233,12 +248,15 @@ class PrePaymentGuard:
|
|
|
233
248
|
fail_open: bool = True,
|
|
234
249
|
paid_check_at_or_above_usd: float | None = None,
|
|
235
250
|
on_decision: Callable[[Decision], None] | None = None,
|
|
251
|
+
remote_policy: RemotePolicy | Mapping[str, Any] | None = None,
|
|
236
252
|
) -> None:
|
|
237
253
|
self.client = client or BotsRatedClient()
|
|
238
254
|
self.policy = policy or GuardPolicy()
|
|
239
255
|
self.fail_open = fail_open
|
|
240
256
|
self.paid_threshold = paid_check_at_or_above_usd
|
|
241
257
|
self.on_decision = on_decision
|
|
258
|
+
self.remote_policy = parse_remote_policy(remote_policy)
|
|
259
|
+
self.remote_policy_version: str | None = None
|
|
242
260
|
|
|
243
261
|
def _open_or_closed(self, code: str, detail: str, host: str | None = None) -> Decision:
|
|
244
262
|
eff: Effect = "info" if self.fail_open else "block"
|
|
@@ -257,9 +275,33 @@ class PrePaymentGuard:
|
|
|
257
275
|
difference (a redirect between the two) is tolerated. Only host names are sent to BotsRated.
|
|
258
276
|
"""
|
|
259
277
|
try:
|
|
260
|
-
|
|
278
|
+
decision = self._decide(resource_url, requirements, request_url)
|
|
279
|
+
except Exception: # noqa: BLE001
|
|
280
|
+
decision = self._open_or_closed("hook_error", "the pre-payment check could not evaluate this payment.")
|
|
281
|
+
return self._merge_remote(decision, requirements)
|
|
282
|
+
|
|
283
|
+
def _merge_remote(self, decision: Decision, requirements: Any) -> Decision:
|
|
284
|
+
"""POST /v1/policy/check when configured. A remote block wins. A missing decision follows fail_mode."""
|
|
285
|
+
policy = self.remote_policy
|
|
286
|
+
host = decision.host
|
|
287
|
+
if policy is None or not host:
|
|
288
|
+
return decision
|
|
289
|
+
try:
|
|
290
|
+
effect = fetch_remote_policy(self.client.unpaid_http(), policy, host, requirements)
|
|
261
291
|
except Exception: # noqa: BLE001
|
|
262
|
-
|
|
292
|
+
effect = interpret_policy_body(None, {}, policy.fail_mode, host)
|
|
293
|
+
version = effect.policy_version or self.remote_policy_version
|
|
294
|
+
if effect.policy_version:
|
|
295
|
+
self.remote_policy_version = effect.policy_version
|
|
296
|
+
if effect.effect and effect.code and effect.fact:
|
|
297
|
+
decision.reasons.append(Reason(effect.code, effect.fact, effect.effect))
|
|
298
|
+
if effect.effect == "block":
|
|
299
|
+
decision.action = "block"
|
|
300
|
+
decision.decided_by = effect.decided_by
|
|
301
|
+
decision.not_a_botsrated_rating = effect.not_a_botsrated_rating
|
|
302
|
+
decision.policy_version = version
|
|
303
|
+
decision.remote_decision = effect.decision
|
|
304
|
+
return decision
|
|
263
305
|
|
|
264
306
|
def _decide(self, resource_url: str | None, requirements: Any, request_url: str | None) -> Decision:
|
|
265
307
|
req = as_requirements(requirements)
|
|
@@ -6,6 +6,9 @@ What it does, and nothing more:
|
|
|
6
6
|
botsrated.com) and compares them locally with the payment request. Advice-only by default: it reports facts and
|
|
7
7
|
stops a payment only when you choose a blocking policy (e.g. ``POLICIES["carefulBuyer"]``, an alias of
|
|
8
8
|
``POLICIES["strict"]``).
|
|
9
|
+
- When ``remote_policy`` is set: ``POST /v1/policy/check`` with that host and the quote, merged with the local rules
|
|
10
|
+
(a remote block stops the payment). HTTP 503 or ``decision: null`` follows your ``fail_mode``. The policy decision
|
|
11
|
+
is not signed.
|
|
9
12
|
- While the payload is built: adds a random x402 ``payment-identifier`` retry key, only when the seller advertises
|
|
10
13
|
that extension, through x402's extension mechanism.
|
|
11
14
|
- After: records the payment locally (never the signature) and offers a read-only on-chain check of whether it
|
|
@@ -26,12 +29,13 @@ import json
|
|
|
26
29
|
import secrets
|
|
27
30
|
import threading
|
|
28
31
|
import time
|
|
29
|
-
from collections.abc import Awaitable, Callable, Iterator
|
|
32
|
+
from collections.abc import Awaitable, Callable, Iterator, Mapping
|
|
30
33
|
from contextlib import contextmanager
|
|
31
34
|
from contextvars import ContextVar
|
|
32
35
|
from dataclasses import asdict, dataclass, field, replace
|
|
33
36
|
from datetime import datetime, timezone
|
|
34
37
|
from typing import Any, Literal, TypeVar
|
|
38
|
+
from urllib.parse import urlsplit
|
|
35
39
|
|
|
36
40
|
import httpx
|
|
37
41
|
|
|
@@ -149,6 +153,11 @@ class GuardDecision:
|
|
|
149
153
|
policy_rule: str | None = None
|
|
150
154
|
facts: GuardFacts | None = None
|
|
151
155
|
dispute_url: str = DISPUTE_URL
|
|
156
|
+
# Present only after a remote policy check. ``remote_decision`` stays None when the server sent none.
|
|
157
|
+
decided_by: str | None = None
|
|
158
|
+
not_a_botsrated_rating: bool | None = None
|
|
159
|
+
policy_version: str | None = None
|
|
160
|
+
remote_decision: Literal["pass", "warn", "block"] | None = None
|
|
152
161
|
|
|
153
162
|
|
|
154
163
|
def _effect(e: RuleEffect, fallback: Effect) -> Effect:
|
|
@@ -193,6 +202,204 @@ def _get(obj: Any, *names: str) -> Any:
|
|
|
193
202
|
return None
|
|
194
203
|
|
|
195
204
|
|
|
205
|
+
# ----------------------------------------------------------------------------------------------------------------
|
|
206
|
+
# Remote policy. The client enforces. A missing decision is never turned into a pass.
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
FailMode = Literal["open", "closed"]
|
|
210
|
+
RemoteDecision = Literal["pass", "warn", "block"]
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
def _ascii_label(text: str, extra: str) -> bool:
|
|
214
|
+
return all(c.isascii() and (c.isalnum() or c in extra) for c in text)
|
|
215
|
+
|
|
216
|
+
|
|
217
|
+
def _policy_origin(base: str) -> str:
|
|
218
|
+
"""Origin only. A path on ``base_url`` is not a prefix (the check path is always ``/v1/policy/check``)."""
|
|
219
|
+
if not isinstance(base, str) or any(c.isspace() for c in base):
|
|
220
|
+
raise ValueError("remote_policy.base_url must be an http(s) URL.")
|
|
221
|
+
parts = urlsplit(base.strip())
|
|
222
|
+
if parts.scheme not in ("http", "https") or not parts.hostname or parts.username or parts.password:
|
|
223
|
+
raise ValueError("remote_policy.base_url must be an http(s) URL.")
|
|
224
|
+
host = f"[{parts.hostname}]" if ":" in parts.hostname else parts.hostname
|
|
225
|
+
netloc = host if parts.port is None else f"{host}:{parts.port}"
|
|
226
|
+
return f"{parts.scheme}://{netloc}"
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
def _token_ok(token: str) -> bool:
|
|
230
|
+
if not isinstance(token, str) or not token or len(token) > 4096:
|
|
231
|
+
return False
|
|
232
|
+
return all(c.isascii() and not c.isspace() and ord(c) >= 33 for c in token)
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
def _version_of(value: Any) -> str | None:
|
|
236
|
+
if isinstance(value, bool) or value is None:
|
|
237
|
+
return None
|
|
238
|
+
text = str(value) if isinstance(value, int) else value.strip() if isinstance(value, str) else None
|
|
239
|
+
if not text or len(text) > 80 or not _ascii_label(text, "._:-"):
|
|
240
|
+
return None
|
|
241
|
+
return text
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
@dataclass(frozen=True)
|
|
245
|
+
class RemotePolicy:
|
|
246
|
+
"""Your private policy check. ``fail_mode`` is required: ``open`` or ``closed``.
|
|
247
|
+
|
|
248
|
+
``base_url`` defaults to https://botsrated.com when omitted. A mapping may use ``fail_mode`` or
|
|
249
|
+
``failMode``, and ``base_url`` or ``baseUrl``.
|
|
250
|
+
"""
|
|
251
|
+
|
|
252
|
+
token: str
|
|
253
|
+
fail_mode: FailMode
|
|
254
|
+
base_url: str | None = None
|
|
255
|
+
|
|
256
|
+
def __post_init__(self) -> None:
|
|
257
|
+
token = self.token[7:].strip() if isinstance(self.token, str) and self.token.lower().startswith("bearer ") else self.token
|
|
258
|
+
if token is not self.token:
|
|
259
|
+
object.__setattr__(self, "token", token)
|
|
260
|
+
if not _token_ok(token if isinstance(token, str) else ""):
|
|
261
|
+
raise ValueError("remote_policy.token must be a non-empty bearer token without whitespace.")
|
|
262
|
+
if self.fail_mode not in ("open", "closed"):
|
|
263
|
+
raise ValueError('remote_policy.fail_mode must be "open" or "closed".')
|
|
264
|
+
if self.base_url is None:
|
|
265
|
+
return
|
|
266
|
+
object.__setattr__(self, "base_url", _policy_origin(self.base_url))
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
def parse_remote_policy(value: RemotePolicy | Mapping[str, Any] | None) -> RemotePolicy | None:
|
|
270
|
+
"""Accept a :class:`RemotePolicy` or a mapping. ``None`` leaves the guard on local rules only."""
|
|
271
|
+
if value is None:
|
|
272
|
+
return None
|
|
273
|
+
if isinstance(value, RemotePolicy):
|
|
274
|
+
return value
|
|
275
|
+
if not isinstance(value, Mapping):
|
|
276
|
+
raise TypeError("remote_policy must be a RemotePolicy or a mapping.")
|
|
277
|
+
if "fail_mode" in value and "failMode" in value and value.get("fail_mode") != value.get("failMode"):
|
|
278
|
+
raise ValueError("remote_policy.fail_mode and failMode disagree.")
|
|
279
|
+
if "base_url" in value and "baseUrl" in value and value.get("base_url") != value.get("baseUrl"):
|
|
280
|
+
raise ValueError("remote_policy.base_url and baseUrl disagree.")
|
|
281
|
+
fail_mode = value.get("fail_mode", value.get("failMode"))
|
|
282
|
+
base_url = value.get("base_url", value.get("baseUrl"))
|
|
283
|
+
return RemotePolicy(str(value.get("token") or ""), fail_mode, base_url) # type: ignore[arg-type]
|
|
284
|
+
|
|
285
|
+
|
|
286
|
+
@dataclass(frozen=True)
|
|
287
|
+
class RemotePolicyEffect:
|
|
288
|
+
"""One policy-check outcome. ``decision`` is set only when the server named pass, warn or block."""
|
|
289
|
+
|
|
290
|
+
decision: RemoteDecision | None
|
|
291
|
+
effect: Effect | None
|
|
292
|
+
code: str | None
|
|
293
|
+
fact: str | None
|
|
294
|
+
decided_by: str | None = None
|
|
295
|
+
not_a_botsrated_rating: bool | None = None
|
|
296
|
+
policy_version: str | None = None
|
|
297
|
+
|
|
298
|
+
|
|
299
|
+
def policy_quote(req: Any) -> dict[str, str]:
|
|
300
|
+
"""Quote fields sent to ``/v1/policy/check``: payTo, amount, asset, network. Nothing else."""
|
|
301
|
+
quote: dict[str, str] = {}
|
|
302
|
+
pay_to = _get(req, "payTo", "pay_to")
|
|
303
|
+
if is_address(pay_to):
|
|
304
|
+
quote["payTo"] = pay_to
|
|
305
|
+
amount = _get(req, "amount")
|
|
306
|
+
if isinstance(amount, bool):
|
|
307
|
+
amount_s = None
|
|
308
|
+
elif isinstance(amount, int):
|
|
309
|
+
amount_s = str(amount)
|
|
310
|
+
elif isinstance(amount, str):
|
|
311
|
+
amount_s = amount
|
|
312
|
+
else:
|
|
313
|
+
amount_s = None
|
|
314
|
+
if is_atomic_amount(amount_s):
|
|
315
|
+
quote["amount"] = amount_s
|
|
316
|
+
asset = _get(req, "asset")
|
|
317
|
+
if is_address(asset):
|
|
318
|
+
quote["asset"] = asset
|
|
319
|
+
network = _get(req, "network")
|
|
320
|
+
if isinstance(network, str) and network.strip():
|
|
321
|
+
quote["network"] = clean_text(network, 40)
|
|
322
|
+
return quote
|
|
323
|
+
|
|
324
|
+
|
|
325
|
+
def _framing(body: Any) -> tuple[str | None, bool | None, str | None]:
|
|
326
|
+
if not isinstance(body, dict):
|
|
327
|
+
return None, None, None
|
|
328
|
+
decided = body.get("decided_by")
|
|
329
|
+
decided_by = decided.strip() if isinstance(decided, str) else None
|
|
330
|
+
if decided_by is not None and (not decided_by or len(decided_by) > 80 or not _ascii_label(decided_by, "_.:-")):
|
|
331
|
+
decided_by = None
|
|
332
|
+
rating = body.get("not_a_botsrated_rating")
|
|
333
|
+
return decided_by, rating if isinstance(rating, bool) else None, _version_of(body.get("policy_version"))
|
|
334
|
+
|
|
335
|
+
|
|
336
|
+
def _named_decision(body: Any) -> RemoteDecision | None:
|
|
337
|
+
"""pass, warn or block. ``allow`` is read as pass. Any other label, including null, is no decision."""
|
|
338
|
+
if not isinstance(body, dict) or "decision" not in body:
|
|
339
|
+
return None
|
|
340
|
+
raw = body.get("decision")
|
|
341
|
+
if not isinstance(raw, str):
|
|
342
|
+
return None
|
|
343
|
+
key = raw.strip().lower()
|
|
344
|
+
if key == "block":
|
|
345
|
+
return "block"
|
|
346
|
+
if key == "warn":
|
|
347
|
+
return "warn"
|
|
348
|
+
if key in ("pass", "allow"):
|
|
349
|
+
return "pass"
|
|
350
|
+
return None
|
|
351
|
+
|
|
352
|
+
|
|
353
|
+
def interpret_policy_body(status: int | None, body: Any, fail_mode: FailMode, host: str) -> RemotePolicyEffect:
|
|
354
|
+
"""Map a policy-check response. 503, 404, transport failure and ``decision: null`` use ``fail_mode``."""
|
|
355
|
+
decided_by, rating, version = _framing(body)
|
|
356
|
+
if status is not None and 200 <= status < 300:
|
|
357
|
+
decision = _named_decision(body)
|
|
358
|
+
if decision == "block":
|
|
359
|
+
return RemotePolicyEffect("block", "block", "remote_policy", f"your policy returned block for {host}.", decided_by, rating, version)
|
|
360
|
+
if decision == "warn":
|
|
361
|
+
return RemotePolicyEffect("warn", "warn", "remote_policy", f"your policy returned warn for {host}.", decided_by, rating, version)
|
|
362
|
+
if decision == "pass":
|
|
363
|
+
return RemotePolicyEffect("pass", None, None, None, decided_by, rating, version)
|
|
364
|
+
effect: Effect = "block" if fail_mode == "closed" else "info"
|
|
365
|
+
fact = f"your policy check returned no decision; fail_mode is {fail_mode}."
|
|
366
|
+
return RemotePolicyEffect(None, effect, "remote_policy_unavailable", fact, decided_by, rating, version)
|
|
367
|
+
|
|
368
|
+
|
|
369
|
+
def _policy_headers(token: str) -> dict[str, str]:
|
|
370
|
+
return {
|
|
371
|
+
"accept": "application/json",
|
|
372
|
+
"content-type": "application/json",
|
|
373
|
+
"user-agent": USER_AGENT,
|
|
374
|
+
"authorization": f"Bearer {token}",
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
|
|
378
|
+
def _read_policy_response(resp: httpx.Response) -> tuple[int, Any]:
|
|
379
|
+
if len(resp.content) > 1_000_000:
|
|
380
|
+
return resp.status_code, {}
|
|
381
|
+
try:
|
|
382
|
+
body = resp.json()
|
|
383
|
+
except ValueError:
|
|
384
|
+
body = {}
|
|
385
|
+
return resp.status_code, body if isinstance(body, dict) else {}
|
|
386
|
+
|
|
387
|
+
|
|
388
|
+
def fetch_remote_policy(http: httpx.Client, policy: RemotePolicy, host: str, req: Any, timeout: float | None = None) -> RemotePolicyEffect:
|
|
389
|
+
"""POST /v1/policy/check. Transport errors and non-decisions follow ``policy.fail_mode``."""
|
|
390
|
+
url = f"{(policy.base_url or BOTSRATED_BASE_URL)}/v1/policy/check"
|
|
391
|
+
payload = {"host": host, "quote": policy_quote(req)}
|
|
392
|
+
try:
|
|
393
|
+
kwargs: dict[str, Any] = {"json": payload, "headers": _policy_headers(policy.token), "follow_redirects": False}
|
|
394
|
+
if timeout is not None:
|
|
395
|
+
kwargs["timeout"] = timeout
|
|
396
|
+
resp = http.post(url, **kwargs)
|
|
397
|
+
status, body = _read_policy_response(resp)
|
|
398
|
+
except Exception: # noqa: BLE001 - a failed check is fail_mode, not a pass
|
|
399
|
+
status, body = None, {}
|
|
400
|
+
return interpret_policy_body(status, body, policy.fail_mode, host)
|
|
401
|
+
|
|
402
|
+
|
|
196
403
|
def evaluate_facts(facts: GuardFacts, req: Any, paid_url: str | None, policy: PaymentGuardPolicy) -> list[GuardReason]:
|
|
197
404
|
"""Pure, local comparison of one payment option with BotsRated facts."""
|
|
198
405
|
out: list[GuardReason] = []
|
|
@@ -376,6 +583,10 @@ class PaymentGuard:
|
|
|
376
583
|
http / async_http: Optional ``httpx.Client`` / ``httpx.AsyncClient`` for the hosted lookup.
|
|
377
584
|
preflight: Replace the hosted lookup: ``(host) -> (found, body)``. Receives a host name only.
|
|
378
585
|
on_decision: Receives every decision. Errors raised in it are ignored.
|
|
586
|
+
remote_policy: Optional private policy check (``token``, ``fail_mode`` ``open`` or ``closed``, optional
|
|
587
|
+
``base_url``). Before paying, ``POST /v1/policy/check`` with the host and quote. A remote block stops
|
|
588
|
+
the payment. HTTP 503, 404 or ``decision: null`` follows ``fail_mode`` and is never read as a pass.
|
|
589
|
+
The last ``policy_version`` is kept on ``remote_policy_version``. Unset: local rules only.
|
|
379
590
|
"""
|
|
380
591
|
|
|
381
592
|
def __init__(
|
|
@@ -395,6 +606,7 @@ class PaymentGuard:
|
|
|
395
606
|
async_http: httpx.AsyncClient | None = None,
|
|
396
607
|
preflight: Callable[[str], tuple[bool, dict[str, Any]]] | None = None,
|
|
397
608
|
on_decision: Callable[[GuardDecision], None] | None = None,
|
|
609
|
+
remote_policy: RemotePolicy | Mapping[str, Any] | None = None,
|
|
398
610
|
) -> None:
|
|
399
611
|
if preset is not None and preset not in PRESETS:
|
|
400
612
|
raise ValueError(f'Unknown payment guard preset "{preset}". Expected warn, carefulBuyer, or dry-run-only.')
|
|
@@ -418,6 +630,8 @@ class PaymentGuard:
|
|
|
418
630
|
self._async_http = async_http
|
|
419
631
|
self._preflight = preflight
|
|
420
632
|
self.on_decision = on_decision
|
|
633
|
+
self.remote_policy = parse_remote_policy(remote_policy)
|
|
634
|
+
self.remote_policy_version: str | None = None
|
|
421
635
|
self._records: dict[str, PaymentRecord] = {}
|
|
422
636
|
self._retry_keys: dict[str, tuple[str, int]] = {}
|
|
423
637
|
self._lock = threading.Lock()
|
|
@@ -495,7 +709,14 @@ class PaymentGuard:
|
|
|
495
709
|
except Exception: # noqa: BLE001, S110 - caller callback errors are ignored
|
|
496
710
|
pass
|
|
497
711
|
|
|
498
|
-
def _finish(
|
|
712
|
+
def _finish(
|
|
713
|
+
self,
|
|
714
|
+
phase: Literal["before_payment", "payment_response"],
|
|
715
|
+
reasons: list[GuardReason],
|
|
716
|
+
host: str | None,
|
|
717
|
+
facts: GuardFacts | None = None,
|
|
718
|
+
remote: RemotePolicyEffect | None = None,
|
|
719
|
+
) -> GuardDecision:
|
|
499
720
|
stopping = next((r for r in reasons if r.effect == "block"), None)
|
|
500
721
|
d = GuardDecision(
|
|
501
722
|
phase=phase,
|
|
@@ -507,10 +728,50 @@ class PaymentGuard:
|
|
|
507
728
|
host=host,
|
|
508
729
|
policy_rule=(stopping.rule or stopping.code) if stopping else None,
|
|
509
730
|
facts=facts,
|
|
731
|
+
decided_by=remote.decided_by if remote else None,
|
|
732
|
+
not_a_botsrated_rating=remote.not_a_botsrated_rating if remote else None,
|
|
733
|
+
policy_version=remote.policy_version if remote else None,
|
|
734
|
+
remote_decision=remote.decision if remote else None,
|
|
510
735
|
)
|
|
511
736
|
d.message = _summarize(d)
|
|
512
737
|
return d
|
|
513
738
|
|
|
739
|
+
def _remember_remote(self, reasons: list[GuardReason], effect: RemotePolicyEffect | None) -> RemotePolicyEffect | None:
|
|
740
|
+
if effect is None:
|
|
741
|
+
return None
|
|
742
|
+
version = effect.policy_version or self.remote_policy_version
|
|
743
|
+
if effect.policy_version:
|
|
744
|
+
self.remote_policy_version = effect.policy_version
|
|
745
|
+
if version != effect.policy_version:
|
|
746
|
+
effect = replace(effect, policy_version=version)
|
|
747
|
+
if effect.effect and effect.code and effect.fact:
|
|
748
|
+
rule = "remotePolicy" if effect.decision else "failMode"
|
|
749
|
+
reasons.append(GuardReason(effect.code, effect.effect, effect.fact, rule))
|
|
750
|
+
return effect
|
|
751
|
+
|
|
752
|
+
def _remote_sync(self, host: str, req: Any) -> RemotePolicyEffect:
|
|
753
|
+
assert self.remote_policy is not None
|
|
754
|
+
if self._http is not None:
|
|
755
|
+
return fetch_remote_policy(self._http, self.remote_policy, host, req, self._timeout)
|
|
756
|
+
with httpx.Client(timeout=self._timeout, follow_redirects=False) as client:
|
|
757
|
+
return fetch_remote_policy(client, self.remote_policy, host, req, self._timeout)
|
|
758
|
+
|
|
759
|
+
async def _remote_async(self, host: str, req: Any) -> RemotePolicyEffect:
|
|
760
|
+
assert self.remote_policy is not None
|
|
761
|
+
url = f"{(self.remote_policy.base_url or BOTSRATED_BASE_URL)}/v1/policy/check"
|
|
762
|
+
headers = _policy_headers(self.remote_policy.token)
|
|
763
|
+
payload = {"host": host, "quote": policy_quote(req)}
|
|
764
|
+
try:
|
|
765
|
+
if self._async_http is not None:
|
|
766
|
+
resp = await self._async_http.post(url, json=payload, headers=headers, timeout=self._timeout, follow_redirects=False)
|
|
767
|
+
else:
|
|
768
|
+
async with httpx.AsyncClient(timeout=self._timeout, follow_redirects=False) as c:
|
|
769
|
+
resp = await c.post(url, json=payload, headers=headers)
|
|
770
|
+
status, body = _read_policy_response(resp)
|
|
771
|
+
except Exception: # noqa: BLE001 - a failed check is fail_mode, not a pass
|
|
772
|
+
status, body = None, {}
|
|
773
|
+
return interpret_policy_body(status, body, self.remote_policy.fail_mode, host)
|
|
774
|
+
|
|
514
775
|
def _local(self, ctx: Any) -> tuple[list[GuardReason], str | None, str | None, Any, str | None]:
|
|
515
776
|
pr = _get(ctx, "payment_required", "paymentRequired")
|
|
516
777
|
req = _get(ctx, "selected_requirements", "selectedRequirements")
|
|
@@ -644,7 +905,8 @@ class PaymentGuard:
|
|
|
644
905
|
try:
|
|
645
906
|
reasons, host, lookup, req, paid_url = self._local(ctx)
|
|
646
907
|
facts = self._with_facts(reasons, lookup, self._lookup_sync(lookup), req, paid_url) if lookup else None
|
|
647
|
-
|
|
908
|
+
remote = self._remember_remote(reasons, self._remote_sync(host, req) if self.remote_policy and host else None)
|
|
909
|
+
return self._finish("before_payment", reasons, host, facts, remote)
|
|
648
910
|
except Exception: # noqa: BLE001
|
|
649
911
|
return self._hook_error()
|
|
650
912
|
|
|
@@ -653,7 +915,8 @@ class PaymentGuard:
|
|
|
653
915
|
try:
|
|
654
916
|
reasons, host, lookup, req, paid_url = self._local(ctx)
|
|
655
917
|
facts = self._with_facts(reasons, lookup, await self._lookup_async(lookup), req, paid_url) if lookup else None
|
|
656
|
-
|
|
918
|
+
remote = self._remember_remote(reasons, await self._remote_async(host, req) if self.remote_policy and host else None)
|
|
919
|
+
return self._finish("before_payment", reasons, host, facts, remote)
|
|
657
920
|
except Exception: # noqa: BLE001
|
|
658
921
|
return self._hook_error()
|
|
659
922
|
|
|
@@ -868,4 +1131,7 @@ def decision_as_dict(d: GuardDecision) -> dict[str, Any]:
|
|
|
868
1131
|
out = asdict(d)
|
|
869
1132
|
if out.get("facts"):
|
|
870
1133
|
out["facts"].pop("probed", None)
|
|
1134
|
+
for key in ("decided_by", "not_a_botsrated_rating", "policy_version", "remote_decision"):
|
|
1135
|
+
if out.get(key) is None:
|
|
1136
|
+
out.pop(key, None)
|
|
871
1137
|
return out
|
|
@@ -6,7 +6,7 @@ import re
|
|
|
6
6
|
from typing import Any
|
|
7
7
|
from urllib.parse import urlsplit
|
|
8
8
|
|
|
9
|
-
VERSION = "0.
|
|
9
|
+
VERSION = "0.3.1"
|
|
10
10
|
# Sent on hosted BotsRated calls. No install id, wallet or other user identifier.
|
|
11
11
|
USER_AGENT = f"botsrated-python/{VERSION}"
|
|
12
12
|
BOTSRATED_BASE_URL = "https://botsrated.com"
|
|
@@ -0,0 +1,301 @@
|
|
|
1
|
+
"""Remote policy on PaymentGuard and PrePaymentGuard.
|
|
2
|
+
|
|
3
|
+
A remote block stops the payment. HTTP 503, 404 and decision null follow fail_mode.
|
|
4
|
+
A missing decision is never stored as a pass, and the check is not signed.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import json
|
|
10
|
+
|
|
11
|
+
import httpx
|
|
12
|
+
import pytest
|
|
13
|
+
|
|
14
|
+
from botsrated import (
|
|
15
|
+
POLICIES,
|
|
16
|
+
STRICT_GUARD_POLICY,
|
|
17
|
+
PaymentGuard,
|
|
18
|
+
PrePaymentGuard,
|
|
19
|
+
RemotePolicy,
|
|
20
|
+
)
|
|
21
|
+
from botsrated.client import BotsRatedClient
|
|
22
|
+
from botsrated.payment_guard import interpret_policy_body
|
|
23
|
+
|
|
24
|
+
DEAD = "0x000000000000000000000000000000000000dEaD"
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def req(found, **over):
|
|
28
|
+
row = {
|
|
29
|
+
"scheme": "exact",
|
|
30
|
+
"network": "eip155:8453",
|
|
31
|
+
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
|
|
32
|
+
"payTo": found["latest_probe"]["live_payTo"],
|
|
33
|
+
"amount": found["latest_probe"]["live_amount"],
|
|
34
|
+
"maxTimeoutSeconds": 60,
|
|
35
|
+
"extra": {"name": "USD Coin", "version": "2"},
|
|
36
|
+
}
|
|
37
|
+
row.update(over)
|
|
38
|
+
return row
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def ctx(resource_url, row):
|
|
42
|
+
return {"payment_required": {"x402Version": 2, "resource": {"url": resource_url}, "accepts": [row]}, "selected_requirements": row}
|
|
43
|
+
|
|
44
|
+
TOKEN = "policy-token-1"
|
|
45
|
+
FRAMING = {"decided_by": "your_policy", "not_a_botsrated_rating": True, "policy_version": "7"}
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def _answer(found, policy):
|
|
49
|
+
seen: list[httpx.Request] = []
|
|
50
|
+
|
|
51
|
+
def respond(request: httpx.Request) -> httpx.Response:
|
|
52
|
+
seen.append(request)
|
|
53
|
+
path = request.url.path
|
|
54
|
+
if path.endswith("/policy/check"):
|
|
55
|
+
status, body = policy(request)
|
|
56
|
+
return httpx.Response(status, json=body)
|
|
57
|
+
return httpx.Response(200, json=found)
|
|
58
|
+
|
|
59
|
+
return seen, respond
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def _payment_guard(found, handler, **kw):
|
|
63
|
+
seen, respond = _answer(found, handler)
|
|
64
|
+
guard = PaymentGuard(http=httpx.Client(transport=httpx.MockTransport(respond)), **kw)
|
|
65
|
+
return guard, seen
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def _pre(found, handler, **kw):
|
|
69
|
+
seen, respond = _answer(found, handler)
|
|
70
|
+
client = BotsRatedClient(http=httpx.Client(transport=httpx.MockTransport(respond)))
|
|
71
|
+
return PrePaymentGuard(client, **kw), seen
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def _policy_bodies(seen: list[httpx.Request]) -> list[dict]:
|
|
75
|
+
out = []
|
|
76
|
+
for request in seen:
|
|
77
|
+
if request.url.path.endswith("/policy/check"):
|
|
78
|
+
out.append(json.loads(request.content))
|
|
79
|
+
return out
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def test_unset_remote_policy_keeps_local_presets_and_does_not_post(found):
|
|
83
|
+
guard, seen = _payment_guard(found, lambda r: (200, {}), policy=POLICIES["carefulBuyer"])
|
|
84
|
+
url = found["latest_probe"]["url"]
|
|
85
|
+
with guard.request(url):
|
|
86
|
+
decision = guard.decide(ctx(url, req(found, payTo=DEAD)))
|
|
87
|
+
assert decision.action == "block" and decision.policy_rule == "payToMismatch"
|
|
88
|
+
assert decision.remote_decision is None
|
|
89
|
+
assert _policy_bodies(seen) == []
|
|
90
|
+
assert all("/v1/preflight" in str(r.url) for r in seen)
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def test_remote_block_wins_over_a_local_allow(found):
|
|
94
|
+
def policy(_request):
|
|
95
|
+
return 200, {"decision": "block", **FRAMING}
|
|
96
|
+
|
|
97
|
+
guard, seen = _payment_guard(found, policy, remote_policy={"token": TOKEN, "fail_mode": "open"})
|
|
98
|
+
url = found["latest_probe"]["url"]
|
|
99
|
+
with guard.request(url):
|
|
100
|
+
decision = guard.decide(ctx(url, req(found)))
|
|
101
|
+
assert decision.action == "block"
|
|
102
|
+
assert decision.policy_rule == "remotePolicy"
|
|
103
|
+
assert decision.remote_decision == "block"
|
|
104
|
+
assert decision.decided_by == "your_policy"
|
|
105
|
+
assert decision.not_a_botsrated_rating is True
|
|
106
|
+
assert decision.policy_version == "7"
|
|
107
|
+
assert guard.remote_policy_version == "7"
|
|
108
|
+
body = _policy_bodies(seen)[0]
|
|
109
|
+
assert body["host"] == "blockrun.ai"
|
|
110
|
+
assert set(body) == {"host", "quote"}
|
|
111
|
+
assert set(body["quote"]) <= {"payTo", "amount", "asset", "network"}
|
|
112
|
+
assert body["quote"]["payTo"] == found["latest_probe"]["live_payTo"]
|
|
113
|
+
assert body["quote"]["amount"] == found["latest_probe"]["live_amount"]
|
|
114
|
+
posted = next(r for r in seen if r.url.path.endswith("/policy/check"))
|
|
115
|
+
assert posted.headers["authorization"] == f"Bearer {TOKEN}"
|
|
116
|
+
assert str(posted.url) == "https://botsrated.com/v1/policy/check"
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def test_remote_pass_does_not_clear_a_local_block(found):
|
|
120
|
+
def policy(_request):
|
|
121
|
+
return 200, {"decision": "pass", **FRAMING}
|
|
122
|
+
|
|
123
|
+
guard, _seen = _payment_guard(found, policy, policy=POLICIES["strict"], remote_policy=RemotePolicy(TOKEN, "open"))
|
|
124
|
+
url = found["latest_probe"]["url"]
|
|
125
|
+
with guard.request(url):
|
|
126
|
+
decision = guard.decide(ctx(url, req(found, payTo=DEAD)))
|
|
127
|
+
assert decision.action == "block" and decision.policy_rule == "payToMismatch"
|
|
128
|
+
assert decision.remote_decision == "pass"
|
|
129
|
+
assert decision.decided_by == "your_policy"
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
def test_503_and_null_decision_follow_fail_mode_and_do_not_invent_a_pass(found):
|
|
133
|
+
url = found["latest_probe"]["url"]
|
|
134
|
+
cases = [
|
|
135
|
+
(503, {"decision": None, **FRAMING}),
|
|
136
|
+
(200, {"decision": None, "decided_by": "your_policy", "not_a_botsrated_rating": True}),
|
|
137
|
+
(404, {}),
|
|
138
|
+
(200, {"decision": "safe"}),
|
|
139
|
+
]
|
|
140
|
+
for status, body in cases:
|
|
141
|
+
closed, _ = _payment_guard(found, lambda r, s=status, b=body: (s, b), remote_policy={"token": TOKEN, "fail_mode": "closed"})
|
|
142
|
+
with closed.request(url):
|
|
143
|
+
blocked = closed.decide(ctx(url, req(found)))
|
|
144
|
+
assert blocked.action == "block", (status, body)
|
|
145
|
+
assert blocked.remote_decision is None
|
|
146
|
+
assert any(r.code == "remote_policy_unavailable" and r.effect == "block" and "fail_mode is closed" in r.fact for r in blocked.reasons)
|
|
147
|
+
assert blocked.remote_decision != "pass"
|
|
148
|
+
|
|
149
|
+
opened, _ = _payment_guard(found, lambda r, s=status, b=body: (s, b), remote_policy={"token": TOKEN, "failMode": "open"})
|
|
150
|
+
with opened.request(url):
|
|
151
|
+
allowed = opened.decide(ctx(url, req(found)))
|
|
152
|
+
assert allowed.action == "allow", (status, body)
|
|
153
|
+
assert allowed.remote_decision is None
|
|
154
|
+
assert any(r.code == "remote_policy_unavailable" and r.effect == "info" and "fail_mode is open" in r.fact for r in allowed.reasons)
|
|
155
|
+
|
|
156
|
+
# A local block still stops the payment when fail_mode is open and the check returns nothing.
|
|
157
|
+
strict, _ = _payment_guard(
|
|
158
|
+
found,
|
|
159
|
+
lambda r: (503, {"decision": None}),
|
|
160
|
+
policy=POLICIES["strict"],
|
|
161
|
+
remote_policy={"token": TOKEN, "fail_mode": "open"},
|
|
162
|
+
)
|
|
163
|
+
with strict.request(url):
|
|
164
|
+
decision = strict.decide(ctx(url, req(found, payTo=DEAD)))
|
|
165
|
+
assert decision.action == "block" and decision.policy_rule == "payToMismatch"
|
|
166
|
+
assert decision.remote_decision is None
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
def test_null_decision_keeps_server_framing(found):
|
|
170
|
+
def policy(_request):
|
|
171
|
+
return 200, {"decision": None, "decided_by": "your_policy", "not_a_botsrated_rating": True, "policy_version": "4"}
|
|
172
|
+
|
|
173
|
+
guard, _seen = _payment_guard(found, policy, remote_policy={"token": TOKEN, "fail_mode": "open"})
|
|
174
|
+
url = found["latest_probe"]["url"]
|
|
175
|
+
with guard.request(url):
|
|
176
|
+
decision = guard.decide(ctx(url, req(found)))
|
|
177
|
+
assert decision.decided_by == "your_policy"
|
|
178
|
+
assert decision.not_a_botsrated_rating is True
|
|
179
|
+
assert decision.policy_version == "4"
|
|
180
|
+
assert decision.remote_decision is None
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def test_policy_check_is_not_signed_and_ignores_a_returned_signature(found):
|
|
184
|
+
def policy(_request):
|
|
185
|
+
return 200, {"decision": "block", "signature": "PRODKEYSIG", **FRAMING}
|
|
186
|
+
|
|
187
|
+
guard, seen = _payment_guard(found, policy, remote_policy={"token": TOKEN, "fail_mode": "closed"})
|
|
188
|
+
url = found["latest_probe"]["url"] + "?api_key=SECRET123"
|
|
189
|
+
with guard.request(url):
|
|
190
|
+
decision = guard.decide(ctx(url, req(found)))
|
|
191
|
+
posted = [r for r in seen if r.url.path.endswith("/policy/check")]
|
|
192
|
+
assert len(posted) == 1
|
|
193
|
+
headers = {k.lower(): v for k, v in posted[0].headers.items()}
|
|
194
|
+
assert "payment-signature" not in headers
|
|
195
|
+
assert "x-payment" not in headers
|
|
196
|
+
raw = posted[0].content.decode()
|
|
197
|
+
assert "PRODKEYSIG" not in raw and "SECRET123" not in raw and "signature" not in raw
|
|
198
|
+
assert "PRODKEYSIG" not in decision.message
|
|
199
|
+
assert not hasattr(decision, "signature")
|
|
200
|
+
blob = json.dumps({"message": decision.message, "reasons": [r.fact for r in decision.reasons]})
|
|
201
|
+
assert TOKEN not in blob
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
def test_last_policy_version_is_remembered_when_the_next_check_fails(found):
|
|
205
|
+
calls = {"n": 0}
|
|
206
|
+
|
|
207
|
+
def policy(_request):
|
|
208
|
+
calls["n"] += 1
|
|
209
|
+
if calls["n"] == 1:
|
|
210
|
+
return 200, {"decision": "pass", "policy_version": "9", "decided_by": "your_policy", "not_a_botsrated_rating": True}
|
|
211
|
+
return 503, {"decision": None}
|
|
212
|
+
|
|
213
|
+
guard, _seen = _payment_guard(found, policy, remote_policy={"token": TOKEN, "fail_mode": "closed"})
|
|
214
|
+
url = found["latest_probe"]["url"]
|
|
215
|
+
with guard.request(url):
|
|
216
|
+
first = guard.decide(ctx(url, req(found)))
|
|
217
|
+
second = guard.decide(ctx(url, req(found)))
|
|
218
|
+
assert first.remote_decision == "pass" and first.policy_version == "9"
|
|
219
|
+
assert second.remote_decision is None and second.action == "block"
|
|
220
|
+
assert second.policy_version == "9"
|
|
221
|
+
assert guard.remote_policy_version == "9"
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
def test_custom_base_url_and_bad_config(found):
|
|
225
|
+
def policy(_request):
|
|
226
|
+
return 200, {"decision": "warn"}
|
|
227
|
+
|
|
228
|
+
guard, seen = _payment_guard(found, policy, remote_policy={"token": TOKEN, "fail_mode": "open", "baseUrl": "https://policy.example/v1/"})
|
|
229
|
+
url = found["latest_probe"]["url"]
|
|
230
|
+
with guard.request(url):
|
|
231
|
+
decision = guard.decide(ctx(url, req(found)))
|
|
232
|
+
assert decision.action == "allow"
|
|
233
|
+
assert any(r.code == "remote_policy" and r.effect == "warn" for r in decision.reasons)
|
|
234
|
+
posted = next(r for r in seen if r.url.path.endswith("/policy/check"))
|
|
235
|
+
assert str(posted.url) == "https://policy.example/v1/policy/check"
|
|
236
|
+
|
|
237
|
+
with pytest.raises(ValueError, match="fail_mode"):
|
|
238
|
+
PaymentGuard(hosted=False, remote_policy={"token": TOKEN})
|
|
239
|
+
with pytest.raises(ValueError, match="token"):
|
|
240
|
+
RemotePolicy("has space", "open")
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
def test_pre_payment_guard_block_wins_503_and_does_not_sign(found):
|
|
244
|
+
url = found["latest_probe"]["url"]
|
|
245
|
+
|
|
246
|
+
def block(_request):
|
|
247
|
+
return 200, {"decision": "block", **FRAMING, "signature": "PRODKEYSIG"}
|
|
248
|
+
|
|
249
|
+
guard, seen = _pre(found, block, remote_policy={"token": TOKEN, "fail_mode": "open"})
|
|
250
|
+
decision = guard.decide(url, req(found), request_url=url)
|
|
251
|
+
assert decision.action == "block"
|
|
252
|
+
assert decision.remote_decision == "block"
|
|
253
|
+
assert decision.decided_by == "your_policy" and decision.not_a_botsrated_rating is True
|
|
254
|
+
posted = next(r for r in seen if r.url.path.endswith("/policy/check"))
|
|
255
|
+
assert "payment-signature" not in {k.lower() for k in posted.headers}
|
|
256
|
+
assert "PRODKEYSIG" not in posted.content.decode()
|
|
257
|
+
|
|
258
|
+
def down(_request):
|
|
259
|
+
return 503, {"decision": None, "decided_by": "your_policy", "not_a_botsrated_rating": True}
|
|
260
|
+
|
|
261
|
+
closed, _ = _pre(found, down, remote_policy={"token": TOKEN, "fail_mode": "closed"})
|
|
262
|
+
blocked = closed.decide(url, req(found), request_url=url)
|
|
263
|
+
assert blocked.action == "block" and blocked.remote_decision is None
|
|
264
|
+
assert any("fail_mode is closed" in r.detail for r in blocked.reasons)
|
|
265
|
+
|
|
266
|
+
opened, _ = _pre(found, down, remote_policy={"token": TOKEN, "fail_mode": "open"})
|
|
267
|
+
allowed = opened.decide(url, req(found), request_url=url)
|
|
268
|
+
assert allowed.action == "allow" and allowed.remote_decision is None
|
|
269
|
+
assert any(r.effect == "info" and "fail_mode is open" in r.detail for r in allowed.reasons)
|
|
270
|
+
|
|
271
|
+
# Remote pass does not clear a local block.
|
|
272
|
+
passed, _ = _pre(found, lambda r: (200, {"decision": "pass"}), policy=STRICT_GUARD_POLICY, remote_policy={"token": TOKEN, "fail_mode": "open"})
|
|
273
|
+
still = passed.decide(url, req(found, payTo=DEAD), request_url=url)
|
|
274
|
+
assert still.action == "block" and still.remote_decision == "pass"
|
|
275
|
+
|
|
276
|
+
|
|
277
|
+
def test_interpret_policy_body_never_maps_a_null_to_pass():
|
|
278
|
+
effect = interpret_policy_body(503, {"decision": None}, "open", "blockrun.ai")
|
|
279
|
+
assert effect.decision is None and effect.effect == "info"
|
|
280
|
+
effect = interpret_policy_body(200, {"decision": None}, "closed", "blockrun.ai")
|
|
281
|
+
assert effect.decision is None and effect.effect == "block"
|
|
282
|
+
effect = interpret_policy_body(200, {"decision": "block"}, "open", "blockrun.ai")
|
|
283
|
+
assert effect.decision == "block"
|
|
284
|
+
effect = interpret_policy_body(None, {}, "closed", "blockrun.ai")
|
|
285
|
+
assert effect.decision is None and effect.effect == "block"
|
|
286
|
+
|
|
287
|
+
|
|
288
|
+
def test_async_payment_guard_applies_fail_mode(found):
|
|
289
|
+
import asyncio
|
|
290
|
+
|
|
291
|
+
seen, respond = _answer(found, lambda r: (503, {"decision": None}))
|
|
292
|
+
guard = PaymentGuard(async_http=httpx.AsyncClient(transport=httpx.MockTransport(respond)), remote_policy={"token": TOKEN, "fail_mode": "closed"})
|
|
293
|
+
url = found["latest_probe"]["url"]
|
|
294
|
+
|
|
295
|
+
async def run():
|
|
296
|
+
with guard.request(url):
|
|
297
|
+
return await guard.adecide(ctx(url, req(found)))
|
|
298
|
+
|
|
299
|
+
decision = asyncio.run(run())
|
|
300
|
+
assert decision.action == "block" and decision.remote_decision is None
|
|
301
|
+
assert any(r.url.path.endswith("/policy/check") for r in seen)
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|