@aurabase/auth 0.6.0 → 0.6.2

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { BaseService, AuraResponse, AdminUser, AdminCreateUserRequest, AdminUpdateUserRequest, GenerateLinkType, GenerateLinkResult, UserStats, IdentityInfo, AdminSessionInfo, AuditLogEntry, AuthSettings, AuthSettingsUpdate, EmailTemplateUpdate, AuraClientLike, AuthChangePayload, SignUpRequest, LoginResponse, SignInRequest, OAuthSignInOptions, MagicLinkRequest, TokenPair, Session, User, SessionInfo, GetClaimsResult, UpdateUserRequest, PasswordResetRequest, MfaEnrollResponse, MfaVerifyRequest, MfaChallenge } from '@aurabase/core';
+import { BaseService, AuraResponse, AdminUser, AdminCreateUserRequest, AdminUpdateUserRequest, GenerateLinkType, GenerateLinkResult, UserStats, IdentityInfo, AdminSessionInfo, AuditLogEntry, AuthSettings, AuthSettingsUpdate, EmailTemplateUpdate, AuraClientLike, AuthChangePayload, SignUpRequest, LoginResponse, SignInRequest, OAuthSignInOptions, OAuthSignInObjectOptions, MagicLinkRequest, TokenPair, Session, User, SessionInfo, GetClaimsResult, UpdateUserRequest, PasswordResetRequest, MfaEnrollResponse, MfaVerifyRequest, MfaChallenge } from '@aurabase/core';
 
 declare class AuthAdminService extends BaseService {
     /**
@@ -7,31 +7,59 @@ declare class AuthAdminService extends BaseService {
      * `services/aura-gateway/src/middleware/project_subdomain.rs`).
      */
     private get prefix();
+    /**
+     * Liste les utilisateurs du projet, avec recherche (`search`) et pagination (`limit`, `offset`).
+     */
     listUsers(params?: {
         limit?: number;
         offset?: number;
         search?: string;
     }): Promise<AuraResponse<AdminUser[]>>;
+    /** Lit un utilisateur par son identifiant. */
     getUser(userId: string): Promise<AuraResponse<AdminUser>>;
+    /**
+     * Crée un utilisateur sans passer par l'inscription publique (e-mail, mot de passe, métadonnées, rôle).
+     */
     createUser(data: AdminCreateUserRequest): Promise<AuraResponse<AdminUser>>;
+    /** Met à jour un utilisateur : seuls les champs fournis changent. */
     updateUser(userId: string, data: AdminUpdateUserRequest): Promise<AuraResponse<AdminUser>>;
+    /** Supprime un utilisateur. */
     deleteUser(userId: string): Promise<AuraResponse<null>>;
+    /** Bannit un utilisateur : il ne peut plus se connecter. */
     banUser(userId: string): Promise<AuraResponse<null>>;
+    /** Lève le bannissement d'un utilisateur. */
     unbanUser(userId: string): Promise<AuraResponse<null>>;
+    /**
+     * Génère un lien à usage unique pour un utilisateur (`'magic'`, `'recovery'` ou `'invite'`) et renvoie `{ link, token }`.
+     */
     generateLink(userId: string, type: GenerateLinkType): Promise<AuraResponse<GenerateLinkResult>>;
+    /**
+     * Statistiques des utilisateurs : total, vérifiés, bannis, avec MFA et nouveaux sur 7 jours.
+     */
     getUserStats(): Promise<AuraResponse<UserStats>>;
+    /** Liste les identités liées à un utilisateur (fournisseurs OAuth, e-mail). */
     listUserIdentities(userId: string): Promise<AuraResponse<IdentityInfo[]>>;
+    /**
+     * Liste les sessions actives de tous les utilisateurs, filtrables par `userId`, avec pagination.
+     */
     listSessions(params?: {
         userId?: string;
         limit?: number;
         offset?: number;
     }): Promise<AuraResponse<AdminSessionInfo[]>>;
+    /** Révoque une session par son identifiant. */
     revokeSession(sessionId: string): Promise<AuraResponse<null>>;
+    /**
+     * Lit le journal d'audit (action, adresse IP, agent utilisateur, date), filtrable par `userId`, avec pagination.
+     */
     getAuditLog(params?: {
         userId?: string;
         limit?: number;
         offset?: number;
     }): Promise<AuraResponse<AuditLogEntry[]>>;
+    /**
+     * Lit les réglages d'authentification du projet. Les secrets (mot de passe SMTP, clés) ne sont jamais renvoyés.
+     */
     getSettings(): Promise<AuraResponse<AuthSettings>>;
     /**
      * Met à jour les réglages auth du projet (fusion partielle : seuls les champs fournis
@@ -49,12 +77,17 @@ declare class AuthAdminService extends BaseService {
      * renvoyez donc pas tel quel un objet lu par {@link getSettings}.
      */
     updateSettings(data: AuthSettingsUpdate): Promise<AuraResponse<AuthSettings>>;
+    /** Liste les modèles d'e-mail d'authentification du projet. */
     listEmailTemplates(): Promise<AuraResponse<Record<string, unknown>[]>>;
+    /** Lit le modèle d'e-mail d'un type donné (par exemple confirmation, récupération). */
     getEmailTemplate(type: string): Promise<AuraResponse<Record<string, unknown>>>;
+    /** Remplace le contenu du modèle d'e-mail d'un type donné. */
     updateEmailTemplate(type: string, data: EmailTemplateUpdate): Promise<AuraResponse<Record<string, unknown>>>;
+    /** Supprime le modèle personnalisé d'un type d'e-mail. */
     deleteEmailTemplate(type: string): Promise<AuraResponse<{
         message: string;
     }>>;
+    /** Envoie un e-mail de test avec le modèle d'un type à l'adresse `to_email`. */
     testEmailTemplate(type: string, body: {
         to_email: string;
     }): Promise<AuraResponse<null>>;
@@ -204,6 +237,10 @@ declare class AuthService extends BaseService {
      * sera jamais adopté.
      */
     private get _oauthInitiatedKey();
+    /**
+     * Écoute les changements d'état de la session (`SIGNED_IN`, `SIGNED_OUT`, `TOKEN_REFRESHED`, `USER_UPDATED`,
+     * `MFA_CHALLENGE`…). Renvoie de quoi se désabonner : `unsubscribe()` ou `data.subscription.unsubscribe()`.
+     */
     onAuthStateChange(callback: AuthStateCallback): {
         unsubscribe: () => void;
         data: {
@@ -213,12 +250,25 @@ declare class AuthService extends BaseService {
         };
     };
     private _emitEvent;
+    /**
+     * Crée un compte avec e-mail et mot de passe. Si le projet n'exige pas de confirmation et que le MFA n'est pas actif,
+     * la session est enregistrée et `SIGNED_IN` est émis ; sinon la réponse est un défi MFA (voir `isMfaChallenge`).
+     */
     signUp(req: SignUpRequest): Promise<AuraResponse<LoginResponse>>;
+    /**
+     * Connecte un utilisateur par e-mail et mot de passe. Enregistre la session et émet `SIGNED_IN` ;
+     * si le MFA est actif, renvoie un défi (`isMfaChallenge`) à compléter par `mfaVerify`.
+     */
     signInWithPassword(req: SignInRequest): Promise<AuraResponse<LoginResponse>>;
     /**
      * Démarre un flux OAuth : renvoie toujours `{ url }` (et redirige en plus le navigateur
      * si un `window` existe).
      *
+     * Accepte indifféremment la signature canonique :
+     * `signInWithOAuth('google', { redirectTo })`
+     * ou la signature objet compatible Supabase :
+     * `signInWithOAuth({ provider: 'google', options: { redirectTo } })`
+     *
      * ### `options.queryParams` — contrat (N22)
      *
      * Les clés listées par {@link OAUTH_FORWARDABLE_QUERY_PARAMS} — `prompt`, `login_hint`,
@@ -248,11 +298,27 @@ declare class AuthService extends BaseService {
     signInWithOAuth(provider: string, options?: OAuthSignInOptions): Promise<AuraResponse<{
         url: string;
     }>>;
+    signInWithOAuth(options: OAuthSignInObjectOptions): Promise<AuraResponse<{
+        url: string;
+    }>>;
+    /**
+     * Envoie un lien de connexion par e-mail (« magic link »). La session s'obtient ensuite par `verifyOtp({ type: 'magiclink' })`.
+     */
     signInWithMagicLink(req: MagicLinkRequest): Promise<AuraResponse<{
         message: string;
     }>>;
+    /**
+     * Crée une session anonyme (utilisateur sans e-mail), enregistrée et signalée par `SIGNED_IN`.
+     */
     signInAnonymously(): Promise<AuraResponse<TokenPair>>;
+    /**
+     * Déconnecte : révoque le jeton de rafraîchissement côté serveur s'il existe, vide la session locale et émet `SIGNED_OUT`.
+     */
     signOut(): Promise<AuraResponse<null>>;
+    /**
+     * Rafraîchit la session avec le jeton de rafraîchissement et émet `TOKEN_REFRESHED`.
+     * Les rafraîchissements concurrents sont fusionnés en un seul appel.
+     */
     refreshSession(): Promise<AuraResponse<TokenPair>>;
     /**
      * Session courante lue depuis le store (synchrone en pratique, pas d'appel réseau).
@@ -270,6 +336,10 @@ declare class AuthService extends BaseService {
         access_token: string | null;
         user: User | null;
     }>;
+    /**
+     * Installe une session à partir d'un jeton d'accès et d'un jeton de rafraîchissement existants (par exemple reçus d'un serveur).
+     * Un jeton d'accès expiré est rafraîchi ; une session invalide est refusée et l'état précédent est restauré.
+     */
     setSession(accessToken: string, refreshToken: string): Promise<AuraResponse<User>>;
     /**
      * Échange le code d'autorisation PKCE contre une session.
@@ -288,8 +358,15 @@ declare class AuthService extends BaseService {
      * récupération de mot de passe, `?code=…&type=recovery` — voir `_detectSessionInUrl`).
      */
     private _exchangeCode;
+    /**
+     * Liste les sessions de l'utilisateur connecté (appareil, adresse IP, dates) ; `is_current` repère la session courante.
+     */
     listSessions(): Promise<AuraResponse<SessionInfo[]>>;
+    /** Révoque une session de l'utilisateur connecté par son identifiant. */
     revokeSession(sessionId: string): Promise<AuraResponse<null>>;
+    /**
+     * Déconnecte l'utilisateur partout : révoque toutes ses sessions, vide la session locale et émet `SIGNED_OUT`.
+     */
     revokeAllSessions(): Promise<AuraResponse<{
         message: string;
     }>>;
@@ -304,7 +381,9 @@ declare class AuthService extends BaseService {
      * (`skipAuthRefresh`, aucun refresh ni retry-401 sur le store). Le backend
      * applique l'isolation projet native : un token d'un AUTRE projet → 403.
      */
-    getUser(jwt?: string): Promise<AuraResponse<User>>;
+    getUser(jwt?: string): Promise<AuraResponse<User & {
+        user: User;
+    }>>;
     /**
      * Vérifie et décode les claims d'un JWT.
      *
@@ -335,17 +414,59 @@ declare class AuthService extends BaseService {
         issuer?: string;
         audience?: string;
     }): Promise<AuraResponse<GetClaimsResult>>;
+    /**
+     * Supprime le compte de l'utilisateur connecté après confirmation par son mot de passe, puis vide la session locale.
+     */
     deleteUser(password: string): Promise<AuraResponse<null>>;
+    /**
+     * Met à jour l'utilisateur connecté (métadonnées, mot de passe…) et émet `USER_UPDATED`. Un changement d'e-mail ne prend effet qu'après confirmation par `verifyOtp({ type: 'email_change' })`.
+     */
     updateUser(req: UpdateUserRequest): Promise<AuraResponse<User>>;
-    resetPasswordForEmail(req: PasswordResetRequest): Promise<AuraResponse<{
+    /** Envoie un e-mail de réinitialisation du mot de passe (accepte un email sous forme de chaîne ou un objet PasswordResetRequest). */
+    resetPasswordForEmail(emailOrReq: string | PasswordResetRequest): Promise<AuraResponse<{
         message: string;
     }>>;
+    /**
+     * Change le mot de passe de l'utilisateur connecté. Le serveur révoque toutes ses sessions : le SDK vide la session locale et émet `SIGNED_OUT`.
+     */
     updatePassword(newPassword: string, currentPassword?: string): Promise<AuraResponse<User>>;
+    /**
+     * Façade unifiée pour les opérations MFA (TOTP).
+     * Permet d'appeler indifféremment `aura.auth.mfa.enroll()` ou `aura.auth.mfaEnroll()`.
+     */
+    get mfa(): {
+        enroll: (params?: {
+            factor_type?: 'totp';
+            factorType?: 'totp';
+        }) => Promise<AuraResponse<MfaEnrollResponse>>;
+        verifySetup: (codeOrParams: string | {
+            code: string;
+        }) => Promise<AuraResponse<{
+            recovery_codes: string[];
+        }>>;
+        verify: (req: MfaVerifyRequest) => Promise<AuraResponse<TokenPair>>;
+        unenroll: (passwordOrParams: string | {
+            password: string;
+        }) => Promise<AuraResponse<{
+            message: string;
+        }>>;
+        regenerateRecoveryCodes: (codeOrParams: string | {
+            code: string;
+        }) => Promise<AuraResponse<{
+            recovery_codes: string[];
+        }>>;
+    };
+    /** MFA : démarre l'enrôlement TOTP et renvoie le `secret` et l'URL `otpauth_url` à afficher en QR code. */
     mfaEnroll(): Promise<AuraResponse<MfaEnrollResponse>>;
+    /** MFA : confirme l'enrôlement avec un premier code et renvoie les codes de récupération. */
     mfaVerifySetup(code: string): Promise<AuraResponse<{
         recovery_codes: string[];
     }>>;
+    /**
+     * MFA : termine une connexion qui a renvoyé un défi (`mfa_token` et code TOTP). Enregistre la session et émet `SIGNED_IN`.
+     */
     mfaVerify(req: MfaVerifyRequest): Promise<AuraResponse<TokenPair>>;
+    /** MFA : désactive le MFA après confirmation par le mot de passe. */
     mfaUnenroll(password: string): Promise<AuraResponse<{
         message: string;
     }>>;
@@ -378,23 +499,34 @@ declare class AuthService extends BaseService {
      * l'endpoint, puis (succès) sauvegarde la session et émet `SIGNED_IN`.
      */
     private _verifyToTokenPair;
+    /** Renvoie l'e-mail de vérification, à `email` ou à l'adresse de l'utilisateur connecté. */
     resendVerificationEmail(email?: string): Promise<AuraResponse<{
         message: string;
     }>>;
+    /**
+     * Envoie un code à usage unique par e-mail ; à confirmer par `verifyOtp({ type: 'email' })`.
+     */
     signInWithEmailOtp(email: string): Promise<AuraResponse<{
         message: string;
     }>>;
+    /** Envoie un code à usage unique par SMS ; à confirmer par `verifyOtp({ type: 'sms' })`. */
     signInWithSmsOtp(phone: string): Promise<AuraResponse<{
         message: string;
     }>>;
+    /** Liste les identités (fournisseurs) liées à l'utilisateur connecté. */
     listIdentities(): Promise<AuraResponse<IdentityInfo[]>>;
+    /**
+     * Démarre la liaison d'un fournisseur OAuth au compte connecté et renvoie l'URL d'autorisation à ouvrir.
+     */
     linkIdentity(provider: string): Promise<AuraResponse<{
         url: string;
         provider: string;
     }>>;
+    /** Détache une identité du compte connecté par son identifiant. */
     unlinkIdentity(identityId: string): Promise<AuraResponse<{
         message: string;
     }>>;
+    /** MFA : régénère les codes de récupération après confirmation par un code TOTP. */
     regenerateRecoveryCodes(code: string): Promise<AuraResponse<{
         recovery_codes: string[];
     }>>;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { BaseService, AuraResponse, AdminUser, AdminCreateUserRequest, AdminUpdateUserRequest, GenerateLinkType, GenerateLinkResult, UserStats, IdentityInfo, AdminSessionInfo, AuditLogEntry, AuthSettings, AuthSettingsUpdate, EmailTemplateUpdate, AuraClientLike, AuthChangePayload, SignUpRequest, LoginResponse, SignInRequest, OAuthSignInOptions, MagicLinkRequest, TokenPair, Session, User, SessionInfo, GetClaimsResult, UpdateUserRequest, PasswordResetRequest, MfaEnrollResponse, MfaVerifyRequest, MfaChallenge } from '@aurabase/core';
+import { BaseService, AuraResponse, AdminUser, AdminCreateUserRequest, AdminUpdateUserRequest, GenerateLinkType, GenerateLinkResult, UserStats, IdentityInfo, AdminSessionInfo, AuditLogEntry, AuthSettings, AuthSettingsUpdate, EmailTemplateUpdate, AuraClientLike, AuthChangePayload, SignUpRequest, LoginResponse, SignInRequest, OAuthSignInOptions, OAuthSignInObjectOptions, MagicLinkRequest, TokenPair, Session, User, SessionInfo, GetClaimsResult, UpdateUserRequest, PasswordResetRequest, MfaEnrollResponse, MfaVerifyRequest, MfaChallenge } from '@aurabase/core';
 
 declare class AuthAdminService extends BaseService {
     /**
@@ -7,31 +7,59 @@ declare class AuthAdminService extends BaseService {
      * `services/aura-gateway/src/middleware/project_subdomain.rs`).
      */
     private get prefix();
+    /**
+     * Liste les utilisateurs du projet, avec recherche (`search`) et pagination (`limit`, `offset`).
+     */
     listUsers(params?: {
         limit?: number;
         offset?: number;
         search?: string;
     }): Promise<AuraResponse<AdminUser[]>>;
+    /** Lit un utilisateur par son identifiant. */
     getUser(userId: string): Promise<AuraResponse<AdminUser>>;
+    /**
+     * Crée un utilisateur sans passer par l'inscription publique (e-mail, mot de passe, métadonnées, rôle).
+     */
     createUser(data: AdminCreateUserRequest): Promise<AuraResponse<AdminUser>>;
+    /** Met à jour un utilisateur : seuls les champs fournis changent. */
     updateUser(userId: string, data: AdminUpdateUserRequest): Promise<AuraResponse<AdminUser>>;
+    /** Supprime un utilisateur. */
     deleteUser(userId: string): Promise<AuraResponse<null>>;
+    /** Bannit un utilisateur : il ne peut plus se connecter. */
     banUser(userId: string): Promise<AuraResponse<null>>;
+    /** Lève le bannissement d'un utilisateur. */
     unbanUser(userId: string): Promise<AuraResponse<null>>;
+    /**
+     * Génère un lien à usage unique pour un utilisateur (`'magic'`, `'recovery'` ou `'invite'`) et renvoie `{ link, token }`.
+     */
     generateLink(userId: string, type: GenerateLinkType): Promise<AuraResponse<GenerateLinkResult>>;
+    /**
+     * Statistiques des utilisateurs : total, vérifiés, bannis, avec MFA et nouveaux sur 7 jours.
+     */
     getUserStats(): Promise<AuraResponse<UserStats>>;
+    /** Liste les identités liées à un utilisateur (fournisseurs OAuth, e-mail). */
     listUserIdentities(userId: string): Promise<AuraResponse<IdentityInfo[]>>;
+    /**
+     * Liste les sessions actives de tous les utilisateurs, filtrables par `userId`, avec pagination.
+     */
     listSessions(params?: {
         userId?: string;
         limit?: number;
         offset?: number;
     }): Promise<AuraResponse<AdminSessionInfo[]>>;
+    /** Révoque une session par son identifiant. */
     revokeSession(sessionId: string): Promise<AuraResponse<null>>;
+    /**
+     * Lit le journal d'audit (action, adresse IP, agent utilisateur, date), filtrable par `userId`, avec pagination.
+     */
     getAuditLog(params?: {
         userId?: string;
         limit?: number;
         offset?: number;
     }): Promise<AuraResponse<AuditLogEntry[]>>;
+    /**
+     * Lit les réglages d'authentification du projet. Les secrets (mot de passe SMTP, clés) ne sont jamais renvoyés.
+     */
     getSettings(): Promise<AuraResponse<AuthSettings>>;
     /**
      * Met à jour les réglages auth du projet (fusion partielle : seuls les champs fournis
@@ -49,12 +77,17 @@ declare class AuthAdminService extends BaseService {
      * renvoyez donc pas tel quel un objet lu par {@link getSettings}.
      */
     updateSettings(data: AuthSettingsUpdate): Promise<AuraResponse<AuthSettings>>;
+    /** Liste les modèles d'e-mail d'authentification du projet. */
     listEmailTemplates(): Promise<AuraResponse<Record<string, unknown>[]>>;
+    /** Lit le modèle d'e-mail d'un type donné (par exemple confirmation, récupération). */
     getEmailTemplate(type: string): Promise<AuraResponse<Record<string, unknown>>>;
+    /** Remplace le contenu du modèle d'e-mail d'un type donné. */
     updateEmailTemplate(type: string, data: EmailTemplateUpdate): Promise<AuraResponse<Record<string, unknown>>>;
+    /** Supprime le modèle personnalisé d'un type d'e-mail. */
     deleteEmailTemplate(type: string): Promise<AuraResponse<{
         message: string;
     }>>;
+    /** Envoie un e-mail de test avec le modèle d'un type à l'adresse `to_email`. */
     testEmailTemplate(type: string, body: {
         to_email: string;
     }): Promise<AuraResponse<null>>;
@@ -204,6 +237,10 @@ declare class AuthService extends BaseService {
      * sera jamais adopté.
      */
     private get _oauthInitiatedKey();
+    /**
+     * Écoute les changements d'état de la session (`SIGNED_IN`, `SIGNED_OUT`, `TOKEN_REFRESHED`, `USER_UPDATED`,
+     * `MFA_CHALLENGE`…). Renvoie de quoi se désabonner : `unsubscribe()` ou `data.subscription.unsubscribe()`.
+     */
     onAuthStateChange(callback: AuthStateCallback): {
         unsubscribe: () => void;
         data: {
@@ -213,12 +250,25 @@ declare class AuthService extends BaseService {
         };
     };
     private _emitEvent;
+    /**
+     * Crée un compte avec e-mail et mot de passe. Si le projet n'exige pas de confirmation et que le MFA n'est pas actif,
+     * la session est enregistrée et `SIGNED_IN` est émis ; sinon la réponse est un défi MFA (voir `isMfaChallenge`).
+     */
     signUp(req: SignUpRequest): Promise<AuraResponse<LoginResponse>>;
+    /**
+     * Connecte un utilisateur par e-mail et mot de passe. Enregistre la session et émet `SIGNED_IN` ;
+     * si le MFA est actif, renvoie un défi (`isMfaChallenge`) à compléter par `mfaVerify`.
+     */
     signInWithPassword(req: SignInRequest): Promise<AuraResponse<LoginResponse>>;
     /**
      * Démarre un flux OAuth : renvoie toujours `{ url }` (et redirige en plus le navigateur
      * si un `window` existe).
      *
+     * Accepte indifféremment la signature canonique :
+     * `signInWithOAuth('google', { redirectTo })`
+     * ou la signature objet compatible Supabase :
+     * `signInWithOAuth({ provider: 'google', options: { redirectTo } })`
+     *
      * ### `options.queryParams` — contrat (N22)
      *
      * Les clés listées par {@link OAUTH_FORWARDABLE_QUERY_PARAMS} — `prompt`, `login_hint`,
@@ -248,11 +298,27 @@ declare class AuthService extends BaseService {
     signInWithOAuth(provider: string, options?: OAuthSignInOptions): Promise<AuraResponse<{
         url: string;
     }>>;
+    signInWithOAuth(options: OAuthSignInObjectOptions): Promise<AuraResponse<{
+        url: string;
+    }>>;
+    /**
+     * Envoie un lien de connexion par e-mail (« magic link »). La session s'obtient ensuite par `verifyOtp({ type: 'magiclink' })`.
+     */
     signInWithMagicLink(req: MagicLinkRequest): Promise<AuraResponse<{
         message: string;
     }>>;
+    /**
+     * Crée une session anonyme (utilisateur sans e-mail), enregistrée et signalée par `SIGNED_IN`.
+     */
     signInAnonymously(): Promise<AuraResponse<TokenPair>>;
+    /**
+     * Déconnecte : révoque le jeton de rafraîchissement côté serveur s'il existe, vide la session locale et émet `SIGNED_OUT`.
+     */
     signOut(): Promise<AuraResponse<null>>;
+    /**
+     * Rafraîchit la session avec le jeton de rafraîchissement et émet `TOKEN_REFRESHED`.
+     * Les rafraîchissements concurrents sont fusionnés en un seul appel.
+     */
     refreshSession(): Promise<AuraResponse<TokenPair>>;
     /**
      * Session courante lue depuis le store (synchrone en pratique, pas d'appel réseau).
@@ -270,6 +336,10 @@ declare class AuthService extends BaseService {
         access_token: string | null;
         user: User | null;
     }>;
+    /**
+     * Installe une session à partir d'un jeton d'accès et d'un jeton de rafraîchissement existants (par exemple reçus d'un serveur).
+     * Un jeton d'accès expiré est rafraîchi ; une session invalide est refusée et l'état précédent est restauré.
+     */
     setSession(accessToken: string, refreshToken: string): Promise<AuraResponse<User>>;
     /**
      * Échange le code d'autorisation PKCE contre une session.
@@ -288,8 +358,15 @@ declare class AuthService extends BaseService {
      * récupération de mot de passe, `?code=…&type=recovery` — voir `_detectSessionInUrl`).
      */
     private _exchangeCode;
+    /**
+     * Liste les sessions de l'utilisateur connecté (appareil, adresse IP, dates) ; `is_current` repère la session courante.
+     */
     listSessions(): Promise<AuraResponse<SessionInfo[]>>;
+    /** Révoque une session de l'utilisateur connecté par son identifiant. */
     revokeSession(sessionId: string): Promise<AuraResponse<null>>;
+    /**
+     * Déconnecte l'utilisateur partout : révoque toutes ses sessions, vide la session locale et émet `SIGNED_OUT`.
+     */
     revokeAllSessions(): Promise<AuraResponse<{
         message: string;
     }>>;
@@ -304,7 +381,9 @@ declare class AuthService extends BaseService {
      * (`skipAuthRefresh`, aucun refresh ni retry-401 sur le store). Le backend
      * applique l'isolation projet native : un token d'un AUTRE projet → 403.
      */
-    getUser(jwt?: string): Promise<AuraResponse<User>>;
+    getUser(jwt?: string): Promise<AuraResponse<User & {
+        user: User;
+    }>>;
     /**
      * Vérifie et décode les claims d'un JWT.
      *
@@ -335,17 +414,59 @@ declare class AuthService extends BaseService {
         issuer?: string;
         audience?: string;
     }): Promise<AuraResponse<GetClaimsResult>>;
+    /**
+     * Supprime le compte de l'utilisateur connecté après confirmation par son mot de passe, puis vide la session locale.
+     */
     deleteUser(password: string): Promise<AuraResponse<null>>;
+    /**
+     * Met à jour l'utilisateur connecté (métadonnées, mot de passe…) et émet `USER_UPDATED`. Un changement d'e-mail ne prend effet qu'après confirmation par `verifyOtp({ type: 'email_change' })`.
+     */
     updateUser(req: UpdateUserRequest): Promise<AuraResponse<User>>;
-    resetPasswordForEmail(req: PasswordResetRequest): Promise<AuraResponse<{
+    /** Envoie un e-mail de réinitialisation du mot de passe (accepte un email sous forme de chaîne ou un objet PasswordResetRequest). */
+    resetPasswordForEmail(emailOrReq: string | PasswordResetRequest): Promise<AuraResponse<{
         message: string;
     }>>;
+    /**
+     * Change le mot de passe de l'utilisateur connecté. Le serveur révoque toutes ses sessions : le SDK vide la session locale et émet `SIGNED_OUT`.
+     */
     updatePassword(newPassword: string, currentPassword?: string): Promise<AuraResponse<User>>;
+    /**
+     * Façade unifiée pour les opérations MFA (TOTP).
+     * Permet d'appeler indifféremment `aura.auth.mfa.enroll()` ou `aura.auth.mfaEnroll()`.
+     */
+    get mfa(): {
+        enroll: (params?: {
+            factor_type?: 'totp';
+            factorType?: 'totp';
+        }) => Promise<AuraResponse<MfaEnrollResponse>>;
+        verifySetup: (codeOrParams: string | {
+            code: string;
+        }) => Promise<AuraResponse<{
+            recovery_codes: string[];
+        }>>;
+        verify: (req: MfaVerifyRequest) => Promise<AuraResponse<TokenPair>>;
+        unenroll: (passwordOrParams: string | {
+            password: string;
+        }) => Promise<AuraResponse<{
+            message: string;
+        }>>;
+        regenerateRecoveryCodes: (codeOrParams: string | {
+            code: string;
+        }) => Promise<AuraResponse<{
+            recovery_codes: string[];
+        }>>;
+    };
+    /** MFA : démarre l'enrôlement TOTP et renvoie le `secret` et l'URL `otpauth_url` à afficher en QR code. */
     mfaEnroll(): Promise<AuraResponse<MfaEnrollResponse>>;
+    /** MFA : confirme l'enrôlement avec un premier code et renvoie les codes de récupération. */
     mfaVerifySetup(code: string): Promise<AuraResponse<{
         recovery_codes: string[];
     }>>;
+    /**
+     * MFA : termine une connexion qui a renvoyé un défi (`mfa_token` et code TOTP). Enregistre la session et émet `SIGNED_IN`.
+     */
     mfaVerify(req: MfaVerifyRequest): Promise<AuraResponse<TokenPair>>;
+    /** MFA : désactive le MFA après confirmation par le mot de passe. */
     mfaUnenroll(password: string): Promise<AuraResponse<{
         message: string;
     }>>;
@@ -378,23 +499,34 @@ declare class AuthService extends BaseService {
      * l'endpoint, puis (succès) sauvegarde la session et émet `SIGNED_IN`.
      */
     private _verifyToTokenPair;
+    /** Renvoie l'e-mail de vérification, à `email` ou à l'adresse de l'utilisateur connecté. */
     resendVerificationEmail(email?: string): Promise<AuraResponse<{
         message: string;
     }>>;
+    /**
+     * Envoie un code à usage unique par e-mail ; à confirmer par `verifyOtp({ type: 'email' })`.
+     */
     signInWithEmailOtp(email: string): Promise<AuraResponse<{
         message: string;
     }>>;
+    /** Envoie un code à usage unique par SMS ; à confirmer par `verifyOtp({ type: 'sms' })`. */
     signInWithSmsOtp(phone: string): Promise<AuraResponse<{
         message: string;
     }>>;
+    /** Liste les identités (fournisseurs) liées à l'utilisateur connecté. */
     listIdentities(): Promise<AuraResponse<IdentityInfo[]>>;
+    /**
+     * Démarre la liaison d'un fournisseur OAuth au compte connecté et renvoie l'URL d'autorisation à ouvrir.
+     */
     linkIdentity(provider: string): Promise<AuraResponse<{
         url: string;
         provider: string;
     }>>;
+    /** Détache une identité du compte connecté par son identifiant. */
     unlinkIdentity(identityId: string): Promise<AuraResponse<{
         message: string;
     }>>;
+    /** MFA : régénère les codes de récupération après confirmation par un code TOTP. */
     regenerateRecoveryCodes(code: string): Promise<AuraResponse<{
         recovery_codes: string[];
     }>>;