FRD: Auth Platform Flows Recipe

Document Summary

Field	Details
Feature Name	Auth Platform Flows Recipe
Status	Draft
Owner	David Holmes
Contributors	Engineering, Security
Target Release	v2.0.0 (P2)
Related Links	Roadmap item #80, ADR-027 (Default Tech Stack)
Last Updated	2026-05-26

Introduction

Overview

The Auth Platform Flows recipe provides copy-pasteable implementations for the authentication flows that sit beyond the existing login, signup, and MFA-verify widgets. It covers password reset, email verification, invitation acceptance, MFA setup (TOTP and recovery codes), recovery-code regeneration, and SSO handoff. Each flow is a self-contained page component with stories, tests, and documentation showing how to wire it to a backend auth service.

Goals

Provide complete, copy-pasteable page components for each auth flow.
Demonstrate proper state management for multi-step auth flows (using wizard pattern where applicable).
Show secure handling of tokens, codes, and sensitive form data.
Document the expected backend API contract for each flow.
Include accessible, mobile-responsive implementations.
Ship with stories covering every flow state and tests covering logic.

Non-Goals

Rebuilding the existing login, signup, or verify-MFA widgets.
Implementing a real auth backend or identity provider.
Providing session management or token refresh logic.
Building a user management admin panel.
Implementing biometric authentication.

Scope

In Scope

Area	Description
Password reset flow	Request reset (email input) -> check email prompt -> reset password (new password input with token) -> success confirmation
Email verification flow	Verify email with token from URL -> success or expired/invalid states
Invitation acceptance flow	Accept invite with token -> set password -> success
MFA setup flow (TOTP)	Show QR code -> verify with authenticator code -> display recovery codes -> confirm save
Recovery code management	Regenerate recovery codes -> confirm action -> display new codes -> confirm save
SSO handoff flow	SSO provider selection -> redirect to IdP -> callback handling states (loading, error)
Shared auth layout	Centered card layout for auth pages with logo and footer
Mock auth service	Mock API layer for testing and stories
Stories	All flow states demonstrated
Tests	Logic and state management coverage
Recipe MDX	Documentation with API contracts and integration guide

Out of Scope

Area	Reason
Login / signup / MFA verify widgets	Already exist as `login-form.tsx`, `signup-form.tsx`, `verify-mfa-form.tsx`
Real auth backend	Consumer responsibility
Session management / token refresh	Separate concern; covered by the consumer’s auth infrastructure
User profile management	Different feature
Biometric authentication	Specialized; not standard flow
OAuth provider implementation	Consumer responsibility; recipe shows the redirect pattern

Users and Pain Points

User Groups

User	Description	Needs
Application developers	Engineers implementing auth flows beyond login/signup	Complete, secure reference implementations for each flow
Security engineers	Team members reviewing auth implementation	Documented security considerations for each flow
QA engineers	Testers verifying auth flows	Stories showing every state including error cases
New team members	Engineers onboarding to auth implementation	Working examples showing how to handle tokens, multi-step flows, and error states

Pain Points

User	Pain Point	Impact
Application developers	Auth widgets exist for login/signup/MFA-verify, but no reference for the surrounding flows	Password reset, email verification, and MFA setup are built from scratch each time
Application developers	Multi-step auth flows (MFA setup) are complex to implement correctly	Developers skip steps (e.g., not showing recovery codes) or implement them insecurely
Application developers	No documented backend API contract for auth flows	Each app defines its own API shape; hard to share auth infrastructure
Security engineers	Recovery codes are often displayed insecurely (no copy button, no download, no confirmation)	Users lose access to their accounts when they cannot recover codes

Definitions

