@omega.js/backend 0.1.0

package/test/events/auth-signup-limit.test.js

@@ -0,0 +1,142 @@
+/**
+ * Test: events/auth resolveSignupLimit(), the per-IP daily signup cap (#133)
+ *
+ * Run: npx omega test backend:events/auth-signup-limit
+ *
+ * before-create.js rate-limits signups per client IP. The cap used to be a
+ * hardcoded 2, which shared egress (NAT/CGNAT/VPN) crosses with legitimate
+ * users. It now comes from config: targets.backend.auth.signup.maxPerIpPerDay,
+ * overlaid at the top level by the config loader like every other target key.
+ *
+ * Pure function (zero I/O), called directly per the test-framework contract.
+ */
+const path = require('path');
+const { loadConfig } = require('../../dist/vendor/config/index.js');
+const { resolveSignupLimit, DEFAULT_MAX_SIGNUPS_PER_DAY } = require('../../dist/manager/events/auth/utils.js');
+const beforeCreate = require('../../dist/manager/events/auth/before-create.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+// A signup event driven straight through the REAL before-create, with ONE seam:
+// what the usage counter does when the gate calls it. That is the whole subject
+// — whether a failure that is not a rate limit is still SOLD as one.
+class HttpsError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'HttpsError';
+    this.code = code;
+  }
+}
+
+function runBeforeCreate(consume) {
+  const lines = [];
+  const record = (...args) => lines.push(args.join(' '));
+
+  const counter = {
+    attach: () => counter,
+    forKey: () => counter,
+    consume: consume,
+  };
+
+  const Manager = { config: {}, Usage: () => counter };
+
+  const ctx = {
+    log: record,
+    debug: record,
+    warn: record,
+    error: record,
+    report: (e, options) => {
+      const error = e instanceof Error ? e : new Error(e);
+      error.code = (options || {}).code || 500;
+      return error;
+    },
+  };
+
+  return beforeCreate({
+    Manager,
+    ctx,
+    user: { uid: 'user-647', email: 'someone@example.com' },
+    context: { ipAddress: '203.0.113.7' },
+    libraries: { functions: { auth: { HttpsError } } },
+  });
+}
+
+// The framework-defaults layer the Manager resolves at boot
+const TEMPLATES_DIR = path.join(__dirname, '../../templates');
+
+module.exports = defineCases({
+  description: 'resolveSignupLimit(): per-IP daily signup cap from config',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'framework-default-is-the-shipped-template-value',
+      auth: 'none',
+
+      async run({ assert }) {
+        const { config } = loadConfig(TEMPLATES_DIR, 'backend');
+
+        assert.equal(config.auth?.signup?.maxPerIpPerDay, 2, 'templates/config/omega.json5 ships the default cap');
+        assert.equal(resolveSignupLimit(config), 2, 'the shipped default resolves through the guard');
+        assert.equal(DEFAULT_MAX_SIGNUPS_PER_DAY, 2, 'the in-code fallback matches the shipped default');
+      },
+    },
+
+    {
+      name: 'configured-value-wins',
+      auth: 'none',
+
+      async run({ assert }) {
+        assert.equal(resolveSignupLimit({ auth: { signup: { maxPerIpPerDay: 25 } } }), 25);
+        assert.equal(resolveSignupLimit({ auth: { signup: { maxPerIpPerDay: 1 } } }), 1);
+      },
+    },
+
+    {
+      name: 'unconfigured-and-invalid-values-keep-the-default',
+      auth: 'none',
+
+      async run({ assert }) {
+        // Nothing configured: a config with no auth block at all
+        assert.equal(resolveSignupLimit({}), DEFAULT_MAX_SIGNUPS_PER_DAY);
+        assert.equal(resolveSignupLimit(undefined), DEFAULT_MAX_SIGNUPS_PER_DAY);
+
+        // Garbage is a validation error (@omega.js/config hard-fails it); the
+        // guard keeps the default rather than running the IP check unprotected
+        for (const value of [0, -1, 2.5, '25', null]) {
+          assert.equal(resolveSignupLimit({ auth: { signup: { maxPerIpPerDay: value } } }), DEFAULT_MAX_SIGNUPS_PER_DAY, `${value} falls back to the default`);
+        }
+      },
+    },
+    // The gate's catch used to swallow EVERYTHING consume() could throw. A
+    // Firestore outage, a programmer error, a 500 of any kind came back to the
+    // caller as "too many signups from this IP" — a diagnosis nobody could act
+    // on, and one that quietly told a legitimate user to wait a day.
+    {
+      name: 'a failure that is not a rate limit is never sold as one',
+      auth: 'none',
+
+      async run({ assert, ctx }) {
+        const boom = Object.assign(new Error('Firestore unavailable'), { code: 500 });
+
+        const thrown = await runBeforeCreate(async () => { throw boom; }).catch((e) => e);
+
+        assert.equal(thrown, boom, 'the original error propagates untouched');
+        assert.equal(thrown.name, 'Error', 'not converted into an auth HttpsError');
+      },
+    },
+
+    {
+      name: 'a real 429 still blocks the signup as resource-exhausted',
+      auth: 'none',
+
+      async run({ assert }) {
+        const refusal = Object.assign(new Error('You have used all 2 of your signups'), { code: 429 });
+
+        const thrown = await runBeforeCreate(async () => { throw refusal; }).catch((e) => e);
+
+        assert.equal(thrown.name, 'HttpsError', 'a rate limit is the one thing this catch is for');
+        assert.equal(thrown.code, 'resource-exhausted');
+      },
+    },
+  ],
+});

