@i4e/invest4edu-access-core 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.9.0",
+  "version": "0.10.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": {
@@ -15,7 +15,8 @@
     "./visible-when": "./src/visible-when.js",
     "./entitlement": "./src/entitlement.js",
     "./entitlement-schema": "./src/entitlement-schema.js",
-    "./grid-schema": "./src/grid-schema.js"
+    "./grid-schema": "./src/grid-schema.js",
+    "./route-features": "./src/route-features.js"
   },
   "scripts": {
     "test": "node --test test/"

package/src/route-features.js

@@ -0,0 +1,153 @@
+/**
+ * Route → feature map: the mechanism, shared by both backends.
+ *
+ * Gates used to be written into each route. That works, and it has one fatal property: **a route
+ * with no gate looks exactly like a route that needs none.** Forgetting is invisible, and auditing
+ * means scraping source for string literals. With a map, the absence is a missing ROW.
+ *
+ * ── The rule this exists to protect ──────────────────────────────────────────────────────────
+ * **The thing being protected decides what protects it — never the caller.** A tempting shortcut
+ * is to have the client send an operation name and check that centrally. It cannot work: the
+ * client would then choose what gets checked, and omitting or renaming the operation would skip
+ * the gate. This map is server-side and keyed on the route.
+ *
+ * ── Mechanism here, DEFAULTS in each repo ────────────────────────────────────────────────────
+ * v1 and v2 mount different routes, so the tables are theirs. What is identical — merge order,
+ * the null-clears-a-default rule, the fail-open lookup, the DB loader — lives here, because two
+ * copies of merge logic is how the halves drift into disagreeing about who may do what.
+ *
+ * ── Precedence: DEFAULT < DB ─────────────────────────────────────────────────────────────────
+ * A `routefeatures` document may override or add an entry, so gating a new endpoint becomes a
+ * config edit rather than a deploy. `feature_code: null` DELETES a default — the escape hatch for
+ * "this should not be gated after all", and deliberately distinct from an absent row, which means
+ * "no opinion, use the default".
+ *
+ * DB rows carry a STRING only. Payload-aware routes — one endpoint serving several capabilities —
+ * need a function, which cannot be serialised, so those stay in each repo's defaults. That is a
+ * feature: the tricky ones stay in code, reviewed.
+ *
+ * ── Keying ───────────────────────────────────────────────────────────────────────────────────
+ * `ControllerName` + METHOD + the path exactly as written in that controller's `routes()` map —
+ * NOT the mounted URL, which is not known when routes are built and would silently stop matching
+ * if a prefix changed.
+ */
+
+/**
+ * @typedef {string | ((req: any) => string | null)} FeatureRef
+ *   A feature code, or a resolver returning one — `null` skips the gate for that request.
+ * @typedef {Record<string, Record<string, Record<string, FeatureRef>>>} RouteFeatureTable
+ *   controller → method → path → FeatureRef
+ */
+
+/**
+ * Merge DB rows over code defaults. Pure — exported so it can be tested without a database.
+ *
+ * @param {RouteFeatureTable} defaults
+ * @param {RouteFeatureTable} overrides
+ * @returns {RouteFeatureTable}
+ */
+export function mergeRouteFeatures(defaults = {}, overrides = {}) {
+  const out = {};
+  for (const [ctrl, methods] of Object.entries(defaults)) {
+    out[ctrl] = {};
+    for (const [method, paths] of Object.entries(methods || {})) {
+      out[ctrl][method] = { ...paths };
+    }
+  }
+  for (const [ctrl, methods] of Object.entries(overrides || {})) {
+    for (const [method, paths] of Object.entries(methods || {})) {
+      for (const [path, code] of Object.entries(paths || {})) {
+        if (code === null) {
+          if (out[ctrl] && out[ctrl][method]) delete out[ctrl][method][path];
+        } else {
+          out[ctrl] = out[ctrl] || {};
+          out[ctrl][method] = out[ctrl][method] || {};
+          out[ctrl][method][path] = code;
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/** Shape DB rows into the nested table. Tolerates malformed rows by skipping them. */
+export function rowsToTable(rows = []) {
+  const out = {};
+  for (const r of rows) {
+    if (!r || !r.controller || !r.method || !r.path) continue;
+    const m = String(r.method).toLowerCase();
+    out[r.controller] = out[r.controller] || {};
+    out[r.controller][m] = out[r.controller][m] || {};
+    out[r.controller][m][r.path] = r.feature_code === undefined ? null : r.feature_code;
+  }
+  return out;
+}
+
+/**
+ * A map instance bound to one repo's defaults.
+ *
+ * Model-agnostic by design: the loader takes a `findRows` function rather than a Mongoose model,
+ * so this package stays free of any database dependency — the same rule the rest of it follows.
+ *
+ * @param {RouteFeatureTable} defaults
+ */
+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.
+  let merged = mergeRouteFeatures(defaults, dbOverrides);
+
+  return {
+    /**
+     * The feature this route enforces, or null.
+     *
+     * Called while mounting routes, so it must NEVER throw: a lookup failure has to mean
+     * "ungated", exactly as before the map existed, rather than taking down boot.
+     */
+    featureForRoute(controllerName, method, path) {
+      try {
+        const byMethod = merged[controllerName];
+        if (!byMethod) return null;
+        const byPath = byMethod[String(method).toLowerCase()];
+        if (!byPath) return null;
+        const found = byPath[path];
+        return found === undefined ? null : found;
+      } catch {
+        return null;
+      }
+    },
+
+    /** Everything currently in force — for the drift check and the admin API. */
+    all() {
+      return merged;
+    },
+
+    /** The code half alone, so an admin API can show what is a default vs an override. */
+    defaults() {
+      return 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.
+     *
+     * @param {() => Promise<Array>} findRows returns the raw `routefeatures` documents
+     */
+    async load(findRows) {
+      try {
+        if (typeof findRows !== "function") return dbOverrides;
+        dbOverrides = rowsToTable(await findRows());
+        merged = mergeRouteFeatures(defaults, dbOverrides);
+      } catch {
+        // keep the last good map — a config read must never break boot or a request
+      }
+      return dbOverrides;
+    },
+  };
+}
+
+export default { createRouteFeatureMap, mergeRouteFeatures, rowsToTable };