@massimo.mazzoleni/cognito-max 1.0.0

package/README.md

@@ -0,0 +1,2410 @@
+# cognito-max
+
+AWS Cognito authentication library for React. Handles SRP login, MFA (TOTP + SMS), session auto-refresh, password flows, and user attribute management — all with full TypeScript types.
+
+```bash
+npm install cognito-max
+```
+
+**Peer dependencies**: `react >= 18` (optional — the core works without React)
+
+---
+
+## Table of contents
+
+- [Prerequisites](#prerequisites)
+- [Quick start](#quick-start)
+- [Entry points](#entry-points)
+- [Configuration](#configuration)
+- [React integration](#react-integration)
+  - [AuthProvider](#authprovider)
+  - [useAuth](#useauth)
+  - [useSession](#usesession)
+  - [useUser](#useuser)
+  - [useMfa](#usemfa)
+  - [ProtectedRoute](#protectedroute)
+  - [useRequireAuth](#userequireauth)
+- [Authentication flows](#authentication-flows)
+  - [Sign in](#sign-in)
+  - [MFA challenge (TOTP / SMS)](#mfa-challenge-totp--sms)
+  - [Forced password change](#forced-password-change)
+  - [TOTP setup during login](#totp-setup-during-login)
+  - [Forgot password](#forgot-password)
+  - [Sign up](#sign-up)
+- [UI layer](#ui-layer)
+  - [Ready-made components](#ready-made-components)
+  - [Headless hooks](#headless-hooks)
+- [Core API](#core-api)
+- [Storage adapters](#storage-adapters)
+- [Events](#events)
+- [Error handling](#error-handling)
+- [TypeScript reference](#typescript-reference)
+
+---
+
+## Prerequisites
+
+Your Cognito User Pool App Client must have these **explicit auth flows** enabled:
+
+| Flow | Why |
+|------|-----|
+| `ALLOW_USER_SRP_AUTH` | SRP login (the default flow used by this library) |
+| `ALLOW_REFRESH_TOKEN_AUTH` | Automatic token refresh |
+| `ALLOW_USER_PASSWORD_AUTH` | Optional — only if you use `USER_PASSWORD_AUTH` directly |
+
+Enable them in the AWS Console → User Pools → App clients → Edit, or with the CLI:
+
+```bash
+aws cognito-idp update-user-pool-client \
+  --user-pool-id YOUR_POOL_ID \
+  --client-id YOUR_CLIENT_ID \
+  --region YOUR_REGION \
+  --explicit-auth-flows \
+    ALLOW_USER_SRP_AUTH \
+    ALLOW_REFRESH_TOKEN_AUTH
+```
+
+---
+
+## Quick start
+
+```tsx
+import { AuthProvider, useAuth } from 'cognito-max/react'
+
+const config = {
+  userPoolId: 'eu-west-1_xxxxxxxxx',
+  clientId: 'xxxxxxxxxxxxxxxxxxxxxxxxxx',
+  region: 'eu-west-1',
+}
+
+function App() {
+  return (
+    <AuthProvider config={config}>
+      <LoginPage />
+    </AuthProvider>
+  )
+}
+
+function LoginPage() {
+  const { signIn, isAuthenticated, user } = useAuth()
+
+  if (isAuthenticated) return <p>Welcome, {user?.email}</p>
+
+  return (
+    <button onClick={() => signIn('user@example.com', 'password')}>
+      Sign in
+    </button>
+  )
+}
+```
+
+---
+
+## Entry points
+
+The package is split into four tree-shakeable entry points so you only bundle what you use:
+
+| Import | Contents |
+|--------|----------|
+| `cognito-max` | Re-exports everything (convenience) |
+| `cognito-max/core` | `CognitoAuthClient`, types, errors, storage adapters |
+| `cognito-max/react` | `AuthProvider`, all hooks, `ProtectedRoute` |
+| `cognito-max/ui` | Headless hooks + ready-made HTML components |
+
+```ts
+// Only import the React layer
+import { AuthProvider, useAuth } from 'cognito-max/react'
+
+// Only use the vanilla client (no React)
+import { CognitoAuthClient } from 'cognito-max/core'
+```
+
+---
+
+## Configuration
+
+```ts
+import type { AuthConfig } from 'cognito-max/core'
+
+const config: AuthConfig = {
+  // Required
+  userPoolId: 'eu-west-1_xxxxxxxxx',
+  clientId:   'xxxxxxxxxxxxxxxxxxxxxxxxxx',
+  region:     'eu-west-1',
+
+  // Optional
+  autoRefresh:          true,   // Renew token before expiry. Default: true
+  refreshMarginSeconds: 300,    // Refresh 5 min before expiry. Default: 300
+  totpIssuer:           'MyApp', // Label in authenticator apps. Default: clientId
+  storage:              new LocalStorageAdapter(), // Default: AutoStorageAdapter
+}
+```
+
+### `AuthConfig` fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `userPoolId` | `string` | required | Cognito User Pool ID |
+| `clientId` | `string` | required | App Client ID |
+| `region` | `string` | required | AWS region (e.g. `eu-west-1`) |
+| `autoRefresh` | `boolean` | `true` | Auto-renew the session before expiry |
+| `refreshMarginSeconds` | `number` | `300` | How many seconds before expiry to trigger refresh |
+| `totpIssuer` | `string` | `clientId` | Label shown in Google Authenticator / Authy |
+| `storage` | `StorageAdapter` | `AutoStorageAdapter` | Where to persist tokens |
+
+---
+
+## React integration
+
+### AuthProvider
+
+Wrap your application (or the auth-protected section) with `AuthProvider`. It initializes the Cognito client, restores any existing session from storage, and provides the auth context to all child components.
+
+```tsx
+import { AuthProvider } from 'cognito-max/react'
+
+function App() {
+  return (
+    <AuthProvider config={config}>
+      <Router />
+    </AuthProvider>
+  )
+}
+```
+
+`AuthProvider` takes a single `config` prop (an `AuthConfig` object). The config is read once at mount; changes after mount are ignored.
+
+---
+
+### useAuth
+
+The main hook. Returns auth state + all authentication actions.
+
+```ts
+import { useAuth } from 'cognito-max/react'
+
+const {
+  // State
+  user,            // AuthUser | null
+  state,           // AuthState
+  isLoading,       // boolean — true during session initialization
+  isAuthenticated, // boolean
+
+  // Actions (all return Promises)
+  signIn,
+  signOut,
+  signUp,
+  confirmSignUp,
+  resendConfirmationCode,
+  forgotPassword,
+  confirmForgotPassword,
+  changePassword,
+  respondToMfaChallenge,
+  respondToNewPasswordChallenge,
+  setupTotpChallenge,
+  verifyTotpChallenge,
+
+  // Raw client for advanced use
+  client,
+} = useAuth()
+```
+
+#### `signIn(email, password)`
+
+Returns a `SignInResult` discriminated union:
+
+```ts
+const result = await signIn('user@example.com', 'password')
+
+switch (result.status) {
+  case 'SUCCESS':
+    // result.user: AuthUser
+    // result.session: AuthSession
+    break
+
+  case 'MFA_REQUIRED':
+    // result.mfaType: 'TOTP' | 'SMS'
+    // result.challengeSession: string  ← pass to respondToMfaChallenge
+    break
+
+  case 'NEW_PASSWORD_REQUIRED':
+    // result.requiredAttributes: string[]
+    // result.challengeSession: string  ← pass to respondToNewPasswordChallenge
+    break
+
+  case 'MFA_SETUP_REQUIRED':
+    // result.challengeSession: string  ← pass to setupTotpChallenge / verifyTotpChallenge
+    break
+
+  case 'CONFIRM_SIGNUP':
+    // Account not yet confirmed — prompt for email verification code
+    break
+}
+```
+
+#### `signOut(global?)`
+
+```ts
+await signOut()          // Local sign-out (clears tokens from storage)
+await signOut(true)      // Global sign-out (invalidates all sessions on Cognito)
+```
+
+#### `changePassword(currentPassword, newPassword)`
+
+```ts
+await changePassword('OldPass123!', 'NewPass456!')
+```
+
+---
+
+### useSession
+
+Returns the current session tokens and expiry information.
+
+```ts
+import { useSession } from 'cognito-max/react'
+
+const {
+  accessToken,    // string | null
+  idToken,        // string | null
+  refreshToken,   // string | null
+  expiresAt,      // Date | null
+  isExpired,      // boolean
+  isAuthenticated,// boolean
+  refresh,        // () => Promise<AuthSession> — force token refresh
+} = useSession()
+```
+
+Use `accessToken` or `idToken` as the `Authorization: Bearer` header in API calls.
+
+```ts
+// Example with fetch
+const response = await fetch('/api/data', {
+  headers: { Authorization: `Bearer ${accessToken}` }
+})
+```
+
+---
+
+### useUser
+
+Read and update the current user's Cognito profile.
+
+```ts
+import { useUser } from 'cognito-max/react'
+
+const {
+  user,                // AuthUser | null
+  attributes,          // Record<string, string> — all Cognito attributes
+  groups,              // string[] — Cognito groups the user belongs to
+
+  update,              // (attrs: Record<string, string>) => Promise<void>
+  verifyAttribute,     // (attr: 'email' | 'phone_number', code: string) => Promise<void>
+  sendVerificationCode,// (attr: 'email' | 'phone_number') => Promise<void>
+  refreshAttributes,   // () => Promise<Record<string, string>>
+  deleteAccount,       // () => Promise<void>
+} = useUser()
+```
+
+```ts
+// Update the user's display name
+await update({ name: 'Mario Rossi' })
+
+// Trigger email re-verification
+await sendVerificationCode('email')
+// User receives code by email, then:
+await verifyAttribute('email', '123456')
+```
+
+---
+
+### useMfa
+
+Manage TOTP and SMS second-factor settings for an already-authenticated user.
+
+```ts
+import { useMfa } from 'cognito-max/react'
+
+const {
+  setup,        // () => Promise<MfaSetupResult> — associate TOTP device
+  verifySetup,  // (code: string) => Promise<void> — confirm TOTP device
+  getPreference,// () => Promise<MfaPreference>
+  setPreference,// (type: 'TOTP' | 'SMS') => Promise<void>
+  disable,      // () => Promise<void>
+} = useMfa()
+```
+
+```ts
+// Set up TOTP for the first time
+const { secretCode, qrCodeUri } = await setup()
+// Show the QR code (qrCodeUri) to the user — they scan it with their authenticator app
+// Then ask for the 6-digit code to confirm:
+await verifySetup('123456')
+
+// Switch from TOTP to SMS
+await setPreference('SMS')
+
+// Read current MFA state
+const pref = await getPreference()
+// pref.totp → boolean, pref.sms → boolean, pref.preferred → 'TOTP' | 'SMS' | null
+```
+
+---
+
+### ProtectedRoute
+
+A React component that renders children only when the user is authenticated. Optionally enforces Cognito group membership.
+
+```tsx
+import { ProtectedRoute } from 'cognito-max/react'
+import { Navigate } from 'react-router-dom'
+
+// Basic protection
+<ProtectedRoute fallback={<Navigate to="/login" replace />}>
+  <Dashboard />
+</ProtectedRoute>
+
+// Group-based access control
+<ProtectedRoute
+  requiredGroups={['admin', 'superuser']}
+  fallback={<Navigate to="/unauthorized" replace />}
+  loading={<Spinner />}
+>
+  <AdminPanel />
+</ProtectedRoute>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | required | Rendered when auth passes |
+| `fallback` | `ReactNode` | `null` | Rendered when not authenticated / no group access |
+| `loading` | `ReactNode` | `null` | Rendered while auth state is initializing |
+| `requiredGroups` | `string[]` | — | User must belong to at least one of these Cognito groups |
+
+---
+
+### useRequireAuth
+
+Imperative alternative to `ProtectedRoute` for redirect logic inside components.
+
+```ts
+import { useRequireAuth } from 'cognito-max/react'
+import { useNavigate } from 'react-router-dom'
+
+function AdminPage() {
+  const navigate = useNavigate()
+  const { isAllowed, isLoading } = useRequireAuth({ requiredGroups: ['admin'] })
+
+  useEffect(() => {
+    if (!isLoading && !isAllowed) navigate('/login')
+  }, [isLoading, isAllowed])
+
+  if (isLoading) return <Spinner />
+  return <AdminContent />
+}
+```
+
+---
+
+## Authentication flows
+
+### Sign in
+
+```tsx
+function LoginForm() {
+  const { signIn } = useAuth()
+  const navigate = useNavigate()
+
+  async function handleSubmit(email: string, password: string) {
+    const result = await signIn(email, password)
+
+    if (result.status === 'SUCCESS') {
+      navigate('/dashboard')
+    } else if (result.status === 'MFA_REQUIRED') {
+      navigate('/mfa', { state: result })
+    } else if (result.status === 'NEW_PASSWORD_REQUIRED') {
+      navigate('/new-password', { state: result })
+    } else if (result.status === 'MFA_SETUP_REQUIRED') {
+      navigate('/mfa-setup', { state: result })
+    }
+  }
+}
+```
+
+---
+
+### MFA challenge (TOTP / SMS)
+
+After `signIn` returns `MFA_REQUIRED`, the user must provide their 6-digit code:
+
+```tsx
+function MfaPage() {
+  const { respondToMfaChallenge } = useAuth()
+  const { challengeSession, mfaType } = useLocation().state
+
+  async function handleCode(code: string) {
+    const result = await respondToMfaChallenge(challengeSession, code, mfaType)
+    if (result.status === 'SUCCESS') navigate('/dashboard')
+  }
+}
+```
+
+---
+
+### Forced password change
+
+After `signIn` returns `NEW_PASSWORD_REQUIRED`:
+
+```tsx
+function NewPasswordPage() {
+  const { respondToNewPasswordChallenge } = useAuth()
+  const { challengeSession, requiredAttributes } = useLocation().state
+
+  async function handleSubmit(newPassword: string) {
+    const result = await respondToNewPasswordChallenge(
+      challengeSession,
+      newPassword,
+      // Pass any required attributes Cognito asks for:
+      { name: 'Mario Rossi' }
+    )
+    if (result.status === 'SUCCESS') navigate('/dashboard')
+  }
+}
+```
+
+---
+
+### TOTP setup during login
+
+When Cognito is configured to require TOTP before the first login (`MFA_SETUP_REQUIRED`), the user must set up their authenticator app as part of the sign-in flow — before a session exists:
+
+```tsx
+function MfaSetupPage() {
+  const { setupTotpChallenge, verifyTotpChallenge } = useAuth()
+  const { challengeSession } = useLocation().state
+  const [qrUri, setQrUri] = useState<string | null>(null)
+
+  useEffect(() => {
+    setupTotpChallenge(challengeSession).then(({ qrCodeUri }) => setQrUri(qrCodeUri))
+  }, [])
+
+  async function handleCode(code: string) {
+    const result = await verifyTotpChallenge(challengeSession, code)
+    if (result.status === 'SUCCESS') navigate('/dashboard')
+  }
+
+  return (
+    <>
+      {qrUri && <img src={`https://api.qrserver.com/v1/create-qr-code/?data=${encodeURIComponent(qrUri)}`} alt="Scan with authenticator" />}
+      <input placeholder="6-digit code" onKeyDown={(e) => e.key === 'Enter' && handleCode(e.currentTarget.value)} />
+    </>
+  )
+}
+```
+
+---
+
+### Forgot password
+
+```tsx
+// Step 1 — request reset code
+const { forgotPassword } = useAuth()
+await forgotPassword('user@example.com')
+// Cognito sends a code to the user's email
+
+// Step 2 — set new password
+const { confirmForgotPassword } = useAuth()
+await confirmForgotPassword('user@example.com', '123456', 'NewPass789!')
+```
+
+---
+
+### Sign up
+
+```tsx
+const { signUp, confirmSignUp, resendConfirmationCode } = useAuth()
+
+// Register
+await signUp('user@example.com', 'Password123!', {
+  name: 'Mario Rossi',
+  // Any additional Cognito attributes
+})
+
+// Confirm email (code sent by Cognito)
+await confirmSignUp('user@example.com', '654321')
+
+// Didn't receive the code?
+await resendConfirmationCode('user@example.com')
+```
+
+---
+
+## UI layer
+
+Import from `cognito-max/ui`.
+
+### Ready-made components
+
+Unstyled HTML components that wire up all the form logic internally. Apply your own CSS classes via the `className` props.
+
+#### SignInForm
+
+Handles the full sign-in flow including MFA and forced password change.
+
+```tsx
+import { SignInForm } from 'cognito-max/ui'
+
+<SignInForm
+  onSuccess={() => navigate('/dashboard')}
+  onForgotPassword={() => navigate('/forgot-password')}
+/>
+```
+
+#### RegisterForm
+
+```tsx
+import { RegisterForm } from 'cognito-max/ui'
+
+<RegisterForm onSuccess={() => navigate('/confirm-email')} />
+```
+
+#### ForgotPasswordForm
+
+Two-step form: email input → code + new password.
+
+```tsx
+import { ForgotPasswordForm } from 'cognito-max/ui'
+
+<ForgotPasswordForm onSuccess={() => navigate('/login')} />
+```
+
+#### ChangePasswordForm
+
+For authenticated users who want to change their password.
+
+```tsx
+import { ChangePasswordForm } from 'cognito-max/ui'
+
+<ChangePasswordForm onSuccess={() => alert('Password changed')} />
+```
+
+#### MfaSetupWizard
+
+Guides the user through TOTP device association: show QR → enter code → confirm.
+
+```tsx
+import { MfaSetupWizard } from 'cognito-max/ui'
+
+<MfaSetupWizard onSuccess={() => navigate('/dashboard')} />
+```
+
+---
+
+### Headless hooks
+
+If the default HTML components don't match your design system, use the headless hooks instead. They handle all state transitions and expose only the data and callbacks your UI needs.
+
+#### useSignInForm
+
+```ts
+import { useSignInForm } from 'cognito-max/ui'
+
+const {
+  step,          // 'credentials' | 'mfa' | 'new_password' | 'mfa_setup'
+  email, setEmail,
+  password, setPassword,
+  mfaCode, setMfaCode,
+  newPassword, setNewPassword,
+  confirmPassword, setConfirmPassword,
+  isLoading,
+  error,         // string | null
+  submitCredentials,   // () => Promise<void>
+  submitMfaCode,       // () => Promise<void>
+  submitNewPassword,   // () => Promise<void>
+} = useSignInForm({ onSuccess: () => navigate('/dashboard') })
+```
+
+#### useRegisterForm
+
+```ts
+import { useRegisterForm } from 'cognito-max/ui'
+
+const {
+  step,        // 'register' | 'confirm'
+  email, setEmail,
+  password, setPassword,
+  code, setCode,
+  isLoading,
+  error,
+  submitRegister,
+  submitConfirmation,
+  resendCode,
+} = useRegisterForm({ onSuccess: () => navigate('/login') })
+```
+
+#### useForgotPasswordForm
+
+```ts
+import { useForgotPasswordForm } from 'cognito-max/ui'
+
+const {
+  step,       // 'request' | 'reset'
+  email, setEmail,
+  code, setCode,
+  newPassword, setNewPassword,
+  isLoading,
+  error,
+  submitEmail,
+  submitReset,
+} = useForgotPasswordForm({ onSuccess: () => navigate('/login') })
+```
+
+#### useChangePasswordForm
+
+```ts
+import { useChangePasswordForm } from 'cognito-max/ui'
+
+const {
+  currentPassword, setCurrentPassword,
+  newPassword, setNewPassword,
+  confirmPassword, setConfirmPassword,
+  isLoading,
+  error,
+  submit,
+} = useChangePasswordForm({ onSuccess: () => alert('Done') })
+```
+
+#### useMfaSetup
+
+```ts
+import { useMfaSetup } from 'cognito-max/ui'
+
+const {
+  step,        // 'scan' | 'verify' | 'done'
+  secretCode,  // string — manual entry fallback
+  qrCodeUri,   // string — otpauth:// URI for QR code
+  code, setCode,
+  isLoading,
+  error,
+  startSetup,  // () => Promise<void> — call on mount or on user action
+  submitCode,  // () => Promise<void>
+} = useMfaSetup({ onSuccess: () => navigate('/dashboard') })
+```
+
+---
+
+## Core API
+
+For use without React, or to extend the client with custom behavior.
+
+```ts
+import { CognitoAuthClient } from 'cognito-max/core'
+
+const client = new CognitoAuthClient({
+  userPoolId: 'eu-west-1_xxxxxxxxx',
+  clientId:   'xxxxxxxxxxxxxxxxxxxxxxxxxx',
+  region:     'eu-west-1',
+})
+```
+
+`CognitoAuthClient` extends `TypedEventEmitter` and exposes all methods available through the React hooks.
+
+### Full method list
+
+| Method | Description |
+|--------|-------------|
+| `signIn(email, password)` | Initiates SRP login |
+| `respondToMfaChallenge(session, code, type)` | Completes SMS or TOTP challenge |
+| `respondToNewPasswordChallenge(session, password, attrs?)` | Completes forced password change |
+| `setupTotpChallenge(session)` | Associates TOTP device during login flow |
+| `verifyTotpChallenge(session, code)` | Verifies TOTP and completes login |
+| `signOut(global?)` | Signs out locally or globally |
+| `signUp(email, password, attrs?)` | Registers a new user |
+| `confirmSignUp(email, code)` | Confirms email after sign-up |
+| `resendConfirmationCode(email)` | Re-sends the confirmation email |
+| `forgotPassword(email)` | Triggers password reset email |
+| `confirmForgotPassword(email, code, newPassword)` | Sets new password with reset code |
+| `changePassword(current, next)` | Changes password for authenticated user |
+| `getSession()` | Returns current `AuthSession` (refreshes if needed) |
+| `getCurrentUser()` | Returns `AuthUser \| null` from stored session |
+| `getUserAttributes()` | Fetches all Cognito attributes |
+| `updateUserAttributes(attrs)` | Updates Cognito attributes |
+| `verifyUserAttribute(attr, code)` | Verifies email or phone with code |
+| `sendAttributeVerificationCode(attr)` | Sends verification code for email/phone |
+| `deleteUser()` | Permanently deletes the account |
+| `setupTotp()` | Associates TOTP for authenticated user |
+| `verifyTotpSetup(code)` | Confirms TOTP device for authenticated user |
+| `getMfaPreference()` | Returns current MFA settings |
+| `setMfaPreference(type)` | Sets preferred MFA type |
+| `disableMfa()` | Disables all MFA factors |
+
+---
+
+## Storage adapters
+
+Controls where Cognito tokens are persisted. Import from `cognito-max/core`.
+
+| Adapter | Persists in | Use case |
+|---------|-------------|----------|
+| `AutoStorageAdapter` | `localStorage` (or in-memory if unavailable) | Default — works in browser and SSR |
+| `LocalStorageAdapter` | `localStorage` | Standard browser |
+| `SessionStorageAdapter` | `sessionStorage` | Token cleared on tab close |
+| `InMemoryStorageAdapter` | JavaScript `Map` | SSR, tests, or when persistence is unwanted |
+
+```ts
+import { InMemoryStorageAdapter } from 'cognito-max/core'
+
+const client = new CognitoAuthClient({
+  // ...
+  storage: new InMemoryStorageAdapter(),
+})
+```
+
+You can also provide a custom adapter by implementing the `StorageAdapter` interface:
+
+```ts
+import type { StorageAdapter } from 'cognito-max/core'
+
+const encryptedStorage: StorageAdapter = {
+  getItem:    (key) => decrypt(localStorage.getItem(key)),
+  setItem:    (key, value) => localStorage.setItem(key, encrypt(value)),
+  removeItem: (key) => localStorage.removeItem(key),
+}
+```
+
+---
+
+## Events
+
+`CognitoAuthClient` emits typed events you can subscribe to from outside React:
+
+```ts
+import { CognitoAuthClient } from 'cognito-max/core'
+
+const client = new CognitoAuthClient(config)
+
+// Subscribe
+const unsub = client.on('signedIn', (user) => {
+  console.log('User signed in:', user.email)
+})
+
+// One-time
+client.once('sessionExpired', () => {
+  window.location.href = '/login'
+})
+
+// Unsubscribe
+unsub()
+```
+
+### Available events
+
+| Event | Payload | Fired when |
+|-------|---------|------------|
+| `signedIn` | `AuthUser` | Login completed successfully |
+| `signedOut` | — | User signed out |
+| `tokenRefreshed` | `AuthSession` | Access token was automatically renewed |
+| `sessionExpired` | — | Token refresh failed — session is no longer valid |
+| `mfaRequired` | `{ mfaType, challengeSession }` | Login requires MFA code |
+| `newPasswordRequired` | `{ requiredAttributes, challengeSession }` | User must set a new password |
+| `userUpdated` | `AuthUser` | User attributes were changed |
+| `stateChanged` | `AuthState` | Auth state machine transitioned |
+
+---
+
+## Error handling
+
+All methods throw `CognitoAuthError` on failure. Import specific error classes to handle them by type:
+
+```ts
+import {
+  CognitoAuthError,
+  NotAuthorizedError,
+  InvalidCodeError,
+  SessionExpiredError,
+} from 'cognito-max/core'
+
+try {
+  await signIn(email, password)
+} catch (error) {
+  if (error instanceof NotAuthorizedError) {
+    setError('Wrong email or password')
+  } else if (error instanceof CognitoAuthError) {
+    // error.code is one of AuthErrorCode
+    // error.message is a human-readable string
+    setError(error.message)
+  }
+}
+```
+
+### Error codes
+
+| Class | `code` | When thrown |
+|-------|--------|-------------|
+| `NotAuthorizedError` | `NOT_AUTHORIZED` | Wrong password or disabled account |
+| `UserNotConfirmedError` | `USER_NOT_CONFIRMED` | Account not email-verified yet |
+| `InvalidCodeError` | `CODE_MISMATCH` / `EXPIRED_CODE` | Wrong or expired verification code |
+| `SessionExpiredError` | `SESSION_EXPIRED` | Session no longer valid |
+| `CognitoAuthError` | various | All other Cognito errors |
+
+All codes (`AuthErrorCode`):
+
+```
+NOT_AUTHORIZED · USER_NOT_FOUND · USER_NOT_CONFIRMED · INVALID_PARAMETER
+INVALID_PASSWORD · CODE_MISMATCH · EXPIRED_CODE · CODE_DELIVERY_FAILURE
+LIMIT_EXCEEDED · TOO_MANY_REQUESTS · TOO_MANY_FAILED_ATTEMPTS
+PASSWORD_RESET_REQUIRED · MFA_METHOD_NOT_FOUND · SOFTWARE_TOKEN_MFA_NOT_FOUND
+SESSION_EXPIRED · NETWORK_ERROR · UNKNOWN
+```
+
+---
+
+## TypeScript reference
+
+### `AuthConfig`
+
+```ts
+interface AuthConfig {
+  userPoolId:           string
+  clientId:             string
+  region:               string
+  storage?:             StorageAdapter
+  autoRefresh?:         boolean
+  refreshMarginSeconds?: number
+  totpIssuer?:          string
+}
+```
+
+### `AuthState`
+
+```ts
+type AuthState =
+  | 'idle'                  // Not yet initialized
+  | 'loading'               // Operation in progress
+  | 'authenticated'         // Valid session
+  | 'unauthenticated'       // No session
+  | 'mfa_required'          // Waiting for MFA code
+  | 'new_password_required' // Waiting for new password
+  | 'confirm_signup'        // Waiting for email confirmation
+```
+
+### `SignInResult`
+
+```ts
+type SignInResult =
+  | { status: 'SUCCESS';              user: AuthUser; session: AuthSession }
+  | { status: 'MFA_REQUIRED';         mfaType: MfaType; challengeSession: string }
+  | { status: 'NEW_PASSWORD_REQUIRED'; requiredAttributes: string[]; challengeSession: string }
+  | { status: 'MFA_SETUP_REQUIRED';   challengeSession: string }
+  | { status: 'CONFIRM_SIGNUP' }
+```
+
+### `AuthUser`
+
+```ts
+interface AuthUser {
+  sub:            string
+  username:       string
+  email:          string
+  emailVerified:  boolean
+  groups:         string[]
+  attributes:     Record<string, string>
+}
+```
+
+### `AuthSession`
+
+```ts
+interface AuthSession {
+  accessToken:  string
+  idToken:      string
+  refreshToken: string
+  expiresAt:    Date
+  isValid():    boolean
+}
+```
+
+### `MfaSetupResult`
+
+```ts
+interface MfaSetupResult {
+  secretCode:  string   // For manual entry in the authenticator app
+  qrCodeUri:   string   // otpauth://totp/<issuer>:<email>?secret=…
+}
+```
+
+### `MfaPreference`
+
+```ts
+interface MfaPreference {
+  enabled:   boolean
+  preferred: 'TOTP' | 'SMS' | null
+  totp:      boolean
+  sms:       boolean
+}
+```
+
+---
+
+## Integrazione con AWS Cloudscape
+
+Questa sezione mostra pattern completi per integrare cognito-max in un'applicazione che usa [AWS Cloudscape Design System](https://cloudscape.design/). Gli esempi sono TypeScript/TSX pronti all'uso — non pseudocodice.
+
+### Setup
+
+Installa le dipendenze:
+
+```bash
+npm install cognito-max @cloudscape-design/components @cloudscape-design/global-styles react-router-dom
+# Opzionale — per il QR code nella pagina di setup MFA
+npm install react-qr-code
+```
+
+Struttura minima di `App.tsx`:
+
+```tsx
+// src/App.tsx
+import '@cloudscape-design/global-styles/index.css'
+import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom'
+import { AuthProvider } from 'cognito-max/react'
+import type { AuthConfig } from 'cognito-max'
+import LoginPage from './pages/login'
+import MfaVerifyPage from './pages/mfa-verify'
+import MfaSetupPage from './pages/mfa-setup'
+import NewPasswordPage from './pages/new-password'
+import ForgotPasswordPage from './pages/forgot-password'
+import ResetPasswordPage from './pages/reset-password'
+import RegisterPage from './pages/register'
+import ConfirmSignupPage from './pages/confirm-signup'
+import ChangePasswordPage from './pages/change-password'
+import ChangeMfaPage from './pages/change-mfa'
+import Dashboard from './pages/dashboard'
+import ProtectedRoute from './components/ProtectedRoute'
+import CognitoTokenSync from './components/CognitoTokenSync'
+
+const cognitoConfig: AuthConfig = {
+  userPoolId: import.meta.env.VITE_USER_POOL_ID,
+  clientId: import.meta.env.VITE_CLIENT_ID,
+  region: import.meta.env.VITE_REGION,
+  totpIssuer: 'MyApp',
+}
+
+export default function App() {
+  return (
+    <AuthProvider config={cognitoConfig}>
+      <CognitoTokenSync>
+        <BrowserRouter>
+          <Routes>
+            <Route path="/login"           element={<LoginPage />} />
+            <Route path="/mfa-verify"      element={<MfaVerifyPage />} />
+            <Route path="/mfa-setup"       element={<MfaSetupPage />} />
+            <Route path="/new-password"    element={<NewPasswordPage />} />
+            <Route path="/forgot-password" element={<ForgotPasswordPage />} />
+            <Route path="/reset-password"  element={<ResetPasswordPage />} />
+            <Route path="/register"        element={<RegisterPage />} />
+            <Route path="/confirm-signup"  element={<ConfirmSignupPage />} />
+            <Route
+              path="/change-password"
+              element={<ProtectedRoute><ChangePasswordPage /></ProtectedRoute>}
+            />
+            <Route
+              path="/change-mfa"
+              element={<ProtectedRoute><ChangeMfaPage /></ProtectedRoute>}
+            />
+            <Route
+              path="/"
+              element={<ProtectedRoute><Dashboard /></ProtectedRoute>}
+            />
+            <Route path="*" element={<Navigate to="/" />} />
+          </Routes>
+        </BrowserRouter>
+      </CognitoTokenSync>
+    </AuthProvider>
+  )
+}
+```
+
+---
+
+### Login completo
+
+Gestisce tutti i possibili esiti di `signIn`: accesso riuscito, MFA, nuova password obbligatoria, setup MFA, account non confermato.
+
+```tsx
+// src/pages/login.tsx
+import { useState } from 'react'
+import { useNavigate } from 'react-router-dom'
+import { useAuth } from 'cognito-max/react'
+import Container from '@cloudscape-design/components/container'
+import Header from '@cloudscape-design/components/header'
+import FormField from '@cloudscape-design/components/form-field'
+import Input from '@cloudscape-design/components/input'
+import Button from '@cloudscape-design/components/button'
+import Alert from '@cloudscape-design/components/alert'
+import SpaceBetween from '@cloudscape-design/components/space-between'
+import Checkbox from '@cloudscape-design/components/checkbox'
+
+export default function LoginPage() {
+  const navigate = useNavigate()
+  const { signIn } = useAuth()
+
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [showPassword, setShowPassword] = useState(false)
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState('')
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setError('')
+    setIsLoading(true)
+    try {
+      const result = await signIn(email, password)
+
+      switch (result.status) {
+        case 'SUCCESS':
+          navigate('/')
+          break
+        case 'MFA_REQUIRED':
+          navigate('/mfa-verify', {
+            state: {
+              challengeSession: result.challengeSession,
+              mfaType: result.mfaType,
+              email,
+            },
+          })
+          break
+        case 'NEW_PASSWORD_REQUIRED':
+          navigate('/new-password', {
+            state: {
+              challengeSession: result.challengeSession,
+              requiredAttributes: result.requiredAttributes,
+              email,
+            },
+          })
+          break
+        case 'MFA_SETUP_REQUIRED':
+          navigate('/mfa-setup', {
+            state: {
+              challengeSession: result.challengeSession,
+              email,
+            },
+          })
+          break
+        case 'CONFIRM_SIGNUP':
+          setError('Account non confermato. Controlla la tua email.')
+          break
+      }
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : 'Errore durante il login')
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  return (
+    <Container header={<Header variant="h1">Accedi al tuo account</Header>}>
+      <form onSubmit={handleSubmit}>
+        <SpaceBetween size="m">
+          {error && (
+            <Alert type="error" dismissible onDismiss={() => setError('')}>
+              {error}
+            </Alert>
+          )}
+
+          <FormField label="Email">
+            <Input
+              type="email"
+              value={email}
+              onChange={({ detail }) => setEmail(detail.value)}
+              autoFocus
+              disabled={isLoading}
+            />
+          </FormField>
+
+          <FormField label="Password">
+            <Input
+              type={showPassword ? 'text' : 'password'}
+              value={password}
+              onChange={({ detail }) => setPassword(detail.value)}
+              disabled={isLoading}
+            />
+          </FormField>
+
+          <Checkbox
+            checked={showPassword}
+            onChange={({ detail }) => setShowPassword(detail.checked)}
+          >
+            Mostra password
+          </Checkbox>
+
+          <Button variant="primary" formAction="submit" loading={isLoading}>
+            Accedi
+          </Button>
+
+          <Button variant="link" onClick={() => navigate('/forgot-password')} disabled={isLoading}>
+            Password dimenticata?
+          </Button>
+
+          <Button variant="link" onClick={() => navigate('/register')} disabled={isLoading}>
+            Non hai un account? Registrati
+          </Button>
+        </SpaceBetween>
+      </form>
+    </Container>
+  )
+}
+```
+
+**Pagina MFA verify** (`/mfa-verify`) — riceve `challengeSession` e `mfaType` dallo state di navigazione:
+
+```tsx
+// src/pages/mfa-verify.tsx
+import { useState } from 'react'
+import { useLocation, useNavigate } from 'react-router-dom'
+import { useAuth } from 'cognito-max/react'
+import type { MfaType } from 'cognito-max'
+import Container from '@cloudscape-design/components/container'
+import Header from '@cloudscape-design/components/header'
+import FormField from '@cloudscape-design/components/form-field'
+import Input from '@cloudscape-design/components/input'
+import Button from '@cloudscape-design/components/button'
+import Alert from '@cloudscape-design/components/alert'
+import SpaceBetween from '@cloudscape-design/components/space-between'
+
+export default function MfaVerifyPage() {
+  const navigate = useNavigate()
+  const location = useLocation()
+  const { respondToMfaChallenge } = useAuth()
+
+  const { challengeSession, mfaType } = (location.state ?? {}) as {
+    challengeSession: string
+    mfaType: MfaType
+  }
+
+  const [code, setCode] = useState('')
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState('')
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    if (!challengeSession) {
+      setError('Sessione non valida. Rieffettua il login.')
+      return
+    }
+    setError('')
+    setIsLoading(true)
+    try {
+      const result = await respondToMfaChallenge(challengeSession, code, mfaType ?? 'TOTP')
+      if (result.status === 'SUCCESS') {
+        navigate('/')
+      }
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : 'Codice MFA non valido')
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  return (
+    <Container header={<Header variant="h1">Verifica codice MFA</Header>}>
+      <form onSubmit={handleSubmit}>
+        <SpaceBetween size="m">
+          <p>
+            Inserisci il codice{' '}
+            {mfaType === 'TOTP' ? "dall'app authenticator" : 'ricevuto via SMS'}.
+          </p>
+
+          {error && (
+            <Alert type="error" dismissible onDismiss={() => setError('')}>
+              {error}
+            </Alert>
+          )}
+
+          <FormField label="Codice MFA" errorText={error || undefined}>
+            <Input
+              type="text"
+              inputMode="numeric"
+              value={code}
+              onChange={({ detail }) => setCode(detail.value)}
+              autoFocus
+              disabled={isLoading}
+            />
+          </FormField>
+
+          <Button variant="primary" formAction="submit" loading={isLoading}>
+            Verifica
+          </Button>
+
+          <Button variant="link" onClick={() => navigate('/login')} disabled={isLoading}>
+            Torna al login
+          </Button>
+        </SpaceBetween>
+      </form>
+    </Container>
+  )
+}
+```
+
+**Pagina nuova password obbligatoria** (`/new-password`):
+
+```tsx
+// src/pages/new-password.tsx
+import { useState } from 'react'
+import { useLocation, useNavigate } from 'react-router-dom'
+import { useAuth } from 'cognito-max/react'
+import Container from '@cloudscape-design/components/container'
+import Header from '@cloudscape-design/components/header'
+import FormField from '@cloudscape-design/components/form-field'
+import Input from '@cloudscape-design/components/input'
+import Button from '@cloudscape-design/components/button'
+import Alert from '@cloudscape-design/components/alert'
+import SpaceBetween from '@cloudscape-design/components/space-between'
+
+export default function NewPasswordPage() {
+  const navigate = useNavigate()
+  const location = useLocation()
+  const { respondToNewPasswordChallenge } = useAuth()
+
+  const { challengeSession, email } = (location.state ?? {}) as {
+    challengeSession: string
+    email?: string
+  }
+
+  const [newPassword, setNewPassword] = useState('')
+  const [confirmPassword, setConfirmPassword] = useState('')
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState('')
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    if (newPassword !== confirmPassword) {
+      setError('Le password non corrispondono')
+      return
+    }
+    setError('')
+    setIsLoading(true)
+    try {
+      const result = await respondToNewPasswordChallenge(
+        challengeSession,
+        newPassword,
+        email ? { email } : undefined,
+      )
+
+      switch (result.status) {
+        case 'SUCCESS':
+          navigate('/')
+          break
+        case 'MFA_REQUIRED':
+          navigate('/mfa-verify', {
+            state: { challengeSession: result.challengeSession, mfaType: result.mfaType, email },
+          })
+          break
+        case 'MFA_SETUP_REQUIRED':
+          navigate('/mfa-setup', {
+            state: { challengeSession: result.challengeSession, email },
+          })
+          break
+        default:
+          setError('Errore imprevisto durante il cambio password')
+      }
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : 'Errore durante il cambio password')
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  return (
+    <Container header={<Header variant="h1">Imposta nuova password</Header>}>
+      <form onSubmit={handleSubmit}>
+        <SpaceBetween size="m">
+          <p>È necessario impostare una nuova password per completare l&apos;accesso.</p>
+
+          {error && (
+            <Alert type="error" dismissible onDismiss={() => setError('')}>
+              {error}
+            </Alert>
+          )}
+
+          <FormField label="Nuova password">
+            <Input
+              type="password"
+              value={newPassword}
+              onChange={({ detail }) => setNewPassword(detail.value)}
+              autoFocus
+              disabled={isLoading}
+            />
+          </FormField>
+
+          <FormField label="Conferma nuova password">
+            <Input
+              type="password"
+              value={confirmPassword}
+              onChange={({ detail }) => setConfirmPassword(detail.value)}
+              disabled={isLoading}
+            />
+          </FormField>
+
+          <Button variant="primary" formAction="submit" loading={isLoading}>
+            Imposta password
+          </Button>
+        </SpaceBetween>
+      </form>
+    </Container>
+  )
+}
+```
+
+---
+
+### Registrazione
+
+Due pagine separate: `register.tsx` per la registrazione e `confirm-signup.tsx` per la verifica email.
+
+```tsx
+// src/pages/register.tsx
+import { useState } from 'react'
+import { useNavigate } from 'react-router-dom'
+import { useAuth } from 'cognito-max/react'
+import Container from '@cloudscape-design/components/container'
+import Header from '@cloudscape-design/components/header'
+import FormField from '@cloudscape-design/components/form-field'
+import Input from '@cloudscape-design/components/input'
+import Button from '@cloudscape-design/components/button'
+import Alert from '@cloudscape-design/components/alert'
+import SpaceBetween from '@cloudscape-design/components/space-between'
+
+export default function RegisterPage() {
+  const navigate = useNavigate()
+  const { signUp } = useAuth()
+
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [confirmPassword, setConfirmPassword] = useState('')
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState('')
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    if (password !== confirmPassword) {
+      setError('Le password non corrispondono')
+      return
+    }
+    setError('')
+    setIsLoading(true)
+    try {
+      await signUp(email, password)
+      // Cognito invia un codice di verifica all'email
+      navigate('/confirm-signup', { state: { email } })
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : 'Errore durante la registrazione')
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  return (
+    <Container header={<Header variant="h1">Crea account</Header>}>
+      <form onSubmit={handleSubmit}>
+        <SpaceBetween size="m">
+          {error && (
+            <Alert type="error" dismissible onDismiss={() => setError('')}>
+              {error}
+            </Alert>
+          )}
+
+          <FormField label="Email">
+            <Input
+              type="email"
+              value={email}
+              onChange={({ detail }) => setEmail(detail.value)}
+              autoFocus
+              disabled={isLoading}
+            />
+          </FormField>
+
+          <FormField label="Password">
+            <Input
+              type="password"
+              value={password}
+              onChange={({ detail }) => setPassword(detail.value)}
+              disabled={isLoading}
+            />
+          </FormField>
+
+          <FormField label="Conferma password">
+            <Input
+              type="password"
+              value={confirmPassword}
+              onChange={({ detail }) => setConfirmPassword(detail.value)}
+              disabled={isLoading}
+            />
+          </FormField>
+
+          <Button variant="primary" formAction="submit" loading={isLoading}>
+            Registrati
+          </Button>
+
+          <Button variant="link" onClick={() => navigate('/login')} disabled={isLoading}>
+            Hai già un account? Accedi
+          </Button>
+        </SpaceBetween>
+      </form>
+    </Container>
+  )
+}
+```
+
+```tsx
+// src/pages/confirm-signup.tsx
+import { useState } from 'react'
+import { useLocation, useNavigate } from 'react-router-dom'
+import { useAuth } from 'cognito-max/react'
+import Container from '@cloudscape-design/components/container'
+import Header from '@cloudscape-design/components/header'
+import FormField from '@cloudscape-design/components/form-field'
+import Input from '@cloudscape-design/components/input'
+import Button from '@cloudscape-design/components/button'
+import Alert from '@cloudscape-design/components/alert'
+import SpaceBetween from '@cloudscape-design/components/space-between'
+
+export default function ConfirmSignupPage() {
+  const navigate = useNavigate()
+  const location = useLocation()
+  const { confirmSignUp, resendConfirmationCode } = useAuth()
+
+  const { email } = (location.state ?? {}) as { email: string }
+
+  const [code, setCode] = useState('')
+  const [isLoading, setIsLoading] = useState(false)
+  const [isResending, setIsResending] = useState(false)
+  const [error, setError] = useState('')
+  const [success, setSuccess] = useState('')
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setError('')
+    setIsLoading(true)
+    try {
+      await confirmSignUp(email, code)
+      navigate('/login')
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : 'Codice non valido')
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  const handleResend = async () => {
+    setError('')
+    setSuccess('')
+    setIsResending(true)
+    try {
+      await resendConfirmationCode(email)
+      setSuccess('Nuovo codice inviato via email.')
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : "Errore nell'invio del codice")
+    } finally {
+      setIsResending(false)
+    }
+  }
+
+  return (
+    <Container header={<Header variant="h1">Conferma registrazione</Header>}>
+      <form onSubmit={handleSubmit}>
+        <SpaceBetween size="m">
+          <p>
+            Controlla la tua email <strong>{email}</strong> e inserisci il codice di verifica.
+          </p>
+
+          {error && (
+            <Alert type="error" dismissible onDismiss={() => setError('')}>
+              {error}
+            </Alert>
+          )}
+          {success && <Alert type="success">{success}</Alert>}
+
+          <FormField label="Codice di verifica">
+            <Input
+              type="text"
+              inputMode="numeric"
+              value={code}
+              onChange={({ detail }) => setCode(detail.value)}
+              autoFocus
+              disabled={isLoading}
+            />
+          </FormField>
+
+          <Button variant="primary" formAction="submit" loading={isLoading}>
+            Conferma
+          </Button>
+
+          <Button
+            variant="link"
+            onClick={handleResend}
+            disabled={isLoading || isResending}
+            loading={isResending}
+          >
+            Non hai ricevuto il codice? Invia di nuovo
+          </Button>
+        </SpaceBetween>
+      </form>
+    </Container>
+  )
+}
+```
+
+---
+
+### Password dimenticata
+
+Due pagine: `forgot-password.tsx` per richiedere il codice, `reset-password.tsx` per inserire codice e nuova password.
+
+```tsx
+// src/pages/forgot-password.tsx
+import { useState } from 'react'
+import { useNavigate } from 'react-router-dom'
+import { useAuth } from 'cognito-max/react'
+import Container from '@cloudscape-design/components/container'
+import Header from '@cloudscape-design/components/header'
+import FormField from '@cloudscape-design/components/form-field'
+import Input from '@cloudscape-design/components/input'
+import Button from '@cloudscape-design/components/button'
+import Alert from '@cloudscape-design/components/alert'
+import SpaceBetween from '@cloudscape-design/components/space-between'
+
+export default function ForgotPasswordPage() {
+  const navigate = useNavigate()
+  const { forgotPassword } = useAuth()
+
+  const [email, setEmail] = useState('')
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState('')
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setError('')
+    setIsLoading(true)
+    try {
+      await forgotPassword(email)
+      // Cognito invia un codice all'email
+      navigate('/reset-password', { state: { email } })
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : "Errore nell'invio del codice")
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  return (
+    <Container header={<Header variant="h1">Password dimenticata</Header>}>
+      <form onSubmit={handleSubmit}>
+        <SpaceBetween size="m">
+          <p>Inserisci la tua email per ricevere il codice di reimpostazione.</p>
+
+          {error && (
+            <Alert type="error" dismissible onDismiss={() => setError('')}>
+              {error}
+            </Alert>
+          )}
+
+          <FormField label="Email">
+            <Input
+              type="email"
+              value={email}
+              onChange={({ detail }) => setEmail(detail.value)}
+              autoFocus
+              disabled={isLoading}
+            />
+          </FormField>
+
+          <Button variant="primary" formAction="submit" loading={isLoading}>
+            Invia codice
+          </Button>
+
+          <Button variant="link" onClick={() => navigate('/login')} disabled={isLoading}>
+            Torna al login
+          </Button>
+        </SpaceBetween>
+      </form>
+    </Container>
+  )
+}
+```
+
+```tsx
+// src/pages/reset-password.tsx
+import { useState } from 'react'
+import { useLocation, useNavigate } from 'react-router-dom'
+import { useAuth } from 'cognito-max/react'
+import Container from '@cloudscape-design/components/container'
+import Header from '@cloudscape-design/components/header'
+import FormField from '@cloudscape-design/components/form-field'
+import Input from '@cloudscape-design/components/input'
+import Button from '@cloudscape-design/components/button'
+import Alert from '@cloudscape-design/components/alert'
+import SpaceBetween from '@cloudscape-design/components/space-between'
+import Checkbox from '@cloudscape-design/components/checkbox'
+
+export default function ResetPasswordPage() {
+  const navigate = useNavigate()
+  const location = useLocation()
+  const { confirmForgotPassword, forgotPassword } = useAuth()
+
+  const { email } = (location.state ?? {}) as { email: string }
+
+  const [code, setCode] = useState('')
+  const [newPassword, setNewPassword] = useState('')
+  const [confirmPassword, setConfirmPassword] = useState('')
+  const [showPasswords, setShowPasswords] = useState(false)
+  const [isLoading, setIsLoading] = useState(false)
+  const [isResending, setIsResending] = useState(false)
+  const [error, setError] = useState('')
+  const [success, setSuccess] = useState('')
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    if (newPassword !== confirmPassword) {
+      setError('Le password non corrispondono')
+      return
+    }
+    setError('')
+    setIsLoading(true)
+    try {
+      await confirmForgotPassword(email, code, newPassword)
+      setSuccess('Password reimpostata con successo!')
+      setTimeout(() => navigate('/login'), 2000)
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : 'Errore durante il reset della password')
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  const handleResend = async () => {
+    setError('')
+    setSuccess('')
+    setIsResending(true)
+    try {
+      await forgotPassword(email)
+      setSuccess('Nuovo codice inviato via email.')
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : "Errore nell'invio del codice")
+    } finally {
+      setIsResending(false)
+    }
+  }
+
+  return (
+    <Container header={<Header variant="h1">Reimposta password</Header>}>
+      <form onSubmit={handleSubmit}>
+        <SpaceBetween size="m">
+          <p>
+            Abbiamo inviato un codice a <strong>{email}</strong>. Inseriscilo insieme alla nuova
+            password.
+          </p>
+
+          {error && (
+            <Alert type="error" dismissible onDismiss={() => setError('')}>
+              {error}
+            </Alert>
+          )}
+          {success && <Alert type="success">{success}</Alert>}
+
+          <FormField label="Codice di verifica">
+            <Input
+              type="text"
+              inputMode="numeric"
+              value={code}
+              onChange={({ detail }) => setCode(detail.value)}
+              autoFocus
+              disabled={isLoading}
+            />
+          </FormField>
+
+          <FormField label="Nuova password">
+            <Input
+              type={showPasswords ? 'text' : 'password'}
+              value={newPassword}
+              onChange={({ detail }) => setNewPassword(detail.value)}
+              disabled={isLoading}
+            />
+          </FormField>
+
+          <FormField label="Conferma nuova password">
+            <Input
+              type={showPasswords ? 'text' : 'password'}
+              value={confirmPassword}
+              onChange={({ detail }) => setConfirmPassword(detail.value)}
+              disabled={isLoading}
+            />
+          </FormField>
+
+          <Checkbox
+            checked={showPasswords}
+            onChange={({ detail }) => setShowPasswords(detail.checked)}
+          >
+            Mostra password
+          </Checkbox>
+
+          <Button variant="primary" formAction="submit" loading={isLoading}>
+            Reimposta password
+          </Button>
+
+          <Button
+            variant="link"
+            onClick={handleResend}
+            disabled={isLoading || isResending}
+            loading={isResending}
+          >
+            Invia nuovo codice
+          </Button>
+
+          <Button variant="link" onClick={() => navigate('/login')} disabled={isLoading}>
+            Torna al login
+          </Button>
+        </SpaceBetween>
+      </form>
+    </Container>
+  )
+}
+```
+
+---
+
+### Cambio password (utente autenticato)
+
+```tsx
+// src/pages/change-password.tsx
+import { useState } from 'react'
+import { useNavigate } from 'react-router-dom'
+import { useAuth } from 'cognito-max/react'
+import Container from '@cloudscape-design/components/container'
+import Header from '@cloudscape-design/components/header'
+import FormField from '@cloudscape-design/components/form-field'
+import Input from '@cloudscape-design/components/input'
+import Button from '@cloudscape-design/components/button'
+import Alert from '@cloudscape-design/components/alert'
+import SpaceBetween from '@cloudscape-design/components/space-between'
+import Checkbox from '@cloudscape-design/components/checkbox'
+
+export default function ChangePasswordPage() {
+  const navigate = useNavigate()
+  const { changePassword } = useAuth()
+
+  const [oldPassword, setOldPassword] = useState('')
+  const [newPassword, setNewPassword] = useState('')
+  const [confirmPassword, setConfirmPassword] = useState('')
+  const [showPasswords, setShowPasswords] = useState(false)
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState('')
+  const [success, setSuccess] = useState('')
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    if (newPassword !== confirmPassword) {
+      setError('Le nuove password non corrispondono')
+      return
+    }
+    if (oldPassword === newPassword) {
+      setError('La nuova password deve essere diversa dalla vecchia')
+      return
+    }
+    setError('')
+    setIsLoading(true)
+    try {
+      await changePassword(oldPassword, newPassword)
+      setSuccess('Password cambiata con successo!')
+      setTimeout(() => navigate('/'), 2000)
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : 'Errore durante il cambio password')
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  return (
+    <Container header={<Header variant="h1">Cambia password</Header>}>
+      <form onSubmit={handleSubmit}>
+        <SpaceBetween size="m">
+          {error && (
+            <Alert type="error" dismissible onDismiss={() => setError('')}>
+              {error}
+            </Alert>
+          )}
+          {success && <Alert type="success">{success}</Alert>}
+
+          <FormField label="Password attuale">
+            <Input
+              type={showPasswords ? 'text' : 'password'}
+              value={oldPassword}
+              onChange={({ detail }) => setOldPassword(detail.value)}
+              autoFocus
+              disabled={isLoading}
+            />
+          </FormField>
+
+          <FormField label="Nuova password">
+            <Input
+              type={showPasswords ? 'text' : 'password'}
+              value={newPassword}
+              onChange={({ detail }) => setNewPassword(detail.value)}
+              disabled={isLoading}
+            />
+          </FormField>
+
+          <FormField label="Conferma nuova password">
+            <Input
+              type={showPasswords ? 'text' : 'password'}
+              value={confirmPassword}
+              onChange={({ detail }) => setConfirmPassword(detail.value)}
+              disabled={isLoading}
+            />
+          </FormField>
+
+          <Checkbox
+            checked={showPasswords}
+            onChange={({ detail }) => setShowPasswords(detail.checked)}
+          >
+            Mostra password
+          </Checkbox>
+
+          <Button variant="primary" formAction="submit" loading={isLoading}>
+            Cambia password
+          </Button>
+
+          <Button variant="link" onClick={() => navigate('/')} disabled={isLoading}>
+            Annulla
+          </Button>
+        </SpaceBetween>
+      </form>
+    </Container>
+  )
+}
+```
+
+---
+
+### Setup MFA (utente autenticato)
+
+Usa `useMfa()` da `cognito-max/react` e `react-qr-code` per il QR code.
+
+```tsx
+// src/pages/change-mfa.tsx
+import { useState, useEffect } from 'react'
+import { useNavigate } from 'react-router-dom'
+import { useMfa } from 'cognito-max/react'
+import QRCode from 'react-qr-code'
+import Container from '@cloudscape-design/components/container'
+import Header from '@cloudscape-design/components/header'
+import FormField from '@cloudscape-design/components/form-field'
+import Input from '@cloudscape-design/components/input'
+import Button from '@cloudscape-design/components/button'
+import Alert from '@cloudscape-design/components/alert'
+import SpaceBetween from '@cloudscape-design/components/space-between'
+import Spinner from '@cloudscape-design/components/spinner'
+import Box from '@cloudscape-design/components/box'
+
+export default function ChangeMfaPage() {
+  const navigate = useNavigate()
+  const { setup, verifySetup } = useMfa()
+
+  const [isInitializing, setIsInitializing] = useState(true)
+  const [isLoading, setIsLoading] = useState(false)
+  const [secretCode, setSecretCode] = useState('')
+  const [qrCodeUri, setQrCodeUri] = useState('')
+  const [totpCode, setTotpCode] = useState('')
+  const [error, setError] = useState('')
+  const [success, setSuccess] = useState('')
+
+  // Avvia il setup TOTP al mount — ottiene secretCode e qrCodeUri
+  useEffect(() => {
+    const init = async () => {
+      try {
+        const result = await setup()
+        setSecretCode(result.secretCode)
+        setQrCodeUri(result.qrCodeUri)
+      } catch (err: unknown) {
+        setError(
+          err instanceof Error ? err.message : "Errore nell'inizializzazione. Riprova.",
+        )
+      } finally {
+        setIsInitializing(false)
+      }
+    }
+    init()
+  }, []) // eslint-disable-line react-hooks/exhaustive-deps
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setError('')
+    setIsLoading(true)
+    try {
+      await verifySetup(totpCode)
+      setSuccess('App autenticatrice aggiornata con successo!')
+      setTimeout(() => navigate('/'), 2500)
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : 'Codice non valido. Verifica e riprova.')
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  return (
+    <Container header={<Header variant="h1">Configura autenticazione a due fattori</Header>}>
+      <form onSubmit={handleSubmit}>
+        <SpaceBetween size="m">
+          {error && (
+            <Alert type="error" dismissible onDismiss={() => setError('')}>
+              {error}
+            </Alert>
+          )}
+          {success && <Alert type="success">{success}</Alert>}
+
+          {isInitializing ? (
+            <Box textAlign="center">
+              <Spinner size="large" />
+              <Box margin={{ top: 's' }}>Generazione codice in corso...</Box>
+            </Box>
+          ) : (
+            secretCode && (
+              <SpaceBetween size="m">
+                <Alert type="info">
+                  1. Apri la tua app authenticator (Google Authenticator, Authy…)
+                  <br />
+                  2. Aggiungi un nuovo account scansionando il QR code o inserendo il codice segreto
+                  <br />
+                  3. Inserisci il codice a 6 cifre generato dall&apos;app
+                </Alert>
+
+                <FormField label="QR Code — scansiona con la nuova app">
+                  <div
+                    style={{
+                      padding: '20px',
+                      backgroundColor: '#ffffff',
+                      display: 'flex',
+                      justifyContent: 'center',
+                      border: '1px solid #ddd',
+                      borderRadius: '4px',
+                    }}
+                  >
+                    <QRCode
+                      size={200}
+                      style={{ height: 'auto', maxWidth: '100%', width: '100%' }}
+                      value={qrCodeUri}
+                      viewBox="0 0 200 200"
+                    />
+                  </div>
+                </FormField>
+
+                <FormField label="Codice segreto (inserimento manuale nell'app)">
+                  <div
+                    style={{
+                      padding: '10px',
+                      backgroundColor: '#f0f0f0',
+                      fontFamily: 'monospace',
+                      wordBreak: 'break-all',
+                      fontSize: '14px',
+                      borderRadius: '4px',
+                    }}
+                  >
+                    {secretCode}
+                  </div>
+                </FormField>
+              </SpaceBetween>
+            )
+          )}
+
+          <FormField label="Codice MFA (6 cifre)">
+            <Input
+              type="text"
+              inputMode="numeric"
+              value={totpCode}
+              onChange={({ detail }) => setTotpCode(detail.value)}
+              autoFocus={!isInitializing}
+              disabled={isInitializing || !!success}
+            />
+          </FormField>
+
+          <Button
+            variant="primary"
+            formAction="submit"
+            loading={isLoading}
+            disabled={isInitializing || !secretCode || totpCode.length !== 6 || !!success}
+          >
+            Conferma
+          </Button>
+
+          <Button variant="link" onClick={() => navigate('/')} disabled={isLoading}>
+            Annulla
+          </Button>
+        </SpaceBetween>
+      </form>
+    </Container>
+  )
+}
+```
+
+**Setup MFA durante il login** (`/mfa-setup`) — riceve `challengeSession` e usa `setupTotpChallenge` / `verifyTotpChallenge`:
+
+```tsx
+// src/pages/mfa-setup.tsx
+import { useState, useEffect } from 'react'
+import { useLocation, useNavigate } from 'react-router-dom'
+import { useAuth } from 'cognito-max/react'
+import QRCode from 'react-qr-code'
+import Container from '@cloudscape-design/components/container'
+import Header from '@cloudscape-design/components/header'
+import FormField from '@cloudscape-design/components/form-field'
+import Input from '@cloudscape-design/components/input'
+import Button from '@cloudscape-design/components/button'
+import Alert from '@cloudscape-design/components/alert'
+import SpaceBetween from '@cloudscape-design/components/space-between'
+import Spinner from '@cloudscape-design/components/spinner'
+import Box from '@cloudscape-design/components/box'
+
+export default function MfaSetupPage() {
+  const navigate = useNavigate()
+  const location = useLocation()
+  const { setupTotpChallenge, verifyTotpChallenge } = useAuth()
+
+  const { challengeSession } = (location.state ?? {}) as { challengeSession: string }
+
+  const [isInitializing, setIsInitializing] = useState(true)
+  const [isLoading, setIsLoading] = useState(false)
+  const [secretCode, setSecretCode] = useState('')
+  const [qrCodeUri, setQrCodeUri] = useState('')
+  const [totpCode, setTotpCode] = useState('')
+  const [error, setError] = useState('')
+
+  useEffect(() => {
+    if (!challengeSession) {
+      setError('Dati di sessione non validi. Rieffettua il login.')
+      setTimeout(() => navigate('/login'), 3000)
+      return
+    }
+    const init = async () => {
+      try {
+        const result = await setupTotpChallenge(challengeSession)
+        setSecretCode(result.secretCode)
+        setQrCodeUri(result.qrCodeUri)
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : 'Errore durante inizializzazione MFA'
+        if (msg.includes('session can only be used once')) {
+          setError('La sessione è scaduta. Effettua nuovamente il login.')
+          setTimeout(() => navigate('/login'), 5000)
+        } else {
+          setError(msg)
+        }
+      } finally {
+        setIsInitializing(false)
+      }
+    }
+    init()
+  }, [challengeSession]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    if (!secretCode) return
+    setError('')
+    setIsLoading(true)
+    try {
+      const result = await verifyTotpChallenge(challengeSession, totpCode)
+      if (result.status === 'SUCCESS') {
+        navigate('/')
+      } else {
+        setError('Errore imprevisto durante la verifica MFA')
+      }
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : 'Errore durante la verifica del codice MFA')
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  return (
+    <Container header={<Header variant="h1">Configurazione MFA</Header>}>
+      <form onSubmit={handleSubmit}>
+        <SpaceBetween size="m">
+          <p>Configura l&apos;autenticazione a due fattori per completare l&apos;accesso.</p>
+
+          {error && (
+            <Alert type="error" dismissible onDismiss={() => setError('')}>
+              {error}
+            </Alert>
+          )}
+
+          {isInitializing ? (
+            <Box textAlign="center">
+              <Spinner size="large" />
+            </Box>
+          ) : (
+            secretCode && (
+              <SpaceBetween size="m">
+                <Alert type="info">
+                  1. Installa un&apos;app TOTP (Google Authenticator, Authy…)
+                  <br />
+                  2. Scansiona il QR code o inserisci manualmente il codice segreto
+                  <br />
+                  3. Inserisci il codice a 6 cifre generato dall&apos;app
+                </Alert>
+
+                <FormField label="QR Code — scansiona con la tua app TOTP">
+                  <div
+                    style={{
+                      padding: '20px',
+                      backgroundColor: '#ffffff',
+                      display: 'flex',
+                      justifyContent: 'center',
+                      border: '1px solid #ddd',
+                      borderRadius: '4px',
+                    }}
+                  >
+                    <QRCode
+                      size={200}
+                      style={{ height: 'auto', maxWidth: '100%', width: '100%' }}
+                      value={qrCodeUri}
+                      viewBox="0 0 200 200"
+                    />
+                  </div>
+                </FormField>
+
+                <FormField label="Codice segreto (inserimento manuale nell'app)">
+                  <div
+                    style={{
+                      padding: '10px',
+                      backgroundColor: '#f0f0f0',
+                      fontFamily: 'monospace',
+                      wordBreak: 'break-all',
+                      fontSize: '14px',
+                    }}
+                  >
+                    {secretCode}
+                  </div>
+                </FormField>
+              </SpaceBetween>
+            )
+          )}
+
+          <FormField label="Codice MFA (6 cifre)">
+            <Input
+              type="text"
+              inputMode="numeric"
+              value={totpCode}
+              onChange={({ detail }) => setTotpCode(detail.value)}
+              autoFocus={!isInitializing}
+              disabled={isInitializing || !secretCode}
+            />
+          </FormField>
+
+          <Button
+            variant="primary"
+            formAction="submit"
+            loading={isLoading}
+            disabled={isInitializing || !secretCode || totpCode.length !== 6}
+          >
+            Verifica e completa setup
+          </Button>
+        </SpaceBetween>
+      </form>
+    </Container>
+  )
+}
+```
+
+---
+
+### Token sync per axios
+
+Il provider Cognito salva i token nel context React, non in `localStorage`. Se l'applicazione usa un interceptor axios che legge il token da `localStorage`, aggiungere questo componente wrapper sotto `<AuthProvider>`:
+
+```tsx
+// src/components/CognitoTokenSync.tsx
+import { useEffect, type ReactNode } from 'react'
+import { useSession } from 'cognito-max/react'
+
+interface Props {
+  children: ReactNode
+}
+
+/**
+ * Sincronizza il token Cognito in localStorage.
+ * Necessario se l'interceptor axios legge il token tramite
+ * localStorage.getItem("idToken") invece che dal context React.
+ */
+export default function CognitoTokenSync({ children }: Props) {
+  const { idToken, isAuthenticated } = useSession()
+
+  useEffect(() => {
+    if (isAuthenticated && idToken) {
+      localStorage.setItem('idToken', idToken)
+      localStorage.setItem('accessToken', idToken)
+    } else if (!isAuthenticated) {
+      localStorage.removeItem('idToken')
+      localStorage.removeItem('accessToken')
+      localStorage.removeItem('refreshToken')
+    }
+  }, [idToken, isAuthenticated])
+
+  return <>{children}</>
+}
+```
+
+Interceptor axios corrispondente:
+
+```ts
+// src/api/axios-instance.ts
+import axios from 'axios'
+
+const api = axios.create({
+  baseURL: import.meta.env.VITE_API_BASE_URL,
+})
+
+api.interceptors.request.use((config) => {
+  const token = localStorage.getItem('idToken')
+  if (token) {
+    config.headers.Authorization = `Bearer ${token}`
+  }
+  return config
+})
+
+api.interceptors.response.use(
+  (res) => res,
+  (err) => {
+    if (err.response?.status === 401) {
+      // Token scaduto — reindirizza al login
+      window.location.href = '/login'
+    }
+    return Promise.reject(err)
+  },
+)
+
+export default api
+```
+
+In alternativa, senza `localStorage`, usa `useSession()` direttamente nel componente o in un custom hook:
+
+```ts
+// src/hooks/useApiClient.ts
+import { useMemo } from 'react'
+import { useSession } from 'cognito-max/react'
+import axios from 'axios'
+
+export function useApiClient() {
+  const { idToken } = useSession()
+
+  return useMemo(
+    () =>
+      axios.create({
+        baseURL: import.meta.env.VITE_API_BASE_URL,
+        headers: idToken ? { Authorization: `Bearer ${idToken}` } : {},
+      }),
+    [idToken],
+  )
+}
+```
+
+---
+
+### Routing completo
+
+Snippet completo di `App.tsx` con tutte le route auth e protezione per le route private:
+
+```tsx
+// src/App.tsx — snippet completo
+import '@cloudscape-design/global-styles/index.css'
+import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom'
+import { AuthProvider, ProtectedRoute } from 'cognito-max/react'
+import type { AuthConfig } from 'cognito-max'
+
+// Pagine auth
+import LoginPage from './pages/login'
+import MfaVerifyPage from './pages/mfa-verify'
+import MfaSetupPage from './pages/mfa-setup'
+import NewPasswordPage from './pages/new-password'
+import ForgotPasswordPage from './pages/forgot-password'
+import ResetPasswordPage from './pages/reset-password'
+import RegisterPage from './pages/register'
+import ConfirmSignupPage from './pages/confirm-signup'
+
+// Pagine autenticate
+import ChangePasswordPage from './pages/change-password'
+import ChangeMfaPage from './pages/change-mfa'
+import Dashboard from './pages/dashboard'
+
+// Componenti
+import CognitoTokenSync from './components/CognitoTokenSync'
+import Spinner from '@cloudscape-design/components/spinner'
+
+const cognitoConfig: AuthConfig = {
+  userPoolId: import.meta.env.VITE_USER_POOL_ID,
+  clientId: import.meta.env.VITE_CLIENT_ID,
+  region: import.meta.env.VITE_REGION,
+  totpIssuer: 'MyApp',
+}
+
+export default function App() {
+  return (
+    <AuthProvider config={cognitoConfig}>
+      <CognitoTokenSync>
+        <BrowserRouter>
+          <Routes>
+            {/* Route pubbliche */}
+            <Route path="/login"           element={<LoginPage />} />
+            <Route path="/mfa-verify"      element={<MfaVerifyPage />} />
+            <Route path="/mfa-setup"       element={<MfaSetupPage />} />
+            <Route path="/new-password"    element={<NewPasswordPage />} />
+            <Route path="/forgot-password" element={<ForgotPasswordPage />} />
+            <Route path="/reset-password"  element={<ResetPasswordPage />} />
+            <Route path="/register"        element={<RegisterPage />} />
+            <Route path="/confirm-signup"  element={<ConfirmSignupPage />} />
+
+            {/* Route protette — richiedono autenticazione */}
+            <Route
+              path="/change-password"
+              element={
+                <ProtectedRoute
+                  fallback={<Navigate to="/login" replace />}
+                  loading={<Spinner />}
+                >
+                  <ChangePasswordPage />
+                </ProtectedRoute>
+              }
+            />
+            <Route
+              path="/change-mfa"
+              element={
+                <ProtectedRoute
+                  fallback={<Navigate to="/login" replace />}
+                  loading={<Spinner />}
+                >
+                  <ChangeMfaPage />
+                </ProtectedRoute>
+              }
+            />
+            <Route
+              path="/"
+              element={
+                <ProtectedRoute
+                  fallback={<Navigate to="/login" replace />}
+                  loading={<Spinner />}
+                >
+                  <Dashboard />
+                </ProtectedRoute>
+              }
+            />
+            <Route path="*" element={<Navigate to="/" />} />
+          </Routes>
+        </BrowserRouter>
+      </CognitoTokenSync>
+    </AuthProvider>
+  )
+}
+```
+
+---
+
+## License
+
+MIT