@omega.js/backend 0.1.0

package/dist/manager/routes/special/electron-client/post.js

@@ -0,0 +1,59 @@
+/**
+ * POST /special/electron-client - Setup Electron Manager client
+ * Returns client configuration with optional auth
+ */
+const path = require('path');
+const { buildPublicConfig } = require(path.join(__dirname, '..', '..', 'brand', 'get.js'));
+
+module.exports = async ({ ctx, Manager, settings, analytics, libraries }) => {
+  const { admin } = libraries;
+
+  // brandId/brand fallback to Manager.config
+  let uid = settings.uid;
+  let config = settings.config;
+
+  let uuid = null;
+  let signInToken = null;
+
+  // If authenticated, get user and create custom token
+  const user = ctx.getUser();
+  if (user.authenticated && user.roles?.admin) {
+    uid = user.auth?.uid ?? null;
+
+    if (uid) {
+      try {
+        signInToken = await admin.auth().createCustomToken(uid);
+      } catch (e) {
+        return ctx.respond(`Failed to create custom token: ${e}`, { code: 500 });
+      }
+    }
+  }
+
+  // Generate UUID if uid is available
+  if (uid) {
+    const uuidLib = Manager.require('uuid');
+    const NAMESPACE = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
+    uuid = uuidLib.v5(uid, NAMESPACE);
+  }
+
+  // Validate config — kept only when the REQUEST is admin-authenticated (the
+  // omega-admin-key header); the config payload itself never carries a secret
+  if (user.roles?.admin) {
+    ctx.log('Validated config', config);
+  } else {
+    config = {};
+  }
+
+  // Track analytics
+  analytics.event('special/electron-client', { action: 'setup' });
+
+  return ctx.respond({
+    uuid: uuid,
+    signInToken: signInToken,
+    timestamp: new Date().toISOString(),
+    ip: ctx.request.geolocation.ip,
+    country: ctx.request.geolocation.country,
+    brand: buildPublicConfig(Manager.config),
+    config: config,
+  });
+};

package/dist/manager/routes/test/authenticate/get.js

@@ -0,0 +1,11 @@
+const { projectUserForLog } = require('../../../helpers/middleware.js');
+
+module.exports = async ({ ctx, user }) => {
+
+  // Log user info — the allow-listed projection, never the document: it carries
+  // api.privateKey ([#632](https://github.com/Omega-JS-Stack/omega/issues/632))
+  ctx.log('User:', projectUserForLog(user));
+
+  // Return user info
+  return ctx.respond({ user });
+};

package/dist/manager/routes/test/health/get.js

@@ -0,0 +1,8 @@
+/**
+ * GET /test/health — the liveness probe's old home, kept for the dev/testing
+ * callers that still ask for it. ONE implementation: the probe is a real route
+ * now (`routes/health`), and this folder is development-only, so the path 404s
+ * in production like every other test route
+ * ([#238](https://github.com/Omega-JS-Stack/omega/issues/238)).
+ */
+module.exports = require('../../health/get.js');

package/dist/manager/routes/test/index.js

@@ -0,0 +1,16 @@
+module.exports = async ({ ctx, analytics }) => {
+
+  // Send analytics event
+  analytics.event('test', {});
+
+  // Log
+  ctx.log('Running test');
+  ctx.log('ctx.request.body', ctx.request.body);
+  ctx.log('ctx.request.query', ctx.request.query);
+  ctx.log('ctx.request.headers', ctx.request.headers);
+  ctx.log('ctx.request.data', ctx.request.data);
+  ctx.log('ctx.settings', ctx.settings);
+
+  // Return success
+  return ctx.respond({timestamp: new Date().toISOString(), id: ctx.id});
+};

package/dist/manager/routes/test/lab/post.js

