skybridge/README.md

# API Key Management Service

A comprehensive, secure API Key Management Service built in modern Go, designed to scale to millions of concurrent requests.

## Features

- **Scalable Architecture**: Built with interfaces and dependency injection for easy extension
- **Dual Token Types**: Support for both static API keys and user JWT tokens
- **Permission System**: Hierarchical permission scopes with granular access control
- **Multiple Auth Providers**: Header-based and SSO authentication providers
- **Rate Limiting**: Configurable rate limiting to prevent abuse
- **Security**: Comprehensive security headers, CORS, and secure token handling
- **Database**: PostgreSQL with proper migrations and connection pooling
- **Monitoring**: Health checks, metrics, and structured logging
- **Docker Ready**: Complete Docker Compose setup for easy deployment

## Architecture

The service follows clean architecture principles with clear separation of concerns:

```
cmd/server/          - Application entry point
internal/
  ├── domain/        - Domain models and business logic
  ├── repository/    - Data access interfaces and implementations
  ├── services/      - Business logic layer
  ├── handlers/      - HTTP request handlers
  ├── middleware/    - HTTP middleware components
  ├── config/        - Configuration management
  └── database/      - Database connection and migrations
```

## Quick Start

### Prerequisites

- Docker and Docker Compose
- Go 1.21+ (for local development)

### Running with Docker Compose

1. **Start the services:**
```bash
docker-compose up -d
```

This starts:
- PostgreSQL database on port 5432
- API service on port 8080
- Nginx proxy on port 80
- Metrics endpoint on port 9090

2. **Check service health:**
```bash
curl http://localhost/health
```

3. **View API documentation:**
```bash
curl http://localhost/api/docs
```

### Configuration

The service is configured via environment variables. Key settings:

```env
# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=kms
DB_USER=postgres
DB_PASSWORD=postgres

# Server
SERVER_HOST=0.0.0.0
SERVER_PORT=8080

# Authentication
AUTH_PROVIDER=header
AUTH_HEADER_USER_EMAIL=X-User-Email

# Security
RATE_LIMIT_ENABLED=true
RATE_LIMIT_RPS=100
RATE_LIMIT_BURST=200
```

## API Usage

### Authentication

All protected endpoints require the `X-User-Email` header when using the HeaderAuthenticationProvider:

```bash
curl -H "X-User-Email: admin@example.com" \
     -H "Content-Type: application/json" \
     http://localhost/api/applications
```

### Creating an Application

```bash
curl -X POST http://localhost/api/applications \
  -H "Content-Type: application/json" \
  -H "X-User-Email: admin@example.com" \
  -d '{
    "app_id": "com.mycompany.api",
    "app_link": "https://api.mycompany.com",
    "type": ["static", "user"],
    "callback_url": "https://api.mycompany.com/callback",
    "token_renewal_duration": "168h",
    "max_token_duration": "720h",
    "owner": {
      "type": "team",
      "name": "API Team",
      "owner": "api-team@mycompany.com"
    }
  }'
```

### Creating a Static Token

```bash
curl -X POST http://localhost/api/applications/com.mycompany.api/tokens \
  -H "Content-Type: application/json" \
  -H "X-User-Email: admin@example.com" \
  -d '{
    "owner": {
      "type": "individual",
      "name": "Service Account",
      "owner": "service@mycompany.com"
    },
    "permissions": ["repo.read", "repo.write"]
  }'
```

### Token Verification

```bash
curl -X POST http://localhost/api/verify \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "com.mycompany.api",
    "type": "static",
    "token": "your-static-token-here",
    "permissions": ["repo.read"]
  }'
```

## Permission Scopes

The service includes a hierarchical permission system:

### System Permissions
- `internal` - Full access to internal system operations
- `internal.admin` - Administrative access to internal system

### Application Management
- `app.read` - Read application information
- `app.write` - Create and update applications
- `app.delete` - Delete applications

### Token Management
- `token.read` - Read token information
- `token.create` - Create new tokens
- `token.revoke` - Revoke existing tokens

### Repository Access (Example)
- `repo.read` - Read repository data
- `repo.write` - Write to repositories
- `repo.admin` - Administrative access to repositories

## Development

### Local Development

1. **Install dependencies:**
```bash
go mod download
```

2. **Run database migrations:**
```bash
# Using Docker for PostgreSQL
docker run --name kms-postgres -e POSTGRES_DB=kms -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:15-alpine
```

3. **Run the service:**
```bash
go run cmd/server/main.go
```

### Testing

The service includes comprehensive logging and can be tested at different user levels:

- **Port 80**: Regular user (`test@example.com`)
- **Port 8081**: Admin user (`admin@example.com`)
- **Port 8082**: Limited user (`limited@example.com`)

### Building with distrobox

If you have distrobox available:

```bash
distrobox create --name golang-dev --image golang:1.21-alpine
distrobox enter golang-dev
cd /path/to/project
go build -o api-key-service ./cmd/server
```

## Security Features

- **Rate Limiting**: Configurable per-endpoint rate limits
- **Security Headers**: Comprehensive security headers on all responses
- **CORS**: Configurable Cross-Origin Resource Sharing
- **Token Security**: Secure token generation and validation
- **Permission Validation**: Hierarchical permission checking
- **Audit Logging**: All operations logged with user attribution
- **Input Validation**: Request validation with detailed error messages

## Monitoring

### Health Checks

- `GET /health` - Basic health check
- `GET /ready` - Readiness check with database connectivity

### Metrics

- `GET /metrics` - Prometheus-style metrics (when enabled)

### Logging

Structured JSON logging with configurable levels:
- Request/response logging
- Error tracking with stack traces
- Performance metrics
- Security events

## Database Schema

The service uses PostgreSQL with the following key tables:

- `applications` - Application definitions
- `static_tokens` - Static API tokens
- `available_permissions` - Permission catalog
- `granted_permissions` - Token-permission relationships

Migrations are automatically applied on startup.

## Production Considerations

1. **Security**:
   - Change default HMAC keys
   - Use HTTPS in production
   - Configure proper CORS origins
   - Set up proper authentication provider

2. **Performance**:
   - Tune database connection pools
   - Configure appropriate rate limits
   - Set up load balancing
   - Monitor metrics and logs

3. **High Availability**:
   - Run multiple service instances
   - Use database clustering
   - Implement health check monitoring
   - Set up proper backup procedures

## API Documentation

Comprehensive API documentation is available in [`docs/API.md`](docs/API.md), including:

- Complete endpoint reference
- Request/response examples
- Error handling
- Authentication flows
- Rate limiting details
- Security considerations

## Architecture Decisions

- **Interface-based Design**: All dependencies are injected as interfaces for easy testing and replacement
- **Clean Architecture**: Clear separation between domain, service, and infrastructure layers
- **Security First**: Built with security considerations from the ground up
- **Scalability**: Designed to handle millions of concurrent requests
- **Observability**: Comprehensive logging, metrics, and health checks
- **Configuration**: Environment-based configuration with sensible defaults

## Contributing

The codebase follows Go best practices and clean architecture principles. Key patterns:

- Repository pattern for data access
- Service layer for business logic
- Middleware for cross-cutting concerns
- Dependency injection throughout
- Comprehensive error handling
- Structured logging

## License

This project is ready for production use with appropriate security measures in place.