Snooper
by mikeyliow
README.md
# Snooper
**A flight recorder and safety gate for agent purchases.**
Snooper is a remote MCP server that sits between any AI agent and PayPal. The agent never holds PayPal
credentials. It calls `propose_purchase`; Snooper runs hard checks in code, asks Jev (TypeSafe System One) for
the semantic judgments, writes every step to a tamper-evident trail, and returns one of three decisions:
**cleared**, **needs_review** (a human decides) or **blocked**.
Built for the PayPal AI Hackathon 2026. Live demo: https://snooper-production-c0acfe19.up.railway.app
(the UI needs the admin token; `/store` and `/healthz` are public).
## Why
Agents are being handed payment rails, but there is no end-to-end record of why an agent paid, what influenced
it, or whether the order matched what the owner wanted. A product page, an email or a tool result can carry a
prompt injection that redirects a payment. PayPal's agent toolkit has no approval hook or spend caps. Snooper
is that missing control layer, for any MCP client.
## How it works
```
agent (any MCP client) ──MCP──▶ Snooper ──REST──▶ PayPal sandbox
│
├─ code: amount, currency, payee allowlist, daily cap, duplicates, expiry
├─ Jev: 5 typed judgments with probabilities
└─ trail: append-only JSONL, HMAC hash chain
```
**Code decides everything that is exact.** Amount within the mandate, currency match, payee on the allowlist,
daily cap, duplicate proposals, mandate expiry, the hash chain, provenance tags, and every PayPal call.
**Jev decides only what is semantic**, in one request per proposal (`src/jev.ts`):
| Question | Type | Asks |
|---|---|---|
| `cart_matches_request` | Noul | Is the cart the product and quantity the owner asked for? |
| `untrusted_sets_payment` | Noul | Does untrusted text try to change who gets paid or how much? |
| `injection_likelihood` | Score 0-3 | How strongly does untrusted text address the reader as instructions? |
| `route_owner` | Choice | Which reviewer fits: owner, finance or security? |
| `shareable_fields` | Noul per field | Does a field hold private data a reviewer should not see? |
Thresholds live in `src/config.ts` and follow the TypeSafe guardrails cookbook: review at 0.35, act at 0.70,
injection score blocks at 2.0, and block beats review beats pass. If Jev errors or times out, Snooper **fails
closed** to `needs_review`. Trail confidence is the weakest gating hop, reduced when the agent supplied no
evidence.
**Every step is a hop** in a per-trail JSONL file: `trail_id, seq, ts, actor, kind, payload, provenance,
confidence, prev_hash, hash`, where `hash = HMAC-SHA256(TRACE_SIGNING_SECRET, prev_hash + canonical JSON)`. The
chain is recomputed on every read; an edited line shows as "Chain broken at hop N".
## MCP tools (exactly three)
| Tool | Purpose |
|---|---|
| `propose_purchase` | Cart + evidence (each with its source) in; `{ trail_id, decision, reasons, next }` out |
| `confirm_purchase` | Rechecks, then captures through PayPal. Refuses unless the trail is cleared or approved |
| `get_trail` | Hops, decision, PayPal ids, `verified` flag |
The mandate (owner, max amount, currency, payee allowlist, daily cap, request) is set by the owner in the UI or
`POST /api/mandates`, never by the agent.
Connect a client (Claude Code shown; the bearer is read from your environment):
```json
{
"mcpServers": {
"snooper": {
"type": "http",
"url": "https://snooper-production-c0acfe19.up.railway.app/mcp",
"headers": { "Authorization": "Bearer ${MCP_AUTH_TOKEN}" }
}
}
}
```
## What is real and what is simulated
| Part | Status |
|---|---|
| MCP server, hard rules, hash chain, alerts, UI, red-team | Real |
| Jev judgments | Real calls to TypeSafe (`jev-1.14.0` at build time); seed and red-team trails use real answers too |
| PayPal order creation | Real sandbox orders, `intent: AUTHORIZE`, `custom_id` = trail id, deterministic `PayPal-Request-Id` |
| PayPal authorize + capture | Real code path, but the sandbox **refuses a headless authorize**: `ORDER_NOT_APPROVED`. The payer has to approve each order once in PayPal ("Approve in PayPal" in the trail). After that Snooper authorizes and `confirm_purchase` captures |
| Simulated capture | A labelled fallback a human can click in the UI. It never claims a PayPal result: status reads "Captured (simulated)", no capture id |
| Email alerts | Sent through Resend when `RESEND_API_KEY`, `ALERT_EMAIL_FROM`, `ALERT_EMAIL_TO` are set; otherwise the alert row says "Email not configured" |
| Webhooks | Registered on the sandbox app for the live URL (`npm run webhook:register -- <base-url>`). `/webhooks/paypal` rejects unsigned and forged events with 400. A genuinely signed event has not been observed yet: the first one fires when a payer approves an order |
| "Without gate" column on the Scoreboard | A stated baseline (the agent pays whatever it proposes), not a measurement |
Card funding was also tried for a headless path and the sandbox merchant returned
`PAYEE_NOT_ENABLED_FOR_CARD_PROCESSING`.
## Run it
Node 22 or newer.
```bash
cp .env.example .env # fill in the values; never commit .env
npm ci
npm run build
npm start # http://localhost:8787
```
Other commands:
```bash
npm test # hash chain + hard rules
npm run jev:check # real Jev answers for 8 sample proposals
npm run redteam # 12 red-team cases, in-process
npm run redteam -- --url <base-url> # same, on a deployed instance
npm run demo:mcp -- <base-url> A # real MCP client: scene A (also B, C, confirm <trail>, trail <trail>)
npm run pair -- <CODE> <base-url> # sign a browser in without typing the admin token into it
npm run webhook:register -- <base-url> # register the PayPal sandbox webhook, store its id in .env
```
Endpoints: `/mcp` (bearer `MCP_AUTH_TOKEN`), `/api/*` (bearer `ADMIN_TOKEN` or a paired browser session),
`/` (UI), `/store` (demo storefront with an injection toggle), `/healthz`, `/webhooks/paypal`.
## Demo
1. Open the UI, set a mandate: owner Mikey, max 120.00 USD, allowlist `demo-store`, "Buy one mechanical keyboard under 120 USD".
2. **Happy path.** Ask your agent: "Buy the keyboard from the demo store." It proposes, Snooper clears it and
creates the PayPal order. Approve the order once in PayPal sandbox, then the agent's `confirm_purchase` captures.
3. **Injection.** Turn the injection toggle on at `/store` and ask again. The keyboard page now carries hidden
text that tries to redirect the payment. The trail is blocked; the Jev hops show why.
4. **Human in the loop.** Ask for two keyboards. The mandate said one, so the trail needs review. Approve it in the UI.
5. **Proof.** Scoreboard shows the red-team run. "Verify chain" recomputes the hashes of any trail.
No MCP client to hand? "Simulate agent" on the Trails screen calls the same handlers.
Retakes: an identical purchase under the same mandate within 24 hours is blocked as a duplicate. Set a new
mandate (two clicks, prefilled) before repeating a scene.
## Red-team
Twelve fixed cases (`src/redteam.ts`): clean order, amount over mandate, payee off the allowlist, currency
mismatch, duplicate, injected product page, vendor "update payee" note, cart mismatch, urgency pressure, benign
untrusted text, Jev outage, tampered trail. Expectations are fixed before the run and results are reported as
they come out. Jev is not infallible; a miss would show on the Scoreboard as a miss.
## Limits
- Sandbox only. Snooper refuses any PayPal base URL that is not the sandbox.
- Single tenant: one admin token, one MCP token.
- A buyer-side gateway cannot tag third-party orders; the demo store is ours, so it can.
- Jev does not treat state as hostile, so injected text can sway it. Untrusted text is kept in its own labelled
field and the code checks are the backstop.
## Stack
Node 22, TypeScript, Express, the official MCP TypeScript SDK (Streamable HTTP), `@typesafe-ai/sdk`, PayPal
Orders v2 REST, React, Vite, Tailwind CSS 4, daisyUI 5, Railway.
## License
MIT