@@ -0,0 +1,17 @@
+module.exports = async ({ ctx, user, settings }) => {
+
+  // Check admin
+  if (!user.roles.admin) {
+    ctx.log('User is not admin');
+  }
+
+  // Example: Send notification (demonstrates calling another @omega.js/backend endpoint)
+  const url = 'https://itwcreativeworks.com';
+  const title = 'https://itwcreativeworks.com';
+  const icon = 'https://cdn.itwcreativeworks.com/assets/itw-creative-works/images/socials/itw-creative-works-brandmark-square-black-1024x1024.png?cb=1651834176';
+
+  // For now, just return success - the lab is a testing sandbox
+  ctx.log('Lab test executed', { url, title, icon });
+
+  return ctx.respond({ success: true });
+};

package/dist/manager/routes/test/redirect/get.js

@@ -0,0 +1,27 @@
+/**
+ * GET /test/redirect
+ * Exercises ctx.redirect(). Development-only like the rest of the `test/`
+ * folder (the middleware gates the whole family), and RELATIVE PATHS ONLY.
+ */
+module.exports = async ({ ctx, settings }) => {
+
+  // Get URL from settings (defaults to the site root)
+  const url = settings.url;
+
+  // Reflecting a caller-supplied absolute URL would make this an open redirect.
+  // Refuse a scheme (`https:`, `javascript:`) and the protocol-relative forms
+  // (`//host`, `/\host`, which browsers treat as `//host`) outright rather than
+  // trying to sanitize them.
+  const isRelative = url.startsWith('/') && !url.startsWith('//') && !url.startsWith('/\\');
+
+  if (!isRelative) {
+    // The refused value is logged, never echoed into the response body.
+    ctx.log('Refusing to redirect to a non-relative URL', url);
+
+    return ctx.respond('Only relative paths may be redirected to', { code: 400 });
+  }
+
+  ctx.log('Redirecting', url);
+
+  return ctx.redirect(url);
+};

package/dist/manager/routes/test/reset-account/post.js

@@ -0,0 +1,79 @@
+const { resolvedBrandHost } = require('../../../../vendor/config/index.js');
+const { getAccountDefinitions, createAccount, seedOrderFixture, seedSessionFixture } = require('../../../../test/test-accounts.js');
+
+/**
+ * POST /test/reset-account
+ * Restore the CALLER's own seeded persona to its seed shape — the user doc
+ * `test-accounts.js` defines plus its canonical purchase record — so a browser
+ * flow that mutated a persona (a cancellation, an upgrade, a trial) can be run
+ * again without rebooting the emulator.
+ *
+ * The one route in the framework that reads the seeder from a request handler:
+ * the seeder IS the shape, so re-seeding here can never drift from the boot
+ * seed. Development/testing only, and only for the account the caller is
+ * signed in as — there is no uid parameter.
+ */
+module.exports = async ({ ctx, user }) => {
+  // Emulator-only: never a route outside development/testing (an explicit
+  // positive check, per the context contract — not `!isProduction()`)
+  if (!ctx.isDevelopment() && !ctx.isTesting()) {
+    return ctx.respond('Not found', { code: 404 });
+  }
+
+  // Require authentication
+  if (!user.authenticated) {
+    return ctx.respond('Authentication required', { code: 401 });
+  }
+
+  const admin = ctx.Manager.libraries.admin;
+  const config = ctx.Manager.config;
+  // An admin-key caller authenticates without being anybody, and this route
+  // only ever acts on the account it is called AS.
+  const uid = user.auth?.uid;
+
+  // The seeder resolves persona emails against the brand's HOST — the same
+  // derivation `omega emulator` seeds with, and the one the dev palette signs
+  // in on ([#708](https://github.com/Omega-JS-Stack/omega/issues/708)).
+  const domain = resolvedBrandHost(config);
+  const definitions = getAccountDefinitions(domain, config);
+  const entry = Object.entries(definitions).find(([, definition]) => definition.uid === uid);
+
+  // Only a persona the FRAMEWORK seeds may be reset: resetting deletes and
+  // recreates the account, which no real user's account may ever undergo.
+  if (!entry) {
+    ctx.log(`test/reset-account: refused — uid ${uid} is not a seeded test account`);
+    return ctx.respond('Not a seeded test account', { code: 403 });
+  }
+
+  const [key, definition] = entry;
+
+  ctx.log(`test/reset-account: resetting persona ${key} (${definition.email}) to its seed`);
+
+  // Clear the persona's purchase records FIRST — a journey buys its own
+  // orders, and a stale one would outlive the reset and re-disqualify the
+  // persona from a trial it is supposed to be offered.
+  const orders = await admin.firestore().collection('payments-orders').where('owner', '==', uid).get();
+  await Promise.all(orders.docs.map((doc) => doc.ref.delete()));
+
+  // Re-run the seeder's own per-account primitive (auth delete + create, then
+  // the seed properties merged over the fresh doc) and stand the persona's
+  // canonical order fixture back up. Its active sessions come back too: they
+  // live in the Realtime Database rather than on the doc, so recreating the
+  // account leaves them behind — and signing out of all sessions is one of the
+  // flows a browser rehearses on this persona.
+  await createAccount(admin, definition);
+  const order = await seedOrderFixture(admin, key, config);
+  const sessions = await seedSessionFixture(admin, key);
+
+  ctx.log(`test/reset-account: ${key} reset (${orders.size} order(s) cleared, ${order ? `order ${order.orderId} reseeded` : 'no order fixture'}, ${sessions ? `${sessions.length} session(s) reseeded` : 'no session fixtures'})`);
+
+  return ctx.respond({
+    success: true,
+    persona: key,
+    uid,
+    email: definition.email,
+    ordersCleared: orders.size,
+    orderId: order?.orderId || null,
+    sessions: sessions?.length || 0,
+  });
+};

