@memberjunction/core-entities-server 6.1.0-edge.6 → 6.1.0

package/dist/custom/MJEntityFieldPermissionEntityServer.server.js

@@ -0,0 +1,347 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var MJEntityFieldPermissionEntityServer_1;
+import { BaseEntity, BaseEntityResult, FieldPermissionAccess, IsRestrictingFieldRule, LogError, RunView, ValidationErrorInfo, ValidationErrorType, } from '@memberjunction/core';
+import { RegisterClass, UUIDsEqual } from '@memberjunction/global';
+import { MJEntityFieldPermissionEntity } from '@memberjunction/core-entities';
+import { SystemUserFieldAccessLossReason, SystemUserHoldsRole, UserCache } from '@memberjunction/generic-database-provider';
+/**
+ * Server-side `MJ: Entity Field Permissions` entity — the save-time half of the
+ * unrestrictable-target guard for field-level security.
+ *
+ * The runtime aggregation (`EntityFieldInfo.GetUserFieldPermissions`) already forces access
+ * open for these targets, so this subclass is not what makes the system safe. It is what makes
+ * the system *diagnosable*: without it an administrator can save a row that silently does
+ * nothing, then reasonably conclude the feature is broken. Rejecting at save says why.
+ *
+ * Two categories are refused, matching the two runtime guards exactly:
+ *
+ * 1. **Primary keys and system columns.** Stripping a primary key from a result breaks entity
+ *    load, `CompositeKey` construction, relationship resolution, and cache fingerprinting —
+ *    failures that surface nowhere near the permission record that caused them.
+ * 2. **The security-configuration and identity surface** (see
+ *    {@link EntityFieldInfo.IsOnUnrestrictableEntity}). Restricting a column on the very
+ *    entities field security is administered through produces a configuration that cannot be
+ *    reversed through the product — recovery would mean direct SQL against the database.
+ *
+ * A third category is refused for a different reason: a **`Deny`** aimed at a role the MJ system
+ * user holds (see {@link SystemUserRoleRejectionReason}). That one is not about diagnosability —
+ * it is what lets the runtime aggregation have no exempt user at all. The server's own account
+ * gets its access from ordinary `Allow` rows like everyone else, and this guard is what stops
+ * those being revoked.
+ *
+ * Note what is deliberately NOT here: any notion of a user who is exempt from a Deny at
+ * RUNTIME. The guards are on which *targets* are restrictable and on what may be *configured*,
+ * never on whose access is evaluated. A feature whose purpose is compensation and donor-giving
+ * confidentiality cannot ship with a role that quietly reads everything.
+ */
+let MJEntityFieldPermissionEntityServer = MJEntityFieldPermissionEntityServer_1 = class MJEntityFieldPermissionEntityServer extends MJEntityFieldPermissionEntity {
+    Validate() {
+        const result = super.Validate();
+        const target = this.resolveTarget();
+        if (target) {
+            const entityPermissionRejection = MJEntityFieldPermissionEntityServer_1.EntityPermissionRequiredRejectionReason(target.Entity, this.RoleID);
+            if (entityPermissionRejection) {
+                result.Errors.push(new ValidationErrorInfo('RoleID', entityPermissionRejection, this.RoleID, ValidationErrorType.Failure));
+            }
+        }
+        const targetField = target?.Field;
+        if (targetField) {
+            const rejection = MJEntityFieldPermissionEntityServer_1.RejectionReason(targetField);
+            if (rejection) {
+                result.Errors.push(new ValidationErrorInfo('EntityFieldID', rejection, this.EntityFieldID, ValidationErrorType.Failure));
+            }
+            const writeVerbRejection = MJEntityFieldPermissionEntityServer_1.WriteVerbRejectionReason(targetField, this);
+            if (writeVerbRejection) {
+                result.Errors.push(new ValidationErrorInfo('EntityFieldID', writeVerbRejection, this.EntityFieldID, ValidationErrorType.Failure));
+            }
+        }
+        const roleRejection = MJEntityFieldPermissionEntityServer_1.SystemUserRoleRejectionReason(this.RoleID, this);
+        if (roleRejection) {
+            result.Errors.push(new ValidationErrorInfo('RoleID', roleRejection, this.RoleID, ValidationErrorType.Failure));
+        }
+        result.Success = result.Success && result.Errors.length === 0;
+        return result;
+    }
+    /**
+     * Refuses an EDIT that would strip the MJ system user's last `Allow` on a field.
+     *
+     * Not in `Validate()` for two reasons. It needs the field's rules as they stand in the
+     * DATABASE — loaded metadata lags recent writes, and reading a stale sibling row as `Allow` is
+     * exactly how three individually-innocent `No Access` edits get through one at a time. And
+     * loading them is asynchronous, which `Validate()` is not.
+     *
+     * Inserts are deliberately not checked: adding a rule can only add access, never remove an
+     * existing `Allow`, so the `Deny` check in `Validate()` covers them completely. It has to —
+     * snapshot initialization writes its rows one at a time, and an aggregate check would refuse
+     * the half-built state.
+     */
+    async Save(options) {
+        if (this.IsSaved) {
+            const rejection = await this.systemUserAccessLossReason(false);
+            if (rejection) {
+                return this.refuse(rejection, 'save');
+            }
+        }
+        return super.Save(options);
+    }
+    /**
+     * Refuses a DELETE that would strip the MJ system user's last `Allow` on a field — the other
+     * way, besides editing one to `No Access`, to remove access without writing a `Deny`.
+     *
+     * Reconciliation's own orphan deletes are unaffected: it only removes rows whose role has lost
+     * entity-level read (so the system user is already denied one level up and the guard stands
+     * down) or whose field became unrestrictable (forced open regardless).
+     */
+    async Delete(options) {
+        const rejection = await this.systemUserAccessLossReason(true);
+        if (rejection) {
+            return this.refuse(rejection, 'delete');
+        }
+        return super.Delete(options);
+    }
+    /**
+     * Records a refusal on the result history so `LatestResult.CompleteMessage` explains it, and
+     * returns false — the contract `Save()` and `Delete()` already have for a logical failure.
+     */
+    refuse(message, type) {
+        const result = new BaseEntityResult();
+        result.Success = false;
+        result.Type = type === 'delete' ? 'delete' : this.IsSaved ? 'update' : 'create';
+        result.Message = message;
+        result.StartedAt = new Date();
+        result.EndedAt = new Date();
+        this.ResultHistory.push(result);
+        return false;
+    }
+    /**
+     * Why the pending change would leave the system user short of its entity-level access, or null.
+     *
+     * @param removing true when this row is being deleted rather than edited
+     */
+    async systemUserAccessLossReason(removing) {
+        // Cheap exit first: the aggregation only ever consults rules bound to a role the user
+        // holds, so a change to any other role's rule cannot move the system user's access at all.
+        // This is what keeps the query below off the path of ordinary permission administration —
+        // it runs only for edits to the handful of roles the server's own account holds.
+        if (!SystemUserHoldsRole(this.RoleID)) {
+            return null;
+        }
+        const target = this.resolveTarget();
+        if (!target) {
+            return null;
+        }
+        const current = await this.loadCurrentRules(target.Field.ID);
+        const others = current.filter(r => !UUIDsEqual(r.ID, this.ID));
+        const projected = removing
+            ? others
+            : [
+                ...others,
+                {
+                    RoleID: this.RoleID,
+                    ReadAccess: this.ReadAccess,
+                    UpdateAccess: this.UpdateAccess,
+                    CreateAccess: this.CreateAccess,
+                },
+            ];
+        return SystemUserFieldAccessLossReason(target.Entity, target.Field, projected);
+    }
+    /**
+     * Every rule currently stored against this field, straight from the database.
+     *
+     * `BypassCache` because this decides an access-control question: a cached result that predates
+     * a sibling row's edit would answer it with data the guard is specifically trying to catch up
+     * with. Inside a transaction this reads the scope's own uncommitted writes, which is what
+     * reconciliation needs.
+     */
+    async loadCurrentRules(entityFieldID) {
+        const rv = new RunView(this.RunViewProviderToUse);
+        const result = await rv.RunView({
+            EntityName: 'MJ: Entity Field Permissions',
+            ExtraFilter: `EntityFieldID = '${entityFieldID}'`,
+            Fields: ['ID', 'RoleID', 'ReadAccess', 'UpdateAccess', 'CreateAccess'],
+            ResultType: 'simple',
+            BypassCache: true,
+        }, this.ContextCurrentUser);
+        if (!result.Success) {
+            // Cannot evaluate the guard — say so rather than silently permitting. The caller sees
+            // an empty rule set, which never produces a refusal, so this is a fail-open that is at
+            // least visible in the log; the startup sweep is the backstop.
+            LogError(`[FieldSecurity] Could not load sibling rules for field ${entityFieldID}; ` +
+                `the system-user access guard did not run: ${result.ErrorMessage}`);
+            return [];
+        }
+        return result.Results ?? [];
+    }
+    /**
+     * Why this rule may not target this role, or null when it may.
+     *
+     * Refuses a **restricting** rule aimed at a role the MJ **system user** holds. The system
+     * user is what the server runs background work as: it pre-warms the shared engine caches at
+     * startup, and in task mode (job and agent runners) whichever caller touches an engine first
+     * configures it for the whole process. Restricting that account does not just restrict it —
+     * engines cache their data process-wide, so a partially loaded engine would then serve
+     * incomplete records to every user afterward. The damage is silent and nowhere near the rule
+     * that caused it.
+     *
+     * **Only a `Deny` is refused.** Field security has no runtime exemption for any user, so the
+     * system user's own access comes from ordinary rows: snapshot initialization writes it
+     * `Allow` on every field its roles can read, and this guard is what stops that access being
+     * taken away again. `Allow` and `No Access` both save — `Allow` is the grant the server
+     * depends on, and `No Access` is neutral, unable to reduce access another role has granted.
+     * Refusing those would make it impossible to enable field security on any entity at all,
+     * since the standard roles (UI, Developer, Integration) carry entity permissions almost
+     * everywhere.
+     *
+     * This is a guard on CONFIGURATION, not a runtime exemption. What is refused is the
+     * arrangement that would make the server unable to do its own work. Take the role off the
+     * system user and the rule saves.
+     *
+     * The database tier already refuses the equivalent arrangement: CodeGen skips a column DENY
+     * for any role a service login belongs to, and warns. This is the same rule for the
+     * application tier.
+     *
+     * @param roleID the role the rule targets
+     * @param rule the rule's three verbs; omitted only by callers that are pre-checking a role
+     *             rather than a specific rule, which are answered as though the rule denied
+     */
+    static SystemUserRoleRejectionReason(roleID, rule) {
+        if (!roleID) {
+            return null;
+        }
+        if (rule && !IsRestrictingFieldRule(rule)) {
+            return null; // grants and neutrals are exactly what keep the system user working
+        }
+        // UserCache is populated on the server; a client-side save (or a cold cache) simply
+        // skips the check rather than blocking an administrator on missing state.
+        const systemUser = UserCache.Instance?.GetSystemUser?.();
+        if (!systemUser?.UserRoles?.length) {
+            return null;
+        }
+        const holdsRole = systemUser.UserRoles.some(ur => UUIDsEqual(ur.RoleID, roleID));
+        if (!holdsRole) {
+            return null;
+        }
+        const roleName = systemUser.UserRoles.find(ur => UUIDsEqual(ur.RoleID, roleID))?.Role ?? roleID;
+        return (`Role '${roleName}' is held by the MJ system user, so it cannot carry a Deny on any field. ` +
+            `The server runs background work as that account and shares one engine cache across all users — ` +
+            `restricting it would let partially loaded records reach everyone. ` +
+            `Remove the role from the system user first, or apply this rule to a different role.`);
+    }
+    /**
+     * Why this rule's Update/Create verbs may not target this field, or null when they may.
+     *
+     * A **read-only** field cannot be written through the API by anyone: it is excluded from the
+     * generated create input type and from the update SET list, and `BaseEntity` never marks it
+     * dirty. So an Update or Create verb on it is inert in both directions — a `Deny` prevents
+     * nothing that was possible, and an `Allow` grants nothing that was not. Left to save, it
+     * reads on screen as a working permission and silently is not one.
+     *
+     * **Read is untouched, deliberately.** Restricting READ on a read-only field is legitimate
+     * and is one of the main things administrators want: foreign-key display columns are
+     * read-only, and "hide which client this contract belongs to" is exactly a read restriction
+     * on one. Only the two write verbs are refused.
+     *
+     * Note `EntityFieldInfo.ReadOnly` is the right predicate here, not `IsVirtual`: IS-A parent
+     * fields are virtual but ARE writable through the child's save chain, and `ReadOnly` is
+     * defined off `AllowUpdateAPI` precisely to tell those apart from joined display columns.
+     */
+    static WriteVerbRejectionReason(field, rule) {
+        if (!field.ReadOnly) {
+            return null;
+        }
+        const offending = [];
+        if (rule.UpdateAccess !== FieldPermissionAccess.NoAccess)
+            offending.push('Update');
+        if (rule.CreateAccess !== FieldPermissionAccess.NoAccess)
+            offending.push('Create');
+        if (offending.length === 0) {
+            return null;
+        }
+        return (`Field '${field.Entity}.${field.Name}' is read-only, so its ${offending.join(' and ')} ` +
+            `${offending.length > 1 ? 'permissions have' : 'permission has'} no effect — the field cannot be written ` +
+            `through the API by any user. Set ${offending.length > 1 ? 'them' : 'it'} to 'No Access'. ` +
+            `Read permission on this field still applies normally.`);
+    }
+    /**
+     * Why this field may not be secured, or null when it may be.
+     * Static + field-driven so the same wording can back a future admin-UI pre-check.
+     */
+    static RejectionReason(field) {
+        if (field.IsUnrestrictableField) {
+            const reason = field.IsPrimaryKey || field.IsSoftPrimaryKey ? 'a primary key' : 'a system column';
+            return (`Field '${field.Entity}.${field.Name}' is ${reason} and cannot be secured by field-level permissions. ` +
+                `Primary keys and system columns must stay readable — removing one from a result breaks entity loading, ` +
+                `composite keys, relationship resolution, and cache fingerprinting. Secure the sensitive field itself instead.`);
+        }
+        if (field.IsOnUnrestrictableEntity) {
+            return (`Entity '${field.Entity}' is part of the security configuration and identity surface, so its fields ` +
+                `cannot be secured by field-level permissions. Restricting a column here can produce a configuration ` +
+                `that cannot be reversed through the application — undoing it would require direct database access.`);
+        }
+        return null;
+    }
+    /**
+     * Resolves `EntityFieldID` to its {@link EntityFieldInfo} from loaded metadata.
+     *
+     * Returns null when metadata cannot resolve it — for instance immediately after a schema
+     * change, before the metadata cache has refreshed. That case passes validation rather than
+     * blocking the administrator: the foreign key already guarantees the row points at a real
+     * field, and the runtime aggregation guards hold regardless of what is stored here. Failing
+     * closed would trade a real, recurring workflow block for no additional protection.
+     */
+    /**
+     * Why this role may not carry a field rule on this entity, or null when it may.
+     *
+     * A field permission REFINES an entity permission — the entity gate decides whether you reach
+     * the record at all, and field rules then decide which columns of it you see. A rule bound to a
+     * role that has no relationship to the entity is not a refinement of anything, and it is the
+     * configuration that made the reconciler's orphan test ambiguous: such a row is fully live at
+     * runtime (aggregation matches on role membership alone) while looking inert to any check that
+     * asks what the role can do on its own.
+     *
+     * Requires only that an entity-permission row EXISTS, not that it grants read. A role whose
+     * entity permission grants nothing is the ordinary way to express a deny-only carve-out —
+     * "these users are normal, minus this column" — and demanding a grant would force an
+     * administrator to hand out entity access in order to take a column away. Deleting the entity
+     * permission removes the relationship, and reconciliation then cleans up the field rules with
+     * it; see `computeOrphanRowIDs`, which tests exactly this condition.
+     *
+     * Attributed to `RoleID` because that is the value the administrator must change — either pick
+     * a role that has entity access, or grant this one an entity permission first.
+     */
+    static EntityPermissionRequiredRejectionReason(entity, roleID) {
+        if (!roleID) {
+            return null; // the NOT NULL column is the base class's problem to report, not ours
+        }
+        if (entity.Permissions.some((p) => UUIDsEqual(p.RoleID, roleID))) {
+            return null;
+        }
+        return (`This role has no entity permission on '${entity.Name}', so a field rule for it would refine nothing. ` +
+            `Field permissions narrow the access an entity permission already grants — give the role an entity ` +
+            `permission on '${entity.Name}' first (one that grants nothing is fine, and is how a deny-only ` +
+            `carve-out is expressed), then set the field rule.`);
+    }
+    resolveTarget() {
+        if (!this.EntityFieldID) {
+            return null; // the NOT NULL column is the base class's problem to report, not ours
+        }
+        const md = this.ProviderToUse;
+        for (const entity of md?.Entities ?? []) {
+            const match = entity.Fields.find((f) => UUIDsEqual(f.ID, this.EntityFieldID));
+            if (match) {
+                return { Entity: entity, Field: match };
+            }
+        }
+        return null;
+    }
+};
+MJEntityFieldPermissionEntityServer = MJEntityFieldPermissionEntityServer_1 = __decorate([
+    RegisterClass(BaseEntity, 'MJ: Entity Field Permissions')
+], MJEntityFieldPermissionEntityServer);
+export { MJEntityFieldPermissionEntityServer };
+//# sourceMappingURL=MJEntityFieldPermissionEntityServer.server.js.map

