Retry job claims after a database error instead of waiting for a wake

A claim that failed with anything but sql.ErrNoRows parked the worker
on the wake channel, so a job queued across a restart (which has no
wake token) stayed queued until another enqueue or restart. The worker
now retries such a claim with backoff from 50ms doubling to 5s, reset
on any successful or empty claim, and stops promptly on shutdown. The
claim error is logged by category only.

The claim query is a Runner field so a test can inject one failing
claim; TestClaimErrorIsRetried drops the wake token and asserts the
queued job still runs.

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,163 @@ 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)
+	}
+}
+
+func TestSeedDefaultsAtBoot(t *testing.T) {
+	ctx := context.Background()
+	db, err := openStore(ctx, t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := db.Close(); err != nil {
+			t.Error(err)
+		}
+	})
+	if err := seedDefaults(ctx, db, "America/Denver"); err != nil {
+		t.Fatal(err)
+	}
+
+	if _, err := household.NewSettingsService(db).Get(ctx); err != nil {
+		t.Errorf("household settings: %v", err)
+	}
+	var provider string
+	if err := db.Reader.QueryRowContext(ctx, `SELECT provider FROM ai_settings`).Scan(&provider); err != nil {
+		t.Errorf("AI settings: %v", err)
+	} else if provider != household.SeedAIProvider {
+		t.Errorf("AI provider = %q, want %q", provider, household.SeedAIProvider)
+	}
+	var prefs int
+	if err := db.Reader.QueryRowContext(ctx, `SELECT count(*) FROM notification_prefs`).Scan(&prefs); err != nil {
+		t.Fatal(err)
+	}
+	if prefs != 5 {
+		t.Errorf("%d notification preferences, want 5", prefs)
+	}
+
+	// A second boot seeds nothing new and succeeds.
+	if err := seedDefaults(ctx, db, ""); err != nil {
+		t.Fatalf("reboot: %v", err)
+	}
+}

cmd/server/jobs_test.go

