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

package/dist/custom/MJUserEntityServer.server.js

@@ -0,0 +1,335 @@
+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;
+};
+import { BaseEntity, BaseEntityResult, ValidationErrorInfo, ValidationErrorType } from '@memberjunction/core';
+import { RegisterClass, UUIDsEqual } from '@memberjunction/global';
+import { MJUserEntity } from '@memberjunction/core-entities';
+/**
+ * Server-side `MJ: Users` entity enforcing MJ's privilege-elevation invariant (issue #4260).
+ *
+ * WHY THIS EXISTS AT ALL. `User.Type` is the column every Owner check in the platform reads —
+ * `SqlLoggingConfigResolver`, magic-link `canIssueInvites`, the backup-system-user fallback in
+ * MJServer's bootstrap. Writing it is therefore equivalent to granting yourself the platform's
+ * superuser level. Nothing below this class stops that: on the baseline seed the `Developer` and
+ * `Integration` roles hold unfiltered `CanCreate`/`CanUpdate`/`CanDelete` on `MJ: Users` (verified
+ * against a live database, not just the seed), `AllowUpdateAPI`/`AllowDeleteAPI` are true on the
+ * entity, `AllowUpdateAPI` is also true on both the `Type` and `Name` fields, `Name` has no unique
+ * index, and CodeGen has already issued `GRANT EXECUTE` on the relevant stored procedures to those
+ * roles' DB roles.
+ *
+ * WHY NOT ROW-LEVEL SECURITY. MJ's only field-adjacent access control is `RowLevelSecurityFilter`,
+ * and an "own row only" update filter does NOT close this: scoping the update to the caller's own
+ * row still permits setting one's OWN `Type` to `'Owner'`. There is no per-role FIELD permission in
+ * MJ, and setting `EntityField.AllowUpdateAPI = 0` on `Type` would block Owners too, breaking every
+ * legitimate admin path. An invariant in the save/delete path is the only mechanism that expresses
+ * the actual rule.
+ *
+ * WHY HERE RATHER THAN IN A RESOLVER. `Validate()` runs inside `BaseEntity.Save()` and this class
+ * also overrides `Save()` and `Delete()`, so all five hold on every write path — GraphQL resolvers,
+ * Remote Operations, the Create/Update/Delete Record actions, metadata sync, one-off scripts — and
+ * for any role a deployment invents, not just the two seeded ones. A resolver-level check would
+ * cover one door in a building with several.
+ *
+ * The `Save()` override is what makes that sentence literally true rather than nearly true.
+ * `Validate()` alone does NOT cover every write path: `BaseEntity.Save()` force-passes validation
+ * without calling `Validate()` when `EntitySaveOptions.ReplayOnly` is set (`baseEntity.ts:3725`),
+ * and `ReplayOnly` does not suppress the write. Invariants 1-4 were therefore skippable by an
+ * option, while invariant 5 was not — `Delete()` being an override. See `Save()` below for the
+ * reachability analysis and why the fix refuses rather than re-validates.
+ *
+ * THE INVARIANTS, for a caller whose `Type` is not `'Owner'`:
+ *
+ *   1. **Creating a `MJ: Users` row at all is refused.** This is stricter than "may not create an
+ *      Owner": there are FOUR automated creators of this entity — `NewUserBase.createNewUser`
+ *      (`MJServer/src/auth/newUsers.ts`), `MagicLinkService`'s provisioning path
+ *      (`MJServer/src/auth/magicLink/MagicLinkService.ts`), and `CreateNewUserBase.createNewUser`
+ *      (`CodeGenLib/src/Misc/createNewUser.ts:33`, a CLI provisioning tool that sets `Type='Owner'`
+ *      unconditionally at `:39` — already refused for a non-Owner caller before this round,
+ *      regardless of the analysis below). The first two run as `ResolveConfiguredPrincipal(...)`,
+ *      whose ladder is: rung 1 matches the configured string against `User.Name`, rung 2 against
+ *      `User.Email` — NEITHER rung filters by `Type` (`MJServer/src/auth/principals.ts:134,141`) —
+ *      and only rungs 3-4 (System-by-ID, then lowest-ID-among-ACTIVE-Owners) guarantee an Owner.
+ *      So "no legitimate path creates a user row as a non-Owner" is NOT unconditional: it holds
+ *      only while a deployment's `contextUserForNewUserCreation` / `contextUserForProvisioning`
+ *      names an Owner-type user's `Name` or `Email` (the shipped default, `not.set@nowhere.com`,
+ *      resolves by Email to the seeded Owner, so default installs are unaffected). A deployment
+ *      that instead points either setting at a non-Owner user will have JWT auto-provisioning and
+ *      magic-link provisioning fail CLOSED at `Save()` after this change — loudly, not silently —
+ *      rather than continuing to create rows as that non-Owner; see the changeset for the upgrade
+ *      note. Separately, Explorer's user-management UI has NO Owner gate today (no such guard
+ *      exists in `user-management.component.ts` or its module), so a Developer-role non-Owner
+ *      reaches it in practice and will now receive this same create/delete refusal there — a real
+ *      consequence for such deployments, not a hypothetical one.
+ *      A FOURTH creator exists and is not config-driven: `SyncRolesUsersResolver.AddNewUsers`
+ *      (`MJServer/src/resolvers/SyncRolesUsersResolver.ts:343`), whose sibling `UpdateExistingUsers`
+ *      also sets `Name` AND `Type` unconditionally on every synced row and whose `DeleteSingleUser`
+ *      deletes. All three carry `@RequireSystemUser()`, and `getSystemUser()` resolves the seeded
+ *      `Type='Owner'` system user, so the guard exempts them on a default install — but a deployment
+ *      whose system user is NOT an Owner will see that sync path fail closed too, for the same
+ *      reason as the config-driven pair above. Note also that `DeleteSingleUser` reads a `false`
+ *      from `Delete()` as an FK-constraint condition and downgrades to a soft delete; invariant 5
+ *      gives that same `false` a second meaning (non-Owner caller), which that call site does not
+ *      distinguish.
+ *      Refusing only `Type='Owner'` on create is NOT enough on its own: `Name` has no unique index
+ *      and both seeded non-Owner roles hold `CanCreate`, so a non-Owner could otherwise repeatedly
+ *      `Create` rows named to match the configured principal string until one sorts below the real
+ *      system user by ID — the exact principal-redirection invariant 4 (below) exists to prevent,
+ *      just reached through INSERT instead of UPDATE.
+ *   2. `Type` may not be changed on an EXISTING row. It is a two-value CHECK column
+ *      (`'User' | 'Owner'`), so any change by a non-Owner is either self-promotion or demoting
+ *      somebody else. (Creation is already covered by invariant 1, so this only needs to consider
+ *      updates.)
+ *   3. The row must be the caller's own, compared against the PRE-SAVE `ID`. `ID` is a primary-key
+ *      field — `EntityFieldInfo.ReadOnly` is `true` for `IsPrimaryKey`, and `EntityField.Value`'s
+ *      setter silently ignores writes to a `ReadOnly` field after the record's initial hydration —
+ *      so on a genuinely LOADED row `this.ID` is not reassignable through ordinary means. The
+ *      pre-save value still matters for a narrower reason: it ties this guard to the row identity
+ *      established the last time the object was actually loaded/hydrated from the database, which
+ *      is what `ResolverBase.UpdateRecord` does first for any entity with `TrackRecordChanges=1`
+ *      (as `MJ: Users` has) — rather than trusting whatever the in-memory object merely arrived
+ *      holding. If that pre-save identity cannot be established at all, the guard fails CLOSED
+ *      (refuses the save) instead of silently permitting it — see `validateOwnRowOnly`.
+ *   4. `Name` may not be changed on an existing row. Invariants 2-3 do NOT cover this — renaming
+ *      yourself is editing your own row. `resolvePrincipalFrom` (MJServer `auth/principals.ts`)
+ *      resolves `contextUserForNewUserCreation` / `contextUserForProvisioning` /
+ *      `contextUserForLookup` against `User.Name` FIRST, breaking ties by lowest ID, so a user
+ *      who can rename themselves to the configured string and who sorts below the real system
+ *      user becomes the principal the server acts as. That ordering is deliberate (backward
+ *      compatibility) and is only sound while `Name` is not writable by untrusted parties; this
+ *      invariant is what makes that true. `Name` is the login identifier — auto-provisioning sets
+ *      `Name = email` — while `FirstName` / `LastName` / `Title` are the display fields and stay
+ *      freely editable.
+ *      `Email` is the ladder's OTHER rung (`principals.ts:141`) with the IDENTICAL lack of a `Type`
+ *      filter, and is deliberately left mutable here — not overlooked. Two things narrow it: (a)
+ *      `MJ: Users.Email` carries the database's `UQ_User_Email` unique constraint, so redirecting
+ *      the Email rung to your own row requires the configured candidate to match NO active user at
+ *      all — already the misconfiguration case this file's docs (and `resolvePrincipalFrom`'s own
+ *      per-redeem logging) already surface loudly, not a quiet success path; and (b) even granting
+ *      that misconfiguration, invariants 1 and 3 mean the payoff is no longer elevation: whatever
+ *      row a provisioning path resolves its principal to, THIS guard still checks that resolved
+ *      principal's actual `Type` before permitting the write it is attempting, so a non-Owner who
+ *      gets themselves matched by the Email rung still cannot create or promote anything through
+ *      it — the provisioning operation that would have run as them instead fails CLOSED. Freezing
+ *      `Email` too would add friction to an already-narrow, already-loud misconfiguration path
+ *      without closing any route that is still open.
+ *   5. **Deleting a `MJ: Users` row at all is refused** (see the `Delete()` override below). MJ
+ *      deactivates users via `IsActive`; it does not delete them. An unguarded delete would let a
+ *      non-Owner remove ANY account — Owners included, which destroys the very accounts every
+ *      exemption above depends on.
+ *
+ * Owner-type callers are exempt from all five — CONDITIONALLY on the deployment's own configuration
+ * keeping `contextUserForNewUserCreation` / `contextUserForProvisioning` pointed at an Owner (see
+ * invariant 1 above for why that is not automatic). Provided it is, this keeps admin user management
+ * working, and it keeps auto-provisioning working — `NewUserBase.createNewUser` runs as
+ * `contextUserForNewUserCreation`, which resolves to the seeded system user (`Type='Owner'`) under
+ * the shipped default.
+ * A caller-less save (no `ActiveUser` at all — e.g. a system/CLI path running under a bound provider
+ * default) is likewise treated as exempt, though for `Save()` this is effectively decorative:
+ * `BaseEntity.CheckPermissions` already throws on a falsy `ActiveUser` and runs BEFORE `Validate()`
+ * inside `Save()`, so in production a caller-less `Save()` never reaches this guard's `Validate()`
+ * body at all — see the "no caller" test for the exact call ordering. `Delete()`'s sequencing is the
+ * OPPOSITE and the "no caller ⇒ exempt" default IS load-bearing there — see `callerIsOwner()`'s
+ * docstring.
+ *
+ * Pure: reads only this record's own field state and the caller. No `RunView`, no provider, no
+ * engine, no I/O — so it costs nothing per save/delete and is unit-testable without a database.
+ */
+let MJUserEntityServer = class MJUserEntityServer extends MJUserEntity {
+    Validate() {
+        const result = super.Validate();
+        if (!this.callerIsOwner()) {
+            if (!this.IsSaved) {
+                this.validateCreateRefused(result);
+            }
+            else {
+                this.validateNoTypeChange(result);
+                this.validateOwnRowOnly(result);
+                this.validateNameImmutable(result);
+            }
+        }
+        result.Success = result.Success && result.Errors.length === 0;
+        return result;
+    }
+    /**
+     * Refuses a `ReplayOnly` save by a non-Owner caller.
+     *
+     * WHY THIS OVERRIDE EXISTS. Invariants 1-4 are enforced in `Validate()`, and `Validate()` is the
+     * one enforcement point `BaseEntity.Save()` can be told to skip: under `EntitySaveOptions.ReplayOnly`
+     * it force-passes validation WITHOUT calling `Validate()` at all (`baseEntity.ts:3725`), and
+     * `ReplayOnly` does NOT suppress the write — the provider only uses it to bypass the
+     * `AllowUpdateAPI`/`AllowCreateAPI` gates before building and executing the SQL
+     * (`databaseProviderBase.ts:1436-1443`). So a `ReplayOnly` save skipped all four Save-side
+     * invariants while invariant 5 stayed enforced, because `Delete()` is an override and an
+     * override cannot be switched off. This restores the symmetry: now neither half depends on the
+     * caller's options.
+     *
+     * NOT CURRENTLY REACHABLE BY AN UNTRUSTED CALLER, and this is deliberately belt-and-braces
+     * rather than a live hole. Every wire path that accepts `ReplayOnly` was enumerated: the
+     * GraphQL `options___`/`DeleteOptionsInput` input exists only on the DELETE mutation (create and
+     * update carry no options input, and `ResolverBase.CreateRecord`/`UpdateRecord` call `Save()`
+     * with none); REST's `EntityCRUDHandler` does accept it, but calls `entity.Validate()`
+     * explicitly before `Save()`, so the guard still runs there; and `graphQLSystemUserClient`
+     * requires the system API key, i.e. a caller who is already superuser. The point is that the
+     * class docstring's "holds on EVERY write path" is a promise a future wire path forwarding save
+     * options would otherwise quietly break — a guard whose protection is one option away from off
+     * is not the guard this file claims to be.
+     *
+     * WHY REFUSE RATHER THAN RE-RUN THE INVARIANTS. Re-running invariants 1-4 here would duplicate
+     * `Validate()`'s logic in a second place that must then be kept in step with it — the exact
+     * duplicated-decision this repo's design rules call out. Refusing outright is smaller and
+     * strictly safer: `ReplayOnly` is a replication/replay facility for trusted sync paths, and a
+     * non-Owner has no legitimate reason to replay writes onto the user table. Owners are exempt,
+     * so replication and admin paths that run as an Owner are unaffected.
+     */
+    async Save(options) {
+        if (options?.ReplayOnly && !this.callerIsOwner()) {
+            return this.refuseSave();
+        }
+        return super.Save(options);
+    }
+    refuseSave() {
+        const result = new BaseEntityResult();
+        result.Success = false;
+        result.Type = this.IsSaved ? 'update' : 'create';
+        result.Message =
+            'Only an Owner may perform a ReplayOnly save on a user record. ReplayOnly bypasses ' +
+                'validation, which is where this entity\'s privilege-elevation invariants are enforced.';
+        result.StartedAt = new Date();
+        result.EndedAt = new Date();
+        this.RegisterResultHistoryEntry(result);
+        return false;
+    }
+    /**
+     * Refuses deletion of any `MJ: Users` row by a non-Owner caller. See invariant 5 above for why:
+     * MJ deactivates users via `IsActive` rather than deleting them, and an unguarded delete would
+     * let a non-Owner remove any account, including Owner accounts this class's other exemptions
+     * depend on.
+     *
+     * Reports the refusal the way `MJListEntityServer.Delete` does for its own row-level DELETE
+     * authorization check — a `BaseEntityResult` on the result history so `LatestResult.CompleteMessage`
+     * carries the reason (`Delete()` returns `false` on a logical rejection rather than throwing; see
+     * the CLAUDE.md Save/Delete error-handling contract) — rather than `MJUserRoutineEntityServer`'s
+     * `Delete()` override, which is FK-cleanup ordering, not an authorization decision, and reports
+     * nothing beyond a bare `false`.
+     */
+    async Delete(options) {
+        if (!this.callerIsOwner()) {
+            return this.refuseDelete();
+        }
+        return super.Delete(options);
+    }
+    refuseDelete() {
+        const result = new BaseEntityResult();
+        result.Success = false;
+        result.Type = 'delete';
+        result.Message =
+            'Only an Owner may delete a user record. MJ deactivates users via IsActive rather than deleting them.';
+        result.StartedAt = new Date();
+        result.EndedAt = new Date();
+        this.RegisterResultHistoryEntry(result);
+        return false;
+    }
+    /**
+     * Invariant 1 — a non-Owner may not create a `MJ: Users` row at all. See the class docstring
+     * for why this is the correct scope (not merely "may not create an Owner"): `Name` has no
+     * unique index, so restricting only `Type='Owner'` on create would leave the INSERT path open
+     * to the same principal-redirection invariant 4 blocks on UPDATE.
+     */
+    validateCreateRefused(result) {
+        // Whole-record refusal, not a field-value problem — no field in this repo's convention
+        // exists for that (surveyed every ValidationErrorInfo call site under custom/*.server.ts;
+        // all attribute to the specific field the value is wrong for). Attributing to 'Type' would
+        // make a form highlight Type for a refusal that has nothing to do with its value; 'ID' is
+        // the closer fit — it is the field that identifies WHICH record is being refused.
+        result.Errors.push(new ValidationErrorInfo('ID', 'Only an Owner may create a user record.', this.ID, ValidationErrorType.Failure));
+    }
+    /**
+     * Invariant 2 — a non-Owner may not change `Type` on an EXISTING row (self-promotion, or
+     * demoting somebody else). Non-Owner creation is refused entirely by `validateCreateRefused`,
+     * so this method only needs to consider updates — `Validate()` only calls it on that branch.
+     */
+    validateNoTypeChange(result) {
+        if (!(this.GetFieldByName('Type')?.Dirty ?? false)) {
+            return;
+        }
+        result.Errors.push(new ValidationErrorInfo('Type', 'Only an Owner may set or change a user\'s Type. Type is the column MJ\'s Owner checks read, ' +
+            'so changing it grants platform-superuser access.', this.Type, ValidationErrorType.Failure));
+    }
+    /**
+     * Invariant 3 — a non-Owner may only modify their own user row, compared against the PRE-SAVE
+     * `ID` (see the class docstring for why the pre-save value is the meaningful comparison here).
+     *
+     * Fails CLOSED: if the pre-save identity cannot be established at all, the save is refused
+     * rather than silently permitted. This is currently unreachable in production only because
+     * `MJ: Users` has `TrackRecordChanges=1`, which forces `ResolverBase.UpdateRecord` to genuinely
+     * load the row from the database before applying edits — but that is an unrelated entity flag,
+     * not a guarantee this class should assume will always hold.
+     */
+    validateOwnRowOnly(result) {
+        const preSaveId = this.GetFieldByName('ID')?.OldValue;
+        if (!preSaveId) {
+            result.Errors.push(new ValidationErrorInfo('ID', 'Could not determine this record\'s pre-save identity, so ownership cannot be verified. ' +
+                'Refusing to save rather than risk permitting an edit to another user\'s row.', preSaveId ?? null, ValidationErrorType.Failure));
+            return;
+        }
+        if (!UUIDsEqual(preSaveId, this.ActiveUser.ID)) {
+            result.Errors.push(new ValidationErrorInfo('ID', 'You may only modify your own user record. Changing another user\'s record requires an Owner.', preSaveId, ValidationErrorType.Failure));
+        }
+    }
+    /**
+     * Invariant 4 — a non-Owner may not change `Name` on an existing row.
+     *
+     * `Name` is the column the context-user ladder resolves against first, so it is effectively a
+     * capability name, not a display name. Non-Owner creation (where auto-provisioning legitimately
+     * sets `Name = email`) is already refused entirely by `validateCreateRefused`, so this method
+     * only runs on updates.
+     *
+     * `Email` is deliberately NOT frozen alongside `Name` — see the class docstring's invariant 4
+     * paragraph for why the ladder's other rung doesn't need the same treatment.
+     */
+    validateNameImmutable(result) {
+        if (!(this.GetFieldByName('Name')?.Dirty ?? false)) {
+            return;
+        }
+        result.Errors.push(new ValidationErrorInfo('Name', 'Only an Owner may change a user\'s Name. Name is the identifier MJ\'s configured-principal ' +
+            'resolution matches against, so changing it can redirect which user the server acts as. ' +
+            'Update FirstName, LastName or Title instead.', this.Name, ValidationErrorType.Failure));
+    }
+    /**
+     * True when the caller is an Owner (or when there is no caller to evaluate — the guard has
+     * nothing to compare against).
+     *
+     * The "no caller ⇒ exempt" default has DIFFERENT reachability for `Save()` vs. `Delete()`:
+     *   - `Save()`: `BaseEntity.CheckPermissions` throws on a falsy `ActiveUser`
+     *     (`baseEntity.ts:4003-4005`) and runs at `baseEntity.ts:3702`, BEFORE `Validate()` is
+     *     called at `baseEntity.ts:3730` — so a caller-less `Save()` never reaches this method at
+     *     all in production. The default is effectively decorative there.
+     *   - `Delete()`: the sequencing is the OPPOSITE. THIS class's `Delete()` override calls
+     *     `callerIsOwner()` as its very first statement, before `super.Delete()` is ever invoked —
+     *     `CheckPermissions` only runs later, INSIDE `super.Delete()` (`baseEntity.ts:4612`). So a
+     *     caller-less `Delete()` call DOES reach this method first, and the "no caller ⇒ exempt"
+     *     default here is load-bearing: it lets the call proceed into `super.Delete()`, where
+     *     `CheckPermissions` is the thing that actually refuses it. If this default were flipped to
+     *     "no caller ⇒ refuse", a caller-less delete would be refused by `refuseDelete()` instead —
+     *     same ultimate outcome (refused), different refusal mechanism and message.
+     *
+     * `Type` is an `NCHAR` column, so it arrives space-padded; casing is normalized for the same
+     * reason `principals.ts` does. Reads `ActiveUser` rather than `ContextCurrentUser` directly so
+     * a per-request provider's `CurrentUser` is honored on multi-provider servers.
+     */
+    callerIsOwner() {
+        const caller = this.ActiveUser;
+        if (!caller) {
+            return true;
+        }
+        return caller.Type?.trim().toLowerCase() === 'owner';
+    }
+};
+MJUserEntityServer = __decorate([
+    RegisterClass(BaseEntity, 'MJ: Users')
+], MJUserEntityServer);
+export { MJUserEntityServer };
+//# sourceMappingURL=MJUserEntityServer.server.js.map

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

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

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

