backend-manager 5.6.1 → 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,15 @@ 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

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/package.json

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

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',