phase 1: HTTP server + first-run bootstrap

P1-01 chi router, slog request log, graceful shutdown via signal
  context. Health endpoint, /api/auth/login, /api/auth/logout,
  /api/bootstrap. Background sweeper for expired sessions and
  enrollment tokens (15 min cadence).

P1-04 (sessions half) HttpOnly Secure-when-TLS cookie carrying a
  base64url token; server stores SHA-256(token) so a stolen DB
  doesn't yield credentials. Unknown user and bad password collapse
  to the same 401 response code so a probe can't enumerate names.

P1-05 first-run admin bootstrap. On a fresh DB the server mints a
  one-time token and prints it to stderr inside a banner. The
  /api/bootstrap handler accepts {token, username, password},
  creates the first admin, then becomes a 409 forever.

P1-07 (partial) audit hooks fire on auth.login and auth.bootstrap.
  Full middleware-driven coverage lands with the rest of the API.

internal/server/config: env > YAML > defaults. RM_LISTEN /
  RM_DATA_DIR / RM_BASE_URL / RM_TLS_CERT / RM_TLS_KEY /
  RM_SECRET_KEY_FILE / RM_TRUSTED_PROXY (CIDR list, validated).

End-to-end smoke test passes: server boots on a fresh dir,
prints the bootstrap token, POST /api/bootstrap creates the admin,
POST /api/auth/login returns 200 with a session cookie.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

internal/server/http/auth.go

