@omega.js/backend 0.1.0

package/test/helpers/webhook-forward.test.js

@@ -0,0 +1,419 @@
+/**
+ * Test: marketing/webhook/forward route — unit-style coverage
+ *
+ * Why this exists as a unit test (not an emulator test):
+ *
+ * The forwarder is gated on Manager.isParent() (config.parent === 'self'). In real test runs
+ * we run AGAINST a child brand's @omega.js/backend (Somiibo, etc.), so the route is invisible
+ * (404). To verify the fan-out logic, we exercise the route handler directly
+ * against a mocked admin SDK + mocked fetch, no HTTP needed.
+ *
+ * What's covered:
+ *   - Gate: returns 404 if Manager.isParent() returns false (config.parent !== 'self')
+ *   - Auth: returns 401 if key missing/wrong
+ *   - Provider validation: returns 400 if missing
+ *   - Brand iteration: reads brands collection, derives API URLs
+ *   - URL derivation: brand.url 'https://somiibo.com' → 'https://api.somiibo.com/omega/marketing/webhook?provider=X&key=Y'
+ *   - Body forwarding: raw body POSTed to every child unchanged
+ *   - Failure isolation: one failed child doesn't break the others
+ *   - Brands without brand.url skipped silently
+ */
+
+// Mock wonderful-fetch before requiring the route — the route does
+// `require('wonderful-fetch')` at module load time.
+//
+// CRITICAL: every test file is `require()`d into the SAME Node process by the
+// runner, so the require cache is shared. We MUST save the original
+// wonderful-fetch cache entry here and restore it in the suite-level `cleanup`
+// below — otherwise this mock leaks into every test file that runs afterwards
+// (e.g. emulator route tests whose `Manager.require('wonderful-fetch')` would
+// then return our stub instead of doing a real HTTP round-trip).
+const originalFetchPath = require.resolve('wonderful-fetch');
+const originalFetchCacheEntry = require.cache[originalFetchPath];
+const fetchCalls = [];
+let fetchMockBehavior = () => ({ received: true });
+
+// Intercept require cache so our mock takes the place of wonderful-fetch
+require.cache[originalFetchPath] = {
+  id: originalFetchPath,
+  filename: originalFetchPath,
+  loaded: true,
+  exports: async (url, opts) => {
+    fetchCalls.push({ url, opts });
+    return fetchMockBehavior(url, opts);
+  },
+};
+
+const route = require('../../dist/manager/routes/marketing/webhook/forward/post.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+// Restore the real wonderful-fetch in the require cache so the mock is confined
+// to this file. Without this, the stub leaks process-wide and poisons every
+// later test file's HTTP calls.
+function restoreFetch() {
+  if (originalFetchCacheEntry) {
+    require.cache[originalFetchPath] = originalFetchCacheEntry;
+  } else {
+    delete require.cache[originalFetchPath];
+  }
+}
+
+// --- Test scaffolding ---
+
+function makeFirestoreMock(brandDocs) {
+  return {
+    collection: (name) => {
+      if (name !== 'brands') {
+        throw new Error(`Unexpected collection: ${name}`);
+      }
+      return {
+        get: async () => ({
+          forEach: (cb) => {
+            for (const { id, data } of brandDocs) {
+              cb({ id, data: () => data });
+            }
+          },
+        }),
+      };
+    },
+  };
+}
+
+function makeAdminMock(brandDocs) {
+  const fs = makeFirestoreMock(brandDocs);
+  return { firestore: () => fs };
+}
+
+function makeAssistant({ query, body }) {
+  const responses = [];
+  return {
+    request: { query: query || {} },
+    ref: { req: { body: body !== undefined ? body : [] } },
+    log: () => {},
+    error: () => {},
+    respond: (data, opts) => {
+      responses.push({ data, code: opts?.code || 200 });
+      return { data, code: opts?.code || 200 };
+    },
+    _responses: responses,
+  };
+}
+
+function makeManager(configOverrides) {
+  const config = {
+    parent: 'self',
+    ...configOverrides,
+  };
+  return {
+    config,
+    libraries: {}, // Not used in this route — admin comes in via libraries arg
+    isParent: () => config.parent === 'self',
+  };
+}
+
+function resetFetchMock() {
+  fetchCalls.length = 0;
+  fetchMockBehavior = () => ({ received: true });
+}
+
+// Saves and restores process.env so tests don't leak side effects
+function withEnv(envOverrides, fn) {
+  const saved = {};
+  for (const k of Object.keys(envOverrides)) {
+    saved[k] = process.env[k];
+    process.env[k] = envOverrides[k];
+  }
+  return Promise.resolve(fn()).finally(() => {
+    for (const k of Object.keys(envOverrides)) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+  });
+}
+
+module.exports = defineCases({
+  description: 'webhook/forward unit tests (mocked admin + fetch)',
+  type: 'group',
+
+  // Restore the real wonderful-fetch after this file's tests so the require-cache
+  // stub does not leak into any test file that runs later in the same process.
+  cleanup() {
+    restoreFetch();
+  },
+
+  tests: [
+    // ─── Gating ───
+
+    {
+      name: 'returns-404-when-parent-not-self',
+      async run({ assert }) {
+        await withEnv({ OMEGA_WEBHOOK_KEY: 'test-key' }, async () => {
+          resetFetchMock();
+          const ctx = makeAssistant({ query: { provider: 'sendgrid', key: 'test-key' } });
+          const Manager = makeManager({ parent: 'https://api.itwcreativeworks.com' }); // NOT 'self'
+          const admin = makeAdminMock([]);
+
+          await route({ ctx, Manager, libraries: { admin } });
+
+          assert.equal(ctx._responses.length, 1, 'should respond once');
+          assert.equal(ctx._responses[0].code, 404, 'should return 404');
+          assert.equal(fetchCalls.length, 0, 'should NOT call fetch when gated');
+        });
+      },
+    },
+
+    {
+      name: 'allows-route-when-parent-is-self',
+      async run({ assert }) {
+        await withEnv({ OMEGA_WEBHOOK_KEY: 'test-key' }, async () => {
+          resetFetchMock();
+          const ctx = makeAssistant({ query: { provider: 'sendgrid', key: 'test-key' } });
+          const Manager = makeManager({ parent: 'self' });
+          const admin = makeAdminMock([]); // No brands — but route still reaches the fan-out step
+
+          await route({ ctx, Manager, libraries: { admin } });
+
+          assert.equal(ctx._responses[0].code, 200, 'should return 200 when parent: self');
+          assert.equal(ctx._responses[0].data.forwarded, 0, 'no brands means 0 forwarded');
+        });
+      },
+    },
+
+    // ─── Auth ───
+
+    {
+      name: 'rejects-missing-provider',
+      async run({ assert }) {
+        await withEnv({ OMEGA_WEBHOOK_KEY: 'test-key' }, async () => {
+          resetFetchMock();
+          const ctx = makeAssistant({ query: { key: 'test-key' } }); // no provider
+          const Manager = makeManager();
+          const admin = makeAdminMock([]);
+
+          await route({ ctx, Manager, libraries: { admin } });
+
+          assert.equal(ctx._responses[0].code, 400, 'missing provider → 400');
+        });
+      },
+    },
+
+    {
+      name: 'rejects-missing-key',
+      async run({ assert }) {
+        await withEnv({ OMEGA_WEBHOOK_KEY: 'test-key' }, async () => {
+          resetFetchMock();
+          const ctx = makeAssistant({ query: { provider: 'sendgrid' } }); // no key
+          const Manager = makeManager();
+          const admin = makeAdminMock([]);
+
+          await route({ ctx, Manager, libraries: { admin } });
+
+          assert.equal(ctx._responses[0].code, 401, 'missing key → 401');
+        });
+      },
+    },
+
+    {
+      name: 'rejects-wrong-key',
+      async run({ assert }) {
+        await withEnv({ OMEGA_WEBHOOK_KEY: 'real-key' }, async () => {
+          resetFetchMock();
+          const ctx = makeAssistant({ query: { provider: 'sendgrid', key: 'wrong-key' } });
+          const Manager = makeManager();
+          const admin = makeAdminMock([]);
+
+          await route({ ctx, Manager, libraries: { admin } });
+
+          assert.equal(ctx._responses[0].code, 401, 'wrong key → 401');
+        });
+      },
+    },
+
+    // ─── Fan-out logic ───
+
+    {
+      name: 'derives-api-url-from-brand-url-and-fans-out',
+      async run({ assert }) {
+        await withEnv({ OMEGA_WEBHOOK_KEY: 'test-key' }, async () => {
+          resetFetchMock();
+          const body = [{ sg_event_id: 'evt1', event: 'group_unsubscribe', email: 't@example.com' }];
+          const ctx = makeAssistant({
+            query: { provider: 'sendgrid', key: 'test-key' },
+            body,
+          });
+          const Manager = makeManager();
+          const admin = makeAdminMock([
+            { id: 'somiibo', data: { brand: { id: 'somiibo', url: 'https://somiibo.com' } } },
+            { id: 'chatsy', data: { brand: { id: 'chatsy', url: 'https://chatsy.com' } } },
+          ]);
+
+          await route({ ctx, Manager, libraries: { admin } });
+
+          assert.equal(fetchCalls.length, 2, 'should fan out to both brands');
+          assert.equal(
+            fetchCalls[0].url,
+            'https://api.somiibo.com/omega/marketing/webhook?provider=sendgrid&key=test-key',
+            'first child URL derived correctly'
+          );
+          assert.equal(
+            fetchCalls[1].url,
+            'https://api.chatsy.com/omega/marketing/webhook?provider=sendgrid&key=test-key',
+            'second child URL derived correctly'
+          );
+          assert.deepEqual(fetchCalls[0].opts.body, body, 'raw body forwarded unchanged');
+          assert.equal(ctx._responses[0].data.succeeded, 2, '2 children succeeded');
+        });
+      },
+    },
+
+    {
+      name: 'forwards-raw-body-unchanged-for-beehiiv',
+      async run({ assert }) {
+        await withEnv({ OMEGA_WEBHOOK_KEY: 'test-key' }, async () => {
+          resetFetchMock();
+          const body = {
+            id: 'beehiiv-evt1',
+            event: 'subscription.unsubscribed',
+            email: 'x@example.com',
+            publication_id: 'pub_abc',
+          };
+          const ctx = makeAssistant({
+            query: { provider: 'beehiiv', key: 'test-key' },
+            body,
+          });
+          const Manager = makeManager();
+          const admin = makeAdminMock([
+            { id: 'somiibo', data: { brand: { id: 'somiibo', url: 'https://somiibo.com' } } },
+          ]);
+
+          await route({ ctx, Manager, libraries: { admin } });
+
+          assert.equal(fetchCalls.length, 1);
+          assert.ok(fetchCalls[0].url.includes('provider=beehiiv'), 'provider param preserved');
+          assert.deepEqual(fetchCalls[0].opts.body, body, 'raw Beehiiv body forwarded unchanged');
+        });
+      },
+    },
+
+    {
+      name: 'skips-brands-without-brand-url',
+      async run({ assert }) {
+        await withEnv({ OMEGA_WEBHOOK_KEY: 'test-key' }, async () => {
+          resetFetchMock();
+          const ctx = makeAssistant({ query: { provider: 'sendgrid', key: 'test-key' }, body: [] });
+          const Manager = makeManager();
+          const admin = makeAdminMock([
+            { id: 'somiibo', data: { brand: { id: 'somiibo', url: 'https://somiibo.com' } } },
+            { id: 'partial-brand', data: { brand: { id: 'partial-brand' /* no url */ } } },
+            { id: 'no-brand-key', data: { /* no brand at all */ } },
+          ]);
+
+          await route({ ctx, Manager, libraries: { admin } });
+
+          assert.equal(fetchCalls.length, 1, 'only the brand with a URL should be fanned to');
+          assert.ok(fetchCalls[0].url.includes('api.somiibo.com'), 'somiibo was the one called');
+        });
+      },
+    },
+
+    {
+      name: 'failure-isolation-one-bad-child-does-not-break-others',
+      async run({ assert }) {
+        await withEnv({ OMEGA_WEBHOOK_KEY: 'test-key' }, async () => {
+          resetFetchMock();
+          fetchMockBehavior = (url) => {
+            if (url.includes('chatsy.com')) {
+              throw new Error('connection refused');
+            }
+            return { received: true };
+          };
+
+          const ctx = makeAssistant({ query: { provider: 'sendgrid', key: 'test-key' }, body: [] });
+          const Manager = makeManager();
+          const admin = makeAdminMock([
+            { id: 'somiibo', data: { brand: { id: 'somiibo', url: 'https://somiibo.com' } } },
+            { id: 'chatsy', data: { brand: { id: 'chatsy', url: 'https://chatsy.com' } } },
+            { id: 'dashqr', data: { brand: { id: 'dashqr', url: 'https://dashqr.com' } } },
+          ]);
+
+          await route({ ctx, Manager, libraries: { admin } });
+
+          assert.equal(fetchCalls.length, 3, 'all 3 children attempted');
+          const response = ctx._responses[0];
+          assert.equal(response.code, 200, 'response is still 200 — provider should not retry parent');
+          assert.equal(response.data.succeeded, 2, '2 children succeeded');
+          assert.equal(response.data.failed, 1, '1 child failed');
+          assert.ok(response.data.failures, 'failures array populated');
+          assert.equal(response.data.failures[0].brandId, 'chatsy', 'failure entry names the brand');
+        });
+      },
+    },
+
+    {
+      name: 'invalid-brand-url-counted-as-failure-not-thrown',
+      async run({ assert }) {
+        await withEnv({ OMEGA_WEBHOOK_KEY: 'test-key' }, async () => {
+          resetFetchMock();
+          const ctx = makeAssistant({ query: { provider: 'sendgrid', key: 'test-key' }, body: [] });
+          const Manager = makeManager();
+          const admin = makeAdminMock([
+            { id: 'somiibo', data: { brand: { id: 'somiibo', url: 'https://somiibo.com' } } },
+            { id: 'broken', data: { brand: { id: 'broken', url: 'not-a-valid-url' } } },
+          ]);
+
+          await route({ ctx, Manager, libraries: { admin } });
+
+          const response = ctx._responses[0];
+          assert.equal(response.code, 200, 'route still returns 200');
+          assert.equal(response.data.succeeded, 1, 'somiibo succeeded');
+          assert.equal(response.data.failed, 1, 'broken brand counted as failed');
+          assert.equal(fetchCalls.length, 1, 'only the valid URL was actually fetched');
+        });
+      },
+    },
+
+    {
+      name: 'self-is-included-in-fanout',
+      async run({ assert }) {
+        // The parent's own brand IS expected to be in the brands collection.
+        // It should be fanned to via HTTP like any other brand, so its own
+        // @omega.js/backend processes its own user updates the same way as siblings.
+        await withEnv({ OMEGA_WEBHOOK_KEY: 'test-key' }, async () => {
+          resetFetchMock();
+          const ctx = makeAssistant({ query: { provider: 'sendgrid', key: 'test-key' }, body: [] });
+          const Manager = makeManager({ brand: { id: 'itw-creative-works' } });
+          const admin = makeAdminMock([
+            { id: 'itw-creative-works', data: { brand: { id: 'itw-creative-works', url: 'https://itwcreativeworks.com' } } },
+            { id: 'somiibo', data: { brand: { id: 'somiibo', url: 'https://somiibo.com' } } },
+          ]);
+
+          await route({ ctx, Manager, libraries: { admin } });
+
+          assert.equal(fetchCalls.length, 2, 'parent fans out to ALL brands including itself');
+          assert.ok(
+            fetchCalls.some(c => c.url.includes('api.itwcreativeworks.com')),
+            'self IS in the fan-out target list'
+          );
+        });
+      },
+    },
+
+    {
+      name: 'zero-brands-handled-gracefully',
+      async run({ assert }) {
+        await withEnv({ OMEGA_WEBHOOK_KEY: 'test-key' }, async () => {
+          resetFetchMock();
+          const ctx = makeAssistant({ query: { provider: 'sendgrid', key: 'test-key' }, body: [] });
+          const Manager = makeManager();
+          const admin = makeAdminMock([]);
+
+          await route({ ctx, Manager, libraries: { admin } });
+
+          assert.equal(fetchCalls.length, 0);
+          assert.equal(ctx._responses[0].code, 200, 'still 200 with no brands');
+          assert.equal(ctx._responses[0].data.forwarded, 0);
+        });
+      },
+    },
+  ],
+});

package/test/helpers/wipe-auth-project.test.js

@@ -0,0 +1,143 @@
+/**
+ * Test: the wipe's auth bulk-clear names the project it is actually wiping
+ * ([#292](https://github.com/Omega-JS-Stack/omega/issues/292)).
+ *
+ * `deleteTestUsers` clears the auth store through the emulator's bulk-clear
+ * REST API, whose URL names a PROJECT — and the emulator answers 200 for a
+ * project it has never heard of. The id came from `GCLOUD_PROJECT || 'demo-test'`
+ * while the runner's env never set GCLOUD_PROJECT, so every run cleared the
+ * empty `demo-test` store, reported "61 deleted", and left the real project's
+ * accounts standing. Ordinary personas masked it (createAccount deletes before
+ * creating); the import-only google personas did not.
+ *
+ * Run: npx omega test backend:helpers/wipe-auth-project
+ *
+ * Real everything: the REAL Auth emulator's own account store, read through the
+ * same REST surface the wipe deletes through, and the REAL admin app the runner
+ * booted. Non-destructive on purpose — the suite's personas (and the api keys
+ * the runner cached from them) must survive this file.
+ */
+const { TEST_ACCOUNTS, resolveWipeProjectId } = require('../../dist/test/test-accounts.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+// The project id the wipe fell back to before the fix — the store it cleared
+// every run.
+const HARDCODED_DEFAULT = 'demo-test';
+
+/**
+ * The emulator's account store FOR ONE PROJECT — the admin query surface, whose
+ * project path is the same one the bulk clear deletes through
+ * (`DELETE /emulator/v1/projects/<id>/accounts`; that path serves no GET).
+ * The emulator keeps a separate store per project id, which is the whole point:
+ * the wipe's URL decides WHICH store it empties.
+ * @param {string} projectId - The project whose store to read.
+ * @returns {Promise<string[]>} The uids it holds.
+ */
+async function listEmulatorAccounts(projectId) {
+  const url = `http://${process.env.FIREBASE_AUTH_EMULATOR_HOST}/identitytoolkit.googleapis.com/v1/projects/${projectId}/accounts:query`;
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: { Authorization: 'Bearer owner', 'Content-Type': 'application/json' },
+    body: '{}',
+  });
+
+  if (!response.ok) {
+    return [];
+  }
+
+  const body = await response.json();
+  return (body.userInfo || []).map((account) => account.localId);
+}
+
+/**
+ * The message a call throws, '' when it returns — a thrown-message matcher
+ * keeps these red-capable (a renamed export would throw a TypeError and still
+ * "throw", but not with this message).
+ * @param {Function} fn - The call under test.
+ * @returns {string} The error message, or '' when nothing threw.
+ */
+function messageOf(fn) {
+  try {
+    fn();
+    return '';
+  } catch (error) {
+    return error.message;
+  }
+}
+
+module.exports = defineCases({
+  description: 'the auth bulk-clear targets THIS project, and fails loudly when it cannot tell',
+  type: 'group',
+  auth: 'none',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'the-runner-env-carries-this-projects-id',
+      async run({ assert, config }) {
+        // The root cause: the runner's child env (buildTestCommand) shipped the
+        // emulator hosts but never the project they belong to.
+        assert.equal(
+          process.env.GCLOUD_PROJECT,
+          config.cloud.config.projectId,
+          'the test runner env must name the project the emulator booted with',
+        );
+      },
+    },
+
+    {
+      name: 'the-wiped-store-is-the-one-holding-the-personas',
+      async run({ assert, Manager, config }) {
+        const admin = Manager.libraries.admin;
+        const projectId = resolveWipeProjectId(admin);
+
+        assert.equal(projectId, config.cloud.config.projectId);
+
+        // The store the wipe's URL names holds the accounts the wipe exists to
+        // remove. This is the assertion the old id failed.
+        const targeted = await listEmulatorAccounts(projectId);
+        assert.equal(
+          targeted.includes(TEST_ACCOUNTS.basic.uid),
+          true,
+          `project "${projectId}" should hold the seeded personas the wipe clears`,
+        );
+
+        // ...and the id it used to fall back to names a store none of them live
+        // in, which is why clearing it returned 200 and removed nothing.
+        const fallback = await listEmulatorAccounts(HARDCODED_DEFAULT);
+        assert.equal(
+          fallback.includes(TEST_ACCOUNTS.basic.uid),
+          false,
+          `project "${HARDCODED_DEFAULT}" is not where this run's accounts live`,
+        );
+      },
+    },
+
+    {
+      name: 'a-project-id-disagreement-throws-instead-of-clearing-a-stranger',
+      async run({ assert, Manager, config }) {
+        const admin = Manager.libraries.admin;
+
+        // A stale GCLOUD_PROJECT from another brand's shell would send the wipe
+        // at a store this process never reads or writes — success there is the
+        // #292 failure wearing a different hat, so it throws.
+        assert.match(
+          messageOf(() => resolveWipeProjectId(admin, { GCLOUD_PROJECT: 'demo-somebody-else' })),
+          /demo-somebody-else/,
+          'a project id that disagrees with the admin app must abort the wipe',
+        );
+
+        // Agreement is the normal case, from either source alone.
+        assert.equal(resolveWipeProjectId(admin, {}), config.cloud.config.projectId);
+        assert.equal(
+          resolveWipeProjectId(undefined, { GCLOUD_PROJECT: config.cloud.config.projectId }),
+          config.cloud.config.projectId,
+        );
+
+        // Nothing to resolve is never a silent default — the old `|| 'demo-test'`
+        // is exactly how a wipe with no identity reported success.
+        assert.match(messageOf(() => resolveWipeProjectId(undefined, {})), /project id/);
+      },
+    },
+  ],
+});

