@djangocfg/api 2.1.448 → 2.1.450

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/api",
-  "version": "2.1.448",
+  "version": "2.1.450",
   "description": "Auto-generated TypeScript API client with React hooks, SWR integration, and Zod validation for Django REST Framework backends",
   "keywords": [
     "django",
@@ -71,7 +71,9 @@
     "build": "tsup",
     "clean": "rm -rf dist",
     "dev": "tsup --watch",
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "peerDependencies": {
     "consola": "^3.4.2",
@@ -84,10 +86,11 @@
   "devDependencies": {
     "@types/node": "^25.2.3",
     "@types/react": "^19.2.15",
-    "@djangocfg/typescript-config": "^2.1.448",
+    "@djangocfg/typescript-config": "^2.1.450",
     "next": "^16.2.2",
     "react": "^19.2.4",
     "tsup": "^8.5.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^3.1.4"
   }
 }

package/src/_api/generated/_cfg_accounts/api.ts

@@ -81,6 +81,14 @@ export class API {
   ): void {
     auth.setRefreshHandler(fn);
   }
+  /**
+   * Proactively refresh now via the registered handler, sharing the single
+   * 401-recovery flight (rotation + dedup + rotated-token persistence).
+   * See `auth.refreshNow`.
+   */
+  refreshNow(): Promise<string | null> {
+    return auth.refreshNow();
+  }
 }
 
 export { CfgAccountsApiKey, CfgAccountsOauth, CfgAccounts, CfgAccountsProfile, CfgAccountsAuth };

package/src/_api/generated/_cfg_accounts/openapi.json

@@ -1505,21 +1505,19 @@
           },
           "is_new_user": {
             "type": "boolean",
+            "default": false,
             "description": "True if a new user was created during this OAuth flow"
           },
           "is_new_connection": {
             "type": "boolean",
+            "default": false,
             "description": "True if a new OAuth connection was created"
           },
           "should_prompt_2fa": {
             "type": "boolean",
             "description": "True if user should be prompted to enable 2FA"
           }
-        },
-        "required": [
-          "is_new_connection",
-          "is_new_user"
-        ]
+        }
       },
       "OTPErrorResponse": {
         "type": "object",
@@ -1574,6 +1572,17 @@
           "message": {
             "type": "string",
             "description": "Success message"
+          },
+          "webmail": {
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/WebmailLink"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Webmail deep-link for the recipient's provider, or null if the domain is unknown."
           }
         },
         "required": [
@@ -1865,6 +1874,76 @@
           "last_login",
           "unanswered_messages_count"
         ]
