@nextage/nx-frame-be 1.0.45 → 1.0.46

package/build/common/base/__test__/audit.test.d.ts

@@ -0,0 +1,15 @@
+/*********************************************************************************************
+ *                                                                                           *
+ * AUDIT - the library keeps `createdBy`/`createdAt`/`updatedBy`/`updatedAt` for models that *
+ * declare them, and keeps out of the way of models that do not.                             *
+ *                                                                                           *
+ * The classes below are EMPTY on purpose. Whatever is stamped has to come from the library, *
+ * so a test that passed while a model helped would prove nothing about the models that      *
+ * never do - which are precisely the ones that used to be left without an audit.            *
+ *                                                                                           *
+ * Every assertion is on the payload the hooks return, not on stored documents: the point is *
+ * what the library puts there, and mongo would only add a round trip and a way to be wrong  *
+ * about it.                                                                                 *
+ *                                                                                           *
+ *********************************************************************************************/
+export {};

package/build/common/base/__test__/audit.test.js

@@ -0,0 +1,126 @@
+"use strict";
+/*********************************************************************************************
+ *                                                                                           *
+ * AUDIT - the library keeps `createdBy`/`createdAt`/`updatedBy`/`updatedAt` for models that *
+ * declare them, and keeps out of the way of models that do not.                             *
+ *                                                                                           *
+ * The classes below are EMPTY on purpose. Whatever is stamped has to come from the library, *
+ * so a test that passed while a model helped would prove nothing about the models that      *
+ * never do - which are precisely the ones that used to be left without an audit.            *
+ *                                                                                           *
+ * Every assertion is on the payload the hooks return, not on stored documents: the point is *
+ * what the library puts there, and mongo would only add a round trip and a way to be wrong  *
+ * about it.                                                                                 *
+ *                                                                                           *
+ *********************************************************************************************/
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const base_model_1 = require("../base.model");
+const mongo_utils_1 = require("../mongo-utils");
+/** Declares all four fields, as a model wanting an audit does. */
+class Audited extends base_model_1.BaseModel {
+}
+/** Declares none of them, as a model wanting no audit does. */
+class Plain extends base_model_1.BaseModel {
+}
+/** Declares them and keeps them itself - the reason `audit: false` exists. */
+class OptedOut extends base_model_1.BaseModel {
+}
+const auditedSchema = {
+    code: { type: String, required: true },
+    createdBy: { type: String },
+    createdAt: { type: Date },
+    updatedBy: { type: String },
+    updatedAt: { type: Date }
+};
+const audited = (0, mongo_utils_1.createModel)({
+    name: 'AuditAudited',
+    modelName: 'AuditAudited',
+    collection: 'auditAudited',
+    classDef: Audited,
+    modelParams: {},
+    schema: auditedSchema
+}, true);
+const plain = (0, mongo_utils_1.createModel)({
+    name: 'AuditPlain',
+    modelName: 'AuditPlain',
+    collection: 'auditPlain',
+    classDef: Plain,
+    modelParams: {},
+    schema: { code: { type: String, required: true } }
+}, true);
+const optedOut = (0, mongo_utils_1.createModel)({
+    name: 'AuditOptedOut',
+    modelName: 'AuditOptedOut',
+    collection: 'auditOptedOut',
+    classDef: OptedOut,
+    modelParams: { audit: false },
+    schema: auditedSchema
+}, true);
+const caller = { user: { id: 'user-1' } };
+const other = { user: { id: 'user-2' } };
+const anonymous = {};
+describe('audit kept by the library', () => {
+    describe('a model that declares the fields', () => {
+        it('stamps author and moment on creation', () => __awaiter(void 0, void 0, void 0, function* () {
+            const item = yield audited.beforeCreate({ code: 'a' }, caller);
+            expect(item.createdBy).toBe('user-1');
+            expect(item.createdAt).toBeInstanceOf(Date);
+        }));
+        it('stamps author and moment on update, and never the creation ones', () => __awaiter(void 0, void 0, void 0, function* () {
+            const item = yield audited.beforeUpdate({ code: 'a' }, other);
+            expect(item.updatedBy).toBe('user-2');
+            expect(item.updatedAt).toBeInstanceOf(Date);
+            expect(item.createdBy).toBeUndefined();
+            expect(item.createdAt).toBeUndefined();
+        }));
+        // The payload is the client's, so an audit it could write would say whatever the client
+        // wanted it to say - which is the same as having none.
+        it('ignores an author named by the payload', () => __awaiter(void 0, void 0, void 0, function* () {
+            const created = yield audited.beforeCreate({ code: 'a', createdBy: 'forged' }, caller);
+            const updated = yield audited.beforeUpdate({ code: 'a', updatedBy: 'forged' }, caller);
+            expect(created.createdBy).toBe('user-1');
+            expect(updated.updatedBy).toBe('user-1');
+        }));
+        // A document is created once: an update carrying the creation fields is either noise or
+        // an attempt to rewrite history, and dropping them costs nothing either way.
+        it('drops the creation fields an update tries to carry', () => __awaiter(void 0, void 0, void 0, function* () {
+            const item = yield audited.beforeUpdate({ code: 'a', createdBy: 'forged', createdAt: new Date(0) }, caller);
+            expect(item.createdBy).toBeUndefined();
+            expect(item.createdAt).toBeUndefined();
+        }));
+        // Nothing to attribute, so nothing is attributed - rather than a document claiming an
+        // author that does not exist.
+        it('leaves the author out when there is no user, and still records the moment', () => __awaiter(void 0, void 0, void 0, function* () {
+            const item = yield audited.beforeCreate({ code: 'a' }, anonymous);
+            expect(item.createdBy).toBeUndefined();
+            expect(item.createdAt).toBeInstanceOf(Date);
+        }));
+    });
+    describe('a model that declares none of them', () => {
+        // What keeps this change safe for consumers that never asked for an audit: no field
+        // appears in a collection that did not declare it.
+        it('is left untouched', () => __awaiter(void 0, void 0, void 0, function* () {
+            const created = yield plain.beforeCreate({ code: 'a' }, caller);
+            const updated = yield plain.beforeUpdate({ code: 'a' }, caller);
+            expect(created).toEqual({ code: 'a' });
+            expect(updated).toEqual({ code: 'a' });
+        }));
+    });
+    describe('a model that opted out', () => {
+        it('is left untouched even though it declares the fields', () => __awaiter(void 0, void 0, void 0, function* () {
+            const created = yield optedOut.beforeCreate({ code: 'a' }, caller);
+            const updated = yield optedOut.beforeUpdate({ code: 'a' }, caller);
+            expect(created).toEqual({ code: 'a' });
+            expect(updated).toEqual({ code: 'a' });
+        }));
+    });
+});

