backend-manager 5.6.0 → 5.6.2

package/.claude/scheduled_tasks.lock

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

package/CHANGELOG.md

@@ -14,6 +14,23 @@ 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.2] - 2026-06-11
+
+### Fixed
+- **4 stale framework tests aligned with shipped v5.5.4–v5.5.6 validation behavior.** The default `npx mgr test` run failed 4 tests whose expectations predated intentional source changes: `test/email/validation.js` still expected all-numeric (`123456@`) and short letter+number (`a123@`) local parts to be blocked (both patterns were removed in v5.5.6 after NeverBounce confirmed real users — QQ emails, real Gmail accounts — were being blocked; tests renamed `localpart-all-numeric-allowed` / `localpart-letter-plus-numbers-allowed`) and expected the pre-v5.5.5 `DEFAULT_CHECKS`/`ALL_CHECKS` lists (now include `typo`, and `dns` in `ALL_CHECKS`); `test/routes/marketing/webhook.js`'s bounce test sent no `bounce_classification`, which v5.5.4 deliberately skips (renamed `sendgrid-hard-bounce-event-handled`, now sends `'Invalid Address'`).
+
+### Added
+- **Suite coverage for the v5.5.5 `typo` + `dns` email validation checks** (previously only covered by the standalone `validation.test.js` script): typo-domain blocking (`gamil.com`, `gmail.con`) + correct-domain pass-through, dns-not-in-default-checks, an offline-safe dns positive (network errors skip, never block), and an extended-gated (`TEST_EXTENDED_MODE`) dns negative for nonexistent domains.
+- **Suite coverage for the v5.5.4 bounce-classification filter**: `dropped` + `'Invalid Address'` revokes, technical bounce (`'Technical Failure'`) skipped, and unclassified bounce skipped — locking in that sender-side bounces never revoke recipient consent.
+
+# [5.6.1] - 2026-06-11
+
+### Added
+- **`docs/audit.md` — full-audit check catalog (`/omega:bem audit`).** ID'd, severity-graded checks with scope auto-detect (consumer vs framework via `functions/package.json`): mirrored universal checks (U-01..U-14 — tests at every surface, sanitization, secrets incl. `service-account.json`, config canon, doc parity, dead/legacy patterns, dep health, …), BEM-specific checks (BEM-01..BEM-09 — name-matched context-object schemas, the required-vs-default footgun, ownership checks + `assistant.respond()`, index.js/rewrites wiring, Firestore canon, usage helper + rate limits, composite indexes, auth gates, rules coverage), and framework-repo checks (F-01..F-04). Findings persist to `functions/.temp/audit/claude-audit.md`; fixes run as a severity-ordered TodoWrite loop ending with a green `npx mgr test`. Wired to the `omega:bem` router's Audit process; `docs/audit.md` is mirrored across UJM/BXM/EM. Indexed in CLAUDE.md.
+
+### Changed
+- **package.json `keywords` corrected** — replaced the thin generic set (`cli`, `backend manager`, `firebase`) with accurate, discovery-oriented ones (`firebase`, `firebase-functions`, `cloud-functions`, `firestore`, `backend`, `serverless`, `api`, `express`, `cli`). npm-listing metadata only; no behavior change. Mirrored across UJM/BXM/EM.
+
 # [5.6.0] - 2026-06-11
 
 ### Added
@@ -31,6 +48,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - **`docs/testing.md` renamed `docs/test-framework.md`** (H1 `# Testing` → `# Test Framework`) for cross-framework doc-file parity — EM/BXM/UJM all name their test reference `docs/test-framework.md`, and the mirrored docs must match down to the file name. All references updated (`CLAUDE.md`, `README.md`, `docs/*.md` cross-links, `src/defaults/CLAUDE.md`, `src/defaults/test/_init.js`, historical CHANGELOG links).
 - **Log files renamed for cross-framework parity.** `functions/serve.log` → `functions/dev.log` (the `npx mgr serve` dev-server output) and `functions/logs.log` → `functions/production.log` (the `npx mgr logs` Cloud Logging output). The `dev`/`test` names now match EM/BXM/UJM; `emulator.log` and `test.log` are unchanged. BEM logs still live in `functions/` (not `logs/`) — that directory is a deliberate exception so they sit beside firebase-tools' own `*-debug.log` files. The watcher reset sentinel `serve.log.reset` is correspondingly `dev.log.reset` (internal, in `.temp/`).
 
