presign-guard-wallet 0.26.1 → 0.27.0
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 +4 -1
- package/index.d.ts +10 -2
- package/index.js +20 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -6,10 +6,12 @@ Before every `sendTransaction`, `writeContract`, `signTypedData` and `signAuthor
|
|
|
6
6
|
|
|
7
7
|
| Verdict | What the wallet does |
|
|
8
8
|
|---|---|
|
|
9
|
-
| 🟢 green | Signs |
|
|
9
|
+
| 🟢 green | Signs; with `onIncomplete: "stop"`, not when presign-guard says a check couldn't run (`checks_complete: false`) |
|
|
10
10
|
| 🟠 orange | `onOrange`: `"stop"` (default, throws), `"allow"`, or your own function (e.g. ask the user) |
|
|
11
11
|
| 🔴 red | Throws `PresignBlockedError` with the reasons; **nothing is signed** |
|
|
12
12
|
|
|
13
|
+
On red and orange the error message ends with presign-guard's fix for the first reason that has one ("to fix: approve exactly the amount needed…", "don't retry: …"), so an agent that reads only the error knows whether to rebuild the request or stop.
|
|
14
|
+
|
|
13
15
|
On top of that it can keep to **spending limits** you set per token (per transaction and per day), and ask a human for anything over them. See [Spending limits](#spending-limits).
|
|
14
16
|
|
|
15
17
|
presign-guard decodes approvals, `increaseAllowance`, `setApprovalForAll`, EIP-2612 and Permit2 permits, EIP-3009 transfer authorizations (what an x402 payment signs) and Seaport orders, and screens every spender, recipient and token: known drainers and phishing addresses, sanctions, unlimited approvals to a plain wallet, honeypot tokens, unverified or brand-new contracts, and, with `origin`, new or lookalike domains and phishing sites. See the [reason codes](https://github.com/Fizzl13/presign-guard#reason-codes).
|
|
@@ -73,6 +75,7 @@ Every other method (`getAddresses`, `extend`, `sendRawTransaction` for a transac
|
|
|
73
75
|
| `creditKey` | | A presign-guard credit key (`pgc_…`): checks are paid from prepaid credits first, then with `pay`. See [Prepaid credits](#prepaid-credits) |
|
|
74
76
|
| `fetch` | `globalThis.fetch` | Plain fetch used for credit-paid checks |
|
|
75
77
|
| `onOrange` | `"stop"` | `"stop"`, `"allow"` or `async (verdict, { method, request }) => boolean`. `"allow"` does not cover [EIP-7702 authorizations](#eip-7702-authorizations) |
|
|
78
|
+
| `onIncomplete` | `"allow"` | A green whose `checks_complete` is `false` (a check that applies couldn't run this time, named in `not_checked`): `"allow"` signs, `"stop"` throws code `incomplete`, or `async (verdict, { method, request }) => boolean` decides (e.g. stop above an amount) |
|
|
76
79
|
| `onError` | `"stop"` | When the check cannot be done (outage, a chain presign-guard does not cover): `"stop"` or `"allow"`. An EIP-7702 authorization always stops |
|
|
77
80
|
| `origin` | | The site asking for the signature: its domain age and phishing lists are checked too |
|
|
78
81
|
| `onVerdict` | | `(verdict, { method, request, paidWith, creditsLeft }) => void`, e.g. for logging; `paidWith` is `"credits"` or `"x402"` |
|
package/index.d.ts
CHANGED
|
@@ -17,7 +17,13 @@ export declare const CREDIT_HEADER: string;
|
|
|
17
17
|
/** A presign-guard verdict: see https://presign-guard.fizzl.eu/openapi.json */
|
|
18
18
|
export interface PresignVerdict {
|
|
19
19
|
verdict: "green" | "orange" | "red";
|
|
20
|
-
reasons?: Array<{ code: string; severity: "red" | "orange" | "info"; subject?: string; details?: Record<string, unknown> }>;
|
|
20
|
+
reasons?: Array<{ code: string; severity: "red" | "orange" | "info"; subject?: string; details?: Record<string, unknown>; fix?: { expected: string; saw: string; change: string; retry: "change" | "elsewhere" | "ask" | "never"; set?: Record<string, unknown> } }>;
|
|
21
|
+
/** true when every orange and red reason can be changed into green */
|
|
22
|
+
fixable?: boolean;
|
|
23
|
+
checked?: Array<{ check: string; what: string }>;
|
|
24
|
+
not_checked?: Array<{ check: string; because: "unavailable" | "not_sent" | "out_of_scope"; why: string; send?: string; subject?: string }>;
|
|
25
|
+
/** false when a check that applies couldn't run this time */
|
|
26
|
+
checks_complete?: boolean;
|
|
21
27
|
subject?: Record<string, unknown>;
|
|
22
28
|
receipt?: Record<string, unknown>;
|
|
23
29
|
[key: string]: unknown;
|
|
@@ -31,7 +37,7 @@ export type CheckRequest =
|
|
|
31
37
|
| { type: "authorization"; chainId: number; address: string; authorizationChainId?: number; nonce?: string; origin?: string; from?: string };
|
|
32
38
|
|
|
33
39
|
export declare class PresignBlockedError extends Error {
|
|
34
|
-
code: "red" | "orange" | "check_failed" | "bad_receipt" | "unsupported_chain" | "over_limit" | "paused" | "limit_unavailable";
|
|
40
|
+
code: "red" | "orange" | "incomplete" | "check_failed" | "bad_receipt" | "unsupported_chain" | "over_limit" | "paused" | "limit_unavailable";
|
|
35
41
|
verdict: PresignVerdict | null;
|
|
36
42
|
request: CheckRequest | null;
|
|
37
43
|
/** With code "over_limit": which limits would be crossed. */
|
|
@@ -184,6 +190,8 @@ export interface GuardOptions {
|
|
|
184
190
|
fetch?: typeof globalThis.fetch;
|
|
185
191
|
/** What to do on an orange verdict. Default "stop". "allow" does not cover EIP-7702 authorizations: an orange one is signed only when your function returns true. */
|
|
186
192
|
onOrange?: "stop" | "allow" | ((verdict: PresignVerdict, info: { method: string; request: CheckRequest }) => boolean | Promise<boolean>);
|
|
193
|
+
/** A green whose checks_complete is false (a check that applies couldn't run): "allow" (default) signs, "stop" throws code "incomplete", a function decides. */
|
|
194
|
+
onIncomplete?: "allow" | "stop" | ((verdict: PresignVerdict, info: { method: string; request: CheckRequest }) => boolean | Promise<boolean>);
|
|
187
195
|
/** When the check cannot be done (outage, unsupported chain). Default "stop". A forged or changed verdict, and an EIP-7702 authorization, always stop. */
|
|
188
196
|
onError?: "stop" | "allow";
|
|
189
197
|
/** The site asking for the signature, if any: domain age and phishing lists are checked. */
|
package/index.js
CHANGED
|
@@ -238,6 +238,15 @@ function cleanPurchase(info) {
|
|
|
238
238
|
return out;
|
|
239
239
|
}
|
|
240
240
|
|
|
241
|
+
// presign-guard's fix for the first orange or red reason that has one (what to change to get green), for the error
|
|
242
|
+
// message: an agent that reads only the error still learns whether to rebuild the request or not sign at all.
|
|
243
|
+
function fixHint(verdict) {
|
|
244
|
+
const fix = (verdict?.reasons || []).find((r) => r?.severity !== "info" && r?.fix?.change)?.fix;
|
|
245
|
+
if (!fix) return "";
|
|
246
|
+
const what = fix.retry === "change" ? "to fix" : fix.retry === "never" ? "don't retry" : fix.retry === "elsewhere" ? "use another contract, pool or site" : "ask the user";
|
|
247
|
+
return `; ${what}: ${String(fix.change).slice(0, 240)}`;
|
|
248
|
+
}
|
|
249
|
+
|
|
241
250
|
/**
|
|
242
251
|
* @param {object} wallet a viem WalletClient
|
|
243
252
|
* @param {object} options
|
|
@@ -246,6 +255,8 @@ function cleanPurchase(info) {
|
|
|
246
255
|
* @param {typeof fetch} [options.fetch] plain fetch for credit-paid checks (default globalThis.fetch)
|
|
247
256
|
* @param {"stop"|"allow"|((verdict: object, info: object) => boolean|Promise<boolean>)} [options.onOrange]
|
|
248
257
|
* @param {"stop"|"allow"} [options.onError] when the check cannot be done (default "stop")
|
|
258
|
+
* @param {"allow"|"stop"|((verdict: object, info: object) => boolean|Promise<boolean>)} [options.onIncomplete] a green whose
|
|
259
|
+
* checks_complete is false (a check that applies couldn't run): "allow" (default) signs, "stop" throws, a function decides
|
|
249
260
|
* @param {string} [options.origin] the site asking for the signature, if any (domain age, phishing lists)
|
|
250
261
|
* @param {(verdict: object, info: {method: string, request: object}) => void} [options.onVerdict]
|
|
251
262
|
* @param {string} [options.presignUrl]
|
|
@@ -263,6 +274,7 @@ export function guardWallet(wallet, {
|
|
|
263
274
|
pay,
|
|
264
275
|
onOrange = "stop",
|
|
265
276
|
onError = "stop",
|
|
277
|
+
onIncomplete = "allow",
|
|
266
278
|
origin,
|
|
267
279
|
onVerdict,
|
|
268
280
|
presignUrl = PRESIGN_URL,
|
|
@@ -283,6 +295,7 @@ export function guardWallet(wallet, {
|
|
|
283
295
|
if (typeof pay !== "function" && !creditKey) throw new TypeError("pay is required: a fetch that pays x402, e.g. wrapFetchWithPayment(fetch, client), or a creditKey");
|
|
284
296
|
if (!["stop", "allow"].includes(onOrange) && typeof onOrange !== "function") throw new TypeError('onOrange must be "stop", "allow" or a function');
|
|
285
297
|
if (!["stop", "allow"].includes(onError)) throw new TypeError('onError must be "stop" or "allow"');
|
|
298
|
+
if (!["stop", "allow"].includes(onIncomplete) && typeof onIncomplete !== "function") throw new TypeError('onIncomplete must be "allow", "stop" or a function');
|
|
286
299
|
if (!["require", "off"].includes(verifyReceipts)) throw new TypeError('verifyReceipts must be "require" or "off"');
|
|
287
300
|
if (typeof checkMessages !== "boolean") throw new TypeError("checkMessages must be true or false");
|
|
288
301
|
|
|
@@ -345,15 +358,20 @@ export function guardWallet(wallet, {
|
|
|
345
358
|
}
|
|
346
359
|
onVerdict?.(verdict, { method, request, paidWith: verdict.paidWith, creditsLeft });
|
|
347
360
|
const why = (verdict.reasons || []).filter((r) => r.severity !== "info").map((r) => r.code).join(", ") || verdict.verdict;
|
|
348
|
-
if (verdict.verdict === "red") throw new PresignBlockedError(`not signed: red (${why})`, { code: "red", verdict, request });
|
|
361
|
+
if (verdict.verdict === "red") throw new PresignBlockedError(`not signed: red (${why})${fixHint(verdict)}`, { code: "red", verdict, request });
|
|
349
362
|
if (verdict.verdict === "orange") {
|
|
350
363
|
// onOrange "allow" does not cover an EIP-7702 authorization: only your function's yes does.
|
|
351
364
|
const authorization = request.type === "authorization";
|
|
352
365
|
const ok = (onOrange === "allow" && !authorization) || (typeof onOrange === "function" && (await onOrange(verdict, { method, request })) === true);
|
|
353
366
|
const hint = authorization && onOrange === "allow" ? '; an EIP-7702 authorization is signed on orange only when your onOrange function says yes' : "";
|
|
354
|
-
if (!ok) throw new PresignBlockedError(`not signed: orange (${why})${hint}`, { code: "orange", verdict, request });
|
|
367
|
+
if (!ok) throw new PresignBlockedError(`not signed: orange (${why})${hint}${fixHint(verdict)}`, { code: "orange", verdict, request });
|
|
355
368
|
} else if (verdict.verdict !== "green") {
|
|
356
369
|
throw new PresignBlockedError(`not signed: unknown verdict ${verdict.verdict}`, { code: "check_failed", verdict, request });
|
|
370
|
+
} else if (verdict.checks_complete === false && onIncomplete !== "allow") {
|
|
371
|
+
// Green on less than usual: a check that applies couldn't run this time (presign-guard's not_checked says which).
|
|
372
|
+
const ok = typeof onIncomplete === "function" && (await onIncomplete(verdict, { method, request })) === true;
|
|
373
|
+
const missing = (verdict.not_checked || []).filter((n) => n?.because === "unavailable").map((n) => n.check).join(", ") || "unknown";
|
|
374
|
+
if (!ok) throw new PresignBlockedError(`not signed: green, but not every check ran (${missing}); check again in a moment`, { code: "incomplete", verdict, request });
|
|
357
375
|
}
|
|
358
376
|
return verdict;
|
|
359
377
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "presign-guard-wallet",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.27.0",
|
|
4
4
|
"description": "A wallet for AI agents (viem on EVM chains, Solana and Algorand) that asks presign-guard ($0.01 over x402) before every transaction, contract write and signature, refuses to sign red, and keeps to per-token spending limits, with approval from your phone over the limit (Telegram, or signed in your own wallet over AC2).",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"exports": {
|