40227-vm/cookie-auth.md at d4a5378adfac8e4c130157a1a7f807b4dc9a941c

Dmitri d4a5378adf Refactor: migrate frontend to Vite/React, add product backend modules

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>

2026-06-09 15:18:23 +02:00

2.5 KiB

Raw Blame History

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.

2.5 KiB Raw Blame History

Cookie Auth