|
| 1 | +# Sign-in and sign-up flow |
| 2 | + |
| 3 | +How sign-in and sign-up decide which screen to show, from the step FAPI says comes next. Paths are relative to `packages/`. |
| 4 | + |
| 5 | +## The model |
| 6 | + |
| 7 | +A step is a step of the auth flow, not a screen. FAPI owns the step, the order of steps, and whether a code is already sent. Mosaic owns the routes, the layout and copy, and when to send a code. |
| 8 | + |
| 9 | +Today FAPI sends `status`, `missing_fields` and `unverified_fields`, not a step. Until it sends `nextStep`, `getSignInNextStep` and `getSignUpNextStep` in `shared` compute it from those fields (see [Bridge](#bridge)). |
| 10 | + |
| 11 | +There is no step machine and no local copy of the step. What the step can't say lives in the route, such as the factor the user picked in `factorOne`'s `:factor` param. |
| 12 | + |
| 13 | +## Pick the screen |
| 14 | + |
| 15 | +The route and the step can disagree: the user went back, opened an old link, or the sign-in reset. A route the step allows stays. Any other route is replaced with the step's route, so the screen and the route never drift. `unknown` shows "Start over" on whatever route it's on. |
| 16 | + |
| 17 | +```tsx |
| 18 | +const { step } = model; |
| 19 | +const { route } = useRouterScope(signInRoutes, { routing, path, root: 'start' }); |
| 20 | +const screen = step.type === 'unknown' ? 'startOver' : allowedRoute(route, step) ? route : routeFor(step); |
| 21 | +``` |
| 22 | + |
| 23 | +- `routeFor(step)` returns the step's route, from the lists below. |
| 24 | +- `allowedRoute(route, step)` is `true` for `start`, for the step's own route, and for `continue` while sign-up verifies, so the user can edit a field. `complete` and `transfer` have no route, so they allow any route: the current screen stays up while `next` runs, and shows the error if it fails. |
| 25 | +- The component that owns the route table computes `screen` during render, with no effect. |
| 26 | +- This runs once the model is `ready`, and after Clerk loads there is always a step. Until then the scope gets `ready: false`, so a starting route like `factor-one` isn't reset to `start`. |
| 27 | + |
| 28 | +## Move on after a submit |
| 29 | + |
| 30 | +The model makes the Clerk call and returns the next step. The methods return `{ error }` instead of rejecting, so the model throws it for `save` and the controller's error owners. The controller passes the step to `next(step)`. |
| 31 | + |
| 32 | +```ts |
| 33 | +submitPassword: async (password: string) => { |
| 34 | + await save(async () => { |
| 35 | + const { error } = await signIn.password({ password }); |
| 36 | + if (error) throw error; |
| 37 | + }, ['password']); |
| 38 | + return getSignInNextStep(signIn); |
| 39 | +}, |
| 40 | +``` |
| 41 | + |
| 42 | +- `complete`: the model's `finalize()`, then leave the flow. In a modal, don't `close()` when the flow leaves: `finalize()`'s navigation is the last write and takes the modal with it. |
| 43 | +- `transfer` from sign-in: the model's `transfer()` calls `signUp.create({ transfer: true, unsafeMetadata })`, then `next` with the sign-up's step. A sign-in with sign-up built in holds the sign-up routes under `create/`, so it stays in the component. Otherwise it leaves for the sign-up page. |
| 44 | +- `transfer` from sign-up, when the identifier already has an account: the model's `transfer()` calls `signIn.create({ transfer: true })`, then `next` with the sign-in's step. |
| 45 | +- `unknown`: nothing. The screen already shows "Start over". |
| 46 | +- Anything else: `go(routeFor(step))`. |
| 47 | +- An error from `finalize()` or the transfer stays on the current screen. |
| 48 | + |
| 49 | +## Routes and steps |
| 50 | + |
| 51 | +Each flow owns one route table through `useRouterScope`. Paths match `ui`'s, so links carry over. |
| 52 | + |
| 53 | +Sign-in: |
| 54 | + |
| 55 | +- `identifier` → `start` |
| 56 | +- `protect` → `protectCheck` |
| 57 | +- `first_factor` (`strategy`, `sent`) → `factorOne` |
| 58 | +- `second_factor` (`strategy`, `sent`) → `factorTwo` |
| 59 | +- `client_trust` → `clientTrust` |
| 60 | +- `new_password` → `resetPassword` |
| 61 | + |
| 62 | +Sign-up: |
| 63 | + |
| 64 | +- `start` → `start` |
| 65 | +- `protect` → `protectCheck` |
| 66 | +- `enterprise_sso` → `enterpriseConnections`, which goes straight to the IdP unless there are several connections to pick from |
| 67 | +- `fields` (`fields`) → `continue` |
| 68 | +- `verify_email` (`target`, `sent`) → `verifyEmail` |
| 69 | +- `verify_phone` (`target`, `sent`) → `verifyPhone` |
| 70 | + |
| 71 | +`identifier` and `start` are what Mosaic shows before the resource exists; a sign-in with no status and a sign-up not yet created both return them. `sent` means a code or link is out, so a reload on the same `:factor` doesn't send another. Picking a different factor always sends, because `sent` can't tell two targets with the same strategy apart (see [Bridge](#bridge)). |
| 72 | + |
| 73 | +With no `:factor`, `factorOne` starts on the factor `ui`'s `determineStartingSignInFactor` picks (`ui/src/components/SignIn/utils.ts:76`). That rule moves to `shared` so both use one copy. |
| 74 | + |
| 75 | +## Back, forward and reload |
| 76 | + |
| 77 | +- FAPI's state changes only on submit. A route the step doesn't allow is replaced with the step's route. |
| 78 | +- Back to `start` shows the identifier form; submitting it creates a new sign-in. Forward to `factorOne` still works. |
| 79 | +- Reload on `factorOne` keeps the picked factor (`:factor`) and sends no second code (`sent`). |
| 80 | +- Virtual routing has no history: a remount starts at `start`, and FAPI's state is kept. |
| 81 | + |
| 82 | +## Entry actions |
| 83 | + |
| 84 | +The controller calls these model callbacks on `start`, then `next(step)`. |
| 85 | + |
| 86 | +- Ticket (`__clerk_ticket`): `__clerk_status=sign_up` redeems it with `signUp.ticket({ unsafeMetadata })`; any other status with `signIn.ticket()`, as `ui/src/components/SignIn/SignInStart.tsx` does. A ticket works only once, so redeem it once: keep the "already started" flag in a component that doesn't remount, so a remount or StrictMode can't redeem it twice. A failed redemption shows its error on `start`. |
| 87 | +- Email-link return (`__clerk_status`): `verified` with a `__clerk_created_session` this client has activates that session (`clerk-js/src/core/clerk.ts:2620-2636`); any other `verified` continues by step. `transferable` and the error statuses show their own screen, as `ui/src/common/EmailLinkVerify.tsx` does. |
| 88 | +- Redirect URLs for email links and OAuth/SAML returns come from the router (the planned `useReturnUrl(name, params)`), never hand-built. That part waits for the routing follow-up. |
| 89 | +- A step that is already `complete` or `transfer` on mount, such as a reload before it ran: `next(step)` runs it once, with the same guard as a ticket. The email-link return is handled first. |
| 90 | + |
| 91 | +## Bridge |
| 92 | + |
| 93 | +`getSignInNextStep` and `getSignUpNextStep` (`shared/src/internal/clerk-js/nextStep.ts`) compute the step from today's fields, and return FAPI's `nextStep` once it is sent. They can't compute three things, so FAPI must send them: |
| 94 | + |
| 95 | +- The sign-up order. |
| 96 | +- `target` for sign-in. Nothing says which email or phone a code went to. |
| 97 | +- `sent` per target for sign-in. `first_factor_verification` has no identification, so after a code to one email, a second email with the same strategy also reads as sent. |
0 commit comments