@iqauth/sdk 2.6.4 → 2.8.1

package/dist/next.js

@@ -27,13 +27,30 @@ __export(next_exports, {
 module.exports = __toCommonJS(next_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;
   }
 };
 
@@ -66,14 +83,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.`
     );
   }
@@ -82,19 +99,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.`
     );
   }
@@ -106,7 +123,271 @@ function isPublishableKeyPayload(value) {
   return typeof v.iss === "string" && typeof v.appId === "string" && typeof v.tenantId === "string" && typeof v.kid === "string";
 }
 
+// src/modules/tokens.ts
+var import_jose = require("jose");
+var JWKS_CACHE_TTL_MS = 60 * 60 * 1e3;
+var DEFAULT_TOKEN_ISSUER = [
+  "https://auth.dispositioniq.com",
+  "auth.dispositioniq.com"
+];
+var DEFAULT_TOKEN_AUDIENCE = [
+  "dispositioniq",
+  "iqcapture",
+  "iqreuse",
+  "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;
+  try {
+    const padded = parts[0] + "=".repeat((4 - parts[0].length % 4) % 4);
+    const b64 = padded.replace(/-/g, "+").replace(/_/g, "/");
+    let json;
+    if (typeof atob === "function") {
+      json = atob(b64);
+    } else {
+      const { Buffer: Buffer2 } = require("buffer");
+      json = Buffer2.from(b64, "base64").toString("utf8");
+    }
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+var TokensModule = class {
+  constructor(baseUrl, options = {}) {
+    this.jwksCache = null;
+    this.inFlightRefresh = null;
+    this.baseUrl = baseUrl;
+    this.defaultIssuer = options.issuer ?? DEFAULT_TOKEN_ISSUER;
+    this.defaultAudience = options.audience ?? DEFAULT_TOKEN_AUDIENCE;
+    this.defaultClockTolerance = options.clockTolerance ?? DEFAULT_CLOCK_TOLERANCE_SECONDS;
+  }
+  /**
+   * Verify a JWT access token using RS256/ES256 via JWKS from
+   * `/.well-known/jwks.json`. Backed by `jose` (Web Crypto) so it runs on
+   * Node, browser, and edge runtimes alike — no `node:crypto` dependency.
+   * Caches JWKS for 1 hour and refetches once on unknown `kid`.
+   */
+  async verify(token, options = {}) {
+    const header = decodeProtectedHeader(token);
+    if (!header) {
+      throw new IQAuthError("token_invalid", "Unable to decode token");
+    }
+    const kid = header.kid;
+    if (!kid) {
+      throw new IQAuthError("token_invalid", "Token missing kid header");
+    }
+    let cache = await this.ensureCache();
+    if (!cache.byKid.has(kid)) {
+      this.jwksCache = null;
+      cache = await this.ensureCache();
+    }
+    if (!cache.byKid.has(kid)) {
+      throw new IQAuthError("token_invalid", `Unknown key ID: ${kid}`);
+    }
+    const issuer = options.issuer ?? this.defaultIssuer;
+    const audience = options.audience ?? this.defaultAudience;
+    const clockTolerance = options.clockTolerance ?? this.defaultClockTolerance;
+    const algorithms = options.algorithms ?? ["RS256", "ES256"];
+    const verifyOptions = {
+      algorithms,
+      clockTolerance,
+      issuer,
+      audience
+    };
+    try {
+      const { payload } = await (0, import_jose.jwtVerify)(token, cache.verifier, verifyOptions);
+      return payload;
+    } catch (err) {
+      const classified = classifyJoseError(err);
+      throw new IQAuthError(classified.code, classified.message, void 0, err);
+    }
+  }
+  /**
+   * Decode a JWT without verification. Returns null if malformed.
+   */
+  decode(token) {
+    try {
+      const parts = token.split(".");
+      if (parts.length < 2) return null;
+      const payload = parts[1];
+      const padded = payload + "=".repeat((4 - payload.length % 4) % 4);
+      const b64 = padded.replace(/-/g, "+").replace(/_/g, "/");
+      let json;
+      if (typeof atob === "function") {
+        json = atob(b64);
+      } else {
+        const { Buffer: Buffer2 } = require("buffer");
+        json = Buffer2.from(b64, "base64").toString("utf8");
+      }
+      try {
+        json = decodeURIComponent(escape(json));
+      } catch {
+      }
+      const claims = JSON.parse(json);
+      if (!claims || typeof claims !== "object") return null;
+      return claims;
+    } catch {
+      return null;
+    }
+  }
+  /** Check if a token is expired based on the `exp` claim. */
+  isExpired(token) {
+    const claims = this.decode(token);
+    if (!claims?.exp) return true;
+    const now = Math.floor(Date.now() / 1e3);
+    return claims.exp <= now;
+  }
+  /** Get the claims from a token without verification. */
+  getClaims(token) {
+    const claims = this.decode(token);
+    if (!claims) {
+      throw new IQAuthError("token_invalid", "Unable to decode token claims");
+    }
+    return claims;
+  }
+  async ensureCache() {
+    if (this.jwksCache && Date.now() - this.jwksCache.fetchedAt <= JWKS_CACHE_TTL_MS) {
+      return this.jwksCache;
+    }
+    await this.refreshJwks();
+    if (!this.jwksCache) {
+      throw new IQAuthError("jwks_unavailable", "JWKS cache unavailable after refresh");
+    }
+    return this.jwksCache;
+  }
+  async refreshJwks() {
+    if (this.inFlightRefresh) {
+      return this.inFlightRefresh;
+    }
+    this.inFlightRefresh = (async () => {
+      try {
+        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(
+            "jwks_fetch_failed",
+            `Failed to fetch JWKS: ${res.status}`,
+            res.status
+          );
+        }
+        let jwks;
+        try {
+          jwks = await res.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(
+            "jwks_fetch_failed",
+            "Malformed JWKS response: expected { keys: [...] }"
+          );
+        }
+        const byKid = /* @__PURE__ */ new Set();
+        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(
+              "jwks_fetch_failed",
+              "Malformed JWKS response: key missing required fields"
+            );
+          }
+          byKid.add(key.kid);
+        }
+        const verifier = (0, import_jose.createLocalJWKSet)({ keys: jwks.keys });
+        this.jwksCache = { raw: jwks.keys, byKid, verifier, fetchedAt: Date.now() };
+      } finally {
+        this.inFlightRefresh = null;
+      }
+    })();
+    return this.inFlightRefresh;
+  }
+  /** @internal Exposed for testing — clears JWKS cache */
+  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/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",
@@ -125,19 +406,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",
@@ -146,9 +470,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,
@@ -163,15 +501,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}`);
@@ -179,14 +555,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" } },
@@ -210,6 +606,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: {
@@ -222,6 +619,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)
@@ -229,6 +646,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 } },
@@ -237,8 +656,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" } },
@@ -254,6 +683,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,
@@ -277,6 +707,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 } },
@@ -285,6 +716,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}`, {
@@ -306,206 +741,94 @@ 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)
   };
 }
