@aurabase/aurabase-js 0.3.0

package/packages/auth/src/AuthService.ts

@@ -0,0 +1,1166 @@
+import { BaseService } from '@aurabase/core'
+import type {
+  AuraResponse,
+  AuthChangePayload,
+  AuthEvent,
+  GetClaimsResult,
+  IdentityInfo,
+  JwtClaims,
+  LoginResponse,
+  MagicLinkRequest,
+  MfaChallenge,
+  MfaEnrollResponse,
+  MfaVerifyRequest,
+  OAuthSignInOptions,
+  PasswordResetRequest,
+  SessionInfo,
+  SignInRequest,
+  SignUpRequest,
+  TokenPair,
+  UpdateUserRequest,
+  User,
+} from '@aurabase/core'
+import type { AuraClientLike } from '@aurabase/core'
+import { refreshOnce, isTokenExpired } from '@aurabase/core'
+import { AuraError } from '@aurabase/core'
+import { emitAuraEvent } from '@aurabase/core'
+import type {
+  VerifyOtpParams,
+  VerifyEmailChangeOtpParams,
+} from './types'
+import { SessionManager } from './SessionManager'
+import { verifyJwtLocal, decodeJwt } from './jwks'
+import { generateCodeVerifier, codeChallengeS256 } from './pkce'
+
+type AuthStateCallback = (payload: AuthChangePayload) => void
+
+export interface AuthServiceOptions {
+  autoRefresh?: boolean
+  persistSession?: boolean
+  /** Interne/test : force l'activation du SessionManager même hors navigateur. */
+  forceEnabled?: boolean
+  /**
+   * Détecte/consomme une session dans l'URL au boot (callback OAuth). Défaut :
+   * `true` en navigateur, no-op hors navigateur. Voir `_detectSessionInUrl`.
+   */
+  detectSessionInUrl?: boolean
+}
+
+/**
+ * Garde de type discriminant `LoginResponse = TokenPair | MfaChallenge` (LOT 3, 3.4).
+ * Exportée (`@aurabase/auth` et re-export `aurabase`) pour permettre aux consommateurs
+ * de discriminer eux-mêmes le retour de `signUp`/`signInWithPassword` sans réimplémenter
+ * la même vérification structurelle (`mfa_required === true`).
+ */
+export function isMfaChallenge(v: unknown): v is MfaChallenge {
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    (v as Record<string, unknown>).mfa_required === true
+  )
+}
+
+export class AuthService extends BaseService {
+  private _stateListeners = new Set<AuthStateCallback>()
+  private _sessionManager: SessionManager
+  private _applyingRemote = false
+  private _unsubStore: (() => void) | null = null
+  private _disposed = false
+
+  constructor(client: AuraClientLike, options?: AuthServiceOptions) {
+    super(client)
+    const browser = typeof window !== 'undefined'
+    const enabled =
+      !!options?.forceEnabled ||
+      ((options?.autoRefresh ?? true) && browser && (options?.persistSession ?? true))
+
+    this._sessionManager = new SessionManager({
+      channelName: `aura-${client.projectId}-auth`,
+      enabled,
+      onTick: () => {
+        void this.refreshSession()
+      },
+      isRefreshDue: () => {
+        const t = this.client.authStore.token
+        return !!t && !!this.client.authStore.refreshToken && isTokenExpired(t, 60)
+      },
+      onRemoteMessage: (data) => this._applyRemoteState(data),
+    })
+    this._sessionManager.start()
+
+    // Le ticker + le broadcast sont pilotés par les changements du store (aucune
+    // duplication dans les méthodes signIn/signOut : leurs save/clear déclenchent ceci).
+    this._unsubStore = this.client.authStore.onChange((token) => {
+      this._sessionManager.setActive(!!token)
+      if (!this._applyingRemote) {
+        const state = this._broadcastState()
+        // Broadcaste un vrai signout (!token → null) OU un état COMPLET ; jamais un
+        // état incomplet (ex. le placeholder user `{}` de setSession).
+        if (!token || state !== null) {
+          this._sessionManager.broadcast(state)
+        }
+      }
+    })
+
+    // Session déjà présente au démarrage (chargée du storage) → armer le ticker.
+    if (this.client.authStore.token) this._sessionManager.setActive(true)
+
+    // detectSessionInUrl : boucle le callback OAuth côté SDK au boot (défaut true en
+    // navigateur). Best-effort, non bloquant, ne throw jamais.
+    const detect = options?.detectSessionInUrl ?? browser
+    if (detect && browser) {
+      void this._detectSessionInUrl()
+    }
+  }
+
+  /**
+   * Détecte et consomme une session présente dans l'URL courante au boot (callback
+   * OAuth), à l'image de `detectSessionInUrl` de supabase-js :
+   *  - fragment `#access_token=…&refresh_token=…` (flux implicit) → `setSession`.
+   *  - query `?token=…&type=recovery` (lien de récupération de mot de passe) → émet
+   *    `PASSWORD_RECOVERY` avec `recoveryToken` (AUCUNE session posée, PAS de `SIGNED_IN`).
+   *  - query `?code=…` (flux PKCE) → `exchangeCodeForSession` (relit le verifier).
+   * Puis nettoie l'URL via `history.replaceState` (retire tokens/code de la barre
+   * d'adresse et de l'historique). Idempotent, no-op si aucun token/code n'est
+   * présent, no-op hors navigateur. NE THROW JAMAIS (best-effort au boot).
+   */
+  async _detectSessionInUrl(): Promise<void> {
+    if (typeof window === 'undefined') return
+    try {
+      const loc = window.location
+      if (!loc) return
+      const hash = typeof loc.hash === 'string' ? loc.hash : ''
+      const search = typeof loc.search === 'string' ? loc.search : ''
+
+      // Flux implicit : tokens dans le fragment (jamais envoyés au serveur).
+      if (hash.includes('access_token')) {
+        // SEC-F3 (anti session-fixation / login-CSRF) : n'ADOPTER un fragment implicit
+        // QUE si CE SDK a lui-même initié le flux (marqueur posé par signInWithOAuth,
+        // survit au redirect via un store persistant). Sans preuve d'initiation, un
+        // `#access_token` peut avoir été forgé par un attaquant et injecté dans l'URL
+        // de la victime (`app/#access_token=<token_attaquant>`) → on ne le consomme
+        // JAMAIS. Le chemin PKCE (`?code=`) est déjà lié au `code_verifier` → intact.
+        const initiatedKey = this._oauthInitiatedKey
+        const initiated = this.client.authStore.getItem(initiatedKey)
+        if (!initiated) return // fragment NON sollicité → ignoré (aucun setSession)
+        // Marqueur à USAGE UNIQUE : purge immédiate (le flux ne doit pas être rejouable).
+        this.client.authStore.removeItem(initiatedKey)
+        const frag = new URLSearchParams(hash.replace(/^#/, ''))
+        const accessToken = frag.get('access_token')
+        const refreshToken = frag.get('refresh_token')
+        if (accessToken && refreshToken) {
+          await this.setSession(accessToken, refreshToken)
+          this._cleanAuthParamsFromUrl()
+        }
+        return
+      }
+
+      // Lien de RÉCUPÉRATION de mot de passe : `?token=<opaque>&type=recovery`
+      // (émis tel quel par le backend `forgot_password`, PAS de flux PKCE — un lien
+      // email froid n'a jamais initié de flux côté SDK, donc pas de code_verifier).
+      // On N'ÉCHANGE AUCUNE session : on se contente d'émettre `PASSWORD_RECOVERY` en
+      // exposant le `recoveryToken` opaque, que l'app repasse ensuite à
+      // `resetPassword(token, newPassword)`. AUCUN `SIGNED_IN`, aucune session posée
+      // (l'utilisateur n'est authentifié qu'après avoir choisi un nouveau mot de passe).
+      {
+        const qs = new URLSearchParams(search.replace(/^\?/, ''))
+        const recoveryToken = qs.get('token')
+        if (qs.get('type') === 'recovery' && recoveryToken) {
+          this._emitEvent('PASSWORD_RECOVERY', null, null, { recoveryToken })
+          this._cleanAuthParamsFromUrl()
+          return
+        }
+      }
+
+      // Flux PKCE : code d'autorisation dans la query (callback OAuth normal).
+      if (/[?&]code=/.test(search)) {
+        const qs = new URLSearchParams(search.replace(/^\?/, ''))
+        const code = qs.get('code')
+        if (code) {
+          await this.exchangeCodeForSession(code)
+          this._cleanAuthParamsFromUrl()
+        }
+        return
+      }
+    } catch {
+      // best-effort au boot : ne jamais throw ni rejeter.
+    }
+  }
+
+  /**
+   * Retire de l'URL courante les paramètres d'auth du callback OAuth : le fragment
+   * entier (flux implicit) et les query params `code`/`state` (flux PKCE), tout en
+   * préservant les autres query params. Via `history.replaceState` (pas de nouvelle
+   * entrée d'historique). Best-effort, ne throw jamais.
+   */
+  private _cleanAuthParamsFromUrl(): void {
+    try {
+      if (typeof window === 'undefined') return
+      const h = window.history
+      const loc = window.location
+      if (!h || typeof h.replaceState !== 'function' || !loc) return
+      const qs = new URLSearchParams(
+        typeof loc.search === 'string' ? loc.search.replace(/^\?/, '') : '',
+      )
+      qs.delete('code')
+      qs.delete('state')
+      // Paramètres du lien de récupération de mot de passe (`?token=…&project_id=…&type=recovery`).
+      qs.delete('token')
+      qs.delete('project_id')
+      qs.delete('type')
+      const remaining = qs.toString()
+      const path = loc.pathname ?? '/'
+      const clean = path + (remaining ? `?${remaining}` : '')
+      h.replaceState(null, '', clean || '/')
+    } catch {
+      // ignore
+    }
+  }
+
+  private _broadcastState(): { token: string; refreshToken: string; user: User } | null {
+    const s = this.client.authStore
+    // État COMPLET uniquement : refuse le placeholder user `{}` (sans id) posé temporairement
+    // par setSession, pour ne pas diffuser d'utilisateur vide aux autres onglets.
+    if (
+      !s.token ||
+      !s.refreshToken ||
+      !s.user ||
+      typeof s.user !== 'object' ||
+      !('id' in s.user) ||
+      !s.user.id
+    ) {
+      return null
+    }
+    return { token: s.token, refreshToken: s.refreshToken, user: s.user }
+  }
+
+  private _applyRemoteState(data: unknown): void {
+    // Valide la FORME du message distant avant d'appliquer (anti-corruption / SDK tiers / message malformé).
+    if (data !== null) {
+      const d = data as Record<string, unknown>
+      if (
+        typeof d.token !== 'string' ||
+        typeof d.refreshToken !== 'string' ||
+        !d.user ||
+        typeof d.user !== 'object'
+      ) {
+        return // message invalide → ignoré
+      }
+    }
+    this._applyingRemote = true
+    try {
+      const store = this.client.authStore
+      const prevToken = store.token
+      if (!data) {
+        store.clear()
+        this._emitEvent('SIGNED_OUT', null, null)
+      } else {
+        const s = data as { token: string; refreshToken: string; user: User }
+        store.save(s.token, s.refreshToken, s.user)
+        // Inférence fidèle de l'événement : login / refresh de token / mise à jour de profil.
+        const event: AuthEvent = !prevToken
+          ? 'SIGNED_IN'
+          : s.token !== prevToken
+            ? 'TOKEN_REFRESHED'
+            : 'USER_UPDATED'
+        this._emitEvent(event, s.user, s.token)
+      }
+    } finally {
+      this._applyingRemote = false
+    }
+  }
+
+  /** Démonte le cycle de vie proactif : ticker, visibilité, BroadcastChannel, listeners. */
+  dispose(): void {
+    if (this._disposed) return
+    this._disposed = true
+    this._sessionManager.stop()
+    this._unsubStore?.()
+    this._unsubStore = null
+    this._stateListeners.clear()
+  }
+
+  private get prefix(): string {
+    return `/v1/auth/${this.client.projectId}`
+  }
+
+  /** Clé project-scoped du `code_verifier` PKCE (anti-collision multi-projets). */
+  private get _pkceVerifierKey(): string {
+    return `aura-${this.client.projectId}-pkce-code-verifier`
+  }
+
+  /**
+   * Clé project-scoped du MARQUEUR d'initiation du flux OAuth implicit (SEC-F3).
+   * Posé par `signInWithOAuth` (flux implicit) avant le redirect ; vérifié + purgé
+   * par `_detectSessionInUrl` au retour. Un fragment `#access_token` forgé/injecté
+   * par un attaquant (login-CSRF / session fixation) n'aura PAS ce marqueur → il ne
+   * sera jamais adopté.
+   */
+  private get _oauthInitiatedKey(): string {
+    return `aura-${this.client.projectId}-oauth-implicit-initiated`
+  }
+
+  // -- Auth state change ------------------------------------------------------
+
+  onAuthStateChange(callback: AuthStateCallback): { unsubscribe: () => void } {
+    // Après dispose(), le client est mort : ne rien émettre (pas même INITIAL_SESSION).
+    if (this._disposed) return { unsubscribe: () => {} }
+    // E20 : bus d'événements UNIQUE (`_stateListeners`). On ne s'abonne plus aussi à
+    // `authStore.onChange` (qui émettait un `SIGNED_IN`/`SIGNED_OUT` en doublon, mal
+    // étiqueté, à chaque save/clear — y compris lors d'un simple refresh). Le store
+    // reste un détail de persistance ; AuthService est le seul émetteur d'événements.
+    this._stateListeners.add(callback)
+    // Emit INITIAL_SESSION on subscribe (Supabase parity)
+    const store = this.client.authStore
+    queueMicrotask(() => {
+      // Se taire si l'abonnement a été retiré (unsubscribe ou dispose avant le tick).
+      if (this._stateListeners.has(callback)) {
+        callback({ event: 'INITIAL_SESSION', user: store.user, accessToken: store.token })
+      }
+    })
+    return {
+      unsubscribe: () => {
+        this._stateListeners.delete(callback)
+      },
+    }
+  }
+
+  private _emitEvent(
+    event: AuthEvent,
+    user: User | null,
+    accessToken: string | null,
+    extra?: { mfaToken?: string; mfaSetupRequired?: boolean; recoveryToken?: string },
+  ): void {
+    for (const cb of this._stateListeners) {
+      try {
+        cb({ event, user, accessToken, ...extra })
+      } catch {
+        // subscriber errors must not break the service
+      }
+    }
+  }
+
+  // -- Sign up / sign in / sign out -------------------------------------------
+
+  async signUp(req: SignUpRequest): Promise<AuraResponse<LoginResponse>> {
+    const res = await this.request<LoginResponse>('POST', `${this.prefix}/register`, req)
+    if (res.data && !isMfaChallenge(res.data)) {
+      const tp = res.data as TokenPair
+      this.client.authStore.save(tp.access_token, tp.refresh_token, tp.user)
+      this._emitEvent('SIGNED_IN', tp.user, tp.access_token)
+    }
+    if (res.data && isMfaChallenge(res.data)) {
+      const mfa = res.data as MfaChallenge
+      this._emitEvent('MFA_CHALLENGE', null, null, {
+        mfaToken: mfa.mfa_token,
+        mfaSetupRequired: mfa.mfa_setup_required,
+      })
+    }
+    return res
+  }
+
+  async signInWithPassword(req: SignInRequest): Promise<AuraResponse<LoginResponse>> {
+    const res = await this.request<LoginResponse>('POST', `${this.prefix}/login`, req)
+    if (res.data && !isMfaChallenge(res.data)) {
+      const tp = res.data as TokenPair
+      this.client.authStore.save(tp.access_token, tp.refresh_token, tp.user)
+      this._emitEvent('SIGNED_IN', tp.user, tp.access_token)
+    }
+    if (res.data && isMfaChallenge(res.data)) {
+      const mfa = res.data as MfaChallenge
+      this._emitEvent('MFA_CHALLENGE', null, null, {
+        mfaToken: mfa.mfa_token,
+        mfaSetupRequired: mfa.mfa_setup_required,
+      })
+    }
+    return res
+  }
+
+  async signInWithOAuth(
+    provider: string,
+    options?: OAuthSignInOptions,
+  ): Promise<AuraResponse<{ url: string }>> {
+    const params = new URLSearchParams()
+    params.set('project_id', this.client.projectId)
+    // Le backend lit `redirect_uri`, PAS `redirect_to` (vérifié empiriquement).
+    if (options?.redirectTo) params.set('redirect_uri', options.redirectTo)
+    if (options?.scopes) params.set('scopes', options.scopes)
+    if (options?.queryParams) {
+      for (const [k, v] of Object.entries(options.queryParams)) {
+        params.set(k, v)
+      }
+    }
+    // PKCE opt-in (flowType: 'pkce') : ne modifie PAS le comportement par défaut
+    // (implicite) des consommateurs existants. Génère + stocke le `code_verifier`
+    // et ajoute code_challenge/code_challenge_method attendus par le backend
+    // (oauth.rs OAuthStartQuery, méthode S256 uniquement).
+    if (options?.flowType === 'pkce') {
+      // DX : PKCE exige un store persistant pour que le `code_verifier` survive au
+      // redirect pleine page vers le provider OAuth et retour. Un store mémoire le
+      // perd → l'échange échouera au retour. On avertit sans bloquer.
+      if (typeof window !== 'undefined' && !this.client.authStore.persistent) {
+        console.warn(
+          '[aurabase] PKCE (flowType:"pkce") requiert un store persistant (LocalAuthStore) pour que le code_verifier survive au redirect OAuth ; le store courant est en mémoire — l\'échange échouera au retour.',
+        )
+      }
+      // WebCrypto peut être indisponible (certains runtimes SSR / edge) →
+      // codeChallengeS256 throw. Le contrat est AuraResponse<{url}> : on échoue
+      // fermé plutôt que de rejeter la promesse.
+      try {
+        const verifier = generateCodeVerifier()
+        const challenge = await codeChallengeS256(verifier)
+        this.client.authStore.setItem(this._pkceVerifierKey, verifier)
+        params.set('code_challenge', challenge)
+        params.set('code_challenge_method', 'S256')
+      } catch {
+        return {
+          data: null,
+          error: new AuraError(0, {
+            error: {
+              code: 'pkce_generation_failed',
+              message: 'PKCE: génération du code_verifier/challenge impossible (WebCrypto indisponible)',
+            },
+          }),
+        }
+      }
+    } else {
+      // SEC-F3 : flux IMPLICIT — pose le MARQUEUR d'initiation. Au retour du provider,
+      // `_detectSessionInUrl` n'adoptera le fragment `#access_token` que si ce marqueur
+      // est présent (preuve que CE SDK a initié le flux). Un fragment forgé par un
+      // attaquant ne l'aura pas. Le marqueur doit survivre au redirect pleine page →
+      // exige un store persistant (LocalAuthStore) ; en store mémoire il ne survit pas
+      // (le fragment ne sera alors pas adopté — fail-closed, plus sûr). On recommande
+      // FORTEMENT le flux PKCE (`flowType:'pkce'`), déjà lié cryptographiquement au
+      // `code_verifier` et non sujet à cette classe d'attaque.
+      if (typeof window !== 'undefined' && !this.client.authStore.persistent) {
+        console.warn(
+          '[aurabase] SÉCURITÉ : signInWithOAuth en flux implicit avec un store NON persistant ' +
+          '(mémoire) — le marqueur anti session-fixation ne survivra pas au redirect OAuth et la ' +
+          'session ne sera pas adoptée au retour. Utilisez un LocalAuthStore, et préférez ' +
+          'flowType:"pkce" (recommandé, immunisé contre la session fixation).',
+        )
+      }
+      try {
+        this.client.authStore.setItem(this._oauthInitiatedKey, '1')
+      } catch {
+        // best-effort : ne bloque jamais le démarrage du flux OAuth.
+      }
+    }
+    // OAuth start is a global route: /v1/auth/oauth/{provider}/start
+    const url = `${this.client.baseUrl}/v1/auth/oauth/${encodeURIComponent(provider)}/start?${params.toString()}`
+    if (typeof window !== 'undefined') {
+      window.location.href = url
+    }
+    // Toujours renvoyer l'URL (pas de no-op silencieux en SSR / hors navigateur).
+    return { data: { url }, error: null }
+  }
+
+  async signInWithMagicLink(req: MagicLinkRequest): Promise<AuraResponse<{ message: string }>> {
+    return this.request('POST', `${this.prefix}/magic-link`, req)
+  }
+
+  async signInAnonymously(): Promise<AuraResponse<TokenPair>> {
+    const res = await this.request<TokenPair>('POST', `${this.prefix}/anonymous`)
+    if (res.data) {
+      this.client.authStore.save(res.data.access_token, res.data.refresh_token, res.data.user)
+      this._emitEvent('SIGNED_IN', res.data.user, res.data.access_token)
+    }
+    return res
+  }
+
+  async signOut(): Promise<AuraResponse<null>> {
+    const refreshToken = this.client.authStore.refreshToken
+    if (!refreshToken) {
+      this.client.authStore.clear()
+      this._emitEvent('SIGNED_OUT', null, null)
+      return { data: null, error: null }
+    }
+    const res = await this.request<null>('POST', `${this.prefix}/logout`, {
+      refresh_token: refreshToken,
+    }, { skipAuthRefresh: true })
+    this.client.authStore.clear()
+    this._emitEvent('SIGNED_OUT', null, null)
+    return res
+  }
+
+  // -- Session management -----------------------------------------------------
+
+  async refreshSession(): Promise<AuraResponse<TokenPair>> {
+    // E17 : passe par le single-flight partagé `refreshOnce` (le même mutex que le
+    // refresh proactif et le retry 401) — évite deux refresh concurrents avec le même
+    // refresh token, qui sur backend à rotation stricte déconnectaient l'utilisateur.
+    const res = await refreshOnce(this.client)
+    if (res.data) {
+      this._emitEvent('TOKEN_REFRESHED', res.data.user, res.data.access_token)
+    }
+    return res
+  }
+
+  /**
+   * Session courante lue depuis le store (synchrone en pratique, pas d'appel réseau).
+   *
+   * ÉCART DE FORME AVEC SUPABASE (LOT 3, 3.5, documenté — pas de breaking change) :
+   * `supabase-js` renvoie `AuraResponse`-like `{data:{session: Session|null}, error}`
+   * où `Session` regroupe `access_token`/`refresh_token`/`expires_at`/`user`. Ici,
+   * `getSession()` renvoie directement `{accessToken, user}` (pas d'enveloppe
+   * `{data, error}`, pas de `refreshToken`/`expiresAt`). Ce choix est délibéré :
+   * cette méthode ne fait aucune requête réseau et ne peut donc jamais échouer
+   * (`error` serait toujours `null`) — l'envelopper aurait été un contrat menteur.
+   * Le `refreshToken` n'est pas exposé pour éviter qu'un consommateur le manipule
+   * hors du store (contrairement à `accessToken`, souvent nécessaire pour des appels
+   * `fetch` manuels côté app). Pour la session complète, lire `client.authStore`
+   * directement (`.token`, `.refreshToken`, `.user`, `.isValid`).
+   */
+  async getSession(): Promise<{ accessToken: string | null; user: User | null }> {
+    return {
+      accessToken: this.client.authStore.token,
+      user: this.client.authStore.user,
+    }
+  }
+
+  async setSession(accessToken: string, refreshToken: string): Promise<AuraResponse<User>> {
+    const store = this.client.authStore
+    // Snapshot pour rollback si la validation échoue : sans lui, un token invalide
+    // laissait le store pollué (token présent + user placeholder `{}`) alors que
+    // `isValid` ne teste que l'expiration du JWT — l'app croyait alors à une
+    // session valide et partait avec un mauvais token.
+    const prev = { token: store.token, refreshToken: store.refreshToken, user: store.user }
+    const hadValidPrev = !!(
+      prev.token &&
+      prev.refreshToken &&
+      prev.user &&
+      (prev.user as { id?: string }).id
+    )
+    const restore = (): void => {
+      if (hadValidPrev) {
+        store.save(prev.token as string, prev.refreshToken as string, prev.user as User)
+      } else {
+        store.clear()
+      }
+    }
+
+    // Parité Supabase : si l'access token fourni est DÉJÀ expiré, on le rafraîchit
+    // via le refresh token plutôt que d'appeler `/user` avec un token périmé
+    // (qui serait rejeté 401 par le gateway).
+    if (isTokenExpired(accessToken, 0)) {
+      store.save(accessToken, refreshToken, {} as User)
+      const refreshed = await refreshOnce(this.client)
+      if (refreshed.data) {
+        this._emitEvent('SIGNED_IN', refreshed.data.user, refreshed.data.access_token)
+        return { data: refreshed.data.user, error: null }
+      }
+      restore()
+      return { data: null, error: refreshed.error }
+    }
+
+    store.save(accessToken, refreshToken, {} as User)
+    const res = await this.request<User>('GET', `${this.prefix}/user`)
+    if (res.data) {
+      store.save(accessToken, refreshToken, res.data)
+      this._emitEvent('SIGNED_IN', res.data, accessToken)
+      return res
+    }
+    // Échec de validation : on ne laisse pas le store pollué.
+    restore()
+    return res
+  }
+
+  async exchangeCodeForSession(authCode: string, codeVerifier?: string): Promise<AuraResponse<TokenPair>> {
+    return this._exchangeCode(authCode, codeVerifier, 'SIGNED_IN')
+  }
+
+  /**
+   * Cœur de l'échange PKCE. `successEvent` détermine l'événement émis en cas de
+   * succès : `SIGNED_IN` (connexion normale) ou `PASSWORD_RECOVERY` (callback de
+   * récupération de mot de passe, `?code=…&type=recovery` — voir `_detectSessionInUrl`).
+   */
+  private async _exchangeCode(
+    authCode: string,
+    codeVerifier: string | undefined,
+    successEvent: AuthEvent,
+  ): Promise<AuraResponse<TokenPair>> {
+    const verifierKey = this._pkceVerifierKey
+    const verifier = codeVerifier ?? this.client.authStore.getItem(verifierKey)
+    if (!verifier) {
+      return {
+        data: null,
+        error: new AuraError(0, {
+          error: { code: 'no_code_verifier', message: 'No PKCE code_verifier available (not provided and none stored)' },
+        }),
+      }
+    }
+    try {
+      const res = await this.request<TokenPair>('POST', `${this.prefix}/oauth/pkce`, {
+        auth_code: authCode,
+        code_verifier: verifier,
+      })
+      if (res.data) {
+        this.client.authStore.save(res.data.access_token, res.data.refresh_token, res.data.user)
+        this._emitEvent(successEvent, res.data.user, res.data.access_token)
+      }
+      return res
+    } finally {
+      // Purge INCONDITIONNELLE du `code_verifier` (succès OU échec) : un code PKCE
+      // est à usage unique — après une tentative d'échange, le verifier ne doit
+      // plus jamais être réutilisable (parité supabase-js `_exchangeCodeForSession`).
+      this.client.authStore.removeItem(verifierKey)
+    }
+  }
+
+  async listSessions(): Promise<AuraResponse<SessionInfo[]>> {
+    const store = this.client.authStore
+    if (store.token && store.refreshToken && !store.isValid) {
+      const refreshed = await this.refreshSession()
+      if (refreshed.error) {
+        return { data: null, error: refreshed.error }
+      }
+    }
+    const refreshToken = store.refreshToken
+    return this.request('GET', `${this.prefix}/sessions`, undefined, {
+      headers: refreshToken ? { 'x-refresh-token': refreshToken } : undefined,
+    })
+  }
+
+  async revokeSession(sessionId: string): Promise<AuraResponse<null>> {
+    return this.request('DELETE', `${this.prefix}/sessions/${sessionId}`)
+  }
+
+  async revokeAllSessions(): Promise<AuraResponse<{ message: string }>> {
+    const rt = this.client.authStore.refreshToken
+    if (!rt) {
+      return {
+        data: null,
+        error: new AuraError(0, { error: { code: 'no_session', message: 'No refresh token available' } }),
+      }
+    }
+    const res = await this.request<{ message: string }>(
+      'POST',
+      `${this.prefix}/logout`,
+      { refresh_token: rt, scope: 'global' },
+      { skipAuthRefresh: true },
+    )
+    if (!res.error) {
+      this.client.authStore.clear()
+      this._emitEvent('SIGNED_OUT', null, null)
+    }
+    return res
+  }
+
+  // -- User management --------------------------------------------------------
+
+  /**
+   * Récupère l'utilisateur validé côté serveur.
+   *
+   * Sans argument : valide le token de la SESSION courante (`store.token`),
+   * avec refresh proactif — comportement historique.
+   *
+   * Avec `jwt` (LOT D) : valide le token ARBITRAIRE passé, via l'override
+   * `authToken` (`Authorization: Bearer <jwt>`), SANS toucher la session
+   * (`skipAuthRefresh`, aucun refresh ni retry-401 sur le store). Le backend
+   * applique l'isolation projet native : un token d'un AUTRE projet → 403.
+   */
+  async getUser(jwt?: string): Promise<AuraResponse<User>> {
+    if (jwt !== undefined) {
+      return this.request('GET', `${this.prefix}/user`, undefined, {
+        authToken: jwt,
+        skipAuthRefresh: true,
+      })
+    }
+    return this.request('GET', `${this.prefix}/user`)
+  }
+
+  /**
+   * Vérifie et décode les claims d'un JWT.
+   *
+   * Chemin nominal : vérification LOCALE via JWKS + WebCrypto, uniquement pour
+   * `alg ∈ {RS256, ES256}` (anti-alg-confusion : jamais de vérif locale HS256).
+   * Chemin fallback : `getUser()` (validation serveur) quand la vérif locale
+   * n'est pas applicable — `alg` non supporté (HS256), JWKS vide, aucune clé
+   * correspondante, ou fetch JWKS en échec. C'est le chemin nominal sur les
+   * déploiements HS256 (JWKS `{"keys":[]}`).
+   *
+   * FOREIGN-TOKEN (LOT D) : le fallback getUser valide le token RÉELLEMENT visé.
+   * Pour le token de session (no-arg, ou `jwt === authStore.token`), c'est
+   * `getUser()` (validation du token du store). Pour un `jwt` ÉTRANGER, c'est
+   * `getUser(jwt)` qui présente CE token en `Authorization` (override `authToken`,
+   * jamais celui du store) : le backend le valide et renvoie SON identité. Aucune
+   * misattribution possible — on présente exactement le token à vérifier — et
+   * l'isolation projet est native côté gateway (token d'un autre projet → 403,
+   * remonté en AuraError, jamais fabriqué).
+   *
+   * NOTE (fallback) : les claims renvoyées par le chemin fallback sont dérivées
+   * de `getUser()` (identité validée serveur) et NE contiennent PAS `exp`/`iat`
+   * (ni les autres champs temporels du JWT) — un consommateur ne doit pas se
+   * fier à `claims.exp` / `claims.iat` après un fallback. Seul le chemin de
+   * vérification locale RS256/ES256 renvoie les claims JWT complètes.
+   */
+  async getClaims(
+    jwt?: string,
+    options?: { allowExpired?: boolean; issuer?: string; audience?: string },
+  ): Promise<AuraResponse<GetClaimsResult>> {
+    const token = jwt ?? this.client.authStore.token
+    // Le fallback getUser valide le token du store, pas l'argument `jwt`. On ne
+    // peut donc l'autoriser que si le token vérifié est bien celui de la session.
+    const usingStoreToken = jwt === undefined || jwt === this.client.authStore.token
+    if (!token) {
+      return {
+        data: null,
+        error: new AuraError(0, { error: { code: 'no_session', message: 'No JWT available' } }),
+      }
+    }
+
+    // SEC-F4 : `this.client` sert de clé d'isolation du cache JWKS (WeakMap
+    // client-scoped dans jwks.ts) — deux clients distincts ne partagent aucun cache.
+    const r = await verifyJwtLocal(this.client, this.client.fetchFn, this.client.baseUrl, token, {
+      allowExpired: options?.allowExpired,
+      // LOT 3 (I8) : relie le callback générique de jwks.ts au hook d'observabilité
+      // du client (onEvent/debug). jwks.ts reste sans dépendance vers @aurabase/core.
+      onEvent: (baseUrl) =>
+        emitAuraEvent(this.client.onEvent, this.client.debug, { kind: 'jwks-fetch-failed', baseUrl }),
+    })
+    // Validation optionnelle iss/aud (parité `jose` : égalité simple, `iss` en
+    // string, `aud` en string OU array via `includes`). N'impose rien par défaut :
+    // contrôlé seulement si l'option est fournie. SEC-F1 : appliquée AUSSI au chemin
+    // fallback (voir plus bas) — plus d'options mortes en prod HS256.
+    const checkIssAud = (c: {
+      iss?: unknown
+      aud?: unknown
+    }): AuraError | null => {
+      if (options?.issuer !== undefined && c.iss !== options.issuer) {
+        return new AuraError(0, {
+          error: { code: 'invalid_issuer', message: `getClaims: issuer mismatch` },
+        })
+      }
+      if (options?.audience !== undefined) {
+        const aud = c.aud
+        const audList = Array.isArray(aud) ? aud : aud !== undefined ? [aud] : []
+        if (!audList.includes(options.audience)) {
+          return new AuraError(0, {
+            error: { code: 'invalid_audience', message: `getClaims: audience mismatch` },
+          })
+        }
+      }
+      return null
+    }
+
+    if (r.ok) {
+      const claims = r.claims as JwtClaims
+      const issAudErr = checkIssAud(claims)
+      if (issAudErr) return { data: null, error: issAudErr }
+      // SEC-F2 : ISOLATION PROJET sur le chemin de vérif LOCALE. Les clés JWKS sont
+      // propres au DÉPLOIEMENT (partagées par tous ses projets) — un token émis pour
+      // un AUTRE projet vérifie donc sa signature et passerait sans ce garde-fou. Le
+      // backend porte l'isolation dans le claim `project_id` (libs/aura-core
+      // AuraClaims.project_id). On refuse par défaut tout token dont le `project_id`
+      // ne correspond PAS au projet du client (le chemin fallback getUser applique
+      // déjà cette isolation nativement via le gateway → 403). On ne rejette que si
+      // le claim est PRÉSENT et divergent (un token tiers sans `project_id` — ex.
+      // Google — n'est pas concerné par l'isolation multi-tenant Aurabase).
+      const claimProject = claims.project_id
+      if (typeof claimProject === 'string' && claimProject !== this.client.projectId) {
+        return {
+          data: null,
+          error: new AuraError(0, {
+            error: {
+              code: 'project_isolation_violation',
+              message: `getClaims: token project mismatch (isolation)`,
+            },
+          }),
+        }
+      }
+      return { data: { claims, header: r.header }, error: null }
+    }
+
+    // Fallback getUser : HS256 (unsupported_alg), JWKS vide / clé absente
+    // (no_matching_key), ou fetch JWKS en échec — le token peut rester valide
+    // côté serveur (cas déploiement HS256).
+    if (
+      r.code === 'unsupported_alg' ||
+      r.code === 'no_matching_key' ||
+      r.code === 'jwks_fetch_failed'
+    ) {
+      // SEC-F1 : les options `issuer`/`audience`/`allowExpired` ne s'appliquaient
+      // qu'au chemin local et étaient MORTES sur le fallback (= la prod HS256). On
+      // décode les claims LOCALEMENT (payload base64url, SANS vérif de signature —
+      // uniquement pour lire iss/aud/exp) et on tranche AVANT tout appel serveur.
+      let localPayload: { iss?: unknown; aud?: unknown; exp?: unknown } = {}
+      try {
+        localPayload = decodeJwt(token).payload
+      } catch {
+        // payload indéchiffrable → on laisse le fallback getUser trancher.
+      }
+      const issAudErr = checkIssAud(localPayload)
+      if (issAudErr) return { data: null, error: issAudErr }
+      // `allowExpired` ne PEUT PAS être honoré par le fallback serveur : `getUser`
+      // rejette un token expiré (401). Plutôt qu'un 401 trompeur qui contredit
+      // l'intention de l'appelant, on remonte un code explicite et cohérent quand
+      // le token est réellement expiré ET que allowExpired était demandé.
+      if (
+        options?.allowExpired &&
+        typeof localPayload.exp === 'number' &&
+        localPayload.exp < Math.floor(Date.now() / 1000)
+      ) {
+        return {
+          data: null,
+          error: new AuraError(0, {
+            error: {
+              code: 'allow_expired_unsupported_on_fallback',
+              message:
+                'getClaims: allowExpired ne peut pas être honoré sur le chemin de validation serveur (fallback HS256/JWKS)',
+            },
+          }),
+        }
+      }
+      // LOT D — plus de confused-deputy : on valide le token RÉELLEMENT visé.
+      // - `usingStoreToken` : `getUser()` no-arg valide le token de session
+      //   (refresh proactif conservé) — chemin historique INCHANGÉ.
+      // - token étranger (`!usingStoreToken`) : `getUser(token)` envoie CE token
+      //   en `Authorization` (override `authToken`), pas celui du store. Le
+      //   backend le valide et renvoie SON identité, avec isolation projet native
+      //   (token d'un autre projet → 403 remonté en AuraError, jamais fabriqué).
+      //   Auparavant fail-closed (`unverifiable_token`) car le SDK ne POUVAIT PAS
+      //   cibler le token étranger (Authorization toujours écrasé par store.token).
+      const u = usingStoreToken ? await this.getUser() : await this.getUser(token)
+      if (u.data) {
+        // Alg RÉEL du token (décodé) plutôt qu'un `HS256` en dur mensonger : sur un
+        // vrai token RS256 tombé en fallback (`jwks_fetch_failed`), le header doit
+        // refléter `RS256`. `unknown` si le header est indéchiffrable.
+        let realAlg = 'unknown'
+        try {
+          realAlg = decodeJwt(token).header.alg ?? 'unknown'
+        } catch {
+          // header indéchiffrable → 'unknown'
+        }
+        return {
+          data: {
+            // Claims dérivées de getUser : PAS de `exp`/`iat` (voir JwtClaims/JSDoc).
+            // `exp`/`iat` étant optionnels, plus de `as unknown as` masquant l'absence.
+            claims: { ...u.data, sub: u.data.id } as JwtClaims,
+            header: { alg: realAlg },
+          },
+          error: null,
+        }
+      }
+      return { data: null, error: u.error }
+    }
+
+    // Échecs de sécurité réels (invalid_jwt, signature_invalid, token_expired,
+    // token_not_yet_valid) : jamais de fallback silencieux.
+    return {
+      data: null,
+      error: new AuraError(0, { error: { code: r.code, message: `getClaims: ${r.code}` } }),
+    }
+  }
+
+  async deleteUser(password: string): Promise<AuraResponse<null>> {
+    const res = await this.request<null>('DELETE', `${this.prefix}/user`, { password })
+    if (!res.error) {
+      this.client.authStore.clear()
+      this._emitEvent('SIGNED_OUT', null, null)
+    }
+    return res
+  }
+
+  async updateUser(req: UpdateUserRequest): Promise<AuraResponse<User>> {
+    const res = await this.request<User>('PUT', `${this.prefix}/user`, req)
+    if (res.data) {
+      const store = this.client.authStore
+      if (store.token && store.refreshToken) {
+        store.save(store.token, store.refreshToken, res.data)
+      }
+      this._emitEvent('USER_UPDATED', res.data, this.client.authStore.token)
+    }
+    return res
+  }
+
+  // -- Password recovery ------------------------------------------------------
+
+  async resetPasswordForEmail(req: PasswordResetRequest): Promise<AuraResponse<{ message: string }>> {
+    return this.request('POST', `${this.prefix}/forgot-password`, req)
+  }
+
+  async updatePassword(newPassword: string, currentPassword?: string): Promise<AuraResponse<User>> {
+    const res = await this.request<User>('PUT', `${this.prefix}/user`, {
+      password: newPassword,
+      current_password: currentPassword,
+    })
+    if (!res.error) {
+      // Le backend révoque TOUTES les sessions au changement de mot de passe et ne renvoie pas
+      // de nouvelle TokenPair → les tokens en store sont morts. On déconnecte proprement.
+      this.client.authStore.clear()
+      this._emitEvent('SIGNED_OUT', null, null)
+    }
+    return res
+  }
+
+  // -- MFA --------------------------------------------------------------------
+
+  async mfaEnroll(): Promise<AuraResponse<MfaEnrollResponse>> {
+    return this.request('POST', `${this.prefix}/mfa/setup`)
+  }
+
+  async mfaVerifySetup(code: string): Promise<AuraResponse<{ recovery_codes: string[] }>> {
+    return this.request('POST', `${this.prefix}/mfa/setup/verify`, { code })
+  }
+
+  async mfaVerify(req: MfaVerifyRequest): Promise<AuraResponse<TokenPair>> {
+    const res = await this.request<TokenPair>('POST', `${this.prefix}/mfa/verify-login`, req)
+    if (res.data) {
+      this.client.authStore.save(res.data.access_token, res.data.refresh_token, res.data.user)
+      this._emitEvent('SIGNED_IN', res.data.user, res.data.access_token)
+    }
+    return res
+  }
+
+  async mfaUnenroll(password: string): Promise<AuraResponse<{ message: string }>> {
+    return this.request('POST', `${this.prefix}/mfa/disable`, { password })
+  }
+
+  // -- OTP verification (façade unifiée, parité @supabase/auth-js) -------------
+
+  /**
+   * Façade unifiée de vérification OTP (parité `verifyOtp` de `@supabase/auth-js`).
+   * Route vers l'endpoint historique correct selon `params.type`, en conservant
+   * l'effet de bord (sauvegarde de session + émission d'événement). SOURCE DE
+   * VÉRITÉ UNIQUE : les méthodes historiques (`verifyEmail`, `verifySmsOtp`, …)
+   * délèguent désormais ici.
+   *
+   * Mapping :
+   *  - `signup`       → POST /verify-email            `{ token }`         → SIGNED_IN
+   *  - `magiclink`    → POST /magic-link/verify       `{ token }`         → SIGNED_IN
+   *  - `email`        → POST /email-otp/verify        `{ email, code }`   → SIGNED_IN
+   *  - `sms`          → POST /sms/verify              `{ phone, code }`   → SIGNED_IN
+   *  - `recovery`     → POST /reset-password          `{ token, password }` → SIGNED_IN
+   *  - `email_change` → POST /user/confirm-email-change `{ token }`       → USER_UPDATED
+   *
+   * Divergences documentées :
+   *  - `recovery` EXIGE `password` (le backend fusionne consommation du token +
+   *    changement de mot de passe) → `AuraError('missing_password')` sans appel réseau sinon.
+   *  - `invite`/`phone_change` n'ont aucun endpoint backend → `AuraError('otp_type_unsupported')`.
+   *  - `email_change` émet dorénavant `USER_UPDATED` (auparavant aucun événement) —
+   *    amélioration assumée (parité), pas une régression.
+   */
+  async verifyOtp(params: VerifyEmailChangeOtpParams): Promise<AuraResponse<User>>
+  async verifyOtp(params: Exclude<VerifyOtpParams, VerifyEmailChangeOtpParams>): Promise<AuraResponse<TokenPair>>
+  async verifyOtp(params: VerifyOtpParams): Promise<AuraResponse<TokenPair | User>> {
+    switch (params.type) {
+      case 'signup':
+        return this._verifyToTokenPair(`${this.prefix}/verify-email`, { token: params.token })
+      case 'magiclink':
+        return this._verifyToTokenPair(`${this.prefix}/magic-link/verify`, { token: params.token })
+      case 'email':
+        return this._verifyToTokenPair(`${this.prefix}/email-otp/verify`, {
+          email: params.email,
+          code: params.token,
+        })
+      case 'sms':
+        return this._verifyToTokenPair(`${this.prefix}/sms/verify`, {
+          phone: params.phone,
+          code: params.token,
+        })
+      case 'recovery': {
+        if (!params.password) {
+          return {
+            data: null,
+            error: new AuraError(0, {
+              error: {
+                code: 'missing_password',
+                message:
+                  "verifyOtp({ type: 'recovery' }) exige `password` : le backend fusionne consommation du token et changement de mot de passe.",
+              },
+            }),
+          }
+        }
+        return this._verifyToTokenPair(`${this.prefix}/reset-password`, {
+          token: params.token,
+          password: params.password,
+        })
+      }
+      case 'email_change': {
+        const res = await this.request<User>('POST', `${this.prefix}/user/confirm-email-change`, {
+          token: params.token,
+        })
+        if (res.data) {
+          const store = this.client.authStore
+          if (store.token && store.refreshToken) {
+            store.save(store.token, store.refreshToken, res.data)
+          }
+          this._emitEvent('USER_UPDATED', res.data, this.client.authStore.token)
+        }
+        return res
+      }
+      case 'invite':
+      case 'phone_change':
+        return {
+          data: null,
+          error: new AuraError(0, {
+            error: {
+              code: 'otp_type_unsupported',
+              message: `verifyOtp: le type '${params.type}' n'est pas supporté (aucun endpoint backend).`,
+            },
+          }),
+        }
+      default:
+        return {
+          data: null,
+          error: new AuraError(0, {
+            error: { code: 'otp_type_unsupported', message: 'verifyOtp: type OTP inconnu.' },
+          }),
+        }
+    }
+  }
+
+  /**
+   * Helper commun aux vérifications OTP renvoyant une `TokenPair` : appelle
+   * l'endpoint, puis (succès) sauvegarde la session et émet `SIGNED_IN`.
+   */
+  private async _verifyToTokenPair(path: string, body: unknown): Promise<AuraResponse<TokenPair>> {
+    const res = await this.request<TokenPair>('POST', path, body)
+    if (res.data) {
+      this.client.authStore.save(res.data.access_token, res.data.refresh_token, res.data.user)
+      this._emitEvent('SIGNED_IN', res.data.user, res.data.access_token)
+    }
+    return res
+  }
+
+  // -- Email verification -----------------------------------------------------
+
+  /** Rétrocompat : délègue à `verifyOtp({ type: 'signup' })` (POST /verify-email). */
+  async verifyEmail(token: string): Promise<AuraResponse<TokenPair>> {
+    return this.verifyOtp({ type: 'signup', token })
+  }
+
+  async resendVerificationEmail(email?: string): Promise<AuraResponse<{ message: string }>> {
+    const e = email ?? this.client.authStore.user?.email
+    if (!e) {
+      return {
+        data: null,
+        error: new AuraError(0, { error: { code: 'missing_email', message: 'Email is required' } }),
+      }
+    }
+    return this.request('POST', `${this.prefix}/resend-verification`, { email: e })
+  }
+
+  // -- Email OTP (Phase 2) --------------------------------------------------
+
+  async signInWithEmailOtp(email: string): Promise<AuraResponse<{ message: string }>> {
+    return this.request('POST', `${this.prefix}/email-otp/send`, { email })
+  }
+
+  /** Rétrocompat : délègue à `verifyOtp({ type: 'email' })` (POST /email-otp/verify). */
+  async verifyEmailOtp(email: string, code: string): Promise<AuraResponse<TokenPair>> {
+    return this.verifyOtp({ type: 'email', email, token: code })
+  }
+
+  // -- SMS OTP (Phase 2) ----------------------------------------------------
+
+  async signInWithSmsOtp(phone: string): Promise<AuraResponse<{ message: string }>> {
+    return this.request('POST', `${this.prefix}/sms/send`, { phone })
+  }
+
+  /** Rétrocompat : délègue à `verifyOtp({ type: 'sms' })` (POST /sms/verify). */
+  async verifySmsOtp(phone: string, code: string): Promise<AuraResponse<TokenPair>> {
+    return this.verifyOtp({ type: 'sms', phone, token: code })
+  }
+
+  // -- Identity linking (Phase 2) -------------------------------------------
+
+  async listIdentities(): Promise<AuraResponse<IdentityInfo[]>> {
+    return this.request('GET', `${this.prefix}/user/identities`)
+  }
+
+  async linkIdentity(provider: string): Promise<AuraResponse<{ url: string; provider: string }>> {
+    return this.request('POST', `${this.prefix}/user/identities/link/${provider}`)
+  }
+
+  async unlinkIdentity(identityId: string): Promise<AuraResponse<{ message: string }>> {
+    return this.request('DELETE', `${this.prefix}/user/identities/${identityId}`)
+  }
+
+  // -- Email change (Phase 2) -----------------------------------------------
+
+  /**
+   * Rétrocompat : délègue à `verifyOtp({ type: 'email_change' })`.
+   * CHANGEMENT ASSUMÉ (parité) : émet désormais `USER_UPDATED` (auparavant aucun
+   * événement) — voir CHANGELOG.
+   */
+  async confirmEmailChange(token: string): Promise<AuraResponse<User>> {
+    return this.verifyOtp({ type: 'email_change', token })
+  }
+
+  // -- MFA recovery codes (Phase 2) -----------------------------------------
+
+  async regenerateRecoveryCodes(code: string): Promise<AuraResponse<{ recovery_codes: string[] }>> {
+    return this.request('POST', `${this.prefix}/mfa/recovery-codes/regenerate`, { code })
+  }
+
+  // -- Native mobile OAuth (Phase 2) ----------------------------------------
+
+  async signInWithIdToken(provider: string, idToken: string, accessToken?: string): Promise<AuraResponse<TokenPair>> {
+    const res = await this.request<TokenPair>('POST', `${this.prefix}/token`, {
+      provider,
+      id_token: idToken,
+      access_token: accessToken,
+    })
+    if (res.data) {
+      this.client.authStore.save(res.data.access_token, res.data.refresh_token, res.data.user)
+      this._emitEvent('SIGNED_IN', res.data.user, res.data.access_token)
+    }
+    return res
+  }
+
+  // -- Project settings / public config --------------------------------------
+
+  /** GoTrue parity : GET /settings — config publique du projet (pas d'auth requise). */
+  async getSettings(): Promise<
+    AuraResponse<{
+      disable_signup: boolean
+      external: Record<string, boolean>
+      mailer_autoconfirm: boolean
+      mfa_enabled: boolean
+    }>
+  > {
+    return this.request('GET', `${this.prefix}/settings`)
+  }
+
+  /** Clé publiable (anon key) du projet — GET /anon-key (public, à l'image du modèle Supabase). */
+  async getAnonKey(): Promise<AuraResponse<{ anon_key: string }>> {
+    return this.request('GET', `${this.prefix}/anon-key`)
+  }
+
+  // -- Password recovery (token consumption) ----------------------------------
+
+  /**
+   * Consomme le token de récupération de mot de passe et applique le nouveau mot de passe.
+   * Body confirmé au handler (`ResetPasswordRequest` — services/aura-auth/src/handlers/auth.rs) :
+   * `{ token, password }`. Révoque les anciennes sessions et renvoie une nouvelle TokenPair.
+   */
+  async resetPassword(token: string, newPassword: string): Promise<AuraResponse<TokenPair>> {
+    return this.verifyOtp({ type: 'recovery', token, password: newPassword })
+  }
+
+  // -- Anonymous promotion -----------------------------------------------------
+
+  /**
+   * Convertit l'utilisateur anonyme courant (JWT requis) en compte régulier email+password.
+   * Body confirmé au handler (`PromoteAnonymousRequest`) : `{ email, password }`.
+   */
+  async promoteAnonymous(credentials: { email: string; password: string }): Promise<AuraResponse<TokenPair>> {
+    const res = await this.request<TokenPair>('POST', `${this.prefix}/anonymous/promote`, credentials)
+    if (res.data) {
+      this.client.authStore.save(res.data.access_token, res.data.refresh_token, res.data.user)
+      this._emitEvent('USER_UPDATED', res.data.user, res.data.access_token)
+    }
+    return res
+  }
+
+  // -- Magic link verification -------------------------------------------------
+
+  /**
+   * Consomme le token de magic link et renvoie une TokenPair.
+   * Body confirmé au handler (`VerifyMagicLinkRequest`) : `{ token }`.
+   */
+  async verifyMagicLink(token: string): Promise<AuraResponse<TokenPair>> {
+    return this.verifyOtp({ type: 'magiclink', token })
+  }
+}