# Ship @suaveplan/react-auth-whitelabel — white-label auth React components

**Package**: `@suaveplan/react-auth-whitelabel`
**Status**: PROPOSED
**Type**: new-package

## Why

Genesis needs a tenant-aware, white-label authentication surface that lets a single
build serve many tenants with their own logo, palette, font, and copy. Upstream
(`/mnt/s/web/suaveplan/packages/react/react-auth-whitelabel`) ships three forms
(`LoginForm`, `RegisterForm`, `PasswordResetForm`), two contexts (`AuthProvider`,
`BrandingProvider`), and six hooks; it powers every tenant-branded sign-in flow
in the upstream stack but was never enterprise-graded. We re-author it on top of
the new `@suaveplan/react-ui` runtime theme mutator so branding writes flow
through the canonical token-layer stack instead of poking
`document.documentElement.style` from package code.

## What changes

- ADDED: `LoginForm` — controlled email/password form with optional OAuth provider list, remember-me, forgot-password, and register-link affordances.
- ADDED: `RegisterForm` — controlled register form with optional name field, terms checkbox, OAuth provider list, password confirmation, configurable min length. Split into `register-form-fields.tsx` + `register-form-terms.tsx` sub-components to honour the 300-LOC budget.
- ADDED: `PasswordResetForm` — dual-mode (`request` | `confirm`) reset form with success state. Split into `password-reset-request.tsx` + `password-reset-confirm.tsx` + `password-reset-success.tsx` sub-components to honour the 300-LOC budget.
- ADDED: `AuthProvider` — context provider that wires `login` / `loginWithProvider` / `register` / `logout` / `requestPasswordReset` / `resetPassword` to a backend reachable at `config.authUrl`. Accepts an injectable `fetch: FetchLike` and an injectable `navigate(url)` seam.
- ADDED: `BrandingProvider` — context provider that fetches per-tenant branding (or accepts static branding) and dispatches CSS custom properties through `useThemeMutator().setExtensionTokens(...)`. Wraps `document.title`, `<link rel="icon">`, and `<style id="tenant-custom-css">` for non-token surfaces.
- ADDED: Hooks `useAuth`, `useBranding`, `useIsAuthenticated`, `useLogo`, `useTenantBranding`, `useUser`.
- ADDED: Types `AuthConfig`, `AuthContextValue`, `AuthProvider as AuthProviderConfig`, `AuthUser`, `BrandingContextValue`, `BrandingProviderProps`, `RegisterData`, `TenantBranding`.
- ADDED: Zod schema `TenantBrandingSchema` so tenant payloads are validated at the branding context boundary.
- ADDED: Error registry `REACT_AUTH_WL` with codes `BRANDING_FETCH_FAILED`, `BRANDING_INVALID_PAYLOAD`, `AUTH_NETWORK_FAILED`, `AUTH_REJECTED`, `MISSING_RESET_TOKEN`, `PROVIDER_OUTSIDE_TREE` (each thrown by ≥1 production path).
- ADDED: Three `.stories.tsx` (default + playground + variants) per form so Storybook + downstream Playwright `e2e/*.spec.ts` keep the parity surface.

## Out of scope

- MFA / TOTP / passkey forms (`MfaChallengeForm`, `PasskeyRegistrationForm`, `PasskeyAuthenticationForm`) — enterprise plan §4 lists these as feature-rich enhancements, not parity baseline. Deferred to a follow-up change once `@suaveplan/webauthn` and `@suaveplan/otp` are migrated to genesis.
- Magic-link / SMS OTP login flows — depend on `@suaveplan/security-codes`, `@suaveplan/emailer`, `@suaveplan/sms`. Out of dep order.
- Audit-log integration (`@suaveplan/audit-logging` event emission) — depends on packages not yet in genesis.
- Password-strength meter via `@suaveplan/password-formats` — dep not yet in genesis.
- Rate-limited submission via `@suaveplan/rate-limiter` — dep not yet in genesis.
- Better-Auth first-class adapter (`createBetterAuthProvider(client)`) — overlaps with `@suaveplan/react-auth` Wave 1 (different concurrent session); revisit once that ships.
- axe-core CI gate across stories — depends on `@suaveplan/storybook-test-utils` not yet migrated.
- Bundle-size snapshot — repo-wide tooling not yet wired.

## Source mapping

This change derives from `../suaveplan/enterprise/react-auth-whitelabel.md` and the
companion source tree at `../suaveplan/packages/react/react-auth-whitelabel/src/`.

