@i4e/invest4edu-access-core 0.10.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.10.0",
+  "version": "0.12.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,8 @@
     "./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"
   },
   "scripts": {
     "test": "node --test test/"

package/src/route-features.js

@@ -93,8 +93,8 @@ export function rowsToTable(rows = []) {
  */
 export function createRouteFeatureMap(defaults = {}) {
   let dbOverrides = {};
-  // Recomputed only when the overrides change: this is consulted once per route at mount time,
-  // but merging on every lookup would still be needless work for a table that rarely changes.
+  // Recomputed only when the overrides change. Lookups happen per request, so merging on every
+  // one would be real waste for a table that changes about never.
   let merged = mergeRouteFeatures(defaults, dbOverrides);
 
   return {
@@ -130,10 +130,10 @@ export function createRouteFeatureMap(defaults = {}) {
     /**
      * Refresh the DB half. A failure keeps the last good map.
      *
-     * NOTE: gates attach at MOUNT time, so a change here affects routes mounted afterwards —
-     * in practice, after a restart. Resolving per request would mean a database read in the hot
-     * path of every write; the restart is the cheaper trade, and callers are told so rather than
-     * left to discover it.
+     * Consumers resolve gates PER REQUEST against this map, so a refresh takes effect without a
+     * restart. Resolving at mount time was the original design and was a bug: routes mount
+     * synchronously at boot, before the database is necessarily connected, so the map would only
+     * ever hold code defaults and every stored row was silently dead.
      *
      * @param {() => Promise<Array>} findRows returns the raw `routefeatures` documents
      */
@@ -150,4 +150,143 @@ export function createRouteFeatureMap(defaults = {}) {
   };
 }
 
-export default { createRouteFeatureMap, mergeRouteFeatures, rowsToTable };
+
+
+/**
+ * Keep a map refreshed in the background.
+ *
+ * Every consumer needs this and it is identical everywhere: load once now, then on a timer,
+ * `unref()` so it never holds the process open, and swallow failures so a config read cannot
+ * break boot. Written three times in two repos before it moved here.
+ *
+ * @param {ReturnType<createRouteFeatureMap>} map
+ * @param {() => Promise<Array>} findRows  may return null/throw before the DB is connected
+ * @param {number} [intervalMs=60000]
+ * @returns {() => void} stop
+ */
+export function startRouteFeatureRefresh(map, findRows, intervalMs = 60 * 1000) {
+  const tick = () => { map.load(findRows).catch(() => {}); };
+  const timer = setInterval(tick, intervalMs);
+  if (timer && typeof timer.unref === "function") timer.unref();
+  tick(); // harmless no-op until the database is up; the timer picks it up after
+  return () => clearInterval(timer);
+}
+
+/**
+ * Every route a controller registry mounts declaratively.
+ *
+ * Without this an UNGATED route is invisible to an admin screen — you would have to already know
+ * the controller name, method and exact path to gate one, which is barely better than editing the
+ * database by hand.
+ *
+ * Takes the registry's `name → class` mapping so the package stays framework-agnostic. Each class
+ * is instantiated to read `routes()`; safe because those are stateless declarations, and wrapped
+ * individually so one malformed controller cannot blank the whole list.
+ *
+ * @param {Record<string, any>} mappings
+ * @returns {Array<{controller: string, method: string, path: string}>}
+ */
+export function enumerateControllerRoutes(mappings = {}) {
+  const out = [];
+  for (const [name, Klass] of Object.entries(mappings)) {
+    try {
+      const inst = new Klass();
+      if (typeof inst.routes !== "function") continue;
+      for (const [method, paths] of Object.entries(inst.routes() || {})) {
+        for (const path of Object.keys(paths || {})) {
+          out.push({ controller: name, method: String(method).toLowerCase(), path });
+        }
+      }
+    } catch {
+      // one bad controller must not cost the whole list
+    }
+  }
+  return out;
+}
+
+/**
+ * The rows an admin screen renders: every mapped route, then every mounted route with NO gate.
+ *
+ * Ungated sort FIRST — finding something unguarded is why anyone opens that screen, and a list of
+ * ninety mostly-gated routes buries them.
+ *
+ * @param {Object} p
+ * @param {Object} p.merged        the in-force table (defaults + DB)
+ * @param {Set<string>} p.storedKeys  `controller|method|path` present in the database
+ * @param {Set<string>} p.knownCodes  defined action codes, to flag a gate that resolves to nothing
+ * @param {Array} p.discovered     from enumerateControllerRoutes
+ */
+export function buildRouteFeatureRows({ merged = {}, storedKeys = new Set(), knownCodes = new Set(), discovered = [] } = {}) {
+  const rows = [];
+  const seen = new Set();
+
+  for (const [controller, methods] of Object.entries(merged)) {
+    for (const [method, paths] of Object.entries(methods || {})) {
+      for (const [path, code] of Object.entries(paths || {})) {
+        const key = `${controller}|${method}|${path}`;
+        seen.add(key);
+        const isFn = typeof code !== "string";
+        rows.push({
+          controller,
+          method,
+          path,
+          // A resolver cannot be shown as a value — it picks its code from the request.
+          feature_code: isFn ? null : code,
+          is_resolver: isFn,
+          source: storedKeys.has(key) ? "database" : "default",
+          // The check that matters: an undefined code makes the gate a silent no-op.
+          code_exists: isFn ? true : knownCodes.has(code),
+        });
+      }
+    }
+  }
+
+  for (const d of discovered) {
+    const key = `${d.controller}|${d.method}|${d.path}`;
+    if (seen.has(key)) continue;
+    rows.push({ ...d, feature_code: null, is_resolver: false, source: "unmapped", code_exists: true });
+  }
+
+  rows.sort((a, b) => {
+    const rank = (r) => (r.source === "unmapped" ? 0 : 1);
+    if (rank(a) !== rank(b)) return rank(a) - rank(b);
+    return `${a.controller}${a.path}`.localeCompare(`${b.controller}${b.path}`);
+  });
+  return rows;
+}
+
+/**
+ * Is this upsert allowed? `{ ok }` or `{ ok: false, message }`.
+ *
+ * The rule worth centralising: a route pointed at a feature_code the registry does not define
+ * enforces NOTHING — an unknown code resolves to rollout "off" — while looking mounted. That is
+ * the single most misleading state the access system can be in, and it has already been created
+ * by hand once. Refuse it at the boundary, in both backends, from one place.
+ */
+export function validateRouteFeatureUpsert({ controller, method, path, feature_code, knownCodes = new Set() } = {}) {
+  if (!controller || !method || !path) {
+    return { ok: false, message: "controller, method and path are required" };
+  }
+  if (feature_code !== null && typeof feature_code !== "string") {
+    return { ok: false, message: "feature_code must be a string, or null to clear" };
+  }
+  if (typeof feature_code === "string" && !knownCodes.has(feature_code)) {
+    return {
+      ok: false,
+      message:
+        `${feature_code} is not a defined action. A route pointed at an unknown code enforces `
+        + `NOTHING — define the action first, then map it here.`,
+    };
+  }
+  return { ok: true };
+}
+
+export default {
+  createRouteFeatureMap,
+  mergeRouteFeatures,
+  rowsToTable,
+  startRouteFeatureRefresh,
+  enumerateControllerRoutes,
+  buildRouteFeatureRows,
+  validateRouteFeatureUpsert,
+};

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 };