docs: MFA roadmap, rate-limit runbook, architecture diagram, API versioning (#788-#791)

Author: portableDD

docs/API_VERSIONING.md

@@ -0,0 +1,78 @@
+# API Versioning — Consumer Guide
+
+## Overview
+
+PropChain uses URL-based API versioning. The current version is **v2** (active). **v1** is deprecated and will sunset on **2026-12-31**.
+
+## Specifying a Version
+
+### Option 1: URL Path (Recommended)
+
+```
+GET /api/v2/properties
+GET /api/v2/users/me
+```
+
+### Option 2: Accept Header
+
+```
+Accept: application/vnd.propchain.v2+json
+```
+
+### Option 3: Custom Header
+
+```
+X-API-Version: v2
+```
+
+If no version is specified, the request defaults to **v2**.
+
+## Version Status
+
+| Version | Status | Released | Sunset Date |
+|---------|--------|----------|-------------|
+| v1 | Deprecated | 2026-01-01 | 2026-12-31 |
+| v2 | Active | 2026-04-01 | — |
+
+## Deprecation Policy
+
+When a version is deprecated:
+
+1. **Response headers** include deprecation warnings:
+   - `Deprecation: true`
+   - `Sunset: <date>`
+   - `Link: <next-version-docs>; rel="successor-version"`
+
+2. **Console warnings** are logged on the server for deprecated-version requests.
+
+3. A **6-month overlap** period exists where both versions remain functional.
+
+## Breaking Changes
+
+Breaking changes only occur in new major versions. Within a version:
+
+- New fields may be added to responses ( additive )
+- Existing fields will not be removed or renamed
+- Response codes will not change for existing success paths
+- New optional parameters may be added to requests
+
+## Migration from v1 to v2
+
+Key differences:
+
+- Versioning headers now included in all responses
+- New endpoint decorators available: `@ApiVersion('v2')`
+- Response format standardized across all endpoints
+
+To migrate, update your base URL:
+
+```diff
+- GET https://api.propchain.io/api/v1/properties
++ GET https://api.propchain.io/api/v2/properties
+```
+
+## Monitoring Deprecated Usage
+
+Check the `X-API-Version` header in your requests. If you see `v1`, migrate to `v2` before the sunset date.
+
+For questions, contact support@propchain.com.

docs/INCIDENT_RUNBOOK_RATE_LIMIT.md

@@ -0,0 +1,93 @@
+# Incident Runbook: Rate-Limit Misfire
+
+## Symptoms
+
+- Legitimate users receiving `429 Too Many Requests` unexpectedly
+- Rate-limit headers show exhausted counters for low-traffic IPs
+- Redis memory growing unbounded on rate-limit keys
+- `console.error('Rate limit check error:', error)` appearing in logs
+
+## Diagnosis
+
+### 1. Inspect Redis Rate-Limit Keys
+
+```bash
+# Connect to Redis
+redis-cli
+
+# List all rate-limit keys
+KEYS rate-limit:*
+
+# Check a specific user's counter
+HGETALL rate-limit:user:<userId>
+
+# Check IP-based counter
+HGETALL rate-limit:ip:<ipAddress>
+
+# Check endpoint-specific counters
+HGETALL rate-limit:endpoint:POST:/api/auth/login
+
+# Check TTL on a key
+TTL rate-limit:user:<userId>
+```
+
+### 2. Check for Key Accumulation
+
+If keys are not expiring:
+
+```bash
+# Count total rate-limit keys
+SCAN 0 MATCH rate-limit:* COUNT 1000
+
+# Check Redis memory usage
+INFO memory
+```
+
+### 3. Verify Guard Configuration
+
+Check `src/auth/rate-limit.config.ts` for:
+- Window size (should match `RATE_LIMIT_WINDOW_MS`)
+- Max requests per window
+- Whether endpoint-specific overrides are misconfigured
+
+## Resolution
+
+### Manual Counter Reset
+
+```bash
+# Reset a specific user's rate limit
+DEL rate-limit:user:<userId>
+
+# Reset an IP's rate limit
+DEL rate-limit:ip:<ipAddress>
+
+# Nuclear option — flush all rate-limit keys (CAREFUL)
+# Only in production if widespread misfire
+redis-cli KEYS "rate-limit:*" | xargs redis-cli DEL
+```
+
+### If Redis Is Unreachable
+
+The `RateLimitGuard` catches Redis errors and **allows the request** (fail-open). Check:
+
+1. Redis connection string in `.env` (`REDIS_URL`)
+2. Redis server health: `redis-cli ping`
+3. Network connectivity between app server and Redis
+
+### If Counters Are Stuck
+
+1. Restart the NestJS application to reinitialize the RateLimitService
+2. Check for orphaned keys from previous deployments
+3. Verify `cache-manager-redis-store` version compatibility
+
+## Escalation
+
+1. **P1 (production down)**: Page on-call engineer, flush Redis rate-limit keys, restart app
+2. **P2 (intermittent 429s)**: Check Redis memory, review rate-limit config, file ticket
+3. **P3 (false positives)**: Add IP/user to skip list via `@SkipRateLimit()` decorator
+
+## Prevention
+
+- Monitor Redis memory via `INFO memory` in health checks
+- Set `maxmemory-policy allkeys-lru` on Redis to auto-evict stale keys
+- Add Grafana alert for `redis_connected_clients` and `used_memory`

docs/MFA_ROADMAP.md

@@ -1,3 +1,4 @@
+<<<<<<< ours
 # Multi-Factor Authentication (MFA) Roadmap
 
 ## Purpose
@@ -40,3 +41,52 @@ These endpoints are currently implemented in the `AuthService` as enrollment and
 - The API contract is simple and opt-in.
 - Existing auth workflows continue to work for users who do not enable MFA.
 - Future expansion can include push notifications, SMS OTP, or hardware keys.
+=======
+# MFA / 2FA Roadmap
+
+## Current State
+
+Two-factor authentication is fully implemented using TOTP (Time-based One-Time Password).
+
+### Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `POST /api/auth/2fa/setup` | POST | Initialize 2FA — returns secret + QR code URL |
+| `POST /api/auth/2fa/verify` | POST | Verify a TOTP code and activate 2FA |
+| `POST /api/auth/2fa/disable` | POST | Disable 2FA (requires current TOTP code) |
+| `POST /api/auth/2fa/backup-codes` | POST | Regenerate backup codes |
+
+### DTOs
+
+- **`VerifyTwoFactorDto`** — `{ code: string }` — used by `POST /api/auth/2fa/verify`
+- **`SetupTwoFactorResponse`** — `{ secret: string; qrCodeUrl: string; otpAuthUrl: string }`
+
+### Login Flow with 2FA
+
+1. User submits email + password
+2. If `twoFactorEnabled === true`, server returns `{ requiresTwoFactor: true, tempToken }`
+3. Client calls `POST /api/auth/2fa/verify` with `tempToken` + TOTP `code`
+4. Server validates code against stored `twoFactorSecret` using `verifyTotpCode()`
+5. Backup codes are supported — each use invalidates the code
+
+### Backup Codes
+
+- 8 codes generated at setup via `generateBackupCodes()`
+- Stored as SHA-256 hashes in `twoFactorBackupCodes` array
+- Verified with timing-safe comparison via `verifyBackupCode()`
+- Each code can only be used once
+
+### Dependencies
+
+- `src/auth/security.utils.ts` — TOTP generation/verification, backup codes, QR code URL
+- `src/auth/auth.service.ts` — `setupTwoFactor()`, `verifyTwoFactor()`, `disableTwoFactor()`
+- `src/types/prisma.types.ts` — `twoFactorEnabled`, `twoFactorSecret`, `twoFactorBackupCodes` fields
+
+## Future Enhancements
+
+- [ ] SMS-based 2FA as fallback
+- [ ] Hardware key (WebAuthn/FIDO2) support
+- [ ] Admin-enforced 2FA for agent/admin roles
+- [ ] Trusted device management
+>>>>>>> theirs

docs/architecture.md

@@ -0,0 +1,102 @@
+# Architecture Diagram
+
+```mermaid
+graph TB
+    Client[Client App] -->|HTTP/WS| Gateway[NestJS Gateway]
+
+    Gateway --> Auth[Auth Module]
+    Gateway --> Users[Users Module]
+    Gateway --> Properties[Properties Module]
+    Gateway --> Transactions[Transactions Module]
+    Gateway --> Documents[Documents Module]
+    Gateway --> Search[Search Module]
+    Gateway --> Admin[Admin Module]
+    Gateway --> Fraud[Fraud Module]
+    Gateway --> Notifications[Notifications Module]
+
+    Auth --> JWT[JWT Strategy]
+    Auth --> Google[Google OAuth]
+    Auth --> MFA[2FA / TOTP]
+    Auth --> RateLimit[Rate Limit Guard]
+    Auth --> APIKeys[API Key Management]
+
+    Users --> Prisma[(Prisma Client)]
+    Properties --> Prisma
+    Transactions --> Prisma
+    Documents --> Prisma
+    Search --> Prisma
+    Admin --> Prisma
+    Fraud --> Prisma
+
+    Prisma --> PostgreSQL[(PostgreSQL)]
+
+    Properties --> Blockchain[Blockchain Service]
+    Blockchain --> Ethereum[Ethereum / Sepolia]
+
+    Documents --> Uploads[File Uploads]
+    Uploads --> LocalFS[Local FS / S3]
+
+    Notifications --> WebSocket[WebSocket Gateway]
+    Notifications --> Email[Email Service]
+    Notifications --> SMS[SMS Service]
+
+    Fraud --> Email
+    Admin --> Backup[Backup Service]
+    Backup --> PgDump[pg_dump]
+
+    Search --> Cache[(Redis Cache)]
+    RateLimit --> Cache
+    Cache --> CacheWarming[Cache Warming]
+
+    Admin --> BullMQ[BullMQ Queues]
+    Transactions --> BullMQ
+
+    Gateway --> GraphQL[GraphQL / Apollo]
+```
+
+## Request Flow
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant G as NestJS Gateway
+    participant RL as Rate Limit Guard
+    participant AU as Auth Service
+    participant S as Feature Service
+    participant DB as PostgreSQL
+    participant BC as Blockchain
+
+    C->>G: HTTP Request
+    G->>RL: canActivate()
+    RL->>RL: Check Redis counters
+    alt Rate limit exceeded
+        RL-->>C: 429 Too Many Requests
+    else Within limits
+        RL->>G: Allow
+        G->>AU: Validate JWT
+        AU->>AU: Verify token + roles
+        AU->>G: Authenticated context
+        G->>S: Handle request
+        S->>DB: Query/Mutate
+        DB-->>S: Result
+        alt Blockchain required
+            S->>BC: Record transaction
+            BC-->>S: Tx hash
+        end
+        S-->>C: Response
+    end
+```
+
+## Module Relationships
+
+| Module | Depends On | Provides |
+|--------|-----------|----------|
+| Auth | Users, JWT, Redis | Authentication, 2FA, API keys |
+| Users | Prisma | User CRUD, profiles |
+| Properties | Prisma, Blockchain, Geocoding | Property listings, images |
+| Transactions | Prisma, Blockchain | Transaction lifecycle |
+| Documents | Prisma, Uploads | Document management, signing |
+| Search | Prisma, Redis | Full-text search, facets, autocomplete |
+| Fraud | Prisma, Email | Fraud detection, alerts, auto-block |
+| Admin | Prisma, Backup, BullMQ | Admin ops, backups, reports |
+| Notifications | WebSocket, Email, SMS | Real-time + async notifications |