Epic: Nat SaaS production-readiness

[ianpatrickhines]

Context

Nat ships in two forms: a CLI (works today) and the SaaS product — Chrome extension + AWS backend + Stripe billing + marketing site. The SaaS was built as a complete MVP (27 Ralph stories) and then half-migrated from per-user to per-nation billing. The migration updated most of the backend but left the tests, the extension, and one handler on the old model — so the pieces no longer agree, CI is red, and the part that actually enforces payment is built but never switched on.

This epic tracks the arc from that half-finished state to production / public launch. Assessment basis: three parallel code audits (backend, extension, site/tests/CI) on 2026-06-20. Overall ~65% ready.

Gating decision: RESOLVED 2026-06-20 — keeping per-nation pricing (Ian). Rationale: it's how NationBuilder customers think about their bills, and it's simpler (no seat management). Per-user revert is off the table; do not re-raise.

Phases

Phase 1 — Finish the migration (make it work end-to-end)

• Fix 39 failing tests left by per-nation billing migration (unblocks CI/deploy) #6 Fix 39 failing tests (unblocks CI/deploy)
• Extension: detect nation_slug and send X-Nat-Nation-Slug for per-nation billing #7 Extension: detect nation_slug + send X-Nat-Nation-Slug
• Migrate non-streaming agent handler to per-nation architecture #8 Migrate non-streaming agent handler to per-nation

Phase 2 — Turn on the money + lock the doors

• Enforce nation subscription gate in agent handlers (middleware built but never called) #9 Enforce nation subscription gate in agent handlers
• Add API authorization to public endpoints (AuthorizationType: NONE) #10 Add API authorization to public endpoints
• Add CSRF protection and redirect_uri allowlist to NB OAuth callback #11 CSRF protection + redirect_uri allowlist on OAuth callback
• Move confirmed_tools/undo_stack to server-side (client can bypass confirmations) #12 Move confirmed_tools/undo_stack server-side
• Validate nation_slug format and make Stripe webhook idempotent #13 Validate nation_slug + idempotent Stripe webhook

Phase 3 — Wire up the real world

• Consolidate to one domain, replace placeholder URLs, load real secrets #14 Consolidate domain, replace placeholder URLs, load secrets
• Create real Stripe products/prices and reconcile pricing tiers #15 Create Stripe products/prices + reconcile pricing tiers

Phase 4 — Chrome Web Store

• Chrome Web Store: add extension icons and prepare store listing #16 Extension icons + store listing

Phase 5 — Operate with confidence

• Add observability: metrics, alarms, error tracking, verify prompt caching #17 Observability: metrics, alarms, error tracking, verify caching

Acceptance Criteria

• Per-nation vs per-user decision recorded — per-nation, 2026-06-20
• Phases 1–2 complete: CI green, extension↔backend agree, paid-only access enforced, security gaps closed
• Phase 3 complete: real domain + secrets + Stripe prices; end-to-end smoke passes in target env
• Phase 4 complete: extension live (or submitted) on the Chrome Web Store
• Phase 5 complete: monitoring/alerting in place

[ianpatrickhines]

