@i4e/invest4edu-access-core 0.32.0 → 0.33.0

package/src/role-capabilities.js

@@ -1,93 +1,93 @@
-/**
- * Role capabilities — @i4e/invest4edu-access-core (Track 3 C1 · G7).
- *
- * Turns role classification from hardcoded per-repo Sets into DATA. A `roleCapabilities`
- * collection (one row per role) overrides these defaults; with no rows, `resolveCapabilities`
- * reproduces the exact legacy behaviour, so wiring this in is behaviour-neutral until config
- * is populated.
- *
- * Flags:
- *   isFullAccess        — sees all data within the account (BROKER_ADMIN-style super-role)
- *   isEmployee          — eligible for the reportee-tree / 5-field visibility scope
- *   canGovernDelegation — may grant / edit / reactivate delegations
- *   canCorrectE1        — may run the audited E1 correction
- *   canCrossAccount     — audited sysadmin cross-account path (default: none)
- *   productScoped       — pages + records restricted to the user's mapped products
- *   bypassAllGates      — system-admin break-glass (D27): opens EVERY gate WITHIN the caller's
- *                         own account (RBAC, nav, entitlement, product scope, grid visibleWhen,
- *                         kill switches). Deliberately NOT cross-tenant — crossing accounts is
- *                         the separate, stricter `canCrossAccount` path (D3/BRI-582: config data
- *                         only, header-driven, logged before bypass). bypassAllGates ≠
- *                         canCrossAccount. Exists so a broken access config can never lock
- *                         everyone out of the screens needed to repair it.
- */
-
-export const CAPABILITY_FLAGS = Object.freeze([
-  "isFullAccess",
-  "isEmployee",
-  "canGovernDelegation",
-  "canCorrectE1",
-  "canCrossAccount",
-  "productScoped",
-  "bypassAllGates",
-  // Edit the GLOBAL feature registry (modules/screens/actions + their flags). Deliberately
-  // narrower than canGovernDelegation: that includes per-account BROKER_ADMINs, and the registry
-  // is cross-account — one edit changes what every tenant sees.
-  "canManageRegistry",
-]);
-
-/**
- * Legacy-parity defaults. MUST mirror the hardcoded Sets they replace:
- *   FULL_ACCESS_ROLES  = SUPER_ADMIN, SYSTEM_ADMIN, BROKER_ADMIN, BACKOFFICE_USER, HR_USER
- *   EMPLOYEE_ROLES     = SALES_USER, PAT_SALES
- *   GRANT_ROLES (deleg)= SUPER_ADMIN, SYSTEM_ADMIN, BROKER_ADMIN
- *   ALLOWED_ROLES (e1) = SUPER_ADMIN, SYSTEM_ADMIN, BROKER_ADMIN, BACKOFFICE_USER
- */
-export const DEFAULT_ROLE_CAPABILITIES = Object.freeze({
-  // bypassAllGates (D27) defaults to the two platform-admin roles. Inert until the access
-  // engine reads it, and revocable from the `rolecapabilities` collection with no deploy.
-  SUPER_ADMIN: { isFullAccess: true, canGovernDelegation: true, canCorrectE1: true, bypassAllGates: true, canManageRegistry: true },
-  SYSTEM_ADMIN: { isFullAccess: true, canGovernDelegation: true, canCorrectE1: true, bypassAllGates: true, canManageRegistry: true },
-  BROKER_ADMIN: { isFullAccess: true, canGovernDelegation: true, canCorrectE1: true },
-  BACKOFFICE_USER: { isFullAccess: true, canCorrectE1: true },
-  HR_USER: { isFullAccess: true },
-  SALES_USER: { isEmployee: true },
-  PAT_SALES: { isEmployee: true },
-});
-
-function pickFlags(row) {
-  const out = {};
-  for (const f of CAPABILITY_FLAGS) if (row[f] != null) out[f] = !!row[f];
-  return out;
-}
-
-/**
- * Merge DB rows over the parity defaults → a role→capabilities map.
- * @param {Array<{role:string} & Record<string, boolean>>} dbRows
- */
-export function buildCapabilityMap(dbRows = []) {
-  const map = {};
-  for (const [role, caps] of Object.entries(DEFAULT_ROLE_CAPABILITIES)) map[role] = { ...caps };
-  for (const row of dbRows) {
-    if (!row || !row.role) continue;
-    map[row.role] = { ...(map[row.role] || {}), ...pickFlags(row) };
-  }
-  return map;
-}
-
-/**
- * OR-combine the capability flags across all of a caller's roles (multi-role = union).
- * @param {string[]} roles
- * @param {Record<string, Record<string, boolean>>} [capabilityMap] defaults if omitted
- * @returns {Record<string, boolean>} every CAPABILITY_FLAG resolved to a boolean
- */
-export function resolveCapabilities(roles, capabilityMap = DEFAULT_ROLE_CAPABILITIES) {
-  const out = {};
-  for (const f of CAPABILITY_FLAGS) out[f] = false;
-  for (const role of Array.isArray(roles) ? roles : [roles].filter(Boolean)) {
-    const caps = capabilityMap[role];
-    if (!caps) continue;
-    for (const f of CAPABILITY_FLAGS) if (caps[f]) out[f] = true;
-  }
-  return out;
-}
+/**
+ * Role capabilities — @i4e/invest4edu-access-core (Track 3 C1 · G7).
+ *
+ * Turns role classification from hardcoded per-repo Sets into DATA. A `roleCapabilities`
+ * collection (one row per role) overrides these defaults; with no rows, `resolveCapabilities`
+ * reproduces the exact legacy behaviour, so wiring this in is behaviour-neutral until config
+ * is populated.
+ *
+ * Flags:
+ *   isFullAccess        — sees all data within the account (BROKER_ADMIN-style super-role)
+ *   isEmployee          — eligible for the reportee-tree / 5-field visibility scope
+ *   canGovernDelegation — may grant / edit / reactivate delegations
+ *   canCorrectE1        — may run the audited E1 correction
+ *   canCrossAccount     — audited sysadmin cross-account path (default: none)
+ *   productScoped       — pages + records restricted to the user's mapped products
+ *   bypassAllGates      — system-admin break-glass (D27): opens EVERY gate WITHIN the caller's
+ *                         own account (RBAC, nav, entitlement, product scope, grid visibleWhen,
+ *                         kill switches). Deliberately NOT cross-tenant — crossing accounts is
+ *                         the separate, stricter `canCrossAccount` path (D3/BRI-582: config data
+ *                         only, header-driven, logged before bypass). bypassAllGates ≠
+ *                         canCrossAccount. Exists so a broken access config can never lock
+ *                         everyone out of the screens needed to repair it.
+ */
+
+export const CAPABILITY_FLAGS = Object.freeze([
+  "isFullAccess",
+  "isEmployee",
+  "canGovernDelegation",
+  "canCorrectE1",
+  "canCrossAccount",
+  "productScoped",
+  "bypassAllGates",
+  // Edit the GLOBAL feature registry (modules/screens/actions + their flags). Deliberately
+  // narrower than canGovernDelegation: that includes per-account BROKER_ADMINs, and the registry
+  // is cross-account — one edit changes what every tenant sees.
+  "canManageRegistry",
+]);
+
+/**
+ * Legacy-parity defaults. MUST mirror the hardcoded Sets they replace:
+ *   FULL_ACCESS_ROLES  = SUPER_ADMIN, SYSTEM_ADMIN, BROKER_ADMIN, BACKOFFICE_USER, HR_USER
+ *   EMPLOYEE_ROLES     = SALES_USER, PAT_SALES
+ *   GRANT_ROLES (deleg)= SUPER_ADMIN, SYSTEM_ADMIN, BROKER_ADMIN
+ *   ALLOWED_ROLES (e1) = SUPER_ADMIN, SYSTEM_ADMIN, BROKER_ADMIN, BACKOFFICE_USER
+ */
+export const DEFAULT_ROLE_CAPABILITIES = Object.freeze({
+  // bypassAllGates (D27) defaults to the two platform-admin roles. Inert until the access
+  // engine reads it, and revocable from the `rolecapabilities` collection with no deploy.
+  SUPER_ADMIN: { isFullAccess: true, canGovernDelegation: true, canCorrectE1: true, bypassAllGates: true, canManageRegistry: true },
+  SYSTEM_ADMIN: { isFullAccess: true, canGovernDelegation: true, canCorrectE1: true, bypassAllGates: true, canManageRegistry: true },
+  BROKER_ADMIN: { isFullAccess: true, canGovernDelegation: true, canCorrectE1: true },
+  BACKOFFICE_USER: { isFullAccess: true, canCorrectE1: true },
+  HR_USER: { isFullAccess: true },
+  SALES_USER: { isEmployee: true },
+  PAT_SALES: { isEmployee: true },
+});
+
+function pickFlags(row) {
+  const out = {};
+  for (const f of CAPABILITY_FLAGS) if (row[f] != null) out[f] = !!row[f];
+  return out;
+}
+
+/**
+ * Merge DB rows over the parity defaults → a role→capabilities map.
+ * @param {Array<{role:string} & Record<string, boolean>>} dbRows
+ */
+export function buildCapabilityMap(dbRows = []) {
+  const map = {};
+  for (const [role, caps] of Object.entries(DEFAULT_ROLE_CAPABILITIES)) map[role] = { ...caps };
+  for (const row of dbRows) {
+    if (!row || !row.role) continue;
+    map[row.role] = { ...(map[row.role] || {}), ...pickFlags(row) };
+  }
+  return map;
+}
+
+/**
+ * OR-combine the capability flags across all of a caller's roles (multi-role = union).
+ * @param {string[]} roles
+ * @param {Record<string, Record<string, boolean>>} [capabilityMap] defaults if omitted
+ * @returns {Record<string, boolean>} every CAPABILITY_FLAG resolved to a boolean
+ */
+export function resolveCapabilities(roles, capabilityMap = DEFAULT_ROLE_CAPABILITIES) {
+  const out = {};
+  for (const f of CAPABILITY_FLAGS) out[f] = false;
+  for (const role of Array.isArray(roles) ? roles : [roles].filter(Boolean)) {
+    const caps = capabilityMap[role];
+    if (!caps) continue;
+    for (const f of CAPABILITY_FLAGS) if (caps[f]) out[f] = true;
+  }
+  return out;
+}