feat(api): Phase 2 — REST-API MVP + CRUD für Domains/Backends/Routing

REST-API mit Response-Envelope (1:1 mail-gateway), HS256-JWT-Signer (Secret persistent unter /var/lib/edgeguard/.jwt_fingerprint), Setup-Wizard (Bcrypt-Admin-Passwort in setup.json), Auth-Middleware (Cookie + Bearer), Setup-Gate. Update-Banner-Endpoints /system/package-versions + /system/upgrade ab Tag 1 wired (Pattern aus enconf-management-agent: systemd-run detached, HTTP-Response geht VOR dem Self-Replace raus). CRUD-Repos für domains/backends/routing_rules mit pgxpool + handgeschriebenem SQL (mail-gateway-Pattern, kein GORM zur Laufzeit). Audit-Log-Schreiber auf jede Mutation, NodeID aus /etc/machine-id. DB-Pool öffnet best-effort — ohne erreichbare PG bleiben CRUD-Routen unregistriert, Auth/Setup/System antworten weiter (Dev ohne PG). End-to-end live-getestet gegen lokale postgres-16: Setup → Login → POST/PUT/DELETE Backends + Domains + Routing-Rules → audit_log schreibt 5 Zeilen mit korrektem actor/action/subject. Graceful degrade ohne DB ebenfalls verifiziert. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-09 09:56:10 +02:00
parent 106ef95f6d
commit 0a6f81beaa
18 changed files with 1925 additions and 10 deletions
--- a/internal/services/audit/audit.go
+++ b/internal/services/audit/audit.go
@@ -0,0 +1,48 @@
+// Package audit appends rows to the audit_log table. Every mutation
+// in the API funnels through this so the operator can answer
+// "who did what when?" from a single SELECT.
+package audit
+
+import (
+	"context"
+	"encoding/json"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+type Repo struct {
+	Pool *pgxpool.Pool
+}
+
+func New(pool *pgxpool.Pool) *Repo { return &Repo{Pool: pool} }
+
+// Log writes one audit_log row. detail is JSON-encodable (typically a
+// map[string]any) — empty map means "no payload". If pool is nil
+// (e.g. dev env without DB), Log silently no-ops so handlers don't
+// have to guard each call site.
+func (r *Repo) Log(ctx context.Context, actor, action, subject string, detail any, nodeID string) error {
+	if r == nil || r.Pool == nil {
+		return nil
+	}
+	var detailJSON []byte
+	if detail != nil {
+		var err error
+		detailJSON, err = json.Marshal(detail)
+		if err != nil {
+			return err
+		}
+	}
+	var subjectArg any = subject
+	if subject == "" {
+		subjectArg = nil
+	}
+	var nodeArg any = nodeID
+	if nodeID == "" {
+		nodeArg = nil
+	}
+	_, err := r.Pool.Exec(ctx,
+		`INSERT INTO audit_log (actor, action, subject, detail, node_id)
+		 VALUES ($1, $2, $3, $4, $5)`,
+		actor, action, subjectArg, detailJSON, nodeArg)
+	return err
+}
--- a/internal/services/backends/backends.go
+++ b/internal/services/backends/backends.go
@@ -0,0 +1,112 @@
+// Package backends implements CRUD against the `backends` table.
+package backends
+
+import (
+	"context"
+	"errors"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"git.netcell-it.de/projekte/edgeguard-native/internal/models"
+)
+
+var ErrNotFound = errors.New("backend not found")
+
+type Repo struct {
+	Pool *pgxpool.Pool
+}
+
+func New(pool *pgxpool.Pool) *Repo { return &Repo{Pool: pool} }
+
+const baseSelect = `
+SELECT id, name, scheme, address, port, health_check_path, active,
+       created_at, updated_at
+FROM backends
+`
+
+func (r *Repo) List(ctx context.Context) ([]models.Backend, error) {
+	rows, err := r.Pool.Query(ctx, baseSelect+" ORDER BY name ASC")
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := make([]models.Backend, 0, 16)
+	for rows.Next() {
+		b, err := scanBackend(rows)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, *b)
+	}
+	return out, rows.Err()
+}
+
+func (r *Repo) Get(ctx context.Context, id int64) (*models.Backend, error) {
+	row := r.Pool.QueryRow(ctx, baseSelect+" WHERE id = $1", id)
+	b, err := scanBackend(row)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, ErrNotFound
+		}
+		return nil, err
+	}
+	return b, nil
+}
+
+func (r *Repo) Create(ctx context.Context, b models.Backend) (*models.Backend, error) {
+	row := r.Pool.QueryRow(ctx, `
+INSERT INTO backends (name, scheme, address, port, health_check_path, active)
+VALUES ($1, $2, $3, $4, $5, $6)
+RETURNING id, name, scheme, address, port, health_check_path, active,
+          created_at, updated_at`,
+		b.Name, b.Scheme, b.Address, b.Port, b.HealthCheckPath, b.Active)
+	return scanBackend(row)
+}
+
+func (r *Repo) Update(ctx context.Context, id int64, b models.Backend) (*models.Backend, error) {
+	row := r.Pool.QueryRow(ctx, `
+UPDATE backends SET
+   name = $1,
+   scheme = $2,
+   address = $3,
+   port = $4,
+   health_check_path = $5,
+   active = $6,
+   updated_at = NOW()
+WHERE id = $7
+RETURNING id, name, scheme, address, port, health_check_path, active,
+          created_at, updated_at`,
+		b.Name, b.Scheme, b.Address, b.Port, b.HealthCheckPath, b.Active, id)
+	out, err := scanBackend(row)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, ErrNotFound
+		}
+		return nil, err
+	}
+	return out, nil
+}
+
+func (r *Repo) Delete(ctx context.Context, id int64) error {
+	tag, err := r.Pool.Exec(ctx, `DELETE FROM backends WHERE id = $1`, id)
+	if err != nil {
+		return err
+	}
+	if tag.RowsAffected() == 0 {
+		return ErrNotFound
+	}
+	return nil
+}
+
+func scanBackend(row interface{ Scan(...any) error }) (*models.Backend, error) {
+	var b models.Backend
+	if err := row.Scan(
+		&b.ID, &b.Name, &b.Scheme, &b.Address, &b.Port,
+		&b.HealthCheckPath, &b.Active,
+		&b.CreatedAt, &b.UpdatedAt,
+	); err != nil {
+		return nil, err
+	}
+	return &b, nil
+}
--- a/internal/services/domains/domains.go
+++ b/internal/services/domains/domains.go
@@ -0,0 +1,115 @@
+// Package domains implements CRUD against the `domains` table.
+package domains
+
+import (
+	"context"
+	"errors"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"git.netcell-it.de/projekte/edgeguard-native/internal/models"
+)
+
+var ErrNotFound = errors.New("domain not found")
+
+type Repo struct {
+	Pool *pgxpool.Pool
+}
+
+func New(pool *pgxpool.Pool) *Repo { return &Repo{Pool: pool} }
+
+const baseSelect = `
+SELECT id, name, active, primary_backend_id, http_to_https, hsts_enabled,
+       notes, created_at, updated_at
+FROM domains
+`
+
+func (r *Repo) List(ctx context.Context) ([]models.Domain, error) {
+	rows, err := r.Pool.Query(ctx, baseSelect+" ORDER BY name ASC")
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := make([]models.Domain, 0, 16)
+	for rows.Next() {
+		d, err := scanDomain(rows)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, *d)
+	}
+	return out, rows.Err()
+}
+
+func (r *Repo) Get(ctx context.Context, id int64) (*models.Domain, error) {
+	row := r.Pool.QueryRow(ctx, baseSelect+" WHERE id = $1", id)
+	d, err := scanDomain(row)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, ErrNotFound
+		}
+		return nil, err
+	}
+	return d, nil
+}
+
+func (r *Repo) Create(ctx context.Context, d models.Domain) (*models.Domain, error) {
+	row := r.Pool.QueryRow(ctx, `
+INSERT INTO domains (name, active, primary_backend_id, http_to_https, hsts_enabled, notes)
+VALUES ($1, $2, $3, $4, $5, $6)
+RETURNING id, name, active, primary_backend_id, http_to_https, hsts_enabled,
+          notes, created_at, updated_at`,
+		d.Name, d.Active, d.PrimaryBackendID, d.HTTPToHTTPS, d.HSTSEnabled, d.Notes)
+	return scanDomain(row)
+}
+
+func (r *Repo) Update(ctx context.Context, id int64, d models.Domain) (*models.Domain, error) {
+	row := r.Pool.QueryRow(ctx, `
+UPDATE domains SET
+   name = $1,
+   active = $2,
+   primary_backend_id = $3,
+   http_to_https = $4,
+   hsts_enabled = $5,
+   notes = $6,
+   updated_at = NOW()
+WHERE id = $7
+RETURNING id, name, active, primary_backend_id, http_to_https, hsts_enabled,
+          notes, created_at, updated_at`,
+		d.Name, d.Active, d.PrimaryBackendID, d.HTTPToHTTPS, d.HSTSEnabled, d.Notes, id)
+	out, err := scanDomain(row)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, ErrNotFound
+		}
+		return nil, err
+	}
+	return out, nil
+}
+
+func (r *Repo) Delete(ctx context.Context, id int64) error {
+	tag, err := r.Pool.Exec(ctx, `DELETE FROM domains WHERE id = $1`, id)
+	if err != nil {
+		return err
+	}
+	if tag.RowsAffected() == 0 {
+		return ErrNotFound
+	}
+	return nil
+}
+
+// scanDomain accepts both pgx.Row (Get/Create/Update) and pgx.Rows
+// (List, via the Scanner shape). pgx exposes both as a single
+// Scan(...any) error method.
+func scanDomain(row interface{ Scan(...any) error }) (*models.Domain, error) {
+	var d models.Domain
+	if err := row.Scan(
+		&d.ID, &d.Name, &d.Active, &d.PrimaryBackendID,
+		&d.HTTPToHTTPS, &d.HSTSEnabled, &d.Notes,
+		&d.CreatedAt, &d.UpdatedAt,
+	); err != nil {
+		return nil, err
+	}
+	return &d, nil
+}
--- a/internal/services/routingrules/routingrules.go
+++ b/internal/services/routingrules/routingrules.go
@@ -0,0 +1,136 @@
+// Package routingrules implements CRUD against the `routing_rules`
+// table. A rule maps (domain, path_prefix) → backend; higher priority
+// wins, ties broken by id.
+package routingrules
+
+import (
+	"context"
+	"errors"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"git.netcell-it.de/projekte/edgeguard-native/internal/models"
+)
+
+var ErrNotFound = errors.New("routing rule not found")
+
+type Repo struct {
+	Pool *pgxpool.Pool
+}
+
+func New(pool *pgxpool.Pool) *Repo { return &Repo{Pool: pool} }
+
+const baseSelect = `
+SELECT id, domain_id, path_prefix, backend_id, priority, active,
+       created_at, updated_at
+FROM routing_rules
+`
+
+// List returns rules ordered by domain_id then priority desc — the
+// shape the config-renderer wants when building haproxy/nginx vhosts.
+func (r *Repo) List(ctx context.Context) ([]models.RoutingRule, error) {
+	rows, err := r.Pool.Query(ctx, baseSelect+
+		" ORDER BY domain_id ASC, priority DESC, id ASC")
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := make([]models.RoutingRule, 0, 16)
+	for rows.Next() {
+		rr, err := scanRule(rows)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, *rr)
+	}
+	return out, rows.Err()
+}
+
+// ListForDomain narrows List to a single domain — handlers expose this
+// as GET /domains/:id/routing-rules so the UI only fetches what it needs.
+func (r *Repo) ListForDomain(ctx context.Context, domainID int64) ([]models.RoutingRule, error) {
+	rows, err := r.Pool.Query(ctx, baseSelect+
+		" WHERE domain_id = $1 ORDER BY priority DESC, id ASC", domainID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := make([]models.RoutingRule, 0, 4)
+	for rows.Next() {
+		rr, err := scanRule(rows)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, *rr)
+	}
+	return out, rows.Err()
+}
+
+func (r *Repo) Get(ctx context.Context, id int64) (*models.RoutingRule, error) {
+	row := r.Pool.QueryRow(ctx, baseSelect+" WHERE id = $1", id)
+	rr, err := scanRule(row)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, ErrNotFound
+		}
+		return nil, err
+	}
+	return rr, nil
+}
+
+func (r *Repo) Create(ctx context.Context, rr models.RoutingRule) (*models.RoutingRule, error) {
+	row := r.Pool.QueryRow(ctx, `
+INSERT INTO routing_rules (domain_id, path_prefix, backend_id, priority, active)
+VALUES ($1, $2, $3, $4, $5)
+RETURNING id, domain_id, path_prefix, backend_id, priority, active,
+          created_at, updated_at`,
+		rr.DomainID, rr.PathPrefix, rr.BackendID, rr.Priority, rr.Active)
+	return scanRule(row)
+}
+
+func (r *Repo) Update(ctx context.Context, id int64, rr models.RoutingRule) (*models.RoutingRule, error) {
+	row := r.Pool.QueryRow(ctx, `
+UPDATE routing_rules SET
+   domain_id = $1,
+   path_prefix = $2,
+   backend_id = $3,
+   priority = $4,
+   active = $5,
+   updated_at = NOW()
+WHERE id = $6
+RETURNING id, domain_id, path_prefix, backend_id, priority, active,
+          created_at, updated_at`,
+		rr.DomainID, rr.PathPrefix, rr.BackendID, rr.Priority, rr.Active, id)
+	out, err := scanRule(row)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, ErrNotFound
+		}
+		return nil, err
+	}
+	return out, nil
+}
+
+func (r *Repo) Delete(ctx context.Context, id int64) error {
+	tag, err := r.Pool.Exec(ctx, `DELETE FROM routing_rules WHERE id = $1`, id)
+	if err != nil {
+		return err
+	}
+	if tag.RowsAffected() == 0 {
+		return ErrNotFound
+	}
+	return nil
+}
+
+func scanRule(row interface{ Scan(...any) error }) (*models.RoutingRule, error) {
+	var rr models.RoutingRule
+	if err := row.Scan(
+		&rr.ID, &rr.DomainID, &rr.PathPrefix, &rr.BackendID,
+		&rr.Priority, &rr.Active,
+		&rr.CreatedAt, &rr.UpdatedAt,
+	); err != nil {
+		return nil, err
+	}
+	return &rr, nil
+}
--- a/internal/services/session/session.go
+++ b/internal/services/session/session.go
@@ -0,0 +1,167 @@
+// Package session implements signed admin-session tokens.
+//
+// Tokens are opaque strings of the form
+//
+//	base64url(payload) . base64url(HMAC-SHA256(payload))
+//
+// where payload is a small JSON ({actor, role, iat, exp}). A 32-byte
+// secret on disk (0600 edgeguard:edgeguard, generated on first use)
+// keys the HMAC. No DB round-trip for verification — handlers
+// validate the token and trust the payload.
+//
+// Pattern 1:1 nach mail-gateway/internal/services/session/. Audience-
+// Splitting (admin vs portal) und API-Key-Synthese sind bewusst nicht
+// im v1-Scope (kein Quarantine-Portal in EdgeGuard).
+package session
+
+import (
+	"crypto/hmac"
+	"crypto/rand"
+	"crypto/sha256"
+	"crypto/subtle"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+const (
+	DefaultSecretPath = "/var/lib/edgeguard/.jwt_fingerprint"
+
+	defaultTTL = 24 * time.Hour
+	secretSize = 32
+)
+
+type Token struct {
+	Actor string `json:"actor"`
+	Role  string `json:"role,omitempty"`
+	Iat   int64  `json:"iat"`
+	Exp   int64  `json:"exp"`
+}
+
+type Signer struct {
+	Secret []byte
+	Now    func() time.Time
+	TTL    time.Duration
+}
+
+// NewSignerFromPath loads or creates a 32-byte secret at path. Parent
+// dir gets 0o700, file is 0o600.
+func NewSignerFromPath(path string) (*Signer, error) {
+	if path == "" {
+		path = DefaultSecretPath
+	}
+	secret, err := loadOrCreateSecret(path)
+	if err != nil {
+		return nil, err
+	}
+	return &Signer{
+		Secret: secret,
+		Now:    func() time.Time { return time.Now().UTC() },
+		TTL:    defaultTTL,
+	}, nil
+}
+
+// NewSigner builds a signer with an in-memory secret — for tests.
+func NewSigner(secret []byte, now func() time.Time, ttl time.Duration) *Signer {
+	if now == nil {
+		now = func() time.Time { return time.Now().UTC() }
+	}
+	if ttl == 0 {
+		ttl = defaultTTL
+	}
+	return &Signer{Secret: secret, Now: now, TTL: ttl}
+}
+
+func loadOrCreateSecret(path string) ([]byte, error) {
+	if b, err := os.ReadFile(path); err == nil {
+		if len(b) < secretSize {
+			return nil, fmt.Errorf("%s is shorter than %d bytes", path, secretSize)
+		}
+		return b[:secretSize], nil
+	}
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		return nil, err
+	}
+	secret := make([]byte, secretSize)
+	if _, err := rand.Read(secret); err != nil {
+		return nil, err
+	}
+	if err := os.WriteFile(path, secret, 0o600); err != nil {
+		return nil, err
+	}
+	return secret, nil
+}
+
+// IssueWithRole returns a signed token for the given actor + role.
+func (s *Signer) IssueWithRole(actor, role string) (string, *Token, error) {
+	now := s.Now()
+	t := Token{
+		Actor: actor,
+		Role:  role,
+		Iat:   now.Unix(),
+		Exp:   now.Add(s.TTL).Unix(),
+	}
+	data, err := json.Marshal(t)
+	if err != nil {
+		return "", nil, err
+	}
+	mac := hmac.New(sha256.New, s.Secret)
+	mac.Write(data)
+	signature := mac.Sum(nil)
+	encoded := base64.RawURLEncoding.EncodeToString(data) + "." +
+		base64.RawURLEncoding.EncodeToString(signature)
+	return encoded, &t, nil
+}
+
+// Issue is IssueWithRole with empty role.
+func (s *Signer) Issue(actor string) (string, *Token, error) {
+	return s.IssueWithRole(actor, "")
+}
+
+// Verify checks a token. Returns ErrInvalidToken or ErrExpiredToken.
+func (s *Signer) Verify(raw string) (*Token, error) {
+	if raw == "" {
+		return nil, ErrInvalidToken
+	}
+	var payloadB64, sigB64 string
+	for i := 0; i < len(raw); i++ {
+		if raw[i] == '.' {
+			payloadB64 = raw[:i]
+			sigB64 = raw[i+1:]
+			break
+		}
+	}
+	if payloadB64 == "" || sigB64 == "" {
+		return nil, ErrInvalidToken
+	}
+	payload, err := base64.RawURLEncoding.DecodeString(payloadB64)
+	if err != nil {
+		return nil, ErrInvalidToken
+	}
+	sig, err := base64.RawURLEncoding.DecodeString(sigB64)
+	if err != nil {
+		return nil, ErrInvalidToken
+	}
+	mac := hmac.New(sha256.New, s.Secret)
+	mac.Write(payload)
+	if subtle.ConstantTimeCompare(mac.Sum(nil), sig) != 1 {
+		return nil, ErrInvalidToken
+	}
+	var t Token
+	if err := json.Unmarshal(payload, &t); err != nil {
+		return nil, ErrInvalidToken
+	}
+	if s.Now().Unix() >= t.Exp {
+		return nil, ErrExpiredToken
+	}
+	return &t, nil
+}
+
+var (
+	ErrInvalidToken = errors.New("invalid session token")
+	ErrExpiredToken = errors.New("session token expired")
+)
--- a/internal/services/session/session_test.go
+++ b/internal/services/session/session_test.go
@@ -0,0 +1,54 @@
+package session
+
+import (
+	"errors"
+	"testing"
+	"time"
+)
+
+func TestIssueAndVerify(t *testing.T) {
+	s := NewSigner([]byte("0123456789abcdef0123456789abcdef"), nil, time.Hour)
+	raw, tok, err := s.IssueWithRole("admin@example.com", "admin")
+	if err != nil {
+		t.Fatalf("issue: %v", err)
+	}
+	if tok.Actor != "admin@example.com" || tok.Role != "admin" {
+		t.Fatalf("token claims: %+v", tok)
+	}
+	got, err := s.Verify(raw)
+	if err != nil {
+		t.Fatalf("verify: %v", err)
+	}
+	if got.Actor != tok.Actor || got.Role != tok.Role {
+		t.Fatalf("roundtrip mismatch: %+v vs %+v", got, tok)
+	}
+}
+
+func TestVerifyRejectsTampered(t *testing.T) {
+	s := NewSigner([]byte("0123456789abcdef0123456789abcdef"), nil, time.Hour)
+	raw, _, _ := s.Issue("a")
+	tampered := raw[:len(raw)-2] + "AA"
+	if _, err := s.Verify(tampered); !errors.Is(err, ErrInvalidToken) {
+		t.Fatalf("expected ErrInvalidToken, got %v", err)
+	}
+}
+
+func TestVerifyExpired(t *testing.T) {
+	now := time.Unix(1_000_000, 0).UTC()
+	s := NewSigner([]byte("0123456789abcdef0123456789abcdef"),
+		func() time.Time { return now }, time.Minute)
+	raw, _, _ := s.Issue("a")
+
+	// shift clock forward past Exp
+	s.Now = func() time.Time { return now.Add(2 * time.Minute) }
+	if _, err := s.Verify(raw); !errors.Is(err, ErrExpiredToken) {
+		t.Fatalf("expected ErrExpiredToken, got %v", err)
+	}
+}
+
+func TestVerifyEmptyRaw(t *testing.T) {
+	s := NewSigner([]byte("0123456789abcdef0123456789abcdef"), nil, time.Hour)
+	if _, err := s.Verify(""); !errors.Is(err, ErrInvalidToken) {
+		t.Fatalf("expected ErrInvalidToken, got %v", err)
+	}
+}
--- a/internal/services/setup/setup.go
+++ b/internal/services/setup/setup.go
@@ -0,0 +1,181 @@
+// Package setup stores the one-time first-boot configuration of an
+// EdgeGuard node. State lives in setup.json inside the data dir
+// (default /var/lib/edgeguard). An incomplete or missing state means
+// the API is in "setup mode" and gates non-setup routes.
+//
+// The cluster-aware version (Phase 3) moves this to ha_nodes /
+// system_settings in PostgreSQL; the on-disk file remains the
+// first-node bootstrap record so the seed peer has somewhere to
+// write before PG holds an admin row.
+//
+// Pattern 1:1 nach mail-gateway/internal/services/setup/.
+package setup
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/mail"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"golang.org/x/crypto/bcrypt"
+)
+
+const (
+	DefaultDir  = "/var/lib/edgeguard"
+	stateFile   = "setup.json"
+	adminPwCost = 12
+)
+
+type State struct {
+	AdminEmail        string     `json:"admin_email"`
+	AdminPasswordHash string     `json:"admin_password_hash"`
+	FQDN              string     `json:"fqdn"`
+	ACMEEmail         string     `json:"acme_email"`
+	LicenseKey        string     `json:"license_key,omitempty"`
+	Completed         bool       `json:"completed"`
+	CompletedAt       *time.Time `json:"completed_at,omitempty"`
+}
+
+// Request is the JSON body POST /api/v1/setup/complete accepts.
+// AdminPassword is plaintext on the wire; the service hashes it
+// before persisting.
+type Request struct {
+	AdminEmail    string `json:"admin_email"    binding:"required,email"`
+	AdminPassword string `json:"admin_password" binding:"required,min=12"`
+	FQDN          string `json:"fqdn"           binding:"required"`
+	ACMEEmail     string `json:"acme_email"     binding:"required,email"`
+	LicenseKey    string `json:"license_key,omitempty"`
+}
+
+type Store struct {
+	Dir string
+}
+
+func NewStore(dir string) *Store { return &Store{Dir: dir} }
+
+func (s *Store) Path() string { return filepath.Join(s.Dir, stateFile) }
+
+// Load returns the current state. Missing file = zero value with
+// Completed=false (the "never set up" case), no error.
+func (s *Store) Load() (*State, error) {
+	data, err := os.ReadFile(s.Path())
+	if err != nil {
+		if os.IsNotExist(err) {
+			return &State{}, nil
+		}
+		return nil, err
+	}
+	var st State
+	if err := json.Unmarshal(data, &st); err != nil {
+		return nil, fmt.Errorf("parse setup state: %w", err)
+	}
+	return &st, nil
+}
+
+// Save writes the state atomically (write-tmp + rename). 0o600 because
+// it carries the bcrypt admin-password hash.
+func (s *Store) Save(st *State) error {
+	if err := os.MkdirAll(s.Dir, 0o700); err != nil {
+		return err
+	}
+	data, err := json.MarshalIndent(st, "", "  ")
+	if err != nil {
+		return err
+	}
+	tmp := s.Path() + ".tmp"
+	if err := os.WriteFile(tmp, data, 0o600); err != nil {
+		return err
+	}
+	return os.Rename(tmp, s.Path())
+}
+
+// Complete validates the request, hashes the password, persists. Re-
+// running with the same admin email overwrites the password (admin-
+// recovery path); a different email after completion is rejected to
+// prevent silent takeover.
+func (s *Store) Complete(req Request) (*State, error) {
+	if err := validate(req); err != nil {
+		return nil, err
+	}
+	prev, err := s.Load()
+	if err != nil {
+		return nil, err
+	}
+	if prev.Completed && prev.AdminEmail != "" &&
+		!strings.EqualFold(prev.AdminEmail, req.AdminEmail) {
+		return nil, errors.New("setup already completed under a different admin email")
+	}
+
+	hash, err := bcrypt.GenerateFromPassword([]byte(req.AdminPassword), adminPwCost)
+	if err != nil {
+		return nil, fmt.Errorf("hash admin password: %w", err)
+	}
+
+	now := time.Now().UTC()
+	st := &State{
+		AdminEmail:        strings.ToLower(strings.TrimSpace(req.AdminEmail)),
+		AdminPasswordHash: string(hash),
+		FQDN:              strings.TrimSpace(req.FQDN),
+		ACMEEmail:         strings.ToLower(strings.TrimSpace(req.ACMEEmail)),
+		LicenseKey:        strings.TrimSpace(req.LicenseKey),
+		Completed:         true,
+		CompletedAt:       &now,
+	}
+	if err := s.Save(st); err != nil {
+		return nil, err
+	}
+	return st, nil
+}
+
+// VerifyAdminPassword does constant-time bcrypt comparison.
+func (st *State) VerifyAdminPassword(plaintext string) bool {
+	return bcrypt.CompareHashAndPassword([]byte(st.AdminPasswordHash), []byte(plaintext)) == nil
+}
+
+func validate(req Request) error {
+	if _, err := mail.ParseAddress(req.AdminEmail); err != nil {
+		return fmt.Errorf("invalid admin_email: %w", err)
+	}
+	if _, err := mail.ParseAddress(req.ACMEEmail); err != nil {
+		return fmt.Errorf("invalid acme_email: %w", err)
+	}
+	if !looksLikeFQDN(req.FQDN) {
+		return fmt.Errorf("fqdn %q does not look like a fully-qualified hostname", req.FQDN)
+	}
+	if len(req.AdminPassword) < 12 {
+		return errors.New("admin_password must be at least 12 characters")
+	}
+	return nil
+}
+
+func looksLikeFQDN(s string) bool {
+	s = strings.TrimSpace(strings.TrimSuffix(s, "."))
+	if len(s) == 0 || len(s) > 253 {
+		return false
+	}
+	if !strings.Contains(s, ".") {
+		return false
+	}
+	for _, label := range strings.Split(s, ".") {
+		if len(label) == 0 || len(label) > 63 {
+			return false
+		}
+		for _, r := range label {
+			ok := r == '-' ||
+				(r >= '0' && r <= '9') ||
+				(r >= 'a' && r <= 'z') ||
+				(r >= 'A' && r <= 'Z')
+			if !ok {
+				return false
+			}
+		}
+		if label[0] == '-' || label[len(label)-1] == '-' {
+			return false
+		}
+	}
+	return true
+}