@nextage/era-lib 1.0.191 → 1.0.193

package/build/utils/claims.d.ts

@@ -0,0 +1,42 @@
+/*********************************************************************************************
+ *                                                                                           *
+ * Identity claims - the SINGLE definition of what identity travels inside an access token.  *
+ *                                                                                           *
+ * Two operations, kept together on purpose because they MUST stay each other's inverse:     *
+ *                                                                                           *
+ *   buildAuthClaims     - auth-srv, when signing a token (login and refresh);               *
+ *   identityFromClaims  - every resource service, when rebuilding the caller per request.   *
+ *                                                                                           *
+ * They used to be four hand-written literals across two services. A drift between them is   *
+ * not a cosmetic bug: a claim that is written but not read means the authorization data      *
+ * silently disappears, and the checks that depend on it fail OPEN or CLOSED at random.       *
+ *                                                                                           *
+ * NOTE: resource services do NOT re-read the user from the database - they trust these       *
+ * claims (ADR-0005 section 5.1). Revoking a grant therefore takes effect only after the      *
+ * token is refreshed: a declared property, bounded by the access-token TTL.                  *
+ *                                                                                           *
+ *********************************************************************************************/
+import { BaseUser } from '@nextage/nx-frame-be';
+import { AuthClaims, ClaimIdentity } from './claims.interfaces';
+/**
+ * Builds the identity claims to embed in an access token.
+ *
+ * `grn` is omitted entirely when the user holds no grant, so the common case adds
+ * nothing to the token.
+ *
+ * @param user the user the token is being issued for, as read from the database
+ * @returns the identity claims to sign
+ */
+export declare function buildAuthClaims(user: Partial<BaseUser>): AuthClaims;
+/**
+ * Rebuilds the caller's identity from the claims of a verified token.
+ *
+ * Tolerant of a MISSING key but never of a malformed one: an older token issued
+ * before grants existed simply yields an empty list, whereas an entry without an
+ * `id` or a `role` is dropped rather than trusted half-formed.
+ *
+ * @param data the `data` payload of the verified access token
+ * @returns roles, memberships and grants, shaped as the `BaseUser` augmentation
+ */
+export declare function identityFromClaims(data?: Partial<AuthClaims>): ClaimIdentity;
+//# sourceMappingURL=claims.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../../src/utils/claims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;+FAiB+F;AAE/F,OAAO,EAAE,QAAQ,EAAE,MAAuB,sBAAsB,CAAC;AAGjE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEhE;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,UAAU,CAcnE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,aAAa,CAS5E"}

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

@@ -0,0 +1,36 @@
+/**
+ * JWT identity-claim types (ADR-0005 section 5.1).
+ *
+ * Kept separate from the logic in `claims.ts` (house-style: types live in a
+ * dedicated `*.interfaces.ts`, never mixed with the logic that consumes them).
+ */
+import { BaseEntity, OrgGrant } from '../interfaces';
+/**
+ * The identity portion of the access-token payload.
+ *
+ * Deliberately terse: these keys are repeated in every request. `rls` and `orgs`
+ * predate this ADR and keep their historic names and shapes.
+ *
+ * `grn` carries `OrgGrant` VERBATIM, not a token-specific shape: the pair
+ * `{ id, role }` is the whole of authorization, so a separate claim type could
+ * only ever drift from it. Provenance (`OrgGrantRecord.grantedBy`/`grantedAt`)
+ * stays out - it is audit data, and the token is neither the place to repeat it
+ * on every request nor a place anything can be revoked from before expiry.
+ */
+export interface AuthClaims {
+    rls: string[];
+    orgs: string[];
+    grn?: OrgGrant[];
+}
+/**
+ * The identity rebuilt from a token by a resource service.
+ *
+ * Mirrors the fields the `BaseUser` augmentation adds, so the result can be spread
+ * straight onto the user stand-in a resource service builds per request.
+ */
+export interface ClaimIdentity {
+    roles: string[];
+    organizations: BaseEntity[];
+    grants: OrgGrant[];
+}
+//# sourceMappingURL=claims.interfaces.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"claims.interfaces.d.ts","sourceRoot":"","sources":["../../src/utils/claims.interfaces.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,EAAG,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,QAAQ,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAU,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,UAAU,EAAE,CAAC;IAC5B,MAAM,EAAS,QAAQ,EAAE,CAAC;CAC3B"}

