You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat(clerk-js,shared,react): expose clientTrustState on SignInFuture - #10775
Custom sign-in flows built on SignInFuture (what useSignIn() returns in Core 3) can't read the Device Trust state of a sign-in. FAPI sends client_trust_state and the legacy SignIn resource parses it, but SignInFuture doesn't expose it. A customer asked for it so they can record, for each sign-in, whether Clerk recognized the device, and tell a trusted device apart from a sign-in that wasn't challenged.
This PR adds clientTrustState ('new', 'known' or 'pending') to SignInFuture, including through the @clerk/react state proxy. While the status is needs_client_trust, it reads 'new' even when FAPI leaves the field out, which FAPI does today for instances on that status. It's undefined when Device Trust is off, and before the first factor is verified. The SignIn snapshot now keeps the field too, so Expo restores it when FAPI is unreachable at startup.
https://github.com/clerk/clerk_go/pull/24016 makes FAPI return the field once the first factor is verified, in both Device Trust modes, and never before it. Until it ships, instances on the needs_client_trust status see 'new' during the challenge and undefined elsewhere. Merging this PR first is safe, but the JSDoc describes the behavior after the backend change, so the backend change should reach production first. The docs PR, https://github.com/clerk/clerk/pull/3821, updates the Device Trust guide and the legacy SignIn reference, and should merge after this change ships in a release.
The prebuilt components don't change. They read the legacy SignIn field, not SignInFuture. The new UI tests pin the "new device" notice. It renders once on each Device Trust screen whether or not FAPI sends the field, and stays hidden on the MFA screen.
The value reflects the device as of the latest response. Completing a sign-in makes the device trusted in most cases, so a completed sign-in usually reads 'known', even right after a challenge. FAPI doesn't return the value before the first factor, so a flow can't read it after create({ identifier }). That's deliberate: a value at that point would tell anyone who types an identifier whether that account has signed in on the browser. A flow reads it after the password, together with the status, which the docs PR explains.
The JSDoc on SignInFutureResource.clientTrustState is new public docs, so please check the wording.
Checklist
pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
No actionable comments were generated in the recent review.
Walkthrough
The Future sign-in resource now exposes clientTrustState, including a new fallback for the needs_client_trust status, and serializes the value in snapshots. The React sign-in proxy exposes the property. Tests and fixtures cover resource behavior, proxy values, device notices, and phone second-factor rendering.
This adds an optional read-only sign-in property, and existing behavior is unchanged. Whether the backend reports the field at the documented times depends on a separate FAPI change, which this review could not check. No concrete merge-blocking risk is evident.
Pre-merge checks: 4
Check name
Status
Explanation
Title check
The title names the main change: it adds clientTrustState to SignInFuture across clerk-js, shared, and react. It matches the changeset, the SignIn resource change, the state proxy change, and the shar…
Linked Issues check
Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check
Check skipped because no linked issues were found for this pull request.
Description check
The description states that the PR adds clientTrustState ('new', 'known', 'pending') to SignInFuture, including through the @clerk/react state proxy. It explains when the value is 'new' …
Full details: Title check
Explanation
The title names the main change: it adds clientTrustState to SignInFuture across clerk-js, shared, and react. It matches the changeset, the SignIn resource change, the state proxy change, and the shared type addition. The title follows conventional commit form and is specific.
Full details: Description check
Explanation
The description states that the PR adds clientTrustState ('new', 'known', 'pending') to SignInFuture, including through the @clerk/react state proxy. It explains when the value is 'new' and when it is undefined, and it says the SignIn snapshot keeps the field. It also covers the related backend and docs PRs and the new UI tests. This matches the changeset, the resource, proxy, shared type, and test changes.
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Warning
Linked repositories: Some configured repositories could not be included in this review. Cross-repository analysis may be incomplete. Please check linked-repository access and settings.
Included review availability: This review used your included allowance. 8 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 10 reviews per hour.
After create() the value is undefined; after password() useSignIn() reads FAPI's known, pending or new, falls back to new on needs_client_trust without the field, and stays undefined with Device Trust off. Before, every cell read undefined.
Proof on 48d45e52 (from 7d2dc324) · mocked: Clerk Frontend API (intercepted responses: Playwright route handlers return the environment, client...) · Did Proof get it right? Yes · No
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Custom sign-in flows built on
SignInFuture(whatuseSignIn()returns in Core 3) can't read the Device Trust state of a sign-in. FAPI sendsclient_trust_stateand the legacySignInresource parses it, butSignInFuturedoesn't expose it. A customer asked for it so they can record, for each sign-in, whether Clerk recognized the device, and tell a trusted device apart from a sign-in that wasn't challenged.This PR adds
clientTrustState('new','known'or'pending') toSignInFuture, including through the@clerk/reactstate proxy. While the status isneeds_client_trust, it reads'new'even when FAPI leaves the field out, which FAPI does today for instances on that status. It'sundefinedwhen Device Trust is off, and before the first factor is verified. TheSignInsnapshot now keeps the field too, so Expo restores it when FAPI is unreachable at startup.https://github.com/clerk/clerk_go/pull/24016 makes FAPI return the field once the first factor is verified, in both Device Trust modes, and never before it. Until it ships, instances on the
needs_client_truststatus see'new'during the challenge andundefinedelsewhere. Merging this PR first is safe, but the JSDoc describes the behavior after the backend change, so the backend change should reach production first. The docs PR, https://github.com/clerk/clerk/pull/3821, updates the Device Trust guide and the legacySignInreference, and should merge after this change ships in a release.The prebuilt components don't change. They read the legacy
SignInfield, notSignInFuture. The new UI tests pin the "new device" notice. It renders once on each Device Trust screen whether or not FAPI sends the field, and stays hidden on the MFA screen.The value reflects the device as of the latest response. Completing a sign-in makes the device trusted in most cases, so a completed sign-in usually reads
'known', even right after a challenge. FAPI doesn't return the value before the first factor, so a flow can't read it aftercreate({ identifier }). That's deliberate: a value at that point would tell anyone who types an identifier whether that account has signed in on the browser. A flow reads it after the password, together with the status, which the docs PR explains.The JSDoc on
SignInFutureResource.clientTrustStateis new public docs, so please check the wording.Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change
✎