toga-ai 1.0.359 → 1.0.360

package/knowledge/2.0/apps/ai-bdr/INDEX.md

@@ -6,6 +6,6 @@
 | [BDR Web Funnel — Full Implementation Plan](features/bdr-web-funnel-plan.md) | > **Execution status (2026-07-16):** PLAN **Phases 0–5 are BUILT and QA'd**, Phase 6 > was **mostly already built** (the `info` contract was implemented at comm | bdr/PLAN.md, bdr/mockup/app.jsx, bdr/mockup/screens.jsx, bdr/mockup/components.jsx |
 | [Call Orchestration — PHP Worker ↔ Vapi (the integration seam)](features/call-orchestration.md) | The **PHP worker** is the orchestrator; **Vapi** is the actor. | ai-bdr/docs/client-onboarding-sop.md, ai-bdr/docs/vapi-firstmessage-timing-fix.md, ai-bdr/docs/vapi-inbound-callback-assistant-request.md, ai-bdr/docs/vapi-voicemail-iphone-screening.md, ai-bdr/scripts/update_structured_output.py |
 | [Vapi Integration — Assistants, Tools, Structured Output](features/vapi-integration.md) | Everything inside Vapi: the three assistants, the three shared tools, the shared structured-output schema, the Liquid-templated system prompt, and the Python sc | ai-bdr/vapi/templates/assistant.template.json, ai-bdr/vapi/templates/system-prompt.template.md, ai-bdr/prompts/archive/prompt-may-15.txt, ai-bdr/prompts/campaigns/healthcare-2026-03-18.md, ai-bdr/prompts/campaigns/healthcare-v2-2026-03-25.md, ai-bdr/prompts/templates/campaign-template.md, ai-bdr/scripts/update_assistant.py, ai-bdr/scripts/update_system_prompt.py, ai-bdr/scripts/update_structured_output.py, ai-bdr/scripts/update_call_summary_context.py, ai-bdr/scripts/fix_booking_guardrails.py, ai-bdr/scripts/get_assistant.py, ai-bdr/docs/vapi-firstmessage-timing-fix.md, ai-bdr/docs/vapi-voicemail-iphone-screening.md |
-| [Web Funnel — Built Next.js App (structure, stack, how to run)](features/web-funnel-app.md) | The **built** state of the BDR web funnel — the Next.js UI / lead-capture front door of the existing AI-BDR product (see `../architecture.md`). | bdr/PLAN.md, bdr/.gitignore, bdr/eslint.config.mjs, bdr/amplify.yml, bdr/src/app, bdr/src/app/layout.tsx, bdr/src/app/page.tsx, bdr/src/app/studio.css, bdr/src/lib/resolveCampaignId.ts, bdr/src/lib/scheduleSlots.ts, bdr/src/lib/formatPhone.ts, bdr/src/lib/analytics.ts, bdr/src/lib/rateLimit.ts, bdr/src/proxy.ts, bdr/.env.example, bdr/src/components/GoogleAnalytics.tsx, bdr/src/components/RichText.tsx, bdr/src/content, bdr/src/components, bdr/src/flow, bdr/src/server, bdr/src/app/api, bdr/test, bdr/public, bdr/mockup/styles.css |
+| [Web Funnel — Built Next.js App (structure, stack, how to run)](features/web-funnel-app.md) | The **built** state of the BDR web funnel — the Next.js UI / lead-capture front door of the existing AI-BDR product (see `../architecture.md`). | bdr/PLAN.md, bdr/.gitignore, bdr/eslint.config.mjs, bdr/amplify.yml, bdr/src/app, bdr/src/app/layout.tsx, bdr/src/app/page.tsx, bdr/src/app/studio.css, bdr/src/lib/resolveCampaignId.ts, bdr/src/lib/scheduleSlots.ts, bdr/src/lib/formatPhone.ts, bdr/src/lib/analytics.ts, bdr/src/lib/rateLimit.ts, bdr/src/lib/clientIp.ts, bdr/src/proxy.ts, bdr/.env.example, bdr/src/components/GoogleAnalytics.tsx, bdr/src/components/RichText.tsx, bdr/src/content, bdr/src/components, bdr/src/flow, bdr/src/server, bdr/src/app/api, bdr/test, bdr/public, bdr/mockup/styles.css |
 | [Web Funnel — Next.js UI + Config-Driven Campaign Content](features/web-funnel-content-model.md) | > **Status note (RESOLVED 2026-07-16):** the content **contract** below (schema, > provider seam, adapters) is BUILT and QA'd (PLAN Phases 0–5). | bdr/src/content/schema.ts, bdr/src/content/provider.ts, bdr/src/content/useCampaign.ts, bdr/src/content/default.ts, bdr/src/lib/resolveCampaignId.ts, bdr/src/server/leadSink.ts, bdr/src/server/callbackService.ts, bdr/src/app/api/call-now/route.ts, bdr/src/app/api/call-later/route.ts, bdr/src/app/api/contact/route.ts |
 | [New-Campaign Onboarding (6-phase runbook)](workflows/new-campaign-onboarding.md) | The end-to-end procedure for launching a new outbound BDR campaign (industry, offer, target persona, geography). | ai-bdr/docs/client-onboarding-sop.md, ai-bdr/docs/calcom-new-campaign-event-guide.md, ai-bdr/prompts/templates/campaign-template.md, ai-bdr/scripts/update_assistant.py, ai-bdr/scripts/update_system_prompt.py |

