spine-framework 0.3.91 → 0.3.92

package/.framework/functions/apps.ts

@@ -59,12 +59,18 @@ export const list = createHandler(async (ctx, body) => {
     throw new Error('Account context required')
   }
 
-  // RLS automatically filters to accessible accounts
+  // Pass user roles to the RPC so filtering happens server-side.
+  // system_admin bypasses all role checks in the RPC.
+  const userRoles = ctx.principal?.roles || []
+  const isSysAdmin = userRoles.includes('system_admin')
+
   const { data, error: err } = await ctx.db
     .rpc('get_account_apps', {
       account_id: targetAccountId,
       include_system: include_system !== 'false',
-      include_inactive: include_inactive === 'true'
+      include_inactive: include_inactive === 'true',
+      user_role_slugs: userRoles,
+      is_system_admin: isSysAdmin,
     })
 
   if (err) throw err

package/.framework/src/contexts/AppContext.tsx

@@ -1,4 +1,4 @@
-import React, { createContext, useContext, useState, useEffect } from 'react'
+import React, { createContext, useContext, useState, useEffect, useRef, useCallback } from 'react'
 import { AppRecord } from '../hooks/useApps'
 import { apiFetch } from '../lib/api'
 import { useAuth } from './AuthContext'
@@ -69,17 +69,23 @@ interface AppsRegistryProviderProps {
 }
 
 /**
- * Fetches all accessible apps once after authentication and provides them
- * globally. Wrap this around AuthenticatedRouter so routes don't re-fetch
- * on every navigation.
+ * Fetches accessible apps for the current user and provides them globally.
+ *
+ * Role-based filtering is done server-side by the `get_account_apps` RPC
+ * (migration 020). The client trusts the backend response and only filters
+ * for routability (has a route_prefix and a renderer).
+ *
+ * Uses an AbortController to cancel in-flight fetches when dependencies
+ * change, preventing interleaved responses from stale requests.
  */
 export function AppsRegistryProvider({ children }: AppsRegistryProviderProps) {
   const { user } = useAuth()
   const [apps, setApps] = useState<AppRecord[]>([])
   const [loading, setLoading] = useState(true)
   const [error, setError] = useState<string | null>(null)
+  const abortRef = useRef<AbortController | null>(null)
 
-  const fetchApps = async () => {
+  const fetchApps = useCallback(async (signal?: AbortSignal) => {
     if (!user) {
       setApps([])
       setLoading(false)
@@ -90,44 +96,54 @@ export function AppsRegistryProvider({ children }: AppsRegistryProviderProps) {
       setLoading(true)
       setError(null)
 
-      const response = await apiFetch('/api/apps?action=list')
+      const response = await apiFetch('/api/apps?action=list', { signal })
+
+      if (signal?.aborted) return
+
       if (!response.ok) throw new Error(`Failed to fetch apps: ${response.statusText}`)
 
       const data = await response.json()
       if (data.error) throw new Error(data.error)
 
+      // Backend already filters by role — no client-side role check needed
       const allApps: AppRecord[] = data.data || data || []
-
-      const accessible = allApps.filter(app => {
-        if (!app.is_active) return false
-        const requiredRoles = app.required_roles || (app.min_role ? [app.min_role] : [])
-        if (requiredRoles.length === 0) return true
-        if (!user.roles || user.roles.length === 0) return false
-        if (user.roles.includes('system_admin')) return true
-        return requiredRoles.some(role => user.roles!.includes(role))
-      })
-
-      setApps(accessible)
+      setApps(allApps)
     } catch (err) {
+      if (err instanceof DOMException && err.name === 'AbortError') return
       setError(err instanceof Error ? err.message : 'Failed to load apps')
       setApps([])
     } finally {
-      setLoading(false)
+      if (!signal?.aborted) setLoading(false)
     }
-  }
+  }, [user])
 
-  // Fetch when user identity or roles change (roles may update after registration)
+  // Fetch when user identity or roles change.
+  // Abort any in-flight request before starting a new one.
   const rolesKey = user?.roles?.join(',') || ''
   useEffect(() => {
-    fetchApps()
-  }, [user?.id, user?.account_id, rolesKey])
+    // Cancel previous fetch
+    abortRef.current?.abort()
+    const controller = new AbortController()
+    abortRef.current = controller
+
+    fetchApps(controller.signal)
+
+    return () => controller.abort()
+  }, [user?.id, user?.account_id, rolesKey, fetchApps])
 
   const routableApps = apps.filter(
     app => app.route_prefix != null && app.renderer !== 'none'
   )
 
+  const refetch = useCallback(() => {
+    abortRef.current?.abort()
+    const controller = new AbortController()
+    abortRef.current = controller
+    fetchApps(controller.signal)
+  }, [fetchApps])
+
   return (
-    <AppsRegistryContext.Provider value={{ apps, routableApps, loading, error, refetch: fetchApps }}>
+    <AppsRegistryContext.Provider value={{ apps, routableApps, loading, error, refetch }}>
       {children}
     </AppsRegistryContext.Provider>
   )

package/.framework/src/contexts/AuthContext.tsx

@@ -10,33 +10,76 @@
  * fetch (principal, account, roles, permissions).
  *
  * **Session hydration strategy:**
- * 1. On mount, restore user from `sessionStorage` (survives page reloads
- *    without a loading flash)
- * 2. If no stored user, call `checkAuth` → `fetchUserContext` → `setAccountId`
+ * 1. On mount, restore user from `localStorage` with TTL/version check
+ *    (cross-tab sync, survives page reloads without a loading flash)
+ * 2. Always verify stored context with the server before rendering routes
  * 3. Subscribe to `supabase.auth.onAuthStateChange` for `SIGNED_IN`,
  *    `TOKEN_REFRESHED`, and `SIGNED_OUT` events
  *
  * **Race-condition guards:**
- * - `isLoggingIn` flag prevents `onAuthStateChange` from re-fetching context
+ * - `isLoggingIn` ref prevents `onAuthStateChange` from re-fetching context
  *   while `login()` is already in progress
- * - `SIGNED_IN` / `TOKEN_REFRESHED` handler skips re-fetch if user is already
- *   loaded (prevents blocking page data fetches on browser focus)
- * - `checkAuth` exits early if user is already loaded from `sessionStorage`
+ * - `onAuthStateChange` checks current user ref before async fetch
+ * - `checkAuth` always verifies with server, even with stored user
  *
  * **Account scope:** Calls `setAccountId(userContext.account_id)` after
  * every successful context fetch, keeping `src/lib/api.ts` in sync.
  *
  * @seeAlso src/lib/supabase.ts (supabase client singleton)
- * @seeAlso src/lib/api.ts (setAccountId, apiFetch)
+ * @seeAlso src/lib/api.ts (setAccountId, apiFetch, onUnauthorized)
  * @seeAlso src/types/auth.ts (User shape)
  * @seeAlso functions/auth.ts (backend `/api/auth?action=context` endpoint)
  */
 
-import React, { createContext, useContext, useEffect, useState } from 'react'
+import React, { createContext, useContext, useEffect, useState, useRef, useCallback } from 'react'
 import { supabase } from '../lib/supabase'
-import { setAccountId, apiFetch } from '../lib/api'
+import { setAccountId, apiFetch, onUnauthorized } from '../lib/api'
 import { User } from '../types/auth'
 
+// ─── STORAGE ──────────────────────────────────────────────────────────────────
+
+/** Version stamp for stored user; bump when User shape changes */
+const STORAGE_VERSION = 1
+const STORAGE_KEY = 'spine_user'
+/** Max age (ms) before stored user is considered stale and discarded */
+const STORAGE_TTL_MS = 5 * 60 * 1000 // 5 minutes
+
+interface StoredUserEnvelope {
+  version: number
+  timestamp: number
+  user: User
+}
+
+function readStoredUser(): User | null {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY)
+    if (!raw) return null
+    const envelope: StoredUserEnvelope = JSON.parse(raw)
+    if (envelope.version !== STORAGE_VERSION) return null
+    if (Date.now() - envelope.timestamp > STORAGE_TTL_MS) return null
+    return envelope.user
+  } catch {
+    return null
+  }
+}
+
+function writeStoredUser(user: User | null) {
+  try {
+    if (user) {
+      const envelope: StoredUserEnvelope = {
+        version: STORAGE_VERSION,
+        timestamp: Date.now(),
+        user,
+      }
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(envelope))
+    } else {
+      localStorage.removeItem(STORAGE_KEY)
+    }
+  } catch {
+    // Storage unavailable (private browsing, quota exceeded)
+  }
+}
+
 // ─── TYPES ───────────────────────────────────────────────────────────────────
 
 /**
@@ -83,53 +126,60 @@ interface AuthProviderProps {
 // ─── INTERNAL HELPERS ───────────────────────────────────────────────────────────
 
 /**
- * Fetches the server-side user context from `GET /api/auth`. Returns null on
- * any error (network, auth, or API) rather than throwing, so callers can
- * apply fallback logic without try/catch.
+ * Fetches the server-side user context from `GET /api/auth` with retry.
+ * Returns null on any persistent error rather than throwing, so callers
+ * can apply fallback logic without try/catch.
+ *
+ * Retries up to `maxRetries` times on network errors and 5xx responses.
+ * Does NOT retry 401/403 (auth failures are not transient).
  *
  * @returns Resolved `User` object or null on failure
  * @throws never (all errors are caught internally)
  * @sideEffects Network request via apiFetch; console logging
  * @calledBy AuthProvider.login, AuthProvider.refreshUser, AuthProvider.checkAuth
  */