Decision (2026-06-20): keeping per-nation pricing. Per Ian — it matches how NationBuilder customers think about their bills and is simpler (no per-seat management). Per-user revert is off the table. All Phase-1 child issues (#6–#9) proceed on the per-nation model as written; #15 confirms removal of the legacy $49/$149/$399 per-seat tiers in favor of $29/$79 per nation.

[ianpatrickhines]

Decision (2026-06-20): auth scheme = login-based session token (JWT). Minted on the existing NationBuilder OAuth callback, signed by us, claims {user_id, nation_slug, exp}; verified on every request with org read from the token (not the browser). Chosen over per-org API key and per-request HMAC. Closes both #10 (no auth) and the IDOR. Spec written into #10.

[ianpatrickhines]

Session 2026-06-22 — Phase 2/4/5 driven to reviewable PRs

Ready for /ship review (verified: tests + mypy from main session):

• Add CSRF protection and redirect_uri allowlist to NB OAuth callback #11 → PR feat(security): OAuth CSRF nonce + redirect allowlist [needs user_id review] (#11) #24 — CSRF nonce + redirect allowlist + the user_id session-fixation hardening now implemented (573 pass). Clears the needs-ian-judgment hold pending your review.
• Move confirmed_tools/undo_stack to server-side (client can bypass confirmations) #12 → PR fix(security): server-authoritative confirmations + undo (fixes #12) #25 — server-authoritative confirmations + undo (572 pass, mypy clean).
• Validate nation_slug format and make Stripe webhook idempotent #13 → PR feat(security): validate nation_slug + idempotent Stripe webhook (fixes #13) #26 — nation_slug validation + idempotent Stripe webhook (596 pass).
• Add observability: metrics, alarms, error tracking, verify prompt caching #17 → PR feat(observability): metrics, alarms, error tracking, cache verification (fixes #17) #27 — observability: metrics, alarms, Sentry (no-ops w/o DSN), cache verification (556 pass).
• Chrome Web Store: add extension icons and prepare store listing #16 → PR feat(extension): brand icons + manifest wiring (partial #16) #28 (partial) — brand icons + manifest wiring; extension is now packageable. Store-listing assets (screenshots, promo tiles, copy) still need design.

⚠️ PRs #26/#27 had no adversarial self-review — their Opus drives hit the 80-turn ceiling before committing; I re-verified and finalized them from the main session. Give the validation entry points (#26) and metric/alarm wiring (#27) a careful review.

Decisions locked this session:

• Canonical domain = natassistant.com (not yet registered).
• Legacy 3-tier ($49/$149/$399) → rip out entirely; queued until feat(security): validate nation_slug + idempotent Stripe webhook (fixes #13) #26/feat(observability): metrics, alarms, error tracking, cache verification (fixes #17) #27 merge (shared files).
• Marketing-site redesign committed to local branch site/brand-refresh (unpushed, your review).

Still needs you (Phase 3/4):

• Consolidate to one domain, replace placeholder URLs, load real secrets #14: register natassistant.com + provision 5 Secrets Manager values. Deploy bug: deploy.yml doesn't package nb_oauth_init and doesn't bundle shared/ for the OAuth Lambdas — fix before first deploy.
• Create real Stripe products/prices and reconcile pricing tiers #15: create 2 Stripe products ($29 Nat / $79 Nat Pro), set price-ID env vars.
• Chrome Web Store: add extension icons and prepare store listing #16: store-listing design assets.

[ianpatrickhines]

Session 2026-06-22 — close-out: open PR queue cleared

Merged to main (all independently reviewed; integrated main = 678 tests pass, mypy + cfn-lint clean):

• Add CSRF protection and redirect_uri allowlist to NB OAuth callback #11 → feat(security): OAuth CSRF nonce + redirect allowlist [needs user_id review] (#11) #24 (OAuth CSRF + user_id hardening)
• Move confirmed_tools/undo_stack to server-side (client can bypass confirmations) #12 → fix(security): server-authoritative confirmations + undo (fixes #12) #25 (server-side confirmations/undo)
• Validate nation_slug format and make Stripe webhook idempotent #13 → feat(security): validate nation_slug + idempotent Stripe webhook (fixes #13) #26 (slug validation + idempotent webhook; review caught + I fixed a regex newline bypass)
• Add observability: metrics, alarms, error tracking, verify prompt caching #17 → feat(observability): metrics, alarms, error tracking, cache verification (fixes #17) #27 (observability; review confirmed security gates survived the merge; added a test for the cache/latency branch)
• Chrome Web Store: add extension icons and prepare store listing #16 → feat(extension): brand icons + manifest wiring (partial #16) #28 (brand icons + manifest; partial — store-listing assets still TODO)

Each later PR conflicted on template.yaml/handlers as the prior merged (all add a DDB table); resolved keeping all resources, re-verified green at each step.

Phase status:

• ✅ Phase 1 (migration): Fix 39 failing tests left by per-nation billing migration (unblocks CI/deploy) #6/Extension: detect nation_slug and send X-Nat-Nation-Slug for per-nation billing #7/Migrate non-streaming agent handler to per-nation architecture #8
• ✅ Phase 2 (turn on money + lock doors): Enforce nation subscription gate in agent handlers (middleware built but never called) #9/Add API authorization to public endpoints (AuthorizationType: NONE) #10/Add CSRF protection and redirect_uri allowlist to NB OAuth callback #11/Move confirmed_tools/undo_stack to server-side (client can bypass confirmations) #12/Validate nation_slug format and make Stripe webhook idempotent #13
• ✅ Phase 5 (observability): Add observability: metrics, alarms, error tracking, verify prompt caching #17
• 🟡 Phase 4 (Chrome store): Chrome Web Store: add extension icons and prepare store listing #16 icons done; listing assets need design
• ⬜ Phase 3 (wire up real world): Consolidate to one domain, replace placeholder URLs, load real secrets #14 (domain + secrets) and Create real Stripe products/prices and reconcile pricing tiers #15 (Stripe products) — the remaining gate. No deploy possible until Consolidate to one domain, replace placeholder URLs, load real secrets #14.

New follow-ups from this session's reviews (non-blocking): #29 (session_id derivability), #30 (filter/consume TOCTOU), #31 (slug-validation coverage), #32 (callback docstring).

Deploy blocker reminder: deploy.yml doesn't package nb_oauth_init or bundle shared/ for the OAuth Lambdas — must fix under #14 before first deploy.