package/build/common/base/__test__/tenancy-opt-out.test.d.ts

@@ -0,0 +1,21 @@
+/*********************************************************************************************
+ *                                                                                           *
+ * TENANT SCOPING IS OPT-OUT                                                                 *
+ *                                                                                           *
+ * These tests state the behaviour of a model that overrides NOTHING. That is the whole      *
+ * point: every leak this file guards against was born the same way - a class that declared  *
+ * a tenant field and forgot one of the hooks that isolate it, silently answering every      *
+ * tenant from then on.                                                                      *
+ *                                                                                           *
+ * So none of the models below has a body. What they have is a schema with a tenant field    *
+ * and, where it matters, a declared mode - and the isolation has to follow from that        *
+ * alone.                                                                                    *
+ *                                                                                           *
+ * Two properties are asserted together, and they pull in opposite directions on purpose:    *
+ *                                                                                           *
+ *   1. WITH a provider registered, an unaware model is scoped anyway.                       *
+ *   2. WITHOUT one, nothing changes at all - the library is used by consumers that have no  *
+ *      notion of a tenant, and for them this file must be a no-op.                          *
+ *                                                                                           *
+ *********************************************************************************************/
+export {};

package/build/common/base/__test__/tenancy-opt-out.test.js

@@ -0,0 +1,214 @@
+"use strict";
+/*********************************************************************************************
+ *                                                                                           *
+ * TENANT SCOPING IS OPT-OUT                                                                 *
+ *                                                                                           *
+ * These tests state the behaviour of a model that overrides NOTHING. That is the whole      *
+ * point: every leak this file guards against was born the same way - a class that declared  *
+ * a tenant field and forgot one of the hooks that isolate it, silently answering every      *
+ * tenant from then on.                                                                      *
+ *                                                                                           *
+ * So none of the models below has a body. What they have is a schema with a tenant field    *
+ * and, where it matters, a declared mode - and the isolation has to follow from that        *
+ * alone.                                                                                    *
+ *                                                                                           *
+ * Two properties are asserted together, and they pull in opposite directions on purpose:    *
+ *                                                                                           *
+ *   1. WITH a provider registered, an unaware model is scoped anyway.                       *
+ *   2. WITHOUT one, nothing changes at all - the library is used by consumers that have no  *
+ *      notion of a tenant, and for them this file must be a no-op.                          *
+ *                                                                                           *
+ *********************************************************************************************/
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const constants_1 = require("../../constants");
+const base_model_1 = require("../base.model");
+const mongo_utils_1 = require("../mongo-utils");
+const enums_1 = require("../../enums");
+/** Marks a document every tenant shares, as an application would mark it. */
+const SHARED = '__GLOBAL__';
+/**
+ * A provider written the way an application would write one: it knows the roles, the
+ * library does not. `systemTier` stands in for the role group entitled to the shared tier.
+ */
+const provider = {
+    field: 'tenantId',
+    read(mode, context) {
+        const tenant = context.tenantId;
+        return (mode === enums_1.TenancyMode.shared) ? { $in: [tenant, SHARED] } : tenant;
+    },
+    write(mode, requested, context) {
+        const ctx = context;
+        if (mode === enums_1.TenancyMode.shared && requested === SHARED) {
+            if (!ctx.systemTier)
+                throw new Error('denied');
+            return SHARED;
+        }
+        return ctx.tenantId;
+    },
+    canWrite(mode, current, context) {
+        const ctx = context;
+        if (current === SHARED)
+            return !!ctx.systemTier;
+        return current === ctx.tenantId;
+    }
+};
+const schema = {
+    code: { type: String, required: true },
+    tenantId: { type: String, required: true }
+};
+/** No body: whatever isolates it has to come from the library. */
+class Unaware extends base_model_1.BaseModel {
+}
+/** Same, in a collection that mixes the shared tier with each tenant's own additions. */
+class Mixed extends base_model_1.BaseModel {
+}
+/** Same, exempted on purpose - as a collection written by event listeners must be. */
+class Exempt extends base_model_1.BaseModel {
+}
+const unaware = (0, mongo_utils_1.createModel)({
+    name: 'TenancyUnaware',
+    modelName: 'TenancyUnaware',
+    collection: 'tenancyUnaware',
+    classDef: Unaware,
+    modelParams: {},
+    schema
+}, true);
+const mixed = (0, mongo_utils_1.createModel)({
+    name: 'TenancyMixed',
+    modelName: 'TenancyMixed',
+    collection: 'tenancyMixed',
+    classDef: Mixed,
+    modelParams: { tenancy: enums_1.TenancyMode.shared },
+    schema
+}, true);
+const exempt = (0, mongo_utils_1.createModel)({
+    name: 'TenancyExempt',
+    modelName: 'TenancyExempt',
+    collection: 'tenancyExempt',
+    classDef: Exempt,
+    modelParams: { tenancy: enums_1.TenancyMode.none },
+    schema
+}, true);
+const owner = { user: { id: 'u1' }, tenantId: 'tenant-a' };
+const outsider = { user: { id: 'u2' }, tenantId: 'tenant-b' };
+const system = { user: { id: 'u3' }, tenantId: 'tenant-a', systemTier: true };
+describe('a model that overrides nothing is scoped anyway', () => {
+    beforeEach(() => { constants_1.APP.tenancy = provider; });
+    afterEach(() => { delete constants_1.APP.tenancy; });
+    it('stamps the owner on create, ignoring what the payload asked for', () => __awaiter(void 0, void 0, void 0, function* () {
+        const doc = yield unaware.create({ code: 'A', tenantId: 'tenant-b' }, owner);
+        expect(doc.tenantId).toBe('tenant-a');
+    }));
+    it('does not resolve another tenant document by id', () => __awaiter(void 0, void 0, void 0, function* () {
+        const doc = yield unaware.create({ code: 'A' }, owner);
+        expect(yield unaware.get(doc.id, outsider)).toBeNull();
+        expect(yield unaware.get(doc.id, owner)).not.toBeNull();
+    }));
+    it('keeps another tenant out of list, count and findOne', () => __awaiter(void 0, void 0, void 0, function* () {
+        yield unaware.create({ code: 'A' }, owner);
+        expect(yield unaware.list({}, {}, {}, outsider)).toHaveLength(0);
+        expect(yield unaware.count({}, outsider)).toBe(0);
+        expect(yield unaware.findOne({ code: 'A' }, outsider)).toBeNull();
+        expect(yield unaware.list({}, {}, {}, owner)).toHaveLength(1);
+    }));
+    it('refuses to delete another tenant document', () => __awaiter(void 0, void 0, void 0, function* () {
+        const doc = yield unaware.create({ code: 'A' }, owner);
+        yield expect(unaware.remove(doc.id, outsider)).rejects.toBeDefined();
+        expect(yield unaware.mgModel.collection.countDocuments({})).toBe(1);
+    }));
+    it('refuses to update another tenant document', () => __awaiter(void 0, void 0, void 0, function* () {
+        const doc = yield unaware.create({ code: 'A' }, owner);
+        yield expect(unaware.update(doc.id, { code: 'B' }, outsider)).rejects.toBeDefined();
+    }));
+    it('will not let an update re-home a document into another tenant', () => __awaiter(void 0, void 0, void 0, function* () {
+        const doc = yield unaware.create({ code: 'A' }, owner);
+        const updated = yield unaware.update(doc.id, { code: 'B', tenantId: 'tenant-b' }, owner);
+        expect(updated.tenantId).toBe('tenant-a');
+    }));
+});
+describe('a shared collection reads across tiers and writes within one', () => {
+    beforeEach(() => { constants_1.APP.tenancy = provider; });
+    afterEach(() => { delete constants_1.APP.tenancy; });
+    it('shows a tenant both the shared documents and its own', () => __awaiter(void 0, void 0, void 0, function* () {
+        yield mixed.create({ code: 'SYS', tenantId: SHARED }, system);
+        yield mixed.create({ code: 'OWN' }, owner);
+        const seen = yield mixed.list({}, {}, {}, owner);
+        expect(seen.map(d => d.code).sort()).toEqual(['OWN', 'SYS']);
+    }));
+    it('hides another tenant additions while still showing the shared ones', () => __awaiter(void 0, void 0, void 0, function* () {
+        yield mixed.mgModel.collection.insertOne({ code: 'SYS', tenantId: SHARED });
+        yield mixed.create({ code: 'OWN' }, owner);
+        const seen = yield mixed.list({}, {}, {}, outsider);
+        expect(seen.map(d => d.code)).toEqual(['SYS']);
+    }));
+    it('lets the system tier create a shared document', () => __awaiter(void 0, void 0, void 0, function* () {
+        const doc = yield mixed.create({ code: 'SYS', tenantId: SHARED }, system);
+        expect(doc.tenantId).toBe(SHARED);
+    }));
+    it('refuses a shared document to a tenant caller, rather than quietly downgrading it', () => __awaiter(void 0, void 0, void 0, function* () {
+        yield expect(mixed.create({ code: 'SYS', tenantId: SHARED }, owner)).rejects.toBeDefined();
+    }));
+    // The one a filter alone cannot express: the shared document IS readable by this caller,
+    // so scoping the read is not enough to stop the write.
+    it('refuses a tenant caller the update and the removal of a shared document', () => __awaiter(void 0, void 0, void 0, function* () {
+        const inserted = yield mixed.mgModel.collection.insertOne({ code: 'SYS', tenantId: SHARED });
+        const id = inserted.insertedId.toString();
+        yield expect(mixed.update(id, { code: 'HACKED' }, owner)).rejects.toBeDefined();
+        yield expect(mixed.remove(id, owner)).rejects.toBeDefined();
+    }));
+    it('lets the system tier update a shared document', () => __awaiter(void 0, void 0, void 0, function* () {
+        const inserted = yield mixed.mgModel.collection.insertOne({ code: 'SYS', tenantId: SHARED });
+        const updated = yield mixed.update(inserted.insertedId.toString(), { code: 'FIXED' }, system);
+        expect(updated.code).toBe('FIXED');
+    }));
+});
+describe('subscription payloads are scoped too', () => {
+    beforeEach(() => { constants_1.APP.tenancy = provider; });
+    afterEach(() => { delete constants_1.APP.tenancy; });
+    // T58: both hooks defaulted to "any authenticated user", and nothing in the project
+    // overrode them - so an event carried a document to every subscriber on the channel.
+    it('withholds another tenant document from a subscriber', () => __awaiter(void 0, void 0, void 0, function* () {
+        const doc = { code: 'A', tenantId: 'tenant-a' };
+        expect(yield unaware.checkContextPermission(doc, owner)).not.toBeNull();
+        expect(yield unaware.checkContextPermission(doc, outsider)).toBeNull();
+    }));
+    it('delivers a shared document to every tenant, and a private one to its owner alone', () => __awaiter(void 0, void 0, void 0, function* () {
+        expect(yield mixed.checkContextPermission({ code: 'S', tenantId: SHARED }, outsider)).not.toBeNull();
+        expect(yield mixed.checkContextPermission({ code: 'P', tenantId: 'tenant-a' }, outsider)).toBeNull();
+    }));
+    it('turns away a channel subscriber from another tenant', () => __awaiter(void 0, void 0, void 0, function* () {
+        expect(yield unaware.checkChannelSubscriber({ tenantId: 'tenant-a' }, owner)).toBe(true);
+        expect(yield unaware.checkChannelSubscriber({ tenantId: 'tenant-a' }, outsider)).toBe(false);
+    }));
+});
+describe('an exempt model is left alone', () => {
+    beforeEach(() => { constants_1.APP.tenancy = provider; });
+    afterEach(() => { delete constants_1.APP.tenancy; });
+    // Written by event listeners, which run with no user in context: scoping them
+    // automatically would break the very cascade they exist to perform.
+    it('neither stamps nor filters', () => __awaiter(void 0, void 0, void 0, function* () {
+        yield exempt.create({ code: 'A', tenantId: 'tenant-b' }, owner);
+        expect(yield exempt.list({}, {}, {}, outsider)).toHaveLength(1);
+        expect(yield exempt.list({}, {}, {}, {})).toHaveLength(1);
+    }));
+});
+describe('with no provider registered nothing is scoped at all', () => {
+    // The library is used by projects that have no notion of a tenant. For them every
+    // assertion above must NOT hold, or upgrading would silently empty their queries.
+    it('behaves as it did before tenancy existed', () => __awaiter(void 0, void 0, void 0, function* () {
+        expect(constants_1.APP.tenancy).toBeUndefined();
+        const doc = yield unaware.create({ code: 'A', tenantId: 'tenant-b' }, owner);
+        expect(doc.tenantId).toBe('tenant-b');
+        expect(yield unaware.list({}, {}, {}, outsider)).toHaveLength(1);
+        expect(yield unaware.get(doc.id, outsider)).not.toBeNull();
+    }));
+});

