@nextage/era-lib 1.0.193 → 1.0.194

package/build/utils/tenant.d.ts

@@ -9,7 +9,7 @@
  *                                                                                           *
  *********************************************************************************************/
 import { BaseUser, NxContext, NxObject } from '@nextage/nx-frame-be';
-import { ScopedReadModel } from './tenant.interfaces';
+import { ExistenceCheckModel, ScopedReadModel } from './tenant.interfaces';
 /**
  * Resolves the organization a request operates on - ALWAYS exactly one.
  *
@@ -95,4 +95,73 @@ export declare function getTenant(user?: BaseUser): string;
  * @throws `AppError('messages.notFound')` when the document is out of scope
  */
 export declare function assertTenantScope(model: ScopedReadModel, id: string, context?: NxContext): Promise<string>;
+/**
+ * Answers whether the organization NAMED by a request actually exists (T49).
+ *
+ * {@link resolveTenant} answers one question - "may this user REACH the
+ * selection" - and for a cross-tenant role the answer is "any of them", so it
+ * hands the value back untouched. EXISTENCE was nobody's job: an `orgId` naming
+ * no organization, never created or since deleted, travelled through unchecked.
+ *
+ * On reads that costs nothing: the filter matches no document and the caller gets
+ * an empty list. It bites on WRITES, because {@link setTenant} also runs inside
+ * `beforeCreate`: the document is stored with a `tenantId` pointing nowhere,
+ * unreachable by every later query and invisible to any tenant-wide cascade,
+ * which keys off an `OrganizationRemoved` event that will never arrive for an
+ * organization that never existed.
+ *
+ * ### Where to call it
+ *
+ * In the REQUEST CONTEXT of the service - the one place `orgId` enters, crossed
+ * ONCE per request - and NOT inside `resolveTenant`. That helper is synchronous
+ * and `setTenant` calls it from `beforeCreate`/`beforeGet`/`updateFilters`, hooks
+ * that run on every single query: making it asynchronous would cost a database
+ * round trip per query, and a signature change rippling through every caller, to
+ * answer a question that only changes when the request does.
+ *
+ * ⚠️ A service whose `orgId` reaches it only through checked paths does NOT need
+ * this: auth-srv, for one, takes the organization from mutation ARGUMENTS and
+ * passes it to `assertOrgScope`, which re-reads the document and fails when it is
+ * missing - the check there would be dead code. Wire it where the selection
+ * enters raw, from a header or from connection params.
+ *
+ * ### Fail-closed, and mute
+ *
+ * A non-existent selection is refused with the very same `messages.forbidden` as
+ * an out-of-reach one: telling them apart would answer a question the caller is
+ * not entitled to ask - whether someone else's organization exists, or has been
+ * deleted.
+ *
+ * A malformed value is refused likewise and deliberately BEFORE the query: the
+ * selection is client-supplied, and handing an arbitrary string to mongoose would
+ * raise a CastError - a 500 where a denial belongs. Note that `toObjectId` does
+ * NOT throw on a bad value, it returns the string unchanged, so the guard cannot
+ * be left to it.
+ *
+ * NO selection means "the caller's own organization" (rule 1) and there is
+ * nothing to verify: the check is a no-op, so requests that simply do not select
+ * are unaffected.
+ *
+ * @param model the organization model, or any local projection standing in for it
+ * @param orgId the organization named by the request, when any
+ * @returns `true` when the selection is usable, `false` when it names nothing
+ */
+export declare function selectedOrgExists(model: ExistenceCheckModel, orgId?: string): Promise<boolean>;
+/**
+ * {@link selectedOrgExists} in throwing form, for GraphQL context builders.
+ *
+ * A rejected context aborts the whole operation, which is exactly what a refusal
+ * means here.
+ *
+ * ⚠️ An Express middleware may NOT be able to use this shape: if the service
+ * registers its error handler BEFORE the routes, the error never reaches it, and
+ * `AppError` carries its code in `extensions.code` rather than in `.status`, so
+ * the handler would answer 500 on an already-written response. There, call
+ * {@link selectedOrgExists} and write the refusal directly.
+ *
+ * @param model the organization model, or any local projection standing in for it
+ * @param orgId the organization named by the request, when any
+ * @throws `AppError('messages.forbidden')` when the selection names no organization
+ */
+export declare function assertSelectedOrgExists(model: ExistenceCheckModel, orgId?: string): Promise<void>;
 //# sourceMappingURL=tenant.d.ts.map

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

