React Native

Package : @mailmus/auth-react-native (code source) — couche fine au-dessus du SDK navigateur, qui gère déjà tout ce qui n'est pas spécifique à la plateforme (HTTP, refresh de session, MFA, sessions, organizations). Ce package ne remplace que deux choses : le stockage des tokens (Keychain/Keystore au lieu de localStorage) et le flow OAuth (navigateur système au lieu de window.open).

[!IMPORTANT] Ce package est en cours de développement (v0.1.0), l'API peut encore changer avant la 1.0.

Installation

npx expo install @mailmus/auth-react-native expo-secure-store expo-web-browser

Fonctionne en Expo managé et en React Native bare avec les modules Expo installés (npx install-expo-modules, supporté officiellement depuis Expo SDK 44+) — ce n'est pas un package réservé à Expo managé malgré la dépendance.

Expo Go ou development build ?

createMailmusAuthClient() (sign-up/in, MFA, sessions, organizations, stockage sécurisé) fonctionne dans Expo Go — expo-secure-store ne nécessite aucun code natif au-delà de ce qui est déjà embarqué dans l'app Expo Go. startOAuth() en revanche ne fonctionne pas dans Expo Go : il a besoin d'un deep link avec un schéma d'URI personnalisé (monapp://oauth-callback), et une app tournant dans Expo Go utilise le schéma d'Expo Go, pas le sien. C'est une limite de la plateforme, pas quelque chose que ce SDK peut contourner — la doc Expo elle-même est explicite : "Expo Go cannot be used for local development and testing of OAuth or OpenID Connect-enabled apps due to the inability to customize your app scheme." Utilisez un development build (expo-dev-client, npx expo run:ios/run:android, ou un profil dev EAS Build) pour tester OAuth.

Usage

import { createMailmusAuthClient, startOAuth } from "@mailmus/auth-react-native";

const client = await createMailmusAuthClient({
  appId: "app_xxx",
  publishableKey: "pk_xxx",
  serverURL: "https://api.mailmus.app",
  hostedPagesURL: "https://www.mailmus.app",
});

// Même API MailmusAuthClient que le SDK navigateur à partir d'ici.
const result = await client.signIn({ email, password });

createMailmusAuthClient() est asynchrone parce que la lecture du Keychain/Keystore l'est intrinsèquement (contrairement à localStorage sur navigateur) — le client renvoyé est déjà entièrement hydraté (client.session.getState() résout directement en signed-in/signed-out, jamais loading).

OAuth — navigateur système, pas de webview

[!IMPORTANT] Nécessite un development build, pas Expo Go.

await startOAuth({
  client,
  appId: "app_xxx",
  publishableKey: "pk_xxx",
  hostedPagesURL: "https://www.mailmus.app",
  provider: "google",
  redirectUri: "monapp://oauth-callback", // doit figurer dans l'allowlist de l'App
});

Ouvre une vraie session ASWebAuthenticationSession (iOS) / Custom Tabs (Android) via expo-web-browser, se termine via un deep link vers votre app — pas un webview embarqué. Setup :

1. Activez le provider (Google/GitHub/Apple) dans App → Authentification — comme sur navigateur, aucune app OAuth à créer vous-même, Mailmus héberge un client partagé par provider.
2. Ajoutez votre deep link (un schéma d'URI personnalisé, ex. monapp://oauth-callback) aux URLs de redirection autorisées.

Aucun changement backend n'a été nécessaire pour ce flow : le bridge OAuth hébergé bascule déjà sur une redirection complète (plutôt qu'un postMessage) dès qu'il n'est pas ouvert via window.open — exactement le cas d'une session de navigateur système.

Lien magique / mot de passe oublié — une vraie limite

client.requestMagicLink()/client.forgotPassword() fonctionnent normalement (purs appels API, aucune dépendance plateforme). La limite est côté réception : pour que le lien envoyé par email rouvre votre app plutôt qu'un onglet de navigateur classique, votre app doit configurer des Universal Links (iOS) / App Links (Android) sur votre propre domaine (apple-app-site-association, assetlinks.json) — une configuration propre à chaque app cliente, que ce SDK ne peut pas faire à votre place. Un schéma d'URI personnalisé n'est pas fiable pour un lien envoyé par email selon les clients mail, contrairement au flow OAuth ci-dessus qui est ouvert directement par votre propre code.

L'OTP par code (requestOtp/verifyOtp) n'a pas cette limite — pas de lien à cliquer, l'utilisateur saisit le code.

MFA, sessions, organizations

Identique au SDK navigateur — purs appels API, aucune dépendance plateforme :

const { secret, otpauthUrl } = await client.mfa.enroll();
const { backupCodes } = await client.mfa.confirm({ code });
await client.sessions.list();
await client.organizations.mine();

Afficher un QR code pour otpauthUrl, ou toute autre UI, est hors du périmètre de ce SDK (une librairie, pas des composants) — utilisez par exemple react-native-qrcode-svg.

Hors scope (roadmap)

SSO/SAML (Home Realm Discovery) — même problème de navigation que OAuth, pas résolu ici. Composants RN pré-faits — chantier séparé si besoin, même phasage que @mailmus/auth-react sur navigateur.

Suivant

• OAuth, MFA — le comportement détaillé est identique au SDK navigateur.
• SDK navigateur — API complète sous-jacente.