@@ -0,0 +1,62 @@
+package main
+
+import (
+	"context"
+	"io"
+	"log/slog"
+	"testing"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
+)
+
+// TestNewJobRunnerRunsNoop proves the runner run builds can execute a job:
+// a noop job enqueued before Start, as at boot, succeeds with its result.
+func TestNewJobRunnerRunsNoop(t *testing.T) {
+	ctx := context.Background()
+	db, err := openStore(ctx, t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := db.Close(); err != nil {
+			t.Error(err)
+		}
+	})
+	runner, kinds, err := newJobRunner(db, slog.New(slog.NewTextHandler(io.Discard, nil)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	id, err := kinds.builtins.Noop.Enqueue(ctx, jobs.NoopPayload{})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	jobsCtx, stopJobs := context.WithCancel(ctx)
+	if err := runner.Start(jobsCtx); err != nil {
+		stopJobs()
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		stopJobs()
+		runner.Wait()
+	})
+
+	deadline := time.Now().Add(5 * time.Second)
+	for {
+		job, err := runner.Get(ctx, id)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if job.Status == jobs.StatusSucceeded || job.Status == jobs.StatusFailed {
+			if job.Kind != jobs.KindNoop || job.Status != jobs.StatusSucceeded || string(job.Result) != `{"ok":true}` || job.Error != nil {
+				t.Fatalf("noop job = %+v (result %s), want succeeded with {\"ok\":true}", job, job.Result)
+			}
+			return
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("noop job never finished; last %+v", job)
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+}

cmd/server/main.go

@@ -13,8 +13,12 @@ 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/jobs"
 	"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"
@@ -24,6 +28,9 @@ import (
 // version is set at build time with -ldflags "-X main.version=<version>".
 var version = "dev"
 
+// jobWorkers is the number of background jobs run at once.
+const jobWorkers = 2
+
 func main() {
 	cfg, err := config.Load()
 	if err != nil {
@@ -31,7 +38,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,10 +63,47 @@ func run(cfg config.Config, logger *slog.Logger) error {
 		}
 	}()
 
-	router, err := server.NewRouter(logger, version, frontend.Assets())
+	if err := seedDefaults(ctx, db, cfg.DefaultTZ); err != nil {
+		return err
+	}
+	settings := household.NewSettingsService(db)
+	runner, _, err := newJobRunner(db, logger)
 	if err != nil {
 		return err
 	}
+
+	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, runner, frontend.Assets())
+	if err != nil {
+		return err
+	}
+
+	// Start fails the jobs a previous process left running before any
+	// worker runs. The workers stop, and are waited for, before the
+	// database closes.
+	jobsCtx, stopJobs := context.WithCancel(ctx)
+	defer func() {
+		stopJobs()
+		runner.Wait()
+	}()
+	if err := runner.Start(jobsCtx); err != nil {
+		return err
+	}
 	srv := &http.Server{
 		Addr:              cfg.HTTPAddr,
 		Handler:           router,
@@ -118,12 +162,65 @@ 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
+}
+
+// seedDefaults creates the household settings, AI settings and notification
+// preferences that do not exist yet. Existing rows are never changed.
+func seedDefaults(ctx context.Context, db *store.Store, defaultTZ string) error {
+	if err := seedSettings(ctx, db, defaultTZ); err != nil {
+		return err
+	}
+	if err := household.SeedAISettings(ctx, db); err != nil {
+		return err
+	}
+	return household.SeedNotificationPrefs(ctx, db)
+}
+
+// jobKinds enqueues every job kind the server runs.
+type jobKinds struct {
+	builtins *jobs.Builtins
+}
+
+// newJobRunner returns the job runner with every job kind registered, ready
+// to Start.
+func newJobRunner(db *store.Store, logger *slog.Logger) (*jobs.Runner, *jobKinds, error) {
+	runner, err := jobs.NewRunner(db, logger, jobWorkers)
+	if err != nil {
+		return nil, nil, err
+	}
+	kinds, err := registerJobKinds(runner)
+	if err != nil {
+		return nil, nil, err
+	}
+	return runner, kinds, nil
+}
+
+// registerJobKinds registers every job kind's handler on runner. Each
+// feature's job kinds are registered here.
+func registerJobKinds(runner *jobs.Runner) (*jobKinds, error) {
+	builtins, err := jobs.RegisterBuiltins(runner)
+	if err != nil {
+		return nil, err
+	}
+	return &jobKinds{builtins: builtins}, nil
+}
+
 // 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/jobs.sql.go

@@ -0,0 +1,166 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: jobs.sql
+
+package db
+
+import (
+	"context"
+	"database/sql"
+)
+
+const claimNextJob = `-- name: ClaimNextJob :one
+UPDATE jobs
+SET status = 'running', started_at = ?1, updated_at = ?1
+WHERE id = (SELECT id FROM jobs WHERE status = 'queued' ORDER BY id LIMIT 1)
+RETURNING id, kind, status, payload, result, error, started_at, finished_at, created_at, updated_at
+`
+
+// Marks the oldest queued job running and returns it. Returns sql.ErrNoRows
+// when no job is queued.
+func (q *Queries) ClaimNextJob(ctx context.Context, now sql.NullString) (Job, error) {
+	row := q.db.QueryRowContext(ctx, claimNextJob, now)
+	var i Job
+	err := row.Scan(
+		&i.ID,
+		&i.Kind,
+		&i.Status,
+		&i.Payload,
+		&i.Result,
+		&i.Error,
+		&i.StartedAt,
+		&i.FinishedAt,
+		&i.CreatedAt,
+		&i.UpdatedAt,
+	)
+	return i, err
+}
+
+const createJob = `-- name: CreateJob :exec
+INSERT INTO jobs (id, kind, status, payload, created_at, updated_at)
+VALUES (?, ?, 'queued', ?, ?, ?)
+`
+
+type CreateJobParams struct {
+	ID        string
+	Kind      string
+	Payload   string
+	CreatedAt string
+	UpdatedAt string
+}
+
+func (q *Queries) CreateJob(ctx context.Context, arg CreateJobParams) error {
+	_, err := q.db.ExecContext(ctx, createJob,
+		arg.ID,
+		arg.Kind,
+		arg.Payload,
+		arg.CreatedAt,
+		arg.UpdatedAt,
+	)
+	return err
+}
+
+const failJob = `-- name: FailJob :execrows
+UPDATE jobs
+SET status = 'failed', error = ?1, finished_at = ?2, updated_at = ?2
+WHERE id = ?3 AND status = 'running'
+`
+
+type FailJobParams struct {
+	Error sql.NullString
+	Now   sql.NullString
+	ID    string
+}
+
+func (q *Queries) FailJob(ctx context.Context, arg FailJobParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, failJob, arg.Error, arg.Now, arg.ID)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+const failRunningJobs = `-- name: FailRunningJobs :execrows
+UPDATE jobs
+SET status = 'failed', error = ?1, finished_at = ?2, updated_at = ?2
+WHERE status = 'running'
+`
+
+type FailRunningJobsParams struct {
+	Error sql.NullString
+	Now   sql.NullString
+}
+
+// Fails every job left running, at boot before any worker starts.
+func (q *Queries) FailRunningJobs(ctx context.Context, arg FailRunningJobsParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, failRunningJobs, arg.Error, arg.Now)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+const getJob = `-- name: GetJob :one
+SELECT id, kind, status, payload, result, error, started_at, finished_at, created_at, updated_at FROM jobs
+WHERE id = ?
+`
+
+func (q *Queries) GetJob(ctx context.Context, id string) (Job, error) {
+	row := q.db.QueryRowContext(ctx, getJob, id)
+	var i Job
+	err := row.Scan(
+		&i.ID,
+		&i.Kind,
+		&i.Status,
+		&i.Payload,
+		&i.Result,
+		&i.Error,
+		&i.StartedAt,
+		&i.FinishedAt,
+		&i.CreatedAt,
+		&i.UpdatedAt,
+	)
+	return i, err
+}
+
+const publishJobResult = `-- name: PublishJobResult :execrows
+UPDATE jobs
+SET result = ?, updated_at = ?
+WHERE id = ? AND status = 'running'
+`
+
+type PublishJobResultParams struct {
+	Result    sql.NullString
+	UpdatedAt string
+	ID        string
+}
+
+// Stores a partial result of a running job.
+func (q *Queries) PublishJobResult(ctx context.Context, arg PublishJobResultParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, publishJobResult, arg.Result, arg.UpdatedAt, arg.ID)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+const succeedJob = `-- name: SucceedJob :execrows
+UPDATE jobs
+SET status = 'succeeded', result = ?1, finished_at = ?2, updated_at = ?2
+WHERE id = ?3 AND status = 'running'
+`
+
+type SucceedJobParams struct {
+	Result sql.NullString
+	Now    sql.NullString
+	ID     string
+}
+
+func (q *Queries) SucceedJob(ctx context.Context, arg SucceedJobParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, succeedJob, arg.Result, arg.Now, arg.ID)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}

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/querier.go

@@ -6,17 +6,25 @@ package db
 
 import (
 	"context"
+	"database/sql"
 )
 
 type Querier interface {
 	// An unknown id returns sql.ErrNoRows.
 	ArchiveDinner(ctx context.Context, arg ArchiveDinnerParams) (Dinner, error)
+	// Marks the oldest queued job running and returns it. Returns sql.ErrNoRows
+	// when no job is queued.
+	ClaimNextJob(ctx context.Context, now sql.NullString) (Job, error)
 	CreateDinner(ctx context.Context, arg CreateDinnerParams) (Dinner, error)
+	CreateJob(ctx context.Context, arg CreateJobParams) error
 	CreatePhoto(ctx context.Context, arg CreatePhotoParams) (Photo, error)
 	CreateRecipeIngredient(ctx context.Context, arg CreateRecipeIngredientParams) error
 	CreateRecipeStep(ctx context.Context, arg CreateRecipeStepParams) error
 	DeleteRecipeIngredients(ctx context.Context, recipeID string) error
 	DeleteRecipeSteps(ctx context.Context, recipeID string) error
+	FailJob(ctx context.Context, arg FailJobParams) (int64, error)
+	// Fails every job left running, at boot before any worker starts.
+	FailRunningJobs(ctx context.Context, arg FailRunningJobsParams) (int64, error)
 	// Returns sql.ErrNoRows until the row exists.
 	GetAISettings(ctx context.Context) (AiSetting, error)
 	// Returns sql.ErrNoRows until the row exists.
@@ -26,6 +34,7 @@ type Querier interface {
 	GetHouseholdSettings(ctx context.Context) (HouseholdSetting, error)
 	// Returns sql.ErrNoRows until the row exists.
 	GetIntegrationsGoogle(ctx context.Context) (IntegrationsGoogle, error)
+	GetJob(ctx context.Context, id string) (Job, error)
 	// Finds stored image bytes by content hash. The schema does not make sha256
 	// unique, so the earliest-created (lowest id) match is returned.
 	GetPhotoBySHA256(ctx context.Context, sha256 string) (Photo, error)
@@ -36,8 +45,11 @@ type Querier interface {
 	ListDinnersByStatus(ctx context.Context, status string) ([]Dinner, error)
 	ListRecipeIngredients(ctx context.Context, recipeID string) ([]RecipeIngredient, error)
 	ListRecipeSteps(ctx context.Context, recipeID string) ([]RecipeStep, error)
+	// Stores a partial result of a running job.
+	PublishJobResult(ctx context.Context, arg PublishJobResultParams) (int64, error)
 	// An unknown id returns sql.ErrNoRows.
 	SetDinnerFavorite(ctx context.Context, arg SetDinnerFavoriteParams) (Dinner, error)
+	SucceedJob(ctx context.Context, arg SucceedJobParams) (int64, error)
 	// An unknown id returns sql.ErrNoRows.
 	UpdateDinner(ctx context.Context, arg UpdateDinnerParams) (Dinner, error)
 	// Creates the single row (id 1) or replaces every column except id and

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/defaults.go

@@ -0,0 +1,93 @@
+package household
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// DefaultPersonaPrompt is the default AI system prompt (CTXD PROMPTS.MD §4).
+// SeedAISettings stores it on first boot and the Admin reset restores it.
+const DefaultPersonaPrompt = `You are MealQuest, a dinner planning assistant for one household. Suggest dinners
+similar to their regular rotation, nudging them to try something a little new each
+week. Prefer weeknight-friendly recipes with common grocery-store ingredients.
+Flag crock pot meals and anything 30 minutes or less as "quick". Keep explanations
+short, warm and specific — mention the household's own regular dinners when you
+explain why something fits. Never suggest a dinner they already make or have
+declined.`
+
+// Seed values for the AI settings (CTXD CONTEXT.MD). The base URL and model
+// are empty until the household picks a provider preset; there is no key.
+const (
+	SeedAIProvider    = "anthropic"
+	SeedAIBaseURL     = ""
+	SeedAIModel       = ""
+	SeedAITemperature = 0.7
+)
+
+// seedNotificationPrefs are the notification preferences for a new
+// household, one per event: push for every event, chat only for the plan
+// and the shopping list.
+var seedNotificationPrefs = []struct {
+	Event      string
+	Push, Chat bool
+}{
+	{Event: "plan_ready", Push: true, Chat: true},
+	{Event: "list_ready", Push: true, Chat: true},
+	{Event: "day_of_reminder", Push: true, Chat: false},
+	{Event: "new_suggestions", Push: true, Chat: false},
+	{Event: "rotation_review", Push: true, Chat: false},
+}
+
+// SeedAISettings creates the AI settings row with the seed values and
+// DefaultPersonaPrompt if it does not exist. An existing row is never
+// changed.
+func SeedAISettings(ctx context.Context, st *store.Store) error {
+	return st.WithTx(ctx, func(tx *sql.Tx) error {
+		q := db.New(tx)
+		_, err := q.GetAISettings(ctx)
+		if err == nil {
+			return nil
+		}
+		if !errors.Is(err, sql.ErrNoRows) {
+			return fmt.Errorf("household: read AI settings: %w", err)
+		}
+		now := store.Now().String()
+		_, err = q.UpsertAISettings(ctx, db.UpsertAISettingsParams{
+			Provider:     SeedAIProvider,
+			BaseUrl:      SeedAIBaseURL,
+			Model:        SeedAIModel,
+			Temperature:  SeedAITemperature,
+			SystemPrompt: sql.NullString{String: DefaultPersonaPrompt, Valid: true},
+			CreatedAt:    now,
+			UpdatedAt:    now,
+		})
+		if err != nil {
+			return fmt.Errorf("household: seed AI settings: %w", err)
+		}
+		return nil
+	})
+}
+
+// SeedNotificationPrefs creates the seed notification preference row of
+// every event that has none. Existing rows are never changed.
+func SeedNotificationPrefs(ctx context.Context, st *store.Store) error {
+	return st.WithTx(ctx, func(tx *sql.Tx) error {
+		now := store.Now().String()
+		for _, p := range seedNotificationPrefs {
+			_, err := tx.ExecContext(ctx,
+				`INSERT INTO notification_prefs (event, push, chat, created_at, updated_at)
+				VALUES (?, ?, ?, ?, ?)
+				ON CONFLICT (event) DO NOTHING`,
+				p.Event, p.Push, p.Chat, now, now)
+			if err != nil {
+				return fmt.Errorf("household: seed notification preference %s: %w", p.Event, err)
+			}
+		}
+		return nil
+	})
+}

internal/household/defaults_test.go

@@ -0,0 +1,220 @@
+package household
+
+import (
+	"context"
+	"database/sql"
+	"testing"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// notificationPrefs returns the stored notification preferences by event as
+// [push, chat].
+func notificationPrefs(t *testing.T, st *store.Store) map[string][2]int64 {
+	t.Helper()
+	rows, err := st.Reader.QueryContext(context.Background(), `SELECT event, push, chat FROM notification_prefs`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer rows.Close()
+	got := make(map[string][2]int64)
+	for rows.Next() {
+		var event string
+		var push, chat int64
+		if err := rows.Scan(&event, &push, &chat); err != nil {
+			t.Fatal(err)
+		}
+		got[event] = [2]int64{push, chat}
+	}
+	if err := rows.Err(); err != nil {
+		t.Fatal(err)
+	}
+	return got
+}
+
+func TestSeedAISettingsCreatesRow(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	st := migratedStore(t, t.TempDir())
+
+	if err := SeedAISettings(ctx, st); err != nil {
+		t.Fatal(err)
+	}
+	got, err := db.New(st.Reader).GetAISettings(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := db.AiSetting{
+		ID:           1,
+		Provider:     "anthropic",
+		BaseUrl:      "",
+		Model:        "",
+		Temperature:  0.7,
+		SystemPrompt: sql.NullString{String: DefaultPersonaPrompt, Valid: true},
+		CreatedAt:    got.CreatedAt,
+		UpdatedAt:    got.UpdatedAt,
+	}
+	if got.ID != want.ID || got.Provider != want.Provider || got.BaseUrl != want.BaseUrl ||
+		got.Model != want.Model || got.Temperature != want.Temperature || got.SystemPrompt != want.SystemPrompt ||
+		got.ApiKeyCt != nil || got.ApiKeyLast4.Valid || got.KeyVerifiedAt.Valid {
+		t.Errorf("seeded AI 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 TestDefaultPersonaPrompt(t *testing.T) {
+	t.Parallel()
+	const want = "You are MealQuest, a dinner planning assistant for one household. Suggest dinners\n" +
+		"similar to their regular rotation, nudging them to try something a little new each\n" +
+		"week. Prefer weeknight-friendly recipes with common grocery-store ingredients.\n" +
+		"Flag crock pot meals and anything 30 minutes or less as \"quick\". Keep explanations\n" +
+		"short, warm and specific — mention the household's own regular dinners when you\n" +
+		"explain why something fits. Never suggest a dinner they already make or have\n" +
+		"declined."
+	if DefaultPersonaPrompt != want {
+		t.Errorf("DefaultPersonaPrompt = %q\nwant %q", DefaultPersonaPrompt, want)
+	}
+}
+
+func TestSeedAISettingsNeverOverwrites(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	dir := t.TempDir()
+
+	// First boot seeds; the household then configures a provider.
+	first := migratedStore(t, dir)
+	if err := SeedAISettings(ctx, first); err != nil {
+		t.Fatal(err)
+	}
+	seeded, err := db.New(first.Reader).GetAISettings(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	changed, err := db.New(first.Writer).UpsertAISettings(ctx, db.UpsertAISettingsParams{
+		Provider:      "ollama",
+		BaseUrl:       "http://ollama:11434",
+		Model:         "llama3",
+		Temperature:   0.2,
+		SystemPrompt:  sql.NullString{String: "Be brief.", Valid: true},
+		ApiKeyCt:      []byte{1, 2, 3},
+		ApiKeyLast4:   sql.NullString{String: "wxyz", Valid: true},
+		KeyVerifiedAt: sql.NullString{String: store.Now().String(), Valid: true},
+		CreatedAt:     seeded.CreatedAt,
+		UpdatedAt:     store.Now().String(),
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := first.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	// A later boot reopens the same database and seeds again.
+	st := migratedStore(t, dir)
+	if err := SeedAISettings(ctx, st); err != nil {
+		t.Fatalf("reboot: %v", err)
+	}
+	got, err := db.New(st.Reader).GetAISettings(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.Provider != changed.Provider || got.BaseUrl != changed.BaseUrl || got.Model != changed.Model ||
+		got.Temperature != changed.Temperature || got.SystemPrompt != changed.SystemPrompt ||
+		string(got.ApiKeyCt) != string(changed.ApiKeyCt) || got.ApiKeyLast4 != changed.ApiKeyLast4 ||
+		got.KeyVerifiedAt != changed.KeyVerifiedAt || got.CreatedAt != changed.CreatedAt || got.UpdatedAt != changed.UpdatedAt {
+		t.Errorf("reboot changed AI settings:\n got %+v\nwant %+v", got, changed)
+	}
+}
+
+func TestSeedNotificationPrefsCreatesRows(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	st := migratedStore(t, t.TempDir())
+
+	if err := SeedNotificationPrefs(ctx, st); err != nil {
+		t.Fatal(err)
+	}
+	want := map[string][2]int64{
+		"plan_ready":      {1, 1},
+		"list_ready":      {1, 1},
+		"day_of_reminder": {1, 0},
+		"new_suggestions": {1, 0},
+		"rotation_review": {1, 0},
+	}
+	got := notificationPrefs(t, st)
+	if len(got) != len(want) {
+		t.Errorf("seeded %d notification preferences, want %d: %v", len(got), len(want), got)
+	}
+	for event, w := range want {
+		if g, ok := got[event]; !ok || g != w {
+			t.Errorf("%s [push, chat] = %v (present %t), want %v", event, g, ok, w)
+		}
+	}
+
+	var created, updated string
+	err := st.Reader.QueryRowContext(ctx, `SELECT created_at, updated_at FROM notification_prefs WHERE event = 'plan_ready'`).Scan(&created, &updated)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var ts store.Timestamp
+	if err := ts.Scan(created); err != nil {
+		t.Errorf("created_at: %v", err)
+	}
+	if updated != created {
+		t.Errorf("updated_at = %q, want created_at %q", updated, created)
+	}
+}
+
+func TestSeedNotificationPrefsNeverOverwrites(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	dir := t.TempDir()
+
+	// First boot seeds; the household then changes two preferences, and one
+	// event's row goes missing.
+	first := migratedStore(t, dir)
+	if err := SeedNotificationPrefs(ctx, first); err != nil {
+		t.Fatal(err)
+	}
+	for _, stmt := range []string{
+		`UPDATE notification_prefs SET push = 0, chat = 0 WHERE event = 'plan_ready'`,
+		`UPDATE notification_prefs SET chat = 1 WHERE event = 'rotation_review'`,
+		`DELETE FROM notification_prefs WHERE event = 'new_suggestions'`,
+	} {
+		if _, err := first.Writer.ExecContext(ctx, stmt); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := first.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	// A later boot keeps the changed rows and seeds only the missing one.
+	st := migratedStore(t, dir)
+	if err := SeedNotificationPrefs(ctx, st); err != nil {
+		t.Fatalf("reboot: %v", err)
+	}
+	want := map[string][2]int64{
+		"plan_ready":      {0, 0},
+		"list_ready":      {1, 1},
+		"day_of_reminder": {1, 0},
+		"new_suggestions": {1, 0},
+		"rotation_review": {1, 1},
+	}
+	got := notificationPrefs(t, st)
+	if len(got) != len(want) {
+		t.Errorf("%d notification preferences after reboot, want %d: %v", len(got), len(want), got)
+	}
+	for event, w := range want {
+		if g, ok := got[event]; !ok || g != w {
+			t.Errorf("after reboot %s [push, chat] = %v (present %t), want %v", event, g, ok, w)
+		}
+	}
+}

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/jobs/builtin.go

@@ -0,0 +1,44 @@
+package jobs
+
+import (
+	"context"
+	"encoding/json"
+)
+
+// KindNoop is the framework's built-in job kind: it does no work and
+// succeeds with {"ok":true}. It is the runner's own trivial kind, as Feature
+// 09's trivial test skill is the harness's, and the startup and readiness
+// job: a noop job reaching succeeded proves the runner claims, runs and
+// records jobs.
+const KindNoop = "noop"
+
+// NoopPayload is the payload of a noop job.
+type NoopPayload struct{}
+
+// NoopResult is the result of a noop job.
+type NoopResult struct{}
+
+// PublicJSON returns {"ok":true}.
+func (NoopResult) PublicJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		OK bool `json:"ok"`
+	}{OK: true})
+}
+
+func runNoop(context.Context, NoopPayload, func(NoopResult) error) (NoopResult, error) {
+	return NoopResult{}, nil
+}
+
+// Builtins enqueues the framework's built-in job kinds.
+type Builtins struct {
+	Noop *Kind[NoopPayload]
+}
+
+// RegisterBuiltins registers the framework's built-in job kinds on r.
+func RegisterBuiltins(r *Runner) (*Builtins, error) {
+	noop, err := Register(r, KindNoop, runNoop)
+	if err != nil {
+		return nil, err
+	}
+	return &Builtins{Noop: noop}, nil
+}

internal/jobs/jobs.go

@@ -0,0 +1,410 @@
+// Package jobs runs long work in the background. A job is a row in the jobs
+// table: Enqueue inserts it queued, and a fixed pool of workers claims queued
+// jobs oldest first, so the table itself is the queue and a job enqueued
+// before a restart still runs after it.
+//
+// Each job kind has one handler, registered before Start. A handler takes a
+// typed payload and returns a result implementing Public; it may publish
+// partial results while it runs. The runner stores only what a result's
+// PublicJSON returns and, for a failed job, only a failure code: either a
+// *Failure code the kind declared at registration or one of the runner's own
+// codes. Handler error text, which may quote a URL, token or response body
+// from a dependency, is never stored, returned by the API or logged.
+package jobs
+
+import (
+	"bytes"
+	"context"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log/slog"
+	"regexp"
+	"sync"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// Status is the state of a job.
+type Status string
+
+// Job states. A job moves queued → running → succeeded or failed.
+const (
+	StatusQueued    Status = "queued"
+	StatusRunning   Status = "running"
+	StatusSucceeded Status = "succeeded"
+	StatusFailed    Status = "failed"
+)
+
+// Failure codes the runner stores itself. A kind cannot declare them.
+const (
+	// CodeInterrupted is the error of a job a previous process left running.
+	// It is fixed framework text, not a snake-case code, so no kind can
+	// declare it.
+	CodeInterrupted = "interrupted by restart"
+	// CodeInternal is the error of a job whose handler failed with anything
+	// but a *Failure with a code its kind declared, or whose payload or
+	// result could not be encoded. The underlying error is neither stored
+	// nor logged.
+	CodeInternal = "internal_error"
+	// CodeUnknownKind is the error of a job whose kind has no handler.
+	CodeUnknownKind = "unknown_kind"
+)
+
+// Claim retry backoff. A worker whose claim fails with a database error
+// retries after claimRetryMin, doubling up to claimRetryMax, so a job queued
+// when the error clears is claimed without waiting for a wake token.
+const (
+	claimRetryMin = 50 * time.Millisecond
+	claimRetryMax = 5 * time.Second
+)
+
+// codePattern is the form of every failure code: lower-case snake case.
+var codePattern = regexp.MustCompile(`^[a-z][a-z0-9_]{0,63}$`)
+
+// ErrNotFound is returned by Get for an unknown job id.
+var ErrNotFound = errors.New("jobs: job not found")
+
+// Failure is a handler error reporting a failure code the household may
+// see. Code must be one the job's kind declared at registration; the runner
+// stores it as the job's error. Any other handler error, including a Failure
+// with an undeclared code, is stored as CodeInternal.
+type Failure struct {
+	Code string
+}
+
+func (f *Failure) Error() string { return "jobs: failure " + f.Code }
+
+// Public is a job result. PublicJSON returns the JSON the runner stores and
+// GET /api/v1/jobs/{id} returns, so a result type states exactly which of its
+// data is public; nothing else of the value is ever encoded.
+type Public interface {
+	PublicJSON() ([]byte, error)
+}
+
+// Handler runs one job with its payload. It may call publish any number of
+// times with a partial result, which Get returns while the job runs; its
+// return value is the final result. ctx is cancelled when the runner stops.
+type Handler[P any, R Public] func(ctx context.Context, payload P, publish func(partial R) error) (R, error)
+
+// Job is a job as reported by GET /api/v1/jobs/{id}. Result is the latest
+// partial or final result, and is null until the handler publishes one.
+// Error is set only on a failed job.
+type Job struct {
+	ID     string          `json:"id"`
+	Kind   string          `json:"kind"`
+	Status Status          `json:"status"`
+	Result json.RawMessage `json:"result"`
+	Error  *string         `json:"error"`
+}
+
+// runFunc is a registered Handler with its payload and results as JSON. It
+// returns the failure code to store, or "" on success; the logged reason
+// never quotes an error.
+type runFunc func(ctx context.Context, payload string, publish func(json.RawMessage) error) (result json.RawMessage, code, reason string)
+
+// Runner owns the job handlers and the worker pool.
+type Runner struct {
+	st      *store.Store
+	logger  *slog.Logger
+	workers int
+	// wake holds up to one token per worker; Enqueue adds one so an idle
+	// worker looks for the new job.
+	wake chan struct{}
+	// claim claims the oldest queued job, marking it running at now.
+	claim func(ctx context.Context, now sql.NullString) (db.Job, error)
+
+	mu       sync.Mutex
+	handlers map[string]runFunc
+	started  bool
+
+	wg sync.WaitGroup
+}
+
+// NewRunner returns a runner over st with workers concurrent workers.
+func NewRunner(st *store.Store, logger *slog.Logger, workers int) (*Runner, error) {
+	if st == nil {
+		return nil, errors.New("jobs: nil store")
+	}
+	if logger == nil {
+		return nil, errors.New("jobs: nil logger")
+	}
+	if workers < 1 {
+		return nil, fmt.Errorf("jobs: %d workers, want at least 1", workers)
+	}
+	return &Runner{
+		st:       st,
+		logger:   logger,
+		workers:  workers,
+		wake:     make(chan struct{}, workers),
+		claim:    db.New(st.Writer).ClaimNextJob,
+		handlers: make(map[string]runFunc),
+	}, nil
+}
+
+// Kind enqueues jobs of one registered kind.
+type Kind[P any] struct {
+	r    *Runner
+	name string
+}
+
+// Register makes h the handler for kind and returns the Kind that enqueues
+// its jobs. failureCodes are the *Failure codes h may report. It must be
+// called before Start, once per kind.
+func Register[P any, R Public](r *Runner, kind string, h Handler[P, R], failureCodes ...string) (*Kind[P], error) {
+	if kind == "" {
+		return nil, errors.New("jobs: register: empty kind")
+	}
+	if h == nil {
+		return nil, fmt.Errorf("jobs: register %q: nil handler", kind)
+	}
+	declared := make(map[string]bool, len(failureCodes))
+	for _, code := range failureCodes {
+		if !codePattern.MatchString(code) {
+			return nil, fmt.Errorf("jobs: register %q: failure code %q is not lower-case snake case", kind, code)
+		}
+		if code == CodeInternal || code == CodeUnknownKind {
+			return nil, fmt.Errorf("jobs: register %q: failure code %q is reserved for the runner", kind, code)
+		}
+		declared[code] = true
+	}
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.started {
+		return nil, fmt.Errorf("jobs: register %q: runner already started", kind)
+	}
+	if _, ok := r.handlers[kind]; ok {
+		return nil, fmt.Errorf("jobs: register %q: kind already registered", kind)
+	}
+	r.handlers[kind] = func(ctx context.Context, payload string, publish func(json.RawMessage) error) (json.RawMessage, string, string) {
+		var p P
+		dec := json.NewDecoder(bytes.NewReader([]byte(payload)))
+		dec.DisallowUnknownFields()
+		if err := dec.Decode(&p); err != nil {
+			return nil, CodeInternal, "payload does not decode"
+		}
+		result, err := h(ctx, p, func(partial R) error {
+			data, err := publicJSON(partial)
+			if err != nil {
+				return err
+			}
+			return publish(data)
+		})
+		if err != nil {
+			var failure *Failure
+			if !errors.As(err, &failure) {
+				return nil, CodeInternal, "handler error"
+			}
+			if !declared[failure.Code] {
+				return nil, CodeInternal, "undeclared failure code"
+			}
+			return nil, failure.Code, "handler failure"
+		}
+		data, err := publicJSON(result)
+		if err != nil {
+			return nil, CodeInternal, "result does not encode"
+		}
+		return data, "", ""
+	}
+	return &Kind[P]{r: r, name: kind}, nil
+}
+
+// publicJSON returns v's PublicJSON, refusing anything that is not one JSON
+// value. Its error never quotes PublicJSON's error.
+func publicJSON(v Public) (json.RawMessage, error) {
+	data, err := v.PublicJSON()
+	if err != nil || !json.Valid(data) {
+		return nil, errors.New("jobs: result has no valid public JSON")
+	}
+	return data, nil
+}
+
+// Enqueue stores a queued job with payload and returns its id. A job
+// enqueued before Start waits for it.
+func (k *Kind[P]) Enqueue(ctx context.Context, payload P) (string, error) {
+	data, err := json.Marshal(payload)
+	if err != nil {
+		return "", fmt.Errorf("jobs: enqueue %s: encode payload: %w", k.name, err)
+	}
+	id := store.NewID()
+	now := store.Now().String()
+	if err := db.New(k.r.st.Writer).CreateJob(ctx, db.CreateJobParams{
+		ID:        id,
+		Kind:      k.name,
+		Payload:   string(data),
+		CreatedAt: now,
+		UpdatedAt: now,
+	}); err != nil {
+		return "", fmt.Errorf("jobs: enqueue %s: %w", k.name, err)
+	}
+	select {
+	case k.r.wake <- struct{}{}:
+	default: // every worker already has a token and will look again
+	}
+	return id, nil
+}
+
+// Start fails every job a previous process left running with
+// CodeInterrupted, then starts the workers. They stop when ctx is cancelled;
+// Wait waits for them. A job whose handler returns an error after ctx is
+// cancelled is left running, so the next Start fails it as interrupted.
+func (r *Runner) Start(ctx context.Context) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.started {
+		return errors.New("jobs: runner already started")
+	}
+	now := store.Now().String()
+	n, err := db.New(r.st.Writer).FailRunningJobs(ctx, db.FailRunningJobsParams{
+		Error: sql.NullString{String: CodeInterrupted, Valid: true},
+		Now:   sql.NullString{String: now, Valid: true},
+	})
+	if err != nil {
+		return fmt.Errorf("jobs: fail interrupted jobs: %w", err)
+	}
+	if n > 0 {
+		r.logger.WarnContext(ctx, "failed jobs interrupted by restart", "count", n)
+	}
+	r.started = true
+	for range r.workers {
+		r.wg.Add(1)
+		go r.work(ctx)
+	}
+	return nil
+}
+
+// Wait blocks until every worker has stopped.
+func (r *Runner) Wait() {
+	r.wg.Wait()
+}
+
+// Get returns the job with id, or ErrNotFound.
+func (r *Runner) Get(ctx context.Context, id string) (Job, error) {
+	row, err := db.New(r.st.Reader).GetJob(ctx, id)
+	if errors.Is(err, sql.ErrNoRows) {
+		return Job{}, ErrNotFound
+	}
+	if err != nil {
+		return Job{}, fmt.Errorf("jobs: read job: %w", err)
+	}
+	job := Job{ID: row.ID, Kind: row.Kind, Status: Status(row.Status)}
+	if row.Result.Valid {
+		job.Result = json.RawMessage(row.Result.String)
+	}
+	if row.Error.Valid {
+		job.Error = &row.Error.String
+	}
+	return job, nil
+}
+
+// work claims and runs queued jobs until ctx is cancelled, waiting for a
+// wake token whenever none is queued. A claim that fails with a database
+// error is retried with backoff rather than waiting for a token, so a job
+// already queued is not stranded by a transient error.
+func (r *Runner) work(ctx context.Context) {
+	defer r.wg.Done()
+	backoff := claimRetryMin
+	for ctx.Err() == nil {
+		job, err := r.claim(ctx, sql.NullString{String: store.Now().String(), Valid: true})
+		switch {
+		case err == nil:
+			backoff = claimRetryMin
+			r.run(ctx, job)
+			continue
+		case errors.Is(err, sql.ErrNoRows):
+			backoff = claimRetryMin
+			select {
+			case <-r.wake:
+			case <-ctx.Done():
+			}
+			continue
+		case ctx.Err() != nil:
+			return
+		}
+		r.logger.ErrorContext(ctx, "claim job failed; retrying", "reason", "database error", "retry_in", backoff)
+		timer := time.NewTimer(backoff)
+		select {
+		case <-timer.C:
+		case <-ctx.Done():
+			timer.Stop()
+		}
+		backoff = min(2*backoff, claimRetryMax)
+	}
+}
+
+// run runs a claimed job to completion. The final write is made even when
+// ctx has been cancelled, so a handler that finishes during shutdown is
+// recorded.
+func (r *Runner) run(ctx context.Context, job db.Job) {
+	write := context.WithoutCancel(ctx)
+	logger := r.logger.With("job_id", job.ID, "kind", job.Kind)
+	q := db.New(r.st.Writer)
+
+	h, ok := r.handlers[job.Kind] // read-only once started
+	if !ok {
+		logger.ErrorContext(ctx, "job failed", "code", CodeUnknownKind, "reason", "no handler registered for the kind")
+		r.fail(write, logger, job.ID, CodeUnknownKind)
+		return
+	}
+
+	publish := func(partial json.RawMessage) error {
+		n, err := q.PublishJobResult(ctx, db.PublishJobResultParams{
+			Result:    sql.NullString{String: string(partial), Valid: true},
+			UpdatedAt: store.Now().String(),
+			ID:        job.ID,
+		})
+		if err != nil {
+			return fmt.Errorf("jobs: publish result: %w", err)
+		}
+		if n != 1 {
+			return fmt.Errorf("jobs: publish result: job %s is not running", job.ID)
+		}
+		return nil
+	}
+
+	result, code, reason := h(ctx, job.Payload, publish)
+	if code != "" {
+		if ctx.Err() != nil {
+			logger.WarnContext(write, "job interrupted by shutdown; it fails at the next start")
+			return
+		}
+		level := slog.LevelInfo
+		if code == CodeInternal {
+			level = slog.LevelError
+		}
+		logger.Log(ctx, level, "job failed", "code", code, "reason", reason)
+		r.fail(write, logger, job.ID, code)
+		return
+	}
+
+	n, err := q.SucceedJob(write, db.SucceedJobParams{
+		Result: sql.NullString{String: string(result), Valid: true},
+		Now:    sql.NullString{String: store.Now().String(), Valid: true},
+		ID:     job.ID,
+	})
+	if err == nil && n != 1 {
+		err = errors.New("job is not running")
+	}
+	if err != nil {
+		logger.ErrorContext(write, "record job success", "error", err)
+	}
+}
+
+// fail records the job as failed with code. The record errors it logs come
+// from the database, never from a handler.
+func (r *Runner) fail(ctx context.Context, logger *slog.Logger, id, code string) {
+	n, err := db.New(r.st.Writer).FailJob(ctx, db.FailJobParams{
+		Error: sql.NullString{String: code, Valid: true},
+		Now:   sql.NullString{String: store.Now().String(), Valid: true},
+		ID:    id,
+	})
+	if err == nil && n != 1 {
+		err = errors.New("job is not running")
+	}
+	if err != nil {
+		logger.ErrorContext(ctx, "record job failure", "error", err)
+	}
+}

internal/jobs/jobs_test.go

@@ -0,0 +1,570 @@
+package jobs
+
+import (
+	"bytes"
+	"context"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
+)
+
+// sentinelSecret stands in for a credential a handler holds while it runs.
+const sentinelSecret = "sk-sentinel-5f2c9a"
+
+type countPayload struct {
+	Steps int `json:"steps"`
+}
+
+type countResult struct {
+	Done int `json:"done"`
+}
+
+func (c countResult) PublicJSON() ([]byte, error) { return json.Marshal(c) }
+
+func migratedStore(t *testing.T) *store.Store {
+	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)
+	}
+	return st
+}
+
+func newRunner(t *testing.T, st *store.Store, workers int) *Runner {
+	t.Helper()
+	return newRunnerLogging(t, st, workers, io.Discard)
+}
+
+func newRunnerLogging(t *testing.T, st *store.Store, workers int, w io.Writer) *Runner {
+	t.Helper()
+	r, err := NewRunner(st, slog.New(slog.NewTextHandler(w, nil)), workers)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return r
+}
+
+// logBuffer collects log output written by concurrent workers.
+type logBuffer struct {
+	mu  sync.Mutex
+	buf bytes.Buffer
+}
+
+func (b *logBuffer) Write(p []byte) (int, error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.buf.Write(p)
+}
+
+func (b *logBuffer) String() string {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.buf.String()
+}
+
+// start starts r and stops it when the test ends. The returned function
+// stops it early and waits for its workers.
+func start(t *testing.T, r *Runner) (stop func()) {
+	t.Helper()
+	ctx, cancel := context.WithCancel(context.Background())
+	if err := r.Start(ctx); err != nil {
+		cancel()
+		t.Fatal(err)
+	}
+	stop = func() {
+		cancel()
+		r.Wait()
+	}
+	t.Cleanup(stop)
+	return stop
+}
+
+func register[P any, R Public](t *testing.T, r *Runner, kind string, h Handler[P, R], failureCodes ...string) *Kind[P] {
+	t.Helper()
+	k, err := Register(r, kind, h, failureCodes...)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return k
+}
+
+func enqueue[P any](t *testing.T, k *Kind[P], payload P) string {
+	t.Helper()
+	id, err := k.Enqueue(context.Background(), payload)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return id
+}
+
+// waitFor polls Get until done accepts the job, failing after five seconds.
+func waitFor(t *testing.T, r *Runner, id string, done func(Job) bool) Job {
+	t.Helper()
+	deadline := time.Now().Add(5 * time.Second)
+	for {
+		job, err := r.Get(context.Background(), id)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if done(job) {
+			return job
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("job %s never reached the expected state; last %+v (result %s)", id, job, job.Result)
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+}
+
+func finished(j Job) bool { return j.Status == StatusSucceeded || j.Status == StatusFailed }
+
+// rawRow returns every column of the job's row joined, for leak checks.
+func rawRow(t *testing.T, st *store.Store, id string) string {
+	t.Helper()
+	var cols [10]any
+	ptrs := make([]any, len(cols))
+	for i := range cols {
+		ptrs[i] = &cols[i]
+	}
+	if err := st.Reader.QueryRow("SELECT * FROM jobs WHERE id = ?", id).Scan(ptrs...); err != nil {
+		t.Fatal(err)
+	}
+	return fmt.Sprint(cols[:]...)
+}
+
+func TestJobSucceeds(t *testing.T) {
+	t.Parallel()
+	st := migratedStore(t)
+	r := newRunner(t, st, 2)
+	count := register(t, r, "count", func(_ context.Context, p countPayload, _ func(countResult) error) (countResult, error) {
+		return countResult{Done: p.Steps}, nil
+	})
+	start(t, r)
+
+	id := enqueue(t, count, countPayload{Steps: 3})
+	job := waitFor(t, r, id, finished)
+	if job.ID != id || job.Kind != "count" || job.Status != StatusSucceeded || job.Error != nil {
+		t.Fatalf("job = %+v, want succeeded count job %s with no error", job, id)
+	}
+	if string(job.Result) != `{"done":3}` {
+		t.Errorf("result = %s, want {\"done\":3}", job.Result)
+	}
+
+	var startedAt, finishedAt, createdAt, updatedAt, payload string
+	if err := st.Reader.QueryRow("SELECT started_at, finished_at, created_at, updated_at, payload FROM jobs WHERE id = ?", id).
+		Scan(&startedAt, &finishedAt, &createdAt, &updatedAt, &payload); err != nil {
+		t.Fatal(err)
+	}
+	for name, v := range map[string]string{"started_at": startedAt, "finished_at": finishedAt, "created_at": createdAt, "updated_at": updatedAt} {
+		var ts store.Timestamp
+		if err := ts.Scan(v); err != nil {
+			t.Errorf("%s = %q: %v", name, v, err)
+		}
+	}
+	if payload != `{"steps":3}` {
+		t.Errorf("payload = %s, want {\"steps\":3}", payload)
+	}
+}
+
+func TestJobFailsWithFailureCode(t *testing.T) {
+	t.Parallel()
+	st := migratedStore(t)
+	r := newRunner(t, st, 1)
+	k := register(t, r, "suggest", func(context.Context, countPayload, func(countResult) error) (countResult, error) {
+		return countResult{}, fmt.Errorf("suggest: %w", &Failure{Code: "no_regulars"})
+	}, "no_regulars")
+	start(t, r)
+
+	job := waitFor(t, r, enqueue(t, k, countPayload{}), finished)
+	if job.Status != StatusFailed || job.Error == nil || *job.Error != "no_regulars" {
+		t.Fatalf("job = %+v, want failed with code no_regulars", job)
+	}
+	if job.Result != nil {
+		t.Errorf("result = %s, want none", job.Result)
+	}
+	var stored string
+	if err := st.Reader.QueryRow("SELECT error FROM jobs WHERE id = ?", job.ID).Scan(&stored); err != nil {
+		t.Fatal(err)
+	}
+	if stored != "no_regulars" {
+		t.Errorf("stored error = %q, want only the code", stored)
+	}
+}
+
+func TestUndeclaredFailureCodeIsInternal(t *testing.T) {
+	t.Parallel()
+	r := newRunner(t, migratedStore(t), 1)
+	k := register(t, r, "suggest", func(context.Context, countPayload, func(countResult) error) (countResult, error) {
+		return countResult{}, &Failure{Code: "not_declared"}
+	}, "no_regulars")
+	start(t, r)
+
+	job := waitFor(t, r, enqueue(t, k, countPayload{}), finished)
+	if job.Status != StatusFailed || job.Error == nil || *job.Error != CodeInternal {
+		t.Fatalf("job = %+v, want failed with %q", job, CodeInternal)
+	}
+}
+
+// credential holds a secret the way config.Secret does: unexported, so
+// encoding/json cannot see it.
+type credential struct{ value string }
+
+func (credential) String() string { return "[REDACTED]" }
+
+// leakyResult holds a secret in exported and unexported fields; only
+// Dinners is public.
+type leakyResult struct {
+	Dinners []string
+	Key     credential
+	Token   string
+	apiKey  string
+}
+
+func (l leakyResult) PublicJSON() ([]byte, error) {
+	return json.Marshal(struct {
+		Dinners []string `json:"dinners"`
+	}{l.Dinners})
+}
+
+// badResult has no valid public JSON; its encoding error quotes a secret.
+type badResult struct{}
+
+func (badResult) PublicJSON() ([]byte, error) {
+	return nil, fmt.Errorf("encode with key %s", sentinelSecret)
+}
+
+// TestSecretsNeverStoredOrLogged proves a handler holding a secret cannot
+// surface it in the jobs row, Get's result or the log through its result,
+// partial results, *Failure, error text or result encoding error.
+func TestSecretsNeverStoredOrLogged(t *testing.T) {
+	t.Parallel()
+	st := migratedStore(t)
+	var logs logBuffer
+	r := newRunnerLogging(t, st, 1, &logs)
+	secretResult := leakyResult{Dinners: []string{"Tacos"}, Key: credential{sentinelSecret}, Token: sentinelSecret, apiKey: sentinelSecret}
+	typed := register(t, r, "typed", func(_ context.Context, _ countPayload, publish func(leakyResult) error) (leakyResult, error) {
+		if err := publish(secretResult); err != nil {
+			return leakyResult{}, err
+		}
+		return secretResult, nil
+	})
+	leakyError := register(t, r, "leaky-error", func(context.Context, countPayload, func(leakyResult) error) (leakyResult, error) {
+		return leakyResult{}, fmt.Errorf("GET https://api.example.com/v1?key=%s: 401 %s", sentinelSecret, sentinelSecret)
+	})
+	leakyFailure := register(t, r, "leaky-failure", func(context.Context, countPayload, func(leakyResult) error) (leakyResult, error) {
+		return leakyResult{}, &Failure{Code: sentinelSecret}
+	}, "quota_exceeded")
+	failure := register(t, r, "failure", func(context.Context, countPayload, func(leakyResult) error) (leakyResult, error) {
+		return leakyResult{}, fmt.Errorf("call with key %s: %w", sentinelSecret, &Failure{Code: "quota_exceeded"})
+	}, "quota_exceeded")
+	badEncoding := register(t, r, "bad-encoding", func(context.Context, countPayload, func(badResult) error) (badResult, error) {
+		return badResult{}, nil
+	})
+	stop := start(t, r)
+
+	cases := []struct {
+		kind       *Kind[countPayload]
+		wantStatus Status
+		wantResult string
+		wantError  string
+	}{
+		{typed, StatusSucceeded, `{"dinners":["Tacos"]}`, ""},
+		{leakyError, StatusFailed, "", CodeInternal},
+		{leakyFailure, StatusFailed, "", CodeInternal},
+		{failure, StatusFailed, "", "quota_exceeded"},
+		{badEncoding, StatusFailed, "", CodeInternal},
+	}
+	var ids []string
+	for _, c := range cases {
+		job := waitFor(t, r, enqueue(t, c.kind, countPayload{}), finished)
+		ids = append(ids, job.ID)
+		gotError := ""
+		if job.Error != nil {
+			gotError = *job.Error
+		}
+		if job.Status != c.wantStatus || string(job.Result) != c.wantResult || gotError != c.wantError {
+			t.Errorf("%s job = %+v (result %s), want %s with result %q and error %q", job.Kind, job, job.Result, c.wantStatus, c.wantResult, c.wantError)
+		}
+		body, err := json.Marshal(job)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if strings.Contains(string(body), sentinelSecret) {
+			t.Errorf("%s job as served contains the secret: %s", job.Kind, body)
+		}
+	}
+	stop()
+	for _, id := range ids {
+		if row := rawRow(t, st, id); strings.Contains(row, sentinelSecret) {
+			t.Errorf("job %s row contains the secret: %s", id, row)
+		}
+	}
+	if strings.Contains(logs.String(), sentinelSecret) {
+		t.Errorf("log contains the secret:\n%s", logs.String())
+	}
+	if !strings.Contains(logs.String(), "code="+CodeInternal) {
+		t.Errorf("log does not record the internal_error code:\n%s", logs.String())
+	}
+}
+
+func TestProgressiveResultsVisibleMidRun(t *testing.T) {
+	t.Parallel()
+	r := newRunner(t, migratedStore(t), 1)
+	release := make(chan struct{})
+	k := register(t, r, "draft", func(ctx context.Context, p countPayload, publish func(countResult) error) (countResult, error) {
+		for i := 1; i < p.Steps; i++ {
+			if err := publish(countResult{Done: i}); err != nil {
+				return countResult{}, err
+			}
+			select {
+			case <-release:
+			case <-ctx.Done():
+				return countResult{}, ctx.Err()
+			}
+		}
+		return countResult{Done: p.Steps}, nil
+	})
+	start(t, r)
+
+	id := enqueue(t, k, countPayload{Steps: 3})
+	for step := 1; step < 3; step++ {
+		want := fmt.Sprintf(`{"done":%d}`, step)
+		job := waitFor(t, r, id, func(j Job) bool { return string(j.Result) == want })
+		if job.Status != StatusRunning || job.Error != nil {
+			t.Fatalf("mid-run job = %+v, want running with no error", job)
+		}
+		release <- struct{}{}
+	}
+	job := waitFor(t, r, id, finished)
+	if job.Status != StatusSucceeded || string(job.Result) != `{"done":3}` {
+		t.Fatalf("job = %+v (result %s), want succeeded with {\"done\":3}", job, job.Result)
+	}
+}
+
+func TestRestartFailsInterruptedJobsAndRunsQueuedOnes(t *testing.T) {
+	t.Parallel()
+	st := migratedStore(t)
+
+	first := newRunner(t, st, 1)
+	started := make(chan struct{})
+	k := register(t, first, "slow", func(ctx context.Context, _ countPayload, publish func(countResult) error) (countResult, error) {
+		if err := publish(countResult{Done: 1}); err != nil {
+			return countResult{}, err
+		}
+		close(started)
+		<-ctx.Done()
+		return countResult{}, ctx.Err()
+	})
+	stop := start(t, first)
+	interrupted := enqueue(t, k, countPayload{})
+	<-started
+	waiting := enqueue(t, k, countPayload{}) // the only worker is busy
+	stop()
+
+	if job := waitFor(t, first, interrupted, func(Job) bool { return true }); job.Status != StatusRunning {
+		t.Fatalf("after shutdown job = %+v, want left running", job)
+	}
+
+	second := newRunner(t, st, 1)
+	register(t, second, "slow", func(context.Context, countPayload, func(countResult) error) (countResult, error) {
+		return countResult{Done: 9}, nil
+	})
+	start(t, second)
+
+	job := waitFor(t, second, interrupted, finished)
+	if job.Status != StatusFailed || job.Error == nil || *job.Error != "interrupted by restart" {
+		t.Errorf("interrupted job = %+v, want failed with %q", job, "interrupted by restart")
+	}
+	if string(job.Result) != `{"done":1}` {
+		t.Errorf("interrupted job result = %s, want the last partial result kept", job.Result)
+	}
+	if job := waitFor(t, second, waiting, finished); job.Status != StatusSucceeded {
+		t.Errorf("queued job = %+v, want run by the new runner", job)
+	}
+}
+
+func TestWorkerPoolIsBounded(t *testing.T) {
+	t.Parallel()
+	r := newRunner(t, migratedStore(t), 2)
+	var running, peak atomic.Int32
+	release := make(chan struct{})
+	k := register(t, r, "busy", func(context.Context, countPayload, func(countResult) error) (countResult, error) {
+		n := running.Add(1)
+		for {
+			p := peak.Load()
+			if n <= p || peak.CompareAndSwap(p, n) {
+				break
+			}
+		}
+		<-release
+		running.Add(-1)
+		return countResult{}, nil
+	})
+	start(t, r)
+
+	ids := make([]string, 5)
+	for i := range ids {
+		ids[i] = enqueue(t, k, countPayload{})
+	}
+	deadline := time.Now().Add(5 * time.Second)
+	for running.Load() < 2 {
+		if time.Now().After(deadline) {
+			t.Fatal("two workers never ran at once")
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	close(release)
+	for _, id := range ids {
+		if job := waitFor(t, r, id, finished); job.Status != StatusSucceeded {
+			t.Errorf("job = %+v, want succeeded", job)
+		}
+	}
+	if got := peak.Load(); got != 2 {
+		t.Errorf("peak concurrent jobs = %d, want 2", got)
+	}
+}
+
+func TestJobWithoutHandlerFails(t *testing.T) {
+	t.Parallel()
+	st := migratedStore(t)
+	old := newRunner(t, st, 1)
+	k := register(t, old, "retired", func(context.Context, countPayload, func(countResult) error) (countResult, error) {
+		return countResult{}, nil
+	})
+	id := enqueue(t, k, countPayload{}) // never started
+
+	r := newRunner(t, st, 1)
+	start(t, r)
+	job := waitFor(t, r, id, finished)
+	if job.Status != StatusFailed || job.Error == nil || *job.Error != CodeUnknownKind {
+		t.Errorf("job = %+v, want failed for a missing handler", job)
+	}
+}
+
+func TestGetUnknownID(t *testing.T) {
+	t.Parallel()
+	r := newRunner(t, migratedStore(t), 1)
+	if _, err := r.Get(context.Background(), store.NewID()); !errors.Is(err, ErrNotFound) {
+		t.Errorf("Get unknown id error = %v, want ErrNotFound", err)
+	}
+}
+
+func TestRegisterRefusesBadRegistrations(t *testing.T) {
+	t.Parallel()
+	r := newRunner(t, migratedStore(t), 1)
+	h := func(context.Context, countPayload, func(countResult) error) (countResult, error) {
+		return countResult{}, nil
+	}
+	register(t, r, "count", h)
+
+	if _, err := Register(r, "count", h); err == nil {
+		t.Error("duplicate kind registered")
+	}
+	if _, err := Register(r, "", h); err == nil {
+		t.Error("empty kind registered")
+	}
+	if _, err := Register[countPayload, countResult](r, "nil", nil); err == nil {
+		t.Error("nil handler registered")
+	}
+	for _, code := range []string{"", "Bad Code", "sk-sentinel", CodeInternal, CodeInterrupted, CodeUnknownKind} {
+		if _, err := Register(r, "code", h, code); err == nil {
+			t.Errorf("failure code %q accepted", code)
+		}
+	}
+	start(t, r)
+	if _, err := Register(r, "late", h); err == nil {
+		t.Error("kind registered after Start")
+	}
+	if err := r.Start(context.Background()); err == nil {
+		t.Error("second Start succeeded")
+	}
+}
+
+func TestNewRunnerRefusesBadConfig(t *testing.T) {
+	t.Parallel()
+	st := migratedStore(t)
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	if _, err := NewRunner(st, logger, 0); err == nil {
+		t.Error("zero workers accepted")
+	}
+	if _, err := NewRunner(nil, logger, 1); err == nil {
+		t.Error("nil store accepted")
+	}
+	if _, err := NewRunner(st, nil, 1); err == nil {
+		t.Error("nil logger accepted")
+	}
+}
+
+func TestNoopSucceeds(t *testing.T) {
+	t.Parallel()
+	r := newRunner(t, migratedStore(t), 1)
+	builtins, err := RegisterBuiltins(r)
+	if err != nil {
+		t.Fatal(err)
+	}
+	start(t, r)
+
+	job := waitFor(t, r, enqueue(t, builtins.Noop, NoopPayload{}), finished)
+	if job.Kind != KindNoop || job.Status != StatusSucceeded || string(job.Result) != `{"ok":true}` || job.Error != nil {
+		t.Errorf("noop job = %+v (result %s), want succeeded with {\"ok\":true}", job, job.Result)
+	}
+}
+
+func TestClaimErrorIsRetried(t *testing.T) {
+	st := migratedStore(t)
+	logs := &logBuffer{}
+	r := newRunnerLogging(t, st, 1, logs)
+	k := register(t, r, "count", func(ctx context.Context, p countPayload, publish func(countResult) error) (countResult, error) {
+		return countResult{Done: p.Steps}, nil
+	})
+	id := enqueue(t, k, countPayload{Steps: 3})
+	// Drop the wake token, as for a job queued before a restart, so only
+	// the retry can find the job.
+	<-r.wake
+
+	var claims atomic.Int32
+	claim := r.claim
+	r.claim = func(ctx context.Context, now sql.NullString) (db.Job, error) {
+		if claims.Add(1) == 1 {
+			return db.Job{}, errors.New("database is locked " + sentinelSecret)
+		}
+		return claim(ctx, now)
+	}
+	start(t, r)
+
+	job := waitFor(t, r, id, finished)
+	if job.Status != StatusSucceeded || string(job.Result) != `{"done":3}` {
+		t.Fatalf("job = %+v (result %s), want succeeded with {\"done\":3}", job, job.Result)
+	}
+	if n := claims.Load(); n < 2 {
+		t.Fatalf("claims = %d, want a retry after the error", n)
+	}
+	out := logs.String()
+	if !strings.Contains(out, "claim job failed; retrying") {
+		t.Fatalf("claim error not logged: %s", out)
+	}
+	if strings.Contains(out, sentinelSecret) {
+		t.Fatalf("claim error text logged: %s", out)
+	}
+}

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/jobs.go

@@ -0,0 +1,29 @@
+package server
+
+import (
+	"errors"
+	"log/slog"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
+)
+
+// getJob serves GET /api/v1/jobs/{id}: the job's id, kind, status, latest
+// result and error.
+func getJob(logger *slog.Logger, runner *jobs.Runner) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		job, err := runner.Get(r.Context(), chi.URLParam(r, "id"))
+		if errors.Is(err, jobs.ErrNotFound) {
+			writeError(w, r, logger, http.StatusNotFound, "not_found", "job not found")
+			return
+		}
+		if err != nil {
+			logger.ErrorContext(r.Context(), "get job", "error", err)
+			writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, job)
+	}
+}

internal/server/jobs_test.go

@@ -0,0 +1,153 @@
+package server
+
+import (
+	"context"
+	"encoding/json"
+	"maps"
+	"net/http"
+	"net/http/httptest"
+	"slices"
+	"testing"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+type draftPayload struct{}
+
+type draftResult struct {
+	Days int `json:"days"`
+}
+
+func (d draftResult) PublicJSON() ([]byte, error) { return json.Marshal(d) }
+
+// startedRunner registers a "draft" kind that publishes {"days":1}, waits
+// for release and returns {"days":7}, or fails with a *jobs.Failure when
+// fail is closed first. It starts the runner and stops it when the test ends.
+func startedRunner(t *testing.T, release, fail <-chan struct{}) (*jobs.Runner, *jobs.Kind[draftPayload]) {
+	t.Helper()
+	runner := newTestRunner(t)
+	kind, err := jobs.Register(runner, "draft", func(ctx context.Context, _ draftPayload, publish func(draftResult) error) (draftResult, error) {
+		if err := publish(draftResult{Days: 1}); err != nil {
+			return draftResult{}, err
+		}
+		select {
+		case <-release:
+			return draftResult{Days: 7}, nil
+		case <-fail:
+			return draftResult{}, &jobs.Failure{Code: "no_regulars"}
+		case <-ctx.Done():
+			return draftResult{}, ctx.Err()
+		}
+	}, "no_regulars")
+	if err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	if err := runner.Start(ctx); err != nil {
+		cancel()
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		cancel()
+		runner.Wait()
+	})
+	return runner, kind
+}
+
+// pollJob GETs the job until want accepts the body, failing after five
+// seconds.
+func pollJob(t *testing.T, h http.Handler, id string, want func(map[string]any) bool) map[string]any {
+	t.Helper()
+	deadline := time.Now().Add(5 * time.Second)
+	for {
+		rec, body := serve(t, h, signedIn(http.MethodGet, "/api/v1/jobs/"+id, nil))
+		if rec.Code != http.StatusOK {
+			t.Fatalf("status = %d, want 200: %s", rec.Code, rec.Body)
+		}
+		if want(body) {
+			if keys := slices.Sorted(maps.Keys(body)); !slices.Equal(keys, []string{"error", "id", "kind", "result", "status"}) {
+				t.Errorf("body fields = %v, want id, kind, status, result, error", keys)
+			}
+			return body
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("job %s never reached the expected state; last %v", id, body)
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+}
+
+func resultDays(body map[string]any) float64 {
+	result, _ := body["result"].(map[string]any)
+	days, _ := result["days"].(float64)
+	return days
+}
+
+func TestGetJobShowsProgressThenResult(t *testing.T) {
+	t.Parallel()
+	release := make(chan struct{})
+	runner, kind := startedRunner(t, release, nil)
+	router := newTestRouterWith(t, "dev", newTestSettings(t), runner)
+	id, err := kind.Enqueue(context.Background(), draftPayload{})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	mid := pollJob(t, router, id, func(b map[string]any) bool { return resultDays(b) == 1 })
+	if mid["id"] != id || mid["kind"] != "draft" || mid["status"] != "running" || mid["error"] != nil {
+		t.Errorf("mid-run body = %v, want running draft job %s with no error", mid, id)
+	}
+
+	close(release)
+	done := pollJob(t, router, id, func(b map[string]any) bool { return b["status"] == "succeeded" })
+	if resultDays(done) != 7 || done["error"] != nil {
+		t.Errorf("finished body = %v, want result {\"days\":7} and no error", done)
+	}
+}
+
+func TestGetJobShowsFailure(t *testing.T) {
+	t.Parallel()
+	fail := make(chan struct{})
+	close(fail)
+	runner, kind := startedRunner(t, nil, fail)
+	router := newTestRouterWith(t, "dev", newTestSettings(t), runner)
+	id, err := kind.Enqueue(context.Background(), draftPayload{})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	body := pollJob(t, router, id, func(b map[string]any) bool { return b["status"] == "failed" })
+	if body["error"] != "no_regulars" {
+		t.Errorf("error = %v, want the Failure code", body["error"])
+	}
+}
+
+func TestGetJobUnknownIDIsNotFound(t *testing.T) {
+	t.Parallel()
+	router := newTestRouter(t, "dev")
+
+	rec, _ := serve(t, router, signedIn(http.MethodGet, "/api/v1/jobs/"+store.NewID(), nil))
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("status = %d, want 404", rec.Code)
+	}
+	var body errorBody
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatal(err)
+	}
+	if want := (errorBody{Error: apiError{Code: "not_found", Message: "job not found"}}); body != want {
+		t.Errorf("body = %+v, want %+v", body, want)
+	}
+}
+
+func TestGetJobRequiresSession(t *testing.T) {
+	t.Parallel()
+	router := newTestRouter(t, "dev")
+
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/api/v1/jobs/"+store.NewID(), nil))
+	if rec.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d, want 401", rec.Code)
+	}
+}

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),
+		newTestRunner(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),
+		newTestRunner(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,43 @@ 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"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
 )
 
 // 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; runner serves
+// /api/v1/jobs/{id}; 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, runner *jobs.Runner, assets fs.FS) (http.Handler, error) {
+	if settings == nil {
+		return nil, errors.New("server: nil household settings service")
+	}
+	if runner == nil {
+		return nil, errors.New("server: nil job runner")
+	}
 	notFound := apiErrorHandler(logger, http.StatusNotFound, "not_found", "not found")
 	methodNotAllowed := apiErrorHandler(logger, http.StatusMethodNotAllowed, "method_not_allowed", "method not allowed")
 
@@ -28,16 +49,34 @@ 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))
+	apiV1.Get("/jobs/{id}", getJob(logger, runner))
 	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 +94,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,13 @@ 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/jobs"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
 )
 
 const (
@@ -19,19 +27,109 @@ const (
 )
 
 func newTestRouter(t *testing.T, version string) http.Handler {
+	t.Helper()
+	return newTestRouterWith(t, version, newTestSettings(t), newTestRunner(t))
+}
+
+func newTestRouterWith(t *testing.T, version string, settings *household.SettingsService, runner *jobs.Runner) 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, runner, 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)
+	}
+}
+
+// newTestStore returns a migrated temp database, closed when the test ends.
+func newTestStore(t *testing.T) *store.Store {
+	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)
+	}
+	return st
+}
+
+// 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()
+	st := newTestStore(t)
+	if err := household.SeedSettings(context.Background(), st, "America/New_York"); err != nil {
+		t.Fatal(err)
+	}
+	return household.NewSettingsService(st)
+}
+
+// newTestRunner returns an unstarted job runner over a migrated temp
+// database.
+func newTestRunner(t *testing.T) *jobs.Runner {
+	t.Helper()
+	runner, err := jobs.NewRunner(newTestStore(t), slog.New(slog.NewTextHandler(io.Discard, nil)), 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return runner
+}
+
+func TestNewRouterRequiresSettings(t *testing.T) {
+	t.Parallel()
+
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, nil, newTestRunner(t), fstest.MapFS{"index.html": {}}); err == nil {
+		t.Fatal("NewRouter accepted a nil settings service")
+	}
+}
+
+func TestNewRouterRequiresJobRunner(t *testing.T) {
+	t.Parallel()
+
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), nil, fstest.MapFS{"index.html": {}}); err == nil {
+		t.Fatal("NewRouter accepted a nil job runner")
+	}
+}
+
 func TestHealth(t *testing.T) {
 	t.Parallel()
 
@@ -98,8 +196,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 +209,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, newTestRunner(t))
+
+	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, newTestRunner(t))
+			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),
+		newTestRunner(t), 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,0003_jobs_status" {
+		t.Errorf("versions = %q, want 0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status", 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,0003_jobs_status" {
+		t.Errorf("versions = %q, want 0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status", got)
 	}
 	if !tableExists(t, s, "dinners") {
 		t.Error("table from 0001_init was not created")
@@ -261,3 +262,50 @@ func TestMigrateReopenSameDataDirIsNoOp(t *testing.T) {
 		t.Errorf("schema changed on reopen:\n got %v\nwant %v", afterSchema, beforeSchema)
 	}
 }
