docs(*): rename "Client Trust" to "Device Trust" - #9266
Conversation
🦋 Changeset detectedLatest commit: 0de860c The changes in this PR will be included in the next version bump. 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 |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 98c96dcc21
ℹ️ 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".
| @@ -0,0 +1,265 @@ | |||
| # Email-Code Sign-Up Abandonment Repro Design | |||
There was a problem hiding this comment.
This 265-line planning document is unrelated to the Client Trust → Device Trust rename and explicitly describes a separate repository, workstation-specific paths, and an internal customer-support scenario. Including it in this commit unnecessarily publishes internal planning context and couples an independent project to this documentation-only release; move it to its intended repository or a separate focused change.
Useful? React with 👍 / 👎.
mwickett
changed the title
98c96dc to
3d6ef32
Compare
📝 WalkthroughWalkthroughThe changes add patch-release metadata for Estimated code review effort: 1 (Trivial) | ~5 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Warning Review ran into problems🔥 ProblemsLinked repositories: Couldn't analyze
Errors logged to '/home/jailuser/git/.git/lfs/logs/20260728T181529.699935639.log'. Errors logged to '/home/jailuser/git/.git/lfs/logs/20260728T181651.755862552.log'. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@docs/superpowers/specs/2026-04-15-email-code-signup-abandonment-repro-design.md`:
- Around line 153-170: Update the “Required Payload Fields” and “State
Observation” sections to define a redacted logging allowlist: permit only the
listed identifiers, status, timestamps, and abandonment fields; explicitly
prohibit full resources, form values, passwords, raw email addresses, and raw
errors; and require deduplication of repeated meaningful signUp state-change
events.
- Around line 206-214: Update the “Check 2: Incomplete Sign-Up” verification to
assert only signUpId and the initial status, without expecting abandonAt to be
populated. Add the abandonAt check after the flow reaches the actual abandonment
transition, where it should no longer be null.
- Around line 20-25: Update the standalone sign-up flow to use Core 3
SignUpFuture APIs: replace the legacy verification and activation calls with
signUp.password(), signUp.verifications.sendEmailCode(), verifyEmailCode(), and
signUp.finalize(). Handle each returned { error } before advancing, and only
proceed after finalize and session setup complete; apply the same changes to the
other referenced flow sections.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro Plus
Run ID: cf302169-2afc-4301-8066-6c9223182b5b
📒 Files selected for processing (4)
.changeset/rename-client-trust-to-device-trust.mddocs/superpowers/specs/2026-04-15-email-code-signup-abandonment-repro-design.mdpackages/shared/src/types/signInFuture.tspackages/upgrade/src/versions/core-3/changes/needs-client-trust-sign-in-status-added.md
🔗 Linked repositories identified
CodeRabbit considers these linked repositories for cross-repo context during reviews:
clerk/clerk_go(manual)clerk/dashboard(manual) → reviewed against branchmwickett/prot-875-rename-client-trust-to-device-trustinstead of the default branchclerk/accounts(manual)clerk/backoffice(manual)clerk/clerk(manual)clerk/clerk-docs(manual)clerk/cloudflare-workers(manual)clerk/cli(auto-detected)clerk/clerk-ios(auto-detected)clerk/clerk-android(auto-detected)
| Build a fresh standalone Next.js App Router repo in keyless mode with a single custom sign-up page that: | ||
|
|
||
| - creates a sign-up attempt with `useSignUp()` | ||
| - sends an email verification code | ||
| - accepts the verification code inline | ||
| - logs the relevant lifecycle data with `console.log()` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
FILE="docs/superpowers/specs/2026-04-15-email-code-signup-abandonment-repro-design.md"
echo "== file outline =="
wc -l "$FILE"
echo
echo "== lines 1-220 with numbers =="
sed -n '1,220p' "$FILE" | nl -ba | sed -n '1,220p'Repository: clerk/javascript
Length of output: 330
🏁 Script executed:
#!/bin/bash
set -euo pipefail
FILE="docs/superpowers/specs/2026-04-15-email-code-signup-abandonment-repro-design.md"
wc -l "$FILE"
echo "---"
sed -n '1,220p' "$FILE" | nl -ba | sed -n '1,220p'Repository: clerk/javascript
Length of output: 282
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n "prepareEmailAddressVerification|attemptEmailAddressVerification|setActive|signUp\.password\(|sendEmailCode\(|verifyEmailCode\(|finalize\(" docs/superpowers/specs/2026-04-15-email-code-signup-abandonment-repro-design.md docs -g '*.md' -g '*.ts' -g '*.tsx' -g '*.js' -g '*.jsx'Repository: clerk/javascript
Length of output: 1056
🌐 Web query:
Clerk Core 3 SignUpFuture useSignUp signUp.password signUp.verifications.sendEmailCode verifyEmailCode finalize setActive prepareEmailAddressVerification attemptEmailAddressVerification
💡 Result:
In Clerk Core 3, the SDK's sign-up API has been significantly redesigned to provide a more stateful, predictable, and easier-to-use interface [1][2]. The methods you listed reflect a migration from Clerk Core 2 (or earlier) patterns to the new Core 3 useSignUp hook and SignUpFuture object [1][2]. Key Changes and Mapping The following table summarizes the mapping from older (Core 2) methods to their recommended Core 3 counterparts [2]: Core 2 Method | Core 3 Method --- | --- signUp.create({ emailAddress, password }) | signUp.password({ emailAddress, password }) [2] signUp.prepareEmailAddressVerification | signUp.verifications.sendEmailCode [2] signUp.attemptEmailAddressVerification | signUp.verifications.verifyEmailCode [2] setActive (as a separate call) | signUp.finalize [2] Core 3 API Overview The SignUpFuture object (accessed via useSignUp()) manages the lifecycle of a sign-up attempt [3][4]. Instead of manually tracking loading or verification states, you can now rely on the object's properties and simplified step methods [1][2]: 1. signUp.password: Used to initiate or progress a sign-up using an email and password [5][2]. It is preferred over the generic signUp.create for standard password-based flows [3][5]. 2. signUp.verifications: This namespace encapsulates all verification methods [6]. Use signUp.verifications.sendEmailCode to trigger a code and signUp.verifications.verifyEmailCode to validate it [4][2][6]. 3. signUp.finalize: This is the mandatory final step once a sign-up attempt is complete (i.e., status === 'complete'). It creates the session and sets it as the active session, effectively replacing previous manual setActive calls [3][4][2]. Implementation Note With Core 3, you no longer need to manage complex error parsing or loading states manually [1]. The useSignUp() hook exposes these directly: const { signUp, errors, fetchStatus } = useSignUp; // Standard Core 3 pattern [4][2] If you encounter documentation referring to prepareEmailAddressVerification or attemptEmailAddressVerification, these are deprecated in favor of the structured verifications namespace methods [2]. Always ensure your application is using the latest Clerk SDK packages to access these updated APIs [1].
Citations:
- 1: https://clerk.com/changelog/2026-03-03-core-3.md
- 2: https://clerk.com/articles/from-setactive-to-finalize-migrating-custom-auth-flows-to-clerk-core-3
- 3: https://clerk.com/docs/nextjs/reference/objects/sign-up-future
- 4: https://clerk.com/docs/guides/development/custom-flows/authentication/email-sms-otp
- 5: https://clerk.com/docs/js-frontend/reference/objects/sign-up-future
- 6: https://cdn.jsdelivr.net/npm/@clerk/clerk-js@6.4.0/dist/types/core/resources/SignUp.d.ts
Switch this flow to Core 3 SignUpFuture. The spec still uses prepareEmailAddressVerification() / attemptEmailAddressVerification() / setActive(). Replace them with signUp.password(), signUp.verifications.sendEmailCode(), verifyEmailCode(), and signUp.finalize(), and only advance after each { error } is handled and finalize/session setup completes. Also applies to 121-138 and 172-179.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@docs/superpowers/specs/2026-04-15-email-code-signup-abandonment-repro-design.md`
around lines 20 - 25, Update the standalone sign-up flow to use Core 3
SignUpFuture APIs: replace the legacy verification and activation calls with
signUp.password(), signUp.verifications.sendEmailCode(), verifyEmailCode(), and
signUp.finalize(). Handle each returned { error } before advancing, and only
proceed after finalize and session setup complete; apply the same changes to the
other referenced flow sections.
| ### Required Payload Fields | ||
|
|
||
| Whenever available, logs should include: | ||
|
|
||
| - `signUpId` | ||
| - `status` | ||
| - `abandonAt` | ||
| - `createdSessionId` | ||
| - `createdUserId` | ||
| - `timestamp` | ||
|
|
||
| ### State Observation | ||
|
|
||
| The flow component should also log whenever the current `signUp` resource changes in a meaningful way. This is the key validation aid for answering: | ||
|
|
||
| > Does the client ever expose a useful `abandoned` transition on its own, or does the customer need to derive abandonment from "started but never completed"? | ||
|
|
||
| We are not assuming the answer ahead of time. The repro exists to validate it. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Define a redacted logging allowlist.
Because this is a public customer-facing example, “sign-up attempt details” and resource-change logging must not mean logging the full resource, form values, or raw errors. Explicitly prohibit passwords and raw email addresses, whitelist only the required identifiers/status fields, and deduplicate state-change events.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@docs/superpowers/specs/2026-04-15-email-code-signup-abandonment-repro-design.md`
around lines 153 - 170, Update the “Required Payload Fields” and “State
Observation” sections to define a redacted logging allowlist: permit only the
listed identifiers, status, timestamps, and abandonment fields; explicitly
prohibit full resources, form values, passwords, raw email addresses, and raw
errors; and require deduplication of repeated meaningful signUp state-change
events.
| ### Check 2: Incomplete Sign-Up | ||
|
|
||
| Start the flow, stop before entering the code, and confirm the console already captured: | ||
|
|
||
| - `signUpId` | ||
| - `status` | ||
| - `abandonAt` | ||
|
|
||
| This demonstrates the data a customer can emit immediately when the sign-up begins. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
file='docs/superpowers/specs/2026-04-15-email-code-signup-abandonment-repro-design.md'
nl -ba "$file" | sed -n '190,230p'
printf '\n--- search for abandonAt in docs/specs ---\n'
rg -n "abandonAt|status|signUpId" docs -g '*.md' || trueRepository: clerk/javascript
Length of output: 194
🌐 Web query:
clerk signUp abandonAt object docs abandonment timestamp
💡 Result:
In the Clerk authentication system, the abandonAt property is a member of the SignUp object [1][2][3]. It is defined as a number | null type, representing the epoch numerical time (timestamp) at which the sign-up process was abandoned by the user [1][4][5]. When a sign-up attempt is abandoned, the status of the sign-up object typically transitions to "abandoned" [4][5]. If the sign-up has not been abandoned, the value of abandonAt is null [1][2][6].
Citations:
- 1: https://clerk.com/docs/js-frontend/reference/objects/sign-up
- 2: https://clerk.com/docs/react/reference/objects/sign-up
- 3: https://clerk.com/docs/expo/reference/objects/sign-up
- 4: https://clerk.com/docs/nextjs/reference/objects/sign-up-future
- 5: https://clerk.com/docs/tanstack-react-start/reference/objects/sign-up-future
- 6: https://clerk.com/docs/chrome-extension/reference/objects/sign-up
Do not expect abandonAt in Check 2. It should stay null until the sign-up is actually abandoned; assert signUpId and initial status there, then check abandonAt only after the abandonment transition.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@docs/superpowers/specs/2026-04-15-email-code-signup-abandonment-repro-design.md`
around lines 206 - 214, Update the “Check 2: Incomplete Sign-Up” verification to
assert only signUpId and the initial status, without expecting abandonAt to be
populated. Add the abandonAt check after the flow reaches the actual abandonment
transition, where it should no longer be null.
Renames the customer-facing feature name in the SignInFutureResource.status JSDoc and in the @clerk/upgrade core-3 change guide. This is a naming change only. Every API value keeps its existing name -- the `needs_client_trust` sign-in status, the `clientTrustState` property, and the rest are untouched -- so consumers need no code changes. The patch changeset is required so a release publishes: the clerk-docs typedoc sync is release-gated, and the generated clerk-typedoc/shared/sign-in-future-resource/properties.mdx must pick up the new links before the docs rename can land. Part of PROT-875.
3d6ef32 to
0de860c
Compare
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/electron
@clerk/electron-passkeys
@clerk/eslint-plugin
@clerk/expo
@clerk/expo-google-signin
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/hono
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/react
@clerk/react-router
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/ui
@clerk/upgrade
@clerk/vue
commit: |
API Changes Report
Summary
No API Changes DetectedAll packages have stable APIs with no detected changes. Report generated by Break Check Last ran on |
2 participants
Part of PROT-875.
Note
Merge order changed after review: merge this AFTER clerk/clerk#3051. Landing it first would deadlock — once this releases, the typedoc sync regenerates
properties.mdxwith links todevice-trust, and that sync PR fails against a clerk/clerk main that does not have the page yet. #3051 now carries the matching generated file itself, so once it lands, the sync here becomes a no-op.What
Renames the customer-facing feature name "Client Trust" → "Device Trust" in the two developer-facing text surfaces this repo owns:
SignInFutureResource.statusJSDoc in@clerk/shared@clerk/upgradecore-3 change guideConsumers need no code changes
This is a naming change only. Every API value keeps its existing name:
'needs_client_trust'— the status string apps compare against — unchangedclientTrustState— unchangedNo type signatures, exports, or runtime behavior are touched. Apps that switch on
signIn.status === 'needs_client_trust'keep working untouched. Per Kyle in the naming thread: "we don't have to change APIs but the way we discuss clients externally should flip to devices."The two docs pages add a note explaining why the API value and the feature name now differ.
Why a changeset for a comment change
The changeset is
patch/patchand exists to trigger a release, not to signal API impact.The clerk-docs typedoc sync is release-gated — per clerk-docs
contributing/CONTRIBUTING.md, the sync PR opens once a javascript PR "has been merged and a release is published." The generatedclerk-typedoc/shared/sign-in-future-resource/properties.mdxstill links to the old docs URLs, and clerk-docs'build:tsxfails on those two links until it is regenerated.Heads up that
updateInternalDependents: "always"means this cascades patch bumps to the 21 packages depending on@clerk/shared. All are no-op upgrades for consumers.Merge order (revised)
clerk/clerkchore(repo): Configure Dependabot #3051 — the docs rename. Self-contained and green; creates the pages and the redirects.clerk/dashboard#9839 — the dashboard UI labels. Must wait for chore(repo): Configure Dependabot #3051 to deploy, or its docs links 404.One thing not to misread
needs-client-trust-sign-in-status-added.mdhascategory: 'breaking'in its frontmatter. That is pre-existing and describes the core-3 change it documents — adding theneeds_client_truststatus was breaking at the time. It is not a label on this rename, and I did not touch it.Verification
prettier --checkon all three files — cleaneslintonsignInFuture.ts— 0 errors (24 pre-existing@extractMethodswarnings at lines 469+, unrelated to the line 337 change)