@zoreal/oauth2-react 0.2.18 → 0.2.20

package/README.md

@@ -89,41 +89,76 @@ import { ZorealOAuthProvider } from '@zoreal/oauth2-react';
 ```
 
 ```tsx
-// ZorealSignIn.tsx
-import { useZorealLogin } from '@zoreal/oauth2-react';
+// ZorealSignIn.tsx — your own button, the way a production sign-in page uses it.
+import { useState } from 'react';
+import { useZorealLogin, ZorealBusyRing, ZorealMark } from '@zoreal/oauth2-react';
+
+function ZorealSignIn({ onSignedIn }: { onSignedIn: () => void }) {
+  // Busy from the tap until the flow ends. On a computer that is while the
+  // pairing modal is open; on a phone it is the moment between the tap and
+  // the hand-over to the ZOREAL ID app. Cleared by every outcome below.
+  const [busy, setBusy] = useState(false);
 
-function ZorealSignIn() {
   // `email` (and profile.name, etc.) are returned from /userinfo on your backend.
   const login = useZorealLogin({
     flow: 'auth-code',
     scope: 'openid email profile.name',
     onSuccess: async ({ code, code_verifier, nonce }) => {
+      setBusy(false);
       // Send ALL THREE to your backend over TLS. It calls POST /token with the
       // code and verifier plus its client authentication, verifies the ID
       // token's nonce is this one, then reads the email and name from
       // /userinfo. That is where personal data is delivered.
-      await fetch('/api/auth/zoreal', {
+      const res = await fetch('/api/auth/zoreal', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ code, code_verifier, nonce }),
       });
+      if (res.ok) onSignedIn();
+    },
+    onError: (e) => {
+      setBusy(false);
+      console.error(e.description ?? e.error);
     },
-    onError: (e) => console.error(e.description ?? e.error),
     onNonOAuthError: (e) => {
-      // The holder closing or ignoring the request is not an error to surface.
-      if (e.type === 'request_denied' || e.type === 'request_expired') return;
+      setBusy(false);
+      // The holder declining or ignoring the request, or closing the dialog,
+      // is not an error to surface: the button is simply ready again.
+      if (e.type === 'request_denied' || e.type === 'request_expired' || e.type === 'popup_closed') return;
       console.error(e.description ?? e.type);
     },
   });
 
-  return <button onClick={login}>Continue with ZOREAL</button>;
+  return (
+    // The wrapper runs the pairing modal's light around the button while busy.
+    // `block` because this button fills its row; `radius` is the button's own.
+    <ZorealBusyRing busy={busy} radius={12} block>
+      <button
+        type="button"
+        disabled={busy}
+        aria-busy={busy}
+        onClick={() => {
+          if (busy) return;
+          setBusy(true);
+          login(); // from the click handler itself: on a phone this tap is the navigation
+        }}
+      >
+        <ZorealMark size={22} brand />
+        Continue with ZOREAL
+      </button>
+    </ZorealBusyRing>
+  );
 }
 ```
 
-That is the whole integration. When `login()` runs, the provider puts the
-pairing modal on screen; on a phone it skips the QR and opens the ZOREAL ID
-app instead. See [The pairing modal](#the-pairing-modal) for what it does and
-how to theme, translate, time out or replace it.
+That is the whole integration. When `login()` runs on a computer, the provider
+puts the pairing modal on screen. On a phone the tap itself navigates to the
+provider, which opens the ZOREAL ID app; once the person has approved, the app
+brings them back to this page, and the same hook finishes the sign-in and calls
+your `onSuccess` there. So mount this component on the page the sign-in starts
+from, and expect `onSuccess` on a fresh page load. See
+[The pairing modal](#the-pairing-modal) for what it does and how to theme,
+translate, time out or replace it.
 
 ## Quick start: the button (no backend, pseudonymous)
 
@@ -251,7 +286,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 +586,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
 
@@ -576,28 +612,28 @@ error path.
 
 ## A complete example
 
-A full sign-in component, end to end — the shape a real auth-code integration
-takes. It renders the button, renders its own pairing UI (the hook renders
-none), hands `{ code, code_verifier, nonce }` to your backend on success, and
-treats the decline/expiry path as the non-events they are.
+A full sign-in component, end to end, the shape a production auth-code
+integration takes: your own button, busy from the tap until the flow ends,
+the SDK's pairing modal on a computer and the app hand-over on a phone,
+`{ code, code_verifier, nonce }` to your backend on success, the human outcomes
+treated as the non-events they are, and the return from the app on a phone
+handled by the same hook.
 
 ```tsx
 import { useState } from 'react';
