Feature 03 task 3: Household group gate and auth middleware (#21)

Co-authored-by: dev_agent <dev_agent@cubecraftlabs.com>
Co-committed-by: dev_agent <dev_agent@cubecraftlabs.com>

internal/server/server.go

@@ -22,9 +22,10 @@ type RouteMounter interface {
 }
 
 // NewRouter returns the HTTP handler for the service. version is reported by
-// GET /health; auth mounts the /auth routes; assets is the web build served
-// for every other GET.
-func NewRouter(logger *slog.Logger, version string, auth RouteMounter, assets fs.FS) (http.Handler, error) {
+// GET /health; auth mounts the /auth routes; sessions guards /api/v1 and
+// /media; assets is the web build served for every other GET. /health, /auth
+// and the web build are public.
+func NewRouter(logger *slog.Logger, version string, auth RouteMounter, sessions SessionLookup, assets fs.FS) (http.Handler, error) {
 	notFound := apiErrorHandler(logger, http.StatusNotFound, "not_found", "not found")
 	methodNotAllowed := apiErrorHandler(logger, http.StatusMethodNotAllowed, "method_not_allowed", "method not allowed")
 
@@ -39,13 +40,23 @@ func NewRouter(logger *slog.Logger, version string, auth RouteMounter, assets fs
 
 	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)
+	apiV1, media := chi.NewRouter(), chi.NewRouter()
+	for _, sub := range []*chi.Mux{apiV1, media} {
+		sub.MethodNotAllowed(methodNotAllowed)
+		sub.NotFound(notFound)
+	}
 	r.Route("/api", func(r chi.Router) {
 		r.MethodNotAllowed(methodNotAllowed)
 		r.NotFound(notFound)
+		r.Mount("/v1", signedIn(apiV1))
 	})
-	// Catch-all for the PWA. Unknown /auth paths and /media (no routes yet)
-	// reach the frontend handler, which 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

internal/server/server_test.go

@@ -27,7 +27,7 @@ func newTestRouter(t *testing.T, version string) http.Handler {
 		"index.html":             {Data: []byte(fixtureIndex)},
 		"assets/index-AbC123.js": {Data: []byte(fixtureAsset)},
 	}
-	r, err := NewRouter(logger, version, stubAuth{}, assets)
+	r, err := NewRouter(logger, version, stubAuth{}, stubSessions{}, assets)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -126,6 +126,8 @@ 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/unknown"},
 		{http.MethodGet, "/media/photo.jpg"},
@@ -137,8 +139,11 @@ func TestReservedPathsNotFound(t *testing.T) {
 		t.Run(tt.method+" "+tt.path, func(t *testing.T) {
 			t.Parallel()
 
+			// Signed in, so /api/v1 and /media reach their routers.
+			req := httptest.NewRequest(tt.method, tt.path, nil)
+			req.AddCookie(validSessionCookie)
 			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's actor in the context (read it with
+// 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.WithActor(r.Context(), s.Actor())))
+			}
+		})
+	}
+}

internal/server/session_test.go

@@ -0,0 +1,151 @@
+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"},
+	}
+)
+
+// 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)
+	}
+}