-
-// src/modules/tokens.ts
-var import_jose = require("jose");
-var JWKS_CACHE_TTL_MS = 60 * 60 * 1e3;
-var DEFAULT_TOKEN_ISSUER = [
-  "https://auth.dispositioniq.com",
-  "auth.dispositioniq.com"
-];
-var DEFAULT_TOKEN_AUDIENCE = [
-  "dispositioniq",
-  "iqcapture",
-  "iqreuse",
-  "iqvalidate"
-];
-var DEFAULT_CLOCK_TOLERANCE_SECONDS = 30;
-function decodeProtectedHeader(token) {
-  const parts = token.split(".");
-  if (parts.length < 2) return null;
-  try {
-    const padded = parts[0] + "=".repeat((4 - parts[0].length % 4) % 4);
-    const b64 = padded.replace(/-/g, "+").replace(/_/g, "/");
-    let json;
-    if (typeof atob === "function") {
-      json = atob(b64);
-    } else {
-      const { Buffer: Buffer2 } = require("buffer");
-      json = Buffer2.from(b64, "base64").toString("utf8");
-    }
-    return JSON.parse(json);
-  } catch {
-    return null;
+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;
 }
-var TokensModule = class {
-  constructor(baseUrl, options = {}) {
-    this.jwksCache = null;
-    this.inFlightRefresh = null;
-    this.baseUrl = baseUrl;
-    this.defaultIssuer = options.issuer ?? DEFAULT_TOKEN_ISSUER;
-    this.defaultAudience = options.audience ?? DEFAULT_TOKEN_AUDIENCE;
-    this.defaultClockTolerance = options.clockTolerance ?? DEFAULT_CLOCK_TOLERANCE_SECONDS;
-  }
-  /**
-   * Verify a JWT access token using RS256/ES256 via JWKS from
-   * `/.well-known/jwks.json`. Backed by `jose` (Web Crypto) so it runs on
-   * Node, browser, and edge runtimes alike — no `node:crypto` dependency.
-   * Caches JWKS for 1 hour and refetches once on unknown `kid`.
-   */
-  async verify(token, options = {}) {
-    const header = decodeProtectedHeader(token);
-    if (!header) {
-      throw new IQAuthError("TOKEN_INVALID", "Unable to decode token");
-    }
-    const kid = header.kid;
-    if (!kid) {
-      throw new IQAuthError("TOKEN_INVALID", "Token missing kid header");
-    }
-    let cache = await this.ensureCache();
-    if (!cache.byKid.has(kid)) {
-      this.jwksCache = null;
-      cache = await this.ensureCache();
-    }
-    if (!cache.byKid.has(kid)) {
-      throw new IQAuthError("TOKEN_INVALID", `Unknown key ID: ${kid}`);
-    }
-    const issuer = options.issuer ?? this.defaultIssuer;
-    const audience = options.audience ?? this.defaultAudience;
-    const clockTolerance = options.clockTolerance ?? this.defaultClockTolerance;
-    const algorithms = options.algorithms ?? ["RS256", "ES256"];
-    const verifyOptions = {
-      algorithms,
-      clockTolerance,
-      issuer,
-      audience
+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: []
     };
-    try {
-      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");
-    }
-  }
-  /**
-   * Decode a JWT without verification. Returns null if malformed.
-   */
-  decode(token) {
-    try {
-      const parts = token.split(".");
-      if (parts.length < 2) return null;
-      const payload = parts[1];
-      const padded = payload + "=".repeat((4 - payload.length % 4) % 4);
-      const b64 = padded.replace(/-/g, "+").replace(/_/g, "/");
-      let json;
-      if (typeof atob === "function") {
-        json = atob(b64);
-      } else {
-        const { Buffer: Buffer2 } = require("buffer");
-        json = Buffer2.from(b64, "base64").toString("utf8");
-      }
-      try {
-        json = decodeURIComponent(escape(json));
-      } catch {
-      }
-      const claims = JSON.parse(json);
-      if (!claims || typeof claims !== "object") return null;
-      return claims;
-    } catch {
-      return null;
-    }
   }
-  /** Check if a token is expired based on the `exp` claim. */
-  isExpired(token) {
-    const claims = this.decode(token);
-    if (!claims?.exp) return true;
-    const now = Math.floor(Date.now() / 1e3);
-    return claims.exp <= now;
+  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: []
+    };
   }
-  /** Get the claims from a token without verification. */
-  getClaims(token) {
-    const claims = this.decode(token);
-    if (!claims) {
-      throw new IQAuthError("TOKEN_INVALID", "Unable to decode token claims");
-    }
-    return claims;
+  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(/\/+$/, "");
   }
-  async ensureCache() {
-    if (this.jwksCache && Date.now() - this.jwksCache.fetchedAt <= JWKS_CACHE_TTL_MS) {
-      return this.jwksCache;
-    }
-    await this.refreshJwks();
-    if (!this.jwksCache) {
-      throw new IQAuthError("INTERNAL_ERROR", "JWKS cache unavailable after refresh");
-    }
-    return this.jwksCache;
+}
+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;
   }
