@omega.js/backend 0.1.0

package/dist/manager/libraries/user-doc.js

@@ -0,0 +1,234 @@
+/**
+ * The user doc's BIRTH — the one shape a `users/{uid}` doc is created in, and
+ * the heal that recreates it when it went missing behind a real account.
+ *
+ * A doc is born at signup (auth:on-create). Out-of-sync states happen in the
+ * wild, so an auth user whose doc is gone gets it back at the next moment it is
+ * needed: sign-in ([#405](https://github.com/Omega-JS-Stack/omega/issues/405)).
+ * Both paths build the SAME record here — a heal that hand-rolled its own shape
+ * would drift from the one a signup writes the day either side changes.
+ *
+ * The opposite direction (a doc with no auth user) is never healed: the payment
+ * guards refuse it and the users migration cleans it up
+ * ([#399](https://github.com/Omega-JS-Stack/omega/issues/399)).
+ */
+
+const _ = require('lodash');
+const { getAuthUser } = require('./auth-user.js');
+
+// metadata.tag the heal stamps, so a healed doc is findable in the database — it
+// is the only tag that says "this account's doc was recreated after the fact".
+const HEAL_TAG = 'auth:heal';
+
+// How long after an account is created the heal stands down and leaves the first
+// write to auth:on-create (which the signup route already polls for).
+const SIGNUP_WINDOW_MS = 120000;
+
+/**
+ * Whether a users/{uid} doc is a REAL user doc rather than residue
+ *
+ * `auth.uid` is what a birth writes and what nothing else does: auth:before-signin
+ * merge-writes activity onto users/{uid} on every sign-in, so a doc-less account
+ * already HAS a doc by the time a request arrives — one holding nothing but
+ * activity. Existence alone reads that as an account.
+ *
+ * @param {object|null} data - The doc data, or null when the doc does not exist
+ * @returns {boolean}
+ */
+function isUserDoc(data) {
+  return !!data?.auth?.uid;
+}
+
+/**
+ * Build the user doc for a Firebase Auth user record
+ *
+ * @param {object} Manager - The booted Manager (owns the User schema + Metadata)
+ * @param {object} user - The firebase-admin UserRecord the doc belongs to
+ * @param {string} tag - metadata.tag naming the seam writing it
+ * @returns {object} The complete user doc, ready to write
+ */
+function buildUserDoc({ Manager, user, tag }) {
+  const providerName = extractProviderName(user);
+
+  // Create user record using Manager.User() helper
+  const userRecord = Manager.User({
+    auth: {
+      uid: user.uid,
+      email: user.email,
+    },
+    personal: providerName ? {
+      name: providerName,
+    } : undefined,
+  }).properties;
+
+  // Add metadata tag (merge into existing metadata to preserve metadata.created from User schema)
+  const meta = Manager.Metadata().set({ tag: tag });
+  userRecord.metadata = { ...userRecord.metadata, ...meta };
+
+  // Stamp metadata.created from Firebase Auth's creationTime (the canonical account-creation
+  // moment) rather than the User schema's "now" — otherwise the doc lands a beat after Auth,
+  // and the OMEGA user migration reconciles every new signup against Auth on its next run.
+  const creationTime = user.metadata?.creationTime;
+  if (creationTime) {
+    const createdDate = new Date(creationTime);
+    userRecord.metadata.created = {
+      timestamp: createdDate.toISOString(),
+      timestampUNIX: Math.round(createdDate.getTime() / 1000),
+    };
+  }
+
+  return userRecord;
+}
+
+/**
+ * Recreate a missing user doc for a signed-in caller
+ *
+ * Idempotent: the write runs in a transaction, so whichever of the two writers
+ * arrives second finds the doc and leaves it alone. One doc per uid, never a
+ * duplicate account, whichever order the two land in:
+ *   - on-create first → the transaction reads a real doc and writes nothing.
+ *   - heal first → on-create's own "already exists" check skips it.
+ * The signup window below keeps that second order off a brand-new account
+ * entirely, so on-create's write stays the authoritative one for every real
+ * signup. Existing values win over the freshly generated schema defaults, so
+ * nothing already on the doc (before-signin's activity, an api key) is clobbered.
+ *
+ * @param {object} Manager - The booted Manager
+ * @param {object} ctx - The RouteContext to log through
+ * @param {object} admin - The firebase-admin app
+ * @param {string} uid - The uid whose doc is missing
+ * @returns {Promise<object|null>} The doc that now exists, or null when there was nothing to heal
+ */
+async function healUserDoc({ Manager, ctx, admin, uid }) {
+  // The auth user is the proof the doc SHOULD exist. A verified ID token outlives
+  // a deleted account by up to an hour, and recreating a doc for one would mint
+  // exactly the auth-less zombie the payment guards refuse (#399).
+  const authUser = await getAuthUser(admin, uid);
+
+  if (!authUser) {
+    ctx.warn(`Not healing users/${uid}: the ID token verifies but the account no longer exists in Auth`);
+    return null;
+  }
+
+  // Anonymous accounts get no user doc anywhere in the framework. The same rule
+  // auth:on-create applies, read off the same record — an account with no
+  // providerData at all is an anonymous sign-in.
+  if (isAnonymous(authUser)) {
+    ctx.log(`Not healing users/${uid}: anonymous accounts get no user doc`);
+    return null;
+  }
+
+  // A signup still in flight belongs to auth:on-create, not here. Its write is
+  // what runs the consumer hook, and a heal that got there first would take that
+  // job away: on-create's own "already exists" check would then skip the account
+  // for good. Inside the window a
+  // doc-less caller is answered exactly as it was before the heal existed, and
+  // the signup route is already polling for the doc it is waiting on.
+  const age = accountAge(authUser);
+
+  if (age !== null && age < SIGNUP_WINDOW_MS) {
+    ctx.log(`Not healing users/${uid}: the account is ${Math.round(age / 1000)}s old, so auth:on-create still owns its first write`);
+    return null;
+  }
+
+  const record = buildUserDoc({ Manager: Manager, user: authUser, tag: HEAL_TAG });
+
+  // A healed account signed up long ago, so its signup flow is long over. Leaving
+  // flags.signupProcessed false sends the next page load back through all of it
+  // (welcome emails, affiliate credit, marketing sync) against an established
+  // account. Stamped on the heal path ONLY — a real new signup still has that
+  // flow ahead of it, so what auth:on-create writes is unchanged.
+  // Assumes the residue the merge below preserves carries no flags of its own:
+  // existing values win there, so a doc-less account that somehow arrived with
+  // flags.signupProcessed=false would keep it. Nothing writes flags onto a
+  // doc-less account today (before-signin writes metadata + activity, nothing else).
+  record.flags = { ...record.flags, signupProcessed: true };
+
+  const ref = admin.firestore().doc(`users/${uid}`);
+
+  const result = await admin.firestore().runTransaction(async (transaction) => {
+    const snapshot = await transaction.get(ref);
+    const existing = snapshot.exists ? snapshot.data() : null;
+
+    // Somebody won the race — a doc that is already real is left exactly as it is
+    if (isUserDoc(existing)) {
+      return { doc: existing, wrote: false };
+    }
+
+    // Deepest-first: the schema-complete record, then whatever residue the doc
+    // already carries (real values win over defaults). _.merge mutates its first
+    // arg, so start from a fresh object.
+    const merged = _.merge({}, record, existing || {});
+
+    transaction.set(ref, merged);
+
+    return { doc: merged, wrote: true };
+  });
+
+  if (result.wrote) {
+    // Loud on purpose: a signed-in account with no doc is a database out of sync
+    // with Auth, and silence here would hide every one of them.
+    ctx.warn(`Healed users/${uid}: a verified caller had no user doc, so it was recreated from the Auth record (tag=${HEAL_TAG})`);
+  } else {
+    ctx.log(`No heal needed for users/${uid}: the doc was written while the heal was running`);
+  }
+
+  return result.doc;
+}
+
+/**
+ * Whether an Auth record is an anonymous sign-in, exactly as auth:on-create reads it
+ *
+ * An account with an EMPTY providerData qualifies: nothing federated and no
+ * password is what an anonymous sign-in leaves behind.
+ *
+ * @param {object} user - The firebase-admin UserRecord
+ * @returns {boolean}
+ */
+function isAnonymous(user) {
+  return !!user.providerData?.every((p) => p.providerId === 'anonymous');
+}
+
+/**
+ * How long ago Firebase Auth created this account, in ms
+ *
+ * A future-dated creationTime (an imported record carrying a skewed clock) reads
+ * as in-window forever, so such an account is never healed. Assumed acceptable:
+ * that is the pre-heal status quo for it, and Auth stamps its own clock on every
+ * account created the normal way.
+ *
+ * @param {object} user - The firebase-admin UserRecord
+ * @returns {number|null} The age, or null when the record carries no usable
+ *   creationTime — nothing to judge the signup window by, so the heal proceeds
+ */
+function accountAge(user) {
+  const created = new Date(user.metadata?.creationTime || '').getTime();
+
+  return Number.isNaN(created) ? null : Date.now() - created;
+}
+
+/**
+ * Extract first/last name from provider data (Google, Facebook, GitHub, etc.)
+ * Returns { first, last } or null if no name found
+ */
+function extractProviderName(user) {
+  // Try provider-specific displayName first, then top-level displayName
+  const displayName = user.providerData?.find(p =>
+    p.providerId !== 'password'
+    && p.providerId !== 'anonymous'
+    && p.displayName
+  )?.displayName || user.displayName;
+
+  if (!displayName) {
+    return null;
+  }
+
+  const parts = displayName.trim().split(/\s+/);
+
+  return {
+    first: parts[0] || null,
+    last: parts.slice(1).join(' ') || null,
+  };
+}
+
+module.exports = { buildUserDoc, healUserDoc, isUserDoc, extractProviderName, HEAL_TAG, SIGNUP_WINDOW_MS };

