@i4e/invest4edu-access-core 0.30.0 → 0.32.0

package/src/route-features.js

@@ -1,292 +1,292 @@
-/**
- * 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. 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 {
-    /**
-     * 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.
-     *
-     * 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
-     */
-    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;
-    },
-  };
-}
-
-
-
-/**
- * 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,
-};
+/**
+ * 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. 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 {
+    /**
+     * 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.
+     *
+     * 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
+     */
+    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;
+    },
+  };
+}
+
+
+
+/**
+ * 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,
+};