From 4cb50d822a3c57b9c7c4e44321e48241352d45cc Mon Sep 17 00:00:00 2001
From: Randy Hammond <revtex@gmail.com>
Date: Sat, 25 Apr 2026 19:22:47 +0000
Subject: [PATCH] feat(auth): add os_session cookie + dual-auth on
 /api/calls/:id/audio
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- New auth.SetSessionCookie / ClearSessionCookie helpers (HttpOnly,
  Secure when HTTPS, SameSite=Strict, Path=/api)
- POST /api/auth/login and /api/auth/refresh issue os_session alongside
  the existing access JWT response; POST /api/auth/logout clears it
- New middleware.OptionalJWTOrSessionAuth resolves identity from, in
  priority order: bearer header, os_session cookie (guarded by
  Sec-Fetch-Site), anonymous
- GET /api/calls/:id/audio swapped to the new middleware; every other
  route is unchanged. Bearer flow continues to work everywhere.
- Routes.RegisterRoutes now promotes deps.Hub into the WSDisconnecter
  interface only when the concrete pointer is non-nil, fixing a
  pre-existing typed-nil interface footgun on the logout path.

Tests:
- backend/internal/auth/cookie_test.go: SetSessionCookie /
  ClearSessionCookie flag matrix
- backend/internal/handler/routes/auth_test.go: login/refresh/logout
  cookie issuance and rotation
- backend/internal/handler/routes/audio_test.go (new): full dual-auth
  matrix on the audio route — bearer, cookie+same-origin, cookie+missing
  Sec-Fetch-Site, cookie+cross-site (publicAccess on/off), stale cookie
  fallthrough (publicAccess on/off), anonymous (publicAccess on/off)

go vet, go build, go test ./... all clean.
Backwards compatible — no frontend changes.
---
 CHANGELOG.md                                  |   9 +
 backend/internal/auth/cookie.go               |  31 ++
 backend/internal/auth/cookie_test.go          |  65 ++++
 backend/internal/handler/auth/auth.go         |  11 +
 backend/internal/handler/routes/audio_test.go | 325 ++++++++++++++++++
 backend/internal/handler/routes/auth_test.go  | 112 ++++++
 backend/internal/handler/routes/routes.go     |  12 +-
 backend/internal/middleware/auth.go           |  80 +++++
 8 files changed, 643 insertions(+), 2 deletions(-)
 create mode 100644 backend/internal/handler/routes/audio_test.go

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4249266..3d64283 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Session cookie (`os_session`) issued on login and refresh, cleared on
+  logout. The `GET /api/calls/:id/audio` route now accepts authentication
+  via either the existing `Authorization: Bearer` header or the new
+  cookie, so `<audio>` element playback can be authenticated without
+  client-side header injection. Cookie is httpOnly, Secure when served
+  over HTTPS, `SameSite=Strict`, scoped to `/api`. Cross-site requests
+  are rejected via a `Sec-Fetch-Site` check; invalid or expired cookies
+  fall through to anonymous so existing `publicAccess=true` deployments
+  continue to work unchanged.
 - Canonical `GET /api/ws` listener WebSocket route. The existing `GET /ws`
   remains as a compatibility alias that delegates to the same handler. The
   frontend now connects to `/api/ws`, and the Vite dev proxy covers both
diff --git a/backend/internal/auth/cookie.go b/backend/internal/auth/cookie.go
index 10cf437..547e2b4 100644
--- a/backend/internal/auth/cookie.go
+++ b/backend/internal/auth/cookie.go
@@ -12,6 +12,16 @@ const (
 
 	// RefreshCookiePath restricts the cookie to auth endpoints only.
 	RefreshCookiePath = "/api/auth"
+
+	// SessionCookieName is the HTTP cookie name for the session access token.
+	// The cookie value is the access JWT itself; ParseToken + Tokens.IsRevoked
+	// remain the single source of truth for validity.
+	SessionCookieName = "os_session"
+
+	// SessionCookiePath scopes the cookie to /api so it accompanies API
+	// requests (including <audio src="/api/calls/:id/audio">) but not
+	// arbitrary same-origin asset requests.
+	SessionCookiePath = "/api"
 )
 
 // isSecure returns true if the request arrived over HTTPS (directly or via proxy).
@@ -35,3 +45,24 @@ func ClearRefreshCookie(c *gin.Context) {
 	c.SetSameSite(http.SameSiteLaxMode)
 	c.SetCookie(RefreshCookieName, "", -1, RefreshCookiePath, "", secure, true)
 }
