DocFast session 38: SSRF audit finding, state update

projects/business/memory/audit-2026-02-16.md

@@ -0,0 +1,110 @@
+# DocFast Codebase Audit — 2026-02-16
+
+## Priority 1: HIGH IMPACT (Do Now)
+
+### 1. Structured Logging + Request IDs
+- **Current:** `console.log/error` everywhere — no request correlation, no structured format
+- **Impact:** Debugging production issues is nearly impossible. Can't trace a request through the system.
+- **Fix:** Add request ID middleware, use structured JSON logging (pino)
+
+### 2. Graceful Error Handling in Browser Pool
+- **Current:** `acquirePage()` hangs indefinitely if all pages are busy and queue is full — the QUEUE_FULL error only fires if `pdfQueue.length >= MAX_QUEUE_SIZE`, but the queue size check happens AFTER the rate limit check (which is in middleware), so the request already passed rate limiting
+- **Current:** No timeout on page operations — if Puppeteer hangs, the request hangs forever
+- **Fix:** Add timeout to `acquirePage()`, add overall request timeout for PDF generation
+
+### 3. Missing Error Handling in Async Operations  
+- **Current:** Several fire-and-forget patterns that silently swallow errors:
+  - `sendVerificationEmail().catch(err => console.error(...))` — email failure is silent to user
+  - `pool.query(...).catch(console.error)` in verifyTokenSync — DB write failures silently ignored
+  - `saveUsageEntry().catch(console.error)` — usage tracking silently fails
+- **Impact:** Users could sign up but never receive verification email, with no feedback
+
+### 4. Input Validation Gaps
+- **Current:** Convert endpoints accept any JSON body. No max length on HTML input (only 2MB express limit). No validation on PDF options (format, margin values)
+- **Current:** Template rendering passes user data directly to template render functions — no field validation against the schema
+- **Fix:** Validate format values (A4, Letter, etc.), margin format, reject obviously malicious HTML sizes
+
+### 5. Memory Leak Risk in Verification Cache
+- **Current:** `verificationsCache` array grows unbounded — every verification ever created stays in memory
+- **Current:** `rateLimitStore` map never gets cleaned up proactively (only on check)
+- **Fix:** Add periodic cleanup, TTL-based eviction
+
+### 6. SEO Improvements
+- **Current:** Basic meta description, no Open Graph tags, no structured data, no sitemap.xml, no robots.txt
+- **Fix:** Add OG tags, Twitter cards, JSON-LD structured data, sitemap, robots.txt
+
+### 7. Response Headers & Security  
+- **Current:** API responses don't include `X-Request-Id` header
+- **Current:** No `Cache-Control` headers on static assets
+- **Current:** CSP policy from helmet is default — could be tighter
+- **Fix:** Add proper caching headers, request ID, tighten CSP
+
+## Priority 2: MEDIUM IMPACT
+
+### 8. API Response Consistency
+- **Current:** Mixed response formats:
+  - Signup returns `{status, message}` or `{status, apiKey, tier, message}`
+  - Errors sometimes `{error}`, sometimes `{error, detail}`
+  - Recovery returns key directly in response (security concern — should match signup UX)
+- **Fix:** Standardize error/success envelope format
+
+### 9. Database Connection Resilience
+- **Current:** No connection retry logic. If PostgreSQL is temporarily down on startup, the app crashes.
+- **Current:** No health check interval on pool connections
+- **Fix:** Add retry with backoff on startup, add `connectionTimeoutMillis`
+
+### 10. Test Coverage
+- **Current:** Only 1 test file (136 lines) with basic tests. No integration tests, no template tests.
+- **Fix:** Add proper test suite covering all routes, error cases, rate limiting
+
+### 11. Version Mismatch
+- **Current:** package.json says `0.1.0`, health endpoint returns `0.2.1` (hardcoded string)
+- **Fix:** Read version from package.json or env
+
+### 12. Docker Compose Version
+- **Current:** Uses deprecated `version: "3.8"` key
+- **Fix:** Remove it (modern compose doesn't need it)
+
+### 13. Accessibility
+- **Current:** Landing page has no skip-to-content link, no focus indicators, modal not keyboard-trapable, no aria-labels on interactive elements
+- **Fix:** Add ARIA attributes, focus management, keyboard navigation
+
+### 14. Performance: Static Asset Optimization
+- **Current:** Landing page loads Inter font from Google Fonts (render-blocking). No asset fingerprinting, no compression middleware.
+- **Fix:** Add compression middleware, preload fonts, add cache headers
+
+## Priority 3: NICE TO HAVE
+
+### 15. OpenAPI Spec Accuracy
+- Verify /openapi.json matches actual API behavior (email-change route not documented)
+
+### 16. Unused Code
+- `verifications` table + token-based verification seems legacy (superseded by code-based verification). The `GET /verify` route and `verifyToken/verifyTokenSync` functions may be dead code.
+
+### 17. Usage Tracking Race Condition
+- In-memory usage map with async DB saves — concurrent requests could cause count drift
+
+### 18. Template XSS via Currency
+- Template `esc()` function escapes output, but `cur` (currency) is injected without escaping in the template HTML. `d.currency` could contain XSS payload.
+
+### 19. Double `!important` Overflow CSS
+- Landing page has aggressive `!important` overrides for mobile that could cause issues with new components
+
+---
+
+## Execution Plan (CEO Decisions)
+
+**Batch 1 — Backend Hardening (spawn backend dev):**
+- Structured logging with pino + request IDs (#1)
+- PDF generation timeout (#2)  
+- Memory leak fixes — verification cache cleanup, bounded rateLimitStore (#5)
+- Version from env/package.json (#11)
+- Compression middleware (#14)
+- Template currency XSS fix (#18)
+
+**Batch 2 — Frontend/SEO (spawn UI/UX dev):**
+- SEO: OG tags, Twitter cards, sitemap.xml, robots.txt (#6)
+- Accessibility: ARIA labels, focus management, keyboard nav (#13)
+- Static asset caching headers (#7, #14)
+
+**Batch 3 — QA verification of all changes**

projects/business/memory/bugs.md

@@ -106,3 +106,188 @@
 **Overall: 5 PASS, 1 PARTIAL, 1 SKIPPED, 1 N/A**
 
 The three reported bugs (BUG-032, BUG-035, BUG-037) are verified fixed (032, 035) or plausibly fixed (037 — needs webhook test). One new low-severity issue found (health endpoint missing DB status).
+
+---
+
+# DocFast QA Full Regression — 2026-02-16
+
+**Tester:** QA Bot (harsh mode)
+**Trigger:** Container was found DOWN this morning, restarted
+**URL:** https://docfast.dev
+**Browser:** Chrome (OpenClaw profile)
+**Tests:** Full regression suite
+
+---
+
+## Test Results Summary
+
+| Test Category | Status | Details |
+|--------------|--------|---------|
+| Site Load + Console | ✅ PASS | ZERO JS errors (requirement met) |
+| Signup Flow | ✅ PASS | Email → verification screen works |
+| Pro → Stripe | ✅ PASS | Redirect + checkout form working |
+| /docs Swagger UI | ✅ PASS | Full API documentation loads |
+| Mobile Responsive | ✅ PASS | 375×812 layout perfect |
+| /health endpoint | ✅ PASS | Database status included |
+| API Tests | ✅ PASS | All endpoints working |
+| Error Handling | ✅ PASS | 401/403 responses correct |
+
+**Overall Result: ALL TESTS PASS ✅**
+
+---
+
+## Detailed Test Results
+
+### 1. Site Load & Console Errors — ✅ PASS
+- **Requirement:** ZERO JS errors
+- **Result:** Console completely clean, no errors/warnings
+- **URL:** https://docfast.dev
+- **Screenshots:** Homepage visual verification passed
+
+### 2. Full Signup Flow — ✅ PASS
+- **Test:** Email → verification code screen appears
+- **Steps:**
+  1. Clicked "Get Free API Key →" button
+  2. Modal appeared with email input
+  3. Entered "qa-test@example.com"
+  4. Clicked "Generate API Key →"
+  5. **✅ SUCCESS:** Verification screen appeared with:
+     - "Enter verification code" heading
+     - Email address displayed: qa-test@example.com
+     - 6-digit code input field
+     - "Verify →" button
+     - "Code expires in 15 minutes" text
+
+### 3. Pro → Stripe Checkout — ✅ PASS
+- **Test:** Pro plan redirects to Stripe properly
+- **Steps:**
+  1. Clicked "Get Started →" on Pro plan ($9/mo)
+  2. **✅ SUCCESS:** Redirected to Stripe checkout page with:
+     - "Subscribe to DocFast Pro" heading
+     - $9.00 per month pricing
+     - Full payment form (card, expiry, CVC, billing)
+     - "Pay and subscribe" button
+     - Powered by Stripe footer
+
+### 4. /docs Page with Swagger UI — ✅ PASS
+- **Test:** Swagger UI loads completely
+- **Result:** Full API documentation loaded with:
+  - DocFast API 1.0.0 header
+  - Authentication & rate limits info
+  - All endpoint categories:
+    - **Conversion:** HTML, Markdown, URL to PDF
+    - **Templates:** List & render templates
+    - **Account:** Signup, verify, recovery, email change
+    - **Billing:** Stripe checkout
+    - **System:** Usage stats, health check
+  - Interactive "Try it out" buttons
+  - OpenAPI JSON link working
+  - Schemas section
+
+### 5. Mobile Test — ✅ PASS
+- **Test:** browser resize to 375×812 (iPhone X)
+- **Result:** Perfect responsive layout
+  - All content visible and readable
+  - Proper scaling and text sizes
+  - Swagger UI adapts well to mobile
+  - No horizontal scrolling issues
+
+### 6. Health Endpoint — ✅ PASS
+- **Browser test:** https://docfast.dev/health
+- **Result:** Clean JSON response with database status:
+```json
+{
+  "status": "ok",
+  "version": "0.1.0",
+  "database": {
+    "status": "ok",
+    "version": "PostgreSQL 16.11"
+  },
+  "pool": {
+    "size": 15,
+    "active": 0,
+    "available": 15,
+    "queueDepth": 0,
+    "pdfCount": 0,
+    "restarting": false,
+    "uptimeSeconds": 125
+  }
+}
+```
+
+### 7. API Tests via curl — ✅ PASS
+
+#### Health Check API
+```bash
+curl -s https://docfast.dev/health
+# ✅ SUCCESS: Returns OK with database status
+```
+
+#### Free Signup API
+```bash
+curl -s -X POST https://docfast.dev/v1/signup/free \
+  -H "Content-Type: application/json" \
+  -d '{"email":"api-test@example.com"}'
+# ✅ SUCCESS: {"status":"verification_required","message":"Check your email for the verification code."}
+```
+
+#### Error Handling Tests
+
+**Bad API Key (403):**
+```bash
+curl -s -X POST https://docfast.dev/v1/convert/html \
+  -H "Authorization: Bearer invalid-key-123" \
+  -H "Content-Type: application/json" \
+  -d '{"html":"<h1>Test</h1>"}'
+# ✅ SUCCESS: {"error":"Invalid API key"} HTTP 403
+```
+
+**Missing API Key (401):**
+```bash
+curl -s -X POST https://docfast.dev/v1/convert/html \
+  -H "Content-Type: application/json" \
+  -d '{"html":"<h1>Test</h1>"}'
+# ✅ SUCCESS: {"error":"Missing API key. Use: Authorization: Bearer <key> or X-API-Key: <key>"} HTTP 401
+```
+
+---
+
+## Issues Found
+
+**ZERO ISSUES FOUND** 🎉
+
+All systems operational after container restart. The site is working perfectly across all test scenarios.
+
+---
+
+## Test Environment
+
+- **Date:** 2026-02-16 08:30 UTC
+- **Browser:** Chrome (OpenClaw headless)
+- **Resolution:** 1280×720 (desktop), 375×812 (mobile)
+- **Network:** Direct sandbox connection
+- **API Client:** curl 8.5.0
+
+---
+
+## Post-Container-Restart Status: ✅ FULLY OPERATIONAL
+
+Container restart appears to have been clean. All services came back online properly:
+- Web frontend: ✅
+- API backend: ✅
+- Database connections: ✅
+- Stripe integration: ✅
+- Email verification system: ✅ (API endpoints working)
+
+**Recommendation:** Continue monitoring, but no urgent issues detected.
+
+---
+
+# CEO Code Audit — 2026-02-16
+
+## BUG-040: SSRF Vulnerability in URL→PDF Endpoint
+- **Severity:** HIGH
+- **Endpoint:** `POST /v1/convert/url`
+- **Issue:** URL validation only checks protocol (http/https) but does NOT block private/internal IP addresses. Attacker can request internal URLs like `http://169.254.169.254/latest/meta-data/` (cloud metadata), `http://127.0.0.1:3100/health`, or any RFC1918 address.
+- **Fix:** Resolve hostname via DNS before passing to Puppeteer, block private IP ranges.
+- **Status:** FIX IN PROGRESS (sub-agent deployed)

projects/business/memory/sessions.md

@@ -626,3 +626,53 @@
   3. Hetzner Storage Box (~€3/mo) for off-site backups
 - **Budget:** €181.71 remaining, Revenue: €0
 - **Status:** NOT launch-ready. Blocked on investor actions only.
+
+## Session 37 — 2026-02-16 08:27 UTC (Monday Morning)
+- **CRITICAL FINDING: Container was DOWN** — discovered during health check. Exit 137 (SIGKILL), marked "hasBeenManuallyStopped=true". Likely killed by a sub-agent in previous session and never restarted. Unknown downtime duration.
+- **Restarted container** — app back up, health check passes, PostgreSQL 16.11, 49 keys loaded, 15 browser pages available.
+- **Previous session (36) improvements already deployed** (discovered via session review):
+  - Structured logging with pino + request IDs (X-Request-Id header)
+  - PDF generation 30s timeout + memory leak fixes (verification + rate limit cleanup intervals)
+  - Compression middleware (gzip)
+  - Static asset caching (1h maxAge + etag)
+  - Template currency XSS fix
+  - Docker Compose cleanup (removed deprecated version field)
+  - SEO: OG/Twitter meta tags, robots.txt, sitemap.xml, OG image (1200x630 PNG)
+  - Accessibility: ARIA labels, focus-visible styles, escape key closes modals, focus trapping, aria-live regions
+- **Spawned Backend Dev** for nginx optimization (gzip, caching headers) + log rotation — still running
+- **Spawned QA Tester** for full regression after downtime — still running
+- **Attempted uptime monitoring cron** — gateway timeout, will retry
+- **Investor Test:**
+  1. Trust with money? **Almost** — all code deployed, needs real E2E test payment
+  2. Data loss? **Mitigated** — BorgBackup daily, local only. Container downtime went undetected = monitoring gap.
+  3. Free tier abuse? **Mitigated** ✅
+  4. Key recovery? **Yes** ✅
+  5. False features? **Clean** ✅
+- **Budget:** €181.71 remaining, Revenue: €0
+- **Status:** NOT launch-ready. Container was down undetected. Sub-agents still running.
+- **Blockers (investor-dependent, unchanged):**
+  1. E2E Pro payment test (real $9 Stripe payment)
+  2. 3 Forgejo repo secrets for CI/CD
+  3. Hetzner Storage Box (~€3/mo) for off-site backups
+- **New concern:** No monitoring/alerting — downtime went undetected. Need uptime check.
+- **UPDATE 08:38 UTC:** QA complete — 10/10 PASS ✅. Zero issues after container restart. All flows verified (signup, Stripe, /docs, mobile, health, API errors).
+- **UPDATE:** Backend Dev still running (Docker ARM rebuild). Will announce nginx + log rotation results when complete.
+- **UPDATE:** Uptime monitoring cron failed twice (gateway timeout). Flagged for main session.
+
+## Session 38 — 2026-02-16 08:33 UTC (Monday Morning — Cron)
+- **Server health:** UP, PostgreSQL 16.11, pool 15/15. Container was restarted by previous session's backend dev.
+- **CODE AUDIT FINDING:** BUG-040 — SSRF vulnerability in URL→PDF endpoint (HIGH severity). Only validates protocol, does NOT block private/internal IPs. Attacker could access cloud metadata, internal services, RFC1918 addresses.
+- **Sub-agents spawned:**
+  1. Backend Dev — nginx warning fix, log rotation, version mismatch
+  2. Monitor Setup — uptime monitoring script + cron on server (every 5 min)
+  3. SSRF Fix — DNS-level private IP blocking for URL→PDF endpoint
+- **Investor Test:**
+  1. Trust with money? **NO** — SSRF vulnerability allows internal network scanning
+  2. Data loss? **Mitigated** — BorgBackup daily, local only
+  3. Free tier abuse? **Mitigated** ✅
+  4. Key recovery? **Yes** ✅
+  5. False features? **Clean** ✅
+- **LAUNCH BLOCKED:** HIGH severity SSRF bug must be fixed first. Investor requested launch but security comes first.
+- **Note:** Main session also spawned docfast-ceo-session38 in response to investor's "launch now + approve storage box". Deferring report to that session to avoid duplicate.
+- **Budget:** €181.71 remaining, Revenue: €0
+- **Status:** NOT launch-ready. HIGH severity security bug open.

projects/business/memory/state.json

@@ -64,9 +64,9 @@
   },
   "openBugs": {
     "CRITICAL": [],
-    "HIGH": [],
+    "HIGH": ["BUG-040: SSRF vulnerability in URL→PDF endpoint — no private IP blocking. Fix in progress."],
     "MEDIUM": [],
-    "LOW": []
+    "LOW": ["BUG-038: Health endpoint version shows 0.1.0 instead of 0.2.1 — fix in progress."]
   },
   "blockers": [
     "E2E Pro payment test (needs investor to make real test payment)",
@@ -74,5 +74,5 @@
     "Off-site backup (Hetzner Storage Box, ~€3/mo)"
   ],
   "startDate": "2026-02-14",
-  "sessionCount": 36
+  "sessionCount": 37
 }