backend-manager 5.1.0 → 5.1.1

package/CHANGELOG.md

@@ -14,6 +14,22 @@ 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.1.1] - 2026-05-13
+
+### Added
+
+- **Corporate / social-media domain blacklist** — new `corporate` check in `email/validation.js` blocks marketing-list adds from corporate social-media domains (meta.com, instagram.com, soundcloud.com, tiktok.com, x.com, reddit.com, linkedin.com, youtube.com, discord.com, telegram.org, signal.org, and more — 21 domains total). Added to `DEFAULT_CHECKS` so every existing caller of `validate()` picks it up automatically. New `isCorporate(emailOrDomain)` helper exported alongside `isDisposable()`.
+- **Defense-in-depth guards** in `Marketing.add()` and `Marketing.sync()` — even when validation is bypassed (e.g. testing mode), corporate domains are blocked before any Beehiiv or SendGrid call.
+- **13 new tests** in `test/helpers/email-validation.js` covering the `corporate` validate-check, the `isCorporate()` helper, case-insensitivity, edge cases, and check-ordering behavior. Suite: 44 pass, 0 fail, 2 skip (ZeroBounce-only).
+
+### Changed
+
+- **Email data files reorganized** — all blacklists now live in `src/manager/libraries/email/data/` (one folder, next to their consumer), instead of being scattered one level up alongside unrelated libraries:
+  - `disposable-domains.json`, `custom-disposable-domains.json`, `corporate-domains.json` — domain blocklists
+  - `blocked-local-parts.json` — categorized local-part blocklist (`generic`, `system`, `junk`, `placeholder`), extracted from a hardcoded `Set` in `validation.js`
+  - `blocked-local-patterns.js` — regex patterns, extracted from `validation.js` (kept as JS so RegExp literals stay native)
+- **`scripts/update-disposable-domains.js`** — prepare-step downloader now writes to `email/data/disposable-domains.json`.
+
 # [5.1.0] - 2026-05-13
 
 ### Added

package/CLAUDE.md

@@ -2,24 +2,100 @@
 
 > **Note for contributors and Claude:** This file is the architectural overview — identity, top-level conventions, and a map to deep references. The **meat** (per-subsystem APIs, behavior tables, recipes) lives in `docs/<topic>.md`. When extending or adding content, write it in the matching `docs/*.md` file and cross-link from here — do NOT inline it. If a topic doesn't have a doc yet, create one. Goal: keep this file under 250 lines.
 
-## Project Identity
+## Identity
 
-**Backend Manager (BEM)** is an NPM package that provides powerful backend features for Firebase Cloud Functions projects, including authentication, rate limiting, analytics, and more.
+Backend Manager (BEM) is a comprehensive framework for building modern Firebase Cloud Functions backends. Sister project to Electron Manager (EM), Browser Extension Manager (BXM), and Ultimate Jekyll Manager (UJM). Provides a single `Manager.init(exports, {...})` bootstrap that wires built-in functions (`bm_api`, auth events, cron jobs), helper classes (Assistant, User, Analytics, Usage, Middleware, Settings, Utilities, Metadata), payment processor integrations (Stripe / PayPal), Firestore-trigger pipelines, marketing campaign automation, an MCP server, and a CLI for emulator/deploy/logs/auth/Firestore operations.
 
-**This repository** (`backend-manager`) is the BEM library itself. If you're working here, you're contributing to the library, not consuming it.
+**This repository** is the BEM library itself. **Consumer projects** are Firebase projects that `require('backend-manager')` in their `functions/index.js`, with `backend-manager-config.json` + `service-account.json` alongside, plus optional `routes/`, `schemas/`, and `hooks/` directories for custom endpoints.
 
-**Consumer projects** are Firebase projects that `require('backend-manager')` in their `functions/index.js`. These have:
-- `functions/` directory with `index.js` that calls `Manager.init(exports, {...})`
-- `backend-manager-config.json` configuration file
-- `service-account.json` for Firebase credentials
-- Optional `routes/` and `schemas/` directories for custom endpoints
+## Recommended skills
 
