@iqauth/sdk 2.0.2 → 2.0.4

package/dist/server/handlers.d.ts

@@ -63,14 +63,33 @@ interface IQAuthHelperConfig {
     logoutPath?: string;
     /** Optional fetch implementation override. */
     fetchImpl?: typeof fetch;
+    /**
+     * Policy for clearing the access + refresh cookies when `/refresh` fails.
+     *
+     * - `"terminal-only"` (default, recommended): only clear cookies when the
+     *   issuer indicates the session is unrecoverable
+     *   (`TOKEN_REVOKED`, `SESSION_REVOKED`, `INVALID_GRANT`,
+     *   `USER_DEACTIVATED`, or HTTP 410 Gone). Transient failures
+     *   (`TOKEN_INVALID` from a rotated-out token, `TOKEN_EXPIRED`, network
+     *   errors, 5xx) leave cookies intact so the next legitimate request can
+     *   either succeed against a still-valid access cookie or be redirected
+     *   cleanly to sign-in by the middleware. Fixes the multi-tab /
+     *   proactive-refresh race that previously silently signed users out.
+     * - `"always"`: pre-2.0.3 behavior — wipe both cookies on any non-2xx.
+     *   Use only if you have an external reason to depend on the old semantics.
+     * - `"never"`: leave cookies untouched on every failure path. Suitable for
+     *   apps that manage cookie lifecycle entirely outside the SDK helpers.
+     */
+    clearCookiesOnRefreshFailure?: "terminal-only" | "always" | "never";
 }
-interface ResolvedConfig extends Required<Omit<IQAuthHelperConfig, "secretKey" | "cookieDomain" | "issuer" | "fetchImpl">> {
+interface ResolvedConfig extends Required<Omit<IQAuthHelperConfig, "secretKey" | "cookieDomain" | "issuer" | "fetchImpl" | "clearCookiesOnRefreshFailure">> {
     secretKey?: string;
     cookieDomain?: string;
     issuer: string;
     fetchImpl: typeof fetch;
     appId: string;
     tenantId: string;
+    clearCookiesOnRefreshFailure: "terminal-only" | "always" | "never";
 }
 /**
  * Serialize a cookie directive to a Set-Cookie header value. Adapters that
@@ -84,7 +103,15 @@ declare function handleCallback(config: IQAuthHelperConfig, input: {
     codeVerifier?: string;
     redirectUri?: string;
 }): Promise<HandlerResponse>;
-/** POST /api/iqauth/refresh — rotate refresh + access cookies. */
+/** POST /api/iqauth/refresh — rotate refresh + access cookies.
+ *
+ * Cookie-clearing policy is governed by `config.clearCookiesOnRefreshFailure`
+ * (default `"terminal-only"`). Prior to 2.0.3 this helper wiped both cookies
+ * on any non-2xx, which converted survivable refresh-token races (multi-tab,
+ * proactive-refresh timer, React StrictMode double-mount) into silent forced
+ * sign-outs. The default behavior now preserves cookies on transient failures
+ * and only clears them when the issuer signals the session is truly dead.
+ */
 declare function handleRefresh(config: IQAuthHelperConfig, input: {
     refreshToken?: string;
 }): Promise<HandlerResponse>;

package/dist/server/handlers.js

@@ -57,6 +57,22 @@ function parsePublishableKey(raw) {
 }
 
 // src/server/handlers.ts
+var TERMINAL_REFRESH_ERROR_CODES = /* @__PURE__ */ new Set([
+  "TOKEN_REVOKED",
+  "SESSION_REVOKED",
+  "INVALID_GRANT",
+  "invalid_grant",
+  "USER_DEACTIVATED",
+  "USER_DISABLED",
+  "TENANT_SUSPENDED"
+]);
+function shouldClearCookiesOnFailure(policy, status, errorCode) {
+  if (policy === "always") return true;
+  if (policy === "never") return false;
+  if (status === 410) return true;
+  if (errorCode && TERMINAL_REFRESH_ERROR_CODES.has(errorCode)) return true;
+  return false;
+}
 var ACCESS_TOKEN_TTL_SECONDS = 60 * 15;
 var REFRESH_TOKEN_TTL_SECONDS = 60 * 60 * 24 * 30;
 function resolve(config) {
@@ -84,7 +100,8 @@ function resolve(config) {
       throw new Error("global fetch is unavailable; pass fetchImpl");
     })),
     appId: parsed.appId,