package/test/mcp/discovery.test.js

@@ -0,0 +1,52 @@
+/**
+ * Test: MCP OAuth discovery endpoints
+ * Tests .well-known/oauth-authorization-server and .well-known/oauth-protected-resource
+ *
+ * Run: npx omega test backend:mcp/discovery
+ */
+const fetch = require('wonderful-fetch');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+module.exports = defineCases({
+  description: 'MCP OAuth discovery endpoints',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'oauth-authorization-server returns valid metadata',
+      async run({ assert, config }) {
+        const response = await fetch(`${config.apiUrl}/.well-known/oauth-authorization-server`, {
+          method: 'GET',
+          response: 'json',
+          timeout: 10000,
+        });
+
+        assert.ok(response, 'Discovery endpoint should return a response');
+        assert.ok(response.issuer, 'Should have issuer');
+        assert.ok(response.authorization_endpoint, 'Should have authorization_endpoint');
+        assert.ok(response.token_endpoint, 'Should have token_endpoint');
+        assert.ok(response.authorization_endpoint.includes('/omega/mcp/authorize'), 'authorization_endpoint should point to mcp/authorize');
+        assert.ok(response.token_endpoint.includes('/omega/mcp/token'), 'token_endpoint should point to mcp/token');
+        assert.ok(response.response_types_supported.includes('code'), 'Should support code response type');
+        assert.ok(response.code_challenge_methods_supported.includes('S256'), 'Should support PKCE S256');
+      },
+    },
+
+    {
+      name: 'oauth-protected-resource returns valid metadata',
+      async run({ assert, config }) {
+        const response = await fetch(`${config.apiUrl}/.well-known/oauth-protected-resource`, {
+          method: 'GET',
+          response: 'json',
+          timeout: 10000,
+        });
+
+        assert.ok(response, 'Protected resource endpoint should return a response');
+        assert.ok(response.resource, 'Should have resource');
+        assert.ok(response.resource.includes('/omega/mcp'), 'resource should point to MCP endpoint');
+        assert.ok(Array.isArray(response.authorization_servers), 'Should have authorization_servers array');
+        assert.ok(response.authorization_servers.length > 0, 'Should have at least one authorization server');
+      },
+    },
+  ],
+});