@i4e/invest4edu-access-core 0.28.0 → 0.29.0

package/README.md

@@ -29,15 +29,35 @@ 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 every
-`find` / `findOne` / `countDocuments`. Mode via `TENANT_ENFORCEMENT`:
+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 |
 |---|---|---|
-| `warn` (default) | inject `account_id` | log `[tenant] identity-less …`, do **not** scope |
+| `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) |
 
-**3. Bypass for legitimately cross-tenant reads** (caches, migrations, scripts):
+`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";
@@ -50,11 +70,17 @@ Model.find(q).setOptions({ skipTenant: true });          // one query
 - `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
 
 ## Not covered
-Aggregation pipelines (add an explicit `{ $match: { account_id } }` stage) and write
-ops — reads are the C0 scope. Visibility/delegation/role-classification land in later
-minor versions (Track 3 C1).
+**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,6 +1,6 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Shared access-control primitives for NeoFindesk: tenant keystone, role capabilities, reportee tree, feature flags, and the unified access engine (registry schema, snapshot resolver, visibleWhen).",
   "type": "module",
   "exports": {
@@ -23,7 +23,7 @@
     "./credits": "./src/credits.js"
   },
   "scripts": {
-    "test": "node --test test/"
+    "test": "node --test test/*.test.mjs test/*.test.js"
   },
   "files": [
     "src",

package/src/index.js

@@ -3,7 +3,14 @@
  * Tenant isolation (D1 keystone) + role capabilities (G7).
  */
 export { default as als, runWithTenant, runAsSystem, getTenantStore } from "./tenant-context.js";
-export { default as tenantPlugin, setTenantMode, getTenantMode } from "./tenant-plugin.js";
+export {
+  default as tenantPlugin,
+  setTenantMode,
+  getTenantMode,
+  setTenantWriteMode,
+  getTenantWriteMode,
+  TENANT_MODES,
+} from "./tenant-plugin.js";
 export {
   CAPABILITY_FLAGS,
   DEFAULT_ROLE_CAPABILITIES,

package/src/tenant-plugin.js

@@ -1,69 +1,177 @@
 /**
  * Tenant-isolation Mongoose plugin — @i4e/invest4edu-access-core (Track 3 D1 keystone).
  *
- * Applied to tenant-scoped models. On every read (`find`/`findOne`/`countDocuments`) it
- * 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.
+ * Applied to tenant-scoped models. It injects `account_id` from the request's ALS store
+ * (tenant-context.js) into the FILTER of every operation that selects existing documents, so a
+ * query cannot reach Mongo without the caller's tenant boundary — even if the controller forgot it.
  *
- * 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.
+ * ── TWO LADDERS, ON PURPOSE ──────────────────────────────────────────────────────────────────
+ * Reads and writes have SEPARATE switches, each defaulting to `off`:
  *
- * Bypass: `runAsSystem(fn)` or `.setOptions({ skipTenant: true })` for legitimately
- * cross-tenant reads. NOT covered: aggregation pipelines and write ops (reads are C0 scope).
+ *   reads   `TENANT_ENFORCEMENT`         / accessconfig.tenantEnforcement
+ *   writes  `TENANT_ENFORCEMENT_WRITES`  / accessconfig.tenantEnforcementWrites
+ *
+ * They are separate because the blast radius is not comparable. A read that gains a filter
+ * returns less data; a write that gains a filter silently modifies NOTHING, and the caller is
+ * told it succeeded. Nobody promoting reads to `warn` should discover they also armed writes.
+ *
+ * Each ladder: off → warn (burn-in, watch `[tenant] identity-less`) → enforce.
+ *
+ *   off (DEFAULT)  literal no-op; behaviour identical to pre-Track-3. Safe merge baseline.
+ *   warn           READS:  inject when identity present; log identity-less reads.
+ *                  WRITES: log identity-less writes; NEVER alter the filter (see below).
+ *   enforce        inject when identity present; THROW on identity-less (fail-closed).
+ *
+ * The read/write asymmetry at `warn` is deliberate. `warn` means "tell me what enforce would do",
+ * and for a destructive operation that promise is only kept by changing nothing. Injecting on a
+ * write under a mode named `warn` would silently turn UPDATEs into no-ops in production — the
+ * exact failure the burn-in step exists to avoid. The signal you need before promoting is which
+ * writes run identity-less, and that is logged.
+ *
+ * Precedence per ladder: env var (if valid) > DB value (setTenantMode/setTenantWriteMode) > "off".
+ * The DB value is the admin-UI toggle (takes effect on the next config refresh, no restart); the
+ * env var is the infra-level emergency override.
+ *
+ * Bypass: `runAsSystem(fn)` or `.setOptions({ skipTenant: true })` for legitimately cross-tenant
+ * operations. NOT covered: aggregation pipelines — add an explicit `{ $match: { account_id } }`.
  *
  * Logging is intentionally `console.warn` (not a repo-specific logger) so this file stays
  * byte-identical across both backends. Warnings surface in stdout logs during burn-in.
  */
 import als from "./tenant-context.js";
 
-const READ_OPS = ["find", "findOne", "countDocuments"];
-const VALID = new Set(["off", "warn", "enforce"]);
+/** Reads. Governed by the READ ladder. */
+const READ_OPS = ["find", "findOne", "countDocuments", "distinct"];
+
+/**
+ * Writes that SELECT existing documents by filter. Governed by the WRITE ladder.
+ *
+ * `save` / `create` / `insertMany` are absent and cannot be added: they carry no filter. Putting
+ * `account_id` ON a new document is the caller's job — this plugin only constrains which EXISTING
+ * documents an operation may reach. `estimatedDocumentCount` is absent for the same reason: it
+ * takes no filter, so there is nothing to scope.
+ */
+const WRITE_OPS = [
+  "updateOne",
+  "updateMany",
+  "replaceOne",
+  "deleteOne",
+  "deleteMany",
+  "findOneAndUpdate",
+  "findOneAndReplace",
+  "findOneAndDelete",
+];
+
+/**
+ * Mongoose registers these names as BOTH document and query middleware, and which one you get by
+ * default has moved between major versions (the package supports mongoose >= 6). Pin the query
+ * form explicitly. The document form would be wrong here anyway — it fires on an already-loaded
+ * document, which was fetched through a read hook and is therefore already scoped.
+ */
+const DUAL_HOOKS = new Set(["updateOne", "deleteOne"]);
+
+/**
+ * The enforcement ladder, in order. Exported because both backends validate an incoming mode
+ * before storing it and render the choices in the admin UI — without this they each keep their
+ * own `["off","warn","enforce"]` literal, and a mode added here would be silently unsettable.
+ */
+export const TENANT_MODES = Object.freeze(["off", "warn", "enforce"]);
+
+const VALID = new Set(TENANT_MODES);
 
-// Enforcement mode is resolvable from TWO places, so it can be flipped from the admin UI
-// (DB) WITHOUT a restart, while the env var stays the infra-level emergency override.
-//   Precedence:  env TENANT_ENFORCEMENT (if valid)  >  DB value (setTenantMode)  >  "off"
-let dbMode = null;
+let dbMode = null; // reads
+let dbWriteMode = null; // writes
+
+/** Bad values are reported once each, not once per query — this runs on every operation. */
+const warnedBadValues = new Set();
+
+/**
+ * Parse a mode from env or DB. Returns null for absent OR unrecognised, so the caller falls
+ * through to the next source in the precedence chain.
+ *
+ * Trimming matters more than it looks: `TENANT_ENFORCEMENT="enforce "` pasted into App Service
+ * config, or a stray space in the admin UI, used to fail the VALID check and silently downgrade
+ * enforcement to `off` while every screen still read "enforce".
+ */
+function normaliseMode(raw, source) {
+  const v = raw == null ? "" : String(raw).trim().toLowerCase();
+  if (!v) return null;
+  if (VALID.has(v)) return v;
+
+  const seen = `${source}=${v}`;
+  if (!warnedBadValues.has(seen)) {
+    warnedBadValues.add(seen);
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[tenant] unrecognised enforcement mode ${seen} — expected ${[...VALID].join(" | ")}; ignoring this source`,
+    );
+  }
+  return null;
+}
 
 /** Called by the backend from the `accessconfig` DB doc so a UI toggle takes effect (~refresh). */
 export function setTenantMode(m) {
-  const v = m ? String(m).toLowerCase() : "";
-  dbMode = VALID.has(v) ? v : null;
+  dbMode = normaliseMode(m, "accessconfig.tenantEnforcement");
 }
 
