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/auth/context.go

@@ -33,3 +33,31 @@ func MustFromContext(ctx context.Context) AuthContext {
 	}
 	return a
 }
+
+const hostCtxKey contextKey = 1
+
+// HostContext is stamped into request context by host token middleware.
+type HostContext struct {
+	HostID string
+}
+
+// WithHostContext returns a new context with the given HostContext.
+func WithHostContext(ctx context.Context, h HostContext) context.Context {
+	return context.WithValue(ctx, hostCtxKey, h)
+}
+
+// HostFromContext retrieves the HostContext. Returns zero value and false if absent.
+func HostFromContext(ctx context.Context) (HostContext, bool) {
+	h, ok := ctx.Value(hostCtxKey).(HostContext)
+	return h, ok
+}
+
+// MustHostFromContext retrieves the HostContext. Panics if absent — only call
+// inside handlers behind host token middleware.
+func MustHostFromContext(ctx context.Context) HostContext {
+	h, ok := HostFromContext(ctx)
+	if !ok {
+		panic("auth: MustHostFromContext called on unauthenticated request")
+	}
+	return h
+}

internal/auth/jwt.go

@@ -8,9 +8,11 @@ import (
 )
 
 const jwtExpiry = 6 * time.Hour
+const hostJWTExpiry = 8760 * time.Hour // 1 year
 
-// Claims are the JWT payload.
+// Claims are the JWT payload for user tokens.
 type Claims struct {
+	Type   string `json:"typ,omitempty"` // empty for user tokens; used to reject host tokens
 	TeamID string `json:"team_id"`
 	Email  string `json:"email"`
 	jwt.RegisteredClaims
@@ -32,7 +34,8 @@ func SignJWT(secret []byte, userID, teamID, email string) (string, error) {
 	return token.SignedString(secret)
 }
 
-// VerifyJWT parses and validates a JWT, returning the claims on success.
+// VerifyJWT parses and validates a user JWT, returning the claims on success.
+// Rejects host JWTs (which carry a "typ" claim) to prevent cross-token confusion.
 func VerifyJWT(secret []byte, tokenStr string) (Claims, error) {
 	token, err := jwt.ParseWithClaims(tokenStr, &Claims{}, func(t *jwt.Token) (any, error) {
 		if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
@@ -47,5 +50,53 @@ func VerifyJWT(secret []byte, tokenStr string) (Claims, error) {
 	if !ok || !token.Valid {
 		return Claims{}, fmt.Errorf("invalid token claims")
 	}
+	if c.Type == "host" {
+		return Claims{}, fmt.Errorf("invalid token: host token cannot be used as user token")
+	}
+	return *c, nil
+}
+
+// HostClaims are the JWT payload for host agent tokens.
+type HostClaims struct {
+	Type   string `json:"typ"` // always "host"
+	HostID string `json:"host_id"`
+	jwt.RegisteredClaims
+}
+
+// SignHostJWT signs a long-lived (1 year) JWT for a registered host agent.
+func SignHostJWT(secret []byte, hostID string) (string, error) {
+	now := time.Now()
+	claims := HostClaims{
+		Type:   "host",
+		HostID: hostID,
+		RegisteredClaims: jwt.RegisteredClaims{
+			Subject:   hostID,
+			IssuedAt:  jwt.NewNumericDate(now),
+			ExpiresAt: jwt.NewNumericDate(now.Add(hostJWTExpiry)),
+		},
+	}
+	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
+	return token.SignedString(secret)
+}
+
+// VerifyHostJWT parses and validates a host JWT, returning the claims on success.
+// It rejects user JWTs by checking the "typ" claim.
+func VerifyHostJWT(secret []byte, tokenStr string) (HostClaims, error) {
+	token, err := jwt.ParseWithClaims(tokenStr, &HostClaims{}, func(t *jwt.Token) (any, error) {
+		if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
+			return nil, fmt.Errorf("unexpected signing method: %v", t.Header["alg"])
+		}
+		return secret, nil
+	})
+	if err != nil {
+		return HostClaims{}, fmt.Errorf("invalid token: %w", err)
+	}
+	c, ok := token.Claims.(*HostClaims)
+	if !ok || !token.Valid {
+		return HostClaims{}, fmt.Errorf("invalid token claims")
+	}
+	if c.Type != "host" {
+		return HostClaims{}, fmt.Errorf("invalid token type: expected host")
+	}
 	return *c, nil
 }