@memberjunction/generic-database-provider 6.1.0-edge.6 → 6.1.0

package/dist/systemUserFieldAccess.js

@@ -0,0 +1,198 @@
+/**
+ * @fileoverview Keeping the MJ system user's own field access intact, now that field-level
+ * security has no runtime exemption for anybody.
+ *
+ * ## Why this file exists
+ *
+ * The system user is the account the server runs its own work as. It pre-warms the shared engine
+ * caches at startup, and in task mode (job and agent runners) engines instead load on first touch,
+ * so whichever caller gets there first configures the engine for the whole process. Those caches
+ * are process-wide. A system user that cannot read a column therefore does not just fail its own
+ * query — it leaves a partially loaded record in a cache every later user reads, with nothing at
+ * the point of failure pointing back at the permission row that caused it.
+ *
+ * Field security deliberately has **no exempt user** at runtime: `GetUserFieldPermissions` has no
+ * identity branch at all, and the system user's access comes from ordinary `Allow` rows that
+ * snapshot initialization writes for the standard roles it holds. That is a better design — an
+ * administrator can see the rows and reason about them, where a code bypass is invisible exactly
+ * where access is decided. But it moves the burden here: something has to stop those rows being
+ * taken away.
+ *
+ * ## Why "does this rule contain a Deny?" is not enough
+ *
+ * Whether a change restricts a user is a property of the **aggregate across every role they
+ * hold**, never of one rule in isolation. Three ways to lock the system user out without writing
+ * a single `Deny`:
+ *
+ * 1. set `ReadAccess = 'No Access'` on each of its roles in turn — every save individually
+ *    harmless, the last one leaves no `Allow` standing;
+ * 2. delete its roles' `Allow` rows;
+ * 3. reach either state through direct SQL, which no entity-layer guard sees at all.
+ *
+ * So the save-time guard evaluates the **projected aggregate** — the rules as they would stand
+ * after the proposed change — and {@link FindSystemUserFieldAccessViolations} sweeps for state
+ * that got there by some other route.
+ *
+ * @module @memberjunction/generic-database-provider
+ */
+import { EntityFieldInfo, UserInfo, } from '@memberjunction/core';
+import { UUIDsEqual } from '@memberjunction/global';
+import { UserCache } from './UserCache.js';
+/**
+ * Why a proposed field-permission state would leave the MJ system user short of its entity-level
+ * access, or null when it would not.
+ *
+ * Callers pass the rules **as they would be after** their change — with the edited row's new
+ * values substituted, or the deleted row removed. Classifying the changed row on its own cannot
+ * answer this question; see the module comment.
+ *
+ * Answers null (permits the change) in three cases, each deliberate:
+ *
+ * - **No system user resolves.** A cold `UserCache` is the normal state during a process's own
+ *   bootstrap. Blocking an administrator on missing state would be worse than the risk, and
+ *   {@link FindSystemUserFieldAccessViolations} runs at startup precisely to catch whatever slips
+ *   through here.
+ * - **The field is unrestrictable.** Primary keys, `__mj_` columns and the security-configuration
+ *   entities are forced open by the aggregation regardless of any row, so no rule about them can
+ *   restrict anyone.
+ * - **The system user has no entity-level read.** It is already denied one level up, where the
+ *   entity permission check has no exemption either, so field rules change nothing for it here.
+ *
+ * Note this does NOT gate on `EnableFieldLevelSecurity`. Rules on a disabled entity are dormant
+ * rather than gone — disabling deliberately preserves them — so gating would leave a three-step
+ * hole: disable, strip the system user's rows, re-enable.
+ *
+ * @param entity the entity the field belongs to
+ * @param field the field whose rules are changing
+ * @param projectedRules every rule that would bind to this field after the change
+ */
+export function SystemUserFieldAccessLossReason(entity, field, projectedRules) {
+    if (!entity || !field) {
+        return null;
+    }
+    const systemUser = resolveSystemUser();
+    if (!systemUser) {
+        return null;
+    }
+    if (field.IsUnrestrictableField || field.IsOnUnrestrictableEntity) {
+        return null;
+    }
+    const lost = lostVerb(entity, field, projectedRules, systemUser);
+    if (!lost) {
+        return null;
+    }
+    return (`This change would leave the MJ system user unable to ${lost} field '${field.Name}' on ` +
+        `'${entity.Name}'. The server runs background work as that account and shares one engine cache ` +
+        `across all users, so restricting it would let partially loaded records reach everyone. ` +
+        `Field security has no exempt user — the system user's access comes from these rows — so at ` +
+        `least one role it holds must keep 'Allow' here. Apply this rule to a different role, or ` +
+        `remove the role from the system user first.`);
+}
+/**
+ * Every field on an FLS-enabled entity that the system user cannot fully use.
+ *
+ * The backstop for state the save-time guard never saw: direct SQL, a migration, or a save made
+ * while the user cache was cold. Walks loaded metadata only — no queries — and skips entities with
+ * field security switched off, which is nearly all of them.
+ *
+ * @param provider the provider whose metadata to walk
+ * @param systemUser the account to check; defaults to the user cache's system user
+ * @param options optional projection — see {@link SystemUserFieldAccessSweepOptions}
+ */
+export function FindSystemUserFieldAccessViolations(provider, systemUser, options = {}) {
+    const resolved = systemUser ?? resolveSystemUser();
+    if (!provider || !resolved) {
+        return [];
+    }
+    const user = options.WithoutRoleID ? projectUserWithoutRole(resolved, options.WithoutRoleID) : resolved;
+    const violations = [];
+    for (const entity of provider.Entities ?? []) {
+        if (!entity.EnableFieldLevelSecurity) {
+            continue; // dormant rules cannot restrict anything
+        }
+        for (const field of entity.Fields) {
+            if (field.IsUnrestrictableField || field.IsOnUnrestrictableEntity) {
+                continue;
+            }
+            const lost = lostVerb(entity, field, field.FieldPermissions, user);
+            if (lost) {
+                violations.push({ EntityName: entity.Name, FieldName: field.Name, Verb: lost });
+            }
+        }
+    }
+    return violations;
+}
+/**
+ * Which verb the system user would lose relative to its ENTITY-level access, or null.
+ *
+ * Compared against the entity-level ceiling rather than against "all three verbs" on purpose. The
+ * snapshot mirrors entity permissions, so a role holding only entity read legitimately produces
+ * `Allow / No Access / No Access`. Demanding update and create unconditionally would make that
+ * ordinary, correct state look like a violation and refuse the very rows the guard exists to
+ * protect.
+ */
+function lostVerb(entity, field, rules, systemUser) {
+    const entityAccess = entity.GetUserPermisions(systemUser);
+    if (!entityAccess?.CanRead) {
+        return null; // already denied one level up; field rules add nothing
+    }
+    const after = EntityFieldInfo.AggregateFieldRulesForUser(rules, systemUser);
+    if (!after.CanRead) {
+        return 'read';
+    }
+    // A read-only field cannot be written through the API by ANY user — it is excluded from the
+    // generated create input and from the update SET list — so the write verbs decide nothing on
+    // it and their absence costs the system user nothing. Reconciliation deliberately authors
+    // `No Access` there rather than an inert `Allow`; without this the guard would read that as
+    // lost access and report every joined display column on an FLS-enabled entity as a violation.
+    if (field.ReadOnly) {
+        return null;
+    }
+    if (entityAccess.CanUpdate && !after.CanUpdate) {
+        return 'update';
+    }
+    if (entityAccess.CanCreate && !after.CanCreate) {
+        return 'create';
+    }
+    return null;
+}
+/**
+ * Whether the MJ system user holds the given role.
+ *
+ * The cheap pre-check for the save-time guard. Field aggregation only ever consults rules bound to
+ * a role the user holds, so a change to any other role's rule provably cannot move the system
+ * user's access — which lets callers skip the work of projecting and re-aggregating for the
+ * overwhelming majority of permission edits.
+ *
+ * False on a cold cache, matching {@link SystemUserFieldAccessLossReason}'s posture: with no system
+ * user to reason about there is nothing to protect, and the startup sweep is the backstop.
+ */
+export function SystemUserHoldsRole(roleID) {
+    if (!roleID) {
+        return false;
+    }
+    const systemUser = resolveSystemUser();
+    return !!systemUser?.UserRoles?.some(ur => UUIDsEqual(ur.RoleID, roleID));
+}
+/**
+ * A copy of the user holding every role except `roleID`.
+ *
+ * `UserRoles` is a read-only accessor over a private backing field, so this rebuilds through the
+ * constructor rather than mutating. `copyInitData` skips accessors (it only assigns own
+ * properties), and the constructor then seeds the backing field from `initData.UserRoles` — so the
+ * filtered list is what the projection ends up holding.
+ */
+function projectUserWithoutRole(user, roleID) {
+    // No provider: `UserInfo` only stores it for lookups this projection never performs, and the
+    // aggregation reads nothing but `UserRoles`.
+    return new UserInfo(undefined, {
+        ...user,
+        UserRoles: (user.UserRoles ?? []).filter(ur => !UUIDsEqual(ur.RoleID, roleID)),
+    });
+}
+/** The system user, or null when the cache is cold. Never throws. */
+function resolveSystemUser() {
+    const user = UserCache.Instance?.GetSystemUser?.();
+    return user?.UserRoles?.length ? user : null;
+}
+//# sourceMappingURL=systemUserFieldAccess.js.map