package/dist/manager/routes/test/roster/get.js

@@ -0,0 +1,40 @@
+const path = require('path');
+const { getPaletteRoster } = require('../../../../test/test-accounts.js');
+const { loadSeedAccounts } = require('../../../../test/seed.js');
+
+/**
+ * GET /test/roster
+ * The personas a HUMAN switches between: every seeded account that carries a
+ * `palette` label, in the order the seeder declares them.
+ * The seed is the ONE owner of that roster ([#400](https://github.com/Omega-JS-Stack/omega/issues/400)):
+ * the dev palette used to keep a hand-curated copy of the list, and the two
+ * drifted apart the moment a persona was seeded without one being added.
+ *
+ * The WHOLE seed, both halves ([#712](https://github.com/Omega-JS-Stack/omega/issues/712)):
+ * the framework's own table plus the project's `test/_init.js` accounts — the
+ * documented extension point the seeder itself merges in. Reading the table
+ * alone made a consumer persona carrying a label invisible, which is the exact
+ * drift #400 built this route to end.
+ *
+ * Development/testing only, and deliberately unauthenticated: the palette asks
+ * for the roster before anybody is signed in, which is the whole point of it.
+ */
+module.exports = async ({ ctx }) => {
+  // Emulator-only: never a route outside development/testing (an explicit
+  // positive check, per the context contract, not `!isProduction()`)
+  if (!ctx.isDevelopment() && !ctx.isTesting()) {
+    return ctx.respond('Not found', { code: 404 });
+  }
+
+  // Manager.cwd is the consumer's functions/ directory; test/_init.js lives one
+  // level up at <projectRoot>/test/ — the same resolution the test-mode watcher
+  // makes. Loaded once per process, not per request.
+  const projectDir = path.dirname(ctx.Manager.cwd);
+  const projectAccounts = loadSeedAccounts({ projectDir, config: ctx.Manager.config, Manager: ctx.Manager });
+
+  const personas = getPaletteRoster(projectAccounts);
+
+  ctx.log(`test/roster: ${personas.length} palette persona(s)`);
+
+  return ctx.respond({ personas });
+};

