@omega.js/backend 0.1.0

package/dist/manager/helpers/usage.js

@@ -0,0 +1,541 @@
+/**
+ * Usage — the counted-feature gate
+ * ([#647](https://github.com/Omega-JS-Stack/omega/issues/647)).
+ *
+ * ONE call does the whole job:
+ *
+ *   const left = await ctx.usage.consume('saves');   // throws a 429 over limit
+ *
+ * `consume` checks both counters, refuses with a 429 that names WHICH one hit,
+ * else counts, writes, and returns what is left. There is no separate
+ * "validate then increment then update" dance for a caller to get half right —
+ * every hand-rolled gate in the framework's own routes existed because there
+ * was one.
+ *
+ * What a feature IS lives in config, once: the top-level `features` catalog
+ * defines it (name, icon, definition, and the `usage` block that meters it)
+ * and each product names only its VALUE. @omega.js/account's features module
+ * owns every derivation from those two halves plus the user's counters — the
+ * effective limit (a per-user override wins over the plan's number), the day
+ * share, what is left — so this gate and the browser's account page can never
+ * speak different numbers.
+ *
+ * Two counters per counted feature per user, month and day. The day's share is
+ * the month limit spread over the days of this month, so a quota cannot be
+ * burned on day one; `usage: { pace: false }` on the catalog entry opts out.
+ * Either counter full refuses, and the month cap always holds.
+ *
+ * Init is LAZY: the middleware `attach`es a counter that resolves the account
+ * on the first consume/read, so a route that never counts pays nothing.
+ *
+ * Anonymous counting is EXPLICIT: `ctx.usage.forKey(ip)` returns a separate
+ * keyed counter. Passing a key can never silently move a signed-in user's
+ * counters into the anonymous store, which is what the old `options.key` did.
+ *
+ * Mirrors are declared in the CATALOG (`usage: { mirror: ['teams'] }`), never
+ * at the call site: `consume` writes the touched feature's counters — that
+ * feature's, not the whole usage object — to the user doc and to every doc the
+ * account owns of each named kind (`owns.teams`), in one parallel write.
+ */
+
+const User = require('./user.js');
+const env = require('../libraries/env.js');
+
+// @omega.js/account is a private workspace package: in the monorepo the bare
+// specifier resolves via the workspace link (and the prepare-package vendor
+// hook rewrites it in dist/), but src/ ships in the tarball UNREWRITTEN — so
+// fall back to the copy vendored into dist/, which sits at the same depth from
+// both trees. The same two-step user.js makes.
+let features;
+try {
+  features = require('../../vendor/account/features.js');
+} catch (e) {
+  features = require('../../../dist/vendor/account/features.js');
+}
+
+// Where an anonymous key's counters live when the brand stores them in
+// Firestore (the default) — one document per key, wiped daily by the cron.
+const ANONYMOUS_COLLECTION = 'usage';
+
+function Usage(m) {
+  const self = this;
+
+  self.Manager = m;
+
+  self.ctx = null;
+  self.options = null;
+
+  // The anonymous key this counter counts against, or null for the signed-in
+  // user. Set ONLY by forKey() — never inferred from a request.
+  self.key = null;
+
+  // The account (or the keyed counter document) the counters live on, resolved
+  // on first use.
+  self.user = null;
+  self.resolved = false;
+
+  self.storage = null;
+}
+
+/**
+ * Attach a counter to a request. Synchronous and I/O-free: nothing is read
+ * until the first consume/read, so a route that never counts pays nothing.
+ *
+ * @param {object} ctx - The RouteContext
+ * @param {object} [options] - Counter options
+ * @param {string} [options.unauthenticatedMode] - 'firestore' (default) or 'local', for keyed counters
+ * @param {string[]} [options.whitelistKeys] - API keys that never get refused
+ * @param {Date} [options.today] - The day being counted (tests)
+ * @param {boolean} [options.log] - Log the counter lines (defaults to dev)
+ * @returns {Usage} this
+ */
+Usage.prototype.attach = function (ctx, options) {
+  const self = this;
+
+  if (!ctx) {
+    throw new Error('Usage.attach(): Missing required {ctx} parameter');
+  }
+
+  // Set options
+  options = options || {};
+  options.unauthenticatedMode = typeof options.unauthenticatedMode === 'undefined' ? 'firestore' : options.unauthenticatedMode;
+  options.whitelistKeys = options.whitelistKeys || [];
+  options.today = typeof options.today === 'undefined' ? undefined : options.today;
+  options.log = typeof options.log === 'undefined' ? ctx.isDevelopment() : options.log;
+
+  // The framework's own admin key always bypasses
+  options.whitelistKeys = options.whitelistKeys.concat([env.get('OMEGA_ADMIN_KEY')]);
+
+  self.ctx = ctx;
+  self.options = options;
+
+  return self;
+};
+
+/**
+ * A counter for an anonymous key (an IP, an installation id) — a SEPARATE
+ * counter, so a signed-in user's own counters are never moved into the
+ * anonymous store by a caller that only meant to rate-limit by address.
+ *
+ * Keyed counters are day-only in practice: the reset cron wipes the whole
+ * anonymous store every day (docs/usage-rate-limiting.md).
+ *
+ * @param {string} key - The key to count against
+ * @returns {Usage} A new counter bound to that key
+ */
+Usage.prototype.forKey = function (key) {
+  const self = this;
+
+  const keyed = new Usage(self.Manager);
+
+  keyed.attach(self.ctx, { ...self.options });
+  keyed.key = `${key || 'unknown'}`;
+
+  return keyed;
+};
+
+/**
+ * The brand's feature catalog.
+ * @returns {object} config.features, keyed by feature id
+ */
+Usage.prototype.catalog = function () {
+  const self = this;
+
+  return self.Manager.config.features || {};
+};
+
+/**
+ * The product whose numbers apply: the account's RESOLVED plan (a cancelled or
+ * suspended subscription resolves to the free tier), else `basic`.
+ * @param {string} [id] - Force a specific product id
+ * @returns {object} The catalog entry, or {}
+ */
+Usage.prototype.getProduct = function (id) {
+  const self = this;
+
+  const products = self.Manager.config.payment?.products || [];
+
+  id = id || User.resolveSubscription(self.user).plan;
+
+  return products.find((product) => product.id === id)
+    || products.find((product) => product.id === 'basic')
+    || {};
+};
+
+/**
+ * Resolve the account (or the keyed counter document) this counter counts on.
+ * Runs at most once — every consume/read awaits it first.
+ * @returns {Promise<Usage>} this
+ */
+Usage.prototype.resolve = async function () {
+  const self = this;
+
+  if (self.resolved) {
+    return self;
+  }
+
+  if (self.key) {
+    self.user = { usage: await self.loadKeyed() };
+  } else if (self.ctx.resolvedUser) {
+    // The middleware already authenticated this request — re-authenticating
+    // would verify the token and re-read the user doc a second time
+    self.user = self.ctx.request.user;
+  } else {
+    self.user = await self.ctx.authenticate();
+  }
+
+  // A signed-OUT caller has no document to count on. `authenticate()` resolves
+  // a full account SHAPE for one (uid null) and marks the request resolved all
+  // the same, so without this the write below would land on `users/null` — one
+  // document every anonymous caller on earth would share, and a limit none of
+  // them could ever exceed. Silently routing to the anonymous store instead
+  // would be the OTHER old bug: a key that switches storage behind the caller's
+  // back. Anonymous counting is explicit, so this says so.
+  if (!self.key && !self.user?.auth?.uid) {
+    throw new Error('usage: no signed-in account to count against; use usage.forKey(<key>) for anonymous callers');
+  }
+
+  self.resolved = true;
+
+  // Log — the counters this counter arrived with, never the document holding
+  // them: it carries api.privateKey, consent and attribution, and a backend
+  // line lands in Cloud Logging for the whole retention window
+  // ([#632](https://github.com/Omega-JS-Stack/omega/issues/632)).
+  self.log(`Usage.resolve(): Resolved ${self.key || self.user?.auth?.uid || 'unauthenticated'}`, self.user?.usage);
+
+  return self;
+};
+
+/**
+ * The stored counters for this counter's anonymous key.
+ * @returns {Promise<object>} feature id → counters
+ */
+Usage.prototype.loadKeyed = async function () {
+  const self = this;
+
+  if (self.options.unauthenticatedMode !== 'firestore') {
+    self.storage = self.storage || self.Manager.storage({ name: ANONYMOUS_COLLECTION, temporary: true, clear: false, log: false });
+
+    return self.storage.get(`users.${self.key}.usage`, {}).value() || {};
+  }
+
+  const found = await self.Manager.libraries.admin.firestore().doc(`${ANONYMOUS_COLLECTION}/${self.key}`)
+    .get()
+    .then((r) => r.data())
+    .catch((e) => {
+      self.ctx.report(`Usage.loadKeyed(): Error fetching usage data: ${e}`, { code: 500 });
+    });
+
+  return found || {};
+};
+
+/**
+ * What this account's state is for a feature, WITHOUT counting: the effective
+ * limit (overrides applied), both counters, and what is left of each.
+ * @param {string} feature - Feature id from the catalog
+ * @returns {Promise<object>} { id, name, limit, used, left, day: { limit, used, left }, ... }
+ */
+Usage.prototype.read = async function (feature) {
+  const self = this;
+
+  await self.resolve();
+
+  return self.state(feature);
+};
+
+/**
+ * The resolved feature state, from what is already loaded (no I/O).
+ * @param {string} feature - Feature id from the catalog
+ * @returns {object} @omega.js/account's resolveFeature shape
+ */
+Usage.prototype.state = function (feature) {
+  const self = this;
+
+  return features.resolveFeature(feature, {
+    catalog: self.catalog(),
+    product: self.getProduct(),
+    account: self.user,
+    now: self.options.today,
+  });
+};
+
+/**
+ * The state of a counter running against an EXPLICIT limit rather than the
+ * plan's — same shape as state(), with no day share (see consume's options).
+ * @param {string} feature - Counter id
+ * @param {number} limit - The limit that applies
+ * @returns {object} The resolveFeature shape
+ */
+Usage.prototype.explicitState = function (feature, limit) {
+  const self = this;
+
+  return features.resolveFeature(feature, {
+    catalog: { [feature]: { name: feature, usage: { pace: false } } },
+    product: { features: { [feature]: limit } },
+    account: self.user,
+    now: self.options.today,
+  });
+};
+
+/**
+ * Count one use of a feature — the ONE call a route makes.
+ *
+ * Refuses with a 429 naming which counter hit: the MONTH is checked first (a
+ * spent month is not "try again tomorrow"), then the day's share.
+ *
+ * `options.limit` is for the counters that are NOT plan features — a per-IP
+ * signup gate is a security control with its own declared config key
+ * (`targets.backend.auth.signup.maxPerIpPerDay`), not a tier anybody buys. An
+ * explicit limit supplies the definition the catalog would have, so the
+ * catalog lookup and the product read are skipped, and the counter is a plain
+ * period counter with no day share (an anonymous key's store is wiped daily,
+ * so its period IS the day).
+ *
+ * @param {string} feature - Feature id from the catalog
+ * @param {number} [amount] - How much to count (default 1)
+ * @param {object} [options] - Consume options
+ * @param {number} [options.limit] - An explicit limit for a non-plan counter
+ * @returns {Promise<object>} { used, left, day: { used, left } } after counting
+ */
+Usage.prototype.consume = async function (feature, amount, options) {
+  const self = this;
+  const ctx = self.ctx;
+
+  // Set amount
+  amount = typeof amount === 'undefined' ? 1 : amount;
+
+  // Set options
+  options = options || {};
+
+  const explicit = typeof options.limit === 'number';
+  const entry = self.catalog()[feature];
+
+  // A feature no catalog defines, or a perk, is a PROGRAMMER error: the route
+  // asked to meter something the config never made countable, and counting it
+  // anyway would build a limit nothing enforces.
+  if (!explicit && !entry) {
+    throw ctx.report(`Usage.consume(): "${feature}" is not defined in the features catalog (config.features)`, { code: 500 });
+  }
+
+  if (!explicit && !features.isCountedFeature(entry)) {
+    throw ctx.report(`Usage.consume(): "${feature}" is a perk, not a counted feature — give features.${feature} a \`usage\` block to meter it`, { code: 500 });
+  }
+
+  await self.resolve();
+
+  const state = explicit ? self.explicitState(feature, options.limit) : self.state(feature);
+  const name = (entry && entry.name) || feature;
+
+  // A whitelisted API key still COUNTS (the record stays honest) — it only
+  // never gets refused.
+  const whitelisted = self.options.whitelistKeys.some((key) => key && key === self.user?.api?.privateKey);
+
+  if (!whitelisted) {
+    if (state.limit >= 0 && state.used + amount > state.limit) {
+      throw ctx.report(
+        `You have used all ${state.limit} of your ${name} this month (${state.used}/${state.limit}). Upgrade your plan for more.`,
+        { code: 429 },
+      );
+    }
+
+    if (state.day.limit >= 0 && state.day.used + amount > state.day.limit) {
+      throw ctx.report(
+        `You have used today's ${name} (${state.day.used}/${state.day.limit} of the ${state.limit} on your plan this month). Try again tomorrow.`,
+        { code: 429 },
+      );
+    }
+  }
+
+  self.count(feature, amount);
+
+  await self.write(feature);
+
+  const counted = explicit ? self.explicitState(feature, options.limit) : self.state(feature);
+
+  return {
+    used: counted.used,
+    left: counted.left,
+    day: { used: counted.day.used, left: counted.day.left },
+  };
+};
+
+/**
+ * Move the counters in memory. `total` never resets; `last` records when the
+ * feature moved.
+ * @param {string} feature - Feature id
+ * @param {number} amount - How much to count
+ * @returns {Usage} this
+ */
+Usage.prototype.count = function (feature, amount) {
+  const self = this;
+
+  const now = self.options.today ? new Date(self.options.today) : new Date();
+
+  self.user.usage = self.user.usage || {};
+
+  const counters = self.user.usage[feature] || {};
+
+  self.user.usage[feature] = {
+    ...counters,
+    monthly: (counters.monthly || 0) + amount,
+    daily: (counters.daily || 0) + amount,
+    total: (counters.total || 0) + amount,
+    last: {
+      timestamp: now.toISOString(),
+      timestampUNIX: Math.floor(now.getTime() / 1000),
+    },
+  };
+
+  // Log the counter this moved — not the whole user document (#632)
+  self.log(`Usage.count(): Counted ${amount} ${feature} for ${self.key || self.user?.auth?.uid || 'unauthenticated'}`, self.user.usage[feature]);
+
+  return self;
+};
+
+/**
+ * The write payload for ONE feature: that feature's counters and nothing else,
+ * so two features counted in the same second cannot overwrite each other.
+ * @param {string} feature - Feature id
+ * @returns {object} { usage: { <feature>: counters } }
+ */
+Usage.prototype.countersPatch = function (feature) {
+  const self = this;
+
+  return { usage: { [feature]: (self.user.usage || {})[feature] } };
+};
+
+/**
+ * The mirror documents this feature's counters also land on: every doc the
+ * account owns of each kind the CATALOG names. Declared in config, never at
+ * the call site.
+ * @param {string} feature - Feature id
+ * @returns {string[]} Firestore document paths
+ */
+Usage.prototype.mirrorPaths = function (feature) {
+  const self = this;
+
+  // An anonymous key owns nothing
+  if (self.key) {
+    return [];
+  }
+
+  const owns = self.user?.owns || {};
+  const paths = [];
+
+  features.featureMirrors(self.catalog()[feature]).forEach((kind) => {
+    const owned = owns[kind];
+    const ids = Array.isArray(owned) ? owned : (owned ? [owned] : []);
+
+    ids.forEach((id) => paths.push(`${kind}/${id}`));
+  });
+
+  return paths;
+};
+
+/**
+ * Persist one feature's counters: the user document and every mirror, in ONE
+ * parallel write.
+ * @param {string} feature - Feature id
+ * @returns {Promise<void>}
+ */
+Usage.prototype.write = async function (feature) {
+  const self = this;
+
+  const { admin } = self.Manager.libraries;
+  const counters = (self.user.usage || {})[feature];
+
+  if (self.key) {
+    if (self.options.unauthenticatedMode !== 'firestore') {
+      self.storage = self.storage || self.Manager.storage({ name: ANONYMOUS_COLLECTION, temporary: true, clear: false, log: false });
+      self.storage.set(`users.${self.key}.usage.${feature}`, counters).write();
+
+      self.log(`Usage.write(): Wrote ${feature} to local storage`, counters);
+
+      return;
+    }
+
+    await admin.firestore().doc(`${ANONYMOUS_COLLECTION}/${self.key}`)
+      .set({ [feature]: counters }, { merge: true })
+      .catch((e) => {
+        throw self.ctx.report(e, { code: 500 });
+      });
+
+    return;
+  }
+
+  const patch = self.countersPatch(feature);
+  const paths = [`users/${self.user.auth.uid}`, ...self.mirrorPaths(feature)];
+
+  await Promise.all(paths.map((path) => admin.firestore().doc(path).set(patch, { merge: true })))
+    .then(() => {
+      self.log(`Usage.write(): Wrote ${feature} to ${paths.length} document(s)`, counters);
+    })
+    .catch((e) => {
+      throw self.ctx.report(e, { code: 500 });
+    });
+};
+
+/**
+ * The counters this account arrived with — the `omega-properties` header's
+ * `usage.current`. Empty until the counter has RESOLVED: a route that never
+ * counted read nothing, and the header must not force a read to report one.
+ * @returns {object} feature id → counters
+ */
+Usage.prototype.counters = function () {
+  const self = this;
+
+  return self.resolved ? (self.user?.usage || {}) : {};
+};
+
+/**
+ * Every counted feature's EFFECTIVE limit for this account (overrides applied)
+ * — the `omega-properties` header's `usage.limits`, which the client merges
+ * into its `usage` bindings. Empty until the counter has resolved.
+ * @returns {object} feature id → limit (-1 unlimited)
+ */
+Usage.prototype.limits = function () {
+  const self = this;
+
+  if (!self.resolved) {
+    return {};
+  }
+
+  const catalog = self.catalog();
+  const limits = {};
+
+  Object.keys(catalog).forEach((id) => {
+    if (features.isCountedFeature(catalog[id])) {
+      limits[id] = self.state(id).limit;
+    }
+  });
+
+  return limits;
+};
+
+/**
+ * Add API keys that never get refused (they still count).
+ * @param {string|string[]} keys - Key(s) to whitelist
+ * @returns {Usage} this
+ */
+Usage.prototype.addWhitelistKeys = function (keys) {
+  const self = this;
+
+  // Make keys an array if not already
+  keys = Array.isArray(keys) ? keys : [keys];
+
+  // Add keys to whitelist
+  self.options.whitelistKeys = self.options.whitelistKeys.concat(keys);
+
+  return self;
+};
+
+Usage.prototype.log = function () {
+  const self = this;
+
+  // Log
+  if (self.options.log) {
+    self.ctx.log(...arguments);
+  }
+};
+
+module.exports = Usage;

