feat(auth): TRUST_REMOTE_USER_HEADER toggle, path-prefix coverage, spoof-resistance, SSE+static tests

Author: terafin

README.md

@@ -72,6 +72,10 @@ Maps host port `80` to container port `80`.
 
 Disables login requirements. This is the default and is intended for trusted internal networks.
 
+`TRUST_REMOTE_USER_HEADER: false`
+
+When `AUTH_MODE=enabled`, set `TRUST_REMOTE_USER_HEADER=true` ONLY if a reverse proxy (e.g. Authelia, Authentik, oauth2-proxy) sits in front of RSM and strips and re-sets the `Remote-User` header on every request. The default (`false`) prevents WAN spoofing — without a stripping proxy, any client could forge the header and bypass authentication.
+
 `SAVE_ROOT: /saves`
 
 The container stores all managed save data under `/saves`.

backend/cmd/server/auth_middleware.go

@@ -13,8 +13,14 @@ import (
 // Paths are matched after stripping any of the well-known route prefixes
 // (/api/v1, /api, /v1) via stripRoutePrefix, so each entry needs to be listed
 // only once.
+//
+// NOTE: /healthz is intentionally NOT in this map. It is registered at the
+// router root only (NOT under any compat-mount prefix), so allowing
+// /api/healthz / /v1/healthz / etc. through the allowlist would let those
+// paths skip auth even though they have no real route — leaking 404s and,
+// worse, falling through to the static-frontend handler. /healthz is matched
+// as an exact path in isPublicAuthPath instead.
 var publicAuthPaths = map[string]struct{}{
-	"/healthz":                  {},
 	"/runtime-config":           {},
 	"/auth/login":               {},
 	"/auth/signup":              {},
@@ -52,7 +58,14 @@ func stripRoutePrefix(p string) string {
 // isPublicAuthPath reports whether p is one of the bootstrap endpoints that
 // must remain reachable without authentication. The check is prefix-aware so
 // that, e.g., /api/v1/auth/login matches the canonical /auth/login entry.
+//
+// /healthz is handled as a special case: only the exact "/healthz" path is
+// allowlisted. /api/healthz, /v1/healthz, etc. are NOT — they have no real
+// route and matching them would invite the static-frontend NotFound fallback.
 func isPublicAuthPath(p string) bool {
+	if p == "/healthz" {
+		return true
+	}
 	canonical := stripRoutePrefix(p)
 	if _, ok := publicAuthPaths[canonical]; ok {
 		return true
@@ -127,7 +140,10 @@ func hasHelperIdentity(r *http.Request) bool {
 // when AUTH_MODE=enabled. See requireAuth for the accepted forms.
 func (a *app) isAuthenticatedRequest(r *http.Request) bool {
 	// 1. Reverse-proxy forwardAuth (Authelia, oauth2-proxy, etc).
-	if strings.TrimSpace(r.Header.Get("Remote-User")) != "" {
+	// Only honored when the operator has explicitly opted in via
+	// TRUST_REMOTE_USER_HEADER — otherwise a WAN-exposed RSM would trust
+	// any client-supplied Remote-User header, which is trivially spoofable.
+	if trustRemoteUserHeader() && strings.TrimSpace(r.Header.Get("Remote-User")) != "" {
 		return true
 	}
 

backend/cmd/server/auth_middleware_test.go

@@ -2,9 +2,12 @@ package main
 
 import (
 	"bytes"
+	"context"
 	"mime/multipart"
 	"net/http"
 	"net/http/httptest"
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 	"time"
@@ -79,6 +82,7 @@ func TestAuthMiddleware_Enabled_AllowsValidXRSMAppPasswordHeader(t *testing.T) {
 
 func TestAuthMiddleware_Enabled_AllowsRemoteUserHeader(t *testing.T) {
 	h := authMiddlewareHarness(t, true)
+	t.Setenv("TRUST_REMOTE_USER_HEADER", "true")
 	req := rawRequest(http.MethodGet, "/api/saves")
 	req.Header.Set("Remote-User", "alice")
 	rr := h.do(req)
@@ -225,3 +229,270 @@ func TestAuthMiddleware_Enabled_GetApiSavesWithValidBearer_Allows(t *testing.T)
 	rr := h.do(req)
 	assertStatus(t, rr, http.StatusOK)
 }
+
+// --- AUTH_MODE=enabled — path-prefix variants of allowlisted endpoints ---
+//
+// The compat router mounts the public-auth endpoints under "" and /v1. The
+// agent router mounts a separate /runtime-config under /api and /api/v1, but
+// does NOT re-expose /auth/login. The middleware's stripRoutePrefix must let
+// each variant that actually has a backing route through without auth.
+
+func TestAuthMiddleware_Enabled_AllowsRuntimeConfigPrefixVariants(t *testing.T) {
+	for _, path := range []string{
+		"/runtime-config",
+		"/v1/runtime-config",
+		"/api/runtime-config",
+		"/api/v1/runtime-config",
+	} {
+		t.Run(path, func(t *testing.T) {
+			h := authMiddlewareHarness(t, true)
+			rr := h.do(rawRequest(http.MethodGet, path))
+			assertStatus(t, rr, http.StatusOK)
+		})
+	}
+}
+
+func TestAuthMiddleware_Enabled_AllowsAuthLoginPrefixVariants(t *testing.T) {
+	// Compat-router mounts only — /api(/v1)/auth/login has no backing route
+	// and is intentionally not part of the agent surface.
+	for _, path := range []string{
+		"/auth/login",
+		"/v1/auth/login",
+	} {
+		t.Run(path, func(t *testing.T) {
+			h := authMiddlewareHarness(t, true)
+			req := httptest.NewRequest(http.MethodPost, path, strings.NewReader(`{}`))
+			req.Header.Set("Content-Type", "application/json")
+			req.Header.Set("X-CSRF-Protection", "1")
+			rr := h.do(req)
+			assertStatus(t, rr, http.StatusOK)
+		})
+	}
+}
+
+// /healthz is registered at the router ROOT only — NOT under any compat mount.
+// Only the exact path is allowlisted; /api/healthz / /v1/healthz / etc. must
+// be treated as non-bootstrap traffic and rejected with 401.
+func TestAuthMiddleware_Enabled_HealthzAllowlistIsRootOnly(t *testing.T) {
+	h := authMiddlewareHarness(t, true)
+
+	rrRoot := h.do(rawRequest(http.MethodGet, "/healthz"))
+	assertStatus(t, rrRoot, http.StatusOK)
+
+	for _, path := range []string{
+		"/api/healthz",
+		"/v1/healthz",
+		"/api/v1/healthz",
+	} {
+		t.Run(path, func(t *testing.T) {
+			h := authMiddlewareHarness(t, true)
+			rr := h.do(rawRequest(http.MethodGet, path))
+			assertStatus(t, rr, http.StatusUnauthorized)
+		})
+	}
+}
+
+// --- AUTH_MODE=enabled — spoof-prevention edge cases ---
+//
+// Empty / whitespace-only Remote-User and session cookies must NOT be
+// accepted as proof of authentication, regardless of how they got there
+// (a misconfigured proxy that always sets Remote-User="" is the most
+// realistic source).
+
+func TestAuthMiddleware_Enabled_RejectsEmptyRemoteUserHeader(t *testing.T) {
+	h := authMiddlewareHarness(t, true)
+	t.Setenv("TRUST_REMOTE_USER_HEADER", "true")
+	req := rawRequest(http.MethodGet, "/api/saves")
+	req.Header.Set("Remote-User", "")
+	rr := h.do(req)
+	assertStatus(t, rr, http.StatusUnauthorized)
+}
+
+func TestAuthMiddleware_Enabled_RejectsWhitespaceRemoteUserHeader(t *testing.T) {
+	h := authMiddlewareHarness(t, true)
+	t.Setenv("TRUST_REMOTE_USER_HEADER", "true")
+	req := rawRequest(http.MethodGet, "/api/saves")
+	req.Header.Set("Remote-User", "    ")
+	rr := h.do(req)
+	assertStatus(t, rr, http.StatusUnauthorized)
+}
+
+func TestAuthMiddleware_Enabled_RejectsEmptySessionCookie(t *testing.T) {
+	h := authMiddlewareHarness(t, true)
+	req := rawRequest(http.MethodGet, "/api/saves")
+	req.AddCookie(&http.Cookie{Name: "session", Value: ""})
+	rr := h.do(req)
+	assertStatus(t, rr, http.StatusUnauthorized)
+}
+
+func TestAuthMiddleware_Enabled_RejectsWhitespaceSessionCookie(t *testing.T) {
+	h := authMiddlewareHarness(t, true)
+	req := rawRequest(http.MethodGet, "/api/saves")
+	req.AddCookie(&http.Cookie{Name: "session", Value: "    "})
+	rr := h.do(req)
+	assertStatus(t, rr, http.StatusUnauthorized)
+}
+
+// --- AUTH_MODE=enabled — SSE /events endpoint ---
+//
+// /events serves text/event-stream and leaks live state if exposed.
+// It must require auth in every prefix-mount variant.
+
+func TestAuthMiddleware_Enabled_BlocksEventsWithoutAuth(t *testing.T) {
+	for _, path := range []string{
+		"/events",
+		"/api/events",
+	} {
+		t.Run(path, func(t *testing.T) {
+			h := authMiddlewareHarness(t, true)
+			rr := h.do(rawRequest(http.MethodGet, path))
+			assertStatus(t, rr, http.StatusUnauthorized)
+		})
+	}
+}
+
+// With a valid Bearer the SSE handler should at least send response headers
+// with the SSE content-type before we tear the connection down. We use the
+// existing ssePrelude helper which cancels right after seeing the initial
+// ": connected\n\n" frame, so the test doesn't hang on the long-lived stream.
+func TestAuthMiddleware_Enabled_AllowsEventsWithValidBearer(t *testing.T) {
+	h := authMiddlewareHarness(t, true)
+	key := mintAppPassword(t, h)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	req := httptest.NewRequest(http.MethodGet, "/events", nil).WithContext(ctx)
+	req.Header.Set("X-CSRF-Protection", "1")
+	req.Header.Set("Authorization", "Bearer "+key)
+
+	rr := httptest.NewRecorder()
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		h.handler.ServeHTTP(rr, req)
+	}()
+
+	deadline := time.Now().Add(2 * time.Second)
+	for {
+		if strings.HasPrefix(rr.Body.String(), ": connected\n\n") {
+			cancel()
+			<-done
+			break
+		}
+		if time.Now().After(deadline) {
+			cancel()
+			<-done
+			t.Fatalf("timed out waiting for SSE prelude; status=%d headers=%v body=%q",
+				rr.Code, rr.Header(), rr.Body.String())
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("expected SSE 200, got %d", rr.Code)
+	}
+	if ct := rr.Header().Get("Content-Type"); !strings.Contains(ct, "text/event-stream") {
+		t.Fatalf("expected Content-Type to contain text/event-stream, got %q", ct)
+	}
+}
+
+// --- AUTH_MODE=enabled — static frontend behavior ---
+//
+// The chi NotFound handler serves the SPA shell for any GET that isn't a
+// reserved API path. With AUTH_MODE=enabled the auth middleware fires BEFORE
+// NotFound, so unauthenticated SPA loads receive 401. This is intentional:
+// when AUTH_MODE=enabled the operator is expected to either expose the UI
+// behind a forwardAuth proxy (Authelia) or accept that the SPA is gated.
+//
+// These tests pin the documented behavior so it can't silently regress.
+
+// staticFrontendHarness installs a minimal dist/index.html + dist/assets/app.js
+// so the static-frontend handler is wired up. Returns the harness.
+func staticFrontendHarness(t *testing.T, enabled bool) *contractHarness {
+	t.Helper()
+	distDir := filepath.Join(t.TempDir(), "dist")
+	if err := os.MkdirAll(filepath.Join(distDir, "assets"), 0o755); err != nil {
+		t.Fatalf("mkdir dist: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(distDir, "index.html"),
+		[]byte("<!doctype html><html><body>RSM</body></html>"), 0o644); err != nil {
+		t.Fatalf("write index: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(distDir, "assets", "app.js"),
+		[]byte("console.log('rsm');"), 0o644); err != nil {
+		t.Fatalf("write asset: %v", err)
+	}
+	t.Setenv("FRONTEND_DIST_DIR", distDir)
+	return authMiddlewareHarness(t, enabled)
+}
+
+func TestAuthMiddleware_Enabled_BlocksStaticRootWithoutAuth(t *testing.T) {
+	h := staticFrontendHarness(t, true)
+	rr := h.do(rawRequest(http.MethodGet, "/"))
+	assertStatus(t, rr, http.StatusUnauthorized)
+}
+
+func TestAuthMiddleware_Enabled_BlocksStaticAssetWithoutAuth(t *testing.T) {
+	h := staticFrontendHarness(t, true)
+	rr := h.do(rawRequest(http.MethodGet, "/assets/app.js"))
+	assertStatus(t, rr, http.StatusUnauthorized)
+}
+
+func TestAuthMiddleware_Enabled_AllowsStaticRootWithRemoteUser(t *testing.T) {
+	h := staticFrontendHarness(t, true)
+	t.Setenv("TRUST_REMOTE_USER_HEADER", "true")
+	req := rawRequest(http.MethodGet, "/")
+	req.Header.Set("Remote-User", "alice")
+	rr := h.do(req)
+	assertStatus(t, rr, http.StatusOK)
+}
+
+func TestAuthMiddleware_Disabled_AllowsStaticRoot(t *testing.T) {
+	h := staticFrontendHarness(t, false)
+	rr := h.do(rawRequest(http.MethodGet, "/"))
+	assertStatus(t, rr, http.StatusOK)
+}
+
+// --- AUTH_MODE=enabled — TRUST_REMOTE_USER_HEADER opt-in ---
+//
+// Remote-User is only honored when the operator explicitly opts in. Default
+// off is the safe-by-default posture: a WAN-exposed RSM with no stripping
+// reverse proxy would otherwise trust any client-supplied header.
+
+func TestAuthMiddleware_Enabled_RemoteUserIgnoredByDefault(t *testing.T) {
+	h := authMiddlewareHarness(t, true)
+	// TRUST_REMOTE_USER_HEADER intentionally unset.
+	req := rawRequest(http.MethodGet, "/api/saves")
+	req.Header.Set("Remote-User", "alice")
+	rr := h.do(req)
+	assertStatus(t, rr, http.StatusUnauthorized)
+}
+
+func TestAuthMiddleware_Enabled_RemoteUserHonoredWhenTrusted(t *testing.T) {
+	h := authMiddlewareHarness(t, true)
+	t.Setenv("TRUST_REMOTE_USER_HEADER", "true")
+	req := rawRequest(http.MethodGet, "/api/saves")
+	req.Header.Set("Remote-User", "alice")
+	rr := h.do(req)
+	assertStatus(t, rr, http.StatusOK)
+}
+
+func TestAuthMiddleware_Enabled_RemoteUserIgnoredWhenExplicitlyFalse(t *testing.T) {
+	h := authMiddlewareHarness(t, true)
+	t.Setenv("TRUST_REMOTE_USER_HEADER", "false")
+	req := rawRequest(http.MethodGet, "/api/saves")
+	req.Header.Set("Remote-User", "alice")
+	rr := h.do(req)
+	assertStatus(t, rr, http.StatusUnauthorized)
+}
+
+// TRUST_REMOTE_USER_HEADER=true + empty/whitespace Remote-User must still
+// reject — the trim check is the last line of defense if a misconfigured
+// proxy strips the user but leaves the header in place.
+func TestAuthMiddleware_Enabled_RemoteUserTrustedButEmptyRejects(t *testing.T) {
+	h := authMiddlewareHarness(t, true)
+	t.Setenv("TRUST_REMOTE_USER_HEADER", "true")
+	req := rawRequest(http.MethodGet, "/api/saves")
+	req.Header.Set("Remote-User", "   ")
+	rr := h.do(req)
+	assertStatus(t, rr, http.StatusUnauthorized)
+}

backend/cmd/server/config_helpers.go

@@ -14,6 +14,25 @@ func authMode() string {
 	return mode
 }
 
+// trustRemoteUserHeader reports whether the Remote-User header should be
+// trusted as proof of authentication when AUTH_MODE=enabled.
+//
+// Default is FALSE — a deployment that exposes RSM directly to the WAN
+// without a stripping reverse proxy in front would otherwise be trivially
+// spoofable by any client that sets the header. Operators who DO have a
+// trusted forwardAuth proxy (Authelia, oauth2-proxy, Authentik, etc.) in
+// front and want SSO to work must opt in explicitly by setting
+// TRUST_REMOTE_USER_HEADER=true (or "yes" / "1").
+func trustRemoteUserHeader() bool {
+	v := strings.TrimSpace(strings.ToLower(os.Getenv("TRUST_REMOTE_USER_HEADER")))
+	switch v {
+	case "true", "yes", "1":
+		return true
+	default:
+		return false
+	}
+}
+
 func baseURLForRequest(r *http.Request) string {
 	if env := strings.TrimSpace(os.Getenv("BASE_URL")); env != "" {
 		return strings.TrimRight(env, "/")