@iqauth/sdk 2.7.0 → 2.8.1

package/dist/index.d.ts

@@ -1,14 +1,14 @@
-export { j as ApiKeysModule, g as AppsModule, A as AuthModule, B as BrandingModule, m as ClientsModule, C as CreateAppRequest, h as CreateAppResponse, E as EntitlementsModule, G as GdprModule, H as HierarchyModule, I as IQAuthClient, a as InMemoryOidcStateStore, k as InvitesModule, M as MembershipsModule, p as MfaModule, d as OidcAuthRequest, e as OidcCallbackResult, O as OidcModule, f as OidcModuleOptions, b as OidcStateStore, c as OidcStoredRequest, i as PermissionGroupsModule, P as PermissionsModule, o as PinModule, R as RolesModule, n as ScopeModule, S as SessionsModule, l as SourcesModule, T as TenantsModule, U as UsersModule, V as VendorsModule, W as WebhooksModule } from './client-CDQ21LvW.js';
+export { j as ApiKeysModule, g as AppsModule, A as AuthModule, B as BrandingModule, m as ClientsModule, C as CreateAppRequest, h as CreateAppResponse, E as EntitlementsModule, G as GdprModule, H as HierarchyModule, I as IQAuthClient, a as InMemoryOidcStateStore, k as InvitesModule, M as MembershipsModule, p as MfaModule, d as OidcAuthRequest, e as OidcCallbackResult, O as OidcModule, f as OidcModuleOptions, b as OidcStateStore, c as OidcStoredRequest, i as PermissionGroupsModule, P as PermissionsModule, o as PinModule, R as RolesModule, n as ScopeModule, S as SessionsModule, l as SourcesModule, T as TenantsModule, U as UsersModule, V as VendorsModule, W as WebhooksModule } from './client-DkPL0EPZ.js';
 export { b as ErrorCode, E as ErrorCodes, I as IQAuthError, c as IQAuthErrorCode, a as IQ_AUTH_ERROR_CODES } from './errors-Jl1Jtm-6.js';
-export { i as iqAuthMiddleware } from './express-Piv2WhWM.js';
-export { b as DEFAULT_CLOCK_TOLERANCE_SECONDS, a as DEFAULT_TOKEN_AUDIENCE, D as DEFAULT_TOKEN_ISSUER, c as TokenVerifyOptions, T as TokensModule, d as TokensModuleOptions } from './tokens-Bqhmqq_R.js';
+export { i as iqAuthMiddleware } from './express-Budysq4h.js';
+export { b as DEFAULT_CLOCK_TOLERANCE_SECONDS, a as DEFAULT_TOKEN_AUDIENCE, D as DEFAULT_TOKEN_ISSUER, c as TokenVerifyOptions, T as TokensModule, d as TokensModuleOptions } from './tokens-9F6ETrzk.js';
 export { K as KeyMode, c as ParsedPublishableKey, P as PublishableKeyPayload, a as assertPublishableKey, e as encodePublishableKey, i as isPublishableKey, b as isSecretKey, p as parsePublishableKey } from './publishableKey-f2kq-rKw.js';
 export { UserinfoResponse, buildUserinfoResponse, handleUserinfo } from './server/handlers.js';
 export { VerifyWsUpgradeOptions, VerifyWsUpgradeResult, WsUpgradeRequestLike, verifyWsUpgrade } from './ws.js';
 export { CreateTestIssuerOptions, MintAuthCodeOptions, MintTokenOptions, TestIssuer, createTestIssuer } from './test.js';
