@massimo.mazzoleni/cognito-max 1.0.0

package/src/core/event-bus.ts

@@ -0,0 +1,41 @@
+type Listener<T> = T extends void ? () => void : (payload: T) => void
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export class TypedEventEmitter<TEvents extends Record<keyof TEvents, any>> {
+  private readonly _listeners = new Map<keyof TEvents, Set<(...args: any[]) => void>>()
+
+  on<K extends keyof TEvents>(event: K, listener: Listener<TEvents[K]>): () => void {
+    if (!this._listeners.has(event)) {
+      this._listeners.set(event, new Set())
+    }
+    this._listeners.get(event)!.add(listener as (...args: any[]) => void)
+    return () => this.off(event, listener)
+  }
+
+  off<K extends keyof TEvents>(event: K, listener: Listener<TEvents[K]>): void {
+    this._listeners.get(event)?.delete(listener as (...args: any[]) => void)
+  }
+
+  once<K extends keyof TEvents>(event: K, listener: Listener<TEvents[K]>): () => void {
+    const unsub = this.on(event, ((...args: any[]) => {
+      unsub()
+      ;(listener as any)(...args)
+    }) as Listener<TEvents[K]>)
+    return unsub
+  }
+
+  protected emit<K extends keyof TEvents>(
+    event: K,
+    ...args: TEvents[K] extends void ? [] : [TEvents[K]]
+  ): void {
+    this._listeners.get(event)?.forEach(l => l(...args))
+  }
+
+  removeAllListeners(event?: keyof TEvents): void {
+    if (event !== undefined) {
+      this._listeners.delete(event)
+    } else {
+      this._listeners.clear()
+    }
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,5 @@
+export * from './types'
+export * from './errors'
+export * from './storage'
+export * from './event-bus'
+export * from './client'

package/src/core/internal/converters.ts

@@ -0,0 +1,32 @@
+import type { CognitoUserSession } from 'amazon-cognito-identity-js'
+import type { AuthSession, AuthUser } from '../types'
+
+export function buildAuthSession(session: CognitoUserSession): AuthSession {
+  const expiresAt = new Date(session.getAccessToken().getExpiration() * 1000)
+  return {
+    accessToken: session.getAccessToken().getJwtToken(),
+    idToken: session.getIdToken().getJwtToken(),
+    refreshToken: session.getRefreshToken().getToken(),
+    expiresAt,
+    isValid: () => session.isValid(),
+  }
+}
+
+export function buildAuthUser(session: CognitoUserSession, fallbackUsername: string): AuthUser {
+  // Estraiamo tutte le info dall'ID token senza roundtrip API
+  const payload = session.getIdToken().decodePayload() as Record<string, unknown>
+
+  const str = (v: unknown): string => (v != null ? String(v) : '')
+  const bool = (v: unknown): boolean => v === true || v === 'true'
+
+  return {
+    sub: str(payload['sub']),
+    username: str(payload['cognito:username'] ?? fallbackUsername),
+    email: str(payload['email']),
+    emailVerified: bool(payload['email_verified']),
+    groups: Array.isArray(payload['cognito:groups'])
+      ? (payload['cognito:groups'] as string[])
+      : [],
+    attributes: Object.fromEntries(Object.entries(payload).map(([k, v]) => [k, str(v)])),
+  }
+}

package/src/core/storage.ts

@@ -0,0 +1,79 @@
+export interface StorageAdapter {
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+  removeItem(key: string): void
+  clear?(): void
+}
+
+export class LocalStorageAdapter implements StorageAdapter {
+  getItem(key: string): string | null {
+    return localStorage.getItem(key)
+  }
+  setItem(key: string, value: string): void {
+    localStorage.setItem(key, value)
+  }
+  removeItem(key: string): void {
+    localStorage.removeItem(key)
+  }
+  clear(): void {
+    localStorage.clear()
+  }
+}
+
+export class SessionStorageAdapter implements StorageAdapter {
+  getItem(key: string): string | null {
+    return sessionStorage.getItem(key)
+  }
+  setItem(key: string, value: string): void {
+    sessionStorage.setItem(key, value)
+  }
+  removeItem(key: string): void {
+    sessionStorage.removeItem(key)
+  }
+  clear(): void {
+    sessionStorage.clear()
+  }
+}
+
+// Safe for SSR / Node.js environments
+export class InMemoryStorageAdapter implements StorageAdapter {
+  private readonly store = new Map<string, string>()
+
+  getItem(key: string): string | null {
+    return this.store.get(key) ?? null
+  }
+  setItem(key: string, value: string): void {
+    this.store.set(key, value)
+  }
+  removeItem(key: string): void {
+    this.store.delete(key)
+  }
+  clear(): void {
+    this.store.clear()
+  }
+}
+
+// Uses localStorage when available, falls back to in-memory (e.g. SSR)
+export class AutoStorageAdapter implements StorageAdapter {
+  private readonly delegate: StorageAdapter
+
+  constructor() {
+    this.delegate =
+      typeof window !== 'undefined' && window.localStorage
+        ? new LocalStorageAdapter()
+        : new InMemoryStorageAdapter()
+  }
+
+  getItem(key: string): string | null {
+    return this.delegate.getItem(key)
+  }
+  setItem(key: string, value: string): void {
+    this.delegate.setItem(key, value)
+  }
+  removeItem(key: string): void {
+    this.delegate.removeItem(key)
+  }
+  clear(): void {
+    this.delegate.clear?.()
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,87 @@
+// ─── State machine ────────────────────────────────────────────────────────────
+
+export type AuthState =
+  | 'idle'
+  | 'loading'
+  | 'authenticated'
+  | 'unauthenticated'
+  | 'mfa_required'
+  | 'new_password_required'
+  | 'confirm_signup'
+
+// ─── MFA ──────────────────────────────────────────────────────────────────────
+
+export type MfaType = 'TOTP' | 'SMS' | 'NOMFA'
+
+export interface MfaSetupResult {
+  secretCode: string
+  /** otpauth://totp/<issuer>:<email>?secret=<secret>&issuer=<issuer> */
+  qrCodeUri: string
+}
+
+export interface MfaPreference {
+  enabled: boolean
+  preferred: MfaType | null
+  totp: boolean
+  sms: boolean
+}
+
+// ─── User & Session ───────────────────────────────────────────────────────────
+
+export interface AuthUser {
+  sub: string
+  username: string
+  email: string
+  emailVerified: boolean
+  groups: string[]
+  attributes: Record<string, string>
+}
+
+export interface AuthSession {
+  accessToken: string
+  idToken: string
+  refreshToken: string
+  expiresAt: Date
+  isValid(): boolean
+}
+
+// ─── Sign-in result (discriminated union) ────────────────────────────────────
+
+export 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' }
+
+// ─── Config ───────────────────────────────────────────────────────────────────
+
+import type { StorageAdapter } from './storage'
+
+export interface AuthConfig {
+  userPoolId: string
+  clientId: string
+  region: string
+  storage?: StorageAdapter
+  /** Rinnova il token automaticamente prima della scadenza. Default: true */
+  autoRefresh?: boolean
+  /** Secondi prima della scadenza in cui scatta il refresh. Default: 300 */
+  refreshMarginSeconds?: number
+  /** Label mostrata nell'app authenticator (es. "MioApp"). Default: clientId */
+  totpIssuer?: string
+}
+
+export interface ResolvedAuthConfig extends Required<AuthConfig> {}
+
+// ─── Events ───────────────────────────────────────────────────────────────────
+
+export interface AuthEvents {
+  signedIn: AuthUser
+  signedOut: void
+  tokenRefreshed: AuthSession
+  sessionExpired: void
+  mfaRequired: { mfaType: MfaType; challengeSession: string }
+  newPasswordRequired: { requiredAttributes: string[]; challengeSession: string }
+  userUpdated: AuthUser
+  stateChanged: AuthState
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './core'

package/src/react/components/ProtectedRoute.tsx

@@ -0,0 +1,56 @@
+import type { ReactNode } from 'react'
+import { useAuthContext } from '../context'
+
+export interface ProtectedRouteProps {
+  children: ReactNode
+  /** Mostrato mentre lo stato auth è in inizializzazione (idle/loading). Default: null */
+  loading?: ReactNode
+  /**
+   * Mostrato quando l'utente non è autenticato o non ha i permessi richiesti.
+   * Con react-router-dom: <Navigate to="/login" replace />
+   */
+  fallback?: ReactNode
+  /** L'utente deve appartenere ad almeno uno di questi gruppi Cognito */
+  requiredGroups?: string[]
+}
+
+export function ProtectedRoute({
+  children,
+  loading = null,
+  fallback = null,
+  requiredGroups,
+}: ProtectedRouteProps) {
+  const { state, user, isLoading, isAuthenticated } = useAuthContext()
+
+  if (isLoading) return <>{loading}</>
+
+  if (!isAuthenticated) return <>{fallback}</>
+
+  if (requiredGroups?.length) {
+    const userGroups = user?.groups ?? []
+    const hasAccess = requiredGroups.some((g) => userGroups.includes(g))
+    if (!hasAccess) return <>{fallback}</>
+  }
+
+  // Unused var from destructuring: kept for clarity
+  void state
+
+  return <>{children}</>
+}
+
+// ─── Hook imperativo per logica di redirect inline ──────────────────────────────
+
+export interface UseRequireAuthOptions {
+  requiredGroups?: string[]
+}
+
+export function useRequireAuth(options?: UseRequireAuthOptions) {
+  const { state, user, isLoading, isAuthenticated } = useAuthContext()
+
+  const isAllowed =
+    isAuthenticated &&
+    (!options?.requiredGroups?.length ||
+      options.requiredGroups.some((g) => (user?.groups ?? []).includes(g)))
+
+  return { isAllowed, isLoading, state, user }
+}

package/src/react/context.tsx

@@ -0,0 +1,126 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from 'react'
+
+import { CognitoAuthClient } from '../core/client'
+import type { AuthConfig, AuthSession, AuthState, AuthUser } from '../core/types'
+
+// ─── Context shape ─────────────────────────────────────────────────────────────
+
+export interface AuthContextValue {
+  client: CognitoAuthClient
+  state: AuthState
+  user: AuthUser | null
+  session: AuthSession | null
+  isLoading: boolean
+  isAuthenticated: boolean
+}
+
+const AuthContext = createContext<AuthContextValue | null>(null)
+
+// ─── Internal hook ──────────────────────────────────────────────────────────────
+
+export function useAuthContext(): AuthContextValue {
+  const ctx = useContext(AuthContext)
+  if (!ctx) {
+    throw new Error('useAuthContext must be used inside <AuthProvider>')
+  }
+  return ctx
+}
+
+// ─── Provider ──────────────────────────────────────────────────────────────────
+
+export interface AuthProviderProps {
+  config: AuthConfig
+  children: ReactNode
+}
+
+export function AuthProvider({ config, children }: AuthProviderProps) {
+  // Client è stabile per tutta la vita del provider — il config viene ignorato dopo il mount
+  const [client] = useState(() => new CognitoAuthClient(config))
+
+  const [authState, setAuthState] = useState<AuthState>('idle')
+  const [user, setUser] = useState<AuthUser | null>(null)
+  const [session, setSession] = useState<AuthSession | null>(null)
+
+  useEffect(() => {
+    let active = true
+
+    // Ripristina la sessione dallo storage (localStorage / adapter configurato)
+    client
+      .getCurrentUser()
+      .then(async (currentUser) => {
+        if (!active) return
+        if (currentUser) {
+          const s = await client.getSession().catch(() => null)
+          if (active) {
+            setUser(currentUser)
+            setSession(s)
+          }
+        } else {
+          if (active) setAuthState('unauthenticated')
+        }
+      })
+      .catch(() => {
+        if (active) setAuthState('unauthenticated')
+      })
+
+    const unsubs = [
+      client.on('stateChanged', (s: AuthState) => {
+        if (active) setAuthState(s)
+        // Pulisce user/session per tutti gli stati non autenticati
+        if (s === 'unauthenticated') {
+          setUser(null)
+          setSession(null)
+        }
+      }),
+      client.on('signedIn', (u) => {
+        if (!active) return
+        setUser(u)
+        client
+          .getSession()
+          .then((s) => { if (active) setSession(s) })
+          .catch(() => {})
+      }),
+      client.on('signedOut', () => {
+        if (active) {
+          setUser(null)
+          setSession(null)
+        }
+      }),
+      client.on('tokenRefreshed', (s) => {
+        if (active) setSession(s)
+      }),
+      client.on('sessionExpired', () => {
+        if (active) {
+          setUser(null)
+          setSession(null)
+        }
+      }),
+    ]
+
+    return () => {
+      active = false
+      unsubs.forEach((unsub) => unsub())
+    }
+  }, [client])
+
+  const value = useMemo<AuthContextValue>(
+    () => ({
+      client,
+      state: authState,
+      user,
+      session,
+      isLoading: authState === 'idle' || authState === 'loading',
+      isAuthenticated: authState === 'authenticated',
+    }),
+    [client, authState, user, session],
+  )
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>
+}

package/src/react/hooks/useAuth.ts

@@ -0,0 +1,75 @@
+import { useMemo } from 'react'
+import { useAuthContext } from '../context'
+import type { MfaType, SignInResult } from '../../core/types'
+
+export function useAuth() {
+  const { client, state, user, isLoading, isAuthenticated } = useAuthContext()
+
+  // useMemo garantisce riferimenti stabili tra i re-render (client non cambia mai)
+  const actions = useMemo(
+    () => ({
+      signIn: (email: string, password: string): Promise<SignInResult> =>
+        client.signIn(email, password),
+
+      signOut: (global?: boolean): Promise<void> =>
+        client.signOut(global),
+
+      signUp: (
+        email: string,
+        password: string,
+        attributes?: Record<string, string>,
+      ): Promise<void> => client.signUp(email, password, attributes),
+
+      confirmSignUp: (email: string, code: string): Promise<void> =>
+        client.confirmSignUp(email, code),
+
+      resendConfirmationCode: (email: string): Promise<void> =>
+        client.resendConfirmationCode(email),
+
+      forgotPassword: (email: string): Promise<void> =>
+        client.forgotPassword(email),
+
+      confirmForgotPassword: (
+        email: string,
+        code: string,
+        newPassword: string,
+      ): Promise<void> => client.confirmForgotPassword(email, code, newPassword),
+
+      changePassword: (current: string, next: string): Promise<void> =>
+        client.changePassword(current, next),
+
+      respondToMfaChallenge: (
+        challengeSession: string,
+        code: string,
+        mfaType: MfaType,
+      ): Promise<SignInResult> =>
+        client.respondToMfaChallenge(challengeSession, code, mfaType),
+
+      respondToNewPasswordChallenge: (
+        challengeSession: string,
+        newPassword: string,
+        userAttributes?: Record<string, string>,
+      ): Promise<SignInResult> =>
+        client.respondToNewPasswordChallenge(challengeSession, newPassword, userAttributes),
+
+      setupTotpChallenge: (challengeSession: string) =>
+        client.setupTotpChallenge(challengeSession),
+
+      verifyTotpChallenge: (challengeSession: string, code: string): Promise<SignInResult> =>
+        client.verifyTotpChallenge(challengeSession, code),
+    }),
+    [client],
+  )
+
+  return {
+    // Stato
+    user,
+    state,
+    isLoading,
+    isAuthenticated,
+    // Azioni
+    ...actions,
+    // Client raw per casi avanzati
+    client,
+  }
+}

package/src/react/hooks/useMfa.ts

@@ -0,0 +1,19 @@
+import { useAuthContext } from '../context'
+import type { MfaType } from '../../core/types'
+
+export function useMfa() {
+  const { client } = useAuthContext()
+
+  return {
+    /** Avvia il setup TOTP — restituisce secretCode e qrCodeUri per l'app authenticator */
+    setup: () => client.setupTotp(),
+    /** Conferma il codice TOTP generato dall'app per completare il setup */
+    verifySetup: (code: string) => client.verifyTotpSetup(code),
+    /** Legge le preferenze MFA correnti (TOTP abilitato, SMS abilitato, preferito) */
+    getPreference: () => client.getMfaPreference(),
+    /** Imposta il tipo MFA preferito ('TOTP' | 'SMS') */
+    setPreference: (type: MfaType) => client.setMfaPreference(type),
+    /** Disabilita completamente il secondo fattore */
+    disable: () => client.disableMfa(),
+  }
+}

package/src/react/hooks/useSession.ts

@@ -0,0 +1,16 @@
+import { useAuthContext } from '../context'
+
+export function useSession() {
+  const { session, state, client } = useAuthContext()
+
+  return {
+    accessToken: session?.accessToken ?? null,
+    idToken: session?.idToken ?? null,
+    refreshToken: session?.refreshToken ?? null,
+    expiresAt: session?.expiresAt ?? null,
+    isExpired: session ? !session.isValid() : true,
+    isAuthenticated: state === 'authenticated',
+    /** Forza il rinnovo del token e aggiorna il context */
+    refresh: () => client.getSession(),
+  }
+}

package/src/react/hooks/useUser.ts

@@ -0,0 +1,24 @@
+import { useAuthContext } from '../context'
+
+export function useUser() {
+  const { user, client } = useAuthContext()
+
+  return {
+    user,
+    attributes: user?.attributes ?? {},
+    groups: user?.groups ?? [],
+    /** Aggiorna uno o più attributi utente in Cognito */
+    update: (attributes: Record<string, string>) =>
+      client.updateUserAttributes(attributes),
+    /** Verifica email o phone_number con il codice ricevuto */
+    verifyAttribute: (attribute: 'email' | 'phone_number', code: string) =>
+      client.verifyUserAttribute(attribute, code),
+    /** Invia un nuovo codice di verifica per email o phone_number */
+    sendVerificationCode: (attribute: 'email' | 'phone_number') =>
+      client.sendAttributeVerificationCode(attribute),
+    /** Recupera gli attributi aggiornati direttamente da Cognito */
+    refreshAttributes: () => client.getUserAttributes(),
+    /** Elimina definitivamente l'account dell'utente corrente */
+    deleteAccount: () => client.deleteUser(),
+  }
+}

package/src/react/index.ts

@@ -0,0 +1,10 @@
+export { AuthProvider, useAuthContext } from './context'
+export type { AuthProviderProps, AuthContextValue } from './context'
+
+export { useAuth } from './hooks/useAuth'
+export { useSession } from './hooks/useSession'
+export { useUser } from './hooks/useUser'
+export { useMfa } from './hooks/useMfa'
+
+export { ProtectedRoute, useRequireAuth } from './components/ProtectedRoute'
+export type { ProtectedRouteProps, UseRequireAuthOptions } from './components/ProtectedRoute'

package/src/ui/components/ChangePasswordForm.tsx

@@ -0,0 +1,105 @@
+import { useId, useRef } from 'react'
+import {
+  useChangePasswordForm,
+  type UseChangePasswordFormOptions,
+} from '../hooks/useChangePasswordForm'
+
+export interface ChangePasswordFormProps extends UseChangePasswordFormOptions {
+  className?: string
+  labels?: {
+    currentPassword?: string
+    newPassword?: string
+    confirmPassword?: string
+    submit?: string
+    successMessage?: string
+  }
+}
+
+export function ChangePasswordForm({
+  className,
+  labels = {},
+  onSuccess,
+  onError,
+}: ChangePasswordFormProps) {
+  const uid = useId()
+  const form = useChangePasswordForm({ onSuccess, onError })
+  const firstInputRef = useRef<HTMLInputElement>(null)
+
+  const l = {
+    currentPassword: labels.currentPassword ?? 'Password attuale',
+    newPassword: labels.newPassword ?? 'Nuova password',
+    confirmPassword: labels.confirmPassword ?? 'Conferma nuova password',
+    submit: labels.submit ?? 'Cambia password',
+    successMessage: labels.successMessage ?? 'Password aggiornata con successo.',
+  }
+
+  const errorId = `${uid}-error`
+
+  if (form.success) {
+    return <p role="status">{l.successMessage}</p>
+  }
+
+  return (
+    <form
+      onSubmit={form.onSubmit}
+      className={className}
+      aria-label="Cambia password"
+    >
+      <div id={errorId} role="alert" aria-live="assertive" aria-atomic="true">
+        {form.error?.message}
+      </div>
+      <div>
+        <label htmlFor={`${uid}-current-password`}>{l.currentPassword}</label>
+        <input
+          id={`${uid}-current-password`}
+          ref={firstInputRef}
+          type="password"
+          autoComplete="current-password"
+          autoFocus
+          required
+          aria-required="true"
+          aria-invalid={!!form.error}
+          aria-describedby={form.error ? errorId : undefined}
+          value={form.currentPassword}
+          onChange={(e) => form.setCurrentPassword(e.target.value)}
+        />
+      </div>
+      <div>
+        <label htmlFor={`${uid}-new-password`}>{l.newPassword}</label>
+        <input
+          id={`${uid}-new-password`}
+          type="password"
+          autoComplete="new-password"
+          required
+          aria-required="true"
+          aria-invalid={!!form.error}
+          value={form.newPassword}
+          onChange={(e) => form.setNewPassword(e.target.value)}
+        />
+      </div>
+      <div>
+        <label htmlFor={`${uid}-confirm-password`}>{l.confirmPassword}</label>
+        <input
+          id={`${uid}-confirm-password`}
+          type="password"
+          autoComplete="new-password"
+          required
+          aria-required="true"
+          aria-invalid={!!form.error}
+          value={form.confirmPassword}
+          onChange={(e) => form.setConfirmPassword(e.target.value)}
+        />
+      </div>
+      <button type="submit" disabled={form.isLoading} aria-busy={form.isLoading}>
+        {form.isLoading ? (
+          <>
+            <span aria-hidden="true">...</span>
+            <span className="sr-only">Caricamento...</span>
+          </>
+        ) : (
+          l.submit
+        )}
+      </button>
+    </form>
+  )
+}