package/dist/manager/routes/admin/backup/post.js

@@ -0,0 +1,106 @@
+/**
+ * POST /admin/backup - Backup Firestore
+ * Admin-only endpoint to export Firestore to Cloud Storage
+ */
+const moment = require('moment');
+const powertools = require('node-powertools');
+const { Storage } = require('@google-cloud/storage');
+
+const storage = new Storage();
+
+module.exports = async ({ ctx, Manager, user, settings, analytics, libraries }) => {
+  const { admin } = libraries;
+
+  // Require authentication (allow in dev)
+  if (!user.authenticated && ctx.isProduction()) {
+    return ctx.respond('Authentication required', { code: 401 });
+  }
+
+  // Require admin (allow in dev)
+  if (!user.roles.admin && ctx.isProduction()) {
+    return ctx.respond('Admin required.', { code: 403 });
+  }
+
+  // Parse deletion regex if provided
+  settings.deletionRegex = settings.deletionRegex
+    ? powertools.regexify(settings.deletionRegex)
+    : settings.deletionRegex;
+
+  // Setup Firestore Admin Client
+  const client = new admin.firestore.v1.FirestoreAdminClient({});
+  const projectId = Manager.project.projectId;
+  const resourceZone = Manager.project.resourceZone;
+  const databaseName = client.databasePath(projectId, '(default)');
+  const bucketName = `bm-backup-firestore-${projectId}`;
+  const bucketAddress = `gs://${bucketName}`;
+
+  // Ensure bucket exists
+  await createBucket(ctx, bucketName, resourceZone);
+
+  // Export documents
+  const result = await client.exportDocuments({
+    name: databaseName,
+    outputUriPrefix: bucketAddress,
+    collectionIds: [],
+  }).catch(async (e) => {
+    await setMetaStats(ctx, e);
+    return e;
+  });
+
+  if (result instanceof Error) {
+    return ctx.respond(result.message, { code: 500 });
+  }
+
+  const response = result[0];
+
+  ctx.log('Saved backup successfully:', response.metadata.outputUriPrefix);
+
+  await setMetaStats(ctx, null);
+
+  // Track analytics
+  analytics.event('admin/backup', { status: 'success' });
+
+  return ctx.respond({ name: response['name'] });
+};
+
+// Helper: Set meta stats
+async function setMetaStats(ctx, error) {
+  const { admin } = ctx.Manager.libraries;
+  const isError = error instanceof Error;
+
+  await admin.firestore().doc('meta/stats')
+    .set({
+      backups: {
+        lastBackup: {
+          date: {
+            timestamp: ctx.meta.startTime.timestamp,
+            timestampUNIX: ctx.meta.startTime.timestampUNIX,
+          },
+          status: {
+            success: !isError,
+            error: isError ? error.message : null,
+          }
+        }
+      },
+      metadata: ctx.Manager.Metadata().set({ tag: 'admin/backup' }),
+    }, { merge: true })
+    .catch(e => {
+      ctx.error('Failed to update meta stats', e);
+    });
+}
+
+// Helper: Create bucket if it doesn't exist
+async function createBucket(ctx, bucketName, resourceZone) {
+  try {
+    const meta = await storage.bucket(bucketName).getMetadata();
+    ctx.log(`${bucketName} metadata`, meta[0]);
+  } catch (e) {
+    // Bucket doesn't exist, create it
+    const result = await storage.createBucket(bucketName, {
+      location: resourceZone,
+      storageClass: 'COLDLINE',
+    }).catch(err => err);
+
+    ctx.log('storageCreation', result);
+  }
+}