-export { ap as AcceptInviteRequest, ac as AddGroupPermissionRequest, af as AddUserOverrideRequest, D as ApiErrorResponse, ai as ApiKeyInfo, al as ApiKeyIntrospection, E as ApiResponse, A as ApiSuccessResponse, a0 as AppInfo, $ as AppManifest, a2 as AppSyncResult, a6 as AssignRoleRequest, aO as AvailableScopesTree, b0 as BackupCodeCountResult, a$ as BackupCodesResult, u as BrandingAsset, B as BrandingConfig, w as BrandingDomainMapping, aD as Client, aj as CreateApiKeyRequest, ak as CreateApiKeyResult, aE as CreateClientRequest, an as CreateInviteRequest, aL as CreateMembershipRequest, a4 as CreateRoleRequest, aB as CreateSourceRequest, C as CreateTenantRequest, ay as CreateVendorRequest, ar as CreateWebhookRequest, as as CreateWebhookResult, ag as EffectivePermission, a_ as EmailEnrollResult, av as Entitlement, X as ExpressMiddlewareOptions, aT as GdprExportData, aw as GrantEntitlementRequest, ab as GroupPermission, aI as HierarchyClient, aJ as HierarchyLink, aH as HierarchySource, aG as HierarchyVendor, i as IQAuthBaseClaims, I as IQAuthBrowserSessionClientConfig, h as IQAuthClaims, e as IQAuthClientConfig, d as IQAuthEnvironment, c as IQAuthNextFunction, a as IQAuthRequestLike, b as IQAuthResponseLike, Y as IQAuthRetryConfig, f as IQAuthTokenClientConfig, Z as IQAuthVerifyConfig, ad as InheritanceRelation, am as Invitation, q as InviteTenantUserRequest, r as InviteTenantUserResult, ao as InviteValidation, x as JwksKey, y as JwksResponse, J as JwtClaims, L as LoginResult, aK as Membership, aN as MembershipWithDetails, aW as MfaAvailableMethods, G as MfaEnrollment, F as MfaMethod, Q as MfaPolicy, K as MfaVerifyResult, M as MigrateUserRequest, O as OidcDiscovery, z as OidcTokenResponse, N as PasswordPolicy, ah as PermissionCheckResult, aa as PermissionGroup, a1 as PermissionNodeInfo, _ as PermissionNodeManifest, aV as PinLoginResult, aU as PinStatus, P as PromoteToVendorRequest, p as PromoteToVendorResult, V as ProvisionUserRequest, W as ProvisionUserResponse, a3 as Role, g as ScopeContext, aS as ScopeSwitchResult, aP as ScopeTreeClient, aQ as ScopeTreeSource, aR as ScopeTreeVendor, m as Session, l as SessionAuthenticatedLoginResult, S as SessionUser, aZ as SmsEnrollResult, aA as Source, j as Tenant, n as TenantInfo, a9 as TenantUser, s as TenantUserRoleUpdate, k as TokenAuthenticatedLoginResult, T as TokenPair, aX as TotpEnrollResult, H as TotpEnrollmentResult, aY as TotpVerifyResult, t as UpdateBrandingRequest, aF as UpdateClientRequest, aM as UpdateMembershipRequest, a5 as UpdateRoleRequest, aC as UpdateSourceRequest, o as UpdateTenantRequest, az as UpdateVendorRequest, v as UploadAssetRequest, a8 as UserGroupAssignment, ae as UserPermissionOverride, R as UserPermissions, U as UserProfile, a7 as UserRoleAssignment, ax as Vendor, at as WebhookDelivery, aq as WebhookEndpoint, au as WebhookTestResult } from './types-XOV9XPVi.js';
+export { ap as AcceptInviteRequest, ac as AddGroupPermissionRequest, af as AddUserOverrideRequest, D as ApiErrorResponse, ai as ApiKeyInfo, al as ApiKeyIntrospection, E as ApiResponse, A as ApiSuccessResponse, a0 as AppInfo, $ as AppManifest, a2 as AppSyncResult, a6 as AssignRoleRequest, aO as AvailableScopesTree, b0 as BackupCodeCountResult, a$ as BackupCodesResult, u as BrandingAsset, B as BrandingConfig, w as BrandingDomainMapping, aD as Client, aj as CreateApiKeyRequest, ak as CreateApiKeyResult, aE as CreateClientRequest, an as CreateInviteRequest, aL as CreateMembershipRequest, a4 as CreateRoleRequest, aB as CreateSourceRequest, C as CreateTenantRequest, ay as CreateVendorRequest, ar as CreateWebhookRequest, as as CreateWebhookResult, ag as EffectivePermission, a_ as EmailEnrollResult, av as Entitlement, X as ExpressMiddlewareOptions, aT as GdprExportData, aw as GrantEntitlementRequest, ab as GroupPermission, aI as HierarchyClient, aJ as HierarchyLink, aH as HierarchySource, aG as HierarchyVendor, i as IQAuthBaseClaims, I as IQAuthBrowserSessionClientConfig, h as IQAuthClaims, e as IQAuthClientConfig, d as IQAuthEnvironment, c as IQAuthNextFunction, a as IQAuthRequestLike, b as IQAuthResponseLike, Y as IQAuthRetryConfig, f as IQAuthTokenClientConfig, Z as IQAuthVerifyConfig, ad as InheritanceRelation, am as Invitation, q as InviteTenantUserRequest, r as InviteTenantUserResult, ao as InviteValidation, x as JwksKey, y as JwksResponse, J as JwtClaims, L as LoginResult, aK as Membership, aN as MembershipWithDetails, aW as MfaAvailableMethods, G as MfaEnrollment, F as MfaMethod, Q as MfaPolicy, K as MfaVerifyResult, M as MigrateUserRequest, O as OidcDiscovery, z as OidcTokenResponse, N as PasswordPolicy, ah as PermissionCheckResult, aa as PermissionGroup, a1 as PermissionNodeInfo, _ as PermissionNodeManifest, aV as PinLoginResult, aU as PinStatus, P as PromoteToVendorRequest, p as PromoteToVendorResult, V as ProvisionUserRequest, W as ProvisionUserResponse, a3 as Role, g as ScopeContext, aS as ScopeSwitchResult, aP as ScopeTreeClient, aQ as ScopeTreeSource, aR as ScopeTreeVendor, m as Session, l as SessionAuthenticatedLoginResult, S as SessionUser, aZ as SmsEnrollResult, aA as Source, j as Tenant, n as TenantInfo, a9 as TenantUser, s as TenantUserRoleUpdate, k as TokenAuthenticatedLoginResult, T as TokenPair, aX as TotpEnrollResult, H as TotpEnrollmentResult, aY as TotpVerifyResult, t as UpdateBrandingRequest, aF as UpdateClientRequest, aM as UpdateMembershipRequest, a5 as UpdateRoleRequest, aC as UpdateSourceRequest, o as UpdateTenantRequest, az as UpdateVendorRequest, v as UploadAssetRequest, a8 as UserGroupAssignment, ae as UserPermissionOverride, R as UserPermissions, U as UserProfile, a7 as UserRoleAssignment, ax as Vendor, at as WebhookDelivery, aq as WebhookEndpoint, au as WebhookTestResult } from './types-Bn8O-OEd.js';
 export { IQAUTH_SIGNATURE_HEADER, IQAuthEvent, IQAuthWebhookEvent, LEGACY_SIGNATURE_HEADERS, ParseWebhookEventOptions, VerifyWebhookOptions, WebhookSignatureError, isValidWebhookSignature, parseWebhookEvent, verifyWebhookSignature } from './webhooks.js';
