Merge branch 'main' into feat/keyboard-shortcuts

Author: Junirezz

.github/workflows/backend-governance.yml

@@ -0,0 +1,36 @@
+name: Backend Governance
+
+on:
+  pull_request:
+    paths:
+      - 'backend/**'
+      - '.github/workflows/backend-governance.yml'
+  push:
+    branches:
+      - main
+    paths:
+      - 'backend/**'
+      - '.github/workflows/backend-governance.yml'
+
+jobs:
+  backend-governance:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: backend
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: backend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run governance checks
+        run: npm run ci:governance

backend/README.md

@@ -1,222 +1,115 @@
 # YieldVault Backend API
 
-Express.js backend server for YieldVault Stellar RWA platform with rate limiting and health monitoring.
+Express.js backend for the YieldVault Stellar RWA platform.
 
 ## Features
 
-- **Health Check Endpoint** (`/health`) - Real-time service health status
-- **Readiness Endpoint** (`/ready`) - Dependency status for deployment orchestration
-- **Rate Limiting** - Per-IP and per-API-key rate limiting to prevent abuse
-- **Dependency Monitoring** - Checks for cache and Stellar RPC availability
-- **Error Handling** - Consistent JSON error responses
-- **TypeScript** - Full type safety with TypeScript
+- Health and readiness endpoints
+- Rate limiting for public API routes
+- Versioned API surface under `/api/v1`
+- Replay-safe mutations via idempotency keys
+- Background job retry policy and dead-letter metrics
+- Migration safety checks in CI
+- TypeScript with Jest test coverage
 
 ## Quick Start
 
-### Setup
-
 ```bash
-# Install dependencies
 npm install
-
-# Create environment file
 cp .env.example .env
-```
-
-### Development
-
-```bash
-# Start development server with auto-reload
 npm run dev
 ```
 
-The server will start on `http://localhost:3000`.
-
-### Production
-
-```bash
-# Build TypeScript
-npm run build
-
-# Start production server
-npm start
-```
+The server starts on `http://localhost:3000`.
 
 ## Configuration
 
-Rate limiting and other settings are configurable via environment variables:
-
 | Variable | Default | Description |
-|----------|---------|-------------|
-| `PORT` | 3000 | Server port |
-| `NODE_ENV` | development | Environment mode |
-| `RATE_LIMIT_WINDOW_MS` | 900000 | Global rate limit window (15 min) |
-| `RATE_LIMIT_MAX_REQUESTS` | 100 | Global requests per window |
-| `API_RATE_LIMIT_WINDOW_MS` | 60000 | API rate limit window (1 min) |
-| `API_RATE_LIMIT_MAX_REQUESTS` | 30 | API requests per window |
-| `STELLAR_RPC_URL` | https://soroban-testnet.stellar.org | Stellar RPC endpoint |
+| --- | --- | --- |
+| `PORT` | `3000` | Server port |
+| `NODE_ENV` | `development` | Runtime mode |
+| `RATE_LIMIT_WINDOW_MS` | `900000` | Global rate limit window |
+| `RATE_LIMIT_MAX_REQUESTS` | `100` | Global requests per window |
+| `API_RATE_LIMIT_WINDOW_MS` | `60000` | API rate limit window |
+| `API_RATE_LIMIT_MAX_REQUESTS` | `30` | API requests per window |
+| `IDEMPOTENCY_KEY_TTL_MS` | `86400000` | Replay window for mutation requests |
+| `STELLAR_RPC_URL` | `https://soroban-testnet.stellar.org` | Stellar RPC endpoint |
 
 ## API Endpoints
 
-### Health Check
+### Health
 
-```
+```http
 GET /health
-```
-
-Returns service health status with dependency checks.
-
-**Response (200 OK):**
-```json
-{
-  "status": "healthy",
-  "timestamp": "2026-03-26T10:30:00.000Z",
-  "uptime": 3600.5,
-  "environment": "development",
-  "checks": {
-    "api": "up",
-    "cache": "up",
-    "stellarRpc": "up"
-  }
-}
-```
-
-### Readiness Check
-
-```
 GET /ready
 ```
 
-Returns service readiness state. Checks all critical dependencies before reporting ready.
-
-**Response (200 OK - Ready):**
-```json
-{
-  "ready": true,
-  "timestamp": "2026-03-26T10:30:00.000Z",
-  "dependencies": {
-    "cache": true,
-    "stellarRpc": true
-  }
-}
-```
+### Versioned API
 
-**Response (503 Unavailable - Not Ready):**
-```json
-{
-  "ready": false,
-  "timestamp": "2026-03-26T10:30:00.000Z",
-  "dependencies": {
-    "cache": false,
-    "stellarRpc": false
-  }
-}
+```http
+GET /api/v1/vault/summary
+GET /api/v1/transactions
+GET /api/v1/portfolio/holdings
+GET /api/v1/vault/history
+POST /api/v1/vault/deposits
+GET /api/v1/ops/job-metrics
 ```
 
