backend-manager 5.6.3 → 5.6.4

package/CHANGELOG.md

@@ -14,6 +14,14 @@ 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.6.4] - 2026-06-11
+
+### Changed
+- **Consent side effects moved off shared test accounts (journey-account isolation).** The marketing webhook suite's revoke-event tests (`test/routes/marketing/webhook.js`) repeatedly write `consent.marketing.status = 'revoked'` to their target account — persistent side-effect data that previously landed on the shared `basic` account, leaving it revoked for the remainder of every run (and, since the v5.6.3 library consent gate, changing `sync()`/`add()` behavior for every later suite touching it). They now target a dedicated `journey-webhook-revoke` account. The extended-mode lifecycle suite (`test/email/marketing-lifecycle.js`) likewise now syncs a dedicated `journey-marketing-sync` account (`_test.allow_*` prefix) instead of the shared `consent-granted` sentinel (which the signup + consent-lifecycle suites rely on). Its cleanup step also now deletes the contact the suite actually created — previously it deleted the ADMIN account's contact, which (post-v5.6.3) revoked admin's doc consent mid-run AND left the synced contact behind in SendGrid/Beehiiv after every extended run. `docs/test-framework.md`'s journey-account rule now lists `consent.marketing` writes as a trigger. Validated: marketing route suites pass (46 passing / 10 env-gated skips / 0 failures).
+
+### Fixed
+- **Anonymous HMAC unsubscribe tests now actually run.** The self-test boot (`src/cli/commands/test.js`) injects a test-only `UNSUBSCRIBE_HMAC_KEY` into the process env (the emulated functions inherit it — same mechanism as the fixture webhook key), closing the fixture gap that left all 8 anon-HMAC tests in `test/routes/marketing/email-preferences.js` failing as "known env gap". Those tests are the route-level coverage for the v5.6.3 HMAC changes (signature validation, rate limiting, consent mirroring); marketing suites went from 38 passing + 8 failing to 46 passing + 0 failing.
+
 # [5.6.3] - 2026-06-11
 
 ### Fixed

package/docs/test-framework.md

