d2de49a591
Implements API key authentication for all rdev endpoints:
## Database (internal/db)
- Auto-migrating postgres connection
- Embedded SQL migrations via go:embed
- api_keys table with scopes, expiration, project restrictions
## Auth Package (internal/auth)
- Key generation: rdev_sk_<prefix>_<random> format
- Scopes: projects:read, projects:execute, keys:read, keys:write, admin
- SHA-256 key hashing (secrets never stored)
- Expiration options: 30d, 60d, 90d, 1y, never
- Middleware skips /health, /ready, /docs, /openapi.json
## Key Management API
- GET /keys - List keys (keys:read)
- POST /keys - Create key (keys:write)
- GET /keys/{id} - Get key details (keys:read)
- DELETE /keys/{id} - Revoke key (keys:write)
## Environment Variables
- DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME
- RDEV_ADMIN_KEY - Super admin key for bootstrapping
Version bumped to 0.5.0.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
564 lines
16 KiB
Go
564 lines
16 KiB
Go
// Package main provides the entry point for the rdev API server.
|
|
//
|
|
// rdev (Remote Developer) provides a REST API for controlling Claude Code
|
|
// instances running in Kubernetes pods. External clients (Discord bots,
|
|
// CLI tools, etc.) connect via this API.
|
|
//
|
|
// Authentication:
|
|
// - All endpoints (except /health, /ready, /docs) require X-API-Key header
|
|
// - Admin key from RDEV_ADMIN_KEY env var for key management
|
|
// - Create additional keys via POST /keys
|
|
//
|
|
// Endpoints:
|
|
// - GET /health - Health check (no auth)
|
|
// - GET /ready - Readiness check (no auth)
|
|
// - GET /docs - Scalar API documentation (no auth)
|
|
// - GET /openapi.json - OpenAPI 3.0 specification (no auth)
|
|
// - GET /keys - List API keys
|
|
// - POST /keys - Create API key
|
|
// - GET /keys/{id} - Get API key details
|
|
// - DELETE /keys/{id} - Revoke API key
|
|
// - GET /projects - List available projects
|
|
// - GET /projects/{id} - Get project details
|
|
// - POST /projects/{id}/claude - Run Claude command
|
|
// - POST /projects/{id}/shell - Run shell command
|
|
// - POST /projects/{id}/git - Run git command
|
|
// - GET /projects/{id}/events - SSE stream for output
|
|
package main
|
|
|
|
import (
|
|
"context"
|
|
"log/slog"
|
|
"os"
|
|
"strconv"
|
|
|
|
"github.com/orchard9/rdev/internal/auth"
|
|
"github.com/orchard9/rdev/internal/db"
|
|
"github.com/orchard9/rdev/internal/handlers"
|
|
"github.com/orchard9/rdev/pkg/api"
|
|
)
|
|
|
|
func main() {
|
|
logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
|
|
Level: slog.LevelInfo,
|
|
}))
|
|
|
|
// Load configuration from environment
|
|
cfg := loadConfig()
|
|
|
|
// Initialize database with auto-migrations
|
|
database, err := db.New(db.Config{
|
|
Host: cfg.DBHost,
|
|
Port: cfg.DBPort,
|
|
User: cfg.DBUser,
|
|
Password: cfg.DBPassword,
|
|
Database: cfg.DBName,
|
|
SSLMode: cfg.DBSSLMode,
|
|
}, logger)
|
|
if err != nil {
|
|
logger.Error("failed to connect to database", "error", err)
|
|
os.Exit(1)
|
|
}
|
|
defer database.Close()
|
|
|
|
// Initialize auth service
|
|
authService := auth.NewService(database.DB, cfg.AdminKey)
|
|
|
|
// Create app
|
|
app := api.New("rdev-api",
|
|
api.WithPort(cfg.Port),
|
|
api.WithLogger(logger),
|
|
)
|
|
|
|
// Add auth middleware (skips /health, /ready, /docs, /openapi.json)
|
|
app.Use(auth.Middleware(authService))
|
|
|
|
// Initialize handlers
|
|
projectsHandler := handlers.NewProjectsHandler()
|
|
keysHandler := handlers.NewKeysHandler(authService)
|
|
|
|
// Register routes
|
|
projectsHandler.Mount(app.Router())
|
|
keysHandler.Mount(app.Router())
|
|
|
|
// Enable API documentation
|
|
app.EnableDocs(buildOpenAPISpec())
|
|
|
|
// Cleanup on shutdown
|
|
app.OnShutdown(func(_ context.Context) error {
|
|
return database.Close()
|
|
})
|
|
|
|
logger.Info("rdev-api starting",
|
|
"port", cfg.Port,
|
|
"db_host", cfg.DBHost,
|
|
"admin_key_set", cfg.AdminKey != "",
|
|
)
|
|
|
|
app.Run()
|
|
}
|
|
|
|
// Config holds application configuration.
|
|
type Config struct {
|
|
Port int
|
|
DBHost string
|
|
DBPort int
|
|
DBUser string
|
|
DBPassword string
|
|
DBName string
|
|
DBSSLMode string
|
|
AdminKey string
|
|
}
|
|
|
|
func loadConfig() Config {
|
|
port := 8080
|
|
if v := os.Getenv("PORT"); v != "" {
|
|
if p, err := strconv.Atoi(v); err == nil {
|
|
port = p
|
|
}
|
|
}
|
|
|
|
dbPort := 5432
|
|
if v := os.Getenv("DB_PORT"); v != "" {
|
|
if p, err := strconv.Atoi(v); err == nil {
|
|
dbPort = p
|
|
}
|
|
}
|
|
|
|
return Config{
|
|
Port: port,
|
|
DBHost: getEnv("DB_HOST", "postgres.databases.svc"),
|
|
DBPort: dbPort,
|
|
DBUser: getEnv("DB_USER", "appuser"),
|
|
DBPassword: os.Getenv("DB_PASSWORD"),
|
|
DBName: getEnv("DB_NAME", "rdev"),
|
|
DBSSLMode: getEnv("DB_SSL_MODE", "disable"),
|
|
AdminKey: os.Getenv("RDEV_ADMIN_KEY"),
|
|
}
|
|
}
|
|
|
|
func getEnv(key, defaultVal string) string {
|
|
if v := os.Getenv(key); v != "" {
|
|
return v
|
|
}
|
|
return defaultVal
|
|
}
|
|
|
|
// buildOpenAPISpec creates the OpenAPI specification for the rdev API.
|
|
func buildOpenAPISpec() *api.OpenAPISpec {
|
|
spec := api.NewOpenAPISpec("rdev API", "0.5.0").
|
|
WithDescription(`Remote Developer API for controlling Claude Code instances in Kubernetes.
|
|
|
|
rdev runs Claude Code CLI in isolated pods, controlled via this REST API with SSE streaming.
|
|
External clients (Discord bots, Slack bots, CLI tools) connect here to interact with projects.
|
|
|
|
## Authentication
|
|
|
|
All endpoints except /health, /ready, and /docs require authentication via API key.
|
|
|
|
**Header**: ` + "`X-API-Key: rdev_sk_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`" + `
|
|
|
|
Or: ` + "`Authorization: Bearer rdev_sk_...`" + `
|
|
|
|
### Getting Started
|
|
|
|
1. Set RDEV_ADMIN_KEY environment variable with your super admin key
|
|
2. Use the admin key to create additional keys via POST /keys
|
|
3. Use created keys for normal operations
|
|
|
|
### Scopes
|
|
|
|
| Scope | Description |
|
|
|-------|-------------|
|
|
| projects:read | List and view projects |
|
|
| projects:execute | Run commands (claude, shell, git) |
|
|
| keys:read | List API keys (metadata only) |
|
|
| keys:write | Create and revoke keys |
|
|
| admin | Full access (all scopes) |
|
|
|
|
## Architecture
|
|
|
|
- **rdev-api**: This Go service
|
|
- **claudebox pods**: Isolated pods running Claude Code CLI
|
|
- **postgres**: API key storage (auto-migrating)
|
|
|
|
## Streaming
|
|
|
|
Command output is streamed via Server-Sent Events (SSE) at /projects/{id}/events.
|
|
`).
|
|
WithServer("http://localhost:8080", "Local development").
|
|
WithServer("http://rdev-api.rdev.svc:8080", "Kubernetes internal")
|
|
|
|
// Tags
|
|
spec.WithTag("Authentication", "API key management")
|
|
spec.WithTag("Projects", "Project management and discovery")
|
|
spec.WithTag("Commands", "Command execution (claude, shell, git)")
|
|
spec.WithTag("Events", "Server-Sent Events for real-time output")
|
|
spec.WithTag("System", "Health and readiness endpoints")
|
|
|
|
// System endpoints
|
|
spec.AddPath("/health", "get", api.Op(
|
|
"Health check",
|
|
"Returns health status. No authentication required.",
|
|
"System",
|
|
))
|
|
spec.AddPath("/ready", "get", api.Op(
|
|
"Readiness check",
|
|
"Returns readiness status. No authentication required.",
|
|
"System",
|
|
))
|
|
|
|
// Key management endpoints
|
|
spec.AddPath("/keys", "get", withAuth(
|
|
"List API keys",
|
|
"Returns all API keys with metadata (not secrets). Requires keys:read scope.",
|
|
"Authentication",
|
|
"keys:read",
|
|
`[
|
|
{
|
|
"id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"name": "discord-bot",
|
|
"key_prefix": "a1b2c3d4",
|
|
"scopes": ["projects:read", "projects:execute"],
|
|
"created_at": "2026-01-24T20:00:00Z",
|
|
"active": true
|
|
}
|
|
]`,
|
|
))
|
|
|
|
spec.AddPath("/keys", "post", withAuthAndBody(
|
|
"Create API key",
|
|
`Creates a new API key. The secret is returned only once - save it securely!
|
|
|
|
**Expiration options**: 30d, 60d, 90d, 1y, never (default: never)`,
|
|
"Authentication",
|
|
"keys:write",
|
|
`{
|
|
"name": "discord-bot",
|
|
"scopes": ["projects:read", "projects:execute"],
|
|
"project_ids": ["pantheon"],
|
|
"expires_in": "90d"
|
|
}`,
|
|
`{
|
|
"key": {
|
|
"id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"name": "discord-bot",
|
|
"key_prefix": "a1b2c3d4",
|
|
"scopes": ["projects:read", "projects:execute"],
|
|
"project_ids": ["pantheon"],
|
|
"created_at": "2026-01-24T20:00:00Z",
|
|
"expires_at": "2026-04-24T20:00:00Z",
|
|
"active": true
|
|
},
|
|
"secret": "rdev_sk_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
|
|
}`,
|
|
))
|
|
|
|
spec.AddPath("/keys/{id}", "get", withAuthAndParams(
|
|
"Get API key",
|
|
"Returns details for a specific API key. Requires keys:read scope.",
|
|
"Authentication",
|
|
"keys:read",
|
|
[]param{{Name: "id", In: "path", Description: "Key ID (UUID)", Required: true}},
|
|
))
|
|
|
|
spec.AddPath("/keys/{id}", "delete", withAuthAndParams(
|
|
"Revoke API key",
|
|
"Revokes an API key immediately. The key cannot be used after revocation. Requires keys:write scope.",
|
|
"Authentication",
|
|
"keys:write",
|
|
[]param{{Name: "id", In: "path", Description: "Key ID (UUID)", Required: true}},
|
|
))
|
|
|
|
// Projects - List and Get
|
|
spec.AddPath("/projects", "get", withAuth(
|
|
"List projects",
|
|
"Returns all available projects (claudebox pods). Requires projects:read scope.",
|
|
"Projects",
|
|
"projects:read",
|
|
`[
|
|
{
|
|
"id": "pantheon",
|
|
"name": "Pantheon",
|
|
"description": "Go API backend",
|
|
"pod": "claudebox-pantheon-0",
|
|
"status": "running"
|
|
}
|
|
]`,
|
|
))
|
|
|
|
spec.AddPath("/projects/{id}", "get", withAuthAndParams(
|
|
"Get project",
|
|
"Returns details for a specific project. Requires projects:read scope.",
|
|
"Projects",
|
|
"projects:read",
|
|
[]param{{Name: "id", In: "path", Description: "Project ID (e.g., 'pantheon')", Required: true}},
|
|
))
|
|
|
|
// Commands
|
|
spec.AddPath("/projects/{id}/claude", "post", withAuthBodyAndParams(
|
|
"Run Claude command",
|
|
"Executes a Claude Code prompt in the project's claudebox pod. Requires projects:execute scope.",
|
|
"Commands",
|
|
"projects:execute",
|
|
[]param{{Name: "id", In: "path", Description: "Project ID", Required: true}},
|
|
`{
|
|
"prompt": "fix the bug in auth handler",
|
|
"stream_id": "optional-correlation-id"
|
|
}`,
|
|
`{
|
|
"id": "cmd-pantheon-001",
|
|
"project": "pantheon",
|
|
"type": "claude",
|
|
"status": "queued",
|
|
"stream_url": "/projects/pantheon/events?stream_id=cmd-pantheon-001"
|
|
}`,
|
|
))
|
|
|
|
spec.AddPath("/projects/{id}/shell", "post", withAuthBodyAndParams(
|
|
"Run shell command",
|
|
"Executes a shell command in the project's claudebox pod. Requires projects:execute scope.",
|
|
"Commands",
|
|
"projects:execute",
|
|
[]param{{Name: "id", In: "path", Description: "Project ID", Required: true}},
|
|
`{
|
|
"command": "go test ./...",
|
|
"stream_id": "optional-correlation-id"
|
|
}`,
|
|
`{
|
|
"id": "cmd-pantheon-002",
|
|
"project": "pantheon",
|
|
"type": "shell",
|
|
"status": "queued",
|
|
"stream_url": "/projects/pantheon/events?stream_id=cmd-pantheon-002"
|
|
}`,
|
|
))
|
|
|
|
spec.AddPath("/projects/{id}/git", "post", withAuthBodyAndParams(
|
|
"Run git command",
|
|
"Executes a git command in the project's claudebox pod. Requires projects:execute scope.",
|
|
"Commands",
|
|
"projects:execute",
|
|
[]param{{Name: "id", In: "path", Description: "Project ID", Required: true}},
|
|
`{
|
|
"args": ["status"],
|
|
"stream_id": "optional-correlation-id"
|
|
}`,
|
|
`{
|
|
"id": "cmd-pantheon-003",
|
|
"project": "pantheon",
|
|
"type": "git",
|
|
"status": "queued",
|
|
"stream_url": "/projects/pantheon/events?stream_id=cmd-pantheon-003"
|
|
}`,
|
|
))
|
|
|
|
// SSE Events
|
|
spec.AddPath("/projects/{id}/events", "get", map[string]any{
|
|
"summary": "Stream events",
|
|
"description": `Server-Sent Events stream for real-time command output.
|
|
|
|
Requires projects:read scope.
|
|
|
|
## Event Types
|
|
|
|
- **connected**: Initial connection confirmation
|
|
- **output**: Command output (stdout or stderr)
|
|
- **error**: Error occurred during execution
|
|
- **complete**: Command finished (includes exit_code and duration_ms)
|
|
- **heartbeat**: Keep-alive (sent every 30s)
|
|
|
|
## Example
|
|
|
|
` + "```javascript" + `
|
|
const events = new EventSource('/projects/pantheon/events?stream_id=cmd-001', {
|
|
headers: { 'X-API-Key': 'rdev_sk_...' }
|
|
});
|
|
|
|
events.addEventListener('output', (e) => {
|
|
const data = JSON.parse(e.data);
|
|
console.log(data.line);
|
|
});
|
|
|
|
events.addEventListener('complete', (e) => {
|
|
const data = JSON.parse(e.data);
|
|
console.log('Done:', data.exit_code);
|
|
events.close();
|
|
});
|
|
` + "```",
|
|
"tags": []string{"Events"},
|
|
"security": []map[string]any{
|
|
{"ApiKeyAuth": []string{}},
|
|
},
|
|
"parameters": []map[string]any{
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"description": "Project ID",
|
|
"required": true,
|
|
"schema": map[string]any{"type": "string"},
|
|
},
|
|
{
|
|
"name": "stream_id",
|
|
"in": "query",
|
|
"description": "Command ID to filter events (optional)",
|
|
"required": false,
|
|
"schema": map[string]any{"type": "string"},
|
|
},
|
|
},
|
|
"responses": map[string]any{
|
|
"200": map[string]any{
|
|
"description": "SSE stream",
|
|
"content": map[string]any{
|
|
"text/event-stream": map[string]any{
|
|
"schema": map[string]any{
|
|
"type": "string",
|
|
"example": "event: output\ndata: {\"line\": \"Building...\", \"stream\": \"stdout\"}\n\n",
|
|
},
|
|
},
|
|
},
|
|
},
|
|
},
|
|
})
|
|
|
|
return spec
|
|
}
|
|
|
|
// param represents an OpenAPI parameter.
|
|
type param struct {
|
|
Name string
|
|
In string
|
|
Description string
|
|
Required bool
|
|
}
|
|
|
|
// withAuth creates an operation that requires authentication.
|
|
func withAuth(summary, description, tag, scope, example string) map[string]any {
|
|
return map[string]any{
|
|
"summary": summary,
|
|
"description": description + "\n\n**Required scope**: `" + scope + "`",
|
|
"tags": []string{tag},
|
|
"security": []map[string]any{
|
|
{"ApiKeyAuth": []string{}},
|
|
},
|
|
"responses": map[string]any{
|
|
"200": map[string]any{
|
|
"description": "Success",
|
|
"content": map[string]any{
|
|
"application/json": map[string]any{
|
|
"example": example,
|
|
},
|
|
},
|
|
},
|
|
"401": map[string]any{"description": "Unauthorized - Missing or invalid API key"},
|
|
"403": map[string]any{"description": "Forbidden - Insufficient permissions"},
|
|
},
|
|
}
|
|
}
|
|
|
|
// withAuthAndBody creates an operation with auth and request body.
|
|
func withAuthAndBody(summary, description, tag, scope, requestExample, responseExample string) map[string]any {
|
|
return map[string]any{
|
|
"summary": summary,
|
|
"description": description + "\n\n**Required scope**: `" + scope + "`",
|
|
"tags": []string{tag},
|
|
"security": []map[string]any{
|
|
{"ApiKeyAuth": []string{}},
|
|
},
|
|
"requestBody": map[string]any{
|
|
"required": true,
|
|
"content": map[string]any{
|
|
"application/json": map[string]any{
|
|
"example": requestExample,
|
|
},
|
|
},
|
|
},
|
|
"responses": map[string]any{
|
|
"201": map[string]any{
|
|
"description": "Created",
|
|
"content": map[string]any{
|
|
"application/json": map[string]any{
|
|
"example": responseExample,
|
|
},
|
|
},
|
|
},
|
|
"400": map[string]any{"description": "Bad Request - Invalid input"},
|
|
"401": map[string]any{"description": "Unauthorized - Missing or invalid API key"},
|
|
"403": map[string]any{"description": "Forbidden - Insufficient permissions"},
|
|
},
|
|
}
|
|
}
|
|
|
|
// withAuthAndParams creates an operation with auth and path parameters.
|
|
func withAuthAndParams(summary, description, tag, scope string, params []param) map[string]any {
|
|
parameters := make([]map[string]any, len(params))
|
|
for i, p := range params {
|
|
parameters[i] = map[string]any{
|
|
"name": p.Name,
|
|
"in": p.In,
|
|
"description": p.Description,
|
|
"required": p.Required,
|
|
"schema": map[string]any{"type": "string"},
|
|
}
|
|
}
|
|
return map[string]any{
|
|
"summary": summary,
|
|
"description": description + "\n\n**Required scope**: `" + scope + "`",
|
|
"tags": []string{tag},
|
|
"security": []map[string]any{
|
|
{"ApiKeyAuth": []string{}},
|
|
},
|
|
"parameters": parameters,
|
|
"responses": map[string]any{
|
|
"200": map[string]any{"description": "Success"},
|
|
"401": map[string]any{"description": "Unauthorized - Missing or invalid API key"},
|
|
"403": map[string]any{"description": "Forbidden - Insufficient permissions"},
|
|
"404": map[string]any{"description": "Not Found"},
|
|
},
|
|
}
|
|
}
|
|
|
|
// withAuthBodyAndParams creates an operation with auth, body, and params.
|
|
func withAuthBodyAndParams(summary, description, tag, scope string, params []param, requestExample, responseExample string) map[string]any {
|
|
parameters := make([]map[string]any, len(params))
|
|
for i, p := range params {
|
|
parameters[i] = map[string]any{
|
|
"name": p.Name,
|
|
"in": p.In,
|
|
"description": p.Description,
|
|
"required": p.Required,
|
|
"schema": map[string]any{"type": "string"},
|
|
}
|
|
}
|
|
return map[string]any{
|
|
"summary": summary,
|
|
"description": description + "\n\n**Required scope**: `" + scope + "`",
|
|
"tags": []string{tag},
|
|
"security": []map[string]any{
|
|
{"ApiKeyAuth": []string{}},
|
|
},
|
|
"parameters": parameters,
|
|
"requestBody": map[string]any{
|
|
"required": true,
|
|
"content": map[string]any{
|
|
"application/json": map[string]any{
|
|
"example": requestExample,
|
|
},
|
|
},
|
|
},
|
|
"responses": map[string]any{
|
|
"201": map[string]any{
|
|
"description": "Created",
|
|
"content": map[string]any{
|
|
"application/json": map[string]any{
|
|
"example": responseExample,
|
|
},
|
|
},
|
|
},
|
|
"400": map[string]any{"description": "Bad Request - Invalid input"},
|
|
"401": map[string]any{"description": "Unauthorized - Missing or invalid API key"},
|
|
"403": map[string]any{"description": "Forbidden - Insufficient permissions"},
|
|
},
|
|
}
|
|
}
|