startup-starter/skybridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

claudefile update

Browse Source
This commit is contained in:
Ryan Copley
2025-08-25 19:38:13 -04:00
parent b292d1c506
commit dc0cd946c2
1 changed files with 208 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

273
CLAUDE.md
View File

@ -6,6 +6,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
This is an API Key Management Service (KMS) built with Go backend and React TypeScript frontend. The system manages API keys, user authentication, permissions, and provides both static tokens and user JWT tokens with hierarchical permission scopes. This is an API Key Management Service (KMS) built with Go backend and React TypeScript frontend. The system manages API keys, user authentication, permissions, and provides both static tokens and user JWT tokens with hierarchical permission scopes.
**Key Technologies:**
- **Backend**: Go 1.23+ with Gin/Gorilla Mux, PostgreSQL, JWT tokens
- **Frontend**: React 19+ with TypeScript, Ant Design 5.27+
- **Infrastructure**: Podman/Docker Compose, Nginx, Redis (optional)
- **Security**: HMAC token signing, RBAC permissions, rate limiting
## Architecture ## Architecture
The project follows clean architecture principles with clear separation: The project follows clean architecture principles with clear separation:
@ -16,13 +22,18 @@ internal/ - Go backend core logic
├── domain/ - Domain models and business logic ├── domain/ - Domain models and business logic
├── repository/ - Data access interfaces and PostgreSQL implementations ├── repository/ - Data access interfaces and PostgreSQL implementations
├── services/ - Business logic layer ├── services/ - Business logic layer
├── handlers/ - HTTP request handlers ├── handlers/ - HTTP request handlers (Gin-based)
├── middleware/ - Authentication, logging, security middleware ├── middleware/ - Authentication, logging, security, CSRF middleware
├── config/ - Configuration management ├── config/ - Configuration management with validation
├── auth/ - JWT, OAuth2, SAML, header-based auth providers
├── cache/ - Redis caching layer (optional)
├── metrics/ - Prometheus metrics collection
└── database/ - Database connection and migrations └── database/ - Database connection and migrations
kms-frontend/ - React TypeScript frontend with Ant Design kms-frontend/ - React TypeScript frontend with Ant Design
migrations/ - PostgreSQL database migration files migrations/ - PostgreSQL database migration files
test/ - Integration and E2E tests test/ - Integration and E2E tests (both Go and bash)
docs/ - Comprehensive technical documentation
nginx/ - Nginx configuration for reverse proxy
``` ```
## Development Commands ## Development Commands
@ -30,13 +41,13 @@ test/ - Integration and E2E tests
### Go Backend ### Go Backend
```bash ```bash
# Run the server locally # Run the server locally (requires environment variables)
go run cmd/server/main.go INTERNAL_HMAC_KEY=test-hmac-key JWT_SECRET=test-jwt-secret AUTH_SIGNING_KEY=test-signing-key go run cmd/server/main.go
# Build the binary # Build the binary
go build -o api-key-service ./cmd/server go build -o api-key-service ./cmd/server
# Run tests # Run tests (uses kms_test database)
go test -v ./test/... go test -v ./test/...
# Run tests with coverage # Run tests with coverage
@ -56,7 +67,7 @@ go test -v ./test/ -run TestConcurrentRequests
# Navigate to frontend directory # Navigate to frontend directory
cd kms-frontend cd kms-frontend
# Install dependencies # Install dependencies (Node 24+, npm 11+)
npm install npm install
# Start development server # Start development server
@ -69,130 +80,262 @@ npm run build
npm test npm test
``` ```
### Docker & Development Environment ### Podman Compose & Development Environment
**CRITICAL**: This project uses `podman-compose`, not `docker-compose`.
```bash ```bash
# Start all services (PostgreSQL, API, Nginx, Frontend) # Start all services (PostgreSQL, API, Nginx, Frontend)
docker-compose up -d podman-compose up -d
# Check service health # Check service health
curl http://localhost/health curl http://localhost:8081/health
# View logs # View logs
docker-compose logs -f podman-compose logs -f
# View specific service logs
podman-compose logs -f api-service
podman-compose logs -f postgres
# Stop services # Stop services
docker-compose down podman-compose down
# Rebuild services after code changes
podman-compose up -d --build
``` ```
## Database Setup ## Database Operations
The project uses PostgreSQL with automatic migrations. For local development: **CRITICAL**: All database operations use `podman exec` commands. Never use direct `psql` commands.
### Database Access
```bash ```bash
# Create development database # Access database shell (container name: kms-postgres)
psql -U postgres -c "CREATE DATABASE kms;" podman exec -it kms-postgres psql -U postgres -d kms
# Create test database # Run SQL commands via exec
psql -U postgres -c "CREATE DATABASE kms_test;" podman exec -it kms-postgres psql -U postgres -c "SELECT * FROM applications LIMIT 5;"
# Check specific tables
podman exec -it kms-postgres psql -U postgres -d kms -c "\dt"
podman exec -it kms-postgres psql -U postgres -d kms -c "SELECT token_id, app_id, user_id FROM static_tokens LIMIT 5;"
# Apply migrations manually if needed
podman exec -it kms-postgres psql -U postgres -d kms -f /docker-entrypoint-initdb.d/001_initial_schema.up.sql
```
### Database Testing
```bash
# Create test database (if needed)
podman exec -it kms-postgres psql -U postgres -c "CREATE DATABASE kms_test;"
# Reset test database
podman exec -it kms-postgres psql -U postgres -c "DROP DATABASE IF EXISTS kms_test; CREATE DATABASE kms_test;"
# Check test data
podman exec -it kms-postgres psql -U postgres -d kms -c "SELECT * FROM applications WHERE name LIKE 'test-%';"
``` ```
## Testing ## Testing
The project uses podman-compose for all testing environments and database operations.
### End-to-End Testing ### End-to-End Testing
```bash ```bash
# Start test environment with podman-compose
podman-compose up -d
# Wait for services to be ready
sleep 10
# Run comprehensive E2E tests with curl # Run comprehensive E2E tests with curl
./test/e2e_test.sh ./test/e2e_test.sh
# Test against different server # Test against specific server and user
BASE_URL=http://localhost:8080 USER_EMAIL=admin@example.com ./test/e2e_test.sh BASE_URL=http://localhost:8080 USER_EMAIL=admin@example.com ./test/e2e_test.sh
# Clean up test environment
podman-compose down
``` ```
### Test Environments ### Go Integration Tests
The service provides different test user contexts on different ports: ```bash
- Port 80: Regular user (`test@example.com`) # Run Go integration tests (uses kms_test database)
- Port 8081: Admin user (`admin@example.com`) go test -v ./test/...
- Port 8082: Limited user (`limited@example.com`)
# With podman-compose environment
podman-compose up -d
sleep 10
go test -v ./test/...
podman-compose down
```
### Test Environments & Ports
- **Port 8080**: Main API service
- **Port 8081**: Nginx proxy (main access point)
- **Port 3000**: React frontend (direct access)
- **Port 5432**: PostgreSQL database
- **Port 9090**: Metrics endpoint (if enabled)
The service provides different test user contexts:
- Regular user: `test@example.com`
- Admin user: `admin@example.com`
- Limited user: `limited@example.com`
## Key Configuration ## Key Configuration
Environment variables for configuration: ### Required Environment Variables
```bash ```bash
# Security (REQUIRED - minimum 32 characters each)
INTERNAL_HMAC_KEY=<secure-hmac-key-32-chars-min>
JWT_SECRET=<secure-jwt-secret-32-chars-min>
AUTH_SIGNING_KEY=<secure-auth-key-32-chars-min>
# Database # Database
DB_HOST=localhost DB_HOST=postgres # Use 'postgres' for containers, 'localhost' for local
DB_PORT=5432 DB_PORT=5432
DB_NAME=kms DB_NAME=kms
DB_USER=postgres DB_USER=postgres
DB_PASSWORD=postgres DB_PASSWORD=postgres
DB_SSLMODE=disable
# Server # Server
SERVER_HOST=0.0.0.0 SERVER_HOST=0.0.0.0
SERVER_PORT=8080 SERVER_PORT=8080
# Authentication # Authentication
AUTH_PROVIDER=header AUTH_PROVIDER=header # or 'sso'
AUTH_HEADER_USER_EMAIL=X-User-Email AUTH_HEADER_USER_EMAIL=X-User-Email
# Security # Features
RATE_LIMIT_ENABLED=true RATE_LIMIT_ENABLED=true
CACHE_ENABLED=false # Set to true to enable Redis
METRICS_ENABLED=true
SAML_ENABLED=false # Set to true for SAML auth
```
### Optional Configuration
```bash
# Rate Limiting
RATE_LIMIT_RPS=100 RATE_LIMIT_RPS=100
RATE_LIMIT_BURST=200 RATE_LIMIT_BURST=200
AUTH_RATE_LIMIT_RPS=5
AUTH_RATE_LIMIT_BURST=10
# Caching (Redis)
REDIS_ADDR=localhost:6379
REDIS_DB=0
# Security
MAX_AUTH_FAILURES=5
AUTH_FAILURE_WINDOW=15m
IP_BLOCK_DURATION=1h
# Logging
LOG_LEVEL=debug # debug, info, warn, error
LOG_FORMAT=json
``` ```
## API Structure ## API Structure
The API provides: ### Core Endpoints
- Health checks (`/health`, `/ready`) - **Health**: `/health`, `/ready`
- Authentication (`/api/login`, `/api/verify`, `/api/renew`) - **Authentication**: `/api/login`, `/api/verify`, `/api/renew`
- Application management (`/api/applications`) - **Applications**: `/api/applications` (CRUD operations)
- Token management (`/api/applications/{id}/tokens`) - **Tokens**: `/api/applications/{id}/tokens` (Static token management)
- Permission hierarchies (repo.read, app.write, internal.admin, etc.) - **Metrics**: `:9090/metrics` (Prometheus format, if enabled)
## Code Patterns ### Permission System
### Backend Patterns Hierarchical permission scopes (parent permissions include child permissions):
- Repository pattern for data access with interfaces - `internal.*` - System operations (highest level)
- Service layer for business logic with dependency injection
- Middleware chain for authentication, logging, security
- Structured error handling with custom error types
- Comprehensive logging with zap structured logger
### Frontend Patterns
- React functional components with TypeScript
- Ant Design component library
- Context API for authentication state
- Axios for API communication
- React Router for navigation
## Permission System
Hierarchical permission scopes:
- `internal.*` - System operations
- `app.*` - Application management - `app.*` - Application management
- `token.*` - Token operations - `token.*` - Token operations
- `repo.*` - Repository access (example domain) - `repo.*` - Repository access (example domain)
- `permission.*` - Permission management - `permission.*` - Permission management
Parent permissions inherit child permissions (e.g., `repo` includes `repo.read` and `repo.write`). Example: `repo` permission includes `repo.read` and `repo.write`.
## Database Schema ## Database Schema
Key tables: ### Key Tables
- `applications` - Application definitions with HMAC keys - `applications` - Application definitions with HMAC keys
- `static_tokens` - Static API tokens - `static_tokens` - Static API tokens with prefixes
- `available_permissions` - Permission catalog - `available_permissions` - Permission catalog
- `granted_permissions` - Token-permission relationships - `granted_permissions` - Token-permission relationships
- `user_sessions` - User session tracking - `user_sessions` - User session tracking with JWT
- `audit_events` - Comprehensive audit logging
### Migration System
- Auto-runs on startup
- Located in `/migrations/`
- Uses `golang-migrate/migrate/v4`
- Supports both up and down migrations
## Code Patterns & Architecture
### Backend Patterns
- **Repository Pattern**: Data access via interfaces (`internal/repository/interfaces.go`)
- **Dependency Injection**: Services receive dependencies via constructors
- **Middleware Chain**: Security, auth, logging, rate limiting
- **Structured Errors**: Custom error types with proper HTTP status codes
- **Structured Logging**: Zap logger with JSON output
- **Configuration Provider**: Interface-based config with validation
- **Multiple Auth Providers**: Header, OAuth2, SAML support
### Frontend Patterns
- **React 19** with TypeScript
- **Ant Design 5.27+** component library
- **Context API** for authentication state (`AuthContext.tsx`)
- **Axios** for API communication with interceptors
- **React Router 7+** for navigation
- **Component Structure**: Organized by feature (Applications, Tokens, Users, Audit)
### Security Patterns
- **HMAC Token Signing**: All tokens cryptographically signed
- **JWT with Rotation**: User tokens with refresh capability
- **Rate Limiting**: Per-endpoint and per-user limits
- **CSRF Protection**: Token-based CSRF protection
- **Audit Logging**: All operations logged with user attribution
- **Input Validation**: Comprehensive validation at all layers
## Development Notes ## Development Notes
- The backend uses interfaces throughout for testability and dependency injection ### Critical Information
- Database migrations run automatically on startup - **Go Version**: Requires Go 1.23+ (currently using 1.24.4)
- Rate limiting is configurable per endpoint - **Node Version**: Requires Node 24+ and npm 11+
- All operations include audit logging with user attribution - **Database**: Auto-migrations run on startup
- Token security uses HMAC signing with rotation capabilities - **Container Names**: Use `kms-postgres`, `kms-api-service`, `kms-frontend`, `kms-nginx`
- Frontend uses protected routes with authentication context - **Default Ports**: API:8080, Nginx:8081, Frontend:3000, DB:5432, Metrics:9090
- E2E tests provide comprehensive API coverage with curl - **Test Database**: `kms_test` (separate from `kms`)
### Important Files
- `internal/config/config.go` - Complete configuration management
- `docker-compose.yml` - Service definitions and environment variables
- `test/e2e_test.sh` - Comprehensive curl-based E2E tests
- `test/README.md` - Detailed testing guide
- `docs/` - Technical documentation (Architecture, Security, API docs)
### Development Workflow
1. Always use `podman-compose` (not `docker-compose`)
2. Database operations via `podman exec` only
3. Required environment variables for local dev (HMAC, JWT, AUTH keys)
4. Run tests after changes: `go test -v ./test/...`
5. Use E2E tests to verify end-to-end functionality
6. Frontend dev server connects to containerized backend
### Security Considerations
- Never commit secrets to repository
- All tokens use HMAC signing with secure keys
- Rate limiting prevents abuse
- Comprehensive audit logging for compliance
- Input validation at all layers
- CORS and security headers properly configured