@johnnyboy11234/esg-idea-contest 0.2.0 → 0.2.2

package/backend/internal/auth/session.go

@@ -0,0 +1,113 @@
+// Package auth owns login, sessions, CSRF and throttling (Backend.md §6).
+// This file is the session store (B1-07); the middleware (B1-08) builds on it.
+package auth
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/sha256"
+	"database/sql"
+	"encoding/base64"
+	"fmt"
+
+	"github.com/google/uuid"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/auth/internal/store"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/security"
+)
+
+// Session timeouts (PRD §6.5). Refresh is written at most once per 60 s
+// (OI-11), so the effective idle timeout is 29-30 minutes.
+const (
+	IdleTimeoutSeconds     = 30 * 60
+	AbsoluteTimeoutSeconds = 8 * 60 * 60
+	RefreshSeconds         = 60
+
+	idBytes = 32
+)
+
+var limits = store.Limits{
+	IdleSeconds:     IdleTimeoutSeconds,
+	AbsoluteSeconds: AbsoluteTimeoutSeconds,
+	RefreshSeconds:  RefreshSeconds,
+}
+
+// Sessions is the server-side session store. It never sees or stores a raw
+// session ID beyond the call that receives it; the table holds SHA-256 only.
+type Sessions struct {
+	DB *sql.DB
+}
+
+// New returns a session store on db.
+func New(db *sql.DB) *Sessions { return &Sessions{DB: db} }
+
+// Create issues a new session for the user and returns the ID for the cookie
+// (32 random bytes, base64url without padding). Every login calls it, so an ID
+// is never reused (no fixation).
+func (s *Sessions) Create(ctx context.Context, userID uuid.UUID) (string, error) {
+	raw := make([]byte, idBytes)
+	if _, err := rand.Read(raw); err != nil {
+		return "", fmt.Errorf("session id: %w", err)
+	}
+	if err := store.Insert(ctx, s.DB, hash(raw), userID); err != nil {
+		return "", err
+	}
+	return base64.RawURLEncoding.EncodeToString(raw), nil
+}
+
+// Validate checks the cookie value and refreshes the session in one atomic
+// statement, then returns the caller. ok is false for anything that is not a
+// live session of an enabled account: malformed, unknown, idle or absolutely
+// expired, disabled user, or removed meanwhile. err is for database failures
+// only.
+func (s *Sessions) Validate(ctx context.Context, id string) (p security.Principal, ok bool, err error) {
+	h, valid := parse(id)
+	if !valid {
+		return security.Principal{}, false, nil
+	}
+	if ok, err = store.Touch(ctx, s.DB, h, limits); err != nil || !ok {
+		return security.Principal{}, false, err
+	}
+	return store.Principal(ctx, s.DB, h)
+}
+
+// Revoke deletes one session. It is idempotent: an unknown or malformed ID is
+// not an error (logout returns 204 either way).
+func (s *Sessions) Revoke(ctx context.Context, id string) error {
+	h, valid := parse(id)
+	if !valid {
+		return nil
+	}
+	return store.Delete(ctx, s.DB, h)
+}
+
+// RevokeAll deletes every session of the user. It implements
+// account.SessionRevoker (wired in main.go; account never imports auth).
+func (s *Sessions) RevokeAll(ctx context.Context, userID uuid.UUID) error {
+	return store.DeleteByUser(ctx, s.DB, userID)
+}
+
+// Purge deletes expired sessions and returns how many; a background ticker
+// calls it. Validation never depends on it: expired rows already fail Touch.
+func (s *Sessions) Purge(ctx context.Context) (int64, error) {
+	return store.DeleteExpired(ctx, s.DB, limits)
+}
+
+// Binding returns SHA-256 of the session ID, the value the CSRF token is bound
+// to (D40). ok is false for a malformed ID.
+func Binding(id string) (b []byte, ok bool) { return parse(id) }
+
+// parse decodes a cookie value and returns its SHA-256. Anything that is not
+// exactly 32 bytes of base64url is rejected without a database call.
+func parse(id string) ([]byte, bool) {
+	raw, err := base64.RawURLEncoding.DecodeString(id)
+	if err != nil || len(raw) != idBytes {
+		return nil, false
+	}
+	return hash(raw), true
+}
+
+func hash(raw []byte) []byte {
+	sum := sha256.Sum256(raw)
+	return sum[:]
+}

