Merge pull request #10 from paccloud/fix/docs-env-vars

docs: add Vite Gemini + OCR env vars

Author: paccloud

app/.env.example

@@ -12,6 +12,8 @@ VITE_API_URL=http://localhost:3000
 VITE_STACK_PROJECT_ID=your-project-id
 VITE_STACK_PUBLISHABLE_CLIENT_KEY=pck_your-publishable-key
 
+VITE_GEMINI_API_KEY=AIza...
+
 # Backend (server-side only) - NEVER expose these to the client
 STACK_PROJECT_ID=your-project-id
 STACK_SECRET_SERVER_KEY=ssk_your-secret-key

docs/ENVIRONMENT_VARIABLES.md

@@ -34,14 +34,28 @@ These are bundled into the client code and exposed to the browser:
 - `VITE_STACK_PROJECT_ID` - Stack Auth project ID
 - `VITE_STACK_PUBLISHABLE_CLIENT_KEY` - Stack Auth public key
 - `VITE_API_URL` - API base URL (empty for production, http://localhost:3000 for dev)
+- `VITE_GEMINI_API_KEY` - **Required**; Gemini API key used for Gemini integration and **bundled into client code (exposed to the browser)** (e.g. `AIza...`)
+- `VITE_OCR_ENDPOINT` - **Optional**; custom OCR backend endpoint URL (default: use the app's built-in OCR flow/config if unset; e.g. `http://localhost:3000/api/ocr`)
 
 ### Backend (Vercel Functions) - Server-side only
+
 These are only accessible on the server:
+
 - `STACK_PROJECT_ID` - Stack Auth project ID (server-side)
 - `STACK_SECRET_SERVER_KEY` - Stack Auth secret key (**NEVER expose to client**)
-- `JWT_SECRET` - Secret for signing JWT tokens
+- `JWT_SECRET` - Secret for signing JWT tokens (required; API/server will fail fast if missing)
+- `JWT_EXPIRES_IN_SECONDS` - Optional; JWT lifetime in seconds (default 86400 / 24h)
 - `DATABASE_URL` - PostgreSQL connection string
 - All `POSTGRES_*` and `PG*` variables from Neon
+- `GEMINI_API_KEY` - **MUST be server-side only** (no `VITE_` prefix); Gemini API key for AI features (e.g., spreadsheet parsing). **NEVER expose to client code**. All Gemini API calls must be routed through server endpoints (e.g., `/api/parse-spreadsheet`) - the browser should never have direct access to this key.
+
+Mitigations / security guidance:
+
+- **Client-side keys are not secrets**: anything prefixed with `VITE_` is shipped to browsers. Treat `VITE_GEMINI_API_KEY` as public.
+- **Prefer server-side proxying** for privileged features: use `GEMINI_API_KEY` only in server routes/functions and enforce auth/authorization there.
+- **Rate-limit Gemini-backed endpoints** to reduce abuse and cost exposure.
+- **Restrict keys in Google Cloud**: apply API restrictions (enable only the needed APIs), lock down allowed origins/referrers for browser keys (for `VITE_GEMINI_API_KEY`), and restrict server keys by IP/service account where possible.
+- **Scope and rotate keys**: use least-privilege API restrictions and rotate keys if exposure is suspected.
 
 ## Common Issues
 
@@ -76,6 +90,8 @@ If you get 401 Unauthorized errors when logged in with OAuth:
 
 3. Never commit `.env`, `.env.development`, or `.env.production` files - they're gitignored for security.
 
+4. For the local Express server (`server/server.js`), create `server/.env` (or `.env.local`) with `JWT_SECRET` and `ALLOWED_ORIGINS` that match your dev URLs. See `server/.env.example` for defaults.
+
 ## Production Deployment
 
 Environment variables for production are managed in Vercel:

server/.env.example

@@ -27,3 +27,6 @@ UPLOAD_DIR=./uploads
 
 # Bcrypt Configuration
 BCRYPT_SALT_ROUNDS=10
+
+# Gemini API Configuration
+GEMINI_API_KEY=AIza...