@i4e/invest4edu-access-core 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.11.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": {
@@ -16,7 +16,9 @@
     "./entitlement": "./src/entitlement.js",
     "./entitlement-schema": "./src/entitlement-schema.js",
     "./grid-schema": "./src/grid-schema.js",
-    "./route-features": "./src/route-features.js"
+    "./route-features": "./src/route-features.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 };

package/src/subscription-lifecycle.js

@@ -0,0 +1,69 @@
+/**
+ * Subscription lifecycle — statuses, transitions and event types. SHARED, because code branches
+ * on these in both backends and a status list that drifts between them means one side treats a
+ * subscription as live while the other has cut access (invariant #11).
+ *
+ * The machine:
+ *
+ *   trialing → active | cancelled | expired
+ *   active   → past_due | blocked | cancelled
+ *   past_due → active | blocked | cancelled          (payment recovered | gave up | user quit)
+ *   blocked  → active | cancelled                    (recovered | closed)
+ *   cancelled / expired → (terminal — a new purchase creates a NEW subscription)
+ *
+ * Terminal states stay terminal on purpose: "reactivating" a cancelled row would resurrect its
+ * history, overrides and period as if nothing happened. A fresh subscription is honest about the
+ * gap and keeps the audit trail of the old one intact.
+ *
+ * Upgrade/downgrade are TRANSITIONS OF PLAN, not of status — a plan change happens on a live
+ * subscription and does not appear here.
+ */
+
+export const SUBSCRIPTION_STATUSES = Object.freeze([
+  "trialing", "active", "past_due", "blocked", "cancelled", "expired",
+]);
+
+/** States in which entitlements resolve. past_due keeps working — cutting access the moment a
+ *  payment is late loses more than it protects; `blocked` is the deliberate cut-off. */
+export const LIVE_STATUSES = Object.freeze(["trialing", "active", "past_due"]);
+
+export const TRANSITIONS = Object.freeze({
+  trialing: ["active", "cancelled", "expired"],
+  active: ["past_due", "blocked", "cancelled"],
+  past_due: ["active", "blocked", "cancelled"],
+  blocked: ["active", "cancelled"],
+  cancelled: [],
+  expired: [],
+});
+
+/** `{ ok }` or `{ ok: false, message }` naming the legal moves — the caller shows it verbatim. */
+export function canTransition(from, to) {
+  const allowed = TRANSITIONS[from];
+  if (!allowed) return { ok: false, message: `${from} is not a subscription status` };
+  if (from === to) return { ok: false, message: `already ${from}` };
+  if (!allowed.includes(to)) {
+    return {
+      ok: false,
+      message: allowed.length
+        ? `${from} can only move to: ${allowed.join(", ")}`
+        : `${from} is terminal — a new purchase creates a new subscription`,
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Event types — the audit spine AND what the Events Engine receives (`subscription.<type>`).
+ * Engagement and monitoring both hang off this list, so an unlisted type is an event nobody can
+ * subscribe to: recording one is refused rather than silently accepted.
+ */
+export const SUBSCRIPTION_EVENT_TYPES = Object.freeze([
+  "created", "trial_started", "activated", "renewed",
+  "plan_changed", "cycle_changed", "period_extended",
+  "override_set", "override_removed",
+  "status_changed", "cancelled", "blocked", "expired",
+  "payment_captured", "payment_failed",
+  "quota_exceeded",
+]);
+
+export default { SUBSCRIPTION_STATUSES, LIVE_STATUSES, TRANSITIONS, canTransition, SUBSCRIPTION_EVENT_TYPES };