suaveplan/openspec/specs/react-auth/spec.md

<!-- markdownlint-disable MD024 -->

# Capability Spec: react-auth

**Package**: `@suaveplan/react-auth`
**Status**: SHIPPED

> Every requirement below carries a `**Verified by:**` line at authoring time.

## ADDED Requirements

### Requirement: AuthClient wraps better-auth with site-domain header propagation

The package SHALL expose an `AuthClient` class and a `createAuthClient(config)` factory. The class SHALL wrap `better-auth/client` and SHALL forward every request through the underlying client. When `AuthClientConfig.siteDomain` is set, every request SHALL carry an `x-site-domain` header.

#### Scenario: site-domain header attached when configured

- **WHEN** `createAuthClient({ baseURL, siteDomain: "tenant-a" }).signIn({ email, password })` is called and the underlying client method is observed
- **THEN** the call options include `fetchOptions.headers["x-site-domain"] === "tenant-a"`

#### Scenario: header omitted when not configured

- **WHEN** `createAuthClient({ baseURL }).getSession()` is called
- **THEN** the call options omit the `x-site-domain` header

#### Scenario: AuthClientConfig validates at the boundary

- **WHEN** `createAuthClient` is invoked with a non-URL `baseURL`
- **THEN** a `ReactAuthConfigInvalidError` is thrown with code `REACT_AUTH.CONFIG_INVALID`

**Verified by:** `src/client/auth-client.test.ts::"propagates x-site-domain header on every method when siteDomain is configured"` AND `src/client/auth-client.test.ts::"omits x-site-domain header when siteDomain is not configured"` AND `src/client/auth-client.test.ts::"throws ReactAuthConfigInvalidError when baseURL is not a valid URL"`

---

### Requirement: AuthClient list-sessions normalises Date fields to ISO strings

The `AuthClient.listSessions()` method SHALL return `Session[]` and SHALL convert each session's `createdAt` / `updatedAt` / `expiresAt` fields from `Date` to ISO string (or leave them as the underlying type when already a string).

#### Scenario: dates converted

- **WHEN** the underlying client returns sessions with `Date` instances
- **THEN** the returned `Session[]` contains ISO-string `createdAt` / `updatedAt`

**Verified by:** `src/client/auth-client.test.ts::"converts Date fields on listSessions to ISO strings"`

---

### Requirement: AuthProvider exposes auth state and 11 actions through context

The package SHALL expose an `AuthProvider` component and a `useAuth()` hook. The context value SHALL include `{ user, session, isLoading, isAuthenticated, error, client }` and the 11 actions `signIn` / `signUp` / `signOut` / `updateProfile` / `changePassword` / `forgotPassword` / `resetPassword` / `verifyEmail` / `resendVerificationEmail` / `deleteAccount` / `refreshSession`. `useAuth()` outside an `AuthProvider` SHALL throw `ReactAuthContextMissingError` with code `REACT_AUTH.CONTEXT_MISSING`.

#### Scenario: initial session loaded on mount

- **WHEN** `AuthProvider` mounts with `skipInitialCheck=false` and the client's `getSession()` returns `{ data: { user, session } }`
- **THEN** the context settles with `isAuthenticated=true`, `user`, `session`, `isLoading=false`

#### Scenario: useAuth outside provider throws

- **WHEN** `useAuth()` is called outside any `AuthProvider`
- **THEN** a `ReactAuthContextMissingError` is thrown with code `REACT_AUTH.CONTEXT_MISSING`

#### Scenario: each action settles loading and surfaces errors

- **WHEN** any of the 11 actions resolves successfully OR rejects
- **THEN** `isLoading` flips false; on reject `error` carries the wrapped `Error` and the action re-throws

**Verified by:** `src/context/auth-context.test.tsx::"loads the initial session and settles isAuthenticated=true"` AND `src/context/auth-context.test.tsx::"useAuth outside an AuthProvider throws ReactAuthContextMissingError"` AND `src/context/auth-context.test.tsx::"every action settles isLoading and propagates errors"`

---

### Requirement: AuthGuard gates children by auth / guest / verified / roles

The `AuthGuard` component SHALL render `loadingComponent` (or a default spinner) while `isLoading=true`. When loading completes it SHALL render `children` if and only if every configured predicate (`requireAuth` / `requireGuest` / `requireVerified` / `allowedRoles`) is satisfied; otherwise it SHALL render `fallback` (or `null`).

#### Scenario: authenticated user passes default requireAuth

- **WHEN** an authenticated, verified user enters an `AuthGuard requireAuth`
- **THEN** `children` is rendered