package/build/common/base/audit.d.ts

@@ -0,0 +1,55 @@
+/*********************************************************************************************
+ *                                                                                           *
+ * AUDIT - who created a document and when, who last changed it and when.                    *
+ *                                                                                           *
+ * Written by `BaseModel` rather than by every model, for the same reason tenancy is: a      *
+ * rule each author has to remember is a rule that gets forgotten, and forgetting this one   *
+ * is SILENT - the document is simply stored without a trace of who made it.                 *
+ *                                                                                           *
+ * That is not hypothetical. Before this existed, some sixty assignments were spread over    *
+ * twenty-one models in four spellings of the same line, two of them commented out, and one  *
+ * model wrote fields its schema never declared - so mongoose dropped them and the audit it  *
+ * appeared to keep was never kept at all.                                                   *
+ *                                                                                           *
+ * ONLY WHAT THE SCHEMA DECLARES                                                             *
+ *                                                                                           *
+ * A field is stamped only if the model's schema has it. That keeps the change INERT for     *
+ * every consumer that never asked for an audit - nothing appears in collections that did    *
+ * not declare it - which is the same property that made tenancy safe to invert. Wanting     *
+ * the audit is therefore an act: declare the field.                                         *
+ *                                                                                           *
+ * WHY NOT MONGOOSE `timestamps: true`                                                       *
+ *                                                                                           *
+ * Because it knows the WHEN and cannot know the WHO. `createdBy` needs the request context, *
+ * which mongoose has no access to, so the timestamps would come from the schema and the     *
+ * actors from here - two mechanisms, in two places, that drift apart the moment a write     *
+ * goes through only one of them. `updateArrayItem` and `addArrayItem` are exactly that      *
+ * write: they call `findOneAndUpdate` directly, so mongoose would refresh `updatedAt`       *
+ * while `updatedBy` kept naming whoever wrote last through `update()`. An audit that names  *
+ * the wrong author is worse than one that names nobody, because it is believed.             *
+ *                                                                                           *
+ *********************************************************************************************/
+import { NxContext, NxObject } from '../interfaces';
+/** The four fields this module knows how to keep, and the only ones it ever touches. */
+export declare const AUDIT_FIELDS: {
+    createdBy: string;
+    createdAt: string;
+    updatedBy: string;
+    updatedAt: string;
+};
+/**
+ * Stamps the audit fields a schema declares, and leaves every other field alone.
+ *
+ * On UPDATE the creation fields are dropped from the payload instead of being checked: a
+ * document is created once, so an update carrying `createdBy` is either noise or an attempt
+ * to rewrite history, and neither is worth honouring. Same reasoning as the tenant field.
+ *
+ * The user is read from the context and never from the payload - a client naming its own
+ * author would make the whole record worthless.
+ *
+ * @param item     the payload, mutated in place
+ * @param schema   the model's schema definition, used to know which fields exist
+ * @param context  the request context
+ * @param creating whether this is a creation or an update
+ */
+export declare function stampAudit(item: NxObject | undefined, schema: NxObject | undefined, context: NxContext | undefined, creating: boolean): void;

