# OpenSpec Change: enterprise-react-auth-whitelabel

- **Change ID**: enterprise-react-auth-whitelabel
- **Package**: `@suaveplan/react-auth-whitelabel`
- **Category**: react
- **Target path**: `react/auth/react-auth-whitelabel`
- **Status**: PROPOSED
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-auth-whitelabel.md`

---

## Summary

Deliver `@suaveplan/react-auth-whitelabel` on genesis from scratch at enterprise quality. White-label authentication React components with tenant branding: `LoginForm`, `RegisterForm`, `PasswordResetForm`, `AuthProvider`, `BrandingProvider`, and six hooks. Genesis adds an interception hook for SSO flows (replacing direct `window.location.href` assignment), improves `BrandingContext` README documentation, and reaches 100% test coverage with real `@suaveplan/react-translate`.

---

## Current-state audit (genesis)

Package does not exist on genesis — fresh build.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/error` (`workspace:^`) | `AuthWhitelabelError` |
| `@suaveplan/react-translate` (`workspace:^`) | i18n |
| `zod` (`catalog:forms`) | Form schemas + branding schemas |

External: `@hookform/resolvers catalog:forms`, `react-hook-form catalog:forms`, `clsx catalog:ui`, `tailwind-merge catalog:ui`, `tslib catalog:build`. React 18 peer.

---

## Preserved public API surface

```ts
// Components
LoginForm, RegisterForm, PasswordResetForm
// Context
AuthProvider (+ AuthProviderProps), BrandingProvider
// Hooks
useAuth, useBranding, useIsAuthenticated, useLogo, useTenantBranding, useUser
// Types
AuthConfig, AuthContextValue, AuthUser, BrandingContextValue, BrandingProviderProps,
RegisterData, TenantBranding, LoginFormProps, LoginFormValues,
PasswordResetConfirmValues, PasswordResetFormProps, PasswordResetMode,
PasswordResetRequestValues, RegisterFormProps, RegisterFormValues,
AuthProviderConfig
```

---

## New additions for genesis

1. **SSO navigation hook** — `AuthProvider` accepts optional `onNavigate(url: string): void`; `loginWithProvider` calls this instead of `window.location.href` directly. Enables full testability.
2. **`AuthWhitelabelError`** — codes: `AUTH_WL_CONTEXT_MISSING`, `AUTH_WL_INVALID_BRANDING`.
3. **`TenantBranding` Zod schema** — documents the full shape (colors, fonts, logoUrl) with validation.
4. **Stories** — all three forms with default branding, custom branding, loading, error states.
5. **E2E** — `e2e/login-form.spec.ts`, `register-form.spec.ts`, `password-reset-form.spec.ts`.

---

## File layout

```text
react/auth/react-auth-whitelabel/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    components/
      login-form/ register-form/ password-reset-form/
    context/
      auth-context/ branding-context/
    hooks/ (6 hooks)
    types/
      branding.types.ts
  e2e/
    login-form.spec.ts
    register-form.spec.ts
    password-reset-form.spec.ts
```