+      },
+      "WebmailLink": {
+        "type": "object",
+        "description": "Deep-link that opens the user's webmail on a search for our login email.\n\nPresent only when the recipient's email domain maps to a known webmail\nprovider (Gmail, Outlook, Mail.ru, Yandex, iCloud, …). For unknown/corporate\ndomains this whole object is null and the frontend shows no button.",
+        "properties": {
+          "provider": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/WebmailLinkProviderEnum"
+              }
+            ],
+            "description": "Provider slug (e.g. 'gmail', 'outlook', 'mail_ru'). Also selects the brand icon on the frontend.\n\n* `gmail` - gmail\n* `outlook` - outlook\n* `yahoo` - yahoo\n* `icloud` - icloud\n* `proton` - proton\n* `zoho` - zoho\n* `aol` - aol\n* `fastmail` - fastmail\n* `gmx` - gmx\n* `mailcom` - mailcom\n* `mail_ru` - mail_ru\n* `yandex` - yandex\n* `rambler` - rambler\n* `qq` - qq\n* `netease` - netease\n* `sina` - sina\n* `aliyun` - aliyun\n* `naver` - naver\n* `daum` - daum\n* `web_de` - web_de\n* `tonline` - tonline\n* `seznam` - seznam\n* `wp_pl` - wp_pl\n* `o2_pl` - o2_pl\n* `interia` - interia\n* `libero` - libero\n* `virgilio` - virgilio\n* `orange` - orange\n* `laposte` - laposte\n* `free_fr` - free_fr\n* `sfr` - sfr"
+          },
+          "provider_name": {
+            "type": "string",
+            "description": "Human-facing provider name, e.g. 'Gmail'."
+          },
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "Absolute URL to open in a new tab (a sender-filtered search, or the inbox as fallback)."
+          },
+          "is_search": {
+            "type": "boolean",
+            "description": "True if the URL opens a search filtered to our sender; False if it only opens the inbox."
+          }
+        },
+        "required": [
+          "is_search",
+          "provider",
+          "provider_name",
+          "url"
+        ]
+      },
+      "WebmailLinkProviderEnum": {
+        "enum": [
+          "gmail",
+          "outlook",
+          "yahoo",
+          "icloud",
+          "proton",
+          "zoho",
+          "aol",
+          "fastmail",
+          "gmx",
+          "mailcom",
+          "mail_ru",
+          "yandex",
+          "rambler",
+          "qq",
+          "netease",
+          "sina",
+          "aliyun",
+          "naver",
+          "daum",
+          "web_de",
+          "tonline",
+          "seznam",
+          "wp_pl",
+          "o2_pl",
+          "interia",
+          "libero",
+          "virgilio",
+          "orange",
+          "laposte",
+          "free_fr",
+          "sfr"
+        ],
+        "type": "string",
+        "description": "* `gmail` - gmail\n* `outlook` - outlook\n* `yahoo` - yahoo\n* `icloud` - icloud\n* `proton` - proton\n* `zoho` - zoho\n* `aol` - aol\n* `fastmail` - fastmail\n* `gmx` - gmx\n* `mailcom` - mailcom\n* `mail_ru` - mail_ru\n* `yandex` - yandex\n* `rambler` - rambler\n* `qq` - qq\n* `netease` - netease\n* `sina` - sina\n* `aliyun` - aliyun\n* `naver` - naver\n* `daum` - daum\n* `web_de` - web_de\n* `tonline` - tonline\n* `seznam` - seznam\n* `wp_pl` - wp_pl\n* `o2_pl` - o2_pl\n* `interia` - interia\n* `libero` - libero\n* `virgilio` - virgilio\n* `orange` - orange\n* `laposte` - laposte\n* `free_fr` - free_fr\n* `sfr` - sfr"
       }
     },
     "securitySchemes": {

package/src/_api/generated/_cfg_accounts/schemas/OAuthTokenResponse.ts

@@ -10,8 +10,8 @@ export const OAuthTokenResponseSchema = z.object({
   access: z.string().nullable().optional(),
   refresh: z.string().nullable().optional(),
   user: z.object({}).passthrough().nullable().optional(),
-  is_new_user: z.boolean(),
-  is_new_connection: z.boolean(),
+  is_new_user: z.boolean().default(false).optional(),
+  is_new_connection: z.boolean().default(false).optional(),
   should_prompt_2fa: z.boolean().optional(),
 });
 

package/src/_api/generated/_cfg_accounts/schemas/OTPRequestResponse.ts

@@ -3,9 +3,11 @@
 // DO NOT EDIT — re-run `make gen-clients`.
 
 import { z } from "zod";
+import { WebmailLinkSchema } from "./WebmailLink";
 
 export const OTPRequestResponseSchema = z.object({
   message: z.string(),
+  webmail: WebmailLinkSchema.nullable().optional(),
 });
 
 export type OTPRequestResponse = z.infer<typeof OTPRequestResponseSchema>;

package/src/_api/generated/_cfg_accounts/schemas/WebmailLink.ts

@@ -0,0 +1,15 @@
+// AUTO-GENERATED by cmdop_server / devtools.generator.ts_extras
+// Source: OpenAPI 3.1 components.schemas
+// DO NOT EDIT — re-run `make gen-clients`.
+
+import { z } from "zod";
+import { WebmailLinkProviderEnumSchema } from "./WebmailLinkProviderEnum";
+
+export const WebmailLinkSchema = z.object({
+  provider: WebmailLinkProviderEnumSchema,
+  provider_name: z.string(),
+  url: z.string(),
+  is_search: z.boolean(),
+});
+
+export type WebmailLink = z.infer<typeof WebmailLinkSchema>;

package/src/_api/generated/_cfg_accounts/schemas/WebmailLinkProviderEnum.ts

@@ -0,0 +1,9 @@
+// AUTO-GENERATED by cmdop_server / devtools.generator.ts_extras
+// Source: OpenAPI 3.1 components.schemas
+// DO NOT EDIT — re-run `make gen-clients`.
+
+import { z } from "zod";
+
+export const WebmailLinkProviderEnumSchema = z.enum(["gmail", "outlook", "yahoo", "icloud", "proton", "zoho", "aol", "fastmail", "gmx", "mailcom", "mail_ru", "yandex", "rambler", "qq", "netease", "sina", "aliyun", "naver", "daum", "web_de", "tonline", "seznam", "wp_pl", "o2_pl", "interia", "libero", "virgilio", "orange", "laposte", "free_fr", "sfr"]);
+
+export type WebmailLinkProviderEnum = z.infer<typeof WebmailLinkProviderEnumSchema>;

package/src/_api/generated/_cfg_accounts/schemas/index.ts

@@ -28,5 +28,7 @@ export * from "./PatchedCfgUserUpdateRequest";
 export * from "./TokenRefresh";
 export * from "./TokenRefreshRequest";
 export * from "./User";
+export * from "./WebmailLink";
+export * from "./WebmailLinkProviderEnum";
 export * from "./cfg_accounts_oauth_connections_response_200_AutoRef";
 export * from "./cfg_accounts_oauth_disconnect_response_200_AutoRef";

package/src/_api/generated/_cfg_centrifugo/api.ts

@@ -73,6 +73,14 @@ export class API {
   ): void {
     auth.setRefreshHandler(fn);
   }
+  /**
+   * Proactively refresh now via the registered handler, sharing the single
+   * 401-recovery flight (rotation + dedup + rotated-token persistence).
+   * See `auth.refreshNow`.
+   */
+  refreshNow(): Promise<string | null> {
+    return auth.refreshNow();
+  }
 }
 
 export { CfgCentrifugo };

