implement full dora api

[pk910]

Add comprehensive v1 API endpoints with advanced authentication and rate limiting

Summary

• Add 16 new v1 API endpoints providing comprehensive access to all blockchain explorer data
• Implement JWT-based authentication system with configurable rate limiting and CORS controls
• Enable programmatic access to epochs, validators, deposits, slashings, exits, withdrawals, consolidations, and MEV blocks
• Support both authenticated and unauthenticated access with flexible security policies

API Endpoints Added

• GET /api/v1/epochs - Epoch data with comprehensive filtering
• GET /api/v1/validators - Validator information with search and filtering
• GET /api/v1/validators/activity - Validator activity information with grouping & filtering
• GET/POST /api/v1/validator_names - Validator name lookup (supports 100 item limit)
• GET /api/v1/deposits/included - Deposits included in blocks with filtering
• GET /api/v1/deposits/transactions - Deposit transactions with comprehensive filtering
• GET /api/v1/deposits/queue - Queued deposits with filtering
• GET /api/v1/slashings - Slashing events with filtering
• GET /api/v1/voluntary_exits - Voluntary exit requests with filtering
• GET /api/v1/withdrawal_requests - Withdrawal requests with filtering
• GET /api/v1/consolidation_requests - Consolidation requests with filtering
• GET /api/v1/network/forks - Network fork information with BPO forks and digests
• GET /api/v1/network/overview - Comprehensive network state overview
• GET /api/v1/network/splits - Active network splits with participation metrics
• GET /api/v1/mev/blocks - MEV block data with offset/limit pagination

Authentication & Rate Limiting System

• JWT Token Authentication - Secure token-based API access with HMAC-256 signing
• Flexible Rate Limiting - Per-token, per-IP, or global rate limits (configurable per minute)
• IP/CIDR Whitelisting - Bypass rate limits for trusted IPv4/IPv6 addresses and ranges
• Token-Based CORS - Restrict API access to specific domains per token
• Unlimited Tokens - Special tokens with no rate limits for internal services
• Token Expiration - Configurable token lifetimes for enhanced security

Token Management Utility

• dora-utils token generate - Create JWT tokens with custom rate limits and CORS policies
• dora-utils token secret - Generate cryptographically secure JWT signing secrets
• Config File Support - Load JWT secrets from dora config files
• Flexible Token Options - Name, rate limits, CORS origins, expiration times
• Usage Examples - Built-in help and example commands

Configuration Features

• API Configuration Block - Comprehensive settings in config.yaml
• Environment Variables - Full env var support for all API settings
• Default Rate Limits - Configurable defaults for unauthenticated requests
• CORS Policies - Global and per-token CORS origin control
• Security Options - Disable rate limiting, whitelist IPs, custom secrets

Technical Implementation

• Middleware Architecture - Clean separation of rate limiting and CORS handling
• Memory Management - Automatic cleanup of unused rate limiters
• IPv6 Support - Full support for IPv6 addresses and CIDR ranges
• Standard Headers - X-RateLimit-* headers for client integration
• V1 Versioning - All handlers suffixed for future API versions
• Service Integration - Proper use of existing service methods and filters
• Comprehensive Filtering - All endpoints support frontend-equivalent filtering
• Error Handling - Consistent JSON error responses across all endpoints
• Shared Code Reuse - Common functions shared between endpoints to avoid duplication
• Caching Support - Network overview cached with SecondsPerSlot timeout for performance
• Bearer Token Authentication - Updated Swagger documentation for proper JWT token usage

Usage Examples

# Generate JWT secret
./dora-utils token secret

# Create unlimited admin token
./dora-utils token generate --name "admin-service" --rate-limit 0

# Create token using config file for secret
./dora-utils token generate --name "webapp" --config "./config.yaml"

# Create frontend token with CORS restrictions
./dora-utils token generate --name "webapp" --rate-limit 200 \
  --cors-origins "https://app.example.com,https://*.app.example.com" \
  --duration "30d"

# API usage with authentication
curl -H "Authorization: Bearer <token>" \
  "http://localhost:8080/api/v1/epochs?limit=10&offset=0"

# Network overview API
curl -H "Authorization: Bearer <token>" \
  "http://localhost:8080/api/v1/network/overview"

# Network splits with stale forks filtered out
curl -H "Authorization: Bearer <token>" \
  "http://localhost:8080/api/v1/network/splits?with_stale=false"

Configuration Example

api:
  enabled: true
  authSecret: "base64-encoded-secret"
  defaultRateLimit: 60  # requests per minute
  defaultRateLimitBurst: 10
  corsOrigins: ["https://explorer.example.com"]
  whitelistedIPs: ["127.0.0.1", "::1", "10.0.0.0/8"]

Security Features

• JWT Signing - HMAC-256 with configurable secrets
• Rate Limit Bypass - IP-based whitelisting for internal services
• CORS Enforcement - Prevent unauthorized cross-origin access
• Token Scoping - Per-token CORS and rate limit policies
• Request Logging - Authentication failures and rate limit violations logged

Test Plan

• All APIs build without errors and integrate properly
• JWT token generation and validation working
• Rate limiting functional with proper headers
• CORS policies enforced for token-specific origins
• IP whitelisting bypasses rate limits correctly
• Service method integration maintains data consistency
• Comprehensive filtering matches frontend capabilities
• Memory cleanup prevents rate limiter leaks
• Config file support for token generator working
• Network overview API returns complete data structure
• Network splits API filters stale forks correctly
• Swagger UI shows Bearer token authentication
• Shared fork logic eliminates code duplication
• Queue statistics show separate time estimates in seconds

[barnabasbusa]

lgtm