skybridge/CLAUDE.md

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.

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
├── middleware/      - Authentication, logging, security middleware
├── config/          - Configuration management
└── database/        - Database connection and migrations
kms-frontend/        - React TypeScript frontend with Ant Design
migrations/          - PostgreSQL database migration files
test/               - Integration and E2E tests

Development Commands

Go Backend

# Run the server locally
go run cmd/server/main.go

# Build the binary
go build -o api-key-service ./cmd/server

# Run tests
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
npm install

# Start development server
npm start

# Build for production
npm run build

# Run tests
npm test

Docker & Development Environment

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

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

# View logs
docker-compose logs -f

# Stop services  
docker-compose down

Database Setup

The project uses PostgreSQL with automatic migrations. For local development:

# Create development database
psql -U postgres -c "CREATE DATABASE kms;"

# Create test database  
psql -U postgres -c "CREATE DATABASE kms_test;"

Testing

End-to-End Testing

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

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

Test Environments

The service provides different test user contexts on different ports:

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

Key Configuration

Environment variables for configuration:

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

The API provides:

• Health checks (/health, /ready)
• Authentication (/api/login, /api/verify, /api/renew)
• Application management (/api/applications)
• Token management (/api/applications/{id}/tokens)
• Permission hierarchies (repo.read, app.write, internal.admin, etc.)

Code Patterns

Backend Patterns

• Repository pattern for data access with interfaces
• 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
• token.* - Token operations
• repo.* - Repository access (example domain)
• permission.* - Permission management

Parent permissions inherit child permissions (e.g., repo includes repo.read and repo.write).

Database Schema

Key tables:

• applications - Application definitions with HMAC keys
• static_tokens - Static API tokens
• available_permissions - Permission catalog
• granted_permissions - Token-permission relationships
• user_sessions - User session tracking

Development Notes

• The backend uses interfaces throughout for testability and dependency injection
• Database migrations run automatically on startup
• Rate limiting is configurable per endpoint
• All operations include audit logging with user attribution
• Token security uses HMAC signing with rotation capabilities
• Frontend uses protected routes with authentication context
• E2E tests provide comprehensive API coverage with curl