package/dist/systemUserFieldAccess.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"systemUserFieldAccess.js","sourceRoot":"","sources":["../src/systemUserFieldAccess.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EACH,eAAe,EAIf,QAAQ,GACX,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAY3C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,+BAA+B,CAC3C,MAAqC,EACrC,KAAyC,EACzC,cAAqD;IAErD,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,MAAM,UAAU,GAAG,iBAAiB,EAAE,CAAC;IACvC,IAAI,CAAC,UAAU,EAAE,CAAC;QACd,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,IAAI,KAAK,CAAC,qBAAqB,IAAI,KAAK,CAAC,wBAAwB,EAAE,CAAC;QAChE,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,UAAU,CAAC,CAAC;IACjE,IAAI,CAAC,IAAI,EAAE,CAAC;QACR,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,OAAO,CACH,wDAAwD,IAAI,WAAW,KAAK,CAAC,IAAI,OAAO;QACxF,IAAI,MAAM,CAAC,IAAI,iFAAiF;QAChG,yFAAyF;QACzF,6FAA6F;QAC7F,0FAA0F;QAC1F,6CAA6C,CAChD,CAAC;AACN,CAAC;AAgBD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mCAAmC,CAC/C,QAA8C,EAC9C,UAA4B,EAC5B,UAA6C,EAAE;IAE/C,MAAM,QAAQ,GAAG,UAAU,IAAI,iBAAiB,EAAE,CAAC;IACnD,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ,EAAE,CAAC;QACzB,OAAO,EAAE,CAAC;IACd,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,sBAAsB,CAAC,QAAQ,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IAExG,MAAM,UAAU,GAAqC,EAAE,CAAC;IACxD,KAAK,MAAM,MAAM,IAAI,QAAQ,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;QAC3C,IAAI,CAAC,MAAM,CAAC,wBAAwB,EAAE,CAAC;YACnC,SAAS,CAAC,yCAAyC;QACvD,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAChC,IAAI,KAAK,CAAC,qBAAqB,IAAI,KAAK,CAAC,wBAAwB,EAAE,CAAC;gBAChE,SAAS;YACb,CAAC;YACD,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;YACnE,IAAI,IAAI,EAAE,CAAC;gBACP,UAAU,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACpF,CAAC;QACL,CAAC;IACL,CAAC;IACD,OAAO,UAAU,CAAC;AACtB,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,QAAQ,CACb,MAAkB,EAClB,KAAsB,EACtB,KAA4C,EAC5C,UAAoB;IAEpB,MAAM,YAAY,GAAG,MAAM,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC;IAC1D,IAAI,CAAC,YAAY,EAAE,OAAO,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,CAAC,uDAAuD;IACxE,CAAC;IAED,MAAM,KAAK,GAAG,eAAe,CAAC,0BAA0B,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IAC5E,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACjB,OAAO,MAAM,CAAC;IAClB,CAAC;IACD,4FAA4F;IAC5F,6FAA6F;IAC7F,0FAA0F;IAC1F,4FAA4F;IAC5F,8FAA8F;IAC9F,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,IAAI,YAAY,CAAC,SAAS,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;QAC7C,OAAO,QAAQ,CAAC;IACpB,CAAC;IACD,IAAI,YAAY,CAAC,SAAS,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;QAC7C,OAAO,QAAQ,CAAC;IACpB,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAiC;IACjE,IAAI,CAAC,MAAM,EAAE,CAAC;QACV,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,MAAM,UAAU,GAAG,iBAAiB,EAAE,CAAC;IACvC,OAAO,CAAC,CAAC,UAAU,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,sBAAsB,CAAC,IAAc,EAAE,MAAc;IAC1D,6FAA6F;IAC7F,6CAA6C;IAC7C,OAAO,IAAI,QAAQ,CAAC,SAAS,EAAE;QAC3B,GAAG,IAAI;QACP,SAAS,EAAE,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACjF,CAAC,CAAC;AACP,CAAC;AAED,qEAAqE;AACrE,SAAS,iBAAiB;IACtB,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,EAAE,aAAa,EAAE,EAAE,CAAC;IACnD,OAAO,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACjD,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/generic-database-provider",
   "type": "module",
-  "version": "6.1.0-edge.6",
+  "version": "6.1.0",
   "description": "Shared database provider logic for MemberJunction — intermediate base class between DatabaseProviderBase and platform-specific providers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,19 +16,19 @@
     "vitest": "^3.1.1"
   },
   "dependencies": {
-    "@memberjunction/actions": "6.1.0-edge.6",
-    "@memberjunction/actions-base": "6.1.0-edge.6",
-    "@memberjunction/ai-vectors-memory": "6.1.0-edge.6",
-    "@memberjunction/aiengine": "6.1.0-edge.6",
-    "@memberjunction/core": "6.1.0-edge.6",
-    "@memberjunction/core-entities": "6.1.0-edge.6",
-    "@memberjunction/encryption": "6.1.0-edge.6",
-    "@memberjunction/geo-core": "6.1.0-edge.6",
-    "@memberjunction/global": "6.1.0-edge.6",
-    "@memberjunction/query-processor": "6.1.0-edge.6",
-    "@memberjunction/sql-dialect": "6.1.0-edge.6",
-    "@memberjunction/sql-parser": "6.1.0-edge.6",
-    "@memberjunction/queue": "6.1.0-edge.6",
+    "@memberjunction/actions": "6.1.0",
+    "@memberjunction/actions-base": "6.1.0",
+    "@memberjunction/ai-vectors-memory": "6.1.0",
+    "@memberjunction/aiengine": "6.1.0",
+    "@memberjunction/core": "6.1.0",
+    "@memberjunction/core-entities": "6.1.0",
+    "@memberjunction/encryption": "6.1.0",
+    "@memberjunction/geo-core": "6.1.0",
+    "@memberjunction/global": "6.1.0",
+    "@memberjunction/query-processor": "6.1.0",
+    "@memberjunction/sql-dialect": "6.1.0",
+    "@memberjunction/sql-parser": "6.1.0",
+    "@memberjunction/queue": "6.1.0",
     "sql-formatter": "^15.7.0",
     "uuid": "^13.0.0"
   },