Feature: Secure Cookie Auth + Session Management (FEAT-31)

Summary

Introduces HTTP-only cookie authentication with refresh-token rotation and database-backed sessions in the public schema. This is the baseline for protected features such as uploads, AI usage, premium access, and user personalization.

Backend Scope

• New auth endpoints: signup, login, refresh, logout, me, verify-email, resend-verification
• Password hashing with bcrypt
• Session persistence in auth_sessions
• Hashed refresh token storage and rotation on every refresh
• Email verification token issuance/consumption via email_verification_tokens
• Guard-based protection on user-scoped routes

Cookie and Token Policy

• access_token: short-lived (default 15 minutes)
• refresh_token: long-lived (7-30 days, default 30 days)
• Tokens are stored in HTTP-only cookies only (no localStorage)
• Hosted env: cookie domain shared on .studyboost.com
• Local dev: host-only cookie domain for localhost compatibility

Frontend Guard Behavior

• Dedicated auth pages are the only auth entry points: /login, /signup
• Unauthenticated access to protected routes/actions redirects to /login?next=<target>
• No in-page auth modal fallback in FEAT-31

QA Coverage Expectations

Use docs/features/FEAT-31-secure-cookie-auth-session-management.md as the implementation-level source of truth for scenario IDs (FEAT-31-01 ...). Required coverage:

• signup/login happy paths
• protected route authorization
• access expiry with auto-refresh
• refresh replay rejection after rotation
• logout invalidation behavior
• auth rate-limiting behavior
• email verification flow

Related Docs

• Features contract: /docs/features
• QA requirements: /docs/features/qa-requirements
• Database schema: /docs/database-schema
• Core systems: /docs/core-systems