-async function fetchUserContext(): Promise<User | null> {
-  try {
-    console.log('Fetching user context from backend API')
+async function fetchUserContext(maxRetries = 2): Promise<User | null> {
+  let lastError: unknown = null
 
-    // Use backend API to get user context - backend handles all security
-    const response = await apiFetch('/api/auth', {
-      method: 'GET'
-    })
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      if (attempt > 0) {
+        // Exponential backoff: 200ms, 800ms, 3200ms
+        await new Promise(r => setTimeout(r, 200 * Math.pow(4, attempt - 1)))
+      }
 
-    if (!response.ok) {
-      console.error('Backend API error:', response.status, response.statusText)
-      return null
-    }
+      const response = await apiFetch('/api/auth', { method: 'GET' })
 
-    const data = await response.json()
-    
-    if (data.error) {
-      console.error('Backend returned error:', data.error)
-      return null
-    }
+      // Don't retry auth failures
+      if (response.status === 401 || response.status === 403) {
+        return null
+      }
 
-    if (!data.data) {
-      console.error('No user data returned from backend')
-      return null
-    }
+      // Retry on 5xx
+      if (response.status >= 500) {
+        lastError = new Error(`Server error: ${response.status}`)
+        continue
+      }
 
-    console.log('User context loaded from backend:', {
-      id: data.data.id,
-      email: data.data.email,
-      account: data.data.account?.slug,
-      role: data.data.roles?.[0]
-    })
+      if (!response.ok) {
+        return null
+      }
 
-    return data.data
-  } catch (error) {
-    console.error('Error fetching user context from backend:', error)
-    return null
+      const data = await response.json()
+      if (data.error || !data.data) return null
+
+      return data.data
+    } catch (error) {
+      lastError = error
+      // Network error (TypeError: Failed to fetch) — retry
+      if (error instanceof TypeError) continue
+      // Other errors — don't retry
+      return null
+    }
   }
+
+  console.error('fetchUserContext failed after retries:', lastError)
+  return null
 }
 
 // ─── AuthProvider ──────────────────────────────────────────────────────────────