package/src/_api/generated/_cfg_totp/api.ts

@@ -79,6 +79,14 @@ export class API {
   ): void {
     auth.setRefreshHandler(fn);
   }
+  /**
+   * Proactively refresh now via the registered handler, sharing the single
+   * 401-recovery flight (rotation + dedup + rotated-token persistence).
+   * See `auth.refreshNow`.
+   */
+  refreshNow(): Promise<string | null> {
+    return auth.refreshNow();
+  }
 }
 
 export { CfgTotpBackupCodes, CfgTotp, CfgTotpSetup, CfgTotpVerify };

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

@@ -263,6 +263,18 @@ export const auth = {
   setRefreshHandler(fn: RefreshHandler | null): void {
     _refreshHandler = fn;
   },
+
+  /**
+   * Proactively run the registered refresh handler right now, reusing the
+   * SAME single-flight promise as the 401-recovery interceptor. Callers
+   * (e.g. an expiry timer / focus / reconnect) get token rotation,
+   * de-duplication and rotated-token persistence for free — they must NOT
+   * re-implement any of it. Returns the fresh access token, or null if
+   * there is no handler / no refresh token / the refresh failed.
+   */
+  refreshNow(): Promise<string | null> {
+    return tryRefresh();
+  },
 };
 
 /**

package/src/_api/generated/openapi.json

@@ -2200,21 +2200,19 @@
           },
           "is_new_user": {
             "type": "boolean",
+            "default": false,
             "description": "True if a new user was created during this OAuth flow"
           },
           "is_new_connection": {
             "type": "boolean",
+            "default": false,
             "description": "True if a new OAuth connection was created"
           },
           "should_prompt_2fa": {
             "type": "boolean",
             "description": "True if user should be prompted to enable 2FA"
           }
-        },
-        "required": [
-          "is_new_connection",
-          "is_new_user"
-        ]
+        }
       },
       "OTPErrorResponse": {
         "type": "object",
@@ -2269,6 +2267,17 @@
           "message": {
             "type": "string",
             "description": "Success message"
+          },
+          "webmail": {
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/WebmailLink"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Webmail deep-link for the recipient's provider, or null if the domain is unknown."
           }
         },
         "required": [
@@ -2827,6 +2836,76 @@
           "user"
         ]
       },
+      "WebmailLink": {
+        "type": "object",
+        "description": "Deep-link that opens the user's webmail on a search for our login email.\n\nPresent only when the recipient's email domain maps to a known webmail\nprovider (Gmail, Outlook, Mail.ru, Yandex, iCloud, …). For unknown/corporate\ndomains this whole object is null and the frontend shows no button.",
+        "properties": {
+          "provider": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/WebmailLinkProviderEnum"
+              }
+            ],
+            "description": "Provider slug (e.g. 'gmail', 'outlook', 'mail_ru'). Also selects the brand icon on the frontend.\n\n* `gmail` - gmail\n* `outlook` - outlook\n* `yahoo` - yahoo\n* `icloud` - icloud\n* `proton` - proton\n* `zoho` - zoho\n* `aol` - aol\n* `fastmail` - fastmail\n* `gmx` - gmx\n* `mailcom` - mailcom\n* `mail_ru` - mail_ru\n* `yandex` - yandex\n* `rambler` - rambler\n* `qq` - qq\n* `netease` - netease\n* `sina` - sina\n* `aliyun` - aliyun\n* `naver` - naver\n* `daum` - daum\n* `web_de` - web_de\n* `tonline` - tonline\n* `seznam` - seznam\n* `wp_pl` - wp_pl\n* `o2_pl` - o2_pl\n* `interia` - interia\n* `libero` - libero\n* `virgilio` - virgilio\n* `orange` - orange\n* `laposte` - laposte\n* `free_fr` - free_fr\n* `sfr` - sfr"
+          },
+          "provider_name": {
+            "type": "string",
+            "description": "Human-facing provider name, e.g. 'Gmail'."
+          },
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "Absolute URL to open in a new tab (a sender-filtered search, or the inbox as fallback)."
+          },
+          "is_search": {
+            "type": "boolean",
+            "description": "True if the URL opens a search filtered to our sender; False if it only opens the inbox."
+          }
+        },
+        "required": [
+          "is_search",
+          "provider",
+          "provider_name",
+          "url"
+        ]
+      },
+      "WebmailLinkProviderEnum": {
+        "enum": [
+          "gmail",
+          "outlook",
+          "yahoo",
+          "icloud",
+          "proton",
+          "zoho",
+          "aol",
+          "fastmail",
+          "gmx",
+          "mailcom",
+          "mail_ru",
+          "yandex",
+          "rambler",
+          "qq",
+          "netease",
+          "sina",
+          "aliyun",
+          "naver",
+          "daum",
+          "web_de",
+          "tonline",
+          "seznam",
+          "wp_pl",
+          "o2_pl",
+          "interia",
+          "libero",
+          "virgilio",
+          "orange",
+          "laposte",
+          "free_fr",
+          "sfr"
+        ],
+        "type": "string",
+        "description": "* `gmail` - gmail\n* `outlook` - outlook\n* `yahoo` - yahoo\n* `icloud` - icloud\n* `proton` - proton\n* `zoho` - zoho\n* `aol` - aol\n* `fastmail` - fastmail\n* `gmx` - gmx\n* `mailcom` - mailcom\n* `mail_ru` - mail_ru\n* `yandex` - yandex\n* `rambler` - rambler\n* `qq` - qq\n* `netease` - netease\n* `sina` - sina\n* `aliyun` - aliyun\n* `naver` - naver\n* `daum` - daum\n* `web_de` - web_de\n* `tonline` - tonline\n* `seznam` - seznam\n* `wp_pl` - wp_pl\n* `o2_pl` - o2_pl\n* `interia` - interia\n* `libero` - libero\n* `virgilio` - virgilio\n* `orange` - orange\n* `laposte` - laposte\n* `free_fr` - free_fr\n* `sfr` - sfr"
+      },
       "cfg_accounts_oauth_connections_response_200_AutoRef": {
         "type": "array",
         "items": {

package/src/_api/generated/types.gen.ts

@@ -469,11 +469,11 @@ export type OAuthTokenResponse = {
     /**
      * True if a new user was created during this OAuth flow
      */
