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) <noreply@anthropic.com>

_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.

_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
+
+<frozen-after-approval reason="human-owned intent — do not modify unless human renegotiates">
+
+## 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 |
+
+</frozen-after-approval>
+
+## 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

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;
     }
 }

app/Http/Controllers/TeamInvitationAcceptController.php

@@ -0,0 +1,103 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Models\TeamInvitation;
+use App\Models\User;
+use App\Models\WorkspaceUser;
+use Illuminate\Http\RedirectResponse;
+use Illuminate\Support\Facades\Auth;
+use Illuminate\Support\Facades\DB;
+use Inertia\Inertia;
+use Inertia\Response;
+
+class TeamInvitationAcceptController extends Controller
+{
+    /**
+     * Handle team invitation acceptance.
+     */
+    public function __invoke(string $token): Response|RedirectResponse
+    {
+        $invitation = TeamInvitation::where('token', $token)->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]));
+    }
+}

app/Http/Responses/LoginResponse.php

@@ -0,0 +1,61 @@
+<?php
+
+namespace App\Http\Responses;
+
+use App\Models\TeamInvitation;
+use App\Models\WorkspaceUser;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Facades\DB;
+use Laravel\Fortify\Contracts\LoginResponse as LoginResponseContract;
+
+class LoginResponse implements LoginResponseContract
+{
+    /**
+     * Create an HTTP response that represents the object.
+     *
+     * @param  \Illuminate\Http\Request  $request
+     * @return \Symfony\Component\HttpFoundation\Response
+     */
+    public function toResponse($request)
+    {
+        $token = $request->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'));
+    }
+}

app/Http/Responses/RegisterResponse.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Http\Responses;
+
+use Illuminate\Http\JsonResponse;
+use Laravel\Fortify\Contracts\RegisterResponse as RegisterResponseContract;
+
+class RegisterResponse implements RegisterResponseContract
+{
+    /**
+     * Create an HTTP response that represents the object.
+     *
+     * @param  \Illuminate\Http\Request  $request
+     * @return \Symfony\Component\HttpFoundation\Response
+     */
+    public function toResponse($request)
+    {
+        if ($request->session()->pull('invitation_accepted')) {
+            return redirect()->intended('/dashboard');
+        }
+
+        return $request->wantsJson()
+            ? new JsonResponse('', 201)
+            : redirect()->intended(config('fortify.home'));
+    }
+}

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'),
             ]
         );

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', [
+        Fortify::loginView(function (Request $request) {
-            'canResetPassword' => Features::enabled(Features::resetPasswords()),
+            $props = [
-            'canRegister' => Features::enabled(Features::registration()),
+                'canResetPassword' => Features::enabled(Features::resetPasswords()),
-            'status' => $request->session()->get('status'),
+                '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'));
 

resources/js/pages/auth/InvitationError.vue

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+import { Head } from '@inertiajs/vue3';
+import TextLink from '@/components/TextLink.vue';
+import AuthBase from '@/layouts/AuthLayout.vue';
+
+type Props = {
+    title: string;
+    message: string;
+    homeUrl: string;
+};
+
+defineProps<Props>();
+</script>
+
+<template>
+    <AuthBase
+        :title="title"
+        :description="message"
+    >
+        <Head :title="title" />
+
+        <div class="flex flex-col items-center gap-4">
+            <TextLink
+                :href="homeUrl"
+                class="underline underline-offset-4"
+            >
+                Retour à l'accueil
+            </TextLink>
+        </div>
+    </AuthBase>
+</template>

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<Props>(), {
+    status: undefined,
+    invitation: undefined,
+});
+
+const registerUrl = props.invitation
+    ? `${register()}?invitation=${props.invitation}`
+    : register();
 </script>
 
 <template>
