@authowl/react 0.16.1 → 0.17.1

package/README.md

@@ -67,6 +67,15 @@ When phone OTP is enabled, `<SignIn />` adds the localized phone flow automatica
 `<PhoneOTP />` is also available as a standalone surface. Production hosts must allow
 Cloudflare Turnstile's challenge script in their Content Security Policy. Local and CI
 servers use AuthOwl's documented dummy-token path when no public site key is configured.
+When the server selects an Akedly Shield V1.2 route, these components fetch a fresh
+challenge and complete its proof-of-work and optional Turnstile ceremony automatically.
+Provider API keys and pipeline credentials remain server-side. Custom phone UIs can call
+`phoneOtp.prepare()` and `solvePhoneOtpChallenge()` to implement the same guarded flow.
+See the [complete headless and retry guide](https://github.com/mstfash/authowl-sdk/blob/main/docs/phone-otp.md).
+
+`@akedly/shield` is installed with `@authowl/core` so every consumer bundler can
+resolve the integration safely. It remains behind a dynamic import, so its
+browser proof code is loaded only when the server selects a Shield route.
 
 When broad auth protection is enabled, the sign-in, sign-up, magic-link, email
 OTP, password-reset, and verification components automatically run an

package/dist/index.cjs

@@ -519,6 +519,7 @@ function useSignIn() {
     signInPasskey: client.signIn.passkey,
     sendEmailOtp: client.emailOtp.sendVerificationOtp,
     signInEmailOtp: client.signIn.emailOtp,
+    preparePhoneOtp: client.phoneOtp.prepare,
     startPhoneOtp: client.phoneOtp.start,
     verifyPhoneOtp: client.phoneOtp.verify
   };
@@ -879,6 +880,14 @@ function SocialButtons({ providers, callbackURL }) {
   const { signInSocial } = useSignIn();
   const [pending, setPending] = React6.useState(null);
   const [error, setError] = React6.useState(null);
+  React6.useEffect(() => {
+    if (typeof window === "undefined") return;
+    const url = new URL(window.location.href);
+    if (!url.searchParams.has("authowl_error")) return;
+    url.searchParams.delete("authowl_error");
+    window.history.replaceState(window.history.state, "", url.toString());
+    setError(t("social.error.startFailed"));
+  }, [t]);
   if (providers.length === 0) return null;
   return /* @__PURE__ */ (0, import_jsx_runtime6.jsxs)("div", { className: "ba-social", children: [
     providers.map((provider) => /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(
@@ -893,7 +902,11 @@ function SocialButtons({ providers, callbackURL }) {
           setPending(provider);
           try {
             const destination = callbackURL ?? window.location.href;
-            const res = await signInSocial({ provider, callbackURL: destination });
+            const res = await signInSocial({
+              provider,
+              callbackURL: destination,
+              errorCallbackURL: window.location.href
+            });
             if (res?.error) {
               setError(toServerError(res.error, t("social.error.startFailed")));
               setPending(null);
@@ -1417,16 +1430,46 @@ function PhoneOTP({ redirectTo, onSignedIn, onBack }) {
   const t = useT();
   const { sessionStore } = useAuthClient();
   const { config, isLoading } = usePublicConfig();
-  const { startPhoneOtp, verifyPhoneOtp } = useSignIn();
+  const { preparePhoneOtp, startPhoneOtp, verifyPhoneOtp } = useSignIn();
   const { pending, error, setError, run } = useSubmitAction();
   const [stage, setStage] = React11.useState("phone");
   const [phoneNumber, setPhoneNumber] = React11.useState("");
   const [code, setCode] = React11.useState("");
   const [turnstileToken, setTurnstileToken] = React11.useState(null);
+  const [guardState, setGuardState] = React11.useState({ status: "loading" });
   const [accepted, setAccepted] = React11.useState(false);
   const attempt = React11.useRef(null);
+  const guardRequest = React11.useRef(0);
   const legal = config?.legal;
   const consentBlocked = Boolean(legal?.required && !accepted);
+  const guard = guardState.status === "ready" ? guardState.data : null;
+  const turnstileBlocked = guardState.status === "ready" && guardState.data.kind === "authowl_turnstile" && !turnstileToken;
+  const humanCheckError = t("phoneOtp.error.humanCheck");
+  const loadGuard = React11.useCallback(async () => {
+    const request = ++guardRequest.current;
+    setGuardState({ status: "loading" });
+    setError(null);
+    try {
+      const result = await preparePhoneOtp();
+      if (request !== guardRequest.current) return;
+      if (result.error || !result.data) {
+        setGuardState({ status: "error" });
+        setError(humanCheckError);
+        return;
+      }
+      setGuardState({ status: "ready", data: result.data });
+    } catch {
+      if (request !== guardRequest.current) return;
+      setGuardState({ status: "error" });
+      setError(humanCheckError);
+    }
+  }, [humanCheckError, preparePhoneOtp, setError]);
+  React11.useEffect(() => {
+    void loadGuard();
+    return () => {
+      guardRequest.current += 1;
+    };
+  }, [loadGuard]);
   if (isLoading) {
     return /* @__PURE__ */ (0, import_jsx_runtime16.jsxs)("div", { className: "ba-fields", "data-testid": "phoneotp-loading", "aria-busy": "true", children: [
       /* @__PURE__ */ (0, import_jsx_runtime16.jsx)("div", { className: "ba-skeleton" }),
@@ -1519,7 +1562,7 @@ function PhoneOTP({ redirectTo, onSignedIn, onBack }) {
           setError(t("signUp.error.consentRequired"));
           return;
         }
-        if (!turnstileToken) {
+        if (!guard || guard.kind === "authowl_turnstile" && !turnstileToken) {
           setError(t("phoneOtp.error.humanCheck"));
           return;
         }
@@ -1528,7 +1571,23 @@ function PhoneOTP({ redirectTo, onSignedIn, onBack }) {
         }
         const idempotencyKey = attempt.current.idempotencyKey;
         void run(
-          () => startPhoneOtp({ phoneNumber, turnstileToken, idempotencyKey }),
+          async () => {
+            const selected = guard?.kind === "akedly_shield_v1_2" ? await preparePhoneOtp() : null;
+            if (selected?.error || selected && !selected.data) {
+              setGuardState({ status: "error" });
+              throw new Error("Phone OTP guard could not be prepared.");
+            }
+            const current = selected?.data ?? guard;
+            if (selected?.data) setGuardState({ status: "ready", data: selected.data });
+            if (current?.kind === "akedly_shield_v1_2") {
+              const akedlyShield = await (0, import_core4.solvePhoneOtpChallenge)(current);
+              return startPhoneOtp({ phoneNumber, akedlyShield, idempotencyKey });
+            }
+            if (current?.kind === "authowl_turnstile" && turnstileToken) {
+              return startPhoneOtp({ phoneNumber, turnstileToken, idempotencyKey });
+            }
+            throw new Error("Phone OTP guard is unavailable.");
+          },
           {
             failure: t("phoneOtp.error.sendFailed"),
             onSuccess: () => setStage("code")
@@ -1565,7 +1624,7 @@ function PhoneOTP({ redirectTo, onSignedIn, onBack }) {
             testId: "phoneotp-consent"
           }
         ),
-        /* @__PURE__ */ (0, import_jsx_runtime16.jsx)(
+        guard?.kind === "authowl_turnstile" && /* @__PURE__ */ (0, import_jsx_runtime16.jsx)(
           Turnstile,
           {
             siteKey: config?.turnstileSiteKey ?? null,
@@ -1575,12 +1634,23 @@ function PhoneOTP({ redirectTo, onSignedIn, onBack }) {
           }
         ),
         /* @__PURE__ */ (0, import_jsx_runtime16.jsx)(FormError, { children: error }),
+        guardState.status === "error" && /* @__PURE__ */ (0, import_jsx_runtime16.jsx)(
+          "button",
+          {
+            type: "button",
+            className: "ba-link-button",
+            onClick: () => {
+              void loadGuard();
+            },
+            children: t("phoneOtp.retryHumanCheck")
+          }
+        ),
         /* @__PURE__ */ (0, import_jsx_runtime16.jsx)(
           "button",
           {
             className: "ba-button",
             type: "submit",
-            disabled: pending || !turnstileToken || consentBlocked,
+            disabled: pending || guardState.status !== "ready" || turnstileBlocked || consentBlocked,
             "aria-busy": pending || void 0,
             children: /* @__PURE__ */ (0, import_jsx_runtime16.jsx)(Busy, { busy: pending, label: t("common.sending"), children: t("phoneOtp.sendSubmit") })
           }

package/dist/index.d.cts

@@ -167,6 +167,8 @@ type UseSignInResult = {
     /** Passwordless: complete sign-in with the emailed code. */
     signInEmailOtp: AuthOwlClient['signIn']['emailOtp'];
     /** Managed SMS: request a phone verification code. */
+    preparePhoneOtp: AuthOwlClient['phoneOtp']['prepare'];
+    /** Managed SMS: request a phone verification code. */
     startPhoneOtp: AuthOwlClient['phoneOtp']['start'];
     /** Managed SMS: verify the phone code and establish a session. */
     verifyPhoneOtp: AuthOwlClient['phoneOtp']['verify'];

package/dist/index.d.ts

@@ -167,6 +167,8 @@ type UseSignInResult = {
     /** Passwordless: complete sign-in with the emailed code. */
     signInEmailOtp: AuthOwlClient['signIn']['emailOtp'];
     /** Managed SMS: request a phone verification code. */
+    preparePhoneOtp: AuthOwlClient['phoneOtp']['prepare'];
+    /** Managed SMS: request a phone verification code. */
     startPhoneOtp: AuthOwlClient['phoneOtp']['start'];
     /** Managed SMS: verify the phone code and establish a session. */
     verifyPhoneOtp: AuthOwlClient['phoneOtp']['verify'];

package/dist/index.js

@@ -436,6 +436,7 @@ function useSignIn() {
     signInPasskey: client.signIn.passkey,
     sendEmailOtp: client.emailOtp.sendVerificationOtp,
     signInEmailOtp: client.signIn.emailOtp,
+    preparePhoneOtp: client.phoneOtp.prepare,
     startPhoneOtp: client.phoneOtp.start,
     verifyPhoneOtp: client.phoneOtp.verify
   };
@@ -798,6 +799,14 @@ function SocialButtons({ providers, callbackURL }) {
   const { signInSocial } = useSignIn();
   const [pending, setPending] = React6.useState(null);
   const [error, setError] = React6.useState(null);
+  React6.useEffect(() => {
+    if (typeof window === "undefined") return;
+    const url = new URL(window.location.href);
+    if (!url.searchParams.has("authowl_error")) return;
+    url.searchParams.delete("authowl_error");
+    window.history.replaceState(window.history.state, "", url.toString());
+    setError(t("social.error.startFailed"));
+  }, [t]);
   if (providers.length === 0) return null;
   return /* @__PURE__ */ jsxs3("div", { className: "ba-social", children: [
     providers.map((provider) => /* @__PURE__ */ jsx6(
@@ -812,7 +821,11 @@ function SocialButtons({ providers, callbackURL }) {
           setPending(provider);
           try {
             const destination = callbackURL ?? window.location.href;
-            const res = await signInSocial({ provider, callbackURL: destination });
+            const res = await signInSocial({
+              provider,
+              callbackURL: destination,
+              errorCallbackURL: window.location.href
+            });
             if (res?.error) {
               setError(toServerError(res.error, t("social.error.startFailed")));
               setPending(null);
@@ -1287,7 +1300,10 @@ function AuthOwlBadge({ href = "https://authowl.dev", force } = {}) {
 
 // src/components/PhoneOTP.tsx
 import * as React11 from "react";
-import { createIdempotencyKey } from "@authowl/core";
+import {
+  createIdempotencyKey,
+  solvePhoneOtpChallenge
+} from "@authowl/core";
 
 // src/components/ConsentDocLinks.tsx
 import { Fragment as Fragment4, jsx as jsx14, jsxs as jsxs10 } from "react/jsx-runtime";
@@ -1336,16 +1352,46 @@ function PhoneOTP({ redirectTo, onSignedIn, onBack }) {
   const t = useT();
   const { sessionStore } = useAuthClient();
   const { config, isLoading } = usePublicConfig();
-  const { startPhoneOtp, verifyPhoneOtp } = useSignIn();
+  const { preparePhoneOtp, startPhoneOtp, verifyPhoneOtp } = useSignIn();
   const { pending, error, setError, run } = useSubmitAction();
   const [stage, setStage] = React11.useState("phone");
   const [phoneNumber, setPhoneNumber] = React11.useState("");
   const [code, setCode] = React11.useState("");
   const [turnstileToken, setTurnstileToken] = React11.useState(null);
+  const [guardState, setGuardState] = React11.useState({ status: "loading" });
   const [accepted, setAccepted] = React11.useState(false);
   const attempt = React11.useRef(null);
+  const guardRequest = React11.useRef(0);
   const legal = config?.legal;
   const consentBlocked = Boolean(legal?.required && !accepted);
+  const guard = guardState.status === "ready" ? guardState.data : null;
+  const turnstileBlocked = guardState.status === "ready" && guardState.data.kind === "authowl_turnstile" && !turnstileToken;
+  const humanCheckError = t("phoneOtp.error.humanCheck");
+  const loadGuard = React11.useCallback(async () => {
+    const request = ++guardRequest.current;
+    setGuardState({ status: "loading" });
+    setError(null);
+    try {
+      const result = await preparePhoneOtp();
+      if (request !== guardRequest.current) return;
+      if (result.error || !result.data) {
+        setGuardState({ status: "error" });
+        setError(humanCheckError);
+        return;
+      }
+      setGuardState({ status: "ready", data: result.data });
+    } catch {
+      if (request !== guardRequest.current) return;
+      setGuardState({ status: "error" });
+      setError(humanCheckError);
+    }
+  }, [humanCheckError, preparePhoneOtp, setError]);
+  React11.useEffect(() => {
+    void loadGuard();
+    return () => {
+      guardRequest.current += 1;
+    };
+  }, [loadGuard]);
   if (isLoading) {
     return /* @__PURE__ */ jsxs12("div", { className: "ba-fields", "data-testid": "phoneotp-loading", "aria-busy": "true", children: [
       /* @__PURE__ */ jsx16("div", { className: "ba-skeleton" }),
@@ -1438,7 +1484,7 @@ function PhoneOTP({ redirectTo, onSignedIn, onBack }) {
           setError(t("signUp.error.consentRequired"));
           return;
         }
-        if (!turnstileToken) {
+        if (!guard || guard.kind === "authowl_turnstile" && !turnstileToken) {
           setError(t("phoneOtp.error.humanCheck"));
           return;
         }
@@ -1447,7 +1493,23 @@ function PhoneOTP({ redirectTo, onSignedIn, onBack }) {
         }
         const idempotencyKey = attempt.current.idempotencyKey;
         void run(
-          () => startPhoneOtp({ phoneNumber, turnstileToken, idempotencyKey }),
+          async () => {
+            const selected = guard?.kind === "akedly_shield_v1_2" ? await preparePhoneOtp() : null;
+            if (selected?.error || selected && !selected.data) {
+              setGuardState({ status: "error" });
+              throw new Error("Phone OTP guard could not be prepared.");
+            }
+            const current = selected?.data ?? guard;
+            if (selected?.data) setGuardState({ status: "ready", data: selected.data });
+            if (current?.kind === "akedly_shield_v1_2") {
+              const akedlyShield = await solvePhoneOtpChallenge(current);
+              return startPhoneOtp({ phoneNumber, akedlyShield, idempotencyKey });
+            }
+            if (current?.kind === "authowl_turnstile" && turnstileToken) {
+              return startPhoneOtp({ phoneNumber, turnstileToken, idempotencyKey });
+            }
+            throw new Error("Phone OTP guard is unavailable.");
+          },
           {
             failure: t("phoneOtp.error.sendFailed"),
             onSuccess: () => setStage("code")
@@ -1484,7 +1546,7 @@ function PhoneOTP({ redirectTo, onSignedIn, onBack }) {
             testId: "phoneotp-consent"
           }
         ),
-        /* @__PURE__ */ jsx16(
+        guard?.kind === "authowl_turnstile" && /* @__PURE__ */ jsx16(
           Turnstile,
           {
             siteKey: config?.turnstileSiteKey ?? null,
@@ -1494,12 +1556,23 @@ function PhoneOTP({ redirectTo, onSignedIn, onBack }) {
           }
         ),
         /* @__PURE__ */ jsx16(FormError, { children: error }),
+        guardState.status === "error" && /* @__PURE__ */ jsx16(
+          "button",
+          {
+            type: "button",
+            className: "ba-link-button",
+            onClick: () => {
+              void loadGuard();
+            },
+            children: t("phoneOtp.retryHumanCheck")
+          }
+        ),
         /* @__PURE__ */ jsx16(
           "button",
           {
             className: "ba-button",
             type: "submit",
-            disabled: pending || !turnstileToken || consentBlocked,
+            disabled: pending || guardState.status !== "ready" || turnstileBlocked || consentBlocked,
             "aria-busy": pending || void 0,
             children: /* @__PURE__ */ jsx16(Busy, { busy: pending, label: t("common.sending"), children: t("phoneOtp.sendSubmit") })
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@authowl/react",
-  "version": "0.16.1",
+  "version": "0.17.1",
   "description": "React provider, hooks, and drop-in components for AuthOwl, the multi-tenant auth SaaS.",
   "license": "MIT",
   "publishConfig": {
@@ -47,7 +47,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@authowl/core": "0.12.0"
+    "@authowl/core": "0.14.0"
   },
   "peerDependencies": {
     "react": ">=18",