create-super-react/templates/CLAUDE.md.templates/auth-password.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** with the **--password-auth** flag. It includes email/password authentication plus Google OAuth, with **local auth (scrypt + secure cookie sessions)**, **CSRF protection** (synchronizer nonce + Origin check), and **Google OAuth (PKCE)**.

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

## Frontend
- React Router routes: `/`, `/login`, `/signup`, `/dashboard` (protected), `/settings` (protected)
- `apiFetch` helper auto‑adds CSRF headers on unsafe methods and sends cookies
- Email/password forms with show/hide toggles (Lucide icons)
- Google OAuth "Continue with Google" buttons
- 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, password_hash?, created_at)` (password_hash is NULL for OAuth‑only users)
  - `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)
- Local auth:
  - Password hashing: **scrypt** (Node crypto) with per‑user salt
  - Session cookie: httpOnly, `SameSite=Lax`, `Secure` in prod, 30‑day TTL, rotation on login
- CSRF & safety:
  - Synchronizer token with **short‑lived nonce** (10 min) + **Origin/Referer check**
  - CSRF is **skipped only** for `/api/auth/login` and `/api/auth/signup` (before a session exists)
  - Never mutate state on GET
- Endpoints:
  - POST `/api/auth/signup`, POST `/api/auth/login`, POST `/api/auth/logout`
  - GET `/api/auth/session` → `{ id, email } | null`
  - GET `/api/auth/csrf` → `{ nonce, token, exp }`
  - PUT `/api/account/password` → change password
  - 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. Users can sign up with email/password OR click **Continue with Google** on `/login` or `/signup`.

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