@iqauth/sdk 2.7.0 → 2.8.1

package/dist/next.js

@@ -357,7 +357,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;
@@ -402,19 +406,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",
@@ -427,9 +474,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,
@@ -448,6 +505,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) {
@@ -473,6 +533,15 @@ 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 serializeCookie(d) {
   const parts = [`${d.name}=${encodeURIComponent(d.value)}`];
   parts.push(`Path=${d.path}`);
@@ -495,6 +564,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 {
@@ -533,6 +619,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)
@@ -540,6 +646,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,
@@ -661,7 +768,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";
@@ -681,7 +791,44 @@ async function handleUserinfo(config, input) {
   };
 }
 
+// src/browser/returnTo.ts
+function normalizeOrigin(o) {
+  try {
+    return new URL(o).origin;
+  } catch {
+    return o.replace(/\/+$/, "");
+  }
+}
+function sanitizeReturnTo(input, options = {}) {
+  const fallback = options.fallback ?? "/";
+  if (!input || typeof input !== "string") return fallback;
+  const trimmed = input.trim();
+  if (!trimmed) return fallback;
+  if (trimmed.includes("\\")) return fallback;
+  if (trimmed.startsWith("//")) return fallback;
+  if (trimmed.startsWith("/") || trimmed.startsWith("#") || trimmed.startsWith("?")) {
+    return trimmed;
+  }
+  if (!/^[a-z][a-z0-9+\-.]*:/i.test(trimmed)) {
+    return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  }
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return fallback;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return fallback;
+  const currentOrigin = options.currentOrigin ?? (typeof window !== "undefined" ? window.location.origin : "");
+  const allowed = /* @__PURE__ */ new Set();
+  if (currentOrigin) allowed.add(normalizeOrigin(currentOrigin));
+  for (const o of options.allowedOrigins ?? []) allowed.add(normalizeOrigin(o));
+  if (allowed.has(parsed.origin)) return parsed.toString();
+  return fallback;
+}
+
 // src/next.ts
+var PKCE_COOKIE = "iqauth_pkce";
 function readCookieFromHeader(header, name) {
   if (!header) return void 0;
   const target = `${name}=`;
@@ -702,12 +849,43 @@ function toResponse(hr) {
   for (const c of hr.cookies) headers.append("set-cookie", serializeCookie(c));
   return new Response(JSON.stringify(hr.body), { status: hr.status, headers });
 }
+function callbackResponse(hr, requestOrigin, returnToCookieValue, returnToCookieName) {
+  const returnTo = sanitizeReturnTo(
+    returnToCookieValue || hr.body?.returnTo,
+    { currentOrigin: requestOrigin, fallback: "/" }
+  );
+  const headers = new Headers({ "Content-Type": "application/json" });
+  for (const c of hr.cookies) headers.append("set-cookie", serializeCookie(c));
+  if (hr.status < 400) {
+    headers.append("set-cookie", `${returnToCookieName}=; Path=/; Max-Age=0; SameSite=Lax`);
+  }
+  const body = { ...hr.body, returnTo };
+  return new Response(JSON.stringify(body), { status: hr.status, headers });
+}
+function callbackRedirectResponse(hr, requestOrigin, returnToCookieValue, cookieNames) {
+  const headers = new Headers();
+  for (const c of hr.cookies) headers.append("set-cookie", serializeCookie(c));
+  headers.append("set-cookie", `${cookieNames.state}=; Path=/; Max-Age=0; SameSite=Lax`);
+  headers.append("set-cookie", `${cookieNames.pkce}=; Path=/; Max-Age=0; SameSite=Lax`);
+  if (hr.status >= 400) {
+    headers.set("Location", "/");
+    return new Response(null, { status: 302, headers });
+  }
+  const dest = sanitizeReturnTo(returnToCookieValue, {
+    currentOrigin: requestOrigin,
+    fallback: "/"
+  });
+  headers.append("set-cookie", `${cookieNames.returnTo}=; Path=/; Max-Age=0; SameSite=Lax`);
+  headers.set("Location", dest);
+  return new Response(null, { status: 302, headers });
+}
 function handler(options) {
   const parsed = assertPublishableKey(options.publishableKey, { context: "@iqauth/sdk/next handler" });
   const issuer = (options.issuer ?? (parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`)).replace(/\/+$/, "");
   const helperConfig = { ...options, issuer };
   const accessCookie = options.accessCookieName ?? "iqauth_at";
   const refreshCookie = options.refreshCookieName ?? "iqauth_rt";
+  const returnToCookie = options.returnToCookieName ?? "iqauth_return_to";
   return async (req) => {
     const url = new URL(req.url);
     const action = url.pathname.split("/").pop();
@@ -723,13 +901,36 @@ function handler(options) {
       const accessToken = auth && auth.replace(/^Bearer /i, "") || readCookieFromHeader(cookieHeader, accessCookie);
       return toResponse(await handleUserinfo(helperConfig, { accessToken, req }));
     }
+    const stateCookie = helperConfig.stateCookieName ?? "iqauth_state";
+    if (action === "callback" && req.method === "GET") {
+      const code = url.searchParams.get("code") ?? void 0;
+      const state = url.searchParams.get("state") ?? void 0;
+      const redirectUri = `${url.origin}${url.pathname}`;
+      const hr = await handleCallback(helperConfig, {
+        code,
+        codeVerifier: readCookieFromHeader(cookieHeader, PKCE_COOKIE),
+        redirectUri,
+        state,
+        expectedState: readCookieFromHeader(cookieHeader, stateCookie)
+      });
+      return callbackRedirectResponse(
+        hr,
+        url.origin,
+        readCookieFromHeader(cookieHeader, returnToCookie),
+        { returnTo: returnToCookie, state: stateCookie, pkce: PKCE_COOKIE }
+      );
+    }
     const body = await req.json().catch(() => ({}));
     if (action === "callback") {
-      return toResponse(await handleCallback(helperConfig, {
+      const hr = await handleCallback(helperConfig, {
         code: body.code,
         codeVerifier: body.codeVerifier,
-        redirectUri: body.redirectUri
-      }));
+        redirectUri: body.redirectUri,
+        // M-2: bind callback to this browser; handleCallback fails closed.
+        state: body.state,
+        expectedState: readCookieFromHeader(cookieHeader, helperConfig.stateCookieName ?? "iqauth_state")
+      });
+      return callbackResponse(hr, url.origin, readCookieFromHeader(cookieHeader, returnToCookie), returnToCookie);
     }
     if (action === "refresh") {
       const refreshToken = body.refreshToken || readCookieFromHeader(cookieHeader, refreshCookie);

package/dist/next.mjs

@@ -1,10 +1,13 @@
+import {
+  sanitizeReturnTo
+} from "./chunk-JRDVUWAL.mjs";
 import {
   handleCallback,
   handleRefresh,
   handleSignout,
   handleUserinfo,
   serializeCookie
-} from "./chunk-RUJXRTEW.mjs";
+} from "./chunk-WSH4SW7F.mjs";
 import {
   assertPublishableKey
 } from "./chunk-HVHNYPDC.mjs";
@@ -15,6 +18,7 @@ import "./chunk-6PJRLRB4.mjs";
 import "./chunk-Y6FXYEAI.mjs";
 
 // src/next.ts
+var PKCE_COOKIE = "iqauth_pkce";
 function readCookieFromHeader(header, name) {
   if (!header) return void 0;
   const target = `${name}=`;
@@ -35,12 +39,43 @@ function toResponse(hr) {
   for (const c of hr.cookies) headers.append("set-cookie", serializeCookie(c));
   return new Response(JSON.stringify(hr.body), { status: hr.status, headers });
 }
+function callbackResponse(hr, requestOrigin, returnToCookieValue, returnToCookieName) {
+  const returnTo = sanitizeReturnTo(
+    returnToCookieValue || hr.body?.returnTo,
+    { currentOrigin: requestOrigin, fallback: "/" }
+  );
+  const headers = new Headers({ "Content-Type": "application/json" });
+  for (const c of hr.cookies) headers.append("set-cookie", serializeCookie(c));
+  if (hr.status < 400) {
+    headers.append("set-cookie", `${returnToCookieName}=; Path=/; Max-Age=0; SameSite=Lax`);
+  }
+  const body = { ...hr.body, returnTo };
+  return new Response(JSON.stringify(body), { status: hr.status, headers });
+}
+function callbackRedirectResponse(hr, requestOrigin, returnToCookieValue, cookieNames) {
+  const headers = new Headers();
+  for (const c of hr.cookies) headers.append("set-cookie", serializeCookie(c));
+  headers.append("set-cookie", `${cookieNames.state}=; Path=/; Max-Age=0; SameSite=Lax`);
+  headers.append("set-cookie", `${cookieNames.pkce}=; Path=/; Max-Age=0; SameSite=Lax`);
+  if (hr.status >= 400) {
+    headers.set("Location", "/");
+    return new Response(null, { status: 302, headers });
+  }
+  const dest = sanitizeReturnTo(returnToCookieValue, {
+    currentOrigin: requestOrigin,
+    fallback: "/"
+  });
+  headers.append("set-cookie", `${cookieNames.returnTo}=; Path=/; Max-Age=0; SameSite=Lax`);
+  headers.set("Location", dest);
+  return new Response(null, { status: 302, headers });
+}
 function handler(options) {
   const parsed = assertPublishableKey(options.publishableKey, { context: "@iqauth/sdk/next handler" });
   const issuer = (options.issuer ?? (parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`)).replace(/\/+$/, "");
   const helperConfig = { ...options, issuer };
   const accessCookie = options.accessCookieName ?? "iqauth_at";
   const refreshCookie = options.refreshCookieName ?? "iqauth_rt";
+  const returnToCookie = options.returnToCookieName ?? "iqauth_return_to";
   return async (req) => {
     const url = new URL(req.url);
     const action = url.pathname.split("/").pop();
@@ -56,13 +91,36 @@ function handler(options) {
       const accessToken = auth && auth.replace(/^Bearer /i, "") || readCookieFromHeader(cookieHeader, accessCookie);
       return toResponse(await handleUserinfo(helperConfig, { accessToken, req }));
     }
+    const stateCookie = helperConfig.stateCookieName ?? "iqauth_state";
+    if (action === "callback" && req.method === "GET") {
+      const code = url.searchParams.get("code") ?? void 0;
+      const state = url.searchParams.get("state") ?? void 0;
+      const redirectUri = `${url.origin}${url.pathname}`;
+      const hr = await handleCallback(helperConfig, {
+        code,
+        codeVerifier: readCookieFromHeader(cookieHeader, PKCE_COOKIE),
+        redirectUri,
+        state,
+        expectedState: readCookieFromHeader(cookieHeader, stateCookie)
+      });
+      return callbackRedirectResponse(
+        hr,
+        url.origin,
+        readCookieFromHeader(cookieHeader, returnToCookie),
+        { returnTo: returnToCookie, state: stateCookie, pkce: PKCE_COOKIE }
+      );
+    }
     const body = await req.json().catch(() => ({}));
     if (action === "callback") {
-      return toResponse(await handleCallback(helperConfig, {
+      const hr = await handleCallback(helperConfig, {
         code: body.code,
         codeVerifier: body.codeVerifier,
-        redirectUri: body.redirectUri
-      }));
+        redirectUri: body.redirectUri,
+        // M-2: bind callback to this browser; handleCallback fails closed.
+        state: body.state,
+        expectedState: readCookieFromHeader(cookieHeader, helperConfig.stateCookieName ?? "iqauth_state")
+      });
+      return callbackResponse(hr, url.origin, readCookieFromHeader(cookieHeader, returnToCookie), returnToCookie);
     }
     if (action === "refresh") {
       const refreshToken = body.refreshToken || readCookieFromHeader(cookieHeader, refreshCookie);

package/dist/{provisioningBridge-M5G47LWO.d.mts → provisioningBridge-BXPMZCLe.d.ts}

@@ -1,4 +1,4 @@
-import { J as JwtClaims } from './types-XOV9XPVi.mjs';
+import { J as JwtClaims } from './types-Bn8O-OEd.js';
 
 /**
  * createProvisioningBridge — server-side helper that lifts the
@@ -21,6 +21,17 @@ import { J as JwtClaims } from './types-XOV9XPVi.mjs';
  * your local user table. See the JSDoc on each adapter for the contract.
  */
 
+/**
+ * Thrown when the bridge refuses to adopt a pre-existing local account because
+ * the IQAuth claims do not assert a verified email (`email_verified !== true`)
+ * and the integrator has not opted in via `allowUnverifiedEmailAdopt`. Carries
+ * a stable `.code` so callers can branch (e.g. provision a brand-new row under
+ * a different identity instead of adopting the email-matched one).
+ */
+declare class ProvisioningError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
 interface ProvisioningContext<TUser> {
     claims: JwtClaims;
     /** The local user record, looked up or freshly inserted. */
@@ -59,6 +70,23 @@ interface ProvisioningBridgeOptions<TUser> {
      * Defaults to checking for Postgres `23505` and SQLite `SQLITE_CONSTRAINT_UNIQUE`.
      */
     isUniqueViolation?: (err: unknown) => boolean;
+    /**
+     * Security gate (H-4): adopting a pre-existing local row matched by email is
+     * only performed when the IQAuth claims assert a verified email
+     * (`claims.email_verified === true`). When the claim is absent/false and a
+     * local row matches the email, the bridge **refuses to adopt** and throws
+     * `ProvisioningError("UNVERIFIED_EMAIL_ADOPT_REFUSED")` (fail closed) so an
+     * IdP that does not assert email verification cannot silently take over an
+     * existing account.
+     *
+     * Brand-new users (no email-matched row) are unaffected — there is nothing
+     * to take over, so they are inserted regardless of verification status.
+     *
+     * Set `true` ONLY when your issuer is trusted to never emit an unverified
+     * email for adoption (or you have a compensating control). Defaults to
+     * `false` (secure).
+     */
+    allowUnverifiedEmailAdopt?: boolean;
 }
 interface ProvisioningBridge<TUser> {
     /**
@@ -83,4 +111,4 @@ interface ProvisioningBridge<TUser> {
  */
 declare function createProvisioningBridge<TUser>(options: ProvisioningBridgeOptions<TUser>): ProvisioningBridge<TUser>;
 
-export { type ProvisioningBridge as P, type ProvisioningBridgeOptions as a, type ProvisioningStorage as b, createProvisioningBridge as c, type ProvisioningContext as d };
+export { type ProvisioningBridge as P, type ProvisioningBridgeOptions as a, type ProvisioningStorage as b, createProvisioningBridge as c, type ProvisioningContext as d, ProvisioningError as e };

package/dist/{provisioningBridge-CGpMRie4.d.ts → provisioningBridge-IEycmsgb.d.mts}

@@ -1,4 +1,4 @@
-import { J as JwtClaims } from './types-XOV9XPVi.js';
+import { J as JwtClaims } from './types-Bn8O-OEd.mjs';
 
 /**
  * createProvisioningBridge — server-side helper that lifts the
@@ -21,6 +21,17 @@ import { J as JwtClaims } from './types-XOV9XPVi.js';
  * your local user table. See the JSDoc on each adapter for the contract.
  */
 
+/**
+ * Thrown when the bridge refuses to adopt a pre-existing local account because
+ * the IQAuth claims do not assert a verified email (`email_verified !== true`)
+ * and the integrator has not opted in via `allowUnverifiedEmailAdopt`. Carries
+ * a stable `.code` so callers can branch (e.g. provision a brand-new row under
+ * a different identity instead of adopting the email-matched one).
+ */
+declare class ProvisioningError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
 interface ProvisioningContext<TUser> {
     claims: JwtClaims;
     /** The local user record, looked up or freshly inserted. */
@@ -59,6 +70,23 @@ interface ProvisioningBridgeOptions<TUser> {
      * Defaults to checking for Postgres `23505` and SQLite `SQLITE_CONSTRAINT_UNIQUE`.
      */
     isUniqueViolation?: (err: unknown) => boolean;
+    /**
+     * Security gate (H-4): adopting a pre-existing local row matched by email is
+     * only performed when the IQAuth claims assert a verified email
+     * (`claims.email_verified === true`). When the claim is absent/false and a
+     * local row matches the email, the bridge **refuses to adopt** and throws
+     * `ProvisioningError("UNVERIFIED_EMAIL_ADOPT_REFUSED")` (fail closed) so an
+     * IdP that does not assert email verification cannot silently take over an
+     * existing account.
+     *
+     * Brand-new users (no email-matched row) are unaffected — there is nothing
+     * to take over, so they are inserted regardless of verification status.
+     *
+     * Set `true` ONLY when your issuer is trusted to never emit an unverified
+     * email for adoption (or you have a compensating control). Defaults to
+     * `false` (secure).
+     */
+    allowUnverifiedEmailAdopt?: boolean;
 }
 interface ProvisioningBridge<TUser> {
     /**
@@ -83,4 +111,4 @@ interface ProvisioningBridge<TUser> {
  */
 declare function createProvisioningBridge<TUser>(options: ProvisioningBridgeOptions<TUser>): ProvisioningBridge<TUser>;
 
-export { type ProvisioningBridge as P, type ProvisioningBridgeOptions as a, type ProvisioningStorage as b, createProvisioningBridge as c, type ProvisioningContext as d };
+export { type ProvisioningBridge as P, type ProvisioningBridgeOptions as a, type ProvisioningStorage as b, createProvisioningBridge as c, type ProvisioningContext as d, ProvisioningError as e };

package/dist/react-permissions.d.mts

@@ -1,11 +1,11 @@
-import { S as SessionError } from './index-CKoZHAoc.mjs';
+import { S as SessionError } from './index-Cko-d5po.mjs';
 import 'csstype';
 import 'react/jsx-runtime';
 import 'react';
-import './signIn-T-CZ6t6r.mjs';
+import './signIn-CReqfXsh.mjs';
 import './publishableKey-f2kq-rKw.mjs';
-import './types-XOV9XPVi.mjs';
-import './types-BdQ2lqfT.mjs';
+import './types-Bn8O-OEd.mjs';
+import './types-DnU2LhXR.mjs';
 
 interface UseEffectivePermissionsOptions {
     /**

package/dist/react-permissions.d.ts

@@ -1,11 +1,11 @@
-import { S as SessionError } from './index-5KSZEnDe.js';
+import { S as SessionError } from './index-RNqwEcmY.js';
 import 'csstype';
 import 'react/jsx-runtime';
 import 'react';
-import './signIn-BLFnz8SV.js';
+import './signIn-Cfa1GTpO.js';
 import './publishableKey-f2kq-rKw.js';
-import './types-XOV9XPVi.js';
-import './types-BdQ2lqfT.js';
+import './types-Bn8O-OEd.js';
+import './types-DnU2LhXR.js';
 
 interface UseEffectivePermissionsOptions {
     /**

package/dist/react-permissions.mjs

@@ -1,15 +1,16 @@
 import {
   __useIQAuthInternal
-} 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 "./chunk-JRDVUWAL.mjs";
 import {
   expandPermissions,
   hasPermission
 } from "./chunk-GLXSIGVS.mjs";
 import "./chunk-HVHNYPDC.mjs";
-import "./chunk-5T7GHBX6.mjs";
+import "./chunk-TLET552H.mjs";
 import "./chunk-6PJRLRB4.mjs";
 import "./chunk-Y6FXYEAI.mjs";
 

package/dist/react.d.mts

@@ -1,11 +1,11 @@
-export { A as AccountSummary, K as AuthCallback, J as AuthCallbackProps, af as CreateOrganization, ad as CreateOrganizationProps, a as IQAuthAppearance, I as IQAuthAppearanceElements, L as IQAuthBranding, x as IQAuthLoaded, w as IQAuthLoading, c as IQAuthProvider, b as IQAuthProviderProps, G as IQAuthReturnToBouncer, F as IQAuthReturnToBouncerProps, N as IQAuthSignInContext, aa as ImpersonationBanner, a9 as ImpersonationBannerProps, a7 as ImpersonationInfo, ax as LinkedAccounts, aw as LinkedAccountsProps, at as MagicLinkSignInForm, as as MagicLinkSignInFormProps, M as MultisessionAppSupport, aj as OrganizationList, ai as OrganizationListProps, ah as OrganizationProfile, ag as OrganizationProfileProps, a6 as OrganizationSwitcher, a5 as OrganizationSwitcherProps, av as PasskeySignInButton, au as PasskeySignInButtonProps, z as Protect, P as ProtectProps, y as RedirectToSignIn, R as RedirectToSignInProps, C as RedirectToSignedIn, B as RedirectToSignedInProps, S as SessionError, m as SessionListItem, O as SharedComponentProps, Y as SignIn, W as SignInProps, $ as SignUp, Z as SignUpProps, t as SignedIn, v as SignedOut, q as UseAccountSwitcherResult, h as UseAuthResult, aq as UseLinkedIdentitiesResult, am as UseMagicLinkResult, j as UseOrganizationResult, ao as UsePasskeyResult, D as UseReturnToOptions, ab as UseReverificationOptions, n as UseSessionListResult, f as UseSessionResult, U as UseUserResult, a2 as UserButton, a1 as UserButtonProps, a4 as UserProfile, a3 as UserProfileProps, a0 as UserSummary, al as Waitlist, ak as WaitlistProps, _ as __useIQAuthInternal, ay as __version__, X as isSilentSsoEligible, H as preflightReturnTo, r as revokeSession, T as sanitizeBrandCss, ae as slugify, p as useAccountList, s as useAccountSwitcher, i as useAuth, l as useAuthFetch, Q as useIQAuthSignInContext, a8 as useImpersonation, ar as useLinkedIdentities, u as useLocale, an as useMagicLink, k as useOrganization, ap as usePasskey, V as useResolvedSdkBranding, E as useReturnTo, ac as useReverification, g as useSession, o as useSessionList, d as useT, e as useUser } from './index-CKoZHAoc.mjs';
-export { I as IQAuthLocaleBundle, a as IQAuthLocaleKey, b as IQAuthLocaleOverride } from './types-BdQ2lqfT.mjs';
+export { A as AccountSummary, Q as AuthCallback, O as AuthCallbackProps, aq as CreateOrganization, ao as CreateOrganizationProps, a as IQAuthAppearance, I as IQAuthAppearanceElements, V as IQAuthBranding, x as IQAuthLoaded, w as IQAuthLoading, c as IQAuthProvider, b as IQAuthProviderProps, L as IQAuthReturnToBouncer, K as IQAuthReturnToBouncerProps, W as IQAuthSignInContext, al as ImpersonationBanner, ak as ImpersonationBannerProps, ai as ImpersonationInfo, aI as LinkedAccounts, aH as LinkedAccountsProps, aE as MagicLinkSignInForm, aD as MagicLinkSignInFormProps, M as MultisessionAppSupport, au as OrganizationList, at as OrganizationListProps, as as OrganizationProfile, ar as OrganizationProfileProps, ac as OrganizationSwitcher, ab as OrganizationSwitcherProps, aG as PasskeySignInButton, aF as PasskeySignInButtonProps, E as Protect, P as ProtectProps, y as RedirectToSignIn, R as RedirectToSignInProps, G as RedirectToSignedIn, F as RedirectToSignedInProps, C as ScopeRequirement, ah as ScopeSwitcher, ag as ScopeSwitcherProps, ad as ScopedMembership, S as SessionError, m as SessionListItem, X as SharedComponentProps, a3 as SignIn, a0 as SignInProps, a5 as SignUp, a4 as SignUpProps, t as SignedIn, v as SignedOut, T as TenantSwitchResult, q as UseAccountSwitcherResult, h as UseAuthResult, aB as UseLinkedIdentitiesResult, ax as UseMagicLinkResult, ae as UseMembershipsResult, j as UseOrganizationResult, az as UsePasskeyResult, H as UseReturnToOptions, am as UseReverificationOptions, n as UseSessionListResult, f as UseSessionResult, U as UseUserResult, a8 as UserButton, a7 as UserButtonProps, aa as UserProfile, a9 as UserProfileProps, a6 as UserSummary, aw as Waitlist, av as WaitlistProps, _ as __useIQAuthInternal, aJ as __version__, D as claimSatisfiesScope, a1 as isSilentSsoEligible, z as performScopeSwitch, B as performTenantSwitch, N as preflightReturnTo, a2 as resolveAfterSignInDestination, r as revokeSession, Z as sanitizeBrandCss, ap as slugify, p as useAccountList, s as useAccountSwitcher, i as useAuth, l as useAuthFetch, Y as useIQAuthSignInContext, aj as useImpersonation, aC as useLinkedIdentities, u as useLocale, ay as useMagicLink, af as useMemberships, k as useOrganization, aA as usePasskey, $ as useResolvedSdkBranding, J as useReturnTo, an as useReverification, g as useSession, o as useSessionList, d as useT, e as useUser } from './index-Cko-d5po.mjs';
+export { I as IQAuthLocaleBundle, a as IQAuthLocaleKey, b as IQAuthLocaleOverride } from './types-DnU2LhXR.mjs';
 import 'csstype';
 import 'react/jsx-runtime';
 import 'react';
-import './signIn-T-CZ6t6r.mjs';
+import './signIn-CReqfXsh.mjs';
 import './publishableKey-f2kq-rKw.mjs';
-import './types-XOV9XPVi.mjs';
+import './types-Bn8O-OEd.mjs';
 
 /**
  * F4 — return-to URL handling.

package/dist/react.d.ts

@@ -1,11 +1,11 @@
-export { A as AccountSummary, K as AuthCallback, J as AuthCallbackProps, af as CreateOrganization, ad as CreateOrganizationProps, a as IQAuthAppearance, I as IQAuthAppearanceElements, L as IQAuthBranding, x as IQAuthLoaded, w as IQAuthLoading, c as IQAuthProvider, b as IQAuthProviderProps, G as IQAuthReturnToBouncer, F as IQAuthReturnToBouncerProps, N as IQAuthSignInContext, aa as ImpersonationBanner, a9 as ImpersonationBannerProps, a7 as ImpersonationInfo, ax as LinkedAccounts, aw as LinkedAccountsProps, at as MagicLinkSignInForm, as as MagicLinkSignInFormProps, M as MultisessionAppSupport, aj as OrganizationList, ai as OrganizationListProps, ah as OrganizationProfile, ag as OrganizationProfileProps, a6 as OrganizationSwitcher, a5 as OrganizationSwitcherProps, av as PasskeySignInButton, au as PasskeySignInButtonProps, z as Protect, P as ProtectProps, y as RedirectToSignIn, R as RedirectToSignInProps, C as RedirectToSignedIn, B as RedirectToSignedInProps, S as SessionError, m as SessionListItem, O as SharedComponentProps, Y as SignIn, W as SignInProps, $ as SignUp, Z as SignUpProps, t as SignedIn, v as SignedOut, q as UseAccountSwitcherResult, h as UseAuthResult, aq as UseLinkedIdentitiesResult, am as UseMagicLinkResult, j as UseOrganizationResult, ao as UsePasskeyResult, D as UseReturnToOptions, ab as UseReverificationOptions, n as UseSessionListResult, f as UseSessionResult, U as UseUserResult, a2 as UserButton, a1 as UserButtonProps, a4 as UserProfile, a3 as UserProfileProps, a0 as UserSummary, al as Waitlist, ak as WaitlistProps, _ as __useIQAuthInternal, ay as __version__, X as isSilentSsoEligible, H as preflightReturnTo, r as revokeSession, T as sanitizeBrandCss, ae as slugify, p as useAccountList, s as useAccountSwitcher, i as useAuth, l as useAuthFetch, Q as useIQAuthSignInContext, a8 as useImpersonation, ar as useLinkedIdentities, u as useLocale, an as useMagicLink, k as useOrganization, ap as usePasskey, V as useResolvedSdkBranding, E as useReturnTo, ac as useReverification, g as useSession, o as useSessionList, d as useT, e as useUser } from './index-5KSZEnDe.js';
-export { I as IQAuthLocaleBundle, a as IQAuthLocaleKey, b as IQAuthLocaleOverride } from './types-BdQ2lqfT.js';
+export { A as AccountSummary, Q as AuthCallback, O as AuthCallbackProps, aq as CreateOrganization, ao as CreateOrganizationProps, a as IQAuthAppearance, I as IQAuthAppearanceElements, V as IQAuthBranding, x as IQAuthLoaded, w as IQAuthLoading, c as IQAuthProvider, b as IQAuthProviderProps, L as IQAuthReturnToBouncer, K as IQAuthReturnToBouncerProps, W as IQAuthSignInContext, al as ImpersonationBanner, ak as ImpersonationBannerProps, ai as ImpersonationInfo, aI as LinkedAccounts, aH as LinkedAccountsProps, aE as MagicLinkSignInForm, aD as MagicLinkSignInFormProps, M as MultisessionAppSupport, au as OrganizationList, at as OrganizationListProps, as as OrganizationProfile, ar as OrganizationProfileProps, ac as OrganizationSwitcher, ab as OrganizationSwitcherProps, aG as PasskeySignInButton, aF as PasskeySignInButtonProps, E as Protect, P as ProtectProps, y as RedirectToSignIn, R as RedirectToSignInProps, G as RedirectToSignedIn, F as RedirectToSignedInProps, C as ScopeRequirement, ah as ScopeSwitcher, ag as ScopeSwitcherProps, ad as ScopedMembership, S as SessionError, m as SessionListItem, X as SharedComponentProps, a3 as SignIn, a0 as SignInProps, a5 as SignUp, a4 as SignUpProps, t as SignedIn, v as SignedOut, T as TenantSwitchResult, q as UseAccountSwitcherResult, h as UseAuthResult, aB as UseLinkedIdentitiesResult, ax as UseMagicLinkResult, ae as UseMembershipsResult, j as UseOrganizationResult, az as UsePasskeyResult, H as UseReturnToOptions, am as UseReverificationOptions, n as UseSessionListResult, f as UseSessionResult, U as UseUserResult, a8 as UserButton, a7 as UserButtonProps, aa as UserProfile, a9 as UserProfileProps, a6 as UserSummary, aw as Waitlist, av as WaitlistProps, _ as __useIQAuthInternal, aJ as __version__, D as claimSatisfiesScope, a1 as isSilentSsoEligible, z as performScopeSwitch, B as performTenantSwitch, N as preflightReturnTo, a2 as resolveAfterSignInDestination, r as revokeSession, Z as sanitizeBrandCss, ap as slugify, p as useAccountList, s as useAccountSwitcher, i as useAuth, l as useAuthFetch, Y as useIQAuthSignInContext, aj as useImpersonation, aC as useLinkedIdentities, u as useLocale, ay as useMagicLink, af as useMemberships, k as useOrganization, aA as usePasskey, $ as useResolvedSdkBranding, J as useReturnTo, an as useReverification, g as useSession, o as useSessionList, d as useT, e as useUser } from './index-RNqwEcmY.js';
+export { I as IQAuthLocaleBundle, a as IQAuthLocaleKey, b as IQAuthLocaleOverride } from './types-DnU2LhXR.js';
 import 'csstype';
 import 'react/jsx-runtime';
 import 'react';
-import './signIn-BLFnz8SV.js';
+import './signIn-Cfa1GTpO.js';
 import './publishableKey-f2kq-rKw.js';
-import './types-XOV9XPVi.js';
+import './types-Bn8O-OEd.js';
 
 /**
  * F4 — return-to URL handling.