package/dist/manager/routes/admin/cron/post.js

@@ -0,0 +1,37 @@
+/**
+ * POST /admin/cron - Run cron job manually
+ * Admin-only endpoint to trigger cron jobs
+ */
+module.exports = async ({ ctx, Manager, user, settings, analytics }) => {
+
+  // Require authentication (allow in dev)
+  if (!user.authenticated && ctx.isProduction()) {
+    return ctx.respond('Authentication required', { code: 401 });
+  }
+
+  // Require admin (allow in dev)
+  if (!user.roles.admin && ctx.isProduction()) {
+    return ctx.respond('Admin required.', { code: 403 });
+  }
+
+  // Check for required parameter
+  if (!settings.id) {
+    return ctx.respond('Missing parameter {id}', { code: 400 });
+  }
+
+  ctx.log('Running cron job:', settings.id);
+
+  // Run the cron job
+  const cronPath = `${Manager.rootDirectory}/events/cron/${settings.id}.js`;
+  const cronHandler = require(cronPath);
+  const result = await cronHandler({ Manager, ctx, context: {}, libraries: Manager.libraries }).catch(e => e);
+
+  if (result instanceof Error) {
+    return ctx.respond(result.message, { code: 500 });
+  }
+
+  // Track analytics
+  analytics.event('admin/cron', { id: settings.id });
+
+  return ctx.respond(result);
+};

