@omega.js/backend 0.1.0

package/dist/defaults/docs/README.md

@@ -0,0 +1,17 @@
+# Project docs
+
+Per-subsystem deep references live here. Keep `AGENTS.md` short — it should read as a **table of contents** that points at files in this directory.
+
+## Pattern
+
+When you find yourself adding more than a paragraph to `AGENTS.md`, create a new `docs/<topic>.md` instead and link to it from `AGENTS.md`. Goal: the project's `AGENTS.md` stays under ~250 lines (`CLAUDE.md` is only the one-line `@AGENTS.md` pointer).
+
+Examples of good `docs/*.md` topics:
+- Subsystem deep-dives (one per area of the codebase)
+- Architectural decisions / "why we built it this way"
+- Defaults tables, behavior matrices, edge cases
+- Setup walkthroughs that don't belong in `README.md`
+
+## See also
+
+`node_modules/@omega.js/AGENTS.md` is the OMEGA map — follow it to `docs/backend/index.md`, the framework's own overview.

package/dist/defaults/test/README.md

@@ -0,0 +1,65 @@
+# Project tests
+
+This project has **two test lanes**, both scaffolded by the OMEGA verbs.
+
+| Lane | Command | What it is |
+|---|---|---|
+| Static | `npm test` (= `npm run test:static`) | Plain `node --test` over `test/_unit/**/*.test.js`. **Socket-free**: `test/_helpers/connect-trap.js` is preloaded into every test process and turns any TCP connect or DNS lookup into a throw. No emulator, no network, no credentials — seconds to run. |
+| Emulator | `npm run test:emulator` (= `npx omega test`) | Everything below: your suites, and the framework's, against a **real Firebase emulator**. |
+
+## The static lane (`test/_unit/`)
+
+The `_` prefix is load-bearing: the framework's test discovery skips `_`-prefixed paths, so these suites never run inside the emulator lane. Three skeletons ship with the project and are YOURS to extend:
+
+| File | Pins |
+|---|---|
+| `_unit/registration.test.js` | `src/index.js` boots the framework that is actually installed; every route it dispatches to exists and its imports load (a broken require fails here, not at cold start) |
+| `_unit/rules-posture.test.js` | Every Firestore/Storage path your rules open is declared in the suite — adding a rule is a deliberate act, not a diff nobody read |
+| `_unit/socket-free.test.js` | The connect trap is loaded and refuses. Leave this one as shipped: without it, a lane that lost the `--require` flag would pass while reaching live Firebase |
+
+A test that needs a real network client belongs in the emulator lane, which boots the environment it talks to. In the static lane, pass a stub.
+
+## Layout (emulator lane)
+
+Name every test file `<concern>.test.js` — the suffix is how the runner finds it, and a plain `.js` file under `test/` is support code that never runs. Match the framework's layout — OMEGA Backend's test runner discovers files by the directory they sit in. Mirror the same per-area split as the framework's own `test/` (see `node_modules/@omega.js/backend/test/`):
+
+| Directory | Use for |
+|---|---|
+| `test/routes/` | Custom HTTP route handlers (`functions/routes/<verb>/<path>.js`) |
+| `test/events/` | Pub/Sub / Firestore-trigger handlers |
+| `test/helpers/` | Shared test utilities for your project |
+| `test/fixtures/` | Static test data (JSON, sample docs) |
+| `test/_init/` | Per-suite setup (Firestore seed data, user accounts) |
+
+Tests run inside the Firebase emulator. Use the @omega.js/backend helpers (`ctx`, admin SDK, fixture loaders) instead of mocking — `npx omega emulator` boots the same environment the tests run against.
+
+## Extended mode (real external APIs)
+
+By default, tests skip REAL external services (SendGrid, OpenAI, Stripe webhooks, etc.) — the routes/libraries short-circuit in-source when not in extended mode. To exercise those paths for real, pass `--extended`:
+
+```bash
+npx omega test --extended            # opt into real external APIs
+TEST_EXTENDED_MODE=true npx omega test   # identical — the env-var form
+```
+
+`--extended` is the CLI shorthand for the shared, unprefixed `TEST_EXTENDED_MODE` env var standardized across @omega.js/backend/BXM/UJM/EM. @omega.js/backend propagates it to BOTH the test runner and the running emulator, so a single flag on the test command flips everything — no need to restart the emulator. Anything an extended test creates in an external system MUST be cleaned up by the test (the runner only wipes local Firestore/Auth).
+
+## Coverage
+
+Every feature ships with tests at every surface it exposes — logic (handler suites), wiring (route round-trips over `http.as(...)`), and rules (when Firestore rules change). Skip a surface only when the feature genuinely doesn't have one; "the handler test covers it" does not excuse the route round-trip.
+
+## Quick example
+
+```js
+// test/routes/hello.test.js
+module.exports = {
+  'GET /hello returns ok': async ({ http }) => {
+    const res = await http.get('hello');
+    if (res.status !== 200) throw new Error('expected 200');
+  },
+};
+```
+
+## See also
+
+The framework's own test suites at `node_modules/@omega.js/backend/test/` are the canonical reference for how each layer is structured.