Term	Definition
Password reset flow	The complete flow from requesting a reset email to setting a new password via a tokenized link
Email verification	Confirming a user’s email address via a tokenized link sent to that address
Invitation acceptance	A flow where a new user accepts an invite, sets their password, and joins an organization
TOTP	Time-based One-Time Password; a standard MFA method using authenticator apps
Recovery codes	One-time-use backup codes that allow login when the primary MFA method is unavailable
SSO handoff	Redirecting a user to an external identity provider (SAML, OIDC) and handling the return callback
Auth token	A short-lived, single-use token embedded in a URL for email verification, password reset, or invitation acceptance

Current State

Existing Behavior

The design system ships three auth widgets: login-form.tsx (email/password login), signup-form.tsx (registration), and verify-mfa-form.tsx (MFA code entry). These handle the core authentication interaction but not the supporting flows.

Current Limitations

No password reset flow (request, check email, set new password).
No email verification flow.
No invitation acceptance flow.
No MFA setup flow (QR code display, code verification, recovery codes).
No recovery code regeneration flow.
No SSO handoff pattern.
No shared auth page layout.

Existing Workarounds

Developers implement each flow from scratch, often with inconsistent UX and missing states.
Recovery codes are sometimes shown in a plain alert dialog without copy/download.
SSO handoff is implemented with raw redirects without loading or error states.

Proposed Solution

Summary

Create a recipe folder (src/recipes/auth-flows/) containing page components for each auth flow, a shared auth layout, a mock auth service, and documentation. Each flow is a self-contained component that can be copied independently.

Key Capabilities

PasswordResetRequest page: email input, submit, check-email prompt.
PasswordResetConfirm page: token validation, new password input with strength indicator, success state.
EmailVerification page: token extraction from URL, verification call, success/expired/invalid states.
InvitationAcceptance page: token validation, set password, accept invite, success.
MfaSetup wizard: display TOTP secret and QR code -> verify code -> display recovery codes -> confirm saved.
RecoveryCodeRegeneration page: confirm action -> display new codes -> confirm saved.
SsoHandoff page: provider selection -> redirect initiation -> callback loading/error states.
AuthLayout shared layout: centered card with logo, heading, and footer.
RecoveryCodeDisplay component: code grid with copy-all, download-as-text, and print actions.

User Experience

Each flow follows a clear progression with appropriate states. Users see loading indicators during API calls, clear error messages on failure, and success confirmations on completion. Recovery codes are displayed in a secure, actionable format with multiple save options.

Developer Experience

Developers copy individual flow components or the entire recipe. Each flow accepts an authService prop (or uses context) for backend integration. The mock auth service makes all flows testable and previewable in Storybook. The recipe MDX documents the expected API contract for each flow.

Requirements

ID	Requirement	Priority	Notes
FR-001	The recipe must include a password reset flow (request + confirm)	Must	Core auth flow
FR-002	The recipe must include an email verification flow	Must	Core auth flow
FR-003	The recipe must include an invitation acceptance flow	Must	Common enterprise flow
FR-004	The recipe must include an MFA setup flow (TOTP)	Must	Security requirement
FR-005	The recipe must include a recovery code display and regeneration flow	Must	MFA recovery
FR-006	The recipe must include an SSO handoff flow	Must	Enterprise auth
FR-007	The recipe must include a shared auth layout	Must	Consistent auth UX
FR-008	The recipe must ship with stories for every flow state	Must	Visual reference
FR-009	The recipe must ship with tests	Must	Quality gate
FR-010	The recipe must document the expected backend API contract per flow	Must	Integration guide

Priority Definitions

Priority	Meaning
Must	Required for this feature to ship.
Should	Important, but can be deferred if needed.
Could	Nice to have. Not required for initial release.

Functional Requirements

