# 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.