-export { P as ProvisioningBridge, a as ProvisioningBridgeOptions, d as ProvisioningContext, b as ProvisioningStorage, c as createProvisioningBridge } from './provisioningBridge-CGpMRie4.js';
+export { P as ProvisioningBridge, a as ProvisioningBridgeOptions, d as ProvisioningContext, b as ProvisioningStorage, c as createProvisioningBridge } from './provisioningBridge-BXPMZCLe.js';
 
 /**
  * Shared wildcard permission utilities.

package/dist/index.js

@@ -393,17 +393,27 @@ function parseLoginResponse(data, browserSessionMode) {
       tenants: data.tenants
     };
   }
+  if (data.type === "scope_selection" && data.scopeSelectionToken && data.scopes && data.tenantId) {
+    return {
+      status: "scope_selection",
+      scopeSelectionToken: data.scopeSelectionToken,
+      tenantId: data.tenantId,
+      scopes: data.scopes
+    };
+  }
   throw new Error("Unexpected login response shape");
 }
 var AuthModule = class {
   constructor(http) {
     this.http = http;
   }
-  async login(email, password) {
+  async login(email, password, opts) {
+    const body = { email, password };
+    if (opts?.scopeHint) body.scopeHint = opts.scopeHint;
     const data = await this.http.request(
       "POST",
       "/api/v1/auth/login",
-      { email, password },
+      body,
       { skipAutoRefresh: true }
     );
     return parseLoginResponse(data, this.http.isBrowserSession());
@@ -441,13 +451,29 @@ var AuthModule = class {
       method
     }, { skipAutoRefresh: true });
   }
-  async selectTenant(tenantSelectionToken, tenantId) {
+  async selectTenant(tenantSelectionToken, tenantId, opts) {
+    const body = { tenantSelectionToken, tenantId };
+    if (opts?.scopeHint) body.scopeHint = opts.scopeHint;
     const data = await this.http.request(
       "POST",
       "/api/v1/auth/select-tenant",
+      body,
+      { skipAutoRefresh: true }
+    );
+    return parseLoginResponse(data, this.http.isBrowserSession());
+  }
+  /**
+   * Task #171 — redeem a scope-selection token + chosen membership for a
+   * real authenticated session. `membershipId` must be one of the scopes
+   * returned in the prior `scope_selection` envelope.
+   */
+  async selectScope(scopeSelectionToken, membershipId) {
+    const data = await this.http.request(
+      "POST",
+      "/api/v1/auth/select-scope",
       {
-        tenantSelectionToken,
-        tenantId
+        scopeSelectionToken,
+        membershipId
       },
       { skipAutoRefresh: true }
     );
@@ -2321,7 +2347,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;
@@ -2336,19 +2366,62 @@ async function buildUserinfoResponse(claims, opts = {}) {
 }
 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",
@@ -2361,7 +2434,9 @@ 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"
   };
 }
 var DEFAULT_SIGNOUT_TTL_MS = 6e4;
