docs(docs): IDENTITY.md (routes, session, providers, MFA gap, manual validation); CLAUDE.md map + architecture; SUPABASE.md wiring; CHANGELOG; plan note; Step 7 verify contract

This commit is contained in:
bchanot committed 2026-10-11 23:39:08 +02:00
1 parent aa1985eead
commit 552733b4c8
6 files changed
+228 -8

No files matched your search

@@ -0,0 +1,57 @@
# CONTRACT — step-07 identity, auth, /app shell (whole step, for the fresh verifier)
- date: 2026-10-11 | flow: ad-hoc step (user brief) | branch: feature/step-07-identity-app-shell
- status: active
- spec: docs/development/IDENTITY.md; user brief (below)
## REQUEST (user brief 2026-10-11, condensed — IMMUTABLE)
Implement Step 7 keeping the current visual identity (logo, palette, cream/white cards, terracotta buttons, desktop side navigation, mobile adaptation). Scope: (1) auth: email/password sign-in and sign-up, email verification, password recovery/reset, Google sign-in, Apple if clean, no phone; (2) guarded /app shell with desktop sidebar, mobile adaptation, light top bar, simple dashboard with useful cards and clean empty states, no fake modules; (3) Mon compte: personal info, professional info, preferences (incl. language), security, sign-out; (4) Supabase auth + profile integration, language synced with profiles.locale, platform roles per the foundations, MFA mandatory for admin roles if the foundations allow it, else document the gap. Constraints: existing local tool routes (home, new report, PDF import, editor) keep working unauthenticated; explicit coexistence; no unvalidated complex UI, no artificial stats, no rich admin screens, no change to the report engine.
## ACCEPTANCE CRITERIA
1. Routes exist and are wired: /login /signup /forgot-password /reset-password /auth/callback /app /app/account.
CHECK: grep -c "path=\"/login\"\|path=\"/signup\"\|path=\"/forgot-password\"\|path=\"/reset-password\"\|path=\"/auth/callback\"\|path=\"/app\"\|path=\"account\"" apps/app/src/app/App.tsx
EXPECT: 7
2. Local tool routes unchanged and unauthenticated: HomeRoute, NewReportRoute, EditorRoute are rendered outside RequireAuth; their characterisation tests pass.
CHECK: grep -n "LocalToolShell\|RequireAuth" apps/app/src/app/App.tsx | head; cd apps/app && corepack pnpm vitest run tests/unit/routes.HomeRoute.import.test.tsx tests/unit/routes.HomeRoute.archive.test.tsx tests/unit/routes.EditorRoute.test.tsx tests/unit/routes.NewReportRoute.test.tsx 2>&1 | tail -2
EXPECT: the three local routes are inside LocalToolShell (path "*"), not under the /app RequireAuth element ; passed
3. Guard: /app/* requires a session, redirects to /login?next=<same-origin path>; `next` never accepts an absolute or protocol-relative URL.
CHECK: cd apps/app && corepack pnpm vitest run tests/unit/guards.RequireAuth.test.tsx tests/unit/auth.validation.test.ts 2>&1 | tail -2; grep -n "startsWith('//')" apps/app/src/auth/redirects.ts
EXPECT: passed ; one match
4. Auth flows call the client with the right inputs: sign-in (email, password), sign-up (metadata display_name + locale, emailRedirectTo ending in /auth/callback), reset (redirectTo /reset-password), updateUser({password}), signOut, signInWithOAuth(provider, redirectTo /auth/callback).
CHECK: grep -n "emailRedirectTo\|RESET_PASSWORD_PATH\|AUTH_CALLBACK_PATH" apps/app/src/app/routes/auth/*.tsx apps/app/src/components/auth/OAuthButtons.tsx | wc -l; cd apps/app && corepack pnpm vitest run tests/unit/routes.LoginRoute.test.tsx tests/unit/routes.SignupRoute.test.tsx tests/unit/routes.AccountRoute.test.tsx 2>&1 | tail -2
EXPECT: >= 4 ; passed
5. Server errors are never shown raw: every GoTrue error goes through classifyAuthError → AuthFailure kind → `auth.failure.<kind>` key present in fr and en for every kind of the union.
CHECK: grep -o "| '[a-z_]*'" packages/supabase/src/auth.ts | sed "s/| '//;s/'//" | sort -u > /tmp/kinds.txt; for k in $(cat /tmp/kinds.txt); do grep -q "'auth.failure.$k'" apps/app/src/i18n/fr.ts && grep -q "'auth.failure.$k'" apps/app/src/i18n/en.ts || echo MISSING $k; done
EXPECT: no MISSING line (12 kinds)
6. Email verification mandatory and password policy mirrored: config.toml enable_confirmations = true, minimum_password_length = 12, password_requirements lower_upper_letters_digits; client passwordSchema min 12 + the three classes.
CHECK: grep -n "enable_confirmations = true\|minimum_password_length = 12\|lower_upper_letters_digits" supabase/config.toml | wc -l; grep -n "PASSWORD_MIN_LENGTH = 12\|\[a-z\]\|\[A-Z\]\|\[0-9\]" apps/app/src/auth/validation.ts | wc -l
EXPECT: 3 ; >= 4
7. Google and Apple: config.toml sections read ids from env(), app shows buttons only for APP_AUTH_PROVIDERS / VITE_AUTH_PROVIDERS, entrypoint and DEPLOY.md carry the variable.
CHECK: grep -n "\[auth.external.google\]\|\[auth.external.apple\]\|env(SUPABASE_AUTH_EXTERNAL" supabase/config.toml | wc -l; grep -n "APP_AUTH_PROVIDERS" docker/entrypoint.sh DEPLOY.md | wc -l; grep -n "resolveAuthProviders" apps/app/src/config/env.ts | wc -l
EXPECT: 6 ; >= 2 ; >= 2
8. Profile integration: own-row read + update through packages/supabase; professional columns exist with CHECKs and column grants; pgTAP 009 runs on PGlite and the real stack; database.types in sync.
CHECK: cd packages/supabase && corepack pnpm vitest run 2>&1 | tail -2; grep -c "grant update (practice_name, professional_title, siret)" supabase/migrations/20261011100000_profiles_professional.sql; grep -c "practice_name" packages/supabase/src/database.types.ts
EXPECT: passed ; 1 ; 3
9. Language sync both ways: profile locale applied on sign-in, switch saved to profiles.locale while signed in, untouched when signed out.
CHECK: cd apps/app && corepack pnpm vitest run tests/unit/services.localeSync.test.ts 2>&1 | tail -2
EXPECT: passed (3 tests)
10. Platform roles shown read-only (badges, `shell.role.*` for the four enum values), no grant/revoke UI.
CHECK: grep -c "'shell.role\." apps/app/src/i18n/fr.ts; grep -rn "grant_platform_role\|revoke_platform_role" apps/app/src | wc -l
EXPECT: 4 ; 0
11. MFA: documented gap (IDENTITY.md §4) and server-side TOTP enabled; the Security section shows the note; no fake enrolment UI.
CHECK: grep -n "enroll_enabled = true" supabase/config.toml | wc -l; grep -n "^## 4. MFA" docs/development/IDENTITY.md; grep -n "mfa_note" apps/app/src/components/account/SecurityPanel.tsx | wc -l
EXPECT: 1 ; one heading ; 1
12. Shell and responsive: desktop sidebar (lg:), mobile drawer behind a labelled button, no horizontal overflow risk patterns; tests pass.
CHECK: cd apps/app && corepack pnpm vitest run tests/unit/shell.AppLayout.test.tsx tests/unit/routes.DashboardRoute.test.tsx 2>&1 | tail -2; grep -n "lg:hidden\|hidden lg:flex" apps/app/src/components/shell/AppLayout.tsx | wc -l
EXPECT: passed ; >= 2
13. Dashboard content is honest: no numeric statistic, no fake module; cards = profile completeness, local tool, account facts.
CHECK: grep -n "ProfileCard\|ToolCard\|AccountCard" apps/app/src/app/routes/app/DashboardRoute.tsx | wc -l; grep -nE "[0-9]+ (bilans|reports|clients)" apps/app/src/i18n/fr.ts apps/app/src/i18n/en.ts | wc -l
EXPECT: >= 6 ; 0
14. i18n parity (fr/en same key set) and lint 0 warnings, typecheck clean, build OK.
CHECK: cd apps/app && corepack pnpm vitest run tests/unit/i18n.dicts.test.ts 2>&1 | tail -2; cd ../.. && corepack pnpm typecheck 2>&1 | grep -c "error TS"; corepack pnpm lint 2>&1 | grep -c "✖"
EXPECT: passed ; 0 ; 0
15. Coexistence explicit: Home header shows the entry only when Supabase is configured (HomeSpaceLink returns null otherwise); /app dashboard links back to the local tool.
CHECK: grep -n "if (!supabase) return null" apps/app/src/components/brand/HomeSpaceLink.tsx | wc -l; grep -n 'to="/new"\|to="/"' apps/app/src/app/routes/app/DashboardRoute.tsx | wc -l
EXPECT: 1 ; 2
16. Docs synced: IDENTITY.md exists with routes, session, config, MFA gap, manual validation; CLAUDE.md map + architecture mention the identity layer; CHANGELOG entry; plan note.
CHECK: grep -c "^## " docs/development/IDENTITY.md; grep -n "authStore\|IDENTITY.md" CLAUDE.md | wc -l; grep -n "Identity (Step 7)" CHANGELOG.md | wc -l; grep -n "Step 7 implementation note" docs/development/IMPLEMENTATION_PLAN.md | wc -l
EXPECT: 5 ; >= 2 ; 1 ; 1