package/build/common/base/audit.js

@@ -0,0 +1,77 @@
+"use strict";
+/*********************************************************************************************
+ *                                                                                           *
+ * AUDIT - who created a document and when, who last changed it and when.                    *
+ *                                                                                           *
+ * Written by `BaseModel` rather than by every model, for the same reason tenancy is: a      *
+ * rule each author has to remember is a rule that gets forgotten, and forgetting this one   *
+ * is SILENT - the document is simply stored without a trace of who made it.                 *
+ *                                                                                           *
+ * That is not hypothetical. Before this existed, some sixty assignments were spread over    *
+ * twenty-one models in four spellings of the same line, two of them commented out, and one  *
+ * model wrote fields its schema never declared - so mongoose dropped them and the audit it  *
+ * appeared to keep was never kept at all.                                                   *
+ *                                                                                           *
+ * ONLY WHAT THE SCHEMA DECLARES                                                             *
+ *                                                                                           *
+ * A field is stamped only if the model's schema has it. That keeps the change INERT for     *
+ * every consumer that never asked for an audit - nothing appears in collections that did    *
+ * not declare it - which is the same property that made tenancy safe to invert. Wanting     *
+ * the audit is therefore an act: declare the field.                                         *
+ *                                                                                           *
+ * WHY NOT MONGOOSE `timestamps: true`                                                       *
+ *                                                                                           *
+ * Because it knows the WHEN and cannot know the WHO. `createdBy` needs the request context, *
+ * which mongoose has no access to, so the timestamps would come from the schema and the     *
+ * actors from here - two mechanisms, in two places, that drift apart the moment a write     *
+ * goes through only one of them. `updateArrayItem` and `addArrayItem` are exactly that      *
+ * write: they call `findOneAndUpdate` directly, so mongoose would refresh `updatedAt`       *
+ * while `updatedBy` kept naming whoever wrote last through `update()`. An audit that names  *
+ * the wrong author is worse than one that names nobody, because it is believed.             *
+ *                                                                                           *
+ *********************************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUDIT_FIELDS = void 0;
+exports.stampAudit = stampAudit;
+/** The four fields this module knows how to keep, and the only ones it ever touches. */
+exports.AUDIT_FIELDS = {
+    createdBy: 'createdBy',
+    createdAt: 'createdAt',
+    updatedBy: 'updatedBy',
+    updatedAt: 'updatedAt'
+};
+/**
+ * Stamps the audit fields a schema declares, and leaves every other field alone.
+ *
+ * On UPDATE the creation fields are dropped from the payload instead of being checked: a
+ * document is created once, so an update carrying `createdBy` is either noise or an attempt
+ * to rewrite history, and neither is worth honouring. Same reasoning as the tenant field.
+ *
+ * The user is read from the context and never from the payload - a client naming its own
+ * author would make the whole record worthless.
+ *
+ * @param item     the payload, mutated in place
+ * @param schema   the model's schema definition, used to know which fields exist
+ * @param context  the request context
+ * @param creating whether this is a creation or an update
+ */
+function stampAudit(item, schema, context, creating) {
+    var _a;
+    if (!item || !schema)
+        return;
+    const userId = (_a = context === null || context === void 0 ? void 0 : context.user) === null || _a === void 0 ? void 0 : _a.id;
+    const now = new Date();
+    if (creating) {
+        if (exports.AUDIT_FIELDS.createdAt in schema)
+            item[exports.AUDIT_FIELDS.createdAt] = now;
+        if (userId && exports.AUDIT_FIELDS.createdBy in schema)
+            item[exports.AUDIT_FIELDS.createdBy] = userId;
+        return;
+    }
+    delete item[exports.AUDIT_FIELDS.createdBy];
+    delete item[exports.AUDIT_FIELDS.createdAt];
+    if (exports.AUDIT_FIELDS.updatedAt in schema)
+        item[exports.AUDIT_FIELDS.updatedAt] = now;
+    if (userId && exports.AUDIT_FIELDS.updatedBy in schema)
+        item[exports.AUDIT_FIELDS.updatedBy] = userId;
+}

package/build/common/base/base.model.d.ts