package/dist/manager/routes/admin/database/get.js

@@ -0,0 +1,35 @@
+/**
+ * GET /admin/database - Read Realtime Database
+ * Admin-only endpoint to read any path
+ */
+module.exports = async ({ ctx, user, settings, libraries }) => {
+  const { admin } = libraries;
+
+  // Require authentication
+  if (!user.authenticated) {
+    return ctx.respond('Authentication required', { code: 401 });
+  }
+
+  // Require admin
+  if (!user.roles.admin) {
+    return ctx.respond('Admin required.', { code: 403 });
+  }
+
+  // Require path
+  if (!settings.path) {
+    return ctx.respond('Path parameter required.', { code: 400 });
+  }
+
+  ctx.log('main(): Read', settings.path);
+
+  // Read from Realtime Database
+  const snapshot = await admin.database().ref(settings.path).once('value')
+    .catch((e) => e);
+
+  if (snapshot instanceof Error) {
+    return ctx.respond(snapshot.message, { code: 500 });
+  }
+
+  // Return empty object if path doesn't exist (snapshot.val() returns null)
+  return ctx.respond(snapshot.val() || {});
+};

package/dist/manager/routes/admin/database/post.js

@@ -0,0 +1,34 @@
+/**
+ * POST /admin/database - Write Realtime Database
+ * Admin-only endpoint to write any path
+ */
+module.exports = async ({ ctx, user, settings, libraries }) => {
+  const { admin } = libraries;
+
+  // Require authentication
+  if (!user.authenticated) {
+    return ctx.respond('Authentication required', { code: 401 });
+  }
+
+  // Require admin
+  if (!user.roles.admin) {
+    return ctx.respond('Admin required.', { code: 403 });
+  }
+
+  // Require path
+  if (!settings.path) {
+    return ctx.respond('Path parameter required.', { code: 400 });
+  }
+
+  ctx.log('main(): Write', settings.path, settings.document);
+
+  // Write to Realtime Database
+  const write = await admin.database().ref(settings.path).set(settings.document)
+    .catch((e) => e);
+
+  if (write instanceof Error) {
+    return ctx.respond(write.message, { code: 500 });
+  }
+
+  return ctx.respond(settings.document);
+};

package/dist/manager/routes/admin/email/post.js

