@omega.js/backend 0.1.0

package/test/routes/verts/serve.test.js

@@ -0,0 +1,185 @@
+/**
+ * Test: GET /omega/verts/serve — public serve route round-trips
+ *
+ * Uses native fetch (not the JSON http client) because the route answers
+ * with a self-contained HTML page. Docs are seeded directly via the admin
+ * firestore helper; the emulator's serve route reads fresh (TTL 0 under
+ * FIRESTORE_EMULATOR_HOST).
+ *
+ * Run: npx omega test backend:routes/verts/serve
+ */
+
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+async function seedAds(firestore) {
+  // Intra-run isolation: wipe docs left by earlier suites (cache/crud/redirect
+  // seed verts too) so the no-fill assertion is deterministic
+  const existing = await firestore.collection('verts').get();
+
+  for (const doc of existing.docs) {
+    await doc.ref.delete();
+  }
+
+  // Idempotent seed — every vert blacklists nofill.example so the no-fill
+  // path has a deterministic parent
+  await firestore.set('verts/serve-open', {
+    id: 'serve-open',
+    enabled: true,
+    title: 'Open Vert',
+    description: 'A vert with no targeting.',
+    button: 'Learn more',
+    link: 'https://open-shop.example/products',
+    image: '',
+    footer: 'Sponsored by Open Shop',
+    weight: 1,
+    targeting: { sites: [], categories: [], keywords: [] },
+    whitelist: [],
+    blacklist: ['nofill.example'],
+  });
+  await firestore.set('verts/serve-target', {
+    id: 'serve-target',
+    enabled: true,
+    title: 'Music Tools Vert',
+    link: 'https://music-shop.example/tools',
+    weight: 1,
+    targeting: { sites: [], categories: ['music'], keywords: ['audio'] },
+    whitelist: [],
+    blacklist: ['nofill.example'],
+  });
+  await firestore.set('verts/serve-self', {
+    id: 'serve-self',
+    enabled: true,
+    title: 'Self Vert',
+    link: 'https://self-test.example/promo',
+    weight: 1,
+    whitelist: [],
+    blacklist: ['nofill.example'],
+  });
+  await firestore.set('verts/serve-xss', {
+    id: 'serve-xss',
+    enabled: true,
+    title: '<script>alert("xss")</script>',
+    description: '"><img src=x onerror=alert(1)>',
+    link: 'https://xss-shop.example/x',
+    weight: 1,
+    whitelist: [],
+    blacklist: ['nofill.example'],
+  });
+}
+
+module.exports = defineCases({
+  description: 'Verts serve route (HTML unit)',
+  type: 'suite',
+  tests: [
+    {
+      name: 'serves-self-contained-html-unit',
+      timeout: 30000,
+      async run({ assert, firestore, config }) {
+        await seedAds(firestore);
+
+        const response = await fetch(`${config.apiUrl}/omega/verts/serve?parent=site.example&brand=site-brand&vertId=serve-open`);
+        const body = await response.text();
+
+        assert.equal(response.status, 200, 'Serve should return 200');
+        assert.match(response.headers.get('content-type') || '', /text\/html/, 'Response should be HTML');
+        assert.ok(body.includes('Open Vert'), 'Unit should render the vert title');
+        assert.ok(body.includes('Learn more'), 'Unit should render the button');
+        assert.ok(body.includes('Sponsored by Open Shop'), 'Unit should render the footer');
+        assert.ok(body.includes('omega-vert:set-dimensions'), 'Unit should report dimensions via postMessage');
+        assert.ok(body.includes('omega-vert:click'), 'Unit should forward clicks via postMessage');
+        assert.ok(body.includes('/omega/verts/redirect?id=serve-open'), 'Click link should point at the redirect route');
+        assert.ok(body.includes('brand=site-brand'), 'The redirect URL should carry the host brand id (the click utm_source)');
+        assert.ok(body.includes('https://site.example'), 'postMessage should target the parent origin (origin-checked)');
+        assert.ok(!body.includes('setInterval') && !body.includes('setTimeout'), 'Unit must have NO self-refresh timers (host owns lifecycle)');
+        assert.ok(!body.includes('<script src') && !body.includes('<link'), 'Unit must be self-contained (no external scripts/styles)');
+      },
+    },
+
+    {
+      name: 'postmessage-target-preserves-dev-port',
+      timeout: 30000,
+      async run({ assert, config }) {
+        // A dev site's parent host carries a port (localhost:4100). The unit's
+        // postMessage target origin must keep it — a portless 'http://localhost'
+        // origin makes the browser silently DROP every dimension report, so
+        // house verts would always collapse as no-fill in local dev (found by
+        // the verts step 6 company-mode proof).
+        const response = await fetch(`${config.apiUrl}/omega/verts/serve?parent=localhost:4100&vertId=serve-open`);
+        const body = await response.text();
+
+        assert.equal(response.status, 200, 'Serve should return 200');
+        assert.ok(body.includes('"http://localhost:4100"'), 'postMessage target origin should preserve the dev port');
+        assert.ok(!body.includes('"http://localhost"'), 'portless localhost origin must not appear as the target');
+      },
+    },
+
+    {
+      name: 'tag-matching-serves-top-scorer',
+      timeout: 30000,
+      async run({ assert, config }) {
+        // serve-target is the only vert scoring > 0 for these tags — deterministic
+        for (let i = 0; i < 5; i++) {
+          const response = await fetch(`${config.apiUrl}/omega/verts/serve?parent=site.example&tags=music,audio`);
+          const body = await response.text();
+
+          assert.equal(response.status, 200, 'Serve should return 200');
+          assert.ok(body.includes('id=serve-target'), 'Top-scoring targeted vert should always win');
+        }
+      },
+    },
+
+    {
+      name: 'never-serves-an-vert-on-its-own-host',
+      timeout: 30000,
+      async run({ assert, config }) {
+        // Pin the self-linked vert while requesting from its own link host —
+        // the pin is ineligible so another vert (or none) must serve
+        const response = await fetch(`${config.apiUrl}/omega/verts/serve?parent=self-test.example&vertId=serve-self`);
+        const body = response.status === 200 ? await response.text() : '';
+
+        assert.ok(!body.includes('id=serve-self'), 'A vert must never serve on its own link host');
+      },
+    },
+
+    {
+      name: 'no-eligible-verts-returns-204',
+      timeout: 30000,
+      async run({ assert, config }) {
+        // Every seeded vert blacklists nofill.example
+        const response = await fetch(`${config.apiUrl}/omega/verts/serve?parent=nofill.example`);
+
+        assert.equal(response.status, 204, 'No fill should return 204');
+      },
+    },
+
+    {
+      name: 'vert-content-is-escaped',
+      timeout: 30000,
+      async run({ assert, config }) {
+        const response = await fetch(`${config.apiUrl}/omega/verts/serve?parent=site.example&vertId=serve-xss`);
+        const body = await response.text();
+
+        assert.equal(response.status, 200, 'Serve should return 200');
+        assert.ok(!body.includes('<script>alert'), 'Vert title must not inject raw script tags');
+        assert.ok(!body.includes('<img src=x'), 'Vert description must not inject raw elements');
+        assert.ok(body.includes('&lt;script&gt;'), 'Vert title should render escaped');
+        assert.ok(body.includes('&lt;img src=x'), 'Vert description should render escaped');
+      },
+    },
+
+    {
+      name: 'theme-and-size-params-are-accepted',
+      timeout: 30000,
+      async run({ assert, config }) {
+        const response = await fetch(`${config.apiUrl}/omega/verts/serve?parent=site.example&vertId=serve-open&width=300&height=250&theme=dark`);
+        const body = await response.text();
+
+        assert.equal(response.status, 200, 'Serve should return 200');
+        assert.ok(body.includes('data-theme="dark"'), 'Theme pin should render on the page');
+        assert.ok(body.includes('max-width: 300px'), 'Width hint should apply');
+        // Content-sized contract: the card carries NO baked height (the HOST
+        // clamps to the preset); height feeds only the compact/stacked branches
+        assert.equal(body.includes('max-height'), false, 'The card is content-sized, never height-capped in the document');
+      },
+    },
+  ],
+});