-    is_new_user: boolean;
+    is_new_user?: boolean;
     /**
      * True if a new OAuth connection was created
      */
-    is_new_connection: boolean;
+    is_new_connection?: boolean;
     /**
      * True if user should be prompted to enable 2FA
      */
@@ -530,6 +530,10 @@ export type OtpRequestResponse = {
      * Success message
      */
     message: string;
+    /**
+     * Webmail deep-link for the recipient's provider, or null if the domain is unknown.
+     */
+    webmail?: WebmailLink | null;
 };
 
 /**
@@ -792,6 +796,131 @@ export type VerifyResponse = {
     warning?: string;
 };
 
+/**
+ * Deep-link that opens the user's webmail on a search for our login email.
+ *
+ * Present only when the recipient's email domain maps to a known webmail
+ * provider (Gmail, Outlook, Mail.ru, Yandex, iCloud, …). For unknown/corporate
+ * domains this whole object is null and the frontend shows no button.
+ */
+export type WebmailLink = {
+    /**
+     * Provider slug (e.g. 'gmail', 'outlook', 'mail_ru'). Also selects the brand icon on the frontend.
+     *
+     * * `gmail` - gmail
+     * * `outlook` - outlook
+     * * `yahoo` - yahoo
+     * * `icloud` - icloud
+     * * `proton` - proton
+     * * `zoho` - zoho
+     * * `aol` - aol
+     * * `fastmail` - fastmail
+     * * `gmx` - gmx
+     * * `mailcom` - mailcom
+     * * `mail_ru` - mail_ru
+     * * `yandex` - yandex
+     * * `rambler` - rambler
+     * * `qq` - qq
+     * * `netease` - netease
+     * * `sina` - sina
+     * * `aliyun` - aliyun
+     * * `naver` - naver
+     * * `daum` - daum
+     * * `web_de` - web_de
+     * * `tonline` - tonline
+     * * `seznam` - seznam
+     * * `wp_pl` - wp_pl
+     * * `o2_pl` - o2_pl
+     * * `interia` - interia
+     * * `libero` - libero
+     * * `virgilio` - virgilio
+     * * `orange` - orange
+     * * `laposte` - laposte
+     * * `free_fr` - free_fr
+     * * `sfr` - sfr
+     */
+    provider: WebmailLinkProviderEnum;
+    /**
+     * Human-facing provider name, e.g. 'Gmail'.
+     */
+    provider_name: string;
+    /**
+     * Absolute URL to open in a new tab (a sender-filtered search, or the inbox as fallback).
+     */
+    url: string;
+    /**
+     * True if the URL opens a search filtered to our sender; False if it only opens the inbox.
+     */
+    is_search: boolean;
+};
+
+/**
+ * * `gmail` - gmail
+ * * `outlook` - outlook
+ * * `yahoo` - yahoo
+ * * `icloud` - icloud
+ * * `proton` - proton
+ * * `zoho` - zoho
+ * * `aol` - aol
+ * * `fastmail` - fastmail
+ * * `gmx` - gmx
+ * * `mailcom` - mailcom
+ * * `mail_ru` - mail_ru
+ * * `yandex` - yandex
+ * * `rambler` - rambler
+ * * `qq` - qq
+ * * `netease` - netease
+ * * `sina` - sina
+ * * `aliyun` - aliyun
+ * * `naver` - naver
+ * * `daum` - daum
+ * * `web_de` - web_de
+ * * `tonline` - tonline
+ * * `seznam` - seznam
+ * * `wp_pl` - wp_pl
+ * * `o2_pl` - o2_pl
+ * * `interia` - interia
+ * * `libero` - libero
+ * * `virgilio` - virgilio
+ * * `orange` - orange
+ * * `laposte` - laposte
+ * * `free_fr` - free_fr
+ * * `sfr` - sfr
+ */
+export enum WebmailLinkProviderEnum {
+    GMAIL = 'gmail',
+    OUTLOOK = 'outlook',
+    YAHOO = 'yahoo',
+    ICLOUD = 'icloud',
+    PROTON = 'proton',
+    ZOHO = 'zoho',
+    AOL = 'aol',
+    FASTMAIL = 'fastmail',
+    GMX = 'gmx',
+    MAILCOM = 'mailcom',
+    MAIL_RU = 'mail_ru',
+    YANDEX = 'yandex',
+    RAMBLER = 'rambler',
+    QQ = 'qq',
+    NETEASE = 'netease',
+    SINA = 'sina',
+    ALIYUN = 'aliyun',
+    NAVER = 'naver',
+    DAUM = 'daum',
+    WEB_DE = 'web_de',
+    TONLINE = 'tonline',
+    SEZNAM = 'seznam',
+    WP_PL = 'wp_pl',
+    O2_PL = 'o2_pl',
+    INTERIA = 'interia',
+    LIBERO = 'libero',
+    VIRGILIO = 'virgilio',
+    ORANGE = 'orange',
+    LAPOSTE = 'laposte',
+    FREE_FR = 'free_fr',
+    SFR = 'sfr'
+}
+
 export type CfgAccountsOauthConnectionsResponse200AutoRef = Array<OAuthConnection>;
 
 export type CfgAccountsOauthDisconnectResponse200AutoRef = {

package/src/auth/__tests__/jwt.test.ts

@@ -0,0 +1,119 @@
+/**
+ * JWT expiry-helper tests (auth/utils/jwt.ts).
+ *
+ * These functions decide whether the client should trust a persisted token or
+ * treat the session as dead. They must FAIL CLOSED: anything undecodable counts
+ * as expired, so garbage in localStorage sends the user to the login form
+ * rather than looping on 401s. (This is the automated version of the user's
+ * manual "clear localStorage and the form appeared".)
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { getTokenExpiry, isTokenExpired, isTokenExpiringSoon } from '../utils/jwt';
+
+const NOW = 1_800_000_000_000; // fixed "now" in ms (injected, not Date.now())
+
+/** Base64url without padding — mirrors real JWT segment encoding. */
+function b64url(obj: unknown): string {
+  const json = JSON.stringify(obj);
+  const b64 = Buffer.from(json, 'utf8').toString('base64');
+  return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/** Build a syntactically valid 3-segment JWT with the given payload. */
+function jwt(payload: Record<string, unknown>): string {
+  const header = b64url({ alg: 'HS256', typ: 'JWT' });
+  const body = b64url(payload);
+  return `${header}.${body}.signature`;
+}
+
+/** exp claim is in SECONDS in a real JWT. */
+const expSeconds = (ms: number) => Math.floor(ms / 1000);
+
+describe('getTokenExpiry', () => {
+  it('extracts exp (converted to ms) from a well-formed token', () => {
+    const token = jwt({ exp: expSeconds(NOW) });
+    expect(getTokenExpiry(token)).toBe(expSeconds(NOW) * 1000);
+  });
+
+  it('returns null for null / undefined / empty', () => {
+    expect(getTokenExpiry(null)).toBeNull();
+    expect(getTokenExpiry(undefined)).toBeNull();
+    expect(getTokenExpiry('')).toBeNull();
+  });
+
+  it('returns null for a non-JWT string (wrong segment count)', () => {
+    expect(getTokenExpiry('not-a-jwt')).toBeNull();
+    expect(getTokenExpiry('only.two')).toBeNull();
+    expect(getTokenExpiry('a.b.c.d')).toBeNull();
+  });
+
+  it('returns null when the payload is not valid base64/JSON', () => {
+    expect(getTokenExpiry('aaa.!!!!.bbb')).toBeNull();
+  });
+
+  it('returns null when exp is missing or non-numeric', () => {
+    expect(getTokenExpiry(jwt({ sub: 'user' }))).toBeNull();
+    expect(getTokenExpiry(jwt({ exp: 'soon' }))).toBeNull();
+    expect(getTokenExpiry(jwt({ exp: null }))).toBeNull();
+  });
+
+  it('handles a non-object payload (e.g. a JSON number) as no-exp', () => {
+    const header = b64url({ alg: 'HS256' });
+    const body = b64url(42 as unknown as Record<string, unknown>);
+    expect(getTokenExpiry(`${header}.${body}.sig`)).toBeNull();
+  });
+});
+
+describe('isTokenExpired (fail-closed)', () => {
+  it('false for a token that expires in the future', () => {
+    const token = jwt({ exp: expSeconds(NOW + 60_000) });
+    expect(isTokenExpired(token, 0, NOW)).toBe(false);
+  });
+
+  it('true for a token already past exp', () => {
+    const token = jwt({ exp: expSeconds(NOW - 1) });
+    expect(isTokenExpired(token, 0, NOW)).toBe(true);
+  });
+
+  it('true exactly at exp (boundary is inclusive → expired)', () => {
+    const token = jwt({ exp: expSeconds(NOW) });
+    expect(isTokenExpired(token, 0, NOW)).toBe(true);
+  });
+
+  it('skew treats a soon-to-expire token as already expired', () => {
+    const token = jwt({ exp: expSeconds(NOW + 30_000) }); // expires in 30s
+    expect(isTokenExpired(token, 60_000, NOW)).toBe(true); // 60s skew
+    expect(isTokenExpired(token, 10_000, NOW)).toBe(false); // 10s skew
+  });
+
+  it('true (fail-closed) for null / garbage / no-exp tokens', () => {
+    expect(isTokenExpired(null, 0, NOW)).toBe(true);
+    expect(isTokenExpired(undefined, 0, NOW)).toBe(true);
+    expect(isTokenExpired('garbage', 0, NOW)).toBe(true);
+    expect(isTokenExpired(jwt({ sub: 'x' }), 0, NOW)).toBe(true);
+  });
+});
+
+describe('isTokenExpiringSoon', () => {
+  it('true when expiry is within the threshold', () => {
+    const token = jwt({ exp: expSeconds(NOW + 5 * 60_000) }); // 5 min
+    expect(isTokenExpiringSoon(token, 10 * 60_000, NOW)).toBe(true);
+  });
+
+  it('false when expiry is beyond the threshold', () => {
+    const token = jwt({ exp: expSeconds(NOW + 20 * 60_000) }); // 20 min
+    expect(isTokenExpiringSoon(token, 10 * 60_000, NOW)).toBe(false);
+  });
+
+  it('false (not "soon") for undecodable tokens — the expired path owns those', () => {
+    expect(isTokenExpiringSoon(null, 10 * 60_000, NOW)).toBe(false);
+    expect(isTokenExpiringSoon('garbage', 10 * 60_000, NOW)).toBe(false);
+  });
+
+  it('true for an already-expired but decodable token', () => {
+    const token = jwt({ exp: expSeconds(NOW - 1000) });
+    expect(isTokenExpiringSoon(token, 10 * 60_000, NOW)).toBe(true);
+  });
+});