-## Architecture (at a glance)
+Two Claude Code skills are tailored to this project. Both auto-trigger on relevant keywords and can be invoked manually with `/<skill-name>`:
+
+- **`BEM:patterns`** — SSOT for Backend Manager routes, schemas, tests, Firebase functions, Firestore rules, usage tracking patterns. Auto-loads on BEM-specific keywords (`route`, `schema`, `endpoint`, `bm_api`, `Manager.init`, `npx mgr test`, `gcloud logs`, etc.) and when touching files in `functions/routes/`, `functions/schemas/`, `functions/index.js`, `test/`, `src/cli/commands/`.
+- **`js:patterns`** — JavaScript/Node.js conventions: file structure, JSDoc, defensive coding (`?.` usage), template literals, `package.json` conventions. Auto-loads when creating new `.js` files or touching JS module structure.
+
+## Quick Start
+
+### For Consuming Projects
+
+1. `npm install backend-manager --save-dev` (inside `functions/`)
+2. `npx mgr setup` — validates config, scaffolds defaults (CLAUDE.md, CHANGELOG.md, docs/, test/), provisions Firestore indexes
+3. `npx mgr emulator` — start Firebase emulators (auth/firestore/functions/database/storage)
+4. `npx mgr serve` — local serve with Stripe webhook forwarding (if `STRIPE_SECRET_KEY` is set)
+5. `npx mgr test` — runs framework + project test suites against an emulator
+6. `npx mgr deploy` — deploy Cloud Functions to Firebase
+7. `npx mgr logs:read` / `npx mgr logs:tail` — Cloud Function logs from Google Cloud Logging
+
+All `npx mgr <cmd>` aliases work: `npx bm <cmd>`, `npx bem <cmd>`, `npx backend-manager <cmd>`.
+
+> **Important:** All `npx mgr ...` commands MUST be run from the consumer project's `functions/` subdirectory. The binary lives in `functions/node_modules/.bin/`.
+
+### For Framework Development (This Repository)
+
+1. `npm install` — install BEM's own deps
+2. `npm run prepare` — build once: copies `src/` → `dist/` via prepare-package
+3. `npm run prepare:watch` — watch mode
+4. Test in a consumer project: from inside the consumer's `functions/` dir, run `npx mgr install local` (swaps BEM to the local repo via the `install` CLI). Reverse with `npx mgr install prod`.
+
+## Architecture
 
 BEM exposes a single `Manager` class that orchestrates everything: it initializes Firebase Admin, wires built-in functions (`bm_api`, auth events, cron), and hands out helper instances via factory methods. Supports **two deployment modes** — Firebase Functions (`projectType: 'firebase'`) or Custom Server (`projectType: 'custom'`). See [docs/architecture.md](docs/architecture.md) for the full overview of the Manager class, dual-mode support, and helper factory pattern.
 
 For the directory layout of both the BEM library and consumer projects, see [docs/directory-structure.md](docs/directory-structure.md).
 
+## CLI
+
+`npx mgr <command>` (aliases `bm`, `bem`, `backend-manager`):
+
+| Command | Description |
+|---|---|
+| `setup` | Validate config, scaffold defaults (CLAUDE.md, CHANGELOG.md, docs/, test/), provision Firestore indexes |
+| `emulator` | Start Firebase emulators (auth/firestore/functions/database/storage) |
+| `serve` | Local Firebase serve (with auto Stripe webhook forwarding if keys set) |
+| `watch` | Auto-reload functions on file change |
+| `deploy` | Deploy Cloud Functions to Firebase |
+| `test` | Run framework + project test suites against an emulator |
+| `mcp` | Start the stdio MCP server (for Claude Code / Claude Desktop) |
+| `firestore:get/set/query/delete` | Direct Firestore reads/writes from the terminal |
+| `auth:get/list/delete/set-claims` | Manage Auth users from the terminal |
+| `logs:read` / `logs:tail` | Cloud Function logs from Google Cloud Logging |
+| `stripe` | Standalone Stripe CLI webhook forwarding |
+| `indexes` | Sync required Firestore indexes into `firestore.indexes.json` |
+| `firebase-init` | Run Firebase Admin SDK initialization helper |
+| `clean` | Remove generated artifacts (logs, test outputs) |
+| `version` | Print BEM version |
+
+See [docs/cli-firestore-auth.md](docs/cli-firestore-auth.md) and [docs/cli-logs.md](docs/cli-logs.md) for full flag references.
+
+## File Conventions
+
+- **CommonJS** throughout. `prepare-package` copies `src/` → `dist/` 1:1 (no transforms).
+- **`fs-jetpack`** over `fs` / `fs-extra` for file operations.
+- One `module.exports = ...` per file.
+- **Short-circuit early returns** rather than nested ifs.
+- **Logical operators at the start of continuation lines** (`|| condB` on a new line, not `condA ||` trailing).
+- **Firestore shorthand**: `admin.firestore().doc('users/abc123')` (path string) rather than `.collection('users').doc('abc123')`.
+- **Template strings for requires**: `` require(`${functionsDir}/node_modules/backend-manager`) `` rather than string concat.
+- **No backwards compatibility** unless explicitly requested.
+- **Routes receive sanitized data by default** — see [docs/sanitization.md](docs/sanitization.md) for opt-out rules.
+- **Match schema names to route names** — if route is `myEndpoint`, schema is `myEndpoint`.
+- **Always use `assistant.respond()` for responses** — do NOT use `res.send()` directly.
+- **Add Firestore composite indexes** for any compound query (`where` + `orderBy`, or multiple `where`s) to `src/cli/commands/setup-tests/helpers/required-indexes.js` (the SSOT). Without the index, queries crash with `FAILED_PRECONDITION` in production.
+
+See [docs/code-patterns.md](docs/code-patterns.md) for code-pattern detail, [docs/common-mistakes.md](docs/common-mistakes.md) for the full anti-pattern checklist, and [docs/file-naming.md](docs/file-naming.md) for the naming table (routes / schemas / API commands / events / cron jobs / hooks).
+
+## Doc-update parity
+
+Whenever you make a behavioral change (new command, new flag, new pattern, removed feature), update:
+
+1. **`README.md`** — user-facing summary
+2. **`CLAUDE.md`** (this file) — architecture overview, one paragraph or cross-link
+3. **`docs/<topic>.md`** — the meat. If a topic doesn't have a doc yet, create one.
+4. **`CHANGELOG.md`** — if the project keeps one
+
+Don't ship behavioral changes with stale docs. Validate first, then document — write docs that describe shipped reality, not intentions.
+
 ## Documentation
 
 Deep references live in `docs/`. **Whenever you make a behavioral change, update both this overview AND the relevant `docs/*.md` deep reference.**