+
+// TestMigrateJobsStatusMapsLegacyRows upgrades a database holding jobs in
+// every 0001 status and checks 0003 carries each row over with its status
+// mapped and every other column unchanged.
+func TestMigrateJobsStatusMapsLegacyRows(t *testing.T) {
+	ctx := context.Background()
+	s := openTestStore(t)
+	before := fstest.MapFS{}
+	for _, name := range []string{"0000_bootstrap.sql", "0001_init.sql", "0002_household_settings_updated_by.sql"} {
+		body, err := fs.ReadFile(migrations.FS, name)
+		if err != nil {
+			t.Fatal(err)
+		}
+		before[name] = &fstest.MapFile{Data: body}
+	}
+	if err := Migrate(ctx, s.Writer, before); err != nil {
+		t.Fatal(err)
+	}
+	legacy := map[string]string{"pending": "queued", "running": "running", "done": "succeeded", "failed": "failed"}
+	for old := range legacy {
+		if _, err := s.Writer.Exec(`INSERT INTO jobs (id, kind, status, payload, result, error, started_at, finished_at, created_at, updated_at)
+			VALUES (?, 'suggest', ?, '{"n":1}', '{"r":2}', 'boom', 's', 'f', 'c', 'u')`, "job-"+old, old); err != nil {
+			t.Fatalf("insert %s job: %v", old, err)
+		}
+	}
+
+	if err := Migrate(ctx, s.Writer, migrations.FS); err != nil {
+		t.Fatal(err)
+	}
+	for old, want := range legacy {
+		var kind, status, payload, result, errText, startedAt, finishedAt, createdAt, updatedAt string
+		if err := s.Reader.QueryRow(`SELECT kind, status, payload, result, error, started_at, finished_at, created_at, updated_at FROM jobs WHERE id = ?`, "job-"+old).
+			Scan(&kind, &status, &payload, &result, &errText, &startedAt, &finishedAt, &createdAt, &updatedAt); err != nil {
+			t.Fatalf("read %s job: %v", old, err)
+		}
+		if status != want {
+			t.Errorf("%s job status = %q, want %q", old, status, want)
+		}
+		got := []string{kind, payload, result, errText, startedAt, finishedAt, createdAt, updatedAt}
+		if wantCols := []string{"suggest", `{"n":1}`, `{"r":2}`, "boom", "s", "f", "c", "u"}; !slices.Equal(got, wantCols) {
+			t.Errorf("%s job columns = %v, want %v", old, got, wantCols)
+		}
+	}
+	if tableExists(t, s, "jobs_new") {
+		t.Error("jobs_new left behind")
+	}
+}