package/dist/manager/helpers/user.js

@@ -0,0 +1,57 @@
+/**
+ * User — thin wrapper over @omega.js/account, the single source of truth for
+ * the OMEGA user/account schema (shared with @omega.js/client, so a doc resolved
+ * here is byte-identical to one resolved on the frontend).
+ *
+ * @omega.js/backend's contribution is injecting the real value generators for the
+ * '$uuid'/'$randomId'/'$apiKey' schema tokens — the frontend injects none and
+ * those fields resolve to null (real values always come from the backend).
+ * API unchanged:
+ *   new User(Manager, settings).properties
+ *   User.resolveSubscription(accountOrUserInstance)
+ */
+const uuid4 = require('uuid').v4;
+const UIDGenerator = require('uid-generator');
+const uidgen = new UIDGenerator(256);
+
+// @omega.js/account is a private workspace package: in the monorepo the bare
+// specifier resolves via the workspace link (and the prepare-package vendor
+// hook rewrites it in dist/), but src/ ships in the tarball UNREWRITTEN and
+// the test corpus deep-requires it in consumers — so fall back to the copy
+// vendored into dist/, which sits at the same depth from both trees.
+let account;
+try {
+  account = require('../../vendor/account/index.js');
+} catch (e) {
+  account = require('../../../dist/vendor/account/index.js');
+}
+
+function User(Manager, settings) {
+  const self = this;
+
+  self.Manager = Manager;
+
+  settings = settings || {};
+
+  self.properties = account.resolveAccount(settings, {
+    generators: {
+      uuid: () => `${uuid4()}`,
+      randomId: () => Manager.Utilities().randomId({ size: 8 }),
+      apiKey: () => `${uidgen.generateSync()}`,
+    },
+  });
+
+  return self;
+}
+
+User.resolveSubscription = account.resolveSubscription;
+
+// The schema's own EMPTY discount node, which is what a CLEARED discount is
+// ([#333](https://github.com/Omega-JS-Stack/omega/issues/333)). The webhook
+// pipeline clears the node with a MERGE write, so every field has to be named or
+// half of the old claim survives it. Read off the resolver rather than spelled
+// out again: the node's shape keeps its one home in the schema, and a field
+// added there is cleared without anyone remembering a second list.
+User.EMPTY_DISCOUNT = account.resolveAccount({}).subscription.discount;
+
+module.exports = User;