+
+// SetSessionCookie writes the access JWT as an httpOnly Secure SameSite=Strict
+// cookie scoped to /api so that <audio src=…> and other same-origin browser
+// requests authenticate without an Authorization header. The cookie's lifetime
+// mirrors the access-token TTL via maxAgeSeconds (pass 0 for a session cookie).
+//
+// SameSite=Strict (deliberately stricter than the refresh cookie's Lax) is
+// the primary CSRF defence: the cookie is never sent on cross-site navigations
+// or sub-resource requests.
+func SetSessionCookie(c *gin.Context, token string, maxAgeSeconds int) {
+	secure := isSecure(c)
+	c.SetSameSite(http.SameSiteStrictMode)
+	c.SetCookie(SessionCookieName, token, maxAgeSeconds, SessionCookiePath, "", secure, true)
+}
+
+// ClearSessionCookie expires the os_session cookie immediately.
+func ClearSessionCookie(c *gin.Context) {
+	secure := isSecure(c)
+	c.SetSameSite(http.SameSiteStrictMode)
+	c.SetCookie(SessionCookieName, "", -1, SessionCookiePath, "", secure, true)
+}
diff --git a/backend/internal/auth/cookie_test.go b/backend/internal/auth/cookie_test.go
index 3492f7f..ca56dcd 100644
--- a/backend/internal/auth/cookie_test.go
+++ b/backend/internal/auth/cookie_test.go
@@ -106,3 +106,68 @@ func TestClearRefreshCookie(t *testing.T) {
 		t.Errorf("SameSite = %v, want Lax", ck.SameSite)
 	}
 }
+
+func TestSetSessionCookie(t *testing.T) {
+	tests := []struct {
+		name       string
+		scheme     string
+		maxAge     int
+		token      string
+		wantSecure bool
+	}{
+		{"http (dev)", "http", 900, "jwt-dev", false},
+		{"https (prod)", "https", 900, "jwt-prod", true},
+		{"session (maxAge=0)", "https", 0, "jwt-session", true},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			c, w := newCookieContext(t, tc.scheme)
+			auth.SetSessionCookie(c, tc.token, tc.maxAge)
+
+			ck := findSetCookie(t, w, auth.SessionCookieName)
+
+			if ck.Value != tc.token {
+				t.Errorf("value = %q, want %q", ck.Value, tc.token)
+			}
+			if !ck.HttpOnly {
+				t.Error("HttpOnly = false, want true")
+			}
+			if ck.Secure != tc.wantSecure {
+				t.Errorf("Secure = %v, want %v", ck.Secure, tc.wantSecure)
+			}
+			if ck.SameSite != http.SameSiteStrictMode {
+				t.Errorf("SameSite = %v, want Strict (%v)", ck.SameSite, http.SameSiteStrictMode)
+			}
+			if ck.Path != auth.SessionCookiePath {
+				t.Errorf("Path = %q, want %q", ck.Path, auth.SessionCookiePath)
+			}
+			if tc.maxAge > 0 && ck.MaxAge != tc.maxAge {
+				t.Errorf("MaxAge = %d, want %d", ck.MaxAge, tc.maxAge)
+			}
+		})
+	}
+}
+
+func TestClearSessionCookie(t *testing.T) {
+	c, w := newCookieContext(t, "https")
+	auth.ClearSessionCookie(c)
+
+	ck := findSetCookie(t, w, auth.SessionCookieName)
+
+	if ck.Value != "" {
+		t.Errorf("value = %q, want empty", ck.Value)
+	}
+	if ck.MaxAge > 0 {
+		t.Errorf("MaxAge = %d, want <= 0", ck.MaxAge)
+	}
+	if ck.Path != auth.SessionCookiePath {
+		t.Errorf("Path = %q, want %q", ck.Path, auth.SessionCookiePath)
+	}
+	if !ck.HttpOnly {
+		t.Error("HttpOnly = false, want true")
+	}
+	if ck.SameSite != http.SameSiteStrictMode {
+		t.Errorf("SameSite = %v, want Strict", ck.SameSite)
+	}
+}
diff --git a/backend/internal/handler/auth/auth.go b/backend/internal/handler/auth/auth.go
index e7cc0e9..9758dd2 100644
--- a/backend/internal/handler/auth/auth.go
+++ b/backend/internal/handler/auth/auth.go
@@ -183,6 +183,12 @@ func (h *Handler) PostLogin(c *gin.Context) {
 		auth.SetRefreshCookie(c, rawRefresh, 0)
 	}
 
