@i4e/invest4edu-access-core 0.32.0 → 0.34.0

package/src/reportee-tree.js

@@ -1,129 +1,129 @@
-/**
- * Reportee-tree DFS — @i4e/invest4edu-access-core (Track 3 G3 shared primitive).
- *
- * The one canonical "self + all reportees" traversal, shared by both backends so v1 and v2
- * compose the SAME hierarchy scope. Pure + data-source agnostic: the caller passes a flat
- * employees list `[{ _id, user_id, reporting_manager }]` (v1 feeds the Redis snapshot, v2 the
- * `employees` collection) and one-or-more root user ids (delegation passes `[self, ...givers]`).
- *
- * ── `reporting_manager` is an employee `_id` (BRI-973) ────────────────────────────────
- * It used to hold the manager's **user id**. It now holds the manager's **employee `_id`**,
- * so the hierarchy no longer depends on `employees.user_id` and that field can be dropped.
- *
- * Through the rollout this accepted both shapes; that widening is gone. Only an `_id` that is
- * present in the list resolves — an unrecognised reference detaches that manager's downline
- * rather than being read as a user id, which is the correct reading now that no row should
- * hold one.
- *
- * ── DEPLOY ORDER: migration first, then this version ──────────────────────────────────
- * This is a BREAKING change to the data this function can read, on a 0.x minor. Against
- * un-migrated rows it returns ZERO reportees — and since it feeds record visibility and the
- * lead access scope, that is a silent narrowing of what people can see rather than an error
- * anyone would notice.
- *
- * So: run nfd-api-node's migrations/verify-reporting-manager-to-employee-id.js and get a
- * clean verdict FIRST, then ship this version. The window that matters is a rolling deploy,
- * where an upgraded instance and un-migrated rows can coexist for real minutes — the
- * migration has to be complete before the first instance carrying this code serves traffic,
- * not merely started.
- *
- * Roots and the returned set stay **user ids** throughout, because that is what the callers
- * compare against (`assigned_rm_id`, `rm_id`). Only the manager reference is translated.
- *
- * ── CALLER CONTRACT: pass the manager's own row ───────────────────────────────────────
- * An employee-id reference can only be resolved if the row carrying that `_id` is in the
- * list. A user-id reference never needed a lookup, so under the old shape an absent manager
- * row cost nothing — under the new shape it silently detaches that manager's entire
- * downline.
- *
- * So a caller must feed EVERY employee for linking, and filter unwanted people out of the
- * RESULT. Feeding a pre-filtered list (`{ status: 1 }`, an account scope, anything) drops
- * link rows, and what you lose is not the filtered person but everyone beneath them.
- *
- * The caller this bites is nfd-api-node's `src/cache/employeeCache.js`, which builds the
- * hierarchy snapshot. It filtered `{ status: 1 }` and argued the filter was safe because it
- * "already breaks the chain at a deactivated manager" — true under the old shape, where the
- * manager's user id was the map key whether or not their row was present, and false under
- * this one. It now selects every employee and filters the RESULT instead. Any new caller
- * has to do the same.
- *
- * @param {string|string[]} roots  root user id(s)
- * @param {Array<{_id?:*, user_id:*, reporting_manager:*}>} employees  flat employee list
- * @param {Object} [options]
- * @param {Function} [options.onUnresolvable]  called once when the list carries no `_id` at
- *   all — see below. Defaults to `console.warn`; pass the app logger to route it properly.
- * @returns {string[]}  de-duplicated reachable set (roots + all reportees) as STRING ids
- */
-export function resolveReporteeUserIds(roots, employees, options = {}) {
-  const rootIds = (Array.isArray(roots) ? roots : [roots]).filter((id) => id != null).map(String);
-
-  /**
-   * employee `_id` -> that employee's user id.
-   *
-   * Built first and over the whole list, because a manager may appear anywhere in it — a
-   * single pass that resolved as it went would miss any manager listed after their reportee.
-   *
-   * Employees with no `user_id` are still indexed: such a row cannot be a REPORTEE (nothing
-   * to return for them) but it can perfectly well be a MANAGER, and dropping it here would
-   * silently orphan their whole downline. `null` marks "known employee, no portal user".
-   */
-  const userIdByEmployeeId = new Map();
-  for (const emp of employees || []) {
-    if (!emp || emp._id == null) continue;
-    userIdByEmployeeId.set(String(emp._id), emp.user_id == null ? null : String(emp.user_id));
-  }
-
-  /**
-   * A list with no `_id` on any row is the pre-BRI-973 shape, and nothing in it can ever
-   * resolve — every caller gets `[roots]` back, which reads as "this manager has no
-   * reportees" rather than as "this list cannot be understood".
-   *
-   * That is the one failure this cannot leave silent. It is not a degraded answer, it is a
-   * confident wrong one, and it is cheap to tell apart: an employee list of any size with
-   * an empty index means the caller passed the old shape or dropped `_id` from a projection.
-   * A warn here costs nothing on a correct call and turns the worst failure mode into an
-   * obvious one. It does not throw — this sits on the login path, and refusing to resolve a
-   * scope is a harder failure than reporting one.
-   */
-  if ((employees?.length || 0) > 0 && userIdByEmployeeId.size === 0) {
-    const warn = options.onUnresolvable || ((message) => console.warn(message));
-    warn(
-      `[reportee-tree] ${employees.length} employees but not one carries an \`_id\`, so no `
-      + 'reporting_manager reference can resolve and every caller sees zero reportees. The list '
-      + 'is in the pre-BRI-973 shape, or `_id` was dropped from the projection.',
-    );
-  }
-
-  const byManager = new Map();
-  for (const emp of employees || []) {
-    if (!emp || !emp.user_id) continue;
-    if (emp.reporting_manager == null) continue;
-
-    const raw = String(emp.reporting_manager);
-    /**
-     * The reference is an employee `_id`; it is translated to that manager's user id.
-     *
-     * `get` rather than the old "fall back to reading it as a user id": an unknown `_id` now
-     * means either a dangling reference or a row the caller filtered out of the list, and
-     * both are conditions to drop the edge on, not to guess about. See the caller contract.
-     */
-    const managerId = userIdByEmployeeId.get(raw);
-    // Unknown reference, or a manager with no portal user — no key to hang reportees on.
-    if (managerId == null) continue;
-
-    if (!byManager.has(managerId)) byManager.set(managerId, []);
-    byManager.get(managerId).push(String(emp.user_id));
-  }
-
-  const visited = new Set();
-  const result = new Set();
-  const stack = [...rootIds];
-  while (stack.length) {
-    const id = stack.pop();
-    if (!id || visited.has(id)) continue;
-    visited.add(id);
-    result.add(id);
-    for (const rep of byManager.get(id) || []) stack.push(rep);
-  }
-  return [...result];
-}
+/**
+ * Reportee-tree DFS — @i4e/invest4edu-access-core (Track 3 G3 shared primitive).
+ *
+ * The one canonical "self + all reportees" traversal, shared by both backends so v1 and v2
+ * compose the SAME hierarchy scope. Pure + data-source agnostic: the caller passes a flat
+ * employees list `[{ _id, user_id, reporting_manager }]` (v1 feeds the Redis snapshot, v2 the
+ * `employees` collection) and one-or-more root user ids (delegation passes `[self, ...givers]`).
+ *
+ * ── `reporting_manager` is an employee `_id` (BRI-973) ────────────────────────────────
+ * It used to hold the manager's **user id**. It now holds the manager's **employee `_id`**,
+ * so the hierarchy no longer depends on `employees.user_id` and that field can be dropped.
+ *
+ * Through the rollout this accepted both shapes; that widening is gone. Only an `_id` that is
+ * present in the list resolves — an unrecognised reference detaches that manager's downline
+ * rather than being read as a user id, which is the correct reading now that no row should
+ * hold one.
+ *
+ * ── DEPLOY ORDER: migration first, then this version ──────────────────────────────────
+ * This is a BREAKING change to the data this function can read, on a 0.x minor. Against
+ * un-migrated rows it returns ZERO reportees — and since it feeds record visibility and the
+ * lead access scope, that is a silent narrowing of what people can see rather than an error
+ * anyone would notice.
+ *
+ * So: run nfd-api-node's migrations/verify-reporting-manager-to-employee-id.js and get a
+ * clean verdict FIRST, then ship this version. The window that matters is a rolling deploy,
+ * where an upgraded instance and un-migrated rows can coexist for real minutes — the
+ * migration has to be complete before the first instance carrying this code serves traffic,
+ * not merely started.
+ *
+ * Roots and the returned set stay **user ids** throughout, because that is what the callers
+ * compare against (`assigned_rm_id`, `rm_id`). Only the manager reference is translated.
+ *
+ * ── CALLER CONTRACT: pass the manager's own row ───────────────────────────────────────
+ * An employee-id reference can only be resolved if the row carrying that `_id` is in the
+ * list. A user-id reference never needed a lookup, so under the old shape an absent manager
+ * row cost nothing — under the new shape it silently detaches that manager's entire
+ * downline.
+ *
+ * So a caller must feed EVERY employee for linking, and filter unwanted people out of the
+ * RESULT. Feeding a pre-filtered list (`{ status: 1 }`, an account scope, anything) drops
+ * link rows, and what you lose is not the filtered person but everyone beneath them.
+ *
+ * The caller this bites is nfd-api-node's `src/cache/employeeCache.js`, which builds the
+ * hierarchy snapshot. It filtered `{ status: 1 }` and argued the filter was safe because it
+ * "already breaks the chain at a deactivated manager" — true under the old shape, where the
+ * manager's user id was the map key whether or not their row was present, and false under
+ * this one. It now selects every employee and filters the RESULT instead. Any new caller
+ * has to do the same.
+ *
+ * @param {string|string[]} roots  root user id(s)
+ * @param {Array<{_id?:*, user_id:*, reporting_manager:*}>} employees  flat employee list
+ * @param {Object} [options]
+ * @param {Function} [options.onUnresolvable]  called once when the list carries no `_id` at
+ *   all — see below. Defaults to `console.warn`; pass the app logger to route it properly.
+ * @returns {string[]}  de-duplicated reachable set (roots + all reportees) as STRING ids
+ */
+export function resolveReporteeUserIds(roots, employees, options = {}) {
+  const rootIds = (Array.isArray(roots) ? roots : [roots]).filter((id) => id != null).map(String);
+
+  /**
+   * employee `_id` -> that employee's user id.
+   *
+   * Built first and over the whole list, because a manager may appear anywhere in it — a
+   * single pass that resolved as it went would miss any manager listed after their reportee.
+   *
+   * Employees with no `user_id` are still indexed: such a row cannot be a REPORTEE (nothing
+   * to return for them) but it can perfectly well be a MANAGER, and dropping it here would
+   * silently orphan their whole downline. `null` marks "known employee, no portal user".
+   */
+  const userIdByEmployeeId = new Map();
+  for (const emp of employees || []) {
+    if (!emp || emp._id == null) continue;
+    userIdByEmployeeId.set(String(emp._id), emp.user_id == null ? null : String(emp.user_id));
+  }
+
+  /**
+   * A list with no `_id` on any row is the pre-BRI-973 shape, and nothing in it can ever
+   * resolve — every caller gets `[roots]` back, which reads as "this manager has no
+   * reportees" rather than as "this list cannot be understood".
+   *
+   * That is the one failure this cannot leave silent. It is not a degraded answer, it is a
+   * confident wrong one, and it is cheap to tell apart: an employee list of any size with
+   * an empty index means the caller passed the old shape or dropped `_id` from a projection.
+   * A warn here costs nothing on a correct call and turns the worst failure mode into an
+   * obvious one. It does not throw — this sits on the login path, and refusing to resolve a
+   * scope is a harder failure than reporting one.
+   */
+  if ((employees?.length || 0) > 0 && userIdByEmployeeId.size === 0) {
+    const warn = options.onUnresolvable || ((message) => console.warn(message));
+    warn(
+      `[reportee-tree] ${employees.length} employees but not one carries an \`_id\`, so no `
+      + 'reporting_manager reference can resolve and every caller sees zero reportees. The list '
+      + 'is in the pre-BRI-973 shape, or `_id` was dropped from the projection.',
+    );
+  }
+
+  const byManager = new Map();
+  for (const emp of employees || []) {
+    if (!emp || !emp.user_id) continue;
+    if (emp.reporting_manager == null) continue;
+
+    const raw = String(emp.reporting_manager);
+    /**
+     * The reference is an employee `_id`; it is translated to that manager's user id.
+     *
+     * `get` rather than the old "fall back to reading it as a user id": an unknown `_id` now
+     * means either a dangling reference or a row the caller filtered out of the list, and
+     * both are conditions to drop the edge on, not to guess about. See the caller contract.
+     */
+    const managerId = userIdByEmployeeId.get(raw);
+    // Unknown reference, or a manager with no portal user — no key to hang reportees on.
+    if (managerId == null) continue;
+
+    if (!byManager.has(managerId)) byManager.set(managerId, []);
+    byManager.get(managerId).push(String(emp.user_id));
+  }
+
+  const visited = new Set();
+  const result = new Set();
+  const stack = [...rootIds];
+  while (stack.length) {
+    const id = stack.pop();
+    if (!id || visited.has(id)) continue;
+    visited.add(id);
+    result.add(id);
+    for (const rep of byManager.get(id) || []) stack.push(rep);
+  }
+  return [...result];
+}

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