[Auth] Epic: Implement Google OIDC authentication #19

Objective

Implement secure Google OIDC login for GoForLift using PostgreSQL-backed server-side sessions and an opaque session ID in an HttpOnly cookie. Application JWT authentication is explicitly outside the MVP.

Architecture decisions

• Google OpenID Connect for registered-user identity
• openid-client for OIDC discovery and Authorization Code Flow
• express-session for session lifecycle and cookies
• connect-pg-simple for PostgreSQL session persistence using the existing pg pool
• csrf-sync for synchronizer-token CSRF protection
• Drizzle owns the session-table migration; runtime table creation remains disabled
• Google users are keyed by the stable sub claim, never email
• Provider tokens are not retained after login unless a future feature requires them
• No Passport and no GoForLift-issued JWT for the MVP

Architecture documentation: #2

Phase 1 — Foundation

Complete these in order:

• [Auth][Phase 1] Select and document authentication libraries #3 Select and document authentication libraries
• [Auth][Phase 1] Finalize session, cookie, CORS, and CSRF policy #4 Finalize session, cookie, CORS, and CSRF policy
• [Auth][Phase 1] Add validated authentication environment configuration #5 Add validated authentication environment configuration
• [Auth][Phase 1] Add PostgreSQL session schema and migration #6 Add PostgreSQL session schema and migration

Phase 2 — Backend authentication

Begin after the relevant Phase 1 dependencies are complete:

• [Auth][Phase 2] Configure PostgreSQL-backed session middleware #7 Configure PostgreSQL-backed session middleware
• [Auth][Phase 2] Implement Google OIDC login initiation #8 Implement Google OIDC login initiation
• [Auth][Phase 2] Implement OIDC callback and user provisioning #9 Implement OIDC callback and user provisioning
• [Auth][Phase 2] Add current-user, CSRF-token, and logout endpoints #10 Add current-user, CSRF-token, and logout endpoints
• [Auth][Phase 2] Add reusable authentication and authorization guards #11 Add reusable authentication and authorization guards

Phase 3 — Web integration

Begin after the corresponding backend contracts are stable:

• [Auth][Phase 3] Add typed web authentication client #12 Add typed web authentication client
• [Auth][Phase 3] Build Google login, guest entry, and logout UI #13 Build Google login, guest entry, and logout UI
• [Auth][Phase 3] Protect registered-user routes #14 Protect registered-user routes

Phase 4 — Hardening and delivery

Complete after the end-to-end flow works:

• [Auth][Phase 4] Add authentication and authorization integration tests #15 Add authentication and authorization integration tests
• [Auth][Phase 4] Add authentication operational safeguards #16 Add authentication operational safeguards
• [Auth][Phase 4] Run complete authentication validation and smoke test #17 Run complete authentication validation and smoke test
• [Auth][Phase 4] Finalize authentication documentation and delivery #18 Finalize authentication documentation and delivery

Cross-cutting security requirements

• Enforce authentication and resource authorization on the server
• Regenerate the session ID after successful login
• Invalidate the server-side session during logout
• Apply CSRF protection to every state-changing cookie-authenticated request
• Use explicit cookie, proxy, CORS, and redirect policies
• Never log or expose cookies, authorization codes, tokens, session contents, or secrets
• Never trust client-provided ownership information

Epic completion criteria

• Every linked issue is complete
• Architecture, database, requirements, and implementation agree
• Repository format, lint, typecheck, test, and build checks pass
• Google login, auth hydration, protected access, CSRF rejection, and logout are manually verified
• The authentication PR is reviewed and merge-ready

Out of scope

• Password authentication
• Additional identity providers
• Account linking
• Device/session management UI
• Native mobile access tokens
• Administrative session revocation
• Application JWT authentication