ID	Requirement	User Benefit	Priority
FUNC-001	`PasswordResetRequest`: email input, submit, show “check your email” on success	Initiates reset flow	Must
FUNC-002	`PasswordResetConfirm`: extract token from URL, validate token, show new-password form with strength indicator, submit, show success	Completes password reset	Must
FUNC-003	`PasswordResetConfirm`: show expired/invalid token state with “request new link” action	Error recovery	Must
FUNC-004	`EmailVerification`: extract token from URL, call verify, show success or expired/invalid state	Email confirmation	Must
FUNC-005	`InvitationAcceptance`: extract token, validate invite, show set-password form, submit, show success	New user onboarding	Must
FUNC-006	`MfaSetup` wizard: step 1 (show QR code + TOTP secret), step 2 (verify 6-digit code), step 3 (display recovery codes), step 4 (confirm saved)	Complete MFA enrollment	Must
FUNC-007	`MfaSetup` uses `PanelWizard` pattern for step management	Per P3 design principles	Must
FUNC-008	`RecoveryCodeDisplay`: shows codes in a grid with copy-all, download-as-text, and print buttons	Users can securely save recovery codes	Must
FUNC-009	`RecoveryCodeRegeneration`: confirmation prompt, regenerate, display new codes, confirm saved	Recovery code management	Must
FUNC-010	`SsoHandoff`: provider list, initiate redirect, callback loading state, callback error state with retry	Enterprise SSO	Must
FUNC-011	All forms show inline validation errors (not just toasts)	Field-level error feedback per P3 principles	Must
FUNC-012	All flows show loading states during API calls	No dead UI during network requests	Must
FUNC-013	Password inputs include a show/hide toggle	Usability	Should
FUNC-014	Password strength indicator shows requirements and visual feedback	Users create strong passwords	Should

Non-Functional Requirements

ID	Requirement	Category	Priority
NFR-001	Recipe code must be copy-pasteable and self-contained	Maintainability	Must
NFR-002	All recipe code must pass TypeScript strict mode	Correctness	Must
NFR-003	Stories must render in light and dark themes	Compatibility	Must
NFR-004	Recovery codes must never be logged to the console	Security	Must
NFR-005	Token extraction from URL must sanitize input	Security	Must
NFR-006	Password inputs must use `type="password"` (togglable) and `autocomplete="new-password"` or `autocomplete="current-password"`	Security	Must
NFR-007	All forms must prevent double-submission during loading	Correctness	Must
NFR-008	Auth layout must be responsive and centered on all screen sizes	Compatibility	Must

API / Interface Requirements

Public API

This is a recipe, not a published package. No new public API is exported from the design system.

Name	Type	Description	Required
Recipe folder	`source`	`src/recipes/auth-flows/` with flow components, layout, and mock service	Yes
Recipe MDX	`documentation`	Storybook MDX page with integration guide and API contracts	Yes
Recipe stories	`stories`	Storybook stories covering every flow state	Yes
Recipe tests	`tests`	Vitest tests for flow logic and state management	Yes

Example Usage

// Password reset request page
import { PasswordResetRequest } from "./auth-flows";

function ResetPage() {
  return (
    <AuthLayout logo="/logo.svg" heading="Reset your password">
      <PasswordResetRequest
        onSubmit={async (email) => {
          await authApi.requestPasswordReset(email);
        }}
      />
    </AuthLayout>
  );
}

// MFA setup wizard
import { MfaSetup } from "./auth-flows";

function SetupMfaPage() {
  return (
    <AuthLayout logo="/logo.svg" heading="Set up two-factor authentication">
      <MfaSetup
        onGenerateSecret={async () => authApi.generateTotpSecret()}
        onVerifyCode={async (code) => authApi.verifyTotpCode(code)}
        onComplete={() => router.navigate("/settings")}
      />
    </AuthLayout>
  );
}

API Notes

Each flow component accepts callback props for backend integration (onSubmit, onVerify, etc.).
The mock auth service simulates realistic delays and configurable failure modes.
Token extraction from URL uses URLSearchParams; the recipe documents the expected parameter names.
MfaSetup returns recovery codes from the onVerifyCode callback response.
The recipe documents the expected API contract for each flow:
- POST /auth/reset-password/request - { email }
- POST /auth/reset-password/confirm - { token, password }
- POST /auth/verify-email - { token }
- POST /auth/invitations/accept - { token, password }
- POST /auth/mfa/totp/setup - returns { secret, qrCodeUrl }
- POST /auth/mfa/totp/verify - { code } - returns { recoveryCodes }
- POST /auth/mfa/recovery-codes/regenerate - returns { recoveryCodes }

