presign-guard-wallet 0.13.0 → 0.15.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 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
@@ -50,7 +52,7 @@ try {
50
52
  }
51
53
  ```
52
54
 
53
- `wallet` is the same client: every other method (`getAddresses`, `signMessage`, `extend`, …) works as before, unchecked.
55
+ `wallet` is the same client. `signMessage` is checked too, as a plain message: a sign-in message (Sign-In with Ethereum) for another site than `origin` is red, unreadable bytes are orange; it counts toward no limit (`checkMessages: false` turns this off). Every other method (`getAddresses`, `extend`, …) works as before, unchecked.
54
56
 
55
57
  ## Options
56
58
 
@@ -64,6 +66,7 @@ try {
64
66
  | `origin` | | The site asking for the signature: its domain age and phishing lists are checked too |
65
67
  | `onVerdict` | | `(verdict, { method, request, paidWith, creditsLeft }) => void`, e.g. for logging; `paidWith` is `"credits"` or `"x402"` |
66
68
  | `verifyReceipts` | `"require"` | Check presign-guard's signed receipt on every verdict; `"off"` skips it |
69
+ | `checkMessages` | `true` | Check `signMessage` too ($0.01 per message, like any check); `false` signs messages unchecked |
67
70
  | `signers` | presign-guard's published signer | Accepted signer addresses |
68
71
  | `authority` | the Fizzl payout wallet | Wallet whose certificates also make a signer trusted (key rotation); `null` accepts only `signers` |
69
72
  | `limits` | | Spending limits per token, see [Spending limits](#spending-limits) |
@@ -290,7 +293,7 @@ presign-guard signs every paid verdict (EIP-191 over canonical JSON, with a hash
290
293
 
291
294
  ## Costs and coverage
292
295
 
293
- - $0.01 per checked signature, paid with your `pay` fetch, or $0.008 / $0.007 with [prepaid credits](#prepaid-credits). Calls presign-guard does not cover (`signMessage`, contract deployments) are not checked and cost nothing.
296
+ - $0.01 per checked signature, paid with your `pay` fetch, or $0.008 / $0.007 with [prepaid credits](#prepaid-credits). Calls presign-guard does not cover (contract deployments) are not checked and cost nothing; `signMessage` is checked unless `checkMessages: false`.
294
297
  - presign-guard reads public data (GoPlus, RugCheck, DexScreener, OFAC via PG1, phishing lists). A green verdict means no known problem was found, not a guarantee.
295
298
  - The requests carry `user-agent: presign-guard-wallet/<version>` so the service can count how often the package is used.
296
299
 
package/index.d.ts CHANGED
@@ -25,8 +25,9 @@ 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 }
29
- | { type: "signature"; chainId: number; typedData: unknown; origin?: string };
28
+ | { type: "transaction"; chainId: number; to: string; data: string; value: string; origin?: string; from?: string }
29
+ | { type: "signature"; chainId: number; typedData: unknown; origin?: string }
30
+ | { type: "message"; method: "personal_sign"; message: string; chainId?: number; origin?: string; from?: string };
30
31
 
31
32
  export declare class PresignBlockedError extends Error {
32
33
  code: "red" | "orange" | "check_failed" | "bad_receipt" | "unsupported_chain" | "over_limit" | "paused" | "limit_unavailable";
@@ -174,6 +175,8 @@ export interface GuardOptions {
174
175
  presignUrl?: string;
175
176
  /** Check presign-guard's signed receipt on every verdict. Default "require". */
176
177
  verifyReceipts?: "require" | "off";
178
+ /** Check signMessage with presign-guard too (default true): eth_sign-style hashes are orange, a sign-in message for another site than origin is red. */
179
+ checkMessages?: boolean;
177
180
  /** Accepted signer addresses. Default: the published signer (PRESIGN_SIGNERS). */
178
181
  signers?: string[];
179
182
  /** Wallet whose certificates also make a signer trusted (key rotation). Default: the Fizzl payout wallet; null accepts only `signers`. */
@@ -192,7 +195,7 @@ export interface GuardOptions {
192
195
 
193
196
  /** The same wallet client; sendTransaction, writeContract and signTypedData are checked first. */
194
197
  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; x402?: Record<string, unknown> }): CheckRequest | null;
198
+ export declare function checkRequestFor(method: string, args: unknown, options?: { chainId?: number; origin?: string; x402?: Record<string, unknown>; from?: string }): CheckRequest | null;
196
199
  /**
197
200
  * Wrap an x402 client scheme so the payment requirements it pays go along with the presign-guard check of its
198
201
  * EIP-3009 signature (red when the signature pays more, someone else, another token or chain than asked).
package/index.js CHANGED
@@ -48,7 +48,7 @@
48
48
  // toward the limits (XRP toward an XRP limit, RLUSD toward USDC). Use it with
49
49
  // @x402/xrpl's ExactXrplScheme to pay x402 services in RLUSD.
50
50
 
51
- import { decodeFunctionData, encodeFunctionData, parseAbi } from "viem";
51
+ import { bytesToHex, decodeFunctionData, encodeFunctionData, parseAbi } from "viem";
52
52
  import { verifyReceipt, AUTHORITY } from "x402-safe-fetch";
53
53
  import { createLimiter, memoryStore } from "./limits.js";
54
54
  import { createRemoteLimiter } from "./remote.js";
@@ -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.13.0";
81
+ export const VERSION = "0.15.0";
82
82
  export const CREDIT_HEADER = "x-credit-key";
83
83
  const ROUTE = "POST /v1/check";
84
84
 
@@ -121,16 +121,32 @@ export function x402Checked(scheme) {
121
121
  });
122
122
  }
123
123
 
124
- // What presign-guard should check for a wallet call, or null for calls it does not cover.
125
- export function checkRequestFor(method, args, { chainId, origin, x402 } = {}) {
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 } = {}) {
126
134
  const base = { chainId, ...(origin ? { origin } : {}) };
135
+ const sender = from ? { from } : {};
127
136
  if (method === "sendTransaction") {
128
137
  if (!args?.to) return null; // contract deployment: nothing to screen
129
- 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) };
130
139
  }
131
140
  if (method === "writeContract") {
132
141
  const data = encodeFunctionData({ abi: args.abi, functionName: args.functionName, args: args.args });
133
- 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) };
143
+ }
144
+ if (method === "signMessage") {
145
+ // viem: a string is signed as text, { raw } as bytes (hex or a byte array).
146
+ const m = args?.message;
147
+ const message = typeof m === "string" ? m : typeof m?.raw === "string" ? m.raw : m?.raw instanceof Uint8Array ? bytesToHex(m.raw) : null;
148
+ if (message === null) return null;
149
+ return { type: "message", method: "personal_sign", message, ...(chainId ? { chainId } : {}), ...(origin ? { origin } : {}), ...sender };
134
150
  }
135
151
  if (method === "signTypedData") {
136
152
  const { domain, types, primaryType, message } = args;
@@ -204,6 +220,7 @@ function cleanPurchase(info) {
204
220
  * @param {(entry: object) => void} [options.onSpend] after each signed spend
205
221
  * @param {{url: string, key: string}} [options.server] a wallet server (fizzl wallet-server) keeps the limits, budget and approvals for all your agents
206
222
  * @param {object} [options.store] where spending is kept (default in memory; fileStore from presign-guard-wallet/file-store)
223
+ * @param {boolean} [options.checkMessages] check signMessage too (default true): a sign-in message for another site is red
207
224
  */
208
225
  export function guardWallet(wallet, {
209
226
  pay,
@@ -216,6 +233,7 @@ export function guardWallet(wallet, {
216
233
  signers = PRESIGN_SIGNERS,
217
234
  authority = AUTHORITY,
218
235
  creditKey,
236
+ checkMessages = true,
219
237
  fetch: plainFetch = globalThis.fetch,
220
238
  limits,
221
239
  onOverLimit,
@@ -229,6 +247,7 @@ export function guardWallet(wallet, {
229
247
  if (!["stop", "allow"].includes(onOrange) && typeof onOrange !== "function") throw new TypeError('onOrange must be "stop", "allow" or a function');
230
248
  if (!["stop", "allow"].includes(onError)) throw new TypeError('onError must be "stop" or "allow"');
231
249
  if (!["require", "off"].includes(verifyReceipts)) throw new TypeError('verifyReceipts must be "require" or "off"');
250
+ if (typeof checkMessages !== "boolean") throw new TypeError("checkMessages must be true or false");
232
251
 
233
252
  if (server !== undefined && (limits !== undefined || onOverLimit || store)) throw new TypeError("with server, the limits and approvals live on the wallet server: leave out limits, onOverLimit and store");
234
253
  if (server === undefined && limits === undefined && (onOverLimit || onSpend || store)) throw new TypeError("onOverLimit, onSpend and store need limits");
@@ -272,7 +291,7 @@ export function guardWallet(wallet, {
272
291
 
273
292
  // The verdict for a request, or null when the check could not be done and onError is "allow".
274
293
  async function verdictFor(method, request, chainId) {
275
- if (!SUPPORTED_CHAINS.includes(chainId) && !XRPL_NETWORKS.includes(chainId)) {
294
+ if (request.type !== "message" && !SUPPORTED_CHAINS.includes(chainId) && !XRPL_NETWORKS.includes(chainId)) {
276
295
  if (onError === "allow") return null;
277
296
  throw new PresignBlockedError(`chain ${chainId} is not covered by presign-guard; nothing was signed`, { code: "unsupported_chain", request });
278
297
  }
@@ -339,11 +358,17 @@ export function guardWallet(wallet, {
339
358
  if (paused) throw new PresignBlockedError(`wallet is paused; nothing was signed`, { code: "paused" });
340
359
  const chainId = args?.chain?.id ?? target.chain?.id;
341
360
  const run = () => original(args, ...rest);
361
+ // A plain message moves nothing by itself, so it is checked but not counted toward the limits.
362
+ if (method === "signMessage") {
363
+ const request = checkRequestFor(method, args, { chainId, origin, from: senderOf(args, target) });
364
+ if (request) await verdictFor(method, request, chainId);
365
+ return run();
366
+ }
342
367
  if (TEMPO_TOKENS[chainId]) {
343
368
  const request = tempoRequest(method, args, chainId);
344
369
  return limiter ? withinLimits(method, request, null, run) : run();
345
370
  }
346
- const request = checkRequestFor(method, args, { chainId, origin, x402: x402Paying.getStore() });
371
+ const request = checkRequestFor(method, args, { chainId, origin, x402: x402Paying.getStore(), from: senderOf(args, target) });
347
372
  if (!request) {
348
373
  // A contract deployment is not checked, but the value it sends still counts.
349
374
  if (limiter && method === "sendTransaction") {
@@ -497,7 +522,7 @@ export function guardWallet(wallet, {
497
522
  get(target, prop, receiver) {
498
523
  if (Object.hasOwn(extras, prop) && !(prop in target)) return extras[prop];
499
524
  const value = Reflect.get(target, prop, receiver);
500
- if (typeof prop !== "string" || !GUARDED.has(prop) || typeof value !== "function") return value;
525
+ if (typeof prop !== "string" || !(GUARDED.has(prop) || (checkMessages && prop === "signMessage")) || typeof value !== "function") return value;
501
526
  return (args, ...rest) => guarded(target, prop, value.bind(target), args, rest);
502
527
  },
503
528
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "presign-guard-wallet",
3
- "version": "0.13.0",
3
+ "version": "0.15.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": {