-/** Effective mode. */
+/** Effective READ mode. */
 export function getTenantMode() {
-  const env = (process.env.TENANT_ENFORCEMENT || "").toLowerCase();
-  if (VALID.has(env)) return env; // explicit env wins (emergency / infra)
-  return dbMode || "off";
+  return normaliseMode(process.env.TENANT_ENFORCEMENT, "TENANT_ENFORCEMENT") || dbMode || "off";
 }
 
-const mode = getTenantMode;
+/** Write-ladder counterpart of setTenantMode. */
+export function setTenantWriteMode(m) {
+  dbWriteMode = normaliseMode(m, "accessconfig.tenantEnforcementWrites");
+}
+
+/** Effective WRITE mode. Independent of the read mode — never inherits it. */
+export function getTenantWriteMode() {
+  return (
+    normaliseMode(process.env.TENANT_ENFORCEMENT_WRITES, "TENANT_ENFORCEMENT_WRITES") ||
+    dbWriteMode ||
+    "off"
+  );
+}
 
-function tenantHook() {
-  if (mode() === "off") return; // literal no-op — identical to pre-Track-3
+/**
+ * @param {() => string} getMode      the ladder this op answers to
+ * @param {string} opName            fallback for `this.op`
+ * @param {"read"|"write"} kind
+ */
+function makeTenantHook(getMode, opName, kind) {
+  return function tenantHook() {
+    const mode = getMode();
+    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;
+    const opts = typeof this.getOptions === "function" ? this.getOptions() : this.options || {};
+    if (opts && opts.skipTenant) return;
 
-  const store = als.getStore();
-  if (store && store.system) return; // runAsSystem — cross-tenant by design
+    const store = als.getStore();
+    if (store && store.system) return; // runAsSystem — cross-tenant by design
 
-  if (store && store.account_id) {
-    this.where({ account_id: store.account_id }); // identity is authoritative
-    return;
-  }
+    if (store && store.account_id) {
+      // A write under `warn` is observed, never altered. See the ladder note at the top.
+      if (kind === "write" && mode === "warn") return;
+      this.where({ account_id: store.account_id }); // identity is authoritative
+      return;
+    }
 
-  const modelName = (this.model && this.model.modelName) || "unknown";
-  if (mode() === "enforce") {
-    throw new Error(`tenant identity required — no account_id in context for ${modelName}.${this.op}`);
-  }
-  // eslint-disable-next-line no-console
-  console.warn(`[tenant] identity-less ${modelName}.${this.op} not scoped (warn mode)`);
+    const modelName = (this.model && this.model.modelName) || "unknown";
+    const op = this.op || opName;
+    if (mode === "enforce") {
+      throw new Error(`tenant identity required — no account_id in context for ${modelName}.${op}`);
+    }
+    // eslint-disable-next-line no-console
+    console.warn(`[tenant] identity-less ${kind} ${modelName}.${op} not scoped (warn mode)`);
+  };
 }
 
 export default function tenantPlugin(schema) {
-  READ_OPS.forEach((op) => schema.pre(op, tenantHook));
+  READ_OPS.forEach((op) => schema.pre(op, makeTenantHook(getTenantMode, op, "read")));
+
+  WRITE_OPS.forEach((op) => {
+    const hook = makeTenantHook(getTenantWriteMode, op, "write");
+    if (DUAL_HOOKS.has(op)) schema.pre(op, { document: false, query: true }, hook);
+    else schema.pre(op, hook);
+  });
 }