@i4e/invest4edu-access-core 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.10.0",
+  "version": "0.11.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": {

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