package/knowledge/2.0/apps/ai-bdr/features/web-funnel-app.md

@@ -22,6 +22,7 @@ files:
   - bdr/src/lib/formatPhone.ts
   - bdr/src/lib/analytics.ts
   - bdr/src/lib/rateLimit.ts
+  - bdr/src/lib/clientIp.ts
   - bdr/src/proxy.ts
   - bdr/.env.example
   - bdr/src/components/GoogleAnalytics.tsx
@@ -56,13 +57,17 @@ fully implemented at commit `34a3910`: `page.tsx primeLead` reads `?hsContactId=
 campaign attribution → only `togaUuid` crosses to the client). The 2026-07-16 session
 added the deltas below (phone prefill + live input mask, `submitOk` on Success, GA4
 wiring) and resolved §9.10 (content mechanism — see `web-funnel-content-model.md`) and
-§9.11 (consent links). A later 2026-07-16 session added an **interim app-layer rate-limit
-mitigation** for the `?hsContactId=` enumeration risk (`src/proxy.ts` + `src/lib/rateLimit.ts`),
+§9.11 (consent links). A later 2026-07-16 session added an **app-layer rate-limit
+mitigation** for the `?hsContactId=` enumeration risk (`src/proxy.ts` + `src/lib/rateLimit.ts`
++ `src/lib/clientIp.ts`),
 documented the **fully server-side request-a-call seam**, the **outbound dialer eligibility
 rules** (see `../../worker2/features/vapi-webhook-handler.md`), the **phone-less-contact
 dialer bug**, and the **local dev env wiring**. Developer QA verdict: the UI is "very close,
-minimal adjustments to be near exact" vs. the mockup. All checks green: tsc, eslint,
-89/89 Vitest, `next build` (build output labels the proxy `ƒ Proxy (Middleware)`).
+minimal adjustments to be near exact" vs. the mockup. The rate-limit mitigation then passed an
+**independent `cso` security review — final verdict SHIP after two rounds** — and was HARDENED
+to its ship state (trusted-IP position for X-Forwarded-For; O(1) LRU-capped limiter map; the
+`?hsCampaignId=` page-prime param now `isTogaUuid`-validated). All checks green: tsc, eslint,
+**104/104 Vitest**, `next build` (build output labels the proxy `ƒ Proxy (Middleware)`).
 
 - **Repo:** `agilantsolutions/BDR` on GitHub, working branch `BDR-Development`. The
   machine-local `.claude/` harness is **gitignored** — committing it would snapshot
@@ -83,15 +88,19 @@ minimal adjustments to be near exact" vs. the mockup. All checks green: tsc, esl
 - **ESLint flat config** carries a **no-em-dash rule** on shipped strings
   (`Literal` / `TemplateElement` / `JSXText` selectors) — enforces the mockup copy
   rule on in-repo strings (`eslint.config.mjs`).
-- **Vitest** test suite: **89 tests, all green** (13 added in the first 2026-07-16 session:
-  phone format/prefill/mask, live-anchor consent links, `submitOk` race; 10 more in the
-  later 2026-07-16 session for the rate limiter). Every phase was verified with `tsc` + lint
-  + build + a live SSR `curl` before commit.
-- **Edge proxy (Next 16 `proxy.ts`).** `src/proxy.ts` is the Next 16 request proxy (the
-  successor to the deprecated `middleware.ts` convention — see the Next 16 gotcha) carrying
-  the interim rate-limit mitigation. It uses `src/lib/rateLimit.ts`, a pure clock-injected
-  in-memory token-bucket limiter (no `server-only`, so it runs in the edge proxy and is
-  unit-testable in Node).
+- **Vitest** test suite: **104 tests, all green** (13 added in the first 2026-07-16 session:
+  phone format/prefill/mask, live-anchor consent links, `submitOk` race; the later 2026-07-16
+  session added the rate-limiter + trusted-IP + LRU-eviction + `hsCampaignId` validation tests
+  to reach 104). Every phase was verified with `tsc` + lint + build + a live SSR `curl` before
+  commit.
+- **Edge proxy (Next 16 `proxy.ts`) — 3-file rate-limit mitigation.** `src/proxy.ts` is the
+  Next 16 request proxy (the successor to the deprecated `middleware.ts` convention — see the
+  Next 16 gotcha) carrying the rate-limit mitigation. It composes two libs: `src/lib/rateLimit.ts`,
+  a pure clock-injected in-memory token-bucket limiter with an O(1) LRU-capped map (no
+  `server-only`, so it runs in the edge proxy and is unit-testable in Node); and
+  `src/lib/clientIp.ts`, the pure client-IP resolution logic (no `next` import, so it is
+  independently testable) that parses `X-Forwarded-For` from a **trusted** position. See the two
+  rate-limiter security gotchas below.
 - **Deploy target:** AWS Amplify (SSR), `amplify.yml` present (Phase 8 not done).
 
 ## Directory map (what got built)
@@ -115,13 +124,14 @@ minimal adjustments to be near exact" vs. the mockup. All checks green: tsc, esl
   `web-funnel-content-model.md`).
 - `src/app/api/*` — route handlers `call-now`, `call-later`, `contact`. **These do NOT
   place a call themselves** — see "Request-a-call is fully server-side" below.
-- `src/proxy.ts` — Next 16 edge proxy (rate limiting; see gotcha). `src/lib/rateLimit.ts` —
-  the token-bucket limiter it uses.
+- `src/proxy.ts` — Next 16 edge proxy (rate limiting; see gotchas). `src/lib/rateLimit.ts` —
+  the LRU-capped token-bucket limiter it uses. `src/lib/clientIp.ts` — pure client-IP
+  resolution (trusted `X-Forwarded-For` position; no `next` import).
 - `public/*` — assets pruned to the **default campaign only**, **plus AutoBuild's
   FLOURISH characters** (Owl 1 `owl-02` + Robot 1 `robot-02`, art + talk videos) which
   the assembly cycle needs even though they are not the campaign agent. See the
   asset-pruning gotcha below.
-- `test/*` — the 67-test Vitest suite.
+- `test/*` — the Vitest suite (104 tests).
 
 ## How the built app behaves (key runtime facts)
 
@@ -248,6 +258,16 @@ PRODUCTION credential set (`TOGA_API_BASE_URL = https://api.togahub.com/v2`).
 - **Remaining work is decision-gated, not code:** leadership's first-campaign copy;
   Phase 8 Amplify SSR (incl. a **per-IP WAF rate rule** — see the enumeration gotcha) +
   `togatech` integration. GA4 (Phase 7) is now wired; §9.10 and §9.11 are resolved.
+- **Non-gating security residuals (recorded in `BDR/PLAN.md` §10 / Phase 8 checklist — do not
+  re-litigate; the `cso` review flagged these as follow-ups, not ship-blockers):** (a) **lock
+  the Amplify origin** so nothing reaches it without transiting CloudFront — any
+  direct-to-origin path lets an attacker own the whole XFF chain, the standing caveat behind
+  every header-based IP-trust decision above; (b) confirm the distribution **injects + strips**
+  `CloudFront-Viewer-Address` before setting `RATE_LIMIT_TRUST_CF_VIEWER_HEADER=true`;
+  (c) `readJsonObject` buffers the body **before** the size check and measures UTF-16 length,
+  not bytes (bounded in practice by the Lambda payload cap + the call limiter); (d) the proxy
+  matcher is an **exact-path allowlist** — re-verify no un-normalized path variant reaches a
+  handler off-matcher.
 
 ## Gotchas
 
@@ -263,21 +283,50 @@ PRODUCTION credential set (`TOGA_API_BASE_URL = https://api.togahub.com/v2`).
   server-rendered prefill, (b) scrape the **full** contact record via `GET /api/contact`
   (see next gotcha), and (c) drive the page-prime Toga upsert, polluting contacts/attribution.
   **Inherited from `info`'s CRM-link URL contract — cannot be changed unilaterally.**
-  **Interim app-layer mitigation (BUILT, 2026-07-16):** `src/proxy.ts` + `src/lib/rateLimit.ts`
-  rate-limit per client. Entry pages carrying `?hsContactId=` **soft-degrade** over the limit
-  (strip `hsContactId`, `NextResponse.rewrite` to render anonymously — a real shared-NAT user
-  keeps the funnel minus prefill; a scraper gets no PII and triggers no Toga upsert;
-  `hsCampaignId` is preserved). `/api/contact`, `/api/call-now`, `/api/call-later` return a
-  `429 {isSuccess:false,…}` envelope with `Retry-After` over the limit. **This is
-  defense-in-depth ONLY** — the limiter is per-runtime-instance in-memory (Amplify SSR may run
-  several instances), so it is not authoritative. The authoritative controls — a **per-IP edge
-  WAF rate rule** (Phase 8) and **opaque/signed CRM link tokens** (raise with the CRM owner) —
-  remain deferred. Tracked in `BDR/PLAN.md` §10/§11. (An independent `cso` review of this
-  mitigation was still running at capture time; treat it as "in place, pending final review".)
+  **App-layer mitigation (BUILT + security-reviewed SHIP, 2026-07-16):** `src/proxy.ts` +
+  `src/lib/rateLimit.ts` + `src/lib/clientIp.ts` rate-limit per client (keyed off a **trusted**
+  client IP — see the two rate-limiter gotchas below). Entry pages carrying `?hsContactId=`
+  **soft-degrade** over the limit (strip `hsContactId`, `NextResponse.rewrite` to render
+  anonymously — a real shared-NAT user keeps the funnel minus prefill; a scraper gets no PII and
+  triggers no Toga upsert; `hsCampaignId` is preserved). `/api/contact`, `/api/call-now`,
+  `/api/call-later` return a `429 {isSuccess:false,…}` envelope with `Retry-After` over the
+  limit. **This is defense-in-depth ONLY** — the limiter is per-runtime-instance in-memory
+  (Amplify SSR may run several instances), so it is not authoritative. The authoritative
+  controls — a **per-IP edge WAF rate rule** (Phase 8) and **opaque/signed CRM link tokens**
+  (raise with the CRM owner) — remain deferred. Tracked in `BDR/PLAN.md` §10/§11. An independent
+  `cso` review of this mitigation returned a **final verdict of SHIP after two rounds**; the
+  hardening from that review (trusted-IP position, LRU-capped map, `hsCampaignId` validation) is
+  documented in the gotchas below.
 - **HIGH (security) — `GET /api/contact?hsContactId=` returns the FULL contact record.** Name,
   email, phone, company, and job title by id — a **more direct** PII scrape vector than the SSR
   phone prefill. Now covered by the same rate limiter; **any change to
   `src/app/api/contact/route.ts` must keep it rate-limited.**
+- **HIGH (security) — rate limiting behind CloudFront MUST key off a TRUSTED IP position, never
+  the leftmost `X-Forwarded-For`.** The leftmost XFF entry is client-prependable, so keying the
+  limiter off it is trivially bypassable (a scraper spoofs a fresh left-most IP per request and
+  never hits the limit). Correct approach (in `src/lib/clientIp.ts`): parse XFF
+  **right-to-left** and take index `parts.length - 1 - RATE_LIMIT_TRUSTED_PROXY_HOPS` (default
+  `0` ⇒ the **rightmost**, CloudFront-appended, viewer IP). `x-real-ip` is **NOT** trusted.
+  `CloudFront-Viewer-Address` is trusted **only** when env
+  `RATE_LIMIT_TRUST_CF_VIEWER_HEADER=true` (default **OFF**) — because an unverified
+  distribution that forwards a client-supplied copy of that header reintroduces the bypass; ops
+  enables it only after confirming CloudFront both injects **and** strips it. `normalizeIp()`
+  handles port strip, `[ipv6]:port`, and `::ffff:` IPv4-mapped forms so one client = one key.
+  This whole approach is a **reusable pattern for any Next app behind CloudFront/Amplify** — do
+  not copy a naive leftmost-XFF limiter into another repo.
+- **HIGH (security) — a naive in-memory limiter sweep is itself a DoS.** A sweep that only
+  reclaims fully-refilled buckets leaves an **unbounded map** plus an O(n) sweep per insert;
+  under a unique-key flood (e.g. rotated IPv6 sources) that is a self-inflicted DoS. Fix (in
+  `src/lib/rateLimit.ts`): a **HARD ceiling** `MAX_TRACKED_KEYS = 10_000` enforced by **O(1) LRU
+  eviction** (Map insertion order; every check re-inserts the key to move it to MRU), **plus**
+  the O(n) reclaim throttled to at most **once per window**. This guarantees the map never
+  exceeds the cap and per-insert work is O(1) amortized. Do not "simplify" the LRU re-insert or
+  the throttle away — both are load-bearing against the flood case.
+- **`?hsCampaignId=` page-prime param must be UUID-validated before it crosses to the Toga
+  upsert.** It flows into the upsert as `togaCampaignUuid`; it previously had only a
+  `typeof === 'string'` guard. `page.tsx` now `isTogaUuid`-validates it before use, dropping a
+  malformed value to `undefined`. Never pass an unvalidated inbound query param into the Toga
+  upsert.
 - **Next 16 — `middleware.ts` is DEPRECATED; use `proxy.ts`.** Next 16.2.3 warns "The
   middleware file convention is deprecated. Please use proxy instead"
   (nextjs.org/docs/messages/middleware-to-proxy). Correct convention: `src/proxy.ts` exporting
@@ -322,6 +371,23 @@ PRODUCTION credential set (`TOGA_API_BASE_URL = https://api.togahub.com/v2`).
   harness; pull it with `npx toga-ai`.
 
 ## Change history
+- 2026-07-16 — Rate-limit mitigation HARDENED to ship state after an independent `cso` security
+  review returned **SHIP after two rounds** (supersedes the mid-state recorded in the entry
+  below: test count is **104**, not 89, and the review is complete, not "still running"). Added
+  `src/lib/clientIp.ts` (pure, `next`-free, testable) → the mitigation is now **3 source files**
+  (`proxy.ts` + `rateLimit.ts` + `clientIp.ts`). Security hardening: (1) rate limiting behind
+  CloudFront keys off a **trusted** XFF position (parse right-to-left, index
+  `len-1-RATE_LIMIT_TRUSTED_PROXY_HOPS`, default rightmost/viewer IP; `x-real-ip` untrusted;
+  `CloudFront-Viewer-Address` trusted only when `RATE_LIMIT_TRUST_CF_VIEWER_HEADER=true`,
+  default OFF) — never the client-prependable leftmost IP; `normalizeIp` collapses port/
+  `[ipv6]:port`/`::ffff:` so one client = one key; (2) the limiter map is bounded by a HARD
+  `MAX_TRACKED_KEYS=10_000` via O(1) LRU eviction + reclaim throttled to once/window, closing a
+  unique-key-flood DoS in the naive sweep; (3) `?hsCampaignId=` is now `isTogaUuid`-validated in
+  `page.tsx` before it crosses to the Toga upsert (was a bare `typeof`-string guard). Recorded
+  the non-gating `cso` follow-ups (lock Amplify origin to CloudFront; verify CF-Viewer-Address
+  inject+strip before trusting it; `readJsonObject` buffers-then-measures UTF-16 not bytes;
+  proxy matcher exact-path allowlist). All green: tsc, eslint, **104/104** Vitest, `next build`.
+  (tcox)
 - 2026-07-16 — Later same-day session. BUILT an interim app-layer rate-limit mitigation for the
   `?hsContactId=` enumeration risk: `src/lib/rateLimit.ts` (pure clock-injected in-memory
   token-bucket, idle-key eviction, no `server-only`) + `src/proxy.ts` (Next 16 proxy). Policy:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.359",
+  "version": "1.0.360",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",