@@ -29,6 +29,36 @@ export declare class BaseModel<TAttrs, TDoc extends BaseMongoDoc, TMongoModel ex
      * Get default parameters
      */
     get modelParams(): any;
+    /**
+     * The tenant scoping in force for THIS model, or `null` when there is none.
+     *
+     * Read on every call rather than resolved once in the constructor: an application
+     * registers its provider during boot, which may well happen after the models have been
+     * built, and a value captured too early would be `null` forever.
+     */
+    private get tenancy();
+    /**
+     * Constrains a filter to what this context may read. No-op without tenancy.
+     *
+     * The field is ALWAYS overwritten, never read: whatever the caller put there is a
+     * request, and honouring it would let a client name another tenant simply by adding a
+     * field to a query.
+     *
+     * @param filter  the filter, mutated in place
+     * @param context the request context
+     */
+    protected scopeFilter(filter: FilterParams, context: NxContext): FilterParams;
+    /**
+     * Asserts this context may write the document it just read. No-op without tenancy.
+     *
+     * Separate from the read filter, and it has to be: in a `shared` collection everybody
+     * reads the shared documents, so a scoped read says nothing about who may change them.
+     *
+     * @param doc     the stored document
+     * @param context the request context
+     * @throws when the write is not allowed
+     */
+    protected assertWritable(doc: NxObject | null, context: NxContext): void;
     /**
      *
      */
@@ -96,12 +126,21 @@ export declare class BaseModel<TAttrs, TDoc extends BaseMongoDoc, TMongoModel ex
      */
     get(id: string, context?: NxContext): Promise<TDoc | null>;
     /**
+     * Decides whether a subscriber may see THIS event payload.
+     *
+     * Being authenticated is not being entitled: with tenancy in force the payload is a
+     * document, and a document has an owner. Left at "any authenticated user" - as it was -
+     * a single channel carried every tenant's documents to every subscriber.
      *
      * @param {*} item
      * @param {*} context
      */
     checkContextPermission(item: any, context?: NxContext): any;
     /**
+     * Decides whether a subscriber may listen on a channel carrying THIS payload.
+     *
+     * Note the parameter is the payload itself, not an id, whatever its name suggests:
+     * `getChannelSubscriber` hands over `payload[payloadId]`.
      *
      * @param {*} context
      */
@@ -127,18 +166,37 @@ export declare class BaseModel<TAttrs, TDoc extends BaseMongoDoc, TMongoModel ex
      */
     findOneNative(params: FilterParams): Promise<mongoose.mongo.WithId<mongoose.mongo.BSON.Document> | null>;
     /**
+     * Scopes a read by id. Overriding this REPLACES the tenant scoping, it does not add to it.
      *
-     * @param id
+     * @param filter
      * @param context
-     * @returns
+     * @returns the filter the query must use - the RETURNED one, which is what `get` uses
      */
     beforeGet(filter: FilterParams, context: NxContext): Promise<FilterParams>;
     /**
+     * Stamps the owner and the audit on a new document.
+     *
+     * The value in the payload is a REQUEST, never an instruction: the provider decides what
+     * is actually written, and refuses rather than downgrade when the context is not
+     * entitled to the scope it asked for.
+     *
+     * Declared `async` because that refusal is a THROW, and the signature promises a promise:
+     * left synchronous, a caller reaching for `.catch()` would never see it, while one using
+     * `await` would - the same split contract that made `beforeGet` silently unsafe.
+     *
+     * Overriding this to set other fields is expected - denormalised data, defaults - but
+     * call `super`, or both the scoping and the audit silently stop happening for this model
+     * alone.
      *
      * @param {*} item
      */
     beforeCreate(item: TAttrs, context: NxContext): Promise<TAttrs>;
     /**
+     * Keeps an update from re-homing a document into another tenant, and stamps the audit.
+     *
+     * The owner is dropped from the payload rather than validated: an update never has a
+     * legitimate reason to move a document across tenants, so there is nothing to allow. The
+     * creation fields go the same way, for the same reason - a document is created once.
      *
      * @param {*} item
      */
@@ -149,6 +207,12 @@ export declare class BaseModel<TAttrs, TDoc extends BaseMongoDoc, TMongoModel ex
      */
     beforeCopy(item: TAttrs, context: NxContext): Promise<TAttrs>;
     /**
+     * Asserts the caller may delete this document, BEFORE it is deleted.
+     *
+     * `remove` deletes by `_id` with no filter whatsoever, and `bulkRemove` is a loop over
+     * it: without this check any caller deletes another tenant's documents knowing only an
+     * id. The document is re-read unscoped on purpose - the point is to judge its real
+     * owner, and a scoped read would hide the very case being guarded against.
      *
      * @param {*} id
      */
@@ -179,6 +243,7 @@ export declare class BaseModel<TAttrs, TDoc extends BaseMongoDoc, TMongoModel ex
      */
     manageFilterArrayParams(params: FilterParams): void;
     /**
+     * Scopes list / count / findOne / aggregate - the bulk of the read surface.
      *
      * @param {*} params
      * @param {*} context

package/build/common/base/base.model.js

@@ -30,6 +30,8 @@ const utils_1 = require("../utils");
 const constants_1 = require("../constants");
 const enums_1 = require("../enums");
 const errors_1 = require("../errors");
+const tenancy_1 = require("./tenancy");
+const audit_1 = require("./audit");
 const mongo_utils_1 = require("./mongo-utils");
 class BaseModel extends events_1.EventEmitter {
     constructor({ name, model, params, logger }) {
@@ -73,6 +75,50 @@ class BaseModel extends events_1.EventEmitter {
             return null;
         return (0, utils_1.clone)(this.defaultParams);
     }
+    /**
+     * The tenant scoping in force for THIS model, or `null` when there is none.
+     *
+     * Read on every call rather than resolved once in the constructor: an application
+     * registers its provider during boot, which may well happen after the models have been
+     * built, and a value captured too early would be `null` forever.
+     */
+    get tenancy() {
+        var _a;
+        return (0, tenancy_1.resolveTenancy)(constants_1.APP.tenancy, this.schema, (_a = this.defaultParams) === null || _a === void 0 ? void 0 : _a.tenancy);
+    }
+    /**
+     * Constrains a filter to what this context may read. No-op without tenancy.
+     *
+     * The field is ALWAYS overwritten, never read: whatever the caller put there is a
+     * request, and honouring it would let a client name another tenant simply by adding a
+     * field to a query.
+     *
+     * @param filter  the filter, mutated in place
+     * @param context the request context
+     */
+    scopeFilter(filter, context) {
+        const tenancy = this.tenancy;
+        if (tenancy && filter)
+            filter[tenancy.provider.field] = tenancy.provider.read(tenancy.mode, context);
+        return filter;
+    }
+    /**
+     * Asserts this context may write the document it just read. No-op without tenancy.
+     *
+     * Separate from the read filter, and it has to be: in a `shared` collection everybody
+     * reads the shared documents, so a scoped read says nothing about who may change them.
+     *
+     * @param doc     the stored document
+     * @param context the request context
+     * @throws when the write is not allowed
+     */
+    assertWritable(doc, context) {
+        const tenancy = this.tenancy;
+        if (!tenancy || !doc)
+            return;
+        if (!tenancy.provider.canWrite(tenancy.mode, doc[tenancy.provider.field], context))
+            throw new errors_1.ForbiddenError();
+    }
     /**
      *
      */
