Sprint 6: Dockerized stack + pre-deploy hardening — one-command boot, webhook at-least-once, memory bounds

[hynding]

Summary

Implements the Sprint 6 plan (docs/superpowers/plans/2026-07-08-sprint-6-docker-hardening.md): the whole platform now boots as production-style containers with one command, CI exercises those containers on every merge, and the pre-deploy hardening backlog is closed.

• Docker (one-command boot): multi-stage turbo prune --docker images for api/cms/demo (alpine, non-root, sharp builds clean — no slim fallback needed); compose stack profile with healthcheck-gated ordering (postgres→cms→api(readyz)→demo); dev flow (docker compose up -d postgres) untouched; documented .env contract incl. the previously-missing apps/api/.env.example
• CI against containers: the e2e job builds all three images and runs the Playwright suite against the compose stack (hand-rolled service boots removed); failure dumps compose logs; if: always() teardown
• Webhook hardening (closes Webhook delivery hardening: redelivery, retention, shutdown, replay protection, SSRF posture #8): required messageId on all webhook payloads; delivered_at/attempts columns (with an 0005 backfill migration so existing DBs don't burst-redeliver on upgrade); redelivery sweep restores at-least-once (5-attempt cap → dead-letter + mark, never silent orphans); dead-letter TTL retention; SIGTERM graceful shutdown (reentrancy-safe, force-exit fallback, live-proven: api stops in 0.18s, cms ~240ms); ended-event scan window with a single-sourced clamp against the redelivery grace
• Memory bounds (closes Rate-limiter memory hardening: bucket eviction + negative auth-cache growth #10): rate-limiter expired-bucket sweep (true-rollover-gated — new-key floods can't trigger O(n) sweeps) + 10k bucket cap with shared overflow bucket; negative auth-cache FIFO eviction cap; NaN-guarded env parsing so misconfiguration can't silently disable the cap
• Offer-id validation (closes Validate offer id on impression/click routes (stats pollution hardening) #13): impression/click reject unknown offer ids (404 not_found), fail-open on config outage — stats can no longer be polluted by injected ids
• Polish (closes MVP fast-follow polish (from Sprint 4 final review) #11): request-id child loggers on route warns; SRI-pinned Redoc page at GET /docs; npm files allowlists; release.yml tests-before-publish + tag push; log-retention note; docs/retros/
• Test hardening (closes Sprint 5 test-hardening bundle #14): 8-way ingestion race loop, StrictMode beacon test, stats/impression schema coverage, hand-verified Levenshtein boundary pair, nameById fallback

Behavior notes for existing consumers

• Webhook payloads now carry a required messageId — additive for receivers (HMAC covers the raw body as sent), but strict schema validators must allow the field. Redeliveries are new messages with fresh ids: dedup by messageId, replay-check the signed createdAt.
• POST /v1/offers/:id/impression|click return 404 not_found for unknown offer ids where they previously returned 200 and recorded. First-party widgets unaffected.
• .env.example flips LOG_PLAINTEXT_KEYS to false — seeded keys no longer print in cms logs on fresh setups.
• Local + CI e2e now require Docker (compose stack replaces hand-booted services).

Test plan

• Full workspace 27/27 turbo tasks green post fix-wave (api 113, adapter-db 25 incl. Testcontainers redelivery/backfill/race suites)
• Live verification: docker compose --profile stack up -d --wait from wiped volumes → readyz 200, seeded demo, e2e 3/3 against containers; graceful docker stop timings captured; README quickstart executed verbatim from a clean clone
• CI run 28982672086 green (test + compose-based e2e); the fix-wave commit re-triggers checks on this PR — watch them

Review notes

Ten tasks through the full gate cycle (four needed fix→re-review loops: zod idiom, markDelivered value-stability, shutdown reentrancy/clamp single-sourcing, sweep gating) plus a final whole-branch review — verdict ready to merge with fixes, fix wave 16ab9c5 applied and re-approved (backfill migration, exhausted-claim dead-lettering, env NaN guards, doc corrections). Known accepted limits, documented in-repo: scheduler downtime longer than the scan grace drops those transitions; overlapping ticks can duplicate a redelivery (at-least-once semantics); overflow-bucket keeps new keys rate-limited-but-shared at cap.

🤖 Generated with Claude Code