backend-manager 5.6.2 → 5.6.3

package/CHANGELOG.md

@@ -14,6 +14,16 @@ 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.3] - 2026-06-11
+
+### Fixed
+- **NeverBounce single-check result parsing — every signup mailbox check has failed since v5.5.1.** `validation-provider-neverbounce.js` compared `data.result` against numeric codes (`data.result === 0 || 3 || 4`), but the NeverBounce v4 single/check API returns string textcodes (`"valid"`, `"invalid"`, ...) — so every completed check returned `{ valid: false, status: 'unknown' }`, including deliverable mailboxes, and the signup route silently skipped marketing sync for ALL signups. Production-confirmed via GCF logs: somiibo June 7 = 30 synced / 0 failed; June 9–11 = 0 synced / 93 failed; first failure 25 minutes after the v5.5.1 deploy (which switched signup to `ALL_CHECKS` and exposed the latent v5.5.0 bug). New `parseResult()` handles textcodes (canonical), tolerates numeric codes, and normalizes `catch-all` → `catchall`; allowed results stay valid/catchall/unknown. 11 regression parse cases added to `validation.test.js` (suite now 69 cases); fix live-validated against the real API. ZeroBounce provider audited — already string-based, no change.
+- **Library-level marketing consent gate.** `Marketing.sync()`/`Marketing.add()` (`src/manager/libraries/email/marketing/index.js`) now skip users whose `consent.marketing.status` is the literal string `'revoked'` and return `{ blocked: 'consent', email }` (mirroring the `{ blocked: 'validation', ... }` shape) — BEFORE validation and provider calls. Previously the gate existed only at SOME call sites, so the payments on-write sync (`events/firestore/payments-webhooks/on-write.js`) and the admin PUT re-sync re-added users who had unsubscribed. `sync()` gates after the user doc is resolved (doc or uid); `add()` looks up the user by email first (same `auth.email` query as the webhook processors) — no user doc or lookup failure proceeds (fail open). ONLY `'revoked'` blocks: missing/null consent proceeds, so legacy users without a `consent` field keep syncing. `remove()` stays ungated. Covers all callers including the legacy API-command twins (`add-marketing-contact.js`). Gate logic unit-tested in `src/manager/libraries/email/marketing/consent-gate.test.js` (28 plain-node cases, no emulator).
+- **Anonymous HMAC unsubscribe now removes the contact from Beehiiv too** (`routes/marketing/email-preferences/post.js`). The email-footer one-click unsubscribe only suppressed the SendGrid ASM group, leaving the contact live on Beehiiv — a compliance bug. The route now also calls `mailer.remove(email)` (best-effort, after the ASM call succeeds).
+- **Anonymous HMAC re-subscribe now actually re-adds the contact.** Previously it only lifted the ASM suppression and wrote consent `granted` — the contact was never re-added to providers. `mirrorAnonymousToUserDoc` now returns the matched uid (or null); the route calls `mailer.sync(uid)` for matched users (the mirror writes `granted` first, so the library consent gate passes — no bypass flags) or `mailer.add({ email, source: 'resubscribe' })` for pure newsletter contacts. Best-effort, same testing guard as the ASM call.
+- **Admin `DELETE /marketing/contact` now sticks** (`routes/marketing/contact/delete.js`). The route removed the contact from providers but left `consent.marketing.status = 'granted'`, so any later sync re-added the contact. After the provider removal it now mirrors `consent.marketing.status = 'revoked'` (`revokedAt` with `source: 'admin'`, same write shape as the webhook processors) to the matching user doc — best-effort, silent when the email maps to no user.
+- **Stale docs/comments corrected in the same change set:** `docs/consent.md` now describes the shipped library gate, cross-provider HMAC unsubscribe, re-subscribe re-add, and admin-DELETE revoke mirror (new capture point 5); `validation.js` header no longer claims signup uses "disposable check only" (it runs `ALL_CHECKS` before marketing sync); `marketing/index.js` header no longer attributes the signup sync to the "Auth on-create handler" (it's the `/user/signup` route).
+
 # [5.6.2] - 2026-06-11
 
 ### Fixed

package/CLAUDE.md

@@ -156,7 +156,7 @@ Deep references live in `docs/`. **Whenever you make a behavioral change, update
 - [docs/admin-post-route.md](docs/admin-post-route.md) — `POST/PUT /admin/post` blog creation via GitHub (image extraction + resize at ingest + `@post/` rewriting). Also the publish target for the Ghostii article engine (`libraries/content/ghostii.js`).
 - [docs/payment-system.md](docs/payment-system.md) — full payment pipeline: Intent → Webhook → On-Write → Transition; subscription model, statuses, `resolveSubscription()`, transition handlers, processor interface, product config, test processor
 - [docs/marketing-campaigns.md](docs/marketing-campaigns.md) — campaign CRUD routes, recurring campaigns, generator pipeline (newsletter), newsletter-driven blog article (`content.article.enabled`), template-owned schemas, asset hosting, seed campaigns
-- [docs/consent.md](docs/consent.md) — marketing consent capture: canonical `consent.{legal,marketing}` user-doc shape, signup-form capture, account-page toggle, HMAC unsub link, SendGrid+Beehiiv webhook receivers, parent forwarder (`/marketing/webhook/forward`), migration script template
+- [docs/consent.md](docs/consent.md) — marketing consent capture: canonical `consent.{legal,marketing}` user-doc shape, signup-form capture, account-page toggle, HMAC unsub link (cross-provider unsub + re-add on resubscribe), admin contact-DELETE revoke mirror, SendGrid+Beehiiv webhook receivers, parent forwarder (`/marketing/webhook/forward`), library-level consent gate in `email.add()`/`email.sync()` (revoked-only skip), migration script template
 - [docs/mcp.md](docs/mcp.md) — Model Context Protocol server: 19 tools, stdio + HTTP transports, OAuth, Claude Chat/Code configuration
 
 ### Subsystems & Libraries

package/README.md

@@ -451,10 +451,10 @@ GDPR/CASL-compliant consent capture and cross-provider unsubscribe sync.
 - **Canonical user-doc shape** — `consent.{legal,marketing}.{status, grantedAt, revokedAt}` with full audit metadata (timestamp, source, IP, exact label text)
 - **Server-authoritative timestamps** — client timestamps ignored, defending against clock manipulation
 - **Account-page toggle** — `/account` notifications section lets logged-in users opt in/out, hits both SendGrid + Beehiiv
-- **HMAC unsubscribe links** — email-footer one-click flow continues to work
+- **HMAC unsubscribe links** — email-footer one-click flow continues to work; unsubscribe removes the contact from ALL providers (not just the SendGrid ASM group), re-subscribe re-adds the contact
 - **Provider webhook receivers** — `POST /marketing/webhook?provider=sendgrid|beehiiv&key=X` catches unsubscribe / spam / bounce events from SendGrid and Beehiiv, writes the user doc + syncs to the OTHER provider
 - **Parent forwarder** — single public webhook endpoint (`/marketing/webhook/forward`) on the parent BEM fans out to every brand's child BEM so each one updates its own Firestore
-- **Guard against marketing sync without consent** — signup route and `email.add()` short-circuit when `consent.marketing.status !== 'granted'`
+- **Library-level consent gate** — `email.add()` and `email.sync()` skip users whose `consent.marketing.status === 'revoked'` (covers every call site: payment syncs, admin re-syncs, newsletter form); admin contact DELETE mirrors `revoked` back to the user doc so removals stick
 
 See [docs/consent.md](docs/consent.md) for the full architecture, source enum reference, migration script template, and provider configuration steps.
 

package/docs/consent.md

@@ -9,7 +9,7 @@ This doc covers the **server-side** (BEM) part of the system. The matching front
 1. **Capture explicit, affirmative consent** at signup with separate checkboxes for legal terms (required) and marketing communications (optional). Store the exact label text the user agreed to.
 2. **Let users withdraw consent at any time** via the account-page toggle or the email-footer unsubscribe link.
 3. **Stay in sync with provider-side actions** — when a user clicks unsubscribe in a SendGrid or Beehiiv email, the user doc updates AND the OTHER provider is also notified.
-4. **Never re-add an unsubscribed user** — `email.add()` and `email.sync()` short-circuit when `consent.marketing.status === 'revoked'`.
+4. **Never re-add an unsubscribed user** — `email.add()` and `email.sync()` short-circuit in the library itself when `consent.marketing.status === 'revoked'`, so every call site (payment-event syncs, admin re-syncs, public newsletter form, legacy API commands) is covered. See "Email library consent gate" below.
 
 ## Canonical user-doc shape
 
@@ -51,7 +51,7 @@ consent: {
 
 ## Capture points
 
-There are four places where consent gets recorded or updated. All four converge on the same canonical shape.
+There are five places where consent gets recorded or updated. All five converge on the same canonical shape.
 
 ### 1. Signup form (Phase B)
 
@@ -110,6 +110,8 @@ Body: { email, asmId, sig, action: 'subscribe' | 'unsubscribe' }
 - `sig = HMAC-SHA256(email, UNSUBSCRIBE_HMAC_KEY)` — proves we generated the link.
 - IP-rate-limited (5/day per IP).
 - **Also writes the user doc** if the email maps to a user — `consent.marketing.{status, revokedAt}` with `source: 'sendgrid'` (since HMAC links only appear in SendGrid email footers).
+- **Unsubscribe is cross-provider** — besides the SendGrid ASM suppression, the route calls `mailer.remove(email)` (best-effort) so the contact is removed from Beehiiv too. ASM suppression alone only stops SendGrid sends.
+- **Subscribe actually re-adds the contact** — the user-doc mirror writes `granted` BEFORE the provider calls, then the route calls `mailer.sync(uid)` when the email maps to a user (the fresh grant passes the library consent gate — no bypass flags) or `mailer.add({ email, source: 'resubscribe' })` when it doesn't. Best-effort, same testing guard as the ASM call.
 - Backward-compatible — old in-flight email links continue to work.
 
 ### 4. Provider webhooks (Phase E)
@@ -145,6 +147,17 @@ Each processor's `handleEvent` does the same shape of work:
 
 **Beehiiv publication filter.** Each Beehiiv event includes a `publication_id`. The processor compares this against `beehiivProvider.getPublicationId()`, which reads `Manager.config.marketing.newsletter.publicationId` (populated at brand-onboarding time by OMEGA's `beehiiv/ensure/publication.js`). Mismatch → silent skip. This is how shared-publication events (e.g. devbeans shared by 6 brands) get routed correctly — each brand processes only events matching its own publication. Brands without `publicationId` in config silently skip all Beehiiv webhook events. The same convention applies to SendGrid: `marketing.campaigns.listId` is populated by OMEGA's `sendgrid/ensure/list.js`.
 
+### 5. Admin contact removal
+
+[src/manager/routes/marketing/contact/delete.js](../src/manager/routes/marketing/contact/delete.js) — admin-only endpoint.
+
+```
+DELETE /backend-manager/marketing/contact
+Body: { email }
+```
+
+After removing the contact from all providers, the route mirrors `consent.marketing.status = 'revoked'` to the user doc when the email maps to a user — `revokedAt` from server time with `source: 'admin'`, same write shape as the webhook processors (`grantedAt` preserved as audit history). Without this mirror, the next `sync()` (payment event, admin re-sync) would re-add the contact the admin just removed. Best-effort and silent when no user matches.
+
 ## Parent forwarder (Phase E)
 
 [src/manager/routes/marketing/webhook/forward/post.js](../src/manager/routes/marketing/webhook/forward/post.js)
@@ -187,11 +200,22 @@ The parent BEM has its own brand (e.g. `itw-creative-works`) with its own users.
 4. The 6 brands sharing the devbeans publication: `getPublicationId()` matches, they each look up the user, only the brand(s) with the user write the doc and call `mailer.remove`.
 5. The brands with dedicated publications: `getPublicationId()` mismatch, silent skip.
 
-## Email library short-circuit
+## Email library consent gate
 
 [src/manager/libraries/email/marketing/index.js](../src/manager/libraries/email/marketing/index.js)
 
-`email.add()` and `email.sync()` check the user's `consent.marketing.status` before contacting providers. A user marked `'revoked'` is never re-added. This is the safety net against accidental re-subscription via batch syncs or campaign sends.
+`email.add()` and `email.sync()` check the user's `consent.marketing.status` IN THE LIBRARY, before validation and provider calls. Because the gate lives in the library rather than at call sites, every caller is covered: the signup route, the email-preferences toggle, payment-event syncs ([events/firestore/payments-webhooks/on-write.js](../src/manager/events/firestore/payments-webhooks/on-write.js)), the admin PUT re-sync (`routes/marketing/contact/put.js`), the public newsletter form (`routes/marketing/contact/post.js`), and the legacy API-command twins (`functions/core/actions/api/general/add-marketing-contact.js`).
+
+**Semantics:**
+
+- **Revoked-only skip.** ONLY the literal string `'revoked'` blocks. Missing consent, `null`, or any other value proceeds — legacy users have no `consent` field and must keep syncing.
+- **`sync()`** — after the user doc is resolved (whether passed as a doc or fetched by uid), a revoked doc logs a warn and returns `{ blocked: 'consent', email }` (mirrors the `{ blocked: 'validation', ... }` shape) BEFORE validation and provider calls.
+- **`add()`** — looks up the user doc by email first (same `auth.email` equality query the webhook processors use). Doc found + revoked → `{ blocked: 'consent', email }`. No doc found → proceed (pure newsletter contact). Lookup failure → proceed (fail open, logged) — a rare duplicate add is recoverable; silently dropping contacts is not.
+- **`remove()` is never gated** — removal is always safe.
+
+The signup route ADDITIONALLY gates at its call site (`userRecord.consent.marketing.status === 'granted'` before calling `mailer.sync(uid)`) — that check runs before the route's paid NeverBounce/ZeroBounce mailbox validation, so declined users never trigger a paid check. The library gate is the safety net for everyone else.
+
+The gate logic is unit-tested without Firestore in [src/manager/libraries/email/marketing/consent-gate.test.js](../src/manager/libraries/email/marketing/consent-gate.test.js) — run with `node src/manager/libraries/email/marketing/consent-gate.test.js`.
 
 ## Configuration
 
@@ -304,6 +328,7 @@ After the migration: optionally run a re-opt-in drip campaign to legally recover
 - [test/routes/marketing/webhook.js](../test/routes/marketing/webhook.js) — 15+ tests covering SendGrid + Beehiiv processors against the emulator
 - [test/routes/marketing/webhook-forward.js](../test/routes/marketing/webhook-forward.js) — verifies the forwarder route returns 404 on non-parent BEMs
 - [test/helpers/webhook-forward.js](../test/helpers/webhook-forward.js) — 12 unit-style tests with mocked admin + fetch, covering fan-out, URL derivation, failure isolation, self-inclusion, edge cases
+- [src/manager/libraries/email/marketing/consent-gate.test.js](../src/manager/libraries/email/marketing/consent-gate.test.js) — 28 plain-node cases for the library consent gate (revoked-only skip semantics, `{ blocked: 'consent' }` returns from `sync()`/`add()`, by-email lookup query + normalization, fail-open on lookup errors); runs directly with `node`, no emulator
 
 **Total: 75+ tests across the consent system.**
 

package/docs/email-system.md

@@ -58,7 +58,7 @@ After `build()`, `send()` delivers via SendGrid, handles scheduled sends (>71h
 
 ### Email Validation Pipeline (`validation.js`)
 
-All marketing contact operations (`add`, `sync`) pass through `validate()` before reaching providers. Checks run in order; the first failure short-circuits.
+All marketing contact operations (`add`, `sync`) pass through `validate()` before reaching providers. Checks run in order; the first failure short-circuits. (The library consent gate runs even earlier — a user with `consent.marketing.status === 'revoked'` returns `{ blocked: 'consent', email }` before validation; see [consent.md](consent.md#email-library-consent-gate).)
 
 | # | Check | What it catches | Cost | Default |
 |---|---|---|---|---|

package/package.json

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

package/src/manager/libraries/email/data/disposable-domains.json

@@ -1256,6 +1256,7 @@
   "cloudgen.world",
   "cloudsign.in",
   "cloudwhitespace.cc.cd",
+  "cloudwhitezone.cc.cd",
   "clout.wiki",
   "clowmail.com",
   "clrmail.com",
@@ -2406,6 +2407,7 @@
   "gdmail.top",
   "gdqoe.net",
   "gdxs.cc.cd",
+  "gear3.pro",
   "gebrauchtwarencenter.com",
   "gedmail.win",
   "geekforex.com",
@@ -2624,6 +2626,7 @@
   "gpt-mail-free-6419.dynv6.net",
   "gpt-mail-free-6603.dynv6.net",
   "gpt-mail-free-6664.dynv6.net",
+  "gpt-mail-free-6691.dynv6.net",
   "gpt-mail-free-6779.dynv6.net",
   "gpt-mail-free-6812.dynv6.net",
   "gpt-mail-free-6925.dynv6.net",
@@ -3412,6 +3415,7 @@
   "kruay.com",
   "krypton.tk",
   "krysentra.cfd",
+  "kskblzdjdwkzkbl.top",
   "ksmtrck.tk",
   "kuhaku.indevs.in",
   "kuhrap.com",
@@ -5818,6 +5822,7 @@
   "tempalias.com",
   "tempblockchain.com",
   "tempe-mail.com",
+  "tempebossok.my.id",
   "tempemail.biz",
   "tempemail.co.za",
   "tempemail.com",
@@ -6656,6 +6661,7 @@
   "x24.com",
   "x80.dpdns.org",
   "x80la.shop",
+  "x9ad1.my",
   "xagloo.co",
   "xagloo.com",
   "xandoria.cfd",

package/src/manager/libraries/email/marketing/consent-gate.test.js

@@ -0,0 +1,249 @@
+/**
+ * Consent gate test — verifies Marketing.add()/sync() skip users whose
+ * consent.marketing.status is the literal string 'revoked' (and ONLY then).
+ *
+ * Plain-node control-flow test (no emulator, no providers, no network):
+ * - isMarketingRevoked() — the pure gate semantic (revoked-only skip).
+ * - sync() — gate fires after doc resolution, BEFORE validation/providers, so a
+ *   revoked doc returns { blocked: 'consent', email } with zero I/O. Proceed cases
+ *   stop at the testing-mode provider guard (assistant.isTesting() → true here).
+ * - add() — by-email lookup runs through a minimal in-memory firestore stand-in to
+ *   exercise add()'s wiring (block on revoked, proceed on no-user, fail open on
+ *   lookup error). The emulator suites (test/routes/marketing/*) remain the
+ *   integration surface for the real Firestore paths.
+ *
+ * Run:   node src/manager/libraries/email/marketing/consent-gate.test.js
+ */
+const Marketing = require('./index.js');
+
+const { isMarketingRevoked } = Marketing;
+
+// Proceed cases must stop at the testing-mode provider guard — never let an ambient
+// TEST_EXTENDED_MODE (or provider API keys) in the shell turn this into a live call.
+delete process.env.TEST_EXTENDED_MODE;
+
+// ─── isMarketingRevoked(): ONLY the literal 'revoked' blocks ───
+const GATE_CASES = [
+  { name: 'status revoked', doc: { consent: { marketing: { status: 'revoked' } } }, expect: true },
+  { name: 'status granted', doc: { consent: { marketing: { status: 'granted' } } }, expect: false },
+  { name: 'status null', doc: { consent: { marketing: { status: null } } }, expect: false },
+  { name: 'status missing', doc: { consent: { marketing: {} } }, expect: false },
+  { name: 'marketing missing', doc: { consent: {} }, expect: false },
+  { name: 'consent missing (legacy user)', doc: { auth: { email: 'legacy@gmail.com' } }, expect: false },
+  { name: 'empty doc', doc: {}, expect: false },
+  { name: 'null doc (no user)', doc: null, expect: false },
+  { name: 'undefined doc', doc: undefined, expect: false },
+  { name: 'status REVOKED (case-sensitive literal)', doc: { consent: { marketing: { status: 'REVOKED' } } }, expect: false },
+  { name: 'status pending (future enum value)', doc: { consent: { marketing: { status: 'pending' } } }, expect: false },
+  { name: 'status true (non-string)', doc: { consent: { marketing: { status: true } } }, expect: false },
+];
+
+/**
+ * Minimal assistant — just what the Marketing constructor + gate paths read.
+ * isTesting() → true so proceed cases stop at the provider guard (no network).
+ */
+function buildAssistant(admin) {
+  const calls = { logs: [], warns: [], errors: [] };
+
+  const assistant = {
+    Manager: {
+      libraries: { admin },
+      config: {},
+    },
+    isTesting: () => true,
+    log: (...args) => calls.logs.push(args),
+    warn: (...args) => calls.warns.push(args),
+    error: (...args) => calls.errors.push(args),
+  };
+
+  return { assistant, calls };
+}
+
+/**
+ * Minimal in-memory firestore stand-in for add()'s by-email lookup and sync()'s
+ * by-uid fetch. `userDoc: null` → empty query result / nonexistent doc.
+ * `failLookup: true` → the query get() rejects (exercises the fail-open path).
+ */
+function buildAdmin({ userDoc = null, failLookup = false } = {}) {
+  const captured = { queries: [], docPaths: [] };
+
+  const admin = {
+    firestore: () => ({
+      collection: (name) => ({
+        where: (field, op, value) => {
+          captured.queries.push({ collection: name, field, op, value });
+          return {
+            limit: () => ({
+              get: async () => {
+                if (failLookup) {
+                  throw new Error('firestore unavailable');
+                }
+                return userDoc
+                  ? { empty: false, docs: [{ id: 'test-uid', data: () => userDoc }] }
+                  : { empty: true, docs: [] };
+              },
+            }),
+          };
+        },
+      }),
+      doc: (path) => {
+        captured.docPaths.push(path);
+        return {
+          get: async () => ({
+            exists: !!userDoc,
+            data: () => userDoc,
+          }),
+        };
+      },
+    }),
+  };
+
+  return { admin, captured };
+}
+
+const REVOKED_DOC = {
+  auth: { email: 'revoked.user@gmail.com' },
+  consent: { marketing: { status: 'revoked' } },
+};
+
+const GRANTED_DOC = {
+  auth: { email: 'granted.user@gmail.com' },
+  consent: { marketing: { status: 'granted' } },
+};
+
+const LEGACY_DOC = {
+  auth: { email: 'legacy.user@gmail.com' },
+  // No consent field at all — pre-consent-system user, must keep syncing
+};
+
+async function run() {
+  let passed = 0;
+  let failed = 0;
+
+  function check(ok, name, detail) {
+    if (ok) {
+      passed++;
+      return;
+    }
+
+    failed++;
+    console.log(`  ✗ ${name}`);
+    if (detail) {
+      console.log(`    ${detail}`);
+    }
+  }
+
+  // ─── 1. isMarketingRevoked() semantics ───
+  for (const { name, doc, expect } of GATE_CASES) {
+    const actual = isMarketingRevoked(doc);
+    check(actual === expect, `isMarketingRevoked: ${name}`, `Expected ${expect}, got ${actual}`);
+  }
+
+  // ─── 2. sync() blocks a revoked doc (gate fires before validation/providers) ───
+  {
+    const { assistant, calls } = buildAssistant(null);
+    const result = await new Marketing(assistant).sync(REVOKED_DOC);
+
+    check(result.blocked === 'consent', 'sync(): blocks revoked doc', `Expected blocked='consent', got ${JSON.stringify(result)}`);
+    check(result.email === 'revoked.user@gmail.com', 'sync(): blocked result includes email', `Got ${JSON.stringify(result)}`);
+    check(calls.warns.length === 1, 'sync(): revoked skip logs a warn', `Got ${calls.warns.length} warns`);
+  }
+
+  // ─── 3. sync() proceeds on missing consent (legacy user) ───
+  {
+    const { assistant } = buildAssistant(null);
+    const result = await new Marketing(assistant).sync(LEGACY_DOC);
+
+    check(result.blocked === undefined, 'sync(): proceeds on missing consent', `Expected no block, got ${JSON.stringify(result)}`);
+  }
+
+  // ─── 4. sync() proceeds on granted consent ───
+  {
+    const { assistant } = buildAssistant(null);
+    const result = await new Marketing(assistant).sync(GRANTED_DOC);
+
+    check(result.blocked === undefined, 'sync(): proceeds on granted consent', `Expected no block, got ${JSON.stringify(result)}`);
+  }
+
+  // ─── 5. sync() by uid blocks when the fetched doc is revoked ───
+  {
+    const { admin, captured } = buildAdmin({ userDoc: REVOKED_DOC });
+    const { assistant } = buildAssistant(admin);
+    const result = await new Marketing(assistant).sync('revoked-uid');
+
+    check(result.blocked === 'consent', 'sync(uid): blocks revoked fetched doc', `Expected blocked='consent', got ${JSON.stringify(result)}`);
+    check(captured.docPaths[0] === 'users/revoked-uid', 'sync(uid): fetches users/{uid}', `Got ${JSON.stringify(captured.docPaths)}`);
+  }
+
+  // ─── 6. add() blocks when the email maps to a revoked user ───
+  {
+    const { admin, captured } = buildAdmin({ userDoc: REVOKED_DOC });
+    const { assistant, calls } = buildAssistant(admin);
+    const result = await new Marketing(assistant).add({ email: 'revoked.user@gmail.com' });
+
+    check(result.blocked === 'consent', 'add(): blocks revoked user by email', `Expected blocked='consent', got ${JSON.stringify(result)}`);
+    check(result.email === 'revoked.user@gmail.com', 'add(): blocked result includes email', `Got ${JSON.stringify(result)}`);
+    check(calls.warns.length === 1, 'add(): revoked skip logs a warn', `Got ${calls.warns.length} warns`);
+
+    const query = captured.queries[0];
+    check(
+      query
+        && query.collection === 'users'
+        && query.field === 'auth.email'
+        && query.op === '=='
+        && query.value === 'revoked.user@gmail.com',
+      'add(): looks up users by auth.email (webhook-processor query)',
+      `Got ${JSON.stringify(query)}`
+    );
+  }
+
+  // ─── 7. add() normalizes the email for the lookup ───
+  {
+    const { admin, captured } = buildAdmin({ userDoc: null });
+    const { assistant } = buildAssistant(admin);
+    await new Marketing(assistant).add({ email: '  Revoked.User@GMAIL.com  ' });
+
+    check(
+      captured.queries[0]?.value === 'revoked.user@gmail.com',
+      'add(): lookup trims + lowercases the email',
+      `Got ${JSON.stringify(captured.queries[0])}`
+    );
+  }
+
+  // ─── 8. add() proceeds when no user doc exists (pure newsletter contact) ───
+  {
+    const { admin } = buildAdmin({ userDoc: null });
+    const { assistant } = buildAssistant(admin);
+    const result = await new Marketing(assistant).add({ email: 'newsletter.reader@gmail.com' });
+
+    check(result.blocked === undefined, 'add(): proceeds when no user doc exists', `Expected no block, got ${JSON.stringify(result)}`);
+  }
+
+  // ─── 9. add() proceeds when the matched user has no consent field (legacy) ───
+  {
+    const { admin } = buildAdmin({ userDoc: LEGACY_DOC });
+    const { assistant } = buildAssistant(admin);
+    const result = await new Marketing(assistant).add({ email: 'legacy.user@gmail.com' });
+
+    check(result.blocked === undefined, 'add(): proceeds on legacy user (no consent field)', `Expected no block, got ${JSON.stringify(result)}`);
+  }
+
+  // ─── 10. add() fails open when the lookup errors ───
+  {
+    const { admin } = buildAdmin({ failLookup: true });
+    const { assistant, calls } = buildAssistant(admin);
+    const result = await new Marketing(assistant).add({ email: 'someone@gmail.com' });
+
+    check(result.blocked === undefined, 'add(): fails open on lookup error', `Expected no block, got ${JSON.stringify(result)}`);
+    check(calls.errors.length === 1, 'add(): lookup error is logged', `Got ${calls.errors.length} errors`);
+  }
+
+  console.log('');
+  console.log(`${passed} passed, ${failed} failed`);
+
+  if (failed > 0) {
+    process.exit(1);
+  }
+}
+
+run();

package/src/manager/libraries/email/marketing/index.js

@@ -20,10 +20,15 @@
  *
  * Used by:
  * - routes/marketing/contact (add)
- * - Auth on-create handler (sync on signup)
+ * - routes/user/signup (sync on signup — call site also gates on consent to skip the paid mailbox check)
  * - Payment transition handlers (sync on subscription change)
  * - Auth on-delete handler (remove contact)
  * - Campaign cron jobs (send campaigns)
+ *
+ * Consent gate: add() and sync() skip users whose consent.marketing.status is the
+ * literal string 'revoked' and return { blocked: 'consent', email }. Missing consent,
+ * null, or any other value proceeds — legacy users have no consent field and must
+ * keep syncing. remove() is always safe and stays ungated.
  */
 const _ = require('lodash');
 
@@ -52,9 +57,52 @@ function Marketing(assistant) {
 }
 
 // ============================================================
-// Contact management (add / sync / remove) — unchanged
+// Contact management (add / sync / remove)
 // ============================================================
 
+/**
+ * Consent gate — true ONLY when consent.marketing.status is the literal string 'revoked'.
+ * Missing consent, null, or any other value proceeds — legacy users have no consent field
+ * and must keep syncing.
+ *
+ * @param {object|null|undefined} userDoc - User doc data (or null/undefined when no user exists)
+ * @returns {boolean}
+ */
+function isMarketingRevoked(userDoc) {
+  return userDoc?.consent?.marketing?.status === 'revoked';
+}
+
+/**
+ * Look up a user doc by email (same query the marketing webhook processors use).
+ * Returns the doc data, or null when no user matches OR the lookup fails (fail open —
+ * a rare duplicate add is recoverable; silently dropping contacts is not).
+ *
+ * @param {object} admin - firebase-admin instance
+ * @param {object} assistant - Assistant (for logging)
+ * @param {string} email - Email address
+ * @returns {Promise<object|null>}
+ */
+async function findUserByEmail(admin, assistant, email) {
+  const snapshot = await admin.firestore().collection('users')
+    .where('auth.email', '==', email.trim().toLowerCase())
+    .limit(1)
+    .get()
+    .catch((e) => {
+      assistant.error('Marketing: User lookup by email failed (proceeding without consent gate):', e);
+      return null;
+    });
+
+  if (!snapshot || snapshot.empty) {
+    return null;
+  }
+
+  return snapshot.docs[0].data();
+}
+
+// Exposed as statics for plain-node unit tests (consent-gate.test.js)
+Marketing.isMarketingRevoked = isMarketingRevoked;
+Marketing.findUserByEmail = findUserByEmail;
+
 Marketing.prototype.add = async function (options) {
   const self = this;
   const assistant = self.assistant;
@@ -65,6 +113,16 @@ Marketing.prototype.add = async function (options) {
     return {};
   }
 
+  // Consent gate — if this email maps to a user who revoked marketing consent, never
+  // re-add them. No user doc → proceed (pure newsletter contact). Lookup failure →
+  // proceed (fail open, logged in findUserByEmail).
+  const userDoc = await findUserByEmail(self.admin, assistant, email);
+
+  if (isMarketingRevoked(userDoc)) {
+    assistant.warn(`Marketing.add(): Consent revoked, skipping: ${email}`);
+    return { blocked: 'consent', email };
+  }
+
   const validation = await validate(email);
   if (!validation.valid) {
     assistant.warn(`Marketing.add(): Validation failed, skipping: ${email}`, validation.checks);
@@ -140,6 +198,13 @@ Marketing.prototype.sync = async function (userDocOrUid) {
     return {};
   }
 
+  // Consent gate — never re-add a user who revoked marketing consent (payment-event
+  // syncs, admin re-syncs, and batch syncs all funnel through here).
+  if (isMarketingRevoked(userDoc)) {
+    assistant.warn(`Marketing.sync(): Consent revoked, skipping: ${email}`);
+    return { blocked: 'consent', email };
+  }
+
   const validation = await validate(email);
   if (!validation.valid) {
     assistant.warn(`Marketing.sync(): Validation failed, skipping: ${email}`, validation.checks);

package/src/manager/libraries/email/validation-provider-neverbounce.js

@@ -1,13 +1,36 @@
 const fetch = require('wonderful-fetch');
 
-const RESULT_MAP = {
+// NeverBounce numeric → textcode map. The v4 single/check API returns `result`
+// as a textcode STRING ('valid', 'invalid', ...); numeric codes only appear in
+// other response modes — tolerate both so a representation change can't silently
+// fail every check again (that exact bug skipped marketing sync for all signups
+// between BEM 5.5.1 and 5.6.1).
+const NUMERIC_RESULT_MAP = {
   0: 'valid',
   1: 'invalid',
   2: 'disposable',
-  3: 'catch-all',
+  3: 'catchall',
   4: 'unknown',
 };
 
+// valid, catchall, unknown are allowed; invalid, disposable are blocked
+const ALLOWED_RESULTS = new Set(['valid', 'catchall', 'unknown']);
+
+/**
+ * Normalize a NeverBounce single-check `result` into { valid, status }.
+ * Accepts textcode strings (canonical) or numeric codes; 'catch-all' → 'catchall'.
+ *
+ * @param {string|number} result - NeverBounce `result` field
+ * @returns {{ valid: boolean, status: string }}
+ */
+function parseResult(result) {
+  const status = typeof result === 'number'
+    ? (NUMERIC_RESULT_MAP[result] || 'unknown')
+    : String(result).toLowerCase().replace('-', '');
+
+  return { valid: ALLOWED_RESULTS.has(status), status };
+}
+
 /**
  * @param {string} email
  * @returns {Promise<{ valid: boolean, status?: string, subStatus?: string, error?: string, provider: string }>}
@@ -29,14 +52,10 @@ async function verify(email) {
       return { valid: true, error: 'Unexpected response format', provider: 'neverbounce' };
     }
 
-    const status = RESULT_MAP[data.result] || 'unknown';
-    // 0=valid, 3=catch-all, 4=unknown are allowed; 1=invalid, 2=disposable are blocked
-    const nbValid = data.result === 0
-      || data.result === 3
-      || data.result === 4;
+    const { valid, status } = parseResult(data.result);
 
     return {
-      valid: nbValid,
+      valid,
       status,
       subStatus: data.flags?.length ? data.flags.join(',') : null,
       provider: 'neverbounce',
@@ -47,4 +66,4 @@ async function verify(email) {
   }
 }
 
-module.exports = { verify };
+module.exports = { verify, parseResult };

package/src/manager/libraries/email/validation.js

@@ -18,7 +18,7 @@
  * Used by:
  * - routes/marketing/contact/post.js
  * - functions/core/actions/api/general/add-marketing-contact.js
- * - routes/user/signup/post.js (disposable check only)
+ * - routes/user/signup/post.js (ALL_CHECKS before marketing sync; isDisposable() for affiliate fraud prevention)
  * - libraries/email/marketing/index.js (safety net before Beehiiv/SendGrid add/sync)
  */
 const path = require('path');

package/src/manager/libraries/email/validation.test.js

@@ -1,9 +1,11 @@
 /**
  * Email validation test — verifies all free checks (format, disposable, corporate, localPart, typo, dns)
+ * plus NeverBounce result parsing (no API calls).
  *
  * Run:   node src/manager/libraries/email/validation.test.js
  */
 const { validate } = require('./validation.js');
+const { parseResult } = require('./validation-provider-neverbounce.js');
 
 const FREE_CHECKS = ['format', 'disposable', 'corporate', 'localPart', 'typo', 'dns'];
 
@@ -85,10 +87,38 @@ const CASES = [
   { email: 'someone@example.com', expect: 'fail', check: 'dns' },
 ];
 
+// NeverBounce single-check `result` parsing — the API returns STRING textcodes.
+// Regression: BEM 5.5.1–5.6.1 compared against numbers, failing every mailbox
+// check and silently skipping marketing sync for all signups.
+const NB_PARSE_CASES = [
+  { result: 'valid', expectValid: true, expectStatus: 'valid' },
+  { result: 'catchall', expectValid: true, expectStatus: 'catchall' },
+  { result: 'catch-all', expectValid: true, expectStatus: 'catchall' },
+  { result: 'unknown', expectValid: true, expectStatus: 'unknown' },
+  { result: 'invalid', expectValid: false, expectStatus: 'invalid' },
+  { result: 'disposable', expectValid: false, expectStatus: 'disposable' },
+  { result: 0, expectValid: true, expectStatus: 'valid' },
+  { result: 1, expectValid: false, expectStatus: 'invalid' },
+  { result: 2, expectValid: false, expectStatus: 'disposable' },
+  { result: 3, expectValid: true, expectStatus: 'catchall' },
+  { result: 4, expectValid: true, expectStatus: 'unknown' },
+];
+
 async function run() {
   let passed = 0;
   let failed = 0;
 
+  for (const { result, expectValid, expectStatus } of NB_PARSE_CASES) {
+    const parsed = parseResult(result);
+    if (parsed.valid === expectValid && parsed.status === expectStatus) {
+      passed++;
+    } else {
+      failed++;
+      console.log(`  ✗ parseResult(${JSON.stringify(result)})`);
+      console.log(`    Expected: valid=${expectValid} status=${expectStatus}, Got: valid=${parsed.valid} status=${parsed.status}`);
+    }
+  }
+
   for (const { email, expect: expected, check: expectedCheck } of CASES) {
     const result = await validate(email, { checks: FREE_CHECKS });
     const actualPass = result.valid;
@@ -115,7 +145,7 @@ async function run() {
   }
 
   console.log('');
-  console.log(`${passed} passed, ${failed} failed out of ${CASES.length} cases`);
+  console.log(`${passed} passed, ${failed} failed out of ${CASES.length + NB_PARSE_CASES.length} cases`);
 
   if (failed > 0) {
     process.exit(1);

package/src/manager/routes/marketing/contact/delete.js

@@ -1,6 +1,10 @@
 /**
  * DELETE /marketing/contact - Remove marketing contact
  * Admin-only endpoint to unsubscribe from newsletter
+ *
+ * Also mirrors consent.marketing.status = 'revoked' (source: 'admin') to the user doc
+ * when the email maps to a user — otherwise the next sync (payment event, admin re-sync)
+ * would re-add the contact the admin just removed.
  */
 
 module.exports = async ({ assistant, Manager, settings, analytics }) => {
@@ -28,6 +32,11 @@ module.exports = async ({ assistant, Manager, settings, analytics }) => {
   const mailer = Manager.Email(assistant);
   const providerResults = await mailer.remove(email);
 
+  // Mirror the removal to the user doc's consent so future syncs hit the email
+  // library's consent gate instead of silently re-adding the contact
+  // (best-effort, silent when the email maps to no user)
+  await mirrorRevokedConsent({ assistant, Manager, email });
+
   // Log result
   assistant.log('marketing/contact delete result:', {
     email,
@@ -42,3 +51,52 @@ module.exports = async ({ assistant, Manager, settings, analytics }) => {
     providers: providerResults,
   });
 };
+
+/**
+ * Write consent.marketing.status = 'revoked' (source: 'admin') to the user doc that
+ * matches the removed email. Same lookup + write shape as the marketing webhook
+ * processors' revoke write. Silent when no user matches.
+ */
+async function mirrorRevokedConsent({ assistant, Manager, email }) {
+  const { admin } = Manager.libraries;
+
+  const snapshot = await admin.firestore().collection('users')
+    .where('auth.email', '==', email)
+    .limit(1)
+    .get()
+    .catch((e) => {
+      assistant.error('marketing/contact delete: Failed to look up user by email:', e);
+      return null;
+    });
+
+  if (!snapshot || snapshot.empty) {
+    return; // Silent — email may not map to a current user
+  }
+
+  const uid = snapshot.docs[0].id;
+  const timestamp = assistant.meta.startTime.timestamp;
+  const timestampUNIX = assistant.meta.startTime.timestampUNIX;
+
+  // Write consent.marketing.status = 'revoked' (preserve grantedAt — informational audit trail)
+  await admin.firestore().doc(`users/${uid}`).set({
+    consent: {
+      marketing: {
+        status: 'revoked',
+        revokedAt: {
+          timestamp,
+          timestampUNIX,
+          source: 'admin',
+          ip: null,
+          text: null,
+        },
+      },
+    },
+    metadata: Manager.Metadata().set({ tag: 'marketing/contact:delete' }),
+  }, { merge: true })
+    .then(() => {
+      assistant.log(`marketing/contact delete: Mirrored revoked consent to user ${uid} (${email})`);
+    })
+    .catch((e) => {
+      assistant.error(`marketing/contact delete: Failed to mirror revoked consent to ${uid}:`, e);
+    });
+}

package/src/manager/routes/marketing/email-preferences/post.js

@@ -14,6 +14,9 @@
  *    - HMAC validates the link was generated by us.
  *    - Hits SendGrid ASM directly (legacy behavior — preserves existing one-click unsub).
  *    - Also writes canonical consent.marketing to user doc when email maps to a user.
+ *    - Then cross-syncs via the email library (best-effort): unsubscribe removes the
+ *      contact from ALL providers (Beehiiv too — compliance); subscribe re-adds the
+ *      contact (sync when the email maps to a user, add when it doesn't).
  */
 const fetch = require('wonderful-fetch');
 const crypto = require('crypto');
@@ -148,8 +151,10 @@ async function handleAnonymous({ assistant, Manager, settings, analytics }) {
   usage.increment('email-preferences');
   await usage.update();
 
-  // Mirror to the user doc if this email maps to a user (best-effort, silent on miss)
-  await mirrorAnonymousToUserDoc({ assistant, Manager, email, action });
+  // Mirror to the user doc if this email maps to a user (best-effort, silent on miss).
+  // Runs BEFORE the provider calls below — on subscribe it writes consent granted first,
+  // so the email library's consent gate passes when we re-sync.
+  const uid = await mirrorAnonymousToUserDoc({ assistant, Manager, email, action });
 
   // Call SendGrid ASM (legacy behavior)
   const shouldCallExternalAPIs = !assistant.isTesting() || process.env.TEST_EXTENDED_MODE;
@@ -184,6 +189,26 @@ async function handleAnonymous({ assistant, Manager, settings, analytics }) {
     return assistant.respond('Failed to process your request', { code: 500 });
   }
 
+  // Cross-provider sync via the email library (best-effort — ASM suppression above
+  // already succeeded). Unsubscribe must remove the contact from Beehiiv too
+  // (compliance); subscribe must actually re-add the contact: sync the matched user
+  // (the mirror above already wrote consent granted, so the library consent gate
+  // passes) or add a bare newsletter contact when no user matched.
+  const mailer = Manager.Email(assistant);
+
+  try {
+    if (action === 'unsubscribe') {
+      await mailer.remove(email);
+    } else if (uid) {
+      await mailer.sync(uid);
+    } else {
+      await mailer.add({ email, source: 'resubscribe' });
+    }
+  } catch (e) {
+    assistant.error(`email-preferences (anon) provider sync failed:`, e);
+    // Doc + ASM are already updated — provider sync is best-effort. Don't fail the request.
+  }
+
   assistant.log('email-preferences (anon) result:', { email, asmId, action });
   analytics.event('marketing/email-preferences', { action, mode: 'anonymous' });
 
@@ -194,6 +219,8 @@ async function handleAnonymous({ assistant, Manager, settings, analytics }) {
  * Anonymous HMAC unsub also writes to the user doc (if found) so consent stays in sync.
  * Silent if the email doesn't map to a user. Source is recorded as 'sendgrid' since the
  * HMAC link only fires from SendGrid email footers.
+ *
+ * @returns {Promise<string|null>} The matched user's uid, or null when no user matches.
  */
 async function mirrorAnonymousToUserDoc({ assistant, Manager, email, action }) {
   const { admin } = Manager.libraries;
@@ -208,7 +235,7 @@ async function mirrorAnonymousToUserDoc({ assistant, Manager, email, action }) {
     });
 
   if (!snapshot || snapshot.empty) {
-    return; // Silent — email may not map to a current user
+    return null; // Silent — email may not map to a current user
   }
 
   const userDoc = snapshot.docs[0];
@@ -233,4 +260,6 @@ async function mirrorAnonymousToUserDoc({ assistant, Manager, email, action }) {
     .catch((e) => {
       assistant.error(`email-preferences (anon): Failed to mirror to user doc ${uid}:`, e);
     });
+
+  return uid;
 }

package/.claude/scheduled_tasks.lock

@@ -1 +0,0 @@
-{"sessionId":"c926cd91-919f-483f-bb49-db72f77f9e2e","pid":30061,"procStart":"Thu Jun 11 11:57:09 2026","acquiredAt":1781179809978}