feat(js,shared): resolve Protect challenges automatically via a managed modal or inline marker

[mwickett]

Description

Stacked on #9391. Second step toward fully Clerk-owned Protect challenge support for custom-flow (headless) apps: clerk-js now notices a challenge-gated response at the resource layer and resolves it itself, so the calling code's await simply completes with the post-challenge state — no customer challenge API, mirroring the bot-protection CAPTCHA contract. Revised after an external review round; the semantics below reflect the revision.

• ProtectCheckGate (core/protectCheckGate.ts): inspects successful payloads for a direct sign-in/sign-up response carrying a pending protect_check. When gated it acquires a host — the <div id="clerk-protect-check" /> placement marker when the page provides one, otherwise the managed modal — drives the shared challenge lifecycle from refactor(shared,ui): extract the Protect check lifecycle into shared internal helpers #9391 (executeProtectCheckWithTimeout → PATCH …/protect_check → submitProtectCheckProof), loops chained challenges and expired-challenge reloads with caps, treats protect_check_already_resolved as soft success, and then replays the original operation — the PATCH only clears the gate; for pre-op gates (e.g. a gated prepareFirstFactor) the gated side effect only happens on the replay, which passes because the attempt's stored proof is re-presented server-side. The caller receives the replay's result. One challenge session at a time: concurrent gated calls wait, then replay.
• Deferred hydration for gated payloads: _baseFetch skips the client piggyback update when the direct response is challenge-gated, so listeners (state/signals, older framework SDKs) never observe the intermediate needs_protect_check while the promise is held. When a registered host owns the gate (prebuilt components), the gate publishes the pending state itself; every replay/PATCH publishes its own final payload as usual.
• Strict termination: a null (offline), wrong-flow, or wrong-id payload during a session is a protocol failure, not gate clearance; perpetual re-gating throws after a bounded number of rounds instead of returning a pending payload.
• Bounded, abortable modal acquisition: openModal resolving without the container ever appearing (an older hot-loaded @clerk/ui accepting the unknown modal name) fails within 5s instead of hanging; session release awaits the modal close so back-to-back sessions can't race.
• Caller cancellation: the request's AbortSignal is threaded through the gate — challenge execution, proof submission, reloads, and queued replays all observe it, and the host is released on abort.
• Mutual exclusion with the legacy captcha modal: the gate waits out captcha's single-flight before opening its UI and vice versa, so the two Clerk-owned modals never stack. (A single unified fraud-challenge coordinator remains a candidate refactor.)
• FraudProtection.execute gains an optional per-request protect context (raw fetch + deferred-publish + signal) supplied by BaseResource._fetch; every result path, including post-captcha replays, funnels through the gate.
• Clerk class: __internal_openProtectCheckModal / __internal_closeProtectCheckModal (same #clerkUI plumbing as the blank captcha modal) and __internal_registerProtectCheckHost(flow) for surfaces that render challenges themselves (the prebuilt components; the placement marker is deliberately not a registrant). All additive and __internal_-prefixed.
• Modal reveal posture matches the captcha modal — opens invisible, non-dismissible, revealed by the script's setWidgetVisible handshake — plus a short delay reveal for long-running checks (proof-of-transfer) so a slow solve is never an invisible frozen page.
• Fail-closed in no-RHC builds and non-DOM environments (protect_check_unsupported_environment).

Inert on its own: the ui package's ProtectCheckModal (next PR) provides the modal markup, and FAPI does not surface protect_check until the server-side version gates are raised. Rollout stays deploy-then-enable; the user-facing changelog entry ships with the PR that makes the feature functional.

Known follow-ups tracked separately: OAuth redirect/popup completion resolves the gate from the nested client mirror (PROT-968); no-RHC/version-skew enablement caveats and PR3/PR4 feature detection (PROT-969); challenge sdk_url origin-restriction decision (PROT-970); expired-challenge re-mint contract + clock-skew allowance (PROT-946).

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[changeset-bot]

🦋 Changeset detected

Latest commit: 7cea771

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 23 packages

Name	Type
@clerk/clerk-js	Patch
@clerk/shared	Patch
@clerk/chrome-extension	Patch
@clerk/electron	Patch
@clerk/expo	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/expo-passkeys	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/headless	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	Patch
@clerk/swingset	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Aug 20, 2026 4:37pm
swingset	Ready	Preview	Aug 20, 2026 4:37pm

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a3e2b4a21a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Implement the modal before waiting for its container

When a custom-flow app has no clerk-protect-check marker, this waits forever: the reviewed packages/ui/src/Components.tsx has no protectCheckModal state, renderer, or ProtectCheckModal, and a repo-wide search finds no element creating cl-modal-protect-check-container. openModal('protectCheck') therefore only writes an unused dynamic state key, while waitForElement() has no timeout and never resolves null, leaving the original sign-in/sign-up promise permanently pending.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Register prebuilt hosts before intercepting their responses

When a mounted prebuilt SignIn or SignUp submits a request that returns protect_check, hasRegisteredHost() is always false because the new __internal_registerProtectCheckHost API has no caller anywhere in the reviewed tree. Since interception happens inside BaseResource._fetch before the resource reaches the prebuilt router, the existing inline Protect card never receives the gated state; the request is diverted into managed handling instead (and currently hangs on the absent modal), contrary to the promised preserved inline experience.

Useful? React with 👍 / 👎.