package/dist/manager/routes/test/schema/post.js

@@ -0,0 +1,20 @@
+/**
+ * POST /test/schema - Test schema validation
+ * Returns the resolved settings for testing purposes
+ */
+module.exports = async ({ ctx, user, settings }) => {
+  ctx.log('test/schema: User subscription info', {
+    subscriptionId: user.subscription?.product?.id,
+    subscriptionStatus: user.subscription?.status,
+    fullSubscription: user.subscription,
+  });
+
+  return ctx.respond({
+    settings,
+    user: {
+      authenticated: user.authenticated,
+      uid: user.auth?.uid || null,
+      subscription: user.subscription?.product?.id || 'basic',
+    },
+  });
+};

package/dist/manager/routes/test/usage/post.js

@@ -0,0 +1,44 @@
+/**
+ * POST /test/usage - Test usage tracking
+ * Consumes the 'requests' counted feature and returns what the call left behind
+ * Signed-in callers count on their own account; anonymous callers count against
+ * their IP, which is an EXPLICIT keyed counter
+ * ([#647](https://github.com/Omega-JS-Stack/omega/issues/647))
+ */
+module.exports = async ({ ctx, user, settings }) => {
+  const amount = settings.amount;
+
+  // Anonymous callers are keyed EXPLICITLY — a key can never silently move a
+  // signed-in user's own counters into the anonymous store
+  const usage = user.authenticated
+    ? ctx.usage
+    : ctx.usage.forKey(ctx.request.geolocation.ip);
+
+  const before = await usage.read('requests');
+
+  // Check, count and write, in one call — a 429 is thrown, never returned
+  const after = await usage.consume('requests', amount);
+
+  // Log
+  ctx.log(`test/usage: Consumed ${amount} requests`, {
+    authenticated: user.authenticated,
+    key: usage.key,
+    before: { used: before.used, left: before.left, day: before.day },
+    after: after,
+  });
+
+  return ctx.respond({
+    feature: 'requests',
+    amount,
+    authenticated: user.authenticated,
+    key: usage.key,
+    limit: before.limit,
+    dayLimit: before.day.limit,
+    before: {
+      used: before.used,
+      left: before.left,
+      day: { used: before.day.used, left: before.day.left },
+    },
+    after: after,
+  });
+};

package/dist/manager/routes/test/webhook/post.js

@@ -0,0 +1,21 @@
+const powertools = require('node-powertools');
+
+module.exports = async ({ ctx, settings }) => {
+
+  // Optional delay
+  if (settings.delay > 0) {
+    await powertools.wait(settings.delay);
+  }
+
+  // Return based on status code
+  if (settings.status >= 200 && settings.status <= 299) {
+    return ctx.respond(settings.response, { code: settings.status });
+  }
+
+  if (settings.status >= 400 && settings.status <= 599) {
+    return ctx.respond(settings.response, { code: settings.status });
+  }
+
+  // Default response
+  return ctx.respond({ received: true });
+};

package/dist/manager/routes/user/api-keys/post.js

@@ -0,0 +1,51 @@
+const uuid4 = require('uuid').v4;
+const UIDGenerator = require('uid-generator');
+const powertools = require('node-powertools');
+const uidgen = new UIDGenerator(256);
+
+/**
+ * POST /user/api-keys - Regenerate API keys
+ * Regenerates clientId and/or privateKey for the user
+ */
+module.exports = async ({ ctx, Manager, user, settings, libraries }) => {
+  const { admin } = libraries;
+
+  // Require authentication
+  if (!user.authenticated) {
+    return ctx.respond('Authentication required', { code: 401 });
+  }
+
+  // Get target UID
+  const uid = settings.uid;
+
+  // Require admin to regenerate other users' keys
+  if (uid !== user.auth.uid && !user.roles.admin) {
+    return ctx.respond('Admin required', { code: 403 });
+  }
+
+  // Determine which keys to regenerate
+  const keys = powertools.arrayify(settings.keys);
+  const newKeys = {};
+
+  keys.forEach((key) => {
+    if (key.match(/client/i)) {
+      newKeys.clientId = uuid4();
+    } else if (key.match(/private/i)) {
+      newKeys.privateKey = uidgen.generateSync();
+    }
+  });
+
+  // Update user document
+  const write = await admin.firestore().doc(`users/${uid}`)
+    .set({
+      api: newKeys,
+      metadata: Manager.Metadata().set({ tag: 'user/api-keys' }),
+    }, { merge: true })
+    .catch((e) => e);
+
+  if (write instanceof Error) {
+    return ctx.respond(`Failed to generate keys: ${write}`, { code: 500 });
+  }
+
+  return ctx.respond(newKeys);
+};

