# Add @suaveplan/react-auth — pages + PermissionGate (Wave 3)

**Package**: `@suaveplan/react-auth`
**Status**: PROPOSED
**Type**: feature

- **Spec delta**: ./specs/react-auth/spec.md

## Why

Wave 1 shipped the `@suaveplan/react-auth` core (client, provider, context, hooks, guard) and Wave 2 shipped the five pure-UI form components. Downstream apps still cannot drop the package into a `react-router-dom` app without re-implementing the routing-aware adapter layer on every page. Wave 3 closes the migration by shipping the six page components (`LoginPage`, `RegisterPage`, `ForgotPasswordPage`, `ResetPasswordPage`, `EmailVerificationPage`, `ProfilePage`) that wire Wave 2 forms to the Wave 1 `useAuth()` actions plus `useNavigate` / `useSearchParams` redirects, and the `PermissionGate` component that conditionally renders children against the Wave 1 `usePermission` hook. After this wave the public surface of `@suaveplan/react-auth` reaches full parity with the upstream `../suaveplan/packages/react/react-auth/` package and the migration is complete.

## What changes

- ADDED: `LoginPage` — wraps `<LoginForm>`, calls `useAuth().signIn`, redirects to `?returnTo` or `/dashboard` on success, applies `useAuthGuard({ requireGuest: true })`.
- ADDED: `RegisterPage` — wraps `<RegisterForm>`, strips `confirmPassword`, calls `useAuth().signUp`, redirects to `/dashboard` on success, applies `useAuthGuard({ requireGuest: true })`.
- ADDED: `ForgotPasswordPage` — wraps `<ForgotPasswordForm>`, calls `useAuth().forgotPassword(email)`, manages local success state + reset.
- ADDED: `ResetPasswordPage` — wraps `<ResetPasswordForm>`, extracts `?token` from search params, calls `useAuth().resetPassword(token, password)`, manages success state, navigates to `/auth/login` and `/auth/forgot-password`, applies `useAuthGuard({ requireGuest: true })`.
- ADDED: `EmailVerificationPage` — wraps `<EmailVerificationView>`, extracts `?token`, auto-runs `useAuth().verifyEmail(token)` on mount, classifies errors into `expired` vs `error`, applies `useAuthGuard({ requireGuest: true })`.
- ADDED: `ProfilePage` — three-tab profile surface (profile / password / account) calling `useAuth().updateProfile`, `changePassword`, `deleteAccount`; applies `useAuthGuard({ requireAuth: true })`; uses `react-ui` Tabs/Card primitives + a new `profilePage` translation group.
- ADDED: `PermissionGate` — renders children when `usePermission()` reports the configured bitmask permissions (any-of by default, all-of when `requireAll`); otherwise renders a fallback (default `null`).
- ADDED: `AuthProfilePageStrings` interface + `profilePage` group on every locale pack (`enGb` / `cyGb` / `zhCn`) — purely additive, the existing Wave 1 `profile` group is left untouched.
- ADDED: Subpath exports under `./pages/<page>` for every page and `./components/permission-gate` for the gate, mirroring the Wave 1 + Wave 2 per-symbol convention.

## Out of scope

- MFA / passkey / magic-link flows — enterprise audit §4 enhancements, never part of upstream.
- `RoleGuard` companion to `PermissionGate` — enterprise audit §4 enhancement.
- Device-management / audit-trail pages — enterprise audit §4 enhancements.

## Source mapping

This change derives from `../suaveplan/enterprise/react-auth.md` and `../suaveplan/packages/react/react-auth/src/`.

| Requirement | Source lines | Notes |
|---|---|---|
| `LoginPage` shape | `pages/login/login.tsx:1-42` | Verbatim semantics; uses Wave 2 `<LoginForm>`. |
| `RegisterPage` shape | `pages/register/register.tsx:1-41` | Verbatim semantics; strips `confirmPassword` before calling `signUp`. |
| `ForgotPasswordPage` shape | `pages/forgot-password/forgot-password.tsx:1-43` | Verbatim semantics. |
| `ResetPasswordPage` shape | `pages/reset-password/reset-password.tsx:1-61` | Verbatim semantics; `?token` from search params. |
| `EmailVerificationPage` shape | `pages/email-verification/email-verification.tsx:1-96` | Verbatim semantics; upstream's `useTranslation` swapped for Wave 2 `translations` prop pattern (consistent with Wave 1 i18n decision). The dual `EmailVerification` legacy fork (lines 99-254) is NOT ported — it duplicated the `EmailVerificationView` which already shipped in Wave 2. |
| `ProfilePage` shape | `pages/profile/profile.tsx:1-638` | Three-tab profile / password / account surface. Upstream's `useTranslation` swapped for a `translations` prop defaulting to `enGb.auth.profilePage`. The implementation is split into `profile-page.tsx` (shell) + `profile-page-sections.tsx` (three section renderers) to honour the 300-line hard cap (§3). |
| `PermissionGate` shape | `components/permission-gate/permission-gate.tsx:1-28` | Verbatim semantics. |

