Add host registration, heartbeat, and multi-host management

Implements the full host ↔ control plane connection flow:

- Host CRUD endpoints (POST/GET/DELETE /v1/hosts) with role-based access:
  regular hosts admin-only, BYOC hosts for admins and team owners
- One-time registration token flow: admin creates host → gets token (1hr TTL
  in Redis + Postgres audit trail) → host agent registers with specs → gets
  long-lived JWT (1yr)
- Host agent registration client with automatic spec detection (arch, CPU,
  memory, disk) and token persistence to disk
- Periodic heartbeat (30s) via POST /v1/hosts/{id}/heartbeat with X-Host-Token
  auth and host ID cross-check
- Token regeneration endpoint (POST /v1/hosts/{id}/token) for retry after
  failed registration
- Tag management (add/remove/list) with team-scoped access control
- Host JWT with typ:"host" claim, cross-use prevention in both VerifyJWT and
  VerifyHostJWT
- requireHostToken middleware for host agent authentication
- DB-level race protection: RegisterHost uses AND status='pending' with
  rows-affected check; Redis GetDel for atomic token consume
- Migration for future mTLS support (cert_fingerprint, mtls_enabled columns)
- Host agent flags: --register (one-time token), --address (required ip:port)
- serviceErrToHTTP extended with "forbidden" → 403 mapping
- OpenAPI spec, .env.example, and README updated

internal/api/server.go

@@ -7,6 +7,7 @@ import (
 
 	"github.com/go-chi/chi/v5"
 	"github.com/jackc/pgx/v5/pgxpool"
+	"github.com/redis/go-redis/v9"
 
 	"git.omukk.dev/wrenn/sandbox/internal/auth/oauth"
 	"git.omukk.dev/wrenn/sandbox/internal/db"
@@ -23,7 +24,7 @@ type Server struct {
 }
 
 // New constructs the chi router and registers all routes.
-func New(queries *db.Queries, agent hostagentv1connect.HostAgentServiceClient, pool *pgxpool.Pool, jwtSecret []byte, oauthRegistry *oauth.Registry, oauthRedirectURL string) *Server {
+func New(queries *db.Queries, agent hostagentv1connect.HostAgentServiceClient, pool *pgxpool.Pool, rdb *redis.Client, jwtSecret []byte, oauthRegistry *oauth.Registry, oauthRedirectURL string) *Server {
 	r := chi.NewRouter()
 	r.Use(requestLogger())
 
@@ -31,6 +32,7 @@ func New(queries *db.Queries, agent hostagentv1connect.HostAgentServiceClient, p
 	sandboxSvc := &service.SandboxService{DB: queries, Agent: agent}
 	apiKeySvc := &service.APIKeyService{DB: queries}
 	templateSvc := &service.TemplateService{DB: queries}
+	hostSvc := &service.HostService{DB: queries, Redis: rdb, JWT: jwtSecret}
 
 	sandbox := newSandboxHandler(sandboxSvc)
 	exec := newExecHandler(queries, agent)
@@ -41,6 +43,7 @@ func New(queries *db.Queries, agent hostagentv1connect.HostAgentServiceClient, p
 	authH := newAuthHandler(queries, pool, jwtSecret)
 	oauthH := newOAuthHandler(queries, pool, jwtSecret, oauthRegistry, oauthRedirectURL)
 	apiKeys := newAPIKeyHandler(apiKeySvc)
+	hostH := newHostHandler(hostSvc, queries)
 
 	// OpenAPI spec and docs.
 	r.Get("/openapi.yaml", serveOpenAPI)
@@ -92,6 +95,30 @@ func New(queries *db.Queries, agent hostagentv1connect.HostAgentServiceClient, p
 		r.Delete("/{name}", snapshots.Delete)
 	})
 
+	// Host management.
+	r.Route("/v1/hosts", func(r chi.Router) {
+		// Unauthenticated: one-time registration token.
+		r.Post("/register", hostH.Register)
+
+		// Host-token-authenticated: heartbeat.
+		r.With(requireHostToken(jwtSecret)).Post("/{id}/heartbeat", hostH.Heartbeat)
+
+		// JWT-authenticated: host CRUD and tags.
+		r.Group(func(r chi.Router) {
+			r.Use(requireJWT(jwtSecret))
+			r.Post("/", hostH.Create)
+			r.Get("/", hostH.List)
+			r.Route("/{id}", func(r chi.Router) {
+				r.Get("/", hostH.Get)
+				r.Delete("/", hostH.Delete)
+				r.Post("/token", hostH.RegenerateToken)
+				r.Get("/tags", hostH.ListTags)
+				r.Post("/tags", hostH.AddTag)
+				r.Delete("/tags/{tag}", hostH.RemoveTag)
+			})
+		})
+	})
+
 	return &Server{router: r}
 }