feat(auth): SEP-10 challenge auth with short-lived EdDSA JWTs

[benedictworks-home]

Summary

Implements #442: SEP-10-style challenge authentication for solver bots, plus short-lived EdDSA (Ed25519) session JWTs — so bots no longer need a long-lived shared secret to reach the WebSocket feed and guarded REST endpoints.

What's new

• GET /api/v1/auth/challenge?account=G... — issues a server-signed SEP-10 challenge bound to this deployment: <home-domain> auth manageData op (single-use 48-byte nonce, source = client account), web_auth_domain op, 5-minute timebounds.
• POST /api/v1/auth/token — exchanges the client-signed challenge for a 15-minute JWT with sub (G-address) and role (admin > solver > user) claims.
  • Verification uses the SDK's readChallengeTx + verifyChallengeTxThreshold against Horizon signers/thresholds — multisig-aware (weight ≥ max(1, thresholds.medium)), so accounts whose thresholds are all zero still must prove key possession.
  • The nonce is consumed atomically and only after signatures verify: challenges are strictly single-use (replay rejected), but a failed exchange (bad signature / unmet threshold) never burns a legitimate challenge.
  • Client accounts must exist on the network (unfunded/pre-authorized SEP-10 path is out of scope).
• Single-use nonce store: process-local memory by default; SEP10_NONCE_STORE=redis uses Redis with a Lua GET+DEL so concurrent exchanges across replicas can only succeed once (required for multi-replica deployments).
• WebSocket gateway (intents.gateway.ts): authenticateJwt tries the EdDSA token first, then falls back to legacy HS256 (AUTH_JWT_SECRET). Works via handshake (?token= / Authorization: Bearer) and first message ({"type":"auth","token":"..."}) — both paths already existed; no protocol change.
• SolverJwtGuard: same EdDSA-first + HS256 fallback, so [High] Scoped Solver API Credentials with Rotation and Revocation #443's credential endpoints accept SEP-10 tokens.
• Key material (src/auth/sep10/sep10-keys.ts): challenge signing reuses the existing STELLAR_SIGNER_SECRET_KEY; JWTs are signed with SEP10_JWT_SIGNING_KEY (Ed25519 PKCS#8 — PEM, literal-\n PEM, or base64 DER; must be distinct from the Soroban signer key). Empty values generate ephemeral dev-only keys with a loud warning; invalid non-empty values fail at boot.

New environment variables

Var	Default	Notes
SEP10_HOME_DOMAIN	localhost	Home domain + web_auth_domain in challenges; set to the real API domain in production
SEP10_JWT_SIGNING_KEY	(empty)	Required when NODE_ENV=production; openssl genpkey -algorithm ed25519
SEP10_ADMIN_ACCOUNTS	(empty)	Comma-separated G-addresses issued role=admin
SEP10_NONCE_STORE	memory	redis for multi-replica replay protection

Added to src/config/env.validation.ts and all four .env*.example files (keeps check:env-drift green).

Files

• New: src/auth/sep10/ (keys, nonce store, Horizon account loader, DTOs, service, controller, module) + tests
• Modified: src/common/jwt.ts (EdDSA sign/verify/key-loading helpers), src/intents/intents.gateway.ts, src/auth/solver-credentials/solver-jwt.guard.ts, src/app.module.ts, config (configuration.ts / env.validation.ts / env examples), docs/solver-onboarding.md (new §2a with the curl flow), e2e SDK mock (WebAuth re-export)

Verification

• Tests written (run in CI): src/auth/sep10/sep10.service.spec.ts — challenge conformance against the real SDK, roles, multisig threshold (incl. "failed attempt doesn't burn the nonce"), replay, never-issued nonce, expiry via fake timers, wrong home domain, unknown account, plus JWT-helper and key-material edge cases; src/auth/solver-credentials/solver-jwt.guard.spec.ts — EdDSA acceptance/expiry/foreign-key, HS256 fallback, extraction, subject match.
• Local checks run on merge commit e815544 (Node 24, Windows): tsc --noEmit clean; eslint src test scripts packages … 0 errors (144 warnings, same baseline as main); check:env-drift pass; check:quarantine pass; check:migrations --base c48de27 pass (3 changed migrations, no unsafe DDL, every one has down.sql); jest --config scripts/jest.config.js pass; full unit suite in 4 shards (--shard=n/4 --maxWorkers=3): 1746 passed, 97 skipped, 0 failed.
• Not run locally: docker-based jobs, psql-backed integration tests, gitleaks, semgrep, and coverage upload (no docker/psql in this environment) — CI is the authority for those.

Merge with upstream/main (e815544)

The branch merges upstream main at c48de27. That tree itself ships ~10 parse-broken files (leaderboard-query.ts, in-memory-intents.repository.spec.ts, intents.types.ts, list-intents.dto.ts, configuration.ts, env.validation.ts, stats.service.ts, intents.controller.ts, intents.gateway.ts, intents.module.ts, stellar-signature.ts) plus 14 zero-byte files (incl. .github/workflows/ci.yml, src/soroban/soroban.service.ts, src/treasury/treasury.service.ts), so conflicts were resolved conservatively:

• Files this PR does not own are taken from 2a922ee — the simulation-harness tree from feat(tools): solver simulation harness and strategy backtesting tool #575, which is c48de27 plus those torn/empty files repaired (independently verified green: tsc, eslint, 1746 passing unit tests).
• Files [High] SEP-10-Style Challenge Authentication for Solvers with Short-Lived JWTs #442 owns (src/auth/sep10/, solver-jwt.guard, common/jwt.ts, config/env/docs, app.module.ts) keep the branch content merged with main's additions. intents.gateway.ts is rebased onto the harness gateway and only [High] SEP-10-Style Challenge Authentication for Solvers with Short-Lived JWTs #442's own delta (+17/−3: the SEP-10 EdDSA public key, EdDSA-first verification, and the WS handshake JWT paths documented in docs/solver-onboarding.md) is re-applied on top.
• prisma/schema.prisma = harness schema + main's @@index([solver]).
• .env.example also picks up the solver-reputation ([High] Solver Reputation Score v2 with Time Decay and Transparency #444) variables so check:env-drift stays green.
• package.json / package-lock.json are byte-identical to the feat(tools): solver simulation harness and strategy backtesting tool #575 tree — this PR adds no dependency of its own and the lockfile is not hand-edited (the @aws-sdk/client-s3 entry present in it originates from feat(tools): solver simulation harness and strategy backtesting tool #575).

Fixes made during verification:

• common/jwt.ts: Ed25519 private keys now load from DER directly — the previous PEM re-wrap emitted a double newline that OpenSSL 3 rejects (DECODER routines::unsupported).
• env.validation.spec.ts: the production fixture now carries SEP10_JWT_SIGNING_KEY (required in production since [High] SEP-10-Style Challenge Authentication for Solvers with Short-Lived JWTs #442).

(The two fix: commits 055a25d/16e86d0 that the branch started with remain in history; after the merge, shared files follow the repaired 2a922ee content.)

Assumptions

• Client accounts must already exist on the network; the SEP-10 unfunded-account path is out of scope.
• Threshold choice: max(1, account.thresholds.medium) — medium is the ecosystem norm, floored at 1 so all-zero-threshold accounts still need one valid signature.
• Challenge signing key reuses the existing (until now unconsumed) STELLAR_SIGNER_SECRET_KEY; the JWT key is a separate new Ed25519 key.
• Signed-message endpoints (accept/fill canonical signatures) are untouched; user wallet login UX remains out of scope.

Checklist

• Tests written for new behaviour
• TSDoc on public APIs
• docs/solver-onboarding.md updated
• New env vars in env.validation.ts + every .env*.example
• Local parse / duplicate-binding / env-drift checks clean
• npm run lint / typecheck / test run locally — tsc clean, eslint 0 errors, 1746 unit tests green on the merge commit
• docker / psql / gitleaks / semgrep / coverage jobs — not runnable in this environment; CI is the authority

Closes #442