-  async refreshJwks() {
-    if (this.inFlightRefresh) {
-      return this.inFlightRefresh;
-    }
-    this.inFlightRefresh = (async () => {
-      try {
-        const res = await fetch(`${this.baseUrl}/.well-known/jwks.json`);
-        if (!res.ok) {
-          throw new IQAuthError(
-            "INTERNAL_ERROR",
-            `Failed to fetch JWKS: ${res.status}`
-          );
-        }
-        let jwks;
-        try {
-          jwks = await res.json();
-        } catch {
-          throw new IQAuthError("INTERNAL_ERROR", "Malformed JWKS response: invalid JSON");
-        }
-        if (!jwks || !Array.isArray(jwks.keys)) {
-          throw new IQAuthError(
-            "INTERNAL_ERROR",
-            "Malformed JWKS response: expected { keys: [...] }"
-          );
-        }
-        const byKid = /* @__PURE__ */ new Set();
-        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",
-              "Malformed JWKS response: key missing required fields"
-            );
-          }
-          byKid.add(key.kid);
-        }
-        const verifier = (0, import_jose.createLocalJWKSet)({ keys: jwks.keys });
-        this.jwksCache = { raw: jwks.keys, byKid, verifier, fetchedAt: Date.now() };
-      } finally {
-        this.inFlightRefresh = null;
-      }
-    })();
-    return this.inFlightRefresh;
+  if (!/^[a-z][a-z0-9+\-.]*:/i.test(trimmed)) {
+    return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
   }