@@ -0,0 +1,146 @@
+import { EntityDeleteOptions, EntitySaveOptions, ValidationResult } from '@memberjunction/core';
+import { MJUserRoleEntity } from '@memberjunction/core-entities';
+/**
+ * Server-side `MJ: User Roles` entity enforcing MJ's role-elevation invariant (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
+ * unguarded: verified against a live database, the `Developer` and `Integration` roles hold
+ * unfiltered `CanCreate`/`CanUpdate`/`CanDelete` on `MJ: User Roles`, `AllowCreateAPI` /
+ * `AllowUpdateAPI` / `AllowDeleteAPI` are all true on the entity, and no server-side subclass
+ * existed — `ClassFactory` resolved the generated `MJUserRoleEntity`, whose `Validate()` knows
+ * nothing about who is calling. Reproduced end to end before this class was written: a caller whose
+ * `Type` is `'User'`, holding only `Developer` and `UI`, inserted a row granting itself
+ * `Integration`; `Validate()` returned `Success=true` and `Save()` returned `true`.
+ *
+ * THE INVARIANT: **a non-Owner may only grant, move or revoke a role they themselves hold.**
+ *
+ * Why that rule and not a stricter one. Unlike `User.Type` — two values, no legitimate non-Owner
+ * write — role assignment has real non-Owner use cases the platform ships with: delegated
+ * administration, IdP/group sync, onboarding automation. The subset rule is the weakest rule that
+ * still closes elevation completely, because it is a CEILING: whatever a non-Owner does through
+ * this entity, the authority they can hand out is authority they already had, so no sequence of
+ * calls lets any caller exceed their own grant. Issue #4282 also floated adding "and may not grant
+ * a role that confers write access to `MJ: Roles`/`MJ: User Roles`". That was considered and
+ * declined: it does not close any elevation the subset rule leaves open (granting a peer a role you
+ * hold is delegation, not escape), it breaks the peer-onboarding case above, and it would require
+ * this guard to read `EntityInfo.Permissions` — trading the purity below for protection that
+ * `MJ: Entity Permissions` (which carries the SAME unfiltered `Developer`/`Integration` grant, and
+ * is a separate, still-open route) would undercut anyway.
+ *
+ * WHY HERE RATHER THAN IN A RESOLVER, and why `Save()`/`Delete()` are overridden alongside
+ * `Validate()`: identical reasoning to `MJUserEntityServer`, and see that file for the full
+ * argument. In short — `Validate()` runs inside `BaseEntity.Save()`, so the rule holds on every
+ * write path (GraphQL resolvers, Remote Operations, the Create/Update/Delete Record actions,
+ * metadata sync, one-off scripts) and for any role a deployment invents; but `BaseEntity.Save()`
+ * force-passes validation WITHOUT calling `Validate()` under `EntitySaveOptions.ReplayOnly`
+ * (`baseEntity.ts:3725`) while still performing the write, and `Delete()` never consults
+ * `Validate()` at all. Overriding all three is what makes "every write path" literal.
+ *
+ * THE INVARIANTS, for a caller whose `Type` is not `'Owner'`:
+ *
+ *   1. **Create** — `RoleID` must name a role the caller holds. This is the #4282 escalation
+ *      itself: the self-grant of an unheld role.
+ *   2. **Update** — the NEW `RoleID` must be held (invariant 1, reached through UPDATE instead of
+ *      INSERT), and so must the PRE-SAVE `RoleID`. The second half is not redundant: moving an
+ *      existing grant off a role you do not hold is a revocation you were not entitled to make,
+ *      and without it a non-Owner could strip an Owner of any role by repointing the row.
+ *      `UserID` is deliberately NOT frozen — moving a grant between users stays within the
+ *      caller's ceiling, which is the whole point of the rule.
+ *   3. **Delete** — the row's `RoleID` must be held by the caller, for the same reason as the
+ *      pre-save half of invariant 2. Revocation is bounded by the same ceiling as granting.
+ *   4. **A `ReplayOnly` save is refused outright**, because `ReplayOnly` is the one option that
+ *      skips `Validate()` and therefore invariants 1-2. Refusing rather than re-running them keeps
+ *      the decision in ONE place; `ReplayOnly` is a replication facility for trusted sync paths and
+ *      a non-Owner has no legitimate reason to replay writes onto the role-assignment table.
+ *
+ * A caller holding NO roles can therefore grant nothing — correct, and it is also why this guard
+ * needs no special case for an unpopulated `UserInfo.UserRoles`: the subset test fails closed on
+ * an empty list on its own. (Server-side that list is populated — `MJServer`'s `context.ts` resolves
+ * the request principal from `UserCache` precisely "to ensure UserRoles is properly populated", and
+ * `CloneUserForSessionContext` carries it onto the per-session clone.)
+ *
+ * NOT COVERED, deliberately: a magic-link session's SYNTHESIZED roles (`context.ts`
+ * `buildMagicLinkSessionUser`) count as roles held, so a scope-limited principal is measured by the
+ * same rule as any other caller. Narrowing scope-limited principals further is a magic-link concern,
+ * not a role-elevation one — `IsScopeLimitedPrincipal` lives in MJServer, which this package cannot
+ * import, and duplicating its predicate here would put one decision in two places. Such a session
+ * still needs `CanCreate` on this entity to reach the guard at all, which the `Magic Link Baseline`
+ * role does not grant.
+ *
+ * Owner-type callers are exempt from all four, so admin role management, and the
+ * `SyncRolesAndUsers` / `SyncUsers` mutations (both `@RequireSystemUser()`, whose `getSystemUser()`
+ * resolves the seeded `Type='Owner'` system user), are unaffected on a default install. A
+ * 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.
+ */
+export declare class MJUserRoleEntityServer extends MJUserRoleEntity {
+    Validate(): ValidationResult;
+    /**
+     * Refuses a `ReplayOnly` save by a non-Owner caller — invariant 4. `ReplayOnly` force-passes
+     * validation without calling `Validate()` (`baseEntity.ts:3725`) yet does not suppress the
+     * write, so without this override invariants 1-2 were one caller-supplied option away from off
+     * while invariant 3 stayed enforced (an override cannot be switched off). Mirrors
+     * `MJUserEntityServer.Save()`, including its reasoning for refusing rather than re-validating.
+     */
+    Save(options?: EntitySaveOptions): Promise<boolean>;
+    /**
+     * Invariant 3 — a non-Owner may only revoke a role they hold themselves.
+     *
+     * Reports the refusal 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.
+     */
+    Delete(options?: EntityDeleteOptions): Promise<boolean>;
+    /**
+     * Invariants 1 and 2's forward half — the role being assigned must be one the caller holds.
+     * Attributed to `RoleID` because that IS the field whose value is refused, so a form highlights
+     * the control the user must change.
+     */
+    private validateRoleHeld;
+    /**
+     * Invariant 2's second half — the role this assignment granted BEFORE the edit must also be one
+     * the caller holds, compared against the pre-save value rather than whatever the in-memory
+     * object arrived holding. `MJ: User Roles` has `TrackRecordChanges=1`, which forces
+     * `ResolverBase.UpdateRecord` to genuinely load the row from the database before applying edits,
+     * so that pre-save value is the row's real prior state on every wire path — but that is an
+     * unrelated entity flag, not a guarantee this class should assume will always hold, so a
+     * pre-save value that cannot be established fails CLOSED with its own message rather than
+     * falling through to "you do not hold role null".
+     */
+    private validatePriorRoleHeld;
+    /** Records a logical refusal on the result history so `LatestResult.CompleteMessage` carries the reason. */
+    private refuse;
+    /**
+     * True when the caller's own role assignments include `roleId`.
+     *
+     * `UUIDsEqual` rather than `===` because role IDs reach this class from two different sources
+     * with two different casings — the cached `UserInfo.UserRoles` and the entity field the client
+     * sent (see `guides/UUID_COMPARISON_GUIDE.md`). A falsy `roleId`, or a caller with no roles,
+     * yields `false`: both are the fail-closed answer, and neither needs a branch of its own.
+     */
+    private callerHoldsRole;
+    /**
+     * True when the caller is an Owner (or when there is no caller to evaluate — the guard has
+     * nothing to compare against). `Type` is an `NCHAR` column, so it arrives space-padded; casing
+     * is normalized for the same reason `MJServer`'s `principals.ts` does.
+     *
+     * The "no caller ⇒ exempt" default has the same asymmetric reachability documented on
+     * `MJUserEntityServer.callerIsOwner()`: `BaseEntity.CheckPermissions` throws on a falsy
+     * `ActiveUser` BEFORE `Validate()` runs inside `Save()`, so the default is decorative there;
+     * in `Delete()` it is load-bearing, letting a caller-less delete proceed into `super.Delete()`
+     * where `CheckPermissions` is what actually refuses it.
+     *
+     * Reads `ActiveUser` rather than `ContextCurrentUser` directly so a per-request provider's
+     * `CurrentUser` is honored on multi-provider servers.
+     */
+    private callerIsOwner;
+}
+//# sourceMappingURL=MJUserRoleEntityServer.server.d.ts.map

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

@@ -0,0 +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"}