BE foundation prompt

gistfile1.txt

# BE foundation prompt

- **Goal:** Establish consistent API contracts, error models, and environments for mobile FE integration.
- **API base:** /api/v1/
- **Error model:** RFC7807 Problem+JSON (`type`, `title`, `status`, `detail`, `instance`)
- **Auth:** Bearer JWT (RS256), `Authorization: Bearer <token>`
- **Tracing:** Include `X-Request-Id` echoing, FE should attach it per request.
- **Pagination:** Query `page`, `size`, `sort`; response `items`, `total`, `page`, `size`.
- **Rate limiting:** FE must handle 429 with backoff and user feedback.
- **Idempotency:** For POST transactions, FE must send `X-Idempotency-Key` (UUID v4).
- **Security headers:** FE sets `X-Device-Id`, `X-App-Version`, `X-Platform` for risk signals.
- **Env:** Local dev uses SQLite; prod uses Postgres; FE toggles base URL via env.

Checklist FE:
- **DI & theming** ready
- **Secure HTTP client** with TLS pinning (if applicable), timeouts, retries for 5xx only
- **Global interceptors** for auth, request-id, idempotency
- **Unified error handler** for Problem+JSON
- **Logging** of non-PII metadata only











# BE auth prompt

Flows:
- **Login/password** → access + refresh tokens; optional biometric binding after success.
- **Login/OTP** → request, verify; throttle requests; cooldown on failures.
- **Refresh** → rotate access; refresh revocation on device unbind or risk events.
- **Device trust** → bind on successful auth; list, remove; enforce per-user max devices.

API contracts:
- POST `/api/v1/auth/login` `{ identity, password }` → `{ accessToken, refreshToken, expiresIn }`
- POST `/api/v1/auth/login/otp` `{ identity }` → `{ challengeId, channel }`
- POST `/api/v1/auth/login/otp/verify` `{ challengeId, otp }` → tokens
- POST `/api/v1/auth/token/refresh` `{ refreshToken }` → new tokens
- POST `/api/v1/auth/register` `{ phone/email, password, profile, ekycToken }` → `{ userId }`
- POST `/api/v1/auth/device/bind` `{ deviceId, platform, model }` → `{ deviceId }`
- GET `/api/v1/auth/device` → list
- DELETE `/api/v1/auth/device/{id}` → `{ success: true }`

Security:
- **RS256 JWT** with `kid` header from JWK; `iss`, `aud`, `sub`, `roles`
- **Refresh tokens** stored server-side (revocable), rotate on each refresh
- **Rate limiting**: login 10/5m, OTP 5/5m; lockout policy after threshold
- **Risk signals**: `X-Device-Id`, IP, user agent; trigger step-up auth if anomalous
- **CSRF**: Not required for token APIs; avoid cookies

FE responsibilities:
- Store tokens in **secure storage**
- Use **biometric** as local step-up; never send secrets to BE
- Handle **429** and lockout messages gracefully
- Use **idempotency key** for sensitive POSTs (optional for auth endpoints)