@iqauth/sdk 2.7.0 → 2.8.1

package/dist/react.mjs

@@ -16,6 +16,7 @@ import {
   Protect,
   RedirectToSignIn,
   RedirectToSignedIn,
+  ScopeSwitcher,
   SignIn,
   SignUp,
   SignedIn,
@@ -25,12 +26,14 @@ import {
   Waitlist,
   __useIQAuthInternal,
   __version__,
-  isReturnToAllowed,
+  claimSatisfiesScope,
   isSilentSsoEligible,
+  performScopeSwitch,
+  performTenantSwitch,
   preflightReturnTo,
+  resolveAfterSignInDestination,
   revokeSession,
   sanitizeBrandCss,
-  sanitizeReturnTo,
   slugify,
   useAccountList,
   useAccountSwitcher,
@@ -41,6 +44,7 @@ import {
   useLinkedIdentities,
   useLocale,
   useMagicLink,
+  useMemberships,
   useOrganization,
   usePasskey,
   useResolvedSdkBranding,
@@ -50,12 +54,16 @@ import {
   useSessionList,
   useT,
   useUser
-} from "./chunk-RR2MGPTK.mjs";
-import "./chunk-RTJAIBXY.mjs";
+} from "./chunk-WHT6WKTY.mjs";
+import "./chunk-4V7FKOTG.mjs";
 import "./chunk-GN37E64I.mjs";
 import "./chunk-C2ZTBOAC.mjs";
+import {
+  isReturnToAllowed,
+  sanitizeReturnTo
+} from "./chunk-JRDVUWAL.mjs";
 import "./chunk-HVHNYPDC.mjs";
-import "./chunk-5T7GHBX6.mjs";
+import "./chunk-TLET552H.mjs";
 import "./chunk-6PJRLRB4.mjs";
 import "./chunk-Y6FXYEAI.mjs";
 export {
@@ -76,6 +84,7 @@ export {
   Protect,
   RedirectToSignIn,
   RedirectToSignedIn,
+  ScopeSwitcher,
   SignIn,
   SignUp,
   SignedIn,
@@ -85,9 +94,13 @@ export {
   Waitlist,
   __useIQAuthInternal,
   __version__,
+  claimSatisfiesScope,
   isReturnToAllowed,
   isSilentSsoEligible,
+  performScopeSwitch,
+  performTenantSwitch,
   preflightReturnTo,
+  resolveAfterSignInDestination,
   revokeSession,
   sanitizeBrandCss,
   sanitizeReturnTo,
@@ -101,6 +114,7 @@ export {
   useLinkedIdentities,
   useLocale,
   useMagicLink,
+  useMemberships,
   useOrganization,
   usePasskey,
   useResolvedSdkBranding,

package/dist/server/handlers.d.mts

@@ -1,5 +1,5 @@
-import { c as TokenVerifyOptions } from '../tokens-CITeoG6P.mjs';
-import { J as JwtClaims, S as SessionUser } from '../types-XOV9XPVi.mjs';
+import { c as TokenVerifyOptions } from '../tokens-B06VtvUi.mjs';
+import { J as JwtClaims, S as SessionUser } from '../types-Bn8O-OEd.mjs';
 
 /**
  * Framework-neutral helper handlers for the auto-mounted routes added by the
@@ -99,8 +99,21 @@ interface IQAuthHelperConfig {
     cookieDomain?: string;
     /** Cookie sameSite policy. Defaults to `lax`. */
     sameSite?: "lax" | "strict" | "none";
-    /** Cookie secure flag. Defaults to true (set false for local http dev). */
+    /**
+     * Cookie secure flag. Defaults to `true`. Setting it to `false` ships auth
+     * cookies over plaintext HTTP, exposing them to passive network attackers —
+     * so it is REFUSED by default (the helper throws `config_invalid`). To run a
+     * local HTTP dev box you must explicitly acknowledge the risk by ALSO setting
+     * {@link IQAuthHelperConfig.allowInsecureCookies} to `true`.
+     */
     secure?: boolean;
+    /**
+     * Explicit, opt-in acknowledgement that `secure: false` is intentional (local
+     * HTTP development only). Without this, `secure: false` throws so a misconfig
+     * can never silently downgrade production cookies to plaintext. Has no effect
+     * unless `secure` is `false`. Production MUST leave this unset / `false`.
+     */
+    allowInsecureCookies?: boolean;
     /** Cookie path. Defaults to `/`. */
     cookiePath?: string;
     /** Path of the OIDC token endpoint. */
@@ -183,6 +196,30 @@ interface IQAuthHelperConfig {
      * legitimate fresh sign-in.
      */
     signoutMarkerTtlMs?: number;
+    /**
+     * M-2 — Server-side OAuth `state` (CSRF) enforcement on the callback.
+     *
+     * When `true` (the DEFAULT), {@link handleCallback} requires BOTH the
+     * `state` returned by the OAuth redirect AND a previously-stored
+     * `expectedState` (read by the adapter from the {@link stateCookieName}
+     * cookie the SDK publishes before redirect), and fails closed with
+     * `STATE_MISMATCH` (no code exchange, no session cookie) when either is
+     * missing or they do not match. This defeats login-CSRF / session-fixation
+     * where an attacker injects their own authorization code.
+     *
+     * Set to `false` to restore the prior permissive behavior (state is only
+     * validated when an `expectedState` cookie happens to be present). This is
+     * an escape hatch for integrators whose initiation step does not publish a
+     * state cookie; it weakens CSRF protection and is not recommended.
+     */
+    requireOAuthState?: boolean;
+    /**
+     * Name of the first-party cookie the SDK publishes the OAuth `state` value
+     * into before redirecting to the issuer. The adapter reads it back on the
+     * callback as `expectedState`. Defaults to `iqauth_state` (matches the
+     * express inline-callback adapter and the React server-managed sign-in).
+     */
+    stateCookieName?: string;
 }
 interface IQAuthTimingEvent {
     phase: "callback" | "refresh" | "signout" | "bootstrap" | "signIn";
@@ -202,7 +239,7 @@ interface SignoutRegistry {
     mark(idempotencyToken: string, ttlMs: number): void | Promise<void>;
     has(idempotencyToken: string): boolean | Promise<boolean>;
 }
-interface ResolvedConfig extends Required<Omit<IQAuthHelperConfig, "secretKey" | "cookieDomain" | "issuer" | "fetchImpl" | "clearCookiesOnRefreshFailure" | "cookieNames" | "mountUserinfo" | "userinfoEnricher" | "verify" | "debug" | "onTimingEvent" | "signoutRegistry" | "signoutMarkerTtlMs">> {
+interface ResolvedConfig extends Required<Omit<IQAuthHelperConfig, "secretKey" | "cookieDomain" | "issuer" | "fetchImpl" | "clearCookiesOnRefreshFailure" | "cookieNames" | "mountUserinfo" | "userinfoEnricher" | "verify" | "debug" | "onTimingEvent" | "signoutRegistry" | "signoutMarkerTtlMs" | "allowInsecureCookies">> {
     cookieNames?: {
         access?: string;
         refresh?: string;
@@ -225,6 +262,12 @@ interface ResolvedConfig extends Required<Omit<IQAuthHelperConfig, "secretKey" |
  * public surface.
  */
 declare function __resetSignoutMarkersForTests(): void;
+/**
+ * Test-only hook to reset the one-time default-registry boot warning so each
+ * test can assert the warn-once behavior in isolation. Not part of the public
+ * surface.
+ */
+declare function __resetSignoutRegistryWarningForTests(): void;
 /**
  * Public factory for a fresh in-memory {@link SignoutRegistry}. Useful for
  * tests that want isolated state per case, and as a reference implementation
@@ -242,6 +285,14 @@ declare function handleCallback(config: IQAuthHelperConfig, input: {
     code?: string;
     codeVerifier?: string;
     redirectUri?: string;
+    /** The `state` value returned by the OAuth redirect (query or body). */
+    state?: string;
+    /**
+     * The `state` value the SDK stored before redirect, read by the adapter
+     * from the {@link IQAuthHelperConfig.stateCookieName} cookie. Compared
+     * against `state` to bind the callback to this browser (M-2 CSRF).
+     */
+    expectedState?: string;
 }): Promise<HandlerResponse>;
 /** POST /api/iqauth/refresh — rotate refresh + access cookies.
  *
@@ -276,4 +327,4 @@ declare function handleUserinfo(config: IQAuthHelperConfig, input: {
     req?: unknown;
 }): Promise<HandlerResponse>;
 
-export { type HandlerResponse, type IQAuthHelperConfig, type IQAuthTimingEvent, type ResolvedConfig as ResolvedIQAuthHelperConfig, type SetCookieDirective, type SignoutRegistry, type UserinfoResponse, __resetSignoutMarkersForTests, buildUserinfoResponse, createInMemorySignoutRegistry, handleCallback, handleRefresh, handleSignout, handleUserinfo, serializeCookie };
+export { type HandlerResponse, type IQAuthHelperConfig, type IQAuthTimingEvent, type ResolvedConfig as ResolvedIQAuthHelperConfig, type SetCookieDirective, type SignoutRegistry, type UserinfoResponse, __resetSignoutMarkersForTests, __resetSignoutRegistryWarningForTests, buildUserinfoResponse, createInMemorySignoutRegistry, handleCallback, handleRefresh, handleSignout, handleUserinfo, serializeCookie };

package/dist/server/handlers.d.ts

@@ -1,5 +1,5 @@
-import { c as TokenVerifyOptions } from '../tokens-Bqhmqq_R.js';
-import { J as JwtClaims, S as SessionUser } from '../types-XOV9XPVi.js';
+import { c as TokenVerifyOptions } from '../tokens-9F6ETrzk.js';
+import { J as JwtClaims, S as SessionUser } from '../types-Bn8O-OEd.js';
 
 /**
  * Framework-neutral helper handlers for the auto-mounted routes added by the
@@ -99,8 +99,21 @@ interface IQAuthHelperConfig {
     cookieDomain?: string;
     /** Cookie sameSite policy. Defaults to `lax`. */
     sameSite?: "lax" | "strict" | "none";
-    /** Cookie secure flag. Defaults to true (set false for local http dev). */
+    /**
+     * Cookie secure flag. Defaults to `true`. Setting it to `false` ships auth
+     * cookies over plaintext HTTP, exposing them to passive network attackers —
+     * so it is REFUSED by default (the helper throws `config_invalid`). To run a
+     * local HTTP dev box you must explicitly acknowledge the risk by ALSO setting
+     * {@link IQAuthHelperConfig.allowInsecureCookies} to `true`.
+     */
     secure?: boolean;
+    /**
+     * Explicit, opt-in acknowledgement that `secure: false` is intentional (local
+     * HTTP development only). Without this, `secure: false` throws so a misconfig
+     * can never silently downgrade production cookies to plaintext. Has no effect
+     * unless `secure` is `false`. Production MUST leave this unset / `false`.
+     */
+    allowInsecureCookies?: boolean;
     /** Cookie path. Defaults to `/`. */
     cookiePath?: string;
     /** Path of the OIDC token endpoint. */
@@ -183,6 +196,30 @@ interface IQAuthHelperConfig {
      * legitimate fresh sign-in.
      */
     signoutMarkerTtlMs?: number;
+    /**
+     * M-2 — Server-side OAuth `state` (CSRF) enforcement on the callback.
+     *
+     * When `true` (the DEFAULT), {@link handleCallback} requires BOTH the
+     * `state` returned by the OAuth redirect AND a previously-stored
+     * `expectedState` (read by the adapter from the {@link stateCookieName}
+     * cookie the SDK publishes before redirect), and fails closed with
+     * `STATE_MISMATCH` (no code exchange, no session cookie) when either is
+     * missing or they do not match. This defeats login-CSRF / session-fixation
+     * where an attacker injects their own authorization code.
+     *
+     * Set to `false` to restore the prior permissive behavior (state is only
+     * validated when an `expectedState` cookie happens to be present). This is
+     * an escape hatch for integrators whose initiation step does not publish a
+     * state cookie; it weakens CSRF protection and is not recommended.
+     */
+    requireOAuthState?: boolean;
+    /**
+     * Name of the first-party cookie the SDK publishes the OAuth `state` value
+     * into before redirecting to the issuer. The adapter reads it back on the
+     * callback as `expectedState`. Defaults to `iqauth_state` (matches the
+     * express inline-callback adapter and the React server-managed sign-in).
+     */
+    stateCookieName?: string;
 }
 interface IQAuthTimingEvent {
     phase: "callback" | "refresh" | "signout" | "bootstrap" | "signIn";
@@ -202,7 +239,7 @@ interface SignoutRegistry {
     mark(idempotencyToken: string, ttlMs: number): void | Promise<void>;
     has(idempotencyToken: string): boolean | Promise<boolean>;
 }
-interface ResolvedConfig extends Required<Omit<IQAuthHelperConfig, "secretKey" | "cookieDomain" | "issuer" | "fetchImpl" | "clearCookiesOnRefreshFailure" | "cookieNames" | "mountUserinfo" | "userinfoEnricher" | "verify" | "debug" | "onTimingEvent" | "signoutRegistry" | "signoutMarkerTtlMs">> {
+interface ResolvedConfig extends Required<Omit<IQAuthHelperConfig, "secretKey" | "cookieDomain" | "issuer" | "fetchImpl" | "clearCookiesOnRefreshFailure" | "cookieNames" | "mountUserinfo" | "userinfoEnricher" | "verify" | "debug" | "onTimingEvent" | "signoutRegistry" | "signoutMarkerTtlMs" | "allowInsecureCookies">> {
     cookieNames?: {
         access?: string;
         refresh?: string;
@@ -225,6 +262,12 @@ interface ResolvedConfig extends Required<Omit<IQAuthHelperConfig, "secretKey" |
  * public surface.
  */
 declare function __resetSignoutMarkersForTests(): void;
+/**
+ * Test-only hook to reset the one-time default-registry boot warning so each
+ * test can assert the warn-once behavior in isolation. Not part of the public
+ * surface.
+ */
+declare function __resetSignoutRegistryWarningForTests(): void;
 /**
  * Public factory for a fresh in-memory {@link SignoutRegistry}. Useful for
  * tests that want isolated state per case, and as a reference implementation
@@ -242,6 +285,14 @@ declare function handleCallback(config: IQAuthHelperConfig, input: {
     code?: string;
     codeVerifier?: string;
     redirectUri?: string;
+    /** The `state` value returned by the OAuth redirect (query or body). */
+    state?: string;
+    /**
+     * The `state` value the SDK stored before redirect, read by the adapter
+     * from the {@link IQAuthHelperConfig.stateCookieName} cookie. Compared
+     * against `state` to bind the callback to this browser (M-2 CSRF).
+     */
+    expectedState?: string;
 }): Promise<HandlerResponse>;
 /** POST /api/iqauth/refresh — rotate refresh + access cookies.
  *
@@ -276,4 +327,4 @@ declare function handleUserinfo(config: IQAuthHelperConfig, input: {
     req?: unknown;
 }): Promise<HandlerResponse>;
 
-export { type HandlerResponse, type IQAuthHelperConfig, type IQAuthTimingEvent, type ResolvedConfig as ResolvedIQAuthHelperConfig, type SetCookieDirective, type SignoutRegistry, type UserinfoResponse, __resetSignoutMarkersForTests, buildUserinfoResponse, createInMemorySignoutRegistry, handleCallback, handleRefresh, handleSignout, handleUserinfo, serializeCookie };
+export { type HandlerResponse, type IQAuthHelperConfig, type IQAuthTimingEvent, type ResolvedConfig as ResolvedIQAuthHelperConfig, type SetCookieDirective, type SignoutRegistry, type UserinfoResponse, __resetSignoutMarkersForTests, __resetSignoutRegistryWarningForTests, buildUserinfoResponse, createInMemorySignoutRegistry, handleCallback, handleRefresh, handleSignout, handleUserinfo, serializeCookie };

package/dist/server/handlers.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var handlers_exports = {};
 __export(handlers_exports, {
   __resetSignoutMarkersForTests: () => __resetSignoutMarkersForTests,
+  __resetSignoutRegistryWarningForTests: () => __resetSignoutRegistryWarningForTests,
   buildUserinfoResponse: () => buildUserinfoResponse,
   createInMemorySignoutRegistry: () => createInMemorySignoutRegistry,
   handleCallback: () => handleCallback,
@@ -362,7 +363,11 @@ async function buildUserinfoResponse(claims, opts = {}) {
     tenantId: claims.tenantId,
     vendorId: claims.vendorId,
     roles: claims.roles ?? [],
-    entitlements: claims.entitlements ?? []
+    entitlements: claims.entitlements ?? [],
+    // Task #171 — project the active source/client scope onto the userinfo
+    // payload so server handlers (`getSessionUser`, `/api/iqauth/userinfo`)
+    // expose it without consumers having to re-decode the JWT.
+    ...claims.scopeContext !== void 0 ? { scopeContext: claims.scopeContext } : {}
   };
   const enriched = opts.enrich ? await opts.enrich(claims) : null;
   const user = enriched ? { ...baseUser, ...enriched } : baseUser;
@@ -407,19 +412,62 @@ function shouldClearCookiesOnFailure(policy, status, errorCode) {
 }
 var ACCESS_TOKEN_TTL_SECONDS = 60 * 15;
 var REFRESH_TOKEN_TTL_SECONDS = 60 * 60 * 24 * 30;
+function assertCookiePrefixInvariants(name, secure, path, domain) {
+  if (name.startsWith("__Host-")) {
+    if (!secure) {
+      throw new IQAuthError(
+        "config_invalid",
+        `Cookie "${name}" uses the __Host- prefix, which browsers only accept on a Secure cookie. Set secure:true (and serve over HTTPS).`
+      );
+    }
+    if (path !== "/") {
+      throw new IQAuthError(
+        "config_invalid",
+        `Cookie "${name}" uses the __Host- prefix, which requires Path=/ (got "${path}"). Remove cookiePath or set it to "/".`
+      );
+    }
+    if (domain) {
+      throw new IQAuthError(
+        "config_invalid",
+        `Cookie "${name}" uses the __Host- prefix, which forbids a Domain attribute (the cookie is host-locked). Remove cookieDomain.`
+      );
+    }
+  } else if (name.startsWith("__Secure-") && !secure) {
+    throw new IQAuthError(
+      "config_invalid",
+      `Cookie "${name}" uses the __Secure- prefix, which browsers only accept on a Secure cookie. Set secure:true (and serve over HTTPS).`
+    );
+  }
+}
 function resolve(config) {
   const parsed = assertPublishableKey(config.publishableKey, { context: "@iqauth/sdk helpers" });
   const inferredIssuer = parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`;
+  maybeWarnDefaultSignoutRegistry(config);
+  const secure = config.secure ?? true;
+  if (config.secure === false && config.allowInsecureCookies !== true) {
+    throw new IQAuthError(
+      "config_invalid",
+      "Refusing to issue auth cookies with secure:false \u2014 this exposes session cookies over plaintext HTTP. For local HTTP development, set allowInsecureCookies:true to acknowledge the risk. Production MUST use HTTPS with secure cookies."
+    );
+  }
+  const accessCookieName = config.accessCookieName ?? config.cookieNames?.access ?? "iqauth_at";
+  const refreshCookieName = config.refreshCookieName ?? config.cookieNames?.refresh ?? "iqauth_rt";
+  const stateCookieName = config.stateCookieName ?? "iqauth_state";
+  const cookiePath = config.cookiePath ?? "/";
+  const cookieDomain = config.cookieDomain;
+  for (const name of [accessCookieName, refreshCookieName, stateCookieName]) {
+    assertCookiePrefixInvariants(name, secure, cookiePath, cookieDomain);
+  }
   return {
     publishableKey: config.publishableKey,
     secretKey: config.secretKey,
     issuer: (config.issuer ?? inferredIssuer).replace(/\/+$/, ""),
-    accessCookieName: config.accessCookieName ?? config.cookieNames?.access ?? "iqauth_at",
-    refreshCookieName: config.refreshCookieName ?? config.cookieNames?.refresh ?? "iqauth_rt",
-    cookieDomain: config.cookieDomain,
+    accessCookieName,
+    refreshCookieName,
+    cookieDomain,
     sameSite: config.sameSite ?? "lax",
-    secure: config.secure ?? true,
-    cookiePath: config.cookiePath ?? "/",
+    secure,
+    cookiePath,
     tokenPath: config.tokenPath ?? "/oidc/token",
     refreshPath: config.refreshPath ?? "/api/v1/auth/refresh",
     logoutPath: config.logoutPath ?? "/api/v1/auth/logout",
@@ -432,9 +480,19 @@ function resolve(config) {
     debug: config.debug,
     onTimingEvent: config.onTimingEvent,
     signoutRegistry: config.signoutRegistry ?? defaultSignoutRegistry,
-    signoutMarkerTtlMs: config.signoutMarkerTtlMs ?? DEFAULT_SIGNOUT_TTL_MS
+    signoutMarkerTtlMs: config.signoutMarkerTtlMs ?? DEFAULT_SIGNOUT_TTL_MS,
+    requireOAuthState: config.requireOAuthState ?? true,
+    stateCookieName: config.stateCookieName ?? "iqauth_state"
   };
 }
+function timingSafeEqualStr(a, b) {
+  const len = Math.max(a.length, b.length);
+  let diff = a.length ^ b.length;
+  for (let i = 0; i < len; i++) {
+    diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
+  }
+  return diff === 0;
+}
 function makeCookie(cfg, name, value, maxAge, httpOnly = true) {
   return {
     name,
@@ -453,6 +511,9 @@ function clearCookies(cfg) {
     { ...makeCookie(cfg, cfg.refreshCookieName, "", 0), clear: true }
   ];
 }
+function clearStateCookie(cfg) {
+  return { ...makeCookie(cfg, cfg.stateCookieName, "", 0, false), clear: true };
+}
 var DEFAULT_SIGNOUT_TTL_MS = 6e4;
 var inMemorySignoutMarkers = /* @__PURE__ */ new Map();
 function pruneInMemoryMarkers(now) {
@@ -478,9 +539,21 @@ var defaultSignoutRegistry = {
     return true;
   }
 };
+var warnedDefaultSignoutRegistry = false;
+function maybeWarnDefaultSignoutRegistry(config) {
+  if (warnedDefaultSignoutRegistry) return;
+  if (config.signoutRegistry) return;
+  warnedDefaultSignoutRegistry = true;
+  console.warn(
+    "[IQAuth] Using the in-memory signout registry (process-local). Signout idempotency is NOT shared across instances \u2014 in a multi-replica deployment a /refresh racing a /signout on another replica can reissue cookies after sign-out. Plug a shared backend (e.g. Redis) into IQAuthHelperConfig.signoutRegistry to fix this and silence this warning."
+  );
+}
 function __resetSignoutMarkersForTests() {
   inMemorySignoutMarkers.clear();
 }
+function __resetSignoutRegistryWarningForTests() {
+  warnedDefaultSignoutRegistry = false;
+}
 function createInMemorySignoutRegistry() {
   const store = /* @__PURE__ */ new Map();
   return {
@@ -523,6 +596,23 @@ async function handleCallback(config, input) {
       cookies: []
     };
   }
+  const provided = input.state;
+  const expected = input.expectedState;
+  const stateOk = cfg.requireOAuthState ? !!expected && !!provided && timingSafeEqualStr(provided, expected) : !expected || !!provided && timingSafeEqualStr(provided, expected);
+  if (!stateOk) {
+    emitTiming(cfg, { phase: "callback", durationMs: Date.now() - t0, ok: false, code: "STATE_MISMATCH" });
+    return {
+      status: 400,
+      body: {
+        success: false,
+        error: {
+          code: "STATE_MISMATCH",
+          message: "OAuth state validation failed; the sign-in could not be verified as originating from this browser."
+        }
+      },
+      cookies: [clearStateCookie(cfg)]
+    };
+  }
   if (!cfg.secretKey) {
     emitTiming(cfg, { phase: "callback", durationMs: Date.now() - t0, ok: false, code: "INTERNAL_ERROR" });
     return {
@@ -561,6 +651,26 @@ async function handleCallback(config, input) {
       cookies: []
     };
   }
+  try {
+    await getTokensFor(cfg.issuer).verify(json.access_token, {
+      issuer: cfg.issuer,
+      ...config.verify
+    });
+  } catch (err) {
+    const code = err instanceof IQAuthError ? err.code : err.code || "TOKEN_INVALID";
+    emitTiming(cfg, { phase: "callback", durationMs: Date.now() - t0, ok: false, code });
+    return {
+      status: 502,
+      body: {
+        success: false,
+        error: {
+          code: "ACCESS_TOKEN_VERIFICATION_FAILED",
+          message: "The issuer returned an access token that failed verification; no session was established."
+        }
+      },
+      cookies: []
+    };
+  }
   const cookies = [];
   cookies.push(
     makeCookie(cfg, cfg.accessCookieName, json.access_token, json.expires_in ?? ACCESS_TOKEN_TTL_SECONDS)
@@ -568,6 +678,7 @@ async function handleCallback(config, input) {
   if (json.refresh_token) {
     cookies.push(makeCookie(cfg, cfg.refreshCookieName, json.refresh_token, REFRESH_TOKEN_TTL_SECONDS));
   }
+  cookies.push(clearStateCookie(cfg));
   emitTiming(cfg, { phase: "callback", durationMs: Date.now() - t0, ok: true });
   return {
     status: 200,
@@ -689,7 +800,10 @@ async function handleUserinfo(config, input) {
   }
   let claims;
   try {
-    claims = await getTokensFor(cfg.issuer).verify(input.accessToken, config.verify);
+    claims = await getTokensFor(cfg.issuer).verify(input.accessToken, {
+      issuer: cfg.issuer,
+      ...config.verify
+    });
   } catch (err) {
     const code = err instanceof IQAuthError ? err.code : err.code || "TOKEN_INVALID";
     const message = err instanceof Error ? err.message : "Access token verification failed";
@@ -711,6 +825,7 @@ async function handleUserinfo(config, input) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   __resetSignoutMarkersForTests,
+  __resetSignoutRegistryWarningForTests,
   buildUserinfoResponse,
   createInMemorySignoutRegistry,
   handleCallback,

package/dist/server/handlers.mjs

@@ -1,5 +1,6 @@
 import {
   __resetSignoutMarkersForTests,
+  __resetSignoutRegistryWarningForTests,
   buildUserinfoResponse,
   createInMemorySignoutRegistry,
   handleCallback,
@@ -7,13 +8,14 @@ import {
   handleSignout,
   handleUserinfo,
   serializeCookie
-} from "../chunk-RUJXRTEW.mjs";
+} from "../chunk-WSH4SW7F.mjs";
 import "../chunk-HVHNYPDC.mjs";
 import "../chunk-NUO2I65G.mjs";
 import "../chunk-6PJRLRB4.mjs";
 import "../chunk-Y6FXYEAI.mjs";
 export {
   __resetSignoutMarkersForTests,
+  __resetSignoutRegistryWarningForTests,
   buildUserinfoResponse,
   createInMemorySignoutRegistry,
   handleCallback,

package/dist/server.d.mts

@@ -1,10 +1,10 @@
-import { J as JwtClaims, f as IQAuthTokenClientConfig, X as ExpressMiddlewareOptions, a as IQAuthRequestLike, b as IQAuthResponseLike, c as IQAuthNextFunction } from './types-XOV9XPVi.mjs';
-import { I as IQAuthClient } from './client-BGFnBpfc.mjs';
+import { J as JwtClaims, f as IQAuthTokenClientConfig, X as ExpressMiddlewareOptions, a as IQAuthRequestLike, b as IQAuthResponseLike, c as IQAuthNextFunction } from './types-Bn8O-OEd.mjs';
+import { I as IQAuthClient } from './client-D8L-PaWr.mjs';
 export { E as ErrorCodes, I as IQAuthError } from './errors-Jl1Jtm-6.mjs';
-export { C as CookieAwareMiddlewareOptions, D as DEFAULT_ACCESS_COOKIE, a as DEFAULT_REFRESH_COOKIE, i as iqAuthMiddleware } from './express-CVNQEkOr.mjs';
+export { C as CookieAwareMiddlewareOptions, D as DEFAULT_ACCESS_COOKIE, a as DEFAULT_REFRESH_COOKIE, i as iqAuthMiddleware } from './express-DDTA3qV1.mjs';
 export { HandlerResponse, IQAuthHelperConfig, SetCookieDirective, UserinfoResponse, buildUserinfoResponse, handleCallback, handleRefresh, handleSignout, handleUserinfo, serializeCookie } from './server/handlers.mjs';
-export { P as ProvisioningBridge, a as ProvisioningBridgeOptions, d as ProvisioningContext, b as ProvisioningStorage, c as createProvisioningBridge } from './provisioningBridge-M5G47LWO.mjs';
-import './tokens-CITeoG6P.mjs';
+export { P as ProvisioningBridge, a as ProvisioningBridgeOptions, d as ProvisioningContext, e as ProvisioningError, b as ProvisioningStorage, c as createProvisioningBridge } from './provisioningBridge-IEycmsgb.mjs';
+import './tokens-B06VtvUi.mjs';
 
 /**
  * linkLocalUserToIqAuthSub — first-time-migration helper.
@@ -31,9 +31,17 @@ import './tokens-CITeoG6P.mjs';
  *   - 'linked'         — wrote claims.sub onto the matched local row.
  *   - 'already_linked' — a row was already keyed by claims.sub. No write.
  *   - 'conflict'       — matched row already has a different non-null sub,
- *                        OR more than one local row matches the email.
+ *                        OR more than one local row matches the email,
+ *                        OR the email is unverified and adoption is gated
+ *                        (reason 'unverified_email' — see H-4 below).
  *   - 'not_found'      — no local row matched any of the provided lookupBy
  *                        keys. Caller should provision a new row separately.
+ *
+ * Security (H-4): writing the IQAuth `sub` onto a pre-existing local row matched
+ * by email is a takeover of that account. It is only performed when the claims
+ * assert a verified email (`claims.email_verified === true`). When the email is
+ * unverified and `allowUnverifiedEmail` is not set, the helper fails closed with
+ * `{ status: 'conflict', reason: 'unverified_email' }` instead of linking.
  */
 
 type LinkLookupBy = "email";
@@ -46,7 +54,7 @@ type LinkResult = {
 } | {
     status: "conflict";
     userId?: string;
-    reason: "different_sub" | "duplicate_email";
+    reason: "different_sub" | "duplicate_email" | "unverified_email";
 } | {
     status: "not_found";
 };
@@ -85,7 +93,7 @@ interface LinkAdapter {
 }
 interface LinkLocalUserOptions {
     adapter: LinkAdapter;
-    claims: Pick<JwtClaims, "sub" | "email">;
+    claims: Pick<JwtClaims, "sub" | "email" | "email_verified">;
     /**
      * Lookup keys to try, in order. Currently only `'email'` is supported.
      * Defaults to `['email']`.
@@ -96,6 +104,18 @@ interface LinkLocalUserOptions {
      * but preserve the cased original at registration time.
      */
     caseInsensitiveEmail?: boolean;
+    /**
+     * Security gate (H-4): by default the email→sub link only proceeds when the
+     * claims assert a verified email (`claims.email_verified === true`). When the
+     * email is unverified and this flag is left `false`, the helper fails closed
+     * with `{ status: 'conflict', reason: 'unverified_email' }` rather than
+     * letting an unverified email take over a pre-existing local account.
+     *
+     * Set `true` ONLY when your issuer is trusted to never emit an unverified
+     * email for linking (or you have a compensating control). Defaults to
+     * `false` (secure).
+     */
+    allowUnverifiedEmail?: boolean;
 }
 declare function linkLocalUserToIqAuthSub(options: LinkLocalUserOptions): Promise<LinkResult>;
 interface DrizzleLikeDb {

package/dist/server.d.ts

@@ -1,10 +1,10 @@
-import { J as JwtClaims, f as IQAuthTokenClientConfig, X as ExpressMiddlewareOptions, a as IQAuthRequestLike, b as IQAuthResponseLike, c as IQAuthNextFunction } from './types-XOV9XPVi.js';
-import { I as IQAuthClient } from './client-CDQ21LvW.js';
+import { J as JwtClaims, f as IQAuthTokenClientConfig, X as ExpressMiddlewareOptions, a as IQAuthRequestLike, b as IQAuthResponseLike, c as IQAuthNextFunction } from './types-Bn8O-OEd.js';
+import { I as IQAuthClient } from './client-DkPL0EPZ.js';
 export { E as ErrorCodes, I as IQAuthError } from './errors-Jl1Jtm-6.js';
-export { C as CookieAwareMiddlewareOptions, D as DEFAULT_ACCESS_COOKIE, a as DEFAULT_REFRESH_COOKIE, i as iqAuthMiddleware } from './express-Piv2WhWM.js';
+export { C as CookieAwareMiddlewareOptions, D as DEFAULT_ACCESS_COOKIE, a as DEFAULT_REFRESH_COOKIE, i as iqAuthMiddleware } from './express-Budysq4h.js';
 export { HandlerResponse, IQAuthHelperConfig, SetCookieDirective, UserinfoResponse, buildUserinfoResponse, handleCallback, handleRefresh, handleSignout, handleUserinfo, serializeCookie } from './server/handlers.js';
-export { P as ProvisioningBridge, a as ProvisioningBridgeOptions, d as ProvisioningContext, b as ProvisioningStorage, c as createProvisioningBridge } from './provisioningBridge-CGpMRie4.js';
-import './tokens-Bqhmqq_R.js';
+export { P as ProvisioningBridge, a as ProvisioningBridgeOptions, d as ProvisioningContext, e as ProvisioningError, b as ProvisioningStorage, c as createProvisioningBridge } from './provisioningBridge-BXPMZCLe.js';
+import './tokens-9F6ETrzk.js';
 
 /**
  * linkLocalUserToIqAuthSub — first-time-migration helper.
@@ -31,9 +31,17 @@ import './tokens-Bqhmqq_R.js';
  *   - 'linked'         — wrote claims.sub onto the matched local row.
  *   - 'already_linked' — a row was already keyed by claims.sub. No write.
  *   - 'conflict'       — matched row already has a different non-null sub,
- *                        OR more than one local row matches the email.
+ *                        OR more than one local row matches the email,
+ *                        OR the email is unverified and adoption is gated
+ *                        (reason 'unverified_email' — see H-4 below).
  *   - 'not_found'      — no local row matched any of the provided lookupBy
  *                        keys. Caller should provision a new row separately.
+ *
+ * Security (H-4): writing the IQAuth `sub` onto a pre-existing local row matched
+ * by email is a takeover of that account. It is only performed when the claims
+ * assert a verified email (`claims.email_verified === true`). When the email is
+ * unverified and `allowUnverifiedEmail` is not set, the helper fails closed with
+ * `{ status: 'conflict', reason: 'unverified_email' }` instead of linking.
  */
 
 type LinkLookupBy = "email";
@@ -46,7 +54,7 @@ type LinkResult = {
 } | {
     status: "conflict";
     userId?: string;
-    reason: "different_sub" | "duplicate_email";
+    reason: "different_sub" | "duplicate_email" | "unverified_email";
 } | {
     status: "not_found";
 };
@@ -85,7 +93,7 @@ interface LinkAdapter {
 }
 interface LinkLocalUserOptions {
     adapter: LinkAdapter;
-    claims: Pick<JwtClaims, "sub" | "email">;
+    claims: Pick<JwtClaims, "sub" | "email" | "email_verified">;
     /**
      * Lookup keys to try, in order. Currently only `'email'` is supported.
      * Defaults to `['email']`.
@@ -96,6 +104,18 @@ interface LinkLocalUserOptions {
      * but preserve the cased original at registration time.
      */
     caseInsensitiveEmail?: boolean;
+    /**
+     * Security gate (H-4): by default the email→sub link only proceeds when the
+     * claims assert a verified email (`claims.email_verified === true`). When the
+     * email is unverified and this flag is left `false`, the helper fails closed
+     * with `{ status: 'conflict', reason: 'unverified_email' }` rather than
+     * letting an unverified email take over a pre-existing local account.
+     *
+     * Set `true` ONLY when your issuer is trusted to never emit an unverified
+     * email for linking (or you have a compensating control). Defaults to
+     * `false` (secure).
+     */
+    allowUnverifiedEmail?: boolean;
 }
 declare function linkLocalUserToIqAuthSub(options: LinkLocalUserOptions): Promise<LinkResult>;
 interface DrizzleLikeDb {