package/test/events/auth-trigger-log-privacy.test.js

@@ -0,0 +1,256 @@
+/**
+ * Test: the three remaining auth triggers open with the uid and nothing else
+ * ([#657](https://github.com/Omega-JS-Stack/omega/issues/657)).
+ *
+ * `beforeCreate`, `beforeSignIn` and `onDelete` each used to open with
+ * `ctx.log(..., user, context)` — the whole Firebase user record (email, display
+ * name, provider data, password hash) plus the trigger context (IP, user agent,
+ * credential) into Cloud Logging, on every signup and every sign-in. The headline
+ * is now the uid alone, the #641 shape `onCreate` already carries, and the fat
+ * payload sits one level down at `debug` — silent on a normal run, one
+ * `OMEGA_DEBUG=1` away.
+ *
+ * Pure: the log seam #632 added is `ctx` itself, so a recorder in its place reads
+ * every line the handler writes with no emulator, no admin SDK and no ports. The
+ * only stand-ins are that recorder and the Firestore/Usage doubles the handlers
+ * reach for AFTER the line under test.
+ *
+ * Note on the IP: `beforeCreate`'s rate-limit lines still name the client IP,
+ * deliberately — it is the rate limiter's KEY, not the user's identity. The line
+ * this test is about is the headline, and the headline is asserted whole.
+ *
+ * Run: npx omega test framework:events/auth-trigger-log-privacy
+ */
+const beforeCreate = require('../../dist/manager/events/auth/before-create.js');
+const beforeSignIn = require('../../dist/manager/events/auth/before-signin.js');
+const onDelete = require('../../dist/manager/events/auth/on-delete.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+const UID = '_test-657-uid';
+const EMAIL = 'leaky.person@omegajs-test.dev';
+const DISPLAY_NAME = 'Leaky Person';
+const IP = '203.0.113.9';
+
+// A UserRecord the way both trigger flavors receive it — the material that used
+// to ride the headline.
+const USER = {
+  uid: UID,
+  email: EMAIL,
+  emailVerified: true,
+  displayName: DISPLAY_NAME,
+  photoURL: 'https://cdn.omegajs-test.dev/leaky-person.png',
+  passwordHash: 'hash-657',
+  providerData: [{ providerId: 'password', uid: EMAIL, email: EMAIL, displayName: DISPLAY_NAME }],
+  metadata: { creationTime: '2026-08-30T00:00:00Z', lastSignInTime: '2026-08-30T00:00:00Z' },
+};
+
+// AuthEventContext (blocking functions): carries the IP, the user agent, the locale.
+const AUTH_CONTEXT = {
+  ipAddress: IP,
+  userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)',
+  locale: 'en-US',
+  eventId: 'event-657',
+  additionalUserInfo: { providerId: 'password', email: EMAIL, isNewUser: true },
+};
+
+// EventContext (1st-gen triggers): no IP, no user agent.
+const EVENT_CONTEXT = {
+  eventId: 'event-657',
+  eventType: 'providers/firebase.auth/eventTypes/user.delete',
+  resource: { service: 'firebaseauth.googleapis.com' },
+};
+
+// The log seam: every level the handlers write to, recorded verbatim.
+function createRecorder() {
+  const calls = { log: [], debug: [], error: [] };
+  const record = (level) => (...args) => calls[level].push(args);
+
+  return {
+    calls: calls,
+    ctx: { log: record('log'), debug: record('debug'), error: record('error') },
+  };
+}
+
+// A call as one string, the way it lands in Cloud Logging.
+function render(args) {
+  return args.map((arg) => (typeof arg === 'string' ? arg : JSON.stringify(arg))).join(' ');
+}
+
+// No hooks/auth/*.js under this dir, so the consumer hook lookup is a no-op.
+const MANAGER = { cwd: __dirname, config: {} };
+
+async function runBeforeCreate() {
+  const { calls, ctx } = createRecorder();
+
+  // The rate limiter is the handler's real path — only the Usage counter is a
+  // double: attach/forKey/consume, the #647 shape the gate calls.
+  const counter = {
+    attach: () => counter,
+    forKey: () => counter,
+    consume: async () => ({ used: 1, left: 1, day: { used: 1, left: 1 } }),
+  };
+  const Manager = { ...MANAGER, Usage: () => counter };
+
+  await beforeCreate({ Manager: Manager, ctx: ctx, user: USER, context: AUTH_CONTEXT, libraries: { functions: {} } });
+
+  return calls;
+}
+
+async function runBeforeSignIn() {
+  const { calls, ctx } = createRecorder();
+  const admin = { firestore: () => ({ doc: () => ({ set: async () => undefined }) }) };
+
+  await beforeSignIn({ Manager: MANAGER, ctx: ctx, user: USER, context: AUTH_CONTEXT, libraries: { admin: admin } });
+
+  return calls;
+}
+
+async function runOnDelete() {
+  const { calls, ctx } = createRecorder();
+
+  // No user doc, so the handler writes its headline and returns before the
+  // delete, the marketing removal and the conversion.
+  const admin = { firestore: () => ({ doc: () => ({ get: async () => ({ exists: false }) }) }) };
+
+  await onDelete({ Manager: MANAGER, ctx: ctx, user: USER, context: EVENT_CONTEXT, libraries: { admin: admin } });
+
+  return calls;
+}
+
+// What the marketing library answers `remove()` with: one entry per enabled
+// provider, each carrying that provider's own payload — the address included.
+const MARKETING_RESULT = {
+  campaigns: { success: true, jobId: 'job-710', contact: { email: EMAIL, name: DISPLAY_NAME } },
+  newsletter: { success: true, subscriber: { id: 'sub-710', email: EMAIL } },
+};
+
+// The full run: an existing doc, so the handler goes past its headline into the
+// delete, the marketing removal and the conversion. The marketing removal is
+// fire-and-forget, so the caller drains the microtask queue before reading.
+async function runOnDeleteWithDoc() {
+  const { calls, ctx } = createRecorder();
+
+  const admin = {
+    firestore: () => ({
+      doc: () => ({
+        get: async () => ({ exists: true, data: () => ({ auth: { uid: UID, email: EMAIL } }) }),
+        delete: async () => undefined,
+      }),
+    }),
+  };
+
+  const Manager = { ...MANAGER, Email: () => ({ remove: async () => MARKETING_RESULT }) };
+
+  await onDelete({ Manager: Manager, ctx: ctx, user: USER, context: EVENT_CONTEXT, libraries: { admin: admin } });
+  await new Promise((resolve) => setImmediate(resolve));
+
+  return calls;
+}
+
+// The two claims every trigger makes, asserted the same way for each.
+function assertHeadlineIsUidAlone({ assert, calls, tag }) {
+  const headline = calls.log[0];
+
+  assert.ok(headline, `${tag}: no headline line was logged`);
+  assert.equal(headline[0], `${tag}: ${UID}`, `${tag}: headline is not the uid alone: ${render(headline)}`);
+  assert.equal(headline.length, 1, `${tag}: the headline carries a payload: ${render(headline.slice(1))}`);
+}
+
+function assertNothingPrivateRidesTheLog({ assert, calls, tag, context }) {
+  const written = [...calls.log, ...calls.error];
+
+  for (const args of written) {
+    const line = render(args);
+
+    assert.equal(line.includes(EMAIL), false, `${tag}: email written to a log line: ${line}`);
+    assert.equal(line.includes(DISPLAY_NAME), false, `${tag}: display name written to a log line: ${line}`);
+    assert.equal(args.includes(USER), false, `${tag}: the user record rides a log line: ${line}`);
+    assert.equal(args.includes(context), false, `${tag}: the trigger context rides a log line: ${line}`);
+  }
+
+  // Not deleted — moved behind the debug gate, which is dropped whole unless
+  // OMEGA_DEBUG is set.
+  const records = calls.debug.filter((args) => args.includes(USER) && args.includes(context));
+
+  assert.equal(records.length, 1, `${tag}: the full record should stay reachable at debug level`);
+}
+
+module.exports = defineCases({
+  description: 'auth triggers log the uid only',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'before-create-headline-is-the-uid-alone',
+      async run({ assert }) {
+        assertHeadlineIsUidAlone({ assert: assert, calls: await runBeforeCreate(), tag: 'beforeCreate' });
+      },
+    },
+
+    {
+      name: 'before-create-never-logs-the-record-or-the-context',
+      async run({ assert }) {
+        assertNothingPrivateRidesTheLog({ assert: assert, calls: await runBeforeCreate(), tag: 'beforeCreate', context: AUTH_CONTEXT });
+      },
+    },
+
+    {
+      name: 'before-signin-headline-is-the-uid-alone',
+      async run({ assert }) {
+        assertHeadlineIsUidAlone({ assert: assert, calls: await runBeforeSignIn(), tag: 'beforeSignIn' });
+      },
+    },
+
+    {
+      name: 'before-signin-never-logs-the-record-or-the-context',
+      async run({ assert }) {
+        assertNothingPrivateRidesTheLog({ assert: assert, calls: await runBeforeSignIn(), tag: 'beforeSignIn', context: AUTH_CONTEXT });
+      },
+    },
+
+    {
+      name: 'on-delete-headline-is-the-uid-alone',
+      async run({ assert }) {
+        assertHeadlineIsUidAlone({ assert: assert, calls: await runOnDelete(), tag: 'onDelete' });
+      },
+    },
+
+    {
+      name: 'on-delete-never-logs-the-record-or-the-context',
+      async run({ assert }) {
+        assertNothingPrivateRidesTheLog({ assert: assert, calls: await runOnDelete(), tag: 'onDelete', context: EVENT_CONTEXT });
+      },
+    },
+
+    // ─── The marketing removal's own line ([#710]) ───
+
+    {
+      name: 'on-delete-marketing-remove-logs-the-uid-and-a-count',
+      async run({ assert }) {
+        const calls = await runOnDeleteWithDoc();
+        const line = calls.log.find((args) => String(args[0]).includes('Marketing remove'));
+
+        assert.ok(line, `no marketing-remove line was logged: ${calls.log.map(render).join(' | ')}`);
+        assert.equal(line.length, 1, `the line carries the provider result: ${render(line.slice(1))}`);
+        assert.match(render(line), new RegExp(UID), 'the line should name the account the removal was for');
+        assert.match(render(line), /2/, 'the line should count the providers that answered');
+      },
+    },
+
+    {
+      name: 'on-delete-marketing-remove-keeps-the-result-behind-the-debug-gate',
+      async run({ assert }) {
+        const calls = await runOnDeleteWithDoc();
+
+        for (const args of [...calls.log, ...calls.error]) {
+          assert.equal(args.includes(MARKETING_RESULT), false, `the provider result rides a log line: ${render(args)}`);
+          assert.equal(render(args).includes(EMAIL), false, `email written to a log line: ${render(args)}`);
+        }
+
+        const records = calls.debug.filter((args) => args.includes(MARKETING_RESULT));
+
+        assert.equal(records.length, 1, 'the provider result should stay reachable at debug level');
+      },
+    },
+  ],
+});

