@iqauth/sdk 2.0.1 → 2.0.3

package/dist/browser.d.mts

@@ -1,4 +1,4 @@
-export { C as CallbackResult, S as SessionManager, d as SessionManagerOptions, a as SessionSnapshot, e as SessionStatus, b as SignInOptions, c as SignOutOptions, f as buildSignInUrl, h as handleAuthCallback, r as redirectToSignIn, s as signIn, g as signOut } from './signIn-C8f6qVjD.mjs';
+export { C as CallbackResult, S as SessionManager, d as SessionManagerOptions, a as SessionSnapshot, e as SessionStatus, b as SignInOptions, c as SignOutOptions, f as buildSignInUrl, h as handleAuthCallback, r as redirectToSignIn, s as signIn, g as signOut } from './signIn-CEMdUAwd.mjs';
 export { K as KeyMode, b as ParsedPublishableKey, P as PublishableKeyPayload, e as encodePublishableKey, i as isPublishableKey, a as isSecretKey, p as parsePublishableKey } from './publishableKey-B5DIK81A.mjs';
 export { a as ErrorCode, E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.mjs';
 import './types-Cxl3bQHt.mjs';

package/dist/browser.d.ts

@@ -1,4 +1,4 @@
-export { C as CallbackResult, S as SessionManager, d as SessionManagerOptions, a as SessionSnapshot, e as SessionStatus, b as SignInOptions, c as SignOutOptions, f as buildSignInUrl, h as handleAuthCallback, r as redirectToSignIn, s as signIn, g as signOut } from './signIn-Cy2lbEXb.js';
+export { C as CallbackResult, S as SessionManager, d as SessionManagerOptions, a as SessionSnapshot, e as SessionStatus, b as SignInOptions, c as SignOutOptions, f as buildSignInUrl, h as handleAuthCallback, r as redirectToSignIn, s as signIn, g as signOut } from './signIn-VRNzlNyG.js';
 export { K as KeyMode, b as ParsedPublishableKey, P as PublishableKeyPayload, e as encodePublishableKey, i as isPublishableKey, a as isSecretKey, p as parsePublishableKey } from './publishableKey-B5DIK81A.js';
 export { a as ErrorCode, E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.js';
 import './types-Cxl3bQHt.js';

package/dist/browser.js

@@ -270,8 +270,9 @@ var SessionManager = class {
     this.refreshPath = options.refreshPath ?? DEFAULT_REFRESH_PATH;
     this.userinfoPath = options.userinfoPath ?? DEFAULT_USERINFO_PATH;
     this.useCookies = options.useCookies ?? true;
-    this.proactiveRefresh = options.proactiveRefresh ?? true;
-    this.tokenStore = options.tokenStore ?? (this.useCookies ? defaultCookieStore() : NO_OP_STORE);
+    this.serverManagedSession = options.serverManagedSession ?? false;
+    this.proactiveRefresh = this.serverManagedSession ? false : options.proactiveRefresh ?? true;
+    this.tokenStore = options.tokenStore ?? (this.serverManagedSession ? NO_OP_STORE : this.useCookies ? defaultCookieStore() : NO_OP_STORE);
     this.crossTabLockTimeoutMs = options.crossTabLockTimeoutMs ?? 4e3;
     this.fetchImpl = options.fetchImpl ?? (typeof fetch !== "undefined" ? fetch.bind(globalThis) : (() => {
       throw new Error("global fetch is not available; pass fetchImpl");
@@ -315,6 +316,40 @@ var SessionManager = class {
   async bootstrap() {
     if (this.bootstrapped) return;
     this.bootstrapped = true;
+    if (this.serverManagedSession) {
+      try {
+        const res = await this.fetchImpl(`${this.issuer}${this.userinfoPath}`, {
+          method: "GET",
+          credentials: "include",
+          headers: { Accept: "application/json" }
+        });
+        if (!res.ok) {
+          this.setStatus("unauthenticated");
+          return;
+        }
+        const body = await res.json().catch(() => ({}));
+        const data = body?.data;
+        const user = data?.user ?? claimsToSessionUser(data?.claims ?? null);
+        if (!user) {
+          this.setStatus("unauthenticated");
+          return;
+        }
+        this.update({
+          status: "authenticated",
+          accessToken: null,
+          user,
+          claims: data?.claims ?? null,
+          tenantId: data?.tenantId ?? user.tenantId ?? this.key.tenantId,
+          error: null,
+          version: this.snapshot.version + 1
+        });
+        this.broadcast("session:update");
+        return;
+      } catch {
+        this.setStatus("unauthenticated");
+        return;
+      }
+    }
     const stored = await Promise.resolve(this.tokenStore.read());
     if (!stored) {
       this.setStatus("unauthenticated");

package/dist/browser.mjs

@@ -12,7 +12,7 @@ import {
   setCookie,
   signIn,
   signOut
-} from "./chunk-YDO2RDWQ.mjs";
+} from "./chunk-S3M2IXCE.mjs";
 import {
   encodePublishableKey,
   isPublishableKey,

package/dist/{chunk-5HF3OBNO.mjs → chunk-JQRTY5MY.mjs}

@@ -3,6 +3,22 @@ import {
 } from "./chunk-5WFR6Y33.mjs";
 
 // 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) {
@@ -30,7 +46,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) {
@@ -126,7 +143,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}`, {
@@ -136,16 +153,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/{chunk-YDO2RDWQ.mjs → chunk-S3M2IXCE.mjs}

@@ -137,8 +137,9 @@ var SessionManager = class {
     this.refreshPath = options.refreshPath ?? DEFAULT_REFRESH_PATH;
     this.userinfoPath = options.userinfoPath ?? DEFAULT_USERINFO_PATH;
     this.useCookies = options.useCookies ?? true;
-    this.proactiveRefresh = options.proactiveRefresh ?? true;
-    this.tokenStore = options.tokenStore ?? (this.useCookies ? defaultCookieStore() : NO_OP_STORE);
+    this.serverManagedSession = options.serverManagedSession ?? false;
+    this.proactiveRefresh = this.serverManagedSession ? false : options.proactiveRefresh ?? true;
+    this.tokenStore = options.tokenStore ?? (this.serverManagedSession ? NO_OP_STORE : this.useCookies ? defaultCookieStore() : NO_OP_STORE);
     this.crossTabLockTimeoutMs = options.crossTabLockTimeoutMs ?? 4e3;
     this.fetchImpl = options.fetchImpl ?? (typeof fetch !== "undefined" ? fetch.bind(globalThis) : (() => {
       throw new Error("global fetch is not available; pass fetchImpl");
@@ -182,6 +183,40 @@ var SessionManager = class {
   async bootstrap() {
     if (this.bootstrapped) return;
     this.bootstrapped = true;
+    if (this.serverManagedSession) {
+      try {
+        const res = await this.fetchImpl(`${this.issuer}${this.userinfoPath}`, {
+          method: "GET",
+          credentials: "include",
+          headers: { Accept: "application/json" }
+        });
+        if (!res.ok) {
+          this.setStatus("unauthenticated");
+          return;
+        }
+        const body = await res.json().catch(() => ({}));
+        const data = body?.data;
+        const user = data?.user ?? claimsToSessionUser(data?.claims ?? null);
+        if (!user) {
+          this.setStatus("unauthenticated");
+          return;
+        }
+        this.update({
+          status: "authenticated",
+          accessToken: null,
+          user,
+          claims: data?.claims ?? null,
+          tenantId: data?.tenantId ?? user.tenantId ?? this.key.tenantId,
+          error: null,
+          version: this.snapshot.version + 1
+        });
+        this.broadcast("session:update");
+        return;
+      } catch {
+        this.setStatus("unauthenticated");
+        return;
+      }
+    }
     const stored = await Promise.resolve(this.tokenStore.read());
     if (!stored) {
       this.setStatus("unauthenticated");

package/dist/express.js

@@ -1980,6 +1980,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) {
@@ -2007,7 +2023,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) {
@@ -2093,7 +2110,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}`, {
@@ -2103,16 +2120,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/express.mjs

@@ -6,7 +6,7 @@ import {
   handleCallback,
   handleRefresh,
   handleSignout
-} from "./chunk-5HF3OBNO.mjs";
+} from "./chunk-JQRTY5MY.mjs";
 import {
   parsePublishableKey
 } from "./chunk-5WFR6Y33.mjs";

package/dist/fastify.js

@@ -1781,6 +1781,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) {
@@ -1808,7 +1824,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) {
@@ -1904,7 +1921,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}`, {
@@ -1914,16 +1931,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/fastify.mjs

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

package/dist/hono.js

@@ -1780,6 +1780,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) {
@@ -1807,7 +1823,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) {
@@ -1903,7 +1920,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}`, {
@@ -1913,16 +1930,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/hono.mjs

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

package/dist/next.js

@@ -66,6 +66,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) {
@@ -93,7 +109,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) {
@@ -189,7 +206,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}`, {
@@ -199,16 +216,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 = [
@@ -2057,7 +2081,7 @@ async function getAuth(options) {
       /* webpackIgnore: true */
       specifier
     );
-    cookieJar = mod.cookies ? mod.cookies() : null;
+    cookieJar = mod.cookies ? await mod.cookies() : null;
   } catch {
     cookieJar = null;
   }

package/dist/next.mjs

@@ -3,7 +3,7 @@ import {
   handleRefresh,
   handleSignout,
   serializeCookie
-} from "./chunk-5HF3OBNO.mjs";
+} from "./chunk-JQRTY5MY.mjs";
 import {
   parsePublishableKey
 } from "./chunk-5WFR6Y33.mjs";
@@ -110,7 +110,7 @@ async function getAuth(options) {
       /* webpackIgnore: true */
       specifier
     );
-    cookieJar = mod.cookies ? mod.cookies() : null;
+    cookieJar = mod.cookies ? await mod.cookies() : null;
   } catch {
     cookieJar = null;
   }

package/dist/react.d.mts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
 import { ReactNode } from 'react';
-import { S as SessionManager, a as SessionSnapshot, b as SignInOptions, c as SignOutOptions, C as CallbackResult } from './signIn-C8f6qVjD.mjs';
+import { S as SessionManager, a as SessionSnapshot, b as SignInOptions, c as SignOutOptions, C as CallbackResult } from './signIn-CEMdUAwd.mjs';
 import { d as SessionUser, J as JwtClaims } from './types-Cxl3bQHt.mjs';
 import './publishableKey-B5DIK81A.mjs';
 

package/dist/react.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
 import { ReactNode } from 'react';
-import { S as SessionManager, a as SessionSnapshot, b as SignInOptions, c as SignOutOptions, C as CallbackResult } from './signIn-Cy2lbEXb.js';
+import { S as SessionManager, a as SessionSnapshot, b as SignInOptions, c as SignOutOptions, C as CallbackResult } from './signIn-VRNzlNyG.js';
 import { d as SessionUser, J as JwtClaims } from './types-Cxl3bQHt.js';
 import './publishableKey-B5DIK81A.js';
 

package/dist/react.js

@@ -215,8 +215,9 @@ var SessionManager = class {
     this.refreshPath = options.refreshPath ?? DEFAULT_REFRESH_PATH;
     this.userinfoPath = options.userinfoPath ?? DEFAULT_USERINFO_PATH;
     this.useCookies = options.useCookies ?? true;
-    this.proactiveRefresh = options.proactiveRefresh ?? true;
-    this.tokenStore = options.tokenStore ?? (this.useCookies ? defaultCookieStore() : NO_OP_STORE);
+    this.serverManagedSession = options.serverManagedSession ?? false;
+    this.proactiveRefresh = this.serverManagedSession ? false : options.proactiveRefresh ?? true;
+    this.tokenStore = options.tokenStore ?? (this.serverManagedSession ? NO_OP_STORE : this.useCookies ? defaultCookieStore() : NO_OP_STORE);
     this.crossTabLockTimeoutMs = options.crossTabLockTimeoutMs ?? 4e3;
     this.fetchImpl = options.fetchImpl ?? (typeof fetch !== "undefined" ? fetch.bind(globalThis) : (() => {
       throw new Error("global fetch is not available; pass fetchImpl");
@@ -260,6 +261,40 @@ var SessionManager = class {
   async bootstrap() {
     if (this.bootstrapped) return;
     this.bootstrapped = true;
+    if (this.serverManagedSession) {
+      try {
+        const res = await this.fetchImpl(`${this.issuer}${this.userinfoPath}`, {
+          method: "GET",
+          credentials: "include",
+          headers: { Accept: "application/json" }
+        });
+        if (!res.ok) {
+          this.setStatus("unauthenticated");
+          return;
+        }
+        const body = await res.json().catch(() => ({}));
+        const data = body?.data;
+        const user = data?.user ?? claimsToSessionUser(data?.claims ?? null);
+        if (!user) {
+          this.setStatus("unauthenticated");
+          return;
+        }
+        this.update({
+          status: "authenticated",
+          accessToken: null,
+          user,
+          claims: data?.claims ?? null,
+          tenantId: data?.tenantId ?? user.tenantId ?? this.key.tenantId,
+          error: null,
+          version: this.snapshot.version + 1
+        });
+        this.broadcast("session:update");
+        return;
+      } catch {
+        this.setStatus("unauthenticated");
+        return;
+      }
+    }
     const stored = await Promise.resolve(this.tokenStore.read());
     if (!stored) {
       this.setStatus("unauthenticated");

package/dist/react.mjs

@@ -4,7 +4,7 @@ import {
   redirectToSignIn,
   signIn,
   signOut
-} from "./chunk-YDO2RDWQ.mjs";
+} from "./chunk-S3M2IXCE.mjs";
 import "./chunk-5WFR6Y33.mjs";
 import "./chunk-6I6RM4MN.mjs";
 import "./chunk-Y6FXYEAI.mjs";

package/dist/server/handlers.d.mts

@@ -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.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.1",
+  "version": "2.0.3",
   "description": "TypeScript SDK for IQAuth — the canonical way for all IQ projects to integrate with IQAuthService",
   "main": "dist/index.js",
   "module": "dist/index.mjs",