@i4e/invest4edu-access-core 0.1.0

package/README.md

@@ -0,0 +1,60 @@
+# @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.
+
+## 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 every
+`find` / `findOne` / `countDocuments`. Mode via `TENANT_ENFORCEMENT`:
+
+| mode | identity present | identity absent |
+|---|---|---|
+| `warn` (default) | inject `account_id` | log `[tenant] identity-less …`, do **not** scope |
+| `enforce` | inject `account_id` | **throw** (fail-closed) |
+
+**3. Bypass for legitimately cross-tenant reads** (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
+
+## 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).
+
+## Compatibility
+Node ≥ 18 (AsyncLocalStorage). `mongoose` ≥ 6 is an optional peer (only the plugin needs it).

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@i4e/invest4edu-access-core",
+  "version": "0.1.0",
+  "description": "Shared tenant-isolation / access-control primitives (Track 3 D1 keystone) for NeoFindesk backends.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./tenant-context": "./src/tenant-context.js",
+    "./tenant-plugin": "./src/tenant-plugin.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/index.js

@@ -0,0 +1,6 @@
+/**
+ * Access-core barrel (Track 3 C1). CANONICAL SHARED — keep identical in both backends.
+ * The tenant-enforcement primitives authored once and vendored into v1 + v2.
+ */
+export { default as als, runWithTenant, runAsSystem, getTenantStore } from "./tenant-context.js";
+export { default as tenantPlugin } from "./tenant-plugin.js";

package/src/tenant-context.js

@@ -0,0 +1,26 @@
+/**
+ * Tenant request-context — @i4e/invest4edu-access-core (Track 3 D1 keystone).
+ *
+ * AsyncLocalStorage carries the authenticated identity (`account_id`, `userId`, `roles`)
+ * for the lifetime of a request. The tenant plugin (tenant-plugin.js) reads `account_id`
+ * from here and injects it into every tenant-scoped read.
+ *
+ * Store shapes:
+ *   { account_id, userId, roles }  — a normal authenticated request (JWT path)
+ *   { system: true }               — a legitimate cross-tenant/non-request context via runAsSystem()
+ *   (empty)                        — no identity. Plugin fails closed in `enforce`, warns in `warn`.
+ */
+import { AsyncLocalStorage } from "async_hooks";
+
+const als = new AsyncLocalStorage();
+
+/** Run `fn` with the given tenant identity in context. */
+export const runWithTenant = (store, fn) => als.run(store || {}, fn);
+
+/** Run `fn` in a system context that bypasses tenant injection (scripts, cross-tenant reads). */
+export const runAsSystem = (fn) => als.run({ system: true }, fn);
+
+/** Current tenant store (or undefined outside any run scope). */
+export const getTenantStore = () => als.getStore();
+
+export default als;

package/src/tenant-plugin.js

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ *
+ * 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)
+ *
+ * Bypass: `runAsSystem(fn)` or `.setOptions({ skipTenant: true })` for legitimately
+ * cross-tenant reads. NOT covered: aggregation pipelines and write ops (reads are C0 scope).
+ *
+ * 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 mode = () => (process.env.TENANT_ENFORCEMENT || "warn").toLowerCase();
+
+function tenantHook() {
+  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
+
+  if (store && store.account_id) {
+    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)`);
+}
+
+export default function tenantPlugin(schema) {
+  READ_OPS.forEach((op) => schema.pre(op, tenantHook));
+}