@@ -1 +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"}
+{"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;AAI/E,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAS,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;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CASpG;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,uBAAuB,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIvG"}

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

@@ -16,4 +16,19 @@ import { NxContext } from '@nextage/nx-frame-be';
 export interface ScopedReadModel {
     get(id: string, context: NxContext): Promise<unknown>;
 }
+/**
+ * A model of which only "does a document with this `_id` exist" is needed.
+ *
+ * Structural for the same reason as {@link ScopedReadModel}, and deliberately
+ * built on `mgModel.exists` rather than on `get`: the question is whether the
+ * document EXISTS AT ALL, so it must NOT go through `beforeGet` and the tenant
+ * scoping it applies - a scoped read would answer "no" for an organization that
+ * exists but the caller cannot reach, which is a different question with a
+ * different answer.
+ */
+export interface ExistenceCheckModel {
+    mgModel: {
+        exists(filter: Record<string, unknown>): Promise<unknown>;
+    };
+}
 //# sourceMappingURL=tenant.interfaces.d.ts.map

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

@@ -1 +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"}
+{"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;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE;QACP,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;KAC3D,CAAC;CACH"}

package/build/utils/tenant.js

@@ -14,7 +14,10 @@ exports.resolveTenant = resolveTenant;
 exports.setTenant = setTenant;
 exports.getTenant = getTenant;
 exports.assertTenantScope = assertTenantScope;
+exports.selectedOrgExists = selectedOrgExists;
+exports.assertSelectedOrgExists = assertSelectedOrgExists;
 const nx_frame_be_1 = require("@nextage/nx-frame-be");