#### Scenario: unauthenticated user gets fallback when requireAuth

- **WHEN** an unauthenticated user enters an `AuthGuard requireAuth fallback={<X/>}`
- **THEN** `<X/>` is rendered and `children` is not

#### Scenario: role mismatch denied

- **WHEN** an authenticated user with `role="user"` enters `AuthGuard allowedRoles={["admin"]}`
- **THEN** the guard does not render `children`

**Verified by:** `src/components/auth-guard/auth-guard.test.tsx::"renders children when authenticated and no extra predicates are set"` AND `src/components/auth-guard/auth-guard.test.tsx::"renders fallback when unauthenticated and requireAuth is set"` AND `src/components/auth-guard/auth-guard.test.tsx::"denies when allowedRoles does not include the user role"`

---

### Requirement: useAuthGuard imperatively redirects via react-router-dom

The `useAuthGuard(options)` hook SHALL call `react-router-dom`'s `useNavigate()` and SHALL navigate to `redirectTo` (default `/auth/login`) when `requireAuth` fails, to `/` when `requireGuest` fails, to `/auth/verify-email` when `requireVerified` fails, and to `/unauthorized` when `allowedRoles` fails. It SHALL invoke `onUnauthorized` before the auth / role redirects. The hook SHALL also return `{ isLoading, isAuthenticated, user, canAccess }` for inline checks.

#### Scenario: redirects to login when not authenticated

- **WHEN** an unauthenticated user mounts a component calling `useAuthGuard({ requireAuth: true })`
- **THEN** `navigate("/auth/login")` is called once

#### Scenario: canAccess reflects every predicate

- **WHEN** any predicate fails
- **THEN** `canAccess === false`; when all predicates pass, `canAccess === true`

**Verified by:** `src/hooks/use-auth-guard.test.tsx::"redirects to /auth/login when requireAuth fails"` AND `src/hooks/use-auth-guard.test.tsx::"canAccess matrix reflects every predicate combination"`

---

### Requirement: usePermission exposes bitwise permission checks

The `usePermission()` hook SHALL expose `hasPermission` / `hasAnyPermission` / `hasAllPermissions` / `getPermissionNames` / `userRoles`. Each predicate SHALL accept either a `Permission` string key or a numeric bitmask and SHALL test `(user.roles & bit) === bit`. With no authenticated user, every predicate SHALL return `false` and `getPermissionNames()` SHALL return `[]`.

#### Scenario: string and numeric permission accepted

- **WHEN** `hasPermission("USER_READ")` and `hasPermission(1)` are called with `user.roles = 0b1`
- **THEN** both return `true`

#### Scenario: unauthenticated bails out

- **WHEN** no user is present
- **THEN** `hasPermission`, `hasAnyPermission`, `hasAllPermissions` all return `false`

**Verified by:** `src/hooks/use-permission.test.tsx::"accepts string and numeric Permission inputs"` AND `src/hooks/use-permission.test.tsx::"returns false for every predicate when unauthenticated"`

---

### Requirement: better-auth response adapter narrows union to internal shapes

The package SHALL expose `isBetterAuthError` / `hasBetterAuthData` / `transformSessionResponse` / `transformAuthResponse` / `transformGenericResponse` / `transformUpdateProfileResponse`. Each transform SHALL accept `unknown` (no `any`), SHALL detect the `error`-tagged and `data`-tagged variants, and SHALL emit the package's internal `User` / `Session` / `AuthResponse` shapes with ISO-string timestamps.

#### Scenario: session response with Date timestamps normalised

- **WHEN** `transformSessionResponse({ data: { user: { ..., createdAt: Date }, session: { ..., expiresAt: Date } } })` is called
- **THEN** the returned `{ user, session }` carries ISO strings

#### Scenario: error variant surfaces message

- **WHEN** the response carries `{ error, message }`
- **THEN** the transform returns `{ session: null, user: null, error: <message> }`

**Verified by:** `src/lib/better-auth-adapter.test.ts::"transformSessionResponse normalises Date timestamps to ISO strings"` AND `src/lib/better-auth-adapter.test.ts::"transforms surface the better-auth error message"`

---

### Requirement: REACT_AUTH error code registry covers every thrown error

The package SHALL export `REACT_AUTH_CODES = defineCodes("REACT_AUTH", [...])` with at least the 10 codes `CONFIG_INVALID`, `CONTEXT_MISSING`, `GUARD_PROPS_INVALID`, `GUARD_OPTIONS_INVALID`, `CLIENT_NOT_INITIALISED`, `BETTER_AUTH_RESPONSE_INVALID`, `SIGN_IN_FAILED`, `SIGN_UP_FAILED`, `SESSION_FETCH_FAILED`, `PERMISSION_DENIED`. Every code SHALL be thrown by at least one production path and SHALL surface through a typed `ReactAuthError` subclass.

#### Scenario: every code has a thrown call site

- **WHEN** the test suite enumerates `REACT_AUTH_CODES` values
- **THEN** every code is reachable via a typed subclass that ships in `src/error-codes/error-codes.ts`

**Verified by:** `src/error-codes/error-codes.test.ts::"every REACT_AUTH code is thrown by at least one production path"`

---

### Requirement: OTel instruments emit through suaveplan.react-auth meter

The package SHALL build OTel instruments lazily under `metrics.getMeter("suaveplan.react-auth")` and SHALL emit at minimum: `react_auth.sign_in.total`, `react_auth.sign_up.total`, `react_auth.sign_out.total`, `react_auth.guard.allow.total`, `react_auth.guard.deny.total` counters, and `react_auth.session_fetch.duration_ms` histogram.

#### Scenario: in-memory MeterProvider captures every emit

- **WHEN** a real `MeterProvider` + `InMemoryMetricExporter` is wired and every production path that emits is executed
- **THEN** the corresponding instrument records the expected attributes

**Verified by:** `src/observability/react-auth-metrics.test.ts::"emits sign-in / sign-up / sign-out / guard / session-fetch instruments through suaveplan.react-auth"`

---

### Requirement: Locale packs ship for en-GB / cy-GB / zh-CN with key parity

The package SHALL export `enGb`, `cyGb`, `zhCn` (default exports) and an aggregate `authTranslations = { "en-gb": enGb, "cy-gb": cyGb, "zh-cn": zhCn }`. Every locale SHALL carry the same set of `auth.<group>.<key>` paths so Wave-2 forms can resolve without locale-specific guards.

#### Scenario: key parity across locales

- **WHEN** the locale-pack test flattens every dotted key in each locale
- **THEN** the three sets are equal

**Verified by:** `src/translations/translations.test.ts::"every locale pack exposes the same dotted key set"`

---

### Requirement: Root barrel uses explicit named re-exports

The root `src/index.ts` and every feature barrel SHALL use explicit `export { … }` re-exports — never `export *`. The barrel SHALL expose the public surface enumerated in `proposal.md` `## What changes` and nothing else.

#### Scenario: package roots are explicit

- **WHEN** repo-wide `grep -rn '^export \\*' packages/react/react-auth/src/` is run
- **THEN** the result is empty

**Verified by:** `src/index.test.ts::"the root barrel exports exactly the documented public surface"`

---

### Requirement: LoginForm renders a Zod-validated sign-in form with email, password, and remember-me

The package SHALL expose a `LoginForm` component that renders a card-layout sign-in form with email + password + remember-me fields. The form SHALL validate via `react-hook-form` + `zodResolver` against an internal `loginSchema` requiring email to be a non-empty valid email and password to be at least 8 characters. Submit SHALL invoke the caller-supplied `onSubmit({ email, password, rememberMe })`. The component SHALL render a destructive `Alert` when `error` is non-null, disable the submit button when `isLoading` or `formState.isSubmitting` is true, and accept a `translations` prop overriding the default `enGb.auth.login` strings.

#### Scenario: invalid email shows Zod error on blur

- **WHEN** the user types `not-an-email` into the email field and submits
- **THEN** the text "Invalid email address" appears

#### Scenario: short password rejected

- **WHEN** the user submits with password `"abc"`
- **THEN** the text "Password must be at least 8 characters" appears and `onSubmit` is NOT called

#### Scenario: happy path submit

- **WHEN** the user fills `alice@example.com` + `correcthorsebatterystaple` and clicks Sign in
- **THEN** `onSubmit({ email: "alice@example.com", password: "correcthorsebatterystaple", rememberMe: true })` is called

#### Scenario: error prop renders alert

- **WHEN** `error={new Error("Invalid credentials")}` is passed
- **THEN** an alert containing "Invalid credentials" is in the document

#### Scenario: translations prop overrides defaults

- **WHEN** `translations={{ submit: "Connexion" }}` is passed
- **THEN** the submit button displays "Connexion"

**Verified by:** `src/components/login-form/login-form.test.tsx::"shows Zod error when email is invalid"` AND `src/components/login-form/login-form.test.tsx::"shows Zod error when password is shorter than 8 characters"` AND `src/components/login-form/login-form.test.tsx::"calls onSubmit with the typed payload on happy path"` AND `src/components/login-form/login-form.test.tsx::"renders the error prop in a destructive Alert"` AND `src/components/login-form/login-form.test.tsx::"overrides the submit copy when translations prop is supplied"`

---

### Requirement: RegisterForm renders a Zod-validated sign-up form with cross-field password match

The package SHALL expose a `RegisterForm` component rendering email, username, password, confirm-password, optional first-name, surname, date-of-birth, sex (4-option select), gender, company fields. The Zod schema SHALL enforce email validity, username `^[a-zA-Z0-9_]+$` with length 3–30, password ≥ 8 chars, and a `confirmPassword` cross-field refinement matching `password`. Submit SHALL fire only when validation passes. The component SHALL accept `error`, `isLoading`, and `translations` props mirroring `LoginForm` semantics.

#### Scenario: confirmPassword mismatch blocks submit

- **WHEN** password `"longenough1"` and confirmPassword `"longenough2"` are submitted
- **THEN** "Passwords don't match" appears under the confirm field and `onSubmit` is NOT called

#### Scenario: username regex enforced

- **WHEN** username `"has space"` is submitted
- **THEN** the Zod regex error appears and `onSubmit` is NOT called

#### Scenario: happy path submit

- **WHEN** every required field is valid and the form is submitted
- **THEN** `onSubmit` receives the full typed payload including the default `sex: "prefer-not-to-say"`

**Verified by:** `src/components/register-form/register-form.test.tsx::"blocks submit when passwords do not match"` AND `src/components/register-form/register-form.test.tsx::"rejects usernames that do not match the regex"` AND `src/components/register-form/register-form.test.tsx::"calls onSubmit with the typed payload on happy path"` AND `src/components/register-form/register-form.test.tsx::"renders the error prop in a destructive Alert"`

---

### Requirement: ForgotPasswordForm renders an email-only Zod-validated form with success view

The package SHALL expose a `ForgotPasswordForm` component rendering an email-only form. When `isSuccess` is true the component SHALL switch to a confirmation card displaying `emailSent`, a "send another" button wired to `onReset`, and a "back to login" link. Otherwise it SHALL render the email form with Zod validation, a destructive alert when `error` is non-null, and a submit button disabled while `isLoading` or `isSubmitting`. A `translations` prop SHALL override `enGb.auth.forgotPassword` defaults.

#### Scenario: invalid email blocked

- **WHEN** the user submits "not-email"
- **THEN** "Invalid email address" appears and `onSubmit` is NOT called

#### Scenario: success view rendered

- **WHEN** `isSuccess` is true and `emailSent="alice@example.com"`
- **THEN** the document contains "alice@example.com" and a button whose click calls `onReset`

**Verified by:** `src/components/forgot-password-form/forgot-password-form.test.tsx::"blocks submit when email is invalid"` AND `src/components/forgot-password-form/forgot-password-form.test.tsx::"calls onSubmit with the typed payload on happy path"` AND `src/components/forgot-password-form/forgot-password-form.test.tsx::"renders the success view with emailSent and a working onReset button"` AND `src/components/forgot-password-form/forgot-password-form.test.tsx::"renders the error prop in a destructive Alert"`

---

### Requirement: ResetPasswordForm renders new+confirm password with success and invalid-token views

The package SHALL expose a `ResetPasswordForm` component supporting three view modes: form (default), success (`isSuccess=true`), and invalid token (`hasToken=false`). The schema SHALL require both `password` and `confirmPassword` ≥ 8 chars with a cross-field match refinement. The success view SHALL render a "sign in" CTA wired to `onNavigateToLogin`; the invalid-token view SHALL render a "request new link" CTA wired to `onNavigateToForgotPassword`. The form view SHALL accept `error`, `isLoading`, and `translations` props.

#### Scenario: password mismatch blocks submit

- **WHEN** password `"longenough1"` and confirm `"longenough2"` are submitted
- **THEN** "Passwords don't match" appears and `onSubmit` is NOT called

#### Scenario: success view renders CTA

- **WHEN** `isSuccess=true`
- **THEN** clicking the Sign in CTA calls `onNavigateToLogin`

#### Scenario: invalid token view renders CTA

- **WHEN** `hasToken=false`
- **THEN** clicking the Request new reset link CTA calls `onNavigateToForgotPassword`

**Verified by:** `src/components/reset-password-form/reset-password-form.test.tsx::"blocks submit when passwords do not match"` AND `src/components/reset-password-form/reset-password-form.test.tsx::"calls onSubmit with the typed payload on happy path"` AND `src/components/reset-password-form/reset-password-form.test.tsx::"renders the success view with a working onNavigateToLogin CTA"` AND `src/components/reset-password-form/reset-password-form.test.tsx::"renders the invalid-token view with a working onNavigateToForgotPassword CTA"`

---

### Requirement: EmailVerificationView renders four status modes with caller-supplied translations

The package SHALL expose an `EmailVerificationView` component accepting `status: "verifying" | "success" | "expired" | "error"`. Each status SHALL render a Card with an icon, title, description, and (where applicable) a CTA wired to one of `onContinueToLogin` / `onRegisterAgain` / `onTryAgain`. The `error` status SHALL render a destructive Alert; the `error` retry CTA SHALL be disabled while `isLoading`. A `translations` prop SHALL override `enGb.auth.emailVerification` defaults; an optional `message` prop SHALL override the default status description.

#### Scenario: verifying state renders spinner and copy

- **WHEN** `status="verifying"`
- **THEN** a `role="status"` spinner is present and the default English "Verifying email..." copy is visible

#### Scenario: success CTA fires onContinueToLogin

- **WHEN** `status="success"` and the CTA is clicked
- **THEN** `onContinueToLogin` is called once

#### Scenario: error CTA fires onTryAgain and respects isLoading

- **WHEN** `status="error"` and `isLoading=false`
- **THEN** the retry CTA is enabled and clicking it calls `onTryAgain`

#### Scenario: expired CTA fires onRegisterAgain

- **WHEN** `status="expired"` and the CTA is clicked
- **THEN** `onRegisterAgain` is called once

**Verified by:** `src/components/email-verification-view/email-verification-view.test.tsx::"renders the verifying status with a spinner"` AND `src/components/email-verification-view/email-verification-view.test.tsx::"fires onContinueToLogin from the success CTA"` AND `src/components/email-verification-view/email-verification-view.test.tsx::"fires onTryAgain from the error CTA"` AND `src/components/email-verification-view/email-verification-view.test.tsx::"fires onRegisterAgain from the expired CTA"` AND `src/components/email-verification-view/email-verification-view.test.tsx::"overrides the default copy when translations prop is supplied"`

---

### Requirement: Wave 2 form components reachable from the root barrel

The `@suaveplan/react-auth` root entry SHALL re-export the 5 Wave 2 form components as named exports (`LoginForm`, `RegisterForm`, `ForgotPasswordForm`, `ResetPasswordForm`, `EmailVerificationView`) with no `export *`. Each form SHALL also be reachable via a dedicated subpath export (`./components/login-form`, etc.) for tree-shaking.

#### Scenario: Wave 2 surface present in root barrel

- **WHEN** the root-barrel test enumerates `Object.keys(import("@suaveplan/react-auth"))`
- **THEN** every Wave 2 form symbol is present alongside the Wave 1 surface

**Verified by:** `src/index.test.ts::"the root barrel exports exactly the documented public surface"`

### Requirement: LoginPage wires LoginForm to the auth context with router redirect

The package SHALL expose a `<LoginPage>` component that renders the Wave 2 `<LoginForm>`, 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** `<LoginPage>` 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** `<LoginPage>` 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 `<LoginForm>` 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 `<RegisterPage>` component that renders the Wave 2 `<RegisterForm>`, 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 `<ForgotPasswordPage>` component that renders the Wave 2 `<ForgotPasswordForm>`, 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 `<ResetPasswordPage>` component that reads `?token` from `useSearchParams`, passes `hasToken={!!token}` to the Wave 2 `<ResetPasswordForm>`, 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** `<ResetPasswordForm>` 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 `<EmailVerificationPage>` component that reads `?token` from `useSearchParams`, calls `useAuth().verifyEmail(token)` once on mount, drives the Wave 2 `<EmailVerificationView>` 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** `<EmailVerificationView status="error">` is rendered AND `useAuth().verifyEmail` is NOT called

#### Scenario: happy-path sets success status

- **WHEN** `verifyEmail` resolves
- **THEN** `<EmailVerificationView status="success">` is rendered

#### Scenario: expired token classifies as expired

- **WHEN** `verifyEmail` rejects with `new Error("token has expired")`
- **THEN** `<EmailVerificationView status="expired">` 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 `<ProfilePage>` (aliased as `Profile` for upstream compatibility) component that renders a three-tab surface (`profile`, `password`, `account`) using `@suaveplan/react-ui` `<Tabs>`, 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<AuthProfilePageStrings>` 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 `<PermissionGate>` 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"`

<!-- markdownlint-enable MD024 -->