d4a5378adf
Frontend: - Replace Next.js with Vite + React + TypeScript - Add new component architecture (app-shell, sidebar, dashboard modules) - Implement product modules: FRAME, safety protocols, walkthrough checkin, campus/staff attendance, personality quiz, sign language, classroom timer - Add shadcn/ui component library with Tailwind CSS - Remove legacy generated components, stores, and pages Backend: - Add product migrations: frame_entries, user_progress, safety_quiz_results, walkthrough_checkins, communication_events, personality_quiz_results, campus_attendance_config/summaries, staff_attendance_records, content_catalog - Add corresponding models, services, and routes - Implement cookie-based auth with refresh token rotation - Add content catalog seeder with product content - Migrate to ESLint flat config - Switch from yarn to npm Infrastructure: - Update .gitignore for new tooling - Add project documentation (CLAUDE.md, docs/) - Remove deprecated config files and yarn.lock Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
85 lines
4.2 KiB
Markdown
85 lines
4.2 KiB
Markdown
# Auth Integration
|
|
|
|
## Purpose
|
|
|
|
The product frontend authenticates through backend-owned session cookies.
|
|
|
|
The backend transport details are documented in `backend/docs/cookie-auth.md`.
|
|
|
|
## Runtime Configuration
|
|
|
|
The frontend reads only public browser-safe API configuration from:
|
|
|
|
- `VITE_BACKEND_API_URL`
|
|
|
|
Local values live in ignored `frontend/.env` files; the template value is documented in `frontend/.env.example`.
|
|
|
|
Do not add secrets to frontend env files. Vite exposes `VITE_*` values to the browser bundle.
|
|
|
|
## Auth Flow
|
|
|
|
1. `AuthContext` delegates auth state to `useAuthSession` from `frontend/src/business/auth/hooks.ts`.
|
|
2. `useAuthSession.signIn` calls `POST /api/auth/signin/local` through `frontend/src/shared/api/auth.ts`.
|
|
3. The backend sets an HttpOnly auth cookie and returns the current user profile.
|
|
4. `useAuthSession` restores the session with `GET /api/auth/me`.
|
|
5. The backend returns the current product profile, including `productRole`, `campus`, `staffProfile`, and `permissions`.
|
|
6. UI-facing `StaffProfile` is derived in `frontend/src/business/auth/mappers.ts`.
|
|
7. `useAuthSession.signOut` calls `POST /api/auth/signout`; the backend clears the auth cookie.
|
|
8. `SignInModal` delegates modal mode, form draft state, validation, and submit workflow to `useAuthModalWorkflow`.
|
|
|
|
## Refresh Tokens
|
|
|
|
The refresh flow keeps tokens backend-owned:
|
|
|
|
1. Backend sign-in sets short-lived access and long-lived refresh HttpOnly cookies.
|
|
2. Protected API requests use the access cookie only.
|
|
3. `POST /api/auth/refresh` uses the refresh cookie only, rotates it server-side, sets fresh cookies, and returns the current user profile.
|
|
4. `httpClient` performs one controlled refresh-and-retry after an access-expiry `401`.
|
|
5. If refresh fails because both access and refresh credentials are expired or invalid, the business layer clears the user and redirects to `/login`.
|
|
6. Non-auth backend failures remain observable errors; no infinite retry and no silent fallback.
|
|
|
|
The frontend must not read, store, or receive access or refresh token values.
|
|
|
|
## Login Route
|
|
|
|
The app exposes `/login` as the deterministic destination for expired sessions. Sign-in also remains available as a modal for in-app guest prompts.
|
|
|
|
Rules:
|
|
|
|
- `/login` must reuse the existing auth business hook and API functions.
|
|
- Auth-expired redirects must use `replace: true`.
|
|
- Safe return paths may be preserved only for same-origin product routes.
|
|
- Tokens and raw session failure details must never be placed in the URL.
|
|
- Expired access plus valid refresh must restore the session without redirecting.
|
|
- Expired access plus expired refresh must redirect to `/login` without showing a raw error.
|
|
|
|
## Layering
|
|
|
|
- View/provider: `frontend/src/contexts/AuthContext.tsx`, `frontend/src/components/frameworks/SignInModal.tsx`, and `frontend/src/components/sign-in-modal/`
|
|
- Business logic: `frontend/src/business/auth/`
|
|
- API/data access: `frontend/src/shared/api/auth.ts`
|
|
- Backend contract types: `frontend/src/shared/types/auth.ts`
|
|
|
|
## Deferred Product Onboarding
|
|
|
|
Registration, company creation, campus creation, user creation, staff profile creation, and profile updates are intentionally deferred.
|
|
|
|
The backend has generated auth signup/profile endpoints, but the customer has not approved the product workflow for creating companies, campuses, users, role assignments, campus assignments, and staff profiles.
|
|
|
|
Rules:
|
|
|
|
- Do not implement frontend registration or profile creation flows until the backend product contract is defined.
|
|
- Do not treat generated auth signup/profile endpoints as the product onboarding contract.
|
|
- Track the cross-application onboarding task in `docs/full-integration-refactor-plan.md`.
|
|
- New persisted workflows must use typed backend API modules and business-layer hooks.
|
|
|
|
## Standards
|
|
|
|
- Do not duplicate backend role mapping in the frontend.
|
|
- Do not add frontend secrets.
|
|
- Do not store auth tokens in frontend browser storage.
|
|
- Do not expose auth tokens in URLs or API responses.
|
|
- Do not add frontend refresh-token storage; refresh uses only backend-owned HttpOnly cookies.
|
|
- New persisted workflows must use `frontend/src/shared/api/` through `frontend/src/business/<module>/`.
|
|
- New server state should use business-layer hooks built on top of shared API modules.
|