@aurabase/auth 0.6.0 → 0.6.1

package/dist/index.cjs

@@ -13,6 +13,9 @@ var AuthAdminService = class extends core.BaseService {
     return "/v1/auth/admin";
   }
   // -- Users ----------------------------------------------------------------
+  /**
+   * Liste les utilisateurs du projet, avec recherche (`search`) et pagination (`limit`, `offset`).
+   */
   async listUsers(params) {
     const query = new URLSearchParams();
     if (params?.limit !== void 0) query.set("limit", String(params.limit));
@@ -21,34 +24,52 @@ var AuthAdminService = class extends core.BaseService {
     const qs = query.toString();
     return this.request("GET", `${this.prefix}/users${qs ? "?" + qs : ""}`);
   }
+  /** Lit un utilisateur par son identifiant. */
   async getUser(userId) {
     return this.request("GET", `${this.prefix}/users/${userId}`);
   }
+  /**
+   * Crée un utilisateur sans passer par l'inscription publique (e-mail, mot de passe, métadonnées, rôle).
+   */
   async createUser(data) {
     return this.request("POST", `${this.prefix}/users`, data);
   }
+  /** Met à jour un utilisateur : seuls les champs fournis changent. */
   async updateUser(userId, data) {
     return this.request("PUT", `${this.prefix}/users/${userId}`, data);
   }
+  /** Supprime un utilisateur. */
   async deleteUser(userId) {
     return this.request("DELETE", `${this.prefix}/users/${userId}`);
   }
+  /** Bannit un utilisateur : il ne peut plus se connecter. */
   async banUser(userId) {
     return this.request("POST", `${this.prefix}/users/${userId}/ban`, {});
   }
+  /** Lève le bannissement d'un utilisateur. */
   async unbanUser(userId) {
     return this.request("POST", `${this.prefix}/users/${userId}/unban`, {});
   }
+  /**
+   * Génère un lien à usage unique pour un utilisateur (`'magic'`, `'recovery'` ou `'invite'`) et renvoie `{ link, token }`.
+   */
   async generateLink(userId, type) {
     return this.request("POST", `${this.prefix}/users/${userId}/generate-link`, { type });
   }
+  /**
+   * Statistiques des utilisateurs : total, vérifiés, bannis, avec MFA et nouveaux sur 7 jours.
+   */
   async getUserStats() {
     return this.request("GET", `${this.prefix}/users/stats`);
   }
+  /** Liste les identités liées à un utilisateur (fournisseurs OAuth, e-mail). */
   async listUserIdentities(userId) {
     return this.request("GET", `${this.prefix}/users/${userId}/identities`);
   }
   // -- Sessions ---------------------------------------------------------------
+  /**
+   * Liste les sessions actives de tous les utilisateurs, filtrables par `userId`, avec pagination.
+   */
   async listSessions(params) {
     const query = new URLSearchParams();
     if (params?.userId !== void 0) query.set("user_id", params.userId);
@@ -57,10 +78,14 @@ var AuthAdminService = class extends core.BaseService {
     const qs = query.toString();
     return this.request("GET", `${this.prefix}/sessions${qs ? "?" + qs : ""}`);
   }
+  /** Révoque une session par son identifiant. */
   async revokeSession(sessionId) {
     return this.request("DELETE", `${this.prefix}/sessions/${sessionId}`);
   }
   // -- Audit log ------------------------------------------------------------
+  /**
+   * Lit le journal d'audit (action, adresse IP, agent utilisateur, date), filtrable par `userId`, avec pagination.
+   */
   async getAuditLog(params) {
     const query = new URLSearchParams();
     if (params?.userId !== void 0) query.set("user_id", params.userId);
@@ -70,6 +95,9 @@ var AuthAdminService = class extends core.BaseService {
     return this.request("GET", `${this.prefix}/audit-log${qs ? "?" + qs : ""}`);
   }
   // -- Settings -------------------------------------------------------------
+  /**
+   * Lit les réglages d'authentification du projet. Les secrets (mot de passe SMTP, clés) ne sont jamais renvoyés.
+   */
   async getSettings() {
     return this.request("GET", `${this.prefix}/settings`);
   }
@@ -92,18 +120,23 @@ var AuthAdminService = class extends core.BaseService {
     return this.request("PUT", `${this.prefix}/settings`, data);
   }
   // -- Email templates ------------------------------------------------------
+  /** Liste les modèles d'e-mail d'authentification du projet. */
   async listEmailTemplates() {
     return this.request("GET", `${this.prefix}/email-templates`);
   }
+  /** Lit le modèle d'e-mail d'un type donné (par exemple confirmation, récupération). */
   async getEmailTemplate(type) {
     return this.request("GET", `${this.prefix}/email-templates/${type}`);
   }
+  /** Remplace le contenu du modèle d'e-mail d'un type donné. */
   async updateEmailTemplate(type, data) {
     return this.request("PUT", `${this.prefix}/email-templates/${type}`, data);
   }
+  /** Supprime le modèle personnalisé d'un type d'e-mail. */
   async deleteEmailTemplate(type) {
     return this.request("DELETE", `${this.prefix}/email-templates/${type}`);
   }
+  /** Envoie un e-mail de test avec le modèle d'un type à l'adresse `to_email`. */
   async testEmailTemplate(type, body) {
     return this.request("POST", `${this.prefix}/email-templates/${type}/test`, body);
   }
@@ -632,6 +665,10 @@ var AuthService = class extends core.BaseService {
     return `aura-${core.clientScope(this.client.baseUrl)}-oauth-implicit-initiated`;
   }
   // -- Auth state change ------------------------------------------------------
+  /**
+   * É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) {
     const unsub = () => {
       this._stateListeners.delete(callback);
@@ -681,8 +718,24 @@ var AuthService = class extends core.BaseService {
     }
   }
   // -- Sign up / sign in / sign out -------------------------------------------
+  /**
+   * 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`).
+   */
   async signUp(req) {
-    const res = await this.request("POST", `${this.prefix}/register`, req);
+    const payload = {
+      email: req.email,
+      password: req.password
+    };
+    if (req.captcha_token) payload.captcha_token = req.captcha_token;
+    if (req.name) {
+      payload.name = req.name;
+    } else if (req.options?.data && typeof req.options.data.name === "string") {
+      payload.name = req.options.data.name;
+    }
+    if (req.options?.data) payload.data = req.options.data;
+    if (req.options?.emailRedirectTo) payload.email_redirect_to = req.options.emailRedirectTo;
+    const res = await this.request("POST", `${this.prefix}/register`, payload);
     if (res.data && !isMfaChallenge(res.data)) {
       const tp = res.data;
       tp.accessToken = tp.access_token;
@@ -715,8 +768,18 @@ var AuthService = class extends core.BaseService {
     }
     return res;
   }
+  /**
+   * 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`.
+   */
   async signInWithPassword(req) {
-    const res = await this.request("POST", `${this.prefix}/login`, req);
+    const payload = {
+      email: req.email,
+      password: req.password
+    };
+    if (req.captcha_token) payload.captcha_token = req.captcha_token;
+    if (req.mfa) payload.mfa = req.mfa;
+    const res = await this.request("POST", `${this.prefix}/login`, payload);
     if (res.data && !isMfaChallenge(res.data)) {
       const tp = res.data;
       tp.accessToken = tp.access_token;
@@ -749,37 +812,32 @@ var AuthService = class extends core.BaseService {
     }
     return res;
   }
-  /**
-   * Démarre un flux OAuth : renvoie toujours `{ url }` (et redirige en plus le navigateur
-   * si un `window` existe).
-   *
-   * ### `options.queryParams` — contrat (N22)
-   *
-   * Les clés listées par {@link OAUTH_FORWARDABLE_QUERY_PARAMS} — `prompt`, `login_hint`,
-   * `display`, `ui_locales`, `max_age`, `acr_values`, `claims_locales`, `access_type`,
-   * `include_granted_scopes`, `hd` — sont **réellement transmises au provider**, jusque
-   * dans l'URL d'autorisation.
-   *
-   * Toute autre clé est **refusée** : la méthode renvoie
-   * `error.code === 'invalid_oauth_query_param'` et n'amorce aucune redirection. Rien
-   * n'est jamais accepté puis jeté en silence. Sont notamment refusés :
-   * - les paramètres du protocole (`state`, `nonce`, `client_id`, `response_type`,
-   *   `scope`, `code_challenge`…) — ils sont calculés par le serveur ;
-   * - les paramètres construits par cette méthode (`redirect_uri`, `scopes`) — passez par
-   *   `redirectTo`, `scopes` ou `flowType` ;
-   * - `project_id` : le projet est porté par l'URL du client, jamais par un paramètre ;
-   * - les variantes de casse (`Prompt`, `State`) et les clés inconnues.
-   *
-   * L'autorité est le **backend** (`OAUTH_FORWARDABLE_PARAMS` de
-   * `services/aura-auth/src/handlers/oauth.rs`), qui répond `400` sur les mêmes règles :
-   * l'endpoint de démarrage est public et appelable sans SDK. Ce filtre-ci n'est que son
-   * miroir, pour échouer avant la redirection ; un test de parité interdit qu'ils divergent.
-   *
-   * Les **valeurs**, elles, ne sont validées que par le backend (non vide, sans caractère
-   * de contrôle, 512 caractères au plus, jamais deux fois la même clé) — un manquement
-   * donne un `400` au démarrage du flux, pas une erreur de cette méthode.
-   */
-  async signInWithOAuth(provider, options) {
+  async signInWithOAuth(providerOrOptions, rawOptions) {
+    let provider;
+    let options;
+    if (typeof providerOrOptions === "object" && providerOrOptions !== null) {
+      provider = providerOrOptions.provider;
+      const nestedOptions = providerOrOptions.options;
+      options = {
+        ...providerOrOptions,
+        ...nestedOptions,
+        ...rawOptions
+      };
+    } else {
+      provider = providerOrOptions;
+      options = rawOptions;
+    }
+    if (typeof provider !== "string" || provider.trim() === "") {
+      return {
+        data: null,
+        error: new core.AuraError(0, {
+          error: {
+            code: "invalid_provider",
+            message: "signInWithOAuth: le fournisseur doit \xEAtre une cha\xEEne non vide, par exemple signInWithOAuth('google', { redirectTo }) ou signInWithOAuth({ provider: 'google', redirectTo })"
+          }
+        })
+      };
+    }
     const params = new URLSearchParams();
     if (options?.redirectTo) params.set("redirect_uri", options.redirectTo);
     if (options?.scopes) params.set("scopes", options.scopes);
@@ -841,9 +899,15 @@ var AuthService = class extends core.BaseService {
     }
     return { data: { url }, error: null };
   }
+  /**
+   * Envoie un lien de connexion par e-mail (« magic link »). La session s'obtient ensuite par `verifyOtp({ type: 'magiclink' })`.
+   */
   async signInWithMagicLink(req) {
     return this.request("POST", `${this.prefix}/magic-link`, req);
   }
+  /**
+   * Crée une session anonyme (utilisateur sans e-mail), enregistrée et signalée par `SIGNED_IN`.
+   */
   async signInAnonymously() {
     const res = await this.request("POST", `${this.prefix}/anonymous`);
     if (res.data) {
@@ -852,6 +916,9 @@ var AuthService = class extends core.BaseService {
     }
     return res;
   }
+  /**
+   * Déconnecte : révoque le jeton de rafraîchissement côté serveur s'il existe, vide la session locale et émet `SIGNED_OUT`.
+   */
   async signOut() {
     const refreshToken = this.client.authStore.refreshToken;
     if (!refreshToken) {
@@ -872,6 +939,10 @@ var AuthService = class extends core.BaseService {
     return res;
   }
   // -- Session management -----------------------------------------------------
+  /**
+   * 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.
+   */
   async refreshSession() {
     const res = await core.refreshOnce(this.client);
     if (res.data) {
@@ -906,6 +977,10 @@ var AuthService = class extends core.BaseService {
       user
     });
   }
+  /**
+   * 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é.
+   */
   async setSession(accessToken, refreshToken) {
     const store = this.client.authStore;
     const prev = { token: store.token, refreshToken: store.refreshToken, user: store.user };
@@ -992,6 +1067,9 @@ var AuthService = class extends core.BaseService {
       this.client.authStore.removeItem(verifierKey);
     }
   }
+  /**
+   * Liste les sessions de l'utilisateur connecté (appareil, adresse IP, dates) ; `is_current` repère la session courante.
+   */
   async listSessions() {
     const store = this.client.authStore;
     if (store.token && store.refreshToken && !store.isValid) {
@@ -1005,9 +1083,13 @@ var AuthService = class extends core.BaseService {
       headers: refreshToken ? { "x-refresh-token": refreshToken } : void 0
     });
   }
+  /** Révoque une session de l'utilisateur connecté par son identifiant. */
   async revokeSession(sessionId) {
     return this.request("DELETE", `${this.prefix}/sessions/${sessionId}`);
   }
+  /**
+   * Déconnecte l'utilisateur partout : révoque toutes ses sessions, vide la session locale et émet `SIGNED_OUT`.
+   */
   async revokeAllSessions() {
     const rt = this.client.authStore.refreshToken;
     if (!rt) {
@@ -1188,6 +1270,9 @@ var AuthService = class extends core.BaseService {
       error: new core.AuraError(0, { error: { code: r.code, message: `getClaims: ${r.code}` } })
     };
   }
+  /**
+   * Supprime le compte de l'utilisateur connecté après confirmation par son mot de passe, puis vide la session locale.
+   */
   async deleteUser(password) {
     const res = await this.request("DELETE", `${this.prefix}/user`, { password });
     if (!res.error) {
@@ -1196,6 +1281,9 @@ var AuthService = class extends core.BaseService {
     }
     return res;
   }
+  /**
+   * 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' })`.
+   */
   async updateUser(req) {
     const res = await this.request("PUT", `${this.prefix}/user`, req);
     if (res.data) {
@@ -1208,9 +1296,13 @@ var AuthService = class extends core.BaseService {
     return res;
   }
   // -- Password recovery ------------------------------------------------------
+  /** Envoie un e-mail de réinitialisation du mot de passe. */
   async resetPasswordForEmail(req) {
     return this.request("POST", `${this.prefix}/forgot-password`, req);
   }
+  /**
+   * 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`.
+   */
   async updatePassword(newPassword, currentPassword) {
     const res = await this.request("PUT", `${this.prefix}/user`, {
       password: newPassword,
@@ -1223,12 +1315,39 @@ var AuthService = class extends core.BaseService {
     return res;
   }
   // -- MFA --------------------------------------------------------------------
+  /**
+   * 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() {
+    return {
+      enroll: () => this.mfaEnroll(),
+      verifySetup: (codeOrParams) => {
+        const code = typeof codeOrParams === "string" ? codeOrParams : codeOrParams.code;
+        return this.mfaVerifySetup(code);
+      },
+      verify: (req) => this.mfaVerify(req),
+      unenroll: (passwordOrParams) => {
+        const password = typeof passwordOrParams === "string" ? passwordOrParams : passwordOrParams.password;
+        return this.mfaUnenroll(password);
+      },
+      regenerateRecoveryCodes: (codeOrParams) => {
+        const code = typeof codeOrParams === "string" ? codeOrParams : codeOrParams.code;
+        return this.regenerateRecoveryCodes(code);
+      }
+    };
+  }
+  /** MFA : démarre l'enrôlement TOTP et renvoie le `secret` et l'URL `otpauth_url` à afficher en QR code. */
   async mfaEnroll() {
     return this.request("POST", `${this.prefix}/mfa/setup`);
   }
+  /** MFA : confirme l'enrôlement avec un premier code et renvoie les codes de récupération. */
   async mfaVerifySetup(code) {
     return this.request("POST", `${this.prefix}/mfa/setup/verify`, { code });
   }
+  /**
+   * MFA : termine une connexion qui a renvoyé un défi (`mfa_token` et code TOTP). Enregistre la session et émet `SIGNED_IN`.
+   */
   async mfaVerify(req) {
     const res = await this.request("POST", `${this.prefix}/mfa/verify-login`, req);
     if (res.data) {
@@ -1237,6 +1356,7 @@ var AuthService = class extends core.BaseService {
     }
     return res;
   }
+  /** MFA : désactive le MFA après confirmation par le mot de passe. */
   async mfaUnenroll(password) {
     return this.request("POST", `${this.prefix}/mfa/disable`, { password });
   }
@@ -1308,6 +1428,7 @@ var AuthService = class extends core.BaseService {
     return res;
   }
   // -- Email verification -----------------------------------------------------
+  /** Renvoie l'e-mail de vérification, à `email` ou à l'adresse de l'utilisateur connecté. */
   async resendVerificationEmail(email) {
     const e = email ?? this.client.authStore.user?.email;
     if (!e) {
@@ -1319,24 +1440,34 @@ var AuthService = class extends core.BaseService {
     return this.request("POST", `${this.prefix}/resend-verification`, { email: e });
   }
   // -- Email OTP (Phase 2) --------------------------------------------------
+  /**
+   * Envoie un code à usage unique par e-mail ; à confirmer par `verifyOtp({ type: 'email' })`.
+   */
   async signInWithEmailOtp(email) {
     return this.request("POST", `${this.prefix}/email-otp/send`, { email });
   }
   // -- SMS OTP (Phase 2) ----------------------------------------------------
+  /** Envoie un code à usage unique par SMS ; à confirmer par `verifyOtp({ type: 'sms' })`. */
   async signInWithSmsOtp(phone) {
     return this.request("POST", `${this.prefix}/sms/send`, { phone });
   }
   // -- Identity linking (Phase 2) -------------------------------------------
+  /** Liste les identités (fournisseurs) liées à l'utilisateur connecté. */
   async listIdentities() {
     return this.request("GET", `${this.prefix}/user/identities`);
   }
+  /**
+   * Démarre la liaison d'un fournisseur OAuth au compte connecté et renvoie l'URL d'autorisation à ouvrir.
+   */
   async linkIdentity(provider) {
     return this.request("POST", `${this.prefix}/user/identities/link/${provider}`);
   }
+  /** Détache une identité du compte connecté par son identifiant. */
   async unlinkIdentity(identityId) {
     return this.request("DELETE", `${this.prefix}/user/identities/${identityId}`);
   }
   // -- MFA recovery codes (Phase 2) -----------------------------------------
+  /** MFA : régénère les codes de récupération après confirmation par un code TOTP. */
   async regenerateRecoveryCodes(code) {
     return this.request("POST", `${this.prefix}/mfa/recovery-codes/regenerate`, { code });
   }