@@ -30,6 +106,8 @@ Deep references live in `docs/`. **Whenever you make a behavioral change, update
 - [docs/directory-structure.md](docs/directory-structure.md) — BEM library + consumer project layouts
 - [docs/code-patterns.md](docs/code-patterns.md) — short-circuit returns, logical operators on new lines, Firestore shorthand, template-string requires, fs-jetpack preference
 - [docs/file-naming.md](docs/file-naming.md) — naming table for routes, schemas, API commands, events, cron jobs, hooks
+- [docs/common-mistakes.md](docs/common-mistakes.md) — anti-pattern checklist (don't modify Manager internals, always await, increment-before-update, etc.)
+- [docs/key-files.md](docs/key-files.md) — quick lookup for the most-touched files (Manager, helpers, auth events, cron, payment processors, CLI commands)
 - [docs/environment-detection.md](docs/environment-detection.md) — `assistant.isDevelopment/isProduction/isTesting()`
 - [docs/response-headers.md](docs/response-headers.md) — automatic `bm-properties` header
 
@@ -60,52 +138,3 @@ Deep references live in `docs/`. **Whenever you make a behavioral change, update
 - [docs/testing.md](docs/testing.md) — running, filtering, log files, test types (standalone/suite/group), context object, assertions, auth levels
 - [docs/cli-firestore-auth.md](docs/cli-firestore-auth.md) — `npx mgr firestore:*` and `auth:*` commands, shared flags, examples
 - [docs/cli-logs.md](docs/cli-logs.md) — `npx mgr logs:read` / `logs:tail` with full flag reference and built-in Cloud Function names
-
-## Common Mistakes to Avoid
-
-1. **Don't modify Manager internals directly** — Use factory methods and public APIs
-2. **Always use `assistant.respond()` for responses** — Don't use `res.send()` directly
-3. **Match schema names to route names** — If route is `myEndpoint`, schema should be `myEndpoint`
-4. **Always await async operations** — Don't forget `await` on Firestore operations
-5. **Handle errors properly** — Use `assistant.errorify()` with appropriate status codes
-6. **Don't call `respond()` multiple times** — Only one response per request
-7. **Use short-circuit returns** — Return early from error conditions
-8. **Increment usage before update** — Call `usage.increment()` then `usage.update()`
-9. **Add Firestore composite indexes for new compound queries** — Any new Firestore query using multiple `.where()` clauses or `.where()` + `.orderBy()` requires a composite index. Add it to `src/cli/commands/setup-tests/helpers/required-indexes.js` (the SSOT). Consumer projects pick these up via `npx mgr setup`, which syncs them into `firestore.indexes.json`. Without the index, the query will crash with `FAILED_PRECONDITION` in production.
-
-## Key Files Reference
-
-| Purpose | File |
-|---------|------|
-| Main Manager class | `src/manager/index.js` |
-| Request/response handling | `src/manager/helpers/assistant.js` |
-| Middleware pipeline | `src/manager/helpers/middleware.js` |
-| Schema validation | `src/manager/helpers/settings.js` |
-| Rate limiting | `src/manager/helpers/usage.js` |
-| User properties + schema | `src/manager/helpers/user.js` |
-| Batch utilities | `src/manager/helpers/utilities.js` |
-| Auth: before-create | `src/manager/events/auth/before-create.js` |
-| Auth: before-signin | `src/manager/events/auth/before-signin.js` |
-| Auth: on-create | `src/manager/events/auth/on-create.js` |
-| Auth: on-delete | `src/manager/events/auth/on-delete.js` |
-| Auth: shared utilities | `src/manager/events/auth/utils.js` |
-| Cron runner | `src/manager/events/cron/runner.js` |
-| Main API handler | `src/manager/functions/core/actions/api.js` |
-| Config template | `templates/backend-manager-config.json` |
-| CLI entry | `src/cli/index.js` |
-| Stripe webhook forwarding | `src/cli/commands/stripe.js` |
-| Firebase init helper (CLI) | `src/cli/commands/firebase-init.js` |
-| Firestore CLI commands | `src/cli/commands/firestore.js` |
-| Auth CLI commands | `src/cli/commands/auth.js` |
-| Logs CLI commands | `src/cli/commands/logs.js` |
-| Intent creation | `src/manager/routes/payments/intent/post.js` |
-| Webhook ingestion | `src/manager/routes/payments/webhook/post.js` |
-| Webhook processing (on-write) | `src/manager/events/firestore/payments-webhooks/on-write.js` |
-| Payment analytics | `src/manager/events/firestore/payments-webhooks/analytics.js` |
-| Transition detection | `src/manager/events/firestore/payments-webhooks/transitions/index.js` |
-| Payment processor libraries | `src/manager/libraries/payment/processors/` |
-| Stripe library | `src/manager/libraries/payment/processors/stripe.js` |
-| PayPal library | `src/manager/libraries/payment/processors/paypal.js` |
-| Order ID generator | `src/manager/libraries/payment/order-id.js` |
-| Required Firestore indexes (SSOT) | `src/cli/commands/setup-tests/helpers/required-indexes.js` |
-| Test accounts | `src/test/test-accounts.js` |

package/docs/common-mistakes.md

@@ -0,0 +1,11 @@
+# Common Mistakes to Avoid
+
+1. **Don't modify Manager internals directly** — Use factory methods and public APIs
+2. **Always use `assistant.respond()` for responses** — Don't use `res.send()` directly
+3. **Match schema names to route names** — If route is `myEndpoint`, schema should be `myEndpoint`
+4. **Always await async operations** — Don't forget `await` on Firestore operations
+5. **Handle errors properly** — Use `assistant.errorify()` with appropriate status codes
+6. **Don't call `respond()` multiple times** — Only one response per request
+7. **Use short-circuit returns** — Return early from error conditions
+8. **Increment usage before update** — Call `usage.increment()` then `usage.update()`
+9. **Add Firestore composite indexes for new compound queries** — Any new Firestore query using multiple `.where()` clauses or `.where()` + `.orderBy()` requires a composite index. Add it to `src/cli/commands/setup-tests/helpers/required-indexes.js` (the SSOT). Consumer projects pick these up via `npx mgr setup`, which syncs them into `firestore.indexes.json`. Without the index, the query will crash with `FAILED_PRECONDITION` in production.

package/docs/key-files.md

@@ -0,0 +1,36 @@
+# Key Files Reference
+
+| Purpose | File |
+|---------|------|
+| Main Manager class | `src/manager/index.js` |
+| Request/response handling | `src/manager/helpers/assistant.js` |
+| Middleware pipeline | `src/manager/helpers/middleware.js` |
+| Schema validation | `src/manager/helpers/settings.js` |
+| Rate limiting | `src/manager/helpers/usage.js` |
+| User properties + schema | `src/manager/helpers/user.js` |
+| Batch utilities | `src/manager/helpers/utilities.js` |
+| Auth: before-create | `src/manager/events/auth/before-create.js` |
+| Auth: before-signin | `src/manager/events/auth/before-signin.js` |
+| Auth: on-create | `src/manager/events/auth/on-create.js` |
+| Auth: on-delete | `src/manager/events/auth/on-delete.js` |
+| Auth: shared utilities | `src/manager/events/auth/utils.js` |
+| Cron runner | `src/manager/events/cron/runner.js` |
+| Main API handler | `src/manager/functions/core/actions/api.js` |
+| Config template | `templates/backend-manager-config.json` |
+| CLI entry | `src/cli/index.js` |
+| Stripe webhook forwarding | `src/cli/commands/stripe.js` |
+| Firebase init helper (CLI) | `src/cli/commands/firebase-init.js` |
+| Firestore CLI commands | `src/cli/commands/firestore.js` |
+| Auth CLI commands | `src/cli/commands/auth.js` |
+| Logs CLI commands | `src/cli/commands/logs.js` |
+| Intent creation | `src/manager/routes/payments/intent/post.js` |
+| Webhook ingestion | `src/manager/routes/payments/webhook/post.js` |
+| Webhook processing (on-write) | `src/manager/events/firestore/payments-webhooks/on-write.js` |
+| Payment analytics | `src/manager/events/firestore/payments-webhooks/analytics.js` |
+| Transition detection | `src/manager/events/firestore/payments-webhooks/transitions/index.js` |
+| Payment processor libraries | `src/manager/libraries/payment/processors/` |
+| Stripe library | `src/manager/libraries/payment/processors/stripe.js` |
+| PayPal library | `src/manager/libraries/payment/processors/paypal.js` |
+| Order ID generator | `src/manager/libraries/payment/order-id.js` |
+| Required Firestore indexes (SSOT) | `src/cli/commands/setup-tests/helpers/required-indexes.js` |
+| Test accounts | `src/test/test-accounts.js` |

package/package.json

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

package/scripts/update-disposable-domains.js

@@ -13,7 +13,7 @@ const fs = require('fs');
 const path = require('path');
 
 const SOURCE_URL = 'https://raw.githubusercontent.com/disposable-email-domains/disposable-email-domains/main/disposable_email_blocklist.conf';
-const OUTPUT_PATH = path.join(__dirname, '..', 'src', 'manager', 'libraries', 'disposable-domains.json');
+const OUTPUT_PATH = path.join(__dirname, '..', 'src', 'manager', 'libraries', 'email', 'data', 'disposable-domains.json');
 
 async function main() {
   console.log('Fetching disposable domain list...');

package/src/manager/functions/core/actions/api/general/add-marketing-contact.js

@@ -89,6 +89,11 @@ Module.prototype.main = function () {
           return reject(assistant.errorify(`Disposable email domain not allowed: ${disposable.domain}`, { code: 400 }));
         }
 
+        const corporate = validation.checks.corporate;
+        if (corporate && !corporate.valid) {
+          return reject(assistant.errorify(`Corporate/social-media domain not allowed: ${corporate.domain}`, { code: 400 }));
+        }
+
         return reject(assistant.errorify('Email validation failed', { code: 400 }));
       }
     }

