Invitations d'organisation

Vue d'ensemble

Les invitations d'organisation utilisent Better Auth pour l'état d'appartenance, mais Yayaw possède l'expérience d'onboarding hors connexion. C'est nécessaire parce que l'acceptation d'invitation Better Auth exige une session authentifiée dont l'e-mail correspond à l'invitation.

L'e-mail d'invitation pointe vers:

/auth/accept-invitation?invitationId=<id>&token=<secret>

invitationId est l'id d'invitation Better Auth. token est un secret d'onboarding Yayaw généré lorsque l'e-mail est envoyé. Seul le hash du token est stocké dans invitation_onboarding_tokens; le token brut n'apparaît que dans le lien envoyé par e-mail.

Flux

Les utilisateurs déconnectés voient d'abord un aperçu sécurisé de l'invitation, adossé au token d'onboarding. Le chemin préféré est la clé d'accès (passkey):

1. Les utilisateurs existants peuvent se connecter avec une clé d'accès existante.
2. Les nouveaux utilisateurs peuvent créer un compte avec une clé d'accès depuis le lien d'invitation.
3. Le magic link reste disponible et est verrouillé sur l'e-mail invité.
4. L'inscription/connexion par mot de passe reste disponible et préserve l'URL de retour d'invitation à travers les flux de vérification d'e-mail et de réinitialisation.

Les utilisateurs connectés relisent l'invitation et l'acceptent ou la rejettent explicitement. Better Auth vérifie que l'e-mail connecté correspond au destinataire de l'invitation avant l'acceptation. Après acceptation, Better Auth définit l'organisation active et Yayaw marque le token d'onboarding comme consommé.

Route runtime:

• /auth/accept-invitation

Services clés:

• src/lib/server/services/auth/invitation-onboarding.ts
• src/lib/server/services/auth/invitation-onboarding-utils.ts
• src/lib/server/services/email/organization-invitation-email.ts

Inscription privilégiant la clé d'accès

L'inscription privilégiant la clé d'accès utilise l'enregistrement de clé d'accès Better Auth avec registration.requireSession: false.

Yayaw ne passe pas le token d'invitation brut dans le contexte WebAuthn. À la place, le client demande au serveur un contexte de clé d'accès opaque et de courte durée après que le token e-mail a déjà été validé. Le resolver d'enregistrement de clé d'accès vérifie ensuite que:

• le contexte est encore valide
• l'invitation est encore en attente
• le token d'onboarding original n'a pas été consommé
• aucun utilisateur n'existe déjà pour l'e-mail invité

Les comptes existants ne peuvent pas ajouter une clé d'accès depuis un simple lien d'invitation. Ils doivent d'abord s'authentifier, puis ajouter une clé d'accès après avoir accepté l'invitation.

Stockage des tokens

Le token d'onboarding brut n'est jamais persisté. La base de données stocke:

• l'id d'invitation
• le hash du token
• l'e-mail invité
• le timestamp de consommation
• les métadonnées d'expiration

Ainsi, des lignes de base de données divulguées ne suffisent pas à accepter une invitation. La livraison e-mail reste sensible parce que le token brut existe dans l'URL envoyée par e-mail.

Comportement des e-mails

Les e-mails d'invitation utilisent le pipeline d'e-mails transactionnels lorsque des modèles actifs en base et RESEND_API_KEY sont disponibles. Une configuration e-mail manquante devrait apparaître comme un échec d'envoi pour l'opérateur, pas comme un grant silencieux d'appartenance.

L'URL d'invitation doit rester absolue et basée sur NEXT_PUBLIC_BASE_URL; les déploiements de production ont donc besoin que l'hôte canonique soit configuré avant l'envoi de vraies invitations.

Synchronisation AuthZ

L'acceptation d'invitation crée un membre Better Auth. Yayaw synchronise aussi les membres d'invitation acceptés dans les groupes d'autorisation internes via les hooks d'organisation Better Auth, afin que les permissions du tableau de bord soient disponibles immédiatement après l'arrivée.

Les rôles Better Auth sont mappés vers des groupes Yayaw scopés par organisation lors de la création d'organisation, de l'acceptation d'invitation, des mises à jour de rôle membre et du retrait de membre. N'insérez pas manuellement de membres Better Auth sans préserver aussi ce chemin de synchronisation.

Règles de sécurité

• Seul l'e-mail invité peut accepter l'invitation.
• L'aperçu d'invitation est autorisé hors connexion, mais la création d'appartenance exige toujours une identité vérifiée/authentifiée.
• Le contexte de clé d'accès est de courte durée et dérivé après validation du token.
• Les tokens consommés ne peuvent pas être réutilisés.
• Les comptes existants doivent s'authentifier avant d'ajouter des clés d'accès.
• Les fallbacks mot de passe et magic-link doivent préserver l'URL de retour d'invitation.

Validation

Vérifications utiles après des changements d'invitations ou d'onboarding auth:

bun test src/lib/server/services/auth/invitation-onboarding-utils.test.ts
bun run check
bunx tsc --noEmit
bun run build