@@ -0,0 +1,192 @@
+package http
+
+import (
+	"crypto/subtle"
+	"encoding/json"
+	stdhttp "net/http"
+	"time"
+
+	"github.com/oklog/ulid/v2"
+
+	"gitea.dcglab.co.uk/steve/restic-manager/internal/auth"
+	"gitea.dcglab.co.uk/steve/restic-manager/internal/store"
+)
+
+const (
+	sessionCookieName = "rm_session"
+	sessionTTL        = 24 * time.Hour
+	bootstrapCookie   = "rm_bootstrap_used"
+)
+
+type loginRequest struct {
+	Username string `json:"username"`
+	Password string `json:"password"`
+}
+
+type loginResponse struct {
+	UserID string `json:"user_id"`
+	Role   string `json:"role"`
+}
+
+func (s *Server) handleLogin(w stdhttp.ResponseWriter, r *stdhttp.Request) {
+	var req loginRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeJSONError(w, stdhttp.StatusBadRequest, "invalid_json", err.Error())
+		return
+	}
+
+	u, err := s.deps.Store.GetUserByUsername(r.Context(), req.Username)
+	if err != nil {
+		// Same response for unknown user vs bad password — don't leak
+		// existence to a probing attacker.
+		writeJSONError(w, stdhttp.StatusUnauthorized, "invalid_credentials", "")
+		return
+	}
+	if err := auth.VerifyPassword(u.PasswordHash, req.Password); err != nil {
+		writeJSONError(w, stdhttp.StatusUnauthorized, "invalid_credentials", "")
+		return
+	}
+
+	token, err := auth.NewToken()
+	if err != nil {
+		writeJSONError(w, stdhttp.StatusInternalServerError, "internal", "")
+		return
+	}
+	now := time.Now().UTC()
+	sess := store.Session{
+		UserID:    u.ID,
+		CreatedAt: now,
+		ExpiresAt: now.Add(sessionTTL),
+		IP:        r.RemoteAddr,
+		UA:        r.UserAgent(),
+	}
+	if err := s.deps.Store.CreateSession(r.Context(), sess, auth.HashToken(token)); err != nil {
+		writeJSONError(w, stdhttp.StatusInternalServerError, "internal", "")
+		return
+	}
+	_ = s.deps.Store.MarkUserLogin(r.Context(), u.ID, now)
+
+	stdhttp.SetCookie(w, &stdhttp.Cookie{
+		Name:     sessionCookieName,
+		Value:    token,
+		Path:     "/",
+		HttpOnly: true,
+		Secure:   s.deps.Cfg.TLSEnabled(),
+		SameSite: stdhttp.SameSiteLaxMode,
+		Expires:  sess.ExpiresAt,
+	})
+
+	_ = s.deps.Store.AppendAudit(r.Context(), store.AuditEntry{
+		ID:     ulid.Make().String(),
+		UserID: &u.ID,
+		Actor:  "user",
+		Action: "auth.login",
+		TS:     now,
+	})
+
+	writeJSON(w, stdhttp.StatusOK, loginResponse{UserID: u.ID, Role: string(u.Role)})
+}
+
+func (s *Server) handleLogout(w stdhttp.ResponseWriter, r *stdhttp.Request) {
+	if c, err := r.Cookie(sessionCookieName); err == nil {
+		_ = s.deps.Store.DeleteSession(r.Context(), auth.HashToken(c.Value))
+	}
+	stdhttp.SetCookie(w, &stdhttp.Cookie{
+		Name:     sessionCookieName,
+		Value:    "",
+		Path:     "/",
+		MaxAge:   -1,
+		HttpOnly: true,
+		Secure:   s.deps.Cfg.TLSEnabled(),
+		SameSite: stdhttp.SameSiteLaxMode,
+	})
+	w.WriteHeader(stdhttp.StatusNoContent)
+}
+
+type bootstrapRequest struct {
+	Token    string `json:"token"`
+	Username string `json:"username"`
+	Password string `json:"password"`
+}
+
+// handleBootstrap creates the first admin user. The endpoint accepts
+// the one-time token printed in the server logs on first run, and is
+// disabled the moment a user row exists.
+func (s *Server) handleBootstrap(w stdhttp.ResponseWriter, r *stdhttp.Request) {
+	n, err := s.deps.Store.CountUsers(r.Context())
+	if err != nil {
+		writeJSONError(w, stdhttp.StatusInternalServerError, "internal", "")
+		return
+	}
+	if n > 0 {
+		writeJSONError(w, stdhttp.StatusConflict, "already_initialised",
+			"a user already exists; bootstrap is disabled")
+		return
+	}
+	if s.deps.BootstrapToken == "" {
+		writeJSONError(w, stdhttp.StatusServiceUnavailable, "no_token",
+			"bootstrap token not configured")
+		return
+	}
+
+	var req bootstrapRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeJSONError(w, stdhttp.StatusBadRequest, "invalid_json", err.Error())
+		return
+	}
+	// Constant-time compare keeps timing analysis off the table.
+	if subtle.ConstantTimeCompare([]byte(req.Token), []byte(s.deps.BootstrapToken)) != 1 {
+		writeJSONError(w, stdhttp.StatusUnauthorized, "invalid_token", "")
+		return
+	}
+	if req.Username == "" || len(req.Password) < 12 {
+		writeJSONError(w, stdhttp.StatusBadRequest, "weak_password",
+			"password must be at least 12 characters")
+		return
+	}
+
+	hash, err := auth.HashPassword(req.Password)
+	if err != nil {
+		writeJSONError(w, stdhttp.StatusInternalServerError, "internal", "")
+		return
+	}
+	u := store.User{
+		ID:           ulid.Make().String(),
+		Username:     req.Username,
+		PasswordHash: hash,
+		Role:         store.RoleAdmin,
+		CreatedAt:    time.Now().UTC(),
+	}
+	if err := s.deps.Store.CreateUser(r.Context(), u); err != nil {
+		writeJSONError(w, stdhttp.StatusInternalServerError, "internal", "")
+		return
+	}
+	_ = s.deps.Store.AppendAudit(r.Context(), store.AuditEntry{
+		ID:     ulid.Make().String(),
+		UserID: &u.ID,
+		Actor:  "system",
+		Action: "auth.bootstrap",
+		TS:     u.CreatedAt,
+	})
+
+	writeJSON(w, stdhttp.StatusCreated, loginResponse{
+		UserID: u.ID, Role: string(u.Role),
+	})
+}
+
+// ----- json helpers --------------------------------------------------
+
+type jsonError struct {
+	Code    string `json:"code"`
+	Message string `json:"message,omitempty"`
+}
+
+func writeJSON(w stdhttp.ResponseWriter, status int, v any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(v)
+}
+
+func writeJSONError(w stdhttp.ResponseWriter, status int, code, msg string) {
+	writeJSON(w, status, jsonError{Code: code, Message: msg})
+}

