slice 8A (controller half): bootstrap.json ingestion + pinned agent local-API client (v0.35.0)

internal/bootstrap: first-run bootstrap.json ingestion (decision (c)) — seed controller.yaml + skip setup; idempotent + fail-safe. internal/agentapi: minimal pinned local-API client (leaf-cert SHA-256 pin, fails closed). config LocalAPIConfig; startup /storage connectivity probe. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-10 09:47:54 +02:00
parent 086281b582
commit 2a0d9a1b7a
7 changed files with 608 additions and 0 deletions
@@ -0,0 +1,141 @@
+// Package agentapi is the in-guest controller's client for the host agent's per-guest local
+// API (doc 03 §6, slice 8A). It reaches the agent over the bridge, pinning the agent's
+// self-signed leaf by SHA-256 (the same pin convention the agent uses for the Proxmox/PBS host
+// certs), and authenticates with the per-guest bearer token. In 8A it exercises GET /storage
+// (connectivity + the controller learning its mounts); the full surface (the /backup/due
+// quiesce loop) lands in 8B.
+package agentapi
+
+import (
+	"context"
+	"crypto/sha256"
+	"crypto/tls"
+	"crypto/x509"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+)
+
+// Client talks to one agent local-API endpoint with a pinned leaf + bearer token.
+type Client struct {
+	baseURL string
+	token   string
+	hc      *http.Client
+}
+
+// MountInfo mirrors the agent's GET /storage mount entry (doc 03 §6).
+type MountInfo struct {
+	Key        string `json:"key"`
+	Storage    string `json:"storage"`
+	MountPoint string `json:"mount_point"`
+	Class      string `json:"class"` // fast | slow | ""
+	Backup     bool   `json:"backup"`
+}
+
+// StorageResponse mirrors the agent's GET /storage data payload.
+type StorageResponse struct {
+	VMID   int         `json:"vmid"`
+	Mounts []MountInfo `json:"mounts"`
+}
+
+// apiResponse is the agent's {ok,data,error} envelope.
+type apiResponse struct {
+	OK    bool            `json:"ok"`
+	Data  json.RawMessage `json:"data"`
+	Error string          `json:"error"`
+}
+
+// New builds a pinned client for endpoint ("host:port") with the given per-guest token and the
+// agent leaf-cert SHA-256 fingerprint (hex, ':'-separators tolerated). The pin is the trust
+// anchor — the agent serves a self-signed cert, so chain verification is replaced by an exact
+// leaf-DER SHA-256 match (fails closed on any mismatch).
+func New(endpoint, token, fingerprintHex string) (*Client, error) {
+	endpoint = strings.TrimSpace(endpoint)
+	if endpoint == "" {
+		return nil, fmt.Errorf("agentapi: endpoint required")
+	}
+	if token == "" {
+		return nil, fmt.Errorf("agentapi: token required")
+	}
+	want, err := normalizeFingerprint(fingerprintHex)
+	if err != nil {
+		return nil, err
+	}
+	tlsCfg := &tls.Config{
+		InsecureSkipVerify: true, // self-signed leaf — the pin below is the real check
+		VerifyPeerCertificate: func(rawCerts [][]byte, _ [][]*x509.Certificate) error {
+			if len(rawCerts) == 0 {
+				return fmt.Errorf("agentapi: TLS pin: peer presented no certificate")
+			}
+			got := sha256.Sum256(rawCerts[0]) // leaf DER
+			if hex.EncodeToString(got[:]) != want {
+				return fmt.Errorf("agentapi: TLS pin mismatch: agent leaf SHA-256 does not match the bootstrap fingerprint")
+			}
+			return nil
+		},
+		MinVersion: tls.VersionTLS12,
+	}
+	return &Client{
+		baseURL: "https://" + endpoint,
+		token:   token,
+		hc: &http.Client{
+			Timeout:   15 * time.Second,
+			Transport: &http.Transport{TLSClientConfig: tlsCfg},
+		},
+	}, nil
+}
+
+// Storage calls GET /storage and returns this guest's mounts (connectivity + placement view).
+func (c *Client) Storage(ctx context.Context) (StorageResponse, error) {
+	var out StorageResponse
+	body, err := c.get(ctx, "/storage")
+	if err != nil {
+		return out, err
+	}
+	if err := json.Unmarshal(body, &out); err != nil {
+		return out, fmt.Errorf("agentapi: decode /storage: %w", err)
+	}
+	return out, nil
+}
+
+// get issues an authenticated GET and unwraps the {ok,data,error} envelope.
+func (c *Client) get(ctx context.Context, path string) (json.RawMessage, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+path, nil)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Authorization", "Bearer "+c.token)
+	resp, err := c.hc.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("agentapi: GET %s: %w", path, err)
+	}
+	defer resp.Body.Close()
+	raw, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("agentapi: GET %s: HTTP %d", path, resp.StatusCode)
+	}
+	var env apiResponse
+	if err := json.Unmarshal(raw, &env); err != nil {
+		return nil, fmt.Errorf("agentapi: GET %s: bad envelope: %w", path, err)
+	}
+	if !env.OK {
+		return nil, fmt.Errorf("agentapi: GET %s: %s", path, env.Error)
+	}
+	return env.Data, nil
+}
+
+// normalizeFingerprint lowercases and strips ':'/' ' separators, requiring a 64-hex SHA-256.
+func normalizeFingerprint(fp string) (string, error) {
+	s := strings.ToLower(strings.NewReplacer(":", "", " ", "", "\t", "").Replace(strings.TrimSpace(fp)))
+	if len(s) != 64 {
+		return "", fmt.Errorf("agentapi: fingerprint must be a SHA-256 (64 hex chars), got %d", len(s))
+	}
+	if _, err := hex.DecodeString(s); err != nil {
+		return "", fmt.Errorf("agentapi: fingerprint is not valid hex: %w", err)
+	}
+	return s, nil
+}
@@ -0,0 +1,101 @@
+package agentapi
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// storageStub serves the agent's {ok,data} envelope for GET /storage, requiring the bearer.
+func storageStub(token string) http.Handler {
+	mux := http.NewServeMux()
+	mux.HandleFunc("GET /storage", func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("Authorization") != "Bearer "+token {
+			w.WriteHeader(http.StatusUnauthorized)
+			_, _ = w.Write([]byte(`{"ok":false,"error":"unauthorized"}`))
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"ok":true,"data":{"vmid":8200,"mounts":[{"key":"mp0","storage":"fast","mount_point":"/var/lib/docker","class":"fast","backup":true}]}}`))
+	})
+	return mux
+}
+
+func leafPin(t *testing.T, s *httptest.Server) string {
+	t.Helper()
+	der := s.Certificate().Raw
+	sum := sha256.Sum256(der)
+	return hex.EncodeToString(sum[:])
+}
+
+// The correct pin + token reaches /storage and decodes the mounts.
+func TestClient_PinnedStorageOK(t *testing.T) {
+	s := httptest.NewTLSServer(storageStub("TOK"))
+	defer s.Close()
+	endpoint := strings.TrimPrefix(s.URL, "https://")
+
+	c, err := New(endpoint, "TOK", leafPin(t, s))
+	if err != nil {
+		t.Fatalf("new: %v", err)
+	}
+	resp, err := c.Storage(context.Background())
+	if err != nil {
+		t.Fatalf("storage: %v", err)
+	}
+	if resp.VMID != 8200 || len(resp.Mounts) != 1 || resp.Mounts[0].Class != "fast" {
+		t.Fatalf("unexpected storage response: %+v", resp)
+	}
+}
+
+// A WRONG pin fails closed — the TLS handshake is rejected before any data flows.
+func TestClient_WrongPinFailsClosed(t *testing.T) {
+	s := httptest.NewTLSServer(storageStub("TOK"))
+	defer s.Close()
+	endpoint := strings.TrimPrefix(s.URL, "https://")
+
+	wrong := strings.Repeat("ab", 32) // 64 hex chars, valid format, wrong value
+	c, err := New(endpoint, "TOK", wrong)
+	if err != nil {
+		t.Fatalf("new: %v", err)
+	}
+	if _, err := c.Storage(context.Background()); err == nil {
+		t.Fatal("expected a TLS pin failure, got success")
+	}
+}
+
+// A bad fingerprint format is rejected at construction.
+func TestClient_BadFingerprintRejected(t *testing.T) {
+	if _, err := New("host:8443", "TOK", "not-a-fingerprint"); err == nil {
+		t.Fatal("expected an error for a non-SHA256 fingerprint")
+	}
+	if _, err := New("host:8443", "", strings.Repeat("a", 64)); err == nil {
+		t.Fatal("expected an error for an empty token")
+	}
+}
+
+// Colon-separated fingerprints (the agent logs them with ':') are accepted.
+func TestClient_AcceptsColonFingerprint(t *testing.T) {
+	s := httptest.NewTLSServer(storageStub("TOK"))
+	defer s.Close()
+	endpoint := strings.TrimPrefix(s.URL, "https://")
+
+	pin := leafPin(t, s)
+	var colon strings.Builder
+	for i := 0; i < len(pin); i += 2 {
+		if i > 0 {
+			colon.WriteByte(':')
+		}
+		colon.WriteString(pin[i : i+2])
+	}
+	c, err := New(endpoint, "TOK", colon.String())
+	if err != nil {
+		t.Fatalf("new with colon fp: %v", err)
+	}
+	if _, err := c.Storage(context.Background()); err != nil {
+		t.Fatalf("storage with colon fp: %v", err)
+	}
+}