@zoreal/oauth2-js 0.1.8 → 0.1.10

package/README.md

@@ -130,9 +130,17 @@ on screen, so this package does it. `startLogin` mounts a dialog, keeps it in
 step with the pairing, and takes it down when the flow settles. You render
 nothing.
 
+The code on screen changes every few seconds. Each image is one frame of the
+pairing, and the provider refuses a frame more than 30 seconds old, so a
+screenshot of the code passed to someone else is already dead when it arrives:
+signing in needs the screen as it is right now. The provider renders the
+frames and this package re-fetches the image on the interval the provider
+gives it, preloading the next one so the code never flickers to blank. There
+is nothing to configure and nothing to draw.
+
 | | |
 | --- | --- |
-| **Mobile** | No QR. The pairing link opens the ZOREAL ID app and the modal never appears. Force one or the other with `display: 'qr'` / `'link'`. |
+| **Mobile** | No QR. The pairing link opens the ZOREAL ID app and the modal never appears. Force one or the other with `display: 'qr'` / `'link'`. The choice is made before the pairing is created, because the provider binds the surface there: a link-mode pairing is claimed only by the app that opened that exact link, and has no QR at all. |
 | **Live status** | Copy and title follow the pairing: waiting for a scan, then waiting for approval once the code is claimed (the spent QR blurs out behind a phone glyph). |
 | **Countdown** | Counts down to expiry, turning amber under 20s. Reads the clock each tick rather than decrementing, so a backgrounded tab comes back honest. |
 | **Timeout** | Closes and cancels at zero. Defaults to 120s; override with `pairingTimeoutMs`. The provider's own expiry wins when it is shorter. |
@@ -184,6 +192,11 @@ startLogin({ clientId: 'ast_your_asset_id', pairingUI: 'none' });
 your own. `mountPairingModal` is also exported if you want the real dialog but
 driven on your own terms.
 
+Render the `qrUrl` from the state you are given, every time, and never cache
+the first one: it is a moving code, a fresh frame arrives every
+`qrRefreshSeconds`, and a UI holding the first URL shows one the provider has
+already refused.
+
 ## The handle
 
 `startLogin` returns synchronously with everything a UI needs to drive the
@@ -194,8 +207,8 @@ flow:
 | `promise` | resolves with the mode's result; rejects with `OAuthFlowError`, `FlowAbandonedError`, or an `AbortError` after `cancel()` |
 | `cancel()` | abandons the flow: stops the poll, rejects the promise |
 | `requestId` | the pairing request id, once the provider has created it |
-| `pairUrl` | the pairing link, once created. The same URL in QR and app link |
-| `qrUrl` | the provider-served SVG of `pairUrl`. Put it in an `<img>`; do not draw your own |
+| `pairUrl` | the pairing link, once created. On an app-link flow it carries the start token; navigate to it verbatim |
+| `qrUrl` | the provider-served SVG of the current code. Put it in an `<img>`; do not draw your own. It changes while the pairing is pending, so read it from `onState` rather than here |
 | `appLink` | true when the flow resolved to the app link (mobile) rather than a QR |
 
 `requestId`, `pairUrl`, `qrUrl` and `appLink` are `undefined` until the
@@ -203,10 +216,10 @@ pairing request exists (one round-trip), and stay `undefined` when
 `prompt: 'none'` resolves silently. The same four values also arrive on every
 `onState` callback, which is the reliable place to render from.
 
-`onState` receives a `PairingState` on every change:
+`onState` receives a `PairingState` on every change, and on every QR frame:
 `status` (`pending | claimed | approved | denied | expired | enrolling`),
-`expiresIn`, `enrolmentDeadline`, `pairUrl`, `qrUrl`, `appLink`, and
-`cancel`.
+`expiresIn`, `enrolmentDeadline`, `pairUrl`, `qrUrl`, `qrRefreshSeconds`,
+`appLink`, and `cancel`.
 
 ## What resolves, per mode
 
