@i4e/invest4edu-access-core 0.32.0 → 0.33.0

package/README.md

@@ -1,126 +1,128 @@
-# @i4e/invest4edu-access-core
-
-Shared tenant-isolation / access-control primitives for the NeoFindesk backends
-(nfd-api-node v1 + nfd-api-node-v2). The **D1 keystone** of the access-management epic:
-central, unforgettable `account_id` scoping.
-
-Both backends are ESM, so this package ships plain ESM source — no build step.
-
-## 0.32.0 — BREAKING, and it fails silently
-
-`resolveReporteeUserIds` **no longer reads `employees.reporting_manager` as a user id.** It
-reads it only as the manager's employee `_id`, which is the shape BRI-973 migrates the field
-to. This is a breaking change on a 0.x minor, so read the two notes below before upgrading a
-consumer.
-
-**1. Against un-migrated data it returns zero reportees, not an error.** The dual-shape
-widening that carried the rollout is gone. A manager whose rows have not been migrated
-resolves to a self-only scope, and because this function feeds record visibility in
-nfd-api-node and the lead access scope in nfd-api-node-v2, that reads as *"this manager has
-no reportees"* — nothing thrown, nothing logged, just a smaller answer.
-
-So the deploy order is **migrate → verify → bump**, not the other way round. Run
-nfd-api-node's `migrations/verify-reporting-manager-to-employee-id.js` and get a clean
-verdict before the first instance carrying 0.32.0 serves traffic. In a rolling deploy that
-window is real, so the migration must be complete rather than merely started.
-
-Under npm's 0.x caret rules `^0.31.0` will not resolve to 0.32.0, so no consumer is dragged
-across by an install — the ordering risk is entirely a human one.
-
-**2. Callers must pass the FULL employee list.** An `_id` reference only resolves if the row
-carrying it is present, so 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.
-Filter the result instead. `resolveReporteeUserIds` warns once when handed a list in which no
-row carries an `_id` at all, which is the one case where the answer is confidently wrong
-rather than merely narrow.
-
-0.32.0 also moves the entity/role vocabulary — `ENTITY`, `ENTITY_STATUS`,
-`isEntityLoginAllowed`, `conflictingEntityFor`, `ROLE_TYPE_PRIORITY`,
-`CLIENT_APP_ROLE_NAMES` — into this package. It was previously written out three times
-(nfd-api-node, nfd-api-node-v2, nfdui-nextjs) and held together by parity tests.
-
-## Install
-
-```
-npm install @i4e/invest4edu-access-core
-```
-
-## Usage
-
-**1. Carry identity per request** (in the auth middleware, JWT path only):
-
-```js
-import als from "@i4e/invest4edu-access-core/tenant-context";
-// after verifying the JWT:
-return als.run({ account_id, userId, roles }, () => next());
-```
-
-**2. Enforce on tenant-scoped models:**
-
-```js
-import { tenantPlugin } from "@i4e/invest4edu-access-core";
-schema.plugin(tenantPlugin);          // before mongoose.model(...)
-```
-
-The plugin injects `account_id` from the request's ALS store into the **filter** of every
-operation that selects existing documents:
-
-| | ops | switch |
-|---|---|---|
-| reads | `find` `findOne` `countDocuments` `distinct` | `TENANT_ENFORCEMENT` / `accessconfig.tenantEnforcement` |
-| writes | `updateOne` `updateMany` `replaceOne` `deleteOne` `deleteMany` `findOneAndUpdate` `findOneAndReplace` `findOneAndDelete` | `TENANT_ENFORCEMENT_WRITES` / `accessconfig.tenantEnforcementWrites` |
-
-Each switch is an independent ladder — `off` → `warn` → `enforce` — and **both default to `off`**,
-so installing the plugin is a literal no-op until you arm it. Reads and writes are separate
-because the blast radius is not comparable: a read that gains a filter returns less data, while a
-write that gains a filter silently modifies **nothing** and still reports success. Arming reads
-must never arm writes by surprise.
-
-| mode | identity present | identity absent |
-|---|---|---|
-| `off` (default) | no-op | no-op |
-| `warn` | reads: inject `account_id` · writes: **unchanged** | log `[tenant] identity-less …`, do **not** scope |
-| `enforce` | inject `account_id` | **throw** (fail-closed) |
-
-`warn` deliberately leaves writes alone. `warn` means "tell me what `enforce` would do", and for a
-destructive operation that promise is only kept by changing nothing — injecting a filter under a
-mode named `warn` would turn live `UPDATE`s into silent no-ops, the exact failure burn-in exists to
-catch. What you need before promoting is which writes run identity-less, and that is logged.
-
-Precedence per ladder: env var (if valid) → DB value → `off`. An unrecognised value is reported
-once and ignored rather than treated as `off`, so a typo cannot silently disarm enforcement.
-
-**3. Bypass for legitimately cross-tenant operations** (caches, migrations, scripts):
-
-```js
-import { runAsSystem } from "@i4e/invest4edu-access-core";
-await runAsSystem(() => Employee.find({ status: 1 }));   // whole scope
-Model.find(q).setOptions({ skipTenant: true });          // one query
-```
-
-## Exports
-
-- `als` (default of `/tenant-context`) — the AsyncLocalStorage instance
-- `runWithTenant(store, fn)`, `runAsSystem(fn)`, `getTenantStore()`
-- `tenantPlugin` (default of `/tenant-plugin`) — the Mongoose plugin
-- `setTenantMode(m)` / `getTenantMode()` — the read ladder
-- `setTenantWriteMode(m)` / `getTenantWriteMode()` — the write ladder
-- `resolveReporteeUserIds(roots, employees, opts)` (`/reportee-tree`) — self + all reportees
-- `ENTITY`, `ENTITY_STATUS`, `isEntityLoginAllowed`, `entityInactiveMessage`,
-  `checkPortalEntityAccess` (`/entity-status`) — which entities permit a login
-- `conflictingEntityFor`, `entityConflictMessage`, `CONFLICTING_ENTITIES`
-  (`/user-entity-link`) — which hats may coexist on one person
-- `ROLE_TYPE_PRIORITY`, `CLIENT_APP_ROLE_NAMES`, `pickPortalRoleName` (`/portal-roles`) —
-  which role names a portal session
-
-## Not covered
-**Aggregation pipelines** — add an explicit `{ $match: { account_id } }` stage.
-
-**Inserts** (`save`, `create`, `insertMany`) — and they cannot be. They carry no filter, so there
-is nothing to constrain; putting `account_id` *on* a new document is the caller's job. The plugin
-only governs which **existing** documents an operation may reach.
-
-`estimatedDocumentCount` takes no filter either, so it is not hooked.
-
-## Compatibility
-Node ≥ 18 (AsyncLocalStorage). `mongoose` ≥ 6 is an optional peer (only the plugin needs it).
+# @i4e/invest4edu-access-core
+
+Shared tenant-isolation / access-control primitives for the NeoFindesk backends
+(nfd-api-node v1 + nfd-api-node-v2). The **D1 keystone** of the access-management epic:
+central, unforgettable `account_id` scoping.
+
+Both backends are ESM, so this package ships plain ESM source — no build step.
+
+## 0.32.0 — BREAKING, and it fails silently
+
+`resolveReporteeUserIds` **no longer reads `employees.reporting_manager` as a user id.** It
+reads it only as the manager's employee `_id`, which is the shape BRI-973 migrates the field
+to. This is a breaking change on a 0.x minor, so read the two notes below before upgrading a
+consumer.
+
+**1. Against un-migrated data it returns zero reportees, not an error.** The dual-shape
+widening that carried the rollout is gone. A manager whose rows have not been migrated
+resolves to a self-only scope, and because this function feeds record visibility in
+nfd-api-node and the lead access scope in nfd-api-node-v2, that reads as *"this manager has
+no reportees"* — nothing thrown, nothing logged, just a smaller answer.
+
+So the deploy order is **migrate → verify → bump**, not the other way round. Run
+nfd-api-node's `migrations/verify-reporting-manager-to-employee-id.js` and get a clean
+verdict before the first instance carrying 0.32.0 serves traffic. In a rolling deploy that
+window is real, so the migration must be complete rather than merely started.
+
+Under npm's 0.x caret rules `^0.31.0` will not resolve to 0.32.0, so no consumer is dragged
+across by an install — the ordering risk is entirely a human one.
+
+**2. Callers must pass the FULL employee list.** An `_id` reference only resolves if the row
+carrying it is present, so 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.
+Filter the result instead. `resolveReporteeUserIds` warns once when handed a list in which no
+row carries an `_id` at all, which is the one case where the answer is confidently wrong
+rather than merely narrow.
+
+0.32.0 also moves the entity/role vocabulary — `ENTITY`, `ENTITY_STATUS`,
+`isEntityLoginAllowed`, `conflictingEntityFor`, `ROLE_TYPE_PRIORITY`,
+`CLIENT_APP_ROLE_NAMES` — into this package. It was previously written out three times
+(nfd-api-node, nfd-api-node-v2, nfdui-nextjs) and held together by parity tests.
+
+## Install
+
+```
+npm install @i4e/invest4edu-access-core
+```
+
+## Usage
+
+**1. Carry identity per request** (in the auth middleware, JWT path only):
+
+```js
+import als from "@i4e/invest4edu-access-core/tenant-context";
+// after verifying the JWT:
+return als.run({ account_id, userId, roles }, () => next());
+```
+
+**2. Enforce on tenant-scoped models:**
+
+```js
+import { tenantPlugin } from "@i4e/invest4edu-access-core";
+schema.plugin(tenantPlugin);          // before mongoose.model(...)
+```
+
+The plugin injects `account_id` from the request's ALS store into the **filter** of every
+operation that selects existing documents:
+
+| | ops | switch |
+|---|---|---|
+| reads | `find` `findOne` `countDocuments` `distinct` | `TENANT_ENFORCEMENT` / `accessconfig.tenantEnforcement` |
+| writes | `updateOne` `updateMany` `replaceOne` `deleteOne` `deleteMany` `findOneAndUpdate` `findOneAndReplace` `findOneAndDelete` | `TENANT_ENFORCEMENT_WRITES` / `accessconfig.tenantEnforcementWrites` |
+
+Each switch is an independent ladder — `off` → `warn` → `enforce` — and **both default to `off`**,
+so installing the plugin is a literal no-op until you arm it. Reads and writes are separate
+because the blast radius is not comparable: a read that gains a filter returns less data, while a
+write that gains a filter silently modifies **nothing** and still reports success. Arming reads
+must never arm writes by surprise.
+
+| mode | identity present | identity absent |
+|---|---|---|
+| `off` (default) | no-op | no-op |
+| `warn` | reads: inject `account_id` · writes: **unchanged** | log `[tenant] identity-less …`, do **not** scope |
+| `enforce` | inject `account_id` | **throw** (fail-closed) |
+
+`warn` deliberately leaves writes alone. `warn` means "tell me what `enforce` would do", and for a
+destructive operation that promise is only kept by changing nothing — injecting a filter under a
+mode named `warn` would turn live `UPDATE`s into silent no-ops, the exact failure burn-in exists to
+catch. What you need before promoting is which writes run identity-less, and that is logged.
+
+Precedence per ladder: env var (if valid) → DB value → `off`. An unrecognised value is reported
+once and ignored rather than treated as `off`, so a typo cannot silently disarm enforcement.
+
+**3. Bypass for legitimately cross-tenant operations** (caches, migrations, scripts):
+
+```js
+import { runAsSystem } from "@i4e/invest4edu-access-core";
+await runAsSystem(() => Employee.find({ status: 1 }));   // whole scope
+Model.find(q).setOptions({ skipTenant: true });          // one query
+```
+
+## Exports
+
+- `als` (default of `/tenant-context`) — the AsyncLocalStorage instance
+- `runWithTenant(store, fn)`, `runAsSystem(fn)`, `getTenantStore()`
+- `tenantPlugin` (default of `/tenant-plugin`) — the Mongoose plugin
+- `setTenantMode(m)` / `getTenantMode()` — the read ladder
+- `setTenantWriteMode(m)` / `getTenantWriteMode()` — the write ladder
+- `resolveReporteeUserIds(roots, employees, opts)` (`/reportee-tree`) — self + all reportees
+- `ENTITY`, `ENTITY_STATUS`, `isEntityLoginAllowed`, `entityInactiveMessage`,
+  `checkPortalEntityAccess` (`/entity-status`) — which entities permit a login
+- `conflictingEntityFor`, `entityConflictMessage`, `CONFLICTING_ENTITIES`
+  (`/user-entity-link`) — which hats may coexist on one person
+- `ROLE_TYPE_PRIORITY`, `CLIENT_APP_ROLE_NAMES`, `pickPortalRoleName` (`/portal-roles`) —
+  which role names a portal session
+- `normalizeRoute(route)`, `screenForRoute(features, route)` (`/route-screen`) — the screen row
+  a route resolves to, so a `MODULE.SCREEN.ACTION` code is read off the registry, never spelled
+
+## Not covered
+**Aggregation pipelines** — add an explicit `{ $match: { account_id } }` stage.
+
+**Inserts** (`save`, `create`, `insertMany`) — and they cannot be. They carry no filter, so there
+is nothing to constrain; putting `account_id` *on* a new document is the caller's job. The plugin
+only governs which **existing** documents an operation may reach.
+
+`estimatedDocumentCount` takes no filter either, so it is not hooked.
+
+## Compatibility
+Node ≥ 18 (AsyncLocalStorage). `mongoose` ≥ 6 is an optional peer (only the plugin needs it).

