create-super-react/templates/CLAUDE.md.templates/auth-google.md

Full‑stack React starter: Vite + TS + Tailwind, Bun/Hono + SQLite, cookie auth, CSRF, and Google OAuth—scaffolded in one command.

# CLAUDE.md

This project was generated by **create-super-react** (default). It includes Google OAuth authentication with secure sessions, CSRF protection, and a clean modern UI.

## Structure
```
{{PROJECT_NAME}}/
  frontend/  → Vite + React + TypeScript + Tailwind v4 + React Router
  backend/   → Bun + Hono + SQLite (bun:sqlite)
```

## Frontend
- React Router routes: `/`, `/login`, `/dashboard` (protected), `/settings` (protected)
- `apiFetch` helper auto‑adds CSRF headers on unsafe methods and sends cookies
- **Google OAuth only** - no email/password forms
- Tailwind v4 via `@tailwindcss/vite` + `@import "tailwindcss"` in `src/index.css`
- Dev proxy: `/api` → `http://localhost:3000` so cookie sessions work in dev

## Backend
- SQLite database at `backend/data.sqlite`
- Tables:
  - `users(id, email, created_at)` (Google OAuth only, no passwords)
  - `sessions(id, user_id, token_hash, csrf_secret, created_at, expires_at, user_agent, ip)`
  - `oauth_accounts(provider, provider_user_id, user_id, created_at)`
  - `oauth_states(state, code_verifier, nonce, created_at)` (temporary PKCE state)
- Session management:
  - Session cookie: httpOnly, `SameSite=Lax`, `Secure` in prod, 30‑day TTL
- CSRF & safety:
  - Synchronizer token with **short‑lived nonce** (10 min) + **Origin/Referer check** for all authenticated actions
  - Never mutate state on GET
- Endpoints:
  - GET `/api/auth/session` → `{ id, email } | null`
  - GET `/api/auth/csrf` → `{ nonce, token, exp }`
  - POST `/api/auth/logout`
  - DELETE `/api/account` → delete account
  - GET `/api/me` (protected example)
  - Google OAuth: GET `/api/auth/google/start`, GET `/api/auth/google/callback`

## Google OAuth Setup (PKCE)
Create `backend/.env` (copy from generated `.env.example`):
```env
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
FRONTEND_ORIGIN=http://localhost:5173
OAUTH_REDIRECT_URI=http://localhost:3000/api/auth/google/callback
```
Then add the redirect URI in Google Cloud Console and restart the backend.

## Dev commands
```bash
# API
cd backend && bun run dev    # http://localhost:3000

# Web
cd ../frontend && npm run dev  # http://localhost:5173
```

## Troubleshooting
- **Bad origin** → set `FRONTEND_ORIGIN` to your frontend dev/prod origin
- **CSRF missing/invalid/expired** → use `apiFetch` or fetch `/api/auth/csrf` and send `X‑CSRF‑Nonce` + `X‑CSRF‑Token`
- **Google not configured** → fill `.env` values above