@stevederico/skateboard-ui 1.2.19 → 1.2.22

package/CHANGELOG.md

@@ -1,4 +1,32 @@
 # CHANGELOG
+
+1.2.22
+
+  Fix SignOut CSRF header
+  Add CSRF retry logic
+  Remove redundant token parsing
+  Update authentication docs
+
+## [1.2.21] - 2026-01-22
+
+### Fixed
+- **SignOut**: Added missing CSRF token header to signout request (critical bug that caused 403 errors)
+- **Error Handling**: Added automatic retry logic for 403 CSRF validation failures with session refresh
+- **Code Quality**: Removed redundant CSRF token parsing in SignInView (getCSRFToken() already handles it)
+
+### Changed
+- `apiRequest()` now automatically recovers from CSRF token failures by refreshing the session and retrying once
+- Improved error messages for CSRF-related failures
+
+### Documentation
+- Updated Authentication.md with CSRF error handling flow
+
+1.2.20
+
+  Fix CSRF token reading
+  Read csrf_token cookie directly
+  Add localStorage fallback
+
 1.2.19
 
   Skip noLogin backend validation

package/SignInView.jsx

@@ -52,14 +52,6 @@ export default function LoginForm({
 
       if (response.ok) {
         const data = await response.json();
-        // Save CSRF token to localStorage for isAuthenticated() check
-        const csrfCookie = document.cookie.split('; ').find(row => row.startsWith('csrf_token='));
-        const csrfToken = csrfCookie ? csrfCookie.split('=')[1] : data.csrfToken;
-        if (csrfToken) {
-          const appName = constants.appName || 'skateboard';
-          const csrfKey = `${appName.toLowerCase().replace(/\s+/g, '-')}_csrf`;
-          localStorage.setItem(csrfKey, csrfToken);
-        }
         dispatch({ type: 'SET_USER', payload: data });
         navigate('/app');
       } else {

package/SignOutView.jsx

@@ -1,6 +1,6 @@
 import { useEffect } from 'react';
 import { useNavigate } from 'react-router-dom';
-import { getBackendURL } from './Utilities';
+import { getBackendURL, getCSRFToken } from './Utilities';
 
 function SignOutView() {
   const navigate = useNavigate();
@@ -8,10 +8,15 @@ function SignOutView() {
   useEffect(() => {
     const signOut = async () => {
       try {
+        const csrfToken = getCSRFToken();
         // Call backend signout endpoint
         await fetch(`${getBackendURL()}/signout`, {
           method: 'POST',
-          credentials: 'include'
+          credentials: 'include',
+          headers: {
+            'Content-Type': 'application/json',
+            ...(csrfToken && { 'X-CSRF-Token': csrfToken })
+          }
         });
       } catch (error) {
         console.error('Sign out error:', error);

package/Utilities.js

@@ -124,10 +124,11 @@ export function getCookie(name) {
 }
 
 /**
- * Get CSRF token from localStorage.
+ * Get CSRF token from cookie or localStorage.
  *
- * Returns the CSRF token saved during signin/signup. This token
- * should be sent in the X-CSRF-Token header for state-changing requests.
+ * Reads CSRF token from csrf_token cookie (set by backend during signin/signup).
+ * Falls back to localStorage for backwards compatibility. This token should be
+ * sent in the X-CSRF-Token header for state-changing requests.
  *
  * @returns {string|null} CSRF token or null if not found
  *
@@ -138,6 +139,11 @@ export function getCookie(name) {
  * });
  */
 export function getCSRFToken() {
+    // Try cookie first (source of truth from backend)
+    const csrfCookie = getCookie('csrf_token');
+    if (csrfCookie) return csrfCookie;
+
+    // Fallback to localStorage (for backwards compatibility)
     const appName = getConstants().appName || 'skateboard';
     const csrfKey = `${appName.toLowerCase().replace(/\s+/g, '-')}_csrf`;
     return safeGetItem(csrfKey);
@@ -608,6 +614,46 @@ export async function apiRequest(endpoint, options = {}) {
         throw new Error('Unauthorized - Redirecting to Sign Out');
     }
 
+    // Handle 403 CSRF token failures with auto-retry
+    if (response.status === 403) {
+        const errorBody = await response.json().catch(() => ({}));
+
+        // If CSRF-related error, try to refresh session and retry once
+        if (errorBody.error && errorBody.error.includes('CSRF')) {
+            console.warn('CSRF token validation failed, attempting recovery...');
+
+            // Fetch fresh user data (triggers CSRF token regeneration on backend)
+            try {
+                await fetch(`${getBackendURL()}/me`, {
+                    credentials: 'include'
+                });
+
+                // Retry original request with fresh token
+                const newCsrfToken = getCSRFToken();
+                return fetch(`${getBackendURL()}${endpoint}`, {
+                    ...options,
+                    credentials: 'include',
+                    signal,
+                    headers: {
+                        'Content-Type': 'application/json',
+                        ...(needsCSRF && newCsrfToken && { 'X-CSRF-Token': newCsrfToken }),
+                        ...options.headers
+                    }
+                }).then(retryResponse => {
+                    if (!retryResponse.ok) {
+                        throw new Error(`Retry failed: ${retryResponse.status} ${retryResponse.statusText}`);
+                    }
+                    return retryResponse.json();
+                });
+            } catch (retryError) {
+                console.error('CSRF recovery failed:', retryError);
+                throw new Error('CSRF validation failed - please refresh the page');
+            }
+        }
+
+        throw new Error(`Forbidden: ${errorBody.error || response.statusText}`);
+    }
+
     // Handle other errors
     if (!response.ok) {
         throw new Error(`Request failed: ${response.status} ${response.statusText}`);

package/docs/AUTHENTICATION.md

@@ -54,6 +54,27 @@ skateboard-ui uses a **hybrid cookie + localStorage authentication system** that
 - Backend validates header matches stored session CSRF token
 - Separate from session cookie to prevent cookie-based CSRF
 
+### CSRF Error Handling
+
+The `apiRequest` utility automatically handles CSRF token failures:
+
+1. **Auto-Regeneration**: Backend auto-regenerates tokens after server restart
+2. **Retry Logic**: Frontend automatically retries failed requests once after refreshing the session
+3. **User Experience**: Transparent recovery without forcing sign-out or page refresh
+
+**Error Flow**:
+```
+POST /api/keys → 403 CSRF error
+    ↓
+Fetch /me (triggers backend auto-regeneration)
+    ↓
+Retry POST /api/keys with fresh token
+    ↓
+Success
+```
+
+**Note**: The retry is automatic and transparent to users. Only if the retry fails will an error be shown.
+
 ## Backend Requirements
 
 ### Required Endpoints
@@ -236,7 +257,7 @@ const response = await fetch(`${getBackendURL()}/protected-endpoint`, {
   credentials: 'include',  // Automatically includes cookies
   headers: {
     'Content-Type': 'application/json',
-    'X-CSRF-Token': getCSRFToken()  // From localStorage
+    'X-CSRF-Token': getCSRFToken()  // From cookie (with localStorage fallback)
   },
   body: JSON.stringify(data)
 });
@@ -466,14 +487,15 @@ app.listen(8000, () => {
 **Symptoms:** Protected endpoints return 403 Forbidden.
 
 **Causes:**
-1. CSRF token not in localStorage
+1. CSRF token cookie missing or expired
 2. Header not being sent
 3. Token mismatch
 
 **Solutions:**
-- Check `localStorage.getItem('{appName}_csrf')` exists
-- Verify `X-CSRF-Token` header is set
-- Ensure CSRF cookie and localStorage token match
+- Verify signin/signup set `csrf_token` cookie (check browser DevTools → Application → Cookies)
+- Check `getCSRFToken()` returns a value (reads from cookie first, localStorage fallback)
+- Verify `X-CSRF-Token` header is set in request
+- Ensure CSRF cookie matches backend session token
 - Check CSRF token not expired (matches session lifetime)
 
 ### Cookies not persisting across requests

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stevederico/skateboard-ui",
   "private": false,
-  "version": "1.2.19",
+  "version": "1.2.22",
   "type": "module",
   "exports": {
     "./AppSidebar": {