@@ -222,19 +268,41 @@ class BaseModel extends events_1.EventEmitter {
         });
     }
     /**
+     * Decides whether a subscriber may see THIS event payload.
+     *
+     * Being authenticated is not being entitled: with tenancy in force the payload is a
+     * document, and a document has an owner. Left at "any authenticated user" - as it was -
+     * a single channel carried every tenant's documents to every subscriber.
      *
      * @param {*} item
      * @param {*} context
      */
     checkContextPermission(item, context = {}) {
-        return Promise.resolve((context.user) ? item : null);
+        if (!context.user)
+            return Promise.resolve(null);
+        const tenancy = this.tenancy;
+        if (!tenancy || !item)
+            return Promise.resolve(item);
+        const allowed = tenancy.provider.read(tenancy.mode, context);
+        return Promise.resolve((0, tenancy_1.matchesTenancy)(item[tenancy.provider.field], allowed) ? item : null);
     }
     /**
+     * Decides whether a subscriber may listen on a channel carrying THIS payload.
+     *
+     * Note the parameter is the payload itself, not an id, whatever its name suggests:
+     * `getChannelSubscriber` hands over `payload[payloadId]`.
      *
      * @param {*} context
      */
     checkChannelSubscriber(payloadId, context = {}) {
-        return Promise.resolve(!!(context.user));
+        if (!context.user)
+            return Promise.resolve(false);
+        const tenancy = this.tenancy;
+        const payload = payloadId;
+        if (!tenancy || !payload || typeof payload !== 'object')
+            return Promise.resolve(true);
+        const allowed = tenancy.provider.read(tenancy.mode, context);
+        return Promise.resolve((0, tenancy_1.matchesTenancy)(payload[tenancy.provider.field], allowed));
     }
     /**
      * Get document using Moongose wrapper method
@@ -268,28 +336,63 @@ class BaseModel extends events_1.EventEmitter {
         return this.mgModel.collection.findOne(params);
     }
     /**
+     * Scopes a read by id. Overriding this REPLACES the tenant scoping, it does not add to it.
      *
-     * @param id
+     * @param filter
      * @param context
-     * @returns
+     * @returns the filter the query must use - the RETURNED one, which is what `get` uses
      */
     beforeGet(filter, context) {
         return __awaiter(this, void 0, void 0, function* () {
-            return filter;
+            return this.scopeFilter(filter, context);
         });
     }
     /**
+     * Stamps the owner and the audit on a new document.
+     *
+     * The value in the payload is a REQUEST, never an instruction: the provider decides what
+     * is actually written, and refuses rather than downgrade when the context is not
+     * entitled to the scope it asked for.
+     *
+     * Declared `async` because that refusal is a THROW, and the signature promises a promise:
+     * left synchronous, a caller reaching for `.catch()` would never see it, while one using
+     * `await` would - the same split contract that made `beforeGet` silently unsafe.
+     *
+     * Overriding this to set other fields is expected - denormalised data, defaults - but
+     * call `super`, or both the scoping and the audit silently stop happening for this model
+     * alone.
      *
      * @param {*} item
      */
     beforeCreate(item, context) {
-        return Promise.resolve(item);
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const tenancy = this.tenancy;
+            if (tenancy && item) {
+                const field = tenancy.provider.field;
+                item[field] = tenancy.provider.write(tenancy.mode, item[field], context);
+            }
+            if (((_a = this.defaultParams) === null || _a === void 0 ? void 0 : _a.audit) !== false)
+                (0, audit_1.stampAudit)(item, this.schema, context, true);
+            return item;
+        });
     }
     /**
+     * Keeps an update from re-homing a document into another tenant, and stamps the audit.
+     *
+     * The owner is dropped from the payload rather than validated: an update never has a
+     * legitimate reason to move a document across tenants, so there is nothing to allow. The
+     * creation fields go the same way, for the same reason - a document is created once.
      *
      * @param {*} item
      */
     beforeUpdate(item, context) {
+        var _a;
+        const tenancy = this.tenancy;
+        if (tenancy && item)
+            delete item[tenancy.provider.field];
+        if (((_a = this.defaultParams) === null || _a === void 0 ? void 0 : _a.audit) !== false)
+            (0, audit_1.stampAudit)(item, this.schema, context, false);
         return Promise.resolve(item);
     }
     /**
@@ -300,11 +403,23 @@ class BaseModel extends events_1.EventEmitter {
         return Promise.resolve(item);
     }
     /**
+     * Asserts the caller may delete this document, BEFORE it is deleted.
+     *
+     * `remove` deletes by `_id` with no filter whatsoever, and `bulkRemove` is a loop over
+     * it: without this check any caller deletes another tenant's documents knowing only an
+     * id. The document is re-read unscoped on purpose - the point is to judge its real
+     * owner, and a scoped read would hide the very case being guarded against.
      *
      * @param {*} id
      */
     beforeRemove(id, context) {
-        return Promise.resolve(id);
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.tenancy && id) {
+                const doc = yield this.mgModel.findOne({ _id: (0, mongo_utils_1.toObjectId)(id) });
+                this.assertWritable(doc, context);
+            }
+            return id;
+        });
     }
     /**
      *
@@ -348,6 +463,7 @@ class BaseModel extends events_1.EventEmitter {
         }
     }
     /**
+     * Scopes list / count / findOne / aggregate - the bulk of the read surface.
      *
      * @param {*} params
      * @param {*} context
@@ -357,6 +473,7 @@ class BaseModel extends events_1.EventEmitter {
             var _a;
             if (!params)
                 params = {};
+            this.scopeFilter(params, context);
             this.manageFilterArrayParams(params);
             (_a = params.rangeDate) !== null && _a !== void 0 ? _a : (params.rangeDate = {});
             let and = [];
@@ -472,6 +589,9 @@ class BaseModel extends events_1.EventEmitter {
                 const itemDoc = yield this.get(id, context);
                 if (!itemDoc)
                     throw new errors_1.AppError('messages.notFound');
+                // A scoped READ is not a permission to WRITE: in a shared collection the document
+                // just read may well be one everybody sees and only the application tier may change.
+                this.assertWritable(itemDoc, context);
                 let toApply = item;
                 // complete merge with the freshly read document
                 if (mergeItem) {

package/build/common/base/mongo.types.d.ts

@@ -1,4 +1,5 @@
 import { NxObject } from '../interfaces';
+import { TenancyMode } from '../enums';
 export type ModelDef<TDoc, TMongoModel, TNxModel> = {
     classDef: new (params: ModelData<TDoc, TMongoModel>) => TNxModel;
     name: string;
@@ -18,4 +19,20 @@ export type ModelData<TDoc, TMongoModel> = {
 export type ModelDefParams = {
     sort?: NxObject;
     CRUDEvents?: boolean;
+    /**
+     * How this collection relates to tenants.
+     *
+     * Omitted, a schema declaring the tenant field is scoped to ONE tenant: the scoping is
+     * opt-OUT, so silence means isolated. Say `none` to exempt a collection, and say WHY
+     * next to it - an unexplained exemption cannot be told apart from an oversight.
+     */
+    tenancy?: TenancyMode;
+    /**
+     * Whether `createdBy`/`createdAt`/`updatedBy`/`updatedAt` are kept automatically.
+     *
+     * Omitted, they are - but only for the fields the schema actually declares, so a model
+     * that never wanted an audit gets none either way. Set `false` for a collection that
+     * declares the fields and fills them itself, which today is nothing.
+     */
+    audit?: boolean;
 };