package/dist/defaults/test/_init.js

@@ -0,0 +1,14 @@
+/**
+ * Test lifecycle hook for this project. Runs before any test (not a test itself).
+ * See @omega.js/backend/docs/test-framework.md → "test/_init.js".
+ */
+
+module.exports = ({ config }) => ({
+  // Extra test accounts (one per lifecycle this project exercises):
+  // { id, uid, email, properties }. email may use the {domain} placeholder.
+  accounts: [],
+
+  // Seed fixtures into the freshly-flushed emulator, after accounts are created.
+  async setup({ admin, accounts }) {
+  },
+});

package/dist/defaults/test/helpers/connect-trap.js

@@ -0,0 +1,72 @@
+/**
+ * Connect trap — the static lane's proof that no test opens a socket.
+ *
+ * Preloaded into EVERY test process by this target's `test` script
+ * (`node --require ./test/_helpers/connect-trap.js --test …`; node forwards the
+ * parent's execArgv to each test child, so one flag covers the whole lane).
+ *
+ * The static lane requires your real source: route handlers, schemas, the
+ * framework module itself. One require deeper than you think and that tree
+ * reaches firebase-admin's gRPC client — against whatever credentials `.env`
+ * and `.omega/secrets/` happen to carry for the REAL project. So the failure
+ * mode is made structural: the socket layer itself refuses, loudly, before any
+ * DNS lookup or TCP connect can happen.
+ *
+ * Everything that can open an outbound connection in Node funnels through
+ * `net.Socket.prototype.connect` — http/https agents, undici/fetch, gRPC
+ * (firebase-admin), and every fetch wrapper on top of them — so trapping that
+ * one method covers the lot. `dns.lookup` is trapped too, since a resolver call
+ * is already an escape even when the connect never happens.
+ *
+ * A test that legitimately needs a network client passes it a stub instead. A
+ * test that wants the real thing belongs in the EMULATOR lane
+ * (`npx omega test`), which boots the environment it talks to.
+ */
+const net = require('node:net');
+const dns = require('node:dns');
+
+const MARKER = '__omegaConnectTrap';
+
+function refuse(what, detail) {
+  const error = new Error(
+    `connect-trap: ${what} was attempted in the static test lane (${detail}). `
+    + 'This lane is socket-free by contract — stub the network client instead.',
+  );
+  error.code = 'CONNECT_TRAP';
+  return error;
+}
+
+function describe(target) {
+  if (!target) {
+    return 'unknown target';
+  }
+  if (typeof target === 'string' || typeof target === 'number') {
+    return String(target);
+  }
+  return `${target.host || target.path || 'unknown'}:${target.port || '?'}`;
+}
+
+// Sockets — the one funnel every outbound protocol goes through.
+const realConnect = net.Socket.prototype.connect;
+net.Socket.prototype.connect = function connect(...args) {
+  throw refuse('a TCP connect', describe(args[0]));
+};
+
+// Resolver — an escape in its own right, and it runs BEFORE the connect above.
+const realLookup = dns.lookup;
+dns.lookup = function lookup(hostname) {
+  throw refuse('a DNS lookup', String(hostname));
+};
+dns.promises.lookup = function lookup(hostname) {
+  throw refuse('a DNS lookup', String(hostname));
+};
+
+// The proof handle: test/_unit/socket-free.test.js asserts this is present, so
+// a lane that silently lost the --require flag fails instead of passing quietly.
+globalThis[MARKER] = {
+  installed: true,
+  marker: MARKER,
+  // The originals are kept ONLY so the trap can describe what it replaced —
+  // nothing in the lane is allowed to put them back.
+  replaced: { connect: typeof realConnect, lookup: typeof realLookup },
+};