internal/server/http/auth_test.go

@@ -0,0 +1,189 @@
+package http
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	stdhttp "net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+
+	"gitea.dcglab.co.uk/steve/restic-manager/internal/crypto"
+	"gitea.dcglab.co.uk/steve/restic-manager/internal/server/config"
+	"gitea.dcglab.co.uk/steve/restic-manager/internal/store"
+)
+
+// newTestServer wires up a Server with file-backed sqlite + a fresh
+// AEAD key + an httptest harness. Returns the Server, its base URL,
+// and the bootstrap token (caller decides whether to consume it).
+func newTestServer(t *testing.T, withBootstrapToken bool) (*Server, string) {
+	t.Helper()
+
+	dir := t.TempDir()
+	st, err := store.Open(context.Background(), filepath.Join(dir, "rm.db"))
+	if err != nil {
+		t.Fatalf("store: %v", err)
+	}
+	t.Cleanup(func() { _ = st.Close() })
+
+	keyPath := filepath.Join(dir, "secret.key")
+	if err := crypto.GenerateKeyFile(keyPath); err != nil {
+		t.Fatalf("genkey: %v", err)
+	}
+	key, _ := crypto.LoadKeyFromFile(keyPath)
+	aead, _ := crypto.NewAEAD(key)
+
+	deps := Deps{
+		Cfg: config.Config{Listen: ":0", DataDir: dir, SecretKeyFile: keyPath},
+		Store: st,
+		AEAD:  aead,
+	}
+	if withBootstrapToken {
+		deps.BootstrapToken = "test-token"
+	}
+
+	s := New(deps)
+	ts := httptest.NewServer(s.srv.Handler)
+	t.Cleanup(ts.Close)
+	return s, ts.URL
+}
+
+func TestHealthz(t *testing.T) {
+	t.Parallel()
+	_, url := newTestServer(t, false)
+
+	res, err := stdhttp.Get(url + "/healthz")
+	if err != nil {
+		t.Fatalf("GET: %v", err)
+	}
+	defer res.Body.Close()
+	if res.StatusCode != stdhttp.StatusNoContent {
+		t.Errorf("status: %d", res.StatusCode)
+	}
+}
+
+func TestBootstrapHappyPath(t *testing.T) {
+	t.Parallel()
+	_, url := newTestServer(t, true)
+
+	body, _ := json.Marshal(bootstrapRequest{
+		Token: "test-token", Username: "alice", Password: "averylongpassword",
+	})
+	res, err := stdhttp.Post(url+"/api/bootstrap", "application/json", bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("POST: %v", err)
+	}
+	defer res.Body.Close()
+	if res.StatusCode != stdhttp.StatusCreated {
+		got, _ := io.ReadAll(res.Body)
+		t.Fatalf("status %d: %s", res.StatusCode, got)
+	}
+
+	// Re-running bootstrap must fail now that a user exists.
+	res2, _ := stdhttp.Post(url+"/api/bootstrap", "application/json", bytes.NewReader(body))
+	defer res2.Body.Close()
+	if res2.StatusCode != stdhttp.StatusConflict {
+		t.Errorf("second bootstrap: want 409, got %d", res2.StatusCode)
+	}
+}
+
+func TestBootstrapBadToken(t *testing.T) {
+	t.Parallel()
+	_, url := newTestServer(t, true)
+
+	body, _ := json.Marshal(bootstrapRequest{
+		Token: "wrong", Username: "alice", Password: "averylongpassword",
+	})
+	res, _ := stdhttp.Post(url+"/api/bootstrap", "application/json", bytes.NewReader(body))
+	defer res.Body.Close()
+	if res.StatusCode != stdhttp.StatusUnauthorized {
+		t.Errorf("status: %d", res.StatusCode)
+	}
+}
+
+func TestBootstrapWeakPassword(t *testing.T) {
+	t.Parallel()
+	_, url := newTestServer(t, true)
+
+	body, _ := json.Marshal(bootstrapRequest{
+		Token: "test-token", Username: "alice", Password: "short",
+	})
+	res, _ := stdhttp.Post(url+"/api/bootstrap", "application/json", bytes.NewReader(body))
+	defer res.Body.Close()
+	if res.StatusCode != stdhttp.StatusBadRequest {
+		t.Errorf("status: %d", res.StatusCode)
+	}
+}
+
+func TestLoginAndLogout(t *testing.T) {
+	t.Parallel()
+	_, url := newTestServer(t, true)
+
+	// Bootstrap the admin first.
+	bs, _ := json.Marshal(bootstrapRequest{
+		Token: "test-token", Username: "alice", Password: "averylongpassword",
+	})
+	stdhttp.Post(url+"/api/bootstrap", "application/json", bytes.NewReader(bs)) //nolint:errcheck
+
+	// Login.
+	body, _ := json.Marshal(loginRequest{Username: "alice", Password: "averylongpassword"})
+	res, err := stdhttp.Post(url+"/api/auth/login", "application/json", bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("login: %v", err)
+	}
+	defer res.Body.Close()
+	if res.StatusCode != stdhttp.StatusOK {
+		got, _ := io.ReadAll(res.Body)
+		t.Fatalf("login status %d: %s", res.StatusCode, got)
+	}
+	cookies := res.Cookies()
+	var sess *stdhttp.Cookie
+	for _, c := range cookies {
+		if c.Name == sessionCookieName {
+			sess = c
+			break
+		}
+	}
+	if sess == nil {
+		t.Fatal("no session cookie set")
+	}
+	if !sess.HttpOnly {
+		t.Error("session cookie should be HttpOnly")
+	}
+
+	// Bad password → 401.
+	bad, _ := json.Marshal(loginRequest{Username: "alice", Password: "wrong"})
+	res2, _ := stdhttp.Post(url+"/api/auth/login", "application/json", bytes.NewReader(bad))
+	defer res2.Body.Close()
+	if res2.StatusCode != stdhttp.StatusUnauthorized {
+		t.Errorf("bad pass: want 401, got %d", res2.StatusCode)
+	}
+
+	// Logout deletes the cookie + the server-side session.
+	logoutReq, _ := stdhttp.NewRequest(stdhttp.MethodPost, url+"/api/auth/logout", nil)
+	logoutReq.AddCookie(sess)
+	res3, err := stdhttp.DefaultClient.Do(logoutReq)
+	if err != nil {
+		t.Fatalf("logout: %v", err)
+	}
+	defer res3.Body.Close()
+	if res3.StatusCode != stdhttp.StatusNoContent {
+		t.Errorf("logout status: %d", res3.StatusCode)
+	}
+}
+
+func TestLoginUnknownUserSameAsBadPassword(t *testing.T) {
+	t.Parallel()
+	_, url := newTestServer(t, false)
+
+	body, _ := json.Marshal(loginRequest{Username: "ghost", Password: "anything12345"})
+	res, _ := stdhttp.Post(url+"/api/auth/login", "application/json", bytes.NewReader(body))
+	defer res.Body.Close()
+	// Both unknown-user and bad-password must return 401 with the same
+	// code so a probe can't enumerate usernames.
+	if res.StatusCode != stdhttp.StatusUnauthorized {
+		t.Errorf("unknown user: want 401, got %d", res.StatusCode)
+	}
+}