package/build/common/base/tenancy.d.ts

@@ -0,0 +1,101 @@
+/*********************************************************************************************
+ *                                                                                           *
+ * TENANCY - the contract that lets `BaseModel` scope by tenant WITHOUT knowing what a       *
+ * tenant is.                                                                                *
+ *                                                                                           *
+ * Isolation used to be opt-IN: `BaseModel` scoped nothing, so a model owning a tenant       *
+ * field was isolated only for as long as somebody remembered to override five hooks in      *
+ * every single class. Forgetting one is silent - the collection simply answers every        *
+ * tenant - and it is a mistake that has already been made three times over.                 *
+ *                                                                                           *
+ * Here it is opt-OUT: a model whose schema declares the tenant field is scoped by           *
+ * default, and a model that must NOT be scoped has to say so.                               *
+ *                                                                                           *
+ * WHY A PROVIDER, AND NOT THE RULES THEMSELVES                                              *
+ *                                                                                           *
+ * "Which tenant is this request" is an application question: it depends on roles, on        *
+ * memberships, on grants - none of which this library knows, nor should. So the library     *
+ * asks, and the application answers by registering a provider on `APP.tenancy`.             *
+ *                                                                                           *
+ * IMPORTANT: with NO provider registered, every model behaves exactly as it did before      *
+ * this file existed. The scoping is inert until an application opts into it, which is       *
+ * what makes the change safe for consumers that know nothing about tenants.                 *
+ *                                                                                           *
+ *********************************************************************************************/
+import { NxContext, NxObject } from '../interfaces';
+import { TenancyMode } from '../enums';
+/**
+ * What the application must answer for the library to scope on its behalf.
+ *
+ * Every method takes the mode, so one provider serves every model: the rules of a `shared`
+ * collection differ from those of an `own` one, and the difference belongs to the
+ * application, not to a second provider.
+ */
+export interface TenancyProvider {
+    /** Schema field carrying the owner. */
+    field: string;
+    /**
+     * The value a READ must be constrained to - a plain id for `own`, typically an `$in`
+     * over the tenant and the shared marker for `shared`.
+     *
+     * @param mode    the model's declared mode
+     * @param context the request context
+     * @returns whatever mongo should match the field against
+     */
+    read(mode: TenancyMode, context: NxContext): unknown;
+    /**
+     * The value a NEW document must carry, and the place where a write is authorised.
+     *
+     * `requested` is whatever the payload carried under the tenant field: it is a REQUEST and
+     * never an instruction - honour it only for a context entitled to it, and refuse
+     * otherwise rather than silently downgrading, which would let a client discover the rule
+     * by trial.
+     *
+     * @param mode      the model's declared mode
+     * @param requested the value found in the payload, when any
+     * @param context   the request context
+     * @returns the value to stamp on the document
+     * @throws when the context may not write the requested scope
+     */
+    write(mode: TenancyMode, requested: unknown, context: NxContext): unknown;
+    /**
+     * Whether an EXISTING document may be modified or deleted by this context.
+     *
+     * Separate from `read` on purpose: in a `shared` collection everybody reads the shared
+     * documents and only the application tier writes them, so a filter alone - which is a
+     * read - cannot express the rule.
+     *
+     * @param mode    the model's declared mode
+     * @param current the value the stored document carries
+     * @param context the request context
+     */
+    canWrite(mode: TenancyMode, current: unknown, context: NxContext): boolean;
+}
+/**
+ * Reads the tenancy in force for a model, or `null` when there is none.
+ *
+ * Three conditions, all necessary: an application must have registered a provider, the
+ * model must not have opted out, and the schema must actually declare the field - a model
+ * without it has no owner to scope by.
+ *
+ * @param provider the registered provider, when any
+ * @param schema   the model's mongoose schema definition
+ * @param declared the mode declared in `ModelDefParams`, when any
+ */
+export declare function resolveTenancy(provider: TenancyProvider | undefined, schema: NxObject | undefined, declared?: TenancyMode): {
+    provider: TenancyProvider;
+    mode: TenancyMode;
+} | null;
+/**
+ * Whether a document's owner satisfies what a read allows.
+ *
+ * The allowed value is whatever `TenancyProvider.read` returned, so it is either a plain
+ * value or a mongo operator. Only `$in` is understood, and deliberately so: this is used
+ * where no query runs - filtering an event payload in memory - and quietly accepting an
+ * operator it cannot evaluate would let a document through unchecked. Anything else is
+ * refused, which fails closed.
+ *
+ * @param current the value carried by the document
+ * @param allowed what `read` returned for this context
+ */
+export declare function matchesTenancy(current: unknown, allowed: unknown): boolean;

package/build/common/base/tenancy.js

