# kaccy-api TODO

## Phase 0 (MVP)

### Authentication Routes

- [x] POST `/api/auth/register`
  - [x] Email/password registration
  - [x] Password hashing with Argon2
  - [x] JWT token generation
  - [x] Email validation
  - [x] Username uniqueness check
- [x] POST `/api/auth/login`
  - [x] Email/password verification
  - [x] JWT token generation
  - [x] Login attempt rate limiting (via LoginAttemptTracker)
  - [x] Account lockout after failed attempts (5 attempts, 15 min lockout)

### User Routes

- [x] GET `/api/users/me` (protected)
- [x] PUT `/api/users/me` (protected)
  - [x] Update display_name, bio, avatar_url
  - [x] Validation for all fields
- [x] GET `/api/users/:id`
  - [x] Public profile view
  - [x] Hide sensitive fields (email, etc.)

### Token Routes

- [x] GET `/api/tokens`
  - [x] Pagination
  - [x] Search by symbol/name
  - [x] Filter by price range (min_price, max_price)
  - [x] Sort by price, supply, created_at (sort_by, order params)
- [x] GET `/api/tokens/:id`
  - [x] Token details with issuer info
  - [x] Current price from bonding curve
- [x] POST `/api/tokens` (protected)
  - [x] Reputation check (>= 400 score)
  - [x] Symbol uniqueness check
  - [x] Bonding curve parameter validation

### Order Routes

- [x] POST `/api/orders/buy` (protected)
  - [x] Generate BTC payment address
  - [x] Calculate total cost via bonding curve
  - [x] Create pending order
  - [x] Slippage protection (max_price_btc)
- [x] POST `/api/orders/sell` (protected)
  - [x] Check user balance
  - [x] Calculate proceeds via bonding curve
  - [x] Lock tokens in transaction
  - [x] Slippage protection (min_price_btc)
- [x] GET `/api/orders` (protected)
  - [x] User's order history
- [x] GET `/api/orders/:id` (protected)
  - [x] Order status with BTC address
- [x] DELETE `/api/orders/:id` (protected)
  - [x] Cancel pending order
  - [x] Unlock tokens if sell order

### Trade Routes

- [x] GET `/api/tokens/:id/trades`
  - [x] Trade history for token
  - [x] Trade summary (avg price, total volume)
  - [x] 24h volume calculation
- [x] GET `/api/tokens/:id/holders`
  - [x] Token holder distribution
  - [x] Percentage calculation
- [x] GET `/api/trades` (protected)
  - [x] User's trade history with pagination

### Portfolio Routes

- [x] GET `/api/portfolio` (protected)
  - [x] User's token holdings
  - [x] Current value via bonding curve
- [x] GET `/api/users/:id/tokens`
  - [x] Tokens issued by user
  - [x] Holder count and volume stats

### Commitment Routes

- [x] POST `/api/commitments` (protected)
  - [x] Create commitment with deadline
  - [x] Validation (title, description, deadline)
  - [x] Verify user owns token
- [x] POST `/api/commitments/:id/evidence` (protected)
  - [x] Submit completion evidence
  - [x] HTTPS URL validation
- [x] GET `/api/commitments` (protected)
  - [x] User's commitments
- [x] GET `/api/commitments/:id`
  - [x] Single commitment details
- [x] GET `/api/tokens/:id/commitments`
  - [x] Token's commitment history

### Admin Routes

- [x] GET `/api/admin/stats` (admin only)
  - [x] Total users, tokens, trades
  - [x] Pending commitments count
  - [x] Total volume
- [x] GET `/api/admin/users` (admin only)
  - [x] User list with pagination
  - [x] Filter by role
- [x] PUT `/api/admin/users/:id/role` (admin only)
  - [x] Update user role
  - [x] Prevent self-demotion
- [x] GET `/api/admin/commitments/pending` (admin only)
  - [x] Pending commitments queue
  - [x] User and token info
- [x] POST `/api/admin/commitments/:id/verify` (admin only)
  - [x] Approve or reject commitment
  - [x] Quality score bonus
  - [x] Reputation delta calculation
  - [x] Record admin action

