@nextage/era-lib 1.0.190 → 1.0.192

package/build/utils/tenant.d.ts

@@ -0,0 +1,98 @@
+/*********************************************************************************************
+ *                                                                                           *
+ * Multi-tenancy helpers - single source of truth for how a request is scoped to a tenant.   *
+ *                                                                                           *
+ * Every rule about "which organization is this operation allowed to touch" lives here and   *
+ * nowhere else: the services (app-srv, auth-srv, ...) import these helpers, they never      *
+ * re-implement the scoping. See ADR-0005 section 4 (capability matrix) and section 5        *
+ * (tenant resolution).                                                                      *
+ *                                                                                           *
+ *********************************************************************************************/
+import { BaseUser, NxContext, NxObject } from '@nextage/nx-frame-be';
+import { ScopedReadModel } from './tenant.interfaces';
+/**
+ * Resolves the organization a request operates on - ALWAYS exactly one.
+ *
+ * The selection NEVER comes from the payload: it travels out of band (`X-Org-Id`
+ * header, or `orgId` in the WebSocket connection params) and lands on
+ * `NxContext.orgId`. Reading it from the body would let a client name any tenant
+ * simply by adding a field to a mutation input (T34).
+ *
+ * Resolution order (ADR-0005 section 5.1) - the first match wins:
+ *
+ *   1. no selection          -> the user's own organization, for EVERYONE
+ *   2. cross-tenant role     -> the selection, whichever it is
+ *   3. selection within reach-> the selection itself (membership or grant)
+ *   4. otherwise             -> throws (fail-closed: an unreachable selection is never
+ *                               silently downgraded to the user's own tenant)
+ *
+ * A cross-tenant role does NOT mean "sees every tenant at once": it means it may
+ * operate on ANY tenant, ONE at a time, upon selection. Without a selection it is
+ * scoped to its own organization exactly like everybody else - the provider one is
+ * an organization like the others and holds its own application data.
+ *
+ * It follows that the return type is a plain `string`: there is no unscoped outcome.
+ * A cross-tenant aggregation - a future dashboard - is a DIFFERENT query, built on
+ * `reachableOrgIds` in its own resolver, and never a relaxation of this helper.
+ *
+ * Built on `reachableOrgIds` on purpose: the set of organizations a selection may
+ * name is the same set a list may show. Two independent implementations would
+ * eventually disagree, and any disagreement is a leak.
+ *
+ * @param user  the authenticated user (`NxContext.user`)
+ * @param orgId the organization named by the request, when any
+ * @returns the tenant id to enforce
+ * @throws `AppError('messages.forbidden')` when the selection is out of reach
+ */
+export declare function resolveTenant(user?: BaseUser, orgId?: string): string;
+/**
+ * Forces `tenantId` on a payload or on a query filter, from the resolved organization.
+ *
+ * The field is ALWAYS overwritten, never read: whatever the client sent under that
+ * name is irrelevant, which is what makes the helper safe to call on user input.
+ * There is no way out of the scoping and no flag to opt out of it - that was exactly
+ * defect D2 of ADR-0005 section 5.1, a fail-open by default.
+ *
+ * @param item    the payload or filter, mutated in place
+ * @param context the request context (authenticated user + selected organization)
+ * @throws when no tenant can be resolved
+ */
+export declare function setTenant(item: NxObject, context?: NxContext): void;
+/**
+ * Returns the user's own tenant id, that is their membership organization.
+ *
+ * Membership is an invariant of exactly one entry (ADR-0005 section 3.1), so the
+ * first entry IS the organization; the array shape only exists to stay compatible
+ * with the shared application base.
+ *
+ * @param user the authenticated user
+ * @returns the tenant id
+ * @throws if the user has no organization
+ */
+export declare function getTenant(user?: BaseUser): string;
+/**
+ * Checks that `id` is reachable by the context user, ahead of a destructive write.
+ *
+ * Fills the gap of **T37**: `BaseModel.remove(id)` calls `beforeRemove` and then
+ * `findByIdAndDelete(id)`, applying neither `updateFilters` nor any `tenantId`
+ * constraint - and `bulkRemove(ids)` is nothing but `ids.map(remove)`. Without this
+ * check any user deletes documents belonging to OTHER organizations, knowing only
+ * their `_id`.
+ *
+ * The check reuses `model.get`, which goes through `beforeGet` and therefore already
+ * applies the tenant scoping: one single source of truth, no tenancy rule duplicated
+ * here. It follows that a cross-tenant role deletes in the organization it SELECTED,
+ * and in its own when it selected none - never across several at once, exactly as
+ * `resolveTenant` prescribes.
+ *
+ * **Fail-closed**: a missing or out-of-scope `id` raises an error, without telling
+ * the two cases apart (the existence of someone else's document is never confirmed).
+ *
+ * @param model   the model the removal happens on (`this` inside the hook)
+ * @param id      the document identifier
+ * @param context the request context, carrying the authenticated user
+ * @returns the same `id`, so it can be used directly inside `beforeRemove`
+ * @throws `AppError('messages.notFound')` when the document is out of scope
+ */
+export declare function assertTenantScope(model: ScopedReadModel, id: string, context?: NxContext): Promise<string>;
+//# sourceMappingURL=tenant.d.ts.map

