self-serve-integration-service

# Integration Service Documentation Welcome to the Self-Serve Integration Service documentation! --- ## 📚 **Documentation Index** ### **🔐 Authentication & Security** | Document | Description | Audience | | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------ | | [**Authentication Architecture**](./AUTHENTICATION_ARCHITECTURE.md) | **Complete authentication guide** covering all three methods: OAuth, JWT, and HMAC | Everyone | | [Quick Reference](./AUTHENTICATION_QUICK_REFERENCE.md) | Quick lookup for authentication methods with code examples | Developers | | [JWT Authentication](./JWT_AUTHENTICATION.md) | Detailed JWT implementation for user and OAuth client tokens | Backend Developers | --- ## 🎯 **Quick Navigation** ### **I want to...** #### **Integrate as an External Partner** → Read: [Authentication Architecture - External Client Access](./AUTHENTICATION_ARCHITECTURE.md#1️⃣-external-client-access-oauth-20) → Quick Start: [OAuth Quick Reference](./AUTHENTICATION_QUICK_REFERENCE.md#1️⃣-external-client-oauth) #### **Build a Frontend Application** → Read: [Authentication Architecture - User Access](./AUTHENTICATION_ARCHITECTURE.md#2️⃣-userfrontend-access-jwt-user-token) → Quick Start: [User Auth Quick Reference](./AUTHENTICATION_QUICK_REFERENCE.md#2️⃣-frontenduser) #### **Call from Another Microservice** → Read: [Authentication Architecture - Service-to-Service](./AUTHENTICATION_ARCHITECTURE.md#3️⃣-service-to-service-hmac-request-signing) → Quick Start: [HMAC Quick Reference](./AUTHENTICATION_QUICK_REFERENCE.md#3️⃣-service-to-service-hmac) #### **Deploy to AWS ECS** → Read: [AWS Secrets Manager Setup](./AUTHENTICATION_ARCHITECTURE.md#aws-ecs-production-secrets-manager) → See: [CloudFormation Templates](./AUTHENTICATION_ARCHITECTURE.md#cloudformation-template) #### **Understand Database Schema** → Read: [Database Structure](./DATABASE_STRUCTURE.md) #### **Implement Retry Logic** → Read: [Retry Mechanism](./RETRY_MECHANISM.md) #### **Configure Swagger/API Docs** → Read: [Swagger Documentation](./SWAGGER_DOCUMENTATION.md) --- ## 🏗️ **Architecture Overview** ``` ┌────────────────────────────────────────────────────────────────┐ │ EXTERNAL ACCESS │ │ (Partners, Frontend, Mobile) via API Gateway │ └────────────────────────┬───────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ API GATEWAY │ │ - OAuth Token Validation │ │ - User JWT Validation │ │ - Rate Limiting │ │ - Routing │ └────────────────────────┬────────────────────────────────────────┘ │ ┌────────────────┼────────────────┐ │ │ │ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Auth Service │ │ Integration │ │ Order Service│ │ │ │ Service │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ └────────────────┴────────────────┘ Service-to-Service (HMAC) ``` --- ## 🔐 **Authentication Methods** ### **1. OAuth 2.0 Client Credentials** (External Partners) - **Use Case:** Third-party integrations - **Flow:** Client ID + Secret → Access Token - **Via:** API Gateway - **Token Lifetime:** 1 hour - **Documentation:** [Full Guide](./AUTHENTICATION_ARCHITECTURE.md#1️⃣-external-client-access-oauth-20) ### **2. JWT User Token** (Frontend/Users) - **Use Case:** Web/Mobile applications - **Flow:** Email + Password → JWT Token - **Via:** API Gateway - **Token Lifetime:** 1 hour (refresh: 7 days) - **Documentation:** [Full Guide](./AUTHENTICATION_ARCHITECTURE.md#2️⃣-userfrontend-access-jwt-user-token) ### **3. HMAC Request Signing** (Service-to-Service) - **Use Case:** Internal microservice communication - **Flow:** Service Secret → HMAC Signature - **Via:** Direct (no gateway) - **Signature Validity:** 5 minutes - **Documentation:** [Full Guide](./AUTHENTICATION_ARCHITECTURE.md#3️⃣-service-to-service-hmac-request-signing) --- ## 🚀 **Getting Started** ### **Prerequisites** - Node.js 22+ - Docker & Docker Compose - PostgreSQL 14+ - AWS Account (for production) ### **Local Development** ```bash # 1. Clone repository git clone https://github.com/your-org/self-serve-integration-service.git cd self-serve-integration-service # 2. Install dependencies npm install # 3. Setup environment variables cp .env.example .env # Edit .env with your configuration # 4. Setup database npx prisma generate npx prisma migrate dev # 5. Start development server npm run dev ``` ### **Docker Development** ```bash # Start all services docker-compose up -d # View logs docker-compose logs -f integration-service # Access Swagger docs open http://localhost:3003/api-docs ``` --- ## 📖 **API Documentation** ### **Swagger/OpenAPI** - **Local:** http://localhost:3003/api-docs - **Staging:** https://staging-api.yourdomain.com/api-docs - **Production:** https://api.yourdomain.com/api-docs ### **Key Endpoints** | Endpoint | Method | Auth | Description | | ------------------------------------------- | ------ | ---- | ------------------- | | `/health` | GET | None | Health check | | `/api/integration/quotes/calculate` | POST | All | Calculate quote | | `/api/integration/proposals/generate` | POST | All | Generate proposal | | `/api/integration/funders` | GET | All | List funders | | `/api/integration/customers/{email}/quotes` | GET | All | Get customer quotes | --- ## 🔧 **Environment Variables** ### **Required** ```env # Database DATABASE_URL=postgresql://user:pass@localhost:5432/integration_db # JWT Configuration (must match auth-service) JWT_SECRET=your-jwt-secret-key JWT_ISSUER=self-serve-platform JWT_AUDIENCE=self-serve-users # Service Identity (for HMAC) SERVICE_NAME=integration-service ``` ### **HMAC Service Secrets** ```env # Local Development ORDER_SERVICE_SECRET=order-service-secret-local-dev DOCUMENT_SERVICE_SECRET=document-service-secret-local-dev API_GATEWAY_SECRET=api-gateway-secret-local-dev ``` ### **AWS Production (use Secrets Manager)** ```yaml # Injected from AWS Secrets Manager in ECS Secrets: - Name: ORDER_SERVICE_SECRET ValueFrom: arn:aws:secretsmanager:region:account:secret:order-service-secret ``` --- ## 🧪 **Testing** ### **Unit Tests** ```bash npm test ``` ### **Integration Tests** ```bash npm run test:integration ``` ### **Test Authentication** ```bash # Test OAuth npm run test:auth:oauth # Test User Login npm run test:auth:user # Test HMAC npm run test:auth:hmac ``` --- ## 📊 **Monitoring & Logging** ### **Health Checks** - **Endpoint:** `/health` - **Liveness:** `/health/live` - **Readiness:** `/health/ready` ### **Logs** - **Local:** Console output - **AWS:** CloudWatch Logs - **Format:** JSON structured logging ### **Metrics** - Authentication success/failure rates - Request latency - Service-to-service call metrics - Token generation/validation metrics --- ## 🔐 **Security Best Practices** ### ✅ **DO** - Use HTTPS in production - Store secrets in AWS Secrets Manager - Enable secret auto-rotation (30 days) - Implement rate limiting - Log authentication failures - Use separate OAuth clients per partner - Validate timestamps in HMAC requests ### ❌ **DON'T** - Commit secrets to git - Share OAuth client secrets - Log token values - Use static API keys - Skip timestamp validation - Reuse the same secret across services --- ## 🚢 **Deployment** ### **AWS ECS Fargate** See [Authentication Architecture - AWS ECS Production](./AUTHENTICATION_ARCHITECTURE.md#aws-ecs-production-secrets-manager) for complete deployment guide. **Quick Steps:** 1. Push Docker image to ECR 2. Create secrets in Secrets Manager 3. Deploy ECS task definition 4. Configure service discovery 5. Update load balancer targets --- ## 🆘 **Troubleshooting** ### **Common Issues** | Issue | Cause | Solution | | ------------------- | ------------------------------- | ---------------------------------- | | "Invalid signature" | Wrong HMAC secret or clock skew | Check secret, sync clocks with NTP | | "Token expired" | JWT token > 1 hour old | Implement token refresh | | "Timestamp too old" | Clock skew > 5 minutes | Sync system clock | | "Unknown service" | Service not registered | Add service to SERVICE_SECRETS | See [Quick Reference - Common Issues](./AUTHENTICATION_QUICK_REFERENCE.md#🆘-common-issues) for detailed troubleshooting. --- ## 📞 **Support** ### **Internal Team** - **Slack:** #platform-security - **Email:** platform-team@yourdomain.com ### **External Partners** - **Email:** partners@yourdomain.com - **Documentation:** https://docs.yourdomain.com --- ## 📝 **Contributing** See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines. --- ## 📜 **License** Proprietary - All Rights Reserved --- **Last Updated:** October 14, 2024 **Version:** 1.0.0