@djangocfg/api 2.1.455 → 2.1.456

package/src/_api/generated/helpers/auth.ts

@@ -149,6 +149,123 @@ let _refreshInflight: Promise<string | null> | null = null;
 /** Marker header — set on retried requests so we never loop on 401. */
 const RETRY_MARKER = 'X-Auth-Retry';
 
+// ── Reactive session snapshot ───────────────────────────────────────────────
+//
+// The store is the single source of truth for "am I logged in". React (or any
+// listener) subscribes via `auth.subscribe` + `auth.getSnapshot` — designed to
+// plug straight into `useSyncExternalStore`. The snapshot flips automatically
+// on: token writes, refresh success/failure, cross-tab storage events, and an
+// internal timer armed to the next JWT `exp` boundary.
+
+export type SessionStatus = 'authenticated' | 'anonymous';
+
+export type SessionSnapshot = {
+  /** 'authenticated' = a live access token OR a live refresh token exists. */
+  status: SessionStatus;
+  /** ms-epoch expiry of the current access token (null: no token / no exp). */
+  accessExpiresAt: number | null;
+};
+
+/** Decode a JWT `exp` claim to ms epoch. Null on any malformed input. */
+function jwtExpMs(token: string): number | null {
+  try {
+    const payload = token.split('.')[1];
+    if (!payload) return null;
+    const json = JSON.parse(atob(payload.replace(/-/g, '+').replace(/_/g, '/')));
+    return typeof json.exp === 'number' ? json.exp * 1000 : null;
+  } catch { return null; }
+}
+
+function computeSnapshot(): SessionSnapshot {
+  const access = _storage.get(ACCESS_KEY);
+  const refresh = _storage.get(REFRESH_KEY);
+  const now = Date.now();
+  const accessExp = access ? jwtExpMs(access) : null;
+  const accessAlive = access !== null && (accessExp === null || accessExp > now);
+  const refreshExp = refresh ? jwtExpMs(refresh) : null;
+  const refreshAlive = refresh !== null && (refreshExp === null || refreshExp > now);
+  return {
+    status: accessAlive || refreshAlive ? 'authenticated' : 'anonymous',
+    accessExpiresAt: accessExp,
+  };
+}
+
+/** Stable object for SSR — `useSyncExternalStore` needs referential equality. */
+const SERVER_SNAPSHOT: SessionSnapshot = { status: 'anonymous', accessExpiresAt: null };
+
+/** Same-tab, cross-store sync channel. An app can host several copies of this
+ * generated store (separate JS modules) sharing the same storage keys; the
+ * `storage` event only fires in OTHER tabs, so a window event bridges them
+ * synchronously within the tab (login in one store flips all of them). */
+const SESSION_SYNC_EVENT = `cfg-auth:changed:${ACCESS_KEY}`;
+
+let _snapshot: SessionSnapshot = computeSnapshot();
+const _sessionListeners = new Set<() => void>();
+let _expiryTimer: ReturnType<typeof setTimeout> | null = null;
+let _storageListenerInstalled = false;
+
+/** Re-arm the timer that flips the snapshot exactly when a token expires. */
+function scheduleExpiryFlip(): void {
+  if (!isBrowser) return;
+  if (_expiryTimer !== null) { clearTimeout(_expiryTimer); _expiryTimer = null; }
+  if (_sessionListeners.size === 0) return;
+  const now = Date.now();
+  const exps: number[] = [];
+  const access = _storage.get(ACCESS_KEY);
+  const refresh = _storage.get(REFRESH_KEY);
+  const accessExp = access ? jwtExpMs(access) : null;
+  const refreshExp = refresh ? jwtExpMs(refresh) : null;
+  if (accessExp !== null && accessExp > now) exps.push(accessExp);
+  if (refreshExp !== null && refreshExp > now) exps.push(refreshExp);
+  if (!exps.length) return;
+  // +250ms grace so the token is REALLY expired when we flip; clamp to the
+  // max signed-32-bit setTimeout delay (~24.8 days).
+  const delay = Math.min(Math.min(...exps) - now + 250, 0x7fffffff);
+  _expiryTimer = setTimeout(notifySessionChanged, delay);
+}
+
+/** Recompute the snapshot; notify subscribers only when it actually changed. */
+function notifySessionChanged(): void {
+  const next = computeSnapshot();
+  const changed =
+    next.status !== _snapshot.status ||
+    next.accessExpiresAt !== _snapshot.accessExpiresAt;
+  if (changed) _snapshot = next;
+  scheduleExpiryFlip();
+  if (!changed) return;
+  for (const listener of Array.from(_sessionListeners)) {
+    try { listener(); } catch {}
+  }
+  // Wake sibling stores in this tab. Re-entrant but convergent: a store that
+  // recomputes to the SAME snapshot doesn't re-dispatch, so the cascade stops
+  // after every store has caught up.
+  if (isBrowser) {
+    try { window.dispatchEvent(new Event(SESSION_SYNC_EVENT)); } catch {}
+  }
+}
+
+/** Cross-tab + cross-store sync — `storage` events only fire in OTHER tabs;
+ * the window event covers sibling stores in THIS tab. Either way a login or
+ * logout anywhere flips every snapshot reading the same keys. */
+function ensureStorageSync(): void {
+  if (!isBrowser || _storageListenerInstalled) return;
+  _storageListenerInstalled = true;
+  window.addEventListener('storage', (e) => {
+    if (e.key === null || e.key === ACCESS_KEY || e.key === REFRESH_KEY) {
+      notifySessionChanged();
+    }
+  });
+  window.addEventListener(SESSION_SYNC_EVENT, () => notifySessionChanged());
+}
+
+/**
+ * Terminal-401 subscribers. Unlike the single `onUnauthorized` slot these
+ * compose: each registration returns its own unsubscribe, so StrictMode
+ * double-mounts and multiple packages can't clobber each other.
+ */
+type SessionExpiredHandler = (response: Response) => void;
+const _sessionExpiredHandlers = new Set<SessionExpiredHandler>();
+
 /**
  * Captured reference to the shared Hey API client. Set exactly once by
  * `installAuthOnClient(client)` (called from client.gen.ts). All `auth.set*`
@@ -194,15 +311,79 @@ export const auth = {
   setStorageMode(mode: StorageMode): void {
     _storageMode = mode;
     _storage = mode === 'cookie' ? cookieBackend : localStorageBackend;
+    notifySessionChanged();
   },
 
   // ── Bearer token ──────────────────────────────────────────────────
   getToken(): string | null { return _storage.get(ACCESS_KEY); },
-  setToken(token: string | null): void { _storage.set(ACCESS_KEY, token); },
+  setToken(token: string | null): void {
+    _storage.set(ACCESS_KEY, token);
+    notifySessionChanged();
+  },
   getRefreshToken(): string | null { return _storage.get(REFRESH_KEY); },
-  setRefreshToken(token: string | null): void { _storage.set(REFRESH_KEY, token); },
-  clearTokens(): void { _storage.set(ACCESS_KEY, null); _storage.set(REFRESH_KEY, null); },
-  isAuthenticated(): boolean { return _storage.get(ACCESS_KEY) !== null; },
+  setRefreshToken(token: string | null): void {
+    _storage.set(REFRESH_KEY, token);
+    notifySessionChanged();
+  },
+  clearTokens(): void {
+    _storage.set(ACCESS_KEY, null);
+    _storage.set(REFRESH_KEY, null);
+    notifySessionChanged();
+  },
+  /** Session-aware: token PRESENT and not past its `exp` (or a live refresh
+   * token exists that can mint one). Prefer `getSnapshot().status` in React. */
+  isAuthenticated(): boolean { return computeSnapshot().status === 'authenticated'; },
+
+  // ── Session (the ONE write path for login/logout flows) ──────────
+  /**
+   * Persist a token pair atomically. Every login flow (OTP verify, 2FA,
+   * OAuth callback) and the refresh handler should end here — do NOT
+   * scatter `setToken`/`setRefreshToken` pairs through app code.
+   * `refresh: undefined` keeps the current refresh token (access-only
+   * rotation); `refresh: null` explicitly drops it.
+   */
+  setSession(tokens: { access: string; refresh?: string | null }): void {
+    _storage.set(ACCESS_KEY, tokens.access);
+    if (tokens.refresh !== undefined) _storage.set(REFRESH_KEY, tokens.refresh);
+    notifySessionChanged();
+  },
+  clearSession(): void { auth.clearTokens(); },
+
+  // ── Reactive snapshot (for useSyncExternalStore) ──────────────────
+  /**
+   * @example React:
+   *   const session = useSyncExternalStore(
+   *     auth.subscribe, auth.getSnapshot, auth.getServerSnapshot,
+   *   );
+   *   const isAuthenticated = session.status === 'authenticated';
+   */
+  getSnapshot(): SessionSnapshot { return _snapshot; },
+  getServerSnapshot(): SessionSnapshot { return SERVER_SNAPSHOT; },
+  subscribe(listener: () => void): () => void {
+    ensureStorageSync();
+    _sessionListeners.add(listener);
+    // Sync state & arm the expiry timer now that someone is listening.
+    notifySessionChanged();
+    return () => {
+      _sessionListeners.delete(listener);
+      if (_sessionListeners.size === 0 && _expiryTimer !== null) {
+        clearTimeout(_expiryTimer);
+        _expiryTimer = null;
+      }
+    };
+  },
+
+  /**
+   * Fired on TERMINAL 401 — after the refresh+retry path is exhausted.
+   * The store has already cleared the session before calling back, so
+   * handlers only need to route to login (no clear-then-redirect
+   * ordering to get wrong). Returns an unsubscribe function; multiple
+   * handlers compose (unlike the legacy single-slot `onUnauthorized`).
+   */
+  onSessionExpired(cb: SessionExpiredHandler): () => void {
+    _sessionExpiredHandlers.add(cb);
+    return () => { _sessionExpiredHandlers.delete(cb); };
+  },
 
   // ── API key ───────────────────────────────────────────────────────
   getApiKey(): string | null {
@@ -278,23 +459,53 @@ export const auth = {
 };
 
 /**
- * Run the user-supplied refresh handler under single-flight, persist
- * the new tokens, and return the fresh access token (or null on any
- * failure path). All concurrent 401s share the same in-flight promise.
+ * Run the user-supplied refresh handler, persist the rotated tokens, and
+ * return the fresh access token (or null on any failure path).
+ *
+ * TWO layers of coordination, because a single app can host MULTIPLE copies of
+ * this generated store (e.g. `@djangocfg/api` + a locally-generated client +
+ * `@djangocfg/monitor`), all sharing the SAME refresh token in storage:
+ *
+ *   1. Per-store single-flight (`_refreshInflight`) — concurrent 401s WITHIN
+ *      this module coalesce onto one promise. Fast path, no lock.
+ *   2. Cross-store mutex (`navigator.locks`) keyed on the refresh-token storage
+ *      key — serializes refreshes across EVERY store in the app. The refresh
+ *      token is re-read INSIDE the lock, so if another store already rotated it
+ *      (SimpleJWT `ROTATE_REFRESH_TOKENS` blacklists the old one), the loser
+ *      picks up the fresh access token instead of re-POSTing a blacklisted
+ *      refresh token and getting a spurious 401 → logout.
+ *
+ * Web Locks is browser-only; on SSR / older runtimes we degrade gracefully to
+ * layer 1 alone (correct whenever at most one store refreshes).
  */
 async function tryRefresh(): Promise<string | null> {
   if (_refreshInflight) return _refreshInflight;
   if (!_refreshHandler) return null;
-  const refresh = auth.getRefreshToken();
-  if (!refresh) return null;
+
+  // The critical section — re-reads the refresh token every time it runs, so a
+  // rotation performed by another store (or by us on a prior attempt) is always
+  // observed. Returns the fresh access token, or null on any failure.
+  const runRefresh = async (): Promise<string | null> => {
+    const refresh = auth.getRefreshToken();
+    if (!refresh) return null;
+    const result = await _refreshHandler!(refresh);
+    if (!result?.access) return null;
+    auth.setToken(result.access);
+    if (result.refresh) auth.setRefreshToken(result.refresh);
+    return result.access;
+  };
 
   _refreshInflight = (async () => {
     try {
-      const result = await _refreshHandler!(refresh);
-      if (!result?.access) return null;
-      auth.setToken(result.access);
-      if (result.refresh) auth.setRefreshToken(result.refresh);
-      return result.access;
+      // Serialize across all stores in this app when Web Locks is available.
+      const locks =
+        typeof navigator !== 'undefined'
+          ? (navigator as Navigator & { locks?: LockManager }).locks
+          : undefined;
+      if (locks?.request) {
+        return await locks.request(`${REFRESH_KEY}:refresh`, runRefresh);
+      }
+      return await runRefresh();
     } catch {
       return null;
     } finally {
@@ -305,6 +516,23 @@ async function tryRefresh(): Promise<string | null> {
   return _refreshInflight;
 }
 
+/**
+ * Terminal 401 — no refresh path can recover this session. The store clears
+ * its own tokens FIRST (subscribers flip to 'anonymous' via the snapshot),
+ * then notifies `onSessionExpired` subscribers and the legacy
+ * `onUnauthorized` slot. Apps only route to login; they never own the
+ * clear-before-redirect ordering.
+ */
+function expireSession(response: Response): void {
+  auth.clearTokens();
+  for (const cb of Array.from(_sessionExpiredHandlers)) {
+    try { cb(response); } catch {}
+  }
+  if (_onUnauthorized) {
+    try { _onUnauthorized(response); } catch {}
+  }
+}
+
 /**
  * Wire the shared client to the global auth store. Called exactly
  * once from `client.gen.ts` (post-processed) right after
@@ -476,7 +704,7 @@ export function installAuthOnClient(client: HeyClient): void {
     if (locale) request.headers.set('Accept-Language', locale);
 
     // Only set X-API-Key from global store if NOT already present on the
-    // request — per-request headers (option 1 above) take precedence.
+    // request — per-request headers take precedence.
     const apiKey = auth.getApiKey();
     if (apiKey && !request.headers.has('X-API-Key')) request.headers.set('X-API-Key', apiKey);
 
@@ -496,9 +724,6 @@ export function installAuthOnClient(client: HeyClient): void {
     return request;
   });
 
-  // Wrap raw JSON error objects (thrown by hey-api on non-2xx responses) into
-  // APIError so callers can do `error instanceof APIError` and read
-  // `error.statusCode` / `error.response` consistently.
   client.interceptors.error.use((err, res, req) => {
     if (err instanceof APIError) return err;
     const url = (req as Request | undefined)?.url ?? '';
@@ -507,22 +732,19 @@ export function installAuthOnClient(client: HeyClient): void {
     return new APIError(status, statusText, err, url);
   });
 
+
   client.interceptors.response.use(async (response, request) => {
     if (response.status !== 401) return response;
 
     // Already retried once — give up to avoid loops.
     if (request.headers.get(RETRY_MARKER)) {
-      if (_onUnauthorized) {
-        try { _onUnauthorized(response); } catch {}
-      }
+      expireSession(response);
       return response;
     }
 
     const newToken = await tryRefresh();
     if (!newToken) {
-      if (_onUnauthorized) {
-        try { _onUnauthorized(response); } catch {}
-      }
+      expireSession(response);
       return response;
     }
 
@@ -540,18 +762,41 @@ export function installAuthOnClient(client: HeyClient): void {
     }
     try {
       const retried = await fetch(retry);
-      if (retried.status === 401 && _onUnauthorized) {
-        try { _onUnauthorized(retried); } catch {}
-      }
+      if (retried.status === 401) expireSession(retried);
       return retried;
     } catch {
-      // Network error on retry — surface the original 401.
-      if (_onUnauthorized) {
-        try { _onUnauthorized(response); } catch {}
-      }
+      // Network error on the retry. The refresh SUCCEEDED (we hold a fresh
+      // token), so the session is alive — a transient network blip must NOT
+      // log the user out. Surface the original 401 to the caller only.
       return response;
     }
   });
 }
 
+// ── Default refresh handler (auto-registered) ──────────────────────────────
+//
+// Wires the SimpleJWT refresh endpoint so a 401 transparently refreshes and
+// retries. Registered at import time; an app can override it afterwards with
+// `auth.setRefreshHandler(...)` (last write wins). Returns the ROTATED refresh
+// token so the store persists it — `ROTATE_REFRESH_TOKENS` blacklists the old
+// one, so reusing it would 401 on the next refresh.
+//
+// The SDK is imported LAZILY inside the handler: a static import would close
+// the cycle auth.ts → sdk.gen → client.gen → auth.ts and TDZ-crash whichever
+// module evaluates first. The dynamic import resolves once, then caches.
+auth.setRefreshHandler(async (refresh) => {
+  try {
+    const { CfgAccountsAuth } = await import('../sdk.gen');
+    const { data } = await CfgAccountsAuth.cfgAccountsTokenRefreshCreate({
+      body: { refresh },
+      throwOnError: true,
+    });
+    return data?.access
+      ? { access: data.access, refresh: data.refresh ?? refresh }
+      : null;
+  } catch {
+    return null;
+  }
+});
+
 export type Auth = typeof auth;

package/src/_api/generated/openapi.json

@@ -241,6 +241,9 @@
           },
           {
             "jwtAuthWithLastLogin": []
+          },
+          {
+            "tokenAuth": []
           }
         ],
         "responses": {
@@ -282,6 +285,9 @@
           },
           {
             "jwtAuthWithLastLogin": []
+          },
+          {
+            "tokenAuth": []
           }
         ],
         "responses": {
@@ -460,6 +466,9 @@
           {
             "jwtAuthWithLastLogin": []
           },
+          {
+            "tokenAuth": []
+          },
           {}
         ],
         "responses": {
@@ -531,6 +540,9 @@
           {
             "jwtAuthWithLastLogin": []
           },
+          {
+            "tokenAuth": []
+          },
           {}
         ],
         "responses": {
@@ -642,6 +654,9 @@
           },
           {
             "jwtAuthWithLastLogin": []
+          },
+          {
+            "tokenAuth": []
           }
         ],
         "responses": {
@@ -756,6 +771,16 @@
                   "summary": "Profile Update with Avatar"
                 }
               }
+            },
+            "multipart/form-data": {
+              "schema": {
+                "$ref": "#/components/schemas/CfgUserUpdateRequest"
+              }
+            },
+            "application/x-www-form-urlencoded": {
+              "schema": {
+                "$ref": "#/components/schemas/CfgUserUpdateRequest"
+              }
             }
           }
         },
@@ -826,6 +851,16 @@
                   "summary": "Profile Update with Avatar"
                 }
               }
+            },
+            "multipart/form-data": {
+              "schema": {
+                "$ref": "#/components/schemas/PatchedCfgUserUpdateRequest"
+              }
+            },
+            "application/x-www-form-urlencoded": {
+              "schema": {
+                "$ref": "#/components/schemas/PatchedCfgUserUpdateRequest"
+              }
             }
           }
         },
@@ -898,6 +933,16 @@
                   "summary": "Valid Profile Update"
                 }
               }
+            },
+            "multipart/form-data": {
+              "schema": {
+                "$ref": "#/components/schemas/CfgUserUpdateRequest"
+              }
+            },
+            "application/x-www-form-urlencoded": {
+              "schema": {
+                "$ref": "#/components/schemas/CfgUserUpdateRequest"
+              }
             }
           }
         },
@@ -968,6 +1013,16 @@
                   "summary": "Valid Profile Update"
                 }
               }
+            },
+            "multipart/form-data": {
+              "schema": {
+                "$ref": "#/components/schemas/PatchedCfgUserUpdateRequest"
+              }
+            },
+            "application/x-www-form-urlencoded": {
+              "schema": {
+                "$ref": "#/components/schemas/PatchedCfgUserUpdateRequest"
+              }
             }
           }
         },
@@ -1014,6 +1069,31 @@
         "x-async-capable": false
       }
     },
+    "/cfg/accounts/token/blacklist/": {
+      "post": {
+        "operationId": "cfg_accounts_token_blacklist_create",
+        "description": "Revoke a refresh token (logout).\n\nBlacklists the posted refresh token so it can never mint another access\ntoken. Called best-effort by the client's logout — without it, \"logout\"\nis purely client-side and a stolen refresh token survives until expiry.",
+        "tags": [
+          "cfg_accounts_auth"
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TokenBlacklistRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "No response body"
+          }
+        },
+        "x-async-capable": false
+      }
+    },
     "/cfg/accounts/token/refresh/": {
       "post": {
         "operationId": "cfg_accounts_token_refresh_create",
@@ -1060,6 +1140,9 @@
           },
           {
             "jwtAuthWithLastLogin": []
+          },
+          {
+            "tokenAuth": []
           }
         ],
         "responses": {
@@ -1110,6 +1193,9 @@
           },
           {
             "jwtAuthWithLastLogin": []
+          },
+          {
+            "tokenAuth": []
           }
         ],
         "responses": {
@@ -1150,6 +1236,9 @@
           },
           {
             "jwtAuthWithLastLogin": []
+          },
+          {
+            "tokenAuth": []
           }
         ],
         "responses": {
@@ -1190,6 +1279,9 @@
           },
           {
             "jwtAuthWithLastLogin": []
+          },
+          {
+            "tokenAuth": []
           }
         ],
         "responses": {
@@ -1231,6 +1323,9 @@
           },
           {
             "jwtAuthWithLastLogin": []
+          },
+          {
+            "tokenAuth": []
           }
         ],
         "responses": {
@@ -1264,6 +1359,9 @@
           },
           {
             "jwtAuthWithLastLogin": []
+          },
+          {
+            "tokenAuth": []
           }
         ],
         "responses": {
@@ -1313,6 +1411,9 @@
           },
           {
             "jwtAuthWithLastLogin": []
+          },
+          {
+            "tokenAuth": []
           }
         ],
         "responses": {
@@ -1363,6 +1464,9 @@
           },
           {
             "jwtAuthWithLastLogin": []
+          },
+          {
+            "tokenAuth": []
           }
         ],
         "responses": {
@@ -1414,6 +1518,9 @@
           {
             "jwtAuthWithLastLogin": []
           },
+          {
+            "tokenAuth": []
+          },
           {}
         ],
         "responses": {
@@ -1475,6 +1582,9 @@
           {
             "jwtAuthWithLastLogin": []
           },
+          {
+            "tokenAuth": []
+          },
           {}
         ],
         "responses": {
@@ -2439,6 +2549,19 @@
           "secret"
         ]
       },
+      "TokenBlacklistRequest": {
+        "type": "object",
+        "properties": {
+          "refresh": {
+            "type": "string",
+            "writeOnly": true,
+            "minLength": 1
+          }
+        },
+        "required": [
+          "refresh"
+        ]
+      },
       "TokenRefresh": {
         "type": "object",
         "properties": {
@@ -2943,6 +3066,12 @@
         "type": "http",
         "scheme": "bearer",
         "bearerFormat": "JWT"
+      },
+      "tokenAuth": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "Authorization",
+        "description": "Token-based authentication with required prefix \"Token\""
       }
     }
   },