# Capability Spec Delta: react-auth (add-react-auth-pages) **Package**: `@suaveplan/react-auth` **Status**: PROPOSED > Every requirement below carries a `**Verified by:**` line at authoring time. ## ADDED Requirements ### Requirement: LoginPage wires LoginForm to the auth context with router redirect The package SHALL expose a `` component that renders the Wave 2 ``, calls `useAuth().signIn(values)` on submit, redirects to `useSearchParams().get("returnTo")` (or `/dashboard` if absent) via `useNavigate`, and applies `useAuthGuard({ requireGuest: true })` so already-authenticated visitors are redirected away. The page SHALL swallow rejections from `signIn` — the underlying `useAuth().error` field carries the surfaced message into the form's destructive alert. #### Scenario: happy path navigates to returnTo - **WHEN** `` is mounted under `/auth/login?returnTo=/inbox` and the user submits valid credentials - **THEN** `useAuth().signIn` is called with the typed credentials AND `useNavigate` is called with `"/inbox"` #### Scenario: happy path defaults to /dashboard - **WHEN** `` is mounted under `/auth/login` (no `returnTo`) and the user submits valid credentials - **THEN** `useNavigate` is called with `"/dashboard"` #### Scenario: signIn rejection does not throw - **WHEN** `useAuth().signIn` rejects - **THEN** the page does not throw and the error message renders inside the `` alert **Verified by:** `src/pages/login/login.test.tsx::"navigates to returnTo on happy path"` AND `src/pages/login/login.test.tsx::"defaults to /dashboard when returnTo is absent"` AND `src/pages/login/login.test.tsx::"swallows signIn rejection and surfaces the error in the form"` --- ### Requirement: RegisterPage wires RegisterForm to signUp and strips confirmPassword The package SHALL expose a `` component that renders the Wave 2 ``, strips `confirmPassword` from the submitted values before calling `useAuth().signUp(data)`, redirects to `/dashboard` on success, and applies `useAuthGuard({ requireGuest: true })`. The page SHALL swallow `signUp` rejections (errors surface via the form alert). #### Scenario: happy path strips confirmPassword - **WHEN** the form submits `{ email, password, confirmPassword, username, ... }` - **THEN** `useAuth().signUp` is called with the payload minus `confirmPassword` AND `useNavigate("/dashboard")` is invoked #### Scenario: signUp rejection does not throw - **WHEN** `useAuth().signUp` rejects - **THEN** the page does not throw **Verified by:** `src/pages/register/register.test.tsx::"strips confirmPassword and navigates to /dashboard on happy path"` AND `src/pages/register/register.test.tsx::"swallows signUp rejection"` --- ### Requirement: ForgotPasswordPage wires ForgotPasswordForm to forgotPassword with success view The package SHALL expose a `` component that renders the Wave 2 ``, calls `useAuth().forgotPassword(email)` on submit, drives the `isSuccess` / `emailSent` props from local state on resolution, and clears that state when the form's `onReset` callback fires. #### Scenario: happy path flips to success view - **WHEN** the form submits and `forgotPassword` resolves - **THEN** the form is re-rendered with `isSuccess={true}` AND `emailSent` equals the submitted email #### Scenario: reset returns to entry view - **WHEN** `isSuccess` is true and the success view's reset callback fires - **THEN** the form is re-rendered with `isSuccess={false}` AND `emailSent=""` **Verified by:** `src/pages/forgot-password/forgot-password.test.tsx::"flips to success view on happy path"` AND `src/pages/forgot-password/forgot-password.test.tsx::"reset returns to entry view"` --- ### Requirement: ResetPasswordPage extracts ?token and drives ResetPasswordForm state The package SHALL expose a `` component that reads `?token` from `useSearchParams`, passes `hasToken={!!token}` to the Wave 2 ``, calls `useAuth().resetPassword(token, password)` on submit when a token exists, flips `isSuccess` on resolution, and exposes `onNavigateToLogin` (`/auth/login`) and `onNavigateToForgotPassword` (`/auth/forgot-password`) callbacks for the form's success / invalid-token CTAs. The page SHALL apply `useAuthGuard({ requireGuest: true })`. #### Scenario: missing token renders invalid-token view - **WHEN** the page is mounted under `/auth/reset-password` (no `?token`) - **THEN** `` is rendered with `hasToken={false}` #### Scenario: happy path flips to success - **WHEN** the form submits with `?token=abc` present and `resetPassword` resolves - **THEN** `useAuth().resetPassword` is called with `("abc", password)` AND the form re-renders with `isSuccess={true}` #### Scenario: navigation CTAs fire - **WHEN** the form invokes `onNavigateToLogin` or `onNavigateToForgotPassword` - **THEN** `useNavigate` is called with `/auth/login` or `/auth/forgot-password` respectively **Verified by:** `src/pages/reset-password/reset-password.test.tsx::"renders invalid-token view when ?token is absent"` AND `src/pages/reset-password/reset-password.test.tsx::"flips to success on happy path"` AND `src/pages/reset-password/reset-password.test.tsx::"navigates on login and forgot-password CTAs"` --- ### Requirement: EmailVerificationPage auto-verifies ?token and classifies errors The package SHALL expose an `` component that reads `?token` from `useSearchParams`, calls `useAuth().verifyEmail(token)` once on mount, drives the Wave 2 `` status via local state (`verifying` → `success` / `error` / `expired`), classifies any error whose message contains `expired` or `invalid` (case-insensitive) as `expired`, and exposes navigation callbacks (`onContinueToLogin` → `/auth/login`, `onRegisterAgain` → `/auth/register`, `onTryAgain` reloads). The page SHALL apply `useAuthGuard({ requireGuest: true })`. #### Scenario: missing token sets error status - **WHEN** the page mounts with no `?token` - **THEN** `` is rendered AND `useAuth().verifyEmail` is NOT called #### Scenario: happy-path sets success status - **WHEN** `verifyEmail` resolves - **THEN** `` is rendered #### Scenario: expired token classifies as expired - **WHEN** `verifyEmail` rejects with `new Error("token has expired")` - **THEN** `` is rendered **Verified by:** `src/pages/email-verification/email-verification.test.tsx::"renders error status when ?token is absent"` AND `src/pages/email-verification/email-verification.test.tsx::"renders success status on happy path"` AND `src/pages/email-verification/email-verification.test.tsx::"classifies expired-token rejection as expired"` --- ### Requirement: ProfilePage renders a three-tab account surface bound to useAuth The package SHALL expose a `` (aliased as `Profile` for upstream compatibility) component that renders a three-tab surface (`profile`, `password`, `account`) using `@suaveplan/react-ui` ``, hydrates the `profile` form from `useAuth().user`, calls `useAuth().updateProfile({ name, email })` on profile-tab submit, calls `useAuth().changePassword({ currentPassword, newPassword })` on password-tab submit (after local validation: required, ≥8 chars, match), and calls `useAuth().deleteAccount(currentPassword)` on account-tab confirmation (then navigates to `/auth/login`). The page SHALL apply `useAuthGuard({ requireAuth: true })`. The page SHALL accept a `translations?: Partial` prop defaulting to `enGb.auth.profilePage`. #### Scenario: guards unauthenticated visitors - **WHEN** the page is mounted with `useAuth().isAuthenticated === false` - **THEN** `useNavigate("/auth/login")` is invoked #### Scenario: tab switching renders the requested section - **WHEN** the user clicks the `password` tab - **THEN** the password form is rendered AND the profile form is hidden #### Scenario: profile update calls updateProfile and shows success - **WHEN** the profile form is submitted with edited name + email - **THEN** `updateProfile({ name, email })` is called AND a success alert appears #### Scenario: password change validates locally before calling changePassword - **WHEN** newPassword and confirmPassword do not match - **THEN** `changePassword` is NOT called AND a mismatch error renders #### Scenario: delete-account flow - **WHEN** the user confirms delete with a password - **THEN** `deleteAccount(password)` is called AND `useNavigate("/auth/login")` is invoked **Verified by:** `src/pages/profile/profile.test.tsx::"guards unauthenticated visitors"` AND `src/pages/profile/profile.test.tsx::"switches tabs on click"` AND `src/pages/profile/profile.test.tsx::"profile update success"` AND `src/pages/profile/profile.test.tsx::"password change validates mismatch locally"` AND `src/pages/profile/profile.test.tsx::"delete account confirmation calls deleteAccount and navigates"` --- ### Requirement: PermissionGate conditionally renders by bitmask permission check The package SHALL expose a `` component that consumes `usePermission()` from Wave 1 and renders `children` when the configured `permissions` array passes the check, otherwise renders `fallback` (default `null`). The default semantics SHALL be ANY-of; setting `requireAll={true}` SHALL switch to ALL-of semantics. Each entry in `permissions` MAY be a named `Permission` key OR a raw `number` bitmask. #### Scenario: any-of permits when one bit matches - **WHEN** the user has `Permissions.USER_READ` and the gate requires `["USER_READ", "ADMIN_WRITE"]` - **THEN** the children are rendered #### Scenario: requireAll denies when one bit missing - **WHEN** the user has only `Permissions.USER_READ` and the gate requires `["USER_READ", "ADMIN_WRITE"]` with `requireAll={true}` - **THEN** the fallback is rendered #### Scenario: numeric permission accepted - **WHEN** the gate is given a raw numeric bitmask matching the user's bits - **THEN** the children are rendered #### Scenario: unauthenticated user always denied - **WHEN** `useAuth().user === null` - **THEN** the fallback is rendered **Verified by:** `src/components/permission-gate/permission-gate.test.tsx::"renders children when any-of matches"` AND `src/components/permission-gate/permission-gate.test.tsx::"renders fallback when requireAll fails"` AND `src/components/permission-gate/permission-gate.test.tsx::"accepts numeric permission"` AND `src/components/permission-gate/permission-gate.test.tsx::"renders fallback when unauthenticated"`