package/src/manager/libraries/email/data/blocked-local-parts.json

@@ -0,0 +1,55 @@
+{
+  "generic": [
+    "test",
+    "testing",
+    "tester",
+    "test1",
+    "test123",
+    "example",
+    "sample",
+    "demo",
+    "dummy",
+    "fake",
+    "temp"
+  ],
+  "system": [
+    "noreply",
+    "no-reply",
+    "donotreply",
+    "do-not-reply",
+    "mailer-daemon",
+    "postmaster",
+    "webmaster",
+    "hostmaster",
+    "abuse",
+    "spam",
+    "root"
+  ],
+  "junk": [
+    "asdf",
+    "qwerty",
+    "zxcv",
+    "asd",
+    "qwe",
+    "aaa",
+    "bbb",
+    "xxx",
+    "zzz",
+    "abc",
+    "abc123",
+    "abcdef"
+  ],
+  "placeholder": [
+    "name",
+    "firstname",
+    "lastname",
+    "foo",
+    "bar",
+    "baz",
+    "foobar",
+    "null",
+    "undefined",
+    "none",
+    "anonymous"
+  ]
+}

package/src/manager/libraries/email/data/blocked-local-patterns.js

@@ -0,0 +1,11 @@
+/**
+ * Regex patterns that indicate junk local parts (checked after stripping +suffix).
+ * Kept as JS (not JSON) so patterns stay as native RegExp literals.
+ */
+module.exports = [
+  /^\d+$/,           // All numeric: 123456
+  /^(.)\1{2,}$/,     // Repeating single char: aaaa, xxxx
+  /^[a-z]{1,2}\d+$/, // Single letter + numbers: a123, x999
+  /^test[._-]/,      // Starts with test separator: test.user, test_123
+  /^example[._-]/,   // Starts with example separator: example.user, example_123
+];

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