+### Fixed
+- **`npm publish` vs the fixture's runtime symlinks.** New `prepublishOnly` script removes `src/test/fixtures/firebase-project/functions/node_modules` before packing — the self-test's `backend-manager` symlink points back at the repo root, and prepare-package's publish-time cleanup walk (`jetpack.find` with a top-level-only `!node_modules/**` exclusion) followed the cycle until `ENAMETOOLONG`. The symlinks are throwaway runtime artifacts; the next self-test run regenerates them via `linkFixtureDeps()`.
+- **Fixture `.firebaserc` re-included over the global `.gitignore` rule** (`!src/test/fixtures/firebase-project/.firebaserc`) — the emulator boots with no `--project` flag and resolves the demo project from `.firebaserc`, so a fresh clone's self-test would have failed without it.
+
 # [5.5.4] - 2026-06-09
 
 ### Fixed

package/CLAUDE.md

@@ -135,6 +135,7 @@ Deep references live in `docs/`. **Whenever you make a behavioral change, update
 - [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/audit.md](docs/audit.md) — full-audit check catalog (U-xx universal / BEM-xx / F-xx IDs with severity + scope), protocol + fix loop
 - [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/cli-output.md](docs/cli-output.md) — shared CLI styling module (`src/cli/utils/ui.js`): OMEGA-style banner/dividers/sections/status symbols + the `Summary` block; used by `setup`, adoptable by other commands
 - [docs/environment-detection.md](docs/environment-detection.md) — `getEnvironment()` returns `'development' | 'testing' | 'production'` (mutually exclusive); gate side effects on the INTENTIONAL check (`isProduction()` for prod-only, `isDevelopment() || isTesting()` for local-or-test) — never `!isDevelopment()`. Plus the URL helper convention (always `Manager.getApiUrl()` — auto-resolves local in dev+test, never read `project.apiUrl`)

package/docs/audit.md

