@zoreal/oauth2-react 0.2.18 → 0.2.19

package/README.md

@@ -251,7 +251,7 @@ What the modal does:
 
 | | |
 | --- | --- |
-| **Mobile** | No QR and no modal. The tap itself is a navigation: the SDK sends the tab to the provider's `/pair/start` with the pairing's parameters, synchronously from the click, and the provider answers with a redirect to the pairing's universal link, which the ZOREAL ID app claims while the page stays put and polls. A browser hands a link to an app only inside a navigation the person began, which is why nothing is fetched first. With no app installed the same redirect lands on the page that installs it. Call `login()` from the click handler itself: `ZorealLogin` does, disables itself and runs a light round its edge until the flow ends; a site with its own button keeps that button and draws its own busy state from the tap until `onSuccess` or `onError` fires, or wraps it in `ZorealBusyRing` to get the same light (a wrapper: pass `block` for a full-width button, keep `overflow: hidden` off its ancestors, and expect `.parent > button` selectors to stop matching). Force one or the other with `display: 'qr'` / `'link'`. |
+| **Mobile** | No QR and no modal. The tap itself is a navigation: the SDK sends the tab to the provider's `/pair/start` with the pairing's parameters, synchronously from the click, and the provider answers with a redirect to the pairing's universal link, which the ZOREAL ID app claims while the page stays put and polls. A browser hands a link to an app only inside a navigation the person began, which is why nothing is fetched first. With no app installed the same redirect lands on the page that installs it. Call `login()` from the click handler itself: `ZorealLogin` does, disables itself and runs a light round its edge until the flow ends. Once the holder has approved, the app reopens your page with the pairing named in the fragment, and the first `useZorealLogin` or `ZorealLogin` on that page finishes the sign-in there, through the same `onSuccess` and `onError`; the tab that was left behind stands down when the returned page finishes first; a site with its own button keeps that button and draws its own busy state from the tap until `onSuccess` or `onError` fires, or wraps it in `ZorealBusyRing` to get the same light (a wrapper: pass `block` for a full-width button, keep `overflow: hidden` off its ancestors, and expect `.parent > button` selectors to stop matching). Force one or the other with `display: 'qr'` / `'link'`. |
 | **Live status** | The copy and the title follow the pairing: waiting for a scan, then waiting for approval once the holder has claimed the code (the spent QR blurs out behind a phone glyph). |
 | **Title** | Says what the scan is for, inferred from the request: "Scan to sign in" for `openid`, `email` and `profile.name`; "Scan to verify your identity" once a document attribute such as `zoreal.age` or `profile.birthdate` is requested; "Scan to prove you are a real human" for `openid` alone with `acr_values: 'zoreal.live'`. Override with `intent`, one of `'sign-in'`, `'identify'`, `'presence'`, when the scope does not say. |
 | **Countdown** | Counts down to expiry, turning amber under 20s. Reads the clock each tick rather than decrementing, so a backgrounded tab comes back honest. |
@@ -551,6 +551,7 @@ These reach your callbacks before any backend is involved — handle them here:
 | `/pair` | `onError` | `login_required` | `prompt: 'none'` with no silent session to resume — the expected quiet outcome, not a failure (`useZorealAutoLogin` turns it into `onUnavailable`) |
 | pairing | `onNonOAuthError` | `request_denied` | The holder declined in their ZOREAL ID app — **not an error to alarm on**; offer to try again |
 | pairing | `onNonOAuthError` | `request_expired` | The pairing window elapsed, or a required liveness the device could not meet — offer to try again |
+| pairing | `onNonOAuthError` | `popup_closed` | The person closed the dialog, cancelled it, pressed Escape, tapped outside it, or let it time out — **not an error to alarm on**; clear your busy state and let them tap again |
 
 ### The type unions
 

package/dist/index.cjs

@@ -41,7 +41,7 @@ var import_react2 = require("react");
 
 // src/wire.ts
 var WIRE_VERSION = 1;
