@aurabase/aurabase-js 0.3.0 → 0.4.0

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

@@ -1,397 +0,0 @@
-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 };