| Requirement | Source lines | Notes |
|---|---|---|
| Three form components with parity feature set | L11-L13, L22-L27 | Verbatim baseline; sub-components added in genesis to honour 300-LOC budget. |
| Two context providers (AuthProvider, BrandingProvider) | L11, L25-L26 | Verbatim. |
| Six hooks (useAuth, useBranding, useIsAuthenticated, useLogo, useTenantBranding, useUser) | L11, L27 | Verbatim. |
| Public types: AuthConfig, AuthContextValue, AuthProvider (AuthProviderConfig), AuthUser, BrandingContextValue, BrandingProviderProps, RegisterData, TenantBranding | L28-L29 | Verbatim. |
| Replace `window.location.href` seam with injectable `navigate(url)` on `AuthConfig` | L57-L58, L67, L102 | Enterprise §3 gap, enterprise §6 acceptance criterion. |
| Inject `fetch: FetchLike` on `AuthConfig` and `BrandingProvider` | enterprise §3, §6 | Required to keep auth + branding contexts testable without `vi.mock` (CLAUDE.md rule 2). |
| Zod schema for `TenantBranding` (`TenantBrandingSchema`) | L60, L104 | Enterprise §3 + §6 acceptance criterion. |
| i18n every user-visible string via `t(...)` | L88 ("Cross-cutting") | Verbatim. Migrate from `@suaveplan/react-translate` to `@suaveplan/react-i18n`; rewrite `t("k", "default")` → `t("k", { defaultValue: "default" })`. |
| Error hierarchy via `@suaveplan/error` | L86 ("Cross-cutting") | Verbatim. Use `defineCodes("REACT_AUTH_WL", [...])` + `ReactAuthWhitelabelError extends SuaveplanError`. |
| 100% test coverage; 250/300/500 file budget; `sideEffects: false`; Biome clean; TypeScript strict; no `any`/`ts-ignore`; co-located `.md` per export | L80-L88 | Cross-cutting. |
| Branding writes flow through canonical theme-token surface | enterprise §4 ("Theme system") | Re-implemented in genesis via the new `useThemeMutator()` from `@suaveplan/react-ui` (commit `ce7c179c1`); BrandingProvider no longer pokes `document.documentElement.style` directly. |
| Three Playwright E2E specs for parity | L7 | Ported to genesis `e2e/` under `### Excluded` if the upstream Storybook glue isn't available; documented decision below. |

### Requirements with no source line

| Requirement | Justification |
|---|---|
| Error code `BRANDING_INVALID_PAYLOAD` thrown via Zod failure | Required to fulfil rule "every error code thrown by ≥1 production path" once we add the Zod schema. |
| Error code `PROVIDER_OUTSIDE_TREE` thrown by hooks called outside their provider | Replaces the upstream's plain `throw new Error("...")` with a typed code so consumers can branch on `.code` (cross-cutting policy). |
| Split `register-form.tsx` + `password-reset-form.tsx` into sub-components | CLAUDE.md 300-LOC hard budget, not an upstream requirement. |
| Test-runner imports only from `@suaveplan/testing/runner` | CLAUDE.md rule 11; not in upstream. |

## Decisions

Four clarifications were locked in before authoring:

1. **Theming** — Compose under `<ThemeProvider>` via the new `useThemeMutator()` returned by `@suaveplan/react-ui`. `BrandingProvider` calls `setExtensionTokens({ "--brand-primary": branding.primaryColor, ... })` on every payload change. Document title swap, favicon swap, and custom-CSS `<style>` injection STAY as direct DOM writes (they are not CSS variables). No `document.documentElement.style.setProperty("--brand-*", ...)` calls in package code.
2. **`useTranslation` rewrite** — Every upstream `t("k", "default")` call site is rewritten to `t("k", { defaultValue: "default" })` to match the genesis `@suaveplan/react-i18n` signature.
3. **`react-hook-form` dropped** — The upstream forms are already `useState`-based; no Hook Form usage exists in `*.tsx`. We do not introduce it.
4. **File-size budget** — `register-form.tsx` (360 LOC upstream) and `password-reset-form.tsx` (388 LOC upstream) are split into named sub-components so every source file stays ≤300 LOC hard.

## Verification approach

Every requirement in the spec delta carries a `**Verified by:**` line naming concrete
`it(...)` titles in the test files below. Coverage is enforced at 100/100/100/100 via
`provider: 'istanbul'`.

- `src/components/login-form/login-form.test.tsx` — LoginForm rendering, submission, OAuth click, forgot/register link routing.
- `src/components/register-form/register-form.test.tsx` — RegisterForm validation, password mismatch, terms enforcement, name-required path, success/error callbacks.
- `src/components/register-form/register-form-fields.test.tsx` — sub-component field rendering + required-indicator.
- `src/components/register-form/register-form-terms.test.tsx` — terms checkbox + links rendering.
- `src/components/password-reset-form/password-reset-form.test.tsx` — mode switching, missing-token guard, success state, validation.
- `src/components/password-reset-form/password-reset-request.test.tsx` — request mode submit + back-to-login link.
- `src/components/password-reset-form/password-reset-confirm.test.tsx` — confirm mode submit + min-length + mismatch.
- `src/components/password-reset-form/password-reset-success.test.tsx` — success copy + back-to-login.
- `src/context/auth-context.test.tsx` — login / register / logout / requestPasswordReset / resetPassword / loginWithProvider via injectable `fetch` + `navigate`; PROVIDER_OUTSIDE_TREE branch.
- `src/context/branding-context.test.tsx` — static branding + fetched branding + `--brand-*` extension tokens propagated via `useThemeMutator`; cleanup on unmount; Zod failure → BRANDING_INVALID_PAYLOAD; network error → BRANDING_FETCH_FAILED.
- `src/types/branding.schema.test.ts` — Zod schema accept/reject cases.
- `src/errors/error-codes.test.ts` — every `REACT_AUTH_WL.*` code thrown by ≥1 production path (regex grep).
- `e2e/login-form.spec.ts` — ported subset of upstream login-form Playwright specs (parity smoke).

## Migration impact

None — additive only. No genesis consumer depends on this package yet.