Accessibility Requirements

ID	Requirement	Notes
A11Y-001	All forms must have accessible labels for every input	`<label>` elements or `aria-label`
A11Y-002	Error messages must be associated with their inputs via `aria-describedby`	Screen readers announce errors in context
A11Y-003	Success and error states must be announced to screen readers	`role="alert"` for errors, `role="status"` for success
A11Y-004	Password visibility toggle must have an accessible label	”Show password” / “Hide password”
A11Y-005	MFA setup wizard must announce step changes	`aria-live` on step indicator or step heading
A11Y-006	Recovery code copy button must announce “Copied” to screen readers	`aria-live="assertive"` confirmation
A11Y-007	QR code must have a text alternative (the TOTP secret as selectable text)	Users who cannot scan QR codes can enter the secret manually
A11Y-008	All interactive elements must be keyboard accessible	Tab, Enter, Space, Escape where applicable
A11Y-009	Auth layout must have a skip-to-content link	Standard a11y pattern

Checklist

Keyboard support is defined.
Focus behavior is defined.
Screen reader behavior is defined.
Color contrast requirements are met.
Reduced motion behavior is considered.
Semantic HTML expectations are documented.
ARIA usage is defined only where needed.

Content and Documentation Requirements

ID	Requirement	Location	Priority
DOC-001	Recipe MDX page with overview and flow diagrams	Storybook MDX	Must
DOC-002	Per-flow integration guide with API contract	Storybook MDX	Must
DOC-003	Security considerations section	Storybook MDX	Must
DOC-004	”How to customize” section for each flow	Storybook MDX	Must
DOC-005	Testing guide	Storybook MDX	Must
DOC-006	Accessibility notes per flow	Storybook MDX	Must

Documentation Should Include

Overview of all auth flows
When to use each flow
Prerequisites (existing auth widgets, backend API)
Per-flow integration guide with expected API contract
Security considerations (token handling, password rules, recovery code safety)
Customization guide (branding, copy, validation rules)
Testing with mock auth service
Accessibility notes
Common mistakes (e.g., not validating tokens on load, logging recovery codes)

Dependencies

Dependency	Type	Owner	Status	Notes
`login-form.tsx`	Design System	David Holmes	Ready	Existing auth widget (reference, not directly imported)
`signup-form.tsx`	Design System	David Holmes	Ready	Existing auth widget (reference)
`verify-mfa-form.tsx`	Design System	David Holmes	Ready	Existing auth widget (reference)
React 18+	Engineering	David Holmes	Ready	Peer dependency
Vitest	Engineering	David Holmes	Ready	Test runner
Design system form components	Design System	David Holmes	Ready	Input, button, etc.
QR code generation library	Engineering	David Holmes	Unknown	Needed for TOTP setup; evaluate `qrcode` or similar

Risks and Tradeoffs

Risk / Tradeoff	Impact	Mitigation
Recipe defines an API contract that may not match consumer backends	Developers must adapt the contract	Document the contract as a recommendation; keep callback props generic
QR code generation adds a dependency	Bundle size increase	Evaluate lightweight options; document as a peer dependency of the recipe
MFA setup wizard complexity	Multi-step flows are harder to implement and test	Use `PanelWizard` pattern per P3 principles; thorough testing and stories
Recovery code display may be screenshotted or photographed	Security risk	Document user guidance about secure storage; provide download-as-file option
SSO handoff requires redirect, which stories cannot fully demonstrate	Limited story coverage for redirect behavior	Show the pre-redirect and callback states; document the redirect in the MDX
Token validation patterns differ across providers	Recipe pattern may not fit all providers	Keep token handling generic; document the pattern, not a specific provider