package/test/routes/verts/unit-document.test.js

@@ -0,0 +1,117 @@
+/**
+ * Test: the vert unit document backend routes hand out
+ *
+ * renderVertUnit is a thin mapping onto the ONE renderer in @omega.js/client
+ * (modules/vert-document.js) — the same function the client's terminal promo
+ * lane calls. These tests cover the mapping (stored vert fields → renderer
+ * options), the escaping posture, and the parity itself: no unit template may
+ * live in this package.
+ *
+ * Run: npx omega test backend:routes/verts/unit-document
+ */
+const fs = require('fs');
+const path = require('path');
+const { renderVertUnit } = require('../../../dist/manager/routes/verts/utils.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+const UTILS_PATH = path.join(__dirname, '../../../dist/manager/routes/verts/utils.js');
+
+function makeVert(overrides) {
+  return {
+    id: 'unit-a',
+    enabled: true,
+    title: 'Open Vert',
+    description: 'A vert with no targeting.',
+    button: 'Learn more',
+    link: 'https://open-shop.example/products',
+    image: '',
+    footer: 'Sponsored by Open Shop',
+    ...overrides,
+  };
+}
+
+module.exports = defineCases({
+  description: 'Verts unit document (shared renderer)',
+  type: 'group',
+  tests: [
+    {
+      name: 'renders-the-media-row-from-the-stored-vert',
+      async run({ assert }) {
+        const html = await renderVertUnit({
+          vert: makeVert(),
+          redirectUrl: 'https://api.example/omega/verts/redirect?id=unit-a',
+          parentOrigin: 'https://site.example',
+          height: 250,
+        });
+
+        assert.ok(html.startsWith('<!DOCTYPE html>'), 'Should be a complete document');
+        assert.ok(html.includes('<span class="omega-vert-title">Open Vert</span>'), 'Title should render');
+        assert.ok(html.includes('<span class="omega-vert-description">A vert with no targeting.</span>'), 'Description should render');
+        assert.ok(html.includes('<span class="omega-vert-button">Learn more</span>'), 'Button should render as the cta');
+        assert.ok(html.includes('<span class="omega-vert-label">Sponsored by Open Shop</span>'), 'Footer should render as the muted label');
+        assert.ok(html.includes('class="omega-vert-row"'), 'Layout should be the media row');
+        assert.ok(html.includes('class="omega-vert-rule"'), 'Row and footer should be split by the hairline');
+        assert.ok(html.includes('href="https://api.example/omega/verts/redirect?id=unit-a"'), 'Link should point at the redirect route');
+        assert.ok(html.includes('var TARGET_ORIGIN = "https://site.example";'), 'Messages should target the parent origin');
+        assert.ok(html.includes('var VERT_ID = "unit-a";'), 'Messages should carry the vert id');
+        assert.ok(!html.includes('height: 250px'), 'The card should be content-sized, not stretched to the slot');
+      },
+    },
+
+    {
+      name: 'labels-a-vert-with-no-footer-plainly-sponsored',
+      async run({ assert }) {
+        const html = await renderVertUnit({ vert: makeVert({ footer: '' }), redirectUrl: 'https://api.example/r' });
+
+        assert.ok(html.includes('<span class="omega-vert-label">Sponsored</span>'), 'Label should fall back to Sponsored');
+      },
+    },
+
+    {
+      name: 'image-renders-only-for-http-sources',
+      async run({ assert }) {
+        const withImage = await renderVertUnit({ vert: makeVert({ image: 'https://cdn.example/a.png' }), redirectUrl: 'https://api.example/r' });
+        const withJunk = await renderVertUnit({ vert: makeVert({ image: 'javascript:alert(1)' }), redirectUrl: 'https://api.example/r' });
+        const without = await renderVertUnit({ vert: makeVert(), redirectUrl: 'https://api.example/r' });
+
+        assert.ok(withImage.includes('<img class="omega-vert-image" src="https://cdn.example/a.png" alt="">'), 'An http image should render as the thumbnail');
+        assert.ok(!withJunk.includes('<img'), 'A non-http image source should never render');
+        assert.ok(!without.includes('<span class="omega-vert-thumb">'), 'No image means no thumbnail slot');
+      },
+    },
+
+    {
+      name: 'served-units-keep-the-neutral-ink-accent',
+      async run({ assert }) {
+        const html = await renderVertUnit({ vert: makeVert(), redirectUrl: 'https://api.example/r' });
+
+        assert.ok(html.includes('--omega-vert-accent: #1a1a1a;'), 'Served units should default to the neutral ink accent');
+        assert.ok(!html.includes('#4f46e5'), 'The omega indigo belongs to the promo only');
+      },
+    },
+
+    {
+      name: 'vert-data-stays-escaped',
+      async run({ assert }) {
+        const html = await renderVertUnit({
+          vert: makeVert({ title: '<script>alert("xss")</script>', description: '"><img src=x onerror=alert(1)>' }),
+          redirectUrl: 'https://api.example/r',
+        });
+
+        assert.ok(!html.includes('<script>alert'), 'Injected markup should never survive');
+        assert.ok(html.includes('&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'), 'Title should be escaped');
+        assert.ok(html.includes('&quot;&gt;&lt;img src=x onerror=alert(1)&gt;'), 'Description should be escaped');
+      },
+    },
+
+    {
+      name: 'no-second-unit-template-lives-in-this-package',
+      async run({ assert }) {
+        const source = fs.readFileSync(UTILS_PATH, 'utf8');
+
+        assert.ok(!source.includes('<!DOCTYPE'), 'The backend must hold no unit template of its own');
+        assert.ok(source.includes('@omega.js/client/modules/vert-document.js'), 'The backend should call the one shared renderer');
+      },
+    },
+  ],
+});

package/test/rules/_environment.js

@@ -0,0 +1,66 @@
+/**
+ * Shared plumbing for the rules suites that compile their OWN ruleset
+ * ([#353](https://github.com/Omega-JS-Stack/omega/issues/353)).
+ *
+ * Everything else in test/rules/ runs against the fixture project's compiled
+ * artifact (the shipped seed, no brand rules). These suites prove what a BRAND
+ * file does to that artifact, so each one compiles a brand source exactly as
+ * `omega build` does and loads the result into its own emulator project.
+ *
+ * `_`-prefixed, so the runner never discovers it as a suite.
+ */
+const jetpack = require('fs-jetpack');
+const { initializeTestEnvironment } = require('@firebase/rules-unit-testing');
+const { BRAND_RULES_SEED, compileRules } = require('../../dist/cli/utils/compile-rules.js');
+
+// The line the seed reserves for a brand's own rules.
+const YOUR_RULES_MARKER = '// ─── Your rules ─';
+
+/**
+ * The shipped seed with `rules` written into its own rules region — the file a
+ * brand would have after typing them in.
+ * @param {string} [rules] - Rules text, indented for the documents block.
+ * @returns {string}
+ */
+function brandSourceWith(rules) {
+  const seed = jetpack.read(BRAND_RULES_SEED);
+  if (!rules) {
+    return seed;
+  }
+
+  const lineEnd = seed.indexOf('\n', seed.indexOf(YOUR_RULES_MARKER));
+
+  return `${seed.slice(0, lineEnd + 1)}${rules}\n${seed.slice(lineEnd + 1)}`;
+}
+
+/**
+ * Compile a brand source against the framework half, exactly as a stage does.
+ * @param {string} [rules] - Rules text, indented for the documents block.
+ * @returns {string} The compiled ruleset.
+ */
+function compiledWith(rules) {
+  return compileRules({ brandSource: brandSourceWith(rules) }).compiled;
+}
+
+/**
+ * A rules-testing environment on its own project id, carrying `rules`.
+ * @param {string} projectId
+ * @param {string} rules - A whole compiled ruleset.
+ * @returns {Promise<object>}
+ */
+async function environment(projectId, rules) {
+  const [host, port] = (process.env.FIRESTORE_EMULATOR_HOST || '127.0.0.1:8080').split(':');
+
+  const env = await initializeTestEnvironment({
+    projectId,
+    firestore: { host, port: Number(port), rules },
+  });
+
+  // Rules-only projects are shared with whatever ran before on the same
+  // emulator, and a create test that finds a document is not a create test.
+  await env.clearFirestore();
+
+  return env;
+}
+
+module.exports = { brandSourceWith, compiledWith, environment };

package/test/rules/brand-merge.test.js

@@ -0,0 +1,195 @@
+/**
+ * Test: a brand TIGHTENS a framework rule by writing an ordinary match block
+ * ([#353](https://github.com/Omega-JS-Stack/omega/issues/353)).
+ *
+ * Firestore ORs `allow` across sibling match blocks, so a brand's own
+ * `match /users/{uid}` can only ever WIDEN access. Merge-by-match is the
+ * answer: the compiler folds a brand block into the framework block with the
+ * same canonicalized path, ANDing the brand's condition onto every op both
+ * declare. The v2 hooks (`protectedFields()`, `canWriteUser()`) are gone.
+ *
+ * The proof is StudyMonkey's case: `users/{uid}.xp` (an XP bank the backend
+ * awards transactionally) must be un-writable by a signed-in client once the
+ * brand protects it — while a brand that writes nothing keeps today's exact
+ * behaviour.
+ *
+ * Each case compiles its own ruleset and loads it into its OWN emulator
+ * project, so every behaviour is proven against the real Firestore rules
+ * engine in one run.
+ *
+ * Run: npx omega test backend:rules/brand-merge
+ */
+const { assertSucceeds, assertFails } = require('@firebase/rules-unit-testing');
+const { compiledWith, environment } = require('./_environment.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+const UID = 'brand-merge-user';
+
+/**
+ * Seed the user doc (rules off), then hand back the signed-in client.
+ * @param {object} env
+ * @returns {Promise<object>}
+ */
+async function seedUser(env) {
+  await env.withSecurityRulesDisabled(async (context) => {
+    await context.firestore().doc(`users/${UID}`).set({
+      auth: { uid: UID, email: `${UID}@test.com` },
+      roles: {},
+      xp: { total: 0 },
+      profile: { displayName: 'Before' },
+    });
+  });
+
+  return env.authenticatedContext(UID, { email: `${UID}@test.com` }).firestore();
+}
+
+module.exports = defineCases({
+  description: 'Firestore rules: a brand match block merges into the framework block it names',
+  type: 'group',
+  timeout: 30000,
+
+  tests: [
+    // The file every brand starts from: writing nothing changes nothing.
+    {
+      name: 'the-shipped-seed-keeps-todays-behavior',
+      auth: 'none',
+
+      async run() {
+        const env = await environment('demo-merge-seed', compiledWith());
+
+        try {
+          const db = await seedUser(env);
+
+          await assertSucceeds(db.doc(`users/${UID}`).set({ xp: { total: 500 } }, { merge: true }));
+          await assertSucceeds(db.doc(`users/${UID}`).set({ profile: { displayName: 'After' } }, { merge: true }));
+          // The framework's own keys stay the framework's
+          await assertFails(db.doc(`users/${UID}`).set({ roles: { admin: true } }, { merge: true }));
+        } finally {
+          await env.cleanup();
+        }
+      },
+    },
+
+    // StudyMonkey's case: the brand protects `xp` in its own users block, and
+    // the client write the framework alone allowed now dies.
+    {
+      name: 'a-merged-brand-condition-denies-what-the-framework-alone-allowed',
+      auth: 'none',
+
+      async run() {
+        const env = await environment('demo-merge-tighten', compiledWith([
+          '    match /users/{uid} {',
+          '      allow create, update: if !isWritingAny([\'xp\']);',
+          '    }',
+        ].join('\n')));
+
+        try {
+          const db = await seedUser(env);
+
+          await assertFails(db.doc(`users/${UID}`).set({ xp: { total: 500 } }, { merge: true }));
+          // Fields are TOP-LEVEL: naming `xp` protects everything under it
+          await assertFails(db.doc(`users/${UID}`).update({ 'xp.total': 500 }));
+          // …and nothing else tightened: an untouched field still writes
+          await assertSucceeds(db.doc(`users/${UID}`).set({ profile: { displayName: 'After' } }, { merge: true }));
+          // Reads are a different op — the brand said nothing about them
+          await assertSucceeds(db.doc(`users/${UID}`).get());
+        } finally {
+          await env.cleanup();
+        }
+      },
+    },
+
+    // The whole-rule gate the retired `canWriteUser()` hook used to buy: an
+    // ordinary condition on the same op now does it.
+    {
+      name: 'a-merged-condition-can-gate-the-whole-write-rule',
+      auth: 'none',
+
+      async run() {
+        const env = await environment('demo-merge-gate', compiledWith([
+          '    match /users/{uid} {',
+          '      allow create, update: if false;',
+          '    }',
+        ].join('\n')));
+
+        try {
+          const db = await seedUser(env);
+
+          await assertFails(db.doc(`users/${UID}`).set({ profile: { displayName: 'After' } }, { merge: true }));
+          await assertSucceeds(db.doc(`users/${UID}`).get());
+        } finally {
+          await env.cleanup();
+        }
+      },
+    },
+
+    // A brand's wildcard name is its own business: the block merges on the
+    // PATH, and the compiler renames the variable inside the folded condition.
+    {
+      name: 'a-brand-wildcard-name-canonicalizes-onto-the-framework-block',
+      auth: 'none',
+
+      async run() {
+        const env = await environment('demo-merge-wildcard', compiledWith([
+          '    match /users/{userId} {',
+          '      allow create, update: if isUser(userId) && !isWritingAny([\'xp\']);',
+          '',
+          '      match /journal/{entryId} {',
+          '        allow read, write: if isUser(userId);',
+          '      }',
+          '    }',
+        ].join('\n')));
+
+        try {
+          const db = await seedUser(env);
+
+          // The renamed `userId` still resolves — a broken rename would error
+          // and deny every write, so this succeeding IS the rename proof.
+          await assertSucceeds(db.doc(`users/${UID}`).set({ profile: { displayName: 'After' } }, { merge: true }));
+          await assertFails(db.doc(`users/${UID}`).set({ xp: { total: 500 } }, { merge: true }));
+          // The nested block spliced in and reads the renamed variable too
+          await assertSucceeds(db.doc(`users/${UID}/journal/today`).set({ text: 'hello' }));
+          await assertFails(db.doc('users/somebody-else/journal/today').set({ text: 'nope' }));
+        } finally {
+          await env.cleanup();
+        }
+      },
+    },
+
+    // Paths the framework never declares are the brand's alone, and an op only
+    // the brand declares appends — that op widens, exactly as a sibling block
+    // always did.
+    {
+      name: 'a-brand-only-collection-and-a-brand-only-op-keep-working',
+      auth: 'none',
+
+      async run() {
+        const env = await environment('demo-merge-brand-only', compiledWith([
+          '    match /leaderboards/{id} {',
+          '      allow read: if true;',
+          '      allow write: if isAdmin();',
+          '    }',
+          '',
+          '    match /users/{uid} {',
+          '      allow delete: if isUser(uid);',
+          '    }',
+        ].join('\n')));
+
+        try {
+          const db = await seedUser(env);
+
+          // Brand-only path: through untouched, calling a framework helper
+          await assertSucceeds(db.doc('leaderboards/weekly').get());
+          await assertFails(db.doc('leaderboards/weekly').set({ hacked: true }));
+
+          // Brand-only op: the framework declares no `delete`, so this grants it
+          await assertSucceeds(db.doc(`users/${UID}`).delete());
+          // …and the ops the framework DOES declare are untouched by it
+          await assertFails(db.doc('users/somebody-else').set({ profile: {} }, { merge: true }));
+        } finally {
+          await env.cleanup();
+        }
+      },
+    },
+  ],
+});