@@ -0,0 +1,23 @@
+[
+  "meta.com",
+  "fb.com",
+  "facebook.com",
+  "instagram.com",
+  "whatsapp.com",
+  "threads.net",
+  "twitter.com",
+  "x.com",
+  "tiktok.com",
+  "bytedance.com",
+  "snap.com",
+  "snapchat.com",
+  "pinterest.com",
+  "reddit.com",
+  "linkedin.com",
+  "soundcloud.com",
+  "youtube.com",
+  "twitch.tv",
+  "discord.com",
+  "telegram.org",
+  "signal.org"
+]

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

@@ -5268,6 +5268,7 @@
   "xepa.ru",
   "xfavaj.com",
   "xidealx.com",
+  "xikemail.com",
   "ximenor.site",
   "xjoi.com",
   "xkx.me",

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

@@ -29,6 +29,7 @@ const md = new MarkdownIt({ html: true, breaks: true, linkify: true });
 
 const { TEMPLATES, GROUPS, SENDERS } = require('../constants.js');
 const { tagLinks } = require('../utm.js');
+const { isCorporate } = require('../validation.js');
 const sendgridProvider = require('../providers/sendgrid.js');
 const beehiivProvider = require('../providers/beehiiv.js');
 
@@ -72,6 +73,11 @@ Marketing.prototype.add = async function (options) {
     return {};
   }
 
