From 88e580306139b0743f56b80f1fcffb5517499dde Mon Sep 17 00:00:00 2001 From: Saad Zoubir Date: Fri, 27 Mar 2026 15:16:45 +0100 Subject: [PATCH] feat: add team invitation acceptance flow with email link routing Implement end-to-end invitation acceptance: neutral entry route validates token and routes to register (new users), login (existing users), or auto-accepts (authenticated users). Handles 2FA token survival via session, email case-insensitive matching, and dedicated error pages. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../implementation-artifacts/deferred-work.md | 6 + .../tech-spec-team-invitation-acceptance.md | 90 +++++++++++++++ app/Actions/Fortify/CreateNewUser.php | 24 +++- .../TeamInvitationAcceptController.php | 103 ++++++++++++++++++ app/Http/Responses/LoginResponse.php | 61 +++++++++++ app/Http/Responses/RegisterResponse.php | 26 +++++ app/Mail/TeamInvitationMail.php | 2 +- app/Providers/FortifyServiceProvider.php | 45 ++++++-- resources/js/pages/auth/InvitationError.vue | 31 ++++++ resources/js/pages/auth/Login.vue | 18 ++- resources/js/pages/auth/Register.vue | 28 ++++- .../views/emails/team-invitation.blade.php | 4 +- routes/web.php | 3 + 13 files changed, 422 insertions(+), 19 deletions(-) create mode 100644 _bmad-output/implementation-artifacts/tech-spec-team-invitation-acceptance.md create mode 100644 app/Http/Controllers/TeamInvitationAcceptController.php create mode 100644 app/Http/Responses/LoginResponse.php create mode 100644 app/Http/Responses/RegisterResponse.php create mode 100644 resources/js/pages/auth/InvitationError.vue diff --git a/_bmad-output/implementation-artifacts/deferred-work.md b/_bmad-output/implementation-artifacts/deferred-work.md index 0d10cc6..4ba633b 100644 --- a/_bmad-output/implementation-artifacts/deferred-work.md +++ b/_bmad-output/implementation-artifacts/deferred-work.md @@ -6,3 +6,9 @@ - **Cross-page selection UX on declarations page** — Navigating between pages clears selections silently. Consider persisting selections across pages or warning the user. - **Bulk notify count mismatch UX** — When some selected declarations are filtered out (no client), the success message count differs from the selection count with no explanation. Consider showing skipped count. - **Nudge email template null guards** — `nudge-notification.blade.php` renders `$clientName`, `$declarationType`, `$dueDate` without null fallbacks, producing blank labels. + +## From: tech-spec-team-invitation-acceptance (2026-03-27) + +- **Race condition on concurrent invitation acceptance** — Two users clicking the same invitation link simultaneously could both pass `isValid()` before either sets `accepted_at`. Fix with `SELECT FOR UPDATE` or atomic `UPDATE WHERE accepted_at IS NULL`. +- **Multiple pending invitations per email/workspace** — No unique constraint on `[workspace_id, email]` in `team_invitations`. Multiple tokens can exist for the same email+workspace. Second token in `CreateNewUser` path would hit unique constraint on `workspace_user` and throw. +- **Vue cross-link URLs should come from PHP props** — Register.vue and Login.vue construct invitation-aware login/register URLs via JS string interpolation instead of receiving them as props from the controller. diff --git a/_bmad-output/implementation-artifacts/tech-spec-team-invitation-acceptance.md b/_bmad-output/implementation-artifacts/tech-spec-team-invitation-acceptance.md new file mode 100644 index 0000000..8566eef --- /dev/null +++ b/_bmad-output/implementation-artifacts/tech-spec-team-invitation-acceptance.md @@ -0,0 +1,90 @@ +--- +title: 'Team Invitation Acceptance Flow' +type: 'feature' +created: '2026-03-27' +status: 'done' +baseline_commit: '8f39bd9' +context: ['_bmad-output/project-context.md'] +--- + +# Team Invitation Acceptance Flow + + + +## Intent + +**Problem:** Clicking the team invitation email link lands on a standard registration page that ignores the invitation token. New users register without being attached to the inviting workspace; existing users have no acceptance path at all. + +**Approach:** Create a neutral entry route `/team/invitation/{token}/accept` that validates the token and routes to the correct flow: auto-accept for authenticated users, redirect to login (with message) for existing accounts, or redirect to register (with pre-filled email) for new users. Modify `CreateNewUser` to process the invitation token after registration. Update both auth Vue pages to pass the token through. + +## Boundaries & Constraints + +**Always:** +- Validate invitation via `TeamInvitation::isValid()` at every entry point +- Attach user to workspace using role from invitation + default permissions from `config('permissions.defaults')` +- Set `current_workspace_id` in session after acceptance +- Mark invitation `accepted_at = now()` in a DB transaction +- Show a dedicated error page for invalid/expired tokens + +**Ask First:** +- Any changes to the invitation email subject or body beyond the URL + +**Never:** +- Modify Fortify's core auth pipeline or middleware stack +- Allow accepting an invitation for an email that doesn't match the authenticated user's email +- Allow a user who is already a member of the workspace to re-accept + +## I/O & Edge-Case Matrix + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|----------|--------------|---------------------------|----------------| +| New user, valid token | Guest visits `/team/invitation/{token}/accept` | Redirect to `/register?invitation={token}` with email pre-filled and read-only | N/A | +| New user completes registration | POST register with `invitation` field | User created, attached to workspace, session set, redirect to `/dashboard` | N/A | +| Existing user, authenticated, valid token | Auth user visits `/team/invitation/{token}/accept` | Auto-accept: attach to workspace, set session, redirect to `/dashboard` with success flash | N/A | +| Existing user, not authenticated | Guest with existing account visits entry route | Redirect to `/login?invitation={token}` with status message | N/A | +| Post-login with invitation token | User logs in with `invitation` query param | Process invitation after login, redirect to dashboard | N/A | +| Expired token | Any visitor | Dedicated error page: "Cette invitation a expiré" | Inertia error page | +| Already-accepted token | Any visitor | Dedicated error page: "Cette invitation a deja ete utilisee" | Inertia error page | +| Email mismatch (auth user email != invitation email) | Auth user visits entry route | Error flash: "Cette invitation est destinee a une autre adresse email" + redirect back | Redirect with error | +| Already a workspace member | Auth user visits entry route | Flash "Vous etes deja membre de cet espace de travail" + redirect to dashboard | Redirect with info | + + + +## Code Map + +- `app/Http/Controllers/TeamInvitationAcceptController.php` -- NEW: entry route controller, handles routing logic and acceptance for authenticated users +- `app/Actions/Fortify/CreateNewUser.php` -- ADD: invitation processing after user creation +- `app/Providers/FortifyServiceProvider.php` -- MODIFY: pass invitation data to register/login views, add custom registration response +- `resources/js/pages/auth/Register.vue` -- MODIFY: accept invitation props, pre-fill email, add hidden field +- `resources/js/pages/auth/Login.vue` -- MODIFY: accept invitation prop, pass token through form, show invitation message +- `routes/web.php` -- ADD: `/team/invitation/{token}/accept` route +- `app/Mail/TeamInvitationMail.php` -- MODIFY: change URL to new acceptance route +- `resources/js/pages/auth/InvitationError.vue` -- NEW: dedicated error page for invalid/expired tokens +- `app/Http/Responses/RegisterResponse.php` -- NEW: custom Fortify response to redirect to dashboard with workspace session after invitation registration + +## Tasks & Acceptance + +**Execution:** +- [ ] `app/Http/Controllers/TeamInvitationAcceptController.php` -- Create single-action controller with `__invoke()`: validate token, check auth state, check if email has existing account, route accordingly +- [ ] `routes/web.php` -- Add `GET /team/invitation/{token}/accept` route (no auth middleware, publicly accessible) +- [ ] `resources/js/pages/auth/InvitationError.vue` -- Create error page with `AuthLayout`, show message + link to home +- [ ] `app/Providers/FortifyServiceProvider.php` -- Update `registerView` to pass `invitation` query param and invitation email as props; update `loginView` to pass `invitation` query param +- [ ] `resources/js/pages/auth/Register.vue` -- Accept `invitation` and `invitationEmail` props, pre-fill email (read-only when invitation present), add hidden `invitation` input +- [ ] `resources/js/pages/auth/Login.vue` -- Accept `invitation` prop, add hidden `invitation` input, show invitation status message +- [ ] `app/Actions/Fortify/CreateNewUser.php` -- After user creation: if `invitation` token present, validate, attach workspace, mark accepted, set session +- [ ] `app/Http/Responses/RegisterResponse.php` -- Create custom `RegisterResponse` implementing `Fortify\Contracts\RegisterResponse`: if session has `invitation_workspace_id`, redirect to `/dashboard`; bind in `FortifyServiceProvider` +- [ ] `app/Mail/TeamInvitationMail.php` -- Change `registerUrl` to `route('team.invitation.accept', $this->invitation->token)` + +**Acceptance Criteria:** +- Given a new user clicks the invitation email link, when they complete registration, then they are attached to the workspace with the correct role and land on the workspace dashboard +- Given an authenticated user clicks the invitation link, when the token is valid and email matches, then they are auto-attached and redirected to the dashboard with the new workspace active +- Given a non-authenticated user with an existing account clicks the link, when they log in, then the invitation is processed and they land on the workspace dashboard +- Given an expired or used token, when any user visits the link, then they see a clear French-language error page +- Given an email mismatch between authenticated user and invitation, when they visit the link, then they see an error and are not attached + +## Verification + +**Commands:** +- `composer test` -- expected: all existing tests pass (no regressions) +- `npm run lint` -- expected: no lint errors +- `composer lint` -- expected: no PHP formatting errors diff --git a/app/Actions/Fortify/CreateNewUser.php b/app/Actions/Fortify/CreateNewUser.php index 3c7c00c..b132905 100644 --- a/app/Actions/Fortify/CreateNewUser.php +++ b/app/Actions/Fortify/CreateNewUser.php @@ -4,7 +4,9 @@ namespace App\Actions\Fortify; use App\Concerns\PasswordValidationRules; use App\Concerns\ProfileValidationRules; +use App\Models\TeamInvitation; use App\Models\User; +use Illuminate\Support\Facades\DB; use Illuminate\Support\Facades\Validator; use Laravel\Fortify\Contracts\CreatesNewUsers; @@ -24,10 +26,30 @@ class CreateNewUser implements CreatesNewUsers 'password' => $this->passwordRules(), ])->validate(); - return User::create([ + $user = User::create([ 'name' => $input['name'], 'email' => $input['email'], 'password' => $input['password'], ]); + + if (! empty($input['invitation'])) { + $invitation = TeamInvitation::where('token', $input['invitation'])->first(); + + if ($invitation && $invitation->isValid() && strtolower($user->email) === strtolower($invitation->email)) { + DB::transaction(function () use ($user, $invitation) { + $user->workspaces()->attach($invitation->workspace_id, [ + 'role' => $invitation->role, + 'permissions' => json_encode(config("permissions.defaults.{$invitation->role}", [])), + ]); + + $invitation->update(['accepted_at' => now()]); + }); + + session(['current_workspace_id' => $invitation->workspace_id]); + session(['invitation_accepted' => true]); + } + } + + return $user; } } diff --git a/app/Http/Controllers/TeamInvitationAcceptController.php b/app/Http/Controllers/TeamInvitationAcceptController.php new file mode 100644 index 0000000..1f05b5b --- /dev/null +++ b/app/Http/Controllers/TeamInvitationAcceptController.php @@ -0,0 +1,103 @@ +first(); + + if (! $invitation) { + return Inertia::render('auth/InvitationError', [ + 'title' => 'Invitation introuvable', + 'message' => 'Ce lien d\'invitation est invalide ou n\'existe pas.', + 'homeUrl' => url('/'), + ]); + } + + if (! $invitation->isValid()) { + $message = $invitation->accepted_at !== null + ? 'Cette invitation a déjà été acceptée.' + : 'Cette invitation a expiré.'; + + return Inertia::render('auth/InvitationError', [ + 'title' => 'Invitation invalide', + 'message' => $message, + 'homeUrl' => url('/'), + ]); + } + + if (Auth::check()) { + return $this->handleAuthenticatedUser($invitation); + } + + return $this->handleUnauthenticatedUser($invitation); + } + + /** + * Handle invitation acceptance for authenticated users. + */ + protected function handleAuthenticatedUser(TeamInvitation $invitation): Response|RedirectResponse + { + /** @var User $user */ + $user = Auth::user(); + + if (strtolower($user->email) !== strtolower($invitation->email)) { + return Inertia::render('auth/InvitationError', [ + 'title' => 'Adresse email incorrecte', + 'message' => 'Cette invitation est destinée à une autre adresse email.', + 'homeUrl' => url('/'), + ]); + } + + $alreadyMember = WorkspaceUser::where('workspace_id', $invitation->workspace_id) + ->where('user_id', $user->id) + ->exists(); + + if ($alreadyMember) { + return redirect()->route('dashboard')->with('info', 'Vous êtes déjà membre de cet espace de travail.'); + } + + DB::transaction(function () use ($user, $invitation) { + $user->workspaces()->attach($invitation->workspace_id, [ + 'role' => $invitation->role, + 'permissions' => json_encode(config("permissions.defaults.{$invitation->role}", [])), + ]); + + $invitation->update(['accepted_at' => now()]); + }); + + session(['current_workspace_id' => $invitation->workspace_id]); + + return redirect()->route('dashboard')->with('success', 'Vous avez rejoint l\'espace de travail avec succès.'); + } + + /** + * Handle invitation acceptance for unauthenticated users. + */ + protected function handleUnauthenticatedUser(TeamInvitation $invitation): RedirectResponse + { + $existingUser = User::where('email', $invitation->email)->first(); + + if ($existingUser) { + return redirect() + ->to(route('login', ['invitation' => $invitation->token])) + ->with('status', 'Connectez-vous pour rejoindre l\'espace de travail'); + } + + return redirect()->to(route('register', ['invitation' => $invitation->token])); + } +} diff --git a/app/Http/Responses/LoginResponse.php b/app/Http/Responses/LoginResponse.php new file mode 100644 index 0000000..9e0d65c --- /dev/null +++ b/app/Http/Responses/LoginResponse.php @@ -0,0 +1,61 @@ +input('invitation') + ?? $request->session()->pull('pending_invitation_token'); + + if ($token) { + $invitation = TeamInvitation::where('token', $token)->first(); + $user = $request->user(); + + if ($invitation && $invitation->isValid() && strtolower($invitation->email) === strtolower($user->email)) { + $alreadyMember = WorkspaceUser::where('workspace_id', $invitation->workspace_id) + ->where('user_id', $user->id) + ->exists(); + + if (! $alreadyMember) { + DB::transaction(function () use ($user, $invitation) { + $user->workspaces()->attach($invitation->workspace_id, [ + 'role' => $invitation->role, + 'permissions' => json_encode(config("permissions.defaults.{$invitation->role}", [])), + ]); + + $invitation->update(['accepted_at' => now()]); + }); + } else { + session(['current_workspace_id' => $invitation->workspace_id]); + + return redirect()->intended('/dashboard'); + } + + session(['current_workspace_id' => $invitation->workspace_id]); + + return redirect()->intended('/dashboard'); + } + } + + // Clean up session token if present but not used + $request->session()->forget('pending_invitation_token'); + + return $request->wantsJson() + ? new JsonResponse('', 204) + : redirect()->intended(config('fortify.home')); + } +} diff --git a/app/Http/Responses/RegisterResponse.php b/app/Http/Responses/RegisterResponse.php new file mode 100644 index 0000000..7a7967e --- /dev/null +++ b/app/Http/Responses/RegisterResponse.php @@ -0,0 +1,26 @@ +session()->pull('invitation_accepted')) { + return redirect()->intended('/dashboard'); + } + + return $request->wantsJson() + ? new JsonResponse('', 201) + : redirect()->intended(config('fortify.home')); + } +} diff --git a/app/Mail/TeamInvitationMail.php b/app/Mail/TeamInvitationMail.php index 163f4d5..3f486ed 100644 --- a/app/Mail/TeamInvitationMail.php +++ b/app/Mail/TeamInvitationMail.php @@ -48,7 +48,7 @@ class TeamInvitationMail extends Mailable implements ShouldQueue with: [ 'workspaceName' => $this->workspace->name, 'roleLabel' => $roleLabels[$this->invitation->role] ?? $this->invitation->role, - 'registerUrl' => route('register', ['invitation' => $this->invitation->token]), + 'acceptUrl' => route('team.invitation.accept', $this->invitation->token), 'expiresAt' => $this->invitation->expires_at->format('d/m/Y à H:i'), ] ); diff --git a/app/Providers/FortifyServiceProvider.php b/app/Providers/FortifyServiceProvider.php index 2caea88..a2cd500 100644 --- a/app/Providers/FortifyServiceProvider.php +++ b/app/Providers/FortifyServiceProvider.php @@ -20,7 +20,15 @@ class FortifyServiceProvider extends ServiceProvider */ public function register(): void { - // + $this->app->singleton( + \Laravel\Fortify\Contracts\RegisterResponse::class, + \App\Http\Responses\RegisterResponse::class + ); + + $this->app->singleton( + \Laravel\Fortify\Contracts\LoginResponse::class, + \App\Http\Responses\LoginResponse::class + ); } /** @@ -47,11 +55,21 @@ class FortifyServiceProvider extends ServiceProvider */ private function configureViews(): void { - Fortify::loginView(fn (Request $request) => Inertia::render('auth/Login', [ - 'canResetPassword' => Features::enabled(Features::resetPasswords()), - 'canRegister' => Features::enabled(Features::registration()), - 'status' => $request->session()->get('status'), - ])); + Fortify::loginView(function (Request $request) { + $props = [ + 'canResetPassword' => Features::enabled(Features::resetPasswords()), + 'canRegister' => Features::enabled(Features::registration()), + 'status' => $request->session()->get('status'), + ]; + + $token = $request->query('invitation'); + if ($token) { + $props['invitation'] = $token; + $request->session()->put('pending_invitation_token', $token); + } + + return Inertia::render('auth/Login', $props); + }); Fortify::resetPasswordView(fn (Request $request) => Inertia::render('auth/ResetPassword', [ 'email' => $request->email, @@ -66,7 +84,20 @@ class FortifyServiceProvider extends ServiceProvider 'status' => $request->session()->get('status'), ])); - Fortify::registerView(fn () => Inertia::render('auth/Register')); + Fortify::registerView(function (Request $request) { + $props = []; + + $token = $request->query('invitation'); + if ($token) { + $invitation = \App\Models\TeamInvitation::where('token', $token)->first(); + if ($invitation && $invitation->isValid()) { + $props['invitation'] = $token; + $props['invitationEmail'] = $invitation->email; + } + } + + return Inertia::render('auth/Register', $props); + }); Fortify::twoFactorChallengeView(fn () => Inertia::render('auth/TwoFactorChallenge')); diff --git a/resources/js/pages/auth/InvitationError.vue b/resources/js/pages/auth/InvitationError.vue new file mode 100644 index 0000000..e52b0db --- /dev/null +++ b/resources/js/pages/auth/InvitationError.vue @@ -0,0 +1,31 @@ + + + diff --git a/resources/js/pages/auth/Login.vue b/resources/js/pages/auth/Login.vue index 4cc8510..8fe3055 100644 --- a/resources/js/pages/auth/Login.vue +++ b/resources/js/pages/auth/Login.vue @@ -12,11 +12,21 @@ import { register } from '@/routes'; import { store } from '@/routes/login'; import { request } from '@/routes/password'; -defineProps<{ +type Props = { status?: string; canResetPassword: boolean; canRegister: boolean; -}>(); + invitation?: string; +}; + +const props = withDefaults(defineProps(), { + status: undefined, + invitation: undefined, +}); + +const registerUrl = props.invitation + ? `${register()}?invitation=${props.invitation}` + : register();