@@ -390,7 +390,7 @@ Security-rules tests use the `rules` client (`src/test/utils/firestore-rules-cli
 
 ## Test Account Isolation (CRITICAL)
 
-**NEVER use shared accounts (`basic`, `admin`, `premium-active`, …) with the `test` processor or any operation that creates side-effect data** (orders, webhooks, subscriptions). The test processor auto-fires webhooks that upgrade a user's subscription asynchronously — using `basic` for a payment-intent test upgrades `basic` to a paid subscription and breaks every subsequent test that depends on `basic` being a basic user.
+**NEVER use shared accounts (`basic`, `admin`, `premium-active`, …) with the `test` processor or any operation that creates side-effect data** (orders, webhooks, subscriptions, consent revocations). The test processor auto-fires webhooks that upgrade a user's subscription asynchronously — using `basic` for a payment-intent test upgrades `basic` to a paid subscription and breaks every subsequent test that depends on `basic` being a basic user.
 
 **Rule: any test that creates persistent side-effect data MUST use a dedicated `journey-*` account.**
 
@@ -402,7 +402,7 @@ const response = await http.as('basic').post('payments/intent', { processor: 'te
 const response = await http.as('journey-payments-intent-discount').post('payments/intent', { processor: 'test', ... });
 ```
 
-**When to create a journey account:** the test uses `processor: 'test'`, creates docs in `payments-orders` / `payments-intents` / `payments-webhooks`, modifies subscription state, or sends webhooks that trigger Firestore onWrite handlers. Add it to `src/test/test-accounts.js` (framework tests) or your project's `test/_init.js` `accounts` array (consumer tests).
+**When to create a journey account:** the test uses `processor: 'test'`, creates docs in `payments-orders` / `payments-intents` / `payments-webhooks`, modifies subscription state, sends webhooks that trigger Firestore onWrite handlers, or **writes `consent.marketing` (grant/revoke)** — e.g. marketing webhook revoke events, or `DELETE /marketing/contact` (which mirrors `revoked` to the user doc). Revoked consent persists for the rest of the run and trips the email library's consent gate (`{ blocked: 'consent' }`) on every later `sync()`/`add()` of that account. Existing examples: `journey-webhook-revoke` (webhook revoke events), `journey-marketing-sync` (extended-mode live-provider sync + cleanup; `_test.allow_*` prefix). Add new ones to `src/test/test-accounts.js` (framework tests) or your project's `test/_init.js` `accounts` array (consumer tests).
 
 **Shared accounts are safe for:** validation-only tests (missing fields, invalid input, auth rejection, unknown processor), read-only operations, and tests with no async side effects.
 

package/package.json

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

package/src/cli/commands/test.js

@@ -237,6 +237,11 @@ class TestCommand extends BaseCommand {
       process.env.BACKEND_MANAGER_WEBHOOK_KEY = process.env.BACKEND_MANAGER_WEBHOOK_KEY || cfg.backend_manager?.webhookKey;
     } catch (_) { /* fixture config unreadable — let the normal key check report it */ }
 
+    // Anonymous HMAC unsubscribe tests sign links with this shared secret; the
+    // emulated functions inherit it from this process env (same mechanism as the
+    // webhook key above). Test-only value — production sets its own env var.
+    process.env.UNSUBSCRIBE_HMAC_KEY = process.env.UNSUBSCRIBE_HMAC_KEY || '_test-unsubscribe-hmac-key';
+
     this.ensureFixtureServiceAccount(fixture);
     this.linkFixtureDeps(fixture);
     this.log(chalk.cyan(`  Self-test: booting bundled fixture project (${fixture})`));

package/src/test/test-accounts.js

@@ -530,6 +530,37 @@ const JOURNEY_ACCOUNTS = {
       subscription: { product: { id: 'premium' }, status: 'cancelled', expires: getPastExpires() },
     },
   },
+  // Journey: marketing webhook revocation (test/routes/marketing/webhook.js). The
+  // SendGrid/Beehiiv revoke-event tests repeatedly write consent.marketing.status='revoked'
+  // to the target account — persistent side-effect data, so it must never be the shared
+  // `basic` account (revoked consent would persist for the rest of the run and trip the
+  // email library's consent gate for every later sync of that account).
+  'journey-webhook-revoke': {
+    id: 'journey-webhook-revoke',
+    uid: '_test-journey-webhook-revoke',
+    email: '_test.journey-webhook-revoke@{domain}',
+    properties: {
+      roles: {},
+      subscription: { product: { id: 'basic' }, status: 'active' },
+      personal: { name: { first: 'Webb', last: 'Revoke' } },
+    },
+  },
+  // Journey: live-provider sync round-trip (test/email/marketing-lifecycle.js, extended
+  // mode only). The `_test.allow_*` email prefix bypasses the `_test.*` marketing block so
+  // sync() reaches real SendGrid/Beehiiv; the suite's cleanup DELETE then removes the
+  // contact AND mirrors revoked consent to this account's doc. Dedicated account so that
+  // side effect stays isolated — the shared `consent-granted` sentinel is used by the
+  // signup and consent-lifecycle suites and must keep its granted state.
+  'journey-marketing-sync': {
+    id: 'journey-marketing-sync',
+    uid: '_test-journey-marketing-sync',
+    email: '_test.allow_journey-marketing-sync@{domain}',
+    properties: {
+      roles: {},
+      subscription: { product: { id: 'basic' }, status: 'active' },
+      personal: { name: { first: 'Lifecycle', last: 'Sync' } },
+    },
+  },
 };
 
 /**

package/test/email/marketing-lifecycle.js

@@ -61,8 +61,10 @@ module.exports = {
       auth: 'admin',
 
       async run({ http, assert, accounts, config, Manager }) {
-        // Use consent-granted account — it has _test.allow_* prefix that bypasses validation
-        const grantedUid = accounts['consent-granted'].uid;
+        // Dedicated journey account — its _test.allow_* prefix bypasses validation, and the
+        // cleanup step's DELETE revokes its doc consent, so it must not be a shared sentinel
+        // (consent-granted is used by the signup + consent-lifecycle suites).
+        const grantedUid = accounts['journey-marketing-sync'].uid;
         const admin = Manager.libraries.admin;
         await admin.firestore().doc(`users/${grantedUid}`).set({
           consent: { marketing: { status: 'granted' } },
@@ -112,14 +114,17 @@ module.exports = {
       },
     },
 
-    // Step 4: Clean up the admin test contact that sync added
+    // Step 4: Clean up the contact the sync step added to the live providers.
+    // DELETE also mirrors revoked consent to the matching user doc — which is why this
+    // targets the dedicated journey account (step 2 re-seeds granted before syncing, so
+    // the suite is self-healing across runs).
     {
-      name: 'cleanup-synced-admin-contact',
+      name: 'cleanup-synced-contact',
       auth: 'admin',
 
       async run({ http, accounts }) {
         await http.delete('backend-manager/marketing/contact', {
-          email: accounts.admin.email,
+          email: accounts['journey-marketing-sync'].email,
         }).catch(() => {});
       },
     },

package/test/routes/marketing/webhook.js

@@ -18,8 +18,12 @@
  *   - Silent skip when email doesn't map to a user (shared SendGrid account scenario)
  *   - Batched events processed independently
  *   - Unsupported event types ignored
+ *
+ * All revoke-event tests target the dedicated `journey-webhook-revoke` account: they
+ * leave it with consent.marketing.status='revoked' (persistent side-effect data), which
+ * must never land on the shared `basic` account — revoked consent persists for the rest
+ * of the run and trips the email library's consent gate for later syncs of that account.
  */