@@ -0,0 +1,66 @@
+"use strict";
+/*********************************************************************************************
+ *                                                                                           *
+ * TENANCY - the contract that lets `BaseModel` scope by tenant WITHOUT knowing what a       *
+ * tenant is.                                                                                *
+ *                                                                                           *
+ * Isolation used to be opt-IN: `BaseModel` scoped nothing, so a model owning a tenant       *
+ * field was isolated only for as long as somebody remembered to override five hooks in      *
+ * every single class. Forgetting one is silent - the collection simply answers every        *
+ * tenant - and it is a mistake that has already been made three times over.                 *
+ *                                                                                           *
+ * Here it is opt-OUT: a model whose schema declares the tenant field is scoped by           *
+ * default, and a model that must NOT be scoped has to say so.                               *
+ *                                                                                           *
+ * WHY A PROVIDER, AND NOT THE RULES THEMSELVES                                              *
+ *                                                                                           *
+ * "Which tenant is this request" is an application question: it depends on roles, on        *
+ * memberships, on grants - none of which this library knows, nor should. So the library     *
+ * asks, and the application answers by registering a provider on `APP.tenancy`.             *
+ *                                                                                           *
+ * IMPORTANT: with NO provider registered, every model behaves exactly as it did before      *
+ * this file existed. The scoping is inert until an application opts into it, which is       *
+ * what makes the change safe for consumers that know nothing about tenants.                 *
+ *                                                                                           *
+ *********************************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTenancy = resolveTenancy;
+exports.matchesTenancy = matchesTenancy;
+const enums_1 = require("../enums");
+/**
+ * Reads the tenancy in force for a model, or `null` when there is none.
+ *
+ * Three conditions, all necessary: an application must have registered a provider, the
+ * model must not have opted out, and the schema must actually declare the field - a model
+ * without it has no owner to scope by.
+ *
+ * @param provider the registered provider, when any
+ * @param schema   the model's mongoose schema definition
+ * @param declared the mode declared in `ModelDefParams`, when any
+ */
+function resolveTenancy(provider, schema, declared) {
+    if (!provider || declared === enums_1.TenancyMode.none)
+        return null;
+    if (!schema || !(provider.field in schema))
+        return null;
+    return { provider, mode: declared !== null && declared !== void 0 ? declared : enums_1.TenancyMode.own };
+}
+/**
+ * Whether a document's owner satisfies what a read allows.
+ *
+ * The allowed value is whatever `TenancyProvider.read` returned, so it is either a plain
+ * value or a mongo operator. Only `$in` is understood, and deliberately so: this is used
+ * where no query runs - filtering an event payload in memory - and quietly accepting an
+ * operator it cannot evaluate would let a document through unchecked. Anything else is
+ * refused, which fails closed.
+ *
+ * @param current the value carried by the document
+ * @param allowed what `read` returned for this context
+ */
+function matchesTenancy(current, allowed) {
+    if (allowed && typeof allowed === 'object') {
+        const values = allowed.$in;
+        return Array.isArray(values) ? values.includes(current) : false;
+    }
+    return current === allowed;
+}

package/build/common/enums.d.ts

@@ -59,3 +59,20 @@ export declare enum AuthIssuer {
     USER = "user",
     DEVICE = "device"
 }
+/**
+ * How a collection relates to tenants. Declared per model in `ModelDefParams.tenancy`.
+ *
+ *  - `own`    every document belongs to exactly ONE tenant. The default whenever the schema
+ *             declares the tenant field, because it is the safe reading of a tenant field:
+ *             assuming otherwise is what leaks.
+ *  - `shared` the collection holds BOTH documents shared by all tenants and documents owned
+ *             by one. Reads span the two, writes do not: see `TenancyProvider.write`.
+ *  - `none`   the collection carries the field but is NOT request-scoped. Always a decision,
+ *             never a default - state the reason next to it, because an unexplained `none`
+ *             is indistinguishable from an oversight.
+ */
+export declare enum TenancyMode {
+    own = "own",
+    shared = "shared",
+    none = "none"
+}

package/build/common/enums.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AuthIssuer = exports.ValueType = exports.DatePeriod = exports.ModelCrudEventType = exports.AppStatus = exports.AppMode = void 0;
+exports.TenancyMode = exports.AuthIssuer = exports.ValueType = exports.DatePeriod = exports.ModelCrudEventType = exports.AppStatus = exports.AppMode = void 0;
 var AppMode;
 (function (AppMode) {
     AppMode["DEV"] = "development";
@@ -73,3 +73,21 @@ var AuthIssuer;
     AuthIssuer["USER"] = "user";
     AuthIssuer["DEVICE"] = "device";
 })(AuthIssuer || (exports.AuthIssuer = AuthIssuer = {}));
+/**
+ * How a collection relates to tenants. Declared per model in `ModelDefParams.tenancy`.
+ *
+ *  - `own`    every document belongs to exactly ONE tenant. The default whenever the schema
+ *             declares the tenant field, because it is the safe reading of a tenant field:
+ *             assuming otherwise is what leaks.
+ *  - `shared` the collection holds BOTH documents shared by all tenants and documents owned
+ *             by one. Reads span the two, writes do not: see `TenancyProvider.write`.
+ *  - `none`   the collection carries the field but is NOT request-scoped. Always a decision,
+ *             never a default - state the reason next to it, because an unexplained `none`
+ *             is indistinguishable from an oversight.
+ */
+var TenancyMode;
+(function (TenancyMode) {
+    TenancyMode["own"] = "own";
+    TenancyMode["shared"] = "shared";
+    TenancyMode["none"] = "none";
+})(TenancyMode || (exports.TenancyMode = TenancyMode = {}));

package/build/common/index.d.ts

@@ -6,5 +6,7 @@ export * from './interfaces';
 export * from './types';
 export * from './manager';
 export * from './utils';
+export * from './base/tenancy';
+export * from './base/audit';
 export * from './express';
 export * from './crypto';

package/build/common/index.js

@@ -22,6 +22,8 @@ __exportStar(require("./interfaces"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./manager"), exports);
 __exportStar(require("./utils"), exports);
+__exportStar(require("./base/tenancy"), exports);
+__exportStar(require("./base/audit"), exports);
 // export * from './models';
 __exportStar(require("./express"), exports);
 // export * from './nx-disk-storage';

package/build/common/types.d.ts

@@ -9,6 +9,7 @@ import { NxObject, NxTypeObject } from './interfaces';
 import { PubSubManager } from './manager/pubsub-manager';
 import { ShutdownManager } from './manager/shutdown-manager';
 import { CryptoManager } from './manager/crypto-manager';
+import { TenancyProvider } from './base/tenancy';
 export type NxDateRage = {
     from?: Date;
     to?: Date;
@@ -32,6 +33,14 @@ export type AppData = {
     cryptoMng?: CryptoManager;
     streams: ChangeStreamData[];
     config: AppConfig;
+    /**
+     * Tenant scoping, registered by the application at boot.
+     *
+     * Left unset - as every consumer that knows nothing about tenants leaves it - the models
+     * behave exactly as they did before tenancy existed: the scoping is inert until somebody
+     * opts into it.
+     */
+    tenancy?: TenancyProvider;
 };
 export type AppConfig = {
     endpoint: AppEndpoint;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextage/nx-frame-be",
-  "version": "1.0.45",
+  "version": "1.0.46",
   "description": "",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",