package/backend/internal/auth/session_integration_test.go

@@ -0,0 +1,245 @@
+//go:build integration
+
+package auth_test
+
+import (
+	"context"
+	"crypto/sha256"
+	"database/sql"
+	"encoding/base64"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/auth"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/dbtest"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/security"
+)
+
+const bcryptHash = "$2a$10$abcdefghijklmnopqrstuuABCDEFGHIJKLMNOPQRSTUVWXYZ01234" // shape only; satisfies ck_app_user_hash
+
+func addUser(t *testing.T, db *sql.DB, empNo, role string, enabled bool) uuid.UUID {
+	t.Helper()
+	id := uuid.New()
+	var email any = empNo + "@example.com"
+	if role == "ADMIN" {
+		email = nil
+	}
+	if _, err := db.Exec(`INSERT INTO app_user (id, emp_no, name, email, password_hash, role, enabled) VALUES (?,?,?,?,?,?,?)`,
+		id.String(), empNo, "N "+empNo, email, bcryptHash, role, enabled); err != nil {
+		t.Fatal(err)
+	}
+	return id
+}
+
+// age moves a session's timestamps into the past (DB time is the only clock,
+// so tests change the rows rather than the clock).
+func age(t *testing.T, db *sql.DB, id string, created, lastAccess time.Duration) {
+	t.Helper()
+	h, _ := auth.Binding(id)
+	if _, err := db.Exec(`UPDATE session SET created_at = NOW(6) - INTERVAL ? SECOND, last_access_at = NOW(6) - INTERVAL ? SECOND WHERE id_hash = ?`,
+		int(created.Seconds()), int(lastAccess.Seconds()), h); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func lastAccess(t *testing.T, db *sql.DB, id string) time.Time {
+	t.Helper()
+	h, _ := auth.Binding(id)
+	var ts time.Time
+	if err := db.QueryRow(`SELECT last_access_at FROM session WHERE id_hash = ?`, h).Scan(&ts); err != nil {
+		t.Fatal(err)
+	}
+	return ts
+}
+
+func TestSessions(t *testing.T) {
+	db := dbtest.New(t)
+	ctx := context.Background()
+	s := auth.New(db)
+	user := addUser(t, db, "100001", "USER", true)
+
+	create := func(t *testing.T, u uuid.UUID) string {
+		t.Helper()
+		id, err := s.Create(ctx, u)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return id
+	}
+	valid := func(t *testing.T, id string) bool {
+		t.Helper()
+		_, ok, err := s.Validate(ctx, id)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return ok
+	}
+
+	t.Run("create stores only the SHA-256 and returns a 32-byte ID", func(t *testing.T) {
+		id := create(t, user)
+		raw, err := base64.RawURLEncoding.DecodeString(id)
+		if err != nil || len(raw) != 32 {
+			t.Fatalf("id %q: %d bytes, %v", id, len(raw), err)
+		}
+		sum := sha256.Sum256(raw)
+		var n int
+		if err := db.QueryRow(`SELECT COUNT(*) FROM session WHERE id_hash = ?`, sum[:]).Scan(&n); err != nil || n != 1 {
+			t.Fatalf("hash row count = %d, %v", n, err)
+		}
+		if err := db.QueryRow(`SELECT COUNT(*) FROM session WHERE id_hash = ?`, raw).Scan(&n); err != nil || n != 0 {
+			t.Fatalf("raw ID stored: %d, %v", n, err)
+		}
+	})
+
+	t.Run("every login gets a new ID", func(t *testing.T) {
+		if a, b := create(t, user), create(t, user); a == b {
+			t.Fatal("same ID twice")
+		}
+	})
+
+	t.Run("validate returns the principal with the role from app_user", func(t *testing.T) {
+		admin := addUser(t, db, "200001", "ADMIN", true)
+		p, ok, err := s.Validate(ctx, create(t, admin))
+		if err != nil || !ok {
+			t.Fatalf("validate: %v %v", ok, err)
+		}
+		want := security.Principal{UserID: admin, EmpNo: "200001", Role: security.RoleAdmin}
+		if p != want {
+			t.Fatalf("principal = %+v, want %+v", p, want)
+		}
+	})
+
+	t.Run("unknown and malformed IDs are not valid", func(t *testing.T) {
+		unknown := base64.RawURLEncoding.EncodeToString(make([]byte, 32))
+		for _, id := range []string{unknown, "", "garbage"} {
+			if valid(t, id) {
+				t.Errorf("%q accepted", id)
+			}
+		}
+	})
+
+	t.Run("matched rows count: a valid session that needs no refresh still validates", func(t *testing.T) {
+		id := create(t, user)
+		before := lastAccess(t, db, id)
+		for i := 0; i < 2; i++ {
+			if !valid(t, id) {
+				t.Fatalf("validate #%d failed although the row matched", i+1)
+			}
+		}
+		if after := lastAccess(t, db, id); !after.Equal(before) {
+			t.Fatalf("last_access_at moved inside the 60 s window: %v -> %v", before, after)
+		}
+	})
+
+	t.Run("refresh happens only when last access is older than 60 s", func(t *testing.T) {
+		id := create(t, user)
+		age(t, db, id, 0, 59*time.Second)
+		before := lastAccess(t, db, id)
+		if !valid(t, id) || !lastAccess(t, db, id).Equal(before) {
+			t.Fatal("59 s old: must validate without writing")
+		}
+		age(t, db, id, 0, 61*time.Second)
+		before = lastAccess(t, db, id)
+		if !valid(t, id) || !lastAccess(t, db, id).After(before) {
+			t.Fatal("61 s old: must validate and refresh")
+		}
+	})
+
+	t.Run("idle timeout is 30 minutes", func(t *testing.T) {
+		id := create(t, user)
+		age(t, db, id, 0, 29*time.Minute+50*time.Second)
+		if !valid(t, id) {
+			t.Fatal("29m50s idle must still be valid")
+		}
+		age(t, db, id, 0, 30*time.Minute+5*time.Second)
+		if valid(t, id) {
+			t.Fatal("30m05s idle must be expired")
+		}
+	})
+
+	t.Run("absolute timeout is 8 hours, even for an active session", func(t *testing.T) {
+		id := create(t, user)
+		age(t, db, id, 7*time.Hour+59*time.Minute, 0)
+		if !valid(t, id) {
+			t.Fatal("7h59m old must still be valid")
+		}
+		age(t, db, id, 8*time.Hour+time.Minute, 0)
+		if valid(t, id) {
+			t.Fatal("8h01m old must be expired although just used")
+		}
+	})
+
+	t.Run("disabled user is rejected on the next request", func(t *testing.T) {
+		u := addUser(t, db, "100002", "USER", true)
+		id := create(t, u)
+		if !valid(t, id) {
+			t.Fatal("enabled user must validate")
+		}
+		if _, err := db.Exec(`UPDATE app_user SET enabled = FALSE WHERE id = ?`, u.String()); err != nil {
+			t.Fatal(err)
+		}
+		if valid(t, id) {
+			t.Fatal("disabled user must not validate")
+		}
+	})
+
+	t.Run("revoke is idempotent and ends only that session", func(t *testing.T) {
+		a, b := create(t, user), create(t, user)
+		for i := 0; i < 2; i++ {
+			if err := s.Revoke(ctx, a); err != nil {
+				t.Fatal(err)
+			}
+		}
+		if err := s.Revoke(ctx, "garbage"); err != nil {
+			t.Fatal(err)
+		}
+		if valid(t, a) || !valid(t, b) {
+			t.Fatal("revoke must end a and leave b")
+		}
+	})
+
+	t.Run("revoke all ends every session of the user only", func(t *testing.T) {
+		u, other := addUser(t, db, "100003", "USER", true), addUser(t, db, "100004", "USER", true)
+		a, b, o := create(t, u), create(t, u), create(t, other)
+		if err := s.RevokeAll(ctx, u); err != nil {
+			t.Fatal(err)
+		}
+		if valid(t, a) || valid(t, b) || !valid(t, o) {
+			t.Fatal("RevokeAll must end the user's sessions and no others")
+		}
+	})
+
+	t.Run("purge removes expired sessions only", func(t *testing.T) {
+		u := addUser(t, db, "100005", "USER", true)
+		live, idle, old := create(t, u), create(t, u), create(t, u)
+		age(t, db, idle, time.Hour, time.Hour)
+		age(t, db, old, 9*time.Hour, 0)
+		n, err := s.Purge(ctx)
+		if err != nil || n < 2 {
+			t.Fatalf("purged %d, %v; want at least 2", n, err)
+		}
+		if !valid(t, live) {
+			t.Fatal("live session purged")
+		}
+		for _, id := range []string{idle, old} {
+			h, _ := auth.Binding(id)
+			var c int
+			if err := db.QueryRow(`SELECT COUNT(*) FROM session WHERE id_hash = ?`, h).Scan(&c); err != nil || c != 0 {
+				t.Fatalf("expired row still present: %d, %v", c, err)
+			}
+		}
+	})
+
+	t.Run("deleting a user deletes the sessions", func(t *testing.T) {
+		u := addUser(t, db, "100006", "USER", true)
+		id := create(t, u)
+		if _, err := db.Exec(`DELETE FROM app_user WHERE id = ?`, u.String()); err != nil {
+			t.Fatal(err)
+		}
+		if valid(t, id) {
+			t.Fatal("session survived its user")
+		}
+	})
+}

package/backend/internal/auth/session_test.go

@@ -0,0 +1,36 @@
+package auth_test
+
+import (
+	"crypto/sha256"
+	"encoding/base64"
+	"testing"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/auth"
+)
+
+func TestBindingIsSHA256OfDecodedID(t *testing.T) {
+	raw := make([]byte, 32)
+	for i := range raw {
+		raw[i] = byte(i)
+	}
+	want := sha256.Sum256(raw)
+	got, ok := auth.Binding(base64.RawURLEncoding.EncodeToString(raw))
+	if !ok || string(got) != string(want[:]) {
+		t.Fatalf("Binding = %x, %v; want %x", got, ok, want)
+	}
+}
+
+func TestBindingRejectsMalformedIDs(t *testing.T) {
+	for name, id := range map[string]string{
+		"empty":      "",
+		"not base64": "!!!",
+		"too short":  base64.RawURLEncoding.EncodeToString(make([]byte, 31)),
+		"too long":   base64.RawURLEncoding.EncodeToString(make([]byte, 33)),
+		"padded":     base64.URLEncoding.EncodeToString(make([]byte, 32)),
+		"std alpha":  base64.StdEncoding.EncodeToString([]byte{0xfb, 0xff, 0xfe, 0xfb, 0xff, 0xfe, 0xfb, 0xff, 0xfe, 0xfb, 0xff, 0xfe, 0xfb, 0xff, 0xfe, 0xfb, 0xff, 0xfe, 0xfb, 0xff, 0xfe, 0xfb, 0xff, 0xfe, 0xfb, 0xff, 0xfe, 0xfb, 0xff, 0xfe, 0xfb, 0xff}),
+	} {
+		if _, ok := auth.Binding(id); ok {
+			t.Errorf("%s: %q accepted", name, id)
+		}
+	}
+}

package/backend/internal/server/api.go

@@ -3,7 +3,9 @@ package server
 import (
 	"net/http"
 
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/account"
 	"github.com/brian-huanggg/AwardRegistration/backend/internal/api"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/auth"
 	"github.com/brian-huanggg/AwardRegistration/backend/internal/deadline"
 )
 
@@ -11,8 +13,18 @@ import (
 // module has not landed yet stay api.Unimplemented (501).
 type API struct {
 	api.Unimplemented
+	Auth     auth.Handler
+	Account  account.Handler
 	Deadline deadline.Handler
 }
 
 // GetDeadline serves GET /deadline.
 func (a API) GetDeadline(w http.ResponseWriter, r *http.Request) { a.Deadline.GetDeadline(w, r) }
+
+// Register serves POST /auth/register.
+func (a API) Register(w http.ResponseWriter, r *http.Request, _ api.RegisterParams) {
+	a.Account.Register(w, r)
+}
+
+// GetCsrfToken serves GET /auth/csrf.
+func (a API) GetCsrfToken(w http.ResponseWriter, r *http.Request) { a.Auth.GetCsrfToken(w, r) }

package/backend/internal/server/errors.go

@@ -5,10 +5,8 @@ import (
 	"encoding/json"
 	"errors"
 	"log/slog"
+	"maps"
 	"net/http"
-	"net/netip"
-
-	"github.com/go-chi/chi/v5"
 
 	"github.com/brian-huanggg/AwardRegistration/backend/internal/audit"
 	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/web"
@@ -59,37 +57,24 @@ func (a ErrorAdapter) record(r *http.Request, e *web.Error) {
 	if outcome == "" {
 		outcome = audit.Denied
 	}
-	after, _ := json.Marshal(map[string]string{"reason": e.AuditReason}) // map of strings cannot fail
+	detail := map[string]string{}
+	maps.Copy(detail, e.AuditDetail)
+	detail["reason"] = e.AuditReason // the reason always wins over a detail key
+	after, _ := json.Marshal(detail) // map of strings cannot fail
 	ev := audit.Event{
 		Action:     audit.Action(e.AuditAction),
 		Outcome:    outcome,
 		TargetType: audit.TargetType(e.AuditTargetType),
 		TargetID:   e.AuditTargetID,
 		Method:     r.Method,
-		Route:      routeTemplate(r),
+		Route:      web.RoutePattern(r),
 		Status:     e.Status,
 		ErrorCode:  string(e.Code),
-		IP:         remoteIP(r),
+		IP:         web.ClientIP(r),
 		UserAgent:  r.UserAgent(),
-		After:      after,
-	}
-	a.Audit.RecordRejected(r.Context(), ev)
-}
 
-// routeTemplate is the matched chi pattern (/api/v1/ideas/{id}), never the raw
-// path, so IDs do not leak into the log and rows group by route.
-func routeTemplate(r *http.Request) string {
-	if rc := chi.RouteContext(r.Context()); rc != nil {
-		return rc.RoutePattern()
+		SubmittedEmpNo: e.AuditSubmittedEmpNo,
+		After:          after,
 	}
-	return ""
-}
-
-// remoteIP is the TCP peer. Trusted-proxy handling is not decided yet.
-func remoteIP(r *http.Request) netip.Addr {
-	ap, err := netip.ParseAddrPort(r.RemoteAddr)
-	if err != nil {
-		return netip.Addr{}
-	}
-	return ap.Addr().Unmap()
+	a.Audit.RecordRejected(r.Context(), ev)
 }

package/backend/internal/server/errors_test.go

@@ -96,3 +96,21 @@ func TestAdapterReasonWithoutActionStillAnswers(t *testing.T) {
 }
 
 func contains(s, sub string) bool { return strings.Contains(s, sub) }
+
+func TestAdapterCarriesSubmittedEmpNoAndDetail(t *testing.T) {
+	e := web.NewError(web.CodeEmpNoTaken, "taken")
+	e.AuditReason, e.AuditAction, e.AuditOutcome = "emp_no_taken", "AUTH_REGISTER", "FAILED"
+	e.AuditSubmittedEmpNo = "089290"
+	e.AuditDetail = map[string]string{"empNo": "089290", "reason": "must not override"}
+	f := &fakeRejecter{}
+
+	rec := serve(t, server.ErrorAdapter{Audit: f}, e)
+
+	if rec.Code != 409 || len(f.got) != 1 {
+		t.Fatalf("status %d rows %d", rec.Code, len(f.got))
+	}
+	g := f.got[0]
+	if g.Outcome != audit.Failed || g.SubmittedEmpNo != "089290" || string(g.After) != `{"empNo":"089290","reason":"emp_no_taken"}` {
+		t.Fatalf("event = %+v (after %s)", g, g.After)
+	}
+}

package/backend/internal/server/public.go

@@ -0,0 +1,35 @@
+package server
+
+import "net/http"
+
+// PublicRoutes is the explicit list of operations that need no session
+// (Backend.md §3). It must equal the operations marked `security: []` in
+// api/openapi.yaml; a test locks that. B1-10 adds POST /auth/login to both. Paths include the /api/v1 prefix.
+var PublicRoutes = []struct{ Method, Path string }{
+	{http.MethodGet, "/api/v1/auth/csrf"},
+	{http.MethodPost, "/api/v1/auth/register"},
+	{http.MethodPost, "/api/v1/auth/logout"},
+	{http.MethodGet, "/api/v1/deadline"},
+}
+
+// IsPublic reports whether r is exactly one of PublicRoutes. A public path with
+// another method is not public: without a session it answers 401, with one 405.
+func IsPublic(r *http.Request) bool {
+	for _, p := range PublicRoutes {
+		if r.Method == p.Method && r.URL.Path == p.Path {
+			return true
+		}
+	}
+	return false
+}
+
+// WriteActions maps the writes that exist today to their audit action, so a
+// CSRF denial is recorded (PRD §6.11). Later PRs add their routes here, with
+// the same exact-path rule; a write on an unknown path is not audited.
+var WriteActions = map[string]string{
+	http.MethodPost + " /api/v1/auth/register": "AUTH_REGISTER",
+	http.MethodPost + " /api/v1/auth/logout":   "AUTH_LOGOUT",
+}
+
+// ActionFor returns the audit action of r, or "" when unknown.
+func ActionFor(r *http.Request) string { return WriteActions[r.Method+" "+r.URL.Path] }

package/backend/internal/server/public_test.go

@@ -0,0 +1,73 @@
+package server_test
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"slices"
+	"testing"
+
+	"github.com/getkin/kin-openapi/openapi3"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/server"
+)
+
+// The public list in code must equal the operations the spec marks
+// `security: []`; otherwise the contract and the middleware disagree.
+func TestPublicRoutesMatchOpenAPI(t *testing.T) {
+	doc, err := openapi3.NewLoader().LoadFromFile("../../api/openapi.yaml")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var want []string
+	for path, item := range doc.Paths.Map() {
+		for method, op := range item.Operations() {
+			if op.Security != nil && len(*op.Security) == 0 {
+				want = append(want, method+" /api/v1"+path)
+			}
+		}
+	}
+	var got []string
+	for _, p := range server.PublicRoutes {
+		got = append(got, p.Method+" "+p.Path)
+	}
+	slices.Sort(want)
+	slices.Sort(got)
+	if !slices.Equal(want, got) {
+		t.Errorf("PublicRoutes\n got  %v\n want %v (spec, security: [])", got, want)
+	}
+}
+
+func TestIsPublicNeedsExactMethodAndPath(t *testing.T) {
+	tests := []struct {
+		method, path string
+		want         bool
+	}{
+		{"GET", "/api/v1/auth/csrf", true},
+		{"POST", "/api/v1/auth/logout", true},
+		{"POST", "/api/v1/auth/csrf", false},
+		{"HEAD", "/api/v1/deadline", false},
+		{"GET", "/api/v1/auth/csrf/", false},
+		{"GET", "/api/v1/auth/me", false},
+		{"GET", "/api/v1/auth/../ideas", false},
+		{"GET", "/auth/csrf", false},
+	}
+	for _, tc := range tests {
+		req := httptest.NewRequestWithContext(context.Background(), tc.method, "http://x"+tc.path, nil)
+		if got := server.IsPublic(req); got != tc.want {
+			t.Errorf("%s %s = %v, want %v", tc.method, tc.path, got, tc.want)
+		}
+	}
+}
+
+func TestActionForCoversPublicWrites(t *testing.T) {
+	for _, p := range server.PublicRoutes {
+		if p.Method == http.MethodGet {
+			continue
+		}
+		r := httptest.NewRequest(p.Method, p.Path, nil)
+		if server.ActionFor(r) == "" {
+			t.Errorf("%s %s has no audit action for a CSRF denial", p.Method, p.Path)
+		}
+	}
+}

package/backend/internal/server/server.go

@@ -22,8 +22,8 @@ const (
 
 // NewPublic builds the public router. Module routes are mounted by `mount`
 // (nil in the skeleton) under the chain: request ID → access log → recover →
-// Accept check.
-func NewPublic(log *slog.Logger, mount func(chi.Router)) http.Handler {
+// extra (the session middleware, so 401 beats 406) → Accept check.
+func NewPublic(log *slog.Logger, mount func(chi.Router), extra ...func(http.Handler) http.Handler) http.Handler {
 	r := chi.NewRouter()
 	r.NotFound(web.NotFound)
 	r.MethodNotAllowed(web.MethodNotAllowed)
@@ -32,7 +32,11 @@ func NewPublic(log *slog.Logger, mount func(chi.Router)) http.Handler {
 	}
 	// The chain wraps the router instead of using r.Use: chi skips r.Use
 	// middleware (also for NotFound) while no route is registered.
-	return web.RequestID(web.AccessLog(log)(web.Recover(log)(web.AcceptCheck(r))))
+	h := web.AcceptCheck(r)
+	for i := len(extra) - 1; i >= 0; i-- {
+		h = extra[i](h)
+	}
+	return web.RequestID(web.AccessLog(log)(web.Recover(log)(h)))
 }
 
 // Check reports whether one dependency is usable; a non-nil error makes

package/backend/internal/shared/config/config.go

@@ -18,8 +18,16 @@ type Config struct {
 	LogLevel        slog.Level
 	ShutdownTimeout time.Duration // must stay below terminationGracePeriodSeconds
 	ReadyDrainDelay time.Duration // time readiness stays false before Shutdown starts
+	CSRFKey         string        // HMAC key that signs CSRF tokens (>= 32 bytes)
+	CSRFKeyPrevious string        // optional: still verifies for 8 h after a rotation
 }
 
+// DefaultCSRFKey is the throwaway key of the local profile only; every other
+// profile must set ESG_CSRF_KEY.
+const DefaultCSRFKey = "local-dev-csrf-key-not-a-secret-0000"
+
+const minCSRFKeyBytes = 32
+
 // DefaultDSN matches docker-compose.yml (throwaway local credentials). The query
 // pins UTC and matched-row counts (Backend.md §2.3).
 const DefaultDSN = "esg:esg@tcp(localhost:3306)/esg?parseTime=true&loc=UTC&time_zone=%27%2B00%3A00%27&clientFoundRows=true"
@@ -33,16 +41,27 @@ func Load(getenv func(string) string) (Config, error) {
 		return def
 	}
 	c := Config{
-		Profile:        get("ESG_PROFILE", "local"),
-		PublicAddr:     get("ESG_PUBLIC_ADDR", ":8080"),
-		ManagementAddr: get("ESG_MANAGEMENT_ADDR", ":8081"),
-		DBDSN:          get("ESG_DB_DSN", DefaultDSN),
+		Profile:         get("ESG_PROFILE", "local"),
+		PublicAddr:      get("ESG_PUBLIC_ADDR", ":8080"),
+		ManagementAddr:  get("ESG_MANAGEMENT_ADDR", ":8081"),
+		DBDSN:           get("ESG_DB_DSN", DefaultDSN),
+		CSRFKey:         getenv("ESG_CSRF_KEY"),
+		CSRFKeyPrevious: getenv("ESG_CSRF_KEY_PREVIOUS"),
 	}
 	switch c.Profile {
 	case "local", "k3s", "dev":
 	default:
 		return Config{}, fmt.Errorf("ESG_PROFILE %q: want local, k3s or dev", c.Profile)
 	}
+	if c.CSRFKey == "" && c.Profile == "local" {
+		c.CSRFKey = DefaultCSRFKey
+	}
+	if len(c.CSRFKey) < minCSRFKeyBytes {
+		return Config{}, fmt.Errorf("ESG_CSRF_KEY: need at least %d bytes", minCSRFKeyBytes)
+	}
+	if c.CSRFKeyPrevious != "" && len(c.CSRFKeyPrevious) < minCSRFKeyBytes {
+		return Config{}, fmt.Errorf("ESG_CSRF_KEY_PREVIOUS: need at least %d bytes", minCSRFKeyBytes)
+	}
 	if err := c.LogLevel.UnmarshalText([]byte(strings.ToUpper(get("ESG_LOG_LEVEL", "info")))); err != nil {
 		return Config{}, fmt.Errorf("ESG_LOG_LEVEL: %w", err)
 	}