@djangocfg/api 2.1.449 → 2.1.450

package/src/auth/utils/jwt.ts

@@ -0,0 +1,66 @@
+/**
+ * JWT inspection helpers (browser-safe, dependency-free).
+ *
+ * These decode ONLY the `exp` claim to reason about token freshness on the
+ * client. They do NOT verify the signature — that is the server's job. The
+ * point is purely to avoid firing doomed requests with a token we can already
+ * see is malformed or expired, and to let auth bootstrap collapse a dead
+ * session to the login form instead of hanging on a preloader.
+ *
+ * A JWT that cannot be decoded is treated as EXPIRED/invalid (fail-closed):
+ * better to re-authenticate than to loop on 401s with garbage in storage.
+ */
+
+/** Base64url-decode a JWT segment. Returns null on any malformation. */
+function decodeSegment(segment: string): unknown {
+  try {
+    const base64 = segment.replace(/-/g, '+').replace(/_/g, '/');
+    // atob is defined in browsers and modern Node (global). Guard anyway.
+    if (typeof atob !== 'function') return null;
+    const json = atob(base64);
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract the `exp` claim (epoch ms), or null if the token is undecodable or
+ * has no numeric `exp`.
+ */
+export function getTokenExpiry(token: string | null | undefined): number | null {
+  if (!token || typeof token !== 'string') return null;
+  const parts = token.split('.');
+  if (parts.length !== 3) return null; // not a well-formed JWT
+  const payload = decodeSegment(parts[1]);
+  if (!payload || typeof payload !== 'object') return null;
+  const exp = (payload as { exp?: unknown }).exp;
+  if (typeof exp !== 'number' || !Number.isFinite(exp)) return null;
+  return exp * 1000;
+}
+
+/**
+ * True when the token is missing, malformed, or already past its `exp`.
+ * `skewMs` treats a token expiring within the skew window as already expired
+ * (default 0). Fail-closed: an undecodable token is considered expired.
+ */
+export function isTokenExpired(token: string | null | undefined, skewMs = 0, now = Date.now()): boolean {
+  const expiry = getTokenExpiry(token);
+  if (expiry === null) return true; // undecodable / no exp → treat as dead
+  return expiry - skewMs <= now;
+}
+
+/**
+ * True when a valid token exists but expires within `thresholdMs` (used by the
+ * proactive refresher). A missing/undecodable token returns false here — that
+ * case is handled by the "expired" path, not the "expiring soon" path.
+ */
+export function isTokenExpiringSoon(
+  token: string | null | undefined,
+  thresholdMs: number,
+  now = Date.now(),
+): boolean {
+  const expiry = getTokenExpiry(token);
+  if (expiry === null) return false;
+  return expiry - now < thresholdMs;
+}