[S11] WebAuthn hardening, tests and hybrid auth documentation #33

S11 — WebAuthn hardening, tests and hybrid auth documentation

Executive summary

This deliverable consolidates 3 atomic server tasks into one sprint-sized ticket for WebAuthn hardening, tests and hybrid auth documentation.
Success means: WebAuthn production-ready.

Product context

Ding Payments is a self-custodial Stellar P2P app: the server validates NFC payment requests, enforces hybrid Supabase + WebAuthn authorization, relays signed XDR to Horizon, and indexes history.

User stories

• As a developer, I want S11 complete so I can run the next ETA without manual archaeology.
• As a receiver, I want my NFC payment request validated consistently with the canonical contract.
• As a sender, I want clear API errors when a payment request is malformed or expired.
• As an operator, I want migrations, health checks, and logs sufficient to debug testnet payments.

Prerequisites

• Deliverable S10 merged and deployed to dev
• Node 20+, npm, Supabase project credentials, Postgres reachable via DATABASE_URL
• Read Sections 3–6 of server-build-plan.md before coding

Atomic sub-task checklist

Scope — In

• All atomic tasks SRV-046, SRV-047, SRV-048 as specified in server-build-plan.md
• NestJS 11 patterns: modules, providers, DTOs with class-validator, Swagger decorators where applicable
• Unit and/or E2E tests for new behavior; keep CI green (ci-server.yml)
• Production-quality code under ding-server/src/ for S11

Scope — Out

• Client UI or Expo changes (ding-payments repo)
• Mainnet launch configuration (testnet MVP only unless explicitly toggled)
• Push notifications on payment confirmation (post-MVP P3)
• Custodial wallets or server-side key storage
• Features not listed in atomic SRV IDs for this deliverable

Architecture & conventions

Target architecture from server-build-plan.md Section 3: flat src/modules/* layout, ConfigModule validation, global exception filter, URI versioning /v1.

ding-server/
├── src/
│   ├── main.ts
│   ├── app.module.ts
│   ├── config/
│   ├── common/filters/
│   ├── database/
│   ├── auth/
│   ├── supabase/
│   ├── stellar/
│   ├── webauthn/
│   ├── contracts/
│   └── modules/
│       ├── users/
│       ├── payment-requests/
│       ├── payments/
│       └── transactions/
├── prisma/schema.prisma
├── docs/
└── test/

Files to create/modify

• ding-server/src/
• See server-build-plan.md atomic files for SRV-046
• See server-build-plan.md atomic files for SRV-047
• See server-build-plan.md atomic files for SRV-048

Implementation guide

1. Implement SRV-046 — Per-device credentials policy; cross-check Section 8 in server-build-plan.md for files and snippets.
2. Implement SRV-047 — WebAuthn tests with mocks; cross-check Section 8 in server-build-plan.md for files and snippets.
3. Implement SRV-048 — Document hybrid auth flow in ARCHITECTURE; cross-check Section 8 in server-build-plan.md for files and snippets.
4. Run npm run lint and fix any new violations.
5. Run targeted unit tests for the module(s) touched.
6. Run npm run test:e2e when HTTP surface changed.
7. Update Swagger decorators if routes or DTOs changed.
8. Verify error responses use { statusCode, message, code?, errors? } shape from Section 5.
9. Document any new env vars in .env.example and README.
10. Manual smoke test with npm run start:dev and curl/httpie against /v1 routes.

Acceptance criteria

• SRV-046 — Per-device credentials policy: acceptance criteria in server-build-plan.md satisfied
• SRV-047 — WebAuthn tests with mocks: acceptance criteria in server-build-plan.md satisfied
• SRV-048 — Document hybrid auth flow in ARCHITECTURE: acceptance criteria in server-build-plan.md satisfied
• CI workflow passes lint, build, and test jobs
• No secrets committed; .env gitignored
• OpenAPI/Swagger reflects new or changed endpoints
• Prisma client regenerated if schema changed (npm run prisma:generate)
• Database migration applied locally without drift
• Error codes align with Appendix A where applicable
• Logs do not print JWTs, XDR secrets, or service role keys
• Code review checklist: DTO validation, auth guard, idempotency where required
• README or docs updated when setup steps change
• Definition of done checklist below is complete

Test plan

• Unit: Services, validators, and state machine pure functions for S11
• Integration: Prisma against local Postgres or test container for repositories
• E2E: Supertest against Nest app with JWT mock and Stellar SDK mocks
• Contract: payment-request.v1 golden vectors (S08+) — invalid BTC/ETH assets rejected
• Manual: curl examples from Section 5 and Appendices
• Regression: Re-run auth suite when touching guards (S06/S07)
• Performance: Smoke load on validate when approaching S20

Client coordination

See Client ↔ server alignment table below.

Security notes

• Never log SUPABASE_JWT_SECRET, SUPABASE_SERVICE_ROLE_KEY, or raw WebAuthn challenges
• Validate all inbound DTOs; reject unknown fields where strict mode applies
• Use parameterized Prisma queries only — no raw SQL unless documented
• Follow hybrid auth model: Supabase session + WebAuthn for payment approval

Risks & pitfalls

• Scope creep — stay within listed SRV atomic tasks for this sprint
• Drift from client NFC contract — coordinate before changing validation rules
• Stellar testnet instability — use health checks and retries (S12/S13)
• Prisma migration conflicts — serialize DB changes with team
• WebAuthn environment mismatch between dev client and server origins
• Underestimating E2E flakiness — mock Horizon in tests where possible

Definition of done

• All atomic SRV tasks implemented
• Tests added/updated and passing locally
• Swagger updated for HTTP changes
• No regression in CI pipeline
• Peer review completed
• Linked client Issue updated if integration contract changed
• Merged to main with migration deploy notes if applicable

Source: build plan