startup-starter/skybridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7ee9a9ac2c1697eee62acd060a7a4c3afea0923c
skybridge/CLAUDE.md
Ryan Copley 7ee9a9ac2c -
2025-08-25 21:44:54 -04:00

12 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

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

The project follows clean architecture principles with clear separation:

cmd/server/          - Application entry point  
internal/            - Go backend core logic
├── domain/          - Domain models and business logic
├── repository/      - Data access interfaces and PostgreSQL implementations  
├── services/        - Business logic layer
├── handlers/        - HTTP request handlers (Gin-based)
├── middleware/      - Authentication, logging, security, CSRF middleware
├── 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
kms-frontend/        - React TypeScript frontend with Ant Design
migrations/          - PostgreSQL database migration files
test/               - Integration and E2E tests (both Go and bash)
docs/               - Comprehensive technical documentation
nginx/              - Nginx configuration for reverse proxy

Development Commands

Go Backend

# Run the server locally (requires environment variables)
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
go build -o api-key-service ./cmd/server

# Run tests (uses kms_test database)
go test -v ./test/...

# Run tests with coverage
go test -v -coverprofile=coverage.out ./test/...
go tool cover -html=coverage.out -o coverage.html

# Run specific test suites
go test -v ./test/ -run TestHealthEndpoints
go test -v ./test/ -run TestApplicationCRUD
go test -v ./test/ -run TestStaticTokenWorkflow
go test -v ./test/ -run TestConcurrentRequests

React Frontend

# Navigate to frontend directory
cd kms-frontend

# Install dependencies (Node 24+, npm 11+)
npm install

# Start development server
npm start

# Build for production
npm run build

# Run tests
npm test

Podman Compose & Development Environment

CRITICAL: This project uses podman-compose, not docker-compose.

# Start all services (PostgreSQL, API, Nginx, Frontend)
podman-compose up -d

# Check service health
curl http://localhost:8081/health

# View logs
podman-compose logs -f

# View specific service logs
podman-compose logs -f api-service
podman-compose logs -f postgres

# Stop services  
podman-compose down

# Rebuild services after code changes
podman-compose up -d --build

Database Operations

CRITICAL: All database operations use podman exec commands. Never use direct psql commands.

Database Access

# Access database shell (container name: kms-postgres)
podman exec -it kms-postgres psql -U postgres -d kms

# Run SQL commands via exec
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

# 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

The project uses podman-compose for all testing environments and database operations.

End-to-End Testing

# Start test environment with podman-compose, guaranteeing that it updates with --build
podman-compose up -d --build

# Wait for services to be ready
sleep 10

# Run comprehensive E2E tests with curl
./test/e2e_test.sh

# Test against specific server and user
BASE_URL=http://localhost:8080 USER_EMAIL=admin@example.com ./test/e2e_test.sh

# Clean up test environment
podman-compose down

Go Integration Tests

# Run Go integration tests (uses kms_test database)
go test -v ./test/...

# 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

Required Environment Variables

# 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
DB_HOST=postgres  # Use 'postgres' for containers, 'localhost' for local
DB_PORT=5432  
DB_NAME=kms
DB_USER=postgres
DB_PASSWORD=postgres
DB_SSLMODE=disable

# Server
SERVER_HOST=0.0.0.0
SERVER_PORT=8080

# Authentication  
AUTH_PROVIDER=header  # or 'sso'
AUTH_HEADER_USER_EMAIL=X-User-Email

# Features
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

# Rate Limiting
RATE_LIMIT_RPS=100
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

Core Endpoints

  • Health: /health, /ready
  • Authentication: /api/login, /api/verify, /api/renew
  • Applications: /api/applications (CRUD operations)
  • Tokens: /api/applications/{id}/tokens (Static token management)
  • Audit: /api/audit/events, /api/audit/events/:id, /api/audit/stats (Audit log management)
  • Metrics: :9090/metrics (Prometheus format, if enabled)

Permission System

Hierarchical permission scopes (parent permissions include child permissions):

  • internal.* - System operations (highest level)
  • app.* - Application management
  • token.* - Token operations
  • repo.* - Repository access (example domain)
  • permission.* - Permission management

Example: repo permission includes repo.read and repo.write.

Database Schema

Key Tables

  • applications - Application definitions with HMAC keys
  • static_tokens - Static API tokens with prefixes
  • available_permissions - Permission catalog
  • granted_permissions - Token-permission relationships
  • user_sessions - User session tracking with JWT
  • audit_events - Comprehensive audit logging with fields:
    • id, type, severity, status, timestamp
    • actor_id, actor_type, actor_ip, user_agent
    • resource_id, resource_type, action, description
    • details (JSON), request_id, session_id

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)
  • Audit Integration: Real-time audit log viewing with filtering, statistics, and timeline views

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

Audit System Architecture

  • Handler: internal/handlers/audit.go - HTTP endpoints for audit data
  • Logger: internal/audit/audit.go - Core audit logging functionality
  • Repository: internal/repository/postgres/audit_repository.go - Data persistence
  • Frontend: kms-frontend/src/components/Audit.tsx - Real-time audit viewing
  • API Service: kms-frontend/src/services/apiService.ts - Frontend-backend integration
  • Event Types: Hierarchical (e.g., auth.login, app.created, token.validated)
  • Filtering: Support for date ranges, event types, statuses, users, resource types
  • Statistics: Aggregated metrics by type, severity, status, and time

Development Notes

Critical Information

  • Go Version: Requires Go 1.23+ (currently using 1.24.4)
  • Node Version: Requires Node 24+ and npm 11+
  • Database: Auto-migrations run on startup
  • Container Names: Use kms-postgres, kms-api-service, kms-frontend, kms-nginx
  • Default Ports: API:8080, Nginx:8081, Frontend:3000, DB:5432, Metrics:9090
  • 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

Build & Deployment Notes

  • Cache Issues: When code changes don't appear, use podman-compose build --no-cache
  • Route Registration: New API routes require full rebuild to appear in Gin debug logs
  • Error Handlers: Use HandleInternalError, HandleValidationError, HandleAuthenticationError
  • API Integration: Frontend components should use real API calls, not mock data
  • Field Mapping: Ensure frontend matches backend field names (e.g., actor_id vs user_id)

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