package/package.json

@@ -1,56 +1,57 @@
-{
-  "name": "@i4e/invest4edu-access-core",
-  "version": "0.32.0",
-  "description": "Shared access-control primitives for NeoFindesk: tenant keystone, role capabilities, reportee tree, entity/role vocabulary, feature flags, and the unified access engine (registry schema, snapshot resolver, visibleWhen).",
-  "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",
-    "./entity-status": "./src/entity-status.js",
-    "./user-entity-link": "./src/user-entity-link.js",
-    "./portal-roles": "./src/portal-roles.js",
-    "./access-config": "./src/access-config.js",
-    "./access-schema": "./src/access-schema.js",
-    "./access-resolver": "./src/access-resolver.js",
-    "./visible-when": "./src/visible-when.js",
-    "./entitlement": "./src/entitlement.js",
-    "./entitlement-schema": "./src/entitlement-schema.js",
-    "./grid-schema": "./src/grid-schema.js",
-    "./route-features": "./src/route-features.js",
-    "./subscription-lifecycle": "./src/subscription-lifecycle.js",
-    "./entitlement-store": "./src/entitlement-store.js",
-    "./proration": "./src/proration.js",
-    "./credits": "./src/credits.js"
-  },
-  "scripts": {
-    "test": "node --test test/*.test.mjs test/*.test.js"
-  },
-  "files": [
-    "src",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "sideEffects": false,
-  "keywords": [
-    "nfd",
-    "access-control",
-    "tenant-isolation",
-    "mongoose",
-    "async-local-storage"
-  ],
-  "peerDependencies": {
-    "mongoose": ">=6"
-  },
-  "peerDependenciesMeta": {
-    "mongoose": {
-      "optional": true
-    }
-  },
-  "license": "UNLICENSED",
-  "private": false
-}
+{
+  "name": "@i4e/invest4edu-access-core",
+  "version": "0.33.0",
+  "description": "Shared access-control primitives for NeoFindesk: tenant keystone, role capabilities, reportee tree, entity/role vocabulary, feature flags, and the unified access engine (registry schema, snapshot resolver, visibleWhen).",
+  "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",
+    "./entity-status": "./src/entity-status.js",
+    "./user-entity-link": "./src/user-entity-link.js",
+    "./portal-roles": "./src/portal-roles.js",
+    "./access-config": "./src/access-config.js",
+    "./access-schema": "./src/access-schema.js",
+    "./access-resolver": "./src/access-resolver.js",
+    "./visible-when": "./src/visible-when.js",
+    "./entitlement": "./src/entitlement.js",
+    "./entitlement-schema": "./src/entitlement-schema.js",
+    "./grid-schema": "./src/grid-schema.js",
+    "./route-features": "./src/route-features.js",
+    "./route-screen": "./src/route-screen.js",
+    "./subscription-lifecycle": "./src/subscription-lifecycle.js",
+    "./entitlement-store": "./src/entitlement-store.js",
+    "./proration": "./src/proration.js",
+    "./credits": "./src/credits.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs test/*.test.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "nfd",
+    "access-control",
+    "tenant-isolation",
+    "mongoose",
+    "async-local-storage"
+  ],
+  "peerDependencies": {
+    "mongoose": ">=6"
+  },
+  "peerDependenciesMeta": {
+    "mongoose": {
+      "optional": true
+    }
+  },
+  "license": "UNLICENSED",
+  "private": false
+}

package/src/access-config.js

@@ -1,68 +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;
-}
+/**
+ * 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;
+}