@iqauth/sdk 2.6.4 → 2.8.1

package/dist/{reverify-4UEJXUS6.mjs → reverify-C64QXKJO.mjs}

@@ -4,8 +4,8 @@ import {
   exitImpersonation,
   reverify,
   withReverification
-} from "./chunk-LIZYFXH7.mjs";
-import "./chunk-6I6RM4MN.mjs";
+} from "./chunk-DFWHSDYQ.mjs";
+import "./chunk-6PJRLRB4.mjs";
 import "./chunk-Y6FXYEAI.mjs";
 export {
   PRIOR_SESSION_STORAGE_KEY,

package/dist/server/handlers.d.mts

@@ -1,3 +1,6 @@
+import { c as TokenVerifyOptions } from '../tokens-B06VtvUi.mjs';
+import { J as JwtClaims, S as SessionUser } from '../types-Bn8O-OEd.mjs';
+
 /**
  * Framework-neutral helper handlers for the auto-mounted routes added by the
  * @iqauth/sdk framework adapters. Each handler takes the parsed request
@@ -17,6 +20,35 @@
  * framework's cookie API. This keeps adapters trivially thin and makes the
  * handlers pure-functionally testable.
  */
+
+/**
+ * Shape returned by the auto-mounted `GET /api/iqauth/me` route.
+ *
+ * Mirrors the envelope the browser SDK's `SessionManager.bootstrap()` already
+ * accepts: `data.user` is preferred when present (so an integrator can supply
+ * extra app-specific fields via `userinfoEnricher`), otherwise the SDK falls
+ * back to deriving a `SessionUser` from `data.claims` directly.
+ */
+interface UserinfoResponse {
+    success: true;
+    data: {
+        user: SessionUser;
+        claims: JwtClaims;
+        tenantId: string | null;
+    };
+}
+/**
+ * Build the documented `/api/iqauth/me` envelope from a verified set of JWT
+ * claims. Pure / framework-neutral — exported so integrators replacing the
+ * route entirely can still emit the canonical shape.
+ *
+ * @param claims  Verified JWT claims (output of `tokens.verify(token)`).
+ * @param opts.enrich  Optional sync/async hook returning a partial
+ *   `SessionUser` to merge over the claim-derived defaults.
+ */
+declare function buildUserinfoResponse(claims: JwtClaims, opts?: {
+    enrich?: (claims: JwtClaims) => Partial<SessionUser> | Promise<Partial<SessionUser>>;
+}): Promise<UserinfoResponse>;
 interface SetCookieDirective {
     name: string;
     value: string;
@@ -27,10 +59,21 @@ interface SetCookieDirective {
     sameSite: "lax" | "strict" | "none";
     path: string;
     domain?: string;
+    /**
+     * Marker for "this directive is clearing the cookie." When true, the
+     * serializer emits `Expires=Thu, 01 Jan 1970 00:00:00 GMT` in addition to
+     * `Max-Age=0` and an empty value. Some browsers (older Safari, certain
+     * embedded WebViews) ignore `Max-Age=0` without an explicit `Expires` in
+     * the past, which is the root cause of "ghost signed-in" sessions after
+     * Sign Out. Adapters with a typed cookie API (Express `res.clearCookie`,
+     * Fastify `reply.clearCookie`) should use the framework helper for the
+     * same belt-and-suspenders behavior.
+     */
+    clear?: boolean;
 }
 interface HandlerResponse {
     status: number;
-    body: Record<string, unknown>;
+    body: Record<string, unknown> | UserinfoResponse;
     cookies: SetCookieDirective[];
 }
 interface IQAuthHelperConfig {
@@ -56,8 +99,21 @@ interface IQAuthHelperConfig {
     cookieDomain?: string;
     /** Cookie sameSite policy. Defaults to `lax`. */
     sameSite?: "lax" | "strict" | "none";
-    /** Cookie secure flag. Defaults to true (set false for local http dev). */
+    /**
+     * Cookie secure flag. Defaults to `true`. Setting it to `false` ships auth
+     * cookies over plaintext HTTP, exposing them to passive network attackers —
+     * so it is REFUSED by default (the helper throws `config_invalid`). To run a
+     * local HTTP dev box you must explicitly acknowledge the risk by ALSO setting
+     * {@link IQAuthHelperConfig.allowInsecureCookies} to `true`.
+     */
     secure?: boolean;
+    /**
+     * Explicit, opt-in acknowledgement that `secure: false` is intentional (local
+     * HTTP development only). Without this, `secure: false` throws so a misconfig
+     * can never silently downgrade production cookies to plaintext. Has no effect
+     * unless `secure` is `false`. Production MUST leave this unset / `false`.
+     */
+    allowInsecureCookies?: boolean;
     /** Cookie path. Defaults to `/`. */
     cookiePath?: string;
     /** Path of the OIDC token endpoint. */
@@ -86,8 +142,104 @@ interface IQAuthHelperConfig {
      *   apps that manage cookie lifecycle entirely outside the SDK helpers.
      */
     clearCookiesOnRefreshFailure?: "terminal-only" | "always" | "never";
+    /**
+     * Mount the auto-mounted `GET ${mountPath}/me` userinfo route. Off by default
+     * in adapters until the integrator opts in. When true, the handler accepts
+     * either an `Authorization: Bearer …` header OR the `iqauth_at` cookie,
+     * verifies the token against the issuer, and returns the documented
+     * {@link UserinfoResponse} envelope (`data.user` + `data.claims` +
+     * `data.tenantId`).
+     *
+     * Independent of `mountHelperRoutes` so apps can opt into `/me` without
+     * also auto-mounting `/callback`/`/refresh`/`/signout` (e.g. if they
+     * already manage those routes themselves).
+     */
+    mountUserinfo?: boolean;
+    /**
+     * Optional hook to add app-specific fields to the `data.user` returned by
+     * the auto-mounted userinfo route. Receives the verified claims and the
+     * raw framework request object (typed `unknown` because adapters differ).
+     * Returned partial is shallow-merged over the claim-derived defaults so
+     * integrators can override e.g. `name`, or add fields not present on
+     * `SessionUser` itself (the response shape stays stable).
+     */
+    userinfoEnricher?: (claims: JwtClaims, req: unknown) => Partial<SessionUser> | Promise<Partial<SessionUser>>;
+    /**
+     * Token verification overrides forwarded to the cached `TokensModule` used
+     * by the userinfo handler. Mirrors the per-call shape on `tokens.verify`.
+     */
+    verify?: TokenVerifyOptions;
+    /**
+     * Task #126: Optional debug + timing-event hook. When `debug` is true, the
+     * helper handlers emit `console.debug("[iqauth_helper]", evt)` for each
+     * phase (`callback`, `refresh`, `signout`). When `onTimingEvent` is set,
+     * the same event is also passed to the callback, with `{ phase, durationMs,
+     * ok, code? }` shape. Use to push timings into your APM (Datadog, OTEL).
+     */
+    debug?: boolean;
+    onTimingEvent?: (event: IQAuthTimingEvent) => void;
+    /**
+     * Pluggable registry that tracks recently-signed-out idempotency tokens
+     * (synthetic per-session opaque strings; see {@link SignoutRegistry}).
+     * Defaults to a module-scoped in-memory `Map` shared by every adapter
+     * instance in this process. Multi-instance deployments (Railway replicas,
+     * autoscaled containers, blue/green) MUST plug in a shared store
+     * (Redis is the obvious fit) so a refresh routed to instance B can see
+     * the signout that landed on instance A. The interface is intentionally
+     * tiny — `mark` records the token with a TTL, `has` queries it.
+     */
+    signoutRegistry?: SignoutRegistry;
+    /**
+     * TTL applied when {@link handleSignout} marks an idempotency token.
+     * Defaults to 60 seconds — long enough to swallow any reasonable
+     * refresh-then-signout race, short enough that it can never delay a
+     * legitimate fresh sign-in.
+     */
+    signoutMarkerTtlMs?: number;
+    /**
+     * M-2 — Server-side OAuth `state` (CSRF) enforcement on the callback.
+     *
+     * When `true` (the DEFAULT), {@link handleCallback} requires BOTH the
+     * `state` returned by the OAuth redirect AND a previously-stored
+     * `expectedState` (read by the adapter from the {@link stateCookieName}
+     * cookie the SDK publishes before redirect), and fails closed with
+     * `STATE_MISMATCH` (no code exchange, no session cookie) when either is
+     * missing or they do not match. This defeats login-CSRF / session-fixation
+     * where an attacker injects their own authorization code.
+     *
+     * Set to `false` to restore the prior permissive behavior (state is only
+     * validated when an `expectedState` cookie happens to be present). This is
+     * an escape hatch for integrators whose initiation step does not publish a
+     * state cookie; it weakens CSRF protection and is not recommended.
+     */
+    requireOAuthState?: boolean;
+    /**
+     * Name of the first-party cookie the SDK publishes the OAuth `state` value
+     * into before redirecting to the issuer. The adapter reads it back on the
+     * callback as `expectedState`. Defaults to `iqauth_state` (matches the
+     * express inline-callback adapter and the React server-managed sign-in).
+     */
+    stateCookieName?: string;
+}
+interface IQAuthTimingEvent {
+    phase: "callback" | "refresh" | "signout" | "bootstrap" | "signIn";
+    durationMs: number;
+    ok: boolean;
+    code?: string;
+}
+/**
+ * Pluggable backing store for the refresh/signout collapse cache. The
+ * default in-memory implementation is process-local and works fine for
+ * single-process deployments; multi-instance deployments should provide a
+ * shared backend (Redis is the canonical choice — `mark` ⇒ `SETEX`,
+ * `has` ⇒ `EXISTS`). Both methods may be sync or async; handlers always
+ * `await` the result.
+ */
+interface SignoutRegistry {
+    mark(idempotencyToken: string, ttlMs: number): void | Promise<void>;
+    has(idempotencyToken: string): boolean | Promise<boolean>;
 }
-interface ResolvedConfig extends Required<Omit<IQAuthHelperConfig, "secretKey" | "cookieDomain" | "issuer" | "fetchImpl" | "clearCookiesOnRefreshFailure" | "cookieNames">> {
+interface ResolvedConfig extends Required<Omit<IQAuthHelperConfig, "secretKey" | "cookieDomain" | "issuer" | "fetchImpl" | "clearCookiesOnRefreshFailure" | "cookieNames" | "mountUserinfo" | "userinfoEnricher" | "verify" | "debug" | "onTimingEvent" | "signoutRegistry" | "signoutMarkerTtlMs" | "allowInsecureCookies">> {
     cookieNames?: {
         access?: string;
         refresh?: string;
@@ -99,7 +251,29 @@ interface ResolvedConfig extends Required<Omit<IQAuthHelperConfig, "secretKey" |
     appId: string;
     tenantId: string;
     clearCookiesOnRefreshFailure: "terminal-only" | "always" | "never";
+    debug?: boolean;
+    onTimingEvent?: (event: IQAuthTimingEvent) => void;
+    signoutRegistry: SignoutRegistry;
+    signoutMarkerTtlMs: number;
 }
+/**
+ * Test-only hook for clearing the default in-memory signout marker cache
+ * between test runs. Custom registries are unaffected. Not part of the
+ * public surface.
+ */
+declare function __resetSignoutMarkersForTests(): void;
+/**
+ * Test-only hook to reset the one-time default-registry boot warning so each
+ * test can assert the warn-once behavior in isolation. Not part of the public
+ * surface.
+ */
+declare function __resetSignoutRegistryWarningForTests(): void;
+/**
+ * Public factory for a fresh in-memory {@link SignoutRegistry}. Useful for
+ * tests that want isolated state per case, and as a reference implementation
+ * for apps building Redis-backed (or other shared-store) registries.
+ */
+declare function createInMemorySignoutRegistry(): SignoutRegistry;
 /**
  * Serialize a cookie directive to a Set-Cookie header value. Adapters that
  * lack a typed cookie API (Hono, raw Node) use this; Express / Fastify /
@@ -111,6 +285,14 @@ declare function handleCallback(config: IQAuthHelperConfig, input: {
     code?: string;
     codeVerifier?: string;
     redirectUri?: string;
+    /** The `state` value returned by the OAuth redirect (query or body). */
+    state?: string;
+    /**
+     * The `state` value the SDK stored before redirect, read by the adapter
+     * from the {@link IQAuthHelperConfig.stateCookieName} cookie. Compared
+     * against `state` to bind the callback to this browser (M-2 CSRF).
+     */
+    expectedState?: string;
 }): Promise<HandlerResponse>;
 /** POST /api/iqauth/refresh — rotate refresh + access cookies.
  *
@@ -123,12 +305,26 @@ declare function handleCallback(config: IQAuthHelperConfig, input: {
  */
 declare function handleRefresh(config: IQAuthHelperConfig, input: {
     refreshToken?: string;
+    idempotencyToken?: string;
 }): Promise<HandlerResponse>;
 /** POST /api/iqauth/signout — clear cookies and best-effort revoke at issuer. */
 declare function handleSignout(config: IQAuthHelperConfig, input: {
     accessToken?: string;
+    refreshToken?: string;
+    idempotencyToken?: string;
     ssoCookieHeader?: string;
     endSsoSession?: boolean;
 }): Promise<HandlerResponse>;
+/**
+ * GET /api/iqauth/me — verify the access token and return the documented
+ * userinfo envelope. Accepts the token from `Authorization: Bearer …` OR
+ * the access cookie (default `iqauth_at`). Adapters call this directly; the
+ * `req` value is forwarded verbatim to `userinfoEnricher` so integrators can
+ * read additional context (headers, sub-paths, etc).
+ */
+declare function handleUserinfo(config: IQAuthHelperConfig, input: {
+    accessToken?: string;
+    req?: unknown;
+}): Promise<HandlerResponse>;
 
-export { type HandlerResponse, type IQAuthHelperConfig, type ResolvedConfig as ResolvedIQAuthHelperConfig, type SetCookieDirective, handleCallback, handleRefresh, handleSignout, serializeCookie };
+export { type HandlerResponse, type IQAuthHelperConfig, type IQAuthTimingEvent, type ResolvedConfig as ResolvedIQAuthHelperConfig, type SetCookieDirective, type SignoutRegistry, type UserinfoResponse, __resetSignoutMarkersForTests, __resetSignoutRegistryWarningForTests, buildUserinfoResponse, createInMemorySignoutRegistry, handleCallback, handleRefresh, handleSignout, handleUserinfo, serializeCookie };

package/dist/server/handlers.d.ts

@@ -1,3 +1,6 @@
+import { c as TokenVerifyOptions } from '../tokens-9F6ETrzk.js';
+import { J as JwtClaims, S as SessionUser } from '../types-Bn8O-OEd.js';
+
 /**
  * Framework-neutral helper handlers for the auto-mounted routes added by the
  * @iqauth/sdk framework adapters. Each handler takes the parsed request
@@ -17,6 +20,35 @@
  * framework's cookie API. This keeps adapters trivially thin and makes the
  * handlers pure-functionally testable.
  */
+
+/**
+ * Shape returned by the auto-mounted `GET /api/iqauth/me` route.
+ *
+ * Mirrors the envelope the browser SDK's `SessionManager.bootstrap()` already
+ * accepts: `data.user` is preferred when present (so an integrator can supply
+ * extra app-specific fields via `userinfoEnricher`), otherwise the SDK falls
+ * back to deriving a `SessionUser` from `data.claims` directly.
+ */
+interface UserinfoResponse {
+    success: true;
+    data: {
+        user: SessionUser;
+        claims: JwtClaims;
+        tenantId: string | null;
+    };
+}
+/**
+ * Build the documented `/api/iqauth/me` envelope from a verified set of JWT
+ * claims. Pure / framework-neutral — exported so integrators replacing the
+ * route entirely can still emit the canonical shape.
+ *
+ * @param claims  Verified JWT claims (output of `tokens.verify(token)`).
+ * @param opts.enrich  Optional sync/async hook returning a partial
+ *   `SessionUser` to merge over the claim-derived defaults.
+ */
+declare function buildUserinfoResponse(claims: JwtClaims, opts?: {
+    enrich?: (claims: JwtClaims) => Partial<SessionUser> | Promise<Partial<SessionUser>>;
+}): Promise<UserinfoResponse>;
 interface SetCookieDirective {
     name: string;
     value: string;
@@ -27,10 +59,21 @@ interface SetCookieDirective {
     sameSite: "lax" | "strict" | "none";
     path: string;
     domain?: string;
+    /**
+     * Marker for "this directive is clearing the cookie." When true, the
+     * serializer emits `Expires=Thu, 01 Jan 1970 00:00:00 GMT` in addition to
+     * `Max-Age=0` and an empty value. Some browsers (older Safari, certain
+     * embedded WebViews) ignore `Max-Age=0` without an explicit `Expires` in
+     * the past, which is the root cause of "ghost signed-in" sessions after
+     * Sign Out. Adapters with a typed cookie API (Express `res.clearCookie`,
+     * Fastify `reply.clearCookie`) should use the framework helper for the
+     * same belt-and-suspenders behavior.
+     */
+    clear?: boolean;
 }
 interface HandlerResponse {
     status: number;
-    body: Record<string, unknown>;
+    body: Record<string, unknown> | UserinfoResponse;
     cookies: SetCookieDirective[];
 }
 interface IQAuthHelperConfig {
@@ -56,8 +99,21 @@ interface IQAuthHelperConfig {
     cookieDomain?: string;
     /** Cookie sameSite policy. Defaults to `lax`. */
     sameSite?: "lax" | "strict" | "none";
-    /** Cookie secure flag. Defaults to true (set false for local http dev). */
+    /**
+     * Cookie secure flag. Defaults to `true`. Setting it to `false` ships auth
+     * cookies over plaintext HTTP, exposing them to passive network attackers —
+     * so it is REFUSED by default (the helper throws `config_invalid`). To run a
+     * local HTTP dev box you must explicitly acknowledge the risk by ALSO setting
+     * {@link IQAuthHelperConfig.allowInsecureCookies} to `true`.
+     */
     secure?: boolean;
+    /**
+     * Explicit, opt-in acknowledgement that `secure: false` is intentional (local
+     * HTTP development only). Without this, `secure: false` throws so a misconfig
+     * can never silently downgrade production cookies to plaintext. Has no effect
+     * unless `secure` is `false`. Production MUST leave this unset / `false`.
+     */
+    allowInsecureCookies?: boolean;
     /** Cookie path. Defaults to `/`. */
     cookiePath?: string;
     /** Path of the OIDC token endpoint. */
@@ -86,8 +142,104 @@ interface IQAuthHelperConfig {
      *   apps that manage cookie lifecycle entirely outside the SDK helpers.
      */
     clearCookiesOnRefreshFailure?: "terminal-only" | "always" | "never";
+    /**
+     * Mount the auto-mounted `GET ${mountPath}/me` userinfo route. Off by default
+     * in adapters until the integrator opts in. When true, the handler accepts
+     * either an `Authorization: Bearer …` header OR the `iqauth_at` cookie,
+     * verifies the token against the issuer, and returns the documented
+     * {@link UserinfoResponse} envelope (`data.user` + `data.claims` +
+     * `data.tenantId`).
+     *
+     * Independent of `mountHelperRoutes` so apps can opt into `/me` without
+     * also auto-mounting `/callback`/`/refresh`/`/signout` (e.g. if they
+     * already manage those routes themselves).
+     */
+    mountUserinfo?: boolean;
+    /**
+     * Optional hook to add app-specific fields to the `data.user` returned by
+     * the auto-mounted userinfo route. Receives the verified claims and the
+     * raw framework request object (typed `unknown` because adapters differ).
+     * Returned partial is shallow-merged over the claim-derived defaults so
+     * integrators can override e.g. `name`, or add fields not present on
+     * `SessionUser` itself (the response shape stays stable).
+     */
+    userinfoEnricher?: (claims: JwtClaims, req: unknown) => Partial<SessionUser> | Promise<Partial<SessionUser>>;
+    /**
+     * Token verification overrides forwarded to the cached `TokensModule` used
+     * by the userinfo handler. Mirrors the per-call shape on `tokens.verify`.
+     */
+    verify?: TokenVerifyOptions;
+    /**
+     * Task #126: Optional debug + timing-event hook. When `debug` is true, the
+     * helper handlers emit `console.debug("[iqauth_helper]", evt)` for each
+     * phase (`callback`, `refresh`, `signout`). When `onTimingEvent` is set,
+     * the same event is also passed to the callback, with `{ phase, durationMs,
+     * ok, code? }` shape. Use to push timings into your APM (Datadog, OTEL).
+     */
+    debug?: boolean;
+    onTimingEvent?: (event: IQAuthTimingEvent) => void;
+    /**
+     * Pluggable registry that tracks recently-signed-out idempotency tokens
+     * (synthetic per-session opaque strings; see {@link SignoutRegistry}).
+     * Defaults to a module-scoped in-memory `Map` shared by every adapter
+     * instance in this process. Multi-instance deployments (Railway replicas,
+     * autoscaled containers, blue/green) MUST plug in a shared store
+     * (Redis is the obvious fit) so a refresh routed to instance B can see
+     * the signout that landed on instance A. The interface is intentionally
+     * tiny — `mark` records the token with a TTL, `has` queries it.
+     */
+    signoutRegistry?: SignoutRegistry;
+    /**
+     * TTL applied when {@link handleSignout} marks an idempotency token.
+     * Defaults to 60 seconds — long enough to swallow any reasonable
+     * refresh-then-signout race, short enough that it can never delay a
+     * legitimate fresh sign-in.
+     */
+    signoutMarkerTtlMs?: number;
+    /**
+     * M-2 — Server-side OAuth `state` (CSRF) enforcement on the callback.
+     *
+     * When `true` (the DEFAULT), {@link handleCallback} requires BOTH the
+     * `state` returned by the OAuth redirect AND a previously-stored
+     * `expectedState` (read by the adapter from the {@link stateCookieName}
+     * cookie the SDK publishes before redirect), and fails closed with
+     * `STATE_MISMATCH` (no code exchange, no session cookie) when either is
+     * missing or they do not match. This defeats login-CSRF / session-fixation
+     * where an attacker injects their own authorization code.
+     *
+     * Set to `false` to restore the prior permissive behavior (state is only
+     * validated when an `expectedState` cookie happens to be present). This is
+     * an escape hatch for integrators whose initiation step does not publish a
+     * state cookie; it weakens CSRF protection and is not recommended.
+     */
+    requireOAuthState?: boolean;
+    /**
+     * Name of the first-party cookie the SDK publishes the OAuth `state` value
+     * into before redirecting to the issuer. The adapter reads it back on the
+     * callback as `expectedState`. Defaults to `iqauth_state` (matches the
+     * express inline-callback adapter and the React server-managed sign-in).
+     */
+    stateCookieName?: string;
+}
+interface IQAuthTimingEvent {
+    phase: "callback" | "refresh" | "signout" | "bootstrap" | "signIn";
+    durationMs: number;
+    ok: boolean;
+    code?: string;
+}
+/**
+ * Pluggable backing store for the refresh/signout collapse cache. The
+ * default in-memory implementation is process-local and works fine for
+ * single-process deployments; multi-instance deployments should provide a
+ * shared backend (Redis is the canonical choice — `mark` ⇒ `SETEX`,
+ * `has` ⇒ `EXISTS`). Both methods may be sync or async; handlers always
+ * `await` the result.
+ */
+interface SignoutRegistry {
+    mark(idempotencyToken: string, ttlMs: number): void | Promise<void>;
+    has(idempotencyToken: string): boolean | Promise<boolean>;
 }
-interface ResolvedConfig extends Required<Omit<IQAuthHelperConfig, "secretKey" | "cookieDomain" | "issuer" | "fetchImpl" | "clearCookiesOnRefreshFailure" | "cookieNames">> {
+interface ResolvedConfig extends Required<Omit<IQAuthHelperConfig, "secretKey" | "cookieDomain" | "issuer" | "fetchImpl" | "clearCookiesOnRefreshFailure" | "cookieNames" | "mountUserinfo" | "userinfoEnricher" | "verify" | "debug" | "onTimingEvent" | "signoutRegistry" | "signoutMarkerTtlMs" | "allowInsecureCookies">> {
     cookieNames?: {
         access?: string;
         refresh?: string;
@@ -99,7 +251,29 @@ interface ResolvedConfig extends Required<Omit<IQAuthHelperConfig, "secretKey" |
     appId: string;
     tenantId: string;
     clearCookiesOnRefreshFailure: "terminal-only" | "always" | "never";
+    debug?: boolean;
+    onTimingEvent?: (event: IQAuthTimingEvent) => void;
+    signoutRegistry: SignoutRegistry;
+    signoutMarkerTtlMs: number;
 }
+/**
+ * Test-only hook for clearing the default in-memory signout marker cache
+ * between test runs. Custom registries are unaffected. Not part of the
+ * public surface.
+ */
+declare function __resetSignoutMarkersForTests(): void;
+/**
+ * Test-only hook to reset the one-time default-registry boot warning so each
+ * test can assert the warn-once behavior in isolation. Not part of the public
+ * surface.
+ */
+declare function __resetSignoutRegistryWarningForTests(): void;
+/**
+ * Public factory for a fresh in-memory {@link SignoutRegistry}. Useful for
+ * tests that want isolated state per case, and as a reference implementation
+ * for apps building Redis-backed (or other shared-store) registries.
+ */
+declare function createInMemorySignoutRegistry(): SignoutRegistry;
 /**
  * Serialize a cookie directive to a Set-Cookie header value. Adapters that
  * lack a typed cookie API (Hono, raw Node) use this; Express / Fastify /
@@ -111,6 +285,14 @@ declare function handleCallback(config: IQAuthHelperConfig, input: {
     code?: string;
     codeVerifier?: string;
     redirectUri?: string;
+    /** The `state` value returned by the OAuth redirect (query or body). */
+    state?: string;
+    /**
+     * The `state` value the SDK stored before redirect, read by the adapter
+     * from the {@link IQAuthHelperConfig.stateCookieName} cookie. Compared
+     * against `state` to bind the callback to this browser (M-2 CSRF).
+     */
+    expectedState?: string;
 }): Promise<HandlerResponse>;
 /** POST /api/iqauth/refresh — rotate refresh + access cookies.
  *
@@ -123,12 +305,26 @@ declare function handleCallback(config: IQAuthHelperConfig, input: {
  */
 declare function handleRefresh(config: IQAuthHelperConfig, input: {
     refreshToken?: string;
+    idempotencyToken?: string;
 }): Promise<HandlerResponse>;
 /** POST /api/iqauth/signout — clear cookies and best-effort revoke at issuer. */
 declare function handleSignout(config: IQAuthHelperConfig, input: {
     accessToken?: string;
+    refreshToken?: string;
+    idempotencyToken?: string;
     ssoCookieHeader?: string;
     endSsoSession?: boolean;
 }): Promise<HandlerResponse>;
+/**
+ * GET /api/iqauth/me — verify the access token and return the documented
+ * userinfo envelope. Accepts the token from `Authorization: Bearer …` OR
+ * the access cookie (default `iqauth_at`). Adapters call this directly; the
+ * `req` value is forwarded verbatim to `userinfoEnricher` so integrators can
+ * read additional context (headers, sub-paths, etc).
+ */
+declare function handleUserinfo(config: IQAuthHelperConfig, input: {
+    accessToken?: string;
+    req?: unknown;
+}): Promise<HandlerResponse>;
 
-export { type HandlerResponse, type IQAuthHelperConfig, type ResolvedConfig as ResolvedIQAuthHelperConfig, type SetCookieDirective, handleCallback, handleRefresh, handleSignout, serializeCookie };
+export { type HandlerResponse, type IQAuthHelperConfig, type IQAuthTimingEvent, type ResolvedConfig as ResolvedIQAuthHelperConfig, type SetCookieDirective, type SignoutRegistry, type UserinfoResponse, __resetSignoutMarkersForTests, __resetSignoutRegistryWarningForTests, buildUserinfoResponse, createInMemorySignoutRegistry, handleCallback, handleRefresh, handleSignout, handleUserinfo, serializeCookie };