-### Rate Limit Exceeded
+Legacy `/api/*` routes redirect to `/api/v1/*` with `308 Permanent Redirect`.
 
-```
-Status: 429 Too Many Requests
-```
-
-```json
-{
-  "error": "Too many requests",
-  "status": 429,
-  "message": "Rate limit exceeded. Please try again later.",
-  "retryAfter": 1711432200000
-}
-```
-
-## Rate Limiting
+## Idempotent Mutations
 
-### Global Rate Limiting
+Mutation endpoints require `x-idempotency-key`.
 
-Applied to all requests except `/health` and `/ready`:
-- Window: 15 minutes (configurable)
-- Max: 100 requests per window (configurable)
-- Per: IP address
+- Same key + same payload returns the original response.
+- Same key + different payload returns `409 Conflict`.
+- TTL is controlled by `IDEMPOTENCY_KEY_TTL_MS`.
 
-### API Endpoint Rate Limiting
-
-Stricter limits for API endpoints (e.g., `/api/vault/summary`):
-- Window: 1 minute (configurable)
-- Max: 30 requests per window (configurable)
-- Per: API key (from `x-api-key` header) or IP address
-
-## Testing
-
-```bash
-# Run all tests
-npm test
+## Background Jobs
 
-# Run tests in watch mode
-npm test -- --watch
+Job execution uses explicit retry policies per job class with exponential backoff.
+Failed jobs are written to a dead-letter sink and surfaced through job metrics.
 
-# Run with coverage
-npm test -- --coverage
-```
+## Migration Safety
 
-## Issues Addressed
+The CI scanner flags:
 
-### Issue #145: Rate Limiting
-- ✅ Global rate limiting per IP
-- ✅ Per-user/API-key rate limiting
-- ✅ Configurable via environment variables
-- ✅ Clear 429 responses with retry information
-- ✅ Tests included for rate limiting behavior
+- irreversible schema changes such as `DROP` and `TRUNCATE`
+- long-running or locking migration patterns
+- schema changes that add indexed columns without an index declaration
 
-### Issue #148: Health & Readiness Endpoints
-- ✅ `/health` endpoint for service health
-- ✅ `/ready` endpoint for deployment readiness
-- ✅ Dependency health checks (cache, RPC)
-- ✅ CI smoke test setup via npm scripts
-- ✅ Consistent response formats
+Rollback expectations:
 
-## CI/CD Integration
+- Prefer additive schema changes.
+- Add indexes before deploying code that depends on them.
+- Avoid destructive drops in the same deploy as a data migration.
+- Document manual rollback steps when a migration cannot be reversed automatically.
 
-### Smoke Test (CI Pipeline)
+Run the scanner locally with:
 
 ```bash
-# Build and start server
-npm run test:smoke
-
-# The server will start in background, ready for health checks
-# Call: curl http://localhost:3000/health
-# Call: curl http://localhost:3000/ready
+npm run check:migrations
 ```
 
-### Docker Deployment
-
-Example Dockerfile:
+## Testing
 
-```dockerfile
-FROM node:20-alpine
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci --only=production
-COPY dist ./dist
-EXPOSE 3000
-HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
-  CMD node -e "require('http').get('http://localhost:3000/health', (r) => r.statusCode === 200 ? process.exit(0) : process.exit(1))"
-CMD ["npm", "start"]
+```bash
+npm test
+npm run build
+npm run check:migrations
 ```
 
-## Monitoring
+## CI
 
-Headers returned in responses:
+The backend governance workflow runs:
 
-- `RateLimit-Limit` - Request limit
-- `RateLimit-Remaining` - Requests remaining
-- `RateLimit-Reset` - Reset timestamp
+- `npm run lint`
+- `npm run test`
+- `npm run build`
+- `npm run check:migrations`
 
-Example:
-```
-RateLimit-Limit: 100
-RateLimit-Remaining: 95
-RateLimit-Reset: 1711432200
-```
+See [`.github/workflows/backend-governance.yml`](../.github/workflows/backend-governance.yml).
 
 ## License
 
-MIT
+MIT

backend/package.json

@@ -10,7 +10,9 @@
     "test": "jest",
     "test:smoke": "npm run build && npm run start &",
     "lint": "eslint src",
-    "format": "prettier --write src"
+    "format": "prettier --write src",
+    "check:migrations": "node scripts/check-migrations.js",
+    "ci:governance": "npm run lint && npm run test && npm run build && npm run check:migrations"
   },
   "keywords": [
     "stellar",