Initial commit: waitlist microservice

README.md

@@ -0,0 +1,69 @@
+# adiuvAI Waitlist Service
+
+Minimal FastAPI microservice that stores waitlist email signups in PostgreSQL.
+
+## Security
+
+Designed to sit behind **Cloudflare** (WAF + DDoS protection). Additional hardening:
+
+| Layer | What |
+|-------|------|
+| **Cloudflare** | WAF, bot management, DDoS mitigation (external) |
+| **Rate limiter** | 5 req/min per IP, Cloudflare-aware (`CF-Connecting-IP`) |
+| **Origin validation** | Rejects POST without valid `Origin`/`Referer` in production |
+| **CORS** | Locked to `adiuvai.com` origins only |
+| **Honeypot field** | Hidden `website` field — bots that fill it get a silent 200 |
+| **Request size limit** | 4 KB max body (email payload is ~100 bytes) |
+| **Input validation** | Pydantic `EmailStr` with normalization |
+| **SQL injection** | SQLAlchemy parameterized queries (no raw SQL) |
+| **No PII leakage** | Errors return generic messages, no email reflection |
+| **Docs disabled in prod** | `/docs` and `/openapi.json` only in development |
+| **Idempotent** | Duplicate emails return success (no enumeration) |
+
+## Quick Start
+
+```bash
+# 1. Start Postgres + app
+docker compose up --build
+
+# 2. Test
+curl -X POST https://waitlist.adiuvai.com/api/v1/waitlist \
+  -H "Content-Type: application/json" \
+  -d '{"email": "user@example.com"}'
+```
+
+## Local Development
+
+```bash
+cd waitlist
+python -m venv .venv
+.venv\Scripts\Activate.ps1   # Windows
+pip install -r requirements.txt
+
+# Copy and edit .env
+cp .env.example .env
+
+# Run migrations
+alembic upgrade head
+
+# Start dev server
+uvicorn app.main:app --reload --port 8001
+
+# Run tests
+pip install pytest pytest-asyncio httpx aiosqlite
+pytest tests/ -v
+```
+
+## Deployment (Cloudflare)
+
+1. Point `waitlist.adiuvai.com` to your server via Cloudflare DNS (orange cloud ON)
+2. Set environment variables (see `.env.example`)
+3. `docker compose up -d`
+4. Cloudflare handles TLS termination, bot filtering, and rate limiting at the edge
+
+### Recommended Cloudflare Settings
+
+- **WAF**: Enable managed rulesets (OWASP Core)
+- **Bot Fight Mode**: ON
+- **Rate Limiting Rule**: 10 req/10s to `/api/v1/waitlist` (defense in depth)
+- **SSL mode**: Full (Strict)