-var SDK_VERSION = "0.2.18";
+var SDK_VERSION = "0.2.19";
 var DEFAULT_ISSUER = "https://id.zoreal.com";
 var POLL_INTERVAL_MS = 2e3;
 var POLL_INTERVAL_ENROLLING_MS = 5e3;
@@ -1636,6 +1636,76 @@ var import_react5 = require("react");
 // src/useZorealLogin.ts
 var import_react3 = require("react");
 
+// src/return.ts
+var PREFIX2 = "zoreal:oauth2:return:";
+var DONE = "zoreal:oauth2:done:";
+var MAX_AGE_MS = 10 * 60 * 1e3;
+function storage() {
+  try {
+    return typeof localStorage === "undefined" ? null : localStorage;
+  } catch {
+    return null;
+  }
+}
+function saveReturnFlow(flow) {
+  try {
+    storage()?.setItem(PREFIX2 + flow.requestId, JSON.stringify(flow));
+  } catch {
+  }
+}
+function peekReturnFlow(requestId) {
+  const store = storage();
+  if (!store) return null;
+  const raw = store.getItem(PREFIX2 + requestId);
+  if (!raw) return null;
+  try {
+    const flow = JSON.parse(raw);
+    if (flow.v !== 1 || flow.requestId !== requestId) return null;
+    if (Date.now() - flow.createdAt > MAX_AGE_MS) return null;
+    return flow;
+  } catch {
+    return null;
+  }
+}
+function forgetReturnFlow(requestId) {
+  try {
+    storage()?.removeItem(PREFIX2 + requestId);
+  } catch {
+  }
+  if (pending === requestId) pending = null;
+}
+function markReturnDone(requestId) {
+  try {
+    const store = storage();
+    store?.setItem(DONE + requestId, String(Date.now()));
+    store?.removeItem(PREFIX2 + requestId);
+  } catch {
+  }
+}
+function isReturnDone(requestId) {
+  return storage()?.getItem(DONE + requestId) !== null && storage()?.getItem(DONE + requestId) !== void 0;
+}
+function returnToUrl() {
+  if (typeof window === "undefined") return void 0;
+  const { href } = window.location;
+  const hash = href.indexOf("#");
+  return hash === -1 ? href : href.slice(0, hash);
+}
+var RETURN_MARK = /(?:^|[#&])zoreal_return=([A-Za-z0-9]{32})(?:&|$)/;
+var pending = null;
+function pendingReturnId() {
+  if (pending) return pending;
+  if (typeof window === "undefined") return null;
+  const match = RETURN_MARK.exec(window.location.hash);
+  if (!match) return null;
+  pending = match[1];
+  try {
+    window.history.replaceState(window.history.state, "", returnToUrl());
+  } catch {
+  }
+  return pending;
+}
+
 // src/jwt.ts
 function unsafeClaims(idToken) {
   try {
@@ -2015,6 +2085,7 @@ function generateRequestId() {
 }
 
 // src/useZorealLogin.ts
+var resumedReturns = /* @__PURE__ */ new Set();
 function useZorealFlow(options) {
   const { clientId, issuer, locale } = useZorealOAuth();
   const [pairing, setPairing] = (0, import_react3.useState)(null);
@@ -2024,6 +2095,7 @@ function useZorealFlow(options) {
   const abortRef = (0, import_react3.useRef)(null);
   const optionsRef = (0, import_react3.useRef)(options);
   optionsRef.current = options;
+  const closedByPerson = (0, import_react3.useRef)(false);
   (0, import_react3.useEffect)(
     () => () => {
       abortRef.current?.abort();
@@ -2031,6 +2103,61 @@ function useZorealFlow(options) {
     },
     []
   );
+  (0, import_react3.useEffect)(() => {
+    const id = pendingReturnId();
+    if (!id || resumedReturns.has(id)) return;
+    const saved = peekReturnFlow(id);
+    if (!saved || saved.clientId !== clientId) return;
+    forgetReturnFlow(id);
+    resumedReturns.add(id);
+    const controller = new AbortController();
+    abortRef.current = controller;
+    void (async () => {
+      const opts = optionsRef.current;
+      try {
+        const code = await pollUntilApproved(issuer, id, void 0, controller.signal, {
+          tolerateUnknownUntil: Date.now() + 5e3
+        });
+        if (saved.flow === "auth-code") {
+          opts.onCode?.({
+            code,
+            scope: saved.scope,
+            app_state: saved.appState,
+            code_verifier: saved.verifier,
+            nonce: saved.nonce
+          });
+        } else {
+          const tokens = await exchangeCode(issuer, {
+            code,
+            code_verifier: saved.verifier,
+            client_id: clientId
+          });
+          const claims = unsafeClaims(tokens.id_token);
+          opts.onCredential?.({
+            credential: tokens.id_token,
+            clientId,
+            select_by: "app_link",
+            acr: claims.acr ?? "zoreal.device"
+          });
+        }
+        markReturnDone(id);
+      } catch (e) {
+        if (e instanceof DOMException && e.name === "AbortError") return;
+        if (e instanceof FlowAbandonedError) {
+          opts.onNonOAuthError?.(e.reason);
+          return;
+        }
+        if (e instanceof OAuthFlowError) {
+          opts.onError?.({ error: e.error, description: e.description });
+          return;
+        }
+        opts.onNonOAuthError?.({
+          type: "unknown",
+          description: e instanceof Error ? e.message : String(e)
+        });
+      }
+    })();
+  }, [clientId, issuer]);
   const login = (0, import_react3.useCallback)(() => {
     const opts = optionsRef.current;
     const run = async () => {
@@ -2047,8 +2174,23 @@ function useZorealFlow(options) {
       try {
         let code;
         let selectBy = "device";
+        let returnId = null;
         if (useAppLink) {
           const requestId = generateRequestId();
+          saveReturnFlow({
+            v: 1,
+            issuer,
+            clientId,
+            flow,
+            verifier,
+            nonce,
+            state,
+            scope: opts.scope ?? "openid",
+            appState: opts.app_state,
+            requestId,
+            createdAt: Date.now()
+          });
+          returnId = requestId;
           const startUrl = sameDeviceStartUrl(issuer, {
             client_id: clientId,
             scope: opts.scope ?? "openid",
@@ -2061,10 +2203,12 @@ function useZorealFlow(options) {
             prompt: opts.prompt,
             locale,
             request_id: requestId,
-            origin: window.location.origin
+            origin: window.location.origin,
+            return_to: returnToUrl()
           });
           selectBy = "app_link";
           const cancel = () => {
+            closedByPerson.current = true;
             controller.abort();
             setPairing(null);
           };
@@ -2091,6 +2235,9 @@ function useZorealFlow(options) {
             controller.signal,
             { tolerateUnknownUntil: Date.now() + 15e3 }
           );
+          if (isReturnDone(requestId)) {
+            throw new DOMException("aborted", "AbortError");
+          }
         } else {
           const started = await startPairing(issuer, {
             client_id: clientId,
@@ -2112,6 +2259,7 @@ function useZorealFlow(options) {
             selectBy = "qr";
             const qrRefreshSeconds = qrRefreshSecondsOf(started);
             const cancel = () => {
+              closedByPerson.current = true;
               controller.abort();
               setPairing(null);
               publishRef.current?.(null);
@@ -2161,6 +2309,7 @@ function useZorealFlow(options) {
         }
         setPairing(null);
         publishRef.current?.(null);
+        if (returnId) markReturnDone(returnId);
         if (flow === "auth-code") {
           opts.onCode?.({
             code,
@@ -2187,7 +2336,16 @@ function useZorealFlow(options) {
       } catch (e) {
         setPairing(null);
         publishRef.current?.(null);
-        if (e instanceof DOMException && e.name === "AbortError") return;
+        if (e instanceof DOMException && e.name === "AbortError") {
+          if (closedByPerson.current) {
+            closedByPerson.current = false;
+            opts.onNonOAuthError?.({
+              type: "popup_closed",
+              description: "the sign-in dialog was closed before the holder approved"
+            });
+          }
+          return;
+        }
         if (e instanceof FlowAbandonedError) {
           opts.onNonOAuthError?.(e.reason);
           return;