+	// Also set the os_session cookie carrying the access JWT so that
+	// <audio src=…> and other same-origin browser requests can authenticate
+	// without injecting an Authorization header. Lifetime mirrors the
+	// access-token TTL; the frontend bearer flow continues to work unchanged.
+	auth.SetSessionCookie(c, token, int(auth.AccessTokenExpiry.Seconds()))
+
 	h.logAuthEvent(c.Request.Context(), "info", "login success: "+user.Username, ip)
 	slog.Info("user logged in", "user_id", user.ID, "username", user.Username, "ip", ip)
 
@@ -238,6 +244,7 @@ func (h *Handler) PostLogout(c *gin.Context) {
 		}
 	}
 	auth.ClearRefreshCookie(c)
+	auth.ClearSessionCookie(c)
 
 	c.JSON(http.StatusOK, gin.H{"ok": true})
 }
@@ -349,6 +356,10 @@ func (h *Handler) PostRefresh(c *gin.Context) {
 	// Set new cookie with same Max-Age as original.
 	auth.SetRefreshCookie(c, newRaw, int(auth.RefreshTokenExpiry.Seconds()))
 
+	// Rotate the os_session cookie alongside the refresh cookie so the
+	// browser-only <audio> auth path always carries a fresh access JWT.
+	auth.SetSessionCookie(c, accessToken, int(auth.AccessTokenExpiry.Seconds()))
+
 	c.JSON(http.StatusOK, refreshResponse{
 		Token: accessToken,
 		User: loginUserResponse{
diff --git a/backend/internal/handler/routes/audio_test.go b/backend/internal/handler/routes/audio_test.go
new file mode 100644
index 0000000..e7b2577
--- /dev/null
+++ b/backend/internal/handler/routes/audio_test.go
@@ -0,0 +1,325 @@
+package routes_test
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/openscanner/openscanner/internal/audio"
+	"github.com/openscanner/openscanner/internal/auth"
+	"github.com/openscanner/openscanner/internal/db"
+	"github.com/openscanner/openscanner/internal/handler/routes"
+)
+
+// audioFixtureBytes is a fixed payload used across the dual-auth audio tests.
+// It is small and not a valid WAV — the handler does not parse the body.
+var audioFixtureBytes = []byte("FAKE_AUDIO_BYTES")
+
+// newTestEngineWithAudio is a variant of newTestEngineWithCalls that exposes
+// the recordings directory so tests can write a real on-disk audio file at the
+// path stored on the calls row. The dual-auth tests need an end-to-end 200
+// response from GET /api/calls/:id/audio, which means the file must exist.
+func newTestEngineWithAudio(t *testing.T) (*gin.Engine, *db.Queries, string) {
+	t.Helper()
+	_, queries := newTestDB(t)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	t.Cleanup(cancel)
+
+	recordingsDir := t.TempDir()
+	pool := audio.NewWorkerPool(ctx)
+	proc := audio.NewProcessor(recordingsDir, pool)
+
+	router := gin.New()
+	rl := auth.NewRateLimiter(context.Background())
+	routes.RegisterRoutes(router, routes.Deps{
+		Queries:     queries,
+		RateLimiter: rl,
+		Processor:   proc,
+		Version:     "test",
+	})
+	return router, queries, recordingsDir
+}
+
+// seedAudioCall writes audioFixtureBytes to a file under recordingsDir and
+// inserts a matching system + talkgroup + call row. Returns the call ID.
+func seedAudioCall(t *testing.T, q *db.Queries, recordingsDir string) int64 {
+	t.Helper()
+	ctx := context.Background()
+
+	// Write the fake audio file at recordingsDir/test/audio.wav so the handler
+	// can resolve it relative to the os.Root.
+	relPath := filepath.Join("test", "audio.wav")
+	absPath := filepath.Join(recordingsDir, relPath)
+	if err := os.MkdirAll(filepath.Dir(absPath), 0o755); err != nil {
+		t.Fatalf("mkdir audio dir: %v", err)
+	}
+	if err := os.WriteFile(absPath, audioFixtureBytes, 0o644); err != nil {
+		t.Fatalf("write audio file: %v", err)
+	}
+
+	sysID, err := q.CreateSystem(ctx, db.CreateSystemParams{
+		SystemID: 100,
+		Label:    "Test System",
+	})
+	if err != nil {
+		t.Fatalf("CreateSystem: %v", err)
+	}
+
+	tgID, err := q.CreateTalkgroup(ctx, db.CreateTalkgroupParams{
+		TalkgroupID: 200,
+		SystemID:    sysID,
+		Label:       sql.NullString{String: "Fire Dispatch", Valid: true},
+		Name:        sql.NullString{String: "FD", Valid: true},
+	})
+	if err != nil {
+		t.Fatalf("CreateTalkgroup: %v", err)
+	}
+
+	callID, err := q.CreateCall(ctx, db.CreateCallParams{
+		AudioPath:   relPath,
+		AudioName:   "audio.wav",
+		AudioType:   "audio/wav",
+		DateTime:    time.Now().Unix(),
+		SystemID:    sysID,
+		TalkgroupID: sql.NullInt64{Int64: tgID, Valid: true},
+		Frequency:   sql.NullInt64{Int64: 851000000, Valid: true},
+		Duration:    sql.NullInt64{Int64: 15, Valid: true},
+		Source:      sql.NullInt64{Int64: 12345, Valid: true},
+	})
+	if err != nil {
+		t.Fatalf("CreateCall: %v", err)
+	}
+	return callID
+}
+
+// setPublicAccess writes the publicAccess setting via the queries helper used
+// elsewhere in the routes tests.
+func setPublicAccess(t *testing.T, q *db.Queries, enabled bool) {
+	t.Helper()
+	val := "false"
+	if enabled {
+		val = "true"
+	}
+	if err := q.UpsertSetting(context.Background(), db.UpsertSettingParams{
+		Key: "publicAccess", Value: val,
+	}); err != nil {
+		t.Fatalf("UpsertSetting publicAccess=%s: %v", val, err)
+	}
+}
+
+// loginAndGetToken seeds an admin user, performs a login, and returns the
+// access JWT (from the JSON body) and the os_session cookie issued by the
+// server.
+func loginAndGetToken(t *testing.T, engine http.Handler, q *db.Queries, username, password string) (string, *http.Cookie) {
+	t.Helper()
+	seedAdminUser(t, q, username, password)
+	w := login(t, engine, username, password)
+	var body struct {
+		Token string `json:"token"`
+	}
+	if err := json.NewDecoder(w.Body).Decode(&body); err != nil {
+		t.Fatalf("decode login response: %v", err)
+	}
+	if body.Token == "" {
+		t.Fatalf("login returned empty token; body cookies: %v", w.Header().Values("Set-Cookie"))
+	}
+	ck := findCookie(w.Result().Cookies(), auth.SessionCookieName)
+	if ck == nil {
+		t.Fatalf("login did not set %s cookie", auth.SessionCookieName)
+	}
+	return body.Token, ck
+}
+
+// TestGetCallAudio_BearerStillWorks verifies the existing Bearer-header path
+// is unaffected by the new dual-auth middleware.
+func TestGetCallAudio_BearerStillWorks(t *testing.T) {
+	engine, queries, recordingsDir := newTestEngineWithAudio(t)
+	callID := seedAudioCall(t, queries, recordingsDir)
+	token, _ := loginAndGetToken(t, engine, queries, "alice", "password123")
+
+	req := httptest.NewRequest(http.MethodGet, fmt.Sprintf("/api/calls/%d/audio", callID), nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	w := httptest.NewRecorder()
+	engine.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200; body: %s", w.Code, w.Body.String())
+	}
+	if got := w.Body.Bytes(); string(got) != string(audioFixtureBytes) {
+		t.Errorf("body = %q, want %q", got, audioFixtureBytes)
+	}
+}
+
+// TestGetCallAudio_CookieWithSameOriginFetchSite verifies the cookie path is
+// honoured when Sec-Fetch-Site indicates a same-origin request.
+func TestGetCallAudio_CookieWithSameOriginFetchSite(t *testing.T) {
+	engine, queries, recordingsDir := newTestEngineWithAudio(t)
+	callID := seedAudioCall(t, queries, recordingsDir)
+	_, sessionCk := loginAndGetToken(t, engine, queries, "alice", "password123")
+
+	req := httptest.NewRequest(http.MethodGet, fmt.Sprintf("/api/calls/%d/audio", callID), nil)
+	req.AddCookie(sessionCk)
+	req.Header.Set("Sec-Fetch-Site", "same-origin")
+	w := httptest.NewRecorder()
+	engine.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200; body: %s", w.Code, w.Body.String())
+	}
+	if got := w.Body.Bytes(); string(got) != string(audioFixtureBytes) {
+		t.Errorf("body = %q, want %q", got, audioFixtureBytes)
+	}
+}
+
+// TestGetCallAudio_CookieWithMissingFetchSite verifies the test-friendly
+// fallback when Sec-Fetch-Site is absent (older clients, server-to-server
+// callers, tests without explicit fetch metadata).
+func TestGetCallAudio_CookieWithMissingFetchSite(t *testing.T) {
+	engine, queries, recordingsDir := newTestEngineWithAudio(t)
+	callID := seedAudioCall(t, queries, recordingsDir)
+	_, sessionCk := loginAndGetToken(t, engine, queries, "alice", "password123")
+
+	req := httptest.NewRequest(http.MethodGet, fmt.Sprintf("/api/calls/%d/audio", callID), nil)
+	req.AddCookie(sessionCk)
+	// Deliberately no Sec-Fetch-Site header.
+	w := httptest.NewRecorder()
+	engine.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200; body: %s", w.Code, w.Body.String())
+	}
+	if got := w.Body.Bytes(); string(got) != string(audioFixtureBytes) {
+		t.Errorf("body = %q, want %q", got, audioFixtureBytes)
+	}
+}
+
+// TestGetCallAudio_CookieWithCrossSiteFetchSite_TreatedAnonymous verifies that
+// a cross-site request causes the cookie to be ignored, falling through to
+// the anonymous path which is gated on publicAccess.
+func TestGetCallAudio_CookieWithCrossSiteFetchSite_TreatedAnonymous(t *testing.T) {
+	t.Run("publicAccess=false yields 401", func(t *testing.T) {
+		engine, queries, recordingsDir := newTestEngineWithAudio(t)
+		callID := seedAudioCall(t, queries, recordingsDir)
+		_, sessionCk := loginAndGetToken(t, engine, queries, "alice", "password123")
+		setPublicAccess(t, queries, false)
+
+		req := httptest.NewRequest(http.MethodGet, fmt.Sprintf("/api/calls/%d/audio", callID), nil)
+		req.AddCookie(sessionCk)
+		req.Header.Set("Sec-Fetch-Site", "cross-site")
+		w := httptest.NewRecorder()
+		engine.ServeHTTP(w, req)
+
+		if w.Code != http.StatusUnauthorized {
+			t.Fatalf("status = %d, want 401; body: %s", w.Code, w.Body.String())
+		}
+	})
+
+	t.Run("publicAccess=true yields 200", func(t *testing.T) {
+		engine, queries, recordingsDir := newTestEngineWithAudio(t)
+		callID := seedAudioCall(t, queries, recordingsDir)
+		_, sessionCk := loginAndGetToken(t, engine, queries, "alice", "password123")
+		setPublicAccess(t, queries, true)
+
+		req := httptest.NewRequest(http.MethodGet, fmt.Sprintf("/api/calls/%d/audio", callID), nil)
+		req.AddCookie(sessionCk)
+		req.Header.Set("Sec-Fetch-Site", "cross-site")
+		w := httptest.NewRecorder()
+		engine.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("status = %d, want 200; body: %s", w.Code, w.Body.String())
+		}
+		if got := w.Body.Bytes(); string(got) != string(audioFixtureBytes) {
+			t.Errorf("body = %q, want %q", got, audioFixtureBytes)
+		}
+	})
+}
+
+// TestGetCallAudio_StaleCookieFallsThroughToAnonymous verifies that an invalid
+// or unparsable session cookie does not abort the request — the middleware
+// silently falls through to the anonymous path.
+func TestGetCallAudio_StaleCookieFallsThroughToAnonymous(t *testing.T) {
+	staleCookie := &http.Cookie{
+		Name:  auth.SessionCookieName,
+		Value: "invalid.jwt.value",
+	}
+
+	t.Run("publicAccess=false yields 401", func(t *testing.T) {
+		engine, queries, recordingsDir := newTestEngineWithAudio(t)
+		callID := seedAudioCall(t, queries, recordingsDir)
+		setPublicAccess(t, queries, false)
+
+		req := httptest.NewRequest(http.MethodGet, fmt.Sprintf("/api/calls/%d/audio", callID), nil)
+		req.AddCookie(staleCookie)
+		req.Header.Set("Sec-Fetch-Site", "same-origin")
+		w := httptest.NewRecorder()
+		engine.ServeHTTP(w, req)
+
+		if w.Code != http.StatusUnauthorized {
+			t.Fatalf("status = %d, want 401; body: %s", w.Code, w.Body.String())
+		}
+	})
+
+	t.Run("publicAccess=true yields 200", func(t *testing.T) {
+		engine, queries, recordingsDir := newTestEngineWithAudio(t)
+		callID := seedAudioCall(t, queries, recordingsDir)
+		setPublicAccess(t, queries, true)
+
+		req := httptest.NewRequest(http.MethodGet, fmt.Sprintf("/api/calls/%d/audio", callID), nil)
+		req.AddCookie(staleCookie)
+		req.Header.Set("Sec-Fetch-Site", "same-origin")
+		w := httptest.NewRecorder()
+		engine.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("status = %d, want 200; body: %s", w.Code, w.Body.String())
+		}
+		if got := w.Body.Bytes(); string(got) != string(audioFixtureBytes) {
+			t.Errorf("body = %q, want %q", got, audioFixtureBytes)
+		}
+	})
+}
+
+// TestGetCallAudio_AnonymousWithPublicAccess verifies that a request with no
+// auth at all succeeds when publicAccess is enabled.
+func TestGetCallAudio_AnonymousWithPublicAccess(t *testing.T) {
+	engine, queries, recordingsDir := newTestEngineWithAudio(t)
+	callID := seedAudioCall(t, queries, recordingsDir)
+	setPublicAccess(t, queries, true)
+
+	req := httptest.NewRequest(http.MethodGet, fmt.Sprintf("/api/calls/%d/audio", callID), nil)
+	w := httptest.NewRecorder()
+	engine.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200; body: %s", w.Code, w.Body.String())
+	}
+	if got := w.Body.Bytes(); string(got) != string(audioFixtureBytes) {
+		t.Errorf("body = %q, want %q", got, audioFixtureBytes)
+	}
+}
+
+// TestGetCallAudio_AnonymousWithoutPublicAccess verifies the default-deny
+// path: no auth and no publicAccess setting yields 401.
+func TestGetCallAudio_AnonymousWithoutPublicAccess(t *testing.T) {
+	engine, queries, recordingsDir := newTestEngineWithAudio(t)
+	callID := seedAudioCall(t, queries, recordingsDir)
+	// Do not set publicAccess; default-unset should be treated as disabled.
+
+	req := httptest.NewRequest(http.MethodGet, fmt.Sprintf("/api/calls/%d/audio", callID), nil)
+	w := httptest.NewRecorder()
+	engine.ServeHTTP(w, req)
+
+	if w.Code != http.StatusUnauthorized {
+		t.Fatalf("status = %d, want 401; body: %s", w.Code, w.Body.String())
+	}
+}
diff --git a/backend/internal/handler/routes/auth_test.go b/backend/internal/handler/routes/auth_test.go
index baafcae..54b28c3 100644
--- a/backend/internal/handler/routes/auth_test.go
+++ b/backend/internal/handler/routes/auth_test.go
@@ -7,6 +7,7 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"testing"
+	"time"
 
 	"github.com/gin-gonic/gin"
 	"github.com/openscanner/openscanner/internal/auth"