@@ -309,7 +322,6 @@ key, `user` a presence/unlock gesture, `face` a face biometric. `zoreal.live` is
 const handle = startLogin({
   clientId: 'ast_your_asset_id',
   acr_values: 'zoreal.live',        // the app now makes the holder pass a face capture
-  onState: (s) => renderPairing(s),
 });
 ```
 
@@ -366,6 +378,9 @@ enforced where enforcement counts: on your backend, against the verified token.
 | `generateVerifier()` / `challengeS256(v)` / `generateState()` | PKCE and state material, S256 only |
 | `unsafeClaims(idToken)` | reads claims without verifying. Convenience only; verification happens server-side |
 | `isMobileUserAgent()` | whether this user agent gets the app link rather than a QR |
+| `mountPairingModal(state, { onCancel, locale?, theme?, timeoutMs? })` | mounts the dialog yourself, for `pairingUI: 'none'` callers who still want the real one. Returns `{ update, close }`, or `null` outside a browser |
+| `DEFAULT_PAIRING_TIMEOUT_MS` | `120000`, the modal's default cap |
+| `DEFAULT_QR_REFRESH_SECONDS` | `3`, how often the QR frame is re-fetched when the provider does not say |
 
 Errors: `OAuthFlowError` (the provider refused; `error` is the OAuth code,
 `description` is the provider's reason verbatim) and `FlowAbandonedError` (a
@@ -373,10 +388,17 @@ human outcome: `reason.type` is `request_denied`, `request_expired`,
 `enrolment_abandoned`, or `unknown` for failures that never reached the
 provider). `cancel()` rejects with a `DOMException` named `AbortError`.
 
+`startLogin` options controlling the built-in modal: `pairingUI`
+(`'modal'` default, `'none'` to render your own), `theme` (`'auto'` default,
+`'light'`, `'dark'`), `pairingTimeoutMs` (120000 default), and `locale`, which
+is sent to the provider AND picks the modal's own language. See
+[The pairing modal](#the-pairing-modal).
+
 All types are exported: `PairingState`, `ZorealCredentialResponse`,
 `ZorealCodeResponse`, `StartLoginOptions`, `BrowserDirectLoginOptions`,
 `AuthCodeLoginOptions`, `LoginHandle`, `ErrorCode`, `NonOAuthError`,
-`SelectBy`, `AcrValue`, and the wire shapes.
+`SelectBy`, `AcrValue`, `PairingUI`, `PairDisplay`, `ZorealTheme`,
+`PairingModalHandle`, `PairingModalOptions`, and the wire shapes.
 
 ## Error reference
 
@@ -461,7 +483,10 @@ export function mountZorealButton(root: HTMLElement) {
     }
     if (s.qrUrl) {
       const img = document.createElement('img');
-      img.src = s.qrUrl; // provider-served; never draw your own QR of pairUrl
+      // Provider-served, and a new frame every few seconds: never draw your
+      // own QR of pairUrl, and never keep the first URL. A real UI keeps one
+      // <img> and assigns src, rather than rebuilding it as this sketch does.
+      img.src = s.qrUrl;
       img.alt = 'Scan with the ZOREAL ID app';
       panel.append(img);
     }
@@ -482,6 +507,9 @@ export function mountZorealButton(root: HTMLElement) {
       flow: 'auth-code',
       clientId: 'ast_your_asset_id',
       scope: 'openid email profile.name',
+      // This example draws its own panel, so it opts out of the built-in
+      // modal. Drop these two lines and delete renderPairing to use it.
+      pairingUI: 'none',
       onState: renderPairing,
     });
 
@@ -598,7 +626,9 @@ And the template renders the state:
 The same shape ports to Svelte (a store fed by `onState`) or Angular (a
 service exposing an observable). The rules a wrapper must keep:
 
-- Render `qrUrl` in an `<img>`; never draw your own QR of `pairUrl`.
+- Render `qrUrl` in an `<img>`; never draw your own QR of `pairUrl`. Re-render
+  it on every state: the code moves, and the last frame you were given is the
+  only one the provider still accepts.
 - Call `cancel()` on unmount or navigation. Do not add your own retry loop:
   the poll cadence is fixed because over-polling cancels the request
   server-side.

package/dist/index.cjs

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   DEFAULT_ISSUER: () => DEFAULT_ISSUER,
   DEFAULT_PAIRING_TIMEOUT_MS: () => DEFAULT_PAIRING_TIMEOUT_MS,
+  DEFAULT_QR_REFRESH_SECONDS: () => DEFAULT_QR_REFRESH_SECONDS,
   FlowAbandonedError: () => FlowAbandonedError,
   OAuthFlowError: () => OAuthFlowError,
   POLL_INTERVAL_ENROLLING_MS: () => POLL_INTERVAL_ENROLLING_MS,
@@ -58,11 +59,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 {
@@ -111,11 +113,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 (; ; ) {
@@ -1305,6 +1311,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;
@@ -1312,7 +1341,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));
@@ -1329,6 +1358,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;
@@ -1378,10 +1408,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;
   };
@@ -1402,7 +1437,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
       );
@@ -1412,19 +1448,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, {
@@ -1437,18 +1479,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,
@@ -1473,7 +1550,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({
@@ -1506,6 +1583,7 @@ function startLogin(options) {
 0 && (module.exports = {
   DEFAULT_ISSUER,
   DEFAULT_PAIRING_TIMEOUT_MS,
+  DEFAULT_QR_REFRESH_SECONDS,
   FlowAbandonedError,
   OAuthFlowError,
   POLL_INTERVAL_ENROLLING_MS,