Seed household settings at boot and serve the settings API

Port of Feature 04 task 3 (7629cab) onto Feature 04 + Feature 03.

On first boot create the single household_settings row with the zone from
MEALQUEST_DEFAULT_TZ and the seed times and days (dinner 17:30, reminder
16:30, rotation check 09:00, plan draft Fri 09:00, suggestions Sun 08:00,
chat autosend Sat 08:00). An existing row is never overwritten.

Add household.SettingsService with Get, a validating Update (IANA zone,
zero-padded 24-hour HH:MM, day of week 0-6) that records updated_by, and
in-process Subscribe for the scheduler. Serve it as GET and PATCH
/api/v1/settings/household; invalid input is a 400 in the standard error
body. Migration 0002 adds household_settings.updated_by. Link time/tzdata
from internal/household so zones load in the minimal image.

Review fixes:
- F1: the settings routes are mounted on the protected /api/v1 subrouter,
  so they need a session (RequireSession) and, for PATCH, the CSRF token.
  updated_by is the session actor's subject from auth.ActorFrom; the
  duplicate internal/actor package is dropped, and Update refuses an empty
  member instead of storing NULL. A test drives PATCH through the
  production router with a real SessionManager session.
- F2: config no longer validates MEALQUEST_DEFAULT_TZ. Seeding requires a
  valid zone only when it creates the row (ErrNoDefaultZone,
  ErrInvalidDefaultZone, both naming the variable at boot), so a reboot
  over existing settings ignores a missing or invalid default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

README.md

@@ -30,14 +30,38 @@ export MEALQUEST_PUBLIC_URL=http://localhost:5173
 export MEALQUEST_DATA_DIR="$HOME/.mealquest-dev"
 export MEALQUEST_SHUTDOWN_TIMEOUT=10s
 export MEALQUEST_SECRET_KEY_FILE="$HOME/.mealquest-dev/secret_key"
+# Authentik OAuth2/OpenID provider for MealQuest (redirect URI:
+# $MEALQUEST_PUBLIC_URL/auth/callback). Save its client secret to the file.
+export MEALQUEST_OIDC_ISSUER=https://auth.example.com/application/o/mealquest/
+export MEALQUEST_OIDC_CLIENT_ID=mealquest
+export MEALQUEST_OIDC_CLIENT_SECRET_FILE="$HOME/.mealquest-dev/oidc_client_secret"
+export MEALQUEST_OIDC_ALLOWED_GROUPS=mealquest-admin
+# Optional: sessions end after MEALQUEST_SESSION_IDLE unused (default 720h)
+# and always MEALQUEST_SESSION_MAX after sign-in (default 4320h).
+# export MEALQUEST_SESSION_IDLE=720h
+# export MEALQUEST_SESSION_MAX=4320h
+# Optional: comma-separated IPs/CIDRs of reverse proxies whose
+# X-Forwarded-For/-Proto headers are honoured (production: Traefik). Unset
+# trusts no peer, which is right for local development.
+# export MEALQUEST_TRUSTED_PROXY=10.60.1.33
+export MEALQUEST_DEFAULT_TZ=America/New_York
 make dev
 ```
 
 `make dev` runs the Go server on `:8080` and the Vite dev server on `:5173`
 (which proxies `/api`, `/auth` and `/media` to `:8080`). Open
 http://localhost:5173. Configuration is environment-only and fails fast:
-every variable above is required, and secrets are read only from files named
-by `*_FILE` variables.
+every variable above is required except the commented-out session
+lifetimes (when set they must be positive, with MAX at least IDLE),
+trusted proxy list (every entry must be an IP or CIDR) and
+`MEALQUEST_DEFAULT_TZ`, and
+secrets are read only from files named by `*_FILE` variables. `MEALQUEST_PUBLIC_URL`, `MEALQUEST_OIDC_ISSUER` and the
+endpoints the issuer advertises must be `https://`; plain `http://` is
+accepted only for `localhost`, `127.0.0.1` and `[::1]`.
+`MEALQUEST_DEFAULT_TZ` is the IANA zone the household settings are created
+with on first boot: until those settings exist, boot fails unless it is a
+valid IANA zone. Later boots ignore it, set or not (change the zone in
+household settings instead).
 
 ## Common commands
 

cmd/server/boot_test.go