@@ -39,6 +49,8 @@ defineProps<{
             v-slot="{ errors, processing }"
             class="flex flex-col gap-6"
         >
+            <input v-if="invitation" type="hidden" name="invitation" :value="invitation" />
+
             <div class="grid gap-6">
                 <div class="grid gap-2">
                     <Label for="email">Email address</Label>
@@ -103,7 +115,7 @@ defineProps<{
                 v-if="canRegister"
             >
                 Don't have an account?
-                <TextLink :href="register()" :tabindex="5">Sign up</TextLink>
+                <TextLink :href="registerUrl" :tabindex="5">Sign up</TextLink>
             </div>
         </Form>
     </AuthBase>

resources/js/pages/auth/Register.vue

@@ -9,14 +9,28 @@ import { Spinner } from '@/components/ui/spinner';
 import AuthBase from '@/layouts/AuthLayout.vue';
 import { login } from '@/routes';
 import { store } from '@/routes/register';
+
+type Props = {
+    invitation?: string;
+    invitationEmail?: string;
+};
+
+const props = withDefaults(defineProps<Props>(), {
+    invitation: undefined,
+    invitationEmail: undefined,
+});
+
+const loginUrl = props.invitation
+    ? `${login()}?invitation=${props.invitation}`
+    : login();
 </script>
 
 <template>
     <AuthBase
-        title="Create an account"
+        :title="invitation ? 'Rejoindre l\'espace de travail' : 'Create an account'"
-        description="Enter your details below to create your account"
+        :description="invitation ? 'Créez votre compte pour accepter l\'invitation' : 'Enter your details below to create your account'"
     >
-        <Head title="Register" />
+        <Head :title="invitation ? 'Rejoindre l\'espace de travail' : 'Register'" />
 
         <Form
             v-bind="store.form()"
@@ -24,6 +38,8 @@ import { store } from '@/routes/register';
             v-slot="{ errors, processing }"
             class="flex flex-col gap-6"
         >
+            <input v-if="invitation" type="hidden" name="invitation" :value="invitation" />
+
             <div class="grid gap-6">
                 <div class="grid gap-2">
                     <Label for="name">Name</Label>
@@ -49,7 +65,9 @@ import { store } from '@/routes/register';
                         :tabindex="2"
                         autocomplete="email"
                         name="email"
-                        placeholder="email@example.com"
+                        :placeholder="invitationEmail ?? 'email@example.com'"
+                        :value="invitationEmail"
+                        :readonly="!!invitationEmail"
                     />
                     <InputError :message="errors.email" />
                 </div>
@@ -97,7 +115,7 @@ import { store } from '@/routes/register';
             <div class="text-center text-sm text-muted-foreground">
                 Already have an account?
                 <TextLink
-                    :href="login()"
+                    :href="loginUrl"
                     class="underline underline-offset-4"
                     :tabindex="6"
                     >Log in</TextLink

resources/views/emails/team-invitation.blade.php

@@ -5,9 +5,9 @@ Bonjour,
 
 Vous êtes invité(e) à rejoindre le cabinet **{{ $workspaceName }}** en tant que **{{ $roleLabel }}**.
 
-Cliquez sur le bouton ci-dessous pour créer votre compte et rejoindre l'équipe.
+Cliquez sur le bouton ci-dessous pour rejoindre l'équipe.
 
-<x-mail::button :url="$registerUrl" color="primary">
+<x-mail::button :url="$acceptUrl" color="primary">
 Rejoindre l'équipe
 </x-mail::button>
 

routes/web.php

@@ -7,6 +7,9 @@ Route::inertia('/', 'Welcome', [
     'canRegister' => Features::enabled(Features::registration()),
 ])->name('home');
 
+Route::get('team/invitation/{token}/accept', \App\Http\Controllers\TeamInvitationAcceptController::class)
+    ->name('team.invitation.accept');
+
 Route::middleware(['auth', 'verified'])->group(function () {
     Route::get('dashboard', \App\Http\Controllers\DashboardController::class)->name('dashboard');
     Route::post('workspace/switch', \App\Http\Controllers\WorkspaceSwitchController::class)