@aurabase/aurabase-js 0.3.0

package/packages/auth/dist/index.d.cts

@@ -0,0 +1,397 @@
+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';
+
+/**
+ * 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.
+ */
+type EmailOtpType = 'signup' | 'invite' | 'magiclink' | 'recovery' | 'email_change' | 'email';
+/**
+ * Types d'OTP « mobile » (parité `MobileOtpType` de supabase-js). `phone_change`
+ * n'a aucun endpoint backend (→ `otp_type_unsupported`).
+ */
+type MobileOtpType = 'sms' | 'phone_change';
+interface VerifySignupOtpParams {
+    type: 'signup';
+    /** Jeton reçu par email (lien de confirmation d'inscription). */
+    token: string;
+}
+interface VerifyMagiclinkOtpParams {
+    type: 'magiclink';
+    /** Jeton du magic link. */
+    token: string;
+}
+interface VerifyEmailOtpParams {
+    type: 'email';
+    email: string;
+    /** Code OTP à 6 chiffres reçu par email (mappé sur `code` côté backend). */
+    token: string;
+}
+interface VerifySmsOtpParams {
+    type: 'sms';
+    phone: string;
+    /** Code OTP reçu par SMS (mappé sur `code` côté backend). */
+    token: string;
+}
+interface VerifyEmailChangeOtpParams {
+    type: 'email_change';
+    /** Jeton de confirmation de changement d'email. */
+    token: string;
+}
+interface VerifyRecoveryOtpParams {
+    type: 'recovery';
+    /** Jeton de récupération reçu par email. */
+    token: string;
+    /**
+     * Nouveau mot de passe. REQUIS : le backend `reset-password` fusionne
+     * consommation du token + changement de mot de passe (divergence documentée
+     * avec supabase-js qui renvoie une session puis attend un `updateUser`).
+     */
+    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.
+ */
+type VerifyOtpParams = VerifySignupOtpParams | VerifyMagiclinkOtpParams | VerifyEmailOtpParams | VerifySmsOtpParams | VerifyEmailChangeOtpParams | VerifyRecoveryOtpParams | VerifyInviteOtpParams | VerifyPhoneChangeOtpParams;
+
+type AuthStateCallback = (payload: AuthChangePayload) => void;
+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`).
+ */
+declare function isMfaChallenge(v: unknown): v is MfaChallenge;
+declare class AuthService extends BaseService {
+    private _stateListeners;
+    private _sessionManager;
+    private _applyingRemote;
+    private _unsubStore;
+    private _disposed;
+    constructor(client: AuraClientLike, options?: AuthServiceOptions);
+    /**
+     * 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).
+     */
+    _detectSessionInUrl(): Promise<void>;
+    /**
+     * 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;
+    private _broadcastState;
+    private _applyRemoteState;
+    /** Démonte le cycle de vie proactif : ticker, visibilité, BroadcastChannel, listeners. */
+    dispose(): void;
+    private get prefix();
+    /** Clé project-scoped du `code_verifier` PKCE (anti-collision multi-projets). */
+    private get _pkceVerifierKey();
+    /**
+     * 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();
+    onAuthStateChange(callback: AuthStateCallback): {
+        unsubscribe: () => void;
+    };
+    private _emitEvent;
+    signUp(req: SignUpRequest): Promise<AuraResponse<LoginResponse>>;
+    signInWithPassword(req: SignInRequest): Promise<AuraResponse<LoginResponse>>;
+    signInWithOAuth(provider: string, options?: OAuthSignInOptions): Promise<AuraResponse<{
+        url: string;
+    }>>;
+    signInWithMagicLink(req: MagicLinkRequest): Promise<AuraResponse<{
+        message: string;
+    }>>;
+    signInAnonymously(): Promise<AuraResponse<TokenPair>>;
+    signOut(): Promise<AuraResponse<null>>;
+    refreshSession(): Promise<AuraResponse<TokenPair>>;
+    /**
+     * 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`).
+     */
+    getSession(): Promise<{
+        accessToken: string | null;
+        user: User | null;
+    }>;
+    setSession(accessToken: string, refreshToken: string): Promise<AuraResponse<User>>;
+    exchangeCodeForSession(authCode: string, codeVerifier?: string): Promise<AuraResponse<TokenPair>>;
+    /**
+     * 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 _exchangeCode;
+    listSessions(): Promise<AuraResponse<SessionInfo[]>>;
+    revokeSession(sessionId: string): Promise<AuraResponse<null>>;
+    revokeAllSessions(): Promise<AuraResponse<{
+        message: string;
+    }>>;
+    /**
+     * 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.
+     */
+    getUser(jwt?: string): Promise<AuraResponse<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.
+     */
+    getClaims(jwt?: string, options?: {
+        allowExpired?: boolean;
+        issuer?: string;
+        audience?: string;
+    }): Promise<AuraResponse<GetClaimsResult>>;
+    deleteUser(password: string): Promise<AuraResponse<null>>;
+    updateUser(req: UpdateUserRequest): Promise<AuraResponse<User>>;
+    resetPasswordForEmail(req: PasswordResetRequest): Promise<AuraResponse<{
+        message: string;
+    }>>;
+    updatePassword(newPassword: string, currentPassword?: string): Promise<AuraResponse<User>>;
+    mfaEnroll(): Promise<AuraResponse<MfaEnrollResponse>>;
+    mfaVerifySetup(code: string): Promise<AuraResponse<{
+        recovery_codes: string[];
+    }>>;
+    mfaVerify(req: MfaVerifyRequest): Promise<AuraResponse<TokenPair>>;
+    mfaUnenroll(password: string): Promise<AuraResponse<{
+        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.
+     *
+     * 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.
+     */
+    verifyOtp(params: VerifyEmailChangeOtpParams): Promise<AuraResponse<User>>;
+    verifyOtp(params: Exclude<VerifyOtpParams, VerifyEmailChangeOtpParams>): Promise<AuraResponse<TokenPair>>;
+    /**
+     * Helper commun aux vérifications OTP renvoyant une `TokenPair` : appelle
+     * 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;
+        provider: string;
+    }>>;
+    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>>;
+    /** GoTrue parity : GET /settings — config publique du projet (pas d'auth requise). */
+    getSettings(): Promise<AuraResponse<{
+        disable_signup: boolean;
+        external: Record<string, boolean>;
+        mailer_autoconfirm: boolean;
+        mfa_enabled: boolean;
+    }>>;
+    /** Clé publiable (anon key) du projet — GET /anon-key (public, à l'image du modèle Supabase). */
+    getAnonKey(): Promise<AuraResponse<{
+        anon_key: string;
+    }>>;
+    /**
+     * 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.
+     */
+    resetPassword(token: string, newPassword: string): Promise<AuraResponse<TokenPair>>;
+    /**
+     * Convertit l'utilisateur anonyme courant (JWT requis) en compte régulier email+password.
+     * Body confirmé au handler (`PromoteAnonymousRequest`) : `{ email, password }`.
+     */
+    promoteAnonymous(credentials: {
+        email: string;
+        password: string;
+    }): Promise<AuraResponse<TokenPair>>;
+    /**
+     * Consomme le token de magic link et renvoie une TokenPair.
+     * Body confirmé au handler (`VerifyMagicLinkRequest`) : `{ token }`.
+     */
+    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;
+    onTick: () => void;
+    isRefreshDue: () => boolean;
+    onRemoteMessage: (data: unknown) => void;
+    tickMs?: number;
+}
+/**
+ * Primitive de cycle de vie de session (timers + BroadcastChannel + visibilité).
+ * Aucune logique métier auth : `AuthService` fournit les callbacks et pilote `setActive`.
+ * Sûr en Node/SSR/RN — tous les globals sont gardés (`typeof … !== 'undefined'`).
+ */
+declare class SessionManager {
+    private readonly opts;
+    private _interval;
+    private _channel;
+    private _active;
+    private _visHandler;
+    constructor(opts: SessionManagerOptions);
+    get isActive(): boolean;
+    start(): void;
+    setActive(active: boolean): void;
+    broadcast(data: unknown): void;
+    stop(): void;
+    private _startInterval;
+    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 };