@zoreal/oauth2-js 0.1.8 → 0.1.10

package/dist/index.d.cts

@@ -31,11 +31,28 @@ interface PairingState {
     /**
      * The pairing link and its provider-served QR image. Present on every
      * callback of a QR/link flow: the QR flow cannot complete unless SOMETHING
-     * renders pairUrl, and in this package that something is always the caller.
+     * renders the code. By default that something is this package's own modal;
+     * these fields are what you render from instead when you opt out with
+     * `pairingUI: 'none'`.
      */
     pairUrl?: string;
-    /** The provider-served SVG of pairUrl. Put it in an <img>; do not draw your own. */
+    /**
+     * The provider-served SVG of the code to scan. Put it in an <img>; do not
+     * draw your own. It CHANGES OVER TIME: while the pairing is pending a fresh
+     * URL arrives every `qrRefreshSeconds`, because the code on screen moves
+     * and the provider refuses a frame older than 30 seconds. That is what
+     * makes a screenshot of it useless to an attacker. Render the qrUrl you
+     * are given on every state; a UI that caches the first one shows a code
+     * that stops working.
+     */
     qrUrl?: string;
+    /**
+     * How often qrUrl changes, in seconds, while the pairing is pending.
+     * Present on a QR flow, absent on an app-link flow and on a provider that
+     * still serves a static code. Informational: the refresh itself is done for
+     * you and arrives through this callback.
+     */
+    qrRefreshSeconds?: number;
     /** True when the flow resolved to the app link (mobile) rather than a QR. */
     appLink?: boolean;
     /** Abandons this pairing: stops the poll. Wire it to your UI's cancel control. */
@@ -153,9 +170,13 @@ interface LoginHandle<T> {
     cancel: () => void;
     /** The pairing request id, once created. Undefined before, and for prompt=none immediate codes. */
     readonly requestId: string | undefined;
-    /** The pairing URL, once created. The same URL in QR and app link. */
+    /** The pairing URL, once created. On an app-link flow it carries the start token; navigate to it verbatim. */
     readonly pairUrl: string | undefined;
-    /** The provider-served QR image of pairUrl. */
+    /**
+     * The provider-served QR image, current frame. Changes every few seconds
+     * while the pairing is pending; the onState callback is where a UI should
+     * read it from, since that is the only place a new frame announces itself.
+     */
     readonly qrUrl: string | undefined;
     /** True when display resolved to the app link rather than the QR. */
     readonly appLink: boolean | undefined;
@@ -222,36 +243,86 @@ declare function mountPairingModal(state: PairingState, options: PairingModalOpt
  * authorized JavaScript origins (the dashboard):
  *
  *   POST /pair                     start a pairing request. Body carries the
- *                                  authorize parameters plus PKCE challenge.
- *                                  Returns { request_id, pair_url, expires_in }
- *                                  or, for prompt=none with a live consented
- *                                  session, { code } immediately.
+ *                                  authorize parameters plus PKCE challenge,
+ *                                  and `display`: which pairing surface this
+ *                                  package is about to show, 'qr' or 'link',
+ *                                  decided before the request is made. Returns
+ *                                  { request_id, pair_url, expires_in, display,
+ *                                  qr_refresh_seconds } or, for prompt=none
+ *                                  with a live consented session, { code }
+ *                                  immediately. `display` is echoed as the
+ *                                  provider bound it ('legacy' for a request
+ *                                  that sent none, which gets the static code
+ *                                  older versions of this package showed).
+ *                                  `qr_refresh_seconds` comes with 'qr' and is
+ *                                  how often to re-fetch the image; 3 today.
+ *                                  A 'link' pairing's pair_url carries
+ *                                  ?t=<start_token>: it can only be claimed by
+ *                                  the app that opened that exact link, and
+ *                                  the provider never renders a QR for it, so
+ *                                  nobody can turn a same-device link into a
+ *                                  static code to relay.
  *   GET  /pair/:id/status          poll: pending | claimed |
  *                                  approved (with code) | denied | expired |
  *                                  enrolling. Over-polling cancels the request
  *                                  rather than throttling it, so the cadence
  *                                  below is not a suggestion.
- *   GET  /pair/:id/qr.svg          the QR image for the pairing URL, served by
- *                                  the provider so the pairing surface stays
- *                                  changeable at runtime and
- *                                  this package keeps zero dependencies.
+ *   GET  /pair/:id/qr.svg          the QR image, rendered by the provider so
+ *                                  this package draws nothing and keeps zero
+ *                                  dependencies. For a 'qr' pairing it encodes
+ *                                  the CURRENT FRAME, the pairing URL with
+ *                                  ?f=<time>.<hmac>: `time` is whole seconds
+ *                                  since the pairing was created on the
+ *                                  provider's clock, `hmac` is keyed with a
+ *                                  secret only the provider holds. Served
+ *                                  Cache-Control: no-store, only while the
+ *                                  pairing is pending. The app sends the frame
+ *                                  it scanned with its claim, and the provider
+ *                                  refuses a frame older than 30 seconds, so a
+ *                                  screenshot of the code is dead on arrival.
+ *                                  This package re-fetches the image every
+ *                                  `qr_refresh_seconds` with a cache-busting
+ *                                  ?t=<Date.now()>. A 'link' pairing has no
+ *                                  image (404).
  *   POST /token                    the code exchange. Browser-direct mode uses
  *                                  it directly with PKCE and no client secret;
  *                                  auth-code mode leaves it to the RP backend.
  */
 declare const WIRE_VERSION = 1;
-declare const SDK_VERSION = "0.1.8";
+declare const SDK_VERSION = "0.1.10";
 declare const SDK_NAME = "@zoreal/oauth2-js";
 declare const DEFAULT_ISSUER = "https://id.zoreal.com";
 /** Pending TTL is short. Poll gently; over-polling cancels the request. */
 declare const POLL_INTERVAL_MS = 2000;
 /** Enrolling extends the window well beyond a normal login; poll slower. */
 declare const POLL_INTERVAL_ENROLLING_MS = 5000;
+/**
+ * How often the QR image is re-fetched while a pairing is pending, when the
+ * provider does not say. The provider's own `qr_refresh_seconds` wins when
+ * present. Refreshing is what makes the code on screen move, and a frame the
+ * provider refuses after 30 seconds is what makes a screenshot of it useless.
+ */
+declare const DEFAULT_QR_REFRESH_SECONDS = 3;
+/** The pairing surface this package will show, sent on POST /pair. */
+type PairDisplay = 'qr' | 'link';
 interface PairCreated {
     request_id: string;
-    /** https://zoreal.com/qr/<request_id>. The same URL in QR and app link. */
+    /**
+     * https://zoreal.com/login/<request_id>. For a 'link' pairing the URL also
+     * carries ?t=<start_token>, and only the app that opens that exact link can
+     * claim it. Navigate to it verbatim.
+     */
     pair_url: string;
     expires_in: number;
+    /**
+     * The surface the provider bound, echoed back. 'legacy' means the request
+     * sent no `display` (an older version of this package) and got the static
+     * code. Absent from a provider that predates the field, which also serves
+     * the static code.
+     */
+    display?: PairDisplay | 'legacy';
+    /** 'qr' pairings only: how often to re-fetch qr.svg. Defaults to 3 when absent. */
+    qr_refresh_seconds?: number;
 }
 interface PairImmediate {
     /** prompt=none resolved silently: consented sector, live session. */
@@ -263,7 +334,12 @@ interface PairStatusResponse {
     code?: string;
     expires_in?: number;
     enrolment_deadline?: number;
-    /** The provider's reason on denial or refusal. Surfaced verbatim, never rewritten. */
+    /**
+     * The provider's reason on denial or refusal. Surfaced verbatim, never
+     * rewritten: it is also how a site's own policy reaches the person, such
+     * as a sign-in refused because the phone that approved it was in a
+     * different country than the browser.
+     */
     error?: string;
     error_description?: string;
 }
@@ -307,6 +383,13 @@ interface StartPairingParams {
     max_age?: number;
     prompt?: string;
     locale?: string;
+    /**
+     * Which surface the caller will show: 'qr' binds the pairing to moving QR
+     * frames, 'link' to a start token only the opened link carries. Decided
+     * before the request, because the provider binds it at creation and will
+     * not serve the other surface afterwards. Omitting it gets the static code.
+     */
+    display?: PairDisplay;
 }
 declare function startPairing(issuer: string, params: StartPairingParams, signal?: AbortSignal): Promise<PairStartResponse>;
 /**
@@ -351,4 +434,4 @@ declare function generateState(): string;
  */
 declare function unsafeClaims(idToken: string): Record<string, unknown>;
 
-export { type AcrValue, type AuthCodeLoginOptions, type BrowserDirectLoginOptions, DEFAULT_ISSUER, DEFAULT_PAIRING_TIMEOUT_MS, type ErrorCode, FlowAbandonedError, type LoginHandle, type NonOAuthError, OAuthFlowError, POLL_INTERVAL_ENROLLING_MS, POLL_INTERVAL_MS, type PairCreated, type PairImmediate, type PairStartResponse, type PairStatusResponse, type PairingModalHandle, type PairingModalOptions, type PairingState, type PairingUI, SDK_NAME, SDK_VERSION, type SelectBy, type StartLoginOptions, type StartPairingParams, type TokenResponse, WIRE_VERSION, type ZorealCodeResponse, type ZorealCredentialResponse, type ZorealTheme, challengeS256, exchangeCode, generateState, generateVerifier, isMobileUserAgent, mountPairingModal, pollUntilApproved, startLogin, startPairing, unsafeClaims };
+export { type AcrValue, type AuthCodeLoginOptions, type BrowserDirectLoginOptions, DEFAULT_ISSUER, DEFAULT_PAIRING_TIMEOUT_MS, DEFAULT_QR_REFRESH_SECONDS, type ErrorCode, FlowAbandonedError, type LoginHandle, type NonOAuthError, OAuthFlowError, POLL_INTERVAL_ENROLLING_MS, POLL_INTERVAL_MS, type PairCreated, type PairDisplay, type PairImmediate, type PairStartResponse, type PairStatusResponse, type PairingModalHandle, type PairingModalOptions, type PairingState, type PairingUI, SDK_NAME, SDK_VERSION, type SelectBy, type StartLoginOptions, type StartPairingParams, type TokenResponse, WIRE_VERSION, type ZorealCodeResponse, type ZorealCredentialResponse, type ZorealTheme, challengeS256, exchangeCode, generateState, generateVerifier, isMobileUserAgent, mountPairingModal, pollUntilApproved, startLogin, startPairing, unsafeClaims };

package/dist/index.d.ts

@@ -31,11 +31,28 @@ interface PairingState {
     /**
      * The pairing link and its provider-served QR image. Present on every
      * callback of a QR/link flow: the QR flow cannot complete unless SOMETHING
-     * renders pairUrl, and in this package that something is always the caller.
+     * renders the code. By default that something is this package's own modal;
+     * these fields are what you render from instead when you opt out with
+     * `pairingUI: 'none'`.
      */
     pairUrl?: string;
-    /** The provider-served SVG of pairUrl. Put it in an <img>; do not draw your own. */
+    /**
+     * The provider-served SVG of the code to scan. Put it in an <img>; do not
+     * draw your own. It CHANGES OVER TIME: while the pairing is pending a fresh
+     * URL arrives every `qrRefreshSeconds`, because the code on screen moves
+     * and the provider refuses a frame older than 30 seconds. That is what
+     * makes a screenshot of it useless to an attacker. Render the qrUrl you
+     * are given on every state; a UI that caches the first one shows a code
+     * that stops working.
+     */
     qrUrl?: string;
+    /**
+     * How often qrUrl changes, in seconds, while the pairing is pending.
+     * Present on a QR flow, absent on an app-link flow and on a provider that
+     * still serves a static code. Informational: the refresh itself is done for
+     * you and arrives through this callback.
+     */
+    qrRefreshSeconds?: number;
     /** True when the flow resolved to the app link (mobile) rather than a QR. */
     appLink?: boolean;
     /** Abandons this pairing: stops the poll. Wire it to your UI's cancel control. */
@@ -153,9 +170,13 @@ interface LoginHandle<T> {
     cancel: () => void;
     /** The pairing request id, once created. Undefined before, and for prompt=none immediate codes. */
     readonly requestId: string | undefined;
-    /** The pairing URL, once created. The same URL in QR and app link. */
+    /** The pairing URL, once created. On an app-link flow it carries the start token; navigate to it verbatim. */
     readonly pairUrl: string | undefined;
-    /** The provider-served QR image of pairUrl. */
+    /**
+     * The provider-served QR image, current frame. Changes every few seconds
+     * while the pairing is pending; the onState callback is where a UI should
+     * read it from, since that is the only place a new frame announces itself.
+     */
     readonly qrUrl: string | undefined;
     /** True when display resolved to the app link rather than the QR. */
     readonly appLink: boolean | undefined;
@@ -222,36 +243,86 @@ declare function mountPairingModal(state: PairingState, options: PairingModalOpt
  * authorized JavaScript origins (the dashboard):
  *
  *   POST /pair                     start a pairing request. Body carries the
- *                                  authorize parameters plus PKCE challenge.
- *                                  Returns { request_id, pair_url, expires_in }
- *                                  or, for prompt=none with a live consented
- *                                  session, { code } immediately.
+ *                                  authorize parameters plus PKCE challenge,
+ *                                  and `display`: which pairing surface this
+ *                                  package is about to show, 'qr' or 'link',
+ *                                  decided before the request is made. Returns
+ *                                  { request_id, pair_url, expires_in, display,
+ *                                  qr_refresh_seconds } or, for prompt=none
+ *                                  with a live consented session, { code }
+ *                                  immediately. `display` is echoed as the
+ *                                  provider bound it ('legacy' for a request
+ *                                  that sent none, which gets the static code
+ *                                  older versions of this package showed).
+ *                                  `qr_refresh_seconds` comes with 'qr' and is
+ *                                  how often to re-fetch the image; 3 today.
+ *                                  A 'link' pairing's pair_url carries
+ *                                  ?t=<start_token>: it can only be claimed by
+ *                                  the app that opened that exact link, and
+ *                                  the provider never renders a QR for it, so
+ *                                  nobody can turn a same-device link into a
+ *                                  static code to relay.
  *   GET  /pair/:id/status          poll: pending | claimed |
  *                                  approved (with code) | denied | expired |
  *                                  enrolling. Over-polling cancels the request
  *                                  rather than throttling it, so the cadence
  *                                  below is not a suggestion.
- *   GET  /pair/:id/qr.svg          the QR image for the pairing URL, served by
- *                                  the provider so the pairing surface stays
- *                                  changeable at runtime and
- *                                  this package keeps zero dependencies.
+ *   GET  /pair/:id/qr.svg          the QR image, rendered by the provider so
+ *                                  this package draws nothing and keeps zero
+ *                                  dependencies. For a 'qr' pairing it encodes
+ *                                  the CURRENT FRAME, the pairing URL with
+ *                                  ?f=<time>.<hmac>: `time` is whole seconds
+ *                                  since the pairing was created on the
+ *                                  provider's clock, `hmac` is keyed with a
+ *                                  secret only the provider holds. Served
+ *                                  Cache-Control: no-store, only while the
+ *                                  pairing is pending. The app sends the frame
+ *                                  it scanned with its claim, and the provider
+ *                                  refuses a frame older than 30 seconds, so a
+ *                                  screenshot of the code is dead on arrival.
+ *                                  This package re-fetches the image every
+ *                                  `qr_refresh_seconds` with a cache-busting
+ *                                  ?t=<Date.now()>. A 'link' pairing has no
+ *                                  image (404).
  *   POST /token                    the code exchange. Browser-direct mode uses
  *                                  it directly with PKCE and no client secret;
  *                                  auth-code mode leaves it to the RP backend.
  */
 declare const WIRE_VERSION = 1;
-declare const SDK_VERSION = "0.1.8";
+declare const SDK_VERSION = "0.1.10";
 declare const SDK_NAME = "@zoreal/oauth2-js";
 declare const DEFAULT_ISSUER = "https://id.zoreal.com";
 /** Pending TTL is short. Poll gently; over-polling cancels the request. */
 declare const POLL_INTERVAL_MS = 2000;
 /** Enrolling extends the window well beyond a normal login; poll slower. */
 declare const POLL_INTERVAL_ENROLLING_MS = 5000;
+/**
+ * How often the QR image is re-fetched while a pairing is pending, when the
+ * provider does not say. The provider's own `qr_refresh_seconds` wins when
+ * present. Refreshing is what makes the code on screen move, and a frame the
+ * provider refuses after 30 seconds is what makes a screenshot of it useless.
+ */
+declare const DEFAULT_QR_REFRESH_SECONDS = 3;
+/** The pairing surface this package will show, sent on POST /pair. */
+type PairDisplay = 'qr' | 'link';
 interface PairCreated {
     request_id: string;
-    /** https://zoreal.com/qr/<request_id>. The same URL in QR and app link. */
+    /**
+     * https://zoreal.com/login/<request_id>. For a 'link' pairing the URL also
+     * carries ?t=<start_token>, and only the app that opens that exact link can
+     * claim it. Navigate to it verbatim.
+     */
     pair_url: string;
     expires_in: number;
+    /**
+     * The surface the provider bound, echoed back. 'legacy' means the request
+     * sent no `display` (an older version of this package) and got the static
+     * code. Absent from a provider that predates the field, which also serves
+     * the static code.
+     */
+    display?: PairDisplay | 'legacy';
+    /** 'qr' pairings only: how often to re-fetch qr.svg. Defaults to 3 when absent. */
+    qr_refresh_seconds?: number;
 }
 interface PairImmediate {
     /** prompt=none resolved silently: consented sector, live session. */
@@ -263,7 +334,12 @@ interface PairStatusResponse {
     code?: string;
     expires_in?: number;
     enrolment_deadline?: number;
-    /** The provider's reason on denial or refusal. Surfaced verbatim, never rewritten. */
+    /**
+     * The provider's reason on denial or refusal. Surfaced verbatim, never
+     * rewritten: it is also how a site's own policy reaches the person, such
+     * as a sign-in refused because the phone that approved it was in a
+     * different country than the browser.
+     */
     error?: string;
     error_description?: string;
 }
@@ -307,6 +383,13 @@ interface StartPairingParams {
     max_age?: number;
     prompt?: string;
     locale?: string;
+    /**
+     * Which surface the caller will show: 'qr' binds the pairing to moving QR
+     * frames, 'link' to a start token only the opened link carries. Decided
+     * before the request, because the provider binds it at creation and will
+     * not serve the other surface afterwards. Omitting it gets the static code.
+     */
+    display?: PairDisplay;
 }
 declare function startPairing(issuer: string, params: StartPairingParams, signal?: AbortSignal): Promise<PairStartResponse>;
 /**
@@ -351,4 +434,4 @@ declare function generateState(): string;
  */
 declare function unsafeClaims(idToken: string): Record<string, unknown>;
 
-export { type AcrValue, type AuthCodeLoginOptions, type BrowserDirectLoginOptions, DEFAULT_ISSUER, DEFAULT_PAIRING_TIMEOUT_MS, type ErrorCode, FlowAbandonedError, type LoginHandle, type NonOAuthError, OAuthFlowError, POLL_INTERVAL_ENROLLING_MS, POLL_INTERVAL_MS, type PairCreated, type PairImmediate, type PairStartResponse, type PairStatusResponse, type PairingModalHandle, type PairingModalOptions, type PairingState, type PairingUI, SDK_NAME, SDK_VERSION, type SelectBy, type StartLoginOptions, type StartPairingParams, type TokenResponse, WIRE_VERSION, type ZorealCodeResponse, type ZorealCredentialResponse, type ZorealTheme, challengeS256, exchangeCode, generateState, generateVerifier, isMobileUserAgent, mountPairingModal, pollUntilApproved, startLogin, startPairing, unsafeClaims };
+export { type AcrValue, type AuthCodeLoginOptions, type BrowserDirectLoginOptions, DEFAULT_ISSUER, DEFAULT_PAIRING_TIMEOUT_MS, DEFAULT_QR_REFRESH_SECONDS, type ErrorCode, FlowAbandonedError, type LoginHandle, type NonOAuthError, OAuthFlowError, POLL_INTERVAL_ENROLLING_MS, POLL_INTERVAL_MS, type PairCreated, type PairDisplay, type PairImmediate, type PairStartResponse, type PairStatusResponse, type PairingModalHandle, type PairingModalOptions, type PairingState, type PairingUI, SDK_NAME, SDK_VERSION, type SelectBy, type StartLoginOptions, type StartPairingParams, type TokenResponse, WIRE_VERSION, type ZorealCodeResponse, type ZorealCredentialResponse, type ZorealTheme, challengeS256, exchangeCode, generateState, generateVerifier, isMobileUserAgent, mountPairingModal, pollUntilApproved, startLogin, startPairing, unsafeClaims };

package/dist/index.js

@@ -14,11 +14,12 @@ function unsafeClaims(idToken) {
 
 // src/wire.ts
 var WIRE_VERSION = 1;
-var SDK_VERSION = "0.1.8";
+var SDK_VERSION = "0.1.10";
 var SDK_NAME = "@zoreal/oauth2-js";
 var DEFAULT_ISSUER = "https://id.zoreal.com";
 var POLL_INTERVAL_MS = 2e3;
 var POLL_INTERVAL_ENROLLING_MS = 5e3;
+var DEFAULT_QR_REFRESH_SECONDS = 3;
 
 // src/pairing.ts
 var OAuthFlowError = class extends Error {
@@ -67,11 +68,15 @@ var sleep = (ms, signal) => new Promise((resolve, reject) => {
     reject(new DOMException("aborted", "AbortError"));
     return;
   }
-  const t = setTimeout(resolve, ms);
-  signal?.addEventListener("abort", () => {
+  const onAbort = () => {
     clearTimeout(t);
     reject(new DOMException("aborted", "AbortError"));
-  });
+  };
+  const t = setTimeout(() => {
+    signal?.removeEventListener("abort", onAbort);
+    resolve();
+  }, ms);
+  signal?.addEventListener("abort", onAbort, { once: true });
 });
 async function pollUntilApproved(issuer, requestId, onState, signal) {
   for (; ; ) {
@@ -1261,6 +1266,29 @@ function mountPairingModal(state, options) {
   scrim.appendChild(card);
   const serverMs = typeof state.expiresIn === "number" ? state.expiresIn * 1e3 : Infinity;
   const deadline = Date.now() + Math.min(timeoutMs, serverMs);
+  let shown = state.qrUrl;
+  let loading = null;
+  const spent = () => qr.dataset.spent === "true";
+  const showFrame = (url) => {
+    if (url === shown || spent()) return;
+    if (!shown) {
+      qr.src = url;
+      shown = url;
+      return;
+    }
+    const next = new Image();
+    loading = next;
+    next.onload = () => {
+      if (loading !== next || spent()) return;
+      loading = null;
+      qr.src = url;
+      shown = url;
+    };
+    next.onerror = () => {
+      if (loading === next) loading = null;
+    };
+    next.src = url;
+  };
   const paint = (s) => {
     const settled = s.status === "claimed" || s.status === "enrolling";
     title.textContent = settled ? t.titleApprove : t.title;
@@ -1268,7 +1296,7 @@ function mountPairingModal(state, options) {
     statusLabel.textContent = settled ? t.waitingApproval : t.waiting;
     qr.dataset.spent = String(settled);
     overlay.style.display = settled ? "" : "none";
-    if (s.qrUrl && qr.src !== s.qrUrl) qr.src = s.qrUrl;
+    if (s.qrUrl) showFrame(s.qrUrl);
   };
   const tick = () => {
     const left = Math.max(0, Math.ceil((deadline - Date.now()) / 1e3));
@@ -1285,6 +1313,7 @@ function mountPairingModal(state, options) {
   const close = () => {
     if (closed) return;
     closed = true;
+    loading = null;
     window.clearInterval(interval);
     document.removeEventListener("keydown", onKey);
     document.body.style.overflow = previousOverflow;
@@ -1334,10 +1363,15 @@ function startLogin(options) {
   const flow = options.flow ?? "browser-direct";
   const issuer = options.issuer ?? DEFAULT_ISSUER;
   const controller = new AbortController();
+  const useAppLink = options.display === "link" || options.display !== "qr" && isMobileUserAgent();
   const surface = {};
   const cancel = () => controller.abort();
   let modal = null;
-  const closeModal = () => {
+  let stopRefresh = () => {
+  };
+  controller.signal.addEventListener("abort", () => stopRefresh());
+  const teardown = () => {
+    stopRefresh();
     modal?.close();
     modal = null;
   };
@@ -1358,7 +1392,8 @@ function startLogin(options) {
           acr_values: Array.isArray(options.acr_values) ? options.acr_values.join(" ") : options.acr_values,
           max_age: options.max_age,
           prompt: options.prompt,
-          locale: options.locale
+          locale: options.locale,
+          display: useAppLink ? "link" : "qr"
         },
         controller.signal
       );
@@ -1368,19 +1403,25 @@ function startLogin(options) {
         code = started.code;
         selectBy = "session";
       } else {
-        const useAppLink = options.display === "link" || options.display !== "qr" && isMobileUserAgent();
         selectBy = useAppLink ? "app_link" : "qr";
-        surface.requestId = started.request_id;
+        const requestId = started.request_id;
+        const qrBase = `${issuer}/pair/${encodeURIComponent(requestId)}/qr.svg`;
+        const animated = !useAppLink && started.display !== "legacy";
+        const qrRefreshSeconds = !animated ? void 0 : typeof started.qr_refresh_seconds === "number" && started.qr_refresh_seconds > 0 ? started.qr_refresh_seconds : DEFAULT_QR_REFRESH_SECONDS;
+        surface.requestId = requestId;
         surface.pairUrl = started.pair_url;
-        surface.qrUrl = `${issuer}/pair/${encodeURIComponent(started.request_id)}/qr.svg`;
+        surface.qrUrl = qrBase;
         surface.appLink = useAppLink;
-        const stateSurface = {
+        const withSurface = (s) => ({
+          ...s,
           pairUrl: surface.pairUrl,
           qrUrl: surface.qrUrl,
+          qrRefreshSeconds,
           appLink: useAppLink,
           cancel
-        };
-        const initial = { status: "pending", expiresIn: started.expires_in, ...stateSurface };
+        });
+        let lastPolled = { status: "pending", expiresIn: started.expires_in };
+        const initial = withSurface(lastPolled);
         options.onState?.(initial);
         if ((options.pairingUI ?? "modal") === "modal" && !useAppLink) {
           modal = mountPairingModal(initial, {
@@ -1393,18 +1434,53 @@ function startLogin(options) {
         if (useAppLink && typeof window !== "undefined") {
           window.location.assign(started.pair_url);
         }
+        if (qrRefreshSeconds !== void 0) {
+          const periodMs = qrRefreshSeconds * 1e3;
+          let due = Date.now() + periodMs;
+          let timer;
+          let stopped = false;
+          const emit = () => {
+            timer = void 0;
+            surface.qrUrl = `${qrBase}?t=${Date.now()}`;
+            const next = withSurface(lastPolled);
+            modal?.update(next);
+            options.onState?.(next);
+            if (stopped) return;
+            due = Date.now() + periodMs;
+            timer = setTimeout(emit, periodMs);
+          };
+          const onVisible = () => {
+            if (document.visibilityState === "visible" && timer !== void 0 && Date.now() >= due) {
+              clearTimeout(timer);
+              emit();
+            }
+          };
+          const hasDocument = typeof document !== "undefined";
+          if (hasDocument) document.addEventListener("visibilitychange", onVisible);
+          stopRefresh = () => {
+            stopped = true;
+            if (timer !== void 0) clearTimeout(timer);
+            timer = void 0;
+            if (hasDocument) document.removeEventListener("visibilitychange", onVisible);
+            stopRefresh = () => {
+            };
+          };
+          timer = setTimeout(emit, Math.max(0, due - Date.now()));
+        }
         code = await pollUntilApproved(
           issuer,
-          started.request_id,
+          requestId,
           (s) => {
-            const next = { ...s, ...stateSurface };
+            lastPolled = s;
+            if (s.status !== "pending") stopRefresh();
+            const next = withSurface(s);
             modal?.update(next);
             options.onState?.(next);
           },
           controller.signal
         );
       }
-      closeModal();
+      teardown();
       if (flow === "auth-code") {
         const response2 = {
           code,
@@ -1429,7 +1505,7 @@ function startLogin(options) {
       };
       return response;
     } catch (e) {
-      closeModal();
+      teardown();
       if (e instanceof DOMException && e.name === "AbortError") throw e;
       if (e instanceof OAuthFlowError || e instanceof FlowAbandonedError) throw e;
       throw new FlowAbandonedError({
@@ -1461,6 +1537,7 @@ function startLogin(options) {
 export {
   DEFAULT_ISSUER,
   DEFAULT_PAIRING_TIMEOUT_MS,
+  DEFAULT_QR_REFRESH_SECONDS,
   FlowAbandonedError,
   OAuthFlowError,
   POLL_INTERVAL_ENROLLING_MS,