@aurabase/auth 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -1,16 +1,85 @@
-import { BaseService, AuraClientLike, AuthChangePayload, SignUpRequest, AuraResponse, LoginResponse, SignInRequest, OAuthSignInOptions, MagicLinkRequest, TokenPair, User, SessionInfo, GetClaimsResult, UpdateUserRequest, PasswordResetRequest, MfaEnrollResponse, MfaVerifyRequest, IdentityInfo, MfaChallenge, AdminUser, AdminCreateUserRequest, AdminUpdateUserRequest, GenerateLinkType, GenerateLinkResult, UserStats, AdminSessionInfo, AuditLogEntry, AuthSettings, EmailTemplateUpdate } from '@aurabase/core';
+import { BaseService, AuraResponse, AdminUser, AdminCreateUserRequest, AdminUpdateUserRequest, GenerateLinkType, GenerateLinkResult, UserStats, IdentityInfo, AdminSessionInfo, AuditLogEntry, AuthSettings, AuthSettingsUpdate, EmailTemplateUpdate, AuraClientLike, AuthChangePayload, SignUpRequest, LoginResponse, SignInRequest, OAuthSignInOptions, MagicLinkRequest, TokenPair, User, SessionInfo, GetClaimsResult, UpdateUserRequest, PasswordResetRequest, MfaEnrollResponse, MfaVerifyRequest, MfaChallenge } from '@aurabase/core';
+
+declare class AuthAdminService extends BaseService {
+    /**
+     * Préfixe des routes de ce service. Aucun identifiant de projet : il est injecté par
+     * la passerelle depuis le sous-domaine du projet (`inject_project_id`,
+     * `services/aura-gateway/src/middleware/project_subdomain.rs`).
+     */
+    private get prefix();
+    listUsers(params?: {
+        limit?: number;
+        offset?: number;
+        search?: string;
+    }): Promise<AuraResponse<AdminUser[]>>;
+    getUser(userId: string): Promise<AuraResponse<AdminUser>>;
+    createUser(data: AdminCreateUserRequest): Promise<AuraResponse<AdminUser>>;
+    updateUser(userId: string, data: AdminUpdateUserRequest): Promise<AuraResponse<AdminUser>>;
+    deleteUser(userId: string): Promise<AuraResponse<null>>;
+    banUser(userId: string): Promise<AuraResponse<null>>;
+    unbanUser(userId: string): Promise<AuraResponse<null>>;
+    generateLink(userId: string, type: GenerateLinkType): Promise<AuraResponse<GenerateLinkResult>>;
+    getUserStats(): Promise<AuraResponse<UserStats>>;
+    listUserIdentities(userId: string): Promise<AuraResponse<IdentityInfo[]>>;
+    listSessions(params?: {
+        userId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<AuraResponse<AdminSessionInfo[]>>;
+    revokeSession(sessionId: string): Promise<AuraResponse<null>>;
+    getAuditLog(params?: {
+        userId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<AuraResponse<AuditLogEntry[]>>;
+    getSettings(): Promise<AuraResponse<AuthSettings>>;
+    /**
+     * Met à jour les réglages auth du projet (fusion partielle : seuls les champs fournis
+     * sont écrits, `COALESCE` côté backend).
+     *
+     * Le corps est un {@link AuthSettingsUpdate}, PAS un `Partial<AuthSettings>` : la vue de
+     * lecture ne sait pas porter les secrets write-only (`smtp_password`, `webhook_secret`,
+     * `captcha_secret_key`, `sms_api_key`/`sms_api_secret`, `hook_secret`) ni les drapeaux
+     * d'effacement (`smtp_clear`, `sms_clear`, `oauth_credentials_clear`), et porte à l'inverse
+     * des projections (`smtp_password_set`, `hook_secret_set`, `updated_at`…) que le backend
+     * REFUSE.
+     *
+     * Le serveur refuse aussi bien un champ inconnu qu'un `null` explicite — `400` dans les deux
+     * cas, le champ fautif est nommé. Ce n'est plus seulement un contrôle TypeScript : ne
+     * renvoyez donc pas tel quel un objet lu par {@link getSettings}.
+     */
+    updateSettings(data: AuthSettingsUpdate): Promise<AuraResponse<AuthSettings>>;
+    listEmailTemplates(): Promise<AuraResponse<Record<string, unknown>[]>>;
+    getEmailTemplate(type: string): Promise<AuraResponse<Record<string, unknown>>>;
+    updateEmailTemplate(type: string, data: EmailTemplateUpdate): Promise<AuraResponse<Record<string, unknown>>>;
+    deleteEmailTemplate(type: string): Promise<AuraResponse<{
+        message: string;
+    }>>;
+    testEmailTemplate(type: string, body: {
+        to_email: string;
+    }): Promise<AuraResponse<null>>;
+}
 
 /**
- * Types d'OTP « email » (parité `EmailOtpType` de supabase-js). Tous ne sont pas
- * exercables côté backend Aurabase : `invite` n'a aucun endpoint (→ `verifyOtp`
- * lève `otp_type_unsupported`). Conservé dans l'union pour la parité de surface.
+ * Types d'OTP « email » — ceux qu'Aurabase EXERCE réellement.
+ *
+ * F4 — `invite` a été RETIRÉ. Il n'a jamais eu d'endpoint de vérification côté backend
+ * (`services/aura-auth/src/main.rs` ne déclare ni `/invite` ni équivalent) : il n'était
+ * présent que « pour la parité de surface » avec supabase-js, et `verifyOtp` y répondait
+ * `otp_type_unsupported`. Une surface qui ne mène nulle part n'est pas de la parité, c'est
+ * une promesse fausse que le typage rendait crédible : elle a été supprimée.
+ *
+ * À ne pas confondre avec {@link GenerateLinkType} (`@aurabase/core`), où `invite` est bien
+ * servi — mais par l'API ADMIN (`POST /admin/users/{id}/generate-link`,
+ * `aura-auth/src/handlers/admin.rs`), qui ÉMET un lien ; c'est sa CONSOMMATION en OTP qui
+ * n'existe pas.
  */
-type EmailOtpType = 'signup' | 'invite' | 'magiclink' | 'recovery' | 'email_change' | 'email';
+type EmailOtpType = 'signup' | 'magiclink' | 'recovery' | 'email_change' | 'email';
 /**
- * Types d'OTP « mobile » (parité `MobileOtpType` de supabase-js). `phone_change`
- * n'a aucun endpoint backend (→ `otp_type_unsupported`).
+ * Types d'OTP « mobile ». F4 — `phone_change` a été RETIRÉ pour la même raison
+ * qu'`invite` : aucun endpoint backend, donc aucune vérification possible.
  */
-type MobileOtpType = 'sms' | 'phone_change';
+type MobileOtpType = 'sms';
 interface VerifySignupOtpParams {
     type: 'signup';
     /** Jeton reçu par email (lien de confirmation d'inscription). */
@@ -49,24 +118,13 @@ interface VerifyRecoveryOtpParams {
      */
     password: string;
 }
-/** Type de surface (parité) sans endpoint backend → `otp_type_unsupported`. */
-interface VerifyInviteOtpParams {
-    type: 'invite';
-    token: string;
-}
-/** Type de surface (parité) sans endpoint backend → `otp_type_unsupported`. */
-interface VerifyPhoneChangeOtpParams {
-    type: 'phone_change';
-    phone: string;
-    token: string;
-}
 /**
- * Union discriminée par `type` de la façade `verifyOtp` (parité surface
- * `@supabase/auth-js`). Chaque variante route vers l'endpoint historique
- * correspondant. `invite`/`phone_change` restent dans l'union pour la parité
- * mais lèvent `otp_type_unsupported` tant que le backend ne les expose pas.
+ * Union discriminée par `type` de la façade `verifyOtp`. Chaque variante route vers un
+ * endpoint qui EXISTE — l'union est la liste de ce que le produit sait faire, pas celle de
+ * ce qu'un autre produit expose (F4 : `invite` et `phone_change` en ont été retirés, faute
+ * d'endpoint de vérification côté backend).
  */
-type VerifyOtpParams = VerifySignupOtpParams | VerifyMagiclinkOtpParams | VerifyEmailOtpParams | VerifySmsOtpParams | VerifyEmailChangeOtpParams | VerifyRecoveryOtpParams | VerifyInviteOtpParams | VerifyPhoneChangeOtpParams;
+type VerifyOtpParams = VerifySignupOtpParams | VerifyMagiclinkOtpParams | VerifyEmailOtpParams | VerifySmsOtpParams | VerifyEmailChangeOtpParams | VerifyRecoveryOtpParams;
 
 type AuthStateCallback = (payload: AuthChangePayload) => void;
 interface AuthServiceOptions {
@@ -98,6 +156,9 @@ declare class AuthService extends BaseService {
      * 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`.
+     *  - fragment `#mfa_token=…` (atterrissage `{redirectTo}/oauth/mfa` d'un utilisateur MFA au
+     *    retour d'OAuth) → émet `MFA_CHALLENGE` avec `mfaToken` (AUCUNE session posée : le défi
+     *    reste à relever via `mfaVerify`).
      *  - 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).
@@ -117,8 +178,23 @@ declare class AuthService extends BaseService {
     private _applyRemoteState;
     /** Démonte le cycle de vie proactif : ticker, visibilité, BroadcastChannel, listeners. */
     dispose(): void;
+    /**
+     * Préfixe des routes de ce service. Aucun identifiant de projet : il est injecté par
+     * la passerelle depuis le sous-domaine du projet (`inject_project_id`,
+     * `services/aura-gateway/src/middleware/project_subdomain.rs`).
+     */
     private get prefix();
-    /** Clé project-scoped du `code_verifier` PKCE (anti-collision multi-projets). */
+    /**
+     * `project_id` de la SESSION en cours, lu dans le token stocké — seule référence de projet
+     * dont dispose encore le client (voir SEC-F2 dans `getClaims`). `null` s'il n'y a pas de
+     * session, si le token est illisible, ou s'il ne porte pas ce claim.
+     */
+    private _sessionProjectId;
+    /**
+     * Clé du `code_verifier` PKCE, scopée par la PORTÉE du client (`clientScope`, dérivée de
+     * l'URL du projet) : deux clients de deux projets instanciés dans la MÊME page partagent
+     * un seul `localStorage`, et ne doivent pas se marcher dessus.
+     */
     private get _pkceVerifierKey();
     /**
      * Clé project-scoped du MARQUEUR d'initiation du flux OAuth implicit (SEC-F3).
@@ -134,6 +210,36 @@ declare class AuthService extends BaseService {
     private _emitEvent;
     signUp(req: SignUpRequest): Promise<AuraResponse<LoginResponse>>;
     signInWithPassword(req: SignInRequest): Promise<AuraResponse<LoginResponse>>;
+    /**
+     * 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.
+     */
     signInWithOAuth(provider: string, options?: OAuthSignInOptions): Promise<AuraResponse<{
         url: string;
     }>>;
@@ -163,7 +269,17 @@ declare class AuthService extends BaseService {
         user: User | null;
     }>;
     setSession(accessToken: string, refreshToken: string): Promise<AuraResponse<User>>;
-    exchangeCodeForSession(authCode: string, codeVerifier?: string): Promise<AuraResponse<TokenPair>>;
+    /**
+     * Échange le code d'autorisation PKCE contre une session.
+     *
+     * Renvoie un `LoginResponse`, PAS un `TokenPair` : si l'utilisateur a le MFA actif, le
+     * backend répond `{ mfa_required: true, mfa_token }` (gate « C1-bis » de
+     * `POST /oauth/pkce`) au lieu d'une paire de jetons. Dans ce cas AUCUNE session n'est
+     * enregistrée et `MFA_CHALLENGE` est émis avec le `mfaToken` : l'application demande le
+     * code TOTP puis appelle `mfaVerify({ mfa_token, code })`. Discriminez avec
+     * {@link isMfaChallenge}.
+     */
+    exchangeCodeForSession(authCode: string, codeVerifier?: string): Promise<AuraResponse<LoginResponse>>;
     /**
      * 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
@@ -232,11 +348,9 @@ declare class AuthService extends BaseService {
         message: string;
     }>>;
     /**
-     * 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.
+     * Point d'entrée UNIQUE de la vérification OTP (parité `verifyOtp` de `@supabase/auth-js`).
+     * Route vers l'endpoint correct selon `params.type`, en conservant l'effet de bord
+     * (sauvegarde de session + émission d'événement).
      *
      * Mapping :
      *  - `signup`       → POST /verify-email            `{ token }`         → SIGNED_IN
@@ -249,9 +363,11 @@ declare class AuthService extends BaseService {
      * 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.
+     *  - F4 : `invite` et `phone_change` ont été RETIRÉS de la surface. Ils n'ont jamais eu
+     *    d'endpoint de vérification côté backend et ne pouvaient que rendre
+     *    `otp_type_unsupported` ; le `default` ci-dessous couvre désormais toute valeur
+     *    inconnue reçue d'un appelant JavaScript non typé.
+     *  - `email_change` renvoie un `User` (pas une `TokenPair`) et émet `USER_UPDATED`.
      */
     verifyOtp(params: VerifyEmailChangeOtpParams): Promise<AuraResponse<User>>;
     verifyOtp(params: Exclude<VerifyOtpParams, VerifyEmailChangeOtpParams>): Promise<AuraResponse<TokenPair>>;
@@ -260,21 +376,15 @@ declare class AuthService extends BaseService {
      * l'endpoint, puis (succès) sauvegarde la session et émet `SIGNED_IN`.
      */
     private _verifyToTokenPair;
-    /** Rétrocompat : délègue à `verifyOtp({ type: 'signup' })` (POST /verify-email). */
-    verifyEmail(token: string): Promise<AuraResponse<TokenPair>>;
     resendVerificationEmail(email?: string): Promise<AuraResponse<{
         message: string;
     }>>;
     signInWithEmailOtp(email: string): Promise<AuraResponse<{
         message: string;
     }>>;
-    /** Rétrocompat : délègue à `verifyOtp({ type: 'email' })` (POST /email-otp/verify). */
-    verifyEmailOtp(email: string, code: string): Promise<AuraResponse<TokenPair>>;
     signInWithSmsOtp(phone: string): Promise<AuraResponse<{
         message: string;
     }>>;
-    /** Rétrocompat : délègue à `verifyOtp({ type: 'sms' })` (POST /sms/verify). */
-    verifySmsOtp(phone: string, code: string): Promise<AuraResponse<TokenPair>>;
     listIdentities(): Promise<AuraResponse<IdentityInfo[]>>;
     linkIdentity(provider: string): Promise<AuraResponse<{
         url: string;
@@ -283,16 +393,18 @@ declare class AuthService extends BaseService {
     unlinkIdentity(identityId: string): Promise<AuraResponse<{
         message: string;
     }>>;
-    /**
-     * Rétrocompat : délègue à `verifyOtp({ type: 'email_change' })`.
-     * CHANGEMENT ASSUMÉ (parité) : émet désormais `USER_UPDATED` (auparavant aucun
-     * événement) — voir CHANGELOG.
-     */
-    confirmEmailChange(token: string): Promise<AuraResponse<User>>;
     regenerateRecoveryCodes(code: string): Promise<AuraResponse<{
         recovery_codes: string[];
     }>>;
-    signInWithIdToken(provider: string, idToken: string, accessToken?: string): Promise<AuraResponse<TokenPair>>;
+    /**
+     * Échange un ID token de provider (Google/Apple, mobile natif) contre une session.
+     *
+     * Renvoie un `LoginResponse`, PAS un `TokenPair` : comme partout ailleurs, un utilisateur
+     * avec MFA actif reçoit `{ mfa_required: true, mfa_token }` et AUCUNE session n'est
+     * enregistrée — `MFA_CHALLENGE` est émis, à relever par `mfaVerify`. Discriminez avec
+     * {@link isMfaChallenge}.
+     */
+    signInWithIdToken(provider: string, idToken: string, accessToken?: string): Promise<AuraResponse<LoginResponse>>;
     /** GoTrue parity : GET /settings — config publique du projet (pas d'auth requise). */
     getSettings(): Promise<AuraResponse<{
         disable_signup: boolean;
@@ -325,46 +437,6 @@ declare class AuthService extends BaseService {
     verifyMagicLink(token: string): Promise<AuraResponse<TokenPair>>;
 }
 
-declare class AuthAdminService extends BaseService {
-    private get prefix();
-    listUsers(params?: {
-        limit?: number;
-        offset?: number;
-        search?: string;
-    }): Promise<AuraResponse<AdminUser[]>>;
-    getUser(userId: string): Promise<AuraResponse<AdminUser>>;
-    createUser(data: AdminCreateUserRequest): Promise<AuraResponse<AdminUser>>;
-    updateUser(userId: string, data: AdminUpdateUserRequest): Promise<AuraResponse<AdminUser>>;
-    deleteUser(userId: string): Promise<AuraResponse<null>>;
-    banUser(userId: string): Promise<AuraResponse<null>>;
-    unbanUser(userId: string): Promise<AuraResponse<null>>;
-    generateLink(userId: string, type: GenerateLinkType): Promise<AuraResponse<GenerateLinkResult>>;
-    getUserStats(): Promise<AuraResponse<UserStats>>;
-    listUserIdentities(userId: string): Promise<AuraResponse<IdentityInfo[]>>;
-    listSessions(params?: {
-        userId?: string;
-        limit?: number;
-        offset?: number;
-    }): Promise<AuraResponse<AdminSessionInfo[]>>;
-    revokeSession(sessionId: string): Promise<AuraResponse<null>>;
-    getAuditLog(params?: {
-        userId?: string;
-        limit?: number;
-        offset?: number;
-    }): Promise<AuraResponse<AuditLogEntry[]>>;
-    getSettings(): Promise<AuraResponse<AuthSettings>>;
-    updateSettings(data: Partial<AuthSettings>): Promise<AuraResponse<AuthSettings>>;
-    listEmailTemplates(): Promise<AuraResponse<Record<string, unknown>[]>>;
-    getEmailTemplate(type: string): Promise<AuraResponse<Record<string, unknown>>>;
-    updateEmailTemplate(type: string, data: EmailTemplateUpdate): Promise<AuraResponse<Record<string, unknown>>>;
-    deleteEmailTemplate(type: string): Promise<AuraResponse<{
-        message: string;
-    }>>;
-    testEmailTemplate(type: string, body: {
-        to_email: string;
-    }): Promise<AuraResponse<null>>;
-}
-
 interface SessionManagerOptions {
     channelName: string;
     enabled: boolean;
@@ -394,4 +466,4 @@ declare class SessionManager {
     private _stopInterval;
 }
 
-export { AuthAdminService, AuthService, type EmailOtpType, type MobileOtpType, SessionManager, type SessionManagerOptions, type VerifyEmailChangeOtpParams, type VerifyEmailOtpParams, type VerifyInviteOtpParams, type VerifyMagiclinkOtpParams, type VerifyOtpParams, type VerifyPhoneChangeOtpParams, type VerifyRecoveryOtpParams, type VerifySignupOtpParams, type VerifySmsOtpParams, isMfaChallenge };
+export { AuthAdminService, AuthService, type EmailOtpType, type MobileOtpType, SessionManager, type SessionManagerOptions, type VerifyEmailChangeOtpParams, type VerifyEmailOtpParams, type VerifyMagiclinkOtpParams, type VerifyOtpParams, type VerifyRecoveryOtpParams, type VerifySignupOtpParams, type VerifySmsOtpParams, isMfaChallenge };