Security diagrams
Visual flows for app service-auth, buyer assertions, webhook signing, QR verification, and public/private data boundaries.
Compatible with the closed-beta ATM app APIs and versioned ATM event headers. Check atm-api-version on every webhook or XRPC receiver event.
App service-auth
- 01
App server chooses method
Use the exact XRPC NSID as lxm.
- 02
App mints service-auth
Issuer is the app DID; audience is the ATM service.
- 03
ATM verifies token
Check issuer, audience, lxm, expiry, signature, and replay jti.
- 04
ATM executes scoped action
Only for the app, environment, and module allowed.
Buyer assertion
- 01
Buyer is signed into app
The app has user presence without forcing checkout re-auth.
- 02
App requests short assertion
Issuer is buyer DID and lxm is the buyer assertion method.
- 03
App includes assertion
ATM receives payer DID plus assertion in private envelope.
- 04
ATM stores verification metadata
Do not store raw assertion JWT in public records.
Webhook signing
- 01
ATM creates event
Event includes id, delivery id, environment, type, app DID, and data.
- 02
ATM signs raw body
Use the app environment signing secret.
- 03
App verifies before parsing
Raw bytes must match the signature.
- 04
App deduplicates
Store delivery id before fulfillment.
QR verification
- 01
Pass contains opaque token
No DID, email, ticket id, payment id, or processor id.
- 02
Scanner submits token
Scanner calls verifyTicket or checkInTicket.
- 03
Tickets checks private state
Token hash, status, void/refund state, and check-in list.
- 04
Check-in is idempotent
Repeat scans return existing entry state.
Public and private data
| Public protocol | Safe catalog refs, public event refs, final amount/currency facts, and proof refs. |
|---|---|
| Private ATM | Checkout sessions, customer contact, processor ids, QR tokens, holds, issued-ticket state, ticket delivery attempts, scanner grants, and webhook logs. |
| Private app | Fulfillment details, buyer messages, downloads, shipping, event UX, and app-local analytics. |