-  /** @internal Exposed for testing — clears JWKS cache */
-  clearCache() {
-    this.jwksCache = null;
+  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/next.ts
+var PKCE_COOKIE = "iqauth_pkce";
 function readCookieFromHeader(header, name) {
   if (!header) return void 0;
   const target = `${name}=`;
@@ -526,32 +849,100 @@ function toResponse(hr) {
   for (const c of hr.cookies) headers.append("set-cookie", serializeCookie(c));
   return new Response(JSON.stringify(hr.body), { status: hr.status, headers });
 }
+function callbackResponse(hr, requestOrigin, returnToCookieValue, returnToCookieName) {
+  const returnTo = sanitizeReturnTo(
+    returnToCookieValue || hr.body?.returnTo,
+    { currentOrigin: requestOrigin, fallback: "/" }
+  );
+  const headers = new Headers({ "Content-Type": "application/json" });
+  for (const c of hr.cookies) headers.append("set-cookie", serializeCookie(c));
+  if (hr.status < 400) {
+    headers.append("set-cookie", `${returnToCookieName}=; Path=/; Max-Age=0; SameSite=Lax`);
+  }
+  const body = { ...hr.body, returnTo };
+  return new Response(JSON.stringify(body), { status: hr.status, headers });
+}
+function callbackRedirectResponse(hr, requestOrigin, returnToCookieValue, cookieNames) {
+  const headers = new Headers();
+  for (const c of hr.cookies) headers.append("set-cookie", serializeCookie(c));
+  headers.append("set-cookie", `${cookieNames.state}=; Path=/; Max-Age=0; SameSite=Lax`);
+  headers.append("set-cookie", `${cookieNames.pkce}=; Path=/; Max-Age=0; SameSite=Lax`);
+  if (hr.status >= 400) {
+    headers.set("Location", "/");
+    return new Response(null, { status: 302, headers });
+  }
+  const dest = sanitizeReturnTo(returnToCookieValue, {
+    currentOrigin: requestOrigin,
+    fallback: "/"
+  });
+  headers.append("set-cookie", `${cookieNames.returnTo}=; Path=/; Max-Age=0; SameSite=Lax`);
+  headers.set("Location", dest);
+  return new Response(null, { status: 302, headers });
+}
 function handler(options) {
   const parsed = assertPublishableKey(options.publishableKey, { context: "@iqauth/sdk/next handler" });
   const issuer = (options.issuer ?? (parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`)).replace(/\/+$/, "");
   const helperConfig = { ...options, issuer };
   const accessCookie = options.accessCookieName ?? "iqauth_at";
   const refreshCookie = options.refreshCookieName ?? "iqauth_rt";
+  const returnToCookie = options.returnToCookieName ?? "iqauth_return_to";
   return async (req) => {
     const url = new URL(req.url);
     const action = url.pathname.split("/").pop();
-    const body = await req.json().catch(() => ({}));
     const cookieHeader = req.headers.get("cookie");
+    if (action === "me" && req.method === "GET") {
+      if (!options.mountUserinfo) {
+        return new Response(JSON.stringify({ success: false, error: { code: "NOT_FOUND", message: "userinfo route not enabled" } }), {
+          status: 404,
+          headers: { "Content-Type": "application/json" }
+        });
+      }
+      const auth = req.headers.get("authorization");
+      const accessToken = auth && auth.replace(/^Bearer /i, "") || readCookieFromHeader(cookieHeader, accessCookie);
+      return toResponse(await handleUserinfo(helperConfig, { accessToken, req }));
+    }
+    const stateCookie = helperConfig.stateCookieName ?? "iqauth_state";
+    if (action === "callback" && req.method === "GET") {
+      const code = url.searchParams.get("code") ?? void 0;
+      const state = url.searchParams.get("state") ?? void 0;
+      const redirectUri = `${url.origin}${url.pathname}`;
+      const hr = await handleCallback(helperConfig, {
+        code,
+        codeVerifier: readCookieFromHeader(cookieHeader, PKCE_COOKIE),
+        redirectUri,
+        state,
+        expectedState: readCookieFromHeader(cookieHeader, stateCookie)
+      });
+      return callbackRedirectResponse(
+        hr,
+        url.origin,
+        readCookieFromHeader(cookieHeader, returnToCookie),
+        { returnTo: returnToCookie, state: stateCookie, pkce: PKCE_COOKIE }
+      );
+    }
+    const body = await req.json().catch(() => ({}));
     if (action === "callback") {
-      return toResponse(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: readCookieFromHeader(cookieHeader, helperConfig.stateCookieName ?? "iqauth_state")
+      });
+      return callbackResponse(hr, url.origin, readCookieFromHeader(cookieHeader, returnToCookie), returnToCookie);
     }
     if (action === "refresh") {
       const refreshToken = body.refreshToken || readCookieFromHeader(cookieHeader, refreshCookie);
-      return toResponse(await handleRefresh(helperConfig, { refreshToken }));
+      const idempotencyToken = req.headers.get("x-iqauth-idempotency") || body.idempotencyToken;
+      return toResponse(await handleRefresh(helperConfig, { refreshToken, idempotencyToken: idempotencyToken ?? void 0 }));
     }
     if (action === "signout") {
       const auth = req.headers.get("authorization");
       const accessToken = auth && auth.replace(/^Bearer /i, "") || readCookieFromHeader(cookieHeader, accessCookie);
-      return toResponse(await handleSignout(helperConfig, { accessToken, ssoCookieHeader: cookieHeader ?? void 0 }));
+      const refreshToken = readCookieFromHeader(cookieHeader, refreshCookie);
+      const idempotencyToken = req.headers.get("x-iqauth-idempotency") ?? void 0;
+      return toResponse(await handleSignout(helperConfig, { accessToken, refreshToken, idempotencyToken, ssoCookieHeader: cookieHeader ?? void 0 }));
     }
     return new Response(JSON.stringify({ success: false, error: { code: "NOT_FOUND", message: `Unknown action: ${action}` } }), {
       status: 404,