@aurabase/auth 0.4.0 → 0.5.0

package/README.md

@@ -23,7 +23,7 @@ Dans l'usage courant, `AuthService` n'est jamais instancié directement : il est
 ```ts
 import { createClient } from '@aurabase/aurabase-js'
 
-const aura = createClient('http://localhost:8080', 'my-project', 'aura_anon_xxx')
+const aura = createClient('https://mon-projet.aurabase.cloud', 'aura_anon_xxx')
 ```
 
 ### Mot de passe
@@ -48,7 +48,10 @@ const refreshed = await aura.auth.refreshSession()
 await aura.auth.setSession('stored-access-token', 'stored-refresh-token')
 
 const sessions = await aura.auth.listSessions()
-await aura.auth.revokeSession(sessions.data![0].id)
+// `data` peut être `null` même en succès (204 / corps vide) : on le teste plutôt
+// que `error`, ce qui évite l'assertion `!` et fait narrower TypeScript.
+const first = sessions.data?.[0]
+if (first) await aura.auth.revokeSession(first.id)
 await aura.auth.revokeAllSessions()
 ```
 
@@ -64,20 +67,103 @@ const { data, error } = await aura.auth.signInWithOAuth('github', {
 })
 
 if (error) throw error
+if (!data) throw new Error("aucune URL de redirection renvoyée")
 
-// Côté serveur / SSR : pas de redirection automatique, il faut rediriger manuellement vers data!.url
-console.log(data!.url)
+// Côté serveur / SSR : pas de redirection automatique, il faut rediriger manuellement vers data.url
+console.log(data.url)
 ```
 
