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>
57 lines
2.5 KiB
Markdown
57 lines
2.5 KiB
Markdown
# Cookie Auth
|
|
|
|
## Purpose
|
|
|
|
Browser authentication uses a backend-owned HttpOnly cookie. The product frontend does not store, read, or send auth tokens manually.
|
|
|
|
## Runtime Contract
|
|
|
|
- `POST /api/auth/signin/local` validates credentials, sets access and refresh HttpOnly cookies, and returns the current user profile.
|
|
- `GET /api/auth/me` authenticates from the access cookie and returns the current user profile.
|
|
- `POST /api/auth/refresh` authenticates from the refresh cookie, rotates it, sets fresh cookies, and returns the current user profile.
|
|
- `POST /api/auth/signout` revokes the active refresh token, clears both cookies, and returns `204 No Content`.
|
|
- Social auth callbacks set access and refresh cookies and redirect to the frontend without token query parameters.
|
|
|
|
## Refresh Tokens
|
|
|
|
Auth uses access/refresh cookie rotation:
|
|
|
|
- short-lived access cookie for normal Passport-protected API requests
|
|
- long-lived opaque refresh cookie used only by `POST /api/auth/refresh`
|
|
- hashed refresh token storage in the backend database
|
|
- refresh-token rotation on every successful refresh
|
|
- refresh-token family revocation when revoked-token reuse is detected
|
|
- both cookies cleared on sign-out
|
|
|
|
The frontend must not read or receive access or refresh tokens. It should only send credentialed requests and perform one controlled refresh-and-retry when an access cookie expires. If both access and refresh credentials are expired or invalid, the frontend must redirect to `/login` instead of showing a raw session error.
|
|
|
|
## Configuration
|
|
|
|
Cookie and CORS values are configured through `backend/src/config.js` from non-secret environment values:
|
|
|
|
- `ALLOWED_ORIGINS`
|
|
- `AUTH_COOKIE_NAME`
|
|
- `AUTH_COOKIE_SAME_SITE`
|
|
- `AUTH_COOKIE_SECURE`
|
|
- `AUTH_COOKIE_MAX_AGE_MS`
|
|
- `AUTH_COOKIE_DOMAIN`
|
|
|
|
Access and refresh cookie names and lifetimes are part of this config contract.
|
|
|
|
Secrets remain in environment variables only, especially `SECRET_KEY` and OAuth/email credentials.
|
|
|
|
## Code Ownership
|
|
|
|
- Cookie helpers live in `backend/src/auth/cookies.js`.
|
|
- Passport JWT extraction reads the cookie in `backend/src/auth/auth.js`.
|
|
- CSRF origin checks live in `backend/src/middlewares/csrf-origin.js`.
|
|
- Auth routes own setting and clearing cookies through helper functions.
|
|
|
|
## Security Rules
|
|
|
|
- Auth tokens must not be returned in response bodies.
|
|
- Auth tokens must not be placed in redirect URLs.
|
|
- Protected browser API routes must authenticate through the HttpOnly cookie.
|
|
- Credentialed CORS must allow only configured frontend origins.
|
|
- Unsafe methods are protected by Origin/Referer validation.
|