@@ -2389,6 +2464,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."
+  );
+}
 var TOKENS_CACHE = /* @__PURE__ */ new Map();
 function getTokensFor(issuer) {
   let m = TOKENS_CACHE.get(issuer);
@@ -2409,7 +2493,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";
@@ -2890,12 +2977,8 @@ function verifyWebhookSignature(opts) {
   }
   const body = toBuffer(opts.payload);
   const { modern, legacy } = computeSignatures(opts.secret, body, t);
-  const matched = v1.some((sig) => {
-    const lower = sig.toLowerCase();
-    if (timingSafeEqualHex(lower, modern)) return true;
-    if (legacy && timingSafeEqualHex(lower, legacy)) return true;
-    return false;
-  });
+  const expected = Number.isFinite(t) ? legacy : modern;
+  const matched = expected !== null && v1.some((sig) => timingSafeEqualHex(sig.toLowerCase(), expected));
   if (!matched) {
     throw new WebhookSignatureError("SIGNATURE_MISMATCH", "Webhook signature does not match expected value");
   }
@@ -2905,6 +2988,29 @@ function verifyWebhookSignature(opts) {
   } catch {
     throw new WebhookSignatureError("MALFORMED_BODY", "Webhook body is not valid JSON");
   }
+  if (!Number.isFinite(t) && !opts.allowMissingTimestamp) {
+    const rawTime = parsed.time;
+    if (typeof rawTime !== "string" || !rawTime) {
+      throw new WebhookSignatureError(
+        "MISSING_TIMESTAMP",
+        "Modern webhook delivery has no header `t=` and no envelope `time`; cannot enforce replay protection. Use parseWebhookEvent, or set allowMissingTimestamp:true (insecure)."
+      );
+    }
+    const eventMs = Date.parse(rawTime);
+    if (!Number.isFinite(eventMs)) {
+      throw new WebhookSignatureError(
+        "MALFORMED_TIMESTAMP",
+        `Envelope \`time\` is not a valid ISO timestamp: ${rawTime}`
+      );
+    }
+    const nowMs = (opts.nowSeconds ?? Math.floor(Date.now() / 1e3)) * 1e3;
+    if (Math.abs(nowMs - eventMs) > tolerance * 1e3) {
+      throw new WebhookSignatureError(
+        "TIMESTAMP_OUT_OF_TOLERANCE",
+        `Envelope time ${rawTime} is outside the ${tolerance}s tolerance window`
+      );
+    }
+  }
   return parsed;
 }
 function isValidWebhookSignature(opts) {
@@ -2974,12 +3080,8 @@ function parseWebhookEvent(rawBody, headers, secrets, opts = {}) {
     const secret = secrets[i];
     if (!secret) continue;
     const { modern, legacy } = computeSignatures(secret, body, t);
-    const ok = v1.some((sig) => {
-      const lower = sig.toLowerCase();
-      if (timingSafeEqualHex(lower, modern)) return true;
-      if (legacy && timingSafeEqualHex(lower, legacy)) return true;
-      return false;
-    });
+    const expected = Number.isFinite(t) ? legacy : modern;
+    const ok = expected !== null && v1.some((sig) => timingSafeEqualHex(sig.toLowerCase(), expected));
     if (ok) {
       verifiedIdx = i;
       break;
@@ -3036,6 +3138,13 @@ function parseWebhookEvent(rawBody, headers, secrets, opts = {}) {
 }
 
 // src/server/provisioningBridge.ts
+var ProvisioningError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "ProvisioningError";
+    this.code = code;
+  }
+};
 function defaultIsUniqueViolation(err) {
   if (!err || typeof err !== "object") return false;
   const e = err;
@@ -3047,6 +3156,16 @@ function defaultIsUniqueViolation(err) {
 function createProvisioningBridge(options) {
   const { storage } = options;
   const isUniqueViolation = options.isUniqueViolation ?? defaultIsUniqueViolation;
+  const allowUnverifiedEmailAdopt = options.allowUnverifiedEmailAdopt === true;
+  const emailVerified = (claims) => claims.email_verified === true;
+  const assertAdoptAllowed = (claims) => {
+    if (!allowUnverifiedEmailAdopt && !emailVerified(claims)) {
+      throw new ProvisioningError(
+        "UNVERIFIED_EMAIL_ADOPT_REFUSED",
+        "Refusing to adopt a pre-existing local account from an unverified email (claims.email_verified !== true). Set allowUnverifiedEmailAdopt:true only if your issuer is trusted to never emit unverified emails for adoption."
+      );
+    }
+  };
   const roleOf = (claims) => {
     try {
       return options.roleMapper?.(claims) ?? null;
@@ -3063,6 +3182,7 @@ function createProvisioningBridge(options) {
     if (claims.email) {
       const byEmail = await storage.findByEmail(claims.email);
       if (byEmail) {
+        assertAdoptAllowed(claims);
         if (storage.adoptByEmail) {
           const adopted = await storage.adoptByEmail(byEmail, claims, roleOf(claims));
           return { user: adopted, claims, created: false, adopted: true };
@@ -3078,7 +3198,10 @@ function createProvisioningBridge(options) {
       if (after) return { user: after, claims, created: false, adopted: false };
       if (claims.email) {
         const byEmail = await storage.findByEmail(claims.email);
-        if (byEmail) return { user: byEmail, claims, created: false, adopted: true };
+        if (byEmail) {
+          assertAdoptAllowed(claims);
+          return { user: byEmail, claims, created: false, adopted: true };
+        }
       }
       throw err;
     }

package/dist/index.mjs

@@ -4,7 +4,7 @@ import {
 } from "./chunk-GLXSIGVS.mjs";
 import {
   createProvisioningBridge
-} from "./chunk-SL3KRS4W.mjs";
+} from "./chunk-CIJORODR.mjs";
 import {
   createTestIssuer
 } from "./chunk-WIFG74IK.mjs";
@@ -15,17 +15,17 @@ import {
   isValidWebhookSignature,
   parseWebhookEvent,
   verifyWebhookSignature
-} from "./chunk-PMAFENVI.mjs";
+} from "./chunk-VYQ3ETCK.mjs";
 import {
   verifyWsUpgrade
 } from "./chunk-WCELYTJ3.mjs";
 import {
   iqAuthMiddleware
-} from "./chunk-YVALAG3B.mjs";
+} from "./chunk-25SSYDIP.mjs";
 import {
   buildUserinfoResponse,
   handleUserinfo
-} from "./chunk-RUJXRTEW.mjs";
+} from "./chunk-WSH4SW7F.mjs";
 import {
   assertPublishableKey,
   encodePublishableKey,
@@ -59,7 +59,7 @@ import {
   UsersModule,
   VendorsModule,
   WebhooksModule
-} from "./chunk-JXQI62A7.mjs";
+} from "./chunk-ZLJPABB7.mjs";
 import {
   DEFAULT_CLOCK_TOLERANCE_SECONDS,
   DEFAULT_TOKEN_AUDIENCE,

package/dist/locales.d.mts

@@ -1,4 +1,4 @@
-import { I as IQAuthLocaleBundle, b as IQAuthLocaleOverride, a as IQAuthLocaleKey } from './types-BdQ2lqfT.mjs';
+import { I as IQAuthLocaleBundle, b as IQAuthLocaleOverride, a as IQAuthLocaleKey } from './types-DnU2LhXR.mjs';
 
 declare const enUS: IQAuthLocaleBundle;
 

package/dist/locales.d.ts

@@ -1,4 +1,4 @@
-import { I as IQAuthLocaleBundle, b as IQAuthLocaleOverride, a as IQAuthLocaleKey } from './types-BdQ2lqfT.js';
+import { I as IQAuthLocaleBundle, b as IQAuthLocaleOverride, a as IQAuthLocaleKey } from './types-DnU2LhXR.js';
 
 declare const enUS: IQAuthLocaleBundle;
 

package/dist/locales.js

@@ -74,6 +74,7 @@ var enUS = {
   "signIn.useDifferentAccount": "Use a different account",
   "signIn.selectTenant": "Choose an organization",
   "signIn.selectTenantSubtitle": "You belong to multiple organizations. Pick one to continue.",
+  "signIn.selectScope": "Choose scope",
   "signIn.dividerOr": "or",
   "signIn.preparingExperience": "Preparing your sign-in experience.",
   "signIn.applicationUnavailable": "Application unavailable",
@@ -162,6 +163,11 @@ var enUS = {
   "orgSwitcher.createNew": "Create organization",
   "orgSwitcher.manage": "Manage organization",
   "orgSwitcher.noOrgs": "You don't belong to any organizations yet.",
+  "orgSwitcher.mfaRequiredTitle": "Two-factor verification required",
+  "orgSwitcher.mfaRequiredBody": "This organization requires an extra verification step. Continue in the hosted sign-in to finish switching.",
+  "orgSwitcher.scopeSelectionRequiredTitle": "Choose what to access",
+  "orgSwitcher.scopeSelectionRequiredBody": "This organization needs you to pick which workspace to open. Continue in the hosted sign-in to choose.",
+  "orgSwitcher.continueInHostedSignIn": "Continue in hosted sign-in \u2192",
   "orgProfile.title": "Organization settings",
   "orgProfile.generalTab": "General",
   "orgProfile.membersTab": "Members",
@@ -254,6 +260,7 @@ var frFR = {
   "signIn.useDifferentAccount": "Utiliser un autre compte",
   "signIn.selectTenant": "Choisir une organisation",
   "signIn.selectTenantSubtitle": "Vous appartenez \xE0 plusieurs organisations. Choisissez-en une pour continuer.",
+  "signIn.selectScope": "Choisir une port\xE9e",
   "signIn.dividerOr": "ou",
   "signIn.preparingExperience": "Pr\xE9paration de votre exp\xE9rience de connexion.",
   "signIn.applicationUnavailable": "Application indisponible",
@@ -342,6 +349,11 @@ var frFR = {
   "orgSwitcher.createNew": "Cr\xE9er une organisation",
   "orgSwitcher.manage": "G\xE9rer l'organisation",
   "orgSwitcher.noOrgs": "Vous n'appartenez encore \xE0 aucune organisation.",
+  "orgSwitcher.mfaRequiredTitle": "V\xE9rification en deux \xE9tapes requise",
+  "orgSwitcher.mfaRequiredBody": "Cette organisation n\xE9cessite une \xE9tape de v\xE9rification suppl\xE9mentaire. Poursuivez sur la page de connexion h\xE9berg\xE9e pour terminer le changement.",
+  "orgSwitcher.scopeSelectionRequiredTitle": "Choisir l'espace \xE0 ouvrir",
+  "orgSwitcher.scopeSelectionRequiredBody": "Cette organisation n\xE9cessite que vous choisissiez un espace de travail. Poursuivez sur la page de connexion h\xE9berg\xE9e pour choisir.",
+  "orgSwitcher.continueInHostedSignIn": "Continuer sur la connexion h\xE9berg\xE9e \u2192",
   "orgProfile.title": "Param\xE8tres de l'organisation",
   "orgProfile.generalTab": "G\xE9n\xE9ral",
   "orgProfile.membersTab": "Membres",
@@ -434,6 +446,7 @@ var esES = {
   "signIn.useDifferentAccount": "Usar otra cuenta",
   "signIn.selectTenant": "Elige una organizaci\xF3n",
   "signIn.selectTenantSubtitle": "Perteneces a varias organizaciones. Selecciona una para continuar.",
+  "signIn.selectScope": "Elegir \xE1mbito",
   "signIn.dividerOr": "o",
   "signIn.preparingExperience": "Preparando tu experiencia de inicio de sesi\xF3n.",
   "signIn.applicationUnavailable": "Aplicaci\xF3n no disponible",
@@ -522,6 +535,11 @@ var esES = {
   "orgSwitcher.createNew": "Crear organizaci\xF3n",
   "orgSwitcher.manage": "Gestionar organizaci\xF3n",
   "orgSwitcher.noOrgs": "A\xFAn no perteneces a ninguna organizaci\xF3n.",
+  "orgSwitcher.mfaRequiredTitle": "Se requiere verificaci\xF3n en dos pasos",
+  "orgSwitcher.mfaRequiredBody": "Esta organizaci\xF3n requiere un paso de verificaci\xF3n adicional. Contin\xFAa en el inicio de sesi\xF3n alojado para completar el cambio.",
+  "orgSwitcher.scopeSelectionRequiredTitle": "Elige a qu\xE9 acceder",
+  "orgSwitcher.scopeSelectionRequiredBody": "Esta organizaci\xF3n requiere que elijas un espacio de trabajo. Contin\xFAa en el inicio de sesi\xF3n alojado para elegir.",
+  "orgSwitcher.continueInHostedSignIn": "Continuar en el inicio de sesi\xF3n alojado \u2192",
   "orgProfile.title": "Configuraci\xF3n de la organizaci\xF3n",
   "orgProfile.generalTab": "Generales",
   "orgProfile.membersTab": "Miembros",
@@ -614,6 +632,7 @@ var deDE = {
   "signIn.useDifferentAccount": "Anderes Konto verwenden",
   "signIn.selectTenant": "Organisation ausw\xE4hlen",
   "signIn.selectTenantSubtitle": "Sie geh\xF6ren zu mehreren Organisationen. Bitte w\xE4hlen Sie eine aus.",
+  "signIn.selectScope": "Bereich ausw\xE4hlen",
   "signIn.preparingExperience": "Anmeldung wird vorbereitet.",
   "signIn.applicationUnavailable": "Anwendung nicht verf\xFCgbar",
   "signIn.applicationNotFound": "Anwendung nicht gefunden",
@@ -702,6 +721,11 @@ var deDE = {
   "orgSwitcher.createNew": "Organisation erstellen",
   "orgSwitcher.manage": "Organisation verwalten",
   "orgSwitcher.noOrgs": "Sie geh\xF6ren noch keiner Organisation an.",
+  "orgSwitcher.mfaRequiredTitle": "Zwei-Faktor-Verifizierung erforderlich",
+  "orgSwitcher.mfaRequiredBody": "Diese Organisation erfordert einen zus\xE4tzlichen Verifizierungsschritt. Fahren Sie in der gehosteten Anmeldung fort, um den Wechsel abzuschlie\xDFen.",
+  "orgSwitcher.scopeSelectionRequiredTitle": "Zugriff ausw\xE4hlen",
+  "orgSwitcher.scopeSelectionRequiredBody": "F\xFCr diese Organisation m\xFCssen Sie einen Arbeitsbereich ausw\xE4hlen. Fahren Sie in der gehosteten Anmeldung fort, um auszuw\xE4hlen.",
+  "orgSwitcher.continueInHostedSignIn": "In der gehosteten Anmeldung fortfahren \u2192",
   "orgProfile.title": "Organisationseinstellungen",
   "orgProfile.generalTab": "Allgemein",
   "orgProfile.membersTab": "Mitglieder",
@@ -794,6 +818,7 @@ var jaJP = {
   "signIn.useDifferentAccount": "\u5225\u306E\u30A2\u30AB\u30A6\u30F3\u30C8\u3092\u4F7F\u7528",
   "signIn.selectTenant": "\u7D44\u7E54\u3092\u9078\u629E",
   "signIn.selectTenantSubtitle": "\u8907\u6570\u306E\u7D44\u7E54\u306B\u6240\u5C5E\u3057\u3066\u3044\u307E\u3059\u3002\u7D9A\u3051\u308B\u306B\u306F 1 \u3064\u3092\u9078\u629E\u3057\u3066\u304F\u3060\u3055\u3044\u3002",
+  "signIn.selectScope": "\u30B9\u30B3\u30FC\u30D7\u3092\u9078\u629E",
   "signIn.preparingExperience": "\u30B5\u30A4\u30F3\u30A4\u30F3\u306E\u6E96\u5099\u3092\u3057\u3066\u3044\u307E\u3059\u3002",
   "signIn.applicationUnavailable": "\u30A2\u30D7\u30EA\u30B1\u30FC\u30B7\u30E7\u30F3\u3092\u5229\u7528\u3067\u304D\u307E\u305B\u3093",
   "signIn.applicationNotFound": "\u30A2\u30D7\u30EA\u30B1\u30FC\u30B7\u30E7\u30F3\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093",
@@ -882,6 +907,11 @@ var jaJP = {
   "orgSwitcher.createNew": "\u7D44\u7E54\u3092\u4F5C\u6210",
   "orgSwitcher.manage": "\u7D44\u7E54\u3092\u7BA1\u7406",
   "orgSwitcher.noOrgs": "\u307E\u3060\u3069\u306E\u7D44\u7E54\u306B\u3082\u6240\u5C5E\u3057\u3066\u3044\u307E\u305B\u3093\u3002",
+  "orgSwitcher.mfaRequiredTitle": "\u4E8C\u6BB5\u968E\u8A8D\u8A3C\u304C\u5FC5\u8981\u3067\u3059",
+  "orgSwitcher.mfaRequiredBody": "\u3053\u306E\u7D44\u7E54\u3067\u306F\u8FFD\u52A0\u306E\u672C\u4EBA\u78BA\u8A8D\u304C\u5FC5\u8981\u3067\u3059\u3002\u30DB\u30B9\u30C8\u3055\u308C\u305F\u30B5\u30A4\u30F3\u30A4\u30F3\u3067\u7D9A\u3051\u3066\u5207\u308A\u66FF\u3048\u3092\u5B8C\u4E86\u3057\u3066\u304F\u3060\u3055\u3044\u3002",
+  "orgSwitcher.scopeSelectionRequiredTitle": "\u30A2\u30AF\u30BB\u30B9\u5148\u3092\u9078\u629E",
+  "orgSwitcher.scopeSelectionRequiredBody": "\u3053\u306E\u7D44\u7E54\u3067\u306F\u30EF\u30FC\u30AF\u30B9\u30DA\u30FC\u30B9\u306E\u9078\u629E\u304C\u5FC5\u8981\u3067\u3059\u3002\u30DB\u30B9\u30C8\u3055\u308C\u305F\u30B5\u30A4\u30F3\u30A4\u30F3\u3067\u9078\u629E\u3057\u3066\u304F\u3060\u3055\u3044\u3002",
+  "orgSwitcher.continueInHostedSignIn": "\u30DB\u30B9\u30C8\u3055\u308C\u305F\u30B5\u30A4\u30F3\u30A4\u30F3\u306B\u9032\u3080 \u2192",
   "orgProfile.title": "\u7D44\u7E54\u306E\u8A2D\u5B9A",
   "orgProfile.generalTab": "\u4E00\u822C",
   "orgProfile.membersTab": "\u30E1\u30F3\u30D0\u30FC",
@@ -974,6 +1004,7 @@ var ptBR = {
   "signIn.useDifferentAccount": "Usar outra conta",
   "signIn.selectTenant": "Escolher uma organiza\xE7\xE3o",
   "signIn.selectTenantSubtitle": "Voc\xEA pertence a v\xE1rias organiza\xE7\xF5es. Escolha uma para continuar.",
+  "signIn.selectScope": "Escolher escopo",
   "signIn.preparingExperience": "Preparando sua experi\xEAncia de login.",
   "signIn.applicationUnavailable": "Aplicativo indispon\xEDvel",
   "signIn.applicationNotFound": "Aplicativo n\xE3o encontrado",
@@ -1061,6 +1092,11 @@ var ptBR = {
   "orgSwitcher.personal": "Conta pessoal",
   "orgSwitcher.createNew": "Criar organiza\xE7\xE3o",
   "orgSwitcher.manage": "Gerenciar organiza\xE7\xE3o",
+  "orgSwitcher.mfaRequiredTitle": "Verifica\xE7\xE3o em duas etapas necess\xE1ria",
+  "orgSwitcher.mfaRequiredBody": "Esta organiza\xE7\xE3o requer uma etapa de verifica\xE7\xE3o adicional. Continue no login hospedado para concluir a troca.",
+  "orgSwitcher.scopeSelectionRequiredTitle": "Escolha o que acessar",
+  "orgSwitcher.scopeSelectionRequiredBody": "Esta organiza\xE7\xE3o exige que voc\xEA escolha um espa\xE7o de trabalho. Continue no login hospedado para escolher.",
+  "orgSwitcher.continueInHostedSignIn": "Continuar no login hospedado \u2192",
   "orgSwitcher.noOrgs": "Voc\xEA ainda n\xE3o pertence a nenhuma organiza\xE7\xE3o.",
   "orgProfile.title": "Configura\xE7\xF5es da organiza\xE7\xE3o",
   "orgProfile.generalTab": "Geral",

package/dist/locales.mjs

@@ -11,7 +11,7 @@ import {
   ptBR,
   resolveBundle,
   t
-} from "./chunk-5T7GHBX6.mjs";
+} from "./chunk-TLET552H.mjs";
 import "./chunk-Y6FXYEAI.mjs";
 export {
   builtInLocales,

package/dist/mobile.d.mts

@@ -1,7 +1,7 @@
-import { I as IQAuthClient } from './client-BGFnBpfc.mjs';
-import { f as IQAuthTokenClientConfig } from './types-XOV9XPVi.mjs';
+import { I as IQAuthClient } from './client-D8L-PaWr.mjs';
+import { f as IQAuthTokenClientConfig } from './types-Bn8O-OEd.mjs';
 export { E as ErrorCodes, I as IQAuthError } from './errors-Jl1Jtm-6.mjs';
-import './tokens-CITeoG6P.mjs';
+import './tokens-B06VtvUi.mjs';
 
 /**
  * Mobile client — wraps IQAuthClient with React Native / Expo–aware behavior.

package/dist/mobile.d.ts

@@ -1,7 +1,7 @@
-import { I as IQAuthClient } from './client-CDQ21LvW.js';
-import { f as IQAuthTokenClientConfig } from './types-XOV9XPVi.js';
+import { I as IQAuthClient } from './client-DkPL0EPZ.js';
+import { f as IQAuthTokenClientConfig } from './types-Bn8O-OEd.js';
 export { E as ErrorCodes, I as IQAuthError } from './errors-Jl1Jtm-6.js';
-import './tokens-Bqhmqq_R.js';
+import './tokens-9F6ETrzk.js';
 
 /**
  * Mobile client — wraps IQAuthClient with React Native / Expo–aware behavior.

package/dist/mobile.js

@@ -335,17 +335,27 @@ function parseLoginResponse(data, browserSessionMode) {
       tenants: data.tenants
     };
   }
+  if (data.type === "scope_selection" && data.scopeSelectionToken && data.scopes && data.tenantId) {
+    return {
+      status: "scope_selection",
+      scopeSelectionToken: data.scopeSelectionToken,
+      tenantId: data.tenantId,
+      scopes: data.scopes
+    };
+  }
   throw new Error("Unexpected login response shape");
 }
 var AuthModule = class {
   constructor(http) {
     this.http = http;
   }
-  async login(email, password) {
+  async login(email, password, opts) {
+    const body = { email, password };
+    if (opts?.scopeHint) body.scopeHint = opts.scopeHint;
     const data = await this.http.request(
       "POST",
       "/api/v1/auth/login",
-      { email, password },
+      body,
       { skipAutoRefresh: true }
     );
     return parseLoginResponse(data, this.http.isBrowserSession());
@@ -383,13 +393,29 @@ var AuthModule = class {
       method
     }, { skipAutoRefresh: true });
   }
-  async selectTenant(tenantSelectionToken, tenantId) {
+  async selectTenant(tenantSelectionToken, tenantId, opts) {
+    const body = { tenantSelectionToken, tenantId };
+    if (opts?.scopeHint) body.scopeHint = opts.scopeHint;
     const data = await this.http.request(
       "POST",
       "/api/v1/auth/select-tenant",
+      body,
+      { skipAutoRefresh: true }
+    );
+    return parseLoginResponse(data, this.http.isBrowserSession());
+  }
+  /**
+   * Task #171 — redeem a scope-selection token + chosen membership for a
+   * real authenticated session. `membershipId` must be one of the scopes
+   * returned in the prior `scope_selection` envelope.
+   */
+  async selectScope(scopeSelectionToken, membershipId) {
+    const data = await this.http.request(
+      "POST",
+      "/api/v1/auth/select-scope",
       {
-        tenantSelectionToken,
-        tenantId
+        scopeSelectionToken,
+        membershipId
       },
       { skipAutoRefresh: true }
     );

package/dist/mobile.mjs

@@ -1,6 +1,6 @@
 import {
   IQAuthClient
-} from "./chunk-JXQI62A7.mjs";
+} from "./chunk-ZLJPABB7.mjs";
 import "./chunk-NUO2I65G.mjs";
 import {
   ErrorCodes,

package/dist/next.d.mts

@@ -1,6 +1,6 @@
 import { IQAuthHelperConfig } from './server/handlers.mjs';
-import { J as JwtClaims } from './types-XOV9XPVi.mjs';
-import './tokens-CITeoG6P.mjs';
+import { J as JwtClaims } from './types-Bn8O-OEd.mjs';
+import './tokens-B06VtvUi.mjs';
 
 /**
  * @iqauth/sdk/next — Next.js (App Router) adapter.
@@ -21,6 +21,14 @@ import './tokens-CITeoG6P.mjs';
 interface IQAuthNextOptions extends IQAuthHelperConfig {
     /** Path prefix where the helper routes live. */
     mountPath?: string;
+    /**
+     * Cookie name the browser SDK publishes the post-login destination into
+     * before redirect. The callback handler reads it, surfaces it as `returnTo`
+     * in the JSON response body after a successful exchange, and clears it on
+     * success. Mirrors the express inline-callback adapter. Defaults to
+     * `iqauth_return_to`.
+     */
+    returnToCookieName?: string;
 }
 declare function handler(options: IQAuthNextOptions): (req: Request) => Promise<Response>;
 /**

package/dist/next.d.ts

@@ -1,6 +1,6 @@
 import { IQAuthHelperConfig } from './server/handlers.js';
-import { J as JwtClaims } from './types-XOV9XPVi.js';
-import './tokens-Bqhmqq_R.js';
+import { J as JwtClaims } from './types-Bn8O-OEd.js';
+import './tokens-9F6ETrzk.js';
 
 /**
  * @iqauth/sdk/next — Next.js (App Router) adapter.
@@ -21,6 +21,14 @@ import './tokens-Bqhmqq_R.js';
 interface IQAuthNextOptions extends IQAuthHelperConfig {
     /** Path prefix where the helper routes live. */
     mountPath?: string;
+    /**
+     * Cookie name the browser SDK publishes the post-login destination into
+     * before redirect. The callback handler reads it, surfaces it as `returnTo`
+     * in the JSON response body after a successful exchange, and clears it on
+     * success. Mirrors the express inline-callback adapter. Defaults to
+     * `iqauth_return_to`.
+     */
+    returnToCookieName?: string;
 }
 declare function handler(options: IQAuthNextOptions): (req: Request) => Promise<Response>;
 /**