Capgo Builder — Support-Logs Upload (R2)

docs/superpowers/specs/2026-06-05-builder-support-logs-upload-design.md · 2026-06-05

✅ APPROVED follow-up — kills the manual attach. Builds on the shipped local-file + mailto flow.

1 · Goal

On confirm, upload the gzipped logs bundle to R2 and put a logs ID + download link in the email body. The user just hits Send; support clicks the link from Discord. The local file stays as the offline/failure fallback — no attach, no Finder/Mail window dance.

2 · Data flow

CLI (existing confirm gate; "view logs first" preview unchanged)
  gzip bundle → sha256(gz) = ID
  POST ${apiHost}/build/support_logs  { appId, jobId?, gzB64 }   (capgkey)
        ▼
capgo backend  public/build/support_logs.ts   (mirrors ai_analyze.ts)
  auth capgkey → resolve user → rate limit → forward { gzB64, appId, jobId?, userId }
        ▼
capgo_builder worker  POST /support-logs
  1. gz ≤ 10 MB (413)      2. text-only validation (gunzip 64KB → UTF-8/printable; 415)
  3. R2 put  capgo-builder-support-logs / <sha256>.log.gz   (idempotent by key)
  4. → { id, url }
        ▼
email body:  "Support logs (kept 30 days): <url>"  → SEND-READY (URL-only; the id is inside it)
support:     GET /support-logs/<sha256> → streams the .log.gz (404 after expiry)

FALLBACK (upload fails/offline): exactly today's shipped behavior —
  clipboard .log.gz path + Finder reveal + attach instructions.

3 · Storage — NEW dedicated bucket

Bucket: capgo-builder-support-logs — separate from the artifact bucket (isolated lifecycle/access/blast radius — decided).
Key: <sha256(gz)>.log.gz — the hash is the ID and the capability; "upload once" by construction (retries/dupes hit the same key, no new storage).
Custom metadata: app_id, job_id?, user_id (account id — no email/PII).
Retention = bucket-wide R2 lifecycle rule, 30 days. No cron, no cleanup code:

npx wrangler r2 bucket create capgo-builder-support-logs
npx wrangler r2 bucket lifecycle add capgo-builder-support-logs --expire-days 30

// worker wrangler.jsonc (prod + preprod)
"r2_buckets": [ …, { "binding": "SUPPORT_LOGS_BUCKET", "bucket_name": "capgo-builder-support-logs" } ]

4 · API

Backend proxy public/build/support_logs.ts — capgkey auth → user → rate limit → forward (same internal backend→worker auth as ai_analyze). Errors: 401 / 413 too big / 415 not-text / 429.
Worker POST /support-logs (validate → sha256 → put → {id,url}) and GET /support-logs/:id (stream gz, Content-Disposition: attachment; friendly 404 "logs expired — ask the user to re-send"). Public route on the artifact-download host pattern.

5 · Abuse posture (the honest version)

Defenses, strongest first:

Economics + TTL: worst case (colo-hopping VPN diluting the limiter ~100×: 1,000/day × 10 MB × 30-day TTL) ≈ 300 GB ≈ $4.50/month, self-purging. R2 egress is free → the GET side can't run up a bill. No payoff.
10 MB gz cap (hard server check).
Text-only validation — kills the only attractive misuse (file hosting behind a capgo URL).
sha256 keying — duplicate floods cost nothing.
Account-keyed limit 1/min + 10/day via the existing CacheHelper limiter. Documented caveat: Cache-API-backed → per-colo, fails open — a speed bump, not a guarantee (acceptable given 1–4).
Account bans as backstop (capgkey required; no anonymous path).

No captcha (authenticated CLI API — wrong tool). Optional later hardening: globally-consistent per-account Postgres counter — deferred unless real abuse appears.

6 · CLI changes

contact-support.ts: new optional upload dep after the confirm + bundle write. Upload OK → email body gets the download URL + "kept 30 days" (URL-only; the id is embedded in it); skip clipboard-path/reveal/attach text (nothing to attach); local paths still printed. Upload fails (15 s timeout) → exactly today's behavior. Never blocks the flow.
support-upload.ts (new): gz→base64 POST to ${apiHost}/build/support_logs (same client pattern as ai/analyze.ts); null on any error.
Confirm copy: "We'll save your logs locally, upload a copy to Capgo support (kept 30 days), and open a pre-filled email…" — preview choice unchanged (shows exactly what's uploaded).
All five entry points (iOS/Android error step, AI prompt, AI result escalation, init, build request) inherit this for free via contactSupport.

7 · Components & tests

Where	What
Ops (one-time)	bucket + lifecycle rule; `SUPPORT_LOGS_BUCKET` binding (prod + preprod)
Worker	POST/GET routes; size cap; gunzip/text validation; sha256; mock-R2 tests (put/get/oversize/non-text/idempotent re-put)
Backend	`support_logs.ts` proxy + registration; tests 401/413/429/forward
CLI	`support-upload.ts` + upload branch + confirm copy; tests: ok-path (id+url in body, no attach text), fail-path (identical to today), timeout degrade

8 · Open items

Exact public GET host/path (reuse the artifact-download pattern — confirm in code).
Backend→worker internal auth detail (mirror ai_analyze — confirm in code).
Preprod: same bucket or -preprod twin (suggest twin).
Deferred: global Postgres rate counter (only if abuse ever appears).

Builds on: 2026-06-03-builder-contact-support-simple-design.md (shipped) · Rejected alternative: backend/bridge email sending (2026-06-03-builder-contact-support-design.md)