@@ -0,0 +1,70 @@
+# Audit Workflow
+
+Full-project audit for BEM — runs against a CONSUMER backend or the FRAMEWORK repo itself (scope auto-detected). Invoked via the `omega:bem` skill (`/omega:bem audit`) or any "audit this backend/project" request.
+
+Every check has a stable ID, a severity, and a scope. Findings are reported as `ID @ file:line`, fixed one at a time, then re-verified. The tables below do NOT restate the rules — each check links to the doc that owns the rule and the fix.
+
+## Protocol
+
+1. **Detect scope** — read `package.json` (consumer: `functions/package.json`): `name` is `backend-manager` → **framework audit** (U + BEM + F checks); `backend-manager` in (dev)dependencies → **consumer audit** (U + BEM checks).
+2. **Run the catalog** — every check matching the scope. Search with Grep/Glob/Read over `functions/` (`routes/`, `schemas/`, `hooks/`, `index.js`), `test/`, and config files; ALWAYS exclude `node_modules/`, `dist/`, `_legacy/`, `_backup/`. Record each finding as `ID @ file:line` + a one-line description.
+3. **Persist the report** — write the findings list to `functions/.temp/audit/claude-audit.md` (BEM's `functions/`-local convention, like its logs) so a long fix loop survives session breaks. Summarize counts by severity in chat.
+4. **Fix loop** — TodoWrite per finding, highest severity first, ONE at a time: mark in-progress → root cause → fix → verify → complete. Ask before structural or destructive fixes (file deletions, schema reshapes, data migrations).
+5. **Re-verify** — re-run every check that produced findings until clean; finish with `npx mgr test` from `functions/` (must be green — it auto-starts its own emulator if needed).
+6. **Doc parity** — if fixes changed behavior, update README / CLAUDE.md / `docs/<topic>.md` / CHANGELOG in the same change set.
+
+Severity: **CRIT** security or broken functionality · **HIGH** hard-rule violation · **MED** convention drift · **LOW** optional improvement.
+Scope: **C** consumer · **F** framework repo · **B** both.
+
+## Universal checks (U-xx)
+
+Mirrored across all four OMEGA frameworks (UJM / BEM / BXM / EM) — same ID means the same check everywhere.
+
+| ID | Sev | Scope | Check |
+|----|-----|-------|-------|
+| U-01 | HIGH | B | Every feature has tests at EVERY surface it exposes — handler suites + `http.as(...)` route round-trips + rules suites; never mocked, real emulator only ([test-framework.md](test-framework.md)) |
+| U-02 | HIGH | B | Test hygiene — side-effect tests use dedicated `journey-*` accounts; real-external-API tests gated behind `TEST_EXTENDED_MODE` in-source (not mocked); files export `{ description, type, tests }` (no raw Mocha); no trailing cleanup steps ([test-framework.md](test-framework.md)) |
+| U-03 | CRIT | B | Sanitization — middleware is trim-only by default; HTML strip via opt-in `{ sanitize: true }`; every HTML-insertion site calls `utilities.sanitize()` ([sanitization.md](sanitization.md)) |
+| U-04 | HIGH | B | Firebase ownership — server code uses `firebase-admin` via Manager (correct here); NO client `firebase` SDK in functions code; consuming frontends go through web-manager ([CLAUDE.md](../CLAUDE.md) §Dependency Resolution) |
+| U-05 | HIGH | C | No BEM transitive deps installed directly in `functions/package.json` — use `Manager.require(name)` ([CLAUDE.md](../CLAUDE.md) §Dependency Resolution) |
+| U-06 | HIGH | B | Env behavior gated on the INTENTIONAL check — `isProduction()` or `isDevelopment() \|\| isTesting()`, never `!isDevelopment()`; always `Manager.getApiUrl()`, never the cached `Manager.project.apiUrl` ([environment-detection.md](environment-detection.md)) |
+| U-07 | HIGH | B | Config canon — `backend-manager-config.json` matches the documented shape; canonical cross-framework blocks (`brand`, payment products, …) not reinvented ([architecture.md](architecture.md), [payment-system.md](payment-system.md)) |
+| U-08 | CRIT | B | No private credentials committed — `service-account.json`, `.env` secrets, API keys (Stripe `sk_`, SendGrid `SG.`, …); `.gitignore` covers them. (The Firebase WEB `apiKey` is public by design — do NOT flag it.) |
+| U-09 | HIGH | B | Source discipline — no live code referencing `_legacy/` / `_backup/`; framework edits in `src/` (never `dist/`) ([common-mistakes.md](common-mistakes.md)) |
+| U-10 | MED | B | Doc parity — README / CLAUDE.md / `docs/` / CHANGELOG match shipped behavior; CLAUDE.md < 250 lines; the docs index lists every `docs/*.md`; no stale names for renamed commands/patterns |
+| U-11 | MED | B | SSOT/DRY — no duplicated constants/config/logic; one authoritative home per value, imported everywhere else |
+| U-12 | MED | B | JS conventions — file structure, JSDoc, short-circuit returns, leading logical operators, `fs-jetpack`, one `module.exports` per file ([code-patterns.md](code-patterns.md) + global `js:patterns` skill) |
+| U-13 | MED | B | Dead code & stale patterns — no orphaned files nothing imports; no leftovers of migrated-away formats (constructor routes, tiered schemas, `Manager.config.*` reads — [migration.md](migration.md)); inventory TODO/FIXME (report only) |
+| U-14 | LOW | B | Dependency health — review `npm outdated` / `npm audit` (in `functions/`); apply fixes via the `general:update-packages` workflow (includes supply-chain checks) |
+
+## BEM-specific checks
+
+| ID | Sev | Scope | Check |
+|----|-----|-------|-------|
+| BEM-01 | HIGH | B | Every custom route has a name-matched schema; handlers are context-object exports (`async ({ Manager, assistant, … }) => {}`) — no legacy constructor routes ([routes.md](routes.md), [schemas.md](schemas.md)) |
+| BEM-02 | HIGH | B | Schema field rules — never `required: true` + `default` together (required is checked BEFORE defaults; use `min: 1` for path-extracted IDs); flat schema with in-function plan branching, no tier arrays ([schemas.md](schemas.md)) |
+| BEM-03 | HIGH | B | Route handlers — ownership checks on PUT/DELETE; plural-noun route names; `assistant.respond()` only (never `res.send()`) ([routes.md](routes.md), [common-operations.md](common-operations.md)) |
+| BEM-04 | HIGH | C | Wiring — every route exported in `functions/index.js`; `firebase.json` rewrites use bracket syntax, ordered most-specific-first ([routes.md](routes.md)) |
+| BEM-05 | HIGH | B | Firestore canon — NO subcollections; path-string `.doc('users/abc')`; batched collection reads (~500, cursor pagination); timestamps under `metadata.{created,updated}`; mirror-the-doc responses; delete-don't-redact ([firestore.md](firestore.md)) |
+| BEM-06 | HIGH | B | Usage — never read/write `{doc}.usage.*` manually, always the `usage` helper; expensive/abusable routes carry usage validation or rate limiting ([usage-rate-limiting.md](usage-rate-limiting.md)) |
+| BEM-07 | MED | B | Composite indexes — every compound query (`where` + `orderBy`, multiple `where`s) is registered in the required-indexes SSOT ([CLAUDE.md](../CLAUDE.md) §File Conventions) |
+| BEM-08 | HIGH | B | Auth gates — routes resolve the caller via `assistant`/`user` before acting; admin-only routes verify admin status ([common-operations.md](common-operations.md), [routes.md](routes.md)) |
+| BEM-09 | HIGH | B | Rules coverage — `firestore.rules` changes ship a rules suite (`rules.asAccount` / `expectSuccess` / `expectFailure`) ([test-framework.md](test-framework.md)) |
+
+## Framework-repo checks (F-xx)
+
+Only when auditing the BEM repo itself. Mirrored across the four frameworks.
+
+| ID | Sev | Check |
+|----|-----|-------|
+| F-01 | MED | Sister parity — mirrored sections (config shapes, test contract, CLAUDE.md skeleton, shared env/test conventions) in sync with UJM / BXM / EM; deviations are deliberate and documented |
+| F-02 | HIGH | Consumer-shipped defaults in sync — what `npx mgr setup` scaffolds matches current conventions and docs |
+| F-03 | MED | Docs completeness — every `docs/*.md` indexed in CLAUDE.md; every subsystem has a doc; no "(planned)" links for things that have shipped |
+| F-04 | HIGH | `npx mgr test mgr:` green before treating the audit as complete |
+
+## See also
+
+- [schemas.md](schemas.md) — the required-vs-default footgun behind BEM-02
+- [firestore.md](firestore.md) — the data canon behind BEM-05
+- [migration.md](migration.md) — the legacy formats U-13 hunts for
+- [test-framework.md](test-framework.md) — the surfaces behind U-01 / U-02 / BEM-09

package/docs/build-system.md

@@ -16,6 +16,8 @@ There are no build modes — environment behavior is governed by emulator vs pro
 
 The BEM library itself has one build step: `npm run prepare` copies `src/` → `dist/` via prepare-package (`npm run prepare:watch` for watch mode). Consumers always require from `dist/`. This mirrors the framework-side prepare step in EM/BXM/UJM.
 
+At publish time, a `prepublishOnly` script first removes the self-test fixture's runtime `node_modules` (`src/test/fixtures/firebase-project/functions/node_modules`) — its `backend-manager` symlink points back at the repo root, which would send prepare-package's publish-time cleanup walk into an infinite cycle. The symlinks are throwaway; the next `npx mgr test` self-test regenerates them (see [test-boot-layer.md](test-boot-layer.md)).
+
 ## Log files
 
 CLI commands tee output to `functions/*.log` (`dev.log`, `emulator.log`, `test.log`, `production.log`). Full reference: [logging.md](logging.md).

package/docs/email-system.md

@@ -284,7 +284,7 @@ All email tests live under `test/email/`, mirroring the source at `src/manager/l
 |---|---|---|
 | `templates.js` | MJML rendering for all 4 email templates (11 tests) | No |
 | `transactional.js` | Transactional email building (assertions on output shape) | No |
-| `validation.js` | Email format/disposable/corporate/local-part/typo/dns checks (60+ tests) | No |
+| `validation.js` | Email format/disposable/corporate/local-part/typo/dns checks (52 tests) | No |
 | `transactional-send.js` | Single transactional email send via SendGrid | Yes |
 | `campaign-send.js` | Marketing campaign send with title + CTA + discount code | Yes |
 | `feedback-and-plain-send.js` | Feedback + plain template visual test sends | Yes |

package/docs/test-boot-layer.md

@@ -44,6 +44,8 @@ module.exports = {
 
 **Runtime-only, gitignored** (never committed): before boot, the test command symlinks the local `backend-manager` (+ `firebase-admin`/`firebase-functions` from BEM's own `node_modules`) into the fixture's `functions/node_modules`, injects the fixture admin keys into the env, and generates a **throwaway RSA `service-account.json`** (emulator-only — a `demo-` project never authenticates against Google). All of this lives in `setupSelfTest()` / `linkFixtureDeps()` / `ensureFixtureServiceAccount()` in [src/cli/commands/test.js](../src/cli/commands/test.js).
 
+Two packaging details keep the fixture sound: the fixture's `.firebaserc` is **re-included over the repo's global `.firebaserc` ignore** (the emulator boots with no `--project` flag, so it resolves `demo-backend-manager` from that file — a fresh clone needs it), and a `prepublishOnly` script **removes the runtime symlinks before `npm publish`** (the `backend-manager` symlink points back at the repo root, which would loop prepare-package's publish-time tree walk; the next self-test run relinks them).
+
 ## `BEM_TEST_BOOT_PROJECT`
 
 | Env | Purpose |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.6.0",
+  "version": "5.6.2",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {
@@ -30,9 +30,15 @@
     "url": "git+https://github.com/itw-creative-works/backend-manager.git"
   },
   "keywords": [
-    "cli",
-    "backend manager",
-    "firebase"
+    "firebase",
+    "firebase-functions",
+    "cloud-functions",
+    "firestore",
+    "backend",
+    "serverless",
+    "api",
+    "express",
+    "cli"
   ],
   "author": "ITW Creative Works",
   "license": "ISC",

package/test/email/validation.js

@@ -1,8 +1,9 @@
 /**
  * Test: Email validation library (libraries/email/validation.js)
- * Unit tests for format, local part, disposable domain, and mailbox checks
+ * Unit tests for format, local part, disposable domain, corporate domain, typo domain, DNS, and mailbox checks
  *
- * Format, local part, and disposable tests always run (free, regex-based).
+ * Format, local part, disposable, corporate, and typo tests always run (free, sync, offline-safe).
+ * DNS negative tests require TEST_EXTENDED_MODE (live DNS resolution).
  * Mailbox verification tests require TEST_EXTENDED_MODE + NEVERBOUNCE_API_KEY or ZEROBOUNCE_API_KEY.
  */
 const { validate, isDisposable, isCorporate, DEFAULT_CHECKS, ALL_CHECKS } = require('../../src/manager/libraries/email/validation.js');
@@ -115,15 +116,17 @@ module.exports = {
     },
 
     {
-      name: 'localpart-all-numeric-blocked',
+      name: 'localpart-all-numeric-allowed',
       timeout: 5000,
 
       async run({ assert }) {
+        // All-numeric local parts are legitimate (QQ emails like 1549482839@qq.com,
+        // student IDs) — the ^\d+$ pattern was removed in v5.5.6 after NeverBounce
+        // confirmed real users were being blocked.
         const result = await validate('123456@gmail.com');
 
-        assert.equal(result.valid, false, 'All-numeric local part should be blocked');
-        assert.propertyEquals(result, 'checks.localPart.blocked', true, 'Should be flagged as blocked');
-        assert.propertyEquals(result, 'checks.localPart.reason', 'Matches junk pattern', 'Should match junk pattern');
+        assert.equal(result.valid, true, 'All-numeric local part should be allowed');
+        assert.propertyEquals(result, 'checks.localPart.valid', true, 'localPart check should pass');
       },
     },
 
@@ -164,14 +167,17 @@ module.exports = {
     },
 
     {
-      name: 'localpart-letter-plus-numbers-blocked',
+      name: 'localpart-letter-plus-numbers-allowed',
       timeout: 5000,
 
       async run({ assert }) {
+        // Short letter + numbers local parts are legitimate (real Gmail users like
+        // mi1925973, hk9526802) — the ^[a-z]{1,2}\d+$ pattern was removed in v5.5.6
+        // after NeverBounce confirmed real users were being blocked.
         const result = await validate('a123@gmail.com');
 
-        assert.equal(result.valid, false, 'Single letter + numbers should be blocked');
-        assert.propertyEquals(result, 'checks.localPart.blocked', true, 'Should be flagged as blocked');
+        assert.equal(result.valid, true, 'Single letter + numbers should be allowed');
+        assert.propertyEquals(result, 'checks.localPart.valid', true, 'localPart check should pass');
       },
     },
 
@@ -370,6 +376,49 @@ module.exports = {
       },
     },
 
+    // --- Typo domain checks ---
+
+    {
+      name: 'typo-gamil-blocked',
+      timeout: 5000,
+
+      async run({ assert }) {
+        const result = await validate('rachel.greene@gamil.com');
+
+        assert.equal(result.valid, false, 'gamil.com should be blocked as a typo of gmail.com');
+        assert.propertyEquals(result, 'checks.typo.valid', false, 'Typo check should fail');
+        assert.propertyEquals(result, 'checks.typo.matchedPrefix', 'gamil.', 'Should report the matched prefix');
+        assert.propertyEquals(result, 'checks.typo.reason', 'Likely misspelled domain', 'Should have human-readable reason');
+      },
+    },
+
+    {
+      name: 'typo-gmail-con-blocked',
+      timeout: 5000,
+
+      async run({ assert }) {
+        const result = await validate('rachel.greene@gmail.con');
+
+        assert.equal(result.valid, false, 'gmail.con should be blocked as a typo TLD');
+        assert.propertyEquals(result, 'checks.typo.valid', false, 'Typo check should fail');
+      },
+    },
+
+    {
+      name: 'typo-correct-domains-pass',
+      timeout: 5000,
+
+      async run({ assert }) {
+        const gmail = await validate('rachel.greene@gmail.com');
+        const hotmail = await validate('rachel.greene@hotmail.com');
+
+        assert.equal(gmail.valid, true, 'gmail.com should pass');
+        assert.propertyEquals(gmail, 'checks.typo.valid', true, 'Typo check should pass for gmail.com');
+        assert.equal(hotmail.valid, true, 'hotmail.com should pass');
+        assert.propertyEquals(hotmail, 'checks.typo.valid', true, 'Typo check should pass for hotmail.com');
+      },
+    },
+
     // --- isCorporate helper ---
 
     {
@@ -529,8 +578,51 @@ module.exports = {
       timeout: 5000,
 
       async run({ assert }) {
-        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');
+        assert.deepEqual(DEFAULT_CHECKS, ['format', 'disposable', 'corporate', 'localPart', 'typo'], 'DEFAULT_CHECKS should be all free sync checks (no dns/mailbox)');
+        assert.deepEqual(ALL_CHECKS, ['format', 'disposable', 'corporate', 'localPart', 'typo', 'dns', 'mailbox'], 'ALL_CHECKS should add dns + mailbox');
+      },
+    },
+
+    // --- DNS check behavior ---
+
+    {
+      name: 'dns-not-in-default-checks',
+      timeout: 5000,
+
+      async run({ assert }) {
+        const result = await validate('rachel.greene@gmail.com');
+
+        assert.equal(result.valid, true, 'Should be valid');
+        assert.equal(result.checks.dns, undefined, 'DNS should not run with default checks (async/slow — opt-in)');
+      },
+    },
+
+    {
+      name: 'dns-valid-domain-passes',
+      timeout: 15000,
+
+      async run({ assert }) {
+        // Offline-safe: on network errors the dns check is skipped (valid stays true);
+        // only definitive no-MX/NXDOMAIN answers block.
+        const result = await validate('rachel.greene@gmail.com', { checks: ['format', 'dns'] });
+
+        assert.equal(result.valid, true, 'gmail.com should pass the DNS check');
+        assert.hasProperty(result, 'checks.dns', 'Should have dns check result');
+      },
+    },
+
+    {
+      name: 'dns-nonexistent-domain-fails',
+      timeout: 15000,
+      skip: !process.env.TEST_EXTENDED_MODE
+        ? 'TEST_EXTENDED_MODE not set (requires live DNS resolution)'
+        : false,
+
+      async run({ assert }) {
+        const result = await validate('rachel.greene@thisdomaindoesnotexist99887766.com', { checks: ['format', 'dns'] });
+
+        assert.equal(result.valid, false, 'Nonexistent domain should fail the DNS check');
+        assert.propertyEquals(result, 'checks.dns.valid', false, 'DNS check should fail');
       },
     },
 

package/test/routes/marketing/webhook.js

@@ -12,6 +12,8 @@
  *
  * SendGrid processor tests:
  *   - Various event types (group_unsubscribe, unsubscribe, spamreport, bounce, dropped)
+ *   - bounce/dropped only revoke on bounce_classification='Invalid Address' (hard bounce);
+ *     technical bounces are sender-side issues and must NOT revoke consent
  *   - Email lookup → user doc mutation with source='sendgrid'
  *   - Silent skip when email doesn't map to a user (shared SendGrid account scenario)
  *   - Batched events processed independently
@@ -25,13 +27,14 @@ function sgEventId(name) {
 }
 
 // Helper — build a SendGrid event payload
-function sgEvent({ id, type, email, timestamp, asmGroupId }) {
+function sgEvent({ id, type, email, timestamp, asmGroupId, bounceClassification }) {
   return {
     sg_event_id: id,
     event: type,
     email,
     timestamp: timestamp || Math.floor(Date.now() / 1000),
     ...(asmGroupId !== undefined ? { asm_group_id: asmGroupId } : {}),
+    ...(bounceClassification !== undefined ? { bounce_classification: bounceClassification } : {}),
   };
 }
 
@@ -167,20 +170,43 @@ module.exports = {
     },
 
     {
-      name: 'sendgrid-bounce-event-handled',
+      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 eventId = sgEventId('bounce');
+        const eventId = sgEventId('hard-bounce');
 
+        // Only hard bounces (bounce_classification='Invalid Address') revoke consent.
         const response = await http.as('none').post(
           `backend-manager/marketing/webhook?provider=sendgrid&key=${process.env.BACKEND_MANAGER_WEBHOOK_KEY}`,
-          [sgEvent({ id: eventId, type: 'bounce', email })]
+          [sgEvent({ id: eventId, type: 'bounce', email, bounceClassification: 'Invalid Address' })]
+        );
+
+        assert.isSuccess(response);
+        assert.propertyEquals(response, 'data.processed', 1, 'Hard bounce should be treated as a revoke');
+
+        const userDoc = await firestore.get(`users/${uid}`);
+        assert.equal(userDoc?.consent?.marketing?.status, 'revoked');
+      },
+    },
+
+    {
+      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 eventId = sgEventId('dropped');
+
+        // 'dropped' follows the same classification filter as 'bounce'.
+        const response = await http.as('none').post(
+          `backend-manager/marketing/webhook?provider=sendgrid&key=${process.env.BACKEND_MANAGER_WEBHOOK_KEY}`,
+          [sgEvent({ id: eventId, type: 'dropped', email, bounceClassification: 'Invalid Address' })]
         );
 
         assert.isSuccess(response);
-        assert.propertyEquals(response, 'data.processed', 1, 'Bounce should be treated as a revoke');
+        assert.propertyEquals(response, 'data.processed', 1, 'Dropped with Invalid Address should be treated as a revoke');
 
         const userDoc = await firestore.get(`users/${uid}`);
         assert.equal(userDoc?.consent?.marketing?.status, 'revoked');
@@ -189,6 +215,45 @@ module.exports = {
 
     // ─── SendGrid processor — events we ignore ───
 
+    {
+      name: 'sendgrid-technical-bounce-ignored',
+      auth: 'none',
+      async run({ http, assert, accounts }) {
+        const email = accounts.basic.email;
+        const eventId = sgEventId('technical-bounce');
+
+        // Technical bounces (DMARC, TLS, DNS) are sender-side issues — the recipient's
+        // mailbox is still valid, so consent must NOT be revoked.
+        const response = await http.as('none').post(
+          `backend-manager/marketing/webhook?provider=sendgrid&key=${process.env.BACKEND_MANAGER_WEBHOOK_KEY}`,
+          [sgEvent({ id: eventId, type: 'bounce', email, bounceClassification: 'Technical Failure' })]
+        );
+
+        assert.isSuccess(response, 'Should accept the request (not error) but ignore the event');
+        assert.propertyEquals(response, 'data.processed', 0, 'Technical bounce should not be processed');
+        assert.propertyEquals(response, 'data.skipped', 1, '1 event should be skipped');
+      },
+    },
+
+    {
+      name: 'sendgrid-bounce-without-classification-ignored',
+      auth: 'none',
+      async run({ http, assert, accounts }) {
+        const email = accounts.basic.email;
+        const eventId = sgEventId('unclassified-bounce');
+
+        // No bounce_classification — can't confirm a hard bounce, so skip.
+        const response = await http.as('none').post(
+          `backend-manager/marketing/webhook?provider=sendgrid&key=${process.env.BACKEND_MANAGER_WEBHOOK_KEY}`,
+          [sgEvent({ id: eventId, type: 'bounce', email })]
+        );
+
+        assert.isSuccess(response, 'Should accept the request (not error) but ignore the event');
+        assert.propertyEquals(response, 'data.processed', 0, 'Unclassified bounce should not be processed');
+        assert.propertyEquals(response, 'data.skipped', 1, '1 event should be skipped');
+      },
+    },
+
     {
       name: 'sendgrid-delivered-event-ignored',
       auth: 'none',