@i4e/invest4edu-access-core 0.8.0 → 0.10.0

package/package.json

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

@@ -12,7 +12,7 @@
  * Design: TDD-unified-access-and-subscription.md §4
  */
 
-import { parentCodeOf } from "./access-schema.js";
+import { parentCodeOf, PRODUCT_UI_MODES } from "./access-schema.js";
 
 /** Reasons a feature can be locked, surfaced so the UI can distinguish upsell from hard-deny. */
 export const ENTITLEMENT_REASONS = Object.freeze({
@@ -219,6 +219,12 @@ export function resolveAccessSnapshot({
       actions: [],
       entitlement,
       tracking: !!f.tracking_enabled,
+      // How this SCREEN should present product-keyed things it renders — distinct from
+      // `products` above, which is *reachability* ("this screen exists only for these
+      // products"). The two are independent: Open Orders is product-agnostic yet renders
+      // product tabs that must be filtered, so the behaviour cannot be derived from the
+      // constraint. Default 'none' keeps every existing screen rendering exactly as today.
+      product_ui: PRODUCT_UI_MODES.includes(f.product_ui) ? f.product_ui : "none",
     };
 
     if (f.feature_type === "screen") allowedScreens.push(f);

package/src/access-schema.js

@@ -23,6 +23,27 @@ export const REGISTRY_STATUSES = Object.freeze(["active", "dormant", "retired"])
 /** Per-feature enforcement ladder (mirrors the platform's off→warn→enforce doctrine). */
 export const ROLLOUT_MODES = Object.freeze(["off", "warn", "enforce"]);
 
+/**
+ * How a SCREEN presents the product-keyed things it renders — product tiles, product tabs, the
+ * product column on Add Order, scheme lists.
+ *
+ * Deliberately separate from `products[]` on the same feature, which is *reachability* ("this
+ * screen exists only for these products"). The two are independent and neither implies the other:
+ * Open Orders is product-agnostic (`products: []`, it serves every product) yet renders product
+ * tabs that must be filtered; Product Setup is equally agnostic and should hide nothing. Same
+ * reachability, opposite presentation — so this cannot be derived, it has to be declared.
+ *
+ *   none      render everything. The default, so every existing screen is unchanged.
+ *   filter    hide product-keyed items outside the caller's scope. For transactional screens.
+ *   readonly  show everything, but out-of-scope items are not interactive. For configuration
+ *             screens, where hiding a product reads as "the catalogue is broken" rather than as
+ *             "you may not touch this".
+ *
+ * This is presentation only. The server-side gate is what actually refuses a write — hiding a
+ * tile has never stopped a POST.
+ */
+export const PRODUCT_UI_MODES = Object.freeze(["none", "filter", "readonly"]);
+
 /** Grant effect. `deny` at the user level replaces the old `revoked_pages`. */
 export const GRANT_EFFECTS = Object.freeze(["allow", "deny"]);
 
@@ -96,6 +117,7 @@ export const ACCESS_FEATURE_DEF = Object.freeze({
     status: { type: "String", enum: REGISTRY_STATUSES, default: "active", index: true },
     kill_switch: { type: "String", enum: ["on", "off"], default: "off" },
     rollout_mode: { type: "String", enum: ROLLOUT_MODES, default: "off" },
+    product_ui: { type: "String", enum: PRODUCT_UI_MODES, default: "none" },
 
     // Survives an entitlement block (login, billing/checkout, profile) — see design §7.4.
     always_available: { type: "Boolean", default: false },
@@ -139,6 +161,7 @@ export default {
   FEATURE_TYPES,
   REGISTRY_STATUSES,
   ROLLOUT_MODES,
+  PRODUCT_UI_MODES,
   GRANT_EFFECTS,
   GRANT_SUBJECTS,
   FEATURE_CODE_PATTERN,

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