### Requirements with no source line

| Requirement | Justification |
|---|---|
| `translations?: Partial<...>` prop on `EmailVerificationPage` and `ProfilePage` | Genesis-specific — Wave 1 dropped `@suaveplan/react-translate`; Wave 2 established the prop-injection precedent. Wave 3 follows. |
| New `profilePage` translation group + `AuthProfilePageStrings` interface | Required because the upstream profile page used 20+ string keys not in Wave 1's slim `profile` group; rather than mutate the Wave 1 group (which Wave 2 also reads), Wave 3 adds a sibling `profilePage` group. |
| 100% statement / branch / function / line coverage | Genesis-wide policy. |
| Sibling `<page>.md` per implementation file | Genesis rule §4. |
| Sibling `<page>.stories.tsx` per page + permission-gate | CLAUDE.md: "Every React component needs `.stories.tsx`." |
| Sibling `.test.tsx` per page + permission-gate | Genesis-wide — upstream's pages had no co-located unit tests at this layer either. |

## Verification approach

Every page and `PermissionGate` ships a sibling `.test.tsx` that uses `@suaveplan/testing/runner` + `@testing-library/react` with real `react-hook-form`, real Zod, real `<MemoryRouter>`, and a real `<AuthProvider>` wrapped around an injectable `AuthClient` stub. No `vi.mock`. The `wrapForm` helper from Wave 2 is reused / extended to mount the auth context.

- `src/pages/login/login.test.tsx` — guard redirect when already authenticated, happy-path navigate to `returnTo`, happy-path default to `/dashboard`, signIn failure swallowed by the page.
- `src/pages/register/register.test.tsx` — guard redirect, happy-path strips `confirmPassword`, navigate to `/dashboard`, signUp failure swallowed.
- `src/pages/forgot-password/forgot-password.test.tsx` — happy-path submit renders success view with email, `onReset` clears, error surfaces.
- `src/pages/reset-password/reset-password.test.tsx` — missing-token branch shows invalid view, happy-path renders success, login navigation CTA, forgot navigation CTA.
- `src/pages/email-verification/email-verification.test.tsx` — missing-token sets `error` state, success sets `success` state, expired-token error classifies as `expired`, `onContinueToLogin` / `onRegisterAgain` / `onTryAgain` navigate correctly.
- `src/pages/profile/profile.test.tsx` — guard redirect for unauthenticated, three tab switches, profile update success, password change validation (required, length, mismatch), delete-account confirmation flow.
- `src/components/permission-gate/permission-gate.test.tsx` — renders children when permitted, renders fallback when denied, `requireAll` AND semantics, unauthenticated denies, numeric permission accepted.
- `src/index.test.ts` — extended to assert the 7 new symbols (`LoginPage`, `RegisterPage`, `ForgotPasswordPage`, `ResetPasswordPage`, `EmailVerificationPage`, `ProfilePage`, `PermissionGate`) appear in the root barrel.

## Migration impact

- `package.json` gains 7 new subpath exports under `./pages/<page>` and `./components/permission-gate`. No new runtime dependencies — every dep is already present from Wave 1 or Wave 2 (`react-router-dom` is a peer + dev dep on Wave 1).
- `vite.config.ts` `lib.entry` gains 7 new entries; `rollupOptions.external` already lists every consumed package.
- No Wave 1 or Wave 2 file is modified except `src/index.ts` (named re-exports for the 7 new symbols added — strictly additive), `src/components/index.ts` (one new entry for `PermissionGate`), `src/index.test.ts` (asserts the new symbols are present), and the three locale-pack files which gain the new `profilePage` group as a strictly additive sibling under `auth`.
- No downstream consumers yet — `@suaveplan/react-auth-whitelabel` is the only sibling and it ships independently. Verified by `bunx turbo ls --filter=...@suaveplan/react-auth` (empty list).