-import { ZorealOAuthProvider, useZorealLogin } from '@zoreal/oauth2-react';
-import type { PairingState } from '@zoreal/oauth2-react';
+import { ZorealOAuthProvider, useZorealLogin, ZorealBusyRing, ZorealMark } from '@zoreal/oauth2-react';
 
 function ZorealSignIn() {
-  const [pairing, setPairing] = useState<PairingState | null>(null);
+  const [busy, setBusy] = useState(false);
   const [note, setNote] = useState<string | null>(null);
 
   const login = useZorealLogin({
     flow: 'auth-code',
     scope: 'openid email profile.name',
     // acr_values: 'zoreal.live',  // request a fresh liveness for a step-up / high-value login
-    onPairingStateChange: setPairing,
 
     onSuccess: async ({ code, code_verifier, nonce }) => {
-      setPairing(null);
+      setBusy(false);
       // Post ALL THREE to YOUR backend over TLS. Your backend does the /token
       // exchange with its client authentication, verifies the ID token
       // (ES256 against the JWKS, iss/aud/exp, and this nonce), checks the acr
@@ -619,37 +655,38 @@ function ZorealSignIn() {
 
     // An OAuth error from the provider (e.g. a scope not on your allow list).
     onError: (e) => {
-      setPairing(null);
+      setBusy(false);
       setNote(e.description ?? e.error); // the provider's words, verbatim
     },
 
-    // The human outcomes: declined, expired, cancelled. Not faults — clear the
-    // pairing UI and let them try again. Do not alarm on these.
+    // The human outcomes: declined, expired, the dialog closed. Not faults:
+    // the button is ready again. Do not alarm on these.
     onNonOAuthError: (e) => {
-      setPairing(null);
+      setBusy(false);
       if (e.type === 'request_denied') setNote('Login was declined. Try again when ready.');
       else if (e.type === 'request_expired') setNote('That took too long. Try again.');
+      else if (e.type === 'popup_closed') setNote(null);
       else setNote('Something went wrong. Try again.');
     },
   });
 
   return (
     <div>
-      <button onClick={login}>Continue with ZOREAL</button>
-
-      {/* The hook renders nothing, so the pairing UI is yours. On desktop the
-          login cannot complete until something shows pairing.qrUrl to scan. */}
-      {pairing && !pairing.appLink && ['pending', 'claimed'].includes(pairing.status) && (
-        <div role="dialog" aria-label="Log in with ZOREAL">
-          <img src={pairing.qrUrl} alt="Log in with ZOREAL" width={200} height={200} />
-          <p>
-            {pairing.status === 'claimed'
-              ? 'Approve the login in your ZOREAL ID app.'
-              : 'Scan with your phone camera or the ZOREAL ID app.'}
-          </p>
-          <button onClick={pairing.cancel}>Cancel</button>
-        </div>
-      )}
+      <ZorealBusyRing busy={busy} radius={12} block>
+        <button
+          type="button"
+          disabled={busy}
+          aria-busy={busy}
+          onClick={() => {
+            if (busy) return;
+            setBusy(true);
+            login();
+          }}
+        >
+          <ZorealMark size={22} brand />
+          Continue with ZOREAL
+        </button>
+      </ZorealBusyRing>
 
       {note && <p role="status">{note}</p>}
     </div>
@@ -658,13 +695,20 @@ function ZorealSignIn() {
 
 export default function App() {
   return (
-    <ZorealOAuthProvider clientId="ast_your_asset_id">
+    <ZorealOAuthProvider clientId="ast_your_asset_id" locale="en" theme="auto">
       <ZorealSignIn />
     </ZorealOAuthProvider>
   );
 }
 ```
 
+On a computer the provider renders the pairing modal for this button; nothing
+here draws a QR. To draw your own instead, see
+[Rendering it yourself](#rendering-it-yourself). On a phone there is no dialog:
+the tap navigates to the provider, the ZOREAL ID app opens, and after the
+approval the app reopens this page, where `useZorealLogin` finishes the sign-in
+and `onSuccess` runs on that fresh page load.
+
 **The backend must verify.** This component only starts the flow and forwards a
 code; on its own it proves nothing. The security is your backend exchanging the
 code with its client authentication and verifying the signed ID token — use a

package/dist/index.cjs

@@ -25,6 +25,7 @@ __export(index_exports, {
   PairingModal: () => PairingModal,
   ZorealBusyRing: () => ZorealBusyRing,
   ZorealLogin: () => ZorealLogin,
+  ZorealMark: () => ZorealMark,
   ZorealOAuthProvider: () => ZorealOAuthProvider,
   hasGrantedAllScopesZoreal: () => hasGrantedAllScopesZoreal,
   hasGrantedAnyScopeZoreal: () => hasGrantedAnyScopeZoreal,
@@ -41,7 +42,7 @@ var import_react2 = require("react");
 
 // src/wire.ts
 var WIRE_VERSION = 1;
-var SDK_VERSION = "0.2.18";
+var SDK_VERSION = "0.2.20";
 var DEFAULT_ISSUER = "https://id.zoreal.com";
 var POLL_INTERVAL_MS = 2e3;
 var POLL_INTERVAL_ENROLLING_MS = 5e3;
@@ -1636,6 +1637,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 +2086,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 +2096,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 +2104,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 +2175,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 +2204,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 +2236,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 +2260,7 @@ function useZorealFlow(options) {
             selectBy = "qr";
             const qrRefreshSeconds = qrRefreshSecondsOf(started);
             const cancel = () => {
+              closedByPerson.current = true;
               controller.abort();
               setPairing(null);
               publishRef.current?.(null);
@@ -2161,6 +2310,7 @@ function useZorealFlow(options) {
         }
         setPairing(null);
         publishRef.current?.(null);
+        if (returnId) markReturnDone(returnId);
         if (flow === "auth-code") {
           opts.onCode?.({
             code,
@@ -2187,7 +2337,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;
@@ -2432,6 +2591,7 @@ function hasGrantedAnyScopeZoreal(response, firstScope, ...restScopes) {
   PairingModal,
   ZorealBusyRing,
   ZorealLogin,
+  ZorealMark,
   ZorealOAuthProvider,
   hasGrantedAllScopesZoreal,
   hasGrantedAnyScopeZoreal,