@i4e/invest4edu-access-core 0.2.0 → 0.4.0

package/package.json

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

package/src/access-config.js

@@ -0,0 +1,68 @@
+/**
+ * Access feature flags — @i4e/invest4edu-access-core (Track 3 master kill-switch).
+ *
+ * A single place to toggle the newer, riskier access behaviours on/off WITHOUT a code deploy,
+ * so a rollout can ship "off" (legacy behaviour) and be flipped on — or killed instantly if it
+ * misbehaves. Precedence (lowest → highest):
+ *
+ *   DEFAULT_ACCESS_FLAGS  <  DB (`accessconfig` collection)  <  env var
+ *
+ * DB toggles propagate in ~60s via the backend helper's background refresh (edit in the admin
+ * UI, no restart). The env var is the emergency kill: set `ACCESS_FLAG_<UPPER_SNAKE>=off` on the
+ * App Service and restart to force a flag regardless of DB.
+ *
+ * ALL defaults are the SAFE/legacy value — turning a flag on is an explicit, reversible act.
+ */
+
+export const DEFAULT_ACCESS_FLAGS = Object.freeze({
+  // #1 — v2 client-lead reads use the canonical 5-field visibility engine (else legacy lead-scope).
+  v2LeadFiveFieldVisibility: false,
+  // M1 — send grant/revoke emails via the comms service.
+  delegationEmailNotifications: false,
+  // H3 — write an access-event when giver-widening actually broadened a delegate's result.
+  delegationReadAudit: false,
+  // H1 — enable the "acting-as" session path (x-acting-as-giver).
+  delegationActingAs: false,
+});
+
+const ENV_PREFIX = "ACCESS_FLAG_";
+
+/** camelCase flag key → env var name, e.g. v2LeadFiveFieldVisibility → ACCESS_FLAG_V2_LEAD_FIVE_FIELD_VISIBILITY */
+export function flagEnvName(key) {
+  return ENV_PREFIX + key.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase();
+}
+
+export const ACCESS_FLAG_ENV_NAMES = Object.freeze(
+  Object.fromEntries(Object.keys(DEFAULT_ACCESS_FLAGS).map((k) => [k, flagEnvName(k)])),
+);
+
+function toBool(v) {
+  if (typeof v === "boolean") return v;
+  if (v == null || v === "") return undefined;
+  return /^(1|true|on|yes|enabled)$/i.test(String(v).trim());
+}
+
+/** Read any recognised flags from a process.env-shaped object. Unset vars are omitted. */
+export function readEnvFlags(env = {}) {
+  const out = {};
+  for (const key of Object.keys(DEFAULT_ACCESS_FLAGS)) {
+    const b = toBool(env[flagEnvName(key)]);
+    if (b !== undefined) out[key] = b;
+  }
+  return out;
+}
+
+/**
+ * Merge sources into the effective flag set. Only known keys are honoured.
+ * @param {{ dbFlags?: object, envFlags?: object }} sources
+ */
+export function resolveFlags({ dbFlags = {}, envFlags = {} } = {}) {
+  const out = { ...DEFAULT_ACCESS_FLAGS };
+  for (const key of Object.keys(DEFAULT_ACCESS_FLAGS)) {
+    const d = toBool(dbFlags ? dbFlags[key] : undefined);
+    if (d !== undefined) out[key] = d;
+    const e = toBool(envFlags ? envFlags[key] : undefined);
+    if (e !== undefined) out[key] = e; // env wins — emergency kill
+  }
+  return out;
+}

package/src/index.js

@@ -10,3 +10,11 @@ export {
   buildCapabilityMap,
   resolveCapabilities,
 } from "./role-capabilities.js";
+export { resolveReporteeUserIds } from "./reportee-tree.js";
+export {
+  DEFAULT_ACCESS_FLAGS,
+  ACCESS_FLAG_ENV_NAMES,
+  flagEnvName,
+  readEnvFlags,
+  resolveFlags,
+} from "./access-config.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];
+}