feat(auth): absolute-timeout ceiling + slide-on-user-activity (AUTH-1 b+c) (#678)

* feat(auth): absolute-timeout ceiling + slide-on-user-activity (AUTH-1 b+c)

Completes AUTH-1 (slice 1 was the client idle timer, #675).

(b) Absolute timeout is now a real hard ceiling. The cookie-refresh path used
to re-mint a session with a FRESH absolute window on the 7-day refresh token,
so the absolute timeout (default 12h) never bit. Carry the original login's
absolute deadline through the refresh-token lineage (migration 0047 adds
refresh_tokens.absolute_expires_at; stamped at login, copied unchanged on every
rotation). ConsumeRefreshToken refuses past the deadline (ErrRefreshSessionExpired
-> 401 + clear cookies); a refreshed session inherits the original deadline via
IssueSessionWithAbsolute. Legacy tokens (pre-migration) are exempt until they
age out within 7 days.

(c) The server idle window now tracks real user activity, not HTTP traffic.
VerifySession gains WithoutSlide; the binder passes it when a request carries
X-Background-Refresh. The SPA API client marks background/poll GETs with that
header, gated on the idle-timer activity signal (slice 1's localStorage key).
Fail-safe: an unmarked request slides as before, so the change is inert until
the activity signal exists -- no premature logout.

Spec system-auth-identity v1.4.0: C-28/C-29 + AC-28..AC-31. Backend + frontend
tests green; specter 31/31 ACs, 100%.

* fix(auth): SSE stream must not slide the idle window; guard zero absolute deadline

Security-review follow-ups on AUTH-1 (c):
- The /api/v1/events SSE stream authenticates via the binder but EventSource
  cannot send X-Background-Refresh, and it reconnects through proxy idle
  timeouts — so each (re)connect slid the idle window, letting an open SPA keep
  an unattended session alive forever, defeating (c). The binder now passes
  WithoutSlide for the SSE path. Binder test extended.
- IssueSessionWithAbsolute now treats a zero deadline as 'no carried ceiling'
  and grants a fresh absolute window, instead of capping idle to the zero time
  (an always-expired session) — defensive against a future caller.

Spec system-auth-identity C-29/AC-31 updated.

Author: remyluslosius

frontend/src/api/client.ts

@@ -24,6 +24,26 @@ const CSRF_HEADER = 'X-CSRF-Token';
 const REFRESH_PATH = '/api/v1/auth/refresh-cookie';
 const LOGIN_PATH = '/login';
 
+// AUTH-1 (c): the server slides the session idle window only on user-initiated
+// requests. We mark background/poll GETs with X-Background-Refresh so they do
+// NOT keep an unattended session alive. "User-initiated" is inferred from the
+// idle-timer's activity signal (the same localStorage key useIdleLogout writes
+// on real pointer/keyboard input). Fail-safe: until that key is written (e.g.
+// the idle timer is not present), we never mark, so the server slides exactly
+// as before — no premature logout.
+const BACKGROUND_HEADER = 'X-Background-Refresh';
+const ACTIVITY_KEY = 'ow.session.lastActivity';
+let lastReportedActivity = 0;
+
+function lastUserActivity(): number {
+  try {
+    const n = Number(localStorage.getItem(ACTIVITY_KEY));
+    return Number.isFinite(n) ? n : 0;
+  } catch {
+    return 0;
+  }
+}
+
 function readCookie(name: string): string | null {
   if (typeof document === 'undefined') return null;
   const target = name + '=';
@@ -131,8 +151,20 @@ baseClient.use({
   onRequest({ request }) {
     const method = request.method.toUpperCase();
     if (method === 'GET' || method === 'HEAD' || method === 'OPTIONS') {
+      // AUTH-1 (c): a safe read rides genuine user activity (don't mark → the
+      // server slides) only when there is NEW activity since the last reported
+      // request; otherwise it is background churn and must not slide the window.
+      const last = lastUserActivity();
+      if (last > 0) {
+        if (last > lastReportedActivity) {
+          lastReportedActivity = last;
+        } else {
+          request.headers.set(BACKGROUND_HEADER, '1');
+        }
+      }
       return request;
     }
+    // Mutations are always user-initiated → never marked background (they slide).
     const token = readCookie(CSRF_COOKIE);
     if (token) request.headers.set(CSRF_HEADER, token);
     return request;

frontend/tests/api/client-retry.test.ts

@@ -207,3 +207,22 @@ describe('api/client — 401 retry middleware', () => {
     expect(navigateSpy).toHaveBeenCalledWith('/login');
   });
 });
+
+// @ac AC-31
+// AC-31 (AUTH-1 c) — the client marks background/poll reads with
+// X-Background-Refresh so the server does not slide the idle window for them,
+// gated on the idle-timer activity signal (fail-safe: inert until that
+// localStorage key is written). Source-inspection of the request middleware.
+test('system-auth-identity/AC-31 — marks background reads with X-Background-Refresh, gated on activity', async () => {
+  const { readFileSync } = await import('node:fs');
+  const { resolve } = await import('node:path');
+  const src = readFileSync(resolve(process.cwd(), 'src/api/client.ts'), 'utf8');
+  // Sets the background marker header...
+  expect(src).toContain("'X-Background-Refresh'");
+  // ...gated on the idle-timer activity signal (the fail-safe localStorage key).
+  expect(src).toContain("'ow.session.lastActivity'");
+  // ...via the request middleware on safe reads (mutations always slide).
+  expect(src).toMatch(/BACKGROUND_HEADER/);
+  // Fail-safe: only marks when an activity timestamp actually exists.
+  expect(src).toMatch(/last > 0/);
+});

internal/db/migrations/0047_refresh_absolute_deadline.sql

@@ -0,0 +1,24 @@
+-- 0047_refresh_absolute_deadline.sql
+--
+-- AUTH-1 (b): make the session ABSOLUTE timeout a real ceiling.
+--
+-- The cookie-refresh path (PostAuthRefreshCookie) re-mints a session on the
+-- 7-day refresh token and, before this change, gave the new session a FRESH
+-- absolute window — so the absolute timeout (default 12h) never actually bit:
+-- a browser could be kept alive for the full 7-day refresh-token life.
+--
+-- Carry the original login's absolute deadline through the refresh-token
+-- lineage: it is stamped at login and copied UNCHANGED on every rotation. Once
+-- now > absolute_expires_at, refresh is refused and the chain ends.
+--
+-- Nullable: refresh tokens minted before this migration (in-flight, up to 7
+-- days) carry NULL and are treated as legacy (no absolute ceiling) until they
+-- naturally expire — no forced logout on upgrade.
+--
+-- Spec: system-auth-identity.
+
+-- +goose Up
+ALTER TABLE refresh_tokens ADD COLUMN absolute_expires_at TIMESTAMPTZ;
+
+-- +goose Down
+ALTER TABLE refresh_tokens DROP COLUMN absolute_expires_at;

internal/identity/binder.go

@@ -18,6 +18,20 @@ import (
 // presentation tokens. Server-set; client reads it back over HTTPS.
 const SessionCookieName = "openwatch_session"
 
+// BackgroundRefreshHeader marks a request as NOT user-initiated (a background
+// poll, an SSE reconnect) so the binder verifies the session without sliding
+// its idle window. The SPA sets it on recurring/background fetches; ordinary
+// user-driven navigation and mutations omit it and slide as before. AUTH-1 (c).
+const BackgroundRefreshHeader = "X-Background-Refresh"
+
+// sseEventsPath is the live-events SSE stream. EventSource cannot set custom
+// headers, so it can never send BackgroundRefreshHeader; yet it is a long-lived
+// background subscription that reconnects (often through a proxy idle-timeout).
+// Treating it as user activity would let an open SPA keep an unattended session
+// alive forever, defeating the idle timeout — so the binder never slides for it.
+// AUTH-1 (c).
+const sseEventsPath = "/api/v1/events"
+
 // authBypassPaths are credential-lifecycle endpoints where the binder
 // MUST NOT 401 on a stale session cookie — they handle their own
 // credential semantics. Login does not need any cookie; logout is
@@ -136,7 +150,16 @@ func writeSessionInvalid(w http.ResponseWriter, r *http.Request, reason string)
 // presented-but-rejected credentials).
 func resolveIdentity(ctx context.Context, pool *pgxpool.Pool, lookups Lookups, cfg binderConfig, r *http.Request) (auth.Identity, string) {
 	if cookie, err := r.Cookie(SessionCookieName); err == nil && cookie.Value != "" {
-		sess, err := VerifySession(ctx, pool, cookie.Value)
+		// AUTH-1 (c): the client marks NON-user-initiated requests (background
+		// polling, SSE) with X-Background-Refresh so the server does not slide
+		// the idle window for them — idle then tracks real user activity, not
+		// HTTP traffic. Fail-safe: an unmarked request slides as before, so a
+		// client that does not send the header is unaffected.
+		var vopts []VerifyOption
+		if r.Header.Get(BackgroundRefreshHeader) == "1" || r.URL.Path == sseEventsPath {
+			vopts = append(vopts, WithoutSlide())
+		}
+		sess, err := VerifySession(ctx, pool, cookie.Value, vopts...)
 		switch {
 		case errors.Is(err, ErrSessionNotFound):
 			return anon(), "invalid_session_token"

internal/identity/binder_test.go

@@ -159,5 +159,72 @@ func TestBinder_ExpiredSession_Writes401(t *testing.T) {
 	})
 }
 
+// @ac AC-31
+// AC-31 (AUTH-1 c): the binder slides the idle window only on user-initiated
+// requests. A request carrying X-Background-Refresh validates the session but
+// does NOT advance expires_at; an unmarked request does.
+func TestBinder_SlideOnlyOnUserActivity(t *testing.T) {
+	t.Run("system-auth-identity/AC-31", func(t *testing.T) {
+		pool := freshPool(t)
+		userID := seedUser(t, pool, "slide-binder")
+		token, sess, err := IssueSession(context.Background(), pool, userID, "127.0.0.1", "ua")
+		if err != nil {
+			t.Fatalf("issue: %v", err)
+		}
+		// Backdate expires_at so a slide is observable.
+		if _, err := pool.Exec(context.Background(),
+			`UPDATE sessions SET expires_at = expires_at - interval '10 minutes' WHERE id = $1`,
+			sess.ID); err != nil {
+			t.Fatalf("backdate: %v", err)
+		}
+		readExpiry := func() time.Time {
+			var e time.Time
+			if err := pool.QueryRow(context.Background(),
+				`SELECT expires_at FROM sessions WHERE id = $1`, sess.ID).Scan(&e); err != nil {
+				t.Fatalf("read expiry: %v", err)
+			}
+			return e
+		}
+		h := Binder(pool, adminLookups)(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			w.WriteHeader(http.StatusOK)
+		}))
+		do := func(background bool) {
+			req := httptest.NewRequest(http.MethodGet, "/api/v1/hosts", nil)
+			req.AddCookie(&http.Cookie{Name: SessionCookieName, Value: token})
+			if background {
+				req.Header.Set(BackgroundRefreshHeader, "1")
+			}
+			rr := httptest.NewRecorder()
+			h.ServeHTTP(rr, req)
+			if rr.Code != http.StatusOK {
+				t.Fatalf("status: want 200, got %d", rr.Code)
+			}
+		}
+
+		before := readExpiry()
+		// Background request must NOT slide.
+		do(true)
+		if got := readExpiry(); !got.Equal(before) {
+			t.Errorf("background request slid the window: before=%v after=%v", before, got)
+		}
+		// User-initiated request must slide.
+		do(false)
+		if got := readExpiry(); !got.After(before) {
+			t.Errorf("user request did not slide the window: before=%v after=%v", before, got)
+		}
+
+		// The SSE events stream must NOT slide — it cannot send the header but
+		// is a long-lived background subscription.
+		afterUser := readExpiry()
+		req := httptest.NewRequest(http.MethodGet, sseEventsPath, nil)
+		req.AddCookie(&http.Cookie{Name: SessionCookieName, Value: token})
+		rr := httptest.NewRecorder()
+		h.ServeHTTP(rr, req)
+		if got := readExpiry(); !got.Equal(afterUser) {
+			t.Errorf("SSE request slid the window: before=%v after=%v", afterUser, got)
+		}
+	})
+}
+
 // Silence the unused-import warning when the test runs without DB.
 var _ = pgxpool.Config{}

internal/identity/jwt_test.go

@@ -84,7 +84,7 @@ func TestRefresh_RotationOnConsume(t *testing.T) {
 		userID := seedUser(t, pool, "ac12-user")
 
 		// Issue an initial refresh token.
-		refresh1, err := IssueRefreshToken(context.Background(), pool, userID)
+		refresh1, err := IssueRefreshToken(context.Background(), pool, userID, time.Now().UTC().Add(12*time.Hour))
 		if err != nil {
 			t.Fatalf("IssueRefreshToken: %v", err)
 		}
@@ -135,7 +135,7 @@ func TestRefresh_ReuseDetectionCascadeRevokes(t *testing.T) {
 			t.Fatalf("IssueSession: %v", err)
 		}
 
-		refresh1, err := IssueRefreshToken(context.Background(), pool, userID)
+		refresh1, err := IssueRefreshToken(context.Background(), pool, userID, time.Now().UTC().Add(12*time.Hour))
 		if err != nil {
 			t.Fatalf("IssueRefreshToken: %v", err)
 		}

internal/identity/refresh.go

@@ -25,6 +25,11 @@ var (
 	ErrRefreshTokenExpired  = errors.New("identity: refresh token expired")
 	ErrRefreshTokenRevoked  = errors.New("identity: refresh token revoked")
 	ErrRefreshTokenReused   = errors.New("identity: refresh token reuse detected")
+	// ErrRefreshSessionExpired — the refresh token is still inside its 7-day
+	// window, but the session's ABSOLUTE deadline (carried through the lineage
+	// from login) has passed. Refresh is refused; the user must re-authenticate.
+	// AUTH-1 (b).
+	ErrRefreshSessionExpired = errors.New("identity: session absolute timeout reached")
 )
 
 // RevokeRefreshToken marks the row identified by presentation-token as
@@ -50,8 +55,14 @@ func RevokeRefreshToken(ctx context.Context, pool *pgxpool.Pool, token string) e
 // presentation token. Token is stored as SHA-256 hash; presentation
 // form is never in the DB.
 //
+// absoluteExpiresAt is the session's absolute deadline (login time + the
+// configured absolute window). It is carried through every rotation so the
+// session cannot be refreshed past it (AUTH-1 b). A zero value stores NULL —
+// the legacy "no absolute ceiling" behavior, used only by callers that have no
+// session deadline to anchor to.
+//
 // Spec AC-12.
-func IssueRefreshToken(ctx context.Context, pool *pgxpool.Pool, userID uuid.UUID) (token string, err error) {
+func IssueRefreshToken(ctx context.Context, pool *pgxpool.Pool, userID uuid.UUID, absoluteExpiresAt time.Time) (token string, err error) {
 	raw := make([]byte, 32)
 	if _, err := rand.Read(raw); err != nil {
 		return "", fmt.Errorf("identity: refresh entropy: %w", err)
@@ -64,21 +75,36 @@ func IssueRefreshToken(ctx context.Context, pool *pgxpool.Pool, userID uuid.UUID
 		return "", fmt.Errorf("identity: uuid: %w", err)
 	}
 	const stmt = `
-		INSERT INTO refresh_tokens (id, user_id, token_hash, expires_at)
-		VALUES ($1, $2, $3, $4)`
-	if _, err := pool.Exec(ctx, stmt, id, userID, hash[:], time.Now().UTC().Add(RefreshTokenWindow)); err != nil {
+		INSERT INTO refresh_tokens (id, user_id, token_hash, expires_at, absolute_expires_at)
+		VALUES ($1, $2, $3, $4, $5)`
+	if _, err := pool.Exec(ctx, stmt, id, userID, hash[:],
+		time.Now().UTC().Add(RefreshTokenWindow), nullableTime(absoluteExpiresAt)); err != nil {
 		return "", fmt.Errorf("identity: insert refresh: %w", err)
 	}
 	return token, nil
 }
 
+// nullableTime returns nil for the zero time (stored as SQL NULL) or the time
+// otherwise — so a missing absolute deadline is recorded honestly as "none".
+func nullableTime(t time.Time) any {
+	if t.IsZero() {
+		return nil
+	}
+	return t
+}
+
 // TokenPair is the result of a successful ConsumeRefreshToken call —
 // a new access JWT plus a new refresh token. The caller delivers both
 // to the client; the old refresh token is now revoked.
 type TokenPair struct {
 	AccessToken  string
 	RefreshToken string
 	Claims       Claims
+	// AbsoluteExpiresAt is the session's carried absolute deadline (AUTH-1 b),
+	// zero when the consumed token had none (legacy). The cookie-refresh handler
+	// stamps it onto the re-minted session so the absolute ceiling is preserved
+	// across refreshes rather than reset.
+	AbsoluteExpiresAt time.Time
 }
 
 // ConsumeRefreshToken atomically:
@@ -106,17 +132,18 @@ func ConsumeRefreshToken(ctx context.Context, pool *pgxpool.Pool, token, role st
 	defer func() { _ = tx.Rollback(ctx) }()
 
 	var (
-		rowID     uuid.UUID
-		userID    uuid.UUID
-		expiresAt time.Time
-		rotatedTo *uuid.UUID
-		revokedAt *time.Time
+		rowID       uuid.UUID
+		userID      uuid.UUID
+		expiresAt   time.Time
+		absoluteExp *time.Time
+		rotatedTo   *uuid.UUID
+		revokedAt   *time.Time
 	)
 	err = tx.QueryRow(ctx, `
-		SELECT id, user_id, expires_at, rotated_to_id, revoked_at
+		SELECT id, user_id, expires_at, absolute_expires_at, rotated_to_id, revoked_at
 		FROM refresh_tokens WHERE token_hash = $1 FOR UPDATE`,
 		hash[:],
-	).Scan(&rowID, &userID, &expiresAt, &rotatedTo, &revokedAt)
+	).Scan(&rowID, &userID, &expiresAt, &absoluteExp, &rotatedTo, &revokedAt)
 	if err != nil {
 		if errors.Is(err, pgx.ErrNoRows) {
 			return nil, ErrRefreshTokenNotFound
@@ -130,6 +157,13 @@ func ConsumeRefreshToken(ctx context.Context, pool *pgxpool.Pool, token, role st
 	if time.Now().UTC().After(expiresAt) {
 		return nil, ErrRefreshTokenExpired
 	}
+	// AUTH-1 (b): the session's absolute deadline is a hard ceiling. Once it
+	// passes, the chain ends even though the 7-day refresh window is still
+	// open. Legacy tokens (absolute_expires_at NULL) are exempt until they age
+	// out. Checked before reuse so an expired-session token simply fails closed.
+	if absoluteExp != nil && time.Now().UTC().After(*absoluteExp) {
+		return nil, ErrRefreshSessionExpired
+	}
 	if rotatedTo != nil {
 		// Reuse! This row was already consumed. An attacker has the old
 		// presentation token. Revoke everything for this user.
@@ -167,10 +201,12 @@ func ConsumeRefreshToken(ctx context.Context, pool *pgxpool.Pool, token, role st
 	if err != nil {
 		return nil, fmt.Errorf("identity: uuid: %w", err)
 	}
+	// Carry the original absolute deadline UNCHANGED onto the rotated row, so
+	// the absolute ceiling cannot be reset by refreshing (AUTH-1 b).
 	if _, err := tx.Exec(ctx, `
-		INSERT INTO refresh_tokens (id, user_id, token_hash, expires_at)
-		VALUES ($1, $2, $3, $4)`,
-		newID, userID, newHash[:], time.Now().UTC().Add(RefreshTokenWindow),
+		INSERT INTO refresh_tokens (id, user_id, token_hash, expires_at, absolute_expires_at)
+		VALUES ($1, $2, $3, $4, $5)`,
+		newID, userID, newHash[:], time.Now().UTC().Add(RefreshTokenWindow), absoluteExp,
 	); err != nil {
 		return nil, fmt.Errorf("identity: insert rotated refresh: %w", err)
 	}
@@ -188,9 +224,13 @@ func ConsumeRefreshToken(ctx context.Context, pool *pgxpool.Pool, token, role st
 	if err := tx.Commit(ctx); err != nil {
 		return nil, fmt.Errorf("identity: refresh commit (happy): %w", err)
 	}
-	return &TokenPair{
+	pair := &TokenPair{
 		AccessToken:  access,
 		RefreshToken: newPres,
 		Claims:       claims,
-	}, nil
+	}
+	if absoluteExp != nil {
+		pair.AbsoluteExpiresAt = *absoluteExp
+	}
+	return pair, nil
 }