@i4e/invest4edu-access-core 0.12.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Shared access-control primitives for NeoFindesk: tenant keystone, role capabilities, reportee tree, feature flags, and the unified access engine (registry schema, snapshot resolver, visibleWhen).",
   "type": "module",
   "exports": {
@@ -17,7 +17,8 @@
     "./entitlement-schema": "./src/entitlement-schema.js",
     "./grid-schema": "./src/grid-schema.js",
     "./route-features": "./src/route-features.js",
-    "./subscription-lifecycle": "./src/subscription-lifecycle.js"
+    "./subscription-lifecycle": "./src/subscription-lifecycle.js",
+    "./entitlement-store": "./src/entitlement-store.js"
   },
   "scripts": {
     "test": "node --test test/"

package/src/entitlement-store.js

@@ -0,0 +1,303 @@
+/**
+ * The entitlement STORE — reading a subject's entitlement, and consuming a unit of it.
+ *
+ * `entitlement.js` next door holds the pure DECISION (given a subscription, rows and a usage
+ * count, what is allowed). This holds the part that talks to the database, because every backend
+ * that gates a metered feature needs exactly the same two operations and there is nothing
+ * app-specific about either.
+ *
+ * ── Why this exists ──────────────────────────────────────────────────────────────────────────
+ * v1 and v2 each grew their own copy of these two functions, and they had ALREADY diverged in
+ * shape before a third service needed them: v1's `entitlementFor` derives the subject from `req`
+ * and returns carried state for `consume` to reuse, while v2's takes explicit ids and splits
+ * `findSubscription` out. Two implementations of one contract is a bug waiting for the day they
+ * disagree about whether someone is over quota. A third would have made it certain.
+ *
+ * So the mechanism lives here and only the DATA differs — which database, which logger. Nothing
+ * Mongoose-shaped crosses this boundary: callers inject a `getDb()` returning a raw driver Db, so
+ * the package stays model-agnostic and services keep owning their own connections.
+ *
+ * ── Fail open, always ────────────────────────────────────────────────────────────────────────
+ * Entitlement never blocks on infrastructure error. RBAC is the layer that fails closed; this one
+ * is commercial, and refusing paid work because our own counter was unreachable turns a small
+ * outage into a customer-visible one. Absence is far more likely to be our gap than a customer
+ * genuinely owning nothing.
+ */
+import { resolveEntitlement, periodKey, subjectKeyFor } from "./entitlement.js";
+import { LIVE_STATUSES } from "./subscription-lifecycle.js";
+
+/** Every failure path returns this, so callers never have to branch on "did the lookup work". */
+const OPEN = (reason) => ({
+  allowed: true,
+  unlocked: true,
+  metered: false,
+  quota: null,
+  used: 0,
+  remaining: null,
+  overage_policy: "unlimited",
+  reason,
+});
+
+const noopLogger = { warn() {}, info() {} };
+
+/**
+ * Build a store bound to one service's database.
+ *
+ * @param {Object}   opts
+ * @param {Function} opts.getDb      returns a raw MongoDB `Db`, or null/undefined when unavailable
+ * @param {Function} [opts.toObjectId] cast a string id the way this service's driver expects.
+ *                                    Defaults to passing the value through — services using
+ *                                    Mongoose should pass `mongoose.Types.ObjectId`, because a
+ *                                    string will not match an ObjectId field and the customer
+ *                                    would silently look unsubscribed.
+ * @param {Object}   [opts.logger]   anything with `warn`
+ */
+export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger = noopLogger } = {}) {
+  if (typeof getDb !== "function") throw new Error("createEntitlementStore requires getDb()");
+
+  const oid = (v) => {
+    try { return toObjectId(String(v)); } catch { return v; }
+  };
+
+  /** The live subscription governing this subject, or null. */
+  async function findSubscription({ subjectType, subjectId } = {}) {
+    const db = getDb();
+    if (!db || !subjectType || !subjectId) return null;
+    return db.collection("account_subscriptions").findOne({
+      subject_type: subjectType,
+      subject_id: oid(subjectId),
+      status: { $in: LIVE_STATUSES },
+    });
+  }
+
+  /**
+   * Resolve entitlement for one feature.
+   *
+   * Returns an OPEN result whenever anything is missing — no subscription, no plan row, no
+   * database — for the reason in the header.
+   */
+  async function entitlementFor({
+    subjectType, subjectId, featureCode, feature = {}, identity = {},
+    bypass = false, now = new Date(),
+  } = {}) {
+    try {
+      const db = getDb();
+      if (!db || !subjectType || !subjectId) return OPEN("no_subject");
+
+      const subscription = await findSubscription({ subjectType, subjectId });
+      if (!subscription) return resolveEntitlement({ subscription: null, featureCode, feature, bypass, now });
+
+      /**
+       * Trial terms: while `trialing`, rows with cycle "trial" take precedence over the purchased
+       * cycle's — that is how a trial offers LESS than the paid plan without being a separate
+       * plan. No trial rows ⇒ the paid terms apply during trial, which is the
+       * time-limited-full-plan case.
+       */
+      const cycles = subscription.status === "trialing"
+        ? ["trial", subscription.cycle]
+        : [subscription.cycle];
+      const fetched = await db.collection("plan_entitlements").find({
+        plan_code: subscription.plan_code,
+        cycle: { $in: cycles },
+        feature_code: featureCode,
+      }).toArray();
+      const trialRows = fetched.filter((r) => r.cycle === "trial");
+      const rows = subscription.status === "trialing" && trialRows.length
+        ? trialRows
+        : fetched.filter((r) => r.cycle === subscription.cycle);
+
+      // Only read the counter when something could actually be metered — an unmetered feature
+      // should not cost a query on every request.
+      let used = 0;
+      const row = rows[0] || null;
+      if (feature.is_meterable && row) {
+        const period = periodKey(row.period_granularity || "month", { now, subscriptionId: subscription._id });
+        const subjectKey = subjectKeyFor(row.quota_scope, identity) || "";
+        const usage = await db.collection("subscription_usage").findOne({
+          subscription_id: subscription._id,
+          feature_code: featureCode,
+          period,
+          subject_key: subjectKey,
+        });
+        used = usage?.used || 0;
+      }
+
+      const result = await resolveEntitlement({
+        subscription, entitlementRows: rows, featureCode, feature, used, identity, bypass, now,
+      });
+
+      // Carry what consume() needs, so it cannot recompute the period key and count against a
+      // different bucket than the one that was just checked.
+      return {
+        ...result,
+        carriedSubscriptionId: subscription._id,
+        carriedIdentity: identity,
+        carriedRow: row,
+      };
+    } catch (e) {
+      logger.warn(`[entitlement] resolve failed for ${featureCode}, allowing through: ${e.message}`);
+      return OPEN("resolve_error");
+    }
+  }
+
+  /**
+   * Consume one unit — race-free by construction.
+   *
+   * The `used < quota` test lives inside the FILTER, so Mongo decides atomically whether the
+   * increment may happen; matchedCount 0 means the ceiling was already reached. A read-then-write
+   * would let two concurrent requests both pass a 5-of-5 check and land a 6th.
+   *
+   * Only `block` enforces the ceiling — under `warn` the count still rises, and that record is the
+   * evidence for whether a quota is right before anyone is ever refused.
+   *
+   * Accepts either the result of `entitlementFor` (preferred — it carries the exact bucket that
+   * was checked) or the explicit pieces, so both existing call shapes keep working.
+   */
+  async function consume({
+    entitlement, featureCode, n = 1, now = new Date(),
+    subscriptionId, row, identity,
+  } = {}) {
+    try {
+      const db = getDb();
+      const subId = subscriptionId || entitlement?.carriedSubscriptionId;
+      const useRow = row || entitlement?.carriedRow;
+      const ident = identity || entitlement?.carriedIdentity || {};
+      // An unmetered feature has nothing to count; saying so is not a failure.
+      if (entitlement && !entitlement.metered) return { consumed: false, reason: "not_metered" };
+      if (!db || !subId || !useRow) return { consumed: false, reason: "not_metered" };
+
+      const period = periodKey(useRow.period_granularity || "month", { now, subscriptionId: subId });
+      const subjectKey = subjectKeyFor(useRow.quota_scope, ident) || "";
+      const filter = {
+        subscription_id: subId,
+        feature_code: featureCode,
+        period,
+        subject_key: subjectKey,
+      };
+      const policy = useRow.overage_policy || "block";
+      const capped = policy === "block" && useRow.quota != null;
+
+      // Unguarded (warn / unlimited): a plain upsert is right — the count rises either way, and
+      // that record is the evidence for whether a quota is set correctly before anyone is refused.
+      if (!capped) {
+        await db.collection("subscription_usage").updateOne(
+          filter, { $inc: { used: n }, $setOnInsert: { ...filter } }, { upsert: true },
+        );
+        return { consumed: true };
+      }
+
+      // Capped: try the GUARDED update first, without upsert.
+      const guarded = { ...filter, used: { $lt: Number(useRow.quota) } };
+      const hit = await db.collection("subscription_usage").updateOne(guarded, { $inc: { used: n } });
+      if (hit.matchedCount > 0) return { consumed: true };
+
+      // No match means either "no row yet" (first use this period) or "quota reached". Distinguish
+      // by INSERTING — the unique index makes that safe under concurrency: exactly one racer wins
+      // and the loser's duplicate-key means the row now exists, i.e. the quota case.
+      //
+      // Doing this as an upsert on the guarded filter instead would rely on a duplicate-key
+      // EXCEPTION to mean "quota exceeded" — correct by accident, and unreadable.
+      try {
+        await db.collection("subscription_usage").insertOne({ ...filter, used: n, createdAt: new Date() });
+        return { consumed: true };
+      } catch (e) {
+        if (e?.code === 11000) return { consumed: false, reason: "quota_exceeded" };
+        throw e;
+      }
+    } catch (e) {
+      logger.warn(`[entitlement] consume failed for ${featureCode}: ${e.message}`);
+      // Fail open on infrastructure error: never refuse a request because our counter misbehaved.
+      return { consumed: false, reason: "error" };
+    }
+  }
+
+  /**
+   * Give a subject the default plan, if there is one and they have none.
+   *
+   * A distributor who has never bought anything currently resolves to "no subscription", which
+   * fails OPEN — so today every distributor silently has unlimited everything. A default plan is
+   * how that becomes deliberate: a real package with real limits, assigned automatically, so the
+   * system's answer to "what may this person do" stops being "we never decided".
+   *
+   * ── Idempotent, and safe to call from anywhere ───────────────────────────────────────────────
+   * Returns the existing subscription untouched if one is live. That matters because the natural
+   * call site is distributor creation, and distributors get created down several paths (self
+   * onboarding, admin, draft approval, bulk import) — a provisioner that could double-assign would
+   * have to be wired carefully into exactly one of them, which is how coverage gaps happen. This
+   * one can be called from all of them, or twice, or after the fact.
+   *
+   * ── Never fatal ──────────────────────────────────────────────────────────────────────────────
+   * Returns null on any failure rather than throwing. Callers create distributors; a subscription
+   * that could not be provisioned must never be the reason a distributor does not exist. The gap
+   * is recoverable by calling this again — a failed creation is not.
+   *
+   * @param {Object} p
+   * @param {string} p.subjectType   "distributor" | "client"
+   * @param {string} p.subjectId
+   * @param {string} [p.accountId]
+   * @param {Date}   [p.now]
+   * @returns {Promise<Object|null>} the subscription (existing or new), or null
+   */
+  async function provisionDefault({ subjectType, subjectId, accountId = null, now = new Date() } = {}) {
+    try {
+      const db = getDb();
+      if (!db || !subjectType || !subjectId) return null;
+
+      const existing = await findSubscription({ subjectType, subjectId });
+      if (existing) return existing;
+
+      // The default plan is a property of the CATALOGUE, not of this code — so which package new
+      // distributors get, and for how long, is changed by editing a plan rather than deploying.
+      const plan = await db.collection("plan_catalog").findOne({
+        default_for: subjectType,
+        status: "active",
+      });
+      if (!plan) return null;
+
+      const days = Number(plan.default_duration_days) || 0;
+      const start = new Date(now);
+      const end = new Date(now);
+      if (days > 0) end.setDate(end.getDate() + days);
+      // No duration means an open-ended default tier; period_end null reads as "does not lapse".
+      const periodEnd = days > 0 ? end : null;
+
+      /**
+       * Status is `active`, not `trialing`.
+       *
+       * This is a real package on real terms, not a taste of a bigger one — and `trialing` would
+       * make trial-cycle entitlement rows take precedence, quietly applying terms nobody wrote for
+       * this plan. The trial mechanism stays available for plans that actually want it.
+       */
+      const doc = {
+        account_id: accountId ? oid(accountId) : null,
+        subject_type: subjectType,
+        subject_id: oid(subjectId),
+        plan_code: plan.plan_code,
+        cycle: plan.default_cycle || "monthly",
+        status: "active",
+        period_start: start,
+        period_end: periodEnd,
+        provisioned_default: true,   // so a report can tell "given" from "bought"
+        createdAt: new Date(),
+      };
+
+      try {
+        await db.collection("account_subscriptions").insertOne(doc);
+      } catch (e) {
+        // Two creation paths racing on the same subject. The partial unique index on a live
+        // subscription is what makes this safe: one wins, and the loser reads the winner's row
+        // rather than creating a duplicate.
+        if (e?.code === 11000) return findSubscription({ subjectType, subjectId });
+        throw e;
+      }
+      return doc;
+    } catch (e) {
+      logger.warn(`[entitlement] default provisioning failed for ${subjectType} ${subjectId}: ${e.message}`);
+      return null;
+    }
+  }
+
+  return { findSubscription, entitlementFor, consume, provisionDefault };
+}
+
+export default { createEntitlementStore };