@@ -16,6 +16,7 @@ import (
 	"time"
 
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/config"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/secretbox"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
@@ -34,15 +35,29 @@ func useBootMigrations(t *testing.T, m fstest.MapFS) {
 // holds keyFile. Tests that call it must not run in parallel.
 func loadConfig(t *testing.T, keyFile string) config.Config {
 	t.Helper()
-	keyPath := filepath.Join(t.TempDir(), "secret_key")
+	dir := t.TempDir()
+	keyPath := filepath.Join(dir, "secret_key")
 	if err := os.WriteFile(keyPath, []byte(keyFile), 0o600); err != nil {
 		t.Fatal(err)
 	}
+	clientSecretPath := filepath.Join(dir, "oidc_client_secret")
+	if err := os.WriteFile(clientSecretPath, []byte("client-secret\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
 	t.Setenv(config.EnvHTTPAddr, "127.0.0.1:0")
 	t.Setenv(config.EnvPublicURL, "http://localhost")
 	t.Setenv(config.EnvDataDir, t.TempDir())
 	t.Setenv(config.EnvShutdownTimeout, "1s")
 	t.Setenv(config.EnvSecretKeyFile, keyPath)
+	t.Setenv(config.EnvOIDCIssuer, "https://auth.example.com/application/o/mealquest/")
+	t.Setenv(config.EnvOIDCClientID, "mealquest")
+	t.Setenv(config.EnvOIDCClientSecretFile, clientSecretPath)
+	t.Setenv(config.EnvOIDCAllowedGroups, "mealquest-admin")
+	// MEALQUEST_DEFAULT_TZ is left unset; t.Setenv restores any outer value.
+	t.Setenv(config.EnvDefaultTZ, "")
+	if err := os.Unsetenv(config.EnvDefaultTZ); err != nil {
+		t.Fatal(err)
+	}
 	cfg, err := config.Load()
 	if err != nil {
 		t.Fatal(err)
@@ -193,3 +208,125 @@ func TestLoadMissingSecretKeyFileStopsBoot(t *testing.T) {
 		t.Fatalf("Load error = %v, want a config error naming %s", err, config.EnvSecretKeyFile)
 	}
 }
+
+func TestRunWithoutValidDefaultZoneOnFirstBootStops(t *testing.T) {
+	tests := []struct {
+		name      string
+		defaultTZ *string // nil leaves MEALQUEST_DEFAULT_TZ unset
+		want      error
+	}{
+		{"unset", nil, household.ErrNoDefaultZone},
+		{"not an IANA zone", ptr("Mars/Olympus_Mons"), household.ErrInvalidDefaultZone},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			loadConfig(t, validKeyFile(t))
+			if tt.defaultTZ != nil {
+				t.Setenv(config.EnvDefaultTZ, *tt.defaultTZ)
+			}
+			cfg, err := config.Load()
+			if err != nil {
+				t.Fatal(err)
+			}
+			var logs bytes.Buffer
+			errc := make(chan error, 1)
+			go func() { errc <- run(cfg, slog.New(slog.NewJSONHandler(&logs, nil))) }()
+
+			select {
+			case err = <-errc:
+			case <-time.After(10 * time.Second):
+				t.Fatal("run kept going with no household settings and no valid default zone")
+			}
+			if !errors.Is(err, tt.want) || !strings.Contains(err.Error(), config.EnvDefaultTZ) {
+				t.Fatalf("run error = %v, want %v naming %s", err, tt.want, config.EnvDefaultTZ)
+			}
+			if strings.Contains(logs.String(), `"listening"`) {
+				t.Errorf("run started listening without household settings: %s", logs.String())
+			}
+		})
+	}
+}
+
+// A reboot over existing household settings must not depend on
+// MEALQUEST_DEFAULT_TZ: config.Load accepts an invalid value and seeding
+// ignores it, keeping the stored zone.
+func TestRebootWithSettingsIgnoresInvalidDefaultZone(t *testing.T) {
+	ctx := context.Background()
+	cfg := loadConfig(t, validKeyFile(t))
+
+	db, err := openStore(ctx, cfg.DataDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := seedSettings(ctx, db, "America/Denver"); err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	t.Setenv(config.EnvDefaultTZ, "Mars/Olympus_Mons")
+	cfg, err = config.Load()
+	if err != nil {
+		t.Fatalf("Load with an invalid %s and existing settings: %v", config.EnvDefaultTZ, err)
+	}
+	db, err = openStore(ctx, cfg.DataDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := db.Close(); err != nil {
+			t.Error(err)
+		}
+	})
+	if err := seedSettings(ctx, db, cfg.DefaultTZ); err != nil {
+		t.Fatalf("reboot with %s=%q: %v", config.EnvDefaultTZ, cfg.DefaultTZ, err)
+	}
+	got, err := household.NewSettingsService(db).Get(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.Timezone != "America/Denver" {
+		t.Errorf("timezone after reboot = %q, want America/Denver", got.Timezone)
+	}
+}
+
+func ptr[T any](v T) *T { return &v }
+
+func TestSeedSettingsAtBoot(t *testing.T) {
+	ctx := context.Background()
+	dir := t.TempDir()
+
+	// First boot seeds from the default zone.
+	db, err := openStore(ctx, dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := seedSettings(ctx, db, "America/Denver"); err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	// A later boot needs no default zone and keeps the stored one.
+	db, err = openStore(ctx, dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := db.Close(); err != nil {
+			t.Error(err)
+		}
+	})
+	if err := seedSettings(ctx, db, ""); err != nil {
+		t.Fatalf("reboot without %s: %v", config.EnvDefaultTZ, err)
+	}
+	got, err := household.NewSettingsService(db).Get(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.Timezone != "America/Denver" {
+		t.Errorf("timezone after reboot = %q, want America/Denver", got.Timezone)
+	}
+}

cmd/server/main.go

@@ -13,8 +13,11 @@ import (
 	"syscall"
 	"time"
 
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/auth"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/config"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/forwarded"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/frontend"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/secretbox"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/server"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
@@ -31,7 +34,7 @@ func main() {
 		os.Exit(1)
 	}
 
-	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+	logger := slog.New(forwarded.LogHandler(slog.NewJSONHandler(os.Stdout, nil)))
 	if err := run(cfg, logger); err != nil {
 		logger.Error("server stopped", "error", err)
 		os.Exit(1)
@@ -56,7 +59,28 @@ func run(cfg config.Config, logger *slog.Logger) error {
 		}
 	}()
 
-	router, err := server.NewRouter(logger, version, frontend.Assets())
+	if err := seedSettings(ctx, db, cfg.DefaultTZ); err != nil {
+		return err
+	}
+	settings := household.NewSettingsService(db)
+
+	sessions, err := auth.NewSessionManager(db, cfg.SessionIdle, cfg.SessionMax)
+	if err != nil {
+		return err
+	}
+	authFlow, err := auth.New(ctx, auth.Config{
+		Issuer:        cfg.OIDCIssuer.String(),
+		ClientID:      cfg.OIDCClientID,
+		ClientSecret:  cfg.OIDCClientSecret.Reveal(),
+		PublicURL:     cfg.PublicURL,
+		SecretKey:     []byte(cfg.SecretKey.Reveal()),
+		AllowedGroups: cfg.OIDCAllowedGroups,
+	}, sessions, logger)
+	if err != nil {
+		return err
+	}
+
+	router, err := server.NewRouter(logger, version, cfg.TrustedProxy, authFlow, sessions, settings, frontend.Assets())
 	if err != nil {
 		return err
 	}
@@ -118,12 +142,24 @@ func openStore(ctx context.Context, dataDir string) (*store.Store, error) {
 	return db, nil
 }
 
+// seedSettings creates the household settings on first boot, naming the
+// variable that supplies the zone when it is missing or invalid. Once the
+// settings exist the variable is ignored.
+func seedSettings(ctx context.Context, db *store.Store, defaultTZ string) error {
+	err := household.SeedSettings(ctx, db, defaultTZ)
+	if errors.Is(err, household.ErrNoDefaultZone) || errors.Is(err, household.ErrInvalidDefaultZone) {
+		return fmt.Errorf("%s: a valid IANA zone is required on first boot to create the household settings: %w", config.EnvDefaultTZ, err)
+	}
+	return err
+}
+
 // logListening logs the startup line. Only the public URL's origin is logged
 // so no credential-bearing URL component can reach the log.
 func logListening(logger *slog.Logger, cfg config.Config) {
 	logger.Info("listening",
 		"addr", cfg.HTTPAddr,
 		"public_origin", cfg.PublicOrigin(),
+		"trusted_proxy", cfg.TrustedProxy,
 		"data_dir", cfg.DataDir,
 		"version", version,
 	)

docs/ARCHITECTURE.md

@@ -29,6 +29,15 @@ docker compose project "mealquest" — 10.60.1.14
 One Go service serves the API, the auth flow, media and the PWA. Its SQLite
 database is replicated by Litestream to the NAS.
 
+Traefik terminates TLS. The service honours `X-Forwarded-For` and
+`X-Forwarded-Proto` only from peers listed in `MEALQUEST_TRUSTED_PROXY`
+(comma-separated IPs/CIDRs; production lists `10.60.1.33`); from any other
+peer they are ignored. The client is the rightmost `X-Forwarded-For` address
+that is not a trusted proxy. The resolved client IP is added as `client_ip`
+to every log line written while handling a request. The OIDC redirect URI
+and the Secure cookies are fixed by `MEALQUEST_PUBLIC_URL`, never by request
+headers, so sign-in works whichever peer the request arrives from.
+
 ## Repository layout
 
 | Path | Purpose |

go.mod

@@ -3,13 +3,16 @@ module code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest
 go 1.25.0
 
 require (
+	github.com/coreos/go-oidc/v3 v3.21.0
 	github.com/go-chi/chi/v5 v5.3.1
 	github.com/oklog/ulid/v2 v2.1.2
+	golang.org/x/oauth2 v0.36.0
 	modernc.org/sqlite v1.59.0
 )
 
 require (
 	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/go-jose/go-jose/v4 v4.1.4 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/mattn/go-isatty v0.0.24 // indirect
 	github.com/ncruces/go-strftime v1.0.0 // indirect

go.sum

@@ -1,7 +1,11 @@
+github.com/coreos/go-oidc/v3 v3.21.0 h1:wZo4Q9Pum8dYEj0eMUPrqR+kvuGkeUplbLpNCkBqoWM=
+github.com/coreos/go-oidc/v3 v3.21.0/go.mod h1:DYCf24+ncYi+XkIH97GY1+dqoRlbaSI26KVTCI9SrY4=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/go-chi/chi/v5 v5.3.1 h1:3j4HZLGZQ3JpMCrPJF/Jl3mYJfWLKBfNJ6quurUGCf8=
 github.com/go-chi/chi/v5 v5.3.1/go.mod h1:R+tYY2hNuVUUjxoPtqUdgBqevM9s9njzkTLutVsOCto=
+github.com/go-jose/go-jose/v4 v4.1.4 h1:moDMcTHmvE6Groj34emNPLs/qtYXRVcd6S7NHbHz3kA=
+github.com/go-jose/go-jose/v4 v4.1.4/go.mod h1:x4oUasVrzR7071A4TnHLGSPpNOm2a21K9Kf04k1rs08=
 github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3 h1:LMLX+LgTNWpfvCBdFebv6EsYotImrt/Ppc5cXIriCSo=
 github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3/go.mod h1:jl5iWTm0/hd5PjEYEOuwAJ57L/CibdZfrqZ5XA5GrCk=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
@@ -19,6 +23,8 @@ github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
 golang.org/x/mod v0.38.0 h1:MECBjubtXD7yj4HrhIUcywNaGeNVUdfVnxmPajOk4yk=
 golang.org/x/mod v0.38.0/go.mod h1:V6Xz0pq8TQ3dGqVQ1FVHuelZpAL0uNhSkk9ogYP3c40=
+golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
+golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
 golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
 golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=

internal/auth/actor.go

@@ -0,0 +1,45 @@
+package auth
+
+import (
+	"context"
+	"slices"
+)
+
+// Actor is the signed-in household member a request acts for. Handlers
+// record Actor.Subject as updated_by on edits.
+type Actor struct {
+	Subject string
+	Email   string
+	Name    string
+	Groups  []string
+}
+
+// Actor returns the household member s belongs to.
+func (s Session) Actor() Actor {
+	return Actor{Subject: s.Subject, Email: s.Email, Name: s.Name, Groups: slices.Clone(s.Groups)}
+}
+
+type sessionKey struct{}
+
+// WithSession returns a copy of ctx carrying s. The session middleware calls
+// it for every authenticated request.
+func WithSession(ctx context.Context, s Session) context.Context {
+	return context.WithValue(ctx, sessionKey{}, s)
+}
+
+// SessionFrom returns the session WithSession stored in ctx. ok is false when
+// ctx has none, which behind the session middleware means a wiring bug.
+func SessionFrom(ctx context.Context) (s Session, ok bool) {
+	s, ok = ctx.Value(sessionKey{}).(Session)
+	return s, ok
+}
+
+// ActorFrom returns the actor of the session WithSession stored in ctx. ok is
+// false when ctx has none.
+func ActorFrom(ctx context.Context) (actor Actor, ok bool) {
+	s, ok := SessionFrom(ctx)
+	if !ok {
+		return Actor{}, false
+	}
+	return s.Actor(), true
+}

internal/auth/actor_test.go

@@ -0,0 +1,40 @@
+package auth
+
+import (
+	"context"
+	"slices"
+	"testing"
+)
+
+func TestActorContext(t *testing.T) {
+	t.Parallel()
+	if _, ok := ActorFrom(context.Background()); ok {
+		t.Error("ActorFrom found an actor in an empty context")
+	}
+	if _, ok := SessionFrom(context.Background()); ok {
+		t.Error("SessionFrom found a session in an empty context")
+	}
+	s := Session{Subject: "user-123", Email: "cook@example.com", Name: "Home Cook", Groups: []string{"mealquest-admin"}, CSRFToken: "t"}
+	ctx := WithSession(context.Background(), s)
+	gotSession, ok := SessionFrom(ctx)
+	if !ok || gotSession.Subject != s.Subject || gotSession.CSRFToken != s.CSRFToken {
+		t.Errorf("SessionFrom = %+v (ok=%v), want %+v", gotSession, ok, s)
+	}
+	got, ok := ActorFrom(ctx)
+	if !ok || got.Subject != s.Subject || got.Email != s.Email || got.Name != s.Name || !slices.Equal(got.Groups, s.Groups) {
+		t.Errorf("ActorFrom = %+v (ok=%v), want the session's actor", got, ok)
+	}
+}
+
+func TestSessionActor(t *testing.T) {
+	t.Parallel()
+	s := Session{Subject: "user-123", Email: "cook@example.com", Name: "Home Cook", Groups: []string{"mealquest-admin"}, CSRFToken: "t"}
+	a := s.Actor()
+	if a.Subject != s.Subject || a.Email != s.Email || a.Name != s.Name || !slices.Equal(a.Groups, s.Groups) {
+		t.Errorf("Actor = %+v, want the session's identity", a)
+	}
+	a.Groups[0] = "changed"
+	if s.Groups[0] != "mealquest-admin" {
+		t.Error("Actor shares the session's groups slice")
+	}
+}

internal/auth/auth.go

@@ -0,0 +1,439 @@
+// Package auth signs the household in with Authentik over OpenID Connect.
+// The service is a confidential client: the authorization code, tokens and
+// client secret stay on the server and never reach JavaScript.
+package auth
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/subtle"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"net/url"
+	"slices"
+	"sync/atomic"
+	"time"
+
+	"github.com/coreos/go-oidc/v3/oidc"
+	"github.com/go-chi/chi/v5"
+	"golang.org/x/oauth2"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/secureurl"
+)
+
+// Routes owned by this package.
+const (
+	LoginPath    = "/auth/login"
+	CallbackPath = "/auth/callback"
+	LogoutPath   = "/auth/logout"
+)
+
+// providerTimeout bounds every request to the identity provider.
+const providerTimeout = 10 * time.Second
+
+// scopes requested at login.
+var scopes = []string{oidc.ScopeOpenID, "profile", "email", "groups", oidc.ScopeOfflineAccess}
+
+// Claims are the verified ID token claims handed to the session layer.
+type Claims struct {
+	Subject           string   `json:"sub"`
+	Email             string   `json:"email"`
+	EmailVerified     bool     `json:"email_verified"`
+	Name              string   `json:"name"`
+	PreferredUsername string   `json:"preferred_username"`
+	Groups            []string `json:"groups"`
+}
+
+// Sessions is the session layer. StartSession is called once per successful
+// login with claims from a verified ID token; it must set the session cookie
+// on w. EndSession is called on logout; it must end the session r carries,
+// if any, and clear the cookie on w. A returned error fails the request with
+// 500.
+type Sessions interface {
+	StartSession(w http.ResponseWriter, r *http.Request, claims Claims) error
+	EndSession(w http.ResponseWriter, r *http.Request) error
+}
+
+// Config is what New needs to reach the identity provider.
+type Config struct {
+	// Issuer is the exact issuer URL; discovery runs against it.
+	Issuer       string
+	ClientID     string
+	ClientSecret string
+	// PublicURL is the service's public URL; its origin prefixes CallbackPath
+	// to form the redirect URI.
+	PublicURL *url.URL
+	// SecretKey is the server key the login cookie's signing key derives from.
+	SecretKey []byte
+	// AllowedGroups are the household's groups; a sign-in is refused unless
+	// the account is in at least one of them.
+	AllowedGroups []string
+}
+
+// Auth serves the login and callback routes.
+type Auth struct {
+	oauth    oauth2.Config
+	verifier *oidc.IDTokenVerifier
+	provider *oidc.Provider
+	client   *http.Client
+	cookie   loginCookie
+	sessions Sessions
+	allowed  []string
+	// endSessionURL is the provider's end_session_endpoint; logout ends
+	// there so the provider's own session ends too.
+	endSessionURL string
+	logger        *slog.Logger
+}
+
+// New discovers the provider at cfg.Issuer and returns the login flow. It
+// fails if discovery fails or the issuer the provider reports differs.
+func New(ctx context.Context, cfg Config, sessions Sessions, logger *slog.Logger) (*Auth, error) {
+	switch {
+	case cfg.Issuer == "", cfg.ClientID == "", cfg.ClientSecret == "":
+		return nil, errors.New("auth: issuer, client ID and client secret are required")
+	case cfg.PublicURL == nil:
+		return nil, errors.New("auth: public URL is required")
+	case len(cfg.SecretKey) == 0:
+		return nil, errors.New("auth: secret key is required")
+	case sessions == nil:
+		return nil, errors.New("auth: session layer is required")
+	case len(cfg.AllowedGroups) == 0:
+		return nil, errors.New("auth: at least one allowed group is required")
+	}
+
+	if err := checkEndpoint("issuer", cfg.Issuer); err != nil {
+		return nil, err
+	}
+
+	client := &http.Client{Timeout: providerTimeout, CheckRedirect: checkRedirect}
+	discovery := *client
+	recorder := &statusRecorder{next: http.DefaultTransport}
+	discovery.Transport = recorder
+	provider, err := oidc.NewProvider(oidc.ClientContext(ctx, &discovery), cfg.Issuer)
+	if err != nil {
+		return nil, discoveryError(err, int(recorder.status.Load()))
+	}
+	endpoint := provider.Endpoint()
+	var discovered struct {
+		JWKSURI       string `json:"jwks_uri"`
+		EndSessionURI string `json:"end_session_endpoint"`
+	}
+	if err := provider.Claims(&discovered); err != nil {
+		return nil, fmt.Errorf("auth: OIDC discovery: %w", err)
+	}
+	// The token endpoint receives the client secret and the key set decides
+	// which tokens verify, so every endpoint used must pass the same rule.
+	for _, e := range []struct{ name, raw string }{
+		{"authorization endpoint", endpoint.AuthURL},
+		{"token endpoint", endpoint.TokenURL},
+		{"JWKS endpoint", discovered.JWKSURI},
+		{"end session endpoint", discovered.EndSessionURI},
+		// Groups come from userinfo when the ID token carries none, and the
+		// access token is sent there.
+		{"userinfo endpoint", provider.UserInfoEndpoint()},
+	} {
+		if err := checkEndpoint(e.name, e.raw); err != nil {
+			return nil, err
+		}
+	}
+	// client_secret_basic, the OIDC default; no auto-detection retries.
+	endpoint.AuthStyle = oauth2.AuthStyleInHeader
+
+	return &Auth{
+		oauth: oauth2.Config{
+			ClientID:     cfg.ClientID,
+			ClientSecret: cfg.ClientSecret,
+			Endpoint:     endpoint,
+			RedirectURL:  cfg.PublicURL.Scheme + "://" + cfg.PublicURL.Host + CallbackPath,
+			Scopes:       scopes,
+		},
+		verifier: provider.Verifier(&oidc.Config{
+			ClientID:             cfg.ClientID,
+			SupportedSigningAlgs: []string{oidc.RS256},
+		}),
+		provider:      provider,
+		client:        client,
+		allowed:       slices.Clone(cfg.AllowedGroups),
+		cookie:        newLoginCookie(cfg.SecretKey),
+		sessions:      sessions,
+		endSessionURL: discovered.EndSessionURI,
+		logger:        logger,
+	}, nil
+}
+
+// statusRecorder records the status of the last response it carries.
+type statusRecorder struct {
+	next   http.RoundTripper
+	status atomic.Int32
+}
+
+func (s *statusRecorder) RoundTrip(req *http.Request) (*http.Response, error) {
+	resp, err := s.next.RoundTrip(req)
+	if err == nil {
+		s.status.Store(int32(resp.StatusCode))
+	}
+	return resp, err
+}
+
+// discoveryError reports a failed discovery. go-oidc puts the provider's
+// response body in its error for a non-200 discovery response, so that
+// error is replaced by the status alone. Transport errors carry no response
+// content and keep their cause.
+func discoveryError(err error, status int) error {
+	var urlErr *url.Error
+	if !errors.As(err, &urlErr) && status != 0 && status != http.StatusOK {
+		return fmt.Errorf("auth: OIDC discovery: provider answered HTTP %d", status)
+	}
+	return fmt.Errorf("auth: OIDC discovery: %w", err)
+}
+
+// checkEndpoint applies secureurl.Check to the provider URL raw, naming the
+// endpoint in the error.
+func checkEndpoint(name, raw string) error {
+	u, err := url.Parse(raw)
+	if err != nil {
+		return fmt.Errorf("auth: OIDC %s %q is not a valid URL", name, raw)
+	}
+	if err := secureurl.Check(u); err != nil {
+		return fmt.Errorf("auth: OIDC %s %q: %w", name, raw, err)
+	}
+	return nil
+}
+
+// maxRedirects matches net/http's default redirect limit.
+const maxRedirects = 10
+
+// checkRedirect is the provider client's redirect policy. On a 307 or 308 to
+// the same host Go resends the body and Authorization header, which carry the
+// code and client secret, so every target must pass secureurl.Check and an
+// https:// request never follows a redirect to plain http://, even loopback.
+func checkRedirect(req *http.Request, via []*http.Request) error {
+	if len(via) >= maxRedirects {
+		return fmt.Errorf("stopped after %d redirects", maxRedirects)
+	}
+	if err := secureurl.Check(req.URL); err != nil {
+		return fmt.Errorf("redirect refused: %w", err)
+	}
+	if via[len(via)-1].URL.Scheme == "https" && req.URL.Scheme != "https" {
+		return errors.New("redirect refused: https:// to plain http:// downgrade")
+	}
+	return nil
+}
+
+// Mount registers GET LoginPath, GET CallbackPath and POST LogoutPath on r.
+func (a *Auth) Mount(r chi.Router) {
+	r.Get(LoginPath, a.login)
+	r.Get(CallbackPath, a.callback)
+	r.Post(LogoutPath, a.logout)
+}
+
+// EndSessionURL is the provider's end_session_endpoint.
+func (a *Auth) EndSessionURL() string { return a.endSessionURL }
+
+// login starts the authorization code flow with PKCE (S256). The optional
+// "return" query parameter must be a same-origin path; anything else fails
+// the login with 400.
+func (a *Auth) login(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Cache-Control", "no-store")
+
+	returnTo, err := returnPath(r.URL.Query().Get("return"))
+	if err != nil {
+		http.Error(w, "invalid return path", http.StatusBadRequest)
+		return
+	}
+	state := loginState{
+		State:    rand.Text(),
+		Nonce:    rand.Text(),
+		Verifier: oauth2.GenerateVerifier(),
+		Return:   returnTo,
+	}
+	if err := a.cookie.set(w, state, time.Now()); err != nil {
+		a.logger.ErrorContext(r.Context(), "set login cookie", "error", err)
+		http.Error(w, "internal error", http.StatusInternalServerError)
+		return
+	}
+	http.Redirect(w, r, a.oauth.AuthCodeURL(state.State,
+		oidc.Nonce(state.Nonce),
+		oauth2.S256ChallengeOption(state.Verifier),
+	), http.StatusFound)
+}
+
+// callback completes the flow: it checks state against the login cookie,
+// exchanges the code, verifies the ID token and nonce, then starts a session
+// if the account is in an allowed group. Membership is checked on every
+// login, so an account removed from the group is refused at its next one.
+func (a *Auth) callback(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Cache-Control", "no-store")
+	ctx := r.Context()
+	// The login cookie is single-use.
+	a.cookie.clear(w)
+
+	state, err := a.cookie.read(r, time.Now())
+	if err != nil {
+		a.logger.WarnContext(ctx, "login callback without a valid login cookie", "error", err)
+		http.Error(w, "sign-in expired; start again", http.StatusBadRequest)
+		return
+	}
+	q := r.URL.Query()
+	if subtle.ConstantTimeCompare([]byte(q.Get("state")), []byte(state.State)) != 1 {
+		a.logger.WarnContext(ctx, "login callback state mismatch")
+		http.Error(w, "sign-in state mismatch; start again", http.StatusBadRequest)
+		return
+	}
+	if q.Get("error") != "" {
+		// error and error_description are provider-supplied text; only the
+		// fixed category is logged.
+		a.logger.WarnContext(ctx, "identity provider returned an authorization error")
+		http.Error(w, "sign-in was refused", http.StatusUnauthorized)
+		return
+	}
+	code := q.Get("code")
+	if code == "" {
+		http.Error(w, "missing authorization code", http.StatusBadRequest)
+		return
+	}
+
+	claims, err := a.verify(ctx, code, state)
+	if err != nil {
+		a.logger.WarnContext(ctx, "sign-in failed", "error", err)
+		http.Error(w, "sign-in failed", http.StatusUnauthorized)
+		return
+	}
+	if !a.member(claims.Groups) {
+		if claims.Groups == nil {
+			a.logger.WarnContext(ctx, "sign-in refused: no groups claim in the ID token or userinfo", "subject", claims.Subject)
+		} else {
+			a.logger.WarnContext(ctx, "sign-in refused: not in an allowed group", "subject", claims.Subject)
+		}
+		// A session this browser already holds ends too, so a refused
+		// sign-in never leaves it signed in.
+		if err := a.sessions.EndSession(w, r); err != nil {
+			a.logger.ErrorContext(ctx, "end session", "error", err)
+			http.Error(w, "internal error", http.StatusInternalServerError)
+			return
+		}
+		a.refuse(w, r)
+		return
+	}
+	if err := a.sessions.StartSession(w, r, claims); err != nil {
+		a.logger.ErrorContext(ctx, "start session", "error", err)
+		http.Error(w, "internal error", http.StatusInternalServerError)
+		return
+	}
+	http.Redirect(w, r, state.Return, http.StatusSeeOther)
+}
+
+// logout ends the session, clears the cookie and sends the browser to the
+// provider's end_session_endpoint to end the provider session as well.
+func (a *Auth) logout(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Cache-Control", "no-store")
+	if err := a.sessions.EndSession(w, r); err != nil {
+		a.logger.ErrorContext(r.Context(), "end session", "error", err)
+		http.Error(w, "internal error", http.StatusInternalServerError)
+		return
+	}
+	http.Redirect(w, r, a.endSessionURL, http.StatusSeeOther)
+}
+
+// verify exchanges code for tokens and returns the verified ID token claims.
+// The verifier enforces RS256, issuer, audience and expiry; nonce is checked
+// here. When the ID token has no groups claim, Groups comes from userinfo;
+// it stays nil when neither has one.
+func (a *Auth) verify(ctx context.Context, code string, state loginState) (Claims, error) {
+	token, err := a.oauth.Exchange(context.WithValue(ctx, oauth2.HTTPClient, a.client), code,
+		oauth2.VerifierOption(state.Verifier))
+	if err != nil {
+		return Claims{}, exchangeError(err)
+	}
+	raw, ok := token.Extra("id_token").(string)
+	if !ok || raw == "" {
+		return Claims{}, errors.New("token response has no id_token")
+	}
+	idToken, err := a.verifier.Verify(ctx, raw)
+	if err != nil {
+		return Claims{}, verifyError(err)
+	}
+	if subtle.ConstantTimeCompare([]byte(idToken.Nonce), []byte(state.Nonce)) != 1 {
+		return Claims{}, errors.New("ID token nonce mismatch")
+	}
+	var claims Claims
+	if err := idToken.Claims(&claims); err != nil {
+		return Claims{}, fmt.Errorf("decode ID token claims: %w", err)
+	}
+	if claims.Subject == "" {
+		return Claims{}, errors.New("ID token has no subject")
+	}
+	if claims.Groups == nil {
+		groups, err := a.userinfoGroups(ctx, token, claims.Subject)
+		if err != nil {
+			return Claims{}, err
+		}
+		claims.Groups = groups
+	}
+	return claims, nil
+}
+
+// userinfoGroups returns the groups claim from the userinfo endpoint, nil if
+// it has none. The userinfo subject must match the ID token's subject.
+func (a *Auth) userinfoGroups(ctx context.Context, token *oauth2.Token, subject string) ([]string, error) {
+	info, err := a.provider.UserInfo(oidc.ClientContext(ctx, a.client), oauth2.StaticTokenSource(token))
+	if err != nil {
+		return nil, userinfoError(err)
+	}
+	if info.Subject != subject {
+		return nil, errors.New("userinfo subject does not match the ID token")
+	}
+	var claims struct {
+		Groups []string `json:"groups"`
+	}
+	if err := info.Claims(&claims); err != nil {
+		return nil, fmt.Errorf("decode userinfo claims: %w", err)
+	}
+	return claims.Groups, nil
+}
+
+// userinfoError reduces a failed userinfo request to a fixed category, like
+// exchangeError: go-oidc's error text can carry the response body.
+func userinfoError(err error) error {
+	var transport *url.Error
+	if errors.As(err, &transport) {
+		return fmt.Errorf("userinfo: request failed: %s: %w", transport.Op, transport.Err)
+	}
+	return errors.New("userinfo: endpoint returned an unusable response")
+}
+
+// verifyError reduces a failed ID token verification to a fixed category.
+// go-oidc's error text can carry the JWKS endpoint's response body or
+// token-supplied values, so only the expiry of an expired token is kept.
+func verifyError(err error) error {
+	var expired *oidc.TokenExpiredError
+	if errors.As(err, &expired) {
+		return fmt.Errorf("verify ID token: token expired at %s", expired.Expiry.UTC().Format(time.RFC3339))
+	}
+	return errors.New("verify ID token: token or provider key set rejected")
+}
+
+// member reports whether groups contains an allowed group.
+func (a *Auth) member(groups []string) bool {
+	return slices.ContainsFunc(groups, func(g string) bool { return slices.Contains(a.allowed, g) })
+}
+
+// exchangeError reduces a failed code exchange to a fixed category and safe
+// metadata. The oauth2 error text can carry the token endpoint's response
+// body or error_description, which may echo credentials, so it is dropped.
+func exchangeError(err error) error {
+	var retrieve *oauth2.RetrieveError
+	var transport *url.Error
+	switch {
+	case errors.As(err, &retrieve):
+		return fmt.Errorf("exchange code: token endpoint rejected the request (HTTP %d)", retrieve.Response.StatusCode)
+	case errors.As(err, &transport):
+		// Request failures never carry the response. The URL is dropped: after
+		// a refused redirect it is the provider-supplied Location.
+		return fmt.Errorf("exchange code: token request failed: %s: %w", transport.Op, transport.Err)
+	default:
+		return errors.New("exchange code: token endpoint returned an unusable response")
+	}
+}

internal/auth/cookie.go

@@ -0,0 +1,124 @@
+package auth
+
+import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+const (
+	loginCookieName = "__Host-mealquest_login"
+	loginCookieTTL  = 10 * time.Minute
+	// loginCookieKeyLabel separates the login cookie's signing key from other
+	// keys derived from the same server secret.
+	loginCookieKeyLabel = "mealquest auth login cookie v1"
+)
+
+// loginState travels from login to callback in the signed login cookie.
+type loginState struct {
+	State    string `json:"s"`
+	Nonce    string `json:"n"`
+	Verifier string `json:"v"`
+	Return   string `json:"r"`
+	Expires  int64  `json:"e"` // Unix seconds
+}
+
+// loginCookie signs and verifies the login cookie with HMAC-SHA256.
+type loginCookie struct {
+	key []byte
+}
+
+func newLoginCookie(secretKey []byte) loginCookie {
+	mac := hmac.New(sha256.New, secretKey)
+	mac.Write([]byte(loginCookieKeyLabel))
+	return loginCookie{key: mac.Sum(nil)}
+}
+
+func (c loginCookie) sign(payload string) string {
+	mac := hmac.New(sha256.New, c.key)
+	mac.Write([]byte(payload))
+	return base64.RawURLEncoding.EncodeToString(mac.Sum(nil))
+}
+
+func (c loginCookie) set(w http.ResponseWriter, s loginState, now time.Time) error {
+	s.Expires = now.Add(loginCookieTTL).Unix()
+	data, err := json.Marshal(s)
+	if err != nil {
+		return err
+	}
+	payload := base64.RawURLEncoding.EncodeToString(data)
+	http.SetCookie(w, &http.Cookie{
+		Name:     loginCookieName,
+		Value:    payload + "." + c.sign(payload),
+		Path:     "/",
+		MaxAge:   int(loginCookieTTL / time.Second),
+		Secure:   true,
+		HttpOnly: true,
+		// Lax so the cookie rides the provider's top-level redirect back.
+		SameSite: http.SameSiteLaxMode,
+	})
+	return nil
+}
+
+func (c loginCookie) clear(w http.ResponseWriter) {
+	http.SetCookie(w, &http.Cookie{
+		Name:     loginCookieName,
+		Path:     "/",
+		MaxAge:   -1,
+		Secure:   true,
+		HttpOnly: true,
+		SameSite: http.SameSiteLaxMode,
+	})
+}
+
+func (c loginCookie) read(r *http.Request, now time.Time) (loginState, error) {
+	cookie, err := r.Cookie(loginCookieName)
+	if err != nil {
+		return loginState{}, errors.New("login cookie missing")
+	}
+	payload, sig, ok := strings.Cut(cookie.Value, ".")
+	if !ok || !hmac.Equal([]byte(sig), []byte(c.sign(payload))) {
+		return loginState{}, errors.New("login cookie signature invalid")
+	}
+	data, err := base64.RawURLEncoding.DecodeString(payload)
+	if err != nil {
+		return loginState{}, fmt.Errorf("login cookie encoding: %w", err)
+	}
+	var s loginState
+	if err := json.Unmarshal(data, &s); err != nil {
+		return loginState{}, fmt.Errorf("login cookie payload: %w", err)
+	}
+	if now.Unix() >= s.Expires {
+		return loginState{}, errors.New("login cookie expired")
+	}
+	return s, nil
+}
+
+// returnPath validates the optional post-login return path. Empty means "/".
+// Only same-origin absolute paths are allowed: no scheme, host, protocol-
+// relative "//" prefix, backslashes or control characters.
+func returnPath(raw string) (string, error) {
+	if raw == "" {
+		return "/", nil
+	}
+	if !strings.HasPrefix(raw, "/") || strings.HasPrefix(raw, "//") || strings.ContainsRune(raw, '\\') {
+		return "", errors.New("return path must be a same-origin path")
+	}
+	for _, c := range raw {
+		if c < 0x20 || c == 0x7f {
+			return "", errors.New("return path contains a control character")
+		}
+	}
+	u, err := url.Parse(raw)
+	if err != nil || u.Scheme != "" || u.Host != "" || u.User != nil {
+		return "", errors.New("return path must be a same-origin path")
+	}
+	return raw, nil
+}

internal/auth/gate_test.go

@@ -0,0 +1,264 @@
+package auth
+
+import (
+	"context"
+	"errors"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/url"
+	"slices"
+	"strings"
+	"testing"
+)
+
+// signInWith completes a login whose ID token has claims edited by edit.
+func (h *harness) signInWith(t *testing.T, edit func(claims map[string]any)) *http.Response {
+	t.Helper()
+	l := h.login(t, LoginPath)
+	c := h.provider.claims(l.query.Get("nonce"))
+	edit(c)
+	return h.callback(l, l.query.Get("state"), h.provider.signRS256(c))
+}
+
+// assertRefused checks resp is the refused-sign-in page and starts no
+// session.
+func assertRefused(t *testing.T, resp *http.Response) {
+	t.Helper()
+	if resp.StatusCode != http.StatusForbidden {
+		t.Fatalf("callback status = %d, want 403", resp.StatusCode)
+	}
+	if ct := resp.Header.Get("Content-Type"); ct != "text/html; charset=utf-8" {
+		t.Errorf("Content-Type = %q, want text/html; charset=utf-8", ct)
+	}
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{
+		"This kitchen is for the household only",
+		`<form method="post" action="/auth/logout">`,
+		"Sign out",
+	} {
+		if !strings.Contains(string(body), want) {
+			t.Errorf("refused page lacks %q:\n%s", want, body)
+		}
+	}
+	for _, c := range resp.Cookies() {
+		// Clearing a session cookie (negative Max-Age) is expected.
+		if (c.Name == SessionCookieName || c.Name == "test_session") && c.MaxAge >= 0 {
+			t.Errorf("refused sign-in set session cookie %s", c.Name)
+		}
+	}
+	assertLoginCookieCleared(t, resp)
+}
+
+func TestGroupGateMember(t *testing.T) {
+	t.Parallel()
+	// Any one allowed group is enough, alongside groups that are not allowed.
+	h := newHarness(t)
+	resp := h.signInWith(t, func(c map[string]any) { c["groups"] = []string{"guests", "mealquest-family"} })
+	if resp.StatusCode != http.StatusSeeOther {
+		t.Fatalf("callback status = %d, want 303", resp.StatusCode)
+	}
+	if started := h.sessions.started(); len(started) != 1 || !slices.Equal(started[0].Groups, []string{"guests", "mealquest-family"}) {
+		t.Errorf("sessions started = %+v, want one with the ID token groups", started)
+	}
+	if n := h.provider.userinfoRequests(); n != 0 {
+		t.Errorf("userinfo requested %d times, want 0 when the ID token has groups", n)
+	}
+}
+
+func TestGroupGateRefused(t *testing.T) {
+	t.Parallel()
+	tests := []struct {
+		name     string
+		groups   any // ID token groups claim; nil removes it
+		userinfo map[string]any
+	}{
+		{name: "non-member", groups: []string{"guests", "MEALQUEST-ADMIN"}},
+		{name: "empty groups claim", groups: []string{}},
+		{name: "groups claim missing from ID token and userinfo", groups: nil},
+		{
+			name:     "non-member in userinfo",
+			groups:   nil,
+			userinfo: map[string]any{"sub": "user-123", "groups": []string{"guests"}},
+		},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			h := newHarness(t)
+			if tc.userinfo != nil {
+				h.provider.setUserinfo(tc.userinfo)
+			}
+			resp := h.signInWith(t, func(c map[string]any) {
+				if tc.groups == nil {
+					delete(c, "groups")
+				} else {
+					c["groups"] = tc.groups
+				}
+			})
+			assertRefused(t, resp)
+			if started := h.sessions.started(); len(started) != 0 {
+				t.Errorf("sessions started = %+v, want none", started)
+			}
+			if !strings.Contains(h.logs.String(), "sign-in refused") {
+				t.Errorf("refusal not logged:\n%s", h.logs.String())
+			}
+		})
+	}
+}
+
+func TestGroupGateUsesUserinfoWhenIDTokenHasNoGroups(t *testing.T) {
+	t.Parallel()
+	h := newHarness(t)
+	h.provider.setUserinfo(map[string]any{"sub": "user-123", "groups": []string{"mealquest-admin"}})
+	resp := h.signInWith(t, func(c map[string]any) { delete(c, "groups") })
+	if resp.StatusCode != http.StatusSeeOther {
+		t.Fatalf("callback status = %d, want 303", resp.StatusCode)
+	}
+	if started := h.sessions.started(); len(started) != 1 || !slices.Equal(started[0].Groups, []string{"mealquest-admin"}) {
+		t.Errorf("sessions started = %+v, want one with the userinfo groups", started)
+	}
+	if n := h.provider.userinfoRequests(); n != 1 {
+		t.Errorf("userinfo requested %d times, want 1", n)
+	}
+}
+
+func TestGroupGateUserinfoFailures(t *testing.T) {
+	t.Parallel()
+	tests := []struct {
+		name     string
+		userinfo map[string]any
+	}{
+		{"subject mismatch", map[string]any{"sub": "someone-else", "groups": []string{"mealquest-admin"}}},
+		{"malformed groups", map[string]any{"sub": "user-123", "groups": "mealquest-admin"}},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			h := newHarness(t)
+			h.provider.setUserinfo(tc.userinfo)
+			resp := h.signInWith(t, func(c map[string]any) { delete(c, "groups") })
+			if resp.StatusCode != http.StatusUnauthorized {
+				t.Errorf("callback status = %d, want 401", resp.StatusCode)
+			}
+			if started := h.sessions.started(); len(started) != 0 {
+				t.Errorf("sessions started = %+v, want none", started)
+			}
+		})
+	}
+}
+
+// A failed userinfo request fails the sign-in without logging the
+// endpoint's response, which may echo credentials.
+func TestGroupGateUserinfoErrorNotLogged(t *testing.T) {
+	t.Parallel()
+	h := newHarness(t)
+	h.provider.mu.Lock()
+	h.provider.userinfoReply = &tokenReply{status: http.StatusInternalServerError, body: `{"error":"leaked-s3cret"}`}
+	h.provider.mu.Unlock()
+	resp := h.signInWith(t, func(c map[string]any) { delete(c, "groups") })
+	if resp.StatusCode != http.StatusUnauthorized {
+		t.Errorf("callback status = %d, want 401", resp.StatusCode)
+	}
+	if started := h.sessions.started(); len(started) != 0 {
+		t.Errorf("sessions started = %+v, want none", started)
+	}
+	logs := h.logs.String()
+	if !strings.Contains(logs, "userinfo") || strings.Contains(logs, "leaked-s3cret") {
+		t.Errorf("logs = %s, want the userinfo failure without the response body", logs)
+	}
+}
+
+// Membership is checked at every login: after removal from the group, the
+// next login is refused and starts no session.
+func TestGroupGateRemovedMemberRefusedAtNextLogin(t *testing.T) {
+	t.Parallel()
+	h := newSessionHarness(t)
+	h.signIn(t)
+	if n := len(h.rows(t)); n != 1 {
+		t.Fatalf("sessions after first login = %d, want 1", n)
+	}
+
+	resp := h.signInWith(t, func(c map[string]any) { c["groups"] = []string{"former-household"} })
+	assertRefused(t, resp)
+	if n := len(h.rows(t)); n != 1 {
+		t.Errorf("sessions after refused login = %d, want still 1", n)
+	}
+}
+
+// A refused sign-in from a browser that still holds a session ends that
+// session and clears its cookie.
+func TestGroupGateRefusalEndsExistingSession(t *testing.T) {
+	t.Parallel()
+	h := newSessionHarness(t)
+	_, cookie := h.signIn(t)
+
+	l := h.login(t, LoginPath)
+	c := h.provider.claims(l.query.Get("nonce"))
+	c["groups"] = []string{"former-household"}
+	code := h.provider.authorize(l.query.Get("code_challenge"), h.provider.signRS256(c))
+	q := url.Values{"code": {code}, "state": {l.query.Get("state")}}
+	resp := h.get(CallbackPath+"?"+q.Encode(), l.cookie, cookie)
+
+	if resp.StatusCode != http.StatusForbidden {
+		t.Fatalf("callback status = %d, want 403", resp.StatusCode)
+	}
+	if n := len(h.rows(t)); n != 0 {
+		t.Errorf("sessions after refused login = %d, want 0", n)
+	}
+	if _, err := h.use(cookie); !errors.Is(err, ErrNoSession) {
+		t.Errorf("old session lookup error = %v, want ErrNoSession", err)
+	}
+	cleared := false
+	for _, c := range resp.Cookies() {
+		cleared = cleared || (c.Name == SessionCookieName && c.MaxAge < 0)
+	}
+	if !cleared {
+		t.Error("refused sign-in did not clear the session cookie")
+	}
+}
+
+func TestGroupGateRefusalEndSessionError(t *testing.T) {
+	t.Parallel()
+	h := newHarness(t)
+	h.sessions.err = errors.New("database down")
+	resp := h.signInWith(t, func(c map[string]any) { c["groups"] = []string{"guests"} })
+	if resp.StatusCode != http.StatusInternalServerError {
+		t.Errorf("callback status = %d, want 500", resp.StatusCode)
+	}
+}
+
+func TestNewRequiresAllowedGroups(t *testing.T) {
+	t.Parallel()
+	p := newFakeProvider(t)
+	_, err := New(context.Background(), Config{
+		Issuer:       p.issuer(),
+		ClientID:     testClientID,
+		ClientSecret: testClientSecret,
+		PublicURL:    testPublicURL,
+		SecretKey:    []byte("k"),
+	}, &memorySessions{}, slog.New(slog.DiscardHandler))
+	if err == nil || !strings.Contains(err.Error(), "allowed group") {
+		t.Errorf("New error = %v, want missing allowed groups named", err)
+	}
+}
+
+func TestNewRequiresUserinfoEndpoint(t *testing.T) {
+	t.Parallel()
+	p := newFakeProvider(t)
+	p.discoveryOverrides = map[string]any{"userinfo_endpoint": nil}
+	_, err := New(context.Background(), Config{
+		Issuer:        p.issuer(),
+		ClientID:      testClientID,
+		ClientSecret:  testClientSecret,
+		PublicURL:     testPublicURL,
+		SecretKey:     []byte("k"),
+		AllowedGroups: testAllowedGroups,
+	}, &memorySessions{}, slog.New(slog.DiscardHandler))
+	if err == nil || !strings.Contains(err.Error(), "userinfo endpoint") {
+		t.Errorf("New error = %v, want the missing userinfo endpoint named", err)
+	}
+}

internal/auth/refused.go

@@ -0,0 +1,37 @@
+package auth
+
+import (
+	"io"
+	"net/http"
+)
+
+// refusedPage is shown when a sign-in succeeds at the provider but the
+// account is not in the household's group. Signing out ends the provider
+// session too, so another account can sign in.
+const refusedPage = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>MealQuest</title>
+</head>
+<body>
+<main>
+<h1>This kitchen is for the household only</h1>
+<p>The account you signed in with is not part of our kitchen.</p>
+<form method="post" action="` + LogoutPath + `">
+<button type="submit">Sign out</button>
+</form>
+</main>
+</body>
+</html>
+`
+
+// refuse writes the refused-sign-in page with 403.
+func (a *Auth) refuse(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	w.WriteHeader(http.StatusForbidden)
+	if _, err := io.WriteString(w, refusedPage); err != nil {
+		a.logger.WarnContext(r.Context(), "write refused sign-in page", "error", err)
+	}
+}

internal/auth/session.go

@@ -0,0 +1,238 @@
+package auth
+
+import (
+	"crypto/rand"
+	"crypto/sha256"
+	"database/sql"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// SessionCookieName is the session cookie. The __Host- prefix makes the
+// browser insist on Secure, Path=/ and no Domain.
+const SessionCookieName = "__Host-mealquest_session"
+
+// sessionIDBytes is the size of the random session ID: 256 bits.
+const sessionIDBytes = 32
+
+// ErrNoSession means the request carries no live session: the cookie is
+// missing or malformed, or its session is unknown, ended or expired.
+var ErrNoSession = errors.New("auth: no valid session")
+
+// Session is a signed-in household member's server-side session.
+type Session struct {
+	Subject   string
+	Email     string
+	Name      string
+	Groups    []string
+	CSRFToken string
+	CreatedAt time.Time
+	// LastSeenAt is the last time the session was used.
+	LastSeenAt time.Time
+	// ExpiresAt is when the session ends unless used again first.
+	ExpiresAt time.Time
+}
+
+// SessionManager keeps sessions in the sessions table. The cookie holds only
+// the random session ID; the table holds only its SHA-256 hash. A session
+// ends after idle without use and always max after it was created.
+type SessionManager struct {
+	db   *store.Store
+	idle time.Duration
+	max  time.Duration
+	// now is the clock; tests replace it.
+	now func() time.Time
+}
+
+// NewSessionManager returns a SessionManager over db. idle and max must be
+// positive with max >= idle.
+func NewSessionManager(db *store.Store, idle, max time.Duration) (*SessionManager, error) {
+	switch {
+	case db == nil:
+		return nil, errors.New("auth: session store is required")
+	case idle <= 0 || max <= 0:
+		return nil, errors.New("auth: session idle and max lifetimes must be positive")
+	case max < idle:
+		return nil, errors.New("auth: session max lifetime must be at least the idle lifetime")
+	}
+	return &SessionManager{db: db, idle: idle, max: max, now: time.Now}, nil
+}
+
+// StartSession creates a session for claims and sets the session cookie.
+func (m *SessionManager) StartSession(w http.ResponseWriter, r *http.Request, claims Claims) error {
+	if claims.Subject == "" {
+		return errors.New("auth: session needs a subject")
+	}
+	id, csrf := randomToken(), randomToken()
+	groups := claims.Groups
+	if groups == nil {
+		groups = []string{}
+	}
+	groupsJSON, err := json.Marshal(groups)
+	if err != nil {
+		return fmt.Errorf("auth: encode session groups: %w", err)
+	}
+
+	now := m.timestamp()
+	if _, err := m.db.Writer.ExecContext(r.Context(), `
+		INSERT INTO sessions (id_hash, subject, email, name, groups, csrf_token, created_at, last_seen_at, expires_at)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+		hashSessionID(id), claims.Subject, claims.Email, claims.Name, string(groupsJSON), csrf,
+		now, now, m.expiry(now.Time, now.Time),
+	); err != nil {
+		return fmt.Errorf("auth: create session: %w", err)
+	}
+
+	// The cookie outlives idle gaps so a returning device presents its ID;
+	// the server decides whether the session is still live. Max-Age is whole
+	// seconds, rounded up so the cookie never ends before the absolute limit.
+	http.SetCookie(w, sessionCookie(id, cookieMaxAge(m.max)))
+	return nil
+}
+
+// cookieMaxAge is lifetime in whole seconds, rounded up. It rounds the
+// quotient rather than adding to lifetime, which would overflow near the
+// largest time.Duration.
+func cookieMaxAge(lifetime time.Duration) int {
+	seconds := lifetime / time.Second
+	if lifetime%time.Second != 0 {
+		seconds++
+	}
+	return int(seconds)
+}
+
+// SessionFor returns the live session r carries and slides its last use to
+// now. It returns ErrNoSession when there is none; an expired session is
+// deleted.
+func (m *SessionManager) SessionFor(r *http.Request) (Session, error) {
+	idHash, err := sessionIDHash(r)
+	if err != nil {
+		return Session{}, err
+	}
+	now := m.timestamp()
+
+	var s Session
+	live := false
+	err = m.db.WithTx(r.Context(), func(tx *sql.Tx) error {
+		var groupsJSON string
+		var created, lastSeen, expires store.Timestamp
+		err := tx.QueryRowContext(r.Context(), `
+			SELECT subject, email, name, groups, csrf_token, created_at, last_seen_at, expires_at
+			FROM sessions WHERE id_hash = ?`, idHash,
+		).Scan(&s.Subject, &s.Email, &s.Name, &groupsJSON, &s.CSRFToken, &created, &lastSeen, &expires)
+		if errors.Is(err, sql.ErrNoRows) {
+			return nil
+		}
+		if err != nil {
+			return fmt.Errorf("auth: read session: %w", err)
+		}
+
+		if !now.Before(expires.Time) || now.Sub(lastSeen.Time) >= m.idle || now.Sub(created.Time) >= m.max {
+			if _, err := tx.ExecContext(r.Context(), `DELETE FROM sessions WHERE id_hash = ?`, idHash); err != nil {
+				return fmt.Errorf("auth: delete expired session: %w", err)
+			}
+			return nil
+		}
+
+		if err := json.Unmarshal([]byte(groupsJSON), &s.Groups); err != nil {
+			return fmt.Errorf("auth: decode session groups: %w", err)
+		}
+		expiresAt := m.expiry(created.Time, now.Time)
+		if _, err := tx.ExecContext(r.Context(), `
+			UPDATE sessions SET last_seen_at = ?, expires_at = ? WHERE id_hash = ?`,
+			now, expiresAt, idHash,
+		); err != nil {
+			return fmt.Errorf("auth: slide session: %w", err)
+		}
+		s.CreatedAt, s.LastSeenAt, s.ExpiresAt = created.Time, now.Time, expiresAt.Time
+		live = true
+		return nil
+	})
+	if err != nil {
+		return Session{}, err
+	}
+	if !live {
+		return Session{}, ErrNoSession
+	}
+	return s, nil
+}
+
+// EndSession deletes the session r carries, if any, and clears the cookie.
+func (m *SessionManager) EndSession(w http.ResponseWriter, r *http.Request) error {
+	http.SetCookie(w, sessionCookie("", -1))
+	idHash, err := sessionIDHash(r)
+	if errors.Is(err, ErrNoSession) {
+		return nil
+	}
+	if err != nil {
+		return err
+	}
+	if _, err := m.db.Writer.ExecContext(r.Context(), `DELETE FROM sessions WHERE id_hash = ?`, idHash); err != nil {
+		return fmt.Errorf("auth: delete session: %w", err)
+	}
+	return nil
+}
+
+// timestamp is the clock's current instant at stored precision.
+func (m *SessionManager) timestamp() store.Timestamp {
+	return store.Timestamp{Time: m.now().UTC().Truncate(time.Millisecond)}
+}
+
+// expiry is when a session created at created and last used at lastSeen
+// ends: idle after lastSeen, but never later than max after created.
+func (m *SessionManager) expiry(created, lastSeen time.Time) store.Timestamp {
+	idle, absolute := lastSeen.Add(m.idle), created.Add(m.max)
+	if absolute.Before(idle) {
+		return store.Timestamp{Time: absolute}
+	}
+	return store.Timestamp{Time: idle}
+}
+
+// sessionCookie is the session cookie carrying value, with maxAge seconds;
+// a negative maxAge clears it.
+func sessionCookie(value string, maxAge int) *http.Cookie {
+	return &http.Cookie{
+		Name:     SessionCookieName,
+		Value:    value,
+		Path:     "/",
+		MaxAge:   maxAge,
+		Secure:   true,
+		HttpOnly: true,
+		SameSite: http.SameSiteLaxMode,
+	}
+}
+
+// sessionIDHash returns the stored hash of r's session ID, or ErrNoSession
+// when the cookie is missing or is not a well-formed ID.
+func sessionIDHash(r *http.Request) (string, error) {
+	c, err := r.Cookie(SessionCookieName)
+	if err != nil {
+		return "", ErrNoSession
+	}
+	raw, err := base64.RawURLEncoding.DecodeString(c.Value)
+	if err != nil || len(raw) != sessionIDBytes {
+		return "", ErrNoSession
+	}
+	return hashSessionID(c.Value), nil
+}
+
+// hashSessionID is the SHA-256 hex digest of the cookie value.
+func hashSessionID(id string) string {
+	sum := sha256.Sum256([]byte(id))
+	return hex.EncodeToString(sum[:])
+}
+
+// randomToken returns 256 random bits, base64url-encoded without padding.
+// crypto/rand.Read never returns an error; it crashes the program instead.
+func randomToken() string {
+	b := make([]byte, sessionIDBytes)
+	rand.Read(b)
+	return base64.RawURLEncoding.EncodeToString(b)
+}

internal/auth/session_test.go

@@ -0,0 +1,523 @@
+package auth
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"slices"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
+)
+
+const (
+	testIdle = 30 * 24 * time.Hour
+	testMax  = 180 * 24 * time.Hour
+)
+
+// testEpoch is the fake clock's starting instant.
+var testEpoch = time.Date(2026, 10, 3, 18, 30, 0, 0, time.UTC)
+
+// sessionHarness runs the real login flow against a fake provider with a
+// SessionManager over a migrated database and a fake clock.
+type sessionHarness struct {
+	*harness
+	db       *store.Store
+	sessions *SessionManager
+	auth     *Auth
+	clock    time.Time
+}
+
+func newSessionHarness(t *testing.T) *sessionHarness {
+	t.Helper()
+	ctx := context.Background()
+	db, err := store.Open(ctx, t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := db.Close(); err != nil {
+			t.Error(err)
+		}
+	})
+	if err := store.Migrate(ctx, db.Writer, migrations.FS); err != nil {
+		t.Fatal(err)
+	}
+	sessions, err := NewSessionManager(db, testIdle, testMax)
+	if err != nil {
+		t.Fatal(err)
+	}
+	h := &sessionHarness{db: db, sessions: sessions, clock: testEpoch}
+	sessions.now = func() time.Time { return h.clock }
+
+	p := newFakeProvider(t)
+	logs := &syncBuffer{}
+	a, err := New(ctx, Config{
+		Issuer:        p.issuer(),
+		ClientID:      testClientID,
+		ClientSecret:  testClientSecret,
+		PublicURL:     testPublicURL,
+		SecretKey:     []byte("server-secret-key"),
+		AllowedGroups: testAllowedGroups,
+	}, sessions, slog.New(slog.NewTextHandler(logs, nil)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	r := chi.NewRouter()
+	a.Mount(r)
+	h.harness = &harness{provider: p, router: r, logs: logs}
+	h.auth = a
+	return h
+}
+
+func (h *sessionHarness) advance(d time.Duration) { h.clock = h.clock.Add(d) }
+
+// signIn completes a login and returns the callback response and the
+// session cookie it set.
+func (h *sessionHarness) signIn(t *testing.T) (*http.Response, *http.Cookie) {
+	t.Helper()
+	l := h.login(t, LoginPath)
+	resp := h.callback(l, l.query.Get("state"), h.provider.signRS256(h.provider.claims(l.query.Get("nonce"))))
+	if resp.StatusCode != http.StatusSeeOther {
+		t.Fatalf("callback status = %d, want 303", resp.StatusCode)
+	}
+	for _, c := range resp.Cookies() {
+		if c.Name == SessionCookieName {
+			return resp, c
+		}
+	}
+	t.Fatalf("callback set no %s cookie", SessionCookieName)
+	return nil, nil
+}
+
+// use looks up the session cookie c names.
+func (h *sessionHarness) use(c *http.Cookie) (Session, error) {
+	req := httptest.NewRequest(http.MethodGet, "/api/anything", nil)
+	if c != nil {
+		req.AddCookie(c)
+	}
+	return h.sessions.SessionFor(req)
+}
+
+type sessionRow struct {
+	idHash, subject, email, name, groups, csrf string
+	created, lastSeen, expires                 store.Timestamp
+}
+
+func (h *sessionHarness) rows(t *testing.T) []sessionRow {
+	t.Helper()
+	rs, err := h.db.Reader.Query(`SELECT id_hash, subject, email, name, groups, csrf_token,
+		created_at, last_seen_at, expires_at FROM sessions`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer rs.Close()
+	var out []sessionRow
+	for rs.Next() {
+		var r sessionRow
+		if err := rs.Scan(&r.idHash, &r.subject, &r.email, &r.name, &r.groups, &r.csrf,
+			&r.created, &r.lastSeen, &r.expires); err != nil {
+			t.Fatal(err)
+		}
+		out = append(out, r)
+	}
+	if err := rs.Err(); err != nil {
+		t.Fatal(err)
+	}
+	return out
+}
+
+// sessionSetCookie returns the raw Set-Cookie header for the session cookie.
+func sessionSetCookie(t *testing.T, resp *http.Response) string {
+	t.Helper()
+	for _, v := range resp.Header.Values("Set-Cookie") {
+		if strings.HasPrefix(v, SessionCookieName+"=") {
+			return v
+		}
+	}
+	t.Fatalf("no Set-Cookie for %s in %q", SessionCookieName, resp.Header.Values("Set-Cookie"))
+	return ""
+}
+
+// assertSessionCookieAttributes checks the attributes the __Host- prefix
+// and D-004 require, on the raw header so nothing is lost in parsing.
+func assertSessionCookieAttributes(t *testing.T, raw string) {
+	t.Helper()
+	attrs := map[string]bool{}
+	for _, a := range strings.Split(raw, ";")[1:] {
+		name, _, _ := strings.Cut(strings.TrimSpace(a), "=")
+		attrs[strings.ToLower(name)] = true
+	}
+	for _, want := range []string{"Path=/", "HttpOnly", "Secure", "SameSite=Lax"} {
+		if !slices.Contains(strings.Split(raw, "; "), want) {
+			t.Errorf("session Set-Cookie %q lacks %s", raw, want)
+		}
+	}
+	if attrs["domain"] {
+		t.Errorf("session Set-Cookie %q has a Domain", raw)
+	}
+}
+
+func sha256Hex(s string) string {
+	sum := sha256.Sum256([]byte(s))
+	return hex.EncodeToString(sum[:])
+}
+
+func TestCallbackStartsSession(t *testing.T) {
+	t.Parallel()
+	h := newSessionHarness(t)
+	resp, cookie := h.signIn(t)
+
+	assertSessionCookieAttributes(t, sessionSetCookie(t, resp))
+	if cookie.MaxAge != int(testMax/time.Second) {
+		t.Errorf("session cookie MaxAge = %d, want %d", cookie.MaxAge, int(testMax/time.Second))
+	}
+
+	rows := h.rows(t)
+	if len(rows) != 1 {
+		t.Fatalf("sessions has %d rows, want 1", len(rows))
+	}
+	r := rows[0]
+	if len(cookie.Value) != 43 {
+		t.Errorf("session ID %q is %d chars, want 43 (256 bits, base64url)", cookie.Value, len(cookie.Value))
+	}
+	if r.idHash != sha256Hex(cookie.Value) {
+		t.Errorf("id_hash = %q, want the SHA-256 of the cookie value", r.idHash)
+	}
+	if r.subject != "user-123" || r.email != "cook@example.com" || r.name != "Home Cook" ||
+		r.groups != `["mealquest-admin"]` {
+		t.Errorf("session row = %+v, want the ID token claims", r)
+	}
+	if len(r.csrf) != 43 || r.csrf == cookie.Value {
+		t.Errorf("csrf_token = %q, want a separate 256-bit token", r.csrf)
+	}
+	if !r.created.Equal(testEpoch) || !r.lastSeen.Equal(testEpoch) || !r.expires.Equal(testEpoch.Add(testIdle)) {
+		t.Errorf("created, last_seen, expires = %v, %v, %v, want %v, %v, %v",
+			r.created, r.lastSeen, r.expires, testEpoch, testEpoch, testEpoch.Add(testIdle))
+	}
+
+	s, err := h.use(cookie)
+	if err != nil {
+		t.Fatalf("SessionFor = %v, want the new session", err)
+	}
+	if s.Subject != "user-123" || s.CSRFToken != r.csrf || !slices.Equal(s.Groups, []string{"mealquest-admin"}) {
+		t.Errorf("SessionFor = %+v", s)
+	}
+}
+
+func TestStartSessionStoresOnlyTheHash(t *testing.T) {
+	t.Parallel()
+	h := newSessionHarness(t)
+	_, cookie := h.signIn(t)
+	var n int
+	err := h.db.Reader.QueryRow(`SELECT count(*) FROM sessions WHERE
+		id_hash = ?1 OR subject = ?1 OR email = ?1 OR name = ?1 OR groups = ?1 OR csrf_token = ?1`,
+		cookie.Value).Scan(&n)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n != 0 {
+		t.Error("the raw session ID is stored in the sessions table")
+	}
+}
+
+func TestSessionLastSeenSlides(t *testing.T) {
+	t.Parallel()
+	h := newSessionHarness(t)
+	_, cookie := h.signIn(t)
+
+	// Used every 20 days, the session outlives several idle periods.
+	for range 4 {
+		h.advance(20 * 24 * time.Hour)
+		s, err := h.use(cookie)
+		if err != nil {
+			t.Fatalf("at %v SessionFor = %v, want the session", h.clock, err)
+		}
+		if !s.LastSeenAt.Equal(h.clock) || !s.ExpiresAt.Equal(h.clock.Add(testIdle)) {
+			t.Errorf("at %v session last seen %v, expires %v, want %v, %v",
+				h.clock, s.LastSeenAt, s.ExpiresAt, h.clock, h.clock.Add(testIdle))
+		}
+		r := h.rows(t)[0]
+		if !r.lastSeen.Equal(h.clock) || !r.expires.Equal(h.clock.Add(testIdle)) || !r.created.Equal(testEpoch) {
+			t.Errorf("at %v row created %v, last seen %v, expires %v", h.clock, r.created, r.lastSeen, r.expires)
+		}
+	}
+}
+
+func TestSessionIdleExpiry(t *testing.T) {
+	t.Parallel()
+	h := newSessionHarness(t)
+	_, cookie := h.signIn(t)
+
+	h.advance(testIdle - time.Millisecond)
+	if _, err := h.use(cookie); err != nil {
+		t.Fatalf("just inside the idle limit SessionFor = %v, want the session", err)
+	}
+	h.advance(testIdle)
+	if _, err := h.use(cookie); !errors.Is(err, ErrNoSession) {
+		t.Fatalf("after idle SessionFor = %v, want ErrNoSession", err)
+	}
+	if n := len(h.rows(t)); n != 0 {
+		t.Errorf("expired session left %d rows, want 0", n)
+	}
+	// Turning the clock back cannot revive it.
+	h.clock = testEpoch
+	if _, err := h.use(cookie); !errors.Is(err, ErrNoSession) {
+		t.Errorf("after deletion SessionFor = %v, want ErrNoSession", err)
+	}
+}
+
+func TestSessionAbsoluteExpiry(t *testing.T) {
+	t.Parallel()
+	h := newSessionHarness(t)
+	_, cookie := h.signIn(t)
+
+	for h.clock.Before(testEpoch.Add(testMax - 20*24*time.Hour)) {
+		h.advance(20 * 24 * time.Hour)
+		if _, err := h.use(cookie); err != nil {
+			t.Fatalf("at %v SessionFor = %v, want the session", h.clock, err)
+		}
+	}
+	// Last used 20 days before the absolute limit: the idle window would run
+	// past it, so expiry is capped there.
+	if r := h.rows(t)[0]; !r.expires.Equal(testEpoch.Add(testMax)) {
+		t.Errorf("expires_at = %v, want the absolute limit %v", r.expires, testEpoch.Add(testMax))
+	}
+
+	h.clock = testEpoch.Add(testMax - time.Millisecond)
+	if _, err := h.use(cookie); err != nil {
+		t.Fatalf("just inside the absolute limit SessionFor = %v, want the session", err)
+	}
+	h.clock = testEpoch.Add(testMax)
+	if _, err := h.use(cookie); !errors.Is(err, ErrNoSession) {
+		t.Fatalf("at the absolute limit, used 1ms ago, SessionFor = %v, want ErrNoSession", err)
+	}
+	if n := len(h.rows(t)); n != 0 {
+		t.Errorf("expired session left %d rows, want 0", n)
+	}
+}
+
+// A max with fractional seconds rounds the cookie Max-Age up, so the browser
+// keeps the cookie until the server-side absolute limit.
+func TestSessionCookieOutlivesFractionalMax(t *testing.T) {
+	t.Parallel()
+	h := newSessionHarness(t)
+	h.sessions.idle, h.sessions.max = 1500*time.Millisecond, 2500*time.Millisecond
+	_, cookie := h.signIn(t)
+	if cookie.MaxAge != 3 {
+		t.Errorf("session cookie MaxAge = %d, want 3", cookie.MaxAge)
+	}
+	if r := h.rows(t)[0]; !r.expires.Equal(testEpoch.Add(1500 * time.Millisecond)) {
+		t.Errorf("expires_at = %v, want %v", r.expires, testEpoch.Add(1500*time.Millisecond))
+	}
+
+	h.advance(time.Second)
+	if _, err := h.use(cookie); err != nil {
+		t.Fatalf("at 1s SessionFor = %v, want the session", err)
+	}
+	h.clock = testEpoch.Add(2500*time.Millisecond - time.Millisecond)
+	if _, err := h.use(cookie); err != nil {
+		t.Fatalf("just inside the absolute limit SessionFor = %v, want the session", err)
+	}
+	h.clock = testEpoch.Add(2500 * time.Millisecond)
+	if _, err := h.use(cookie); !errors.Is(err, ErrNoSession) {
+		t.Errorf("at the absolute limit SessionFor = %v, want ErrNoSession", err)
+	}
+}
+
+// A lifetime near the largest accepted duration still yields a positive,
+// rounded-up cookie Max-Age rather than overflowing.
+func TestSessionCookieMaxAgeNearLargestMax(t *testing.T) {
+	t.Parallel()
+	largest, err := time.ParseDuration("2562047h47m16.854s")
+	if err != nil {
+		t.Fatal(err)
+	}
+	h := newSessionHarness(t)
+	h.sessions.max = largest
+	_, cookie := h.signIn(t)
+	if want := 9223372037; cookie.MaxAge != want {
+		t.Errorf("session cookie MaxAge = %d, want %d", cookie.MaxAge, want)
+	}
+}
+
+// A lifetime shortened by configuration applies to existing sessions even
+// though their stored expires_at is later.
+func TestSessionLifetimeChecksUseCurrentConfig(t *testing.T) {
+	t.Parallel()
+	h := newSessionHarness(t)
+	_, cookie := h.signIn(t)
+	h.sessions.idle = 24 * time.Hour
+	h.advance(24 * time.Hour)
+	if _, err := h.use(cookie); !errors.Is(err, ErrNoSession) {
+		t.Errorf("past the shortened idle SessionFor = %v, want ErrNoSession", err)
+	}
+
+	_, cookie = h.signIn(t)
+	h.sessions.idle, h.sessions.max = 24*time.Hour, 48*time.Hour
+	for range 3 {
+		h.advance(12 * time.Hour)
+		if _, err := h.use(cookie); err != nil {
+			t.Fatalf("SessionFor = %v, want the session", err)
+		}
+	}
+	h.advance(12 * time.Hour)
+	if _, err := h.use(cookie); !errors.Is(err, ErrNoSession) {
+		t.Errorf("past the shortened max SessionFor = %v, want ErrNoSession", err)
+	}
+
+	// Used recently and with expires_at still ahead, but older than a max
+	// shortened after that use: only the absolute check ends it.
+	h.sessions.idle, h.sessions.max = testIdle, testMax
+	_, cookie = h.signIn(t)
+	h.advance(10 * 24 * time.Hour)
+	if _, err := h.use(cookie); err != nil {
+		t.Fatalf("SessionFor = %v, want the session", err)
+	}
+	h.sessions.max = 10 * 24 * time.Hour
+	h.advance(time.Hour)
+	if _, err := h.use(cookie); !errors.Is(err, ErrNoSession) {
+		t.Errorf("past a max shortened after the last use SessionFor = %v, want ErrNoSession", err)
+	}
+}
+
+func TestSessionForRejectsBadCookies(t *testing.T) {
+	t.Parallel()
+	h := newSessionHarness(t)
+	h.signIn(t)
+	for name, c := range map[string]*http.Cookie{
+		"missing":      nil,
+		"empty":        {Name: SessionCookieName, Value: ""},
+		"not base64":   {Name: SessionCookieName, Value: strings.Repeat("!", 43)},
+		"short":        {Name: SessionCookieName, Value: "AAAA"},
+		"unknown ID":   {Name: SessionCookieName, Value: randomToken()},
+		"other cookie": {Name: "mealquest_session", Value: randomToken()},
+	} {
+		if _, err := h.use(c); !errors.Is(err, ErrNoSession) {
+			t.Errorf("%s: SessionFor = %v, want ErrNoSession", name, err)
+		}
+	}
+	if n := len(h.rows(t)); n != 1 {
+		t.Errorf("sessions has %d rows, want the signed-in session only", n)
+	}
+}
+
+func (h *sessionHarness) logout(cookies ...*http.Cookie) *http.Response {
+	req := httptest.NewRequest(http.MethodPost, LogoutPath, nil)
+	for _, c := range cookies {
+		req.AddCookie(c)
+	}
+	rec := httptest.NewRecorder()
+	h.router.ServeHTTP(rec, req)
+	return rec.Result()
+}
+
+func TestLogout(t *testing.T) {
+	t.Parallel()
+	h := newSessionHarness(t)
+	_, cookie := h.signIn(t)
+	_, other := h.signIn(t)
+
+	resp := h.logout(cookie)
+	if resp.StatusCode != http.StatusSeeOther {
+		t.Fatalf("logout status = %d, want 303", resp.StatusCode)
+	}
+	want := h.provider.issuer() + "/end-session/"
+	if got := resp.Header.Get("Location"); got != want || h.auth.EndSessionURL() != want {
+		t.Errorf("logout redirect = %q, EndSessionURL = %q, want %q", got, h.auth.EndSessionURL(), want)
+	}
+	raw := sessionSetCookie(t, resp)
+	assertSessionCookieAttributes(t, raw)
+	if !strings.HasPrefix(raw, SessionCookieName+"=;") || !strings.Contains(raw, "Max-Age=0") {
+		t.Errorf("logout Set-Cookie = %q, want the cookie cleared", raw)
+	}
+
+	rows := h.rows(t)
+	if len(rows) != 1 || rows[0].idHash != sha256Hex(other.Value) {
+		t.Errorf("after logout sessions = %+v, want only the other session", rows)
+	}
+	if _, err := h.use(cookie); !errors.Is(err, ErrNoSession) {
+		t.Errorf("logged-out cookie: SessionFor = %v, want ErrNoSession", err)
+	}
+	if _, err := h.use(other); err != nil {
+		t.Errorf("other session: SessionFor = %v, want it untouched", err)
+	}
+}
+
+func TestLogoutWithoutSession(t *testing.T) {
+	t.Parallel()
+	h := newSessionHarness(t)
+	resp := h.logout()
+	if resp.StatusCode != http.StatusSeeOther || resp.Header.Get("Location") != h.provider.issuer()+"/end-session/" {
+		t.Errorf("logout = %d to %q, want 303 to the end session endpoint", resp.StatusCode, resp.Header.Get("Location"))
+	}
+	assertSessionCookieAttributes(t, sessionSetCookie(t, resp))
+}
+
+func TestLogoutIsPostOnly(t *testing.T) {
+	t.Parallel()
+	h := newSessionHarness(t)
+	_, cookie := h.signIn(t)
+	if resp := h.get(LogoutPath, cookie); resp.StatusCode != http.StatusMethodNotAllowed {
+		t.Errorf("GET %s status = %d, want 405", LogoutPath, resp.StatusCode)
+	}
+	if _, err := h.use(cookie); err != nil {
+		t.Errorf("after GET %s SessionFor = %v, want the session", LogoutPath, err)
+	}
+}
+
+func TestLogoutSessionError(t *testing.T) {
+	t.Parallel()
+	h := newHarness(t)
+	h.sessions.err = errors.New("database down")
+	rec := httptest.NewRecorder()
+	h.router.ServeHTTP(rec, httptest.NewRequest(http.MethodPost, LogoutPath, nil))
+	if rec.Code != http.StatusInternalServerError {
+		t.Errorf("logout status = %d, want 500", rec.Code)
+	}
+}
+
+func TestNewRequiresEndSessionEndpoint(t *testing.T) {
+	t.Parallel()
+	p := newFakeProvider(t)
+	p.discoveryOverrides = map[string]any{"end_session_endpoint": nil}
+	_, err := New(context.Background(), Config{
+		Issuer:        p.issuer(),
+		ClientID:      testClientID,
+		ClientSecret:  testClientSecret,
+		PublicURL:     testPublicURL,
+		SecretKey:     []byte("k"),
+		AllowedGroups: testAllowedGroups,
+	}, &memorySessions{}, slog.New(slog.DiscardHandler))
+	if err == nil || !strings.Contains(err.Error(), "end session endpoint") {
+		t.Errorf("New error = %v, want the missing end session endpoint named", err)
+	}
+}
+
+func TestNewSessionManagerValidates(t *testing.T) {
+	t.Parallel()
+	db := &store.Store{}
+	for _, tc := range []struct {
+		name      string
+		db        *store.Store
+		idle, max time.Duration
+	}{
+		{"nil store", nil, time.Hour, time.Hour},
+		{"zero idle", db, 0, time.Hour},
+		{"negative max", db, time.Hour, -time.Hour},
+		{"max below idle", db, 2 * time.Hour, time.Hour},
+	} {
+		if _, err := NewSessionManager(tc.db, tc.idle, tc.max); err == nil {
+			t.Errorf("%s: NewSessionManager succeeded", tc.name)
+		}
+	}
+}

internal/config/config.go

@@ -11,6 +11,9 @@ import (
 	"strconv"
 	"strings"
 	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/forwarded"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/secureurl"
 )
 
 // Environment variable names.
@@ -20,6 +23,25 @@ const (
 	EnvDataDir         = "MEALQUEST_DATA_DIR"
 	EnvShutdownTimeout = "MEALQUEST_SHUTDOWN_TIMEOUT"
 	EnvSecretKeyFile   = "MEALQUEST_SECRET_KEY_FILE"
+
+	EnvOIDCIssuer           = "MEALQUEST_OIDC_ISSUER"
+	EnvOIDCClientID         = "MEALQUEST_OIDC_CLIENT_ID"
+	EnvOIDCClientSecretFile = "MEALQUEST_OIDC_CLIENT_SECRET_FILE"
+	EnvOIDCAllowedGroups    = "MEALQUEST_OIDC_ALLOWED_GROUPS"
+
+	EnvSessionIdle = "MEALQUEST_SESSION_IDLE"
+	EnvSessionMax  = "MEALQUEST_SESSION_MAX"
+
+	EnvTrustedProxy = "MEALQUEST_TRUSTED_PROXY"
+
+	EnvDefaultTZ = "MEALQUEST_DEFAULT_TZ"
+)
+
+// Session lifetime defaults (D-004): long enough that the kitchen tablet
+// stays signed in.
+const (
+	DefaultSessionIdle = 720 * time.Hour  // 30 days
+	DefaultSessionMax  = 4320 * time.Hour // 180 days
 )
 
 // Config is the validated service configuration.
@@ -29,6 +51,28 @@ type Config struct {
 	DataDir         string
 	ShutdownTimeout time.Duration
 	SecretKey       Secret
+
+	// OIDCIssuer is the Authentik issuer URL used for discovery.
+	OIDCIssuer       *url.URL
+	OIDCClientID     string
+	OIDCClientSecret Secret
+	// OIDCAllowedGroups lists the groups whose members may sign in.
+	OIDCAllowedGroups []string
+
+	// SessionIdle ends a session left unused this long.
+	SessionIdle time.Duration
+	// SessionMax ends every session this long after sign-in, used or not.
+	SessionMax time.Duration
+
+	// TrustedProxy lists the reverse proxies whose X-Forwarded-For and
+	// X-Forwarded-Proto headers are honoured. Empty trusts no peer.
+	TrustedProxy forwarded.Trusted
+
+	// DefaultTZ is the IANA zone the household settings are created with on
+	// first boot. It is optional and not validated here: boot requires and
+	// validates it only while the settings do not exist yet, and ignores it
+	// once they do. Empty when unset.
+	DefaultTZ string
 }
 
 // PublicOrigin returns the scheme and host of PublicURL, the only parts of it
@@ -47,10 +91,25 @@ func load(lookup func(string) (string, bool)) (Config, error) {
 	r := reader{lookup: lookup}
 	cfg := Config{
 		HTTPAddr:        r.listenAddr(EnvHTTPAddr),
-		PublicURL:       r.httpURL(EnvPublicURL),
+		PublicURL:       r.secureURL(EnvPublicURL),
 		DataDir:         r.dir(EnvDataDir),
 		ShutdownTimeout: r.duration(EnvShutdownTimeout),
 		SecretKey:       r.secretFile(EnvSecretKeyFile),
+
+		OIDCIssuer:        r.secureURL(EnvOIDCIssuer),
+		OIDCClientID:      r.str(EnvOIDCClientID),
+		OIDCClientSecret:  r.secretFile(EnvOIDCClientSecretFile),
+		OIDCAllowedGroups: r.list(EnvOIDCAllowedGroups),
+
+		SessionIdle: r.sessionDuration(EnvSessionIdle, DefaultSessionIdle),
+		SessionMax:  r.sessionDuration(EnvSessionMax, DefaultSessionMax),
+
+		TrustedProxy: r.trustedProxy(EnvTrustedProxy),
+
+		DefaultTZ: r.optional(EnvDefaultTZ),
+	}
+	if cfg.SessionIdle > 0 && cfg.SessionMax > 0 && cfg.SessionMax < cfg.SessionIdle {
+		r.fail(EnvSessionMax, "must be at least %s (%s)", EnvSessionIdle, cfg.SessionIdle)
 	}
 	if len(r.problems) > 0 {
 		return Config{}, &Error{Problems: r.problems}
@@ -114,6 +173,41 @@ func (r *reader) required(name string) (string, bool) {
 	return v, true
 }
 
+func (r *reader) str(name string) string {
+	v, _ := r.required(name)
+	return v
+}
+
+// list parses a comma-separated list. Every entry must be non-empty after
+// trimming spaces.
+func (r *reader) list(name string) []string {
+	v, ok := r.required(name)
+	if !ok {
+		return nil
+	}
+	items := strings.Split(v, ",")
+	for i, item := range items {
+		items[i] = strings.TrimSpace(item)
+		if items[i] == "" {
+			r.fail(name, "empty entry in comma-separated list %q", v)
+			return nil
+		}
+	}
+	return items
+}
+
+// trustedProxy parses an optional comma-separated list of IP addresses and
+// CIDR prefixes with forwarded.ParseTrusted. Unset or blank trusts no peer.
+func (r *reader) trustedProxy(name string) forwarded.Trusted {
+	v, _ := r.lookup(name)
+	t, err := forwarded.ParseTrusted(v)
+	if err != nil {
+		r.fail(name, "%v", err)
+		return nil
+	}
+	return t
+}
+
 func (r *reader) listenAddr(name string) string {
 	v, ok := r.required(name)
 	if !ok {
@@ -155,15 +249,21 @@ func validHostname(h string) bool {
 	return true
 }
 
-func (r *reader) httpURL(name string) *url.URL {
+// secureURL reads an absolute URL that must pass secureurl.Check: https://,
+// or http:// to a loopback host only.
+func (r *reader) secureURL(name string) *url.URL {
 	v, ok := r.required(name)
 	if !ok {
 		return nil
 	}
 	// The value is never echoed: it may carry credentials.
 	u, err := url.Parse(v)
-	if err != nil || (u.Scheme != "http" && u.Scheme != "https") || u.Hostname() == "" {
-		r.fail(name, "invalid URL (want absolute http:// or https:// URL)")
+	if err != nil {
+		r.fail(name, "invalid URL (want absolute https:// URL)")
+		return nil
+	}
+	if err := secureurl.Check(u); err != nil {
+		r.fail(name, "invalid URL: %v", err)
 		return nil
 	}
 	if u.User != nil {
@@ -195,6 +295,32 @@ func (r *reader) duration(name string) time.Duration {
 	if !ok {
 		return 0
 	}
+	return r.parseDuration(name, v)
+}
+
+// optionalDuration returns def when name is unset. A set value, even an empty
+// one, must be a valid positive duration.
+func (r *reader) optionalDuration(name string, def time.Duration) time.Duration {
+	v, ok := r.lookup(name)
+	if !ok {
+		return def
+	}
+	return r.parseDuration(name, v)
+}
+
+// sessionDuration is optionalDuration restricted to whole milliseconds:
+// session expiry is stored as a store.Timestamp, which keeps millisecond
+// precision, so a finer duration could not be honoured.
+func (r *reader) sessionDuration(name string, def time.Duration) time.Duration {
+	d := r.optionalDuration(name, def)
+	if d%time.Millisecond != 0 {
+		r.fail(name, "duration must be a whole number of milliseconds, got %s", d)
+		return 0
+	}
+	return d
+}
+
+func (r *reader) parseDuration(name, v string) time.Duration {
 	d, err := time.ParseDuration(v)
 	if err != nil {
 		r.fail(name, "invalid duration %q (want e.g. 10s, 1m)", v)
@@ -207,6 +333,12 @@ func (r *reader) duration(name string) time.Duration {
 	return d
 }
 
+// optional returns the variable's value, or "" when it is unset.
+func (r *reader) optional(name string) string {
+	v, _ := r.lookup(name)
+	return v
+}
+
 // secretFile reads a secret from the file named by name, which must end in
 // _FILE. Setting the secret inline (name without _FILE) is rejected.
 func (r *reader) secretFile(name string) Secret {

internal/config/config_test.go

@@ -3,13 +3,17 @@ package config
 import (
 	"errors"
 	"fmt"
+	"net/netip"
 	"net/url"
 	"os"
 	"path/filepath"
+	"reflect"
 	"slices"
 	"strings"
 	"testing"
 	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/forwarded"
 )
 
 func TestLoad(t *testing.T) {
@@ -21,6 +25,10 @@ func TestLoad(t *testing.T) {
 		t.Fatal(err)
 	}
 	unreadablePath := filepath.Join(dir, "missing_secret")
+	clientSecretPath := filepath.Join(dir, "oidc_client_secret")
+	if err := os.WriteFile(clientSecretPath, []byte("client-s3cret\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
 	emptyPath := filepath.Join(dir, "empty_secret")
 	if err := os.WriteFile(emptyPath, []byte("\n"), 0o600); err != nil {
 		t.Fatal(err)
@@ -33,6 +41,11 @@ func TestLoad(t *testing.T) {
 			EnvDataDir:         dir,
 			EnvShutdownTimeout: "15s",
 			EnvSecretKeyFile:   secretPath,
+
+			EnvOIDCIssuer:           "https://auth.example.com/application/o/mealquest/",
+			EnvOIDCClientID:         "mealquest",
+			EnvOIDCClientSecretFile: clientSecretPath,
+			EnvOIDCAllowedGroups:    "mealquest-admin",
 		}
 	}
 	with := func(changes map[string]string, unset ...string) map[string]string {
@@ -55,6 +68,16 @@ func TestLoad(t *testing.T) {
 			name: "all required vars present",
 			env:  valid(),
 		},
+		{
+			name: "default time zone set",
+			env:  with(map[string]string{EnvDefaultTZ: "America/New_York"}),
+		},
+		{
+			// Validated only when seeding the household settings, so a
+			// stale value cannot stop a boot that no longer uses it.
+			name: "default time zone not an IANA zone",
+			env:  with(map[string]string{EnvDefaultTZ: "Mars/Olympus_Mons"}),
+		},
 		{
 			name:    "one missing",
 			env:     with(nil, EnvHTTPAddr),
@@ -70,6 +93,7 @@ func TestLoad(t *testing.T) {
 			env:  map[string]string{},
 			badVars: []string{
 				EnvHTTPAddr, EnvPublicURL, EnvDataDir, EnvShutdownTimeout, EnvSecretKeyFile,
+				EnvOIDCIssuer, EnvOIDCClientID, EnvOIDCClientSecretFile, EnvOIDCAllowedGroups,
 			},
 		},
 		{
@@ -139,6 +163,24 @@ func TestLoad(t *testing.T) {
 			env:     with(map[string]string{EnvPublicURL: "http://:8080"}),
 			badVars: []string{EnvPublicURL},
 		},
+		{
+			name:    "plain HTTP public URL on a remote host",
+			env:     with(map[string]string{EnvPublicURL: "http://meals.example.com"}),
+			badVars: []string{EnvPublicURL},
+		},
+		{
+			name:    "plain HTTP public URL on a non-loopback IP",
+			env:     with(map[string]string{EnvPublicURL: "http://192.168.1.20:8080"}),
+			badVars: []string{EnvPublicURL},
+		},
+		{
+			name: "plain HTTP public URL on 127.0.0.1",
+			env:  with(map[string]string{EnvPublicURL: "http://127.0.0.1:8080"}),
+		},
+		{
+			name: "plain HTTP public URL on [::1]",
+			env:  with(map[string]string{EnvPublicURL: "http://[::1]:8080"}),
+		},
 		{
 			name:    "relative public URL",
 			env:     with(map[string]string{EnvPublicURL: "meals.example.com"}),
@@ -169,6 +211,143 @@ func TestLoad(t *testing.T) {
 			env:     with(map[string]string{"MEALQUEST_SECRET_KEY": "inline"}),
 			badVars: []string{"MEALQUEST_SECRET_KEY"},
 		},
+		{
+			name:    "inline OIDC client secret rejected",
+			env:     with(map[string]string{"MEALQUEST_OIDC_CLIENT_SECRET": "inline"}),
+			badVars: []string{"MEALQUEST_OIDC_CLIENT_SECRET"},
+		},
+		{
+			name:    "unreadable OIDC client secret file",
+			env:     with(map[string]string{EnvOIDCClientSecretFile: unreadablePath}),
+			badVars: []string{EnvOIDCClientSecretFile},
+		},
+		{
+			name:    "relative OIDC issuer",
+			env:     with(map[string]string{EnvOIDCIssuer: "auth.example.com"}),
+			badVars: []string{EnvOIDCIssuer},
+		},
+		{
+			name:    "non-http OIDC issuer",
+			env:     with(map[string]string{EnvOIDCIssuer: "ftp://auth.example.com"}),
+			badVars: []string{EnvOIDCIssuer},
+		},
+		{
+			name:    "plain HTTP OIDC issuer on a remote host",
+			env:     with(map[string]string{EnvOIDCIssuer: "http://auth.example.com/application/o/mealquest/"}),
+			badVars: []string{EnvOIDCIssuer},
+		},
+		{
+			name: "plain HTTP OIDC issuer on localhost",
+			env:  with(map[string]string{EnvOIDCIssuer: "http://localhost:9000/application/o/mealquest/"}),
+		},
+		{
+			name: "several allowed groups",
+			env:  with(map[string]string{EnvOIDCAllowedGroups: "mealquest-admin, family"}),
+		},
+		{
+			name:    "empty allowed group entry",
+			env:     with(map[string]string{EnvOIDCAllowedGroups: "mealquest-admin,,family"}),
+			badVars: []string{EnvOIDCAllowedGroups},
+		},
+		{
+			name:    "trailing comma in allowed groups",
+			env:     with(map[string]string{EnvOIDCAllowedGroups: "mealquest-admin,"}),
+			badVars: []string{EnvOIDCAllowedGroups},
+		},
+		{
+			name:    "blank OIDC client ID",
+			env:     with(map[string]string{EnvOIDCClientID: "  "}),
+			badVars: []string{EnvOIDCClientID},
+		},
+		{
+			name: "session lifetimes set",
+			env:  with(map[string]string{EnvSessionIdle: "24h", EnvSessionMax: "48h"}),
+		},
+		{
+			name: "session max equal to idle",
+			env:  with(map[string]string{EnvSessionIdle: "24h", EnvSessionMax: "24h"}),
+		},
+		{
+			name:    "invalid session idle",
+			env:     with(map[string]string{EnvSessionIdle: "a month"}),
+			badVars: []string{EnvSessionIdle},
+		},
+		{
+			name:    "empty session idle",
+			env:     with(map[string]string{EnvSessionIdle: ""}),
+			badVars: []string{EnvSessionIdle},
+		},
+		{
+			name:    "non-positive session max",
+			env:     with(map[string]string{EnvSessionMax: "-1h"}),
+			badVars: []string{EnvSessionMax},
+		},
+		{
+			name: "whole-millisecond session lifetimes",
+			env:  with(map[string]string{EnvSessionIdle: "1ms", EnvSessionMax: "2ms"}),
+		},
+		{
+			name:    "sub-millisecond session idle",
+			env:     with(map[string]string{EnvSessionIdle: "1500us", EnvSessionMax: "2ms"}),
+			badVars: []string{EnvSessionIdle},
+		},
+		{
+			name:    "sub-millisecond session max",
+			env:     with(map[string]string{EnvSessionIdle: "1ms", EnvSessionMax: "1ms500us"}),
+			badVars: []string{EnvSessionMax},
+		},
+		{
+			name:    "session max below idle",
+			env:     with(map[string]string{EnvSessionIdle: "48h", EnvSessionMax: "24h"}),
+			badVars: []string{EnvSessionMax},
+		},
+		{
+			name:    "session max below default idle",
+			env:     with(map[string]string{EnvSessionMax: "719h"}),
+			badVars: []string{EnvSessionMax},
+		},
+		{
+			name: "trusted proxy IP",
+			env:  with(map[string]string{EnvTrustedProxy: "10.60.1.33"}),
+		},
+		{
+			name: "trusted proxy IPs and CIDRs",
+			env:  with(map[string]string{EnvTrustedProxy: "10.60.1.33, 172.16.0.0/12,2001:db8::/32,::1"}),
+		},
+		{
+			name: "blank trusted proxy trusts no peer",
+			env:  with(map[string]string{EnvTrustedProxy: "  "}),
+		},
+		{
+			name:    "trusted proxy not an IP",
+			env:     with(map[string]string{EnvTrustedProxy: "traefik"}),
+			badVars: []string{EnvTrustedProxy},
+		},
+		{
+			name:    "trusted proxy invalid CIDR",
+			env:     with(map[string]string{EnvTrustedProxy: "10.60.1.0/33"}),
+			badVars: []string{EnvTrustedProxy},
+		},
+		{
+			name:    "trusted proxy CIDR with host bits",
+			env:     with(map[string]string{EnvTrustedProxy: "10.60.1.33/24"}),
+			badVars: []string{EnvTrustedProxy},
+		},
+		{
+			name:    "trusted proxy empty entry",
+			env:     with(map[string]string{EnvTrustedProxy: "10.60.1.33,,10.60.1.34"}),
+			badVars: []string{EnvTrustedProxy},
+		},
+		{
+			name:    "trusted proxy trusting everyone",
+			env:     with(map[string]string{EnvTrustedProxy: "0.0.0.0/0"}),
+			badVars: []string{EnvTrustedProxy},
+		},
+		{
+			name:    "trusted proxy with port",
+			env:     with(map[string]string{EnvTrustedProxy: "10.60.1.33:443"}),
+			badVars: []string{EnvTrustedProxy},
+		},
 		{
 			name: "several invalid values are all named",
 			env: with(map[string]string{
@@ -211,7 +390,7 @@ func TestLoad(t *testing.T) {
 					t.Errorf("error message %q does not name %s", err.Error(), v)
 				}
 			}
-			if cfg != (Config{}) {
+			if !reflect.ValueOf(cfg).IsZero() {
 				t.Errorf("load() returned non-zero Config alongside error: %+v", cfg)
 			}
 		})
@@ -226,12 +405,23 @@ func TestLoadValues(t *testing.T) {
 	if err := os.WriteFile(secretPath, []byte("s3cret-value\r\n"), 0o600); err != nil {
 		t.Fatal(err)
 	}
+	clientSecretPath := filepath.Join(dir, "oidc_client_secret")
+	if err := os.WriteFile(clientSecretPath, []byte("client-s3cret\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
 	env := map[string]string{
 		EnvHTTPAddr:        "127.0.0.1:9000",
 		EnvPublicURL:       "http://localhost:9000",
 		EnvDataDir:         dir,
 		EnvShutdownTimeout: "1m30s",
 		EnvSecretKeyFile:   secretPath,
+
+		EnvOIDCIssuer:           "https://auth.example.com/application/o/mealquest/",
+		EnvOIDCClientID:         "mealquest",
+		EnvOIDCClientSecretFile: clientSecretPath,
+		EnvOIDCAllowedGroups:    " mealquest-admin ,family",
+
+		EnvDefaultTZ: "Europe/London",
 	}
 	cfg, err := load(func(k string) (string, bool) { v, ok := env[k]; return v, ok })
 	if err != nil {
@@ -253,6 +443,43 @@ func TestLoadValues(t *testing.T) {
 	if cfg.SecretKey.Reveal() != "s3cret-value" {
 		t.Errorf("SecretKey.Reveal() = %q, want trailing newline trimmed", cfg.SecretKey.Reveal())
 	}
+	if got, want := cfg.OIDCIssuer.String(), "https://auth.example.com/application/o/mealquest/"; got != want {
+		t.Errorf("OIDCIssuer = %q, want %q", got, want)
+	}
+	if cfg.OIDCClientID != "mealquest" {
+		t.Errorf("OIDCClientID = %q", cfg.OIDCClientID)
+	}
+	if cfg.OIDCClientSecret.Reveal() != "client-s3cret" {
+		t.Errorf("OIDCClientSecret.Reveal() = %q", cfg.OIDCClientSecret.Reveal())
+	}
+	if want := []string{"mealquest-admin", "family"}; !slices.Equal(cfg.OIDCAllowedGroups, want) {
+		t.Errorf("OIDCAllowedGroups = %q, want %q", cfg.OIDCAllowedGroups, want)
+	}
+	if cfg.SessionIdle != 720*time.Hour || cfg.SessionMax != 4320*time.Hour {
+		t.Errorf("SessionIdle, SessionMax = %v, %v, want defaults 720h, 4320h", cfg.SessionIdle, cfg.SessionMax)
+	}
+
+	if cfg.TrustedProxy != nil {
+		t.Errorf("TrustedProxy = %v, want none when unset", cfg.TrustedProxy)
+	}
+
+	env[EnvSessionIdle] = "12h"
+	env[EnvSessionMax] = "36h"
+	env[EnvTrustedProxy] = "10.60.1.33, 172.16.0.0/12"
+	cfg, err = load(func(k string) (string, bool) { v, ok := env[k]; return v, ok })
+	if err != nil {
+		t.Fatalf("load() error = %v", err)
+	}
+	if cfg.SessionIdle != 12*time.Hour || cfg.SessionMax != 36*time.Hour {
+		t.Errorf("SessionIdle, SessionMax = %v, %v, want 12h, 36h", cfg.SessionIdle, cfg.SessionMax)
+	}
+	want := forwarded.Trusted{netip.MustParsePrefix("10.60.1.33/32"), netip.MustParsePrefix("172.16.0.0/12")}
+	if !slices.Equal(cfg.TrustedProxy, want) {
+		t.Errorf("TrustedProxy = %v, want %v", cfg.TrustedProxy, want)
+	}
+	if cfg.DefaultTZ != "Europe/London" {
+		t.Errorf("DefaultTZ = %q, want Europe/London", cfg.DefaultTZ)
+	}
 }
 
 func TestSecretRedacted(t *testing.T) {
@@ -260,7 +487,7 @@ func TestSecretRedacted(t *testing.T) {
 
 	s := Secret{value: "s3cret-value"}
 	for _, format := range []string{"%v", "%s", "%+v", "%#v"} {
-		cfg := Config{SecretKey: s}
+		cfg := Config{SecretKey: s, OIDCClientSecret: s}
 		for _, out := range []string{fmt.Sprintf(format, s), fmt.Sprintf(format, cfg)} {
 			if strings.Contains(out, "s3cret-value") {
 				t.Errorf("format %s leaked secret: %s", format, out)

internal/db/models.go

@@ -85,6 +85,7 @@ type HouseholdSetting struct {
 	UpdatesSeenAt         sql.NullString
 	CreatedAt             string
 	UpdatedAt             string
+	UpdatedBy             sql.NullString
 }
 
 type IntegrationsGoogle struct {

internal/db/settings.sql.go

@@ -57,7 +57,7 @@ func (q *Queries) GetChatSettings(ctx context.Context) (ChatSetting, error) {
 }
 
 const getHouseholdSettings = `-- name: GetHouseholdSettings :one
-SELECT id, timezone, dinner_time, reminder_time, review_time, plan_draft_dow, plan_draft_time, suggestions_dow, suggestions_time, chat_autosend_dow, chat_autosend_time, onboarding_completed_at, updates_seen_at, created_at, updated_at FROM household_settings
+SELECT id, timezone, dinner_time, reminder_time, review_time, plan_draft_dow, plan_draft_time, suggestions_dow, suggestions_time, chat_autosend_dow, chat_autosend_time, onboarding_completed_at, updates_seen_at, created_at, updated_at, updated_by FROM household_settings
 WHERE id = 1
 `
 
@@ -81,6 +81,7 @@ func (q *Queries) GetHouseholdSettings(ctx context.Context) (HouseholdSetting, e
 		&i.UpdatesSeenAt,
 		&i.CreatedAt,
 		&i.UpdatedAt,
+		&i.UpdatedBy,
 	)
 	return i, err
 }
@@ -248,12 +249,12 @@ INSERT INTO household_settings (
 	id, timezone, dinner_time, reminder_time, review_time, plan_draft_dow,
 	plan_draft_time, suggestions_dow, suggestions_time, chat_autosend_dow,
 	chat_autosend_time, onboarding_completed_at, updates_seen_at,
-	created_at, updated_at
+	updated_by, created_at, updated_at
 ) VALUES (
 	1, ?, ?, ?, ?, ?,
 	?, ?, ?, ?,
 	?, ?, ?,
-	?, ?
+	?, ?, ?
 )
 ON CONFLICT (id) DO UPDATE SET
 	timezone = excluded.timezone,
@@ -268,8 +269,9 @@ ON CONFLICT (id) DO UPDATE SET
 	chat_autosend_time = excluded.chat_autosend_time,
 	onboarding_completed_at = excluded.onboarding_completed_at,
 	updates_seen_at = excluded.updates_seen_at,
+	updated_by = excluded.updated_by,
 	updated_at = excluded.updated_at
-RETURNING id, timezone, dinner_time, reminder_time, review_time, plan_draft_dow, plan_draft_time, suggestions_dow, suggestions_time, chat_autosend_dow, chat_autosend_time, onboarding_completed_at, updates_seen_at, created_at, updated_at
+RETURNING id, timezone, dinner_time, reminder_time, review_time, plan_draft_dow, plan_draft_time, suggestions_dow, suggestions_time, chat_autosend_dow, chat_autosend_time, onboarding_completed_at, updates_seen_at, created_at, updated_at, updated_by
 `
 
 type UpsertHouseholdSettingsParams struct {
@@ -285,6 +287,7 @@ type UpsertHouseholdSettingsParams struct {
 	ChatAutosendTime      string
 	OnboardingCompletedAt sql.NullString
 	UpdatesSeenAt         sql.NullString
+	UpdatedBy             sql.NullString
 	CreatedAt             string
 	UpdatedAt             string
 }
@@ -305,6 +308,7 @@ func (q *Queries) UpsertHouseholdSettings(ctx context.Context, arg UpsertHouseho
 		arg.ChatAutosendTime,
 		arg.OnboardingCompletedAt,
 		arg.UpdatesSeenAt,
+		arg.UpdatedBy,
 		arg.CreatedAt,
 		arg.UpdatedAt,
 	)
@@ -325,6 +329,7 @@ func (q *Queries) UpsertHouseholdSettings(ctx context.Context, arg UpsertHouseho
 		&i.UpdatesSeenAt,
 		&i.CreatedAt,
 		&i.UpdatedAt,
+		&i.UpdatedBy,
 	)
 	return i, err
 }

internal/forwarded/forwarded.go

@@ -0,0 +1,221 @@
+// Package forwarded resolves where a request really came from. The service
+// runs behind a reverse proxy (Traefik), so the TCP peer is usually the proxy;
+// the X-Forwarded-For and X-Forwarded-Proto headers it adds are believed only
+// when the peer is a trusted proxy. From anyone else they are ignored, so a
+// client cannot spoof its address or scheme.
+package forwarded
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"net/netip"
+	"strings"
+)
+
+// Header names honoured from trusted proxies.
+const (
+	HeaderFor   = "X-Forwarded-For"
+	HeaderProto = "X-Forwarded-Proto"
+)
+
+// ErrInvalidHeader marks a malformed forwarded header from a trusted peer.
+var ErrInvalidHeader = errors.New("invalid forwarded header")
+
+// Trusted is the set of proxy addresses whose forwarded headers are honoured.
+// The zero value trusts no peer.
+type Trusted []netip.Prefix
+
+// ParseTrusted parses a comma-separated list of IP addresses and CIDR
+// prefixes. A blank list trusts no peer. Each entry must be a plain address
+// or a prefix with no host bits set; zones, IPv4-mapped IPv6 forms and
+// zero-length prefixes, which would trust every peer, are rejected.
+func ParseTrusted(s string) (Trusted, error) {
+	if strings.TrimSpace(s) == "" {
+		return nil, nil
+	}
+	var t Trusted
+	for _, entry := range strings.Split(s, ",") {
+		entry = strings.TrimSpace(entry)
+		if entry == "" {
+			return nil, fmt.Errorf("empty entry in comma-separated list %q", s)
+		}
+		p, err := parseEntry(entry)
+		if err != nil {
+			return nil, err
+		}
+		t = append(t, p)
+	}
+	return t, nil
+}
+
+func parseEntry(entry string) (netip.Prefix, error) {
+	var p netip.Prefix
+	if strings.Contains(entry, "/") {
+		var err error
+		p, err = netip.ParsePrefix(entry)
+		if err != nil {
+			return netip.Prefix{}, fmt.Errorf("invalid CIDR %q", entry)
+		}
+		if p != p.Masked() {
+			return netip.Prefix{}, fmt.Errorf("CIDR %q has host bits set (did you mean %s?)", entry, p.Masked())
+		}
+	} else {
+		a, err := netip.ParseAddr(entry)
+		if err != nil {
+			return netip.Prefix{}, fmt.Errorf("invalid IP address %q", entry)
+		}
+		if a.Zone() != "" {
+			return netip.Prefix{}, fmt.Errorf("IP address %q must not have a zone", entry)
+		}
+		p = netip.PrefixFrom(a, a.BitLen())
+	}
+	switch {
+	case p.Addr().Is4In6():
+		return netip.Prefix{}, fmt.Errorf("%q is IPv4-mapped IPv6; write the IPv4 form", entry)
+	case p.Bits() == 0:
+		return netip.Prefix{}, fmt.Errorf("%q would trust every peer", entry)
+	}
+	return p, nil
+}
+
+// Contains reports whether a is a trusted proxy address. IPv4-mapped IPv6
+// addresses, as a dual-stack listener reports IPv4 peers, match their IPv4
+// form.
+func (t Trusted) Contains(a netip.Addr) bool {
+	a = normalize(a)
+	for _, p := range t {
+		if p.Contains(a) {
+			return true
+		}
+	}
+	return false
+}
+
+func normalize(a netip.Addr) netip.Addr { return a.Unmap().WithZone("") }
+
+// Origin is where a request came from.
+type Origin struct {
+	// ClientIP is the client's address.
+	ClientIP netip.Addr
+	// Scheme is "https" or "http": the scheme the client used.
+	Scheme string
+}
+
+// Resolve works out r's Origin. When the TCP peer (r.RemoteAddr) is not in
+// trusted, both forwarded headers are ignored: the client is the peer and the
+// scheme is that of the connection.
+//
+// When the peer is trusted:
+//   - X-Forwarded-For entries (across all its header lines, in order) are
+//     walked right to left, skipping trusted proxy addresses; the first
+//     untrusted address is the client. Entries left of it are client-supplied
+//     and not examined. If every entry is trusted the leftmost is the client;
+//     with no X-Forwarded-For the peer is the client.
+//   - X-Forwarded-Proto, if present, must be a single "http" or "https" and
+//     is the scheme; without it the connection's scheme is used.
+//
+// A malformed header from a trusted peer is an error wrapping
+// ErrInvalidHeader; any other error means RemoteAddr is not an IP and port.
+func Resolve(r *http.Request, trusted Trusted) (Origin, error) {
+	peer, err := netip.ParseAddrPort(r.RemoteAddr)
+	if err != nil {
+		return Origin{}, fmt.Errorf("peer address %q is not an IP and port", r.RemoteAddr)
+	}
+	o := Origin{ClientIP: normalize(peer.Addr()), Scheme: "http"}
+	if r.TLS != nil {
+		o.Scheme = "https"
+	}
+	if !trusted.Contains(o.ClientIP) {
+		return o, nil
+	}
+	if values := r.Header.Values(HeaderFor); len(values) > 0 {
+		o.ClientIP, err = clientFromChain(strings.Split(strings.Join(values, ","), ","), trusted)
+		if err != nil {
+			return Origin{}, err
+		}
+	}
+	switch values := r.Header.Values(HeaderProto); len(values) {
+	case 0:
+	case 1:
+		switch scheme := strings.ToLower(strings.TrimSpace(values[0])); scheme {
+		case "http", "https":
+			o.Scheme = scheme
+		default:
+			return Origin{}, fmt.Errorf("%w: %s %q is not http or https", ErrInvalidHeader, HeaderProto, values[0])
+		}
+	default:
+		return Origin{}, fmt.Errorf("%w: %d %s headers, want one", ErrInvalidHeader, len(values), HeaderProto)
+	}
+	return o, nil
+}
+
+// clientFromChain returns the rightmost untrusted address in chain, or the
+// leftmost address when all are trusted.
+func clientFromChain(chain []string, trusted Trusted) (netip.Addr, error) {
+	var client netip.Addr
+	for i := len(chain) - 1; i >= 0; i-- {
+		a, err := netip.ParseAddr(strings.TrimSpace(chain[i]))
+		if err != nil {
+			return netip.Addr{}, fmt.Errorf("%w: %s entry %q is not an IP address", ErrInvalidHeader, HeaderFor, strings.TrimSpace(chain[i]))
+		}
+		client = normalize(a)
+		if !trusted.Contains(client) {
+			break
+		}
+	}
+	return client, nil
+}
+
+type contextKey struct{}
+
+// NewContext returns ctx carrying o.
+func NewContext(ctx context.Context, o Origin) context.Context {
+	return context.WithValue(ctx, contextKey{}, o)
+}
+
+// FromContext returns the Origin ctx carries; ok is false when the request
+// was not resolved.
+func FromContext(ctx context.Context) (o Origin, ok bool) {
+	o, ok = ctx.Value(contextKey{}).(Origin)
+	return o, ok
+}
+
+// ClientIP returns the resolved client address ctx carries.
+func ClientIP(ctx context.Context) (netip.Addr, bool) {
+	o, ok := FromContext(ctx)
+	return o.ClientIP, ok
+}
+
+// Scheme returns the resolved request scheme ctx carries.
+func Scheme(ctx context.Context) (string, bool) {
+	o, ok := FromContext(ctx)
+	return o.Scheme, ok
+}
+
+// LogAttr is the log attribute key for the resolved client address.
+const LogAttr = "client_ip"
+
+// LogHandler wraps h so every record logged with a resolved request's
+// context carries the client address as LogAttr.
+func LogHandler(h slog.Handler) slog.Handler { return logHandler{h} }
+
+type logHandler struct{ slog.Handler }
+
+func (h logHandler) Handle(ctx context.Context, rec slog.Record) error {
+	if ip, ok := ClientIP(ctx); ok {
+		rec = rec.Clone()
+		rec.AddAttrs(slog.String(LogAttr, ip.String()))
+	}
+	return h.Handler.Handle(ctx, rec)
+}
+
+func (h logHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
+	return logHandler{h.Handler.WithAttrs(attrs)}
+}
+
+func (h logHandler) WithGroup(name string) slog.Handler {
+	return logHandler{h.Handler.WithGroup(name)}
+}

internal/forwarded/forwarded_test.go

@@ -0,0 +1,260 @@
+package forwarded
+
+import (
+	"bytes"
+	"context"
+	"crypto/tls"
+	"errors"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"net/netip"
+	"slices"
+	"strings"
+	"testing"
+)
+
+func TestParseTrusted(t *testing.T) {
+	t.Parallel()
+	tests := []struct {
+		in      string
+		want    []string
+		wantErr string
+	}{
+		{in: "", want: nil},
+		{in: "   ", want: nil},
+		{in: "10.60.1.33", want: []string{"10.60.1.33/32"}},
+		{in: "10.60.1.33, 172.16.0.0/12", want: []string{"10.60.1.33/32", "172.16.0.0/12"}},
+		{in: "2001:db8::1,2001:db8::/32", want: []string{"2001:db8::1/128", "2001:db8::/32"}},
+		{in: "traefik", wantErr: "invalid IP address"},
+		{in: "10.60.1.33:443", wantErr: "invalid IP address"},
+		{in: "10.60.1.0/33", wantErr: "invalid CIDR"},
+		{in: "10.60.1.33/24", wantErr: "did you mean 10.60.1.0/24"},
+		{in: "10.60.1.33,,10.60.1.34", wantErr: "empty entry"},
+		{in: "10.60.1.33,", wantErr: "empty entry"},
+		{in: "fe80::1%eth0", wantErr: "zone"},
+		{in: "::ffff:10.60.1.33", wantErr: "IPv4-mapped"},
+		{in: "0.0.0.0/0", wantErr: "every peer"},
+		{in: "::/0", wantErr: "every peer"},
+	}
+	for _, tt := range tests {
+		got, err := ParseTrusted(tt.in)
+		if tt.wantErr != "" {
+			if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
+				t.Errorf("ParseTrusted(%q) error = %v, want one containing %q", tt.in, err, tt.wantErr)
+			}
+			continue
+		}
+		if err != nil {
+			t.Errorf("ParseTrusted(%q) error = %v", tt.in, err)
+			continue
+		}
+		var gotStr []string
+		for _, p := range got {
+			gotStr = append(gotStr, p.String())
+		}
+		if !slices.Equal(gotStr, tt.want) {
+			t.Errorf("ParseTrusted(%q) = %v, want %v", tt.in, gotStr, tt.want)
+		}
+	}
+}
+
+func TestTrustedContainsMappedIPv4(t *testing.T) {
+	t.Parallel()
+	trusted := mustTrusted(t, "10.60.1.33")
+	if !trusted.Contains(netip.MustParseAddr("::ffff:10.60.1.33")) {
+		t.Error("IPv4-mapped form of a trusted address is not trusted")
+	}
+	if Trusted(nil).Contains(netip.MustParseAddr("10.60.1.33")) {
+		t.Error("an empty set trusts a peer")
+	}
+}
+
+func mustTrusted(t *testing.T, s string) Trusted {
+	t.Helper()
+	tr, err := ParseTrusted(s)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return tr
+}
+
+func TestResolve(t *testing.T) {
+	t.Parallel()
+	// 10.60.1.33 is Traefik; 10.60.2.0/24 is an inner proxy tier.
+	trusted := mustTrusted(t, "10.60.1.33,10.60.2.0/24")
+	tests := []struct {
+		name       string
+		peer       string
+		tls        bool
+		xff        []string
+		xfp        []string
+		wantIP     string
+		wantScheme string
+	}{
+		{
+			name: "untrusted peer, no headers",
+			peer: "198.51.100.9:5000", wantIP: "198.51.100.9", wantScheme: "http",
+		},
+		{
+			name: "untrusted peer over TLS",
+			peer: "198.51.100.9:5000", tls: true, wantIP: "198.51.100.9", wantScheme: "https",
+		},
+		{
+			name: "untrusted peer spoofing both headers is ignored",
+			peer: "198.51.100.9:5000", xff: []string{"203.0.113.7"}, xfp: []string{"https"},
+			wantIP: "198.51.100.9", wantScheme: "http",
+		},
+		{
+			name: "untrusted peer's malformed headers are ignored, not rejected",
+			peer: "198.51.100.9:5000", xff: []string{"not-an-ip"}, xfp: []string{"gopher"},
+			wantIP: "198.51.100.9", wantScheme: "http",
+		},
+		{
+			name: "trusted peer: client from X-Forwarded-For, scheme from X-Forwarded-Proto",
+			peer: "10.60.1.33:41000", xff: []string{"203.0.113.7"}, xfp: []string{"https"},
+			wantIP: "203.0.113.7", wantScheme: "https",
+		},
+		{
+			name: "trusted peer seen as IPv4-mapped IPv6",
+			peer: "[::ffff:10.60.1.33]:41000", xff: []string{"203.0.113.7"}, xfp: []string{"https"},
+			wantIP: "203.0.113.7", wantScheme: "https",
+		},
+		{
+			name: "trusted peer without headers is itself the client",
+			peer: "10.60.1.33:41000", wantIP: "10.60.1.33", wantScheme: "http",
+		},
+		{
+			name: "rightmost untrusted address wins over a client-supplied prefix",
+			peer: "10.60.1.33:41000", xff: []string{"1.2.3.4, 203.0.113.7"}, xfp: []string{"https"},
+			wantIP: "203.0.113.7", wantScheme: "https",
+		},
+		{
+			name: "trusted proxies in the chain are skipped",
+			peer: "10.60.1.33:41000", xff: []string{"1.2.3.4, 203.0.113.7, 10.60.2.5"}, xfp: []string{"https"},
+			wantIP: "203.0.113.7", wantScheme: "https",
+		},
+		{
+			name: "several header lines form one chain",
+			peer: "10.60.1.33:41000", xff: []string{"1.2.3.4", "203.0.113.7, 10.60.2.5"},
+			wantIP: "203.0.113.7", wantScheme: "http",
+		},
+		{
+			name: "garbage left of the client is not examined",
+			peer: "10.60.1.33:41000", xff: []string{"spoofed, 203.0.113.7"},
+			wantIP: "203.0.113.7", wantScheme: "http",
+		},
+		{
+			name: "all trusted: leftmost is the client",
+			peer: "10.60.1.33:41000", xff: []string{"10.60.2.5, 10.60.2.6"},
+			wantIP: "10.60.2.5", wantScheme: "http",
+		},
+		{
+			name: "IPv6 client",
+			peer: "10.60.1.33:41000", xff: []string{"2001:db8::7"}, xfp: []string{"HTTPS"},
+			wantIP: "2001:db8::7", wantScheme: "https",
+		},
+		{
+			name: "trusted peer may downgrade to http",
+			peer: "10.60.1.33:41000", tls: true, xfp: []string{"http"},
+			wantIP: "10.60.1.33", wantScheme: "http",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			r := request(tt.peer, tt.xff, tt.xfp)
+			if tt.tls {
+				r.TLS = &tls.ConnectionState{}
+			}
+			o, err := Resolve(r, trusted)
+			if err != nil {
+				t.Fatalf("Resolve error = %v", err)
+			}
+			if o.ClientIP.String() != tt.wantIP || o.Scheme != tt.wantScheme {
+				t.Errorf("Resolve = %s %s, want %s %s", o.ClientIP, o.Scheme, tt.wantIP, tt.wantScheme)
+			}
+		})
+	}
+}
+
+func TestResolveRejectsMalformedHeadersFromTrustedPeer(t *testing.T) {
+	t.Parallel()
+	trusted := mustTrusted(t, "10.60.1.33")
+	for _, tt := range []struct {
+		name     string
+		xff, xfp []string
+	}{
+		{"X-Forwarded-For not an IP", []string{"not-an-ip"}, nil},
+		{"X-Forwarded-For with a port", []string{"203.0.113.7:5000"}, nil},
+		{"X-Forwarded-For empty entry", []string{"203.0.113.7, "}, nil},
+		{"X-Forwarded-For empty", []string{""}, nil},
+		{"X-Forwarded-Proto unknown scheme", nil, []string{"ftp"}},
+		{"X-Forwarded-Proto list", nil, []string{"https, http"}},
+		{"X-Forwarded-Proto repeated", nil, []string{"https", "https"}},
+	} {
+		_, err := Resolve(request("10.60.1.33:41000", tt.xff, tt.xfp), trusted)
+		if !errors.Is(err, ErrInvalidHeader) {
+			t.Errorf("%s: Resolve error = %v, want ErrInvalidHeader", tt.name, err)
+		}
+	}
+}
+
+func TestResolveBadPeerAddress(t *testing.T) {
+	t.Parallel()
+	r := request("@", nil, nil)
+	_, err := Resolve(r, nil)
+	if err == nil || errors.Is(err, ErrInvalidHeader) {
+		t.Errorf("Resolve error = %v, want a peer address error", err)
+	}
+}
+
+func request(peer string, xff, xfp []string) *http.Request {
+	r := httptest.NewRequest(http.MethodGet, "/", nil)
+	r.RemoteAddr = peer
+	for _, v := range xff {
+		r.Header.Add(HeaderFor, v)
+	}
+	for _, v := range xfp {
+		r.Header.Add(HeaderProto, v)
+	}
+	return r
+}
+
+func TestContextHelpers(t *testing.T) {
+	t.Parallel()
+	if _, ok := ClientIP(context.Background()); ok {
+		t.Error("ClientIP ok on an unresolved context")
+	}
+	if _, ok := Scheme(context.Background()); ok {
+		t.Error("Scheme ok on an unresolved context")
+	}
+	ctx := NewContext(context.Background(), Origin{ClientIP: netip.MustParseAddr("203.0.113.7"), Scheme: "https"})
+	if ip, ok := ClientIP(ctx); !ok || ip.String() != "203.0.113.7" {
+		t.Errorf("ClientIP = %s %v, want 203.0.113.7 true", ip, ok)
+	}
+	if s, ok := Scheme(ctx); !ok || s != "https" {
+		t.Errorf("Scheme = %q %v, want https true", s, ok)
+	}
+}
+
+func TestLogHandler(t *testing.T) {
+	t.Parallel()
+	var buf bytes.Buffer
+	logger := slog.New(LogHandler(slog.NewTextHandler(&buf, nil))).With("component", "test")
+	ctx := NewContext(context.Background(), Origin{ClientIP: netip.MustParseAddr("203.0.113.7"), Scheme: "https"})
+
+	logger.InfoContext(ctx, "resolved")
+	logger.InfoContext(context.Background(), "unresolved")
+
+	lines := strings.Split(strings.TrimSpace(buf.String()), "\n")
+	if len(lines) != 2 {
+		t.Fatalf("logged %d lines, want 2: %q", len(lines), buf.String())
+	}
+	if !strings.Contains(lines[0], "client_ip=203.0.113.7") || !strings.Contains(lines[0], "component=test") {
+		t.Errorf("resolved line = %q, want client_ip and the With attribute", lines[0])
+	}
+	if strings.Contains(lines[1], "client_ip") {
+		t.Errorf("unresolved line = %q, want no client_ip", lines[1])
+	}
+}

internal/household/settings.go

@@ -0,0 +1,340 @@
+package household
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"regexp"
+	"strings"
+	"sync"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// Seed values for a new household (CTXD CONTEXT.MD). Days count from
+// Sunday = 0, as time.Weekday does.
+const (
+	SeedDinnerTime       = "17:30"
+	SeedReminderTime     = "16:30"
+	SeedReviewTime       = "09:00" // rotation check
+	SeedPlanDraftDow     = 5       // Friday
+	SeedPlanDraftTime    = "09:00"
+	SeedSuggestionsDow   = 0 // Sunday
+	SeedSuggestionsTime  = "08:00"
+	SeedChatAutosendDow  = 6 // Saturday
+	SeedChatAutosendTime = "08:00"
+)
+
+// ErrNoDefaultZone is returned by SeedSettings when the household settings
+// do not exist yet and no default zone was configured to create them with.
+var ErrNoDefaultZone = errors.New("household settings do not exist yet and no default time zone is configured")
+
+// ErrInvalidDefaultZone is returned by SeedSettings when the household
+// settings do not exist yet and the configured default zone cannot be loaded.
+var ErrInvalidDefaultZone = errors.New("household settings do not exist yet and the default time zone is invalid")
+
+// Settings are the shared household settings. Times are household-local
+// 24-hour HH:MM in Timezone; days of the week count from Sunday = 0.
+type Settings struct {
+	Timezone              string  `json:"timezone"`
+	DinnerTime            string  `json:"dinner_time"`
+	ReminderTime          string  `json:"reminder_time"`
+	ReviewTime            string  `json:"review_time"`
+	PlanDraftDow          int     `json:"plan_draft_dow"`
+	PlanDraftTime         string  `json:"plan_draft_time"`
+	SuggestionsDow        int     `json:"suggestions_dow"`
+	SuggestionsTime       string  `json:"suggestions_time"`
+	ChatAutosendDow       int     `json:"chat_autosend_dow"`
+	ChatAutosendTime      string  `json:"chat_autosend_time"`
+	OnboardingCompletedAt *string `json:"onboarding_completed_at"`
+	UpdatesSeenAt         *string `json:"updates_seen_at"`
+	UpdatedBy             *string `json:"updated_by"`
+	CreatedAt             string  `json:"created_at"`
+	UpdatedAt             string  `json:"updated_at"`
+}
+
+// SettingsPatch changes the household settings. Nil fields are left as they
+// are.
+type SettingsPatch struct {
+	Timezone         *string
+	DinnerTime       *string
+	ReminderTime     *string
+	ReviewTime       *string
+	PlanDraftDow     *int
+	PlanDraftTime    *string
+	SuggestionsDow   *int
+	SuggestionsTime  *string
+	ChatAutosendDow  *int
+	ChatAutosendTime *string
+}
+
+// Problem is one invalid field of a SettingsPatch, named by its JSON key.
+type Problem struct {
+	Field  string
+	Reason string
+}
+
+// ValidationError lists every invalid field of a SettingsPatch.
+type ValidationError struct {
+	Problems []Problem
+}
+
+func (e *ValidationError) Error() string {
+	parts := make([]string, len(e.Problems))
+	for i, p := range e.Problems {
+		parts[i] = p.Field + ": " + p.Reason
+	}
+	return "invalid household settings: " + strings.Join(parts, "; ")
+}
+
+// SeedSettings creates the household settings row with zone defaultTZ and the
+// seed times and days if it does not exist. An existing row is never changed,
+// and defaultTZ is then ignored, valid or not. With no row, an empty
+// defaultTZ is ErrNoDefaultZone and an unloadable one ErrInvalidDefaultZone.
+func SeedSettings(ctx context.Context, st *store.Store, defaultTZ string) error {
+	return st.WithTx(ctx, func(tx *sql.Tx) error {
+		q := db.New(tx)
+		_, err := q.GetHouseholdSettings(ctx)
+		if err == nil {
+			return nil
+		}
+		if !errors.Is(err, sql.ErrNoRows) {
+			return fmt.Errorf("household: read settings: %w", err)
+		}
+		if defaultTZ == "" {
+			return ErrNoDefaultZone
+		}
+		if _, err := LoadZone(defaultTZ); err != nil {
+			return fmt.Errorf("%w: %v", ErrInvalidDefaultZone, err)
+		}
+		now := store.Now().String()
+		_, err = q.UpsertHouseholdSettings(ctx, db.UpsertHouseholdSettingsParams{
+			Timezone:         defaultTZ,
+			DinnerTime:       SeedDinnerTime,
+			ReminderTime:     SeedReminderTime,
+			ReviewTime:       SeedReviewTime,
+			PlanDraftDow:     SeedPlanDraftDow,
+			PlanDraftTime:    SeedPlanDraftTime,
+			SuggestionsDow:   SeedSuggestionsDow,
+			SuggestionsTime:  SeedSuggestionsTime,
+			ChatAutosendDow:  SeedChatAutosendDow,
+			ChatAutosendTime: SeedChatAutosendTime,
+			CreatedAt:        now,
+			UpdatedAt:        now,
+		})
+		if err != nil {
+			return fmt.Errorf("household: seed settings: %w", err)
+		}
+		return nil
+	})
+}
+
+// SettingsService reads and changes the household settings, and tells
+// in-process subscribers (the scheduler) about every change.
+type SettingsService struct {
+	st *store.Store
+
+	// updateMu serialises Update with its publish, so subscribers see
+	// changes in commit order.
+	updateMu sync.Mutex
+
+	subsMu sync.Mutex
+	subs   map[int]func(Settings)
+	nextID int
+}
+
+// NewSettingsService returns a service over st. Call SeedSettings first.
+func NewSettingsService(st *store.Store) *SettingsService {
+	return &SettingsService{st: st, subs: make(map[int]func(Settings))}
+}
+
+// Get returns the household settings.
+func (s *SettingsService) Get(ctx context.Context) (Settings, error) {
+	row, err := db.New(s.st.Reader).GetHouseholdSettings(ctx)
+	if err != nil {
+		return Settings{}, fmt.Errorf("household: read settings: %w", err)
+	}
+	return fromRow(row), nil
+}
+
+// Update validates patch, applies it, records updatedBy (the signed-in
+// member's subject, which must not be empty) and publishes the new settings
+// to every subscriber. An invalid patch is a *ValidationError and changes
+// nothing.
+func (s *SettingsService) Update(ctx context.Context, patch SettingsPatch, updatedBy string) (Settings, error) {
+	if updatedBy == "" {
+		return Settings{}, errors.New("household: update settings: no member to record as updated_by")
+	}
+	if err := patch.validate(); err != nil {
+		return Settings{}, err
+	}
+
+	s.updateMu.Lock()
+	defer s.updateMu.Unlock()
+
+	var row db.HouseholdSetting
+	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
+		q := db.New(tx)
+		cur, err := q.GetHouseholdSettings(ctx)
+		if err != nil {
+			return fmt.Errorf("household: read settings: %w", err)
+		}
+		p := db.UpsertHouseholdSettingsParams{
+			Timezone:              cur.Timezone,
+			DinnerTime:            cur.DinnerTime,
+			ReminderTime:          cur.ReminderTime,
+			ReviewTime:            cur.ReviewTime,
+			PlanDraftDow:          cur.PlanDraftDow,
+			PlanDraftTime:         cur.PlanDraftTime,
+			SuggestionsDow:        cur.SuggestionsDow,
+			SuggestionsTime:       cur.SuggestionsTime,
+			ChatAutosendDow:       cur.ChatAutosendDow,
+			ChatAutosendTime:      cur.ChatAutosendTime,
+			OnboardingCompletedAt: cur.OnboardingCompletedAt,
+			UpdatesSeenAt:         cur.UpdatesSeenAt,
+			UpdatedBy:             sql.NullString{String: updatedBy, Valid: true},
+			CreatedAt:             cur.CreatedAt,
+			UpdatedAt:             store.Now().String(),
+		}
+		setString(&p.Timezone, patch.Timezone)
+		setString(&p.DinnerTime, patch.DinnerTime)
+		setString(&p.ReminderTime, patch.ReminderTime)
+		setString(&p.ReviewTime, patch.ReviewTime)
+		setDow(&p.PlanDraftDow, patch.PlanDraftDow)
+		setString(&p.PlanDraftTime, patch.PlanDraftTime)
+		setDow(&p.SuggestionsDow, patch.SuggestionsDow)
+		setString(&p.SuggestionsTime, patch.SuggestionsTime)
+		setDow(&p.ChatAutosendDow, patch.ChatAutosendDow)
+		setString(&p.ChatAutosendTime, patch.ChatAutosendTime)
+		row, err = q.UpsertHouseholdSettings(ctx, p)
+		if err != nil {
+			return fmt.Errorf("household: update settings: %w", err)
+		}
+		return nil
+	})
+	if err != nil {
+		return Settings{}, err
+	}
+
+	settings := fromRow(row)
+	s.publish(settings)
+	return settings, nil
+}
+
+// Subscribe registers fn to receive the new settings after every successful
+// Update. fn runs synchronously on the updating goroutine, so it must return
+// promptly and must not call Update. The returned function unsubscribes fn.
+func (s *SettingsService) Subscribe(fn func(Settings)) (unsubscribe func()) {
+	s.subsMu.Lock()
+	defer s.subsMu.Unlock()
+	id := s.nextID
+	s.nextID++
+	s.subs[id] = fn
+	return func() {
+		s.subsMu.Lock()
+		defer s.subsMu.Unlock()
+		delete(s.subs, id)
+	}
+}
+
+func (s *SettingsService) publish(settings Settings) {
+	s.subsMu.Lock()
+	fns := make([]func(Settings), 0, len(s.subs))
+	for _, fn := range s.subs {
+		fns = append(fns, fn)
+	}
+	s.subsMu.Unlock()
+	for _, fn := range fns {
+		fn(settings)
+	}
+}
+
+func (p SettingsPatch) validate() error {
+	var problems []Problem
+	fail := func(field, reason string) {
+		problems = append(problems, Problem{Field: field, Reason: reason})
+	}
+	if p == (SettingsPatch{}) {
+		fail("settings", "no settings to change")
+	}
+	if p.Timezone != nil {
+		if _, err := LoadZone(*p.Timezone); err != nil {
+			fail("timezone", err.Error())
+		}
+	}
+	for _, t := range []struct {
+		field string
+		value *string
+	}{
+		{"dinner_time", p.DinnerTime},
+		{"reminder_time", p.ReminderTime},
+		{"review_time", p.ReviewTime},
+		{"plan_draft_time", p.PlanDraftTime},
+		{"suggestions_time", p.SuggestionsTime},
+		{"chat_autosend_time", p.ChatAutosendTime},
+	} {
+		if t.value != nil && !clockTime.MatchString(*t.value) {
+			fail(t.field, fmt.Sprintf("invalid time %q (want 24-hour HH:MM, 00:00-23:59)", *t.value))
+		}
+	}
+	for _, d := range []struct {
+		field string
+		value *int
+	}{
+		{"plan_draft_dow", p.PlanDraftDow},
+		{"suggestions_dow", p.SuggestionsDow},
+		{"chat_autosend_dow", p.ChatAutosendDow},
+	} {
+		if d.value != nil && (*d.value < 0 || *d.value > 6) {
+			fail(d.field, fmt.Sprintf("invalid day of the week %d (want 0-6, Sunday = 0)", *d.value))
+		}
+	}
+	if len(problems) > 0 {
+		return &ValidationError{Problems: problems}
+	}
+	return nil
+}
+
+// clockTime matches a zero-padded 24-hour HH:MM time.
+var clockTime = regexp.MustCompile(`^([01][0-9]|2[0-3]):[0-5][0-9]$`)
+
+func setString(dst *string, v *string) {
+	if v != nil {
+		*dst = *v
+	}
+}
+
+func setDow(dst *int64, v *int) {
+	if v != nil {
+		*dst = int64(*v)
+	}
+}
+
+func fromRow(r db.HouseholdSetting) Settings {
+	return Settings{
+		Timezone:              r.Timezone,
+		DinnerTime:            r.DinnerTime,
+		ReminderTime:          r.ReminderTime,
+		ReviewTime:            r.ReviewTime,
+		PlanDraftDow:          int(r.PlanDraftDow),
+		PlanDraftTime:         r.PlanDraftTime,
+		SuggestionsDow:        int(r.SuggestionsDow),
+		SuggestionsTime:       r.SuggestionsTime,
+		ChatAutosendDow:       int(r.ChatAutosendDow),
+		ChatAutosendTime:      r.ChatAutosendTime,
+		OnboardingCompletedAt: nullable(r.OnboardingCompletedAt),
+		UpdatesSeenAt:         nullable(r.UpdatesSeenAt),
+		UpdatedBy:             nullable(r.UpdatedBy),
+		CreatedAt:             r.CreatedAt,
+		UpdatedAt:             r.UpdatedAt,
+	}
+}
+
+func nullable(s sql.NullString) *string {
+	if !s.Valid {
+		return nil
+	}
+	return &s.String
+}

internal/household/settings_test.go

@@ -0,0 +1,374 @@
+package household
+
+import (
+	"context"
+	"errors"
+	"slices"
+	"sync"
+	"testing"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
+)
+
+// migratedStore opens a temp store in dir migrated with the embedded
+// migrations, closed when the test ends.
+func migratedStore(t *testing.T, dir string) *store.Store {
+	t.Helper()
+	ctx := context.Background()
+	st, err := store.Open(ctx, dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := st.Close(); err != nil {
+			t.Error(err)
+		}
+	})
+	if err := store.Migrate(ctx, st.Writer, migrations.FS); err != nil {
+		t.Fatal(err)
+	}
+	return st
+}
+
+// seededService returns a settings service over a migrated temp database
+// seeded with zone America/New_York.
+func seededService(t *testing.T) *SettingsService {
+	t.Helper()
+	st := migratedStore(t, t.TempDir())
+	if err := SeedSettings(context.Background(), st, "America/New_York"); err != nil {
+		t.Fatal(err)
+	}
+	return NewSettingsService(st)
+}
+
+func ptr[T any](v T) *T { return &v }
+
+func TestSeedSettingsCreatesRow(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	st := migratedStore(t, t.TempDir())
+
+	if err := SeedSettings(ctx, st, "America/Chicago"); err != nil {
+		t.Fatal(err)
+	}
+	got, err := NewSettingsService(st).Get(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := Settings{
+		Timezone:         "America/Chicago",
+		DinnerTime:       "17:30",
+		ReminderTime:     "16:30",
+		ReviewTime:       "09:00",
+		PlanDraftDow:     5,
+		PlanDraftTime:    "09:00",
+		SuggestionsDow:   0,
+		SuggestionsTime:  "08:00",
+		ChatAutosendDow:  6,
+		ChatAutosendTime: "08:00",
+		CreatedAt:        got.CreatedAt,
+		UpdatedAt:        got.UpdatedAt,
+	}
+	if !equalSettings(got, want) {
+		t.Errorf("seeded settings = %+v\nwant %+v", got, want)
+	}
+	var created store.Timestamp
+	if err := created.Scan(got.CreatedAt); err != nil {
+		t.Errorf("created_at: %v", err)
+	}
+	if got.UpdatedAt != got.CreatedAt {
+		t.Errorf("updated_at = %q, want created_at %q", got.UpdatedAt, got.CreatedAt)
+	}
+}
+
+func TestSeedSettingsNeverOverwrites(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	dir := t.TempDir()
+
+	// First boot seeds; the household then changes a setting.
+	first := migratedStore(t, dir)
+	if err := SeedSettings(ctx, first, "America/Chicago"); err != nil {
+		t.Fatal(err)
+	}
+	changed, err := NewSettingsService(first).Update(ctx, SettingsPatch{DinnerTime: ptr("18:15")}, "sam")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := first.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	// Later boots reopen the same database with a different default zone,
+	// an invalid one and none at all.
+	for _, defaultTZ := range []string{"Europe/London", "Mars/Olympus_Mons", ""} {
+		st := migratedStore(t, dir)
+		if err := SeedSettings(ctx, st, defaultTZ); err != nil {
+			t.Fatalf("reboot with default zone %q: %v", defaultTZ, err)
+		}
+		got, err := NewSettingsService(st).Get(ctx)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if !equalSettings(got, changed) {
+			t.Errorf("reboot with default zone %q changed settings:\n got %+v\nwant %+v", defaultTZ, got, changed)
+		}
+		if err := st.Close(); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func TestSeedSettingsRequiresDefaultZone(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+
+	tests := []struct {
+		name      string
+		defaultTZ string
+		is        error
+	}{
+		{"unset", "", ErrNoDefaultZone},
+		{"not an IANA zone", "Mars/Olympus_Mons", ErrInvalidDefaultZone},
+		{"Local", "Local", ErrInvalidDefaultZone},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			st := migratedStore(t, t.TempDir())
+			err := SeedSettings(ctx, st, tt.defaultTZ)
+			if err == nil {
+				t.Fatal("SeedSettings succeeded")
+			}
+			if !errors.Is(err, tt.is) {
+				t.Errorf("error = %v, want %v", err, tt.is)
+			}
+			if _, err := NewSettingsService(st).Get(ctx); err == nil {
+				t.Error("a settings row was created despite the error")
+			}
+		})
+	}
+}
+
+func TestUpdateAppliesPatchAndRecordsUpdatedBy(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	svc := seededService(t)
+	before, err := svc.Get(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	got, err := svc.Update(ctx, SettingsPatch{
+		Timezone:         ptr("Europe/Paris"),
+		DinnerTime:       ptr("19:00"),
+		ReminderTime:     ptr("00:00"),
+		ReviewTime:       ptr("23:59"),
+		PlanDraftDow:     ptr(4),
+		PlanDraftTime:    ptr("10:30"),
+		SuggestionsDow:   ptr(1),
+		SuggestionsTime:  ptr("07:45"),
+		ChatAutosendDow:  ptr(0),
+		ChatAutosendTime: ptr("12:00"),
+	}, "sam")
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := Settings{
+		Timezone:         "Europe/Paris",
+		DinnerTime:       "19:00",
+		ReminderTime:     "00:00",
+		ReviewTime:       "23:59",
+		PlanDraftDow:     4,
+		PlanDraftTime:    "10:30",
+		SuggestionsDow:   1,
+		SuggestionsTime:  "07:45",
+		ChatAutosendDow:  0,
+		ChatAutosendTime: "12:00",
+		UpdatedBy:        ptr("sam"),
+		CreatedAt:        before.CreatedAt,
+		UpdatedAt:        got.UpdatedAt,
+	}
+	if !equalSettings(got, want) {
+		t.Errorf("Update = %+v\nwant %+v", got, want)
+	}
+	if got.UpdatedAt < before.UpdatedAt {
+		t.Errorf("updated_at went back: %s < %s", got.UpdatedAt, before.UpdatedAt)
+	}
+	stored, err := svc.Get(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !equalSettings(stored, got) {
+		t.Errorf("stored = %+v\nwant %+v", stored, got)
+	}
+
+	// A partial patch changes only its fields and records its own member.
+	got, err = svc.Update(ctx, SettingsPatch{DinnerTime: ptr("18:00")}, "alex")
+	if err != nil {
+		t.Fatal(err)
+	}
+	want.DinnerTime = "18:00"
+	want.UpdatedBy = ptr("alex")
+	want.UpdatedAt = got.UpdatedAt
+	if !equalSettings(got, want) {
+		t.Errorf("partial Update = %+v\nwant %+v", got, want)
+	}
+}
+
+func TestUpdateRequiresMember(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	svc := seededService(t)
+	notified := 0
+	svc.Subscribe(func(Settings) { notified++ })
+
+	if _, err := svc.Update(ctx, SettingsPatch{DinnerTime: ptr("18:00")}, ""); err == nil {
+		t.Fatal("Update with no member succeeded")
+	}
+	got, err := svc.Get(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.DinnerTime != SeedDinnerTime || got.UpdatedBy != nil || notified != 0 {
+		t.Errorf("Update with no member changed settings or notified: %+v, notified %d", got, notified)
+	}
+}
+
+func TestUpdateValidation(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+
+	tests := []struct {
+		name   string
+		patch  SettingsPatch
+		fields []string
+	}{
+		{"empty patch", SettingsPatch{}, []string{"settings"}},
+		{"unknown zone", SettingsPatch{Timezone: ptr("Mars/Olympus_Mons")}, []string{"timezone"}},
+		{"empty zone", SettingsPatch{Timezone: ptr("")}, []string{"timezone"}},
+		{"Local zone", SettingsPatch{Timezone: ptr("Local")}, []string{"timezone"}},
+		{"zone path traversal", SettingsPatch{Timezone: ptr("../../etc/passwd")}, []string{"timezone"}},
+		{"hour 24", SettingsPatch{DinnerTime: ptr("24:00")}, []string{"dinner_time"}},
+		{"minute 60", SettingsPatch{ReminderTime: ptr("16:60")}, []string{"reminder_time"}},
+		{"unpadded hour", SettingsPatch{ReviewTime: ptr("9:00")}, []string{"review_time"}},
+		{"seconds", SettingsPatch{PlanDraftTime: ptr("09:00:00")}, []string{"plan_draft_time"}},
+		{"12-hour", SettingsPatch{SuggestionsTime: ptr("08:00 AM")}, []string{"suggestions_time"}},
+		{"empty time", SettingsPatch{ChatAutosendTime: ptr("")}, []string{"chat_autosend_time"}},
+		{"dow 7", SettingsPatch{PlanDraftDow: ptr(7)}, []string{"plan_draft_dow"}},
+		{"dow -1", SettingsPatch{SuggestionsDow: ptr(-1)}, []string{"suggestions_dow"}},
+		{"dow 100", SettingsPatch{ChatAutosendDow: ptr(100)}, []string{"chat_autosend_dow"}},
+		{
+			"every problem is reported",
+			SettingsPatch{Timezone: ptr("Nowhere"), DinnerTime: ptr("5pm"), PlanDraftDow: ptr(9)},
+			[]string{"timezone", "dinner_time", "plan_draft_dow"},
+		},
+		{
+			"valid fields do not mask an invalid one",
+			SettingsPatch{DinnerTime: ptr("18:00"), ChatAutosendDow: ptr(8)},
+			[]string{"chat_autosend_dow"},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			svc := seededService(t)
+			before, err := svc.Get(ctx)
+			if err != nil {
+				t.Fatal(err)
+			}
+			published := 0
+			svc.Subscribe(func(Settings) { published++ })
+
+			_, err = svc.Update(ctx, tt.patch, "sam")
+			var verr *ValidationError
+			if !errors.As(err, &verr) {
+				t.Fatalf("Update error = %v, want *ValidationError", err)
+			}
+			var fields []string
+			for _, p := range verr.Problems {
+				fields = append(fields, p.Field)
+			}
+			if !slices.Equal(fields, tt.fields) {
+				t.Errorf("problem fields = %v, want %v", fields, tt.fields)
+			}
+
+			after, err := svc.Get(ctx)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if !equalSettings(after, before) {
+				t.Errorf("invalid patch changed settings:\n got %+v\nwant %+v", after, before)
+			}
+			if published != 0 {
+				t.Errorf("invalid patch published %d times", published)
+			}
+		})
+	}
+}
+
+func TestUpdatePublishesToSubscribers(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	svc := seededService(t)
+
+	var mu sync.Mutex
+	var first, second []Settings
+	unsubscribe := svc.Subscribe(func(s Settings) {
+		mu.Lock()
+		defer mu.Unlock()
+		first = append(first, s)
+	})
+	svc.Subscribe(func(s Settings) {
+		mu.Lock()
+		defer mu.Unlock()
+		second = append(second, s)
+	})
+
+	updated, err := svc.Update(ctx, SettingsPatch{Timezone: ptr("Asia/Tokyo")}, "sam")
+	if err != nil {
+		t.Fatal(err)
+	}
+	mu.Lock()
+	if len(first) != 1 || !equalSettings(first[0], updated) {
+		t.Errorf("first subscriber got %+v, want [%+v]", first, updated)
+	}
+	if len(second) != 1 || !equalSettings(second[0], updated) {
+		t.Errorf("second subscriber got %+v, want [%+v]", second, updated)
+	}
+	mu.Unlock()
+
+	unsubscribe()
+	updated, err = svc.Update(ctx, SettingsPatch{DinnerTime: ptr("18:45")}, "sam")
+	if err != nil {
+		t.Fatal(err)
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	if len(first) != 1 {
+		t.Errorf("unsubscribed subscriber got %d notifications, want 1", len(first))
+	}
+	if len(second) != 2 || !equalSettings(second[1], updated) {
+		t.Errorf("second subscriber got %+v, want a second notification %+v", second, updated)
+	}
+}
+
+func TestUpdateWithoutSeedFails(t *testing.T) {
+	t.Parallel()
+	svc := NewSettingsService(migratedStore(t, t.TempDir()))
+	if _, err := svc.Update(context.Background(), SettingsPatch{DinnerTime: ptr("18:00")}, ""); err == nil {
+		t.Fatal("Update succeeded with no settings row")
+	}
+}
+
+// equalSettings compares settings by value, following the nullable pointers.
+func equalSettings(a, b Settings) bool {
+	eq := func(x, y *string) bool { return (x == nil) == (y == nil) && (x == nil || *x == *y) }
+	if !eq(a.OnboardingCompletedAt, b.OnboardingCompletedAt) || !eq(a.UpdatesSeenAt, b.UpdatesSeenAt) || !eq(a.UpdatedBy, b.UpdatedBy) {
+		return false
+	}
+	a.OnboardingCompletedAt, a.UpdatesSeenAt, a.UpdatedBy = nil, nil, nil
+	b.OnboardingCompletedAt, b.UpdatesSeenAt, b.UpdatedBy = nil, nil, nil
+	return a == b
+}

internal/household/zone.go

@@ -0,0 +1,28 @@
+package household
+
+import (
+	"errors"
+	"fmt"
+	"time"
+
+	// Embeds the IANA zone database in the binary, so zones load the same
+	// way in a minimal image with no /usr/share/zoneinfo.
+	_ "time/tzdata"
+)
+
+// LoadZone loads the IANA zone name, such as "America/New_York". The empty
+// name and "Local", which time.LoadLocation maps to UTC and the process zone,
+// are refused: the household zone is never implied.
+func LoadZone(name string) (*time.Location, error) {
+	if name == "" {
+		return nil, errors.New("time zone is empty (want an IANA zone such as America/New_York)")
+	}
+	if name == "Local" {
+		return nil, errors.New(`time zone "Local" is not an IANA zone (want e.g. America/New_York)`)
+	}
+	loc, err := time.LoadLocation(name)
+	if err != nil {
+		return nil, fmt.Errorf("unknown time zone %q (want an IANA zone such as America/New_York)", name)
+	}
+	return loc, nil
+}

internal/secureurl/secureurl.go

@@ -0,0 +1,32 @@
+// Package secureurl holds the one transport rule for URLs that carry
+// credentials or session cookies: HTTPS, or plain HTTP to a loopback host for
+// local development and tests.
+package secureurl
+
+import (
+	"errors"
+	"fmt"
+	"net/url"
+	"strings"
+)
+
+// loopbackHosts are the only hosts plain HTTP is allowed for, compared
+// case-insensitively. url.URL's Hostname strips the brackets from "[::1]".
+var loopbackHosts = map[string]bool{"localhost": true, "127.0.0.1": true, "::1": true}
+
+// Check reports an error unless u is an absolute https:// URL, or an http://
+// URL whose host is localhost, 127.0.0.1 or ::1.
+func Check(u *url.URL) error {
+	switch {
+	case u.Hostname() == "":
+		return errors.New("URL has no host")
+	case u.Scheme == "https":
+		return nil
+	case u.Scheme == "http" && loopbackHosts[strings.ToLower(u.Hostname())]:
+		return nil
+	case u.Scheme == "http":
+		return errors.New("plain http:// is allowed only for localhost, 127.0.0.1 or [::1]; use https://")
+	default:
+		return fmt.Errorf("unsupported scheme %q (want https://)", u.Scheme)
+	}
+}

internal/secureurl/secureurl_test.go

@@ -0,0 +1,40 @@
+package secureurl
+
+import (
+	"net/url"
+	"testing"
+)
+
+func TestCheck(t *testing.T) {
+	t.Parallel()
+	tests := []struct {
+		raw string
+		ok  bool
+	}{
+		{"https://meals.example.com", true},
+		{"https://auth.example.com/application/o/mealquest/", true},
+		{"https://192.0.2.10:8443", true},
+		{"http://localhost:8080", true},
+		{"http://LOCALHOST:8080", true},
+		{"http://127.0.0.1:8080/path", true},
+		{"http://[::1]:8080", true},
+		{"http://[::1]", true},
+		{"http://meals.example.com", false},
+		{"http://192.0.2.10", false},
+		{"http://127.0.0.2", false},
+		{"http://localhost.example.com", false},
+		{"http://0.0.0.0:8080", false},
+		{"ftp://localhost", false},
+		{"https://", false},
+		{"meals.example.com", false},
+	}
+	for _, tc := range tests {
+		u, err := url.Parse(tc.raw)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if err := Check(u); (err == nil) != tc.ok {
+			t.Errorf("Check(%q) error = %v, want ok=%v", tc.raw, err, tc.ok)
+		}
+	}
+}

internal/server/csrf.go

@@ -0,0 +1,42 @@
+package server
+
+import (
+	"crypto/subtle"
+	"log/slog"
+	"net/http"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/auth"
+)
+
+// CSRFHeader carries the session's CSRF token, which the client reads from
+// GET /api/v1/me.
+const CSRFHeader = "X-MealQuest-CSRF"
+
+// requireCSRF passes GET requests to next; every other
+// request must carry CSRFHeader equal to its session's CSRF token or get 403
+// csrf. It runs behind requireSession, which puts the session in the context.
+func requireCSRF(logger *slog.Logger) func(http.Handler) http.Handler {
+	forbidden := apiErrorHandler(logger, http.StatusForbidden, "csrf", "missing or invalid CSRF token")
+	internal := apiErrorHandler(logger, http.StatusInternalServerError, "internal", "internal error")
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			switch r.Method {
+			case http.MethodGet:
+				next.ServeHTTP(w, r)
+				return
+			}
+			s, ok := auth.SessionFrom(r.Context())
+			if !ok || s.CSRFToken == "" {
+				// An empty token would match a missing header.
+				logger.ErrorContext(r.Context(), "csrf check without a session token", "session", ok)
+				internal(w, r)
+				return
+			}
+			if subtle.ConstantTimeCompare([]byte(r.Header.Get(CSRFHeader)), []byte(s.CSRFToken)) != 1 {
+				forbidden(w, r)
+				return
+			}
+			next.ServeHTTP(w, r)
+		})
+	}
+}

internal/server/csrf_test.go

@@ -0,0 +1,167 @@
+package server
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/auth"
+)
+
+const (
+	csrfJSON             = `{"error":{"code":"csrf","message":"missing or invalid CSRF token","retryable":false}}`
+	methodNotAllowedJSON = `{"error":{"code":"method_not_allowed","message":"method not allowed","retryable":false}}`
+)
+
+func TestCSRFThroughRouter(t *testing.T) {
+	t.Parallel()
+
+	router := newTestRouter(t, "dev")
+	for _, tc := range []struct {
+		name, method, path string
+		header             []string // nil sends no CSRF header
+		wantStatus         int
+		wantBody           string
+	}{
+		{"POST without header", http.MethodPost, "/api/v1/me", nil, http.StatusForbidden, csrfJSON},
+		{"POST with wrong header", http.MethodPost, "/api/v1/me", []string{"wrong-token"}, http.StatusForbidden, csrfJSON},
+		{"POST with empty header", http.MethodPost, "/api/v1/me", []string{""}, http.StatusForbidden, csrfJSON},
+		{"POST with token prefix", http.MethodPost, "/api/v1/me", []string{"csrf-token"}, http.StatusForbidden, csrfJSON},
+		{"PATCH without header", http.MethodPatch, "/api/v1/settings/household", nil, http.StatusForbidden, csrfJSON},
+		{"DELETE with wrong header", http.MethodDelete, "/api/v1/me", []string{"wrong-token"}, http.StatusForbidden, csrfJSON},
+		// The right token passes the check and reaches the router, which has
+		// no POST /api/v1/me, and the settings handler, which refuses the
+		// empty body.
+		{"POST with right header", http.MethodPost, "/api/v1/me", []string{testSession.CSRFToken}, http.StatusMethodNotAllowed, methodNotAllowedJSON},
+		{"PATCH with right header", http.MethodPatch, "/api/v1/settings/household", []string{testSession.CSRFToken}, http.StatusBadRequest, `{"error":{"code":"invalid_request","message":"request body must be a JSON object","retryable":false}}`},
+		{"GET without header", http.MethodGet, "/api/v1/me", nil, http.StatusOK, ""},
+		// Only GET is exempt; HEAD and OPTIONS need the header too.
+		{"HEAD without header", http.MethodHead, "/api/v1/me", nil, http.StatusForbidden, csrfJSON},
+		{"OPTIONS without header", http.MethodOptions, "/api/v1/me", nil, http.StatusForbidden, csrfJSON},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			req := httptest.NewRequest(tc.method, tc.path, nil)
+			req.AddCookie(validSessionCookie)
+			if tc.header != nil {
+				req.Header.Set(CSRFHeader, tc.header[0])
+			}
+			rec := httptest.NewRecorder()
+			router.ServeHTTP(rec, req)
+
+			if rec.Code != tc.wantStatus {
+				t.Errorf("status = %d, want %d (body %s)", rec.Code, tc.wantStatus, rec.Body.String())
+			}
+			if tc.wantBody != "" && rec.Body.String() != tc.wantBody {
+				t.Errorf("body = %s, want %s", rec.Body.String(), tc.wantBody)
+			}
+		})
+	}
+}
+
+func TestCSRFUnauthenticatedGets401(t *testing.T) {
+	t.Parallel()
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/me", nil)
+	rec := httptest.NewRecorder()
+	newTestRouter(t, "dev").ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusUnauthorized || rec.Body.String() != unauthenticatedJSON {
+		t.Errorf("response = %d %s, want 401 %s", rec.Code, rec.Body.String(), unauthenticatedJSON)
+	}
+}
+
+func TestRequireCSRF(t *testing.T) {
+	t.Parallel()
+
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	for _, tc := range []struct {
+		name       string
+		method     string
+		session    *auth.Session
+		header     string
+		wantStatus int
+	}{
+		{"right header reaches handler", http.MethodPost, &testSession, testSession.CSRFToken, http.StatusNoContent},
+		{"wrong header", http.MethodPut, &testSession, "nope", http.StatusForbidden},
+		{"GET needs no header", http.MethodGet, &testSession, "", http.StatusNoContent},
+		{"HEAD needs the header", http.MethodHead, &testSession, "", http.StatusForbidden},
+		{"OPTIONS needs the header", http.MethodOptions, &testSession, "", http.StatusForbidden},
+		{"no session in context", http.MethodPost, nil, "", http.StatusInternalServerError},
+		{"session without token", http.MethodPost, &auth.Session{Subject: "user-123"}, "", http.StatusInternalServerError},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			called := false
+			h := requireCSRF(logger)(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				called = true
+				w.WriteHeader(http.StatusNoContent)
+			}))
+			ctx := context.Background()
+			if tc.session != nil {
+				ctx = auth.WithSession(ctx, *tc.session)
+			}
+			req := httptest.NewRequestWithContext(ctx, tc.method, "/api/v1/anything", nil)
+			if tc.header != "" {
+				req.Header.Set(CSRFHeader, tc.header)
+			}
+			rec := httptest.NewRecorder()
+			h.ServeHTTP(rec, req)
+
+			if rec.Code != tc.wantStatus {
+				t.Errorf("status = %d, want %d", rec.Code, tc.wantStatus)
+			}
+			if called != (tc.wantStatus == http.StatusNoContent) {
+				t.Errorf("handler called = %v with status %d", called, rec.Code)
+			}
+		})
+	}
+}
+
+func TestMe(t *testing.T) {
+	t.Parallel()
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/me", nil)
+	req.AddCookie(validSessionCookie)
+	rec := httptest.NewRecorder()
+	newTestRouter(t, "dev").ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200 (body %s)", rec.Code, rec.Body.String())
+	}
+	if ct := rec.Header().Get("Content-Type"); ct != "application/json" {
+		t.Errorf("Content-Type = %q, want application/json", ct)
+	}
+	if cc := rec.Header().Get("Cache-Control"); cc != "no-store" {
+		t.Errorf("Cache-Control = %q, want no-store", cc)
+	}
+	var got map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
+		t.Fatalf("decode %s: %v", rec.Body.String(), err)
+	}
+	want := map[string]any{
+		"name":      "Home Cook",
+		"email":     "cook@example.com",
+		"household": map[string]any{"label": "Our kitchen"},
+		"csrfToken": "csrf-token-123",
+	}
+	gotJSON, _ := json.Marshal(got)
+	wantJSON, _ := json.Marshal(want)
+	if string(gotJSON) != string(wantJSON) {
+		t.Errorf("body = %s, want %s", gotJSON, wantJSON)
+	}
+}
+
+func TestMeNeedsSession(t *testing.T) {
+	t.Parallel()
+
+	rec := httptest.NewRecorder()
+	newTestRouter(t, "dev").ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/api/v1/me", nil))
+	if rec.Code != http.StatusUnauthorized || rec.Body.String() != unauthenticatedJSON {
+		t.Errorf("response = %d %s, want 401 %s", rec.Code, rec.Body.String(), unauthenticatedJSON)
+	}
+}

internal/server/login_test.go

@@ -0,0 +1,140 @@
+package server
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"testing"
+	"testing/fstest"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/auth"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/forwarded"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
+)
+
+// newDiscoveryProvider serves the OIDC discovery document auth.New needs;
+// login only redirects to its authorization endpoint.
+func newDiscoveryProvider(t *testing.T) *httptest.Server {
+	t.Helper()
+	var srv *httptest.Server
+	srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/.well-known/openid-configuration" {
+			http.NotFound(w, r)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]any{
+			"issuer":                                srv.URL,
+			"authorization_endpoint":                srv.URL + "/authorize",
+			"token_endpoint":                        srv.URL + "/token",
+			"jwks_uri":                              srv.URL + "/jwks",
+			"userinfo_endpoint":                     srv.URL + "/userinfo",
+			"end_session_endpoint":                  srv.URL + "/end-session/",
+			"response_types_supported":              []string{"code"},
+			"subject_types_supported":               []string{"public"},
+			"id_token_signing_alg_values_supported": []string{"RS256"},
+		})
+	}))
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+// newLoginRouter wires the production router as cmd/server does: the real
+// auth flow and session manager, trusting Traefik only.
+func newLoginRouter(t *testing.T, issuer string) http.Handler {
+	t.Helper()
+	ctx := context.Background()
+	db, err := store.Open(ctx, t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := db.Close(); err != nil {
+			t.Error(err)
+		}
+	})
+	if err := store.Migrate(ctx, db.Writer, migrations.FS); err != nil {
+		t.Fatal(err)
+	}
+	sessions, err := auth.NewSessionManager(db, 720*time.Hour, 4320*time.Hour)
+	if err != nil {
+		t.Fatal(err)
+	}
+	logger := slog.New(forwarded.LogHandler(slog.NewTextHandler(io.Discard, nil)))
+	flow, err := auth.New(ctx, auth.Config{
+		Issuer:        issuer,
+		ClientID:      "mealquest",
+		ClientSecret:  "client-s3cret",
+		PublicURL:     &url.URL{Scheme: "https", Host: "meals.example.com"},
+		SecretKey:     []byte("server-secret-key"),
+		AllowedGroups: []string{"mealquest-admin"},
+	}, sessions, logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	trusted, err := forwarded.ParseTrusted(traefik)
+	if err != nil {
+		t.Fatal(err)
+	}
+	r, err := NewRouter(logger, "dev", trusted, flow, sessions, newTestSettings(t),
+		fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return r
+}
+
+// TestLoginThroughRouter starts a login through the production router. The
+// redirect URI and the Secure login cookie come from MEALQUEST_PUBLIC_URL
+// whatever the direct peer: forwarded headers from an untrusted peer are
+// ignored but never fail sign-in.
+func TestLoginThroughRouter(t *testing.T) {
+	t.Parallel()
+	provider := newDiscoveryProvider(t)
+	router := newLoginRouter(t, provider.URL)
+	// Traefik reaches the service over plain http on its internal address;
+	// the host headers must not leak into the redirect URI.
+	headers := map[string]string{
+		forwarded.HeaderFor:   "203.0.113.7",
+		forwarded.HeaderProto: "https",
+		"X-Forwarded-Host":    "evil.example.com",
+	}
+	tests := []struct {
+		name string
+		peer string
+	}{
+		{"trusted proxy", traefik + ":41000"},
+		{"untrusted peer", "172.17.0.1:5000"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			rec := httptest.NewRecorder()
+			router.ServeHTTP(rec, originRequest("http://mealquest:8080"+auth.LoginPath, tt.peer, headers))
+			resp := rec.Result()
+			if resp.StatusCode != http.StatusFound {
+				t.Fatalf("login status = %d, want 302", resp.StatusCode)
+			}
+			loc, err := url.Parse(resp.Header.Get("Location"))
+			if err != nil {
+				t.Fatal(err)
+			}
+			if got, want := loc.Scheme+"://"+loc.Host+loc.Path, provider.URL+"/authorize"; got != want {
+				t.Errorf("redirect to %s, want %s", got, want)
+			}
+			if got, want := loc.Query().Get("redirect_uri"), "https://meals.example.com/auth/callback"; got != want {
+				t.Errorf("redirect_uri = %q, want %q from the public URL", got, want)
+			}
+			cookies := resp.Cookies()
+			if len(cookies) != 1 || cookies[0].Name != "__Host-mealquest_login" || !cookies[0].Secure || !cookies[0].HttpOnly {
+				t.Errorf("login cookies = %v, want one Secure, HttpOnly __Host-mealquest_login", cookies)
+			}
+		})
+	}
+}

internal/server/me.go

@@ -0,0 +1,52 @@
+package server
+
+import (
+	"encoding/json"
+	"log/slog"
+	"net/http"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/auth"
+)
+
+// householdLabel is the single shared household identity.
+const householdLabel = "Our kitchen"
+
+type meResponse struct {
+	Name      string        `json:"name"`
+	Email     string        `json:"email"`
+	Household householdInfo `json:"household"`
+	CSRFToken string        `json:"csrfToken"`
+}
+
+type householdInfo struct {
+	Label string `json:"label"`
+}
+
+// me answers GET /api/v1/me with the signed-in member, the household and the
+// session's CSRF token for CSRFHeader.
+func me(logger *slog.Logger) http.HandlerFunc {
+	internal := apiErrorHandler(logger, http.StatusInternalServerError, "internal", "internal error")
+	return func(w http.ResponseWriter, r *http.Request) {
+		s, ok := auth.SessionFrom(r.Context())
+		if !ok {
+			logger.ErrorContext(r.Context(), "GET /api/v1/me without a session")
+			internal(w, r)
+			return
+		}
+		body, err := json.Marshal(meResponse{
+			Name:      s.Name,
+			Email:     s.Email,
+			Household: householdInfo{Label: householdLabel},
+			CSRFToken: s.CSRFToken,
+		})
+		if err != nil {
+			panic(err) // string fields cannot fail to marshal
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.Header().Set("Cache-Control", "no-store")
+		w.WriteHeader(http.StatusOK)
+		if _, err := w.Write(body); err != nil {
+			logger.WarnContext(r.Context(), "write me response", "error", err)
+		}
+	}
+}

internal/server/origin.go

@@ -0,0 +1,34 @@
+package server
+
+import (
+	"errors"
+	"log/slog"
+	"net/http"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/forwarded"
+)
+
+// resolveOrigin resolves every request's client address and scheme with
+// forwarded.Resolve and puts them in the context (read them with
+// forwarded.ClientIP and forwarded.Scheme). Forwarded headers are honoured
+// only from a peer in trusted. A malformed forwarded header from a trusted
+// peer gets 400 bad_request.
+func resolveOrigin(logger *slog.Logger, trusted forwarded.Trusted) func(http.Handler) http.Handler {
+	badRequest := apiErrorHandler(logger, http.StatusBadRequest, "bad_request", "invalid forwarded headers")
+	internal := apiErrorHandler(logger, http.StatusInternalServerError, "internal", "internal error")
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			o, err := forwarded.Resolve(r, trusted)
+			switch {
+			case errors.Is(err, forwarded.ErrInvalidHeader):
+				logger.WarnContext(r.Context(), "rejected forwarded headers", "peer", r.RemoteAddr, "error", err)
+				badRequest(w, r)
+			case err != nil:
+				logger.ErrorContext(r.Context(), "resolve request origin", "error", err)
+				internal(w, r)
+			default:
+				next.ServeHTTP(w, r.WithContext(forwarded.NewContext(r.Context(), o)))
+			}
+		})
+	}
+}

internal/server/origin_test.go

@@ -0,0 +1,145 @@
+package server
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"testing/fstest"
+
+	"github.com/go-chi/chi/v5"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/forwarded"
+)
+
+// traefik is the production proxy's address.
+const traefik = "10.60.1.33"
+
+// probeAuth mounts GET /auth/probe, which reports the request's resolved
+// origin, in place of the real auth flow.
+type probeAuth struct{}
+
+func (probeAuth) Mount(r chi.Router) {
+	r.Get("/auth/probe", func(w http.ResponseWriter, r *http.Request) {
+		ip, ipOK := forwarded.ClientIP(r.Context())
+		scheme, schemeOK := forwarded.Scheme(r.Context())
+		if !ipOK || !schemeOK {
+			http.Error(w, "origin not resolved", http.StatusInternalServerError)
+			return
+		}
+		fmt.Fprintf(w, "%s %s", ip, scheme)
+	})
+}
+
+// newOriginRouter builds the production router trusting Traefik, logging
+// through forwarded.LogHandler as cmd/server does.
+func newOriginRouter(t *testing.T, logs io.Writer) http.Handler {
+	t.Helper()
+	trusted, err := forwarded.ParseTrusted(traefik)
+	if err != nil {
+		t.Fatal(err)
+	}
+	logger := slog.New(forwarded.LogHandler(slog.NewJSONHandler(logs, nil)))
+	r, err := NewRouter(logger, "dev", trusted, probeAuth{}, stubSessions{}, newTestSettings(t),
+		fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return r
+}
+
+func originRequest(target, peer string, headers map[string]string) *http.Request {
+	req := httptest.NewRequest(http.MethodGet, target, nil)
+	req.RemoteAddr = peer
+	for k, v := range headers {
+		req.Header.Set(k, v)
+	}
+	return req
+}
+
+func TestRouterResolvesOrigin(t *testing.T) {
+	t.Parallel()
+	spoofed := map[string]string{forwarded.HeaderFor: "203.0.113.7", forwarded.HeaderProto: "https"}
+	tests := []struct {
+		name string
+		peer string
+		want string
+	}{
+		{"trusted proxy's forwarded headers are honoured", traefik + ":41000", "203.0.113.7 https"},
+		{"untrusted peer spoofing them is ignored", "198.51.100.9:5000", "198.51.100.9 http"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			rec := httptest.NewRecorder()
+			newOriginRouter(t, io.Discard).ServeHTTP(rec, originRequest("/auth/probe", tt.peer, spoofed))
+			if rec.Code != http.StatusOK || rec.Body.String() != tt.want {
+				t.Errorf("probe = %d %q, want 200 %q", rec.Code, rec.Body.String(), tt.want)
+			}
+		})
+	}
+}
+
+func TestRouterLogsResolvedClientIP(t *testing.T) {
+	t.Parallel()
+	spoofed := map[string]string{forwarded.HeaderFor: "203.0.113.7", forwarded.HeaderProto: "https"}
+	tests := []struct {
+		name string
+		peer string
+		want string
+	}{
+		{"trusted proxy", traefik + ":41000", "203.0.113.7"},
+		{"untrusted peer spoofing", "198.51.100.9:5000", "198.51.100.9"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			var logs bytes.Buffer
+			// A failed session lookup is logged with the request's context.
+			req := originRequest("/api/v1/me", tt.peer, spoofed)
+			req.AddCookie(brokenSessionCookie)
+			rec := httptest.NewRecorder()
+			newOriginRouter(t, &logs).ServeHTTP(rec, req)
+			if rec.Code != http.StatusInternalServerError {
+				t.Fatalf("status = %d, want 500", rec.Code)
+			}
+			var line map[string]any
+			if err := json.Unmarshal(logs.Bytes(), &line); err != nil {
+				t.Fatalf("log %q: %v", logs.String(), err)
+			}
+			if line["msg"] != "look up session" || line[forwarded.LogAttr] != tt.want {
+				t.Errorf("log = %v, want the session error with %s=%s", line, forwarded.LogAttr, tt.want)
+			}
+		})
+	}
+}
+
+func TestRouterRejectsMalformedForwardedHeaders(t *testing.T) {
+	t.Parallel()
+	const badRequestJSON = `{"error":{"code":"bad_request","message":"invalid forwarded headers","retryable":false}}`
+	for _, headers := range []map[string]string{
+		{forwarded.HeaderFor: "not-an-ip"},
+		{forwarded.HeaderProto: "ftp"},
+	} {
+		var logs bytes.Buffer
+		rec := httptest.NewRecorder()
+		newOriginRouter(t, &logs).ServeHTTP(rec, originRequest("/health", traefik+":41000", headers))
+		if rec.Code != http.StatusBadRequest || rec.Body.String() != badRequestJSON {
+			t.Errorf("%v: response = %d %s, want 400 %s", headers, rec.Code, rec.Body.String(), badRequestJSON)
+		}
+		if !bytes.Contains(logs.Bytes(), []byte("rejected forwarded headers")) {
+			t.Errorf("%v: logs = %q, want the rejection logged", headers, logs.String())
+		}
+
+		// The same headers from an untrusted peer are not examined at all.
+		rec = httptest.NewRecorder()
+		newOriginRouter(t, io.Discard).ServeHTTP(rec, originRequest("/health", "198.51.100.9:5000", headers))
+		if rec.Code != http.StatusOK {
+			t.Errorf("%v from an untrusted peer: status = %d, want 200", headers, rec.Code)
+		}
+	}
+}

internal/server/server.go

@@ -3,22 +3,38 @@ package server
 
 import (
 	"encoding/json"
+	"errors"
 	"io/fs"
 	"log/slog"
 	"net/http"
 
 	"github.com/go-chi/chi/v5"
 
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/forwarded"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/frontend"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
 )
 
 // reservedPrefixes are owned by the API router and are never answered with the
 // SPA's index.html.
 var reservedPrefixes = []string{"/api", "/auth", "/media", "/health"}
 
-// NewRouter returns the HTTP handler for the service. version is reported by
-// GET /health; assets is the web build served for every other GET.
-func NewRouter(logger *slog.Logger, version string, assets fs.FS) (http.Handler, error) {
+// RouteMounter registers its own routes on the router.
+type RouteMounter interface {
+	Mount(r chi.Router)
+}
+
+// NewRouter returns the HTTP handler for the service. Every request first
+// has its client address and scheme resolved, honouring forwarded headers
+// only from a peer in trusted (see resolveOrigin). version is reported by
+// GET /health; auth mounts the /auth routes; sessions guards /api/v1 and
+// /media; settings serves /api/v1/settings/household; assets is the web build
+// served for every other GET. /health, /auth and the web build are public.
+// Requests to /api/v1 other than GET also need the session's CSRF token in CSRFHeader.
+func NewRouter(logger *slog.Logger, version string, trusted forwarded.Trusted, auth RouteMounter, sessions SessionLookup, settings *household.SettingsService, assets fs.FS) (http.Handler, error) {
+	if settings == nil {
+		return nil, errors.New("server: nil household settings service")
+	}
 	notFound := apiErrorHandler(logger, http.StatusNotFound, "not_found", "not found")
 	methodNotAllowed := apiErrorHandler(logger, http.StatusMethodNotAllowed, "method_not_allowed", "method not allowed")
 
@@ -28,16 +44,33 @@ func NewRouter(logger *slog.Logger, version string, assets fs.FS) (http.Handler,
 	}
 
 	r := chi.NewRouter()
+	r.Use(resolveOrigin(logger, trusted))
 	r.MethodNotAllowed(methodNotAllowed)
 	r.NotFound(notFound)
 
 	r.Get("/health", health(logger, version))
+	auth.Mount(r)
+	// The session middleware wraps the whole /api/v1 and /media subrouters
+	// rather than being added with Use: chi skips a subrouter's middleware
+	// when it has no routes, which would leave it unguarded.
+	signedIn := requireSession(logger, sessions)
+	csrf := requireCSRF(logger)
+	apiV1, media := chi.NewRouter(), chi.NewRouter()
+	for _, sub := range []*chi.Mux{apiV1, media} {
+		sub.MethodNotAllowed(methodNotAllowed)
+		sub.NotFound(notFound)
+	}
+	apiV1.Get("/me", me(logger))
+	apiV1.Get("/settings/household", getHouseholdSettings(logger, settings))
+	apiV1.Patch("/settings/household", patchHouseholdSettings(logger, settings))
 	r.Route("/api", func(r chi.Router) {
 		r.MethodNotAllowed(methodNotAllowed)
 		r.NotFound(notFound)
+		r.Mount("/v1", signedIn(csrf(apiV1)))
 	})
-	// Catch-all for the PWA. /auth and /media have no routes yet; the frontend
-	// handler passes them to notFound rather than the SPA fallback.
+	r.Mount("/media", signedIn(media))
+	// Catch-all for the PWA. Unknown /auth paths reach the frontend handler,
+	// which passes them to notFound rather than the SPA fallback.
 	r.Method(http.MethodGet, "/*", web)
 	r.Method(http.MethodHead, "/*", web)
 	return r, nil
@@ -55,19 +88,8 @@ type apiError struct {
 
 // apiErrorHandler responds with status and a fixed, non-retryable API error.
 func apiErrorHandler(logger *slog.Logger, status int, code, message string) http.HandlerFunc {
-	body, err := json.Marshal(errorBody{Error: apiError{
-		Code:    code,
-		Message: message,
-	}})
-	if err != nil {
-		panic(err) // fixed string and bool fields cannot fail to marshal
-	}
 	return func(w http.ResponseWriter, r *http.Request) {
-		w.Header().Set("Content-Type", "application/json")
-		w.WriteHeader(status)
-		if _, err := w.Write(body); err != nil {
-			logger.WarnContext(r.Context(), "write error response", "code", code, "error", err)
-		}
+		writeError(w, r, logger, status, code, message)
 	}
 }
 

internal/server/server_test.go

@@ -1,6 +1,7 @@
 package server
 
 import (
+	"context"
 	"encoding/json"
 	"io"
 	"log/slog"
@@ -10,6 +11,12 @@ import (
 	"strings"
 	"testing"
 	"testing/fstest"
+
+	"github.com/go-chi/chi/v5"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
 )
 
 const (
@@ -19,19 +26,82 @@ const (
 )
 
 func newTestRouter(t *testing.T, version string) http.Handler {
+	t.Helper()
+	return newTestRouterWith(t, version, newTestSettings(t))
+}
+
+func newTestRouterWith(t *testing.T, version string, settings *household.SettingsService) http.Handler {
 	t.Helper()
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
 	assets := fstest.MapFS{
 		"index.html":             {Data: []byte(fixtureIndex)},
 		"assets/index-AbC123.js": {Data: []byte(fixtureAsset)},
 	}
-	r, err := NewRouter(logger, version, assets)
+	r, err := NewRouter(logger, version, nil, stubAuth{}, stubSessions{}, settings, assets)
 	if err != nil {
 		t.Fatal(err)
 	}
 	return r
 }
 
+// stubAuth mounts a fixed GET /auth/login in place of the real auth flow.
+type stubAuth struct{}
+
+func (stubAuth) Mount(r chi.Router) {
+	r.Get("/auth/login", func(w http.ResponseWriter, _ *http.Request) {
+		io.WriteString(w, "stub login")
+	})
+}
+
+func TestAuthRoutesMounted(t *testing.T) {
+	t.Parallel()
+
+	router := newTestRouter(t, "dev")
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/auth/login", nil))
+	if rec.Code != http.StatusOK || rec.Body.String() != "stub login" {
+		t.Errorf("GET /auth/login = %d %q, want the mounted handler", rec.Code, rec.Body.String())
+	}
+
+	rec = httptest.NewRecorder()
+	router.ServeHTTP(rec, httptest.NewRequest(http.MethodPost, "/auth/login", nil))
+	if rec.Code != http.StatusMethodNotAllowed {
+		t.Errorf("POST /auth/login status = %d, want 405", rec.Code)
+	}
+}
+
+// newTestSettings returns a settings service over a migrated temp database
+// seeded with zone America/New_York.
+func newTestSettings(t *testing.T) *household.SettingsService {
+	t.Helper()
+	ctx := context.Background()
+	st, err := store.Open(ctx, t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := st.Close(); err != nil {
+			t.Error(err)
+		}
+	})
+	if err := store.Migrate(ctx, st.Writer, migrations.FS); err != nil {
+		t.Fatal(err)
+	}
+	if err := household.SeedSettings(ctx, st, "America/New_York"); err != nil {
+		t.Fatal(err)
+	}
+	return household.NewSettingsService(st)
+}
+
+func TestNewRouterRequiresSettings(t *testing.T) {
+	t.Parallel()
+
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, nil, fstest.MapFS{"index.html": {}}); err == nil {
+		t.Fatal("NewRouter accepted a nil settings service")
+	}
+}
+
 func TestHealth(t *testing.T) {
 	t.Parallel()
 
@@ -98,8 +168,10 @@ func TestReservedPathsNotFound(t *testing.T) {
 	}{
 		{http.MethodGet, "/api"},
 		{http.MethodGet, "/api/unknown"},
+		{http.MethodGet, "/api/v1/unknown"},
+		{http.MethodPost, "/api/v1/unknown"},
 		{http.MethodPost, "/api/unknown"},
-		{http.MethodGet, "/auth/callback"},
+		{http.MethodGet, "/auth/unknown"},
 		{http.MethodGet, "/media/photo.jpg"},
 		{http.MethodGet, "/health/deep"},
 		{http.MethodGet, "/auth/../quests/42"},
@@ -109,8 +181,13 @@ func TestReservedPathsNotFound(t *testing.T) {
 		t.Run(tt.method+" "+tt.path, func(t *testing.T) {
 			t.Parallel()
 
+			// Signed in with the CSRF token, so /api/v1 and /media reach
+			// their routers.
+			req := httptest.NewRequest(tt.method, tt.path, nil)
+			req.AddCookie(validSessionCookie)
+			req.Header.Set(CSRFHeader, testSession.CSRFToken)
 			rec := httptest.NewRecorder()
-			router.ServeHTTP(rec, httptest.NewRequest(tt.method, tt.path, nil))
+			router.ServeHTTP(rec, req)
 
 			if rec.Code != http.StatusNotFound {
 				t.Errorf("status = %d, want 404", rec.Code)

internal/server/session.go

@@ -0,0 +1,37 @@
+package server
+
+import (
+	"errors"
+	"log/slog"
+	"net/http"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/auth"
+)
+
+// SessionLookup finds the live session a request carries; it returns
+// auth.ErrNoSession when there is none. *auth.SessionManager implements it.
+type SessionLookup interface {
+	SessionFor(r *http.Request) (auth.Session, error)
+}
+
+// requireSession is the RequireSession middleware. It passes requests with a
+// live session to next with the session in the context (read it with
+// auth.SessionFrom or auth.ActorFrom); others get 401 unauthenticated.
+func requireSession(logger *slog.Logger, sessions SessionLookup) func(http.Handler) http.Handler {
+	unauthenticated := apiErrorHandler(logger, http.StatusUnauthorized, "unauthenticated", "sign in required")
+	internal := apiErrorHandler(logger, http.StatusInternalServerError, "internal", "internal error")
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			s, err := sessions.SessionFor(r)
+			switch {
+			case errors.Is(err, auth.ErrNoSession):
+				unauthenticated(w, r)
+			case err != nil:
+				logger.ErrorContext(r.Context(), "look up session", "error", err)
+				internal(w, r)
+			default:
+				next.ServeHTTP(w, r.WithContext(auth.WithSession(r.Context(), s)))
+			}
+		})
+	}
+}

internal/server/session_test.go

@@ -0,0 +1,152 @@
+package server
+
+import (
+	"errors"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"slices"
+	"testing"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/auth"
+)
+
+const (
+	unauthenticatedJSON = `{"error":{"code":"unauthenticated","message":"sign in required","retryable":false}}`
+	internalJSON        = `{"error":{"code":"internal","message":"internal error","retryable":false}}`
+)
+
+var (
+	validSessionCookie  = &http.Cookie{Name: auth.SessionCookieName, Value: "valid"}
+	brokenSessionCookie = &http.Cookie{Name: auth.SessionCookieName, Value: "broken"}
+	testSession         = auth.Session{
+		Subject:   "user-123",
+		Email:     "cook@example.com",
+		Name:      "Home Cook",
+		Groups:    []string{"mealquest-admin"},
+		CSRFToken: "csrf-token-123",
+	}
+)
+
+// stubSessions knows one valid session cookie; the broken cookie fails the
+// lookup as a database error would.
+type stubSessions struct{}
+
+func (stubSessions) SessionFor(r *http.Request) (auth.Session, error) {
+	c, err := r.Cookie(auth.SessionCookieName)
+	switch {
+	case err != nil:
+		return auth.Session{}, auth.ErrNoSession
+	case c.Value == validSessionCookie.Value:
+		return testSession, nil
+	case c.Value == brokenSessionCookie.Value:
+		return auth.Session{}, errors.New("database down")
+	default:
+		return auth.Session{}, auth.ErrNoSession
+	}
+}
+
+func TestProtectedPathsRequireSession(t *testing.T) {
+	t.Parallel()
+
+	router := newTestRouter(t, "dev")
+	for _, tc := range []struct {
+		method, path string
+		cookie       *http.Cookie
+	}{
+		{http.MethodGet, "/api/v1/settings/household", nil},
+		{http.MethodPatch, "/api/v1/settings/household", nil},
+		{http.MethodGet, "/api/v1", nil},
+		{http.MethodGet, "/media/photo.jpg", nil},
+		{http.MethodGet, "/api/v1/settings/household", &http.Cookie{Name: auth.SessionCookieName, Value: "unknown"}},
+	} {
+		t.Run(tc.method+" "+tc.path, func(t *testing.T) {
+			t.Parallel()
+			req := httptest.NewRequest(tc.method, tc.path, nil)
+			if tc.cookie != nil {
+				req.AddCookie(tc.cookie)
+			}
+			rec := httptest.NewRecorder()
+			router.ServeHTTP(rec, req)
+
+			if rec.Code != http.StatusUnauthorized {
+				t.Errorf("status = %d, want 401", rec.Code)
+			}
+			if ct := rec.Header().Get("Content-Type"); ct != "application/json" {
+				t.Errorf("Content-Type = %q, want application/json", ct)
+			}
+			if got := rec.Body.String(); got != unauthenticatedJSON {
+				t.Errorf("body = %s, want %s", got, unauthenticatedJSON)
+			}
+		})
+	}
+}
+
+func TestPublicPathsNeedNoSession(t *testing.T) {
+	t.Parallel()
+
+	router := newTestRouter(t, "dev")
+	for _, path := range []string{"/health", "/auth/login", "/", "/assets/index-AbC123.js", "/quests/42"} {
+		t.Run(path, func(t *testing.T) {
+			t.Parallel()
+			rec := httptest.NewRecorder()
+			router.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, path, nil))
+			if rec.Code != http.StatusOK {
+				t.Errorf("GET %s without a cookie = %d, want 200", path, rec.Code)
+			}
+		})
+	}
+}
+
+func TestSessionLookupFailure(t *testing.T) {
+	t.Parallel()
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/settings/household", nil)
+	req.AddCookie(brokenSessionCookie)
+	rec := httptest.NewRecorder()
+	newTestRouter(t, "dev").ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusInternalServerError || rec.Body.String() != internalJSON {
+		t.Errorf("response = %d %s, want 500 %s", rec.Code, rec.Body.String(), internalJSON)
+	}
+}
+
+func TestRequireSessionAttachesActor(t *testing.T) {
+	t.Parallel()
+
+	var got auth.Actor
+	var ok bool
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		got, ok = auth.ActorFrom(r.Context())
+		w.WriteHeader(http.StatusNoContent)
+	})
+	h := requireSession(slog.New(slog.NewTextHandler(io.Discard, nil)), stubSessions{})(next)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/settings/household", nil)
+	req.AddCookie(validSessionCookie)
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusNoContent {
+		t.Fatalf("status = %d, want the handler's 204", rec.Code)
+	}
+	if !ok || got.Subject != "user-123" || got.Email != "cook@example.com" || got.Name != "Home Cook" ||
+		!slices.Equal(got.Groups, []string{"mealquest-admin"}) {
+		t.Errorf("actor = %+v (ok=%v), want the session's household member", got, ok)
+	}
+}
+
+func TestRequireSessionStopsUnauthenticated(t *testing.T) {
+	t.Parallel()
+
+	called := false
+	next := http.HandlerFunc(func(http.ResponseWriter, *http.Request) { called = true })
+	h := requireSession(slog.New(slog.NewTextHandler(io.Discard, nil)), stubSessions{})(next)
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/api/v1/settings/household", nil))
+
+	if called || rec.Code != http.StatusUnauthorized {
+		t.Errorf("handler called = %v, status = %d; want not called and 401", called, rec.Code)
+	}
+}

internal/server/settings.go

@@ -0,0 +1,135 @@
+package server
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/auth"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+)
+
+// maxSettingsBody bounds a PATCH /settings/household request body.
+const maxSettingsBody = 16 << 10
+
+// settingsPatch is the PATCH /settings/household body. Every field is
+// optional; unknown fields and null values are refused.
+type settingsPatch struct {
+	Timezone         *string `json:"timezone"`
+	DinnerTime       *string `json:"dinner_time"`
+	ReminderTime     *string `json:"reminder_time"`
+	ReviewTime       *string `json:"review_time"`
+	PlanDraftDow     *int    `json:"plan_draft_dow"`
+	PlanDraftTime    *string `json:"plan_draft_time"`
+	SuggestionsDow   *int    `json:"suggestions_dow"`
+	SuggestionsTime  *string `json:"suggestions_time"`
+	ChatAutosendDow  *int    `json:"chat_autosend_dow"`
+	ChatAutosendTime *string `json:"chat_autosend_time"`
+}
+
+func getHouseholdSettings(logger *slog.Logger, svc *household.SettingsService) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		settings, err := svc.Get(r.Context())
+		if err != nil {
+			logger.ErrorContext(r.Context(), "get household settings", "error", err)
+			writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, settings)
+	}
+}
+
+// patchHouseholdSettings records the session's actor subject as updated_by.
+func patchHouseholdSettings(logger *slog.Logger, svc *household.SettingsService) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		actor, ok := auth.ActorFrom(r.Context())
+		if !ok {
+			logger.ErrorContext(r.Context(), "PATCH /api/v1/settings/household without a session")
+			writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+			return
+		}
+		patch, err := decodeSettingsPatch(http.MaxBytesReader(w, r.Body, maxSettingsBody))
+		if err != nil {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_request", err.Error())
+			return
+		}
+		settings, err := svc.Update(r.Context(), household.SettingsPatch(patch), actor.Subject)
+		var invalid *household.ValidationError
+		if errors.As(err, &invalid) {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_settings", invalid.Error())
+			return
+		}
+		if err != nil {
+			logger.ErrorContext(r.Context(), "update household settings", "error", err)
+			writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, settings)
+	}
+}
+
+// decodeSettingsPatch reads a single JSON object, refusing unknown fields,
+// null values and trailing data.
+func decodeSettingsPatch(body io.Reader) (settingsPatch, error) {
+	data, err := io.ReadAll(body)
+	if err != nil {
+		var tooLarge *http.MaxBytesError
+		if errors.As(err, &tooLarge) {
+			return settingsPatch{}, fmt.Errorf("request body exceeds %d bytes", tooLarge.Limit)
+		}
+		return settingsPatch{}, errors.New("cannot read request body")
+	}
+
+	var fields map[string]json.RawMessage
+	if err := json.Unmarshal(data, &fields); err != nil || fields == nil {
+		return settingsPatch{}, errors.New("request body must be a JSON object")
+	}
+	for name, raw := range fields {
+		if bytes.Equal(raw, []byte("null")) {
+			return settingsPatch{}, fmt.Errorf("%s: must not be null", name)
+		}
+	}
+
+	var patch settingsPatch
+	dec := json.NewDecoder(bytes.NewReader(data))
+	dec.DisallowUnknownFields()
+	if err := dec.Decode(&patch); err != nil {
+		var typeErr *json.UnmarshalTypeError
+		if errors.As(err, &typeErr) {
+			return settingsPatch{}, fmt.Errorf("%s: want a JSON %s", typeErr.Field, typeErr.Type)
+		}
+		return settingsPatch{}, fmt.Errorf("invalid settings: %v", err)
+	}
+	return patch, nil
+}
+
+func writeJSON(w http.ResponseWriter, r *http.Request, logger *slog.Logger, status int, v any) {
+	body, err := json.Marshal(v)
+	if err != nil {
+		logger.ErrorContext(r.Context(), "encode response", "error", err)
+		writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+		return
+	}
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	if _, err := w.Write(body); err != nil {
+		logger.WarnContext(r.Context(), "write response", "error", err)
+	}
+}
+
+// writeError responds with status and a non-retryable API error.
+func writeError(w http.ResponseWriter, r *http.Request, logger *slog.Logger, status int, code, message string) {
+	body, err := json.Marshal(errorBody{Error: apiError{Code: code, Message: message}})
+	if err != nil {
+		panic(err) // string and bool fields cannot fail to marshal
+	}
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	if _, err := w.Write(body); err != nil {
+		logger.WarnContext(r.Context(), "write error response", "code", code, "error", err)
+	}
+}

internal/server/settings_test.go

@@ -0,0 +1,278 @@
+package server
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"testing/fstest"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/auth"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
+)
+
+const settingsPath = "/api/v1/settings/household"
+
+// signedIn returns a request carrying stubSessions' valid session cookie and
+// its CSRF token.
+func signedIn(method, target string, body io.Reader) *http.Request {
+	req := httptest.NewRequest(method, target, body)
+	req.AddCookie(validSessionCookie)
+	req.Header.Set(CSRFHeader, testSession.CSRFToken)
+	return req
+}
+
+func serve(t *testing.T, h http.Handler, req *http.Request) (*httptest.ResponseRecorder, map[string]any) {
+	t.Helper()
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	if ct := rec.Header().Get("Content-Type"); ct != "application/json" {
+		t.Errorf("Content-Type = %q, want application/json", ct)
+	}
+	var body map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("decode body %q: %v", rec.Body.String(), err)
+	}
+	return rec, body
+}
+
+func TestGetHouseholdSettings(t *testing.T) {
+	t.Parallel()
+
+	rec, body := serve(t, newTestRouter(t, "dev"), signedIn(http.MethodGet, settingsPath, nil))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200: %s", rec.Code, rec.Body)
+	}
+	want := map[string]any{
+		"timezone":                "America/New_York",
+		"dinner_time":             "17:30",
+		"reminder_time":           "16:30",
+		"review_time":             "09:00",
+		"plan_draft_dow":          float64(5),
+		"plan_draft_time":         "09:00",
+		"suggestions_dow":         float64(0),
+		"suggestions_time":        "08:00",
+		"chat_autosend_dow":       float64(6),
+		"chat_autosend_time":      "08:00",
+		"onboarding_completed_at": nil,
+		"updates_seen_at":         nil,
+		"updated_by":              nil,
+	}
+	for k, v := range want {
+		got, ok := body[k]
+		if !ok || got != v {
+			t.Errorf("%s = %#v (present %v), want %#v", k, got, ok, v)
+		}
+	}
+	for _, k := range []string{"created_at", "updated_at"} {
+		if s, ok := body[k].(string); !ok || s == "" {
+			t.Errorf("%s = %#v, want a timestamp", k, body[k])
+		}
+	}
+	if len(body) != len(want)+2 {
+		t.Errorf("body has %d fields, want %d: %v", len(body), len(want)+2, body)
+	}
+}
+
+func TestPatchHouseholdSettings(t *testing.T) {
+	t.Parallel()
+	settings := newTestSettings(t)
+	router := newTestRouterWith(t, "dev", settings)
+
+	var notified []household.Settings
+	settings.Subscribe(func(s household.Settings) { notified = append(notified, s) })
+
+	rec, body := serve(t, router, signedIn(http.MethodPatch, settingsPath,
+		strings.NewReader(`{"timezone":"Europe/Berlin","dinner_time":"18:00","plan_draft_dow":4}`)))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200: %s", rec.Code, rec.Body)
+	}
+	for k, v := range map[string]any{
+		"timezone":       "Europe/Berlin",
+		"dinner_time":    "18:00",
+		"plan_draft_dow": float64(4),
+		"reminder_time":  "16:30", // unchanged
+		"updated_by":     testSession.Subject,
+	} {
+		if body[k] != v {
+			t.Errorf("%s = %#v, want %#v", k, body[k], v)
+		}
+	}
+	if len(notified) != 1 || notified[0].Timezone != "Europe/Berlin" {
+		t.Errorf("subscriber notified with %+v, want one change to Europe/Berlin", notified)
+	}
+
+	_, body = serve(t, router, signedIn(http.MethodGet, settingsPath, nil))
+	if body["timezone"] != "Europe/Berlin" || body["updated_by"] != testSession.Subject {
+		t.Errorf("GET after PATCH = %v", body)
+	}
+}
+
+func TestPatchHouseholdSettingsRejected(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		body string
+		code string
+		in   string // the error message must contain this
+	}{
+		{"bad timezone", `{"timezone":"Mars/Olympus_Mons"}`, "invalid_settings", "timezone"},
+		{"bad time", `{"dinner_time":"25:00"}`, "invalid_settings", "dinner_time"},
+		{"unpadded time", `{"reminder_time":"9:30"}`, "invalid_settings", "reminder_time"},
+		{"bad dow", `{"suggestions_dow":7}`, "invalid_settings", "suggestions_dow"},
+		{"negative dow", `{"chat_autosend_dow":-1}`, "invalid_settings", "chat_autosend_dow"},
+		{"empty object", `{}`, "invalid_settings", "no settings to change"},
+		{"fractional dow", `{"plan_draft_dow":5.5}`, "invalid_request", "plan_draft_dow"},
+		{"string dow", `{"plan_draft_dow":"5"}`, "invalid_request", "plan_draft_dow"},
+		{"numeric time", `{"dinner_time":1730}`, "invalid_request", "dinner_time"},
+		{"null value", `{"timezone":null}`, "invalid_request", "timezone"},
+		{"unknown field", `{"dinner":"17:30"}`, "invalid_request", "dinner"},
+		{"read-only field", `{"updated_by":"someone"}`, "invalid_request", "updated_by"},
+		{"not an object", `["timezone"]`, "invalid_request", "JSON object"},
+		{"null body", `null`, "invalid_request", "JSON object"},
+		{"trailing data", `{"dinner_time":"18:00"} {}`, "invalid_request", "JSON object"},
+		{"malformed", `{"dinner_time":`, "invalid_request", "JSON object"},
+		{"too large", `{"timezone":"` + strings.Repeat("a", maxSettingsBody) + `"}`, "invalid_request", "exceeds"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			settings := newTestSettings(t)
+			router := newTestRouterWith(t, "dev", settings)
+			notified := 0
+			settings.Subscribe(func(household.Settings) { notified++ })
+
+			rec, body := serve(t, router, signedIn(http.MethodPatch, settingsPath, strings.NewReader(tt.body)))
+			if rec.Code != http.StatusBadRequest {
+				t.Fatalf("status = %d, want 400: %s", rec.Code, rec.Body)
+			}
+			apiErr, ok := body["error"].(map[string]any)
+			if !ok || len(body) != 1 || len(apiErr) != 3 {
+				t.Fatalf("body = %s, want {\"error\":{code,message,retryable}}", rec.Body)
+			}
+			if apiErr["code"] != tt.code || apiErr["retryable"] != false {
+				t.Errorf("error = %v, want code %q, retryable false", apiErr, tt.code)
+			}
+			if msg, _ := apiErr["message"].(string); !strings.Contains(msg, tt.in) {
+				t.Errorf("message %q does not contain %q", msg, tt.in)
+			}
+			if notified != 0 {
+				t.Errorf("rejected PATCH notified subscribers %d times", notified)
+			}
+			_, after := serve(t, router, signedIn(http.MethodGet, settingsPath, nil))
+			if after["timezone"] != "America/New_York" || after["dinner_time"] != "17:30" || after["updated_by"] != nil {
+				t.Errorf("rejected PATCH changed settings: %v", after)
+			}
+		})
+	}
+}
+
+func TestHouseholdSettingsMethodNotAllowed(t *testing.T) {
+	t.Parallel()
+
+	rec, body := serve(t, newTestRouter(t, "dev"), signedIn(http.MethodPut, settingsPath, strings.NewReader(`{}`)))
+	if rec.Code != http.StatusMethodNotAllowed {
+		t.Errorf("status = %d, want 405", rec.Code)
+	}
+	if apiErr, _ := body["error"].(map[string]any); apiErr["code"] != "method_not_allowed" {
+		t.Errorf("body = %v", body)
+	}
+}
+
+// TestHouseholdSettingsWithRealSession drives the settings API through the
+// production router and session manager: a member signs in, reads the CSRF
+// token from GET /api/v1/me and PATCHes; updated_by comes from the session.
+// Without a session, or without the CSRF token, the PATCH is refused and
+// nothing changes.
+func TestHouseholdSettingsWithRealSession(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	st, err := store.Open(ctx, t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := st.Close(); err != nil {
+			t.Error(err)
+		}
+	})
+	if err := store.Migrate(ctx, st.Writer, migrations.FS); err != nil {
+		t.Fatal(err)
+	}
+	if err := household.SeedSettings(ctx, st, "America/New_York"); err != nil {
+		t.Fatal(err)
+	}
+	sessions, err := auth.NewSessionManager(st, time.Hour, 24*time.Hour)
+	if err != nil {
+		t.Fatal(err)
+	}
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	router, err := NewRouter(logger, "dev", nil, stubAuth{}, sessions, household.NewSettingsService(st),
+		fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Sign in as the callback would.
+	login := httptest.NewRecorder()
+	if err := sessions.StartSession(login, httptest.NewRequest(http.MethodGet, "/auth/callback", nil), auth.Claims{
+		Subject: "authentik-sub-42",
+		Email:   "cook@example.com",
+		Name:    "Home Cook",
+		Groups:  []string{"mealquest-admin"},
+	}); err != nil {
+		t.Fatal(err)
+	}
+	cookies := login.Result().Cookies()
+	if len(cookies) != 1 || cookies[0].Name != auth.SessionCookieName {
+		t.Fatalf("StartSession set cookies %v, want the session cookie", cookies)
+	}
+	cookie := cookies[0]
+	withCookie := func(req *http.Request) *http.Request {
+		req.AddCookie(cookie)
+		return req
+	}
+
+	rec, me := serve(t, router, withCookie(httptest.NewRequest(http.MethodGet, "/api/v1/me", nil)))
+	token, _ := me["csrfToken"].(string)
+	if rec.Code != http.StatusOK || token == "" {
+		t.Fatalf("GET /api/v1/me = %d %v, want 200 with a CSRF token", rec.Code, me)
+	}
+
+	patch := `{"dinner_time":"18:45"}`
+	refused := []struct {
+		name   string
+		req    *http.Request
+		status int
+	}{
+		{"no session", httptest.NewRequest(http.MethodPatch, settingsPath, strings.NewReader(patch)), http.StatusUnauthorized},
+		{"no CSRF token", withCookie(httptest.NewRequest(http.MethodPatch, settingsPath, strings.NewReader(patch))), http.StatusForbidden},
+	}
+	for _, tt := range refused {
+		if rec, body := serve(t, router, tt.req); rec.Code != tt.status {
+			t.Errorf("%s: PATCH status = %d, want %d: %v", tt.name, rec.Code, tt.status, body)
+		}
+	}
+	_, body := serve(t, router, withCookie(httptest.NewRequest(http.MethodGet, settingsPath, nil)))
+	if body["dinner_time"] != household.SeedDinnerTime || body["updated_by"] != nil {
+		t.Fatalf("refused PATCH changed settings: %v", body)
+	}
+
+	req := withCookie(httptest.NewRequest(http.MethodPatch, settingsPath, strings.NewReader(patch)))
+	req.Header.Set(CSRFHeader, token)
+	rec, body = serve(t, router, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("PATCH status = %d, want 200: %v", rec.Code, body)
+	}
+	if body["dinner_time"] != "18:45" || body["updated_by"] != "authentik-sub-42" {
+		t.Errorf("PATCH = %v, want dinner_time 18:45 updated_by authentik-sub-42", body)
+	}
+}

internal/store/migrate_test.go

@@ -175,8 +175,8 @@ func TestMigrateEmbeddedMigrations(t *testing.T) {
 	if err := Migrate(context.Background(), s.Writer, migrations.FS); err != nil {
 		t.Fatal(err)
 	}
-	if got := versions(migrationRows(t, s)); got != "0000_bootstrap,0001_init" {
-		t.Errorf("versions = %q, want 0000_bootstrap,0001_init", got)
+	if got := versions(migrationRows(t, s)); got != "0000_bootstrap,0001_init,0002_household_settings_updated_by" {
+		t.Errorf("versions = %q, want 0000_bootstrap,0001_init,0002_household_settings_updated_by", got)
 	}
 }
 
@@ -188,15 +188,16 @@ func TestMigrateBootstrapThenEmbeddedInitApplies(t *testing.T) {
 		t.Fatal(err)
 	}
 	// A database migrated by the bootstrap-only build upgrades to the
-	// embedded set, which adds 0001_init.sql alongside the unchanged bootstrap.
+	// embedded set, which adds the later migrations alongside the unchanged
+	// bootstrap.
 	if err := Migrate(ctx, s.Writer, fstest.MapFS{"0000_bootstrap.sql": {Data: bootstrap}}); err != nil {
 		t.Fatal(err)
 	}
 	if err := Migrate(ctx, s.Writer, migrations.FS); err != nil {
 		t.Fatal(err)
 	}
-	if got := versions(migrationRows(t, s)); got != "0000_bootstrap,0001_init" {
-		t.Errorf("versions = %q, want 0000_bootstrap,0001_init", got)
+	if got := versions(migrationRows(t, s)); got != "0000_bootstrap,0001_init,0002_household_settings_updated_by" {
+		t.Errorf("versions = %q, want 0000_bootstrap,0001_init,0002_household_settings_updated_by", got)
 	}
 	if !tableExists(t, s, "dinners") {
 		t.Error("table from 0001_init was not created")

migrations/0002_household_settings_updated_by.sql

@@ -0,0 +1,4 @@
+-- 0002_household_settings_updated_by: record who last changed the household
+-- settings, as dinners and suggestion_batches already do. NULL until the
+-- first change made by a signed-in member.
+ALTER TABLE household_settings ADD COLUMN updated_by TEXT;

migrations/queries/settings.sql

@@ -10,12 +10,12 @@ INSERT INTO household_settings (
 	id, timezone, dinner_time, reminder_time, review_time, plan_draft_dow,
 	plan_draft_time, suggestions_dow, suggestions_time, chat_autosend_dow,
 	chat_autosend_time, onboarding_completed_at, updates_seen_at,
-	created_at, updated_at
+	updated_by, created_at, updated_at
 ) VALUES (
 	1, ?, ?, ?, ?, ?,
 	?, ?, ?, ?,
 	?, ?, ?,
-	?, ?
+	?, ?, ?
 )
 ON CONFLICT (id) DO UPDATE SET
 	timezone = excluded.timezone,
@@ -30,6 +30,7 @@ ON CONFLICT (id) DO UPDATE SET
 	chat_autosend_time = excluded.chat_autosend_time,
 	onboarding_completed_at = excluded.onboarding_completed_at,
 	updates_seen_at = excluded.updates_seen_at,
+	updated_by = excluded.updated_by,
 	updated_at = excluded.updated_at
 RETURNING *;