@iqauth/sdk 2.6.3 → 2.7.0

package/dist/{chunk-BVV54LPI.mjs → chunk-YVALAG3B.mjs}

@@ -1,21 +1,27 @@
 import {
   assertPublishableKey
-} from "./chunk-WQWBJSSS.mjs";
+} from "./chunk-HVHNYPDC.mjs";
 import {
   IQAuthClient
-} from "./chunk-W3F4JYGP.mjs";
+} from "./chunk-JXQI62A7.mjs";
 import {
   IQAuthError
-} from "./chunk-6I6RM4MN.mjs";
+} from "./chunk-6PJRLRB4.mjs";
 
 // src/middleware/express.ts
 var KNOWN_AUTH_ERROR_CODES = /* @__PURE__ */ new Set([
+  // Legacy UPPER_SNAKE codes (server-originated and SDK ≤2.6.x throws).
   "TOKEN_INVALID",
   "TOKEN_EXPIRED",
   "TOKEN_REVOKED",
   "SESSION_EXPIRED",
   "SESSION_INVALID",
-  "AUTH_REQUIRED"
+  "AUTH_REQUIRED",
+  // Task #127 — typed `IQAuthErrorCode` taxonomy thrown by `tokens.verify`.
+  // Mapped to 401 here so framework consumers don't have to learn the new
+  // codes to keep their auth-failure handling working.
+  "token_invalid",
+  "token_expired"
 ]);
 var DEFAULT_ACCESS_COOKIE = "iqauth_at";
 var DEFAULT_REFRESH_COOKIE = "iqauth_rt";

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-kYlJFgPv.d.mts → client-BGFnBpfc.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.mjs';
-import { T as TokensModule } from './tokens-DCyzzn8L.mjs';
+import { d as IQAuthEnvironment, T as TokenPair, Y as IQAuthRetryConfig, L as LoginResult, b1 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, b2 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-XOV9XPVi.mjs';
+import { T as TokensModule } from './tokens-CITeoG6P.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;
@@ -594,11 +601,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 +864,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-BNQe3AgF.d.ts → client-CDQ21LvW.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.js';
-import { T as TokensModule } from './tokens-aHiGFr_E.js';
+import { d as IQAuthEnvironment, T as TokenPair, Y as IQAuthRetryConfig, L as LoginResult, b1 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, b2 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-XOV9XPVi.js';
+import { T as TokensModule } from './tokens-Bqhmqq_R.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;
@@ -594,11 +601,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 +864,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

package/dist/errors-Jl1Jtm-6.d.mts

@@ -0,0 +1,107 @@
+/**
+ * SOURCE REFS:
+ * - Route file: src/lib/response.ts (error envelope: { success: false, error: { code, message } })
+ * - All route files for error code extraction
+ * - Verified claims: N/A (error module)
+ * - Last verified: Phase 0 Research Summary
+ *
+ * Task #127 (SDK 2.7.0): typed `IQAuthErrorCode` taxonomy.
+ * The SDK historically threw `IQAuthError` with arbitrary string codes,
+ * forcing every integrator to either string-match the message or memorize
+ * the full server code list. This module now ships a discriminated union of
+ * 10 normalized codes that callers can pattern-match exhaustively, and the
+ * `IQAuthError.code` field is typed as `IQAuthErrorCode | (string & {})` so
+ * existing throw sites that pass server-supplied strings (e.g.
+ * `"TOKEN_REVOKED"`, `"SESSION_EXPIRED_INACTIVITY"`) continue to compile and
+ * still pass through to consumers verbatim.
+ *
+ * Migration: existing `catch (e: Error)` keeps working unchanged. The new
+ * codes are additive — `e.code` may now equal one of the 10 lowercase
+ * tokens for SDK-originated errors (verify, JWKS fetch, config validation,
+ * network) while server-originated errors keep their existing UPPER_SNAKE
+ * codes (so framework adapters that switch on `TOKEN_EXPIRED` still work).
+ */
+/**
+ * Discriminated union of normalized SDK error codes. Use these for typed
+ * pattern-matching on errors thrown by SDK calls (`tokens.verify`, JWKS
+ * fetch, config validation, network failures).
+ *
+ * Server-originated errors (e.g. those rethrown from API responses or from
+ * the issuer) may still surface with their UPPER_SNAKE_CASE codes
+ * (`TOKEN_REVOKED`, `MFA_INVALID_CODE`, …) — `code` is widened to accept
+ * those alongside the typed taxonomy.
+ */
+type IQAuthErrorCode = "token_expired" | "token_invalid" | "jwks_unavailable" | "jwks_fetch_failed" | "rate_limited" | "network" | "config_invalid" | "app_not_found" | "permission_denied" | "unknown";
+/**
+ * The 10 canonical typed codes, exposed as a runtime tuple for exhaustive
+ * `switch` checks and for SDK consumers that want to enumerate them.
+ */
+declare const IQ_AUTH_ERROR_CODES: readonly IQAuthErrorCode[];
+declare class IQAuthError extends Error {
+    /**
+     * Normalized error code. Prefer matching against {@link IQAuthErrorCode}
+     * for SDK-originated errors. Server-originated errors may carry their
+     * UPPER_SNAKE server code (e.g. `"TOKEN_REVOKED"`).
+     */
+    code: IQAuthErrorCode | (string & {});
+    status?: number;
+    /**
+     * The underlying error or response payload that triggered this throw.
+     * Aliased as `raw` for back-compat with SDK ≤2.6.x.
+     */
+    cause?: unknown;
+    /** @deprecated alias for {@link cause}; kept for SDK ≤2.6.x compatibility. */
+    raw?: unknown;
+    constructor(code: IQAuthErrorCode | (string & {}), message: string, status?: number, cause?: unknown);
+    /**
+     * Type guard: true when `value` is an `IQAuthError`. Useful for adapters
+     * that round-trip errors through `unknown` (e.g. fastify's `setErrorHandler`).
+     */
+    static isIQAuthError(value: unknown): value is IQAuthError;
+    /**
+     * Type-narrowed code check. Lets callers write
+     * `if (err.is("token_expired")) …` with full IntelliSense for the typed
+     * taxonomy without losing the ability to handle server codes via
+     * `err.code === "TOKEN_REVOKED"`.
+     */
+    is(code: IQAuthErrorCode): boolean;
+}
+declare const ErrorCodes: {
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly INVALID_CREDENTIALS: "INVALID_CREDENTIALS";
+    readonly ACCOUNT_INACTIVE: "ACCOUNT_INACTIVE";
+    readonly ACCOUNT_LOCKED: "ACCOUNT_LOCKED";
+    readonly INSUFFICIENT_PERMISSIONS: "INSUFFICIENT_PERMISSIONS";
+    readonly TOKEN_INVALID: "TOKEN_INVALID";
+    readonly TOKEN_EXPIRED: "TOKEN_EXPIRED";
+    readonly TOKEN_REVOKED: "TOKEN_REVOKED";
+    readonly USER_INACTIVE: "USER_INACTIVE";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly SESSION_INVALID: "SESSION_INVALID";
+    readonly SESSION_EXPIRED: "SESSION_EXPIRED";
+    readonly REFRESH_TOKEN_REUSED: "REFRESH_TOKEN_REUSED";
+    readonly PASSWORD_EXPIRED: "PASSWORD_EXPIRED";
+    readonly PIN_EXPIRED: "PIN_EXPIRED";
+    readonly PASSWORD_POLICY_VIOLATION: "PASSWORD_POLICY_VIOLATION";
+    readonly MFA_INVALID_CODE: "MFA_INVALID_CODE";
+    readonly MFA_METHOD_UNAVAILABLE: "MFA_METHOD_UNAVAILABLE";
+    readonly MFA_RATE_LIMITED: "MFA_RATE_LIMITED";
+    readonly MFA_ENROLLMENT_REQUIRED: "MFA_ENROLLMENT_REQUIRED";
+    readonly API_KEY_REQUIRED: "API_KEY_REQUIRED";
+    readonly API_KEY_INVALID: "API_KEY_INVALID";
+    readonly AUTH_REQUIRED: "AUTH_REQUIRED";
+    readonly ALREADY_EXISTS: "ALREADY_EXISTS";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly OAUTH_NOT_CONFIGURED: "OAUTH_NOT_CONFIGURED";
+    readonly UPLOAD_ERROR: "UPLOAD_ERROR";
+    readonly EMAIL_SERVICE_UNAVAILABLE: "EMAIL_SERVICE_UNAVAILABLE";
+    readonly INVALID_CODE: "INVALID_CODE";
+    readonly CODE_ALREADY_USED: "CODE_ALREADY_USED";
+    readonly CODE_EXPIRED: "CODE_EXPIRED";
+    readonly CODE_IP_MISMATCH: "CODE_IP_MISMATCH";
+    readonly UNKNOWN_PAYLOAD: "UNKNOWN_PAYLOAD";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
+export { ErrorCodes as E, IQAuthError as I, IQ_AUTH_ERROR_CODES as a, type ErrorCode as b, type IQAuthErrorCode as c };

package/dist/errors-Jl1Jtm-6.d.ts

@@ -0,0 +1,107 @@
+/**
+ * SOURCE REFS:
+ * - Route file: src/lib/response.ts (error envelope: { success: false, error: { code, message } })
+ * - All route files for error code extraction
+ * - Verified claims: N/A (error module)
+ * - Last verified: Phase 0 Research Summary
+ *
+ * Task #127 (SDK 2.7.0): typed `IQAuthErrorCode` taxonomy.
+ * The SDK historically threw `IQAuthError` with arbitrary string codes,
+ * forcing every integrator to either string-match the message or memorize
+ * the full server code list. This module now ships a discriminated union of
+ * 10 normalized codes that callers can pattern-match exhaustively, and the
+ * `IQAuthError.code` field is typed as `IQAuthErrorCode | (string & {})` so
+ * existing throw sites that pass server-supplied strings (e.g.
+ * `"TOKEN_REVOKED"`, `"SESSION_EXPIRED_INACTIVITY"`) continue to compile and
+ * still pass through to consumers verbatim.
+ *
+ * Migration: existing `catch (e: Error)` keeps working unchanged. The new
+ * codes are additive — `e.code` may now equal one of the 10 lowercase
+ * tokens for SDK-originated errors (verify, JWKS fetch, config validation,
+ * network) while server-originated errors keep their existing UPPER_SNAKE
+ * codes (so framework adapters that switch on `TOKEN_EXPIRED` still work).
+ */
+/**
+ * Discriminated union of normalized SDK error codes. Use these for typed
+ * pattern-matching on errors thrown by SDK calls (`tokens.verify`, JWKS
+ * fetch, config validation, network failures).
+ *
+ * Server-originated errors (e.g. those rethrown from API responses or from
+ * the issuer) may still surface with their UPPER_SNAKE_CASE codes
+ * (`TOKEN_REVOKED`, `MFA_INVALID_CODE`, …) — `code` is widened to accept
+ * those alongside the typed taxonomy.
+ */
+type IQAuthErrorCode = "token_expired" | "token_invalid" | "jwks_unavailable" | "jwks_fetch_failed" | "rate_limited" | "network" | "config_invalid" | "app_not_found" | "permission_denied" | "unknown";
+/**
+ * The 10 canonical typed codes, exposed as a runtime tuple for exhaustive
+ * `switch` checks and for SDK consumers that want to enumerate them.
+ */
+declare const IQ_AUTH_ERROR_CODES: readonly IQAuthErrorCode[];
+declare class IQAuthError extends Error {
+    /**
+     * Normalized error code. Prefer matching against {@link IQAuthErrorCode}
+     * for SDK-originated errors. Server-originated errors may carry their
+     * UPPER_SNAKE server code (e.g. `"TOKEN_REVOKED"`).
+     */
+    code: IQAuthErrorCode | (string & {});
+    status?: number;
+    /**
+     * The underlying error or response payload that triggered this throw.
+     * Aliased as `raw` for back-compat with SDK ≤2.6.x.
+     */
+    cause?: unknown;
+    /** @deprecated alias for {@link cause}; kept for SDK ≤2.6.x compatibility. */
+    raw?: unknown;
+    constructor(code: IQAuthErrorCode | (string & {}), message: string, status?: number, cause?: unknown);
+    /**
+     * Type guard: true when `value` is an `IQAuthError`. Useful for adapters
+     * that round-trip errors through `unknown` (e.g. fastify's `setErrorHandler`).
+     */
+    static isIQAuthError(value: unknown): value is IQAuthError;
+    /**
+     * Type-narrowed code check. Lets callers write
+     * `if (err.is("token_expired")) …` with full IntelliSense for the typed
+     * taxonomy without losing the ability to handle server codes via
+     * `err.code === "TOKEN_REVOKED"`.
+     */
+    is(code: IQAuthErrorCode): boolean;
+}
+declare const ErrorCodes: {
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly INVALID_CREDENTIALS: "INVALID_CREDENTIALS";
+    readonly ACCOUNT_INACTIVE: "ACCOUNT_INACTIVE";
+    readonly ACCOUNT_LOCKED: "ACCOUNT_LOCKED";
+    readonly INSUFFICIENT_PERMISSIONS: "INSUFFICIENT_PERMISSIONS";
+    readonly TOKEN_INVALID: "TOKEN_INVALID";
+    readonly TOKEN_EXPIRED: "TOKEN_EXPIRED";
+    readonly TOKEN_REVOKED: "TOKEN_REVOKED";
+    readonly USER_INACTIVE: "USER_INACTIVE";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly SESSION_INVALID: "SESSION_INVALID";
+    readonly SESSION_EXPIRED: "SESSION_EXPIRED";
+    readonly REFRESH_TOKEN_REUSED: "REFRESH_TOKEN_REUSED";
+    readonly PASSWORD_EXPIRED: "PASSWORD_EXPIRED";
+    readonly PIN_EXPIRED: "PIN_EXPIRED";
+    readonly PASSWORD_POLICY_VIOLATION: "PASSWORD_POLICY_VIOLATION";
+    readonly MFA_INVALID_CODE: "MFA_INVALID_CODE";
+    readonly MFA_METHOD_UNAVAILABLE: "MFA_METHOD_UNAVAILABLE";
+    readonly MFA_RATE_LIMITED: "MFA_RATE_LIMITED";
+    readonly MFA_ENROLLMENT_REQUIRED: "MFA_ENROLLMENT_REQUIRED";
+    readonly API_KEY_REQUIRED: "API_KEY_REQUIRED";
+    readonly API_KEY_INVALID: "API_KEY_INVALID";
+    readonly AUTH_REQUIRED: "AUTH_REQUIRED";
+    readonly ALREADY_EXISTS: "ALREADY_EXISTS";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly OAUTH_NOT_CONFIGURED: "OAUTH_NOT_CONFIGURED";
+    readonly UPLOAD_ERROR: "UPLOAD_ERROR";
+    readonly EMAIL_SERVICE_UNAVAILABLE: "EMAIL_SERVICE_UNAVAILABLE";
+    readonly INVALID_CODE: "INVALID_CODE";
+    readonly CODE_ALREADY_USED: "CODE_ALREADY_USED";
+    readonly CODE_EXPIRED: "CODE_EXPIRED";
+    readonly CODE_IP_MISMATCH: "CODE_IP_MISMATCH";
+    readonly UNKNOWN_PAYLOAD: "UNKNOWN_PAYLOAD";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
+export { ErrorCodes as E, IQAuthError as I, IQ_AUTH_ERROR_CODES as a, type ErrorCode as b, type IQAuthErrorCode as c };

package/dist/{express-B6_1vBYZ.d.mts → express-CVNQEkOr.d.mts}

@@ -1,5 +1,5 @@
-import { I as IQAuthClient } from './client-kYlJFgPv.mjs';
-import { J as JwtClaims, N as ExpressMiddlewareOptions, Q as IQAuthRequestLike, R as IQAuthResponseLike, V as IQAuthNextFunction } from './types-DZAflmmq.mjs';
+import { I as IQAuthClient } from './client-BGFnBpfc.mjs';
+import { J as JwtClaims, X as ExpressMiddlewareOptions, a as IQAuthRequestLike, b as IQAuthResponseLike, c as IQAuthNextFunction } from './types-XOV9XPVi.mjs';
 
 /**
  * SOURCE REFS:

package/dist/{express-CHpfa7D_.d.ts → express-Piv2WhWM.d.ts}

@@ -1,5 +1,5 @@
-import { I as IQAuthClient } from './client-BNQe3AgF.js';
-import { J as JwtClaims, N as ExpressMiddlewareOptions, Q as IQAuthRequestLike, R as IQAuthResponseLike, V as IQAuthNextFunction } from './types-DZAflmmq.js';
+import { I as IQAuthClient } from './client-CDQ21LvW.js';
+import { J as JwtClaims, X as ExpressMiddlewareOptions, a as IQAuthRequestLike, b as IQAuthResponseLike, c as IQAuthNextFunction } from './types-XOV9XPVi.js';
 
 /**
  * SOURCE REFS:

package/dist/express.d.mts

@@ -1,10 +1,10 @@
-import { I as IQAuthClient } from './client-kYlJFgPv.mjs';
-import { C as CookieAwareMiddlewareOptions } from './express-B6_1vBYZ.mjs';
-export { i as iqAuthMiddleware } from './express-B6_1vBYZ.mjs';
+import { I as IQAuthClient } from './client-BGFnBpfc.mjs';
+import { C as CookieAwareMiddlewareOptions } from './express-CVNQEkOr.mjs';
+export { i as iqAuthMiddleware } from './express-CVNQEkOr.mjs';
 import { IQAuthHelperConfig } from './server/handlers.mjs';
-import { Q as IQAuthRequestLike, R as IQAuthResponseLike, V as IQAuthNextFunction } from './types-DZAflmmq.mjs';
-export { E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.mjs';
-import './tokens-DCyzzn8L.mjs';
+import { a as IQAuthRequestLike, b as IQAuthResponseLike, c as IQAuthNextFunction } from './types-XOV9XPVi.mjs';
+export { E as ErrorCodes, I as IQAuthError } from './errors-Jl1Jtm-6.mjs';
+import './tokens-CITeoG6P.mjs';
 
 /**
  * @iqauth/sdk/express — drop-in Express adapter.
@@ -111,6 +111,7 @@ declare function iqAuth(options: IQAuthExpressOptions): {
     middleware: (req: IQAuthRequestLike, res: IQAuthResponseLike, next: IQAuthNextFunction) => void | Promise<void>;
     attachHelpers: (app: ExpressLikeApp | ExpressLikeRouter) => void;
     client: IQAuthClient;
+    prewarm: () => Promise<void>;
 };
 
 export { CookieAwareMiddlewareOptions, type IQAuthExpressOptions, type InlineCallbackBrandedConfig, type InlineCallbackBrandedRenderArgs, type InlineCallbackConfig, iqAuth };

package/dist/express.d.ts

@@ -1,10 +1,10 @@
-import { I as IQAuthClient } from './client-BNQe3AgF.js';
-import { C as CookieAwareMiddlewareOptions } from './express-CHpfa7D_.js';
-export { i as iqAuthMiddleware } from './express-CHpfa7D_.js';
+import { I as IQAuthClient } from './client-CDQ21LvW.js';
+import { C as CookieAwareMiddlewareOptions } from './express-Piv2WhWM.js';
+export { i as iqAuthMiddleware } from './express-Piv2WhWM.js';
 import { IQAuthHelperConfig } from './server/handlers.js';
-import { Q as IQAuthRequestLike, R as IQAuthResponseLike, V as IQAuthNextFunction } from './types-DZAflmmq.js';
-export { E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.js';
-import './tokens-aHiGFr_E.js';
+import { a as IQAuthRequestLike, b as IQAuthResponseLike, c as IQAuthNextFunction } from './types-XOV9XPVi.js';
+export { E as ErrorCodes, I as IQAuthError } from './errors-Jl1Jtm-6.js';
+import './tokens-Bqhmqq_R.js';
 
 /**
  * @iqauth/sdk/express — drop-in Express adapter.
@@ -111,6 +111,7 @@ declare function iqAuth(options: IQAuthExpressOptions): {
     middleware: (req: IQAuthRequestLike, res: IQAuthResponseLike, next: IQAuthNextFunction) => void | Promise<void>;
     attachHelpers: (app: ExpressLikeApp | ExpressLikeRouter) => void;
     client: IQAuthClient;
+    prewarm: () => Promise<void>;
 };
 
 export { CookieAwareMiddlewareOptions, type IQAuthExpressOptions, type InlineCallbackBrandedConfig, type InlineCallbackBrandedRenderArgs, type InlineCallbackConfig, iqAuth };