internal/store/schema_test.go

@@ -165,7 +165,7 @@ func testRow(table string, i int) map[string]any {
 		r["attempts"] = 0
 	case "jobs":
 		r["kind"] = "suggest"
-		r["status"] = "pending"
+		r["status"] = "queued"
 		r["payload"] = "{}"
 	case "schedule_runs":
 		r["schedule"] = "plan_draft"
@@ -330,7 +330,7 @@ func TestSchemaEnumChecksRejectInvalidValues(t *testing.T) {
 		{"notification_prefs", "chat", 2},
 		{"notification_outbox", "channel", "email"},
 		{"notification_outbox", "status", "queued"},
-		{"jobs", "status", "queued"},
+		{"jobs", "status", "bogus"},
 		{"schedule_runs", "schedule", "hourly"},
 	}
 	s := seededStore(t)

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/0003_jobs_status.sql

@@ -0,0 +1,32 @@
+-- 0003_jobs_status: jobs.status becomes queued, running, succeeded, failed,
+-- the states the job runner (internal/jobs) reports. SQLite cannot change a
+-- CHECK in place, so the table is rebuilt: create the new table, copy every
+-- row, drop the old one and rename. Nothing references jobs and it has no
+-- indexes or triggers, so the rebuild touches no other schema object. Rows
+-- written under the 0001 values are mapped (pending -> queued,
+-- done -> succeeded) so the copy cannot fail on an existing database.
+
+CREATE TABLE jobs_new (
+	id          TEXT NOT NULL PRIMARY KEY,
+	kind        TEXT NOT NULL,
+	status      TEXT NOT NULL CHECK (status IN ('queued', 'running', 'succeeded', 'failed')),
+	payload     TEXT NOT NULL, -- JSON
+	result      TEXT,          -- JSON, written progressively
+	error       TEXT,
+	started_at  TEXT,
+	finished_at TEXT,
+	created_at  TEXT NOT NULL,
+	updated_at  TEXT NOT NULL
+);
+
+INSERT INTO jobs_new (id, kind, status, payload, result, error, started_at, finished_at, created_at, updated_at)
+SELECT
+	id,
+	kind,
+	CASE status WHEN 'pending' THEN 'queued' WHEN 'done' THEN 'succeeded' ELSE status END,
+	payload, result, error, started_at, finished_at, created_at, updated_at
+FROM jobs;
+
+DROP TABLE jobs;
+
+ALTER TABLE jobs_new RENAME TO jobs;

migrations/queries/jobs.sql

@@ -0,0 +1,37 @@
+-- name: CreateJob :exec
+INSERT INTO jobs (id, kind, status, payload, created_at, updated_at)
+VALUES (?, ?, 'queued', ?, ?, ?);
+
+-- name: ClaimNextJob :one
+-- Marks the oldest queued job running and returns it. Returns sql.ErrNoRows
+-- when no job is queued.
+UPDATE jobs
+SET status = 'running', started_at = sqlc.arg(now), updated_at = sqlc.arg(now)
+WHERE id = (SELECT id FROM jobs WHERE status = 'queued' ORDER BY id LIMIT 1)
+RETURNING *;
+
+-- name: PublishJobResult :execrows
+-- Stores a partial result of a running job.
+UPDATE jobs
+SET result = ?, updated_at = ?
+WHERE id = ? AND status = 'running';
+
+-- name: SucceedJob :execrows
+UPDATE jobs
+SET status = 'succeeded', result = sqlc.arg(result), finished_at = sqlc.arg(now), updated_at = sqlc.arg(now)
+WHERE id = sqlc.arg(id) AND status = 'running';
+
+-- name: FailJob :execrows
+UPDATE jobs
+SET status = 'failed', error = sqlc.arg(error), finished_at = sqlc.arg(now), updated_at = sqlc.arg(now)
+WHERE id = sqlc.arg(id) AND status = 'running';
+
+-- name: FailRunningJobs :execrows
+-- Fails every job left running, at boot before any worker starts.
+UPDATE jobs
+SET status = 'failed', error = sqlc.arg(error), finished_at = sqlc.arg(now), updated_at = sqlc.arg(now)
+WHERE status = 'running';
+
+-- name: GetJob :one
+SELECT * FROM jobs
+WHERE id = ?;

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 *;