+  if (isCorporate(email)) {
+    assistant.warn(`Marketing.add(): Blocked corporate/social-media domain, skipping: ${email}`);
+    return { blocked: 'corporate', email };
+  }
+
   if (assistant.isTesting() && !process.env.TEST_EXTENDED_MODE) {
     assistant.log('Marketing.add(): Skipping providers (testing mode)');
     return {};
@@ -151,6 +157,11 @@ Marketing.prototype.sync = async function (userDocOrUid) {
     return {};
   }
 
+  if (isCorporate(email)) {
+    assistant.warn(`Marketing.sync(): Blocked corporate/social-media domain, skipping: ${email}`);
+    return { blocked: 'corporate', email };
+  }
+
   if (assistant.isTesting() && !process.env.TEST_EXTENDED_MODE) {
     assistant.log('Marketing.sync(): Skipping providers (testing mode)');
     return {};

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

@@ -4,11 +4,12 @@
  * Available checks (run in this order):
  * - format     — basic email regex
  * - disposable — checks against known disposable domain list
+ * - corporate  — blocks corporate/social-media domains (meta.com, instagram.com, soundcloud.com, etc.)
  * - localPart  — blocks spam/junk local parts (test, noreply, all-numeric, etc.)
  * - mailbox  — verifies mailbox exists via API (costs money, requires ZEROBOUNCE_API_KEY)
  *
  * Usage:
- *   validate(email)                                          // All free checks (format + disposable + localPart)
+ *   validate(email)                                          // All free checks (format + disposable + corporate + localPart)
  *   validate(email, { checks: ['format', 'disposable'] })    // Only format + disposable
  *   validate(email, { checks: ALL_CHECKS })                  // Everything including mailbox
  *
@@ -16,57 +17,41 @@
  * - routes/marketing/contact/post.js
  * - functions/core/actions/api/general/add-marketing-contact.js
  * - routes/user/signup/post.js (disposable check only)
+ * - libraries/email/marketing/index.js (safety net before Beehiiv/SendGrid add/sync)
  */
 const fetch = require('wonderful-fetch');
 const path = require('path');
 
+// All data lives in ./data/ — domains and local-part blocklists are co-located JSON files.
+const DATA_DIR = path.join(__dirname, 'data');
+
 // Load disposable domains: curated vendor list + custom additions
-const DISPOSABLE_DOMAINS = require(path.join(__dirname, '..', 'disposable-domains.json'));
-const CUSTOM_DISPOSABLE_DOMAINS = require(path.join(__dirname, '..', 'custom-disposable-domains.json'));
+const DISPOSABLE_DOMAINS = require(path.join(DATA_DIR, 'disposable-domains.json'));
+const CUSTOM_DISPOSABLE_DOMAINS = require(path.join(DATA_DIR, 'custom-disposable-domains.json'));
 const DISPOSABLE_SET = new Set([
   ...DISPOSABLE_DOMAINS.map(d => d.toLowerCase()),
   ...CUSTOM_DISPOSABLE_DOMAINS.map(d => d.toLowerCase()),
 ]);
 
-// Spam/junk local parts — exact matches (checked after stripping +suffix)
-const BLOCKED_LOCAL_PARTS = new Set([
-  // Generic/test
-  'test', 'testing', 'tester', 'test1', 'test123',
-  'example', 'sample', 'demo', 'dummy', 'fake', 'temp',
-  // System/role addresses
-  'noreply', 'no-reply', 'donotreply', 'do-not-reply',
-  'mailer-daemon', 'postmaster', 'webmaster', 'hostmaster',
-  'abuse', 'spam', 'root',
-  // Keyboard walks / junk
-  'asdf', 'qwerty', 'zxcv', 'asd', 'qwe',
-  'aaa', 'bbb', 'xxx', 'zzz',
-  'abc', 'abc123', 'abcdef',
-  // Team
-  // 'user', 'email', 'mail', 'hello', 'info',
-  // 'admin', 'administrator', 'support',
-  // 'contact',
-  // Placeholder
-  'name', 'firstname', 'lastname',
-  'foo', 'bar', 'baz', 'foobar',
-  'null', 'undefined', 'none', 'anonymous',
-]);
+// Load corporate/social-media domains — real mailboxes we never want on marketing lists
+const CORPORATE_DOMAINS = require(path.join(DATA_DIR, 'corporate-domains.json'));
+const CORPORATE_SET = new Set(CORPORATE_DOMAINS.map(d => d.toLowerCase()));
 
-// Patterns that indicate junk local parts (checked after stripping +suffix)
-const BLOCKED_LOCAL_PATTERNS = [
-  /^\d+$/,           // All numeric: 123456
-  /^(.)\1{2,}$/,     // Repeating single char: aaaa, xxxx
-  /^[a-z]{1,2}\d+$/, // Single letter + numbers: a123, x999
-  /^test[._-]/,      // Starts with test separator: test.user, test_123
-];
+// Load local-part blocklists from ./data/ (JSON for strings, JS for regex patterns)
+const BLOCKED_LOCAL_PARTS_DATA = require(path.join(DATA_DIR, 'blocked-local-parts.json'));
+const BLOCKED_LOCAL_PARTS = new Set(
+  Object.values(BLOCKED_LOCAL_PARTS_DATA).flat().map(p => p.toLowerCase())
+);
+const BLOCKED_LOCAL_PATTERNS = require(path.join(DATA_DIR, 'blocked-local-patterns.js'));
 
 // Format regex
 const EMAIL_FORMAT = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 
 // Default checks (all free checks — mailbox excluded because it costs money)
-const DEFAULT_CHECKS = ['format', 'disposable', 'localPart'];
+const DEFAULT_CHECKS = ['format', 'disposable', 'corporate', 'localPart'];
 
 // All available checks
-const ALL_CHECKS = ['format', 'disposable', 'localPart', 'mailbox'];
+const ALL_CHECKS = ['format', 'disposable', 'corporate', 'localPart', 'mailbox'];
 
 /**
  * Validate an email address through selected checks.
@@ -76,7 +61,7 @@ const ALL_CHECKS = ['format', 'disposable', 'localPart', 'mailbox'];
  * @param {string} email
  * @param {object} [options]
  * @param {Array<string>} [options.checks] - Which checks to run (default: DEFAULT_CHECKS)
- * @returns {{ valid: boolean, checks: { format?: object, disposable?: object, localPart?: object, mailbox?: object } }}
+ * @returns {{ valid: boolean, checks: { format?: object, disposable?: object, corporate?: object, localPart?: object, mailbox?: object } }}
  */
 async function validate(email, options = {}) {
   const checks = new Set(options.checks || DEFAULT_CHECKS);
@@ -106,7 +91,18 @@ async function validate(email, options = {}) {
     result.checks.disposable = { valid: true, blocked: false };
   }
 
-  // 3. Local part — strip +suffix before checking
+  // 3. Corporate / social-media domain (real mailbox, but never wanted on marketing lists)
+  if (checks.has('corporate') && domain) {
+    if (CORPORATE_SET.has(domain)) {
+      result.valid = false;
+      result.checks.corporate = { valid: false, blocked: true, domain, reason: 'Corporate/social-media domain' };
+      return result;
+    }
+
+    result.checks.corporate = { valid: true, blocked: false };
+  }
+
+  // 4. Local part — strip +suffix before checking
   if (checks.has('localPart') && rawLocalPart) {
     const localPart = rawLocalPart.split('+')[0];
 
@@ -127,7 +123,7 @@ async function validate(email, options = {}) {
     result.checks.localPart = { valid: true };
   }
 
-  // 4. Mailbox verification (ZeroBounce)
+  // 5. Mailbox verification (ZeroBounce)
   if (checks.has('mailbox')) {
     if (!process.env.ZEROBOUNCE_API_KEY) {
       result.checks.mailbox = { valid: true, skipped: true, reason: 'No API key' };
@@ -190,4 +186,23 @@ function isDisposable(emailOrDomain) {
   return DISPOSABLE_SET.has(domain.toLowerCase());
 }
 
-module.exports = { validate, isDisposable, DEFAULT_CHECKS, ALL_CHECKS };
+/**
+ * Quick check: is this email from a blocked corporate/social-media domain?
+ * Works with a full email address or just a domain.
+ *
+ * @param {string} emailOrDomain
+ * @returns {boolean}
+ */
+function isCorporate(emailOrDomain) {
+  if (!emailOrDomain) {
+    return false;
+  }
+
+  const domain = emailOrDomain.includes('@')
+    ? emailOrDomain.split('@')[1]
+    : emailOrDomain;
+
+  return CORPORATE_SET.has(domain.toLowerCase());
+}
+
+module.exports = { validate, isDisposable, isCorporate, DEFAULT_CHECKS, ALL_CHECKS };

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

@@ -41,7 +41,7 @@ module.exports = async ({ assistant, Manager, settings, analytics }) => {
       return assistant.respond({ success: true });
     }
 
-    const { format, localPart, disposable } = validation.checks;
+    const { format, localPart, disposable, corporate } = validation.checks;
 
     if (format && !format.valid) {
       return assistant.respond('Invalid email format', { code: 400 });
@@ -55,6 +55,10 @@ module.exports = async ({ assistant, Manager, settings, analytics }) => {
       return assistant.respond(`Disposable email domain not allowed: ${disposable.domain}`, { code: 400 });
     }
 
+    if (corporate && !corporate.valid) {
+      return assistant.respond(`Corporate/social-media domain not allowed: ${corporate.domain}`, { code: 400 });
+    }
+
     return assistant.respond('Email validation failed', { code: 400 });
   }
 

package/test/helpers/email-validation.js

@@ -5,7 +5,7 @@
  * Format, local part, and disposable tests always run (free, regex-based).
  * Mailbox verification tests require TEST_EXTENDED_MODE + ZEROBOUNCE_API_KEY.
  */
-const { validate, isDisposable, DEFAULT_CHECKS, ALL_CHECKS } = require('../../src/manager/libraries/email/validation.js');
+const { validate, isDisposable, isCorporate, DEFAULT_CHECKS, ALL_CHECKS } = require('../../src/manager/libraries/email/validation.js');
 
 module.exports = {
   description: 'Email validation',
@@ -287,6 +287,144 @@ module.exports = {
       },
     },
 
+    // --- Corporate / social-media domain checks ---
+
+    {
+      name: 'corporate-meta-blocked',
+      timeout: 5000,
+
+      async run({ assert }) {
+        const result = await validate('ian@meta.com');
+
+        assert.equal(result.valid, false, 'meta.com should be blocked');
+        assert.propertyEquals(result, 'checks.corporate.blocked', true, 'Should be flagged as blocked');
+        assert.propertyEquals(result, 'checks.corporate.domain', 'meta.com', 'Should include blocked domain');
+        assert.propertyEquals(result, 'checks.corporate.reason', 'Corporate/social-media domain', 'Should have human-readable reason');
+      },
+    },
+
+    {
+      name: 'corporate-instagram-blocked',
+      timeout: 5000,
+
+      async run({ assert }) {
+        const result = await validate('rachel.greene@instagram.com');
+
+        assert.equal(result.valid, false, 'instagram.com should be blocked');
+        assert.propertyEquals(result, 'checks.corporate.blocked', true, 'Should be flagged as blocked');
+      },
+    },
+
+    {
+      name: 'corporate-soundcloud-blocked',
+      timeout: 5000,
+
+      async run({ assert }) {
+        const result = await validate('user@soundcloud.com');
+
+        assert.equal(result.valid, false, 'soundcloud.com should be blocked');
+        assert.propertyEquals(result, 'checks.corporate.blocked', true, 'Should be flagged as blocked');
+      },
+    },
+
+    {
+      name: 'corporate-gmail-allowed',
+      timeout: 5000,
+
+      async run({ assert }) {
+        const result = await validate('rachel.greene@gmail.com');
+
+        assert.equal(result.valid, true, 'gmail.com should NOT be flagged as corporate');
+        assert.propertyEquals(result, 'checks.corporate.valid', true, 'Corporate check should pass');
+        assert.propertyEquals(result, 'checks.corporate.blocked', false, 'Should not be blocked');
+      },
+    },
+
+    {
+      name: 'corporate-runs-before-localpart',
+      timeout: 5000,
+
+      async run({ assert }) {
+        // "test@meta.com" would be blocked by BOTH corporate and localPart;
+        // corporate runs first, so we should see corporate (not localPart) in the result.
+        const result = await validate('test@meta.com');
+
+        assert.equal(result.valid, false, 'Should be blocked');
+        assert.propertyEquals(result, 'checks.corporate.blocked', true, 'Corporate should be the failure reason');
+        assert.equal(result.checks.localPart, undefined, 'localPart should not run after corporate fails');
+      },
+    },
+
+    {
+      name: 'corporate-can-be-skipped-via-checks-option',
+      timeout: 5000,
+
+      async run({ assert }) {
+        // Allow a caller to bypass the corporate check (e.g., during signup, where Meta employees are real users)
+        const result = await validate('ian@meta.com', { checks: ['format', 'disposable', 'localPart'] });
+
+        assert.equal(result.valid, true, 'Without corporate check, meta.com should pass');
+        assert.equal(result.checks.corporate, undefined, 'corporate should not run');
+      },
+    },
+
+    // --- isCorporate helper ---
+
+    {
+      name: 'isCorporate-social-domain-detected',
+      timeout: 5000,
+
+      async run({ assert }) {
+        assert.equal(isCorporate('user@meta.com'), true, 'meta.com should be corporate');
+        assert.equal(isCorporate('user@instagram.com'), true, 'instagram.com should be corporate');
+        assert.equal(isCorporate('user@soundcloud.com'), true, 'soundcloud.com should be corporate');
+        assert.equal(isCorporate('user@tiktok.com'), true, 'tiktok.com should be corporate');
+        assert.equal(isCorporate('user@linkedin.com'), true, 'linkedin.com should be corporate');
+      },
+    },
+
+    {
+      name: 'isCorporate-legitimate-domain-passes',
+      timeout: 5000,
+
+      async run({ assert }) {
+        assert.equal(isCorporate('user@gmail.com'), false, 'gmail.com should not be corporate');
+        assert.equal(isCorporate('user@somiibo.com'), false, 'Custom domain should not be corporate');
+        assert.equal(isCorporate('user@mailinator.com'), false, 'Disposable is a separate category');
+      },
+    },
+
+    {
+      name: 'isCorporate-accepts-domain-only',
+      timeout: 5000,
+
+      async run({ assert }) {
+        assert.equal(isCorporate('meta.com'), true, 'Should work with bare domain');
+        assert.equal(isCorporate('gmail.com'), false, 'Should work with bare domain');
+      },
+    },
+
+    {
+      name: 'isCorporate-handles-edge-cases',
+      timeout: 5000,
+
+      async run({ assert }) {
+        assert.equal(isCorporate(''), false, 'Empty string should return false');
+        assert.equal(isCorporate(null), false, 'Null should return false');
+        assert.equal(isCorporate(undefined), false, 'Undefined should return false');
+      },
+    },
+
+    {
+      name: 'isCorporate-case-insensitive',
+      timeout: 5000,
+
+      async run({ assert }) {
+        assert.equal(isCorporate('user@META.COM'), true, 'Should be case-insensitive');
+        assert.equal(isCorporate('USER@Instagram.Com'), true, 'Should be case-insensitive');
+      },
+    },
+
     // --- isDisposable helper ---
 
     {
@@ -389,8 +527,8 @@ module.exports = {
       timeout: 5000,
 
       async run({ assert }) {
-        assert.deepEqual(DEFAULT_CHECKS, ['format', 'disposable', 'localPart'], 'DEFAULT_CHECKS should be format + disposable + localPart');
-        assert.deepEqual(ALL_CHECKS, ['format', 'disposable', 'localPart', 'mailbox'], 'ALL_CHECKS should include mailbox');
+        assert.deepEqual(DEFAULT_CHECKS, ['format', 'disposable', 'corporate', 'localPart'], 'DEFAULT_CHECKS should be format + disposable + corporate + localPart');
+        assert.deepEqual(ALL_CHECKS, ['format', 'disposable', 'corporate', 'localPart', 'mailbox'], 'ALL_CHECKS should include mailbox');
       },
     },