package/build/utils/claims.interfaces.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * JWT identity-claim types (ADR-0005 section 5.1).
+ *
+ * Kept separate from the logic in `claims.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=claims.interfaces.js.map

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

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

package/build/utils/claims.js

@@ -0,0 +1,64 @@
+"use strict";
+/*********************************************************************************************
+ *                                                                                           *
+ * Identity claims - the SINGLE definition of what identity travels inside an access token.  *
+ *                                                                                           *
+ * Two operations, kept together on purpose because they MUST stay each other's inverse:     *
+ *                                                                                           *
+ *   buildAuthClaims     - auth-srv, when signing a token (login and refresh);               *
+ *   identityFromClaims  - every resource service, when rebuilding the caller per request.   *
+ *                                                                                           *
+ * They used to be four hand-written literals across two services. A drift between them is   *
+ * not a cosmetic bug: a claim that is written but not read means the authorization data      *
+ * silently disappears, and the checks that depend on it fail OPEN or CLOSED at random.       *
+ *                                                                                           *
+ * NOTE: resource services do NOT re-read the user from the database - they trust these       *
+ * claims (ADR-0005 section 5.1). Revoking a grant therefore takes effect only after the      *
+ * token is refreshed: a declared property, bounded by the access-token TTL.                  *
+ *                                                                                           *
+ *********************************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAuthClaims = buildAuthClaims;
+exports.identityFromClaims = identityFromClaims;
+/**
+ * Builds the identity claims to embed in an access token.
+ *
+ * `grn` is omitted entirely when the user holds no grant, so the common case adds
+ * nothing to the token.
+ *
+ * @param user the user the token is being issued for, as read from the database
+ * @returns the identity claims to sign
+ */
+function buildAuthClaims(user) {
+    // rebuilt entry by entry, never spread: `user.grants` is an `OrgGrantRecord[]`
+    // read from the database, and spreading it would carry `grantedBy`/`grantedAt`
+    // into every request's token. The pair below is the whole of authorization.
+    const grants = (user.grants ?? [])
+        .filter(g => g.id && g.role)
+        .map(g => ({ id: String(g.id), role: g.role }));
+    return {
+        rls: user.roles ?? [],
+        orgs: (user.organizations ?? []).map(o => o.id).filter(Boolean),
+        ...(grants.length && { grn: grants })
+    };
+}
+/**
+ * Rebuilds the caller's identity from the claims of a verified token.
+ *
+ * Tolerant of a MISSING key but never of a malformed one: an older token issued
+ * before grants existed simply yields an empty list, whereas an entry without an
+ * `id` or a `role` is dropped rather than trusted half-formed.
+ *
+ * @param data the `data` payload of the verified access token
+ * @returns roles, memberships and grants, shaped as the `BaseUser` augmentation
+ */
+function identityFromClaims(data) {
+    return {
+        roles: data?.rls ?? [],
+        organizations: (data?.orgs ?? []).map(id => ({ id })),
+        grants: (data?.grn ?? [])
+            .filter(g => g?.id && g?.role)
+            .map(g => ({ id: g.id, role: g.role }))
+    };
+}
+//# sourceMappingURL=claims.js.map

package/build/utils/claims.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.js","sourceRoot":"","sources":["../../src/utils/claims.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;+FAiB+F;;AAgB/F,0CAcC;AAYD,gDASC;AA5CD;;;;;;;;GAQG;AACH,SAAgB,eAAe,CAAC,IAAuB;IAErD,+EAA+E;IAC/E,+EAA+E;IAC/E,4EAA4E;IAC5E,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;SAC/B,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC;SAC3B,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAElD,OAAO;QACL,GAAG,EAAG,IAAI,CAAC,KAAK,IAAI,EAAE;QACtB,IAAI,EAAE,CAAC,IAAI,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;QAChE,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;KACtC,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,kBAAkB,CAAC,IAA0B;IAE3D,OAAO;QACL,KAAK,EAAU,IAAI,EAAE,GAAG,IAAI,EAAE;QAC9B,aAAa,EAAE,CAAC,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACrD,MAAM,EAAS,CAAC,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC;aAC7B,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC;aAC7B,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAiB,EAAE,CAAC,CAAC;KACvD,CAAC;AACJ,CAAC"}

package/build/utils/express.js

@@ -63,11 +63,11 @@ function allowMethods(methods = [], message = 'Method Not Allowed') {
 }
 ;
 /**
- * Normalise an array of HTTP methods.
+ * Normalize an array of HTTP methods.
  *
  * @access private
  * @param {Array<string>} methods
- *     The HTTP methods to normalise.
+ *     The HTTP methods to normalize.
  * @returns {Array<string>}
  *     Returns an array of capitalised HTTP methods.
  */

package/build/utils/functs.d.ts

@@ -18,7 +18,7 @@ export declare function initConfig(dir: string): Promise<AppData>;
  */
 export declare function buildMongoDBConfig(): Promise<AppMongoDB>;
 /**
- * Reads and normalises the application environment.
+ * Reads and normalizes the application environment.
  *
  * Loads the dotenv file for the active `NODE_ENV`, applies the {@link ENV_DEFAULTS}
  * table for any unset variable, resolves the few defaults that depend on other
@@ -120,13 +120,13 @@ export declare function getEntityI18nString(input: NxTypeObject<string> | string
  */
 export declare function setEntityI18nString(input: NxTypeObject<string> | string, lang: string): NxTypeObject<string>;
 /**
- * Validates and normalises an absolute http(s) URL (SSRF guard).
+ * Validates and normalizes an absolute http(s) URL (SSRF guard).
  *
  * Requires an explicit `http`/`https` protocol and rejects loopback hosts
  * (`localhost`/`127.0.0.1`) to prevent server-side request forgery.
  *
  * @param input the URL to validate
- * @returns the parsed, normalised URL string
+ * @returns the parsed, normalized URL string
  * @throws `Invalid URL` when malformed, `Forbidden URL` when pointing at loopback
  */
 export declare function validateUrl(input: string): string;

package/build/utils/functs.js

@@ -258,7 +258,7 @@ function validateEnv() {
     }
 }
 /**
- * Reads and normalises the application environment.
+ * Reads and normalizes the application environment.
  *
  * Loads the dotenv file for the active `NODE_ENV`, applies the {@link ENV_DEFAULTS}
  * table for any unset variable, resolves the few defaults that depend on other
@@ -500,13 +500,13 @@ function setEntityI18nString(input, lang) {
     return res;
 }
 /**
- * Validates and normalises an absolute http(s) URL (SSRF guard).
+ * Validates and normalizes an absolute http(s) URL (SSRF guard).
  *
  * Requires an explicit `http`/`https` protocol and rejects loopback hosts
  * (`localhost`/`127.0.0.1`) to prevent server-side request forgery.
  *
  * @param input the URL to validate
- * @returns the parsed, normalised URL string
+ * @returns the parsed, normalized URL string
  * @throws `Invalid URL` when malformed, `Forbidden URL` when pointing at loopback
  */
 function validateUrl(input) {

package/build/utils/index.d.ts

@@ -1,8 +1,12 @@
+export * from './claims';
+export * from './claims.interfaces';
 export * from './express';
 export * from './functs';
 export * from './jwt';
 export * from './jwt.constants';
 export * from './jwt.interfaces';
+export * from './scope';
+export * from './scope.interfaces';
 export * from './start-service';
 export * from './tenant';
 export * from './tenant.interfaces';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,OAAO,CAAC;AACtB,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC;AACpC,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,OAAO,CAAC;AACtB,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,SAAS,CAAC;AACxB,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC"}

package/build/utils/index.js

@@ -14,11 +14,15 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./claims"), exports);
+__exportStar(require("./claims.interfaces"), exports);
 __exportStar(require("./express"), exports);
 __exportStar(require("./functs"), exports);
 __exportStar(require("./jwt"), exports);
 __exportStar(require("./jwt.constants"), exports);
 __exportStar(require("./jwt.interfaces"), exports);
+__exportStar(require("./scope"), exports);
+__exportStar(require("./scope.interfaces"), exports);
 __exportStar(require("./start-service"), exports);
 __exportStar(require("./tenant"), exports);
 __exportStar(require("./tenant.interfaces"), exports);

package/build/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4CAA0B;AAC1B,2CAAyB;AACzB,wCAAsB;AACtB,kDAAgC;AAChC,mDAAiC;AACjC,kDAAgC;AAChC,2CAAyB;AACzB,sDAAoC;AACpC,4DAA0C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,sDAAoC;AACpC,4CAA0B;AAC1B,2CAAyB;AACzB,wCAAsB;AACtB,kDAAgC;AAChC,mDAAiC;AACjC,0CAAwB;AACxB,qDAAmC;AACnC,kDAAgC;AAChC,2CAAyB;AACzB,sDAAoC;AACpC,4DAA0C"}

package/build/utils/scope.d.ts

@@ -0,0 +1,75 @@
+/*********************************************************************************************
+ *                                                                                           *
+ * Organization scope - THE single answer to "may this user operate on THIS organization?"   *
+ *                                                                                           *
+ * The organization arrives EXPLICITLY from the request (an `oid`/`uid` on a mutation).      *
+ * The sibling question - "which organization is this user operating on?", where the tenant  *
+ * must be DEDUCED - is answered by `resolveTenant` in `tenant.ts`. Two questions, two        *
+ * functions, no overlap.                                                                    *
+ *                                                                                           *
+ * SINGLE SOURCE OF TRUTH: every caller imports from here and NEVER re-implements the        *
+ * check. `@auth(requires:)` alone is never sufficient - it verifies the ROLE, never the      *
+ * ORGANIZATION (ADR-0005 section 5).                                                        *
+ *                                                                                           *
+ *********************************************************************************************/
+import { BaseUser } from '@nextage/nx-frame-be';
+import { OrgScope } from './scope.interfaces';
+/**
+ * Resolves how `user` reaches the organization `orgId`, or `null` if they cannot.
+ *
+ * Resolution order (ADR-0005 section 5) - the first match wins:
+ *
+ *   1. cross-tenant level        -> { tier: PROVIDER }        // no organization constraint
+ *   2. membership on `orgId`     -> { tier: MEMBER,  role }   // role from `roles[]`
+ *   3. grant on `orgId`          -> { tier: GRANTED, role }   // role from the grant
+ *   4. otherwise                 -> null                      // denied
+ *
+ * Membership is checked BEFORE grants because it is identity: a user who belongs to
+ * the organization already reaches it, and a grant on one's own organization would
+ * be redundant. Note the two carry the role differently - membership entries hold no
+ * role (it lives in `users.roles[]`, one organization-tier role per user), whereas a
+ * grant carries its own, which is what allows a different role per organization.
+ *
+ * FAIL-CLOSED: a missing user, a missing `orgId` or no match at all all yield `null`.
+ * Callers must treat `null` as "denied" and never as "unknown".
+ *
+ * @param user  the authenticated user (`NxContext.user`)
+ * @param orgId the target organization id, as received from the request
+ * @returns the scope through which the user reaches the organization, or `null`
+ */
+export declare function resolveOrgScope(user?: BaseUser, orgId?: string): OrgScope | null;
+/**
+ * Throwing variant of `resolveOrgScope`, for the call sites that must simply deny.
+ *
+ * Raises the same error whether the organization is out of scope or does not exist:
+ * distinguishing the two would confirm the existence of somebody else's organization.
+ *
+ * @param user  the authenticated user (`NxContext.user`)
+ * @param orgId the target organization id, as received from the request
+ * @returns the resolved scope (never `null`)
+ * @throws `AppError('messages.authorization.missingRole')` when out of scope
+ */
+export declare function assertOrgScope(user?: BaseUser, orgId?: string): OrgScope;
+/**
+ * Every organization the user reaches, for the LIST case.
+ *
+ * `resolveOrgScope` answers about ONE organization named by the request; this answers
+ * "which ones may appear at all?", which is what a model's `updateFilters` needs. The
+ * two share the same rules deliberately: a list that showed an organization the point
+ * check would then deny would be a leak by itself.
+ *
+ * Three outcomes, and the caller MUST tell them apart:
+ *
+ *   `undefined` -> no constraint: a cross-tenant user, every organization is visible
+ *   `string[]`  -> exactly these ids (memberships UNION grants), never any other
+ *   `[]`        -> nothing is visible; the caller must yield an EMPTY result, never all
+ *
+ * The union is what makes a grant visible in the organization switcher: an
+ * `ORG_EDITOR` granted on another organization must find it in the list, or the
+ * grant would be unusable (ADR-0005 section 3.2).
+ *
+ * @param user the authenticated user (`NxContext.user`)
+ * @returns `undefined` for no constraint, otherwise the exact set of reachable ids
+ */
+export declare function reachableOrgIds(user?: BaseUser): string[] | undefined;
+//# sourceMappingURL=scope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../src/utils/scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;+FAa+F;AAE/F,OAAO,EAAY,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAM1D,OAAO,EAAE,QAAQ,EAAE,MAAgB,oBAAoB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAqBhF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,CAQxE;AAcD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,MAAM,EAAE,GAAG,SAAS,CAcrE"}

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

@@ -0,0 +1,20 @@
+/**
+ * Organization-scope types & interfaces (ADR-0005 section 5).
+ *
+ * Kept separate from the logic in `scope.ts` (house-style: types live in a
+ * dedicated `*.interfaces.ts`, never mixed with the logic that consumes them).
+ * `OrgScopeTier` itself lives in `enums.ts`, next to `BaseRoles`/`RolesType`.
+ */
+import { BaseRoles, OrgScopeTier } from '../enums';
+/**
+ * Outcome of `resolveOrgScope`: the tier through which the user reaches the
+ * organization, plus the organization-tier role that applies THERE.
+ *
+ * `role` is undefined only for the `PROVIDER` tier, whose capabilities come from
+ * the capability matrix (ADR-0005 section 4) and not from an organization role.
+ */
+export interface OrgScope {
+    tier: OrgScopeTier;
+    role?: BaseRoles;
+}
+//# sourceMappingURL=scope.interfaces.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scope.interfaces.d.ts","sourceRoot":"","sources":["../../src/utils/scope.interfaces.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAG,YAAY,CAAC;IACpB,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB"}

package/build/utils/scope.interfaces.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Organization-scope types & interfaces (ADR-0005 section 5).
+ *
+ * Kept separate from the logic in `scope.ts` (house-style: types live in a
+ * dedicated `*.interfaces.ts`, never mixed with the logic that consumes them).
+ * `OrgScopeTier` itself lives in `enums.ts`, next to `BaseRoles`/`RolesType`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=scope.interfaces.js.map

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

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

package/build/utils/scope.js

@@ -0,0 +1,121 @@
+"use strict";
+/*********************************************************************************************
+ *                                                                                           *
+ * Organization scope - THE single answer to "may this user operate on THIS organization?"   *
+ *                                                                                           *
+ * The organization arrives EXPLICITLY from the request (an `oid`/`uid` on a mutation).      *
+ * The sibling question - "which organization is this user operating on?", where the tenant  *
+ * must be DEDUCED - is answered by `resolveTenant` in `tenant.ts`. Two questions, two        *
+ * functions, no overlap.                                                                    *
+ *                                                                                           *
+ * SINGLE SOURCE OF TRUTH: every caller imports from here and NEVER re-implements the        *
+ * check. `@auth(requires:)` alone is never sufficient - it verifies the ROLE, never the      *
+ * ORGANIZATION (ADR-0005 section 5).                                                        *
+ *                                                                                           *
+ *********************************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveOrgScope = resolveOrgScope;
+exports.assertOrgScope = assertOrgScope;
+exports.reachableOrgIds = reachableOrgIds;
+const nx_frame_be_1 = require("@nextage/nx-frame-be");
+const constants_1 = require("../constants");
+const constants_2 = require("../constants");
+const enums_1 = require("../enums");
+/**
+ * Resolves how `user` reaches the organization `orgId`, or `null` if they cannot.
+ *
+ * Resolution order (ADR-0005 section 5) - the first match wins:
+ *
+ *   1. cross-tenant level        -> { tier: PROVIDER }        // no organization constraint
+ *   2. membership on `orgId`     -> { tier: MEMBER,  role }   // role from `roles[]`
+ *   3. grant on `orgId`          -> { tier: GRANTED, role }   // role from the grant
+ *   4. otherwise                 -> null                      // denied
+ *
+ * Membership is checked BEFORE grants because it is identity: a user who belongs to
+ * the organization already reaches it, and a grant on one's own organization would
+ * be redundant. Note the two carry the role differently - membership entries hold no
+ * role (it lives in `users.roles[]`, one organization-tier role per user), whereas a
+ * grant carries its own, which is what allows a different role per organization.
+ *
+ * FAIL-CLOSED: a missing user, a missing `orgId` or no match at all all yield `null`.
+ * Callers must treat `null` as "denied" and never as "unknown".
+ *
+ * @param user  the authenticated user (`NxContext.user`)
+ * @param orgId the target organization id, as received from the request
+ * @returns the scope through which the user reaches the organization, or `null`
+ */
+function resolveOrgScope(user, orgId) {
+    if (!user || !orgId)
+        return null;
+    // 1. cross-tenant level: reaches every organization by definition of level.
+    if (user.hasRole?.(constants_1.CROSS_TENANT_ROLES))
+        return { tier: enums_1.OrgScopeTier.PROVIDER };
+    // 2. membership (identity): the role is the highest organization-tier one held.
+    if (user.organizations?.some(o => o.id === orgId))
+        return { tier: enums_1.OrgScopeTier.MEMBER, role: highestOrgRole(user) };
+    // 3. grant (authorization): the role travels WITH the grant.
+    const grant = user.grants?.find(g => g.id === orgId);
+    if (grant)
+        return { tier: enums_1.OrgScopeTier.GRANTED, role: grant.role };
+    // 4. no path to this organization.
+    return null;
+}
+/**
+ * Throwing variant of `resolveOrgScope`, for the call sites that must simply deny.
+ *
+ * Raises the same error whether the organization is out of scope or does not exist:
+ * distinguishing the two would confirm the existence of somebody else's organization.
+ *
+ * @param user  the authenticated user (`NxContext.user`)
+ * @param orgId the target organization id, as received from the request
+ * @returns the resolved scope (never `null`)
+ * @throws `AppError('messages.authorization.missingRole')` when out of scope
+ */
+function assertOrgScope(user, orgId) {
+    const scope = resolveOrgScope(user, orgId);
+    if (!scope)
+        throw new nx_frame_be_1.AppError('messages.authorization.missingRole');
+    return scope;
+}
+/**
+ * The highest organization-tier role the user holds, if any.
+ *
+ * `ORG_MEMBER_ROLES` is ordered from the highest to the lowest privilege, so the
+ * first match IS the highest. Returns `undefined` for a user with no
+ * organization-tier role at all (possible for a pure provider-level account).
+ */
+function highestOrgRole(user) {
+    return constants_2.ORG_MEMBER_ROLES.find(r => user.hasRole?.(r));
+}
+/**
+ * Every organization the user reaches, for the LIST case.
+ *
+ * `resolveOrgScope` answers about ONE organization named by the request; this answers
+ * "which ones may appear at all?", which is what a model's `updateFilters` needs. The
+ * two share the same rules deliberately: a list that showed an organization the point
+ * check would then deny would be a leak by itself.
+ *
+ * Three outcomes, and the caller MUST tell them apart:
+ *
+ *   `undefined` -> no constraint: a cross-tenant user, every organization is visible
+ *   `string[]`  -> exactly these ids (memberships UNION grants), never any other
+ *   `[]`        -> nothing is visible; the caller must yield an EMPTY result, never all
+ *
+ * The union is what makes a grant visible in the organization switcher: an
+ * `ORG_EDITOR` granted on another organization must find it in the list, or the
+ * grant would be unusable (ADR-0005 section 3.2).
+ *
+ * @param user the authenticated user (`NxContext.user`)
+ * @returns `undefined` for no constraint, otherwise the exact set of reachable ids
+ */
+function reachableOrgIds(user) {
+    if (!user)
+        return [];
+    if (user.hasRole?.(constants_1.CROSS_TENANT_ROLES))
+        return undefined;
+    const ids = new Set();
+    user.organizations?.forEach(o => o.id && ids.add(String(o.id)));
+    user.grants?.forEach(g => g.id && ids.add(String(g.id)));
+    return [...ids];
+}
+//# sourceMappingURL=scope.js.map

package/build/utils/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../src/utils/scope.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;+FAa+F;;AAiC/F,0CAqBC;AAaD,wCAQC;AAmCD,0CAcC;AA1HD,sDAA0D;AAE1D,4CAAkD;AAClD,4CAAkD;AAElD,oCAA8C;AAG9C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAgB,eAAe,CAAC,IAAe,EAAE,KAAc;IAE7D,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK;QACjB,OAAO,IAAI,CAAC;IAEd,4EAA4E;IAC5E,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC,8BAAkB,CAAC;QACpC,OAAO,EAAE,IAAI,EAAE,oBAAY,CAAC,QAAQ,EAAE,CAAC;IAEzC,gFAAgF;IAChF,IAAI,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,KAAK,CAAC;QAC/C,OAAO,EAAE,IAAI,EAAE,oBAAY,CAAC,MAAM,EAAE,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;IAEnE,6DAA6D;IAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,KAAK,CAAC,CAAC;IAErD,IAAI,KAAK;QACP,OAAO,EAAE,IAAI,EAAE,oBAAY,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;IAE1D,mCAAmC;IACnC,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,cAAc,CAAC,IAAe,EAAE,KAAc;IAE5D,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAE3C,IAAI,CAAC,KAAK;QACR,MAAM,IAAI,sBAAQ,CAAC,oCAAoC,CAAC,CAAC;IAE3D,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,SAAS,cAAc,CAAC,IAAc;IAEpC,OAAO,4BAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,eAAe,CAAC,IAAe;IAE7C,IAAI,CAAC,IAAI;QACP,OAAO,EAAE,CAAC;IAEZ,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC,8BAAkB,CAAC;QACpC,OAAO,SAAS,CAAC;IAEnB,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAE9B,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAChE,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAEzD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC;AAClB,CAAC"}

package/build/utils/start-service.js

@@ -152,7 +152,7 @@ async function safeCheck(check) {
     }
 }
 /**
- * Normalises an unknown thrown value into a readable message.
+ * Normalizes an unknown thrown value into a readable message.
  */
 function errMessage(err) {
     if (err instanceof Error)