@i4e/invest4edu-access-core 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.12.0",
+  "version": "0.13.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,217 @@
+/**
+ * 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" };
+    }
+  }
+
+  return { findSubscription, entitlementFor, consume };
+}
+
+export default { createEntitlementStore };