@iqauth/sdk 2.6.3 → 2.7.0

package/README.md

@@ -8,7 +8,7 @@
 
 The canonical TypeScript SDK for **IQAuthService** — DispositionIQ's multi-tenant identity and authorization platform. One package covers the React client, the four major Node frameworks (Express, Fastify, Hono, Next.js), native mobile, and headless service automation.
 
-> **New in 2.0.3** — `SessionManager` gains `serverManagedSession: true` for confidential-client apps, and the cookie-managed `/refresh` helper no longer wipes cookies on transient failures. See [What's new in 2.0.3](#whats-new-in-203).
+> **New in 2.7.0** — `IQAuthError` now exposes a typed `code` taxonomy (`token_expired`, `jwks_unavailable`, `rate_limited`, …) plus `err.is(code)` / `IQAuthError.isIQAuthError(value)` helpers, and `tokens.verify<T>()` accepts a custom-claims generic so the returned object is fully typed. Both changes are purely additive — existing `catch (e: Error)` and untyped `verify()` callers keep compiling. See [What's new in 2.7.0](#whats-new-in-270).
 
 ---
 
@@ -17,6 +17,8 @@ The canonical TypeScript SDK for **IQAuthService** — DispositionIQ's multi-ten
 - [Install](#install)
 - [Five-line integration](#five-line-integration)
 - [Pick your environment](#pick-your-environment)
+- [What's new in 2.7.0](#whats-new-in-270)
+- [What's new in 2.6.5](#whats-new-in-265)
 - [What's new in 2.6.2](#whats-new-in-262)
 - [What's new in 2.6.1](#whats-new-in-261)
 - [What's new in 2.0.3](#whats-new-in-203)
@@ -174,6 +176,121 @@ The SDK is not "one auth model for every environment". The safe pattern depends
 
 ---
 
+## What's new in 2.7.0
+
+### 1. Typed `IQAuthError` taxonomy
+
+Every SDK-originated throw now carries a `code` from a fixed 10-value union,
+so callers can stop string-matching on `err.message` or guessing whether
+`err.code` is upper-snake or lowercase. Two helpers ship alongside it:
+`IQAuthError.isIQAuthError(value)` (instanceof-safe across realms) and
+`err.is(code)` (narrow-friendly).
+
+```ts
+import { IQAuthError, type IQAuthErrorCode } from "@iqauth/sdk";
+
+try {
+  const claims = await client.tokens.verify(token);
+} catch (err) {
+  if (IQAuthError.isIQAuthError(err)) {
+    if (err.is("token_expired"))      return refreshAndRetry();
+    if (err.is("jwks_fetch_failed"))  return retryAfterBackoff();
+    if (err.is("rate_limited"))       return showRateLimitToast();
+    if (err.is("network"))            return showOfflineBanner();
+    if (err.is("config_invalid"))     throw err; // boot-time misconfig
+  }
+  throw err;
+}
+```
+
+The full union:
+
+```ts
+type IQAuthErrorCode =
+  | "token_expired"
+  | "token_invalid"
+  | "jwks_unavailable"
+  | "jwks_fetch_failed"
+  | "rate_limited"
+  | "network"
+  | "config_invalid"
+  | "app_not_found"
+  | "permission_denied"
+  | "unknown";
+```
+
+**Back-compat:** the field is widened to `IQAuthErrorCode | (string & {})`,
+so server-rethrown codes (`TOKEN_REVOKED`, `SESSION_EXPIRED_INACTIVITY`, …)
+still flow through unchanged. The framework adapters (`/express`,
+`/fastify`, `/hono`) map both upper-snake and the new lowercase codes to
+`401`, so this rollout is invisible to existing app code. `IQAuthError`
+also gains a `cause` accessor (alias for the legacy `raw`).
+
+See [`docs/error-handling.md`](./docs/error-handling.md) for the full
+recipe book.
+
+### 2. `IQAuthClaims<T>` generic on `tokens.verify`
+
+`verify()` now accepts a custom-claims generic so your app's bespoke
+claims show up *typed* on the result — no index-signature widening, no
+`as any`:
+
+```ts
+interface MyClaims { plan: "free" | "pro"; orgId: string }
+
+const claims = await client.tokens.verify<MyClaims>(token);
+//    ^? IQAuthBaseClaims & MyClaims & JwtClaims
+
+if (claims.plan === "pro") doProThing(claims.orgId);
+console.log(claims.tenantId, claims.sub); // base claims still typed
+```
+
+`IQAuthBaseClaims` is exported separately for callers composing their own
+envelope. `JwtClaims` continues to be exported and remains the return
+type of `tokens.decode()` / `tokens.getClaims()` for back-compat. Calls
+to `verify()` without a generic argument behave exactly as before.
+
+---
+
+## What's new in 2.6.5
+
+### Server-managed userinfo (`mountUserinfo: true`)
+
+The framework adapters can now auto-mount `GET /api/iqauth/me` so
+server-managed integrators don't have to hand-roll a userinfo handler
+that calls `tokens.verify` and shapes a `data.user` / `data.claims`
+envelope.
+
+```ts
+app.use(iqAuth({
+  publishableKey: process.env.IQAUTH_PUBLISHABLE_KEY!,
+  secretKey:     process.env.IQAUTH_SECRET_KEY!,
+  mountUserinfo: true,
+  // Optional — shallow-merged over the claim-derived SessionUser defaults.
+  userinfoEnricher: async (claims, req) => ({
+    name: await loadDisplayName(claims.sub),
+  }),
+}));
+```
+
+Returns the documented `UserinfoResponse` envelope —
+`{ success: true, data: { user, claims, tenantId } }` — which is exactly
+the shape the browser SDK's `SessionManager.bootstrap()` already accepts
+(`data.user` is preferred; `claimsToSessionUser(data.claims)` is the
+fallback). The token is read from `Authorization: Bearer …` OR the
+`iqauth_at` cookie; verification reuses a per-issuer cached
+`TokensModule` so JWKS fetches are amortized.
+
+Two new framework-neutral exports for integrators who'd rather mount
+their own route but still emit the canonical envelope:
+`buildUserinfoResponse(claims, { enrich? })` and
+`handleUserinfo(config, { accessToken, req? })`. Re-exported from both
+`@iqauth/sdk` and `@iqauth/sdk/server`. See the
+[Server-managed userinfo](#server-managed-userinfo) section below for
+the full reference.
+
+---
+
 ## What's new in 2.6.2
 
 ### Card grows responsively on desktop (no more phone-sized form)
@@ -381,6 +498,7 @@ app.use("/admin",
 | `GET`  | `/api/iqauth/callback` | Receives the OIDC redirect, exchanges the code, sets `iqauth_at` + `iqauth_rt`, redirects to `return_to` |
 | `POST` | `/api/iqauth/refresh`  | Reads `iqauth_rt`, rotates, sets new cookies. Honors `clearCookiesOnRefreshFailure` |
 | `POST` | `/api/iqauth/signout`  | Revokes the refresh token upstream and clears both cookies |
+| `GET`  | `/api/iqauth/me`       | **Opt-in via `mountUserinfo: true`.** Verifies the access token and returns the documented userinfo envelope. See [Server-managed userinfo](#server-managed-userinfo) |
 
 All three set cookies with `HttpOnly; Secure; SameSite=lax; Path=/` by default. Override per-app:
 
@@ -398,6 +516,60 @@ iqAuth({
 
 ---
 
+### Server-managed userinfo
+
+When you're doing the cookie-managed pattern (browser SDK proxies through
+your own backend), your frontend needs *some* endpoint to learn "who am I"
+on first paint. Before 2.6.5 you had to hand-roll that handler — call
+`tokens.verify`, shape a `data.user` envelope, and remember to read the
+token from either `Authorization: Bearer …` OR the `iqauth_at` cookie.
+
+Opt into the auto-mounted route instead:
+
+```ts
+app.use(iqAuth({
+  publishableKey: process.env.IQAUTH_PUBLISHABLE_KEY!,
+  secretKey:     process.env.IQAUTH_SECRET_KEY!,
+  mountUserinfo: true,
+  // Optional — shallow-merged over the claim-derived SessionUser defaults.
+  userinfoEnricher: async (claims, req) => ({
+    name: await loadDisplayName(claims.sub),
+  }),
+}));
+```
+
+`GET /api/iqauth/me` returns the documented `UserinfoResponse` envelope:
+
+```jsonc
+{
+  "success": true,
+  "data": {
+    "user":     { "sub": "...", "email": "...", "name": "...", "tenantId": "...", "roles": [...], "entitlements": [...] },
+    "claims":   { /* full verified JWT payload */ },
+    "tenantId": "ten_..." // or null
+  }
+}
+```
+
+This is exactly the shape `SessionManager.bootstrap()` already accepts:
+`data.user` is preferred when present, `claimsToSessionUser(data.claims)`
+is the documented fallback. Same option works on Express, Fastify, Hono,
+and the Next.js handler. Token is verified with a per-issuer cached
+`TokensModule` so JWKS fetches are amortized across requests.
+
+Want to mount your own route but still emit the canonical envelope? Use
+the framework-neutral helpers:
+
+```ts
+import { buildUserinfoResponse, type UserinfoResponse } from "@iqauth/sdk/server";
+
+const envelope: UserinfoResponse = await buildUserinfoResponse(verifiedClaims, {
+  enrich: (c) => ({ name: lookupName(c.sub) }),
+});
+```
+
+---
+
 ## Token verification without a framework adapter
 
 If you're not using Express/Fastify/Hono/Next (custom Node server, AWS Lambda, Cloudflare Worker, etc.):

package/dist/browser-session.d.mts

@@ -1,7 +1,7 @@
-import { c as IQAuthBrowserSessionClientConfig, d as SessionUser } from './types-DZAflmmq.mjs';
-import { I as IQAuthClient } from './client-kYlJFgPv.mjs';
-export { E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.mjs';
-import './tokens-DCyzzn8L.mjs';
+import { I as IQAuthBrowserSessionClientConfig, S as SessionUser } from './types-XOV9XPVi.mjs';
+import { I as IQAuthClient } from './client-BGFnBpfc.mjs';
+export { E as ErrorCodes, I as IQAuthError } from './errors-Jl1Jtm-6.mjs';
+import './tokens-CITeoG6P.mjs';
 
 declare class BrowserSessionIQAuthClient extends IQAuthClient {
     constructor(config: Omit<IQAuthBrowserSessionClientConfig, "environment">);

package/dist/browser-session.d.ts

@@ -1,7 +1,7 @@
-import { c as IQAuthBrowserSessionClientConfig, d as SessionUser } from './types-DZAflmmq.js';
-import { I as IQAuthClient } from './client-BNQe3AgF.js';
-export { E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.js';
-import './tokens-aHiGFr_E.js';
+import { I as IQAuthBrowserSessionClientConfig, S as SessionUser } from './types-XOV9XPVi.js';
+import { I as IQAuthClient } from './client-CDQ21LvW.js';
+export { E as ErrorCodes, I as IQAuthError } from './errors-Jl1Jtm-6.js';
+import './tokens-Bqhmqq_R.js';
 
 declare class BrowserSessionIQAuthClient extends IQAuthClient {
     constructor(config: Omit<IQAuthBrowserSessionClientConfig, "environment">);

package/dist/browser-session.js

@@ -39,13 +39,30 @@ __export(browser_session_exports, {
 module.exports = __toCommonJS(browser_session_exports);
 
 // src/errors.ts
-var IQAuthError = class extends Error {
-  constructor(code, message, status, raw) {
+var IQAuthError = class _IQAuthError extends Error {
+  constructor(code, message, status, cause) {
     super(message);
     this.name = "IQAuthError";
     this.code = code;
     this.status = status;
-    this.raw = raw;
+    this.cause = cause;
+    this.raw = cause;
+  }
+  /**
+   * 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) {
+    return value instanceof _IQAuthError || typeof value === "object" && value !== null && value.name === "IQAuthError" && typeof value.code === "string";
+  }
+  /**
+   * 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) {
+    return this.code === code;
   }
 };
 var ErrorCodes = {
@@ -196,7 +213,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 }) };
           })()
         });
@@ -213,7 +230,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,
@@ -231,7 +248,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}`;
@@ -459,6 +476,18 @@ var DEFAULT_TOKEN_AUDIENCE = [
   "iqvalidate"
 ];
 var DEFAULT_CLOCK_TOLERANCE_SECONDS = 30;
+function classifyJoseError(err) {
+  if (err instanceof import_jose.errors.JWTExpired) {
+    return { code: "token_expired", message: "Token has expired" };
+  }
+  if (err instanceof import_jose.errors.JOSEError) {
+    return { code: "token_invalid", message: err.message };
+  }
+  if (err instanceof Error) {
+    return { code: "token_invalid", message: err.message };
+  }
+  return { code: "token_invalid", message: "Token verification failed" };
+}
 function decodeProtectedHeader(token) {
   const parts = token.split(".");
   if (parts.length < 2) return null;
@@ -495,11 +524,11 @@ var TokensModule = class {
   async verify(token, options = {}) {
     const header = decodeProtectedHeader(token);
     if (!header) {
-      throw new IQAuthError("TOKEN_INVALID", "Unable to decode token");
+      throw new IQAuthError("token_invalid", "Unable to decode token");
     }
     const kid = header.kid;
     if (!kid) {
-      throw new IQAuthError("TOKEN_INVALID", "Token missing kid header");
+      throw new IQAuthError("token_invalid", "Token missing kid header");
     }
     let cache = await this.ensureCache();
     if (!cache.byKid.has(kid)) {
@@ -507,7 +536,7 @@ var TokensModule = class {
       cache = await this.ensureCache();
     }
     if (!cache.byKid.has(kid)) {
-      throw new IQAuthError("TOKEN_INVALID", `Unknown key ID: ${kid}`);
+      throw new IQAuthError("token_invalid", `Unknown key ID: ${kid}`);
     }
     const issuer = options.issuer ?? this.defaultIssuer;
     const audience = options.audience ?? this.defaultAudience;
@@ -523,16 +552,8 @@ var TokensModule = class {
       const { payload } = await (0, import_jose.jwtVerify)(token, cache.verifier, verifyOptions);
       return payload;
     } catch (err) {
-      if (err instanceof import_jose.errors.JWTExpired) {
-        throw new IQAuthError("TOKEN_EXPIRED", "Token has expired");
-      }
-      if (err instanceof import_jose.errors.JOSEError) {
-        throw new IQAuthError("TOKEN_INVALID", err.message);
-      }
-      if (err instanceof Error) {
-        throw new IQAuthError("TOKEN_INVALID", err.message);
-      }
-      throw new IQAuthError("TOKEN_INVALID", "Token verification failed");
+      const classified = classifyJoseError(err);
+      throw new IQAuthError(classified.code, classified.message, void 0, err);
     }
   }
   /**
@@ -574,7 +595,7 @@ var TokensModule = class {
   getClaims(token) {
     const claims = this.decode(token);
     if (!claims) {
-      throw new IQAuthError("TOKEN_INVALID", "Unable to decode token claims");
+      throw new IQAuthError("token_invalid", "Unable to decode token claims");
     }
     return claims;
   }
@@ -584,7 +605,7 @@ var TokensModule = class {
     }
     await this.refreshJwks();
     if (!this.jwksCache) {
-      throw new IQAuthError("INTERNAL_ERROR", "JWKS cache unavailable after refresh");
+      throw new IQAuthError("jwks_unavailable", "JWKS cache unavailable after refresh");
     }
     return this.jwksCache;
   }
@@ -594,22 +615,38 @@ var TokensModule = class {
     }
     this.inFlightRefresh = (async () => {
       try {
-        const res = await fetch(`${this.baseUrl}/.well-known/jwks.json`);
+        let res;
+        try {
+          res = await fetch(`${this.baseUrl}/.well-known/jwks.json`);
+        } catch (err) {
+          throw new IQAuthError(
+            "network",
+            err instanceof Error ? err.message : "JWKS fetch network error",
+            void 0,
+            err
+          );
+        }
         if (!res.ok) {
           throw new IQAuthError(
-            "INTERNAL_ERROR",
-            `Failed to fetch JWKS: ${res.status}`
+            "jwks_fetch_failed",
+            `Failed to fetch JWKS: ${res.status}`,
+            res.status
           );
         }
         let jwks;
         try {
           jwks = await res.json();
-        } catch {
-          throw new IQAuthError("INTERNAL_ERROR", "Malformed JWKS response: invalid JSON");
+        } catch (err) {
+          throw new IQAuthError(
+            "jwks_fetch_failed",
+            "Malformed JWKS response: invalid JSON",
+            res.status,
+            err
+          );
         }
         if (!jwks || !Array.isArray(jwks.keys)) {
           throw new IQAuthError(
-            "INTERNAL_ERROR",
+            "jwks_fetch_failed",
             "Malformed JWKS response: expected { keys: [...] }"
           );
         }
@@ -617,7 +654,7 @@ var TokensModule = class {
         for (const key of jwks.keys) {
           if (!key || typeof key.kid !== "string" || typeof key.n !== "string" && typeof key.x !== "string" || key.kty === "RSA" && (typeof key.n !== "string" || typeof key.e !== "string")) {
             throw new IQAuthError(
-              "INTERNAL_ERROR",
+              "jwks_fetch_failed",
               "Malformed JWKS response: key missing required fields"
             );
           }
@@ -635,6 +672,19 @@ var TokensModule = class {
   clearCache() {
     this.jwksCache = null;
   }
+  /**
+   * Task #126: Eagerly populate the JWKS cache so the first verify() call
+   * doesn't pay a network round-trip. Safe to call repeatedly — single-flight
+   * behavior is shared with the lazy refresh path. Errors are swallowed so
+   * callers (e.g. `attachHelpers` auto-prewarm) can fire-and-forget.
+   */
+  async prewarm() {
+    if (this.jwksCache && Date.now() - this.jwksCache.fetchedAt <= JWKS_CACHE_TTL_MS) return;
+    try {
+      await this.refreshJwks();
+    } catch {
+    }
+  }
 };
 
 // src/modules/sessions.ts
@@ -958,14 +1008,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 {
@@ -983,7 +1033,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"
         );
       }
@@ -994,7 +1044,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"
         );
       }
@@ -1195,6 +1245,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)}`);
   }
   /**
@@ -1214,6 +1267,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);
   }
   /**
@@ -1223,11 +1286,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;
@@ -1264,6 +1330,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;
@@ -1284,7 +1364,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}`);
@@ -1308,21 +1395,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
@@ -1747,6 +1864,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,
@@ -1787,6 +1908,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" });
   }
@@ -1803,6 +1931,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/browser-session.mjs

@@ -1,11 +1,11 @@
 import {
   IQAuthClient
-} from "./chunk-W3F4JYGP.mjs";
-import "./chunk-UNYDG2L4.mjs";
+} from "./chunk-JXQI62A7.mjs";
+import "./chunk-NUO2I65G.mjs";
 import {
   ErrorCodes,
   IQAuthError
-} from "./chunk-6I6RM4MN.mjs";
+} from "./chunk-6PJRLRB4.mjs";
 import "./chunk-Y6FXYEAI.mjs";
 
 // src/browser-session.ts