Phone verification by text message, as a step of sign-up

Decisions these frames freeze

• Placement. The step comes right after POST /signup (201, session issued) and before the check-inbox screen, running in parallel with email verification. Phone verification does need an authenticated session: /verify/phone/start and /verify/status call requireBearer. Signup issues one, so the step can run immediately. Waiting for email verification first would make a working SMS step depend on email, and a user who opens the link on another device would arrive there without a session. See 01.
• One exit rule. Every way out of the step goes through nextAfterPhone(), using freshly re-fetched status: Continue, Skip, a deferral, and every bypass (flag or policy off, SMS unavailable, already verified). The user sees check-inbox only if an email was sent and isn't confirmed yet. If email verification is off, or the link was confirmed in parallel, they go straight into the app.
• Skip policy. Both outcomes are designed, with one server switch verification.phoneAtSignup (Δ). The recommended default is optional. required removes the user's Skip but still never blocks account creation. Every failure state, including a network error or an unclassified 5xx, offers Continue for now in place of Skip.
• Re-prompt at sign-in. Under required, a flagged redirect after every successful sign-in sends an unverified user to /signup/phone?next=… when SMS is available. See 01.
• Honest copy. The screens promise only what /verify/phone does: confirm a contact number. They don't claim it enables text-message sign-in codes or account recovery. SMS MFA enrolment is a separate flow.
• No enumeration. /start returns 202 for any well-formed number. "Number can't be used" (409) comes only from /confirm, after a correct code, so only the phone's owner ever sees it.
• Honest degrade. If AuthMethods.verification.sms is false, the step is never shown. If SMS fails mid-flow (503), the screen says so plainly and offers Continue. There is no dead end anywhere.
• No vendor names in the UI. The text-message provider is never mentioned.

Build inventory approve = approve this plan

Contract binding & deltas

OpenAPI packages/security/openapi.yaml → @fuzefront/security-client · flag fuzefront.auth.signup-phone-verification (default OFF, builders audience) · endpoints GET /v1/security/methods, GET /v1/security/verify/status, POST /v1/security/verify/phone/start, POST /v1/security/verify/phone/resend (new, Δ), POST /v1/security/verify/phone/confirm.

AuthMethods does advertise SMS availability: verification.sms, derived from SMS_SERVICE_URL in GET /methods. The step relies on it to decide whether to appear. The contract today is not enough to render these frames honestly. The deltas below are for contract-designer → backend-engineer:

1. security POST /verify/phone/confirm must require bearerAuth and bind to the session user. Today the route has no requireBearer, and the provider runs users.where({ phone }).update({ phone_verified: true }), which marks every account with that number as verified.
2. /start must not write users.phone before the user proves they have the phone. Today the provider writes users.phone and only then awaits sendSmsOtp. It should hold a pending number, promote it on confirm, and accept a confirm body of { code }. The pending challenge, and so phonePending, is committed only after the SMS provider accepts the send. On 502, 503 or 429 it is rolled back, so a reload never resumes at code entry when no code was sent.
3. security Every ?next goes through one safeReturnPath() guard, following LoginPage's allowlist approach: a single leading / (never //, never a scheme), same origin, normalized, and on the allowlist of app routes. Anything else goes to the default app. Without it, ?next=//evil.example is an open redirect straight after sign-in.
4. 202 body PhoneVerifyStartAck { maskedPhone, expiresInSeconds, resendAfterSeconds }. On a resend, expiresInSeconds is the code's actual remaining lifetime. The provider may re-send the same unexpired code without extending it.
5. /start errors: 400 PHONE_INVALID · 429 RATE_LIMITED+Retry-After (no limiter exists today) · 502 SMS_SEND_FAILED · 503 SMS_UNAVAILABLE. Today these fall through to 401 UNKNOWN "Authentication failed", so a failed send looks like a lost session.
6. /confirm errors: 422 CODE_INVALID {attemptsRemaining} · 422 CODE_EXPIRED · 429 TOO_MANY_ATTEMPTS+Retry-After · 409 PHONE_UNAVAILABLE (only after a correct code). Today all of these come back as 401 NOT_ACTIVE.
7. /start returns 202 for every well-formed number, whether or not another account already uses it.
8. AuthMethods.verification.phoneAtSignup: "off" | "optional" | "required".
9. VerificationStatus.phonePending?: { maskedPhone, expiresInSeconds, resendAfterSeconds } so the step can resume after a reload. Only the masked number ever comes back to the client.
10. New POST /verify/phone/resend: session-bound with an empty body. It resends to the pending number the server holds, so Resend still works after a reload, when the client knows only the masked number. Returns PhoneVerifyStartAck; 404 NO_PENDING_VERIFICATION sends the user back to enter-phone. /start remains the only call that takes a full number.
11. Confirm-time outage: when sms-service /sms/verify times out or returns non-2xx, the result is 503 VERIFY_UNAVAILABLE. It doesn't use an attempt and isn't reported as a wrong code. Today checkSmsOtp turns every failure into false, and /sms/verify returns only a boolean. It should return the provider status, and the client should get a tagged result.
12. Rate-limit pass-through: sms-service /sms/send returns 429 with no Retry-After, and sendSmsOtp discards the response. Both must carry retryAfterSeconds through to 429 RATE_LIMITED + Retry-After on /start and /resend.
13. Routing: when the step applies, 01-signup's submit goes to /signup/phone. Otherwise it goes through nextAfterPhone(): /signup/verify only if an email is pending, else the app. Behind the flag; no approved frame changes.
14. Routing: after a successful sign-in in auth-experience's signin flow, redirect to /signup/phone?next=… when phoneAtSignup === "required", phoneVerified is false and SMS is available. Behind the flag; no approved frame changes.

Reconciliation with existing frames

• mfa-stepup-mobile · 03-confirm-contact (flow confirm-contact-phone, unapproved). This feature is the sign-up version of the same phone OTP screen. It uses the same data-panel="confirm-contact" and the same state and action vocabulary (enter-phone · sending · enter-code · error-invalid · error-send · verified; send-code · verify-contact · resend · skip), adds data-context="signup", and adds the states that frame lacks (expired, locked/429, rate-limited, unavailable, number-unavailable, loading, session, generic). It uses the same OtpInput, but with cells widened to 44×52 so both dimensions meet the 44px tap target; mfa-stepup-mobile's 42px-wide cells should adopt this. The implementation should be one ContactVerifyPanel + state machine used in both places, not two parallel trees. If this is approved first, mfa-stepup-mobile's 03 should gain these states when it is next revised.
• auth-experience (approved). 01-signup, 03-check-inbox and 04-verify-landing are unchanged. Email stays link-click, as mfa-stepup-mobile's reconciliation also decided. This step is placed between 01 and 03.
• account-security / mfa-stepup-mobile 04. After a skip, the reminder is the existing "Unverified" phone chip in the security status view. No new reminder surface is designed here.

Open questions for the owner

• Skip-policy default: these frames assume optional.
• Can one number be used by more than one account? If yes, the 409 state goes away.
• Package home of the shared ContactVerifyPanel: @fuzefront/auth-ui (assumed here), consumed by @fuzefront/account-security-ui?
• Gate coverage: auth-experience's approved flows claim packages/auth-ui/src/**, so gate-frames-first would count this feature's code as approved through them and would not block it before these frames are approved. Fixing this means narrowing auth-experience's implementation.paths, which changes its stamp and needs re-approval, or making the gate prefer the most specific claim.