@@ -140,9 +190,10 @@ async function fetchUserContext(): Promise<User | null> {
  *
  * @param children - React subtree to wrap
  * @sideEffects
- *   - Reads/writes `sessionStorage` key `spine_user` for persistence
+ *   - Reads/writes `localStorage` key `spine_user` for persistence
  *   - Calls `setAccountId` (mutates `src/lib/api.ts` module state)
  *   - Subscribes to `supabase.auth.onAuthStateChange`; unsubscribes on unmount
+ *   - Registers 401 interceptor via `onUnauthorized`
  * @calledBy src/main.tsx (app root)
  *
  * @example
@@ -153,230 +204,202 @@ async function fetchUserContext(): Promise<User | null> {
  * ```
  */
 export function AuthProvider({ children }: AuthProviderProps) {
-  // Initialize user from sessionStorage to survive full page reloads
-  const getStoredUser = (): User | null => {
-    try {
-      const stored = sessionStorage.getItem('spine_user')
-      return stored ? JSON.parse(stored) : null
-    } catch {
-      return null
-    }
-  }
-
-  const storedUser = getStoredUser()
+  const storedUser = readStoredUser()
   const [user, setUser] = useState<User | null>(storedUser)
   // If we have a stored user, start loading to verify context before rendering routes
-  const [isLoading, setIsLoading] = useState(!!storedUser)
-  const [isLoggingIn, setIsLoggingIn] = useState(false)
+  const [isLoading, setIsLoading] = useState(true)
+  const isLoggingInRef = useRef(false)
+  const userRef = useRef<User | null>(storedUser)
+
+  // Keep ref in sync with state so async callbacks see current value
+  useEffect(() => { userRef.current = user }, [user])
+
+  const setUserWithStorage = useCallback((u: User | null) => {
+    setUser(u)
+    userRef.current = u
+    writeStoredUser(u)
+  }, [])
+
+  const clearUser = useCallback(() => {
+    setUserWithStorage(null)
+    setAccountId(null)
+  }, [setUserWithStorage])
+
+  const applyUserContext = useCallback((ctx: User) => {
+    setUserWithStorage(ctx)
+    setAccountId(ctx.account_id)
+  }, [setUserWithStorage])
+
+  // ── Login ──────────────────────────────────────────────────────────────────
+
+  const login = useCallback(async (email: string, password: string) => {
+    isLoggingInRef.current = true
 
-  // Save user to sessionStorage whenever it changes
-  const setUserWithStorage = (user: User | null) => {
-    setUser(user)
     try {
-      if (user) {
-        sessionStorage.setItem('spine_user', JSON.stringify(user))
-      } else {
-        sessionStorage.removeItem('spine_user')
+      const { data, error } = await supabase.auth.signInWithPassword({ email, password })
+
+      if (error) throw error
+
+      if (data.user) {
+        // Brief pause for session to establish
+        await new Promise(resolve => setTimeout(resolve, 100))
+
+        const userContext = await fetchUserContext()
+        if (userContext) {
+          applyUserContext(userContext)
+        } else {
+          // Fallback to minimal user object
+          applyUserContext({
+            id: data.user.id,
+            email: data.user.email || '',
+            full_name: data.user.user_metadata?.full_name || data.user.email || 'User',
+            account_id: '',
+            roles: [],
+            permissions: [],
+          })
+        }
       }
-    } catch (error) {
-      console.warn('Failed to save user to sessionStorage:', error)
+    } finally {
+      isLoggingInRef.current = false
     }
-  }
+  }, [applyUserContext])
 
-  const login = async (email: string, password: string) => {
-    console.log('Login function called with:', email)
-    setIsLoggingIn(true)
-    
-    const { data, error } = await supabase.auth.signInWithPassword({
-      email,
-      password,
-    })
+  // ── Logout ─────────────────────────────────────────────────────────────────
+
+  const logout = useCallback(async () => {
+    await supabase.auth.signOut()
+    clearUser()
+  }, [clearUser])
 
-    console.log('Supabase auth response:', { data, error })
+  // ── Refresh ────────────────────────────────────────────────────────────────
 
-    if (error) {
-      console.error('Supabase auth error:', error)
-      setIsLoggingIn(false)
-      throw error
+  const refreshUser = useCallback(async () => {
+    const { data: { session } } = await supabase.auth.getSession()
+
+    if (!session?.user) {
+      clearUser()
+      return
     }
 
-    if (data.user) {
-      console.log('User logged in, fetching server context...')
-      
-      // Wait a moment for the session to be properly established
-      await new Promise(resolve => setTimeout(resolve, 100))
-      
-      // Fetch user context from server instead of hardcoding
-      const userContext = await fetchUserContext()
-      if (userContext) {
-        console.log('Setting server-derived user context:', userContext)
-        setUserWithStorage(userContext)
-        setAccountId(userContext.account_id)
-      } else {
-        console.error('Failed to get user context from server')
-        // Fallback to minimal user object
-        const fallbackUser = {
-          id: data.user.id,
-          email: data.user.email || '',
-          full_name: data.user.user_metadata?.full_name || data.user.email || 'User',
-          account_id: '',
-          roles: [],
-          permissions: [],
-        }
-        setUserWithStorage(fallbackUser)
-        setAccountId(fallbackUser.account_id)
-      }
+    const userContext = await fetchUserContext()
+    if (userContext) {
+      applyUserContext(userContext)
+    } else {
+      clearUser()
     }
-    
-    setIsLoggingIn(false)
-  }
+  }, [applyUserContext, clearUser])
 
-  const logout = async () => {
-    await supabase.auth.signOut()
-    setUserWithStorage(null)
-    setAccountId(null)
-  }
+  // ── Register 401 interceptor ───────────────────────────────────────────────
 
-  const refreshUser = async () => {
-    try {
-      console.log('Refreshing user...')
-      const { data: { session } } = await supabase.auth.getSession()
-      console.log('Got session:', session)
-      
-      if (!session?.user) {
-        console.log('No session user, setting user to null')
-        setUser(null)
-        return
-      }
+  useEffect(() => {
+    const unregister = onUnauthorized(() => {
+      // Session expired — sign out cleanly
+      supabase.auth.signOut().then(() => clearUser())
+    })
+    return unregister
+  }, [clearUser])
 
-      // Fetch user context from server instead of hardcoding
-      const userContext = await fetchUserContext()
-      if (userContext) {
-        console.log('Setting server-derived user context:', userContext)
-        setUser(userContext)
-        setAccountId(userContext.account_id)
-      } else {
-        console.error('Failed to get user context from server')
+  // ── Listen for storage events from other tabs ──────────────────────────────
+
+  useEffect(() => {
+    const handleStorage = (e: StorageEvent) => {
+      if (e.key !== STORAGE_KEY) return
+      if (e.newValue === null) {
+        // Other tab logged out
         setUser(null)
+        userRef.current = null
         setAccountId(null)
+      } else {
+        // Other tab logged in or refreshed
+        const parsed = readStoredUser()
+        if (parsed) {
+          setUser(parsed)
+          userRef.current = parsed
+          setAccountId(parsed.account_id)
+        }
       }
-    } catch (error) {
-      console.error('Error refreshing user:', error)
-      setUser(null)
-      setAccountId(null)
     }
-  }
+    window.addEventListener('storage', handleStorage)
+    return () => window.removeEventListener('storage', handleStorage)
+  }, [])
+
+  // ── Initial auth check + subscription ──────────────────────────────────────
 
   useEffect(() => {
-    // Check initial auth state
+    let cancelled = false
+
     const checkAuth = async () => {
       try {
-        // If user is loaded from sessionStorage, verify context from server
-        // before rendering routes (isLoading starts true in this case)
-        if (user) {
-          console.log('User loaded from storage, verifying context:', user.id)
-          const { data: { session } } = await supabase.auth.getSession()
-          if (session?.user) {
-            const userContext = await fetchUserContext()
-            if (userContext) {
-              setUserWithStorage(userContext)
-              setAccountId(userContext.account_id)
-            }
-          } else {
-            // Session expired — clear stored user
-            setUserWithStorage(null)
-            setAccountId(null)
-          }
+        const { data: { session } } = await supabase.auth.getSession()
+
+        if (!session?.user) {
+          if (!cancelled) clearUser()
           return
         }
-        
-        // No stored user — show loading spinner while checking
-        setIsLoading(true)
-        console.log('Checking initial auth state...')
-        const { data: { session } } = await supabase.auth.getSession()
-        console.log('Initial session check:', session?.user?.id ? 'User found' : 'No user')
-        
-        if (session?.user) {
-          // Fetch user context from server instead of hardcoding
-          const userContext = await fetchUserContext()
-          if (userContext) {
-            console.log('Setting server-derived user context from session:', userContext)
-            setUserWithStorage(userContext)
-            setAccountId(userContext.account_id)
+
+        const userContext = await fetchUserContext()
+        if (cancelled) return
+
+        if (userContext) {
+          applyUserContext(userContext)
+        } else if (userRef.current) {
+          // Network issue but we have a stored user — keep it (offline resilience)
+          setAccountId(userRef.current.account_id)
+        } else {
+          clearUser()
+        }
+      } catch (error) {
+        if (!cancelled) {
+          // Network down with stored user — keep going (offline resilience)
+          if (userRef.current) {
+            setAccountId(userRef.current.account_id)
           } else {
-            console.error('Failed to get user context from server')
-            setUserWithStorage(null)
-            setAccountId(null)
+            clearUser()
           }
         }
-      } catch (error) {
-        console.error('Auth check failed:', error)
-        setUserWithStorage(null)
-        setAccountId(null)
       } finally {
-        // Always set loading to false after checking
-        setIsLoading(false)
-        console.log('Auth check completed, loading set to false')
+        if (!cancelled) setIsLoading(false)
       }
     }
 
     checkAuth()
 
-    // Listen for auth changes
+    // Listen for auth changes — async work is in the callback body, not
+    // inside a state updater (React anti-pattern)
     const { data: { subscription } } = supabase.auth.onAuthStateChange(
       async (event, session) => {
-        console.log('Auth state changed:', event, session?.user?.id)
-        
+        if (cancelled) return
+
         // Don't refresh during login to avoid conflicts
-        if (isLoggingIn) {
-          console.log('Skipping refresh during login')
-          return
-        }
-        
+        if (isLoggingInRef.current) return
+
         if (event === 'SIGNED_IN' || event === 'TOKEN_REFRESHED') {
-          if (session?.user) {
-            // Skip re-fetching if user is already loaded — prevents blocking
-            // page fetches when Supabase re-fires SIGNED_IN on browser focus
-            setUser(currentUser => {
-              if (currentUser) {
-                console.log('Auth state changed: user already loaded, skipping re-fetch')
-                return currentUser
-              }
-              // No user yet — fetch context asynchronously
-              fetchUserContext().then(userContext => {
-                if (userContext) {
-                  console.log('Setting server-derived user context from auth state change:', userContext)
-                  setUserWithStorage(userContext)
-                  setAccountId(userContext.account_id)
-                } else {
-                  console.error('Failed to get user context from server')
-                  setUserWithStorage(null)
-                  setAccountId(null)
-                }
-              })
-              return currentUser
-            })
+          if (!session?.user) return
+          // Skip re-fetch if user is already loaded — prevents blocking
+          // page fetches when Supabase re-fires SIGNED_IN on browser focus
+          if (userRef.current) return
+
+          const userContext = await fetchUserContext()
+          if (cancelled) return
+
+          if (userContext) {
+            applyUserContext(userContext)
+          } else {
+            clearUser()
           }
         } else if (event === 'SIGNED_OUT') {
-          setUserWithStorage(null)
-          setAccountId(null)
+          clearUser()
         }
       }
     )
 
-    return () => subscription.unsubscribe()
-  }, [isLoggingIn])
-
-  const value = {
-    user,
-    isLoading,
-    login,
-    logout,
-    refreshUser
-  }
+    return () => {
+      cancelled = true
+      subscription.unsubscribe()
+    }
+  }, [applyUserContext, clearUser])
 
-  // Debug: Log loading state changes
-  console.log('AuthContext state:', { user: user?.id, isLoading, userEmail: user?.email })
+  const value: AuthContextType = { user, isLoading, login, logout, refreshUser }
 
   return (
     <AuthContext.Provider value={value}>

package/.framework/src/lib/api.ts

@@ -14,6 +14,10 @@
  * ```
  * All subsequent `apiFetch` calls include `X-Account-Id` automatically.
  *
+ * **401 interceptor:** Register a callback via `onUnauthorized(cb)` to be
+ * notified when any non-auth API call returns 401. AuthContext uses this to
+ * trigger logout when the session expires mid-use.
+ *
  * INVARIANT: Call `setAccountId` before making any authenticated API requests.
  *   If `_accountId` is null, the backend may reject scoped requests.
  *
@@ -51,6 +55,26 @@ export function getAccountId(): string | null {
   return _accountId
 }
 
+// ─── 401 INTERCEPTOR ─────────────────────────────────────────────────────────
+
+/** Paths that are expected to return 401 (don't trigger the interceptor) */
+const AUTH_PATHS = ['/api/auth']
+
+let _onUnauthorizedCallback: (() => void) | null = null
+
+/**
+ * Register a callback to be invoked when a non-auth API call returns 401.
+ * Returns an unregister function. Only one callback may be active at a time.
+ *
+ * @param cb - Callback invoked once on 401
+ * @returns Unregister function
+ * @calledBy AuthContext (registers logout handler)
+ */
+export function onUnauthorized(cb: () => void): () => void {
+  _onUnauthorizedCallback = cb
+  return () => { _onUnauthorizedCallback = null }
+}
+
 // ─── INTERNAL HELPERS ─────────────────────────────────────────────────────────
 
 /**
@@ -110,6 +134,9 @@ export async function getAuthHeaders(): Promise<Record<string, string>> {
  * headers, strips invalid Bearer values (`null`/`undefined`/empty), and
  * forwards all other options (including `signal` for AbortController).
  *
+ * If a non-auth endpoint returns 401, the registered `onUnauthorized`
+ * callback fires (typically triggers logout).
+ *
  * Use this for ALL Spine API calls from the frontend. Never call `fetch`
  * directly for API routes.
  *
@@ -120,7 +147,8 @@ export async function getAuthHeaders(): Promise<Record<string, string>> {
  * @inputSpec path: string — relative URL to a Netlify function
  * @inputSpec options.signal: AbortSignal | undefined — forwarded for cancellation
  * @outputSpec Response — with auth headers injected; not yet parsed
- * @sideEffects Network request; reads localStorage via getAuthHeaders
+ * @sideEffects Network request; reads localStorage via getAuthHeaders;
+ *   may trigger onUnauthorized callback on 401
  * @calledBy src/hooks/useApi.ts, useEntityList.ts, useEntityRecord.ts
  *
  * @example
@@ -131,7 +159,6 @@ export async function getAuthHeaders(): Promise<Record<string, string>> {
  * ```
  */
 export async function apiFetch(path: string, options: RequestInit = {}): Promise<Response> {
-  console.log('apiFetch called with:', { path, options, signal: options.signal })
   const authHeaders = await getAuthHeaders()
   const optionHeaders = normalizeHeaders(options.headers)
   const optionAuthorization = optionHeaders.Authorization || optionHeaders.authorization
@@ -151,6 +178,16 @@ export async function apiFetch(path: string, options: RequestInit = {}): Promise
       ...optionHeaders,
     },
   }
-  console.log('apiFetch final options:', { fetchOptions, signal: fetchOptions.signal })
-  return fetch(path, fetchOptions)
+
+  const response = await fetch(path, fetchOptions)
+
+  // 401 on a non-auth endpoint means the session has expired
+  if (response.status === 401 && _onUnauthorizedCallback) {
+    const isAuthPath = AUTH_PATHS.some(p => path.startsWith(p))
+    if (!isAuthPath) {
+      _onUnauthorizedCallback()
+    }
+  }
+
+  return response
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-framework",
-  "version": "0.3.91",
+  "version": "0.3.92",
   "description": "Multi-tenant, modular application platform for modern SaaS systems",
   "type": "module",
   "bin": {