-const { TEST_ACCOUNTS } = require('../../../src/test/test-accounts.js');
 
 // Helper — generate a unique sg_event_id per test
 function sgEventId(name) {
@@ -105,8 +109,8 @@ module.exports = {
       name: 'sendgrid-group-unsubscribe-writes-consent',
       auth: 'none',
       async run({ http, firestore, assert, accounts }) {
-        const uid = accounts.basic.uid;
-        const email = accounts.basic.email;
+        const uid = accounts['journey-webhook-revoke'].uid;
+        const email = accounts['journey-webhook-revoke'].email;
         const eventId = sgEventId('group-unsub');
         const eventTimestamp = Math.floor(Date.now() / 1000);
 
@@ -130,8 +134,8 @@ module.exports = {
       name: 'sendgrid-unsubscribe-event-handled',
       auth: 'none',
       async run({ http, firestore, assert, accounts }) {
-        const uid = accounts.basic.uid;
-        const email = accounts.basic.email;
+        const uid = accounts['journey-webhook-revoke'].uid;
+        const email = accounts['journey-webhook-revoke'].email;
         const eventId = sgEventId('unsub');
 
         const response = await http.as('none').post(
@@ -152,8 +156,8 @@ module.exports = {
       name: 'sendgrid-spamreport-event-handled',
       auth: 'none',
       async run({ http, firestore, assert, accounts }) {
-        const uid = accounts.basic.uid;
-        const email = accounts.basic.email;
+        const uid = accounts['journey-webhook-revoke'].uid;
+        const email = accounts['journey-webhook-revoke'].email;
         const eventId = sgEventId('spamreport');
 
         const response = await http.as('none').post(
@@ -173,8 +177,8 @@ module.exports = {
       name: 'sendgrid-hard-bounce-event-handled',
       auth: 'none',
       async run({ http, firestore, assert, accounts }) {
-        const uid = accounts.basic.uid;
-        const email = accounts.basic.email;
+        const uid = accounts['journey-webhook-revoke'].uid;
+        const email = accounts['journey-webhook-revoke'].email;
         const eventId = sgEventId('hard-bounce');
 
         // Only hard bounces (bounce_classification='Invalid Address') revoke consent.
@@ -195,8 +199,8 @@ module.exports = {
       name: 'sendgrid-dropped-hard-bounce-handled',
       auth: 'none',
       async run({ http, firestore, assert, accounts }) {
-        const uid = accounts.basic.uid;
-        const email = accounts.basic.email;
+        const uid = accounts['journey-webhook-revoke'].uid;
+        const email = accounts['journey-webhook-revoke'].email;
         const eventId = sgEventId('dropped');
 
         // 'dropped' follows the same classification filter as 'bounce'.
@@ -219,7 +223,7 @@ module.exports = {
       name: 'sendgrid-technical-bounce-ignored',
       auth: 'none',
       async run({ http, assert, accounts }) {
-        const email = accounts.basic.email;
+        const email = accounts['journey-webhook-revoke'].email;
         const eventId = sgEventId('technical-bounce');
 
         // Technical bounces (DMARC, TLS, DNS) are sender-side issues — the recipient's
@@ -239,7 +243,7 @@ module.exports = {
       name: 'sendgrid-bounce-without-classification-ignored',
       auth: 'none',
       async run({ http, assert, accounts }) {
-        const email = accounts.basic.email;
+        const email = accounts['journey-webhook-revoke'].email;
         const eventId = sgEventId('unclassified-bounce');
 
         // No bounce_classification — can't confirm a hard bounce, so skip.
@@ -258,7 +262,7 @@ module.exports = {
       name: 'sendgrid-delivered-event-ignored',
       auth: 'none',
       async run({ http, firestore, assert, accounts }) {
-        const email = accounts.basic.email;
+        const email = accounts['journey-webhook-revoke'].email;
         const eventId = sgEventId('delivered');
 
         const response = await http.as('none').post(
@@ -276,7 +280,7 @@ module.exports = {
       name: 'sendgrid-open-event-ignored',
       auth: 'none',
       async run({ http, assert, accounts }) {
-        const email = accounts.basic.email;
+        const email = accounts['journey-webhook-revoke'].email;
         const eventId = sgEventId('open');
 
         const response = await http.as('none').post(
@@ -317,8 +321,8 @@ module.exports = {
       name: 'sendgrid-batched-events-processed-independently',
       auth: 'none',
       async run({ http, firestore, assert, accounts }) {
-        const uid = accounts.basic.uid;
-        const email = accounts.basic.email;
+        const uid = accounts['journey-webhook-revoke'].uid;
+        const email = accounts['journey-webhook-revoke'].email;
         const e1 = sgEventId('batch-1');
         const e2 = sgEventId('batch-2');
         const e3 = sgEventId('batch-3');
@@ -348,8 +352,8 @@ module.exports = {
       name: 'sendgrid-duplicate-event-reprocessed-idempotently',
       auth: 'none',
       async run({ http, firestore, assert, accounts }) {
-        const uid = accounts.basic.uid;
-        const email = accounts.basic.email;
+        const uid = accounts['journey-webhook-revoke'].uid;
+        const email = accounts['journey-webhook-revoke'].email;
         const eventId = sgEventId('duplicate');
 
         // First delivery
@@ -380,8 +384,8 @@ module.exports = {
       name: 'sendgrid-event-without-eventId-processed',
       auth: 'none',
       async run({ http, firestore, assert, accounts }) {
-        const uid = accounts.basic.uid;
-        const email = accounts.basic.email;
+        const uid = accounts['journey-webhook-revoke'].uid;
+        const email = accounts['journey-webhook-revoke'].email;
 
         const response = await http.as('none').post(
           `backend-manager/marketing/webhook?provider=sendgrid&key=${process.env.BACKEND_MANAGER_WEBHOOK_KEY}`,
@@ -404,8 +408,8 @@ module.exports = {
       name: 'beehiiv-subscription-unsubscribed-writes-consent',
       auth: 'none',
       async run({ http, firestore, assert, accounts, config, skip }) {
-        const uid = accounts.basic.uid;
-        const email = accounts.basic.email;
+        const uid = accounts['journey-webhook-revoke'].uid;
+        const email = accounts['journey-webhook-revoke'].email;
         const eventId = `_test-bh-unsub-${Date.now()}`;
         const eventISO = new Date().toISOString();
         const publicationId = config.marketing?.newsletter?.publicationId;
@@ -439,8 +443,8 @@ module.exports = {
       name: 'beehiiv-subscription-deleted-handled',
       auth: 'none',
       async run({ http, firestore, assert, accounts, config }) {
-        const uid = accounts.basic.uid;
-        const email = accounts.basic.email;
+        const uid = accounts['journey-webhook-revoke'].uid;
+        const email = accounts['journey-webhook-revoke'].email;
         const eventId = `_test-bh-deleted-${Date.now()}`;
         const publicationId = config.marketing?.newsletter?.publicationId;
 
@@ -468,8 +472,8 @@ module.exports = {
       name: 'beehiiv-subscription-paused-handled',
       auth: 'none',
       async run({ http, firestore, assert, accounts, config }) {
-        const uid = accounts.basic.uid;
-        const email = accounts.basic.email;
+        const uid = accounts['journey-webhook-revoke'].uid;
+        const email = accounts['journey-webhook-revoke'].email;
         const eventId = `_test-bh-paused-${Date.now()}`;
         const publicationId = config.marketing?.newsletter?.publicationId;
 
@@ -499,13 +503,13 @@ module.exports = {
         // Send an event with a publication_id that does NOT match this brand's pub.
         // Simulates the shared-devbeans scenario where the parent forwarder fans
         // an event to brands that don't share the publication — they silent-skip.
-        const email = accounts.basic.email;
+        const email = accounts['journey-webhook-revoke'].email;
         const eventId = `_test-bh-pubmismatch-${Date.now()}`;
 
         // Snapshot revokedAt BEFORE the request so we can prove the pub-mismatch
         // handler didn't write anything new. (The basic account may already have
         // a beehiiv-sourced revoke from a prior test that legitimately fired.)
-        const beforeDoc = await firestore.get(`users/${accounts.basic.uid}`);
+        const beforeDoc = await firestore.get(`users/${accounts['journey-webhook-revoke'].uid}`);
         const beforeRevokedAt = beforeDoc?.consent?.marketing?.revokedAt || null;
 
         const response = await http.as('none').post(
@@ -527,7 +531,7 @@ module.exports = {
 
         // Reload the user doc and verify revokedAt is byte-equivalent to before —
         // pub-mismatch must not write a new revoke entry.
-        const afterDoc = await firestore.get(`users/${accounts.basic.uid}`);
+        const afterDoc = await firestore.get(`users/${accounts['journey-webhook-revoke'].uid}`);
         const afterRevokedAt = afterDoc?.consent?.marketing?.revokedAt || null;
 
         assert.deepEqual(
@@ -568,7 +572,7 @@ module.exports = {
       auth: 'none',
       async run({ http, assert, accounts, config }) {
         // 'subscription.created' (new signup) is NOT a revoke — should be ignored.
-        const email = accounts.basic.email;
+        const email = accounts['journey-webhook-revoke'].email;
         const publicationId = config.marketing?.newsletter?.publicationId;
         const eventId = `_test-bh-created-${Date.now()}`;
 
@@ -593,8 +597,8 @@ module.exports = {
       name: 'beehiiv-duplicate-event-reprocessed-idempotently',
       auth: 'none',
       async run({ http, firestore, assert, accounts, config, skip }) {
-        const uid = accounts.basic.uid;
-        const email = accounts.basic.email;
+        const uid = accounts['journey-webhook-revoke'].uid;
+        const email = accounts['journey-webhook-revoke'].email;
         const publicationId = config.marketing?.newsletter?.publicationId;
         const eventId = `_test-bh-dup-${Date.now()}`;