feat(auth): enforce session idle and absolute timeouts (#1387)

* feat(auth): enforce session idle and absolute timeouts Hosted browser sessions now carry an HMAC-signed, HttpOnly cookie holding session start, last activity and sign-in method, bound to the Supabase session. Middleware enforces a 30 min idle and 12 h absolute limit (reason-coded redirects to /login), a heartbeat route advances idle activity from real user input, and a client controller warns 2 minutes before expiry. BankID users are routed back to BankID on re-auth via a short-lived method hint. API-key and MCP bearer surfaces are exempt; self-hosted installs default off and can opt in via env vars. Fixes #362 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(auth): derive session-timeout signing key via HKDF The HMAC key is now HKDF-derived with a purpose-bound info string, so the SUPABASE_SERVICE_ROLE_KEY fallback never uses the privileged credential directly as a signing key. Addresses the security review finding on PR #1387. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(auth): back signature bytes with a plain ArrayBuffer crypto.subtle.verify requires a BufferSource; Uint8Array.from is typed over ArrayBufferLike, which the Vercel TypeScript build rejects. Decode base64url into a Uint8Array constructed over a fresh ArrayBuffer. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(auth): address session-timeout review findings - signSessionTimeoutState returns null on signing failure instead of throwing, so a missing secret degrades the timeout feature in line with verifySessionTimeoutState rather than crashing authenticated requests; middleware and heartbeat skip the cookie write when null - heartbeat initializes a fresh signed state for a missing or session-mismatched cookie, mirroring middleware, instead of returning SESSION_EXPIRED during normal initialization - sessionStateMatchesUser treats an unresolved current session id as a mismatch for session-bound state so another session's cookie is never accepted on the userId fallback alone - drop aria-live from the countdown DialogDescription so screen readers are not interrupted every second Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-04 09:59:42 +02:00
parent f55bfc478b
commit 1c9d378df8
21 changed files with 1610 additions and 13 deletions
@@ -0,0 +1,193 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  apiRequestSkipsSessionTimeout,
+  createSessionTimeoutState,
+  evaluateSessionTimeout,
+  getSessionTimeoutConfig,
+  sessionStateMatchesUser,
+  signSessionTimeoutState,
+  verifySessionTimeoutState,
+} from '../session-timeout'
+
+const SIGNING_ENV = { SESSION_TIMEOUT_SECRET: 'test-session-timeout-secret' }
+
+describe('session timeout configuration', () => {
+  afterEach(() => vi.unstubAllEnvs())
+
+  it('uses banking-style defaults for hosted deployments', () => {
+    expect(getSessionTimeoutConfig({})).toEqual({
+      enabled: true,
+      idleTimeoutMs: 30 * 60 * 1000,
+      absoluteTimeoutMs: 12 * 60 * 60 * 1000,
+      warningMs: 2 * 60 * 1000,
+    })
+  })
+
+  it('is disabled by default for self-hosted deployments', () => {
+    expect(getSessionTimeoutConfig({ NEXT_PUBLIC_SELF_HOSTED: 'true' })).toEqual({
+      enabled: false,
+      idleTimeoutMs: 0,
+      absoluteTimeoutMs: 0,
+      warningMs: 0,
+    })
+  })
+
+  it('allows self-hosted deployments to opt in and bounds the warning', () => {
+    expect(getSessionTimeoutConfig({
+      NEXT_PUBLIC_SELF_HOSTED: 'true',
+      NEXT_PUBLIC_SESSION_IDLE_TIMEOUT_MS: '60000',
+      NEXT_PUBLIC_SESSION_WARNING_MS: '120000',
+    })).toEqual({
+      enabled: true,
+      idleTimeoutMs: 60000,
+      absoluteTimeoutMs: 0,
+      warningMs: 60000,
+    })
+  })
+
+  it('warns when only the absolute limit is enabled', () => {
+    expect(getSessionTimeoutConfig({
+      NEXT_PUBLIC_SELF_HOSTED: 'true',
+      NEXT_PUBLIC_SESSION_ABSOLUTE_TIMEOUT_MS: '60000',
+      NEXT_PUBLIC_SESSION_WARNING_MS: '10000',
+    })).toEqual({
+      enabled: true,
+      idleTimeoutMs: 0,
+      absoluteTimeoutMs: 60000,
+      warningMs: 10000,
+    })
+  })
+
+  it('ignores negative and non-integer overrides', () => {
+    expect(getSessionTimeoutConfig({
+      NEXT_PUBLIC_SESSION_IDLE_TIMEOUT_MS: '-1',
+      NEXT_PUBLIC_SESSION_ABSOLUTE_TIMEOUT_MS: '12.5',
+    })).toMatchObject({
+      idleTimeoutMs: 30 * 60 * 1000,
+      absoluteTimeoutMs: 12 * 60 * 60 * 1000,
+    })
+  })
+})
+
+describe('signed session timeout state', () => {
+  it('round-trips an authentic state', async () => {
+    const state = createSessionTimeoutState({
+      userId: 'user-1',
+      sessionId: 'session-1',
+      method: 'bankid',
+      now: 1000,
+    })
+
+    const signed = await signSessionTimeoutState(state, SIGNING_ENV)
+
+    expect(signed).not.toBeNull()
+    await expect(verifySessionTimeoutState(signed!, SIGNING_ENV)).resolves.toEqual(state)
+  })
+
+  it('returns null instead of throwing when no signing secret is configured', async () => {
+    const state = createSessionTimeoutState({
+      userId: 'user-1',
+      sessionId: 'session-1',
+      method: 'password',
+      now: 1000,
+    })
+
+    await expect(signSessionTimeoutState(state, {})).resolves.toBeNull()
+  })
+
+  it('rejects payload and signature tampering', async () => {
+    const state = createSessionTimeoutState({
+      userId: 'user-1',
+      sessionId: 'session-1',
+      method: 'password',
+      now: 1000,
+    })
+    const signed = await signSessionTimeoutState(state, SIGNING_ENV)
+    const [payload, signature] = signed!.split('.')
+
+    await expect(
+      verifySessionTimeoutState(`${payload}x.${signature}`, SIGNING_ENV),
+    ).resolves.toBeNull()
+    await expect(
+      verifySessionTimeoutState(`${payload}.${signature.slice(0, -1)}x`, SIGNING_ENV),
+    ).resolves.toBeNull()
+  })
+
+  it('binds state to both the user and Supabase session', () => {
+    const state = createSessionTimeoutState({
+      userId: 'user-1',
+      sessionId: 'session-1',
+      method: 'password',
+      now: 1000,
+    })
+
+    expect(sessionStateMatchesUser(state, 'user-1', 'session-1')).toBe(true)
+    expect(sessionStateMatchesUser(state, 'user-2', 'session-1')).toBe(false)
+    expect(sessionStateMatchesUser(state, 'user-1', 'session-2')).toBe(false)
+  })
+
+  it('treats an unresolved current session id as a mismatch for bound state', () => {
+    const bound = createSessionTimeoutState({
+      userId: 'user-1',
+      sessionId: 'session-1',
+      method: 'password',
+      now: 1000,
+    })
+    const unbound = createSessionTimeoutState({
+      userId: 'user-1',
+      sessionId: null,
+      method: 'password',
+      now: 1000,
+    })
+
+    expect(sessionStateMatchesUser(bound, 'user-1', null)).toBe(false)
+    expect(sessionStateMatchesUser(unbound, 'user-1', null)).toBe(true)
+    expect(sessionStateMatchesUser(unbound, 'user-1', 'session-2')).toBe(true)
+  })
+})
+
+describe('session expiry', () => {
+  const config = {
+    enabled: true,
+    idleTimeoutMs: 30_000,
+    absoluteTimeoutMs: 60_000,
+    warningMs: 10_000,
+  }
+
+  it('uses inclusive boundaries and gives absolute expiry precedence', () => {
+    const state = {
+      ...createSessionTimeoutState({
+        userId: 'user-1',
+        sessionId: 'session-1',
+        method: 'password' as const,
+        now: 1000,
+      }),
+      lastActivityAt: 31_000,
+    }
+
+    expect(evaluateSessionTimeout(state, config, 60_999)).toBeNull()
+    expect(evaluateSessionTimeout(state, config, 61_000)).toBe('absolute')
+  })
+
+  it('expires an otherwise valid session after the idle limit', () => {
+    const state = createSessionTimeoutState({
+      userId: 'user-1',
+      sessionId: null,
+      method: 'password',
+      now: 1000,
+    })
+
+    expect(evaluateSessionTimeout(state, config, 30_999)).toBeNull()
+    expect(evaluateSessionTimeout(state, config, 31_000)).toBe('idle')
+  })
+})
+
+describe('API exclusions', () => {
+  it('only lets bearer-authenticated machine surfaces bypass timeouts', () => {
+    expect(apiRequestSkipsSessionTimeout('/api/v1/companies/c1/invoices', true)).toBe(true)
+    expect(apiRequestSkipsSessionTimeout('/api/v1/companies/c1/invoices', false)).toBe(false)
+    expect(apiRequestSkipsSessionTimeout('/api/invoices', true)).toBe(false)
+    expect(apiRequestSkipsSessionTimeout('/api/mcp-oauth/token', false)).toBe(true)
+    expect(apiRequestSkipsSessionTimeout('/api/health', false)).toBe(true)
+  })
+})
@@ -0,0 +1,28 @@
+export const SESSION_TIMEOUT_COOKIE = 'gnubok-session-timeout'
+export const SESSION_AUTH_METHOD_HINT_COOKIE = 'gnubok-auth-method'
+export const SESSION_TIMEOUT_CHANNEL = 'gnubok-session-timeout'
+
+export type SessionAuthMethod = 'password' | 'bankid'
+export type SessionTimeoutReason = 'idle' | 'absolute'
+
+export interface SessionTimeoutClientState {
+  enabled: boolean
+  idleTimeoutMs: number
+  absoluteTimeoutMs: number
+  warningMs: number
+  serverNow: number
+  startedAt: number
+  lastActivityAt: number
+  method: SessionAuthMethod
+}
+
+export function isSessionAuthMethod(value: unknown): value is SessionAuthMethod {
+  return value === 'password' || value === 'bankid'
+}
+
+export function setSessionAuthMethodHint(method: SessionAuthMethod): void {
+  if (typeof document === 'undefined') return
+
+  const secure = window.location.protocol === 'https:' ? '; Secure' : ''
+  document.cookie = `${SESSION_AUTH_METHOD_HINT_COOKIE}=${method}; Path=/; Max-Age=300; SameSite=Lax${secure}`
+}
@@ -0,0 +1,330 @@
+import {
+  SESSION_TIMEOUT_COOKIE,
+  type SessionAuthMethod,
+  type SessionTimeoutClientState,
+  type SessionTimeoutReason,
+} from './session-timeout-shared'
+
+const DEFAULT_IDLE_TIMEOUT_MS = 30 * 60 * 1000
+const DEFAULT_ABSOLUTE_TIMEOUT_MS = 12 * 60 * 60 * 1000
+const DEFAULT_WARNING_MS = 2 * 60 * 1000
+const COOKIE_MAX_AGE_SECONDS = 365 * 24 * 60 * 60
+const SIGNING_CONTEXT = 'accounted-session-timeout-v1:'
+
+export interface SessionTimeoutConfig {
+  enabled: boolean
+  idleTimeoutMs: number
+  absoluteTimeoutMs: number
+  warningMs: number
+}
+
+export interface SessionTimeoutState {
+  version: 1
+  userId: string
+  sessionId: string | null
+  startedAt: number
+  lastActivityAt: number
+  method: SessionAuthMethod
+}
+
+type Environment = Record<string, string | undefined>
+
+function parseDuration(value: string | undefined, fallback: number): number {
+  if (value === undefined || value.trim() === '') return fallback
+
+  const parsed = Number(value)
+  if (!Number.isSafeInteger(parsed) || parsed < 0) return fallback
+  return parsed
+}
+
+export function getSessionTimeoutConfig(
+  env: Environment = process.env,
+): SessionTimeoutConfig {
+  const defaultTimeout = env.NEXT_PUBLIC_SELF_HOSTED === 'true' ? 0 : undefined
+  const idleTimeoutMs = parseDuration(
+    env.NEXT_PUBLIC_SESSION_IDLE_TIMEOUT_MS,
+    defaultTimeout ?? DEFAULT_IDLE_TIMEOUT_MS,
+  )
+  const absoluteTimeoutMs = parseDuration(
+    env.NEXT_PUBLIC_SESSION_ABSOLUTE_TIMEOUT_MS,
+    defaultTimeout ?? DEFAULT_ABSOLUTE_TIMEOUT_MS,
+  )
+  const configuredWarningMs = parseDuration(
+    env.NEXT_PUBLIC_SESSION_WARNING_MS,
+    DEFAULT_WARNING_MS,
+  )
+  const enabledTimeouts = [idleTimeoutMs, absoluteTimeoutMs]
+    .filter((timeout) => timeout > 0)
+  const warningMs = enabledTimeouts.length > 0
+    ? Math.min(configuredWarningMs, ...enabledTimeouts)
+    : 0
+
+  return {
+    enabled: idleTimeoutMs > 0 || absoluteTimeoutMs > 0,
+    idleTimeoutMs,
+    absoluteTimeoutMs,
+    warningMs,
+  }
+}
+
+export function createSessionTimeoutState(args: {
+  userId: string
+  sessionId: string | null
+  method: SessionAuthMethod
+  now?: number
+}): SessionTimeoutState {
+  const now = args.now ?? Date.now()
+  return {
+    version: 1,
+    userId: args.userId,
+    sessionId: args.sessionId,
+    startedAt: now,
+    lastActivityAt: now,
+    method: args.method,
+  }
+}
+
+export function evaluateSessionTimeout(
+  state: SessionTimeoutState,
+  config: SessionTimeoutConfig,
+  now = Date.now(),
+): SessionTimeoutReason | null {
+  if (
+    config.absoluteTimeoutMs > 0 &&
+    now - state.startedAt >= config.absoluteTimeoutMs
+  ) {
+    return 'absolute'
+  }
+
+  if (
+    config.idleTimeoutMs > 0 &&
+    now - state.lastActivityAt >= config.idleTimeoutMs
+  ) {
+    return 'idle'
+  }
+
+  return null
+}
+
+function getSigningSecret(env: Environment): string {
+  const dedicated = env.SESSION_TIMEOUT_SECRET?.trim()
+  if (dedicated) return dedicated
+
+  const serviceRole = env.SUPABASE_SERVICE_ROLE_KEY?.trim()
+  if (serviceRole) return serviceRole
+
+  throw new Error(
+    'Session timeout enforcement requires SESSION_TIMEOUT_SECRET or SUPABASE_SERVICE_ROLE_KEY',
+  )
+}
+
+function bytesToBase64Url(bytes: Uint8Array): string {
+  let binary = ''
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary)
+    .replaceAll('+', '-')
+    .replaceAll('/', '_')
+    .replace(/=+$/u, '')
+}
+
+function base64UrlToBytes(value: string): Uint8Array<ArrayBuffer> | null {
+  try {
+    const base64 = value.replaceAll('-', '+').replaceAll('_', '/')
+    const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, '=')
+    const binary = atob(padded)
+    const bytes = new Uint8Array(binary.length)
+    for (let index = 0; index < binary.length; index += 1) {
+      bytes[index] = binary.charCodeAt(index)
+    }
+    return bytes
+  } catch {
+    return null
+  }
+}
+
+function encodePayload(state: SessionTimeoutState): string {
+  return bytesToBase64Url(new TextEncoder().encode(JSON.stringify(state)))
+}
+
+function decodePayload(payload: string): unknown {
+  const bytes = base64UrlToBytes(payload)
+  if (!bytes) return null
+
+  try {
+    return JSON.parse(new TextDecoder().decode(bytes))
+  } catch {
+    return null
+  }
+}
+
+function isValidState(value: unknown): value is SessionTimeoutState {
+  if (!value || typeof value !== 'object') return false
+  const state = value as Partial<SessionTimeoutState>
+
+  return (
+    state.version === 1 &&
+    typeof state.userId === 'string' &&
+    state.userId.length > 0 &&
+    (state.sessionId === null || typeof state.sessionId === 'string') &&
+    Number.isSafeInteger(state.startedAt) &&
+    Number.isSafeInteger(state.lastActivityAt) &&
+    (state.method === 'password' || state.method === 'bankid') &&
+    (state.startedAt as number) > 0 &&
+    (state.lastActivityAt as number) >= (state.startedAt as number)
+  )
+}
+
+async function importSigningKey(secret: string): Promise<CryptoKey> {
+  // The signing key is HKDF-derived with a purpose-bound info string, never
+  // the raw secret: the SUPABASE_SERVICE_ROLE_KEY fallback must not use the
+  // privileged credential itself as an HMAC key.
+  const baseKey = await crypto.subtle.importKey(
+    'raw',
+    new TextEncoder().encode(secret),
+    'HKDF',
+    false,
+    ['deriveKey'],
+  )
+  return crypto.subtle.deriveKey(
+    {
+      name: 'HKDF',
+      hash: 'SHA-256',
+      salt: new Uint8Array(32),
+      info: new TextEncoder().encode(SIGNING_CONTEXT),
+    },
+    baseKey,
+    { name: 'HMAC', hash: 'SHA-256', length: 256 },
+    false,
+    ['sign', 'verify'],
+  )
+}
+
+export async function signSessionTimeoutState(
+  state: SessionTimeoutState,
+  env: Environment = process.env,
+): Promise<string | null> {
+  // A missing signing secret must degrade the timeout feature, never crash
+  // authenticated requests: verifySessionTimeoutState already returns null in
+  // the same misconfiguration, so returning null here keeps both halves of
+  // the feature consistently disabled.
+  try {
+    const payload = encodePayload(state)
+    const key = await importSigningKey(getSigningSecret(env))
+    const signature = await crypto.subtle.sign(
+      'HMAC',
+      key,
+      new TextEncoder().encode(`${SIGNING_CONTEXT}${payload}`),
+    )
+    return `${payload}.${bytesToBase64Url(new Uint8Array(signature))}`
+  } catch (error) {
+    console.error(
+      '[session-timeout] signing failed; timeout state not persisted',
+      error,
+    )
+    return null
+  }
+}
+
+export async function verifySessionTimeoutState(
+  value: string | undefined,
+  env: Environment = process.env,
+): Promise<SessionTimeoutState | null> {
+  if (!value) return null
+  const [payload, signature, extra] = value.split('.')
+  if (!payload || !signature || extra !== undefined) return null
+
+  const signatureBytes = base64UrlToBytes(signature)
+  if (!signatureBytes) return null
+
+  try {
+    const key = await importSigningKey(getSigningSecret(env))
+    const valid = await crypto.subtle.verify(
+      'HMAC',
+      key,
+      signatureBytes,
+      new TextEncoder().encode(`${SIGNING_CONTEXT}${payload}`),
+    )
+    if (!valid) return null
+  } catch {
+    return null
+  }
+
+  const state = decodePayload(payload)
+  return isValidState(state) ? state : null
+}
+
+interface SessionTimeoutCookieOptions {
+  path: '/'
+  httpOnly: true
+  secure: boolean
+  sameSite: 'lax'
+  maxAge: number
+}
+
+export function sessionTimeoutCookieOptions(): SessionTimeoutCookieOptions {
+  return {
+    path: '/',
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'lax',
+    maxAge: COOKIE_MAX_AGE_SECONDS,
+  }
+}
+
+export function sessionTimeoutClearCookieOptions(): SessionTimeoutCookieOptions {
+  return {
+    ...sessionTimeoutCookieOptions(),
+    maxAge: 0,
+  }
+}
+
+export function toSessionTimeoutClientState(
+  state: SessionTimeoutState,
+  config: SessionTimeoutConfig,
+  serverNow = Date.now(),
+): SessionTimeoutClientState {
+  return {
+    enabled: config.enabled,
+    idleTimeoutMs: config.idleTimeoutMs,
+    absoluteTimeoutMs: config.absoluteTimeoutMs,
+    warningMs: config.warningMs,
+    serverNow,
+    startedAt: state.startedAt,
+    lastActivityAt: state.lastActivityAt,
+    method: state.method,
+  }
+}
+
+export function sessionStateMatchesUser(
+  state: SessionTimeoutState,
+  userId: string,
+  sessionId: string | null,
+): boolean {
+  if (state.userId !== userId) return false
+  if (state.sessionId === null) return true
+  // The state is bound to a specific Supabase session. If the current session
+  // id cannot be resolved it is unknown, not a wildcard: report a mismatch so
+  // the caller mints a fresh state instead of accepting another session's.
+  if (sessionId === null) return false
+  return state.sessionId === sessionId
+}
+
+export function apiRequestSkipsSessionTimeout(
+  pathname: string,
+  hasAuthorizationHeader: boolean,
+): boolean {
+  if (
+    pathname === '/api/health' ||
+    pathname === '/api/log' ||
+    pathname.startsWith('/api/mcp-oauth/')
+  ) {
+    return true
+  }
+
+  return hasAuthorizationHeader && (
+    pathname.startsWith('/api/v1/') ||
+    pathname.startsWith('/api/extensions/ext/mcp-server/mcp')
+  )
+}
+
+export { SESSION_TIMEOUT_COOKIE }
@@ -11,6 +11,7 @@ import { NextRequest } from 'next/server'

 const state = vi.hoisted(() => ({
  user: null as null | { id: string; app_metadata?: Record<string, unknown> },
+  sessionId: 'session-1' as string | null,
  authError: null as unknown,
  aal: null as null | { currentLevel: string; nextLevel: string },
  factors: null as null | { totp: Array<{ id: string; status: string }> },
@@ -25,6 +26,7 @@ const state = vi.hoisted(() => ({
    }>
    error: unknown
  },
+  signOut: vi.fn(async () => ({ error: null })),
 }))

 vi.mock('@supabase/ssr', () => ({
@@ -34,7 +36,10 @@ vi.mock('@supabase/ssr', () => ({
        data: { user: state.user },
        error: state.authError,
      })),
-      signOut: vi.fn(async () => ({ error: null })),
+      getClaims: vi.fn(async () => ({
+        data: { claims: state.sessionId ? { session_id: state.sessionId } : {} },
+      })),
+      signOut: state.signOut,
      mfa: {
        getAuthenticatorAssuranceLevel: vi.fn(async () => ({ data: state.aal })),
        listFactors: vi.fn(async () => ({ data: state.factors })),
@@ -58,6 +63,12 @@ vi.mock('@supabase/ssr', () => ({
 }))

 import { updateSession } from '../middleware'
+import {
+  createSessionTimeoutState,
+  signSessionTimeoutState,
+  verifySessionTimeoutState,
+} from '@/lib/auth/session-timeout'
+import { SESSION_TIMEOUT_COOKIE } from '@/lib/auth/session-timeout-shared'

 const ORIGIN = 'http://localhost:3000'
 const SIGNED_IN = { id: 'user-1', app_metadata: {} }
@@ -66,19 +77,24 @@ function locationOf(response: Response) {
  return response.headers.get('location')
 }

-function run(path: string) {
-  return updateSession(new NextRequest(`${ORIGIN}${path}`))
+function run(path: string, init?: RequestInit) {
+  return updateSession(new NextRequest(`${ORIGIN}${path}`, init))
 }

 describe('updateSession redirect destinations', () => {
  const envBackup = {
    require: process.env.NEXT_PUBLIC_REQUIRE_MFA,
    selfHosted: process.env.NEXT_PUBLIC_SELF_HOSTED,
+    signingSecret: process.env.SESSION_TIMEOUT_SECRET,
+    idleTimeout: process.env.NEXT_PUBLIC_SESSION_IDLE_TIMEOUT_MS,
+    absoluteTimeout: process.env.NEXT_PUBLIC_SESSION_ABSOLUTE_TIMEOUT_MS,
+    warning: process.env.NEXT_PUBLIC_SESSION_WARNING_MS,
  }

  beforeEach(() => {
    vi.clearAllMocks()
    state.user = null
+    state.sessionId = 'session-1'
    state.authError = null
    state.aal = null
    state.factors = null
@@ -88,6 +104,10 @@ describe('updateSession redirect destinations', () => {
    }
    delete process.env.NEXT_PUBLIC_REQUIRE_MFA
    delete process.env.NEXT_PUBLIC_SELF_HOSTED
+    process.env.SESSION_TIMEOUT_SECRET = 'middleware-test-secret'
+    delete process.env.NEXT_PUBLIC_SESSION_IDLE_TIMEOUT_MS
+    delete process.env.NEXT_PUBLIC_SESSION_ABSOLUTE_TIMEOUT_MS
+    delete process.env.NEXT_PUBLIC_SESSION_WARNING_MS
  })

  afterEach(() => {
@@ -95,6 +115,138 @@ describe('updateSession redirect destinations', () => {
    else process.env.NEXT_PUBLIC_REQUIRE_MFA = envBackup.require
    if (envBackup.selfHosted === undefined) delete process.env.NEXT_PUBLIC_SELF_HOSTED
    else process.env.NEXT_PUBLIC_SELF_HOSTED = envBackup.selfHosted
+    if (envBackup.signingSecret === undefined) delete process.env.SESSION_TIMEOUT_SECRET
+    else process.env.SESSION_TIMEOUT_SECRET = envBackup.signingSecret
+    if (envBackup.idleTimeout === undefined) delete process.env.NEXT_PUBLIC_SESSION_IDLE_TIMEOUT_MS
+    else process.env.NEXT_PUBLIC_SESSION_IDLE_TIMEOUT_MS = envBackup.idleTimeout
+    if (envBackup.absoluteTimeout === undefined) delete process.env.NEXT_PUBLIC_SESSION_ABSOLUTE_TIMEOUT_MS
+    else process.env.NEXT_PUBLIC_SESSION_ABSOLUTE_TIMEOUT_MS = envBackup.absoluteTimeout
+    if (envBackup.warning === undefined) delete process.env.NEXT_PUBLIC_SESSION_WARNING_MS
+    else process.env.NEXT_PUBLIC_SESSION_WARNING_MS = envBackup.warning
+  })
+
+  describe('session timeout enforcement', () => {
+    beforeEach(() => {
+      state.user = SIGNED_IN
+      process.env.NEXT_PUBLIC_SESSION_IDLE_TIMEOUT_MS = '30000'
+      process.env.NEXT_PUBLIC_SESSION_ABSOLUTE_TIMEOUT_MS = '60000'
+      process.env.NEXT_PUBLIC_SESSION_WARNING_MS = '10000'
+    })
+
+    async function signedCookie(args?: {
+      startedAt?: number
+      lastActivityAt?: number
+      method?: 'password' | 'bankid'
+      userId?: string
+      sessionId?: string | null
+    }) {
+      const stateValue = {
+        ...createSessionTimeoutState({
+          userId: args?.userId ?? 'user-1',
+          sessionId: args?.sessionId === undefined ? 'session-1' : args.sessionId,
+          method: args?.method ?? 'password',
+          now: args?.startedAt ?? Date.now(),
+        }),
+        ...(args?.lastActivityAt === undefined
+          ? {}
+          : { lastActivityAt: args.lastActivityAt }),
+      }
+      const signed = await signSessionTimeoutState(stateValue)
+      if (!signed) throw new Error('test signing secret missing')
+      return signed
+    }
+
+    it('initializes a signed, session-bound cookie for an existing session', async () => {
+      const response = await run('/settings/tax', {
+        headers: { cookie: 'gnubok-auth-method=bankid' },
+      })
+
+      expect(response.status).toBe(200)
+      const encoded = response.cookies.get(SESSION_TIMEOUT_COOKIE)?.value
+      expect(encoded).toBeTruthy()
+      await expect(verifySessionTimeoutState(encoded)).resolves.toMatchObject({
+        userId: 'user-1',
+        sessionId: 'session-1',
+        method: 'bankid',
+      })
+      expect(response.cookies.get('gnubok-auth-method')?.value).toBe('')
+    })
+
+    it('rejects a tampered cookie and revokes only the current session', async () => {
+      const response = await run('/settings/tax', {
+        headers: { cookie: `${SESSION_TIMEOUT_COOKIE}=tampered.value` },
+      })
+
+      expect(response.status).toBe(307)
+      expect(new URL(locationOf(response)!).searchParams.get('reason')).toBe('absolute')
+      expect(state.signOut).toHaveBeenCalledWith({ scope: 'local' })
+      expect(response.cookies.get(SESSION_TIMEOUT_COOKIE)?.value).toBe('')
+    })
+
+    it('redirects an idle session with its original method and deep link', async () => {
+      const now = Date.now()
+      const encoded = await signedCookie({
+        startedAt: now - 40_000,
+        lastActivityAt: now - 30_000,
+        method: 'bankid',
+      })
+
+      const response = await run('/reports/vat?period=2026-01', {
+        headers: { cookie: `${SESSION_TIMEOUT_COOKIE}=${encoded}` },
+      })
+
+      const url = new URL(locationOf(response)!)
+      expect(url.pathname).toBe('/login')
+      expect(url.searchParams.get('reason')).toBe('idle')
+      expect(url.searchParams.get('method')).toBe('bankid')
+      expect(url.searchParams.get('next')).toBe('/reports/vat?period=2026-01')
+      expect(state.signOut).toHaveBeenCalledWith({ scope: 'local' })
+    })
+
+    it('gives absolute expiry precedence and returns structured API errors', async () => {
+      const now = Date.now()
+      const encoded = await signedCookie({
+        startedAt: now - 60_000,
+        lastActivityAt: now - 30_000,
+      })
+
+      const response = await run('/api/invoices', {
+        headers: { cookie: `${SESSION_TIMEOUT_COOKIE}=${encoded}` },
+      })
+
+      expect(response.status).toBe(401)
+      expect(response.headers.get('x-session-timeout-reason')).toBe('absolute')
+      await expect(response.json()).resolves.toMatchObject({
+        error: { code: 'SESSION_EXPIRED', reason: 'absolute' },
+      })
+    })
+
+    it('does not let a forged Authorization header bypass normal APIs', async () => {
+      const now = Date.now()
+      const encoded = await signedCookie({ lastActivityAt: now - 30_000, startedAt: now - 40_000 })
+      const headers = {
+        authorization: 'Bearer forged',
+        cookie: `${SESSION_TIMEOUT_COOKIE}=${encoded}`,
+      }
+
+      expect((await run('/api/invoices', { headers })).status).toBe(401)
+      expect((await run('/api/v1/companies/c1/invoices', { headers })).status).toBe(200)
+    })
+
+    it('starts a new timeout window when the Supabase session changes', async () => {
+      const encoded = await signedCookie({ sessionId: 'old-session' })
+
+      const response = await run('/settings/tax', {
+        headers: { cookie: `${SESSION_TIMEOUT_COOKIE}=${encoded}` },
+      })
+
+      expect(response.status).toBe(200)
+      const renewed = response.cookies.get(SESSION_TIMEOUT_COOKIE)?.value
+      await expect(verifySessionTimeoutState(renewed)).resolves.toMatchObject({
+        sessionId: 'session-1',
+      })
+      expect(state.signOut).not.toHaveBeenCalled()
+    })
  })

  // ── Site 1: protected-route bounce ────────────────────────────────────
@@ -5,6 +5,24 @@ import { apiPathSkipsMfaGate } from '@/lib/auth/api-mfa-gate'
 import { DEFAULT_LOCALE, LOCALE_COOKIE, isLocale } from '@/i18n/config'
 import { userHasPassword } from '@/lib/auth/has-password'
 import { safeReturnTo } from '@/lib/auth/safe-return-to'
+import {
+  apiRequestSkipsSessionTimeout,
+  createSessionTimeoutState,
+  evaluateSessionTimeout,
+  getSessionTimeoutConfig,
+  sessionStateMatchesUser,
+  sessionTimeoutClearCookieOptions,
+  sessionTimeoutCookieOptions,
+  signSessionTimeoutState,
+  verifySessionTimeoutState,
+} from '@/lib/auth/session-timeout'
+import {
+  isSessionAuthMethod,
+  SESSION_AUTH_METHOD_HINT_COOKIE,
+  SESSION_TIMEOUT_COOKIE,
+  type SessionAuthMethod,
+  type SessionTimeoutReason,
+} from '@/lib/auth/session-timeout-shared'

 export async function updateSession(request: NextRequest) {
  let supabaseResponse = NextResponse.next({
@@ -62,6 +80,72 @@ export async function updateSession(request: NextRequest) {
    }
  }

+  const timeoutConfig = getSessionTimeoutConfig()
+  const hasAuthorizationHeader = request.headers.get('authorization') !== null
+
+  if (!user) {
+    clearSessionTimeoutCookies(request, supabaseResponse)
+  } else if (
+    timeoutConfig.enabled &&
+    !apiRequestSkipsSessionTimeout(pathname, hasAuthorizationHeader)
+  ) {
+    const encodedState = request.cookies.get(SESSION_TIMEOUT_COOKIE)?.value
+    const sessionId = await getSupabaseSessionId(supabase)
+    const verifiedState = await verifySessionTimeoutState(encodedState)
+
+    if (encodedState && !verifiedState) {
+      await signOutTimedOutSession(supabase)
+      return sessionTimeoutResponse(
+        request,
+        supabaseResponse,
+        'absolute',
+        'password',
+      )
+    }
+
+    if (
+      !verifiedState ||
+      !sessionStateMatchesUser(verifiedState, user.id, sessionId)
+    ) {
+      const hintedMethod = request.cookies.get(
+        SESSION_AUTH_METHOD_HINT_COOKIE,
+      )?.value
+      const method = isSessionAuthMethod(hintedMethod)
+        ? hintedMethod
+        : 'password'
+      const state = createSessionTimeoutState({
+        userId: user.id,
+        sessionId,
+        method,
+      })
+      const signedState = await signSessionTimeoutState(state)
+
+      if (signedState) {
+        request.cookies.set(SESSION_TIMEOUT_COOKIE, signedState)
+        supabaseResponse.cookies.set(
+          SESSION_TIMEOUT_COOKIE,
+          signedState,
+          sessionTimeoutCookieOptions(),
+        )
+        clearAuthMethodHint(request, supabaseResponse)
+      }
+    } else {
+      const timeoutReason = evaluateSessionTimeout(
+        verifiedState,
+        timeoutConfig,
+      )
+      if (timeoutReason) {
+        await signOutTimedOutSession(supabase)
+        return sessionTimeoutResponse(
+          request,
+          supabaseResponse,
+          timeoutReason,
+          verifiedState.method,
+        )
+      }
+    }
+  }
+
  // ── API routes ──────────────────────────────────────────────────────────
  // API routes authenticate themselves (requireAuth, API-key Bearer, cron
  // secret, webhook signatures). Middleware runs on them for ONE reason: to
@@ -78,7 +162,7 @@ export async function updateSession(request: NextRequest) {
  if (pathname.startsWith('/api')) {
    const skipMfaGate = apiPathSkipsMfaGate(
      pathname,
-      request.headers.get('authorization') !== null,
+      hasAuthorizationHeader,
    )
    if (!skipMfaGate && user && shouldEnforceMfa(user)) {
      const { data: aal } =
@@ -300,6 +384,112 @@ export async function updateSession(request: NextRequest) {
  return supabaseResponse
 }

+async function getSupabaseSessionId(
+  supabase: ReturnType<typeof createServerClient>,
+): Promise<string | null> {
+  if (typeof supabase.auth.getClaims !== 'function') return null
+
+  try {
+    const { data } = await supabase.auth.getClaims()
+    return typeof data?.claims?.session_id === 'string'
+      ? data.claims.session_id
+      : null
+  } catch (error) {
+    console.warn('[middleware] could not resolve Supabase session id', error)
+    return null
+  }
+}
+
+async function signOutTimedOutSession(
+  supabase: ReturnType<typeof createServerClient>,
+): Promise<void> {
+  try {
+    await supabase.auth.signOut({ scope: 'local' })
+  } catch (error) {
+    console.warn('[middleware] timed-out session revocation failed', error)
+  }
+}
+
+function clearAuthMethodHint(
+  request: NextRequest,
+  response: NextResponse,
+): void {
+  if (!request.cookies.has(SESSION_AUTH_METHOD_HINT_COOKIE)) return
+  request.cookies.delete(SESSION_AUTH_METHOD_HINT_COOKIE)
+  response.cookies.set(SESSION_AUTH_METHOD_HINT_COOKIE, '', {
+    path: '/',
+    maxAge: 0,
+    sameSite: 'lax',
+    secure: process.env.NODE_ENV === 'production',
+  })
+}
+
+function clearSessionTimeoutCookies(
+  request: NextRequest,
+  response: NextResponse,
+): void {
+  if (request.cookies.has(SESSION_TIMEOUT_COOKIE)) {
+    request.cookies.delete(SESSION_TIMEOUT_COOKIE)
+    response.cookies.set(
+      SESSION_TIMEOUT_COOKIE,
+      '',
+      sessionTimeoutClearCookieOptions(),
+    )
+  }
+  clearAuthMethodHint(request, response)
+}
+
+function copyResponseCookies(from: NextResponse, to: NextResponse): void {
+  for (const cookie of from.cookies.getAll()) {
+    to.cookies.set(cookie)
+  }
+}
+
+function sessionTimeoutResponse(
+  request: NextRequest,
+  authResponse: NextResponse,
+  reason: SessionTimeoutReason,
+  method: SessionAuthMethod,
+): NextResponse {
+  clearSessionTimeoutCookies(request, authResponse)
+
+  if (request.nextUrl.pathname.startsWith('/api')) {
+    const response = NextResponse.json(
+      {
+        error: {
+          code: 'SESSION_EXPIRED',
+          message: reason === 'idle'
+            ? 'Sessionen har upphört på grund av inaktivitet.'
+            : 'Sessionen har upphört av säkerhetsskäl.',
+          message_en: reason === 'idle'
+            ? 'The session expired due to inactivity.'
+            : 'The session expired for security reasons.',
+          reason,
+        },
+      },
+      { status: 401 },
+    )
+    response.headers.set('X-Session-Timeout-Reason', reason)
+    response.headers.set('Cache-Control', 'no-store')
+    copyResponseCookies(authResponse, response)
+    return response
+  }
+
+  const url = new URL('/login', request.url)
+  url.searchParams.set('reason', reason)
+  url.searchParams.set('method', method)
+  const destination = safeReturnTo(
+    request.nextUrl.pathname + request.nextUrl.search,
+    '/',
+  )
+  if (destination !== '/') url.searchParams.set('next', destination)
+
+  const response = NextResponse.redirect(url)
+  response.headers.set('Cache-Control', 'no-store')
+  copyResponseCookies(authResponse, response)
+  return response
+}
+
 /**
 * Which query parameter each auth page reads its post-auth destination from.
 * /login reads `next` (app/(auth)/login/page.tsx), the MFA pages read