package/build/utils/tenant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant.d.ts","sourceRoot":"","sources":["../../src/utils/tenant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;+FAS+F;AAE/F,OAAO,EAAY,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAG/E,OAAO,EAAE,eAAe,EAAE,MAA8B,qBAAqB,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAerE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,GAAE,SAAc,GAAG,IAAI,CAGvE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,MAAM,CAMjD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,SAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAMpH"}

package/build/utils/tenant.interfaces.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Tenancy types & interfaces.
+ *
+ * Kept separate from the tenancy logic in `tenant.ts` (house-style: types live in
+ * a dedicated `*.interfaces.ts`, never mixed with the logic that consumes them).
+ */
+import { NxContext } from '@nextage/nx-frame-be';
+/**
+ * A model of which only the read-by-`_id` is needed, already tenant-scoped by its
+ * own `beforeGet`.
+ *
+ * Deliberately **structural** and not `BaseModel<Attrs, Doc, Model>`: the library
+ * must not depend on the concrete model types of a single service, and any model
+ * able to read by `_id` satisfies the contract.
+ */
+export interface ScopedReadModel {
+    get(id: string, context: NxContext): Promise<unknown>;
+}
+//# sourceMappingURL=tenant.interfaces.d.ts.map

package/build/utils/tenant.interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant.interfaces.d.ts","sourceRoot":"","sources":["../../src/utils/tenant.interfaces.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACvD"}

package/build/utils/tenant.interfaces.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Tenancy types & interfaces.
+ *
+ * Kept separate from the tenancy logic in `tenant.ts` (house-style: types live in
+ * a dedicated `*.interfaces.ts`, never mixed with the logic that consumes them).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=tenant.interfaces.js.map

package/build/utils/tenant.interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant.interfaces.js","sourceRoot":"","sources":["../../src/utils/tenant.interfaces.ts"],"names":[],"mappings":";AAAA;;;;;GAKG"}

package/build/utils/tenant.js

