@zoreal/oauth2-react 0.2.7 → 0.2.9

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. */
@@ -71,10 +88,13 @@ interface ZorealButtonConfiguration {
     theme?: 'outline' | 'filled' | 'filled_black';
     size?: 'large' | 'medium' | 'small';
     /**
-     * All four are neutral. The button asserts nothing about a person who has not yet
-     * authenticated; there is no 'verified_human' variant.
+     * All five are neutral. The button asserts nothing about a person who has
+     * not yet authenticated; there is no 'verified_human' variant. 'verify_with'
+     * stays inside that rule: it names the act the button starts, not a state
+     * the person already holds — built for surfaces where the login IS a check
+     * (ZOREAL Meet's presence request), not a sign-in.
      */
-    text?: 'continue_with' | 'signin_with' | 'signup_with' | 'signin';
+    text?: 'continue_with' | 'signin_with' | 'signup_with' | 'signin' | 'verify_with';
     shape?: 'rectangular' | 'pill' | 'square';
     logo_alignment?: 'left' | 'center';
     width?: string | number;
@@ -126,8 +146,21 @@ interface AuthCodeFlowOptions extends ZorealLoginRequestOptions {
     redirect_uri?: string;
     ux_mode?: 'popup' | 'redirect';
 }
-type ZorealLoginProps = {
+/**
+ * The button runs either flow, discriminated on `flow` exactly as
+ * useZorealLogin is: browser-direct (the default) hands onSuccess an ID
+ * token; auth-code hands it the code, PKCE verifier and nonce for YOUR
+ * backend to redeem. Added in 0.2.8 — before that the button was
+ * browser-direct only and auth-code integrations had to rebuild the button
+ * around the hook to get the same pixels.
+ */
+type ZorealLoginProps = ({
+    flow?: 'browser-direct';
     onSuccess: (response: ZorealCredentialResponse) => void;
+} | {
+    flow: 'auth-code';
+    onSuccess: (response: ZorealCodeResponse) => void;
+}) & {
     onError?: (error: NonOAuthError) => void;
     containerProps?: React.ComponentPropsWithoutRef<'div'>;
 } & ZorealLoginRequestOptions & ZorealButtonConfiguration;

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. */
@@ -71,10 +88,13 @@ interface ZorealButtonConfiguration {
     theme?: 'outline' | 'filled' | 'filled_black';
     size?: 'large' | 'medium' | 'small';
     /**
-     * All four are neutral. The button asserts nothing about a person who has not yet
-     * authenticated; there is no 'verified_human' variant.
+     * All five are neutral. The button asserts nothing about a person who has
+     * not yet authenticated; there is no 'verified_human' variant. 'verify_with'
+     * stays inside that rule: it names the act the button starts, not a state
+     * the person already holds — built for surfaces where the login IS a check
+     * (ZOREAL Meet's presence request), not a sign-in.
      */
-    text?: 'continue_with' | 'signin_with' | 'signup_with' | 'signin';
+    text?: 'continue_with' | 'signin_with' | 'signup_with' | 'signin' | 'verify_with';
     shape?: 'rectangular' | 'pill' | 'square';
     logo_alignment?: 'left' | 'center';
     width?: string | number;
@@ -126,8 +146,21 @@ interface AuthCodeFlowOptions extends ZorealLoginRequestOptions {
     redirect_uri?: string;
     ux_mode?: 'popup' | 'redirect';
 }
-type ZorealLoginProps = {
+/**
+ * The button runs either flow, discriminated on `flow` exactly as
+ * useZorealLogin is: browser-direct (the default) hands onSuccess an ID
+ * token; auth-code hands it the code, PKCE verifier and nonce for YOUR
+ * backend to redeem. Added in 0.2.8 — before that the button was
+ * browser-direct only and auth-code integrations had to rebuild the button
+ * around the hook to get the same pixels.
+ */
+type ZorealLoginProps = ({
+    flow?: 'browser-direct';
     onSuccess: (response: ZorealCredentialResponse) => void;
+} | {
+    flow: 'auth-code';
+    onSuccess: (response: ZorealCodeResponse) => void;
+}) & {
     onError?: (error: NonOAuthError) => void;
     containerProps?: React.ComponentPropsWithoutRef<'div'>;
 } & ZorealLoginRequestOptions & ZorealButtonConfiguration;

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.7";
+var SDK_VERSION = "0.2.9";
 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";
@@ -1113,6 +1114,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(() => {
@@ -1164,7 +1182,7 @@ function PairingModal({
             /* @__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 }),
+              /* @__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: [
@@ -1302,55 +1320,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 +1439,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 +1490,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 +1503,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 +1512,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 +1521,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 +1547,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);
@@ -1555,7 +1631,8 @@ var TEXTS = {
   continue_with: "Continue with ZOREAL",
   signin_with: "Sign in with ZOREAL",
   signup_with: "Sign up with ZOREAL",
-  signin: "Sign in"
+  signin: "Sign in",
+  verify_with: "Verify with ZOREAL ID"
 };
 var SIZES = {
   large: { height: 44, font: 15, pad: 20 },
@@ -1575,12 +1652,14 @@ function ZorealLogin(props) {
     logo_alignment = "left",
     width,
     click_listener,
+    flow = "browser-direct",
     ...request
   } = props;
   const { login } = useZorealFlow({
     ...request,
-    flow: "browser-direct",
-    onCredential: onSuccess,
+    flow,
+    onCredential: flow === "browser-direct" ? onSuccess : void 0,
+    onCode: flow === "auth-code" ? onSuccess : void 0,
     onError: (e) => onError?.({ type: "unknown", description: e.description ?? e.error }),
     onNonOAuthError: (e) => onError?.(e)
   });