package/test/events/cron-job-doc-shape.test.js

@@ -0,0 +1,101 @@
+/**
+ * Test: the documented cron job actually RUNS
+ * ([#495](https://github.com/Omega-JS-Stack/omega/issues/495)).
+ *
+ * `docs/routes.md` § "New Cron Job (Consumer Project)" documented a
+ * `Job.prototype.main` constructor shape, but the runner does
+ * `await handler({ Manager, ctx, context, libraries })` — a job written to the
+ * doc was called as a plain function, its body never ran, and nothing errored.
+ * That is the defect class that made legacy playlisteer's clear-promotions
+ * route 500 for years (a pre-BEM export shape meeting a newer middleware).
+ *
+ * So the doc's example is not read here, it is EXECUTED: lifted out of the
+ * markdown verbatim, dropped into a jobs directory, and run through the
+ * runner's own `loadAndExecuteJobs`. A doc that drifts from the call shape goes
+ * red the day it drifts.
+ *
+ * Run: npx omega test backend:events/cron-job-doc-shape
+ */
+const path = require('path');
+const jetpack = require('fs-jetpack');
+
+const { loadAndExecuteJobs } = require('../../dist/manager/events/cron/runner.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+const ROUTES_DOC = path.join(__dirname, '..', '..', 'docs', 'routes.md');
+const HEADING = '## New Cron Job (Consumer Project)';
+
+// The line the documented job logs when its body runs.
+const JOB_MARKER = 'Running daily job...';
+
+/** The first fenced javascript block under the cron-job heading, verbatim. */
+function documentedCronJob() {
+  const doc = jetpack.read(ROUTES_DOC);
+  const heading = doc.indexOf(HEADING);
+
+  if (heading === -1) {
+    throw new Error(`docs/routes.md no longer carries "${HEADING}" — the consumer cron recipe must stay documented`);
+  }
+
+  const fence = doc.indexOf('```javascript', heading);
+  const start = doc.indexOf('\n', fence) + 1;
+  const end = doc.indexOf('```', start);
+
+  return doc.slice(start, end);
+}
+
+/** Run `fn` with console.log captured. */
+async function capturingLogs(fn) {
+  const lines = [];
+  const original = console.log;
+
+  console.log = (...args) => lines.push(args.map((a) => String(a)).join(' '));
+
+  try {
+    await fn();
+  } finally {
+    console.log = original;
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = defineCases({
+  description: 'the documented consumer cron job runs under the real runner',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'the-documented-job-body-executes',
+      auth: 'none',
+
+      async run({ assert, Manager }) {
+        const jobsDir = jetpack.tmpDir({ prefix: 'omega-cron-doc-' }).path();
+        jetpack.write(path.join(jobsDir, 'documented-job.js'), documentedCronJob());
+
+        const output = await capturingLogs(() => loadAndExecuteJobs('daily', jobsDir, Manager, {}));
+
+        assert.ok(output.includes(JOB_MARKER), 'the documented job must RUN when the runner calls it — a job the runner cannot call fails silently, exactly as this one did');
+        assert.equal(output.includes('Error executing:'), false, `the documented job must not throw: ${output}`);
+        assert.ok(output.includes('Completed!'), 'the runner must report the documented job complete');
+
+        jetpack.remove(jobsDir);
+      },
+    },
+
+    {
+      name: 'the-documented-job-is-authored-under-src',
+      auth: 'none',
+
+      async run({ assert }) {
+        // Consumers are src-first: `dist/` is staged output, so a doc naming
+        // the runtime path teaches an edit that the next build wipes.
+        const doc = jetpack.read(ROUTES_DOC);
+        const heading = doc.indexOf(HEADING);
+        const recipe = doc.slice(heading, doc.indexOf('```', doc.indexOf('```javascript', heading) + 3));
+
+        assert.match(recipe, /src\/hooks\/cron\/daily\//, 'the cron recipe must name the AUTHORED path (src/hooks/cron/daily/)');
+      },
+    },
+  ],
+});

package/test/events/cron-reset-usage.test.js

@@ -0,0 +1,116 @@
+/**
+ * The daily usage reset cron (`events/cron/daily/reset-usage.js`)
+ * ([#647](https://github.com/Omega-JS-Stack/omega/issues/647)).
+ *
+ * The promises, all of them things a user is silently punished by when broken:
+ *  - EVERY counter block under `usage` is reset, whatever its key. Catalog
+ *    membership is not the test: the framework's own anti-abuse gates count on
+ *    the user doc with an explicit limit and carry no catalog entry, so a
+ *    catalog-only sweep left them growing forever and the user permanently
+ *    refused after five email-preference changes;
+ *  - `usage.overrides` is NEVER touched — an admin granted those credits and a
+ *    reset is not a revoke;
+ *  - the day counter resets every day, the month counter only on the 1st;
+ *  - one write per user, however many counters moved.
+ *
+ * Plain-node unit test (no emulator): the cron's collaborators are the
+ * collection walk and the document write, and both are recorded here rather
+ * than performed — which is what makes the resulting patch assertable.
+ */
+const assert = require('node:assert');
+
+const resetUsage = require('../../dist/manager/events/cron/daily/reset-usage.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+const CATALOG = {
+  saves: { name: 'Saves', usage: {} },
+  support: { name: 'Priority support' },
+};
+
+// One user carrying three kinds of key under `usage`: a catalog feature, a
+// framework gate the catalog never defines, and the overrides map.
+function userDoc() {
+  return {
+    saves: { monthly: 40, daily: 4, total: 900 },
+    'email-preferences': { monthly: 5, daily: 5, total: 12 },
+    overrides: { saves: 500 },
+  };
+}
+
+/** Run the whole cron over one synthetic user and hand back what it wrote. */
+async function runCron() {
+  const writes = [];
+  const usage = userDoc();
+
+  const doc = {
+    id: 'user-647',
+    ref: { update: async (patch) => writes.push(patch) },
+    data: () => ({ usage: usage }),
+  };
+
+  const Manager = {
+    config: { features: CATALOG },
+    storage: () => ({ setState: () => ({ write: () => {} }) }),
+    Utilities: () => ({
+      // Every query answers with the one user — the cron dedupes by doc id, so
+      // a user found by several field paths is still written once
+      iterateCollection: async (handler) => handler({ docs: [doc] }),
+    }),
+  };
+
+  const ctx = { log: () => {}, warn: () => {}, error: () => {}, report: () => {} };
+  const libraries = { admin: { firestore: () => ({ recursiveDelete: async () => {}, collection: () => ({}) }) } };
+
+  await resetUsage({ Manager, ctx, context: {}, libraries });
+
+  return { writes, usage };
+}
+
+module.exports = defineCases({
+  description: 'Daily usage reset cron',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'every counter block resets — a counter the catalog never defined included',
+
+      async run() {
+        const { writes } = await runCron();
+
+        assert.equal(writes.length, 1, 'one write per user, however many counters moved');
+
+        const written = writes[0].usage;
+
+        assert.equal(written.saves.daily, 0, 'the catalog feature reset');
+        assert.equal(
+          written['email-preferences'].daily,
+          0,
+          'and so did the framework gate the catalog never defines — the counter that used to grow forever',
+        );
+      },
+    },
+
+    {
+      name: 'the month counter survives a day that is not the 1st',
+
+      async run() {
+        const { writes } = await runCron();
+        const written = writes[0].usage;
+        const isFirst = new Date().getDate() === 1;
+
+        assert.equal(written.saves.monthly, isFirst ? 0 : 40, 'the month resets on the 1st and only then');
+        assert.equal(written.saves.total, 900, 'the all-time counter never resets');
+      },
+    },
+
+    {
+      name: 'overrides are never touched — a reset is not a revoke',
+
+      async run() {
+        const { writes } = await runCron();
+
+        assert.deepEqual(writes[0].usage.overrides, { saves: 500 }, 'the granted credits survive the sweep');
+      },
+    },
+  ],
+});