@iqauth/sdk 2.6.4 → 2.8.1

package/dist/{chunk-W3F4JYGP.mjs → chunk-ZLJPABB7.mjs}

@@ -1,9 +1,9 @@
 import {
   TokensModule
-} from "./chunk-UNYDG2L4.mjs";
+} from "./chunk-NUO2I65G.mjs";
 import {
   IQAuthError
-} from "./chunk-6I6RM4MN.mjs";
+} from "./chunk-6PJRLRB4.mjs";
 
 // src/modules/auth.ts
 function parseLoginResponse(data, browserSessionMode) {
@@ -36,17 +36,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());
@@ -84,13 +94,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 }
     );
@@ -484,14 +510,14 @@ var OidcModule = class {
    */
   async handleCallback(params) {
     if (!params.state) {
-      throw new IQAuthError("VALIDATION_ERROR", "OIDC callback missing state parameter");
+      throw new IQAuthError("config_invalid", "OIDC callback missing state parameter");
     }
     if (!params.code) {
-      throw new IQAuthError("VALIDATION_ERROR", "OIDC callback missing code parameter");
+      throw new IQAuthError("config_invalid", "OIDC callback missing code parameter");
     }
     const stored = await this.stateStore.get(params.state);
     if (!stored) {
-      throw new IQAuthError("VALIDATION_ERROR", "Unknown or expired OIDC state");
+      throw new IQAuthError("config_invalid", "Unknown or expired OIDC state");
     }
     let tokens;
     try {
@@ -509,7 +535,7 @@ var OidcModule = class {
     if (tokens.id_token) {
       if (!this.tokensModule) {
         throw new IQAuthError(
-          "INTERNAL_ERROR",
+          "config_invalid",
           "OIDC handleCallback received an id_token but no TokensModule is configured for verification"
         );
       }
@@ -520,7 +546,7 @@ var OidcModule = class {
       const tokenNonce = typeof claimsBag.nonce === "string" ? claimsBag.nonce : void 0;
       if (!tokenNonce || tokenNonce !== stored.nonce) {
         throw new IQAuthError(
-          "TOKEN_INVALID",
+          "token_invalid",
           "OIDC id_token nonce did not match the stored value"
         );
       }
@@ -721,6 +747,9 @@ var AppsModule = class {
    * @remarks Wraps GET /api/v1/apps/:appKey
    */
   async get(appKey) {
+    if (typeof appKey !== "string" || appKey.trim() === "") {
+      throw new IQAuthError("VALIDATION_ERROR", "appKey is required (no env-var fallback).", 400);
+    }
     return this.http.request("GET", `/api/v1/apps/${encodeURIComponent(appKey)}`);
   }
   /**
@@ -740,6 +769,16 @@ var AppsModule = class {
         401
       );
     }
+    if (!manifest || typeof manifest.key !== "string" || manifest.key.trim() === "") {
+      throw new IQAuthError("VALIDATION_ERROR", "manifest.key (appKey) is required for register().", 400);
+    }
+    if (!manifest.environment || !["production", "staging", "development"].includes(manifest.environment)) {
+      throw new IQAuthError(
+        "ENVIRONMENT_REQUIRED",
+        "manifest.environment is required and must be 'production', 'staging', or 'development'. This guards against a dev workstation silently overwriting a production app's permission tree.",
+        400
+      );
+    }
     return this.http.request("POST", "/api/v1/apps/sync", manifest);
   }
   /**
@@ -749,11 +788,14 @@ var AppsModule = class {
    * @remarks Uses GET /api/v1/apps/:appKey — catches 404 errors
    */
   async isRegistered(appKey) {
+    if (typeof appKey !== "string" || appKey.trim() === "") {
+      throw new IQAuthError("VALIDATION_ERROR", "appKey is required (no env-var fallback).", 400);
+    }
     try {
       await this.get(appKey);
       return true;
     } catch (err) {
-      if (err.code === "NOT_FOUND" || err.status === 404) {
+      if (err.code === "app_not_found" || err.code === "NOT_FOUND" || err.status === 404) {
         return false;
       }
       throw err;
@@ -790,6 +832,20 @@ var RolesModule = class {
 };
 
 // src/modules/permissionGroups.ts
+function assertAppKey(appKey, callsite) {
+  if (typeof appKey !== "string" || appKey.trim() === "") {
+    throw new IQAuthError(
+      "VALIDATION_ERROR",
+      `appKey is required for ${callsite} (no env-var fallback, no 'product' alias).`,
+      400
+    );
+  }
+}
+function assertNodeKey(nodeKey, callsite) {
+  if (typeof nodeKey !== "string" || nodeKey.trim() === "") {
+    throw new IQAuthError("VALIDATION_ERROR", `nodeKey is required for ${callsite}.`, 400);
+  }
+}
 var PermissionGroupsModule = class {
   constructor(http) {
     this.http = http;
@@ -810,7 +866,14 @@ var PermissionGroupsModule = class {
     return this.http.request("GET", `/api/v1/tenants/${tenantId}/permission-groups/${groupId}/permissions`);
   }
   async addPermission(tenantId, groupId, data) {
-    return this.http.request("POST", `/api/v1/tenants/${tenantId}/permission-groups/${groupId}/permissions`, data);
+    assertAppKey(data?.appKey, "permissionGroups.addPermission");
+    assertNodeKey(data?.nodeKey, "permissionGroups.addPermission");
+    return this.http.request("POST", `/api/v1/tenants/${tenantId}/permission-groups/${groupId}/permissions`, {
+      appKey: data.appKey,
+      nodeKey: data.nodeKey,
+      effect: data.effect,
+      weight: data.weight
+    });
   }
   async removePermission(tenantId, groupId, permissionId) {
     return this.http.request("DELETE", `/api/v1/tenants/${tenantId}/permission-groups/${groupId}/permissions/${permissionId}`);
@@ -834,21 +897,51 @@ var PermissionGroupsModule = class {
     return this.http.request("GET", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/overrides`);
   }
   async addUserOverride(tenantId, userId, data) {
-    return this.http.request("POST", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/overrides`, data);
+    assertAppKey(data?.appKey, "permissionGroups.addUserOverride");
+    assertNodeKey(data?.nodeKey, "permissionGroups.addUserOverride");
+    return this.http.request("POST", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/overrides`, {
+      appKey: data.appKey,
+      nodeKey: data.nodeKey,
+      effect: data.effect,
+      weight: data.weight,
+      expiresAt: data.expiresAt
+    });
   }
   async removeUserOverride(tenantId, userId, overrideId) {
     return this.http.request("DELETE", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/overrides/${overrideId}`);
   }
+  /**
+   * Task #130 — `appKey` is REQUIRED. The legacy `product` query alias is no
+   * longer accepted at the SDK boundary; pass it as `appKey` instead. The
+   * server still accepts `product=` from raw HTTP callers during the
+   * deprecation window, but the SDK will not silently translate it.
+   */
   async getEffectivePermissions(tenantId, userId, params) {
-    const query = new URLSearchParams();
-    if (params.product) query.set("product", params.product);
-    if (params.appKey) query.set("appKey", params.appKey);
-    const qs = query.toString();
-    return this.http.request("GET", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/effective${qs ? `?${qs}` : ""}`);
+    assertAppKey(params?.appKey, "permissionGroups.getEffectivePermissions");
+    const qs = new URLSearchParams({ appKey: params.appKey }).toString();
+    return this.http.request("GET", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/effective?${qs}`);
   }
   async checkPermission(tenantId, userId, appKey, nodeKey) {
+    assertAppKey(appKey, "permissionGroups.checkPermission");
+    assertNodeKey(nodeKey, "permissionGroups.checkPermission");
     return this.http.request("POST", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/check`, { appKey, nodeKey });
   }
+  /**
+   * Task #130 — every entry in `checks` must include a non-empty `appKey`
+   * AND `nodeKey`. The SDK validates the whole batch before sending so a
+   * single misconfigured entry can't slip through and silently report
+   * `allowed: false` from the server's per-entry validation branch.
+   */
+  async batchCheckPermissions(tenantId, userId, checks) {
+    if (!Array.isArray(checks) || checks.length === 0) {
+      throw new IQAuthError("VALIDATION_ERROR", "checks must be a non-empty array of { appKey, nodeKey }.", 400);
+    }
+    checks.forEach((c, i) => {
+      assertAppKey(c?.appKey, `permissionGroups.batchCheckPermissions[${i}]`);
+      assertNodeKey(c?.nodeKey, `permissionGroups.batchCheckPermissions[${i}]`);
+    });
+    return this.http.request("POST", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/batch-check`, { checks });
+  }
 };
 
 // src/modules/apiKeys.ts
@@ -1365,7 +1458,7 @@ var HttpClient = class {
           headers: this.buildHeaders(),
           ...this.isBrowserSession() ? { credentials: "include" } : (() => {
             const refreshToken = this.config.getRefreshToken();
-            if (!refreshToken) throw new IQAuthError("TOKEN_INVALID", "No refresh token available");
+            if (!refreshToken) throw new IQAuthError("config_invalid", "No refresh token available");
             return { body: JSON.stringify({ refreshToken }) };
           })()
         });
@@ -1382,7 +1475,7 @@ var HttpClient = class {
           return;
         }
         if (!body.data.accessToken || !body.data.refreshToken) {
-          throw new IQAuthError("TOKEN_INVALID", "Refresh response did not include a token pair");
+          throw new IQAuthError("token_invalid", "Refresh response did not include a token pair");
         }
         const tokens = {
           accessToken: body.data.accessToken,
@@ -1400,7 +1493,7 @@ var HttpClient = class {
     return this.requestWithRetry(method, path, body, options, false);
   }
   async requestWithRetry(method, path, body, options, hasRetried) {
-    if (this.config.autoRefresh && !options?.skipAutoRefresh && !this.isBrowserSession() && this.config.getRefreshToken() && this.isTokenExpiringSoon()) {
+    if (this.config.autoRefresh && this.config.proactiveRefresh !== false && !options?.skipAutoRefresh && !this.isBrowserSession() && this.config.getRefreshToken() && this.isTokenExpiringSoon()) {
       await this.attemptRefresh();
     }
     const url = `${this.config.baseUrl}${path}`;
@@ -1475,6 +1568,10 @@ var IQAuthClient = class _IQAuthClient {
         this._refreshToken = tokens.refreshToken;
       },
       autoRefresh: "autoRefresh" in config ? config.autoRefresh !== false : true,
+      // `'app-state'` is mobile-only — on any other environment we treat it
+      // as the default `true` (proactive refresh ON). Only the mobile client
+      // disables proactive refresh and replaces it with an AppState listener.
+      proactiveRefresh: "autoRefresh" in config && config.autoRefresh === "app-state" && _IQAuthClient.resolveEnvironment(config) === "mobile" ? false : true,
       onTokenRefresh: "onTokenRefresh" in config ? config.onTokenRefresh : void 0,
       sessionHeaderName: config.sessionHeaderName,
       sessionHeaderValue: config.sessionHeaderValue,
@@ -1515,6 +1612,13 @@ var IQAuthClient = class _IQAuthClient {
   static forServer(config) {
     return new _IQAuthClient({ ...config, environment: "server" });
   }
+  /**
+   * Construct a mobile-environment client. NOTE: this constructor does NOT
+   * subscribe to React Native's `AppState` even when `autoRefresh: 'app-state'`
+   * is passed — it only disables the per-request proactive refresh. Use
+   * `createMobileClient` from `@iqauth/sdk/mobile` if you want the full
+   * AppState-driven refresh behavior (recommended for Expo / React Native).
+   */
   static forMobile(config) {
     return new _IQAuthClient({ ...config, environment: "mobile" });
   }
@@ -1531,6 +1635,18 @@ var IQAuthClient = class _IQAuthClient {
   getRefreshToken() {
     return this._refreshToken;
   }
+  /**
+   * Task #126: Eagerly fetch JWKS + OIDC discovery so the first verify() /
+   * refresh round-trip on the request hot path doesn't pay the discovery
+   * fetch latency. Safe to call repeatedly. Errors are swallowed; callers
+   * may fire-and-forget. Called automatically by `iqAuth({...}).attachHelpers()`.
+   */
+  async prewarm() {
+    await Promise.all([
+      this.tokens.prewarm(),
+      this.oidc.getDiscovery().catch(() => void 0)
+    ]);
+  }
   getCurrentClaims() {
     if (!this._accessToken) return null;
     return this.tokens.decode(this._accessToken);

package/dist/cli/index.js

@@ -538,10 +538,10 @@ async function getCtx(flags) {
   const env = await loadEnv(flags.get("env-file") || ".env");
   const baseUrl = flags.get("base-url") || env.IQAUTH_ISSUER;
   const token = flags.get("token") || env.IQAUTH_ADMIN_TOKEN || env.IQAUTH_SECRET_KEY;
-  const app = flags.get("app") || env.IQAUTH_APP_ID || env.IQAUTH_APP_KEY;
+  const app = flags.get("app") || env.IQAUTH_APP_ID;
   if (!baseUrl) throw new Error("Missing --base-url (or IQAUTH_ISSUER in env).");
   if (!token) throw new Error("Missing --token (or IQAUTH_ADMIN_TOKEN / IQAUTH_SECRET_KEY in env).");
-  if (!app) throw new Error("Missing --app <appId|appKey> (or IQAUTH_APP_ID in env).");
+  if (!app) throw new Error("Missing --app <appId> (or IQAUTH_APP_ID in env). The `IQAUTH_APP_KEY` env-var fallback has been removed (Task #130) \u2014 pass --app explicitly.");
   return { baseUrl, token, app };
 }
 async function runKeys(argv) {

package/dist/cli/index.mjs

@@ -17,12 +17,12 @@ async function run() {
       return;
     }
     case "doctor": {
-      const { runDoctor } = await import("../doctor-YYNHNMLD.mjs");
+      const { runDoctor } = await import("../doctor-JAFXWU3X.mjs");
       await runDoctor(rest);
       return;
     }
     case "keys": {
-      const { runKeys } = await import("../keys-NLWFAOEM.mjs");
+      const { runKeys } = await import("../keys-6Y776TG2.mjs");
       await runKeys(rest);
       return;
     }

package/dist/{client-BNQe3AgF.d.ts → client-D8L-PaWr.d.mts}

@@ -1,5 +1,5 @@
-import { I as IQAuthEnvironment, T as TokenPair, W as IQAuthRetryConfig, L as LoginResult, a$ as SignupRequest, D as MfaVerifyResult, d as SessionUser, h as Session, U as UserProfile, H as ProvisionUserRequest, K as ProvisionUserResponse, G as UserPermissions, J as JwtClaims, O as OidcDiscovery, t as JwksResponse, u as OidcTokenResponse, b0 as HostedClientContext, i as TenantInfo, C as CreateTenantRequest, j as UpdateTenantRequest, P as PromoteToVendorRequest, k as PromoteToVendorResult, a7 as TenantUser, l as InviteTenantUserRequest, m as InviteTenantUserResult, n as TenantUserRoleUpdate, M as MigrateUserRequest, E as PasswordPolicy, F as MfaPolicy, B as BrandingConfig, _ as AppInfo, $ as PermissionNodeInfo, Z as AppManifest, a0 as AppSyncResult, a1 as Role, a2 as CreateRoleRequest, a3 as UpdateRoleRequest, a4 as AssignRoleRequest, a5 as UserRoleAssignment, a8 as PermissionGroup, a9 as GroupPermission, aa as AddGroupPermissionRequest, ab as InheritanceRelation, a6 as UserGroupAssignment, ac as UserPermissionOverride, ad as AddUserOverrideRequest, ae as EffectivePermission, af as PermissionCheckResult, ah as CreateApiKeyRequest, ai as CreateApiKeyResult, ag as ApiKeyInfo, aj as ApiKeyIntrospection, al as CreateInviteRequest, ak as Invitation, am as InviteValidation, an as AcceptInviteRequest, ap as CreateWebhookRequest, aq as CreateWebhookResult, ao as WebhookEndpoint, ar as WebhookDelivery, as as WebhookTestResult, at as Entitlement, au as GrantEntitlementRequest, av as Vendor, aw as CreateVendorRequest, ax as UpdateVendorRequest, az as CreateSourceRequest, ay as Source, aA as UpdateSourceRequest, aC as CreateClientRequest, aB as Client, aD as UpdateClientRequest, aE as HierarchyVendor, aH as HierarchyLink, aL as MembershipWithDetails, aJ as CreateMembershipRequest, aI as Membership, aK as UpdateMembershipRequest, aM as AvailableScopesTree, aQ as ScopeSwitchResult, aR as GdprExportData, aS as PinStatus, aU as MfaAvailableMethods, aV as TotpEnrollResult, aW as TotpVerifyResult, aX as SmsEnrollResult, y as MfaEnrollment, aY as EmailEnrollResult, aZ as BackupCodesResult, a_ as BackupCodeCountResult, o as UpdateBrandingRequest, q as UploadAssetRequest, p as BrandingAsset, r as BrandingDomainMapping, a as IQAuthClientConfig, c as IQAuthBrowserSessionClientConfig, b as IQAuthTokenClientConfig } from './types-DZAflmmq.js';
-import { T as TokensModule } from './tokens-aHiGFr_E.js';
+import { d as IQAuthEnvironment, T as TokenPair, Y as IQAuthRetryConfig, b1 as ScopeHint, L as LoginResult, b2 as SignupRequest, K as MfaVerifyResult, S as SessionUser, m as Session, U as UserProfile, V as ProvisionUserRequest, W as ProvisionUserResponse, R as UserPermissions, J as JwtClaims, O as OidcDiscovery, y as JwksResponse, z as OidcTokenResponse, b3 as HostedClientContext, n as TenantInfo, C as CreateTenantRequest, o as UpdateTenantRequest, P as PromoteToVendorRequest, p as PromoteToVendorResult, a9 as TenantUser, q as InviteTenantUserRequest, r as InviteTenantUserResult, s as TenantUserRoleUpdate, M as MigrateUserRequest, N as PasswordPolicy, Q as MfaPolicy, B as BrandingConfig, a0 as AppInfo, a1 as PermissionNodeInfo, $ as AppManifest, a2 as AppSyncResult, a3 as Role, a4 as CreateRoleRequest, a5 as UpdateRoleRequest, a6 as AssignRoleRequest, a7 as UserRoleAssignment, aa as PermissionGroup, ab as GroupPermission, ac as AddGroupPermissionRequest, ad as InheritanceRelation, a8 as UserGroupAssignment, ae as UserPermissionOverride, af as AddUserOverrideRequest, ag as EffectivePermission, ah as PermissionCheckResult, aj as CreateApiKeyRequest, ak as CreateApiKeyResult, ai as ApiKeyInfo, al as ApiKeyIntrospection, an as CreateInviteRequest, am as Invitation, ao as InviteValidation, ap as AcceptInviteRequest, ar as CreateWebhookRequest, as as CreateWebhookResult, aq as WebhookEndpoint, at as WebhookDelivery, au as WebhookTestResult, av as Entitlement, aw as GrantEntitlementRequest, ax as Vendor, ay as CreateVendorRequest, az as UpdateVendorRequest, aB as CreateSourceRequest, aA as Source, aC as UpdateSourceRequest, aE as CreateClientRequest, aD as Client, aF as UpdateClientRequest, aG as HierarchyVendor, aJ as HierarchyLink, aN as MembershipWithDetails, aL as CreateMembershipRequest, aK as Membership, aM as UpdateMembershipRequest, aO as AvailableScopesTree, aS as ScopeSwitchResult, aT as GdprExportData, aU as PinStatus, aW as MfaAvailableMethods, aX as TotpEnrollResult, aY as TotpVerifyResult, aZ as SmsEnrollResult, G as MfaEnrollment, a_ as EmailEnrollResult, a$ as BackupCodesResult, b0 as BackupCodeCountResult, t as UpdateBrandingRequest, v as UploadAssetRequest, u as BrandingAsset, w as BrandingDomainMapping, e as IQAuthClientConfig, I as IQAuthBrowserSessionClientConfig, f as IQAuthTokenClientConfig } from './types-Bn8O-OEd.mjs';
+import { T as TokensModule } from './tokens-B06VtvUi.mjs';
 
 /**
  * SOURCE REFS:
@@ -18,6 +18,13 @@ interface HttpClientConfig {
     getApiKey: () => string | undefined;
     setTokens: (tokens: TokenPair) => void;
     autoRefresh: boolean;
+    /**
+     * When false, the per-request "expiring soon" proactive refresh is skipped.
+     * Reactive refresh on a TOKEN_EXPIRED response still fires when `autoRefresh` is true.
+     * Used by the mobile client's `'app-state'` mode where the AppState listener
+     * drives proactive refresh instead.
+     */
+    proactiveRefresh?: boolean;
     onTokenRefresh?: (tokens: TokenPair) => void;
     sessionHeaderName?: string;
     sessionHeaderValue?: string;
@@ -49,7 +56,9 @@ declare class HttpClient {
 declare class AuthModule {
     private http;
     constructor(http: HttpClient);
-    login(email: string, password: string): Promise<LoginResult>;
+    login(email: string, password: string, opts?: {
+        scopeHint?: ScopeHint;
+    }): Promise<LoginResult>;
     signup(input: SignupRequest): Promise<LoginResult>;
     completeMfa(mfaChallengeToken: string, code: string, method?: string): Promise<MfaVerifyResult>;
     completeMfaWithBackup(mfaChallengeToken: string, backupCode: string): Promise<MfaVerifyResult>;
@@ -57,7 +66,15 @@ declare class AuthModule {
         sent: boolean;
         method: string;
     }>;
-    selectTenant(tenantSelectionToken: string, tenantId: string): Promise<LoginResult>;
+    selectTenant(tenantSelectionToken: string, tenantId: string, opts?: {
+        scopeHint?: ScopeHint;
+    }): Promise<LoginResult>;
+    /**
+     * 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.
+     */
+    selectScope(scopeSelectionToken: string, membershipId: string): Promise<LoginResult>;
     logout(): Promise<{
         message: string;
     }>;
@@ -594,11 +611,33 @@ declare class PermissionGroupsModule {
     removeUserOverride(tenantId: string, userId: string, overrideId: string): Promise<{
         message: string;
     }>;
+    /**
+     * Task #130 — `appKey` is REQUIRED. The legacy `product` query alias is no
+     * longer accepted at the SDK boundary; pass it as `appKey` instead. The
+     * server still accepts `product=` from raw HTTP callers during the
+     * deprecation window, but the SDK will not silently translate it.
+     */
     getEffectivePermissions(tenantId: string, userId: string, params: {
-        product?: string;
-        appKey?: string;
+        appKey: string;
     }): Promise<EffectivePermission[]>;
     checkPermission(tenantId: string, userId: string, appKey: string, nodeKey: string): Promise<PermissionCheckResult>;
+    /**
+     * Task #130 — every entry in `checks` must include a non-empty `appKey`
+     * AND `nodeKey`. The SDK validates the whole batch before sending so a
+     * single misconfigured entry can't slip through and silently report
+     * `allowed: false` from the server's per-entry validation branch.
+     */
+    batchCheckPermissions(tenantId: string, userId: string, checks: Array<{
+        appKey: string;
+        nodeKey: string;
+    }>): Promise<{
+        results: Array<{
+            appKey: string;
+            nodeKey: string;
+            allowed: boolean;
+            error?: string;
+        }>;
+    }>;
 }
 
 declare class ApiKeysModule {
@@ -835,11 +874,25 @@ declare class IQAuthClient {
     constructor(config: IQAuthClientConfig);
     static forBrowserSession(config: Omit<IQAuthBrowserSessionClientConfig, "environment">): IQAuthClient;
     static forServer(config: IQAuthTokenClientConfig): IQAuthClient;
+    /**
+     * Construct a mobile-environment client. NOTE: this constructor does NOT
+     * subscribe to React Native's `AppState` even when `autoRefresh: 'app-state'`
+     * is passed — it only disables the per-request proactive refresh. Use
+     * `createMobileClient` from `@iqauth/sdk/mobile` if you want the full
+     * AppState-driven refresh behavior (recommended for Expo / React Native).
+     */
     static forMobile(config: IQAuthTokenClientConfig): IQAuthClient;
     static forService(config: IQAuthTokenClientConfig): IQAuthClient;
     setTokens(tokens: TokenPair): void;
     getAccessToken(): string | undefined;
     getRefreshToken(): string | undefined;
+    /**
+     * Task #126: Eagerly fetch JWKS + OIDC discovery so the first verify() /
+     * refresh round-trip on the request hot path doesn't pay the discovery
+     * fetch latency. Safe to call repeatedly. Errors are swallowed; callers
+     * may fire-and-forget. Called automatically by `iqAuth({...}).attachHelpers()`.
+     */
+    prewarm(): Promise<void>;
     private getCurrentClaims;
     private static resolveEnvironment;
 }

package/dist/{client-kYlJFgPv.d.mts → client-DkPL0EPZ.d.ts}

@@ -1,5 +1,5 @@
-import { I as IQAuthEnvironment, T as TokenPair, W as IQAuthRetryConfig, L as LoginResult, a$ as SignupRequest, D as MfaVerifyResult, d as SessionUser, h as Session, U as UserProfile, H as ProvisionUserRequest, K as ProvisionUserResponse, G as UserPermissions, J as JwtClaims, O as OidcDiscovery, t as JwksResponse, u as OidcTokenResponse, b0 as HostedClientContext, i as TenantInfo, C as CreateTenantRequest, j as UpdateTenantRequest, P as PromoteToVendorRequest, k as PromoteToVendorResult, a7 as TenantUser, l as InviteTenantUserRequest, m as InviteTenantUserResult, n as TenantUserRoleUpdate, M as MigrateUserRequest, E as PasswordPolicy, F as MfaPolicy, B as BrandingConfig, _ as AppInfo, $ as PermissionNodeInfo, Z as AppManifest, a0 as AppSyncResult, a1 as Role, a2 as CreateRoleRequest, a3 as UpdateRoleRequest, a4 as AssignRoleRequest, a5 as UserRoleAssignment, a8 as PermissionGroup, a9 as GroupPermission, aa as AddGroupPermissionRequest, ab as InheritanceRelation, a6 as UserGroupAssignment, ac as UserPermissionOverride, ad as AddUserOverrideRequest, ae as EffectivePermission, af as PermissionCheckResult, ah as CreateApiKeyRequest, ai as CreateApiKeyResult, ag as ApiKeyInfo, aj as ApiKeyIntrospection, al as CreateInviteRequest, ak as Invitation, am as InviteValidation, an as AcceptInviteRequest, ap as CreateWebhookRequest, aq as CreateWebhookResult, ao as WebhookEndpoint, ar as WebhookDelivery, as as WebhookTestResult, at as Entitlement, au as GrantEntitlementRequest, av as Vendor, aw as CreateVendorRequest, ax as UpdateVendorRequest, az as CreateSourceRequest, ay as Source, aA as UpdateSourceRequest, aC as CreateClientRequest, aB as Client, aD as UpdateClientRequest, aE as HierarchyVendor, aH as HierarchyLink, aL as MembershipWithDetails, aJ as CreateMembershipRequest, aI as Membership, aK as UpdateMembershipRequest, aM as AvailableScopesTree, aQ as ScopeSwitchResult, aR as GdprExportData, aS as PinStatus, aU as MfaAvailableMethods, aV as TotpEnrollResult, aW as TotpVerifyResult, aX as SmsEnrollResult, y as MfaEnrollment, aY as EmailEnrollResult, aZ as BackupCodesResult, a_ as BackupCodeCountResult, o as UpdateBrandingRequest, q as UploadAssetRequest, p as BrandingAsset, r as BrandingDomainMapping, a as IQAuthClientConfig, c as IQAuthBrowserSessionClientConfig, b as IQAuthTokenClientConfig } from './types-DZAflmmq.mjs';
-import { T as TokensModule } from './tokens-DCyzzn8L.mjs';
+import { d as IQAuthEnvironment, T as TokenPair, Y as IQAuthRetryConfig, b1 as ScopeHint, L as LoginResult, b2 as SignupRequest, K as MfaVerifyResult, S as SessionUser, m as Session, U as UserProfile, V as ProvisionUserRequest, W as ProvisionUserResponse, R as UserPermissions, J as JwtClaims, O as OidcDiscovery, y as JwksResponse, z as OidcTokenResponse, b3 as HostedClientContext, n as TenantInfo, C as CreateTenantRequest, o as UpdateTenantRequest, P as PromoteToVendorRequest, p as PromoteToVendorResult, a9 as TenantUser, q as InviteTenantUserRequest, r as InviteTenantUserResult, s as TenantUserRoleUpdate, M as MigrateUserRequest, N as PasswordPolicy, Q as MfaPolicy, B as BrandingConfig, a0 as AppInfo, a1 as PermissionNodeInfo, $ as AppManifest, a2 as AppSyncResult, a3 as Role, a4 as CreateRoleRequest, a5 as UpdateRoleRequest, a6 as AssignRoleRequest, a7 as UserRoleAssignment, aa as PermissionGroup, ab as GroupPermission, ac as AddGroupPermissionRequest, ad as InheritanceRelation, a8 as UserGroupAssignment, ae as UserPermissionOverride, af as AddUserOverrideRequest, ag as EffectivePermission, ah as PermissionCheckResult, aj as CreateApiKeyRequest, ak as CreateApiKeyResult, ai as ApiKeyInfo, al as ApiKeyIntrospection, an as CreateInviteRequest, am as Invitation, ao as InviteValidation, ap as AcceptInviteRequest, ar as CreateWebhookRequest, as as CreateWebhookResult, aq as WebhookEndpoint, at as WebhookDelivery, au as WebhookTestResult, av as Entitlement, aw as GrantEntitlementRequest, ax as Vendor, ay as CreateVendorRequest, az as UpdateVendorRequest, aB as CreateSourceRequest, aA as Source, aC as UpdateSourceRequest, aE as CreateClientRequest, aD as Client, aF as UpdateClientRequest, aG as HierarchyVendor, aJ as HierarchyLink, aN as MembershipWithDetails, aL as CreateMembershipRequest, aK as Membership, aM as UpdateMembershipRequest, aO as AvailableScopesTree, aS as ScopeSwitchResult, aT as GdprExportData, aU as PinStatus, aW as MfaAvailableMethods, aX as TotpEnrollResult, aY as TotpVerifyResult, aZ as SmsEnrollResult, G as MfaEnrollment, a_ as EmailEnrollResult, a$ as BackupCodesResult, b0 as BackupCodeCountResult, t as UpdateBrandingRequest, v as UploadAssetRequest, u as BrandingAsset, w as BrandingDomainMapping, e as IQAuthClientConfig, I as IQAuthBrowserSessionClientConfig, f as IQAuthTokenClientConfig } from './types-Bn8O-OEd.js';
+import { T as TokensModule } from './tokens-9F6ETrzk.js';
 
 /**
  * SOURCE REFS:
@@ -18,6 +18,13 @@ interface HttpClientConfig {
     getApiKey: () => string | undefined;
     setTokens: (tokens: TokenPair) => void;
     autoRefresh: boolean;
+    /**
+     * When false, the per-request "expiring soon" proactive refresh is skipped.
+     * Reactive refresh on a TOKEN_EXPIRED response still fires when `autoRefresh` is true.
+     * Used by the mobile client's `'app-state'` mode where the AppState listener
+     * drives proactive refresh instead.
+     */
+    proactiveRefresh?: boolean;
     onTokenRefresh?: (tokens: TokenPair) => void;
     sessionHeaderName?: string;
     sessionHeaderValue?: string;
@@ -49,7 +56,9 @@ declare class HttpClient {
 declare class AuthModule {
     private http;
     constructor(http: HttpClient);
-    login(email: string, password: string): Promise<LoginResult>;
+    login(email: string, password: string, opts?: {
+        scopeHint?: ScopeHint;
+    }): Promise<LoginResult>;
     signup(input: SignupRequest): Promise<LoginResult>;
     completeMfa(mfaChallengeToken: string, code: string, method?: string): Promise<MfaVerifyResult>;
     completeMfaWithBackup(mfaChallengeToken: string, backupCode: string): Promise<MfaVerifyResult>;
@@ -57,7 +66,15 @@ declare class AuthModule {
         sent: boolean;
         method: string;
     }>;
-    selectTenant(tenantSelectionToken: string, tenantId: string): Promise<LoginResult>;
+    selectTenant(tenantSelectionToken: string, tenantId: string, opts?: {
+        scopeHint?: ScopeHint;
+    }): Promise<LoginResult>;
+    /**
+     * 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.
+     */
+    selectScope(scopeSelectionToken: string, membershipId: string): Promise<LoginResult>;
     logout(): Promise<{
         message: string;
     }>;
@@ -594,11 +611,33 @@ declare class PermissionGroupsModule {
     removeUserOverride(tenantId: string, userId: string, overrideId: string): Promise<{
         message: string;
     }>;
+    /**
+     * Task #130 — `appKey` is REQUIRED. The legacy `product` query alias is no
+     * longer accepted at the SDK boundary; pass it as `appKey` instead. The
+     * server still accepts `product=` from raw HTTP callers during the
+     * deprecation window, but the SDK will not silently translate it.
+     */
     getEffectivePermissions(tenantId: string, userId: string, params: {
-        product?: string;
-        appKey?: string;
+        appKey: string;
     }): Promise<EffectivePermission[]>;
     checkPermission(tenantId: string, userId: string, appKey: string, nodeKey: string): Promise<PermissionCheckResult>;
+    /**
+     * Task #130 — every entry in `checks` must include a non-empty `appKey`
+     * AND `nodeKey`. The SDK validates the whole batch before sending so a
+     * single misconfigured entry can't slip through and silently report
+     * `allowed: false` from the server's per-entry validation branch.
+     */
+    batchCheckPermissions(tenantId: string, userId: string, checks: Array<{
+        appKey: string;
+        nodeKey: string;
+    }>): Promise<{
+        results: Array<{
+            appKey: string;
+            nodeKey: string;
+            allowed: boolean;
+            error?: string;
+        }>;
+    }>;
 }
 
 declare class ApiKeysModule {
@@ -835,11 +874,25 @@ declare class IQAuthClient {
     constructor(config: IQAuthClientConfig);
     static forBrowserSession(config: Omit<IQAuthBrowserSessionClientConfig, "environment">): IQAuthClient;
     static forServer(config: IQAuthTokenClientConfig): IQAuthClient;
+    /**
+     * Construct a mobile-environment client. NOTE: this constructor does NOT
+     * subscribe to React Native's `AppState` even when `autoRefresh: 'app-state'`
+     * is passed — it only disables the per-request proactive refresh. Use
+     * `createMobileClient` from `@iqauth/sdk/mobile` if you want the full
+     * AppState-driven refresh behavior (recommended for Expo / React Native).
+     */
     static forMobile(config: IQAuthTokenClientConfig): IQAuthClient;
     static forService(config: IQAuthTokenClientConfig): IQAuthClient;
     setTokens(tokens: TokenPair): void;
     getAccessToken(): string | undefined;
     getRefreshToken(): string | undefined;
+    /**
+     * Task #126: Eagerly fetch JWKS + OIDC discovery so the first verify() /
+     * refresh round-trip on the request hot path doesn't pay the discovery
+     * fetch latency. Safe to call repeatedly. Errors are swallowed; callers
+     * may fire-and-forget. Called automatically by `iqAuth({...}).attachHelpers()`.
+     */
+    prewarm(): Promise<void>;
     private getCurrentClaims;
     private static resolveEnvironment;
 }

package/dist/{doctor-YYNHNMLD.mjs → doctor-JAFXWU3X.mjs}

@@ -5,8 +5,8 @@ import {
 } from "./chunk-X3K3WOBR.mjs";
 import {
   parsePublishableKey
-} from "./chunk-WQWBJSSS.mjs";
-import "./chunk-6I6RM4MN.mjs";
+} from "./chunk-HVHNYPDC.mjs";
+import "./chunk-6PJRLRB4.mjs";
 import "./chunk-Y6FXYEAI.mjs";
 
 // src/cli/doctor.ts