package/dist/custom/MJEntityFieldPermissionEntityServer.server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MJEntityFieldPermissionEntityServer.server.js","sourceRoot":"","sources":["../../src/custom/MJEntityFieldPermissionEntityServer.server.ts"],"names":[],"mappings":"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"}

package/dist/custom/MJUserRoleEntityServer.server.d.ts

@@ -1,7 +1,21 @@
-import { EntityDeleteOptions, EntitySaveOptions, ValidationResult } from '@memberjunction/core';
+import { EntityDeleteOptions, EntitySaveOptions, IMetadataProvider, ValidationResult } from '@memberjunction/core';
 import { MJUserRoleEntity } from '@memberjunction/core-entities';
 /**
- * Server-side `MJ: User Roles` entity enforcing MJ's role-elevation invariant (issue #4282).
+ * Server-side `MJ: User Roles` entity. It carries TWO independent guards that happen to protect the
+ * same table from opposite directions. They share no state and no helpers, and every write path
+ * must satisfy both:
+ *
+ *   A. **Role elevation** (issue #4282) — bounds what the CALLER may do, by their own roles.
+ *   B. **System-user field access** — bounds what may be done TO the system user's role set.
+ *
+ * Guard A and guard B are orthogonal: A asks "is this caller entitled to make this change", B asks
+ * "does this change leave the system user field-restricted". A change must clear both, so the
+ * checks compose as a conjunction and are evaluated A-then-B (A is an in-memory role-list test; B
+ * walks cached metadata and only ever runs when the system user is the target).
+ *
+ * ---------------------------------------------------------------------------------------------
+ * GUARD A — ROLE ELEVATION (issue #4282)
+ * ---------------------------------------------------------------------------------------------
  *
  * WHY THIS EXISTS AT ALL. Issue #4260 (`MJUserEntityServer`) closed the `User.Type` route to
  * elevated capability. Role assignment is the platform's OTHER authority mechanism and was
@@ -74,9 +88,43 @@ import { MJUserRoleEntity } from '@memberjunction/core-entities';
  * deployment whose system user is NOT an Owner will see those sync paths fail closed — loudly,
  * at the save — exactly as #4260 documented for `MJ: Users`.
  *
- * Pure: reads only this record's own field state and the caller's cached roles. No `RunView`, no
- * provider, no engine, no I/O — so it costs nothing per save/delete and is unit-testable without a
- * database.
+ * Guard A is pure: it reads only this record's own field state and the caller's cached roles. No
+ * `RunView`, no provider, no engine, no I/O — so it costs nothing per save/delete and is
+ * unit-testable without a database. (Guard B is NOT pure in that sense; see below.)
+ *
+ * ---------------------------------------------------------------------------------------------
+ * GUARD B — SYSTEM-USER FIELD ACCESS
+ * ---------------------------------------------------------------------------------------------
+ *
+ * This is the other half of the system-user guard for field-level security.
+ * `MJEntityFieldPermissionEntityServer` guards the RULES; this guards the account's ROLE SET, from
+ * both directions. Without both halves an administrator reaches the forbidden state simply by
+ * doing the steps in a different order.
+ *
+ * - **Assignment** ({@link SystemUserRejectionReason}) — refuses giving the system user a role that
+ *   already denies a field. Only DENYING rules count here, because adding a role can only add rules
+ *   to the aggregate: its `Allow` rows grant, its `No Access` rows are inert, and only a `Deny`
+ *   can take something away. A guard that counted every rule would refuse to reassemble the
+ *   account's own role set the moment field security was enabled anywhere.
+ * - **Removal** ({@link Delete}) — refuses taking a role away when that would leave the account
+ *   short of its entity-level access. Removal is the opposite shape: it drops rules OUT of the
+ *   aggregate, so what matters is not what the departing role said but whether an `Allow` survives
+ *   without it.
+ *
+ * Why the system user must stay unrestricted: the server runs background work as that account.
+ * It pre-warms the shared engine caches at startup, and in task mode — which job and agent
+ * runners use — engines instead load on first touch, so whichever caller gets there first
+ * configures the engine for the entire process. Engine caches are process-wide and shared
+ * across users. A restricted system user could therefore leave partially loaded records in a
+ * cache that everyone reads afterward, with nothing at the point of failure pointing back at
+ * the role assignment that caused it.
+ *
+ * Unlike guard A, guard B reads cached metadata (`Metadata.Entities`, the provider, `UserCache`).
+ * It still performs no database I/O, but it is not state-free, and it needs those caches populated
+ * to have an opinion — a cold `UserCache` skips the check rather than blocking an administrator.
+ *
+ * This restricts CONFIGURATION only. There is no user who is exempt from a Deny at runtime —
+ * not even the system user, whose access comes from the same rows as everyone else's.
  */
 export declare class MJUserRoleEntityServer extends MJUserRoleEntity {
     Validate(): ValidationResult;
@@ -89,14 +137,26 @@ export declare class MJUserRoleEntityServer extends MJUserRoleEntity {
      */
     Save(options?: EntitySaveOptions): Promise<boolean>;
     /**
-     * Invariant 3 — a non-Owner may only revoke a role they hold themselves.
+     * Enforces both guards on the delete path.
+     *
+     * Guard A, invariant 3 — a non-Owner may only revoke a role they hold themselves.
+     *
+     * Guard B — refuses REMOVING a role from the system user when that would cost the account its
+     * field access. The mirror of the assignment guard, and needed for the same reason the
+     * field-permission subclass guards its own delete path: the system user's access is ordinary
+     * `Allow` rows, and taking a role away drops that role's rows out of the aggregate. If the
+     * remaining roles have `No Access` on a field, the last removal denies it — with no `Deny`
+     * written anywhere and no field-permission row touched. It permits the removal when it also
+     * costs the account its entity-level read, since it is then denied one level up and field rules
+     * decide nothing — which is why the projection re-evaluates the entity ceiling too, rather than
+     * only the field rules.
      *
-     * Reports the refusal the way `MJUserEntityServer.Delete` does — a `BaseEntityResult` on the
+     * Reports refusals the way `MJUserEntityServer.Delete` does — a `BaseEntityResult` on the
      * result history, so `LatestResult.CompleteMessage` carries the reason, `Delete()` returning
      * `false` on a logical rejection rather than throwing (the CLAUDE.md Save/Delete error-handling
      * contract). Note that `SyncRolesUsersResolver.SyncUserRoles` treats a `false` from this method
      * as a hard error and throws, rolling its transaction back; that mutation runs as the system
-     * Owner, so it is exempt and never sees this refusal on a default install.
+     * Owner, so it is exempt from guard A and never sees that refusal on a default install.
      */
     Delete(options?: EntityDeleteOptions): Promise<boolean>;
     /**
@@ -140,7 +200,44 @@ export declare class MJUserRoleEntityServer extends MJUserRoleEntity {
      *
      * Reads `ActiveUser` rather than `ContextCurrentUser` directly so a per-request provider's
      * `CurrentUser` is honored on multi-provider servers.
+     *
+     * Applies to guard A only. Guard B has no Owner exemption — see `Validate()`.
      */
     private callerIsOwner;
+    /**
+     * Why this role may not be taken off this user, or null when it may.
+     * Only ever rejects for the system user; every other user is unaffected.
+     */
+    private systemUserRoleRemovalReason;
+    /**
+     * Why this role may not be given to this user, or null when it may.
+     * Only ever rejects for the system user; every other user is unaffected.
+     */
+    static SystemUserRejectionReason(userID: string | null, roleID: string | null, provider?: IMetadataProvider): string | null;
+    /**
+     * Names of entities where this role carries at least one RESTRICTING field rule — a `Deny`
+     * on any verb. Walks cached metadata only — no database access. Runs only when the system
+     * user is the save target, which is rare.
+     *
+     * Grants and neutrals are ignored, and must be: the system user holds the standard roles
+     * (UI, Developer, Integration), snapshot initialization writes those roles `Allow` rows on
+     * every entity they can read, and field security has no runtime exemption to fall back on.
+     * A guard that counted any rule at all would refuse to reassemble the system user's own role
+     * set the moment field security was enabled anywhere.
+     *
+     * Deliberately does NOT gate on {@link EntityInfo.EnableFieldLevelSecurity}, even though
+     * rules on a disabled entity are inactive and gating would be the cheaper walk. Gating
+     * would leave the two halves of this guard unable to compose, and the gap is reachable in
+     * three ordinary steps: disable field security on an entity, assign the role (now carrying
+     * no active rules) to the system user, re-enable. Each step is permitted and the end state
+     * is the one both guards exist to prevent. Disabling preserves rules so re-enabling does
+     * not lose them, so a rule on a disabled entity is dormant rather than gone.
+     */
+    private static EntitiesWithRestrictingFieldRulesForRole;
 }
+/**
+ * Loader stub — prevents the class from being tree-shaken out of the bundle. Mirrors the
+ * pattern used by the other server-side entity subclasses in this package.
+ */
+export declare function LoadMJUserRoleEntityServer(): void;
 //# sourceMappingURL=MJUserRoleEntityServer.server.d.ts.map

package/dist/custom/MJUserRoleEntityServer.server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MJUserRoleEntityServer.server.d.ts","sourceRoot":"","sources":["../../src/custom/MJUserRoleEntityServer.server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgC,mBAAmB,EAAE,iBAAiB,EAAsD,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAElL,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,qBACa,sBAAuB,SAAQ,gBAAgB;IACxC,QAAQ,IAAI,gBAAgB;IAiB5C;;;;;;OAMG;IACmB,IAAI,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IAWzE;;;;;;;;;OASG;IACmB,MAAM,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAW7E;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAOxB;;;;;;;;;OASG;IACH,OAAO,CAAC,qBAAqB;IAqB7B,4GAA4G;IAC5G,OAAO,CAAC,MAAM;IAWd;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAQvB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,aAAa;CAOxB"}
+{"version":3,"file":"MJUserRoleEntityServer.server.d.ts","sourceRoot":"","sources":["../../src/custom/MJUserRoleEntityServer.server.ts"],"names":[],"mappings":"AAAA,OAAO,EAGH,mBAAmB,EAEnB,iBAAiB,EACjB,iBAAiB,EAMjB,gBAAgB,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6HG;AACH,qBACa,sBAAuB,SAAQ,gBAAgB;IACxC,QAAQ,IAAI,gBAAgB;IAgC5C;;;;;;OAMG;IACmB,IAAI,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IAWzE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACmB,MAAM,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAiB7E;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAOxB;;;;;;;;;OASG;IACH,OAAO,CAAC,qBAAqB;IAqB7B,4GAA4G;IAC5G,OAAO,CAAC,MAAM;IAWd;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAQvB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,aAAa;IAQrB;;;OAGG;IACH,OAAO,CAAC,2BAA2B;IAqBnC;;;OAGG;WACW,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,CAAC,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI;IAyBlI;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,MAAM,CAAC,wCAAwC;CAe1D;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD"}