package/dist/manager/routes/user/connections/_context.js

@@ -0,0 +1,194 @@
+/**
+ * WHO a call acts on, and the two 400s that decide it
+ * ([#793](https://github.com/Omega-JS-Stack/omega/issues/793)): the
+ * authenticated caller, the target user an admin may name, and the destination
+ * an authorize leg may come back to.
+ *
+ * One concern, one file: the provider lookup is `_providers.js`, the secrets
+ * are `_state.js`, the steps are `_grant.js`.
+ */
+
+const { loadProvider } = require('./_providers.js');
+
+/**
+ * The 400 an action that does NOT take `uid` answers when one is passed
+ * ([#782](https://github.com/Omega-JS-Stack/omega/issues/782)).
+ *
+ * `authorize` and `tokenize` are the connecting user's OWN legs — the
+ * authorization URL is opened by their browser and the code comes back from it —
+ * so an admin cannot run them for somebody else. A caller still passing `uid`
+ * was written against the argument they used to take, and ignoring it silently
+ * would answer for the WRONG user; it fails loudly here instead, naming the
+ * argument. A plain read of another user's stored record is the admin firestore
+ * route (`GET /admin/firestore?path=users/<uid>`).
+ *
+ * @param {object} settings - The resolved route settings
+ * @returns {object|null} The error, or null when no uid was passed
+ */
+function droppedUidError(settings) {
+  if (!settings.uid) {
+    return null;
+  }
+
+  return {
+    message: 'The uid parameter is not accepted by this action: it acts on the authenticated user. Use `status`, `refresh` or `delete` to act on another user as an admin, or GET /admin/firestore to read their record.',
+    code: 400,
+  };
+}
+
+// The rule `returnUrl` has to satisfy, in the words the 400 says it in
+// ([#784](https://github.com/Omega-JS-Stack/omega/issues/784))
+const RETURN_PATH_RULE = 'a path on this site: it starts with a single `/` and carries no scheme, no `//`, no backslash and no whitespace (a query and a hash are fine)';
+
+/**
+ * Whether a value is a path on this site — the ONE home of the rule
+ * ([#784](https://github.com/Omega-JS-Stack/omega/issues/784)).
+ *
+ * The value ends up assigned to `location` in the connecting user's browser, so
+ * every shape that could name another origin is out: an absolute URL, a
+ * protocol-relative `//host`, a backslash (browsers read `/\host` as `//host`),
+ * a `javascript:` scheme, and any whitespace a parser might strip on the way to
+ * one of those. What is left is a path, and a path can only land here.
+ *
+ * @param {*} value - The candidate
+ * @returns {boolean} True when it is a path on this site
+ */
+function isSitePath(value) {
+  return typeof value === 'string'
+    && value.startsWith('/')
+    && !value.startsWith('//')
+    && !value.includes('\\')
+    && !/\s/.test(value);
+}
+
+/**
+ * The 400 `authorize` answers when its optional `returnUrl` is not a path
+ * ([#784](https://github.com/Omega-JS-Stack/omega/issues/784)).
+ *
+ * The parameter is optional, so an absent one is no error. A value that is not a
+ * path is refused rather than dropped: a caller that asked to be sent somewhere
+ * would otherwise be silently landed on the default and never learn why.
+ *
+ * @param {object} settings - The resolved route settings
+ * @returns {object|null} The error, or null when no returnUrl was passed or it is a path
+ */
+function returnUrlError(settings) {
+  if (!settings.returnUrl) {
+    return null;
+  }
+
+  if (isSitePath(settings.returnUrl)) {
+    return null;
+  }
+
+  return {
+    // The caller's value is never echoed: it is refused precisely because it may
+    // be an attacker's, and this message can end up on a page
+    message: `The returnUrl parameter must be ${RETURN_PATH_RULE}.`,
+    code: 400,
+  };
+}
+
+/**
+ * Build context object with common connection data
+ * Used by GET, POST, DELETE handlers
+ *
+ * `honorUid` is the per-action flag ([#782](https://github.com/Omega-JS-Stack/omega/issues/782)):
+ * true for the actions a trusted server may run at the provider on a user's
+ * behalf (`status`, `refresh`, `delete`), false for the ones that need the
+ * connecting user's own browser (`authorize`, `tokenize`) — those answer
+ * droppedUidError() rather than acting on anybody.
+ *
+ * @param {object} options
+ * @param {object} options.ctx - The route context
+ * @param {object} options.user - The authenticated caller
+ * @param {object} options.settings - The resolved route settings
+ * @param {boolean} [options.requireProvider] - Load the provider named in `settings`
+ * @param {boolean} [options.honorUid] - Whether an admin's `uid` acts on that user
+ * @returns {Promise<object>} The route context, or `{ error }`
+ */
+async function buildContext({ ctx, user, settings, requireProvider = true, honorUid = false }) {
+  const Manager = ctx.Manager;
+  const { admin } = Manager.libraries;
+
+  // Require authentication
+  if (!user.authenticated) {
+    return { error: { message: 'Authentication required', code: 401 } };
+  }
+
+  if (!honorUid) {
+    const dropped = droppedUidError(settings);
+
+    if (dropped) {
+      return { error: dropped };
+    }
+  }
+
+  // Get target user (admin can manage other users)
+  const targetUid = (honorUid && settings.uid) || user.auth.uid;
+
+  if (targetUid !== user.auth.uid && !user.roles.admin) {
+    return { error: { message: 'Admin required to manage other users', code: 403 } };
+  }
+
+  // Resolve target user data
+  let targetUser = user;
+
+  if (targetUid !== user.auth.uid) {
+    const doc = await admin.firestore().doc(`users/${targetUid}`).get();
+
+    if (!doc.exists) {
+      return { error: { message: 'User not found', code: 404 } };
+    }
+
+    targetUser = doc.data();
+  }
+
+  // Build redirect URI
+  const redirectUri = `${Manager.project.websiteUrl}/connections/callback`;
+
+  // If provider not required (e.g., tokenize gets it from encrypted state), skip loading
+  if (!requireProvider) {
+    return {
+      ctx,
+      Manager,
+      admin,
+      settings,
+      targetUid,
+      targetUser,
+      redirectUri,
+    };
+  }
+
+  // Provider is required
+  if (!settings.provider) {
+    return { error: { message: 'The provider parameter is required', code: 400 } };
+  }
+
+  // The module and the credentials it was registered with, in ONE lookup: the
+  // brand's own dir first, then the package's
+  const resolved = loadProvider(settings.provider, Manager);
+
+  if (resolved.error) {
+    return { error: resolved.error };
+  }
+
+  return {
+    ctx,
+    Manager,
+    admin,
+    connectionProvider: resolved.connectionProvider,
+    settings,
+    targetUid,
+    targetUser,
+    clientId: resolved.clientId,
+    clientSecret: resolved.clientSecret,
+    redirectUri,
+  };
+}
+
+module.exports = {
+  buildContext,
+  droppedUidError,
+  returnUrlError,
+};