@zoreal/oauth2-react 0.2.8 → 0.2.10

package/dist/index.d.cts

@@ -37,8 +37,25 @@ interface PairingState {
      * carrying nothing to render. Present on every callback of a QR/link flow.
      */
     pairUrl?: string;
-    /** The provider-served SVG of pairUrl. Put it in an <img>; do not draw your own. */
+    /**
+     * The provider-served SVG to show right now. Put it in an <img>; do not draw
+     * your own.
+     *
+     * IT CHANGES DURING THE PAIRING. The code on screen is one frame of a
+     * rotating sequence, and a frame the provider has moved past is refused when
+     * the phone tries to claim it, which is what stops a screenshot of the code
+     * from being relayed to someone else's browser. So render the qrUrl of the
+     * state you are handed, every time you are handed one; a UI that caches the
+     * first value shows a code that stops working seconds later.
+     */
     qrUrl?: string;
+    /**
+     * How often, in seconds, `qrUrl` is replaced while the pairing is pending.
+     * Informational: the SDK already emits a new state on that cadence, so a
+     * custom UI does not need a timer of its own. Absent on the app link, which
+     * has no QR.
+     */
+    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. */

package/dist/index.d.ts

@@ -37,8 +37,25 @@ interface PairingState {
      * carrying nothing to render. Present on every callback of a QR/link flow.
      */
     pairUrl?: string;
-    /** The provider-served SVG of pairUrl. Put it in an <img>; do not draw your own. */
+    /**
+     * The provider-served SVG to show right now. Put it in an <img>; do not draw
+     * your own.
+     *
+     * IT CHANGES DURING THE PAIRING. The code on screen is one frame of a
+     * rotating sequence, and a frame the provider has moved past is refused when
+     * the phone tries to claim it, which is what stops a screenshot of the code
+     * from being relayed to someone else's browser. So render the qrUrl of the
+     * state you are handed, every time you are handed one; a UI that caches the
+     * first value shows a code that stops working seconds later.
+     */
     qrUrl?: string;
+    /**
+     * How often, in seconds, `qrUrl` is replaced while the pairing is pending.
+     * Informational: the SDK already emits a new state on that cadence, so a
+     * custom UI does not need a timer of its own. Absent on the app link, which
+     * has no QR.
+     */
+    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. */

package/dist/index.js

@@ -5,10 +5,11 @@ import { createContext, useContext, useMemo, useState as useState2 } from "react
 
 // src/wire.ts
 var WIRE_VERSION = 1;
-var SDK_VERSION = "0.2.8";
+var SDK_VERSION = "0.2.10";
 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/PairingModal.tsx
 import { useEffect, useId, useRef, useState } from "react";
@@ -905,20 +906,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%;
@@ -1061,6 +1152,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,
@@ -1070,6 +1188,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() {
@@ -1113,6 +1235,23 @@ function PairingModal({
   const deadlineRef = useRef(0);
   const [remaining, setRemaining] = useState(Math.round(timeoutMs / 1e3));
   const settled = state.status === "claimed" || state.status === "enrolling";
+  const [frameUrl, setFrameUrl] = useState(qrUrl);
+  useEffect(() => {
+    if (settled || frameUrl === qrUrl) return;
+    let abandoned = false;
+    const next = new Image();
+    next.onload = () => {
+      if (!abandoned) setFrameUrl(qrUrl);
+    };
+    next.onerror = () => {
+    };
+    next.src = qrUrl;
+    return () => {
+      abandoned = true;
+      next.onload = null;
+      next.onerror = null;
+    };
+  }, [qrUrl, settled, frameUrl]);
   const onCancelRef = useRef(onCancel);
   onCancelRef.current = onCancel;
   useEffect(() => {
@@ -1163,9 +1302,12 @@ function PairingModal({
             /* @__PURE__ */ jsx3(ZorealLockup, { height: 44, className: cx("lockup") }),
             /* @__PURE__ */ jsx3("h2", { id: titleId, className: cx("title"), children: settled ? t.titleApprove : t.title }),
             /* @__PURE__ */ jsx3("p", { className: cx("body-text"), children: body }),
-            /* @__PURE__ */ jsxs3("div", { className: cx("qr-well"), children: [
-              /* @__PURE__ */ jsx3("img", { className: cx("qr"), "data-spent": settled, src: qrUrl, alt: t.qrAlt, width: 180, height: 180 }),
-              settled && /* @__PURE__ */ jsx3("span", { className: cx("qr-overlay"), children: /* @__PURE__ */ jsx3("span", { className: cx("qr-badge"), children: /* @__PURE__ */ jsx3(IconPhone, {}) }) })
+            /* @__PURE__ */ jsxs3("div", { className: cx("qr-halo"), "data-spent": settled, children: [
+              /* @__PURE__ */ jsx3("span", { className: cx("qr-glow"), "aria-hidden": true, children: /* @__PURE__ */ jsx3("span", { className: cx("qr-arc") }) }),
+              /* @__PURE__ */ jsxs3("div", { className: cx("qr-well"), children: [
+                /* @__PURE__ */ jsx3("img", { className: cx("qr"), "data-spent": settled, src: frameUrl, alt: t.qrAlt, width: 180, height: 180 }),
+                settled && /* @__PURE__ */ jsx3("span", { className: cx("qr-overlay"), children: /* @__PURE__ */ jsx3("span", { className: cx("qr-badge"), children: /* @__PURE__ */ jsx3(IconPhone, {}) }) })
+              ] })
             ] }),
             /* @__PURE__ */ jsxs3("div", { className: cx("status"), children: [
               /* @__PURE__ */ jsxs3("span", { className: cx("dot"), children: [
@@ -1302,55 +1444,99 @@ async function startPairing(issuer, params) {
   }
   return body;
 }
+function qrRefreshSecondsOf(started) {
+  const seconds = started.qr_refresh_seconds;
+  return typeof seconds === "number" && seconds > 0 ? seconds : DEFAULT_QR_REFRESH_SECONDS;
+}
+function qrFrameUrl(issuer, requestId) {
+  return `${issuer}/pair/${encodeURIComponent(requestId)}/qr.svg?t=${Date.now()}`;
+}
 var sleep = (ms, signal) => new Promise((resolve, reject) => {
   if (signal?.aborted) {
     reject(new DOMException("aborted", "AbortError"));
     return;
   }
-  const t = setTimeout(resolve, ms);
-  signal?.addEventListener("abort", () => {
-    clearTimeout(t);
+  const onAbort = () => {
+    clearTimeout(timer);
     reject(new DOMException("aborted", "AbortError"));
-  });
+  };
+  const timer = setTimeout(() => {
+    signal?.removeEventListener("abort", onAbort);
+    resolve();
+  }, ms);
+  signal?.addEventListener("abort", onAbort, { once: true });
 });
-async function pollUntilApproved(issuer, requestId, onState, signal) {
-  for (; ; ) {
-    const response = await fetch(`${issuer}/pair/${encodeURIComponent(requestId)}/status`, {
-      signal
-    });
-    const body = await parseJson(response);
-    if (!response.ok) {
-      throw new OAuthFlowError(
-        body.error ?? "server_error",
-        body.error_description ?? `Pairing status failed (${response.status})`
-      );
-    }
-    onState?.({
-      status: body.status,
-      expiresIn: body.expires_in,
-      enrolmentDeadline: body.enrolment_deadline
+async function pollUntilApproved(issuer, requestId, onState, signal, options = {}) {
+  let last = { status: "pending" };
+  const emit = (state) => {
+    last = state;
+    onState?.(state);
+  };
+  let frames = null;
+  const stopFrames = () => {
+    frames?.abort();
+    frames = null;
+  };
+  const startFrames = () => {
+    const seconds = options.qrRefreshSeconds;
+    if (frames || signal?.aborted || typeof seconds !== "number" || !(seconds > 0)) return;
+    const period = seconds * 1e3;
+    const controller = new AbortController();
+    frames = controller;
+    signal?.addEventListener("abort", stopFrames, { signal: controller.signal });
+    void (async () => {
+      let due = Date.now() + period;
+      for (; ; ) {
+        await sleep(Math.max(0, due - Date.now()), controller.signal);
+        emit({ ...last, qrUrl: qrFrameUrl(issuer, requestId) });
+        due = Date.now() + period;
+      }
+    })().catch(() => {
     });
-    switch (body.status) {
-      case "approved":
-        if (!body.code) {
-          throw new OAuthFlowError("server_error", "approved with no authorization code");
-        }
-        return body.code;
-      case "denied":
-        throw new FlowAbandonedError({ type: "request_denied", description: body.error_description });
-      case "expired":
-        throw new FlowAbandonedError({ type: "request_expired", description: body.error_description });
-      case "cancelled":
-        throw new FlowAbandonedError({
-          type: "request_expired",
-          description: body.error_description ?? "the provider cancelled the pairing request"
-        });
-      case "enrolling":
-        await sleep(POLL_INTERVAL_ENROLLING_MS, signal);
-        break;
-      default:
-        await sleep(POLL_INTERVAL_MS, signal);
+  };
+  try {
+    for (; ; ) {
+      const response = await fetch(`${issuer}/pair/${encodeURIComponent(requestId)}/status`, {
+        signal
+      });
+      const body = await parseJson(response);
+      if (!response.ok) {
+        throw new OAuthFlowError(
+          body.error ?? "server_error",
+          body.error_description ?? `Pairing status failed (${response.status})`
+        );
+      }
+      emit({
+        status: body.status,
+        expiresIn: body.expires_in,
+        enrolmentDeadline: body.enrolment_deadline
+      });
+      if (body.status === "pending") startFrames();
+      else stopFrames();
+      switch (body.status) {
+        case "approved":
+          if (!body.code) {
+            throw new OAuthFlowError("server_error", "approved with no authorization code");
+          }
+          return body.code;
+        case "denied":
+          throw new FlowAbandonedError({ type: "request_denied", description: body.error_description });
+        case "expired":
+          throw new FlowAbandonedError({ type: "request_expired", description: body.error_description });
+        case "cancelled":
+          throw new FlowAbandonedError({
+            type: "request_expired",
+            description: body.error_description ?? "the provider cancelled the pairing request"
+          });
+        case "enrolling":
+          await sleep(POLL_INTERVAL_ENROLLING_MS, signal);
+          break;
+        default:
+          await sleep(POLL_INTERVAL_MS, signal);
+      }
     }
+  } finally {
+    stopFrames();
   }
 }
 async function exchangeCode(issuer, input) {
@@ -1377,6 +1563,11 @@ function isMobileUserAgent() {
   if (typeof navigator === "undefined") return false;
   return /android|iphone|ipad|ipod/i.test(navigator.userAgent);
 }
+function resolveDisplay(display) {
+  if (display === "link") return "link";
+  if (display === "qr") return "qr";
+  return isMobileUserAgent() ? "link" : "qr";
+}
 
 // src/pkce.ts
 var VERIFIER_BYTES = 32;
@@ -1423,6 +1614,8 @@ function useZorealFlow(options) {
       const verifier = generateVerifier();
       const state = generateState();
       const nonce = generateState();
+      const display = resolveDisplay(opts.display);
+      const useAppLink = display === "link";
       try {
         const started = await startPairing(issuer, {
           client_id: clientId,
@@ -1434,7 +1627,8 @@ function useZorealFlow(options) {
           acr_values: Array.isArray(opts.acr_values) ? opts.acr_values.join(" ") : opts.acr_values,
           max_age: opts.max_age,
           prompt: opts.prompt,
-          locale
+          locale,
+          display
         });
         let code;
         let selectBy = "device";
@@ -1442,8 +1636,8 @@ function useZorealFlow(options) {
           code = started.code;
           selectBy = "session";
         } else {
-          const useAppLink = opts.display === "link" || opts.display !== "qr" && isMobileUserAgent();
           selectBy = useAppLink ? "app_link" : "qr";
+          const qrRefreshSeconds = qrRefreshSecondsOf(started);
           const cancel = () => {
             controller.abort();
             setPairing(null);
@@ -1451,21 +1645,23 @@ function useZorealFlow(options) {
           };
           const surface = {
             pairUrl: started.pair_url,
-            qrUrl: `${issuer}/pair/${encodeURIComponent(started.request_id)}/qr.svg`,
             appLink: useAppLink,
-            cancel
+            cancel,
+            // The app link has no QR and therefore no cadence to report.
+            ...useAppLink ? null : { qrRefreshSeconds }
           };
+          let qrUrl = `${issuer}/pair/${encodeURIComponent(started.request_id)}/qr.svg`;
           const active = {
             requestId: started.request_id,
             pairUrl: surface.pairUrl,
-            qrUrl: surface.qrUrl,
-            state: { status: "pending", expiresIn: started.expires_in, ...surface },
+            qrUrl,
+            state: { status: "pending", expiresIn: started.expires_in, qrUrl, ...surface },
             appLink: useAppLink,
             cancel
           };
           setPairing(active);
           if (!useAppLink) {
-            publishRef.current?.({ state: active.state, qrUrl: surface.qrUrl, cancel });
+            publishRef.current?.({ state: active.state, qrUrl, cancel });
           }
           opts.onPairingStateChange?.(active.state);
           if (useAppLink) {
@@ -1475,16 +1671,20 @@ function useZorealFlow(options) {
             issuer,
             started.request_id,
             (s) => {
-              const enriched = { ...s, ...surface };
+              if (s.qrUrl) qrUrl = s.qrUrl;
+              const enriched = { ...s, ...surface, qrUrl };
               setPairing(
-                (p) => p && p.requestId === started.request_id ? { ...p, state: enriched } : p
+                (p) => p && p.requestId === started.request_id ? { ...p, qrUrl, state: enriched } : p
               );
               if (!useAppLink) {
-                publishRef.current?.({ state: enriched, qrUrl: surface.qrUrl, cancel });
+                publishRef.current?.({ state: enriched, qrUrl, cancel });
               }
               opts.onPairingStateChange?.(enriched);
             },
-            controller.signal
+            controller.signal,
+            // The app link has no QR to animate, and the provider answers 404
+            // for one, so the frames are asked for only on the QR surface.
+            { qrRefreshSeconds: useAppLink ? void 0 : qrRefreshSeconds }
           );
         }
         setPairing(null);