### Health Routes

- [x] GET `/health`
  - [x] Basic health check
- [x] GET `/health/detailed`
  - [x] Database health
  - [x] Pool statistics
  - [x] Latency measurement
- [x] GET `/ready`
  - [x] Kubernetes readiness probe

### Middleware

- [x] JWT authentication (require_auth)
- [x] Admin authorization (require_admin)
- [x] CORS configuration
- [x] Rate limiting (RateLimiter, rate_limit_middleware)
  - [x] 100 requests/minute per IP (configurable via RateLimitConfig)
  - [x] Login attempt tracking (LoginAttemptTracker with lockout)
- [x] Request logging (logging_middleware)
- [x] Response compression (tower-http CompressionLayer)
- [x] Request ID tracking (request_id_middleware, x-request-id header)

### Error Handling

- [x] Error types (Validation, Auth, NotFound, Forbidden, Database, Core, Internal)
- [x] Standardized error response format
- [x] Validation error details (FieldError, ValidationErrors, ValidationBuilder)

### State Management

- [x] AppState with pool and jwt_secret
- [x] Add Bitcoin client to state (with_bitcoin, has_bitcoin, bitcoin methods)
- [x] Add Redis connection (state.rs - with_redis, connect_redis, redis methods)

## Phase 1 (Post-MVP)

### WebSocket Support

- [x] Real-time price updates (WsBroadcaster, token_prices_ws)
- [x] Order status notifications (user_orders_ws, OrderUpdate)
- [x] Trade notifications (token_ws, TradeNotification)
- [x] Chat/messaging (token_chat_ws, ChatMessage, broadcast_chat, subscribe_chat)

### API Documentation

- [x] OpenAPI/Swagger specification (utoipa, ApiDoc)
- [x] Auto-generated from code (schema definitions)
- [x] Interactive API explorer (swagger-ui at /swagger-ui)

### KYC Routes (routes/kyc.rs)

- [x] GET `/api/kyc` (protected) - get_my_kyc
  - [x] Get current user's KYC status
- [x] POST `/api/kyc` (protected) - submit_kyc
  - [x] Submit KYC application with documents
  - [x] Validation for required fields
  - [x] KYC level determination (Standard/Enhanced)
- [x] GET `/api/admin/kyc-queue` (admin only) - get_kyc_queue
  - [x] Pagination support
  - [x] Filter by status
- [x] POST `/api/admin/kyc/:id/verify` (admin only) - verify_kyc
  - [x] Approve or reject KYC application
  - [x] Update user KYC status on approval
  - [x] Require rejection reason when rejecting
- [x] GET `/api/admin/kyc/stats` (admin only) - get_kyc_stats
  - [x] KYC application counts by status

## Phase 2 (Future)

### Advanced Features

- [x] GraphQL alternative endpoint
  - [x] GraphQL schema and type definitions
  - [x] Query support (users, tokens, orders, trades)
  - [x] Mutation support (user profile updates)
  - [x] Authentication integration (Claims context)
  - [x] GraphQL playground interface
  - [x] Unit tests for GraphQL types
- [x] Webhook subscriptions
  - [x] Webhook registration (create, update, delete)
  - [x] Event types (token, order, trade, commitment, KYC)
  - [x] Webhook secret generation for HMAC verification
  - [x] Webhook status management
  - [x] Webhook delivery tracking
  - [x] HTTPS-only enforcement
  - [x] Routes: create, get, list, update, delete, deliveries
  - [x] Unit tests for webhook functionality
