@zoreal/oauth2-js 0.1.9 → 0.1.11

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
 
@@ -367,6 +380,7 @@ enforced where enforcement counts: on your backend, against the verified token.
 | `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
@@ -383,8 +397,8 @@ is sent to the provider AND picks the modal's own language. See
 All types are exported: `PairingState`, `ZorealCredentialResponse`,
 `ZorealCodeResponse`, `StartLoginOptions`, `BrowserDirectLoginOptions`,
 `AuthCodeLoginOptions`, `LoginHandle`, `ErrorCode`, `NonOAuthError`,
-`SelectBy`, `AcrValue`, `PairingUI`, `ZorealTheme`, `PairingModalHandle`,
-`PairingModalOptions`, and the wire shapes.
+`SelectBy`, `AcrValue`, `PairingUI`, `PairDisplay`, `ZorealTheme`,
+`PairingModalHandle`, `PairingModalOptions`, and the wire shapes.
 
 ## Error reference
 
@@ -469,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);
     }
@@ -609,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.9";
+var SDK_VERSION = "0.1.11";
 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 (; ; ) {
@@ -1006,20 +1012,110 @@ var CSS = `
   color: var(--zrl-ink-soft);
 }
 
+/* The light around the well: a thin ring in the accent, one bright arc
+   travelling round it, and a soft glow of the same colour bleeding a few
+   pixels outward. It says the pairing is live without a word.
+
+   It sits BELOW the well, which is why the well is wrapped instead of given a
+   pseudo-element. Anything drawn inside the well paints over the white quiet
+   zone the camera needs, and a negative z-index from inside the well lands
+   wherever the card's stacking context happens to be that frame (the card's
+   entrance animation makes and unmakes one). The wrapper is the well's old
+   box exactly, same size, same margin, so nothing moves; the well keeps its
+   own stacking order on top, and the ring cannot touch the QR. */
+.${PREFIX}-qr-halo {
+  position: relative;
+  isolation: isolate;
+  width: 204px;
+  height: 204px;
+  margin: 20px auto 0;
+}
+
 .${PREFIX}-qr-well {
   position: relative;
+  z-index: 1;
   display: grid;
   place-items: center;
   box-sizing: border-box;
   width: 204px;
   height: 204px;
-  margin: 20px auto 0;
+  margin: 0;
   padding: 12px;
   border: 1px solid var(--zrl-line);
   border-radius: 16px;
   background: var(--zrl-qr-bg);
 }
 
