# Security and operational runbook

Grounded in docs/security-notes.md and docs/ops-runtime.md.

## Controls in place

| Area | Control |
|------|---------|
| CSRF | Double-submit cookie + X-CSRF-Token on dashboard /api/* (skipped for /api/v1, /api/public/*, webhooks) |
| Sessions | scs + Postgres store; HttpOnly; idle SESSION_IDLE_HOURS (default 24); absolute 7d |
| CORS | Allowlist = WEB_ORIGIN only; credentials allowed |
| SSRF | Feed + Woo URL checks; Shopify *.myshopify.com; optional FEED_URL_PRIVATE_ALLOWLIST / settings allowlist |
| Uploads | CSV/logo size + type caps under UPLOAD_DIR/{company_id}/ |
| AuthZ | Session company context; API key company binding; admin vs support_staff |
| Rate limits | Auth POSTs / IP; process/sync/export / company (in-process — not cluster-global) |

## Ops runbook

```mermaid
flowchart LR
  Deploy --> Migrate["scripts/migrate.ps1 / goose up"]
  Migrate --> API[cmd/api]
  Migrate --> Worker[cmd/worker]
  API --> Probes["/healthz /readyz"]
  Worker --> Probes
  Probes --> Hypercare["/api/admin/readiness + diagnostics"]
```

1. **Bring up:** Docker Postgres → migrate → API + **worker** → web.  
2. **Probes:** /healthz no DB; /readyz pings Postgres and reports maintenance/read_only.  
3. **Maintenance:** MAINTENANCE_MODE / READ_ONLY_MODE — keep probes green during cutover rehearsal.  
4. **Mail:** Platform invites need SMTP_ENABLED + host/from; tenant marketing mail is separate.  
5. **Credentials:** Set APP_ENCRYPTION_KEY before storing production Woo/AI secrets; rotating without re-save breaks ciphertext.  
6. **Stuck jobs:** diagnostics → stuck-cleanup → retry; ensure worker is running.  
7. **Support auto-reply:** default off (enabled=false); publish KB + raise threshold before enabling FAQ; AI needs support role configured.  
8. **Never log:** Stripe/OpenAI/SMTP/Woo/Shopify/EPREL secrets.

## Known residual risks (honest)

In-process rate limits do not cluster; broad private feed allowlists re-enable SSRF; public export tokens rely on entropy; demo API keys are local-only.

For cutover blockers and SMTP verification, see docs/ops-runtime.md and docs/production-checklist.md.