Inspiration

Every "agentic commerce" demo has the same quiet assumption: the agent is on your side. It isn't. It's on the side of whatever it read last.

A shopping agent spends its day reading pages written by strangers: listings, reviews, seller notes. So I wrote some of those pages. A fake SYSTEM: line inside a five-star review. Zero-width characters hiding an instruction. A store called amaz0n.com. A note that says the user "pre-approved three units". Then I gave a live AI agent a real PayPal sandbox wallet and let it shop.

It fell for 4 of 18 attacks on its own. In my full 21-attack red team it moved $1,398.13 in real sandbox captures. A captured payment doesn't come back because the model said sorry.

So I stopped asking "how do I make the agent smarter?" and asked a better question:

What if the agent could be fooled, and your money still couldn't?

Built solo. One person, no team: every line of the backend, the PayPal lifecycle, the security model, the red team, the console and the demo video. A team of one has no room for hand-waving, so every claim here has a receipt in the repo.

What it does

Chaperone sits between an AI agent and your PayPal wallet. The agent keeps every useful power (search, compare, open listings, propose a buy) and loses the one that matters: it can never move money.

1. You sign a mandate once. One sentence ("Buy me one 65W USB-C charger, under $50") becomes hard, typed limits: per-purchase cap, total budget, units, must-have specs, max % over market, blocked sellers, velocity, expiry. You approve your PayPal wallet once through Vault v3, and the agent never sees a card.

