@i4e/invest4edu-access-core 0.1.0 → 0.3.0

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.1.0",
-  "description": "Shared tenant-isolation / access-control primitives (Track 3 D1 keystone) for NeoFindesk backends.",
+  "version": "0.3.0",
+  "description": "Shared tenant-isolation / access-control primitives (Track 3 D1 keystone + role capabilities + reportee tree) for NeoFindesk backends.",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
     "./tenant-context": "./src/tenant-context.js",
-    "./tenant-plugin": "./src/tenant-plugin.js"
+    "./tenant-plugin": "./src/tenant-plugin.js",
+    "./role-capabilities": "./src/role-capabilities.js",
+    "./reportee-tree": "./src/reportee-tree.js"
   },
   "files": [
     "src",

package/src/index.js

@@ -1,6 +1,13 @@
 /**
- * Access-core barrel (Track 3 C1). CANONICAL SHARED — keep identical in both backends.
- * The tenant-enforcement primitives authored once and vendored into v1 + v2.
+ * @i4e/invest4edu-access-core — shared access-control primitives for the NFD backends.
+ * Tenant isolation (D1 keystone) + role capabilities (G7).
  */
 export { default as als, runWithTenant, runAsSystem, getTenantStore } from "./tenant-context.js";
 export { default as tenantPlugin } from "./tenant-plugin.js";
+export {
+  CAPABILITY_FLAGS,
+  DEFAULT_ROLE_CAPABILITIES,
+  buildCapabilityMap,
+  resolveCapabilities,
+} from "./role-capabilities.js";
+export { resolveReporteeUserIds } from "./reportee-tree.js";

package/src/reportee-tree.js

@@ -0,0 +1,35 @@
+/**
+ * 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 `[{ user_id, reporting_manager }]` (v1 feeds the Redis snapshot, v2 the
+ * `employees` collection) and one-or-more root user ids (delegation passes `[self, ...givers]`).
+ *
+ * @param {string|string[]} roots  root user id(s)
+ * @param {Array<{user_id:*, reporting_manager:*}>} employees  flat employee list
+ * @returns {string[]}  de-duplicated reachable set (roots + all reportees) as STRING ids
+ */
+export function resolveReporteeUserIds(roots, employees) {
+  const rootIds = (Array.isArray(roots) ? roots : [roots]).filter((id) => id != null).map(String);
+
+  const byManager = new Map();
+  for (const emp of employees || []) {
+    if (!emp || !emp.user_id) continue;
+    const managerId = String(emp.reporting_manager);
+    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

@@ -0,0 +1,79 @@
+/**
+ * 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
+ */
+
+export const CAPABILITY_FLAGS = Object.freeze([
+  "isFullAccess",
+  "isEmployee",
+  "canGovernDelegation",
+  "canCorrectE1",
+  "canCrossAccount",
+  "productScoped",
+]);
+
+/**
+ * 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({
+  SUPER_ADMIN: { isFullAccess: true, canGovernDelegation: true, canCorrectE1: true },
+  SYSTEM_ADMIN: { isFullAccess: true, canGovernDelegation: true, canCorrectE1: 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;
+}