Skip to content
2 changes: 2 additions & 0 deletions .changeset/shared-sign-up-next-step-order.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
---
---
6 changes: 3 additions & 3 deletions packages/mosaic/docs/internals/sign-in-sign-up-flow.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ How sign-in and sign-up decide which screen to show, from the step FAPI says com

## The model

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.
FAPI tracks which requirements are outstanding and whether a code has been sent. When several sign-up requirements are outstanding, the shared client picks which one comes next. Mosaic maps the step to a screen and owns the routes, layout, copy, and when to send a code.

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)).

Expand Down Expand Up @@ -64,9 +64,9 @@ Sign-up:
- `start` → `start`
- `protect` → `protectCheck`
- `enterprise_sso` → `enterpriseConnections`, which goes straight to the IdP unless there are several connections to pick from
- `fields` (`fields`) → `continue`
- `verify_email` (`target`, `sent`) → `verifyEmail`
- `verify_phone` (`target`, `sent`) → `verifyPhone`
- `fields` (`fields`) → `continue`

`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)).

Expand All @@ -92,6 +92,6 @@ The controller calls these model callbacks on `start`, then `next(step)`.

`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:

- The sign-up order.
- The sign-up order. Until FAPI sends it, `getSignUpNextStep` follows `ui`'s order (`shared/src/internal/clerk-js/completeSignUpFlow.ts`): verify the email, then the phone, then collect the missing fields.
- `target` for sign-in. Nothing says which email or phone a code went to.
- `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.
10 changes: 5 additions & 5 deletions packages/shared/src/internal/clerk-js/__tests__/nextStep.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -168,11 +168,11 @@ describe('getSignUpNextStep', () => {
});
});

it('collects missing fields before verifying the email', () => {
expect(getSignUpNextStep(signUp({ missingFields: ['username'], unverifiedFields: ['email_address'] }))).toEqual({
type: 'fields',
fields: ['username'],
});
it('verifies the email before collecting missing fields', () => {
const step = getSignUpNextStep(
signUp({ missingFields: ['username'], unverifiedFields: ['email_address'], emailAddress: 'ada@example.com' }),
);
expect(step).toEqual({ type: 'verify_email', target: 'ada@example.com', sent: false });
});

it('verifies the email before the phone', () => {
Expand Down
34 changes: 22 additions & 12 deletions packages/shared/src/internal/clerk-js/nextStep.ts
Original file line number Diff line number Diff line change
@@ -1,20 +1,28 @@
import type { ProtectCheckResource, SignUpField, SignUpIdentificationField, VerificationResource } from '../../types';

export type NextStep =
type SharedNextStep =
| { type: 'protect' }
| { type: 'transfer' }
| { type: 'complete'; createdSessionId: string | null }
| { type: 'unknown' };

export type SignInNextStep =
| SharedNextStep
| { type: 'identifier' }
| { type: 'first_factor'; strategy: string | null; sent: boolean }
| { type: 'second_factor'; strategy: string | null; sent: boolean }
| { type: 'client_trust' }
| { type: 'new_password' }
| { type: 'protect' }
| { type: 'transfer' }
| { type: 'new_password' };

export type SignUpNextStep =
| SharedNextStep
| { type: 'start' }
| { type: 'enterprise_sso' }
| { type: 'fields'; fields: SignUpField[] }
| { type: 'verify_email'; target: string | null; sent: boolean }
| { type: 'verify_phone'; target: string | null; sent: boolean }
| { type: 'complete'; createdSessionId: string | null }
| { type: 'unknown' };
| { type: 'verify_phone'; target: string | null; sent: boolean };

export type NextStep = SignInNextStep | SignUpNextStep;

type VerificationInput = Pick<VerificationResource, 'status' | 'strategy'>;

Expand Down Expand Up @@ -48,7 +56,7 @@ export type SignUpNextStepInput = {
*
* @internal
*/
export function getSignInNextStep(signIn: SignInNextStepInput): NextStep {
export function getSignInNextStep(signIn: SignInNextStepInput): SignInNextStep {
if (signIn.protectCheck) {
return { type: 'protect' };
}
Expand Down Expand Up @@ -81,7 +89,7 @@ export function getSignInNextStep(signIn: SignInNextStepInput): NextStep {
*
* @internal
*/
export function getSignUpNextStep(signUp: SignUpNextStepInput): NextStep {
export function getSignUpNextStep(signUp: SignUpNextStepInput): SignUpNextStep {
if (!signUp.id) {
return { type: 'start' };
}
Expand All @@ -100,9 +108,6 @@ export function getSignUpNextStep(signUp: SignUpNextStepInput): NextStep {
if (signUp.missingFields.includes('enterprise_sso')) {
return { type: 'enterprise_sso' };
}
if (signUp.missingFields.length > 0) {
return { type: 'fields', fields: signUp.missingFields };
}
if (signUp.unverifiedFields.includes('email_address')) {
return {
type: 'verify_email',
Expand All @@ -117,6 +122,11 @@ export function getSignUpNextStep(signUp: SignUpNextStepInput): NextStep {
sent: signUp.verifications.phoneNumber.nextAction === 'needs_attempt',
};
}
if (signUp.missingFields.length > 0) {
return { type: 'fields', fields: signUp.missingFields };
}
// TODO: FAPI computes `MissingRequirements` in `checkStatus` but does not serialize it, so a sign-up blocked only
// by an unmet identifier requirement lands here. Return `fields` from `missing_requirements` once FAPI sends it.
return { type: 'unknown' };
}

Expand Down
Loading