@i4e/invest4edu-access-core 0.3.0 → 0.4.1

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.3.0",
-  "description": "Shared tenant-isolation / access-control primitives (Track 3 D1 keystone + role capabilities + reportee tree) for NeoFindesk backends.",
+  "version": "0.4.1",
+  "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",
-    "./reportee-tree": "./src/reportee-tree.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

@@ -11,3 +11,10 @@ export {
   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/tenant-plugin.js

@@ -5,9 +5,11 @@
  * injects `account_id` from the request's ALS store (tenant-context.js), so a query cannot
  * reach Mongo without the caller's tenant boundary — even if the controller forgot it.
  *
- * Modes (env `TENANT_ENFORCEMENT`, default `warn`):
- *   - identity present → inject `account_id` unconditionally (BOTH modes)
- *   - identity absent  → `enforce`: THROW (fail-closed) · `warn`: log + do not scope (burn-in)
+ * Modes (env `TENANT_ENFORCEMENT`, default `off`):
+ *   - `off` (DEFAULT)  → literal no-op; behaviour identical to pre-Track-3. Safe merge baseline.
+ *   - `warn`           → inject `account_id` when identity present; log identity-less reads.
+ *   - `enforce`        → inject when present; THROW on identity-less reads (fail-closed).
+ * Rollout ladder: off → warn (burn-in, watch `[tenant] identity-less`) → enforce.
  *
  * Bypass: `runAsSystem(fn)` or `.setOptions({ skipTenant: true })` for legitimately
  * cross-tenant reads. NOT covered: aggregation pipelines and write ops (reads are C0 scope).
@@ -18,9 +20,11 @@
 import als from "./tenant-context.js";
 
 const READ_OPS = ["find", "findOne", "countDocuments"];
-const mode = () => (process.env.TENANT_ENFORCEMENT || "warn").toLowerCase();
+const mode = () => (process.env.TENANT_ENFORCEMENT || "off").toLowerCase();
 
 function tenantHook() {
+  if (mode() === "off") return; // literal no-op — identical to pre-Track-3
+
   const opts = typeof this.getOptions === "function" ? this.getOptions() : this.options || {};
   if (opts && opts.skipTenant) return;