feat(auth): implement SEP-10 wallet authentication (#778)

[ogbemercyada-sketch]

Summary

Replaces ad-hoc x-stellar-signature header trust on protected routes with a proper SEP-10
Stellar Web Authentication (https://stellar.org/protocol/sep-10) challenge-response flow backed
by short-lived JWTs.

What changed

New endpoints

┌────────┬───────────────────────────┬─────────────────────────────────────────────────────┐
│ Method │ Path │ Description │
├────────┼───────────────────────────┼─────────────────────────────────────────────────────┤
│ GET │ /api/auth/challenge?accou │ Issues a signed SEP-10 challenge transaction the │
│ │ nt=G... │ wallet must sign │
├────────┼───────────────────────────┼─────────────────────────────────────────────────────┤
│ POST │ /api/auth/verify │ Verifies the signed challenge and returns a JWT │
└────────┴───────────────────────────┴─────────────────────────────────────────────────────┘

New files

┌────────────────────────────────────────┬──────────────────────────────────────────────────┐
│ File │ Purpose │
├────────────────────────────────────────┼──────────────────────────────────────────────────┤
│ backend/src/services/sep10Auth.ts │ Core SEP-10 service — challenge build/verify, │
│ │ HMAC-SHA256 JWT (no external deps) │
├────────────────────────────────────────┼──────────────────────────────────────────────────┤
│ backend/src/routes/auth.ts │ Express router for GET /api/auth/challenge and │
│ │ POST /api/auth/verify │
├────────────────────────────────────────┼──────────────────────────────────────────────────┤
│ backend/src/middleware/sep10Session.ts │ requireSep10Auth() middleware — validates │
│ │ Authorization: Bearer │
└────────────────────────────────────────┴──────────────────────────────────────────────────┘

Modified files

• backend/src/app.ts — mounts /api/auth; replaces all six
  createStellarSignatureAuthMiddleware() calls (release, refund, cancel, dispute, notes,
  extend-deadline) with requireSep10Auth()
• backend/test/authMiddleware.test.ts — updated release/refund tests to use Bearer JWT auth
• backend/.env.example — documents SERVER_SIGNING_SECRET, JWT_SECRET, HOME_DOMAIN,
  WEB_AUTH_DOMAIN

Authentication flow

1. GET /api/auth/challenge?account=GABC...
   ← { transaction: "", network_passphrase: "..." }

2. Client signs the transaction with its wallet keypair

3. POST /api/auth/verify { transaction: "", account: "GABC..." }
   ← { token: "", account: "GABC..." }

4. Protected route:
   Authorization: Bearer

Security properties

• Expired challenges — rejected via WebAuth.readChallengeTx time-bound check
• Replayed challenges — rejected via SHA-256 nonce cache (TTL = 2× challenge window)
• Wrong-key signatures — rejected by WebAuth.verifyChallengeTxSigners
• JWT tampering — rejected via timing-safe HMAC-SHA256 comparison
• JWT expiry — 24 h TTL, enforced on every request

Environment variables

SERVER_SIGNING_SECRET=S... # Stellar secret key for signing challenges (required in prod)
JWT_SECRET=... # HMAC secret for JWT signing (derived from SERVER_SIGNING_SECRET
if unset)
HOME_DOMAIN=your-domain.com # Appears in SEP-10 ManageData operation keys
WEB_AUTH_DOMAIN=... # Defaults to HOME_DOMAIN

Testing

• 27 new tests in test/sep10Auth.test.ts covering: challenge build, verify, expired, replayed,
  wrong-key, JWT round-trip, tamper, expiry, all HTTP endpoints, and the full end-to-end flow
• Updated test/authMiddleware.test.ts — 7/7 passing with new SEP-10 JWT auth

npm test

Closes

Closes #778

[vercel]

@ogbemercyada-sketch is attempting to deploy a commit to the ritik4ever's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@ogbemercyada-sketch Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits