# 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={}` - **THEN** `` 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: }` **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..` 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 `` 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"`