Add x402 spend limits and payment audit logging

[kome12]

Summary

• Add a configurable cumulative spend cap for x402 auto-payments (NANSEN_X402_DAILY_MAX_AMOUNT, default $10.00; NANSEN_X402_SESSION_MAX_AMOUNT optional per-process cap)
• Persist local x402 payment audit records at ~/.nansen/x402/payments.jsonl for signed, accepted, rejected, and ambiguous payment attempts
• Enforce caps before local, Privy, and WalletConnect signing; only accepted and ambiguous outcomes count against the daily ledger
• Surface likely insufficient-balance rejections with a clearer stderr message
• Document new x402 safety environment variables in wallet help text and schema

Details

• New src/x402-ledger.js: atomic daily ledger writes (temp-file + rename), JSONL audit log, fail-closed on corrupt ledger, URL sanitisation strips query strings before logging
• evaluatePaymentRequirement() return extended with network, asset, payTo, amountRaw so providers have full metadata without re-deriving it
• handleX402Payment() in walletconnect-x402.js now returns { signature, paymentId, network, asset } instead of a bare string — also fixes a silent gap where network was always null in the WalletConnect retry path
• _x402Retry() gains a paymentMeta argument and finalises each attempt at every outcome branch before returning or throwing

Testing

• npm test (72/72 pass)
• npm run lint

[nansen-pr-reviewer]

pr-reviewer Summary for #f12cce8

📝 3 findings

Review completed. Please address the findings below.

Findings by Severity

Severity	Count
🟡 Medium	2
🔵 Low	1

Review effort: 4/5 (Complex)

Summary

This is a well-structured PR that adds meaningful financial safety guards to x402 auto-payments. The atomic write pattern (temp-file + rename), fail-closed ledger semantics, per-outcome finalization at every branch, and the X402_PAYMENT_REJECTED sentinel fix are all solid. No critical bugs found. Three findings worth addressing before or shortly after merge.

Findings

---

src/x402-ledger.js — Temp file orphaned on writeFileSync failure (medium)

Lines 343–344

fs.writeFileSync(tmpPath, JSON.stringify(updated), { mode: 0o600 });
fs.renameSync(tmpPath, filePath);

writeFileSync can fail mid-write (e.g. ENOSPC, permissions error) and leave a .pid.tmp file behind. The error propagates out of withLedgerLock, which then unlinks only the .lock file. On the next invocation readDailySpendMicros never touches the stale .tmp file, so no data is lost — but the orphan accumulates silently. Under concurrent load or repeated low-disk failures this can fill the ledger directory.

Fix: wrap the write+rename in a try/finally that attempts fs.unlinkSync(tmpPath) on failure:

fs.writeFileSync(tmpPath, JSON.stringify(updated), { mode: 0o600 });
try {
  fs.renameSync(tmpPath, filePath);
} catch (err) {
  try { fs.unlinkSync(tmpPath); } catch { /* best-effort */ }
  throw err;
}

---

src/privy.js — Generator catch block silently swallows errors when signing succeeds but yield throws (medium)

Lines 361–368 and 434–440 (EVM and SVM loops, same pattern)

try {
  // ... build header ...
  paymentId = recordPaymentAttempt({ ... });
  yield { signature: header, ... , paymentId };
} catch (err) {
  if (paymentId) {
    finalizePaymentAttempt(paymentId, { status: 'ambiguous', reason: err.message });
    throw err;   // ← re-throws
  }
  console.error(`[x402] Privy EVM signing failed …`);
  continue;      // ← swallowed
}

The catch branch that reaches continue is only reachable before paymentId is assigned — i.e., an error in buildEIP712TypedData, ethSignTypedDataV4, or buildPaymentSignatureHeader. Those are all pre-signature failures and the continue is correct. However, if yield throws (the generator consumer throws back into the generator, which is legal and happens when _x402Retry propagates PAYMENT_AMBIGUOUS), and that throw arrives after paymentId was set, the paymentId branch correctly re-throws. That part is fine.

The subtler issue: recordPaymentAttempt itself can never throw (its file I/O is wrapped in try/catch { /* best-effort */ }), so if signing succeeds but recordPaymentAttempt returns without setting paymentId (which only happens if entry.amountUsd is undefined) the payment is yielded without a paymentId and will never be finalized. In the Privy path decision.usd is always set by evaluatePaymentRequirement before reaching this code, so in practice this is unreachable — but the invariant is not asserted. Consider adding a guard:

paymentId = recordPaymentAttempt({ amountUsd: decision.usd, ... });
if (!paymentId) throw new Error('recordPaymentAttempt returned no id'); // defensive

Or document that decision.usd is always defined at this point so a future refactor doesn't silently drop audit records.