+#### `queryParams` — ce qui atteint vraiment le provider
+
+```ts
+await aura.auth.signInWithOAuth('google', {
+  queryParams: { prompt: 'consent', access_type: 'offline', login_hint: 'user@example.com' },
+})
+```
+
+Ces clés-là — et elles seules — sont recopiées dans l'URL d'autorisation du provider :
+
+| Clé | Origine |
+| --- | --- |
+| `prompt`, `login_hint`, `display`, `ui_locales`, `max_age`, `acr_values`, `claims_locales` | OpenID Connect Core §3.1.2.1 |
+| `access_type`, `include_granted_scopes`, `hd` | Google OAuth 2.0 |
+
+**Toute autre clé est refusée**, jamais transmise et jamais ignorée en silence : la méthode
+renvoie `error.code === 'invalid_oauth_query_param'` sans déclencher de redirection.
+
+> `hd` est un **indice** d'affichage Google, pas un contrôle : il n'empêche pas de se
+> connecter avec un autre domaine. Pour restreindre pour de bon, vérifiez le domaine de
+> l'utilisateur au retour du flux.
+
+- Les paramètres du protocole (`state`, `nonce`, `client_id`, `response_type`, `scope`,
+  `code_challenge`, `code_challenge_method`, `response_mode`…) sont **calculés par le
+  serveur** : les laisser fournir par un client permettrait de détourner le flux.
+- Les paramètres de la requête (`redirect_uri`, `scopes`) ont leur option dédiée
+  (`redirectTo`, `scopes`). `project_id` n'est pas fournissable non plus : le projet est
+  celui de l'URL passée à `createClient()`.
+- Les variantes de casse (`Prompt`, `State`) et les clés inconnues sont refusées aussi.
+
+`redirectTo` part en `redirect_uri` (le backend accepte aussi l'alias `redirect_to`, nom
+employé par les SDK Dart/Python/Rust) : il est validé contre les URLs autorisées du projet
+et ne remplace jamais le `redirect_uri` envoyé au provider, qui reste le callback Aurabase.
+
+#### Où atterrit l'utilisateur au retour
+
+| Cas | URL servie |
+| --- | --- |
+| `redirectTo` fournie, connexion aboutie | `{redirectTo}#access_token=…&refresh_token=…&expires_in=…&token_type=bearer&user=…` — **l'URL exacte**, aucun segment ajouté |
+| `redirectTo` omise, connexion aboutie | `{site_url du projet}/oauth/callback#access_token=…` (`site_url` est une base, pas une page) |
+| **Utilisateur avec MFA actif** | `{redirectTo}/oauth/mfa#mfa_token=…` — ou `{site_url}/oauth/mfa#mfa_token=…` si `redirectTo` est omise |
+
+L'utilisateur MFA n'a pas fini de se connecter : il reste un défi à relever, et `#mfa_token`
+n'est pas une session. Le backend l'envoie donc sur un **sous-chemin dédié**, `…/oauth/mfa`,
+plutôt que sur votre page d'atterrissage où le jeton ne serait attendu par personne. Ce
+sous-chemin reste sous l'origine et le préfixe de chemin validés : il n'échappe pas à
+l'allowlist.
+
+Votre application doit donc servir une page sur `{redirectTo}/oauth/mfa`. Le SDK y fait le
+reste : `detectSessionInUrl` reconnaît `#mfa_token`, émet `MFA_CHALLENGE` avec `mfaToken`
+(**aucune session n'est posée**) et nettoie l'URL.
+
+```ts
+aura.auth.onAuthStateChange(async ({ event, mfaToken }) => {
+  if (event !== 'MFA_CHALLENGE' || !mfaToken) return
+  const code = await demanderLeCodeTotp()          // votre UI
+  await aura.auth.mfaVerify({ mfa_token: mfaToken, code })  // → SIGNED_IN
+})
+```
+
+> **Divergence Supabase assumée.** Une `redirectTo` **hors allowlist** fait échouer le
+> démarrage (`400`). Supabase, lui, l'ignore en silence et retombe sur le Site URL. Aurabase
+> préfère l'erreur explicite : une redirection silencieuse vers une autre destination que
+> celle demandée est indétectable côté application.
+
+La décision appartient au **backend** (`GET /v1/auth/oauth/{provider}/start`, qui répond
+`400` sur les mêmes règles, plus le refus des doublons, des valeurs vides, démesurées ou
+porteuses d'un caractère de contrôle) : cet endpoint est public, une allowlist purement
+cliente ne protégerait rien. Le filtre du SDK n'en est que le miroir — un test de parité lit
+la source Rust pour interdire toute divergence — et sert à échouer avant la redirection.
+
 Retour du provider (flux PKCE) :
 
 ```ts
-const session = await aura.auth.exchangeCodeForSession('auth-code-from-callback')
+import { isMfaChallenge } from '@aurabase/auth'
+
+const { data, error } = await aura.auth.exchangeCodeForSession('auth-code-from-callback')
 
 // Mobile natif : échange d'un ID token provider (Google/Apple) contre une session Aurabase
 await aura.auth.signInWithIdToken('google', 'id-token-from-provider')
 ```
 
+Ces deux méthodes renvoient un `LoginResponse` (`TokenPair | MfaChallenge`), pas un `TokenPair` :
+sur un utilisateur avec MFA actif, le backend répond `{ mfa_required: true, mfa_token }` et
+**aucune session n'est enregistrée** — `MFA_CHALLENGE` est émis, à relever par `mfaVerify`.
+Discriminez avant de lire les jetons :
+
+```ts
+if (data && !isMfaChallenge(data)) console.log(data.access_token)
+```
+
 ### Magic link / OTP
 
 ```ts
@@ -85,10 +171,10 @@ await aura.auth.signInWithMagicLink({ email: 'user@example.com', redirect_url: '
 await aura.auth.verifyMagicLink('token-from-link')
 
 await aura.auth.signInWithEmailOtp('user@example.com')
-await aura.auth.verifyEmailOtp('user@example.com', '123456')
+await aura.auth.verifyOtp({ type: 'email', email: 'user@example.com', token: '123456' })
 
 await aura.auth.signInWithSmsOtp('+15551234567')
-await aura.auth.verifySmsOtp('+15551234567', '123456')
+await aura.auth.verifyOtp({ type: 'sms', phone: '+15551234567', token: '123456' })
 ```
 
 ### Anonyme
@@ -145,9 +231,9 @@ via `history.replaceState`).
 ### Vérification d'email
 
 ```ts
-await aura.auth.verifyEmail('token-from-email')
+await aura.auth.verifyOtp({ type: 'signup', token: 'token-from-email' })
 await aura.auth.resendVerificationEmail() // reprend l'email de la session courante si omis
-await aura.auth.confirmEmailChange('token-from-email')
+await aura.auth.verifyOtp({ type: 'email_change', token: 'token-from-email' })
 ```
 
 ### MFA (TOTP)
@@ -192,7 +278,7 @@ Réservé au serveur (clé `service_role`). Deux façons d'y accéder :
 // Via le client admin (recommandé)
 import { createAdminClient } from '@aurabase/aurabase-js'
 
-const admin = createAdminClient('http://localhost:8080', 'my-project', process.env.SERVICE_ROLE_KEY!)
+const admin = createAdminClient('https://mon-projet.aurabase.cloud', process.env.SERVICE_ROLE_KEY!)
 await admin.authAdmin.listUsers({ limit: 50 })
 ```