@zoreal/oauth2-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bynn Intelligence, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# @zoreal/oauth2-react
+
+Login with ZOREAL for React: a chip-verified human behind every sign-in.
+
+The API mirrors `@react-oauth/google` one to one, renamed, so a team already
+integrated with Google ports by find and replace. The full mapping and every
+design decision live in the specification this package is built against:
+`zoreal/products/oauth2/05-react-sdk.md` in the specification repo.
+
+## Status
+
+The package is real; the provider it speaks to is being built. This code pins
+wire protocol v1 and is not yet published to npm. Nothing below works against
+production today, and this section is removed the day that changes.
+
+## Install
+
+Not yet published. When it is: `npm install @zoreal/oauth2-react`.
+
+## Quick start: the button (no backend needed)
+
+```tsx
+import { ZorealOAuthProvider, ZorealLogin } from '@zoreal/oauth2-react';
+
+<ZorealOAuthProvider clientId="ast_your_asset_id">
+  <ZorealLogin
+    onSuccess={({ credential }) => {
+      // credential is an ID token: a pairwise pseudonymous `sub` plus
+      // assurance claims. Verify it server-side against the JWKS before
+      // trusting it. It NEVER contains personal data, by construction.
+    }}
+    onError={(e) => console.warn(e.type, e.description)}
+  />
+</ZorealOAuthProvider>
+```
+
+On desktop the button shows a QR; the user scans it with their phone and
+approves in the ZOREAL ID app. On a phone it opens the app directly. Either
+way your page just receives `onSuccess`.
+
+## Quick start: auth-code (personal data, requires your backend)
+
+```tsx
+import { useZorealLogin } from '@zoreal/oauth2-react';
+
+const login = useZorealLogin({
+  flow: 'auth-code',
+  scope: 'openid profile.name',
+  onSuccess: async ({ code, code_verifier }) => {
+    // Send BOTH to your backend over TLS. Your backend calls POST /token
+    // with them plus its client authentication (private_key_jwt, mTLS, or
+    // client secret), then reads personal claims from /userinfo.
+    await fetch('/api/auth/zoreal', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ code, code_verifier }),
+    });
+  },
+});
+```
+
+`ux_mode: 'redirect'` is not supported in v1: it would put the PKCE verifier
+in a URL, which is a credential in every access log on the path.
+
+## What your page needs to allow
+
+The package loads no third-party script, no stylesheet, no font, and has zero
+runtime dependencies. Two things touch the network, both on the ZOREAL origin:
+
+| CSP directive | Value | Why |
+|---|---|---|
+| `connect-src` | `https://id.zoreal.com` | starting the pairing, polling it, and (button mode) the code exchange |
+| `img-src` | `https://id.zoreal.com` | the QR image, served by the provider so it stays correct and current |
+
+## The rules this package follows
+
+- **No secret has a home here.** The provider takes no `clientSecret` prop and
+  never will; a pull request adding one is a security bug regardless of its
+  documentation.
+- **The ID token in browser mode carries no personal data.** Personal claims
+  exist only at `/userinfo`, behind an access token browser mode is never
+  issued for those scopes. There is no configuration that changes this.
+- **Server errors are shown, not rewritten.** Whatever reason the provider
+  gives, `description` carries it verbatim.
+- **The button copy is neutral.** "Continue with ZOREAL" and variants; there is
+  no "verified human" button text and there will not be one. The assertion
+  lives in the token, where it is verifiable.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,520 @@
+'use client';
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ZorealLogin: () => ZorealLogin,
+  ZorealOAuthProvider: () => ZorealOAuthProvider,
+  hasGrantedAllScopesZoreal: () => hasGrantedAllScopesZoreal,
+  hasGrantedAnyScopeZoreal: () => hasGrantedAnyScopeZoreal,
+  useZorealAutoLogin: () => useZorealAutoLogin,
+  useZorealLogin: () => useZorealLogin,
+  useZorealOAuth: () => useZorealOAuth,
+  zorealLogout: () => zorealLogout
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/context.tsx
+var import_react = require("react");
+
+// src/wire.ts
+var WIRE_VERSION = 1;
+var SDK_VERSION = "0.1.0";
+var DEFAULT_ISSUER = "https://id.zoreal.com";
+var POLL_INTERVAL_MS = 2e3;
+var POLL_INTERVAL_ENROLLING_MS = 5e3;
+
+// src/context.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var ZorealOAuthContext = (0, import_react.createContext)(null);
+function ZorealOAuthProvider({
+  clientId,
+  issuer = DEFAULT_ISSUER,
+  locale,
+  children
+}) {
+  const value = (0, import_react.useMemo)(
+    () => ({ clientId, issuer: issuer.replace(/\/$/, ""), locale }),
+    [clientId, issuer, locale]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ZorealOAuthContext.Provider, { value, children });
+}
+function useZorealOAuth() {
+  const ctx = (0, import_react.useContext)(ZorealOAuthContext);
+  if (!ctx) {
+    throw new Error(
+      "useZorealOAuth must be used inside <ZorealOAuthProvider clientId=...>. Wrap your app (or the part that logs in) in the provider."
+    );
+  }
+  return ctx;
+}
+
+// src/ZorealLogin.tsx
+var import_react3 = require("react");
+
+// src/useZorealLogin.ts
+var import_react2 = require("react");
+
+// src/jwt.ts
+function unsafeClaims(idToken) {
+  try {
+    const payload = idToken.split(".")[1] ?? "";
+    const b64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = b64 + "=".repeat((4 - b64.length % 4) % 4);
+    return JSON.parse(
+      new TextDecoder().decode(Uint8Array.from(atob(padded), (c) => c.charCodeAt(0)))
+    );
+  } catch {
+    return {};
+  }
+}
+
+// src/pairing.ts
+var OAuthFlowError = class extends Error {
+  constructor(error, description) {
+    super(description ?? error);
+    this.error = error;
+    this.description = description;
+  }
+};
+var FlowAbandonedError = class extends Error {
+  constructor(reason) {
+    super(reason.description ?? reason.type);
+    this.reason = reason;
+  }
+};
+async function parseJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    return {};
+  }
+}
+async function startPairing(issuer, params) {
+  const response = await fetch(`${issuer}/pair`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      ...params,
+      code_challenge_method: "S256",
+      wire_version: WIRE_VERSION,
+      sdk: `@zoreal/oauth2-react/${SDK_VERSION}`
+    })
+  });
+  const body = await parseJson(response);
+  if (!response.ok) {
+    throw new OAuthFlowError(
+      body.error ?? "server_error",
+      body.error_description ?? `The provider refused the request (${response.status})`
+    );
+  }
+  return body;
+}
+var sleep = (ms, signal) => new Promise((resolve, reject) => {
+  const t = setTimeout(resolve, ms);
+  signal?.addEventListener("abort", () => {
+    clearTimeout(t);
+    reject(new DOMException("aborted", "AbortError"));
+  });
+});
+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
+    });
+    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 "enrolling":
+        await sleep(POLL_INTERVAL_ENROLLING_MS, signal);
+        break;
+      default:
+        await sleep(POLL_INTERVAL_MS, signal);
+    }
+  }
+}
+async function exchangeCode(issuer, input) {
+  const response = await fetch(`${issuer}/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code: input.code,
+      code_verifier: input.code_verifier,
+      client_id: input.client_id
+    })
+  });
+  const body = await parseJson(response);
+  if (!response.ok || body.error) {
+    throw new OAuthFlowError(
+      body.error ?? "server_error",
+      body.error_description ?? `Token exchange failed (${response.status})`
+    );
+  }
+  return body;
+}
+function isMobileUserAgent() {
+  if (typeof navigator === "undefined") return false;
+  return /android|iphone|ipad|ipod/i.test(navigator.userAgent);
+}
+
+// src/pkce.ts
+var VERIFIER_BYTES = 32;
+var base64url = (bytes) => btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+function generateVerifier() {
+  const bytes = new Uint8Array(VERIFIER_BYTES);
+  crypto.getRandomValues(bytes);
+  return base64url(bytes);
+}
+async function challengeS256(verifier) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return base64url(new Uint8Array(digest));
+}
+function generateState() {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return base64url(bytes);
+}
+
+// src/useZorealLogin.ts
+function useZorealFlow(options) {
+  const { clientId, issuer, locale } = useZorealOAuth();
+  const [pairing, setPairing] = (0, import_react2.useState)(null);
+  const abortRef = (0, import_react2.useRef)(null);
+  const optionsRef = (0, import_react2.useRef)(options);
+  optionsRef.current = options;
+  (0, import_react2.useEffect)(() => () => abortRef.current?.abort(), []);
+  const login = (0, import_react2.useCallback)(() => {
+    const opts = optionsRef.current;
+    const run = async () => {
+      abortRef.current?.abort();
+      const controller = new AbortController();
+      abortRef.current = controller;
+      const flow = opts.flow;
+      const verifier = generateVerifier();
+      const state = generateState();
+      const nonce = generateState();
+      try {
+        const started = await startPairing(issuer, {
+          client_id: clientId,
+          scope: opts.scope ?? "openid",
+          state,
+          nonce,
+          code_challenge: await challengeS256(verifier),
+          redirect_uri: flow === "auth-code" ? opts.redirect_uri : void 0,
+          acr_values: Array.isArray(opts.acr_values) ? opts.acr_values.join(" ") : opts.acr_values,
+          max_age: opts.max_age,
+          prompt: opts.prompt,
+          locale
+        });
+        let code;
+        let selectBy = "device";
+        if ("code" in started) {
+          code = started.code;
+          selectBy = "session";
+        } else {
+          const useAppLink = opts.display === "link" || opts.display !== "qr" && isMobileUserAgent();
+          selectBy = useAppLink ? "app_link" : "qr";
+          const active = {
+            requestId: started.request_id,
+            pairUrl: started.pair_url,
+            qrUrl: `${issuer}/pair/${encodeURIComponent(started.request_id)}/qr.svg`,
+            state: { status: "pending", expiresIn: started.expires_in },
+            appLink: useAppLink,
+            cancel: () => {
+              controller.abort();
+              setPairing(null);
+            }
+          };
+          setPairing(active);
+          if (useAppLink) {
+            window.location.assign(started.pair_url);
+          }
+          code = await pollUntilApproved(
+            issuer,
+            started.request_id,
+            (s) => {
+              setPairing((p) => p && p.requestId === started.request_id ? { ...p, state: s } : p);
+              opts.onPairingStateChange?.(s);
+            },
+            controller.signal
+          );
+        }
+        setPairing(null);
+        if (flow === "auth-code") {
+          opts.onCode?.({
+            code,
+            scope: opts.scope ?? "openid",
+            app_state: opts.app_state,
+            code_verifier: verifier
+          });
+          return;
+        }
+        const tokens = await exchangeCode(issuer, {
+          code,
+          code_verifier: verifier,
+          client_id: clientId
+        });
+        const claims = unsafeClaims(tokens.id_token);
+        const response = {
+          credential: tokens.id_token,
+          clientId,
+          select_by: selectBy,
+          acr: claims.acr ?? "zoreal.device"
+        };
+        opts.onCredential?.(response);
+      } catch (e) {
+        setPairing(null);
+        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)
+        });
+      }
+    };
+    void run();
+  }, [clientId, issuer, locale]);
+  return { login, internals: { pairing } };
+}
+function useZorealLogin(options) {
+  if (options.ux_mode === "redirect") {
+    throw new Error(
+      "@zoreal/oauth2-react: ux_mode 'redirect' is not supported in v1. Use the default 'popup' shape and post the code and code_verifier from onSuccess to your backend."
+    );
+  }
+  const flow = options.flow ?? "browser-direct";
+  return useZorealFlow({
+    ...options,
+    flow,
+    onCredential: flow === "browser-direct" ? options.onSuccess : void 0,
+    onCode: flow === "auth-code" ? options.onSuccess : void 0
+  }).login;
+}
+
+// src/ZorealLogin.tsx
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var TEXTS = {
+  continue_with: "Continue with ZOREAL",
+  signin_with: "Sign in with ZOREAL",
+  signup_with: "Sign up with ZOREAL",
+  signin: "Sign in"
+};
+var SIZES = {
+  large: { height: 44, font: 15, pad: 20 },
+  medium: { height: 38, font: 14, pad: 16 },
+  small: { height: 32, font: 12, pad: 12 }
+};
+var Mark = ({ size }) => /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("svg", { width: size, height: size, viewBox: "0 0 24 24", "aria-hidden": true, focusable: "false", children: [
+  /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("circle", { cx: "12", cy: "12", r: "9", fill: "none", stroke: "currentColor", strokeWidth: "2.6" }),
+  /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("circle", { cx: "12", cy: "12", r: "3.4", fill: "currentColor" })
+] });
+var PairingPanel = ({ pairing }) => {
+  const { status } = pairing.state;
+  const line = status === "claimed" ? "Approve the login in your ZOREAL ID app." : status === "enrolling" ? "Finishing enrolment. This screen will continue by itself." : pairing.appLink ? "Continue in the ZOREAL ID app, then return to this tab." : "Scan with your phone camera or the ZOREAL ID app.";
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
+    "div",
+    {
+      role: "dialog",
+      "aria-label": "Log in with ZOREAL",
+      style: {
+        marginTop: 8,
+        padding: 16,
+        width: 232,
+        borderRadius: 12,
+        border: "1px solid rgba(128,128,128,0.35)",
+        background: "Canvas",
+        color: "CanvasText",
+        textAlign: "center",
+        fontFamily: "inherit"
+      },
+      children: [
+        !pairing.appLink && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+          "img",
+          {
+            src: pairing.qrUrl,
+            alt: `QR code for ${pairing.pairUrl}`,
+            width: 200,
+            height: 200,
+            style: { display: "block", margin: "0 auto", borderRadius: 8 }
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { style: { margin: "10px 0 0", fontSize: 12, lineHeight: 1.5 }, children: line }),
+        /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+          "button",
+          {
+            type: "button",
+            onClick: pairing.cancel,
+            style: {
+              marginTop: 10,
+              border: "none",
+              background: "none",
+              color: "inherit",
+              opacity: 0.6,
+              fontSize: 12,
+              cursor: "pointer",
+              textDecoration: "underline"
+            },
+            children: "Cancel"
+          }
+        )
+      ]
+    }
+  );
+};
+function ZorealLogin(props) {
+  const {
+    onSuccess,
+    onError,
+    containerProps,
+    type = "standard",
+    theme = "filled",
+    size = "large",
+    text = "continue_with",
+    shape = "rectangular",
+    logo_alignment = "left",
+    width,
+    click_listener,
+    ...request
+  } = props;
+  const { login, internals } = useZorealFlow({
+    ...request,
+    flow: "browser-direct",
+    onCredential: onSuccess,
+    onError: (e) => onError?.({ type: "unknown", description: e.description ?? e.error }),
+    onNonOAuthError: (e) => onError?.(e)
+  });
+  const s = SIZES[size];
+  const style = (0, import_react3.useMemo)(
+    () => ({
+      display: "inline-flex",
+      alignItems: "center",
+      justifyContent: logo_alignment === "center" ? "center" : "flex-start",
+      gap: 10,
+      height: s.height,
+      padding: `0 ${s.pad}px`,
+      width,
+      fontSize: s.font,
+      fontFamily: "inherit",
+      fontWeight: 500,
+      cursor: "pointer",
+      borderRadius: shape === "pill" ? s.height / 2 : shape === "square" ? 4 : 8,
+      ...theme === "outline" ? { background: "transparent", color: "inherit", border: "1px solid rgba(128,128,128,0.5)" } : theme === "filled_black" ? { background: "#111", color: "#fff", border: "1px solid #111" } : { background: "#00b4d9", color: "#fff", border: "1px solid #00b4d9" }
+    }),
+    [logo_alignment, s, shape, theme, width]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { ...containerProps, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
+      "button",
+      {
+        type: "button",
+        style,
+        onClick: () => {
+          click_listener?.();
+          login();
+        },
+        children: [
+          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(Mark, { size: Math.round(s.font * 1.25) }),
+          type === "standard" && TEXTS[text]
+        ]
+      }
+    ),
+    internals.pairing && !internals.pairing.appLink && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(PairingPanel, { pairing: internals.pairing })
+  ] });
+}
+
+// src/useZorealAutoLogin.ts
+var import_react4 = require("react");
+function useZorealAutoLogin(options) {
+  const { login } = useZorealFlow({
+    flow: "browser-direct",
+    scope: options.scope,
+    prompt: "none",
+    onCredential: options.onSuccess,
+    onError: (e) => {
+      const quiet = ["login_required", "consent_required", "interaction_required"];
+      if (quiet.includes(e.error)) {
+        options.onUnavailable?.();
+      } else {
+        options.onError?.({ type: "unknown", description: e.description ?? e.error });
+      }
+    },
+    onNonOAuthError: (e) => options.onError?.(e)
+  });
+  const fired = (0, import_react4.useRef)(false);
+  (0, import_react4.useEffect)(() => {
+    if (options.disabled || fired.current) return;
+    fired.current = true;
+    login();
+  }, [options.disabled, login]);
+}
+
+// src/logout.ts
+function zorealLogout() {
+}
+
+// src/scopes.ts
+function hasGrantedAllScopesZoreal(response, firstScope, ...restScopes) {
+  const granted = new Set((response.scope ?? "").split(/\s+/).filter(Boolean));
+  return [firstScope, ...restScopes].every((s) => granted.has(s));
+}
+function hasGrantedAnyScopeZoreal(response, firstScope, ...restScopes) {
+  const granted = new Set((response.scope ?? "").split(/\s+/).filter(Boolean));
+  return [firstScope, ...restScopes].some((s) => granted.has(s));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ZorealLogin,
+  ZorealOAuthProvider,
+  hasGrantedAllScopesZoreal,
+  hasGrantedAnyScopeZoreal,
+  useZorealAutoLogin,
+  useZorealLogin,
+  useZorealOAuth,
+  zorealLogout
+});
+//# sourceMappingURL=index.cjs.map