@iqauth/sdk 2.6.4 → 2.8.1

package/dist/fastify.js

@@ -36,13 +36,30 @@ __export(fastify_exports, {
 module.exports = __toCommonJS(fastify_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;
   }
 };
 
@@ -157,7 +174,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 }) };
           })()
         });
@@ -174,7 +191,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,
@@ -192,7 +209,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}`;
@@ -279,17 +296,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());
@@ -327,13 +354,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 }
     );
@@ -420,6 +463,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;
@@ -456,11 +511,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)) {
@@ -468,7 +523,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;
@@ -484,16 +539,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);
     }
   }
   /**
@@ -535,7 +582,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;
   }
@@ -545,7 +592,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;
   }
@@ -555,22 +602,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: [...] }"
           );
         }
@@ -578,7 +641,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"
             );
           }
@@ -596,6 +659,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
@@ -919,14 +995,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 {
@@ -944,7 +1020,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"
         );
       }
@@ -955,7 +1031,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"
         );
       }
@@ -1156,6 +1232,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)}`);
   }
   /**
@@ -1175,6 +1254,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);
   }
   /**
@@ -1184,11 +1273,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;
@@ -1225,6 +1317,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;
@@ -1245,7 +1351,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}`);
@@ -1269,21 +1382,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
@@ -1708,6 +1851,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,
@@ -1748,6 +1895,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" });
   }
@@ -1764,6 +1918,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);
@@ -1804,14 +1970,14 @@ function assertPublishableKey(raw, opts) {
   const ctx = opts?.context ? `${opts.context}: ` : "";
   if (typeof raw !== "string" || raw.length === 0) {
     throw new IQAuthError(
-      "CONFIG_INVALID",
+      "config_invalid",
       `${ctx}IQAuth publishable key is missing. Set IQAUTH_PUBLISHABLE_KEY (or pass publishableKey) to a pk_test_\u2026 or pk_live_\u2026 value from the IQAuth admin console.`
     );
   }
   const shapeMatch = raw.match(/^pk_(test|live)_([A-Za-z0-9_-]+)$/);
   if (!shapeMatch) {
     throw new IQAuthError(
-      "CONFIG_INVALID",
+      "config_invalid",
       `${ctx}IQAuth publishable key is malformed (got ${raw.slice(0, 12)}\u2026). Expected pk_test_\u2026 or pk_live_\u2026; regenerate the key from the IQAuth admin console.`
     );
   }
@@ -1820,19 +1986,19 @@ function assertPublishableKey(raw, opts) {
     decoded = JSON.parse(b64urlDecode(shapeMatch[2]));
   } catch {
     throw new IQAuthError(
-      "CONFIG_INVALID",
+      "config_invalid",
       `${ctx}IQAuth publishable key payload is not valid base64url JSON. Regenerate the key from the IQAuth admin console.`
     );
   }
   if (!isPublishableKeyPayload(decoded)) {
     throw new IQAuthError(
-      "CONFIG_INVALID",
+      "config_invalid",
       `${ctx}IQAuth publishable key payload is missing required fields {iss, appId, tenantId, kid}. Regenerate the key from the IQAuth admin console.`
     );
   }
   if (!isValidIssuerUrl(decoded.iss)) {
     throw new IQAuthError(
-      "CONFIG_INVALID",
+      "config_invalid",
       `${ctx}IQAuth publishable key encodes an invalid issuer (iss=${JSON.stringify(decoded.iss)}). Expected a fully-qualified URL like "https://auth.example.com" (scheme required). Regenerate the key from the IQAuth admin console \u2014 the new key will encode a valid issuer URL.`
     );
   }
@@ -1845,6 +2011,45 @@ function isPublishableKeyPayload(value) {
 }
 
 // src/server/handlers.ts
+async function buildUserinfoResponse(claims, opts = {}) {
+  const baseUser = {
+    sub: claims.sub,
+    email: claims.email,
+    name: claims.name,
+    tenantId: claims.tenantId,
+    vendorId: claims.vendorId,
+    roles: claims.roles ?? [],
+    entitlements: claims.entitlements ?? [],
+    // Task #171 — project the active source/client scope onto the userinfo
+    // payload so server handlers (`getSessionUser`, `/api/iqauth/userinfo`)
+    // expose it without consumers having to re-decode the JWT.
+    ...claims.scopeContext !== void 0 ? { scopeContext: claims.scopeContext } : {}
+  };
+  const enriched = opts.enrich ? await opts.enrich(claims) : null;
+  const user = enriched ? { ...baseUser, ...enriched } : baseUser;
+  return {
+    success: true,
+    data: {
+      user,
+      claims,
+      tenantId: claims.tenantId ?? null
+    }
+  };
+}
+function emitTiming(cfg, event) {
+  if (cfg.debug) {
+    try {
+      console.debug("[iqauth_helper]", event);
+    } catch {
+    }
+  }
+  if (cfg.onTimingEvent) {
+    try {
+      cfg.onTimingEvent(event);
+    } catch {
+    }
+  }
+}
 var TERMINAL_REFRESH_ERROR_CODES = /* @__PURE__ */ new Set([
   "TOKEN_REVOKED",
   "SESSION_REVOKED",
@@ -1863,19 +2068,62 @@ function shouldClearCookiesOnFailure(policy, status, errorCode) {
 }
 var ACCESS_TOKEN_TTL_SECONDS = 60 * 15;
 var REFRESH_TOKEN_TTL_SECONDS = 60 * 60 * 24 * 30;
+function assertCookiePrefixInvariants(name, secure, path, domain) {
+  if (name.startsWith("__Host-")) {
+    if (!secure) {
+      throw new IQAuthError(
+        "config_invalid",
+        `Cookie "${name}" uses the __Host- prefix, which browsers only accept on a Secure cookie. Set secure:true (and serve over HTTPS).`
+      );
+    }
+    if (path !== "/") {
+      throw new IQAuthError(
+        "config_invalid",
+        `Cookie "${name}" uses the __Host- prefix, which requires Path=/ (got "${path}"). Remove cookiePath or set it to "/".`
+      );
+    }
+    if (domain) {
+      throw new IQAuthError(
+        "config_invalid",
+        `Cookie "${name}" uses the __Host- prefix, which forbids a Domain attribute (the cookie is host-locked). Remove cookieDomain.`
+      );
+    }
+  } else if (name.startsWith("__Secure-") && !secure) {
+    throw new IQAuthError(
+      "config_invalid",
+      `Cookie "${name}" uses the __Secure- prefix, which browsers only accept on a Secure cookie. Set secure:true (and serve over HTTPS).`
+    );
+  }
+}
 function resolve(config) {
   const parsed = assertPublishableKey(config.publishableKey, { context: "@iqauth/sdk helpers" });
   const inferredIssuer = parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`;
+  maybeWarnDefaultSignoutRegistry(config);
+  const secure = config.secure ?? true;
+  if (config.secure === false && config.allowInsecureCookies !== true) {
+    throw new IQAuthError(
+      "config_invalid",
+      "Refusing to issue auth cookies with secure:false \u2014 this exposes session cookies over plaintext HTTP. For local HTTP development, set allowInsecureCookies:true to acknowledge the risk. Production MUST use HTTPS with secure cookies."
+    );
+  }
+  const accessCookieName = config.accessCookieName ?? config.cookieNames?.access ?? "iqauth_at";
+  const refreshCookieName = config.refreshCookieName ?? config.cookieNames?.refresh ?? "iqauth_rt";
+  const stateCookieName = config.stateCookieName ?? "iqauth_state";
+  const cookiePath = config.cookiePath ?? "/";
+  const cookieDomain = config.cookieDomain;
+  for (const name of [accessCookieName, refreshCookieName, stateCookieName]) {
+    assertCookiePrefixInvariants(name, secure, cookiePath, cookieDomain);
+  }
   return {
     publishableKey: config.publishableKey,
     secretKey: config.secretKey,
     issuer: (config.issuer ?? inferredIssuer).replace(/\/+$/, ""),
-    accessCookieName: config.accessCookieName ?? config.cookieNames?.access ?? "iqauth_at",
-    refreshCookieName: config.refreshCookieName ?? config.cookieNames?.refresh ?? "iqauth_rt",
-    cookieDomain: config.cookieDomain,
+    accessCookieName,
+    refreshCookieName,
+    cookieDomain,
     sameSite: config.sameSite ?? "lax",
-    secure: config.secure ?? true,
-    cookiePath: config.cookiePath ?? "/",
+    secure,
+    cookiePath,
     tokenPath: config.tokenPath ?? "/oidc/token",
     refreshPath: config.refreshPath ?? "/api/v1/auth/refresh",
     logoutPath: config.logoutPath ?? "/api/v1/auth/logout",
@@ -1884,9 +2132,23 @@ function resolve(config) {
     })),
     appId: parsed.appId,
     tenantId: parsed.tenantId,
-    clearCookiesOnRefreshFailure: config.clearCookiesOnRefreshFailure ?? "terminal-only"
+    clearCookiesOnRefreshFailure: config.clearCookiesOnRefreshFailure ?? "terminal-only",
+    debug: config.debug,
+    onTimingEvent: config.onTimingEvent,
+    signoutRegistry: config.signoutRegistry ?? defaultSignoutRegistry,
+    signoutMarkerTtlMs: config.signoutMarkerTtlMs ?? DEFAULT_SIGNOUT_TTL_MS,
+    requireOAuthState: config.requireOAuthState ?? true,
+    stateCookieName: config.stateCookieName ?? "iqauth_state"
   };
 }
+function timingSafeEqualStr(a, b) {
+  const len = Math.max(a.length, b.length);
+  let diff = a.length ^ b.length;
+  for (let i = 0; i < len; i++) {
+    diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
+  }
+  return diff === 0;
+}
 function makeCookie(cfg, name, value, maxAge, httpOnly = true) {
   return {
     name,
@@ -1901,15 +2163,53 @@ function makeCookie(cfg, name, value, maxAge, httpOnly = true) {
 }
 function clearCookies(cfg) {
   return [
-    makeCookie(cfg, cfg.accessCookieName, "", 0),
-    makeCookie(cfg, cfg.refreshCookieName, "", 0)
+    { ...makeCookie(cfg, cfg.accessCookieName, "", 0), clear: true },
+    { ...makeCookie(cfg, cfg.refreshCookieName, "", 0), clear: true }
   ];
 }
+function clearStateCookie(cfg) {
+  return { ...makeCookie(cfg, cfg.stateCookieName, "", 0, false), clear: true };
+}
+var DEFAULT_SIGNOUT_TTL_MS = 6e4;
+var inMemorySignoutMarkers = /* @__PURE__ */ new Map();
+function pruneInMemoryMarkers(now) {
+  if (inMemorySignoutMarkers.size === 0) return;
+  for (const [k, exp] of inMemorySignoutMarkers) {
+    if (exp <= now) inMemorySignoutMarkers.delete(k);
+  }
+}
+var defaultSignoutRegistry = {
+  mark(token, ttlMs) {
+    const now = Date.now();
+    pruneInMemoryMarkers(now);
+    inMemorySignoutMarkers.set(token, now + ttlMs);
+  },
+  has(token) {
+    const now = Date.now();
+    const exp = inMemorySignoutMarkers.get(token);
+    if (!exp) return false;
+    if (exp <= now) {
+      inMemorySignoutMarkers.delete(token);
+      return false;
+    }
+    return true;
+  }
+};
+var warnedDefaultSignoutRegistry = false;
+function maybeWarnDefaultSignoutRegistry(config) {
+  if (warnedDefaultSignoutRegistry) return;
+  if (config.signoutRegistry) return;
+  warnedDefaultSignoutRegistry = true;
+  console.warn(
+    "[IQAuth] Using the in-memory signout registry (process-local). Signout idempotency is NOT shared across instances \u2014 in a multi-replica deployment a /refresh racing a /signout on another replica can reissue cookies after sign-out. Plug a shared backend (e.g. Redis) into IQAuthHelperConfig.signoutRegistry to fix this and silence this warning."
+  );
+}
 function serializeCookie(d) {
   const parts = [`${d.name}=${encodeURIComponent(d.value)}`];
   parts.push(`Path=${d.path}`);
   if (d.domain) parts.push(`Domain=${d.domain}`);
   parts.push(`Max-Age=${d.maxAge}`);
+  if (d.clear) parts.push("Expires=Thu, 01 Jan 1970 00:00:00 GMT");
   if (d.secure) parts.push("Secure");
   if (d.httpOnly) parts.push("HttpOnly");
   parts.push(`SameSite=${d.sameSite}`);
@@ -1917,14 +2217,34 @@ function serializeCookie(d) {
 }
 async function handleCallback(config, input) {
   const cfg = resolve(config);
+  const t0 = Date.now();
   if (!input.code || !input.redirectUri) {
+    emitTiming(cfg, { phase: "callback", durationMs: Date.now() - t0, ok: false, code: "VALIDATION_ERROR" });
     return {
       status: 400,
       body: { success: false, error: { code: "VALIDATION_ERROR", message: "code and redirectUri are required" } },
       cookies: []
     };
   }
+  const provided = input.state;
+  const expected = input.expectedState;
+  const stateOk = cfg.requireOAuthState ? !!expected && !!provided && timingSafeEqualStr(provided, expected) : !expected || !!provided && timingSafeEqualStr(provided, expected);
+  if (!stateOk) {
+    emitTiming(cfg, { phase: "callback", durationMs: Date.now() - t0, ok: false, code: "STATE_MISMATCH" });
+    return {
+      status: 400,
+      body: {
+        success: false,
+        error: {
+          code: "STATE_MISMATCH",
+          message: "OAuth state validation failed; the sign-in could not be verified as originating from this browser."
+        }
+      },
+      cookies: [clearStateCookie(cfg)]
+    };
+  }
   if (!cfg.secretKey) {
+    emitTiming(cfg, { phase: "callback", durationMs: Date.now() - t0, ok: false, code: "INTERNAL_ERROR" });
     return {
       status: 500,
       body: { success: false, error: { code: "INTERNAL_ERROR", message: "secretKey is required for the callback handler" } },
@@ -1948,6 +2268,7 @@ async function handleCallback(config, input) {
   });
   const json = await res.json().catch(() => ({}));
   if (!res.ok || !json.access_token) {
+    emitTiming(cfg, { phase: "callback", durationMs: Date.now() - t0, ok: false, code: json.error || "OIDC_EXCHANGE_FAILED" });
     return {
       status: res.status || 502,
       body: {
@@ -1960,6 +2281,26 @@ async function handleCallback(config, input) {
       cookies: []
     };
   }
+  try {
+    await getTokensFor(cfg.issuer).verify(json.access_token, {
+      issuer: cfg.issuer,
+      ...config.verify
+    });
+  } catch (err) {
+    const code = err instanceof IQAuthError ? err.code : err.code || "TOKEN_INVALID";
+    emitTiming(cfg, { phase: "callback", durationMs: Date.now() - t0, ok: false, code });
+    return {
+      status: 502,
+      body: {
+        success: false,
+        error: {
+          code: "ACCESS_TOKEN_VERIFICATION_FAILED",
+          message: "The issuer returned an access token that failed verification; no session was established."
+        }
+      },
+      cookies: []
+    };
+  }
   const cookies = [];
   cookies.push(
     makeCookie(cfg, cfg.accessCookieName, json.access_token, json.expires_in ?? ACCESS_TOKEN_TTL_SECONDS)
@@ -1967,6 +2308,8 @@ async function handleCallback(config, input) {
   if (json.refresh_token) {
     cookies.push(makeCookie(cfg, cfg.refreshCookieName, json.refresh_token, REFRESH_TOKEN_TTL_SECONDS));
   }
+  cookies.push(clearStateCookie(cfg));
+  emitTiming(cfg, { phase: "callback", durationMs: Date.now() - t0, ok: true });
   return {
     status: 200,
     body: { success: true, data: { authenticated: true } },
@@ -1975,8 +2318,18 @@ async function handleCallback(config, input) {
 }
 async function handleRefresh(config, input) {
   const cfg = resolve(config);
+  const t0 = Date.now();
   const refreshToken = input.refreshToken;
+  const idemKey = input.idempotencyToken;
+  if (idemKey && await Promise.resolve(cfg.signoutRegistry.has(idemKey))) {
+    return {
+      status: 401,
+      body: { success: false, error: { code: "SESSION_REVOKED", message: "Session was signed out" } },
+      cookies: clearCookies(cfg)
+    };
+  }
   if (!refreshToken) {
+    emitTiming(cfg, { phase: "refresh", durationMs: Date.now() - t0, ok: false, code: "TOKEN_INVALID" });
     return {
       status: 401,
       body: { success: false, error: { code: "TOKEN_INVALID", message: "Missing refresh token" } },
@@ -1992,6 +2345,7 @@ async function handleRefresh(config, input) {
   if (!res.ok || !json.success || !json.data?.accessToken) {
     const status = res.status || 401;
     const errorCode = json.error?.code || "TOKEN_INVALID";
+    emitTiming(cfg, { phase: "refresh", durationMs: Date.now() - t0, ok: false, code: errorCode });
     const shouldClear = shouldClearCookiesOnFailure(
       cfg.clearCookiesOnRefreshFailure,
       status,
@@ -2015,6 +2369,7 @@ async function handleRefresh(config, input) {
   if (json.data.refreshToken) {
     cookies.push(makeCookie(cfg, cfg.refreshCookieName, json.data.refreshToken, REFRESH_TOKEN_TTL_SECONDS));
   }
+  emitTiming(cfg, { phase: "refresh", durationMs: Date.now() - t0, ok: true });
   return {
     status: 200,
     body: { success: true, data: { accessToken: json.data.accessToken } },
@@ -2023,6 +2378,10 @@ async function handleRefresh(config, input) {
 }
 async function handleSignout(config, input) {
   const cfg = resolve(config);
+  const t0 = Date.now();
+  if (input.idempotencyToken) {
+    await Promise.resolve(cfg.signoutRegistry.mark(input.idempotencyToken, cfg.signoutMarkerTtlMs));
+  }
   if (input.accessToken) {
     try {
       await cfg.fetchImpl(`${cfg.issuer}${cfg.logoutPath}`, {
@@ -2044,21 +2403,104 @@ async function handleSignout(config, input) {
     } catch {
     }
   }
+  emitTiming(cfg, { phase: "signout", durationMs: Date.now() - t0, ok: true });
   return {
     status: 200,
     body: { success: true, data: { signedOut: true } },
     cookies: clearCookies(cfg)
   };
 }
+var TOKENS_CACHE = /* @__PURE__ */ new Map();
+function getTokensFor(issuer) {
+  let m = TOKENS_CACHE.get(issuer);
+  if (!m) {
+    m = new TokensModule(issuer);
+    TOKENS_CACHE.set(issuer, m);
+  }
+  return m;
+}
+async function handleUserinfo(config, input) {
+  const cfg = resolve(config);
+  if (!input.accessToken) {
+    return {
+      status: 401,
+      body: { success: false, error: { code: "TOKEN_INVALID", message: "Missing access token" } },
+      cookies: []
+    };
+  }
+  let claims;
+  try {
+    claims = await getTokensFor(cfg.issuer).verify(input.accessToken, {
+      issuer: cfg.issuer,
+      ...config.verify
+    });
+  } catch (err) {
+    const code = err instanceof IQAuthError ? err.code : err.code || "TOKEN_INVALID";
+    const message = err instanceof Error ? err.message : "Access token verification failed";
+    return {
+      status: 401,
+      body: { success: false, error: { code, message } },
+      cookies: []
+    };
+  }
+  const envelope = await buildUserinfoResponse(claims, {
+    enrich: config.userinfoEnricher ? (c) => config.userinfoEnricher(c, input.req) : void 0
+  });
+  return {
+    status: 200,
+    body: envelope,
+    cookies: []
+  };
+}
+
+// src/browser/returnTo.ts
+function normalizeOrigin(o) {
+  try {
+    return new URL(o).origin;
+  } catch {
+    return o.replace(/\/+$/, "");
+  }
+}
+function sanitizeReturnTo(input, options = {}) {
+  const fallback = options.fallback ?? "/";
+  if (!input || typeof input !== "string") return fallback;
+  const trimmed = input.trim();
+  if (!trimmed) return fallback;
+  if (trimmed.includes("\\")) return fallback;
+  if (trimmed.startsWith("//")) return fallback;
+  if (trimmed.startsWith("/") || trimmed.startsWith("#") || trimmed.startsWith("?")) {
+    return trimmed;
+  }
+  if (!/^[a-z][a-z0-9+\-.]*:/i.test(trimmed)) {
+    return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  }
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return fallback;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return fallback;
+  const currentOrigin = options.currentOrigin ?? (typeof window !== "undefined" ? window.location.origin : "");
+  const allowed = /* @__PURE__ */ new Set();
+  if (currentOrigin) allowed.add(normalizeOrigin(currentOrigin));
+  for (const o of options.allowedOrigins ?? []) allowed.add(normalizeOrigin(o));
+  if (allowed.has(parsed.origin)) return parsed.toString();
+  return fallback;
+}
 
 // src/fastify.ts
+var PKCE_COOKIE = "iqauth_pkce";
 var KNOWN_AUTH_ERRORS = /* @__PURE__ */ new Set([
   "TOKEN_INVALID",
   "TOKEN_EXPIRED",
   "TOKEN_REVOKED",
   "SESSION_EXPIRED",
   "SESSION_INVALID",
-  "AUTH_REQUIRED"
+  "AUTH_REQUIRED",
+  // Task #127 — typed `IQAuthErrorCode` taxonomy.
+  "token_invalid",
+  "token_expired"
 ]);
 function applyResponse(reply, hr) {
   for (const c of hr.cookies) {
@@ -2070,6 +2512,54 @@ function applyResponse(reply, hr) {
   }
   reply.code(hr.status).send(hr.body);
 }
+function applyCallbackResponse(reply, hr, requestOrigin, returnToCookieValue, returnToCookieName) {
+  const returnTo = sanitizeReturnTo(
+    returnToCookieValue || hr.body?.returnTo,
+    { currentOrigin: requestOrigin, fallback: "/" }
+  );
+  for (const c of hr.cookies) {
+    const cookie = serializeCookie(c);
+    const existing = reply.getHeader?.("set-cookie") ?? [];
+    const list = Array.isArray(existing) ? existing : [existing];
+    list.push(cookie);
+    reply.header("set-cookie", list);
+  }
+  if (hr.status < 400) {
+    const existing = reply.getHeader?.("set-cookie") ?? [];
+    const list = Array.isArray(existing) ? existing : [existing];
+    list.push(`${returnToCookieName}=; Path=/; Max-Age=0; SameSite=Lax`);
+    reply.header("set-cookie", list);
+  }
+  reply.code(hr.status).send({ ...hr.body, returnTo });
+}
+function applyCallbackRedirect(reply, hr, requestOrigin, returnToCookieValue, cookieNames) {
+  const pushCookie = (value) => {
+    const existing = reply.getHeader?.("set-cookie") ?? [];
+    const list = Array.isArray(existing) ? existing : [existing];
+    list.push(value);
+    reply.header("set-cookie", list);
+  };
+  for (const c of hr.cookies) pushCookie(serializeCookie(c));
+  pushCookie(`${cookieNames.state}=; Path=/; Max-Age=0; SameSite=Lax`);
+  pushCookie(`${cookieNames.pkce}=; Path=/; Max-Age=0; SameSite=Lax`);
+  if (hr.status >= 400) {
+    reply.header("location", "/");
+    reply.code(302).send();
+    return;
+  }
+  const dest = sanitizeReturnTo(returnToCookieValue, {
+    currentOrigin: requestOrigin,
+    fallback: "/"
+  });
+  pushCookie(`${cookieNames.returnTo}=; Path=/; Max-Age=0; SameSite=Lax`);
+  reply.header("location", dest);
+  reply.code(302).send();
+}
+function requestOriginOf(req) {
+  const proto = req.headers?.["x-forwarded-proto"]?.split(",")[0]?.trim() || (typeof req.protocol === "string" ? req.protocol : void 0) || "https";
+  const host = req.headers?.["x-forwarded-host"]?.split(",")[0]?.trim() || req.headers?.host || "";
+  return host ? `${proto}://${host}` : "";
+}
 function readCookie(req, name) {
   if (req.cookies && typeof req.cookies[name] === "string") return req.cookies[name];
   const raw = req.headers?.cookie;
@@ -2103,10 +2593,12 @@ async function iqAuth(fastify, options) {
   } : void 0;
   const accessCookie = options.accessCookieName ?? "iqauth_at";
   const refreshCookie = options.refreshCookieName ?? "iqauth_rt";
+  const returnToCookie = options.returnToCookieName ?? "iqauth_return_to";
   const mount = (options.mountPath ?? "/api/iqauth").replace(/\/+$/, "");
   const mountHelpers = options.mountHelperRoutes !== false;
   const isPublic = (p) => {
     if (mountHelpers && p.startsWith(mount + "/")) return true;
+    if (options.mountUserinfo && p === `${mount}/me`) return true;
     if (Array.isArray(options.publicPaths)) return options.publicPaths.includes(p);
     if (typeof options.publicPaths === "function") return options.publicPaths(p);
     return false;
@@ -2136,22 +2628,54 @@ async function iqAuth(fastify, options) {
   if (mountHelpers) {
     fastify.post(`${mount}/callback`, async (req, reply) => {
       const body = req.body || {};
-      applyResponse(reply, await handleCallback(helperConfig, {
+      const hr = await handleCallback(helperConfig, {
         code: body.code,
         codeVerifier: body.codeVerifier,
-        redirectUri: body.redirectUri
-      }));
+        redirectUri: body.redirectUri,
+        // M-2: bind callback to this browser; handleCallback fails closed.
+        state: body.state,
+        expectedState: readCookie(req, helperConfig.stateCookieName ?? "iqauth_state")
+      });
+      applyCallbackResponse(reply, hr, requestOriginOf(req), readCookie(req, returnToCookie), returnToCookie);
+    });
+    fastify.get(`${mount}/callback`, async (req, reply) => {
+      const stateCookie = helperConfig.stateCookieName ?? "iqauth_state";
+      const q = req.query || {};
+      const origin = requestOriginOf(req);
+      const redirectUri = `${origin}${mount}/callback`;
+      const hr = await handleCallback(helperConfig, {
+        code: q.code,
+        codeVerifier: readCookie(req, PKCE_COOKIE),
+        redirectUri,
+        state: q.state,
+        expectedState: readCookie(req, stateCookie)
+      });
+      applyCallbackRedirect(reply, hr, origin, readCookie(req, returnToCookie), {
+        returnTo: returnToCookie,
+        state: stateCookie,
+        pkce: PKCE_COOKIE
+      });
     });
     fastify.post(`${mount}/refresh`, async (req, reply) => {
       const body = req.body || {};
       const refreshToken = body.refreshToken || readCookie(req, refreshCookie);
-      applyResponse(reply, await handleRefresh(helperConfig, { refreshToken }));
+      const idempotencyToken = req.headers?.["x-iqauth-idempotency"] || body.idempotencyToken;
+      applyResponse(reply, await handleRefresh(helperConfig, { refreshToken, idempotencyToken }));
     });
     fastify.post(`${mount}/signout`, async (req, reply) => {
       const auth = req.headers?.authorization;
       const accessToken = (typeof auth === "string" ? auth.replace(/^Bearer /i, "") : void 0) || readCookie(req, accessCookie);
+      const refreshToken = readCookie(req, refreshCookie);
       const ssoCookieHeader = typeof req.headers?.cookie === "string" ? req.headers.cookie : void 0;
-      applyResponse(reply, await handleSignout(helperConfig, { accessToken, ssoCookieHeader }));
+      const idempotencyToken = req.headers?.["x-iqauth-idempotency"];
+      applyResponse(reply, await handleSignout(helperConfig, { accessToken, refreshToken, idempotencyToken, ssoCookieHeader }));
+    });
+  }
+  if (options.mountUserinfo) {
+    fastify.get(`${mount}/me`, async (req, reply) => {
+      const auth = req.headers?.authorization;
+      const accessToken = (typeof auth === "string" ? auth.replace(/^Bearer /i, "") : void 0) || readCookie(req, accessCookie);
+      applyResponse(reply, await handleUserinfo(helperConfig, { accessToken, req }));
     });
   }
   fastify.decorate("iqauth", { client, issuer });