backend-manager 5.2.5 → 5.2.7

package/CHANGELOG.md

@@ -14,6 +14,46 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+# [5.2.7] - 2026-05-24
+
+### Fixed
+
+- **`inferContact` silent-failure logging.** When the AI inference returned an empty result (either the AI call failed and returned null, or `gpt-5-mini` returned a parsed response with all-empty fields, or the response shape was missing `firstName`), the whole flow silently swallowed the failure and the signup's `user.personal.name` got written as `null`/`null`. Confirmed live on Somiibo: signed up `ian.wiedenman.business@gmail.com` twice on the same backend — first signup inferred nothing (empty name written), second signup correctly inferred "Ian Wiedenman". Same email, same code, transient AI hiccup, zero log trail. Added three unconditional diagnostic logs to `src/manager/libraries/infer-contact.js` (AI returned null, AI parsed response had all fields empty, AI response missing firstName) plus a log in `src/manager/routes/user/signup/post.js#inferUserContact` when the helper returns null. Next silent failure will at least leave a breadcrumb.
+
+# [5.2.6] - 2026-05-24
+
+### Added
+
+- **`scripts/test-helper-providers.js`** — small CLI for live-test verification. Run from any consumer's `functions/` dir: `node <bem>/scripts/test-helper-providers.js find <email>` (check SendGrid + Beehiiv state without dashboards) or `purge <email>` (remove from both providers). Used during end-to-end consent-pipeline testing.
+- **Email-template namespacing.** `general/email` route now translates `:` in `settings.id` to a folder separator, so `general:download-app-link` resolves to `templates/general/download-app-link.js`. Existing `templates/download-app-link.js` moved into `templates/general/` to match.
+
+### Changed
+
+- **Payment webhook + dispute-alert routes now accept either `BACKEND_MANAGER_WEBHOOK_KEY` (preferred) or `BACKEND_MANAGER_KEY` (legacy).** Phase 1 of the webhook-key migration plan in `TODO-WEBHOOK-KEY-UPGRADE.md` — non-breaking dual-acceptance so consumers can roll over at their own pace. `src/manager/routes/payments/webhook/post.js:28` + `src/manager/routes/payments/dispute-alert/post.js:20` validate against either env var. Test-processor self-fire in `src/manager/routes/payments/intent/processors/test.js:158` now uses `BACKEND_MANAGER_WEBHOOK_KEY` directly. All 13 payment test files (`test/routes/payments/*.js`, `test/events/payments/journey-*.js`) updated to use `BACKEND_MANAGER_WEBHOOK_KEY` for webhook URLs. `src/test/utils/http-client.js` + `src/test/runner.js` thread the new env var through the test context. `docs/stripe-webhook-forwarding.md` reflects the dual-key acceptance. Phase 2 (drop the legacy fallback) is tracked in `TODO-WEBHOOK-KEY-LEGACY-REMOVAL.md`.
+- **`npx mgr emulator` no longer wraps the emulator in a keep-alive subprocess.** Previously spawned a sleep-86400 wrapper via `runWithEmulator`; now spawns the emulator child directly and uses a clean SIGINT handler. Cleaner shutdown, no orphaned subprocesses, no `node-powertools` dep on the boot path. `npx mgr test`'s auto-start path uses the same helper.
+
+### Fixed
+
+- **Finished the v5.2.3 SendGrid timeout bump that missed 5 sites.** v5.2.3's CHANGELOG claimed "All 9 fetch sites updated" but actually 5 sites in `sendgrid.js` (including `upsertContacts:118` — the hot path used by `Marketing.sync()`) were still using `timeout: 15000`. Confirmed live on Somiibo: a signup with marketing consent granted silently dropped both SendGrid and Beehiiv with `Request timed out` after ~18s. Now every API call in `sendgrid.js` goes through the `SENDGRID_TIMEOUT_MS` (60s) constant. The only remaining literal is the S3 CSV download in `getSegmentContacts:578` (30s — not a SendGrid API call).
+- **`beehiiv.js` timeouts unified under a new `BEEHIIV_TIMEOUT_MS` (60s) constant.** Two hot-path sites (`addSubscriber:71` and the unsub endpoint at `:455`) were still on `timeout: 15000`. Same silent-drop failure mode as SendGrid above. Every Beehiiv API call now uses the constant.
+- **Audited entire BEM codebase for short timeouts. Zero prod-path timeouts under 60s remain.**
+  - **Bumped 6 sites from 10-15s → 60s:**
+    - `src/manager/libraries/email/validation.js:136` — ZeroBounce mailbox check
+    - `src/manager/libraries/email/generators/newsletter.js:520, 549` — parent-server `/newsletter-sources` GET + PUT
+    - `src/manager/routes/payments/intent/processors/test.js:163` — test-processor self-fire webhook
+    - `src/manager/routes/marketing/email-preferences/post.js:169, 179` — SendGrid ASM suppression POST + DELETE
+  - **Bumped 9 sites from 30s → 60s:**
+    - `src/manager/libraries/infer-contact.js:46` — PeopleDataLabs AI enrichment
+    - `src/manager/libraries/email/providers/sendgrid.js:578` — S3 CSV download for segment exports
+    - `src/manager/functions/core/actions/api/user/delete.js:34` + `src/manager/routes/user/delete.js:51` — internal sign-out fan-out
+    - `src/manager/events/firestore/payments-webhooks/analytics.js:228, 301` — Facebook + Reddit Conversions API
+    - `src/manager/routes/user/oauth2/providers/discord.js:25` + `…/google.js:30` — OAuth token-revoke
+    - `src/manager/helpers/analytics.js:331` — itwcw-package-analytics event fire
+  - **Bumped 2 sites from 30s → 120s:**
+    - `src/manager/events/cron/daily/ghostii-auto-publisher.js:106` — gpt-image-1 hero image generation (regularly 30-60s)
+    - `src/manager/events/cron/daily/ghostii-auto-publisher.js:177` — gpt-5+web-search blog post generation (regularly 60-90s)
+- **Audit rule going forward:** any external-API call in BEM prod paths uses **60s minimum** (120s+ for LLM/image generation). Short timeouts are silent-failure machines in serverless code where Cloud Function timeouts already give us a generous outer bound. `_legacy/` files, `src/test/` infra, and `src/cli/` commands keep their existing timeouts — they're not on the request hot path.
+
 # [5.2.5] - 2026-05-22
 
 ### Added