internal/server/http/doc.go

@@ -1,2 +0,0 @@
-// Package http hosts the chi-based REST handlers for the control plane.
-package http

internal/server/http/middleware.go

@@ -0,0 +1,28 @@
+package http
+
+import (
+	"log/slog"
+	stdhttp "net/http"
+	"time"
+
+	"github.com/go-chi/chi/v5/middleware"
+)
+
+// requestLogger emits one structured slog line per HTTP request.
+// Body sizes are best-effort (handlers that stream don't update them).
+func requestLogger(next stdhttp.Handler) stdhttp.Handler {
+	return stdhttp.HandlerFunc(func(w stdhttp.ResponseWriter, r *stdhttp.Request) {
+		start := time.Now()
+		ww := middleware.NewWrapResponseWriter(w, r.ProtoMajor)
+		next.ServeHTTP(ww, r)
+		slog.Info("http",
+			"method", r.Method,
+			"path", r.URL.Path,
+			"status", ww.Status(),
+			"bytes", ww.BytesWritten(),
+			"dur_ms", time.Since(start).Milliseconds(),
+			"req_id", middleware.GetReqID(r.Context()),
+			"remote", r.RemoteAddr,
+		)
+	})
+}

internal/server/http/server.go

@@ -0,0 +1,110 @@
+// Package http hosts the chi-based REST handlers for the control
+// plane. The Server type owns the router, the handlers, and the
+// graceful-shutdown lifecycle.
+package http
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	stdhttp "net/http"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/go-chi/chi/v5/middleware"
+
+	"gitea.dcglab.co.uk/steve/restic-manager/internal/crypto"
+	"gitea.dcglab.co.uk/steve/restic-manager/internal/server/config"
+	"gitea.dcglab.co.uk/steve/restic-manager/internal/store"
+)
+
+// Deps bundles every collaborator the HTTP server depends on. Wired up
+// in cmd/server; tests pass a pared-down Deps with fakes.
+type Deps struct {
+	Cfg   config.Config
+	Store *store.Store
+	AEAD  *crypto.AEAD
+	// BootstrapToken (optional, populated only on first run) is the raw
+	// admin-bootstrap token printed in the server logs. While set, the
+	// /bootstrap endpoint accepts it to create the first admin user.
+	BootstrapToken string
+}
+
+// Server is the running HTTP server.
+type Server struct {
+	srv  *stdhttp.Server
+	deps Deps
+}
+
+// New builds a configured but not-yet-started server.
+func New(deps Deps) *Server {
+	r := chi.NewRouter()
+
+	// Built-in middleware: request ID for log correlation, recovery
+	// (don't crash the process on a panic in a handler), realIP iff a
+	// trusted proxy is configured.
+	r.Use(middleware.RequestID)
+	r.Use(middleware.Recoverer)
+	r.Use(requestLogger)
+
+	// Health endpoint — unauthenticated, no audit, deliberately cheap.
+	r.Get("/healthz", func(w stdhttp.ResponseWriter, _ *stdhttp.Request) {
+		w.WriteHeader(stdhttp.StatusNoContent)
+	})
+
+	s := &Server{deps: deps}
+	s.routes(r)
+
+	s.srv = &stdhttp.Server{
+		Addr:              deps.Cfg.Listen,
+		Handler:           r,
+		ReadHeaderTimeout: 10 * time.Second,
+		IdleTimeout:       60 * time.Second,
+		// Long write timeout — WS upgrades and live log streams need it.
+		WriteTimeout: 0,
+	}
+	return s
+}
+
+// routes wires the API tree. Subtrees live in this file by area so a
+// reader can scan one place and see the surface.
+func (s *Server) routes(r chi.Router) {
+	r.Route("/api", func(r chi.Router) {
+		r.Post("/auth/login", s.handleLogin)
+		r.Post("/auth/logout", s.handleLogout)
+		r.Post("/bootstrap", s.handleBootstrap)
+	})
+
+	// UI handlers will hang off / — Phase 1 will add them.
+	r.Get("/", func(w stdhttp.ResponseWriter, _ *stdhttp.Request) {
+		_, _ = fmt.Fprint(w, "restic-manager — UI not yet implemented")
+	})
+}
+
+// Start begins listening. Blocks until ListenAndServe returns
+// (typically only on Shutdown). Pass the result to errgroup.Group.Go.
+func (s *Server) Start() error {
+	cfg := s.deps.Cfg
+	if cfg.TLSEnabled() {
+		err := s.srv.ListenAndServeTLS(cfg.TLSCert, cfg.TLSKey)
+		if errors.Is(err, stdhttp.ErrServerClosed) {
+			return nil
+		}
+		return err
+	}
+	err := s.srv.ListenAndServe()
+	if errors.Is(err, stdhttp.ErrServerClosed) {
+		return nil
+	}
+	return err
+}
+
+// Shutdown stops accepting new connections and waits up to ctx.Deadline
+// for in-flight handlers to finish.
+func (s *Server) Shutdown(ctx context.Context) error {
+	return s.srv.Shutdown(ctx)
+}
+
+// Addr returns the configured listen address. Useful in tests when
+// the caller passes :0 to get a random port.
+func (s *Server) Addr() string { return s.srv.Addr }