-    tenantId: parsed.tenantId
+    tenantId: parsed.tenantId,
+    clearCookiesOnRefreshFailure: config.clearCookiesOnRefreshFailure ?? "terminal-only"
   };
 }
 function makeCookie(cfg, name, value, maxAge, httpOnly = true) {
@@ -180,7 +197,7 @@ async function handleRefresh(config, input) {
     return {
       status: 401,
       body: { success: false, error: { code: "TOKEN_INVALID", message: "Missing refresh token" } },
-      cookies: clearCookies(cfg)
+      cookies: cfg.clearCookiesOnRefreshFailure === "always" ? clearCookies(cfg) : []
     };
   }
   const res = await cfg.fetchImpl(`${cfg.issuer}${cfg.refreshPath}`, {
@@ -190,16 +207,23 @@ async function handleRefresh(config, input) {
   });
   const json = await res.json().catch(() => ({}));
   if (!res.ok || !json.success || !json.data?.accessToken) {
+    const status = res.status || 401;
+    const errorCode = json.error?.code || "TOKEN_INVALID";
+    const shouldClear = shouldClearCookiesOnFailure(
+      cfg.clearCookiesOnRefreshFailure,
+      status,
+      errorCode
+    );
     return {
-      status: res.status || 401,
+      status,
       body: {
         success: false,
         error: {
-          code: json.error?.code || "TOKEN_INVALID",
+          code: errorCode,
           message: json.error?.message || "Refresh failed"
         }
       },
-      cookies: clearCookies(cfg)
+      cookies: shouldClear ? clearCookies(cfg) : []
     };
   }
   const cookies = [

package/dist/server/handlers.mjs

@@ -3,7 +3,7 @@ import {
   handleRefresh,
   handleSignout,
   serializeCookie
-} from "../chunk-5HF3OBNO.mjs";
+} from "../chunk-JQRTY5MY.mjs";
 import "../chunk-5WFR6Y33.mjs";
 import "../chunk-Y6FXYEAI.mjs";
 export {

package/dist/server.js

@@ -1988,6 +1988,22 @@ function iqAuthMiddleware(clientOrOptions, options = {}) {
 }
 
 // src/server/handlers.ts
+var TERMINAL_REFRESH_ERROR_CODES = /* @__PURE__ */ new Set([
+  "TOKEN_REVOKED",
+  "SESSION_REVOKED",
+  "INVALID_GRANT",
+  "invalid_grant",
+  "USER_DEACTIVATED",
+  "USER_DISABLED",
+  "TENANT_SUSPENDED"
+]);
+function shouldClearCookiesOnFailure(policy, status, errorCode) {
+  if (policy === "always") return true;
+  if (policy === "never") return false;
+  if (status === 410) return true;
+  if (errorCode && TERMINAL_REFRESH_ERROR_CODES.has(errorCode)) return true;
+  return false;
+}
 var ACCESS_TOKEN_TTL_SECONDS = 60 * 15;
 var REFRESH_TOKEN_TTL_SECONDS = 60 * 60 * 24 * 30;
 function resolve(config) {
@@ -2015,7 +2031,8 @@ function resolve(config) {
       throw new Error("global fetch is unavailable; pass fetchImpl");
     })),
     appId: parsed.appId,
-    tenantId: parsed.tenantId
+    tenantId: parsed.tenantId,
+    clearCookiesOnRefreshFailure: config.clearCookiesOnRefreshFailure ?? "terminal-only"
   };
 }
 function makeCookie(cfg, name, value, maxAge, httpOnly = true) {
@@ -2111,7 +2128,7 @@ async function handleRefresh(config, input) {
     return {
       status: 401,
       body: { success: false, error: { code: "TOKEN_INVALID", message: "Missing refresh token" } },
-      cookies: clearCookies(cfg)
+      cookies: cfg.clearCookiesOnRefreshFailure === "always" ? clearCookies(cfg) : []
     };
   }
   const res = await cfg.fetchImpl(`${cfg.issuer}${cfg.refreshPath}`, {
@@ -2121,16 +2138,23 @@ async function handleRefresh(config, input) {
   });
   const json = await res.json().catch(() => ({}));
   if (!res.ok || !json.success || !json.data?.accessToken) {
+    const status = res.status || 401;
+    const errorCode = json.error?.code || "TOKEN_INVALID";
+    const shouldClear = shouldClearCookiesOnFailure(
+      cfg.clearCookiesOnRefreshFailure,
+      status,
+      errorCode
+    );
     return {
-      status: res.status || 401,
+      status,
       body: {
         success: false,
         error: {
-          code: json.error?.code || "TOKEN_INVALID",
+          code: errorCode,
           message: json.error?.message || "Refresh failed"
         }
       },
-      cookies: clearCookies(cfg)
+      cookies: shouldClear ? clearCookies(cfg) : []
     };
   }
   const cookies = [

package/dist/server.mjs

@@ -8,7 +8,7 @@ import {
   handleRefresh,
   handleSignout,
   serializeCookie
-} from "./chunk-5HF3OBNO.mjs";
+} from "./chunk-JQRTY5MY.mjs";
 import "./chunk-5WFR6Y33.mjs";
 import {
   IQAuthClient

package/dist/{signIn-C8f6qVjD.d.mts → signIn-CEMdUAwd.d.mts}

@@ -80,6 +80,27 @@ interface SessionManagerOptions {
      * refresh to finish before falling back to its own. Defaults to 4000.
      */
     crossTabLockTimeoutMs?: number;
+    /**
+     * "Server-managed" session mode for apps where the backend (via the
+     * `@iqauth/sdk/{express,fastify,hono,next}` adapters) owns the HttpOnly
+     * `iqauth_at` + `iqauth_rt` cookies and is the sole authority on token
+     * rotation. When `true`:
+     *
+     *   - `bootstrap()` learns session state with a single `GET userinfoPath`
+     *     call (no token rotation, no race surface), instead of POSTing to
+     *     `/refresh` with an empty body.
+     *   - `scheduleProactiveRefresh()` is suppressed — the server middleware
+     *     refreshes on real navigation, which is single-flight per request.
+     *   - `tokenStore` defaults to a no-op store so JS never tries to read the
+     *     (HttpOnly, invisible) refresh cookie.
+     *
+     * This is the recommended mode for any app with its own backend, especially
+     * confidential-client OIDC flows. It eliminates the multi-tab refresh-token
+     * rotation race that previously caused silent sign-outs.
+     *
+     * Defaults to `false` to preserve pre-2.0.3 behavior.
+     */
+    serverManagedSession?: boolean;
 }
 declare class SessionManager {
     private snapshot;
@@ -96,6 +117,7 @@ declare class SessionManager {
     private readonly proactiveRefresh;
     private readonly tokenStore;
     private readonly crossTabLockTimeoutMs;
+    private readonly serverManagedSession;
     private proactiveTimer;
     private bootstrapped;
     /** Pending refresh awaited by other tabs after a `refresh:claim` from us. */

package/dist/{signIn-Cy2lbEXb.d.ts → signIn-VRNzlNyG.d.ts}

@@ -80,6 +80,27 @@ interface SessionManagerOptions {
      * refresh to finish before falling back to its own. Defaults to 4000.
      */
     crossTabLockTimeoutMs?: number;
+    /**
+     * "Server-managed" session mode for apps where the backend (via the
+     * `@iqauth/sdk/{express,fastify,hono,next}` adapters) owns the HttpOnly
+     * `iqauth_at` + `iqauth_rt` cookies and is the sole authority on token
+     * rotation. When `true`:
+     *
+     *   - `bootstrap()` learns session state with a single `GET userinfoPath`
+     *     call (no token rotation, no race surface), instead of POSTing to
+     *     `/refresh` with an empty body.
+     *   - `scheduleProactiveRefresh()` is suppressed — the server middleware
+     *     refreshes on real navigation, which is single-flight per request.
+     *   - `tokenStore` defaults to a no-op store so JS never tries to read the
+     *     (HttpOnly, invisible) refresh cookie.
+     *
+     * This is the recommended mode for any app with its own backend, especially
+     * confidential-client OIDC flows. It eliminates the multi-tab refresh-token
+     * rotation race that previously caused silent sign-outs.
+     *
+     * Defaults to `false` to preserve pre-2.0.3 behavior.
+     */
+    serverManagedSession?: boolean;
 }
 declare class SessionManager {
     private snapshot;
@@ -96,6 +117,7 @@ declare class SessionManager {
     private readonly proactiveRefresh;
     private readonly tokenStore;
     private readonly crossTabLockTimeoutMs;
+    private readonly serverManagedSession;
     private proactiveTimer;
     private bootstrapped;
     /** Pending refresh awaited by other tabs after a `refresh:claim` from us. */

package/docs/BROWSER_SESSION_MIGRATION.md

@@ -2,6 +2,40 @@
 
 Use this guide when a first-party web app currently owns IQAuth tokens in browser code and needs to move to the supported session model.
 
+## Cookie-managed / confidential-client (recommended for any app with a backend)
+
+If your app uses one of the framework adapters (`@iqauth/sdk/{express,fastify,hono,next}`) the backend owns the HttpOnly `iqauth_at` + `iqauth_rt` cookies and should be the **sole** authority on token rotation. In that setup the browser `SessionManager` must NOT also try to rotate refresh tokens — otherwise the proactive-refresh timer + multi-tab BroadcastChannel + React StrictMode double-mount can race against the backend's own refreshes, and one lost race used to wipe the cookies.
+
+As of `@iqauth/sdk@2.0.3`, opt into "server-managed" mode with a single flag:
+
+```ts
+import { SessionManager } from "@iqauth/sdk/browser";
+
+const manager = new SessionManager({
+  publishableKey: process.env.NEXT_PUBLIC_IQAUTH_PUBLISHABLE_KEY!,
+  issuer: window.location.origin,
+  refreshPath: "/api/iqauth/refresh", // mounted by the framework adapter
+  serverManagedSession: true,         // ← do this
+});
+```
+
+What `serverManagedSession: true` does:
+
+- `bootstrap()` learns session state with a single read-only `GET /api/v1/auth/me` (override with `userinfoPath`) instead of POSTing to `/refresh`. No rotation, no race surface.
+- `scheduleProactiveRefresh()` is suppressed. The server middleware refreshes on real navigation, which is single-flight per request and can't race itself.
+- `tokenStore` defaults to a no-op store, so JS never tries to read the (HttpOnly, invisible) refresh cookie.
+
+`<SignedIn>` / `<SignedOut>` / `useUser()` continue to work — they read from the userinfo bootstrap.
+
+### Cookie-clearing policy on `/refresh` failures
+
+`@iqauth/sdk/server::handleRefresh` now defaults to `clearCookiesOnRefreshFailure: "terminal-only"`. Cookies are only wiped when the issuer signals the session is unrecoverable (`TOKEN_REVOKED`, `SESSION_REVOKED`, `INVALID_GRANT`, `USER_DEACTIVATED`, `TENANT_SUSPENDED`, or HTTP 410 Gone). Transient failures — `TOKEN_INVALID` from a rotated-out token, `TOKEN_EXPIRED`, network blips, 5xx — return 401 without touching cookies, so the next legitimate request can either succeed against a still-valid access cookie or get redirected to sign-in cleanly by the middleware.
+
+Pre-2.0.3 behavior is available with `clearCookiesOnRefreshFailure: "always"`.
+
+---
+
+
 ## Target Model
 
 - browser talks to app backend

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iqauth/sdk",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "TypeScript SDK for IQAuth — the canonical way for all IQ projects to integrate with IQAuthService",
   "main": "dist/index.js",
   "module": "dist/index.mjs",