@@ -0,0 +1,124 @@
+"use strict";
+/*********************************************************************************************
+ *                                                                                           *
+ * Multi-tenancy helpers - single source of truth for how a request is scoped to a tenant.   *
+ *                                                                                           *
+ * Every rule about "which organization is this operation allowed to touch" lives here and   *
+ * nowhere else: the services (app-srv, auth-srv, ...) import these helpers, they never      *
+ * re-implement the scoping. See ADR-0005 section 4 (capability matrix) and section 5        *
+ * (tenant resolution).                                                                      *
+ *                                                                                           *
+ *********************************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTenant = resolveTenant;
+exports.setTenant = setTenant;
+exports.getTenant = getTenant;
+exports.assertTenantScope = assertTenantScope;
+const nx_frame_be_1 = require("@nextage/nx-frame-be");
+const scope_1 = require("./scope");
+/**
+ * Resolves the organization a request operates on - ALWAYS exactly one.
+ *
+ * The selection NEVER comes from the payload: it travels out of band (`X-Org-Id`
+ * header, or `orgId` in the WebSocket connection params) and lands on
+ * `NxContext.orgId`. Reading it from the body would let a client name any tenant
+ * simply by adding a field to a mutation input (T34).
+ *
+ * Resolution order (ADR-0005 section 5.1) - the first match wins:
+ *
+ *   1. no selection          -> the user's own organization, for EVERYONE
+ *   2. cross-tenant role     -> the selection, whichever it is
+ *   3. selection within reach-> the selection itself (membership or grant)
+ *   4. otherwise             -> throws (fail-closed: an unreachable selection is never
+ *                               silently downgraded to the user's own tenant)
+ *
+ * A cross-tenant role does NOT mean "sees every tenant at once": it means it may
+ * operate on ANY tenant, ONE at a time, upon selection. Without a selection it is
+ * scoped to its own organization exactly like everybody else - the provider one is
+ * an organization like the others and holds its own application data.
+ *
+ * It follows that the return type is a plain `string`: there is no unscoped outcome.
+ * A cross-tenant aggregation - a future dashboard - is a DIFFERENT query, built on
+ * `reachableOrgIds` in its own resolver, and never a relaxation of this helper.
+ *
+ * Built on `reachableOrgIds` on purpose: the set of organizations a selection may
+ * name is the same set a list may show. Two independent implementations would
+ * eventually disagree, and any disagreement is a leak.
+ *
+ * @param user  the authenticated user (`NxContext.user`)
+ * @param orgId the organization named by the request, when any
+ * @returns the tenant id to enforce
+ * @throws `AppError('messages.forbidden')` when the selection is out of reach
+ */
+function resolveTenant(user, orgId) {
+    if (!orgId)
+        return getTenant(user);
+    const reachable = (0, scope_1.reachableOrgIds)(user);
+    // `undefined` means no constraint on WHICH organization may be named.
+    if (!reachable)
+        return orgId;
+    if (!reachable.includes(orgId))
+        throw new nx_frame_be_1.AppError('messages.forbidden');
+    return orgId;
+}
+/**
+ * Forces `tenantId` on a payload or on a query filter, from the resolved organization.
+ *
+ * The field is ALWAYS overwritten, never read: whatever the client sent under that
+ * name is irrelevant, which is what makes the helper safe to call on user input.
+ * There is no way out of the scoping and no flag to opt out of it - that was exactly
+ * defect D2 of ADR-0005 section 5.1, a fail-open by default.
+ *
+ * @param item    the payload or filter, mutated in place
+ * @param context the request context (authenticated user + selected organization)
+ * @throws when no tenant can be resolved
+ */
+function setTenant(item, context = {}) {
+    item.tenantId = resolveTenant(context.user, context.orgId);
+}
+/**
+ * Returns the user's own tenant id, that is their membership organization.
+ *
+ * Membership is an invariant of exactly one entry (ADR-0005 section 3.1), so the
+ * first entry IS the organization; the array shape only exists to stay compatible
+ * with the shared application base.
+ *
+ * @param user the authenticated user
+ * @returns the tenant id
+ * @throws if the user has no organization
+ */
+function getTenant(user) {
+    if (!user?.organizations?.length)
+        throw new Error('Cannot proceed: organization not set');
+    return String(user.organizations[0].id);
+}
+/**
+ * Checks that `id` is reachable by the context user, ahead of a destructive write.
+ *
+ * Fills the gap of **T37**: `BaseModel.remove(id)` calls `beforeRemove` and then
+ * `findByIdAndDelete(id)`, applying neither `updateFilters` nor any `tenantId`
+ * constraint - and `bulkRemove(ids)` is nothing but `ids.map(remove)`. Without this
+ * check any user deletes documents belonging to OTHER organizations, knowing only
+ * their `_id`.
+ *
+ * The check reuses `model.get`, which goes through `beforeGet` and therefore already
+ * applies the tenant scoping: one single source of truth, no tenancy rule duplicated
+ * here. It follows that a cross-tenant role deletes in the organization it SELECTED,
+ * and in its own when it selected none - never across several at once, exactly as
+ * `resolveTenant` prescribes.
+ *
+ * **Fail-closed**: a missing or out-of-scope `id` raises an error, without telling
+ * the two cases apart (the existence of someone else's document is never confirmed).
+ *
+ * @param model   the model the removal happens on (`this` inside the hook)
+ * @param id      the document identifier
+ * @param context the request context, carrying the authenticated user
+ * @returns the same `id`, so it can be used directly inside `beforeRemove`
+ * @throws `AppError('messages.notFound')` when the document is out of scope
+ */
+async function assertTenantScope(model, id, context = {}) {
+    if (!await model.get(id, context))
+        throw new nx_frame_be_1.AppError('messages.notFound');
+    return id;
+}
+//# sourceMappingURL=tenant.js.map

package/build/utils/tenant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant.js","sourceRoot":"","sources":["../../src/utils/tenant.ts"],"names":[],"mappings":";AAAA;;;;;;;;;+FAS+F;;AAyC/F,sCAeC;AAcD,8BAGC;AAaD,8BAMC;AA0BD,8CAMC;AA1HD,sDAA+E;AAE/E,mCAAkE;AAGlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,SAAgB,aAAa,CAAC,IAAe,EAAE,KAAc;IAE3D,IAAI,CAAC,KAAK;QACR,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;IAEzB,MAAM,SAAS,GAAG,IAAA,uBAAe,EAAC,IAAI,CAAC,CAAC;IAExC,sEAAsE;IACtE,IAAI,CAAC,SAAS;QACZ,OAAO,KAAK,CAAC;IAEf,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC;QAC5B,MAAM,IAAI,sBAAQ,CAAC,oBAAoB,CAAC,CAAC;IAE3C,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,SAAS,CAAC,IAAc,EAAE,UAAqB,EAAE;IAE/D,IAAI,CAAC,QAAQ,GAAG,aAAa,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,SAAS,CAAC,IAAe;IAEvC,IAAI,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM;QAC9B,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAE1D,OAAO,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACI,KAAK,UAAU,iBAAiB,CAAC,KAAsB,EAAE,EAAU,EAAE,UAAqB,EAAE;IAEjG,IAAI,CAAC,MAAM,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC;QAC/B,MAAM,IAAI,sBAAQ,CAAC,mBAAmB,CAAC,CAAC;IAE1C,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextage/era-lib",
-  "version": "1.0.190",
+  "version": "1.0.192",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
   "files": [