Open Questions

ID	Question	Owner	Status	Resolution
Q-001	Should the recipe include a “remember this device” checkbox for MFA?	David Holmes	Open	—
Q-002	Should recovery codes be displayed as a downloadable text file, a printable page, or both?	David Holmes	Open	—
Q-003	Should the SSO flow support a configurable list of providers or is that the consumer’s responsibility?	David Holmes	Open	—
Q-004	Should the password strength indicator use zxcvbn or a simpler rule-based checker?	David Holmes	Open	—
Q-005	Should the invitation acceptance flow include an organization name and inviter display?	David Holmes	Open	—

Acceptance Criteria

ID	Criteria	Related Requirement
AC-001	Password reset request flow: email submission shows “check your email” state	FUNC-001
AC-002	Password reset confirm flow: expired token shows error with “request new link”	FUNC-003
AC-003	Email verification: valid token shows success; expired token shows error	FUNC-004
AC-004	Invitation acceptance: valid invite shows set-password form; submission shows success	FUNC-005
AC-005	MFA setup wizard progresses through QR code, verification, recovery codes, and confirmation steps	FUNC-006
AC-006	MFA setup uses `PanelWizard` pattern	FUNC-007
AC-007	Recovery codes display with copy-all and download actions	FUNC-008
AC-008	Recovery code regeneration: confirm, display new codes, confirm saved	FUNC-009
AC-009	SSO handoff: shows provider list and handles callback loading/error states	FUNC-010
AC-010	All forms show inline validation errors, not just toasts	FUNC-011
AC-011	Stories cover every flow state (loading, success, error, expired)	FR-008
AC-012	Unit tests pass covering flow logic and state transitions	FR-009
AC-013	All recipe code passes TypeScript strict mode	NFR-002
AC-014	Recipe MDX renders in Storybook without errors	DOC-001
AC-015	Recovery codes are never logged to the console in any code path	NFR-004

LLM Handoff Instructions

Expected LLM Behavior

Follow the requirements and acceptance criteria in this document.
Do not expand scope beyond the In Scope section.
Respect the Out of Scope section.
Use existing design system form components (inputs, buttons, etc.); do not rebuild them.
Use PanelWizard pattern for the MFA setup flow per P3 design principles.
Keep inline validation errors on fields, not toasts, per P3 design principles.
Use semantic toasts only for success confirmations, not field errors, per P3 design principles.
Token extraction from URL must sanitize and validate input.
Never log recovery codes, tokens, or passwords.
Each flow component should accept callback props for backend integration.
Place the recipe in src/recipes/auth-flows/.

LLM Should Not

Invent undocumented product behavior.
Implement real authentication backends or identity providers.
Modify existing auth widgets (login-form.tsx, signup-form.tsx, verify-mfa-form.tsx).
Add heavy dependencies without justification (evaluate lightweight QR code options).
Store tokens or passwords in localStorage.
Log sensitive data (tokens, passwords, recovery codes).
Use alert() or confirm() for security-sensitive prompts.
Skip the recovery code display step in MFA setup.

Decision Log

Date	Decision	Reason	Owner
2026-05-26	Recipe, not published components	Auth flows are heavily customized per application; recipes give developers full control	David Holmes
2026-05-26	Each flow is an independent component	Consumers may only need some flows; independence simplifies adoption	David Holmes
2026-05-26	Use PanelWizard for MFA setup	Per P3 design principles: multi-step flows with dependent choices use PanelWizard	David Holmes
2026-05-26	Document API contracts as recommendations, not requirements	Different backends have different APIs; the contract is guidance	David Holmes
2026-05-26	Recovery codes with copy-all and download	Users need multiple options to securely save codes; copy and download cover most use cases	David Holmes

Document History

Date	Author	Change
2026-05-26	David Holmes	Initial draft