package/TODO-CANCEL-EMAIL-MISSING-ORDER-ID.md

@@ -0,0 +1,159 @@
+# TODO: Cancel email missing Order # on non-trial cancels
+
+## Symptom
+
+Observed 2026-05-23 in `_test.journey-payments-cancel@somiibo.com`'s inbox:
+
+```
+Subject: Your subscription has been cancelled #
+Body:    Order #
+         Your subscription has been cancelled.
+```
+
+The `#` after both `Subject` and `Order #` is bare — `order.id` rendered as empty string.
+
+The trial-cancel sibling (`_test.journey-payments-trial-cancel@somiibo.com`) on the SAME run got the order ID correctly:
+
+```
+Subject: Your subscription has been cancelled #3794-5306-7041
+Body:    Order #3794-5306-7041
+```
+
+So this is path-specific, not a template bug.
+
+## Root cause (narrowed but not yet proven)
+
+Two cancel paths feed the same `subscription-cancelled` transition handler ([src/manager/events/firestore/payments-webhooks/transitions/subscription/subscription-cancelled.js:17](src/manager/events/firestore/payments-webhooks/transitions/subscription/subscription-cancelled.js#L17)):
+
+```js
+subject: `Your subscription has been cancelled #${order?.id || ''}`,
+```
+
+Subject + template both render `order.id`. When `order.id` is falsy it falls through to `''`.
+
+`order.id` is built in [src/manager/events/firestore/payments-webhooks/on-write.js:241-242](src/manager/events/firestore/payments-webhooks/on-write.js#L241-L242):
+
+```js
+const order = {
+  id: orderId,
+  ...
+};
+```
+
+Where `orderId` (line 118) is:
+
+```js
+orderId = library.getOrderId(resource) || passThruOrderId;
+```
+
+`library.getOrderId(resource)` reads the order ID off the processor resource's `meta_data` field. `passThruOrderId` is a PayPal-only fallback from the hosted-page `pass_thru_content`.
+
+**Working path** (`journey-payments-trial-cancel`): the trial cancel goes through the `/payments/cancel` endpoint, which already has the `orderId` from `users/{uid}.subscription.payment.orderId`. By the time Stripe/PayPal fires the cancellation webhook back, `meta_data.orderId` on the subscription resource is set, so `library.getOrderId(resource)` returns the order ID. Email shows the ID.
+
+**Broken path** (`journey-payments-cancel`): this is the webhook-driven cancel (no `/payments/cancel` endpoint call — `orderDoc.requests.cancellation` is null in the test assertions). The webhook arrives with a subscription resource whose `meta_data.orderId` is empty (or `library.getOrderId(resource)` returns null/empty string). `passThruOrderId` is null because this is Stripe, not PayPal. `orderId` ends up null. `order.id = null`. Email renders `Order #`.
+
+## What's still unknown
+
+1. **Why is `meta_data.orderId` missing on the Stripe subscription resource at cancel time?** Possibilities:
+   - The journey test never set `meta_data` on the subscription (only on the customer or the initial intent).
+   - `library.setMetaData` was called during the new-subscription transition but Stripe's subscription resource didn't persist it (Stripe quirk where `metadata` on subscription vs. customer vs. invoice diverge).
+   - The `customer.subscription.deleted` event payload doesn't include `metadata` even when it was set — this would be a Stripe-side gotcha.
+2. **Does this affect production?** Possibly — depends on whether real users' Stripe subscription resources have `meta_data.orderId` set. Worth checking one real cancelled subscription in the Stripe dashboard.
+
+## Investigation steps
+
+1. **Re-run the cancel journey with `TEST_EXTENDED_MODE=true`** and watch the BEM logs:
+   ```bash
+   cd /Users/ian/Developer/Repositories/Somiibo/somiibo-backend/functions
+   TEST_EXTENDED_MODE=true npx mgr test events/payments/journey-payments-cancel
+   ```
+   Search the logs around the cancellation webhook for the resolved `orderId` value:
+   ```bash
+   npx mgr logs:read --filter "journey-payments-cancel" --limit 200 | grep -i "orderid\|order id"
+   ```
+
+2. **Inspect the raw webhook payload** stored in `payments-webhooks/{eventId}` for that test run:
+   ```bash
+   npx mgr firestore:query "payments-webhooks" --limit 20  # find the deleted-subscription event
+   npx mgr firestore:get "payments-webhooks/<eventId>"     # inspect raw.data.object.metadata
+   ```
+   If `raw.data.object.metadata.orderId` is empty → confirms Stripe didn't include it in the event.
+
+3. **Check `library.getOrderId(resource)` implementation** for the Stripe library:
+   ```bash
+   grep -n "getOrderId" /Users/ian/Developer/Repositories/ITW-Creative-Works/backend-manager/src/manager/libraries/payment/stripe.js
+   ```
+   Confirm what field path it reads. If it reads only `resource.metadata.orderId`, that's the bug — should also check `resource.metadata.bm_orderId` (some processors have different conventions) or fall through to a Firestore lookup.
+
+## Fix options (in order of preference)
+
+### Option A — Fall back to userDoc on the transition side (safest)
+
+In [subscription-cancelled.js:17](src/manager/events/firestore/payments-webhooks/transitions/subscription/subscription-cancelled.js#L17), if `order.id` is missing, fall back to `userDoc.subscription.payment.orderId`:
+
+```js
+const orderId = order?.id || userDoc?.subscription?.payment?.orderId || '';
+
+sendOrderEmail({
+  template: 'core/order/cancelled',
+  subject: `Your subscription has been cancelled${orderId ? ` #${orderId}` : ''}`,
+  ...
+  data: {
+    order: {
+      ...order,
+      id: orderId,
+      ...
+    },
+  },
+});
+```
+
+This is the **safest** fix because it works regardless of whether the bug is in `library.getOrderId`, in Stripe's event payload, or in how `meta_data` was set originally. `userDoc.subscription.payment.orderId` is written when the subscription first activates and reliably has the ID by cancel time.
+
+The subject also degrades gracefully — `Your subscription has been cancelled` (no bare `#`) when the ID truly can't be found.
+
+### Option B — Fix at the source (`on-write.js`)
+
+In [on-write.js:118](src/manager/events/firestore/payments-webhooks/on-write.js#L118), add another fallback after `library.getOrderId`:
+
+```js
+orderId = library.getOrderId(resource)
+  || passThruOrderId
+  || userDoc?.subscription?.payment?.orderId
+  || null;
+```
+
+This fixes it for ALL handlers (not just cancel), and at the cost of a Firestore read of the user doc earlier in `on-write.js` than today. May not need a new read if userDoc is already fetched by this point — confirm by reading the function top-to-bottom.
+
+### Option C — Fix `library.getOrderId(resource)` (Stripe library)
+
+If investigation step 3 shows the Stripe library is reading the wrong field path, fix it there. Smallest blast radius if the bug is genuinely in one processor's resolver and not a Stripe-event-payload gotcha.
+
+## Recommendation
+
+Do **A + B together** — A makes the email correct today regardless of root cause; B prevents the same gap from biting any other handler (refund, suspend, etc.). C only if investigation step 3 reveals an actual mis-read.
+
+## Regression test
+
+Add an assertion to `test/events/payments/journey-payments-cancel.js` that the post-cancellation userDoc still has `subscription.payment.orderId` set AND that the cancel email's `order.id` would render non-empty. Without a regression test, the same bug will silently come back the next time someone refactors `library.getOrderId`.
+
+Pseudo-assertion:
+
+```js
+assert.ok(userDoc.subscription?.payment?.orderId, 'userDoc.subscription.payment.orderId should be set after cancellation');
+// And if we capture the email payload (via a test-mode hook in sendOrderEmail), assert order.id !== '' in the rendered data.
+```
+
+If `sendOrderEmail` doesn't already have a test-mode capture, that's a small enhancement worth doing once — it would let every email-emitting transition assert its rendered payload, not just cancel.
+
+## Affected versions
+
+Confirmed broken: BEM 5.2.5 (current live on Somiibo as of 2026-05-23). Likely broken in earlier versions too — the `order?.id || ''` template defensive fallback was added explicitly to handle missing IDs, suggesting this gap has been latent for a while. The trial-cancel path masked it because trial cancels go through the endpoint and have `orderId` set in a different code path.
+
+## Related files
+
+- [src/manager/events/firestore/payments-webhooks/transitions/subscription/subscription-cancelled.js](src/manager/events/firestore/payments-webhooks/transitions/subscription/subscription-cancelled.js) — handler with `order?.id || ''` fallback
+- [src/manager/events/firestore/payments-webhooks/on-write.js:241](src/manager/events/firestore/payments-webhooks/on-write.js#L241) — `order` object construction
+- [src/manager/events/firestore/payments-webhooks/on-write.js:118](src/manager/events/firestore/payments-webhooks/on-write.js#L118) — `orderId` resolution from `library.getOrderId` + pass-through fallback
+- [test/events/payments/journey-payments-cancel.js](test/events/payments/journey-payments-cancel.js) — broken-path test (currently passes because it doesn't assert the email payload)
+- [test/events/payments/journey-payments-trial-cancel.js](test/events/payments/journey-payments-trial-cancel.js) — working-path test

package/TODO-WEBHOOK-KEY-LEGACY-REMOVAL.md

@@ -0,0 +1,15 @@
+# TODO: Remove legacy BACKEND_MANAGER_KEY acceptance from webhook routes
+
+When v5.2.x shipped, the two payment-webhook routes were switched to prefer `BACKEND_MANAGER_WEBHOOK_KEY` but still accept `BACKEND_MANAGER_KEY` as a transitional fallback so existing provider URLs (registered with the old key) keep working until OMEGA re-registers them with the new key.
+
+Once every brand's provider URLs (Stripe / PayPal / Chargebee / Chargeblast / Coinbase / etc.) have been re-registered via OMEGA to use `BACKEND_MANAGER_WEBHOOK_KEY`, drop the legacy fallback:
+
+## Files to update
+
+- `src/manager/routes/payments/webhook/post.js` — line ~28: remove the `|| key === process.env.BACKEND_MANAGER_KEY` half of the validation check.
+- `src/manager/routes/payments/dispute-alert/post.js` — line ~20: same removal. Also update the docstring at line ~11 to drop the "BACKEND_MANAGER_KEY accepted as legacy fallback" note.
+- `docs/stripe-webhook-forwarding.md` — drop the "BACKEND_MANAGER_KEY also accepted as a legacy fallback" parenthetical.
+
+## How to verify it's safe
+
+Grep production logs (`npx mgr logs:read --fn bm_api --grep "payments/webhook" --limit 1000`) and confirm zero `401 Invalid key` hits over a meaningful window. If there are any, those are providers still on the old URL — re-register them via OMEGA before dropping the fallback.

package/TODO-WEBHOOK-KEY-UPGRADE.md

@@ -0,0 +1,138 @@
+# TODO: Payment Webhook Key Upgrade — `BACKEND_MANAGER_KEY` → `BACKEND_MANAGER_WEBHOOK_KEY`
+
+## Context
+
+In BEM v5.2.0 we introduced `BACKEND_MANAGER_WEBHOOK_KEY` as a dedicated env var for third-party webhook authentication, scoped narrowly so it can be rotated independently of the admin key. The marketing routes (`/marketing/webhook`, `/marketing/webhook/forward`) use it correctly.
+
+The **payment webhook** (`/payments/webhook`) and **dispute-alert webhook** (`/payments/dispute-alert`) still validate against `BACKEND_MANAGER_KEY` — the general-purpose admin key. This is a security misalignment: a leaked admin key could forge payment webhooks, and rotating the admin key forces every Stripe/PayPal/Chargebee webhook URL to be re-registered.
+
+Plan: gradual rollout. Phase 1 (this BEM release) makes the payment routes accept **either** key so existing brand deploys (with only `BACKEND_MANAGER_KEY` set) keep working AND new brands can start using `BACKEND_MANAGER_WEBHOOK_KEY` immediately. Phase 2 (a later BEM release) drops the legacy fallback after every brand has been migrated.
+
+## Files needing the dual-key check
+
+| File | Line | Current |
+|---|---|---|
+| [src/manager/routes/payments/webhook/post.js](src/manager/routes/payments/webhook/post.js) | 28 | `if (!key \|\| key !== process.env.BACKEND_MANAGER_KEY)` |
+| [src/manager/routes/payments/dispute-alert/post.js](src/manager/routes/payments/dispute-alert/post.js) | 20 | `if (!key \|\| key !== process.env.BACKEND_MANAGER_KEY)` |
+| [src/manager/routes/payments/intent/processors/test.js](src/manager/routes/payments/intent/processors/test.js) | 158 | `key=${process.env.BACKEND_MANAGER_KEY}` |
+
+## Phase 1 — Dual-key acceptance (this BEM release)
+
+### Validation change (webhook + dispute-alert)
+
+Replace the single-key check with a dual-key check. Accept the request if `key` matches EITHER `BACKEND_MANAGER_WEBHOOK_KEY` OR the legacy `BACKEND_MANAGER_KEY`.
+
+```js
+// Before
+if (!key || key !== process.env.BACKEND_MANAGER_KEY) {
+  return assistant.respond('Invalid key', { code: 401 });
+}
+
+// After (Phase 1 — dual-key fallback)
+const validKeys = [
+  process.env.BACKEND_MANAGER_WEBHOOK_KEY,
+  process.env.BACKEND_MANAGER_KEY, // legacy — remove in Phase 2
+].filter(Boolean);
+
+if (!key || !validKeys.includes(key)) {
+  return assistant.respond('Invalid key', { code: 401 });
+}
+```
+
+Notes:
+- `.filter(Boolean)` matters — if a brand hasn't set `BACKEND_MANAGER_WEBHOOK_KEY` yet, `validKeys` becomes `[BACKEND_MANAGER_KEY]` (single-element). If a brand HAS set it, both are accepted.
+- If BOTH env vars are unset (misconfigured brand), `validKeys` is `[]` and every request 401s. That's the right behavior — explicit failure beats silent acceptance.
+- Update the route header comments (lines 11 and 27 of dispute-alert, 27 of webhook) to mention both keys.
+
+### Test processor self-fire URL
+
+Switch [src/manager/routes/payments/intent/processors/test.js:158](src/manager/routes/payments/intent/processors/test.js#L158) to PREFER `BACKEND_MANAGER_WEBHOOK_KEY` and fall back to `BACKEND_MANAGER_KEY`:
+
+```js
+const webhookKey = process.env.BACKEND_MANAGER_WEBHOOK_KEY || process.env.BACKEND_MANAGER_KEY;
+const webhookUrl = `${assistant.Manager.project.apiUrl}/backend-manager/payments/webhook?processor=test&key=${webhookKey}`;
+```
+
+This way the test processor exercises the new key when it's set, and falls back to the legacy key on brands that haven't migrated yet.
+
+### Test infrastructure updates
+
+**`src/test/utils/http-client.js`** — add `backendManagerWebhookKey` field alongside the existing `backendManagerKey`.
+
+**`src/test/runner.js`** — thread `backendManagerWebhookKey` through the runner context the same way `backendManagerKey` is threaded today (3 sites).
+
+**`src/cli/commands/test.js`** — read `BACKEND_MANAGER_WEBHOOK_KEY` from env (parallel to the existing `BACKEND_MANAGER_KEY` read), pass it through to the runner, fall back to the admin key if unset.
+
+**Route + journey tests** — update test fixtures to prefer `BACKEND_MANAGER_WEBHOOK_KEY` when set:
+- `test/routes/payments/webhook.js` — all `${config.backendManagerKey}` interpolations in `payments/webhook?...&key=` URLs
+- `test/routes/payments/dispute-alert.js` — same (13 sites)
+- `test/events/payments/journey-*.js` — only the `payments/webhook?...&key=` URLs (NOT the admin-auth uses elsewhere in journey tests)
+
+Use `config.backendManagerWebhookKey || config.backendManagerKey` everywhere so both keys are exercised.
+
+### Docs
+
+- **`docs/stripe-webhook-forwarding.md`** — line 7 + 18 — note the dual-key acceptance, recommend `BACKEND_MANAGER_WEBHOOK_KEY` for new setups, note legacy `BACKEND_MANAGER_KEY` is still accepted for backwards compatibility.
+- **`CHANGELOG.md`** — entry under the next version. Categorize under `Changed` (NOT `BREAKING` — that's reserved for Phase 2). Spell out: "Payment webhook + dispute-alert routes now accept either `BACKEND_MANAGER_WEBHOOK_KEY` (preferred) or `BACKEND_MANAGER_KEY` (legacy). Set `BACKEND_MANAGER_WEBHOOK_KEY` in every consumer brand's `.env` and run OMEGA payment ensure before Phase 2 ships."
+- **`templates/_.env`** — already declares both keys, no change.
+
+### Verification (manual)
+
+1. **Local test (no `BACKEND_MANAGER_WEBHOOK_KEY` set)** — confirm legacy fallback still passes:
+   ```bash
+   npx mgr test routes/payments/webhook routes/payments/dispute-alert events/payments
+   ```
+   Expect green.
+
+2. **Local test (`BACKEND_MANAGER_WEBHOOK_KEY` set to a different value)** — confirm the new key is accepted AND the legacy key still works:
+   ```bash
+   BACKEND_MANAGER_WEBHOOK_KEY=test-webhook-key npx mgr test routes/payments/webhook routes/payments/dispute-alert events/payments
+   ```
+   Expect green.
+
+3. **Live spot-check on one brand (Somiibo)** — deploy this BEM release to Somiibo (whose `.env` currently only has `BACKEND_MANAGER_KEY` set OR has both), trigger a Stripe test event, confirm the webhook doc lands in Firestore.
+
+## Phase 2 — Drop legacy fallback (future BEM release)
+
+**Do NOT do this until every consumer brand has been migrated and verified.** Tracking checklist for migration readiness:
+
+- [ ] Every consumer `.env` has `BACKEND_MANAGER_WEBHOOK_KEY` set (spot-check via OMEGA across all brands)
+- [ ] OMEGA `payment/ensure/{stripe,paypal,chargebee}-webhook.js` updated to use `BACKEND_MANAGER_WEBHOOK_KEY` when constructing webhook URLs (see "OMEGA changes" below)
+- [ ] OMEGA `--service payment` run across every brand to re-register webhook URLs at Stripe/PayPal/Chargebee with the new key
+- [ ] Stale webhook URLs (the old ones with `key=BACKEND_MANAGER_KEY`) deleted from each provider — these will start 401-ing the moment Phase 2 ships
+- [ ] At least one live billing cycle (Stripe charge, refund, dispute) observed working end-to-end on the new key for at least 3 brands
+
+When all boxes are checked, Phase 2 ships as a **breaking change**:
+
+```js
+// Phase 2 — single-key (legacy removed)
+if (!key || key !== process.env.BACKEND_MANAGER_WEBHOOK_KEY) {
+  return assistant.respond('Invalid key', { code: 401 });
+}
+```
+
+Phase 2 CHANGELOG entry goes under `BREAKING`.
+
+## OMEGA changes (separate repo, needed for Phase 2 prep)
+
+Touched files (do NOT do these in Phase 1 — they're for Phase 2 prep):
+
+| File | Change |
+|---|---|
+| `/Users/ian/Developer/Repositories/ITW-Creative-Works/omega-manager/src/services/payment/ensure/stripe-webhook.js` | Line 38: swap `BACKEND_MANAGER_KEY` → `BACKEND_MANAGER_WEBHOOK_KEY`. Line 76 check + line 77 message + line 64 doc comment: update env var name. |
+| `/Users/ian/Developer/Repositories/ITW-Creative-Works/omega-manager/src/services/payment/ensure/paypal-webhook.js` | Same change at lines 40, 66, 77, 78, 79. |
+| `/Users/ian/Developer/Repositories/ITW-Creative-Works/omega-manager/src/services/payment/ensure/chargebee-webhook.js` | Same change at lines 34, 45, 57, 58, 59. |
+
+**Idempotent re-registration + stale cleanup:** Each ensure file looks up existing webhooks **by URL**. Since the URL will change (the `key=` query param differs), the existing webhook will NOT match and a new one will be created. The OLD webhook (with the admin key) needs to be cleaned up — otherwise the third party will deliver to both and the old one will start failing 401 once Phase 2 ships.
+
+Cleanup approach in each ensure file: after creating the new webhook, scan for any other webhook whose URL points at `/payments/webhook?processor={name}` (regardless of key) and delete the stale ones. Match on path prefix, not full URL. Stripe + PayPal + Chargebee all support webhook deletion via the same API methods these files already use for listing.
+
+Helper: extract a `pathMatchesOurProcessor(url, processor)` in each ensure file — strip query string, match the path-and-processor segment.
+
+## Known constraints / gotchas
+
+1. **Phase 1 is non-breaking.** Any consumer can deploy this BEM release without touching their `.env` — the legacy key still works.
+2. **`BACKEND_MANAGER_KEY` continues to grant admin via `assistant.authenticate()`.** That hasn't changed; it's still the admin secret for internal API calls (newsletter, send-email, user/delete, ghostii cron, electron-client, oauth2 state encryption). This TODO is *only* about scoping webhook endpoints to a separate key.
+3. **`UNSUBSCRIBE_HMAC_KEY` is unrelated** and stays separate.
+4. **Admin grant is NOT triggered by the webhook routes.** Middleware auto-runs `assistant.authenticate()` via `Usage.init()`, which reads `data.backendManagerKey` from the request body. The three webhook routes get their key via `?key=` query string (NOT body), and their request bodies are third-party payloads (Stripe events, PayPal events, Chargeblast alerts) that can't contain the real admin secret. So switching the routes' validation does NOT remove any admin-grant the handlers depend on — they write to Firestore via `libraries.admin` (Admin SDK, always full access) anyway.
+5. **Test processor self-fire** must use the same key the BEM endpoint accepts, which is why the test processor URL also gets updated in Phase 1.

package/docs/stripe-webhook-forwarding.md

@@ -4,7 +4,7 @@ BEM auto-starts Stripe CLI webhook forwarding when running `npx mgr serve` or `n
 
 **Requirements:**
 - `STRIPE_SECRET_KEY` set in `functions/.env`
-- `BACKEND_MANAGER_KEY` set in `functions/.env`
+- `BACKEND_MANAGER_WEBHOOK_KEY` set in `functions/.env` (`BACKEND_MANAGER_KEY` also accepted as a legacy fallback)
 - [Stripe CLI](https://stripe.com/docs/stripe-cli) installed
 
 **Standalone usage:**
@@ -15,4 +15,4 @@ npx mgr stripe
 
 If any prerequisite is missing, webhook forwarding is silently skipped with an info message.
 
-The forwarding URL is: `http://localhost:{hostingPort}/backend-manager/payments/webhook?processor=stripe&key={BACKEND_MANAGER_KEY}`
+The forwarding URL is: `http://localhost:{hostingPort}/backend-manager/payments/webhook?processor=stripe&key={BACKEND_MANAGER_WEBHOOK_KEY}`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.2.5",
+  "version": "5.2.7",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {

package/scripts/test-helper-providers.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+
+/**
+ * Test Helper — direct provider lookups + removals via API
+ *
+ * Lets the live-test checklist verify SendGrid + Beehiiv state without
+ * clicking around in dashboards. Reuses the same provider helpers that
+ * BEM uses in production (findContact / removeContact).
+ *
+ * Usage (run from a consumer project's functions/ dir):
+ *
+ *   node ../../../backend-manager/scripts/test-helper-providers.js find  user@example.com
+ *   node ../../../backend-manager/scripts/test-helper-providers.js purge user@example.com
+ *
+ * Or symlink: `ln -s ../../../backend-manager/scripts/test-helper-providers.js ./prov`
+ * then: `node ./prov find user@example.com`
+ *
+ * - find:  prints whether the contact exists in SendGrid + Beehiiv (and the data shape).
+ * - purge: removes the contact from BOTH providers (idempotent; safe if absent).
+ *
+ * The script picks up:
+ *   - SENDGRID_API_KEY, BEEHIIV_API_KEY from <cwd>/.env (functions/.env)
+ *   - marketing.sendgrid.listId, marketing.beehiiv.publicationId from <cwd>/backend-manager-config.json
+ *   - service-account from <cwd>/service-account.json
+ *
+ * Exit codes: 0 ok, 1 usage error, 2 provider error.
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+const cwd = process.cwd();
+const envPath = path.join(cwd, '.env');
+const configPath = path.join(cwd, 'backend-manager-config.json');
+const serviceAccountPath = path.join(cwd, 'service-account.json');
+
+// --- sanity checks ---
+if (!fs.existsSync(envPath)) {
+  console.error(`✗ Missing ${envPath} — run from the consumer's functions/ dir`);
+  process.exit(1);
+}
+if (!fs.existsSync(configPath)) {
+  console.error(`✗ Missing ${configPath} — run from the consumer's functions/ dir`);
+  process.exit(1);
+}
+if (!fs.existsSync(serviceAccountPath)) {
+  console.error(`✗ Missing ${serviceAccountPath} — run from the consumer's functions/ dir`);
+  process.exit(1);
+}
+
+// --- parse args ---
+const [, , cmd, email] = process.argv;
+const VALID_CMDS = ['find', 'purge'];
+
+if (!cmd || !VALID_CMDS.includes(cmd) || !email) {
+  console.error('Usage:');
+  console.error('  node test-helper-providers.js find  <email>');
+  console.error('  node test-helper-providers.js purge <email>');
+  process.exit(1);
+}
+
+// --- bootstrap env (dotenv style, minimal) ---
+require('dotenv').config({ path: envPath });
+
+if (!process.env.SENDGRID_API_KEY) {
+  console.error('✗ SENDGRID_API_KEY not set in .env');
+  process.exit(1);
+}
+if (!process.env.BEEHIIV_API_KEY) {
+  console.error('✗ BEEHIIV_API_KEY not set in .env');
+  process.exit(1);
+}
+
+// --- bootstrap Manager so providers can read Manager.config.marketing.* ---
+// The providers require '../../../index.js' which is the Manager singleton.
+// We need to load BEM from the consumer's node_modules (not the BEM repo's own src)
+// so it picks up the consumer's config + service account.
+let Manager;
+try {
+  const BackendManager = require(path.join(cwd, 'node_modules', 'backend-manager'));
+  Manager = (new BackendManager()).init({}, { setupFunctionsLegacy: false, log: false });
+} catch (e) {
+  console.error('✗ Failed to bootstrap Manager from consumer node_modules:', e.message);
+  process.exit(2);
+}
+
+// --- load providers via the BEM Manager.libraries surface (preferred) or direct path ---
+const sendgridProviderPath = path.join(cwd, 'node_modules', 'backend-manager', 'src', 'manager', 'libraries', 'email', 'providers', 'sendgrid.js');
+const beehiivProviderPath = path.join(cwd, 'node_modules', 'backend-manager', 'src', 'manager', 'libraries', 'email', 'providers', 'beehiiv.js');
+
+const sendgrid = require(sendgridProviderPath);
+const beehiiv = require(beehiivProviderPath);
+
+// --- commands ---
+async function find(email) {
+  console.log(`Looking up ${email} on both providers...`);
+
+  const [sgContact, bhContact] = await Promise.all([
+    sendgrid.findContact(email).catch(e => ({ _error: e.message })),
+    beehiiv.findContact(email).catch(e => ({ _error: e.message })),
+  ]);
+
+  console.log('\n── SendGrid ──');
+  if (sgContact?._error) {
+    console.log(`  ✗ error: ${sgContact._error}`);
+  } else if (!sgContact) {
+    console.log('  ⊘ not found');
+  } else {
+    console.log(`  ✓ found — id=${sgContact.id || '?'}, email=${sgContact.email || '?'}`);
+  }
+
+  console.log('\n── Beehiiv ──');
+  if (bhContact?._error) {
+    console.log(`  ✗ error: ${bhContact._error}`);
+  } else if (!bhContact) {
+    console.log('  ⊘ not found');
+  } else {
+    console.log(`  ✓ found — id=${bhContact.id || '?'}, email=${bhContact.email || '?'}, status=${bhContact.status || '?'}`);
+  }
+
+  return { sgContact, bhContact };
+}
+
+async function purge(email) {
+  console.log(`Removing ${email} from both providers...`);
+
+  const [sgResult, bhResult] = await Promise.all([
+    sendgrid.removeContact(email).catch(e => ({ _error: e.message })),
+    beehiiv.removeContact(email).catch(e => ({ _error: e.message })),
+  ]);
+
+  console.log('\n── SendGrid ──');
+  if (sgResult?._error) {
+    console.log(`  ✗ error: ${sgResult._error}`);
+  } else {
+    console.log(`  ✓ ${JSON.stringify(sgResult)}`);
+  }
+
+  console.log('\n── Beehiiv ──');
+  if (bhResult?._error) {
+    console.log(`  ✗ error: ${bhResult._error}`);
+  } else {
+    console.log(`  ✓ ${JSON.stringify(bhResult)}`);
+  }
+
+  return { sgResult, bhResult };
+}
+
+// --- main ---
+(async () => {
+  try {
+    if (cmd === 'find') {
+      await find(email);
+    } else if (cmd === 'purge') {
+      await purge(email);
+    }
+    process.exit(0);
+  } catch (e) {
+    console.error('✗ Unexpected error:', e);
+    process.exit(2);
+  }
+})();

package/src/cli/commands/base-command.js

@@ -236,7 +236,7 @@ class BaseCommand {
     this.log(chalk.gray('  (Stripe webhook forwarding is currently disabled - coming soon!)\n'));
     return null;
 
-    // Load .env so STRIPE_SECRET_KEY and BACKEND_MANAGER_KEY are available
+    // Load .env so STRIPE_SECRET_KEY and BACKEND_MANAGER_WEBHOOK_KEY are available
     const envPath = path.join(functionsDir, '.env');
     if (jetpack.exists(envPath)) {
       require('dotenv').config({ path: envPath, quiet: true });
@@ -248,9 +248,9 @@ class BaseCommand {
       return null;
     }
 
-    // Check for Backend Manager key
-    if (!process.env.BACKEND_MANAGER_KEY) {
-      this.log(chalk.gray('  (Stripe webhook forwarding disabled - BACKEND_MANAGER_KEY not set in .env)\n'));
+    // Check for Backend Manager webhook key
+    if (!process.env.BACKEND_MANAGER_WEBHOOK_KEY) {
+      this.log(chalk.gray('  (Stripe webhook forwarding disabled - BACKEND_MANAGER_WEBHOOK_KEY not set in .env)\n'));
       return null;
     }
 
@@ -276,7 +276,7 @@ class BaseCommand {
       }
     }
 
-    const forwardUrl = `http://localhost:${hostingPort}/backend-manager/payments/webhook?processor=stripe&key=${process.env.BACKEND_MANAGER_KEY}`;
+    const forwardUrl = `http://localhost:${hostingPort}/backend-manager/payments/webhook?processor=stripe&key=${process.env.BACKEND_MANAGER_WEBHOOK_KEY}`;
 
     this.log(chalk.gray(`  Stripe webhook forwarding -> localhost:${hostingPort}\n`));