+const mongo_utils_1 = require("@nextage/nx-frame-be/build/common/base/mongo-utils");
 const scope_1 = require("./scope");
 /**
  * Resolves the organization a request operates on - ALWAYS exactly one.
@@ -121,4 +124,82 @@ async function assertTenantScope(model, id, context = {}) {
         throw new nx_frame_be_1.AppError('messages.notFound');
     return id;
 }
+/**
+ * Answers whether the organization NAMED by a request actually exists (T49).
+ *
+ * {@link resolveTenant} answers one question - "may this user REACH the
+ * selection" - and for a cross-tenant role the answer is "any of them", so it
+ * hands the value back untouched. EXISTENCE was nobody's job: an `orgId` naming
+ * no organization, never created or since deleted, travelled through unchecked.
+ *
+ * On reads that costs nothing: the filter matches no document and the caller gets
+ * an empty list. It bites on WRITES, because {@link setTenant} also runs inside
+ * `beforeCreate`: the document is stored with a `tenantId` pointing nowhere,
+ * unreachable by every later query and invisible to any tenant-wide cascade,
+ * which keys off an `OrganizationRemoved` event that will never arrive for an
+ * organization that never existed.
+ *
+ * ### Where to call it
+ *
+ * In the REQUEST CONTEXT of the service - the one place `orgId` enters, crossed
+ * ONCE per request - and NOT inside `resolveTenant`. That helper is synchronous
+ * and `setTenant` calls it from `beforeCreate`/`beforeGet`/`updateFilters`, hooks
+ * that run on every single query: making it asynchronous would cost a database
+ * round trip per query, and a signature change rippling through every caller, to
+ * answer a question that only changes when the request does.
+ *
+ * ⚠️ A service whose `orgId` reaches it only through checked paths does NOT need
+ * this: auth-srv, for one, takes the organization from mutation ARGUMENTS and
+ * passes it to `assertOrgScope`, which re-reads the document and fails when it is
+ * missing - the check there would be dead code. Wire it where the selection
+ * enters raw, from a header or from connection params.
+ *
+ * ### Fail-closed, and mute
+ *
+ * A non-existent selection is refused with the very same `messages.forbidden` as
+ * an out-of-reach one: telling them apart would answer a question the caller is
+ * not entitled to ask - whether someone else's organization exists, or has been
+ * deleted.
+ *
+ * A malformed value is refused likewise and deliberately BEFORE the query: the
+ * selection is client-supplied, and handing an arbitrary string to mongoose would
+ * raise a CastError - a 500 where a denial belongs. Note that `toObjectId` does
+ * NOT throw on a bad value, it returns the string unchanged, so the guard cannot
+ * be left to it.
+ *
+ * NO selection means "the caller's own organization" (rule 1) and there is
+ * nothing to verify: the check is a no-op, so requests that simply do not select
+ * are unaffected.
+ *
+ * @param model the organization model, or any local projection standing in for it
+ * @param orgId the organization named by the request, when any
+ * @returns `true` when the selection is usable, `false` when it names nothing
+ */
+async function selectedOrgExists(model, orgId) {
+    if (!orgId)
+        return true;
+    if (!(0, mongo_utils_1.isValidObjectId)(orgId))
+        return false;
+    return !!await model.mgModel.exists({ _id: (0, mongo_utils_1.toObjectId)(orgId) });
+}
+/**
+ * {@link selectedOrgExists} in throwing form, for GraphQL context builders.
+ *
+ * A rejected context aborts the whole operation, which is exactly what a refusal
+ * means here.
+ *
+ * ⚠️ An Express middleware may NOT be able to use this shape: if the service
+ * registers its error handler BEFORE the routes, the error never reaches it, and
+ * `AppError` carries its code in `extensions.code` rather than in `.status`, so
+ * the handler would answer 500 on an already-written response. There, call
+ * {@link selectedOrgExists} and write the refusal directly.
+ *
+ * @param model the organization model, or any local projection standing in for it
+ * @param orgId the organization named by the request, when any
+ * @throws `AppError('messages.forbidden')` when the selection names no organization
+ */
+async function assertSelectedOrgExists(model, orgId) {
+    if (!await selectedOrgExists(model, orgId))
+        throw new nx_frame_be_1.AppError('messages.forbidden');
+}
 //# sourceMappingURL=tenant.js.map

package/build/utils/tenant.js.map

@@ -1 +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"}
+{"version":3,"file":"tenant.js","sourceRoot":"","sources":["../../src/utils/tenant.ts"],"names":[],"mappings":";AAAA;;;;;;;;;+FAS+F;;AA0C/F,sCAeC;AAcD,8BAGC;AAaD,8BAMC;AA0BD,8CAMC;AAqDD,8CASC;AAkBD,0DAIC;AA/MD,sDAA+E;AAC/E,oFAA6G;AAE7G,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;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACI,KAAK,UAAU,iBAAiB,CAAC,KAA0B,EAAE,KAAc;IAEhF,IAAI,CAAC,KAAK;QACR,OAAO,IAAI,CAAC;IAEd,IAAI,CAAC,IAAA,6BAAe,EAAC,KAAK,CAAC;QACzB,OAAO,KAAK,CAAC;IAEf,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,IAAA,wBAAU,EAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACI,KAAK,UAAU,uBAAuB,CAAC,KAA0B,EAAE,KAAc;IAEtF,IAAI,CAAC,MAAM,iBAAiB,CAAC,KAAK,EAAE,KAAK,CAAC;QACxC,MAAM,IAAI,sBAAQ,CAAC,oBAAoB,CAAC,CAAC;AAC7C,CAAC"}

package/package.json

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