@@ -0,0 +1,74 @@
+/**
+ * POST /admin/email - Send email via SendGrid
+ *
+ * Admin-only endpoint to send transactional emails.
+ * Supports flexible recipient formats (string, object, UID, or arrays of mixed).
+ *
+ * See: src/manager/libraries/email/ for the shared email builder and sender.
+ */
+const prepare = require('../../../libraries/email/prepare.js');
+const env = require('../../../libraries/env.js');
+
+/**
+ * How many recipients a send carries, across to/cc/bcc.
+ *
+ * Each field is a string, an object, or an array of either — the count is all the log
+ * needs, so no address is ever read out of them.
+ *
+ * @param {object} settings - Caller-supplied send settings
+ * @returns {number} Total recipient entries
+ */
+function recipientCount(settings) {
+  return ['to', 'cc', 'bcc'].reduce((total, field) => {
+    const value = settings[field];
+
+    if (!value) {
+      return total;
+    }
+
+    return total + (Array.isArray(value) ? value.length : 1);
+  }, 0);
+}
+
+module.exports = async ({ ctx, user, settings }) => {
+  // Require authentication
+  if (!user.authenticated) {
+    return ctx.respond('Authentication required', { code: 401 });
+  }
+
+  // Require admin
+  if (!user.roles.admin) {
+    return ctx.respond('Admin required.', { code: 403 });
+  }
+
+  // The raw-HTML fields are internal-caller only — this route (and the MCP
+  // send_email tool that calls it) sends markdown through the escaped lane.
+  const internalOnlyFault = prepare.internalOnlyFieldFault(settings);
+
+  if (internalOnlyFault) {
+    // Log the rejection so the attempt leaves a trace — the field name only, never
+    // the payload it tried to smuggle.
+    ctx.log(`Rejected: ${internalOnlyFault.message}`);
+
+    return ctx.respond(internalOnlyFault.message, { code: internalOnlyFault.code });
+  }
+
+  // Check for SendGrid key
+  if (!env.has('SENDGRID_API_KEY')) {
+    return ctx.respond('SendGrid API key not configured.', { code: 500 });
+  }
+
+  // Metadata only — never the payload. The full settings object carries every
+  // recipient address and the body itself, and this line lands in Cloud Logging where
+  // it outlives the send ([#127](https://github.com/Omega-JS-Stack/omega/issues/127)).
+  ctx.log(`Request: recipients=${recipientCount(settings)}, template=${settings.template}, subject=${settings.subject}`);
+
+  const email = ctx.Manager.Email(ctx);
+  const result = await email.send(settings).catch(e => e);
+
+  if (result instanceof Error) {
+    return ctx.respond(result.message, { code: result.code || 500 });
+  }
+
+  return ctx.respond(result);
+};

package/dist/manager/routes/admin/firestore/get.js

@@ -0,0 +1,35 @@
+/**
+ * GET /admin/firestore - Read Firestore document
+ * Admin-only endpoint to read any document
+ */
+module.exports = async ({ ctx, user, settings, libraries }) => {
+  const { admin } = libraries;
+
+  // Require authentication
+  if (!user.authenticated) {
+    return ctx.respond('Authentication required', { code: 401 });
+  }
+
+  // Require admin
+  if (!user.roles.admin) {
+    return ctx.respond('Admin required.', { code: 403 });
+  }
+
+  // Require path
+  if (!settings.path) {
+    return ctx.respond('Path parameter required.', { code: 400 });
+  }
+
+  ctx.log('main(): Reading', settings.path);
+
+  // Read from Firestore
+  const doc = await admin.firestore().doc(settings.path).get()
+    .catch((e) => e);
+
+  if (doc instanceof Error) {
+    return ctx.respond(doc.message, { code: 500 });
+  }
+
+  // Return empty object if document doesn't exist (doc.data() returns undefined)
+  return ctx.respond(doc.data() || {});
+};

package/dist/manager/routes/admin/firestore/post.js

@@ -0,0 +1,56 @@
+const pushid = require('pushid');
+
+/**
+ * POST /admin/firestore - Write Firestore document
+ * Admin-only endpoint to write any document
+ */
+module.exports = async ({ ctx, Manager, user, settings, libraries }) => {
+  const { admin } = libraries;
+
+  // Require authentication
+  if (!user.authenticated) {
+    return ctx.respond('Authentication required', { code: 401 });
+  }
+
+  // Require admin
+  if (!user.roles.admin) {
+    return ctx.respond('Admin required.', { code: 403 });
+  }
+
+  // Require path
+  if (!settings.path) {
+    return ctx.respond('Path parameter required.', { code: 400 });
+  }
+
+  // Process path placeholders
+  let path = settings.path;
+
+  if (path.includes('{pushId}')) {
+    path = path.replace(/\{pushId\}/gi, pushid());
+  } else if (path.includes('{nanoId}')) {
+    path = path.replace(/\{nanoId\}/gi, Manager.Utilities().randomId());
+  }
+
+  // Prepare document
+  const document = {
+    ...settings.document,
+    metadata: Manager.Metadata().set({ tag: settings.metadataTag }),
+  };
+
+  // Build options
+  const options = {
+    merge: settings.merge,
+  };
+
+  ctx.log('main(): Writing', path, document, options);
+
+  // Write to Firestore
+  const write = await admin.firestore().doc(path).set(document, options)
+    .catch((e) => e);
+
+  if (write instanceof Error) {
+    return ctx.respond(write.message, { code: 500 });
+  }
+
+  return ctx.respond({ path });
+};