+/* The glow is the ring's own alpha, blurred and drawn beneath it, so it
+   follows the arc round and fades with it. It has to be a parent of the
+   masked band: a filter is applied before a mask, so a shadow cast from the
+   band itself would be cut off at the band's edge. Two shadows because one
+   2px source blurred over 10px is too faint to read as light; the second
+   blurs the first. */
+.${PREFIX}-qr-glow {
+  position: absolute;
+  inset: -2px;
+  pointer-events: none;
+  filter: drop-shadow(0 0 3px var(--zrl-accent)) drop-shadow(0 0 10px var(--zrl-accent));
+}
+
+/* The band: a 2px ring just outside the well, cut with a mask that keeps the
+   padding and drops the content box. The gradient is on a pseudo-element
+   rather than on the band, because in the fallback it has to rotate as a
+   whole while the band stays put. The prefixed mask is for Chrome before 120;
+   the unprefixed one, declared after it, wins everywhere else. */
+.${PREFIX}-qr-arc {
+  position: absolute;
+  inset: 0;
+  padding: 2px;
+  border-radius: 18px;
+  overflow: hidden;
+  -webkit-mask: linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0);
+  -webkit-mask-composite: xor;
+  mask: linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0);
+  mask-composite: exclude;
+}
+.${PREFIX}-qr-arc::before,
+.${PREFIX}-qr-arc::after {
+  content: '';
+  position: absolute;
+  transition: opacity 400ms cubic-bezier(0.23, 1, 0.32, 1);
+}
+
+/* The light. Mostly transparent, a tail that builds over a quarter turn, a
+   short full-strength head and a drop-off within a few degrees, so it reads
+   as travelling rather than blinking. One revolution every 3s, linear:
+   continuous motion has no ease. Oversized so its corners still cover the
+   band mid-rotation in the transform fallback; the property path shrinks it
+   back to the band. */
+.${PREFIX}-qr-arc::before {
+  inset: -50%;
+  background: conic-gradient(
+    from var(--zrl-angle, 0deg),
+    transparent 0deg 245deg,
+    var(--zrl-accent) 332deg 346deg,
+    transparent 356deg 360deg
+  );
+  animation: ${PREFIX}-orbit 3s linear infinite;
+}
+
+/* The rest state: the same ring, evenly lit. Faint under the moving light so
+   the ring reads as a ring; stronger once the light has stopped. */
+.${PREFIX}-qr-arc::after {
+  inset: 0;
+  background: var(--zrl-accent);
+  opacity: 0.16;
+}
+
+/* Spent: the light stops where it is and fades, and the ring settles to a
+   dim, even glow. Paused rather than removed, so it does not jump back to
+   its start on the way out. */
+.${PREFIX}-qr-halo[data-spent="true"] .${PREFIX}-qr-arc::before {
+  animation-play-state: paused;
+  opacity: 0;
+}
+.${PREFIX}-qr-halo[data-spent="true"] .${PREFIX}-qr-arc::after { opacity: 0.34; }
+
 .${PREFIX}-qr {
   display: block;
   width: 100%;
@@ -1162,6 +1258,33 @@ var CSS = `
   70%, 100% { transform: scale(2.6); opacity: 0 }
 }
 
+/* Two ways to turn the light, one look.
+   Where the browser can register a typed custom property, the gradient's own
+   angle animates and the element never moves. Where it cannot (Firefox before
+   128), an untyped custom property cannot interpolate and the light would
+   snap once a cycle, so the oversized pseudo-element rotates instead and the
+   band's mask keeps the ring in place. At rest the two are the same pixels:
+   same gradient, same centre, angle zero.
+   There is no direct query for @property support. transition-behavior
+   shipped after it in every engine (Chrome 117 vs 85, Firefox 129 vs 128,
+   Safari 17.4 vs 16.4), so it stands in: a yes is never wrong, and a no only
+   sends a capable browser down the fallback, which looks the same.
+   inherits: false so the angle stays on the element that animates it and
+   never reaches the host page or the well. */
+@property --zrl-angle {
+  syntax: '<angle>';
+  inherits: false;
+  initial-value: 0deg;
+}
+@keyframes ${PREFIX}-orbit { to { transform: rotate(360deg) } }
+@keyframes ${PREFIX}-orbit-angle { to { --zrl-angle: 360deg } }
+@supports (transition-behavior: allow-discrete) {
+  .${PREFIX}-qr-arc::before {
+    inset: 0;
+    animation-name: ${PREFIX}-orbit-angle;
+  }
+}
+
 @media (prefers-reduced-motion: reduce) {
   .${PREFIX}-scrim,
   .${PREFIX}-card,
@@ -1171,6 +1294,10 @@ var CSS = `
   .${PREFIX}-cancel,
   .${PREFIX}-close,
   .${PREFIX}-timer { transition: none }
+  /* No travelling light. The ring keeps a still, soft glow instead, a step
+     brighter than the spent state so pending and spent still read apart. */
+  .${PREFIX}-qr-arc::before { animation: none; opacity: 0 }
+  .${PREFIX}-qr-arc::after { opacity: 0.5 }
 }
 `;
 function ensureStyles() {
@@ -1275,6 +1402,10 @@ function mountPairingModal(state, options) {
   const title = el("h2", cx("title"));
   title.id = titleId;
   const bodyText = el("p", cx("body-text"));
+  const halo = el("div", cx("qr-halo"));
+  const glow = el("span", cx("qr-glow"));
+  glow.setAttribute("aria-hidden", "true");
+  glow.appendChild(el("span", cx("qr-arc")));
   const well = el("div", cx("qr-well"));
   const qr = el("img", cx("qr"));
   qr.alt = t.qrAlt;
@@ -1286,13 +1417,14 @@ function mountPairingModal(state, options) {
   badge.appendChild(strokeIcon(24, ["M8.5 2h7a2.5 2.5 0 0 1 2.5 2.5v15a2.5 2.5 0 0 1-2.5 2.5h-7A2.5 2.5 0 0 1 6 19.5v-15A2.5 2.5 0 0 1 8.5 2Z", "M11 18.5h2"], "1.8"));
   overlay.appendChild(badge);
   well.append(qr, overlay);
+  halo.append(glow, well);
   const status = el("div", cx("status"));
   const dot = el("span", cx("dot"));
   dot.append(el("i"), el("i"));
   const statusLabel = el("span");
   status.append(dot, statusLabel);
   const timer = el("p", cx("timer"));
-  body.append(mark, title, bodyText, well, status, timer);
+  body.append(mark, title, bodyText, halo, status, timer);
   const help = el("div", cx("help"));
   help.append(el("p", cx("help-title"), t.noIdTitle), el("p", cx("help-body"), t.noIdBody));
   const footer = el("div", cx("footer"));
@@ -1305,14 +1437,38 @@ 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;
     bodyText.textContent = s.status === "enrolling" ? t.bodyEnrolling : settled ? t.bodyApprove : t.bodyScan;
     statusLabel.textContent = settled ? t.waitingApproval : t.waiting;
     qr.dataset.spent = String(settled);
+    halo.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 +1485,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 +1535,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 +1564,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 +1575,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 +1606,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 +1677,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 +1710,7 @@ function startLogin(options) {
 0 && (module.exports = {
   DEFAULT_ISSUER,
   DEFAULT_PAIRING_TIMEOUT_MS,
+  DEFAULT_QR_REFRESH_SECONDS,
   FlowAbandonedError,
   OAuthFlowError,
   POLL_INTERVAL_ENROLLING_MS,