- [x] API versioning (v1, v2)
  - [x] Version extraction from path (/api/v1/*)
  - [x] Version extraction from Accept header
  - [x] Version middleware with X-API-Version response header
  - [x] Version requirement enforcement
  - [x] Default version (V1)
- [x] OAuth2 integration
  - [x] OAuth2 provider configuration (Google, GitHub)
  - [x] Authorization flow with PKCE
  - [x] User info fetching
  - [x] Automatic user creation/linking
  - [x] JWT token generation after OAuth2 auth
  - [x] Routes: login initiation, callback handling
  - [x] Unit tests for OAuth2 providers
- [x] 2FA support (TOTP)
  - [x] TOTP secret generation
  - [x] QR code generation for easy setup
  - [x] Backup code generation (10 codes)
  - [x] TOTP verification
  - [x] Routes: setup, enable, disable, status, verify
  - [x] Unit tests for TOTP functionality

### Performance

- [x] Response caching
  - [x] Redis-based HTTP response caching middleware
  - [x] Cache GET requests with configurable TTL
  - [x] Cache hit/miss headers (X-Cache-Status)
  - [x] Cache invalidation helpers (by path and pattern)
  - [x] Fire-and-forget async cache storage
- [x] Request batching
  - [x] Batch endpoint for multiple requests
  - [x] Parallel request execution support
  - [x] Batch size limits (max 10 requests)
  - [x] Individual request validation
  - [x] Request/response ID matching
  - [x] Recursion prevention
  - [x] Unit tests for batch functionality
- [x] Streaming responses for large datasets
  - [x] NDJSON (Newline-Delimited JSON) streaming
  - [x] JSON Lines streaming
  - [x] Chunked JSON array streaming
  - [x] CSV export streaming
  - [x] Configurable chunk sizes
  - [x] Cursor-based pagination support
  - [x] Unit tests for streaming functionality

## Phase 3 (Future Enhancements)

### Observability & Monitoring

- [x] Prometheus metrics endpoint
  - [x] Request/response metrics (latency, count, status codes)
  - [x] Database connection pool metrics
  - [x] Custom business metrics (tokens created, trades executed, orders, commitments, auth)
  - [x] Memory and CPU usage tracking (via process collector)
- [x] OpenTelemetry distributed tracing
  - [x] Trace ID propagation (via W3C Trace Context)
  - [x] Span annotations for key operations (HTTP method, path, status code)
  - [x] Integration with Jaeger/Zipkin (via OTLP exporter)
  - [x] Configurable sampling rate
  - [x] Graceful shutdown
- [x] Structured logging enhancements
  - [x] Request correlation IDs in all logs
  - [x] Performance profiling logs
  - [x] Audit trail for sensitive operations

### Security Enhancements

- [x] API key authentication
  - [x] API key generation and management
  - [x] Scoped permissions per API key
  - [x] Key rotation support
  - [x] Rate limiting per API key (infrastructure ready)
- [x] Advanced rate limiting
  - [x] Per-user rate limits
  - [x] Per-endpoint rate limits
  - [x] Dynamic rate limit adjustment
  - [x] Rate limit analytics
- [x] Request signing
  - [x] HMAC-based request verification
  - [x] Timestamp validation
  - [x] Replay attack prevention
- [x] IP filtering
  - [x] Whitelist/blacklist management
  - [x] Auto-blacklisting based on rate limits
  - [x] Manual blacklist management
  - [x] IP filter statistics

### Developer Experience

- [x] API client SDK generation
  - [x] TypeScript/JavaScript SDK
  - [x] Python SDK
  - [x] Rust SDK
  - [x] Go SDK
- [x] Enhanced documentation
  - [x] Postman collection export (v2.1 format)
  - [x] OpenAPI 3.1 upgrade
  - [x] Interactive examples
  - [x] Code snippets in multiple languages
- [x] Testing infrastructure
  - [x] Integration test suite
  - [x] Load testing benchmarks
  - [x] Contract testing
  - [x] Chaos engineering tests

### Production Readiness

- [x] Graceful shutdown
  - [x] Connection draining
  - [x] In-flight request completion
  - [x] Resource cleanup
- [x] Enhanced health checks
  - [x] Database health with query timeout
  - [x] Redis health check
  - [x] External service dependencies check (Bitcoin RPC, extensible)
  - [x] Disk space monitoring
- [x] Circuit breaker pattern
  - [x] Automatic failover
  - [x] Retry with exponential backoff (via circuit states)
  - [x] Fallback responses (via open state)
- [x] Connection pool optimization
  - [x] Pool statistics endpoint
  - [x] Pool health recommendations
  - [x] Connection lifecycle monitoring

### Advanced Features

- [x] Event-driven architecture
  - [x] Pub/Sub for real-time events (EventBus, Publisher, Subscriber)
  - [x] Event sourcing for audit trail (Event storage and history)
  - [x] Event handlers (Audit, Metrics, Notification, Webhook, Analytics)
  - [x] **ENHANCED**: Audit handler with database persistence (audit_events table)
  - [x] **ENHANCED**: Metrics handler with Prometheus integration
- [x] Background job processing
  - [x] Task queue system
  - [x] Scheduled jobs (cron-like)
  - [x] Job retry and failure handling
  - [x] Job monitoring (queue statistics)
- [x] Notification system
  - [x] **ENHANCED**: Email notifications with lettre library (SMTP support)
  - [x] SMS notifications (stub implementation)
  - [x] Push notifications (stub implementation)
  - [x] In-app notifications (full implementation)
- [x] Advanced analytics
  - [x] User behavior tracking (Sessions, Actions)
  - [x] Performance analytics (Metrics, Statistics, P95/P99)
  - [x] Business intelligence (Counters, Gauges, Metrics)
  - [x] Analytics event tracking


### Health Endpoint Enhancement
- [x] Added uptime tracking to health check responses
  - [x] Added `uptime_seconds` field to HealthResponse struct
  - [x] Updated health_detailed endpoint to include application uptime
  - [x] Provides real-time uptime information for monitoring and SLA tracking
- [x] Benefits:
  - Uptime visible in health checks for monitoring systems (Prometheus, Datadog, etc.)
  - Better operational visibility without needing separate metrics endpoint
  - Consistent uptime reporting across all monitoring endpoints
  - Useful for debugging and incident response

### Code Quality Verification
- [x] All 153 unit tests passing (+4 new tests)
- [x] All 24 chaos tests passing
- [x] All 17 contract tests passing
- [x] Zero compiler warnings
- [x] Zero clippy warnings
- [x] Clean build verification
- [x] All TODO comments resolved in codebase

## Latest Enhancements (2026-01-02)

### Audit Log Enhancement
- [x] Implemented dynamic query filtering with proper SQL parameterization
  - [x] Replaced hardcoded queries with QueryBuilder for safety and flexibility
  - [x] All filters now properly applied (event_type, user_id, correlation_id, source, date range)
  - [x] Prevents SQL injection through proper parameter binding
  - [x] Efficient query construction with minimal overhead
  - [x] Production-ready implementation

### API Key Usage Analytics
- [x] New comprehensive API key analytics system
  - [x] GET `/api/api-keys/:id/usage` - Detailed usage statistics
    - [x] Total requests, success rate, response time metrics
    - [x] Top endpoints by usage with average response times
    - [x] Hourly/Daily/Weekly aggregated distributions
    - [x] Status code distribution
    - [x] Customizable date ranges
  - [x] GET `/api/api-keys/:id/usage/logs` - Paginated usage logs
    - [x] Individual request details (timestamp, endpoint, method, status, response time)
    - [x] Pagination support
    - [x] Date range filtering
  - [x] GET `/api/api-keys/:id/quota` - Quota usage tracking
    - [x] Current usage vs quota limits
    - [x] Percentage used calculation
    - [x] Monthly reset dates
    - [x] Quota enforcement ready
  - [x] GET `/api/api-keys/usage/all` - Comparative statistics
    - [x] Compare all user's API keys
    - [x] Total requests per key
    - [x] Success/failure breakdown
    - [x] Last used timestamps

### Benefits
- [x] Better visibility into API key usage patterns
- [x] Quota management and enforcement infrastructure
- [x] Anomaly detection capabilities
- [x] Performance monitoring per API key
- [x] Usage-based billing support
- [x] Security auditing and compliance

### Code Quality
- [x] All 153 unit tests passing (+4 new tests)
- [x] All 24 chaos tests passing
- [x] All 17 contract tests passing
- [x] Zero compiler warnings
- [x] Zero clippy warnings
- [x] Clean, production-ready code

## Latest Enhancements (2026-01-09)

### Middleware Stack Integration
- [x] Integrated profiling_middleware into main application
  - [x] Automatic performance profiling for all requests
  - [x] Response time tracking with X-Response-Time header
  - [x] Slow request detection and logging (>1000ms threshold)
  - [x] Useful for production performance monitoring and debugging
- [x] Integrated version_middleware into main application
  - [x] Automatic API version detection from path (/api/v1/*)
  - [x] Version detection from Accept header (application/vnd.kaccy.v1+json)
  - [x] X-API-Version response header for all requests
  - [x] Version negotiation infrastructure ready for API evolution
- [x] Integrated cache_middleware into main application
  - [x] Redis-based HTTP response caching for GET requests
  - [x] Configurable TTL (default 5 minutes)
  - [x] X-Cache-Status header (HIT/MISS) for debugging
  - [x] Graceful degradation when Redis is not configured
  - [x] Fire-and-forget async cache storage for low latency
  - [x] Automatic cache key generation from path and query params

### Production Benefits
- [x] Enhanced observability with response time tracking on every request
- [x] Better API version management for gradual rollouts and breaking changes
- [x] Reduced database load and improved response times with intelligent caching
- [x] Zero-config middleware activation (cache only works when Redis is configured)
- [x] Production-ready performance monitoring without additional tools

### Middleware Stack Order (Outer to Inner)
1. request_id_middleware - Assigns unique correlation IDs
2. tracing_middleware - Distributed tracing with OpenTelemetry
3. version_middleware - API version detection and header injection
4. metrics_middleware - Prometheus metrics collection
5. profiling_middleware - Performance profiling and slow request detection
6. logging_middleware - Structured request/response logging
7. cache_middleware - Redis-based response caching (State-aware)
8. request_validation_middleware - Request size, method, and format validation
9. security_headers_middleware - Security header injection (HSTS, CSP, etc.)
10. CORS layer - Cross-origin resource sharing
11. Compression layer - Response compression (gzip, br)

### Code Quality Verification
- [x] All 153 unit tests passing
- [x] All 24 chaos tests passing
- [x] All 17 contract tests passing
- [x] Zero compiler warnings in kaccy-api
- [x] Zero clippy warnings in kaccy-api
- [x] Clean, maintainable, production-ready code

## Latest Enhancements (2026-01-09 Session 2)

### Startup and Operational Visibility
- [x] Enhanced startup banner with comprehensive middleware status
  - [x] Visual indicators (✓/✗/○) for all services and middleware
  - [x] Detailed middleware stack listing with descriptions
  - [x] Optional integration status (Redis, Bitcoin RPC, SMTP)
  - [x] Clear environment and configuration summary
- [x] Optional service connection testing on startup
  - [x] Redis connection verification with health check ping
  - [x] Automatic Redis integration if connection succeeds
  - [x] Graceful degradation with warning messages if connection fails
  - [x] Informative logging for all optional services
- [x] Middleware initialization logging
  - [x] Debug-level logs for each middleware component
  - [x] Redis cache middleware status (active/inactive) based on configuration
  - [x] Clear visibility into the complete middleware stack

### AppState Enhancements
- [x] Added `add_bitcoin_client()` builder method
  - [x] Allows adding Bitcoin client to existing state
  - [x] Consistent with `with_redis()` pattern
  - [x] Supports optional service pattern

### Production Benefits
- [x] Better operator visibility into system configuration at startup
- [x] Early detection of service configuration issues
- [x] Clear messaging about which features are active/inactive
- [x] Graceful degradation for optional services
- [x] Improved debugging and troubleshooting capabilities
- [x] Professional startup experience with clear status indicators

### Code Quality
- [x] All 153 unit tests passing
- [x] All 24 chaos tests passing
- [x] All 17 contract tests passing
- [x] Zero compiler warnings in kaccy-api
- [x] Zero clippy warnings in kaccy-api
- [x] Production-ready code with comprehensive logging
