Files
faunosteo/docs/development/IDENTITY.md
T

133 lines
7.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Identity: auth, profile, /app shell (Step 7)
Validated by the owner on 2026-10-12. Graphic reference:
`docs/design/faunosteo-etape7-maquettes-validees.png` (see `docs/design/README.md`
for what the mockup shows beyond this step).
Source of truth for the signed-in space added in Step 7. The local tool
(`/`, `/new`, `/editor`) is untouched and needs no account; the two live side
by side until the plan's Step 14 decides what goes behind authentication.
## 1. Routes
| Route | Guard | Screen |
|---|---|---|
| `/login` | visitor only (`RedirectIfSignedIn`) | email + password, OAuth buttons per `authProviders`, link to signup / forgot |
| `/signup` | visitor only | display name, email, password ×2 → "check your inbox" step |
| `/forgot-password` | visitor only | email → "link sent" step |
| `/reset-password` | none; needs the recovery session | new password ×2; "invalid or expired link" otherwise |
| `/auth/callback` | none | landing of OAuth redirects and confirmation links; waits for the session then goes to `/app` (or `?next=`) |
| `/app` | `RequireAuth` | dashboard: greeting, profile completeness card, local tool card, account card |
| `/app/account` | `RequireAuth` | Mon compte: personal, professional, preferences (language, timezone), security (password, MFA note, sign out) |
`RequireAuth` waits for the client to read the persisted session, then sends
a visitor to `/login?next=<path>`; `next` is honoured only when it is a
same-origin path (`safeNextPath`). `/app/*` under the guard renders inside
`AppLayout` (desktop sidebar, light top bar, mobile drawer).
A deployment without Supabase (`APP_SUPABASE_URL` empty) shows an
"unavailable" notice on the auth screens; `/app` redirects to `/login`; the
Home header shows no entry to the space. With Supabase configured, the Home
header shows "Se connecter" or "Mon espace".
## 2. Session and profile in the app
- `state/authStore.ts` subscribes to `client.auth.onAuthStateChange` after
`client.auth.initialize()` (which also exchanges the PKCE code found in the
URL). Status: `loading | unavailable | signed_out | signed_in`. On sign-in it
loads `profiles` (own row) and the active `profile_roles`.
- `services/localeSync.ts`: when a profile loads, its `locale` wins over the
device choice (once per sign-in); while signed in, switching the language
(header toggle or the Preferences select) writes `profiles.locale`.
- Profile writes go through `updateOwnProfile` (`packages/supabase`), one
PATCH per account section; the columns are the ones the migrations grant
(`display_name, first_name, last_name, phone, locale, timezone,
practice_name, professional_title, siret`). `active`,
`phone_verified_at` and roles are server-only.
- Platform roles are read-only badges (`shell.role.*`); no admin screen yet.
- GoTrue errors never reach the screen: `classifyAuthError` folds codes into a
closed `AuthFailureKind`, phrased by `auth.failure.*`.
## 3. Server configuration
`supabase/config.toml`:
- email/password with confirmation mandatory, password policy 12 chars +
lower/upper/digit (mirrored client-side in `src/auth/validation.ts`);
- `[auth.external.google]` / `[auth.external.apple]` read their ids from
`env(SUPABASE_AUTH_EXTERNAL_<PROVIDER>_CLIENT_ID|SECRET)`; both are
`enabled = false` until the ids exist (put them in `supabase/.env`, gitignored,
then flip `enabled`). Google needs an OAuth client with the redirect
`http://127.0.0.1:54321/auth/v1/callback` (local) or
`https://<project>.supabase.co/auth/v1/callback`; Apple needs a paid developer
account and a Services ID (BACKEND_ARCHITECTURE §2);
- `[auth.mfa.totp]` enrolment and verification are on server-side;
- redirect URLs allow `http://127.0.0.1:5173/**` and `http://localhost:5173/**`
(local only). On the hosted project the allowlist is exact, never a host
wildcard: Site URL `https://<prod-origin>`, Redirect URLs
`https://<prod-origin>/auth/callback` and `https://<prod-origin>/reset-password`.
A broad pattern there turns `emailRedirectTo` / `redirectTo` into a
server-side open redirect.
The app side: `APP_AUTH_PROVIDERS=google,apple` (Docker) or
`VITE_AUTH_PROVIDERS` (dev) lists the buttons to show. Showing a button for a
provider the server has not enabled yields the phrased error
"this sign-in method is not enabled".
PKCE pitfall: a confirmation or recovery link must be opened in the browser
that made the request (the code verifier lives in its localStorage). Opened
elsewhere, the email is still confirmed server-side but no session opens; the
callback page says so and the user signs in normally.
## 4. MFA: what the foundations have, what is missing
Architecture §2 wants TOTP mandatory for `owner/admin/moderator/support`,
enforced by an RLS helper `has_mfa()` on admin tables. Today:
- server: TOTP enrolment/verification enabled (this step); nothing enforces it;
- SQL: no `private.has_mfa()` helper (would read `auth.jwt() ->> 'aal' = 'aal2'`);
the role helpers `private.is_platform_*` ignore the assurance level;
- app: no enrolment UI (QR + code), no `aal2` step-up on sign-in;
- there is no admin table or screen yet to protect.
The Security section shows a note instead. To close the gap (a later step):
migration adding `private.has_mfa()` and folding it into `is_platform_*` (or
into the policies of the first admin table) with pgTAP allowed/denied cases;
enrolment + challenge screens in Mon compte; step-up at sign-in for accounts
holding a platform role.
## 5. Manual validation (local stack)
```bash
pnpm db:start # prints API URL + anon key; Mailpit at http://127.0.0.1:54324
VITE_SUPABASE_URL=http://127.0.0.1:54321 VITE_SUPABASE_ANON_KEY=<anon key> \
VITE_AUTH_PROVIDERS=google pnpm dev
```
1. `/app` while signed out → `/login?next=%2Fapp`. The login card shows a
Google button (not functional until the provider is enabled: expect the
"not enabled" message).
2. Wrong password → "E-mail ou mot de passe incorrect". Seeded account
`alice@faunosteo.local` / `LocalDev-only-password-1` → lands on `/app`.
3. Dashboard: greeting, "À compléter : Prénom, Nom", "Adresse confirmée",
no platform role (owner@ shows "Propriétaire plateforme").
4. Mon compte: fill professional title / practice / SIRET → "Modifications
enregistrées"; SIRET `1234` → inline error, nothing saved. Language select
or the FR/EN toggle → the UI switches; reload → the account language is
applied (profiles.locale in Studio).
5. Mobile (375 px): hamburger opens the drawer; navigation closes it; no
horizontal scroll on login, dashboard, account.
6. Home shows "Mon espace" while signed in; sidebar "Se déconnecter" → Home with
"Se connecter"; `/app` guarded again.
7. `/signup` with a new address → "Vérifiez votre boîte mail"; open Mailpit,
click the confirmation link in the same browser → `/app` signed in,
"Adresse confirmée".
8. `/forgot-password` → Mailpit recovery link → `/reset-password` → new
password → `/app`; sign out and sign in with the new password.
9. REST: anon cannot read profiles (`42501`), alice reads one row only
(SUPABASE.md §8).
Automated: `pnpm test:run` (auth store, locale sync, forms, guards, shell,
dashboard, account, pgTAP 009), plus the headless end-to-end run described in
the Step 7 report (not part of CI).