2. Every proposal runs a five-layer gate. In a real block from the sandbox, three independent layers failed the same fake charger in 776 ms:

  • Signed limits, in plain code. Budget, caps, quantity, specs (stemmed and negation-aware, so "not noise-cancelling" doesn't pass for "noise-cancelling"), plus lookalike-merchant detection. Caught 8 of 21 red-team attacks.
  • Channel3 as ground truth. GET /v1/products/{id} says which retailers really sell this product and at what price; /v0/price-tracking/history/{id} gives 90 days of prices. Not a listed retailer → fail. Far above the 90-day high → fail. Suspiciously far below the low → warn (bait). Caught 2, including amaz0n.com selling a real product.
  • Injection scanner. Deterministic fingerprints for hidden Unicode, fake system/assistant role markers, lookalike domains and swapped payees. Caught 7.
  • Quarantined reader (AI #1). The only model that sees attacker-controlled text. It may answer typed yes/no flags and nothing else. Its "yes" can hold a purchase for you, but can never pass one: a requirement only passes if plain code finds it stated in the page text.
  • Privileged auditor (AI #2). Judges the purchase against your words, from facts the code extracted. It never sees the page. Caught 1.

That's the dual-LLM pattern done strictly: the model that reads the attacker has no authority, and the model with authority never reads the attacker. Gemini leads; when it times out or runs out of quota, Amazon Nova on Bedrock answers the same structured call; if both are down, nothing gets waved through. The gate fails closed and asks you.

3. Even a "yes" isn't payment. An approved purchase becomes Orders v2 intent=AUTHORIZE on the vaulted token. The money is held, not taken.

4. The seller is paid only when you confirm the right item arrived.

  • Right item → capture, attach tracking, pay the seller via Payouts.
  • Wrong item → void. Nothing charged.
  • Units missing → final partial capture; the rest is released.
  • Problem later → refund, and partial refunds add up but can never exceed what was captured.

The delivery check uses AI vision on your photo (only a fingerprint is kept). A seller or carrier saying "delivered" can only hold the money. Only you can release it. In the red team, three attacks slipped past the gate and still walked away with $0: voided, partially captured, held.

5. The agent can't promote itself. Its API key gets HTTP 403 on approve, confirm-delivery, refund, payout retry and signing mandates. Those need the human's HMAC-signed session plus a WebAuthn passkey check from the last 10 minutes. An agent can call every endpoint the console calls; it can't make your Touch ID sign.

$$ \text{money moves} \iff \text{gate passes} \;\land\; \text{PayPal holds it} \;\land\; \text{a human with a passkey says so} $$

And it's a product, not a script. A live control room streams every PayPal REST call, AI call and Channel3 search over server-sent events. You can rob the agent yourself in the Arena (same agent, same poisoned results, two lanes, real captures on the left), drag a what-if slider that re-runs the real gate on any purchase, open hash-chained receipts your browser re-verifies, and plug any agent in over MCP.

How I built it

Backend: Node 22 + TypeScript, Hono, zod everywhere. A per-mandate state machine with locks (no double-spend from parallel proposals), and a SHA-256 hash chain over every purchase's timeline. Edit or drop one event and verification fails, in your browser.

PayPal, used as a money-safety system rather than a checkout button:

  • Vault v3: setup token → payment token → vault_id with stored-credential flags.
  • Orders v2 AUTHORIZE, then Authorizations: capture (incl. final_capture partials), void, and reauthorize once PayPal's 3-day honor period has passed. A background sweep voids authorizations that lapse with nobody confirming, so nothing sits "held" forever.
  • Captures: refund, with one PayPal-Request-Id per refund (ref-{purchase}-{n}) and a cap at captured minus refunded.
  • Shipment tracking on capture, Payouts to the seller (a failed payout can be retried with the same request id, so it can never pay twice), Transaction Search for a ledger view.
  • Webhooks verified with verify-webhook-signature before anything changes, deduped by event id. A refund or void made outside Chaperone (PayPal dashboard, a dispute) is mirrored onto the timeline; Chaperone's own refunds aren't double-counted.
  • Every mutating call is idempotent via PayPal-Request-Id. A retry never charges twice.

AI: @google/genai for function calling (the shopper), structured JSON (reader + auditor) and vision (delivery). Amazon Nova via the Bedrock Converse API with a forced tool call to get the same strict JSON. A quota-aware switch puts Nova first for 10 minutes after Gemini reports quota exhaustion, instead of paying for a failed call every time.

Channel3: search for the agent; product detail and 90-day price history as catalog truth inside the gate; "buy the real one instead" proposes the same product from a listed retailer, and it still goes through the whole gate.

Security: agent-scoped key vs HMAC-signed HttpOnly; SameSite=Lax human cookie, same-origin checks on every human action, WebAuthn step-up (@simplewebauthn, user verification required), rate limits per IP and session and globally (so no single visitor burns the shared AI quota), strict CSP with no third-party scripts, frame-ancestors 'none', HSTS.

Frontend: React 19 + Vite + Motion. A system map where each real purchase pulses through the layers it hit, a trace waterfall with per-layer milliseconds, a money-flow chart, provider health, a ⌘K command palette and a guided tour, all live over SSE. No mock data anywhere on screen.

MCP: list_mandates, search_products, propose_purchase, purchase_status. There is deliberately no tool to approve, confirm or refund.

Tested like I meant it: 148 tests, including agent-403s on every money route, forged cookies, cross-origin requests, spoofed X-Forwarded-For against the rate limiter, unsigned webhooks, a fooled reader that says "yes" to everything, reauthorization, expiry sweeps, refund caps and payout retries.

Challenges I ran into

  • My own gate was robbing honest shoppers. Against real Channel3 data, specs hide in bullet points ("Noise cancellation" vs "noise-cancelling", "65W" only in key features, "20,000 mAh"). I added stemming and negation-aware matching, a regression test per case, and then took the AI reader's power to pass anything away entirely.
  • Agents narrate wrong. The agent told users "purchased" when the money was only held. Now the final status line is written from the purchase state machine, never from the model.
  • The AI quota wall. Free-tier Gemini ran dry mid-run, so I wired in Amazon Nova as a real backup. During my recorded vaulted purchase, Gemini was over quota and Nova answered every AI step, unannounced.
  • Money is all edge cases. Honor periods vs expiry, partial captures, refunds that add up, payouts that fail after a successful capture, webhooks echoing my own refunds. Each one became code plus a test.

Accomplishments that I'm proud of

  • Red team, real PayPal sandbox: agent alone −$1,398.13. Through Chaperone $0.00: 18 blocked at the gate, 3 caught at delivery, and all 4 honest purchases still went through.
  • Held-out round: a separate model invented 20 brand-new attacks after the gate was frozen. 19 blocked, 1 held for a human, 0 got money past the gate.
  • One honest purchase, end to end, on a real vaulted wallet: wallet approved in PayPal → agent found a StarTech 65W charger on newegg.com via Channel3 → gate passed → authorized on the vault_id → captured on delivery with tracking → seller paid by Payouts → $8 partial refund. Eight PayPal APIs, one purchase, every ID in the repo.
  • A live webhook, signature-verified against PayPal and mirrored onto a receipt.
  • Every number above has a receipt in docs/receipts, and every capture ID is real.

What I learned

You can't patch your way to a gate that catches everything. A new attack will eventually get through. What makes agent payments safe isn't how clever the filter is. It's where the money sits. If it waits in PayPal until a human confirms delivery, even a successful attack can be undone. PayPal's authorize-then-capture model is basically an undo button for agentic commerce, and nobody was using it that way.

Second lesson: give the AI a job, not authority. The moment the model that reads untrusted text can't approve anything, prompt injection stops being a money problem.

What's next for Chaperone

  • PayPal Multiparty with delayed disbursement, so the capture belongs to the onboarded seller and the buyer keeps PayPal Purchase Protection end to end. (Today the platform account captures and pays out; I document that honestly in the README.)
  • PayPal Log In bound to the passkey step-up, replacing the demo's per-browser session.
  • Carrier APIs as delivery evidence next to the buyer's photo.
  • A drop-in SDK + MCP package, so any agent framework gets this protection with one import.

Chaperone. Your agent can be fooled. Your money can't.

Built With

Share this project:

Updates

Submission history