toga-ai 1.0.359 → 1.0.361

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/knowledge/sessions/2026-07-16-bdr-hscontactid-rate-limit-tcox.md

@@ -0,0 +1,81 @@
+---
+type: session
+slug: bdr-hscontactid-rate-limit
+title: BDR ?hsContactId= enumeration rate-limit mitigation (security-reviewed SHIP)
+author: tcox
+repos: [bdr, ai-bdr]
+framework: "2.0"
+client: shared
+status: active
+created: 2026-07-16
+updated: 2026-07-16
+---
+
+# Session: bdr-hscontactid-rate-limit
+**Date:** 2026-07-16
+**Project/Repo:** bdr (2.0) — local `C:\WWW\BDR`, GitHub `agilantsolutions/BDR`, branch `BDR-Phase-2`
+**Task:** Build an interim app-layer rate-limit mitigation for the public funnel's `?hsContactId=` enumeration risk (PLAN §10, HIGH), driven to a security-reviewed SHIP; along the way, wire local dev env and diagnose why a live test call never fired.
+
+---
+
+## What WORKED
+- **Interim rate-limit mitigation BUILT and SHIP-verified (two CSO review rounds).** New `src/proxy.ts` (Next 16 proxy), `src/lib/rateLimit.ts` (token bucket), `src/lib/clientIp.ts` (trusted IP resolution). Policy: entry pages with `?hsContactId=` **soft-degrade** over limit (strip id, `NextResponse.rewrite` to render anonymously — no PII, no Toga upsert; hsCampaignId preserved); `/api/contact`, `/api/call-now`, `/api/call-later` return a `429` `{isSuccess,status,error,messages,data}` envelope with `Retry-After`. Evidence: tsc clean, eslint clean, **104/104 vitest**, `next build` compiles it (logs `ƒ Proxy (Middleware)`).
+- **C1 (Critical) FIXED — trusted client IP.** `resolveClientIp()` parses `X-Forwarded-For` **right-to-left** at `parts.length - 1 - RATE_LIMIT_TRUSTED_PROXY_HOPS` (default 0 => rightmost = CloudFront-appended viewer), so a forged/leftmost XFF can't shift the selected index. `x-real-ip` no longer trusted. `CloudFront-Viewer-Address` trusted ONLY when `RATE_LIMIT_TRUST_CF_VIEWER_HEADER=true` (env, default OFF). `normalizeIp` strips port, `[ipv6]:port`, `::ffff:` mapping. Verified by `test/clientIp.test.ts` incl. a 20-entry spoof-flood that still resolves to the trusted tail.
+- **H1 (High) FIXED — limiter map hard-bounded.** `MAX_TRACKED_KEYS=10_000`; `check()` re-inserts existing keys (Map order = LRU); new-key insert at cap runs `makeRoom()` = throttled `sweepIdle` (≤ once/window) + O(1) LRU eviction loop. Verified: 50k unique keys → size ≤ 10k; a key touched every 50 iters survives a 40k flood and stays drained/denied.
+- **M FIXED — `?hsCampaignId=` validated.** `page.tsx` now `isTogaUuid`-validates it before it flows into `togaLeadSink.upsertLead` as `togaCampaignUuid`; malformed drops to `undefined`.
+- **CSO re-review verdict: SHIP** (SAFE TO SHIP) — all of C1/H1/M genuinely closed, no new defects.
+- **Local dev env wired.** Created `C:\WWW\BDR\.env.local` (gitignored) by copying the 5 server-side vars (`HUBSPOT_ACCESS_TOKEN` + 4 `TOGA_*`) from `C:\WWW\info\.env.local` (PRODUCTION values, base `https://api.togahub.com/v2`). GA left unset locally (analytics.ts no-ops). Verified auth + contact writes hit prod.
+- **Diagnosed the BDR call flow end to end.** A `200 POST /api/call-now` in the browser is success from BDR's side; Toga calls are server-side (never in the browser network tab). BDR only sets `dtNextContactRequested`/`isOkayToCall`/call-type on the contact; the worker2 dialer cron places the actual Vapi call. Confirmed the test contact `88800869-acc7-632b-2520-bbd601224ff5` got `dtNextContactRequested` written in prod.
+- **Two `/capture` pushes to team KB (PUSHED).** `web-funnel-app.md` (rate-limit mitigation, server-side call seam, phone-less bug, `/api/contact` scrape vector, Next 16 proxy gotcha, dev-setup), `worker2/vapi-webhook-handler.md` (new "Outbound dialer eligibility" section), `ai-bdr/call-orchestration.md` (cross-ref). Second capture superseded the mid-state (test count → 104, clientIp.ts, SHIP verdict, 3 new security gotchas).
+
+## What did NOT work — DO NOT RETRY THESE
+- **Live test call never fired despite a correct 200 submit — TWO production-data blockers, not a code bug.**
+  1. The test contact's `Contacts.primaryContactPhoneNumberId` is **null**, so the dialer's eligibility SQL (`getEligibleContactsForVapi`, INNER JOIN `ContactPhoneNumbers ON Contacts.primaryContactPhoneNumberId`) can't see it. Root cause: the contact was created WITHOUT a phone (HubSpot record has none); the phone arrives via the later Call Now `PUT`, and **api2 creates the ContactPhoneNumber row but does not set the primary pointer on update**. Re-PUTting does NOT fix it (verified: primary stayed null while a phone row `(630) 803-7765` existed). This is a real product bug — any phone-less HubSpot contact can never be called; the funnel still shows success.
+  2. The active campaign `26.05 - AI BDR - Ryan Nitti` (`15d0c02f-501e-e081-2ead-61b78c854223`) reads `campaignAssistantId = null`; the dialer INNER JOINs `CampaignAssistants`, so a null-assistant campaign is never dialed. Could not confirm whether truly null or hidden from the API credential.
+- **`node check-contact.mjs` with a `with=ContactCallType,PrimaryContactPhoneNumber,CampaignsContacts` clause → HTTP 404.** The `with=` relation names were wrong for this endpoint; the plain `join=…&where=(…)` query returns 200. Use the join form, not `with=`.
+- **Toga `/contact-attempts` and `/campaigns-contacts` (some join variants) → HTTP 403/500 for this API credential.** Can't read ContactAttempts or all campaign-contact links directly; infer from contact + campaign state instead.
+- **Running `npx tsc`/`npx vitest`/`npx eslint`/`npx next build` without `cd /c/WWW/BDR &&` first.** The Bash tool cwd resets to `c:\WWW`, so tsc resolves the wrong binary and vitest runs sibling repos (saw 189 failing toga-blox-npm tests). ALWAYS prefix `cd /c/WWW/BDR &&`.
+- **`middleware.ts` on Next 16 is DEPRECATED.** Next 16.2.3 warns "use proxy instead". Correct convention is `src/proxy.ts` exporting a `proxy` function + `export const config: ProxyConfig`; import from `next/server`. (Confirmed from `node_modules/next/dist/lib/constants.js` + build source; did not ship a middleware.ts.)
+- **`info/.env.beta` is a DEAD file** — empty URLs, obsolete var names (`TOGA_CLIENT_SECRET` vs the current `TOGA_CLIENT_API_UUID`/`SECRET` pair). Production (`info/.env.local`) is the only working credential set `info` has. Do not source dev env from `.env.beta`.
+
+## Not tried yet (candidates for next session)
+- **Commit the working-tree changes** on `BDR-Phase-2` (developer has not asked yet). Suggested split: `feat: rate-limit hsContactId enumeration surfaces` (proxy.ts, rateLimit.ts, clientIp.ts, tests, PLAN §10) + `fix: validate hsCampaignId before toga upsert` (page.tsx).
+- **Unblock the live call test** (needs AI-BDR owner or a production write): set the test contact's `primaryContactPhoneNumberId`, and confirm/fix the campaign's `campaignAssistantId`.
+- **Decide the phone-less-contact bug fix**: api2-side (set primary on phone-row create during update) vs. a BDR workaround (PUT linking the existing phone-row uuid as primary).
+- **Non-gating security follow-ups (PLAN §10 / Phase 8):** lock the Amplify origin so nothing bypasses CloudFront; confirm the distribution injects+strips `CloudFront-Viewer-Address` before enabling `RATE_LIMIT_TRUST_CF_VIEWER_HEADER`; harden `readJsonObject` (body buffered before size check; measures UTF-16 length not bytes); re-verify no un-normalized path variant reaches a handler off the proxy `matcher`.
+- **Phase 8 authoritative controls:** edge WAF per-IP rate rule (supersedes the interim in-app limiter); opaque/signed CRM link tokens instead of raw `hsContactId` (raise with HubSpot/CRM owner).
+- Remaining PLAN §9 items (unchanged from prior sessions): §9.3 agent choice, §9.4 Landing service-picker scope, §9.5 campaign catalog, §9.6 togatech integration mechanism (gates deploy), §9.7 Tweaks panel in prod, §9.8 first-campaign copy, §9.12 Share button (still a mock), §9.13 connect-time copy. Phase 7 polish (pixel/motion/a11y; GA4 done).
+
+## Current file state
+| File | Status | Notes |
+|------|--------|-------|
+| `src/proxy.ts` | ADDED, uncommitted | Next 16 proxy; per-IP limits, soft-degrade entry + 429 API routes; env `RATE_LIMIT_TRUSTED_PROXY_HOPS`, `RATE_LIMIT_TRUST_CF_VIEWER_HEADER` |
+| `src/lib/rateLimit.ts` | ADDED, uncommitted | Pure token-bucket, clock-injected, hard-bounded 10k-key LRU map |
+| `src/lib/clientIp.ts` | ADDED, uncommitted | Pure trusted-IP resolution (right-to-left XFF; CF header opt-in; normalizeIp) |
+| `src/app/page.tsx` | MODIFIED, uncommitted | `isTogaUuid`-validate `hsCampaignId` before Toga upsert |
+| `test/rateLimit.test.ts` | ADDED, uncommitted | limiter unit tests incl. hard-bound-under-flood + LRU survival |
+| `test/clientIp.test.ts` | ADDED, uncommitted | IP-resolution tests incl. spoofed-leftmost-XFF bypass attempt |
+| `PLAN.md` | MODIFIED, uncommitted | §10 mitigation + SHIP + residuals; §11 Phase-8 checklist items |
+| `.env.local` | ADDED, uncommitted (gitignored) | 5 server-side vars from info prod; NEVER committed |
+| Repo otherwise | clean at `bb40b15` on `BDR-Phase-2` | all above are working-tree only; no commit/PR yet |
+| Team KB (`toga-tech`) | PUSHED | web-funnel-app.md, worker2/vapi-webhook-handler.md, ai-bdr/call-orchestration.md updated via 2× /capture |
+
+## Decisions made
+- **App-layer rate limiting now, as defense-in-depth** — not the authoritative fix. Per-instance memory on Amplify SSR is honestly documented; the WAF per-IP rule + opaque/signed CRM tokens remain the real controls (Phase 8). Chosen because it's the only layer buildable pre-deploy.
+- **Entry page soft-degrades; API routes hard-429.** Stripping `hsContactId` keeps a real (shared-NAT) user in the funnel minus prefill while denying a scraper any PII/upsert; the call/contact routes trigger real actions or leak full PII, so a hard stop is correct.
+- **Trust IP from the rightmost XFF, not leftmost** (C1 fix) — the leftmost is client-prependable behind CloudFront; the rightmost is CloudFront-appended. `CloudFront-Viewer-Address` made **opt-in (default off)** so an unverified distribution can't be bypassed via a forged copy — safe-by-default, ops enables after verifying.
+- **Hard-bound the limiter map with LRU eviction** (H1 fix) — a refill-only sweep is itself a unique-key-flood DoS; a hard ceiling + O(1) LRU + throttled reclaim guarantees bounded memory and O(1) amortized inserts.
+- **Used Next 16 `proxy.ts`, not `middleware.ts`** — the latter is deprecated in 16.
+- **Deferred `readJsonObject` + matcher-normalization fixes** as non-gating follow-ups — pre-existing, bounded by the Lambda payload cap + the call limiter; keeping the change focused and low-risk was the better call than widening scope into shared validated code.
+- **Phone-less-contact bug recorded as a gotcha, not its own doc** — has an api2-side root cause but surfaces on the funnel + worker2 dialer docs per KB conventions.
+
+## Blockers
+- **Live call test blocked on production data** (owner: AI-BDR owner, e.g. Rohan/Akash): test contact `primaryContactPhoneNumberId` is null, and campaign `campaignAssistantId` appears null. Both need a production write or owner action; developer's standing rule is read-only DB access for Claude.
+- **Committing to `BDR-Phase-2`** awaits developer go-ahead (standing "ask before git/remote" policy).
+- Pre-existing PLAN blockers unchanged: §9.6 togatech integration (gates Phase 8 deploy), §9.8 first-campaign copy from leadership.
+
+## Exact next step
+> Decide whether to (a) commit the working-tree changes on `BDR-Phase-2` as the two commits noted above, or (b) tackle the phone-less-contact bug fix — whichever the developer wants first. The security work itself is complete (SHIP-verified) and fully captured; nothing there is pending.
+
+---
+_Saved by /session-save on 2026-07-16_

package/package.json

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