presign-guard-wallet 0.12.0 → 0.14.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 +17 -0
- package/index.d.ts +7 -2
- package/index.js +42 -7
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -14,6 +14,8 @@ On top of that it can keep to **spending limits** you set per token (per transac
|
|
|
14
14
|
|
|
15
15
|
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).
|
|
16
16
|
|
|
17
|
+
Transactions are also **simulated**: the wallet sends its own address along (`from`), and presign-guard runs the transaction against the latest block to see what really leaves the wallet, also inside routers, multicalls and batches. An approval the call doesn't show (`HIDDEN_APPROVAL`), an NFT leaving the wallet (`SIMULATION_NFT_OUT`) or a transaction that would fail (`SIMULATION_FAILS`) is orange, so with the default `onOrange: "stop"` nothing is signed.
|
|
18
|
+
|
|
17
19
|
> **Just want an agent that pays within limits, with approvals on your phone?** The hosted [Fizzl Agent Wallet](https://wallet.fizzl.eu/?ref=readme) wraps this library in an MCP server for Claude, Cursor and other MCP clients: sign in, add an agent, copy its setup. No code needed.
|
|
18
20
|
|
|
19
21
|
## Install
|
|
@@ -202,6 +204,21 @@ const wallet = guardWallet(walletClient, {
|
|
|
202
204
|
|
|
203
205
|
If the server can't be reached the wallet stops (`limit_unavailable`); paused on the dashboard means `paused`.
|
|
204
206
|
|
|
207
|
+
## Checking x402 payments against what the seller asked
|
|
208
|
+
|
|
209
|
+
Wrap the x402 payment scheme with `x402Checked` and the payment requirements it pays (the `accepts` entry it chose) go along with the presign-guard check of its EIP-3009 signature. presign-guard then makes a signature that pays more than asked, someone else, another token or another chain red (`X402_AMOUNT_ABOVE_REQUIRED`, `X402_RECIPIENT_MISMATCH`, `X402_ASSET_MISMATCH`, `X402_NETWORK_MISMATCH`), and one that stays valid far longer than the seller's timeout orange (`X402_VALIDITY_TOO_LONG`), before anything is signed. It catches a hostile server or a broken client library.
|
|
210
|
+
|
|
211
|
+
```js
|
|
212
|
+
import { guardWallet, x402Checked } from "presign-guard-wallet";
|
|
213
|
+
import { ExactEvmScheme } from "@x402/evm/exact/client";
|
|
214
|
+
|
|
215
|
+
const wallet = guardWallet(walletClient, { pay });
|
|
216
|
+
const signer = { address: account.address, signTypedData: (t) => wallet.signTypedData({ account, ...t }) };
|
|
217
|
+
client.register("eip155:8453", x402Checked(new ExactEvmScheme(signer)));
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
It combines with a mandate: `x402Checked(mandatePayer(scheme, mandate))`.
|
|
221
|
+
|
|
205
222
|
## Paying under a mandate
|
|
206
223
|
|
|
207
224
|
A principal can give an agent a signed spending mandate ([x402 `authority` extension draft](https://github.com/x402-foundation/x402/pull/3220), `x402-mandate/1`): "spend up to CAP, to recipients in R, until T". Wrap the payment scheme with `mandatePayer` and each x402 payment is made under it: the EIP-3009 nonce becomes the binding of (mandate, paymentId), so the settled payment proves which grant it used, and the guarded wallet sends the mandate along with the check. presign-guard then makes a payment outside the mandate red (over `perPayment` or `cap`, another recipient, payer or token, expired, bad signature), before anything is signed.
|
package/index.d.ts
CHANGED
|
@@ -25,7 +25,7 @@ export interface PresignVerdict {
|
|
|
25
25
|
|
|
26
26
|
/** What is sent to presign-guard's POST /v1/check. */
|
|
27
27
|
export type CheckRequest =
|
|
28
|
-
| { type: "transaction"; chainId: number; to: string; data: string; value: string; origin?: string }
|
|
28
|
+
| { type: "transaction"; chainId: number; to: string; data: string; value: string; origin?: string; from?: string }
|
|
29
29
|
| { type: "signature"; chainId: number; typedData: unknown; origin?: string };
|
|
30
30
|
|
|
31
31
|
export declare class PresignBlockedError extends Error {
|
|
@@ -192,7 +192,12 @@ export interface GuardOptions {
|
|
|
192
192
|
|
|
193
193
|
/** The same wallet client; sendTransaction, writeContract and signTypedData are checked first. */
|
|
194
194
|
export declare function guardWallet<W extends WalletClient>(wallet: W, options: GuardOptions): W & GuardControls;
|
|
195
|
-
export declare function checkRequestFor(method: string, args: unknown, options?: { chainId?: number; origin?: string }): CheckRequest | null;
|
|
195
|
+
export declare function checkRequestFor(method: string, args: unknown, options?: { chainId?: number; origin?: string; x402?: Record<string, unknown>; from?: string }): CheckRequest | null;
|
|
196
|
+
/**
|
|
197
|
+
* Wrap an x402 client scheme so the payment requirements it pays go along with the presign-guard check of its
|
|
198
|
+
* EIP-3009 signature (red when the signature pays more, someone else, another token or chain than asked).
|
|
199
|
+
*/
|
|
200
|
+
export function x402Checked<S extends { scheme?: string; createPaymentPayload: (...args: any[]) => Promise<unknown> }>(scheme: S): S;
|
|
196
201
|
|
|
197
202
|
/** A principal's signed spending mandate (x402 `authority` extension draft, x402-mandate/1). */
|
|
198
203
|
export interface MandateEnvelope {
|
package/index.js
CHANGED
|
@@ -78,7 +78,7 @@ const ESCROW_ABI = parseAbi([
|
|
|
78
78
|
const TRANSFER_ABI = parseAbi(["function transfer(address to, uint256 amount)"]);
|
|
79
79
|
const VOUCHER_DOMAIN = "TIP20 Channel Reserve";
|
|
80
80
|
export const XRPL_NETWORKS = ["xrpl:0", "xrpl:1"];
|
|
81
|
-
export const VERSION = "0.
|
|
81
|
+
export const VERSION = "0.14.0";
|
|
82
82
|
export const CREDIT_HEADER = "x-credit-key";
|
|
83
83
|
const ROUTE = "POST /v1/check";
|
|
84
84
|
|
|
@@ -96,22 +96,57 @@ export class PresignBlockedError extends Error {
|
|
|
96
96
|
// JSON with bigints as decimal strings (viem uses bigint for values and amounts).
|
|
97
97
|
const toJson = (value) => JSON.stringify(value, (_k, v) => (typeof v === "bigint" ? v.toString() : v));
|
|
98
98
|
|
|
99
|
-
//
|
|
100
|
-
|
|
99
|
+
// The x402 payment requirements being paid right now (x402Checked), so presign-guard can check that the
|
|
100
|
+
// EIP-3009 signature pays exactly what the seller asked: amount, payTo, asset, network, validity.
|
|
101
|
+
const x402Paying = new AsyncLocalStorage();
|
|
102
|
+
function cleanRequirements(r) {
|
|
103
|
+
if (!r || typeof r !== "object") return null;
|
|
104
|
+
const out = {};
|
|
105
|
+
for (const k of ["scheme", "network", "amount", "maxAmountRequired", "asset", "payTo", "maxTimeoutSeconds"]) if (r[k] !== undefined && r[k] !== null) out[k] = typeof r[k] === "bigint" ? r[k].toString() : r[k];
|
|
106
|
+
if (r.extra && typeof r.extra === "object") out.extra = { ...(r.extra.name !== undefined && { name: r.extra.name }), ...(r.extra.version !== undefined && { version: r.extra.version }) };
|
|
107
|
+
return out;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* Wrap an x402 client scheme (e.g. new ExactEvmScheme(guardedSigner)) so the payment requirements it pays go
|
|
112
|
+
* along with the presign-guard check of the EIP-3009 signature: a signature that pays more, someone else, another
|
|
113
|
+
* token or chain than the seller asked is red (X402_AMOUNT_ABOVE_REQUIRED, X402_RECIPIENT_MISMATCH, …).
|
|
114
|
+
*/
|
|
115
|
+
export function x402Checked(scheme) {
|
|
116
|
+
return Object.assign(Object.create(scheme), {
|
|
117
|
+
scheme: scheme.scheme ?? "exact",
|
|
118
|
+
createPaymentPayload(x402Version, requirements, ...rest) {
|
|
119
|
+
return x402Paying.run(cleanRequirements(requirements), () => scheme.createPaymentPayload(x402Version, requirements, ...rest));
|
|
120
|
+
},
|
|
121
|
+
});
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
// The wallet a transaction is sent from: the call's account, else the client's.
|
|
125
|
+
function senderOf(args, client) {
|
|
126
|
+
const a = args?.account ?? client?.account;
|
|
127
|
+
const address = typeof a === "string" ? a : a?.address;
|
|
128
|
+
return typeof address === "string" && /^0x[0-9a-fA-F]{40}$/.test(address) ? address : null;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
// What presign-guard should check for a wallet call, or null for calls it does not cover. With `from` (the
|
|
132
|
+
// sending wallet) presign-guard simulates a transaction and reports what really leaves the wallet.
|
|
133
|
+
export function checkRequestFor(method, args, { chainId, origin, x402, from } = {}) {
|
|
101
134
|
const base = { chainId, ...(origin ? { origin } : {}) };
|
|
135
|
+
const sender = from ? { from } : {};
|
|
102
136
|
if (method === "sendTransaction") {
|
|
103
137
|
if (!args?.to) return null; // contract deployment: nothing to screen
|
|
104
|
-
return { type: "transaction", ...base, to: args.to, data: args.data ?? "0x", value: String(args.value ?? 0n) };
|
|
138
|
+
return { type: "transaction", ...base, ...sender, to: args.to, data: args.data ?? "0x", value: String(args.value ?? 0n) };
|
|
105
139
|
}
|
|
106
140
|
if (method === "writeContract") {
|
|
107
141
|
const data = encodeFunctionData({ abi: args.abi, functionName: args.functionName, args: args.args });
|
|
108
|
-
return { type: "transaction", ...base, to: args.address, data, value: String(args.value ?? 0n) };
|
|
142
|
+
return { type: "transaction", ...base, ...sender, to: args.address, data, value: String(args.value ?? 0n) };
|
|
109
143
|
}
|
|
110
144
|
if (method === "signTypedData") {
|
|
111
145
|
const { domain, types, primaryType, message } = args;
|
|
112
146
|
// A payment made by mandatePayer() (mandate.js) is checked against its mandate too.
|
|
113
147
|
const under = primaryType === "TransferWithAuthorization" ? mandateFor(message?.nonce) : null;
|
|
114
|
-
|
|
148
|
+
const paying = primaryType === "TransferWithAuthorization" && x402 ? { x402: { accepted: x402 } } : {};
|
|
149
|
+
return { type: "signature", ...base, typedData: { domain, types, primaryType, message }, ...(under && { mandate: { ...under.envelope, paymentId: under.paymentId } }), ...paying };
|
|
115
150
|
}
|
|
116
151
|
return null;
|
|
117
152
|
}
|
|
@@ -317,7 +352,7 @@ export function guardWallet(wallet, {
|
|
|
317
352
|
const request = tempoRequest(method, args, chainId);
|
|
318
353
|
return limiter ? withinLimits(method, request, null, run) : run();
|
|
319
354
|
}
|
|
320
|
-
const request = checkRequestFor(method, args, { chainId, origin });
|
|
355
|
+
const request = checkRequestFor(method, args, { chainId, origin, x402: x402Paying.getStore(), from: senderOf(args, target) });
|
|
321
356
|
if (!request) {
|
|
322
357
|
// A contract deployment is not checked, but the value it sends still counts.
|
|
323
358
|
if (limiter && method === "sendTransaction") {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "presign-guard-wallet",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.14.0",
|
|
4
4
|
"description": "A viem wallet for AI agents that asks presign-guard ($0.01 over x402) before every transaction, contract write and typed-data signature, refuses to sign red, and keeps to per-token spending limits, with approval from your phone over the limit.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"exports": {
|