---

src/x402-ledger.js — Atomics.wait on the main thread is documented as non-blocking in some environments (low)

Line 170

function sleepSync(ms) {
  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
}

Atomics.wait is forbidden in the main browser thread and returns "not-equal" without blocking in some embedded V8 environments (Deno, certain embedding hosts). In Node.js on the main thread it works correctly, and this CLI is Node.js-only — so this is not a current bug. If the codebase ever gets an MCP server wrapper or is embedded in another runtime, sleepSync will silently become a busy-spin (lock acquisition retries without sleeping, spiking CPU). A short comment noting the Node.js main-thread assumption would help reviewers:

// Node.js main thread only — Atomics.wait blocks here but returns 'not-equal'
// without sleeping in Worker threads or non-Node runtimes.
function sleepSync(ms) { … }

---

Token usage: 24,592 input, 5,647 output, 1,168,813 cache read, 82,776 cache write | Usage Guide

New pushes are reviewed automatically with a 10-minute cooldown between reviews. To request a review at any time, comment @nansen-pr-reviewer re-review.

[aikido-pr-checks]

Potential file inclusion attack via reading file - high severity
If an attacker can control the input leading into the ReadFile function, they might be able to read sensitive files and launch further attacks with that information.

Show fix

Remediation: Ignore this issue only after you've verified or sanitized the input going into this function. This issue is only relevant in the backend, not in the frontend!

_{Reply @AikidoSec ignore: [REASON] to ignore this issue.
More info}

[kome12]

@AikidoSec ignore: path is derived solely from $HOME + UTC date; no attacker-controllable input; local CLI.

[aikido-pr-checks]

✅ Based on your feedback, we ignored this issue because of the following reason:

path is derived solely from $HOME + UTC date; no attacker-controllable input; local CLI.

[aikido-pr-checks]

Potential file inclusion attack via reading file - high severity
If an attacker can control the input leading into the ReadFile function, they might be able to read sensitive files and launch further attacks with that information.

Show fix

Remediation: Ignore this issue only after you've verified or sanitized the input going into this function. This issue is only relevant in the backend, not in the frontend!

_{Reply @AikidoSec ignore: [REASON] to ignore this issue.
More info}

[kome12]

@AikidoSec ignore: false positive. This path is local CLI state under the current user HOME/USERPROFILE (~/.nansen/x402), not remote/API-controlled input. If an attacker can control HOME for the process, they already control where this CLI stores local state; no privilege boundary or backend file inclusion is involved.

[aikido-pr-checks]

✅ Based on your feedback, we ignored this issue because of the following reason:

false positive. This path is local CLI state under the current user HOME/USERPROFILE (~/.nansen/x402), not remote/API-controlled input. If an attacker can control HOME for the process, they already control where this CLI stores local state; no privilege boundary or backend file inclusion is involved.

[nansen-pr-reviewer]

nansen-pr-reviewer summary

The change adds cumulative daily/session x402 caps, reservations, audit logging, and fail-closed ledger handling. The malformed-ledger issue from the earlier review is addressed and covered by shape-validation tests. Two edge cases remain around audit persistence and releasing reservations when local payment recording fails.

Findings by Severity

Severity	Count
🟡 Medium	2

Deterministic check: success — Found 2 finding(s) within acceptable thresholds

Risk: 4/5 (High) — raised by: dependency/lockfile change; complexity: 2743 added lines

---

Token usage: 80,553 input, 3,642 output, 122,987 cache read | Usage Guide

Cooldown: for the next 10 minutes (counting from when this review finished), new pushes to this PR will not trigger another review — the next push after the window expires will. Need a fresh review sooner? Comment @nansen-pr-reviewer[bot] re-review.

[nansen-pr-reviewer]

🟡 - Medium | Local wallet reservations can leak when recording the signed payment throws

The local-wallet path reserves budget before signing, but recordPaymentAttempt is called outside the try/catch that releases the reservation. If recording throws after the payment payload has been built—for example, if an unexpected ledger-path or timestamp error occurs—the outer generator catches the error as an ordinary option failure and proceeds without calling releasePaymentReservation. The reservation then holds daily/session budget until its TTL, causing subsequent valid payments to be refused.

[nansen-pr-reviewer]

🟡 - Medium | Audit-log write failures are silently ignored despite the documented audit guarantee

The implementation deliberately suppresses all failures while writing the initial audit record. A permissions error, disk-full condition, or unavailable home directory can therefore allow a signed/transmitted payment to proceed without a payments.jsonl record, contradicting the documented guarantee that every signed attempt is recorded and making reconciliation against the accounting-failure flow incomplete. The spend ledger may still be updated, but the operator has no reliable audit entry for that payment.