@omega.js/backend 0.1.0

package/test/email/unsubscribe-groups.test.js

@@ -0,0 +1,155 @@
+/**
+ * Unsubscribe-group resolution test — the ASM group a send attaches comes from
+ * CONFIG, never from a constant.
+ *
+ * SendGrid unsubscribe-group ids are per ACCOUNT, so the seven ids that used to
+ * sit in constants.js belonged to one company's account: every other brand sent
+ * with ids that do not exist in its own. The manager's campaigns service now
+ * provisions the groups by name and writes each id into
+ * `marketing.campaigns.providers.sendgrid.groups.<key>`; prepare.js reads it
+ * there, and a missing one is a LOUD failure (the manage walk never ran) rather
+ * than a silent send under someone else's group
+ * ([#649](https://github.com/Omega-JS-Stack/omega/issues/649)).
+ *
+ * Plain-node unit test (no emulator, no network) — the build path is pure, so
+ * the assertions run against the real Transactional.build().
+ */
+const assert = require('node:assert');
+const { GROUP_KEYS, DEFAULT_GROUP_KEY } = require('../../dist/manager/libraries/email/constants.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+// This brand's own account ids — deliberately nothing like the ITW ids that
+// used to be compiled in.
+const GROUP_IDS = {
+  orders: 900001,
+  hello: 900002,
+  account: 900003,
+  marketing: 900004,
+  security: 900005,
+  newsletter: 900006,
+  internal: 900007,
+};
+
+function makeManager(groups) {
+  return {
+    config: {
+      brand: { id: 'testbrand', name: 'Test Brand', url: 'https://test.dev', contact: { email: 'hello@test.dev' }, images: {} },
+      ...(groups ? { marketing: { campaigns: { providers: { sendgrid: { groups } } } } } : {}),
+    },
+    project: { websiteUrl: 'https://test.dev' },
+    libraries: { admin: {} },
+    User: () => ({ properties: {} }),
+  };
+}
+
+function build(settings, { groups = GROUP_IDS } = {}) {
+  process.env.UNSUBSCRIBE_HMAC_KEY = process.env.UNSUBSCRIBE_HMAC_KEY || 'test-key';
+
+  const Transactional = require('../../dist/manager/libraries/email/transactional/index.js');
+  const Manager = makeManager(groups);
+  const ctx = { Manager, log: () => {}, error: () => {} };
+
+  return new Transactional(ctx).build({
+    to: 'user@test.dev',
+    subject: 'Group resolution',
+    template: 'card',
+    data: { content: { message: 'Hi' } },
+    ...settings,
+  });
+}
+
+module.exports = defineCases({
+  description: 'Unsubscribe group ids resolve from config (#649)',
+  type: 'group',
+  tests: [
+    {
+      name: 'constants carry KEYS only — no compiled-in ASM ids',
+
+      run() {
+        const constants = require('../../dist/manager/libraries/email/constants.js');
+
+        assert.ok(!('GROUPS' in constants), 'the hardcoded id map is gone');
+        assert.deepEqual(GROUP_KEYS, ['orders', 'hello', 'account', 'marketing', 'security', 'newsletter', 'internal']);
+        for (const sender of Object.values(constants.SENDERS)) {
+          assert.ok(GROUP_KEYS.includes(sender.group), `sender names a group KEY, got ${sender.group}`);
+        }
+      },
+    },
+
+    {
+      name: "a sender's group id comes from this brand's config",
+
+      async run() {
+        const email = await build({ sender: 'orders' });
+
+        assert.equal(email.asm.groupId, GROUP_IDS.orders);
+      },
+    },
+
+    {
+      name: 'every sender category resolves its own configured id',
+
+      async run() {
+        const { SENDERS } = require('../../dist/manager/libraries/email/constants.js');
+
+        for (const [sender, config] of Object.entries(SENDERS)) {
+          const email = await build({ sender });
+          assert.equal(email.asm.groupId, GROUP_IDS[config.group], `${sender} attached the wrong group`);
+        }
+      },
+    },
+
+    {
+      name: 'a send naming no sender falls back to the configured account group',
+
+      async run() {
+        const email = await build({});
+
+        assert.equal(email.asm.groupId, GROUP_IDS[DEFAULT_GROUP_KEY]);
+      },
+    },
+
+    {
+      name: 'an explicit group KEY resolves from config; a raw id passes through',
+
+      async run() {
+        const byKey = await build({ sender: 'orders', group: 'security' });
+        assert.equal(byKey.asm.groupId, GROUP_IDS.security, 'the key won over the sender default');
+
+        const byId = await build({ sender: 'orders', group: 424242 });
+        assert.equal(byId.asm.groupId, 424242, 'a caller-supplied id is used as-is');
+      },
+    },
+
+    {
+      name: 'a missing group id fails LOUDLY — it never sends under a guessed group',
+
+      async run() {
+        // The programmer error this guards: the manage walk never ran, so the
+        // brand has no groups of its own. Sending anyway would attach an id
+        // belonging to whichever account it was created in.
+        await assert.rejects(
+          () => build({ sender: 'orders' }, { groups: null }),
+          (error) => {
+            assert.equal(error.code, 400, 'classed as a build failure');
+            assert.match(error.message, /marketing\.campaigns\.providers\.sendgrid\.groups\.orders/, 'names the config path to set');
+            return true;
+          },
+        );
+      },
+    },
+
+    {
+      name: 'one missing key fails even when the others are configured',
+
+      async run() {
+        const { security, ...rest } = GROUP_IDS;
+
+        await assert.rejects(
+          () => build({ sender: 'security' }, { groups: rest }),
+          /groups\.security/,
+        );
+      },
+    },
+  ],
+});

package/test/email/unsubscribe-key.test.js

@@ -0,0 +1,91 @@
+/**
+ * The unsubscribe signing key guard (#569) — a brand deployed without
+ * UNSUBSCRIBE_HMAC_KEY used to crash inside node's crypto with
+ * `The "key" argument must be of type string ... Received undefined`, and only
+ * ever at a real customer's first order email. The key is the manager's to
+ * mint; when it is absent anyway, the failure has to NAME it.
+ *
+ * Since #581 there is ONE reader of the key — libraries/env.js, the reader
+ * every framework env read goes through — so the named error is its
+ * MissingEnvKeyError, and the boot guard refuses long before an email does.
+ *
+ * Plain-node unit test (no emulator, no network).
+ */
+const assert = require('node:assert');
+const crypto = require('crypto');
+
+const { buildUnsubscribeUrl } = require('../../dist/manager/libraries/email/prepare.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+// The runner sets a key for the whole run, so every case here forces its own
+// and puts the run's value back — a leaked delete would break every later
+// email test in the process.
+function withKey(value, fn) {
+  const saved = process.env.UNSUBSCRIBE_HMAC_KEY;
+  if (value === undefined) {
+    delete process.env.UNSUBSCRIBE_HMAC_KEY;
+  } else {
+    process.env.UNSUBSCRIBE_HMAC_KEY = value;
+  }
+
+  try {
+    return fn();
+  } finally {
+    if (saved === undefined) {
+      delete process.env.UNSUBSCRIBE_HMAC_KEY;
+    } else {
+      process.env.UNSUBSCRIBE_HMAC_KEY = saved;
+    }
+  }
+}
+
+const LINK = {
+  email: 'Customer@Example.com',
+  groupId: 123,
+  template: 'order',
+  websiteUrl: 'https://brand.dev',
+};
+
+module.exports = defineCases({
+  description: 'Email unsubscribe signing key guard (UNSUBSCRIBE_HMAC_KEY)',
+  type: 'group',
+  tests: [
+    {
+      name: 'an unset UNSUBSCRIBE_HMAC_KEY throws a named error that says the key',
+
+      run() {
+        withKey(undefined, () => {
+          assert.throws(() => buildUnsubscribeUrl(LINK), (error) => {
+            assert.strictEqual(error.name, 'MissingEnvKeyError');
+            assert.match(error.message, /UNSUBSCRIBE_HMAC_KEY/);
+            // Not node's crypto TypeError — the point of the guard
+            assert.strictEqual(error instanceof TypeError, false);
+            return true;
+          });
+        });
+      },
+    },
+
+    {
+      name: 'an empty UNSUBSCRIBE_HMAC_KEY is just as missing',
+
+      run() {
+        withKey('', () => {
+          assert.throws(() => buildUnsubscribeUrl(LINK), /UNSUBSCRIBE_HMAC_KEY/);
+        });
+      },
+    },
+
+    {
+      name: 'with the key set, the link carries a lowercase-email signature',
+
+      run() {
+        const url = withKey('unit-test-key', () => buildUnsubscribeUrl(LINK));
+
+        const expected = crypto.createHmac('sha256', 'unit-test-key').update('customer@example.com').digest('hex');
+        assert.ok(url.startsWith('https://brand.dev/portal/email-preferences?'));
+        assert.ok(url.endsWith(`&sig=${expected}`));
+      },
+    },
+  ],
+});

package/test/email/validation-cases.test.js

@@ -0,0 +1,152 @@
+/**
+ * Email validation case corpus — verifies all free checks (format, disposable,
+ * corporate, localPart, typo, dns) plus NeverBounce result parsing (no API calls).
+ *
+ * The behavior-by-behavior suite lives next door in validation.test.js; this file is
+ * the broad address corpus — one test per address, one per parse code.
+ */
+const { validate } = require('../../dist/manager/libraries/email/validation.js');
+const { parseResult } = require('../../dist/manager/libraries/email/validation-provider-neverbounce.js');
+const assert = require('node:assert');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+const FREE_CHECKS = ['format', 'disposable', 'corporate', 'localPart', 'typo', 'dns'];
+
+const CASES = [
+  // ---- Should PASS ----
+  { email: 'user@gmail.com', expect: 'pass' },
+  { email: 'someone@yahoo.com', expect: 'pass' },
+  { email: 'hello@outlook.com', expect: 'pass' },
+  { email: 'sarah@protonmail.com', expect: 'pass' },
+  { email: 'first.last@microsoft.com', expect: 'pass' },
+  { email: 'user+tag@gmail.com', expect: 'pass' },
+  { email: 'john@icloud.com', expect: 'pass' },
+  { email: 'user@aol.com', expect: 'pass' },
+  { email: 'user@hotmail.com', expect: 'pass' },
+
+  // ---- Should FAIL: format ----
+  { email: '', expect: 'fail', check: 'format' },
+  { email: 'notanemail', expect: 'fail', check: 'format' },
+  { email: '@nodomain.com', expect: 'fail', check: 'format' },
+  { email: 'noat.com', expect: 'fail', check: 'format' },
+  { email: 'spaces in@email.com', expect: 'fail', check: 'format' },
+
+  // ---- Should FAIL: disposable (vendor list) ----
+  { email: 'test@mailinator.com', expect: 'fail', check: 'disposable' },
+  { email: 'test@guerrillamail.com', expect: 'fail', check: 'disposable' },
+  { email: 'user@yopmail.com', expect: 'fail', check: 'disposable' },
+
+  // ---- Should FAIL: disposable (custom list) ----
+  { email: 'test@dollicons.com', expect: 'fail', check: 'disposable' },
+  { email: 'test@availors.com', expect: 'fail', check: 'disposable' },
+  { email: 'test@sharebot.net', expect: 'fail', check: 'disposable' },
+  { email: 'test@deltajohnsons.com', expect: 'fail', check: 'disposable' },
+  { email: 'test@gmail10p.com', expect: 'fail', check: 'disposable' },
+  { email: 'test@dyzov.com', expect: 'fail', check: 'disposable' },
+  { email: 'test@mailpwr.com', expect: 'fail', check: 'disposable' },
+  { email: 'test@closetab.email', expect: 'fail', check: 'disposable' },
+  { email: 'test@biosu.dev', expect: 'fail', check: 'disposable' },
+  { email: 'test@wikfee.com', expect: 'fail', check: 'disposable' },
+  { email: 'test@oakon.com', expect: 'fail', check: 'disposable' },
+
+  // ---- Should FAIL: corporate ----
+  { email: 'user@instagram.com', expect: 'fail', check: 'corporate' },
+  { email: 'user@facebook.com', expect: 'fail', check: 'corporate' },
+
+  // ---- Should FAIL: localPart (exact) ----
+  { email: 'noreply@gmail.com', expect: 'fail', check: 'localPart' },
+  { email: 'no-reply@gmail.com', expect: 'fail', check: 'localPart' },
+
+  // ---- Should FAIL: localPart (patterns) ----
+  { email: 'aaaa@gmail.com', expect: 'fail', check: 'localPart' },
+  { email: 'testuser@gmail.com', expect: 'fail', check: 'localPart' },
+  { email: '_test.basic@somiibo.com', expect: 'fail', check: 'localPart' },
+  { email: '_test.allow_consent-granted@somiibo.com', expect: 'pass' },
+
+  // ---- Should FAIL: typo domains ----
+  { email: 'user@gamil.com', expect: 'fail', check: 'typo' },
+  { email: 'user@gamil.con', expect: 'fail', check: 'typo' },
+  { email: 'user@gmai.com', expect: 'fail', check: 'typo' },
+  { email: 'user@gmai.co', expect: 'fail', check: 'typo' },
+  { email: 'user@gmial.com', expect: 'fail', check: 'disposable' },
+  { email: 'user@gnail.com', expect: 'fail', check: 'typo' },
+  { email: 'user@gmail.con', expect: 'fail', check: 'typo' },
+  { email: 'user@gmail.cok', expect: 'fail', check: 'typo' },
+  { email: 'user@gmail.cm', expect: 'fail', check: 'typo' },
+  { email: 'user@aol.con', expect: 'fail', check: 'typo' },
+  { email: 'user@icloud.con', expect: 'fail', check: 'typo' },
+  { email: 'user@hotmail.con', expect: 'fail', check: 'typo' },
+  { email: 'user@hotmial.com', expect: 'fail', check: 'disposable' },
+  { email: 'user@hotnail.com', expect: 'fail', check: 'typo' },
+  { email: 'user@outlook.con', expect: 'fail', check: 'typo' },
+  { email: 'user@outlok.com', expect: 'fail', check: 'typo' },
+  { email: 'user@yahoo.con', expect: 'fail', check: 'typo' },
+  { email: 'user@protonmial.com', expect: 'fail', check: 'typo' },
+  { email: 'user@oegmail.com', expect: 'fail', check: 'typo' },
+
+  // ---- Should FAIL: dns (no MX / null MX / domain not found) ----
+  { email: 'someone@thisdoesnotexist99887766.com', expect: 'fail', check: 'dns' },
+  { email: 'someone@zzzznotreal123456.net', expect: 'fail', check: 'dns' },
+  { email: 'someone@example.com', expect: 'fail', check: 'dns' },
+];
+
+// NeverBounce single-check `result` parsing — the API returns STRING textcodes.
+// Regression: @omega.js/backend 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' },
+];
+
+module.exports = defineCases({
+  description: 'Email validation case corpus (free checks + NeverBounce parsing)',
+  type: 'group',
+  tests: [
+    ...NB_PARSE_CASES.map(({ result, expectValid, expectStatus }) => ({
+      name: `parseResult(${JSON.stringify(result)})`,
+
+      run() {
+        const parsed = parseResult(result);
+
+        assert.strictEqual(parsed.valid, expectValid, `Expected valid=${expectValid}, got ${parsed.valid}`);
+        assert.strictEqual(parsed.status, expectStatus, `Expected status=${expectStatus}, got ${parsed.status}`);
+      },
+    })),
+
+    ...CASES.map(({ email, expect: expected, check: expectedCheck }) => ({
+      name: `${expected}: ${email || '(empty)'}`,
+      timeout: 10000,
+      // Negative DNS cases need a live NXDOMAIN answer — extended-only, matching
+      // validation.test.js. Pass cases keep the dns check: it is offline-safe
+      // (network errors skip; only definitive no-MX/NXDOMAIN answers block).
+      skip: expectedCheck === 'dns' && !process.env.TEST_EXTENDED_MODE
+        ? 'TEST_EXTENDED_MODE not set (requires live DNS resolution)'
+        : false,
+
+      async run() {
+        const result = await validate(email, { checks: FREE_CHECKS });
+        const failedCheck = Object.entries(result.checks).find(([, v]) => v && !v.valid);
+
+        assert.equal(
+          result.valid,
+          expected === 'pass',
+          `Expected: ${expected}, Got: ${result.valid ? 'pass' : 'fail'}${failedCheck ? ` (${failedCheck[0]})` : ''}`,
+        );
+
+        // A failing case must fail on the check it was written for.
+        if (expectedCheck && !result.valid && failedCheck) {
+          assert.strictEqual(failedCheck[0], expectedCheck, `Expected to fail on: ${expectedCheck}, actually failed on: ${failedCheck[0]}`);
+        }
+      },
+    })),
+  ],
+});