implement security and infrastructure improvements

Author: DokaIzk

backend/.env.example

@@ -0,0 +1,31 @@
+# Backend Server Configuration
+# Copy this to .env and customize for your environment
+
+# Server Configuration
+PORT=3000
+NODE_ENV=development
+
+# Rate Limiting Configuration
+# Global rate limiter: 100 requests per 15 minutes (900000 ms)
+RATE_LIMIT_WINDOW_MS=900000
+RATE_LIMIT_MAX_REQUESTS=100
+
+# API endpoint rate limiter: 30 requests per minute (60000 ms)
+API_RATE_LIMIT_WINDOW_MS=60000
+API_RATE_LIMIT_MAX_REQUESTS=30
+
+# Stellar RPC Configuration
+STELLAR_RPC_URL=https://soroban-testnet.stellar.org
+STELLAR_NETWORK=testnet
+STELLAR_NETWORK_PASSPHRASE=Test SDF Network ; September 2015
+
+# Vault Configuration
+VAULT_CONTRACT_ID=
+
+# Optional: Database Configuration (for future use)
+# DATABASE_URL=
+# DATABASE_POOL_SIZE=10
+
+# Optional: Cache Configuration (for future use)
+# REDIS_URL=redis://localhost:6379
+# CACHE_TTL=300

backend/.eslintrc.json

@@ -0,0 +1,39 @@
+{
+  "env": {
+    "node": true,
+    "es2020": true,
+    "jest": true
+  },
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 2020,
+    "sourceType": "module"
+  },
+  "plugins": [
+    "@typescript-eslint"
+  ],
+  "rules": {
+    "@typescript-eslint/explicit-function-return-types": "warn",
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/no-unused-vars": [
+      "error",
+      {
+        "argsIgnorePattern": "^_"
+      }
+    ],
+    "no-console": [
+      "warn",
+      {
+        "allow": [
+          "warn",
+          "error",
+          "log"
+        ]
+      }
+    ]
+  }
+}

backend/.gitignore

@@ -0,0 +1,19 @@
+node_modules/
+dist/
+.env
+.env.local
+.env.*.local
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.DS_Store
+coverage/
+.nyc_output/
+build/
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.cache/

backend/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false
+}

backend/README.md

@@ -0,0 +1,222 @@
+# YieldVault Backend API
+
+Express.js backend server for YieldVault Stellar RWA platform with rate limiting and health monitoring.
+
+## 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
+
+## 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
+```
+
+## 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 |
+
+## API Endpoints
+
+### Health Check
+
+```
+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
+  }
+}
+```
+
+**Response (503 Unavailable - Not Ready):**
+```json
+{
+  "ready": false,
+  "timestamp": "2026-03-26T10:30:00.000Z",
+  "dependencies": {
+    "cache": false,
+    "stellarRpc": false
+  }
+}
+```
+
+### Rate Limit Exceeded
+
+```
+Status: 429 Too Many Requests
+```
+
+```json
+{
+  "error": "Too many requests",
+  "status": 429,
+  "message": "Rate limit exceeded. Please try again later.",
+  "retryAfter": 1711432200000
+}
+```
+
+## Rate Limiting
+
+### Global Rate Limiting
+
+Applied to all requests except `/health` and `/ready`:
+- Window: 15 minutes (configurable)
+- Max: 100 requests per window (configurable)
+- Per: IP address
+
+### 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
+
+# Run tests in watch mode
+npm test -- --watch
+
+# Run with coverage
+npm test -- --coverage
+```
+
+## Issues Addressed
+
+### 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
+
+### 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
+
+## CI/CD Integration
+
+### Smoke Test (CI Pipeline)
+
+```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
+```
+
+### Docker Deployment
+
+Example Dockerfile:
+
+```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"]
+```
+
+## Monitoring
+
+Headers returned in responses:
+
+- `RateLimit-Limit` - Request limit
+- `RateLimit-Remaining` - Requests remaining
+- `RateLimit-Reset` - Reset timestamp
+
+Example:
+```
+RateLimit-Limit: 100
+RateLimit-Remaining: 95
+RateLimit-Reset: 1711432200
+```
+
+## License
+
+MIT

backend/jest.config.js

@@ -0,0 +1,21 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src'],
+  testMatch: ['**/__tests__/**/*.test.ts'],
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts',
+    '!src/__tests__/**',
+  ],
+  coverageThreshold: {
+    global: {
+      branches: 50,
+      functions: 50,
+      lines: 50,
+      statements: 50,
+    },
+  },
+  setupFilesAfterEnv: ['<rootDir>/src/__tests__/setup.ts'],
+};

backend/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "yieldvault-backend",
+  "version": "1.0.0",
+  "description": "YieldVault Stellar RWA Backend API",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "jest",
+    "test:smoke": "npm run build && npm run start &",
+    "lint": "eslint src",
+    "format": "prettier --write src"
+  },
+  "keywords": [
+    "stellar",
+    "vault",
+    "rwa",
+    "yield"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "express": "^4.18.2",
+    "express-rate-limit": "^7.0.0",
+    "dotenv": "^16.3.1",
+    "node-cache": "^5.1.2"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.17",
+    "@types/node": "^20.0.0",
+    "@types/jest": "^29.5.0",
+    "typescript": "^5.1.0",
+    "tsx": "^4.0.0",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "supertest": "^6.3.3",
+    "@types/supertest": "^2.0.12",
+    "eslint": "^8.40.0",
+    "@typescript-eslint/eslint-plugin": "^5.59.0",
+    "@typescript-eslint/parser": "^5.59.0",
+    "prettier": "^3.0.0"
+  }
+}