@@ -229,3 +230,114 @@ func TestRequireAdmin_AdminGets200(t *testing.T) {
 		t.Errorf("status = %d, want 200", w.Code)
 	}
 }
+
+// findCookie returns the first Set-Cookie value with the given name, or nil.
+func findCookie(cookies []*http.Cookie, name string) *http.Cookie {
+	for _, c := range cookies {
+		if c.Name == name {
+			return c
+		}
+	}
+	return nil
+}
+
+func TestPostLogin_SetsSessionCookie(t *testing.T) {
+	engine, queries := newTestEngine(t)
+	seedAdminUser(t, queries, "alice", "password123")
+
+	w := login(t, engine, "alice", "password123")
+
+	var body struct {
+		Token string `json:"token"`
+	}
+	if err := json.NewDecoder(w.Body).Decode(&body); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+
+	ck := findCookie(w.Result().Cookies(), auth.SessionCookieName)
+	if ck == nil {
+		t.Fatalf("os_session cookie not set on login; cookies: %v", w.Header().Values("Set-Cookie"))
+	}
+	if ck.Value != body.Token {
+		t.Errorf("os_session value mismatch: cookie=%q response.token=%q", ck.Value, body.Token)
+	}
+	if !ck.HttpOnly {
+		t.Error("os_session: HttpOnly = false, want true")
+	}
+	if ck.SameSite != http.SameSiteStrictMode {
+		t.Errorf("os_session: SameSite = %v, want Strict", ck.SameSite)
+	}
+	if ck.Path != auth.SessionCookiePath {
+		t.Errorf("os_session: Path = %q, want %q", ck.Path, auth.SessionCookiePath)
+	}
+}
+
+func TestPostRefresh_RotatesSessionCookie(t *testing.T) {
+	engine, queries := newTestEngine(t)
+	seedAdminUser(t, queries, "alice", "password123")
+
+	loginW := login(t, engine, "alice", "password123")
+	originalSession := findCookie(loginW.Result().Cookies(), auth.SessionCookieName)
+	refreshCk := findCookie(loginW.Result().Cookies(), auth.RefreshCookieName)
+	if originalSession == nil || refreshCk == nil {
+		t.Fatalf("missing cookies after login: session=%v refresh=%v", originalSession, refreshCk)
+	}
+
+	// Sleep for one second so the JWT iat/exp differs and the rotated
+	// access token is guaranteed not to byte-equal the original.
+	time.Sleep(1100 * time.Millisecond)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/auth/refresh", nil)
+	req.AddCookie(refreshCk)
+	w := httptest.NewRecorder()
+	engine.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("refresh status = %d, want 200; body: %s", w.Code, w.Body.String())
+	}
+
+	rotated := findCookie(w.Result().Cookies(), auth.SessionCookieName)
+	if rotated == nil {
+		t.Fatalf("os_session cookie not rotated on refresh; cookies: %v", w.Header().Values("Set-Cookie"))
+	}
+	if rotated.Value == "" {
+		t.Error("rotated os_session has empty value")
+	}
+	if rotated.Value == originalSession.Value {
+		t.Error("os_session value did not change after refresh")
+	}
+	if rotated.SameSite != http.SameSiteStrictMode {
+		t.Errorf("rotated os_session: SameSite = %v, want Strict", rotated.SameSite)
+	}
+}
+
+func TestPostLogout_ClearsSessionCookie(t *testing.T) {
+	engine, queries := newTestEngine(t)
+	seedAdminUser(t, queries, "alice", "password123")
+
+	loginW := login(t, engine, "alice", "password123")
+	var body struct {
+		Token string `json:"token"`
+	}
+	if err := json.NewDecoder(loginW.Body).Decode(&body); err != nil {
+		t.Fatalf("decode login: %v", err)
+	}
+
+	req := httptest.NewRequest(http.MethodPost, "/api/auth/logout", nil)
+	req.Header.Set("Authorization", "Bearer "+body.Token)
+	w := httptest.NewRecorder()
+	engine.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("logout status = %d, want 200; body: %s", w.Code, w.Body.String())
+	}
+
+	ck := findCookie(w.Result().Cookies(), auth.SessionCookieName)
+	if ck == nil {
+		t.Fatalf("os_session not cleared on logout; cookies: %v", w.Header().Values("Set-Cookie"))
+	}
+	if ck.Value != "" {
+		t.Errorf("os_session value = %q, want empty", ck.Value)
+	}
+	if ck.MaxAge > 0 {
+		t.Errorf("os_session MaxAge = %d, want <= 0", ck.MaxAge)
+	}
+}
diff --git a/backend/internal/handler/routes/routes.go b/backend/internal/handler/routes/routes.go
index 98868a1..24c2be0 100644
--- a/backend/internal/handler/routes/routes.go
+++ b/backend/internal/handler/routes/routes.go
@@ -72,7 +72,15 @@ type Deps struct {
 func RegisterRoutes(r *gin.Engine, deps Deps) {
 	healthHandler := health.New(deps.Version)
 	setupHandler := setup.New(deps.Queries)
-	authH := authhandler.New(deps.Queries, deps.RateLimiter, deps.Hub)
+	// Avoid the typed-nil interface footgun: only promote deps.Hub into the
+	// WSDisconnecter interface when the concrete pointer is non-nil. This
+	// keeps tests that pass Deps{} (no Hub) from triggering nil-pointer
+	// dereferences on logout / token revocation paths.
+	var disconnecter authhandler.WSDisconnecter
+	if deps.Hub != nil {
+		disconnecter = deps.Hub
+	}
+	authH := authhandler.New(deps.Queries, deps.RateLimiter, disconnecter)
 	callHandler := calls.New(deps.Queries, deps.Processor, deps.Hub, deps.DownstreamNotifier, deps.Transcriber)
 	shareHandler := share.New(deps.Queries, deps.Processor)
 	bookmarkHandler := bookmarks.New(deps.Queries)
@@ -110,7 +118,7 @@ func RegisterRoutes(r *gin.Engine, deps Deps) {
 
 	// Call search — public access with optional auth for bookmarks.
 	api.GET("/calls", middleware.OptionalJWTAuth(), callHandler.GetCalls)
-	api.GET("/calls/:id/audio", middleware.OptionalJWTAuth(), callHandler.GetCallAudio)
+	api.GET("/calls/:id/audio", middleware.OptionalJWTOrSessionAuth(), callHandler.GetCallAudio)
 	api.GET("/calls/:id/transcript", middleware.OptionalJWTAuth(), callHandler.GetCallTranscript)
 
 	// Shared calls — token-based public access (no auth required).
diff --git a/backend/internal/middleware/auth.go b/backend/internal/middleware/auth.go
index 882c0ae..051a2f1 100644
--- a/backend/internal/middleware/auth.go
+++ b/backend/internal/middleware/auth.go
@@ -86,6 +86,86 @@ func OptionalJWTAuth() gin.HandlerFunc {
 	}
 }
 
+// applyClaimsToContext sets the standard JWT claim values onto the Gin context.
+// Shared by the bearer and session-cookie auth paths.
+func applyClaimsToContext(c *gin.Context, claims *auth.Claims) {
+	c.Set("userID", claims.UserID)
+	c.Set("username", claims.Username)
+	c.Set("role", claims.Role)
+	c.Set("jti", claims.ID)
+}
+
+// claimsValid runs the same revocation, expiration and account-expiration
+// checks as JWTAuth/OptionalJWTAuth. Returns true when the token can be used
+// to identify the user.
+func claimsValid(claims *auth.Claims) bool {
+	if auth.Tokens.IsRevoked(claims.ID) {
+		return false
+	}
+	if claims.AccountExp > 0 && time.Now().Unix() > claims.AccountExp {
+		return false
+	}
+	return true
+}
+
+// OptionalJWTOrSessionAuth resolves identity from, in priority order:
+//
+//  1. Authorization: Bearer header (existing behaviour, unchanged).
+//  2. os_session cookie (new) — only honoured when the request is same-site,
+//     determined by the Sec-Fetch-Site fetch metadata header. SameSite=Strict
+//     on the cookie itself already enforces same-site at the browser layer;
+//     this is defence-in-depth at the server.
+//  3. Anonymous (no userID set in context — downstream handlers fall back to
+//     publicAccess semantics or 401 as appropriate).
+//
+// The middleware never aborts the request: invalid/expired/revoked credentials
+// (header or cookie) silently fall through to anonymous so that the
+// publicAccess setting still controls access. This mirrors OptionalJWTAuth.
+func OptionalJWTOrSessionAuth() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		// 1. Bearer header takes priority.
+		if header := c.GetHeader("Authorization"); strings.HasPrefix(header, "Bearer ") {
+			tokenStr := strings.TrimPrefix(header, "Bearer ")
+			if claims, err := auth.ParseToken(tokenStr); err == nil && claimsValid(claims) {
+				applyClaimsToContext(c, claims)
+			}
+			c.Next()
+			return
+		}
+
+		// 2. os_session cookie — only for same-site requests.
+		cookieValue, err := c.Cookie(auth.SessionCookieName)
+		if err != nil || cookieValue == "" {
+			c.Next()
+			return
+		}
+
+		// Sec-Fetch-Site is a fetch-metadata header. Browsers always send it
+		// for HTTP/1.1+ requests. Acceptable values for a same-origin/same-site
+		// request are "same-origin", "same-site", and "none" (the user
+		// directly typed/bookmarked the URL). If the header is missing
+		// (older clients, tests), fall back to trusting the SameSite=Strict
+		// browser-side enforcement.
+		switch c.GetHeader("Sec-Fetch-Site") {
+		case "", "same-origin", "same-site", "none":
+			// allowed
+		default:
+			// "cross-site" or any unrecognised value — refuse to authenticate
+			// from the cookie. Treat as anonymous; do not 401.
+			c.Next()
+			return
+		}
+
+		claims, err := auth.ParseToken(cookieValue)
+		if err != nil || !claimsValid(claims) {
+			c.Next()
+			return
+		}
+		applyClaimsToContext(c, claims)
+		c.Next()
+	}
+}
+
 // RequireAdmin checks that the authenticated user has the admin role.
 // Must be chained after JWTAuth. Aborts with 403 if the role is not admin.
 func RequireAdmin() gin.HandlerFunc {