package/dist/defaults/test/unit/registration.test.js

@@ -0,0 +1,143 @@
+/**
+ * Registration guard — what this target actually deploys, and whether every
+ * route it dispatches to still loads.
+ *
+ * The deployed surface is the FRAMEWORK's own (the `omega_*` functions
+ * `Manager.init(exports, {})` registers) PLUS whatever `src/index.js` exports.
+ * Nothing below is a hardcoded mirror of your tree:
+ *
+ *   1. The consumer functions and the route names they dispatch to are READ OUT
+ *      OF `src/index.js` (as text), not listed here. A function you add there
+ *      shows up in these assertions on its own.
+ *   2. For each route name index.js dispatches, the handler is resolved the way
+ *      `Middleware.run()` resolves it — `<routesDir>/<name>/<method>.js`, method
+ *      file first, `index.js` fallback — and then REQUIRED, so a broken import
+ *      in a route (an ESM-only dependency, a moved util) fails HERE rather than
+ *      at cold start in production.
+ *
+ * `src/index.js` is read as TEXT, never required — requiring it boots the
+ * Manager (Firebase Admin init, .env cascade, config load), which is exactly the
+ * runtime dependency this lane avoids. That nothing in any of these requires
+ * reaches the network is not taken on trust: the connect trap preloaded into
+ * this process (test/_helpers/connect-trap.js) throws on the first DNS lookup
+ * or TCP connect.
+ *
+ * Yours to extend: pin the resources a function needs (`runWith` memory and
+ * timeout), the rewrites your published API paths depend on, and the schema
+ * shape each route resolves. See `node_modules/@omega.js/backend/test/` for how
+ * the framework does each of those.
+ *
+ *   node --require ./test/_helpers/connect-trap.js --test test/_unit/registration.test.js
+ */
+const assert = require('node:assert/strict');
+const test = require('node:test');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const APP_DIR = path.join(__dirname, '..', '..');
+const SRC = path.join(APP_DIR, 'src');
+const INDEX = fs.readFileSync(path.join(SRC, 'index.js'), 'utf8');
+const FIREBASE = JSON.parse(fs.readFileSync(path.join(APP_DIR, 'firebase.json'), 'utf8'));
+
+const FRAMEWORK_DIR = path.dirname(require.resolve('@omega.js/backend/package.json', { paths: [APP_DIR] }));
+
+// The prefixes the framework's own registrations occupy. A consumer export
+// wearing one would silently overwrite a framework function, or be overwritten
+// by it — either way something stops deploying.
+const RESERVED_PREFIXES = ['omega_', 'bm_'];
+
+// The HTTP verbs Middleware.run() looks for as `<route>/<method>.js`.
+const METHOD_FILES = ['get.js', 'post.js', 'put.js', 'patch.js', 'delete.js'];
+
+/**
+ * The consumer Cloud Functions index.js registers, read out of the source:
+ * `exports.<name> = functions….run('<route>')`.
+ * @returns {Array<{name: string, route: string}>}
+ */
+function consumerFunctions() {
+  return [...INDEX.matchAll(/exports\.(\w+)\s*=([\s\S]*?);\n/g)].map((match) => ({
+    name: match[1],
+    route: (match[2].match(/\.run\(\s*'([^']+)'/) || [])[1],
+  }));
+}
+
+test('index.js boots the framework from the package that is actually installed', () => {
+  assert.match(INDEX, /require\('@omega\.js\/backend'\)/, 'index.js does not boot @omega.js/backend');
+  assert.match(INDEX, /\.init\(exports,/, 'Manager.init(exports, …) is the bootstrap call');
+
+  // The specifier index.js requires, resolved the way NODE resolves it FROM
+  // src/ — the same lookup the deployed function performs at cold start. A
+  // renamed dependency, a missing workspace link or a `file:` path off by a
+  // directory all fail here instead of at boot.
+  const resolved = require.resolve('@omega.js/backend', { paths: [SRC] });
+
+  assert.ok(
+    resolved.startsWith(FRAMEWORK_DIR + path.sep),
+    `index.js's '@omega.js/backend' resolves to ${resolved}, outside the framework package`,
+  );
+});
+
+test('no consumer function collides with the framework namespace', () => {
+  for (const fn of consumerFunctions()) {
+    for (const prefix of RESERVED_PREFIXES) {
+      assert.ok(
+        !fn.name.startsWith(prefix),
+        `exports.${fn.name} takes the framework's reserved "${prefix}" prefix — one of the two functions will not deploy`,
+      );
+    }
+  }
+});
+
+test('every route index.js dispatches to resolves and loads the way the middleware loads it', () => {
+  // Middleware.run() resolves `path.resolve(<routesDir>, <route>)` and then
+  // takes `<method>.js` if it exists, `index.js` otherwise. A function that
+  // does not dispatch through `.run()` carries its handler inline — nothing to
+  // resolve, so it is this test's business only if it names a route.
+  for (const fn of consumerFunctions().filter((f) => f.route)) {
+    const routeDir = path.resolve(SRC, 'routes', fn.route);
+    assert.ok(fs.existsSync(routeDir), `src/routes/${fn.route}/ does not exist — the route answers 500`);
+
+    const handlers = [...METHOD_FILES, 'index.js']
+      .map((file) => path.join(routeDir, file))
+      .filter((file) => fs.existsSync(file));
+
+    assert.ok(
+      handlers.length > 0,
+      `src/routes/${fn.route}/ has no <method>.js and no index.js — every request answers 405`,
+    );
+
+    // Requiring is the point: a route's own imports are exercised here instead
+    // of at cold start.
+    for (const file of handlers) {
+      const handler = require(file);
+
+      assert.equal(typeof handler, 'function', `${path.relative(APP_DIR, file)} does not export a handler function`);
+      assert.equal(handler.constructor.name, 'AsyncFunction', `${path.relative(APP_DIR, file)}'s handler is not async`);
+    }
+  }
+});
+
+test('src/ is the authored tree, so firebase deploys the staged dist/', () => {
+  // `omega build` copies src/** → dist/** and firebase.json deploys dist/.
+  assert.equal(FIREBASE.functions[0].source, 'dist', 'functions deploy from the staged dist/, never src/');
+  assert.equal(FIREBASE.hosting.public, 'dist/public', 'hosting serves the staged public dir');
+});
+
+test('the omega_api rewrite still serves the framework prefixes, first', () => {
+  const rewrites = FIREBASE.hosting.rewrites;
+  const api = rewrites.find((r) => r.function === 'omega_api');
+
+  assert.ok(api, 'no omega_api rewrite — every built-in route would 404');
+
+  // Firebase hosting glob groups match a WHOLE path, so `/omega/**` alone would
+  // not cover the bare `/omega` — each prefix is listed on its own as well.
+  const alternatives = api.source.replace(/^\{|\}$/g, '').split(',');
+
+  for (const prefix of ['/omega', '/omega/**']) {
+    assert.ok(alternatives.includes(prefix), `the ${prefix} path is not routed to omega_api`);
+  }
+
+  // The omega rewrite has to stay FIRST: hosting takes the first match, and a
+  // broader pattern above it would swallow the framework prefixes.
+  assert.equal(rewrites[0].function, 'omega_api', 'the omega_api rewrite is no longer first');
+});

package/dist/defaults/test/unit/rules-posture.test.js

@@ -0,0 +1,101 @@
+/**
+ * Rules-posture guard — every rule this brand opens is a rule someone reviewed.
+ *
+ * `firestore.rules` is YOUR half of the compiled model: `omega build` splices it
+ * together with the framework half into `dist/firestore.rules`, and that is what
+ * the emulator and `firebase deploy` read. A match block you add here widens (or
+ * tightens) real access to real user data, so this suite makes adding one a
+ * DELIBERATE act: list the path in `AUTHORED_FIRESTORE_PATHS` below, with a
+ * comment saying why it is open, or the suite goes red.
+ *
+ * Same deal for Storage: the scaffold denies every path, and each one you expose
+ * goes in `EXPOSED_STORAGE_PATHS`.
+ *
+ * Static + emulator-free: reads the rules FILES, compares text. Behavioral rules
+ * coverage (allow/deny against a real Firestore) lives in the emulator suite
+ * (`npx omega test`), which boots the database it asserts against.
+ *
+ * Lives under `_unit/` on purpose: the framework's test discovery skips
+ * `_`-prefixed paths, so this file runs in the static lane and never inside the
+ * emulator lane.
+ *
+ *   node --require ./test/_helpers/connect-trap.js --test test/_unit/rules-posture.test.js
+ */
+const assert = require('node:assert/strict');
+const test = require('node:test');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const APP_DIR = path.join(__dirname, '..', '..');
+
+// ── Yours to fill in ────────────────────────────────────────────────────────
+// Every collection path YOUR firestore.rules opens, and every Storage path you
+// expose. Empty is the scaffold's posture: the framework half gates everything
+// it owns and the default lock closes the rest.
+//
+//   const AUTHORED_FIRESTORE_PATHS = [
+//     '/posts/{id}',   // public blog posts — read-only to clients, admin writes
+//   ];
+const AUTHORED_FIRESTORE_PATHS = [];
+const EXPOSED_STORAGE_PATHS = [];
+// ────────────────────────────────────────────────────────────────────────────
+
+function read(file) {
+  return fs.readFileSync(path.join(APP_DIR, file), 'utf8');
+}
+
+// Comments carry no posture — strip them before any rule text is read, so a
+// commented-out example never counts as an open path.
+function rulePaths(contents) {
+  const live = contents
+    .split('\n')
+    .map((line) => line.replace(/\/\/.*$/, ''))
+    .join('\n');
+
+  return [...live.matchAll(/match\s+(\/\S+)/g)].map((match) => match[1]);
+}
+
+test('firestore.rules opens exactly the paths this brand declared', () => {
+  const authored = rulePaths(read('firestore.rules'))
+    // The scope opener every rules file carries, not a rule.
+    .filter((rulePath) => !rulePath.startsWith('/databases/'));
+
+  assert.deepEqual(
+    authored,
+    AUTHORED_FIRESTORE_PATHS,
+    'firestore.rules opens a path this suite does not declare — add it to AUTHORED_FIRESTORE_PATHS with the reason, or take the rule out',
+  );
+});
+
+test('storage.rules denies every path this brand has not exposed', () => {
+  const storage = read('storage.rules');
+
+  assert.ok(
+    /match \/\{allPaths=\*\*\} \{\s*\n\s*allow read, write: if false;/.test(storage),
+    'the storage deny-all default is gone — every path without its own rule is now open',
+  );
+
+  const exposed = rulePaths(storage)
+    .filter((rulePath) => !rulePath.startsWith('/b/') && rulePath !== '/{allPaths=**}');
+
+  assert.deepEqual(
+    exposed,
+    EXPOSED_STORAGE_PATHS,
+    'storage.rules exposes a path this suite does not declare — add it to EXPOSED_STORAGE_PATHS with the reason, or take the rule out',
+  );
+});
+
+test('firebase.json reads the COMPILED firestore rules, not the source half', () => {
+  const firebase = JSON.parse(read('firebase.json'));
+
+  // `firestore.rules` here is source: on its own it carries none of the
+  // framework's gating. Pointed at directly, a deploy would ship whatever this
+  // file alone says — which for a fresh brand is nothing at all.
+  assert.equal(
+    firebase.firestore.rules,
+    'dist/firestore.rules',
+    'firestore rules no longer read the compiled artifact — the framework half is not being deployed',
+  );
+  assert.equal(firebase.database.rules, 'database.rules.json', 'the Realtime Database rules file moved');
+  assert.equal(firebase.storage.rules, 'storage.rules', 'the Storage rules file moved');
+});

package/dist/defaults/test/unit/socket-free.test.js

@@ -0,0 +1,43 @@
+/**
+ * The static lane's socket-free contract, asserted rather than assumed.
+ *
+ * `test/_helpers/connect-trap.js` is preloaded into every test process by the
+ * `test` script. If that flag is ever dropped from package.json, or node stops
+ * forwarding execArgv to test children, the rest of this lane would still pass
+ * — quietly able to reach the REAL Firebase project through the framework tree
+ * registration.test.js loads, with whatever credentials the environment happens
+ * to carry. This file is what turns that silent regression into a red test.
+ *
+ * Nothing here is yours to fill in: leave it as shipped.
+ *
+ *   node --require ./test/_helpers/connect-trap.js --test test/_unit/socket-free.test.js
+ */
+const assert = require('node:assert/strict');
+const test = require('node:test');
+const net = require('node:net');
+const dns = require('node:dns');
+
+test('the connect trap is loaded in this test process', () => {
+  assert.ok(
+    globalThis.__omegaConnectTrap?.installed,
+    'the connect-trap preload is missing — the static lane can reach the network',
+  );
+});
+
+test('opening a TCP socket is refused', () => {
+  const socket = new net.Socket();
+
+  assert.throws(
+    () => socket.connect(443, 'firestore.googleapis.com'),
+    (e) => e.code === 'CONNECT_TRAP',
+    'a TCP connect went through — the live Firestore is one call away',
+  );
+});
+
+test('resolving a hostname is refused', () => {
+  assert.throws(
+    () => dns.lookup('firestore.googleapis.com', () => {}),
+    (e) => e.code === 'CONNECT_TRAP',
+    'a DNS lookup went through',
+  );
+});

package/dist/manager/events/auth/before-create.js

@@ -0,0 +1,89 @@
+const { isDisposable } = require('../../libraries/email/validation.js');
+const { runAuthHook, resolveSignupLimit } = require('./utils.js');
+
+const ERROR_TOO_MANY_ATTEMPTS = 'Unable to create account at this time. Please try again later.';
+const ERROR_DISPOSABLE_EMAIL = 'This email domain is not allowed. Please use a different email address.';
+
+/**
+ * beforeUserCreated - Disposable email blocking + IP rate limiting
+ *
+ * User doc creation is handled by on-create.js (which fires for all user creations including Admin SDK).
+ *
+ * Why not create user doc here?
+ * - Admin SDK (used for tests) does NOT trigger beforeUserCreated
+ * - on-create fires for ALL user creations, making it more reliable
+ *
+ * Available parameters (1st gen):
+ *
+ * user (AuthUserRecord):
+ *   uid, email, emailVerified, displayName, photoURL, phoneNumber, disabled,
+ *   metadata: { creationTime, lastSignInTime },
+ *   providerData: [{ uid, displayName, email, photoURL, providerId, phoneNumber }],
+ *   passwordHash, passwordSalt, customClaims, tenantId, tokensValidAfterTime, multiFactor
+ *
+ * context (AuthEventContext):
+ *   ipAddress, userAgent, locale, eventId, eventType, authType, resource, timestamp,
+ *   additionalUserInfo: { providerId, profile, username, isNewUser, recaptchaScore, email, phoneNumber },
+ *   credential: { providerId, signInMethod, claims, idToken, accessToken, refreshToken, expirationTime, secret } | null,
+ *   emailType, smsType, params
+ *
+ * Note: recaptchaScore requires reCAPTCHA Enterprise (Google Cloud level), NOT the Firebase SMS fraud toggle.
+ * Note: credential tokens (idToken, accessToken, refreshToken) require opt-in via BlockingOptions.
+ */
+module.exports = async ({ Manager, ctx, user, context, libraries }) => {
+  const startTime = Date.now();
+  const { functions } = libraries;
+  const ipAddress = context.ipAddress || '';
+
+  // The UID and nothing else. The AuthUserRecord carries the email, the display
+  // name and the provider data, the AuthEventContext carries the IP, the user
+  // agent and the credential, and a backend line lands in Cloud Logging for the
+  // whole retention window — so none of it rides this line
+  // ([#657](https://github.com/Omega-JS-Stack/omega/issues/657)). Both stay
+  // reachable one level down, at debug.
+  ctx.log(`beforeCreate: ${user.uid}`);
+  ctx.debug(`beforeCreate: ${user.uid} record`, user, context);
+
+  // Block disposable email domains
+  if (isDisposable(user.email)) {
+    ctx.error(`beforeCreate: Blocked disposable email ${user.email}`);
+
+    throw new functions.auth.HttpsError('invalid-argument', ERROR_DISPOSABLE_EMAIL);
+  }
+
+  // Skip rate limiting if no IP (shouldn't happen in production)
+  if (!ipAddress) {
+    ctx.log(`beforeCreate: No IP address, skipping rate limit check (${Date.now() - startTime}ms)`);
+    return;
+  }
+
+  // IP rate limiting — an EXPLICIT keyed counter, never the caller's own
+  // ([#647](https://github.com/Omega-JS-Stack/omega/issues/647)). The limit is
+  // this backend's own `auth.signup.maxPerIpPerDay`, not a plan number: a
+  // signup gate is a security control and the caller has no account yet.
+  // consume() is the whole gate — check, count, write — so a refusal is a
+  // throw and there is nothing here to get half right.
+  const usage = Manager.Usage().attach(ctx, { log: true }).forKey(ipAddress);
+  const maxSignupsPerDay = resolveSignupLimit(Manager.config);
+
+  try {
+    await usage.consume('signups', 1, { limit: maxSignupsPerDay });
+  } catch (e) {
+    // ONLY a rate limit is a rate limit. consume() also throws 500s — a
+    // Firestore outage, a feature the catalog does not define — and selling one
+    // of those as "too many signups from your IP" is a diagnosis nobody can act
+    // on, told to a user who did nothing wrong.
+    if (e.code !== 429) {
+      throw e;
+    }
+
+    ctx.error(`beforeCreate: Too many signups from ${ipAddress} (limit ${maxSignupsPerDay}/day)`);
+
+    throw new functions.auth.HttpsError('resource-exhausted', ERROR_TOO_MANY_ATTEMPTS);
+  }
+
+  // Run consumer hook (can throw HttpsError to block signup)
+  await runAuthHook('before-create', { Manager, ctx, user, context, libraries });
+
+  ctx.log(`beforeCreate: Completed for ${user.uid} (${Date.now() - startTime}ms)`);
+};

package/dist/manager/events/auth/before-signin.js

@@ -0,0 +1,76 @@
+/**
+ * beforeUserSignedIn - Update activity + send sign-in analytics
+ *
+ * This function fires on every sign-in (including right after account creation).
+ * It updates last activity and sends sign-in analytics.
+ *
+ * TODO: Add mailer.sync(uid) here with 1x/day rate limit to keep marketing
+ * contact data (name, country, subscription fields) fresh between sessions.
+ *
+ * Available parameters (1st gen):
+ *
+ * user (AuthUserRecord):
+ *   uid, email, emailVerified, displayName, photoURL, phoneNumber, disabled,
+ *   metadata: { creationTime, lastSignInTime },
+ *   providerData: [{ uid, displayName, email, photoURL, providerId, phoneNumber }],
+ *   passwordHash, passwordSalt, customClaims, tenantId, tokensValidAfterTime, multiFactor
+ *
+ * context (AuthEventContext):
+ *   ipAddress, userAgent, locale, eventId, eventType, authType, resource, timestamp,
+ *   additionalUserInfo: { providerId, profile, username, isNewUser, recaptchaScore, email, phoneNumber },
+ *   credential: { providerId, signInMethod, claims, idToken, accessToken, refreshToken, expirationTime, secret } | null,
+ *   emailType, smsType, params
+ *
+ * Note: recaptchaScore requires reCAPTCHA Enterprise (Google Cloud level), NOT the Firebase SMS fraud toggle.
+ * Note: credential tokens (idToken, accessToken, refreshToken) require opt-in via BlockingOptions.
+ */
+const { runAuthHook } = require('./utils.js');
+
+module.exports = async ({ Manager, ctx, user, context, libraries }) => {
+  const startTime = Date.now();
+  const { admin } = libraries;
+
+  // The UID and nothing else. The AuthUserRecord carries the email, the display
+  // name and the provider data, the AuthEventContext carries the IP, the user
+  // agent and the credential, and a backend line lands in Cloud Logging for the
+  // whole retention window — so none of it rides this line
+  // ([#657](https://github.com/Omega-JS-Stack/omega/issues/657)). Both stay
+  // reachable one level down, at debug.
+  ctx.log(`beforeSignIn: ${user.uid}`);
+  ctx.debug(`beforeSignIn: ${user.uid} record`, user, context);
+
+  const now = new Date();
+
+  // Update last activity and geolocation
+  const update = await admin.firestore().doc(`users/${user.uid}`)
+    .set({
+      metadata: {
+        updated: {
+          timestamp: now.toISOString(),
+          timestampUNIX: Math.round(now.getTime() / 1000),
+        },
+      },
+      activity: {
+        geolocation: {
+          ip: context.ipAddress,
+        },
+        client: {
+          userAgent: context.userAgent,
+          language: context.locale,
+        },
+      },
+    }, { merge: true })
+    .catch(e => e);
+
+  if (update instanceof Error) {
+    ctx.error(`beforeSignIn: Failed to update user ${user.uid}:`, update);
+    // Don't block sign-in for activity update failure
+  } else {
+    ctx.log(`beforeSignIn: Updated user activity`);
+  }
+
+  // Run consumer hook (can throw HttpsError to block sign-in)
+  await runAuthHook('before-signin', { Manager, ctx, user, context, libraries });
+
+  ctx.log(`beforeSignIn: Completed for ${user.uid} (${Date.now() - startTime}ms)`);
+};