@i4e/invest4edu-access-core 0.32.0 → 0.34.0

package/src/access-resolver.js

@@ -1,269 +1,269 @@
-/**
- * Access snapshot resolver — @i4e/invest4edu-access-core (unified access framework, P1).
- *
- * ONE resolver produces the "access snapshot" for a request: the nav tree, the per-feature
- * allow/actions/entitlement/tracking map, and the product scope. Everything downstream — nav,
- * `hasFeature`, `requireFeature`, grid `visibleWhen`, entitlement, metering — reads this one
- * object, so there is a single place where access is decided.
- *
- * PURE by design: callers inject already-loaded data (`registry`, `grants`, `mappedProducts`, …).
- * No Mongoose, no I/O, no ALS — which is what makes allow/deny matrices testable without a DB.
- *
- * Design: TDD-unified-access-and-subscription.md §4
- */
-
-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({
-  OK: "ok",
-  ADMIN_BYPASS: "admin_bypass",
-  NO_SUBSCRIPTION: "no_subscription",
-  TRIAL_ACTIVE: "trial_active",
-  TRIAL_EXPIRED: "trial_expired",
-  LOCKED: "locked",
-  QUOTA_EXCEEDED: "quota_exceeded",
-  PAYMENT_OVERDUE: "payment_overdue",
-  SUBSCRIPTION_EXPIRED: "subscription_expired",
-});
-
-const isLive = (f) =>
-  !!f && f.status === "active" && f.kill_switch !== "on";
-
-/**
- * Merge grants into an effective allow-set per feature.
- *
- * Rules (design §3.3): union(role allows) − union(user denies) + union(user allows).
- * Deny beats allow at the same subject level; the user level beats the role level.
- *
- * Product dimension: a grant with `product_code: null` is UNSCOPED and contributes the caller's
- * whole product set (legacy-equivalent). A scoped grant contributes only that product, and only
- * when the caller actually has it mapped (default-deny).
- *
- * @returns {Map<string, {products: Set<string>|null}>} null products = unscoped/all
- */
-export function mergeGrants(grants = [], { mappedProducts = [], now = new Date() } = {}) {
-  const mapped = new Set(mappedProducts.map(String));
-
-  const roleAllow = new Map(); // code → Set|null
-  const userAllow = new Map();
-  const userDeny = new Set();
-  const roleDeny = new Set();
-
-  const addTo = (map, code, product) => {
-    if (!map.has(code)) map.set(code, { products: null, anyUnscoped: false });
-    const e = map.get(code);
-    if (product == null) {
-      e.anyUnscoped = true; // unscoped grant wins — covers everything the user has
-      e.products = null;
-    } else if (!e.anyUnscoped) {
-      if (!e.products) e.products = new Set();
-      e.products.add(String(product));
-    }
-  };
-
-  for (const g of grants) {
-    if (!g || !g.feature_code) continue;
-    if (g.expires_at && new Date(g.expires_at) <= now) continue; // expired grants are inert
-
-    // A product-scoped grant only counts when the caller actually has that product mapped.
-    if (g.product_code != null && !mapped.has(String(g.product_code))) continue;
-
-    const isUser = g.subject_type === "user";
-    if (g.effect === "deny") {
-      (isUser ? userDeny : roleDeny).add(g.feature_code);
-    } else {
-      addTo(isUser ? userAllow : roleAllow, g.feature_code, g.product_code ?? null);
-    }
-  }
-
-  const out = new Map();
-  const put = (code, entry) => {
-    const prev = out.get(code);
-    if (!prev) {
-      out.set(code, { products: entry.anyUnscoped ? null : new Set(entry.products || []) });
-      return;
-    }
-    if (prev.products === null || entry.anyUnscoped) prev.products = null;
-    else for (const p of entry.products || []) prev.products.add(p);
-  };
-
-  for (const [code, entry] of roleAllow) {
-    if (roleDeny.has(code)) continue; // deny beats allow at the same level
-    put(code, entry);
-  }
-  for (const code of userDeny) out.delete(code); // user deny beats role allow
-  for (const [code, entry] of userAllow) put(code, entry); // user allow beats role deny
-
-  return out;
-}
-
-/**
- * Build the nav tree from the features the caller holds.
- * Screens only, `nav.show_in_nav`, grouped by module and ordered by position.
- *
- * The nav IS the access model projected — not a parallel copy (requirement 2).
- */
-export function buildNav(allowedScreenFeatures = [], modules = []) {
-  const modByCode = new Map(
-    modules.filter((m) => m && m.status !== "retired").map((m) => [m.module_code, m]),
-  );
-
-  const groups = new Map();
-  for (const f of allowedScreenFeatures) {
-    if (!f?.nav?.show_in_nav) continue;
-    const code = f.module_code;
-    const mod = modByCode.get(code);
-    if (!mod) continue; // a feature whose module is missing/retired is simply not navigable
-    if (!groups.has(code)) {
-      groups.set(code, {
-        module_code: code,
-        name: mod.name,
-        icon: mod.icon || null,
-        position: mod.position ?? 0,
-        items: [],
-      });
-    }
-    groups.get(code).items.push({
-      feature_code: f.feature_code,
-      name: f.name,
-      route: f.route || null,
-      position: f.nav.position ?? 0,
-      is_external_url: !!f.nav.is_external_url,
-      external_url: f.nav.external_url || null,
-    });
-  }
-
-  const nav = [...groups.values()].sort((a, b) => a.position - b.position);
-  for (const g of nav) g.items.sort((a, b) => a.position - b.position);
-  return nav;
-}
-
-/**
- * Resolve the access snapshot.
- *
- * @param {Object} p
- * @param {Object} p.identity         { account_id, userId, roles[], actingAs? }
- * @param {Object} p.registry         { features: [], modules: [] }  (already filtered to live rows)
- * @param {Array}  p.grants           access_grants rows for {account, roles ∪ userId}
- * @param {Array}  p.mappedProducts   the caller's product codes
- * @param {Object} p.capabilities     capsFor(roles) — reads `bypassAllGates` (D27)
- * @param {Function} [p.entitlementFor] (feature) → entitlement block | null
- */
-export function resolveAccessSnapshot({
-  identity = {},
-  registry = {},
-  grants = [],
-  mappedProducts = [],
-  capabilities = {},
-  entitlementFor = null,
-  now = new Date(),
-} = {}) {
-  const features = (registry.features || []).filter(isLive);
-  const modules = registry.modules || [];
-
-  // ── D27: system-admin break-glass ───────────────────────────────────────────────────────────
-  // Resolved ONCE, here — never re-checked per gate, so no gate can forget to honour it. Opens
-  // every gate WITHIN the caller's own account. Deliberately NOT cross-tenant: crossing accounts
-  // is the separate, stricter canCrossAccount path (D3/BRI-582). bypassAllGates ≠ canCrossAccount.
-  const bypass = !!capabilities.bypassAllGates;
-
-  const allowedByCode = bypass
-    ? new Map(features.map((f) => [f.feature_code, { products: null }]))
-    : mergeGrants(grants, { mappedProducts, now });
-
-  const byCode = new Map(features.map((f) => [f.feature_code, f]));
-  // Product scope comes from the IDENTITY, for admins too. The loader already resolves an
-  // unmapped identity (internal staff, platform admins) to every product code, so this is "all"
-  // for them without any special case. Deriving a bypass admin's scope from the products declared
-  // ON FEATURES — as this used to — yields [] whenever no feature declares one, which is the state
-  // of the registry today: a system admin resolved to NO products, and every feature then inherited
-  // `products: []`. Kept only as a fallback for the case where identity scope is genuinely empty.
-  const identityScope = [...new Set(mappedProducts.map(String))];
-  const productScope = bypass && !identityScope.length
-    ? [...new Set(features.flatMap((f) => f.products || []))]
-    : identityScope;
-
-  const featureMap = {};
-  const allowedScreens = [];
-
-  for (const f of features) {
-    const grant = allowedByCode.get(f.feature_code);
-    if (!grant) continue;
-
-    // Platform-level product constraint on the feature itself, intersected with the grant's.
-    let products = grant.products ? [...grant.products] : [...productScope];
-    if (Array.isArray(f.products) && f.products.length) {
-      const allowedForFeature = new Set(f.products.map(String));
-      products = products.filter((p) => allowedForFeature.has(p));
-      // A product-constrained feature with no overlap is not reachable at all.
-      if (products.length === 0 && !bypass) continue;
-    }
-
-    const entitlement = bypass
-      ? {
-          unlocked: true,
-          quota: null,
-          used: 0,
-          remaining: null,
-          overage_policy: "unlimited",
-          reason: ENTITLEMENT_REASONS.ADMIN_BYPASS,
-        }
-      : entitlementFor
-        ? entitlementFor(f)
-        : null;
-
-    featureMap[f.feature_code] = {
-      allowed: true,
-      products: grant.products === null && !Array.isArray(f.products) ? "*" : products,
-      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);
-  }
-
-  // Attach each allowed action to its parent screen (actions are features, design §2).
-  for (const code of Object.keys(featureMap)) {
-    const f = byCode.get(code);
-    if (f?.feature_type !== "action") continue;
-    const parent = f.parent_feature_code || parentCodeOf(code);
-    if (parent && featureMap[parent]) featureMap[parent].actions.push(code);
-  }
-
-  return {
-    version: 1,
-    resolved_at: now.toISOString(),
-    resolved_for: {
-      userId: identity.userId ? String(identity.userId) : null,
-      account_id: identity.account_id ? String(identity.account_id) : null,
-      actingAs: identity.actingAs?.giver_id || null,
-      real_userId: identity.actingAs?.delegate_id || (identity.userId ? String(identity.userId) : null),
-      admin_bypass: bypass,
-    },
-    nav: buildNav(allowedScreens, modules),
-    features: featureMap,
-    productScope,
-  };
-}
-
-/** Snapshot-based `hasFeature` (the server-side twin of the client helper). */
-export function hasFeature(snapshot, featureCode) {
-  return !!snapshot?.features?.[featureCode]?.allowed;
-}
-
-/** True when the feature is allowed AND (no entitlement gate OR it is unlocked). */
-export function isUsable(snapshot, featureCode) {
-  const f = snapshot?.features?.[featureCode];
-  if (!f?.allowed) return false;
-  return !f.entitlement || f.entitlement.unlocked !== false;
-}
-
-export default { resolveAccessSnapshot, mergeGrants, buildNav, hasFeature, isUsable, ENTITLEMENT_REASONS };
+/**
+ * Access snapshot resolver — @i4e/invest4edu-access-core (unified access framework, P1).
+ *
+ * ONE resolver produces the "access snapshot" for a request: the nav tree, the per-feature
+ * allow/actions/entitlement/tracking map, and the product scope. Everything downstream — nav,
+ * `hasFeature`, `requireFeature`, grid `visibleWhen`, entitlement, metering — reads this one
+ * object, so there is a single place where access is decided.
+ *
+ * PURE by design: callers inject already-loaded data (`registry`, `grants`, `mappedProducts`, …).
+ * No Mongoose, no I/O, no ALS — which is what makes allow/deny matrices testable without a DB.
+ *
+ * Design: TDD-unified-access-and-subscription.md §4
+ */
+
+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({
+  OK: "ok",
+  ADMIN_BYPASS: "admin_bypass",
+  NO_SUBSCRIPTION: "no_subscription",
+  TRIAL_ACTIVE: "trial_active",
+  TRIAL_EXPIRED: "trial_expired",
+  LOCKED: "locked",
+  QUOTA_EXCEEDED: "quota_exceeded",
+  PAYMENT_OVERDUE: "payment_overdue",
+  SUBSCRIPTION_EXPIRED: "subscription_expired",
+});
+
+const isLive = (f) =>
+  !!f && f.status === "active" && f.kill_switch !== "on";
+
+/**
+ * Merge grants into an effective allow-set per feature.
+ *
+ * Rules (design §3.3): union(role allows) − union(user denies) + union(user allows).
+ * Deny beats allow at the same subject level; the user level beats the role level.
+ *
+ * Product dimension: a grant with `product_code: null` is UNSCOPED and contributes the caller's
+ * whole product set (legacy-equivalent). A scoped grant contributes only that product, and only
+ * when the caller actually has it mapped (default-deny).
+ *
+ * @returns {Map<string, {products: Set<string>|null}>} null products = unscoped/all
+ */
+export function mergeGrants(grants = [], { mappedProducts = [], now = new Date() } = {}) {
+  const mapped = new Set(mappedProducts.map(String));
+
+  const roleAllow = new Map(); // code → Set|null
+  const userAllow = new Map();
+  const userDeny = new Set();
+  const roleDeny = new Set();
+
+  const addTo = (map, code, product) => {
+    if (!map.has(code)) map.set(code, { products: null, anyUnscoped: false });
+    const e = map.get(code);
+    if (product == null) {
+      e.anyUnscoped = true; // unscoped grant wins — covers everything the user has
+      e.products = null;
+    } else if (!e.anyUnscoped) {
+      if (!e.products) e.products = new Set();
+      e.products.add(String(product));
+    }
+  };
+
+  for (const g of grants) {
+    if (!g || !g.feature_code) continue;
+    if (g.expires_at && new Date(g.expires_at) <= now) continue; // expired grants are inert
+
+    // A product-scoped grant only counts when the caller actually has that product mapped.
+    if (g.product_code != null && !mapped.has(String(g.product_code))) continue;
+
+    const isUser = g.subject_type === "user";
+    if (g.effect === "deny") {
+      (isUser ? userDeny : roleDeny).add(g.feature_code);
+    } else {
+      addTo(isUser ? userAllow : roleAllow, g.feature_code, g.product_code ?? null);
+    }
+  }
+
+  const out = new Map();
+  const put = (code, entry) => {
+    const prev = out.get(code);
+    if (!prev) {
+      out.set(code, { products: entry.anyUnscoped ? null : new Set(entry.products || []) });
+      return;
+    }
+    if (prev.products === null || entry.anyUnscoped) prev.products = null;
+    else for (const p of entry.products || []) prev.products.add(p);
+  };
+
+  for (const [code, entry] of roleAllow) {
+    if (roleDeny.has(code)) continue; // deny beats allow at the same level
+    put(code, entry);
+  }
+  for (const code of userDeny) out.delete(code); // user deny beats role allow
+  for (const [code, entry] of userAllow) put(code, entry); // user allow beats role deny
+
+  return out;
+}
+
+/**
+ * Build the nav tree from the features the caller holds.
+ * Screens only, `nav.show_in_nav`, grouped by module and ordered by position.
+ *
+ * The nav IS the access model projected — not a parallel copy (requirement 2).
+ */
+export function buildNav(allowedScreenFeatures = [], modules = []) {
+  const modByCode = new Map(
+    modules.filter((m) => m && m.status !== "retired").map((m) => [m.module_code, m]),
+  );
+
+  const groups = new Map();
+  for (const f of allowedScreenFeatures) {
+    if (!f?.nav?.show_in_nav) continue;
+    const code = f.module_code;
+    const mod = modByCode.get(code);
+    if (!mod) continue; // a feature whose module is missing/retired is simply not navigable
+    if (!groups.has(code)) {
+      groups.set(code, {
+        module_code: code,
+        name: mod.name,
+        icon: mod.icon || null,
+        position: mod.position ?? 0,
+        items: [],
+      });
+    }
+    groups.get(code).items.push({
+      feature_code: f.feature_code,
+      name: f.name,
+      route: f.route || null,
+      position: f.nav.position ?? 0,
+      is_external_url: !!f.nav.is_external_url,
+      external_url: f.nav.external_url || null,
+    });
+  }
+
+  const nav = [...groups.values()].sort((a, b) => a.position - b.position);
+  for (const g of nav) g.items.sort((a, b) => a.position - b.position);
+  return nav;
+}
+
+/**
+ * Resolve the access snapshot.
+ *
+ * @param {Object} p
+ * @param {Object} p.identity         { account_id, userId, roles[], actingAs? }
+ * @param {Object} p.registry         { features: [], modules: [] }  (already filtered to live rows)
+ * @param {Array}  p.grants           access_grants rows for {account, roles ∪ userId}
+ * @param {Array}  p.mappedProducts   the caller's product codes
+ * @param {Object} p.capabilities     capsFor(roles) — reads `bypassAllGates` (D27)
+ * @param {Function} [p.entitlementFor] (feature) → entitlement block | null
+ */
+export function resolveAccessSnapshot({
+  identity = {},
+  registry = {},
+  grants = [],
+  mappedProducts = [],
+  capabilities = {},
+  entitlementFor = null,
+  now = new Date(),
+} = {}) {
+  const features = (registry.features || []).filter(isLive);
+  const modules = registry.modules || [];
+
+  // ── D27: system-admin break-glass ───────────────────────────────────────────────────────────
+  // Resolved ONCE, here — never re-checked per gate, so no gate can forget to honour it. Opens
+  // every gate WITHIN the caller's own account. Deliberately NOT cross-tenant: crossing accounts
+  // is the separate, stricter canCrossAccount path (D3/BRI-582). bypassAllGates ≠ canCrossAccount.
+  const bypass = !!capabilities.bypassAllGates;
+
+  const allowedByCode = bypass
+    ? new Map(features.map((f) => [f.feature_code, { products: null }]))
+    : mergeGrants(grants, { mappedProducts, now });
+
+  const byCode = new Map(features.map((f) => [f.feature_code, f]));
+  // Product scope comes from the IDENTITY, for admins too. The loader already resolves an
+  // unmapped identity (internal staff, platform admins) to every product code, so this is "all"
+  // for them without any special case. Deriving a bypass admin's scope from the products declared
+  // ON FEATURES — as this used to — yields [] whenever no feature declares one, which is the state
+  // of the registry today: a system admin resolved to NO products, and every feature then inherited
+  // `products: []`. Kept only as a fallback for the case where identity scope is genuinely empty.
+  const identityScope = [...new Set(mappedProducts.map(String))];
+  const productScope = bypass && !identityScope.length
+    ? [...new Set(features.flatMap((f) => f.products || []))]
+    : identityScope;
+
+  const featureMap = {};
+  const allowedScreens = [];
+
+  for (const f of features) {
+    const grant = allowedByCode.get(f.feature_code);
+    if (!grant) continue;
+
+    // Platform-level product constraint on the feature itself, intersected with the grant's.
+    let products = grant.products ? [...grant.products] : [...productScope];
+    if (Array.isArray(f.products) && f.products.length) {
+      const allowedForFeature = new Set(f.products.map(String));
+      products = products.filter((p) => allowedForFeature.has(p));
+      // A product-constrained feature with no overlap is not reachable at all.
+      if (products.length === 0 && !bypass) continue;
+    }
+
+    const entitlement = bypass
+      ? {
+          unlocked: true,
+          quota: null,
+          used: 0,
+          remaining: null,
+          overage_policy: "unlimited",
+          reason: ENTITLEMENT_REASONS.ADMIN_BYPASS,
+        }
+      : entitlementFor
+        ? entitlementFor(f)
+        : null;
+
+    featureMap[f.feature_code] = {
+      allowed: true,
+      products: grant.products === null && !Array.isArray(f.products) ? "*" : products,
+      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);
+  }
+
+  // Attach each allowed action to its parent screen (actions are features, design §2).
+  for (const code of Object.keys(featureMap)) {
+    const f = byCode.get(code);
+    if (f?.feature_type !== "action") continue;
+    const parent = f.parent_feature_code || parentCodeOf(code);
+    if (parent && featureMap[parent]) featureMap[parent].actions.push(code);
+  }
+
+  return {
+    version: 1,
+    resolved_at: now.toISOString(),
+    resolved_for: {
+      userId: identity.userId ? String(identity.userId) : null,
+      account_id: identity.account_id ? String(identity.account_id) : null,
+      actingAs: identity.actingAs?.giver_id || null,
+      real_userId: identity.actingAs?.delegate_id || (identity.userId ? String(identity.userId) : null),
+      admin_bypass: bypass,
+    },
+    nav: buildNav(allowedScreens, modules),
+    features: featureMap,
+    productScope,
+  };
+}
+
+/** Snapshot-based `hasFeature` (the server-side twin of the client helper). */
+export function hasFeature(snapshot, featureCode) {
+  return !!snapshot?.features?.[featureCode]?.allowed;
+}
+
+/** True when the feature is allowed AND (no entitlement gate OR it is unlocked). */
+export function isUsable(snapshot, featureCode) {
+  const f = snapshot?.features?.[featureCode];
+  if (!f?.allowed) return false;
+  return !f.entitlement || f.entitlement.unlocked !== false;
+}
+
+export default { resolveAccessSnapshot, mergeGrants, buildNav, hasFeature, isUsable, ENTITLEMENT_REASONS };