@memberjunction/server 6.1.0-edge.5 → 6.1.0-edge.6

package/src/__tests__/principals.callSites.test.ts

@@ -0,0 +1,112 @@
+/**
+ * There is ONE resolver for the three config-named context users — issue #4209, second half.
+ *
+ * The bug was not that a lookup used the wrong column; it was that the lookup was written out by
+ * hand at every consumer. Six copies existed across MJServer in three mutually inconsistent
+ * variants, and two of them could not resolve the value MJ itself ships. `auth/principals.ts`
+ * exists to make that impossible, and this test is what keeps it that way: any file that reads
+ * one of the three settings must go through the ladder rather than growing a fourth variant.
+ *
+ * Source-scanning rather than behavioural because the failure mode is *a new call site*, which no
+ * behavioural test of the existing call sites can see. Same technique as
+ * `AdhocQueryResolver.scopeGuard.test.ts` and `serverExtensionReservedRoots.test.ts`.
+ */
+import { describe, it, expect } from 'vitest';
+import { readdirSync, readFileSync, statSync } from 'fs';
+import { dirname, join, relative, sep } from 'path';
+import { fileURLToPath } from 'url';
+
+const SRC_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+/** The three settings that name a principal in config. `config.ts` DEFINES them; it does not resolve them. */
+const CONTEXT_USER_SETTINGS = [
+    'contextUserForNewUserCreation',
+    'contextUserForProvisioning',
+    'contextUserForLookup',
+] as const;
+
+/**
+ * Files that legitimately mention a setting without resolving it, as paths RELATIVE TO `src/`.
+ * Deliberately not basenames: exempting every file called `config.ts` anywhere under `src/` would
+ * let a future `realtimeWidget/config.ts` hand-roll a lookup and still pass this guard.
+ */
+const NOT_CONSUMERS = ['config.ts', 'auth/principals.ts'];
+
+/** `src/`-relative, forward-slashed, so the assertions below read the same on every platform. */
+function relativeToSrc(absolutePath: string): string {
+    return relative(SRC_ROOT, absolutePath).split(sep).join('/');
+}
+
+function everyTsFileUnder(dir: string): string[] {
+    return readdirSync(dir).flatMap((name) => {
+        const full = join(dir, name);
+        if (statSync(full).isDirectory()) {
+            return name === '__tests__' || name === 'generated' ? [] : everyTsFileUnder(full);
+        }
+        return name.endsWith('.ts') && !name.endsWith('.d.ts') ? [full] : [];
+    });
+}
+
+/** Files that READ one of the settings — i.e. resolve it to a user, rather than declaring it. */
+function consumersOfAContextUserSetting(): { path: string; source: string }[] {
+    return everyTsFileUnder(SRC_ROOT)
+        .filter((p) => !NOT_CONSUMERS.includes(relativeToSrc(p)))
+        .map((path) => ({ path: relativeToSrc(path), source: readFileSync(path, 'utf8') }))
+        .filter(({ source }) => CONTEXT_USER_SETTINGS.some((s) => source.includes(`.${s}`)));
+}
+
+describe('context-user resolution has exactly one implementation', () => {
+    it('finds the known consumers, so the scan itself is not silently matching nothing', () => {
+        const found = consumersOfAContextUserSetting().map((c) => c.path);
+
+        expect(found).toContain('auth/newUsers.ts');
+        expect(found).toContain('auth/magicLink/MagicLinkService.ts');
+    });
+
+    it('routes every consumer through auth/principals.ts', () => {
+        const handRolled = consumersOfAContextUserSetting()
+            .filter(({ source }) => !source.includes('ResolveConfiguredPrincipal'))
+            .map(({ path }) => path);
+
+        expect(handRolled).toEqual([]);
+    });
+
+    it('leaves no consumer matching the setting against a single column by hand', () => {
+        // The two shapes that produced #4209: `UserByName(candidate)` and `u.Email === candidate`.
+        //
+        // Scoped to the statement that READS the setting, not the whole file: MagicLinkService
+        // also resolves the INVITEE by Email (`provisionUser`, ~270 lines away), which is tier-1
+        // identity and correct. A file-wide grep would condemn it, and a guard that cries wolf
+        // gets deleted.
+        const COLUMN_MATCH = /UserByName\s*\(|\.(Email|Name)\b[^\n]*===/;
+        const handRolled = consumersOfAContextUserSetting()
+            .filter(({ source }) =>
+                source.split('\n').some(
+                    (line) => CONTEXT_USER_SETTINGS.some((s) => line.includes(`.${s}`)) && COLUMN_MATCH.test(line),
+                ),
+            )
+            .map(({ path }) => path);
+
+        expect(handRolled).toEqual([]);
+    });
+});
+
+describe('the ladder is reachable by the integrators the example is written for', () => {
+    // `exampleNewUserSubClass.ts` exists to be COPIED into a deployment's own package — its header
+    // says so, and it tells you to uncomment `@RegisterClass` in your code. Now that it resolves
+    // through `ResolveConfiguredPrincipal`, an integrator who copies it needs to be able to import
+    // that. `package.json` publishes only `"."`, so the package index is the whole public surface,
+    // and this guard cannot see downstream code — it can only make sure the door exists.
+    it('exports ResolveConfiguredPrincipal from the package index', () => {
+        const index = readFileSync(join(SRC_ROOT, 'index.ts'), 'utf8');
+
+        expect(index).toMatch(/ResolveConfiguredPrincipal/);
+    });
+
+    it('exports the types a caller needs to hold the result', () => {
+        const index = readFileSync(join(SRC_ROOT, 'index.ts'), 'utf8');
+
+        expect(index).toMatch(/ResolvablePrincipal/);
+        expect(index).toMatch(/PrincipalResolution/);
+    });
+});

package/src/__tests__/principals.logging.test.ts

@@ -0,0 +1,160 @@
+/**
+ * Log policy for context-user resolution — the second half of issue #4209.
+ *
+ * The defect had two costs. One was attribution (covered by principals.test.ts). The other was
+ * volume: because the shipped default could never resolve, EVERY magic-link redeem and EVERY
+ * auto-provisioned user emitted an error-level line, on every host that took the default. Real
+ * errors were buried under it.
+ *
+ * Resolution is a pure function; this file covers the impure shell around it — reading the user
+ * cache and deciding how often a misconfiguration is worth saying out loud.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const { mockLogError, mockUsers, SYSTEM_USER_ID } = vi.hoisted(() => ({
+    mockLogError: vi.fn(),
+    mockUsers: [] as Array<Record<string, unknown>>,
+    SYSTEM_USER_ID: 'ECAFCCEC-6A37-EF11-86D4-000D3A4E707E',
+}));
+
+vi.mock('@memberjunction/core', () => ({
+    LogError: mockLogError,
+    UserInfo: class {},
+}));
+
+vi.mock('@memberjunction/generic-database-provider', () => ({
+    UserCache: {
+        get Users() {
+            return mockUsers;
+        },
+        Instance: {
+            get Users() {
+                return mockUsers;
+            },
+            get SYSTEM_USER_ID() {
+                return SYSTEM_USER_ID;
+            },
+        },
+    },
+}));
+
+/** Stock seed: the system user MJ's own default is aiming at, plus a human Owner. */
+const SYSTEM = { ID: SYSTEM_USER_ID, Name: 'System', Email: 'not.set@nowhere.com', Type: 'Owner          ', IsActive: true };
+const HOST_ADMIN = { ID: 'AAAA1111-0000-0000-0000-000000000001', Name: 'jane.admin@acme.com', Email: 'jane.admin@acme.com', Type: 'Owner', IsActive: true };
+
+/** Fresh module per test: the de-duplication state is module-scoped by design. */
+async function loadSubject() {
+    vi.resetModules();
+    return import('../auth/principals.js');
+}
+
+beforeEach(() => {
+    vi.clearAllMocks();
+    mockUsers.length = 0;
+    mockUsers.push(SYSTEM, HOST_ADMIN);
+});
+
+describe('ResolveConfiguredPrincipal', () => {
+    it('resolves MJ\'s own shipped default without logging anything', async () => {
+        const { ResolveConfiguredPrincipal } = await loadSubject();
+
+        const user = ResolveConfiguredPrincipal('not.set@nowhere.com', 'MagicLink');
+
+        expect(user).toBe(SYSTEM);
+        expect(mockLogError).not.toHaveBeenCalled();
+    });
+
+    it('logs an unresolvable candidate ONCE however many times it is asked for', async () => {
+        const { ResolveConfiguredPrincipal } = await loadSubject();
+
+        for (let i = 0; i < 25; i++) {
+            ResolveConfiguredPrincipal('ghost@nowhere.example', 'MagicLink');
+        }
+
+        expect(mockLogError).toHaveBeenCalledTimes(1);
+    });
+
+    it('names both the purpose and the candidate so the operator can find the setting', async () => {
+        const { ResolveConfiguredPrincipal } = await loadSubject();
+
+        ResolveConfiguredPrincipal('ghost@nowhere.example', 'MagicLink');
+
+        const logged = String(mockLogError.mock.calls[0][0]);
+        expect(logged).toContain('MagicLink');
+        expect(logged).toContain('ghost@nowhere.example');
+    });
+
+    it('still reports a DIFFERENT misconfiguration rather than swallowing it', async () => {
+        const { ResolveConfiguredPrincipal } = await loadSubject();
+
+        ResolveConfiguredPrincipal('ghost@nowhere.example', 'MagicLink');
+        ResolveConfiguredPrincipal('other@nowhere.example', 'MagicLink');
+
+        expect(mockLogError).toHaveBeenCalledTimes(2);
+    });
+
+    it('reports the same candidate separately for a different purpose', async () => {
+        const { ResolveConfiguredPrincipal } = await loadSubject();
+
+        ResolveConfiguredPrincipal('ghost@nowhere.example', 'MagicLink');
+        ResolveConfiguredPrincipal('ghost@nowhere.example', 'Widget');
+
+        expect(mockLogError).toHaveBeenCalledTimes(2);
+    });
+
+    it('does not treat an unset candidate as a misconfiguration', async () => {
+        const { ResolveConfiguredPrincipal } = await loadSubject();
+
+        const user = ResolveConfiguredPrincipal(undefined, 'NewUser');
+
+        expect(user).toBe(SYSTEM);
+        expect(mockLogError).not.toHaveBeenCalled();
+    });
+
+    it('returns null and says so when the deployment offers no principal at all', async () => {
+        mockUsers.length = 0;
+        const { ResolveConfiguredPrincipal } = await loadSubject();
+
+        const user = ResolveConfiguredPrincipal('ghost@nowhere.example', 'MagicLink');
+
+        expect(user).toBeNull();
+        expect(mockLogError).toHaveBeenCalledTimes(1);
+    });
+});
+
+describe('the misconfiguration report stays bounded WITHOUT regressing to per-request logging', () => {
+    it('publishes its bound, so this test cannot silently pass against a different one', async () => {
+        const { MAX_REPORTED_MISCONFIGURATIONS } = await loadSubject();
+
+        expect(typeof MAX_REPORTED_MISCONFIGURATIONS).toBe('number');
+        expect(MAX_REPORTED_MISCONFIGURATIONS).toBeGreaterThan(0);
+    });
+
+    it('still says a NEW misconfiguration exactly once after the bound is reached', async () => {
+        // The bound exists so a caller passing a per-request candidate cannot grow the tracker
+        // forever. But whatever it does at the limit must not be "log every time" — that is
+        // precisely the per-request error line issue #4209 was filed about, reintroduced for the
+        // one caller the bound was added for.
+        const { ResolveConfiguredPrincipal, MAX_REPORTED_MISCONFIGURATIONS } = await loadSubject();
+        expect(typeof MAX_REPORTED_MISCONFIGURATIONS).toBe('number'); // else the loop below is a no-op and this passes for free
+        for (let i = 0; i < MAX_REPORTED_MISCONFIGURATIONS + 5; i++) {
+            ResolveConfiguredPrincipal(`filler-${i}@nowhere.example`, 'MagicLink');
+        }
+        mockLogError.mockClear();
+
+        ResolveConfiguredPrincipal('late@nowhere.example', 'MagicLink');
+        ResolveConfiguredPrincipal('late@nowhere.example', 'MagicLink');
+        ResolveConfiguredPrincipal('late@nowhere.example', 'MagicLink');
+
+        expect(mockLogError).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not grow without bound', async () => {
+        const { ResolveConfiguredPrincipal, ReportedMisconfigurationCount, MAX_REPORTED_MISCONFIGURATIONS } = await loadSubject();
+        for (let i = 0; i < MAX_REPORTED_MISCONFIGURATIONS * 3; i++) {
+            ResolveConfiguredPrincipal(`filler-${i}@nowhere.example`, 'MagicLink');
+        }
+
+        expect(ReportedMisconfigurationCount()).toBeLessThanOrEqual(MAX_REPORTED_MISCONFIGURATIONS);
+    });
+});

package/src/__tests__/principals.test.ts

@@ -0,0 +1,305 @@
+/**
+ * Resolution of an operator-named context user — regression suite for issue #4209.
+ *
+ * MJServer has three settings that name a user in config (`contextUserForNewUserCreation`,
+ * `contextUserForProvisioning`, `contextUserForLookup`). All three were resolved through
+ * `UserCache.UserByName`, which matches `User.Name` — but the shipped default for the first is
+ * `'not.set@nowhere.com'`, an EMAIL. On a stock database the seeded system user is
+ * `Name='System'` / `Email='not.set@nowhere.com'`, so the default names the very user it was
+ * aiming at and can never reach it. Every magic-link redeem logged an error and provisioned
+ * under whichever user happened to sort first as an Owner.
+ *
+ * These tests drive the pure core of the resolver, so they need neither the `UserCache`
+ * singleton nor a database — the seam is `(candidate, users) -> resolution`.
+ */
+import { describe, it, expect } from 'vitest';
+import { resolvePrincipalFrom, type ResolvablePrincipal } from '../auth/principals.js';
+
+/**
+ * The system user's ID, pinned by `UserCache` (`SYSTEM_USER_ID`) and seeded by every baseline.
+ * Spelled in the mixed case the migration writes to prove the match is case-insensitive.
+ */
+const SYSTEM_USER_ID = 'ECAFCCEC-6A37-EF11-86D4-000D3A4E707E';
+
+/**
+ * The shipped default for `userHandling.contextUserForNewUserCreation` — see `src/config.ts`.
+ * It is email-shaped, which is the whole defect: it is matched against `Name`.
+ */
+const SHIPPED_DEFAULT = 'not.set@nowhere.com';
+
+/**
+ * Rows exactly as seeded by `migrations/v5/B202607091514__v5.46.x__Baseline.sql`. `Type` is
+ * `NCHAR(15)`, so the seeded values carry trailing padding — the resolver must trim before
+ * comparing, and these fixtures keep the padding so that stays tested.
+ */
+const SYSTEM: ResolvablePrincipal = {
+    ID: SYSTEM_USER_ID,
+    Name: 'System',
+    Email: 'not.set@nowhere.com',
+    Type: 'Owner          ',
+    IsActive: true,
+};
+
+const ANONYMOUS: ResolvablePrincipal = {
+    ID: '273910DF-28F1-45C1-A8F8-6E9AD8E5F008',
+    Name: 'Anonymous',
+    Email: 'anonymous@magic-link.local',
+    Type: 'User           ',
+    IsActive: true,
+};
+
+/** A human admin, as every real host has: created by MJ, so `Name` IS the email address. */
+const HOST_ADMIN: ResolvablePrincipal = {
+    ID: 'AAAA1111-0000-0000-0000-000000000001',
+    Name: 'jane.admin@acme.com',
+    Email: 'jane.admin@acme.com',
+    Type: 'Owner',
+    IsActive: true,
+};
+
+/** The stock seed plus one human admin — the shape of an ordinary deployment. */
+const STOCK_HOST: ResolvablePrincipal[] = [SYSTEM, ANONYMOUS, HOST_ADMIN];
+
+describe('resolvePrincipalFrom', () => {
+    describe('the shipped default (#4209)', () => {
+        it('resolves the email-shaped default to the seeded System user', () => {
+            const result = resolvePrincipalFrom(SHIPPED_DEFAULT, STOCK_HOST, SYSTEM_USER_ID);
+
+            expect(result.user).toBe(SYSTEM);
+            expect(result.reason).toBe('email');
+        });
+
+        it('reports no warning when the default resolves, so a stock host logs nothing', () => {
+            const result = resolvePrincipalFrom(SHIPPED_DEFAULT, STOCK_HOST, SYSTEM_USER_ID);
+
+            expect(result.warning).toBeUndefined();
+        });
+    });
+
+    describe('attribution determinism', () => {
+        it('resolves identically however the user cache happens to be ordered', () => {
+            // `SELECT * FROM vwUsers` carries no ORDER BY and the cache is mutated in place at
+            // runtime, so row order differs between boots AND within a process. Attribution must
+            // not depend on it: this is what made CreatedByUserID incidental.
+            const ordered = resolvePrincipalFrom(SHIPPED_DEFAULT, STOCK_HOST, SYSTEM_USER_ID);
+            const reversed = resolvePrincipalFrom(SHIPPED_DEFAULT, [...STOCK_HOST].reverse(), SYSTEM_USER_ID);
+
+            expect(reversed.user).toBe(ordered.user);
+        });
+    });
+
+    describe('explicitly configured principals', () => {
+        it('keeps a Name match ahead of another user whose Email is that same string', () => {
+            // The compatibility guarantee: a host that resolves today must resolve to the SAME
+            // user after the Email fallback is added. Name is tried first for exactly this reason.
+            const namedSupport: ResolvablePrincipal = {
+                ID: 'BBBB2222-0000-0000-0000-000000000002',
+                Name: 'support@acme.com',
+                Email: 'someone.else@acme.com',
+                Type: 'User',
+                IsActive: true,
+            };
+            const emailSupport: ResolvablePrincipal = {
+                ID: 'CCCC3333-0000-0000-0000-000000000003',
+                Name: 'Bob Support',
+                Email: 'support@acme.com',
+                Type: 'User',
+                IsActive: true,
+            };
+
+            const result = resolvePrincipalFrom('support@acme.com', [emailSupport, namedSupport], SYSTEM_USER_ID);
+
+            expect(result.user).toBe(namedSupport);
+            expect(result.reason).toBe('name');
+        });
+    });
+
+    describe('duplicate matches resolve deterministically', () => {
+        // `User.Name` carries NO unique constraint. MJ's own rows do not collide — `NewUserBase`
+        // sets `Name = email` and `UQ_User_Email` makes Email unique, so MJ-created Names are
+        // unique BY CONSEQUENCE, not by rule — but a hand-created or externally-synced row can
+        // collide, and then `find()` returns whichever the cache happens to hold first. That is
+        // the same cache-order dependence the Owner rung is sorted to remove, so every rung
+        // resolves ties the same way: lowest ID.
+        const LOW: ResolvablePrincipal = { ID: '11111111-0000-0000-0000-000000000001', Name: 'shared.name', Email: 'low@acme.com', Type: 'User', IsActive: true };
+        const HIGH: ResolvablePrincipal = { ID: 'FFFFFFFF-0000-0000-0000-00000000000F', Name: 'shared.name', Email: 'high@acme.com', Type: 'User', IsActive: true };
+
+        it('picks the lowest-ID user when two users share the configured Name', () => {
+            const result = resolvePrincipalFrom('shared.name', [HIGH, LOW, SYSTEM], SYSTEM_USER_ID);
+
+            expect(result.user).toBe(LOW);
+            expect(result.reason).toBe('name');
+        });
+
+        it('resolves a duplicated Name identically however the cache is ordered', () => {
+            const forward = resolvePrincipalFrom('shared.name', [HIGH, LOW, SYSTEM], SYSTEM_USER_ID);
+            const reversed = resolvePrincipalFrom('shared.name', [SYSTEM, LOW, HIGH], SYSTEM_USER_ID);
+
+            expect(reversed.user).toBe(forward.user);
+        });
+
+        it('applies the same tiebreak to the Email rung', () => {
+            // `UQ_User_Email` should make this unreachable from the database, but `UserCache` is
+            // also written through `SetUsers` and mutated in place by `Users.push`, so the rung
+            // must not depend on the constraint holding in memory.
+            const lowEmail: ResolvablePrincipal = { ...LOW, Name: 'a.person', Email: 'shared@acme.com' };
+            const highEmail: ResolvablePrincipal = { ...HIGH, Name: 'b.person', Email: 'shared@acme.com' };
+
+            const result = resolvePrincipalFrom('shared@acme.com', [highEmail, lowEmail, SYSTEM], SYSTEM_USER_ID);
+
+            expect(result.user).toBe(lowEmail);
+            expect(result.reason).toBe('email');
+        });
+    });
+
+    describe('a DEACTIVATED configured candidate', () => {
+        /**
+         * The case an operator actually hits: the admin whose address sits in
+         * `contextUserForProvisioning` leaves, and their account is deactivated. Every other rung
+         * requires `IsActive`, so without this one the ladder would read "we never act as a
+         * disabled user, except the one the operator named" — and provisioning would keep running,
+         * silently, as someone who no longer works here.
+         */
+        const RETIRED: ResolvablePrincipal = {
+            ID: 'BBBB2222-0000-0000-0000-000000000002',
+            Name: 'departed@acme.com',
+            Email: 'departed@acme.com',
+            Type: 'Owner          ',
+            IsActive: false,
+        };
+
+        it('does not resolve a deactivated candidate by Email', () => {
+            const result = resolvePrincipalFrom('departed@acme.com', [...STOCK_HOST, RETIRED], SYSTEM_USER_ID);
+
+            expect(result.user).toBe(SYSTEM);
+            expect(result.reason).toBe('system');
+        });
+
+        it('does not resolve a deactivated candidate by Name', () => {
+            // The Name rung is the compatibility rung and is tried first, so it needs the guard
+            // most: without it the guarantee holds only for the rungs nobody configures.
+            const renamed: ResolvablePrincipal = { ...RETIRED, Name: 'ops-service-account', Email: 'ops@acme.com' };
+
+            const result = resolvePrincipalFrom('ops-service-account', [...STOCK_HOST, renamed], SYSTEM_USER_ID);
+
+            expect(result.user).toBe(SYSTEM);
+            expect(result.reason).toBe('system');
+        });
+
+        it('reports that the candidate matched but is inactive, not that it matched nothing', () => {
+            const result = resolvePrincipalFrom('departed@acme.com', [...STOCK_HOST, RETIRED], SYSTEM_USER_ID);
+
+            // "matched no user's Name or Email" would send the operator hunting for a typo in a
+            // value that is spelled correctly. The fix here is to reactivate the account or name a
+            // different user, and the message has to point at that one.
+            expect(result.warning).toMatch(/inactive/i);
+            expect(result.warning).not.toMatch(/matched no user/i);
+        });
+
+        it('advances to the next rung rather than stopping at the inactive match', () => {
+            // An inactive Name match must not shadow an ACTIVE Email match. The ladder's job is to
+            // find the user the string names, and at that point it has not run out of places to
+            // look — this is #4209's own shape, with the Name holder deactivated.
+            const inactiveByName: ResolvablePrincipal = {
+                ID: 'CCCC3333-0000-0000-0000-000000000003',
+                Name: 'ops@acme.com',
+                Email: 'old-ops@acme.com',
+                Type: 'User           ',
+                IsActive: false,
+            };
+            const activeByEmail: ResolvablePrincipal = {
+                ID: 'DDDD4444-0000-0000-0000-000000000004',
+                Name: 'Ops Service Account',
+                Email: 'ops@acme.com',
+                Type: 'User           ',
+                IsActive: true,
+            };
+
+            const result = resolvePrincipalFrom('ops@acme.com', [inactiveByName, activeByEmail], SYSTEM_USER_ID);
+
+            expect(result.user).toBe(activeByEmail);
+            expect(result.reason).toBe('email');
+            expect(result.warning).toBeUndefined();
+        });
+    });
+    describe('fallbacks', () => {
+        it('falls back to the System user rather than an arbitrary Owner when the candidate is unresolvable', () => {
+            const result = resolvePrincipalFrom('nobody@nowhere.example', STOCK_HOST, SYSTEM_USER_ID);
+
+            expect(result.user).toBe(SYSTEM);
+            expect(result.reason).toBe('system');
+        });
+
+        it('warns when a configured candidate did not resolve, naming the candidate', () => {
+            const result = resolvePrincipalFrom('nobody@nowhere.example', STOCK_HOST, SYSTEM_USER_ID);
+
+            expect(result.warning).toContain('nobody@nowhere.example');
+        });
+
+        it('falls back to the System user WITHOUT warning when no candidate is configured', () => {
+            // Zod defaults this setting to '', so an unset/blank value must not be reported as a
+            // misconfiguration — but it must still land somewhere deterministic.
+            const result = resolvePrincipalFrom('', STOCK_HOST, SYSTEM_USER_ID);
+
+            expect(result.user).toBe(SYSTEM);
+            expect(result.warning).toBeUndefined();
+        });
+
+        it('picks the lowest-ID active Owner when the deployment has no System user', () => {
+            // Last resort, and still deterministic — never "whichever Owner sorts first in the cache".
+            const laterOwner: ResolvablePrincipal = {
+                ID: 'FFFF9999-0000-0000-0000-000000000009',
+                Name: 'zoe@acme.com',
+                Email: 'zoe@acme.com',
+                Type: 'Owner          ',
+                IsActive: true,
+            };
+            const users = [laterOwner, HOST_ADMIN, ANONYMOUS];
+
+            const result = resolvePrincipalFrom('nobody@nowhere.example', users, SYSTEM_USER_ID);
+
+            expect(result.user).toBe(HOST_ADMIN);
+            expect(result.reason).toBe('owner');
+        });
+
+        it('never returns an inactive user as the Owner fallback', () => {
+            const inactiveOwner: ResolvablePrincipal = {
+                ID: '11111111-0000-0000-0000-000000000000', // sorts first, so only IsActive can exclude it
+                Name: 'retired@acme.com',
+                Email: 'retired@acme.com',
+                Type: 'Owner',
+                IsActive: false,
+            };
+
+            const result = resolvePrincipalFrom('nobody@nowhere.example', [inactiveOwner, HOST_ADMIN], SYSTEM_USER_ID);
+
+            expect(result.user).toBe(HOST_ADMIN);
+        });
+
+        it('does not fall back to a DEACTIVATED system user', () => {
+            // The Owner rung requires IsActive; the system rung must too, or the guarantee is
+            // "we never act as a disabled user, except as the one user we reach first".
+            const inactiveSystem: ResolvablePrincipal = { ...SYSTEM, IsActive: false };
+
+            const result = resolvePrincipalFrom('nobody@nowhere.example', [inactiveSystem, HOST_ADMIN], SYSTEM_USER_ID);
+
+            expect(result.user).toBe(HOST_ADMIN);
+            expect(result.reason).toBe('owner');
+        });
+
+        it('returns no principal when the system user is deactivated and no active Owner remains', () => {
+            const inactiveSystem: ResolvablePrincipal = { ...SYSTEM, IsActive: false };
+
+            const result = resolvePrincipalFrom('nobody@nowhere.example', [inactiveSystem, ANONYMOUS], SYSTEM_USER_ID);
+
+            expect(result.user).toBeNull();
+        });
+
+        it('returns no principal at all when the cache is empty', () => {
+            const result = resolvePrincipalFrom(SHIPPED_DEFAULT, [], SYSTEM_USER_ID);
+
+            expect(result.user).toBeNull();
+            expect(result.reason).toBe('none');
+        });
+    });
+});

package/src/__tests__/resolverBase.refusalMessage.test.ts

@@ -0,0 +1,88 @@
+/**
+ * What the API says when a save or a delete is REFUSED.
+ *
+ * The three write resolvers all end the same way — `throw new GraphQLError(<a string off
+ * LatestResult> ?? 'Unknown error')` — and they did not agree on which string. `CreateRecord` read
+ * `CompleteMessage`; `UpdateRecord` and `DeleteRecord` read `Message`. A validation refusal puts its
+ * reasons in `Errors` and leaves `Message` null, so the same rule on the same entity explained itself
+ * on a create and produced the literal text "Unknown error" on an update.
+ *
+ * Nothing could catch it: both properties exist, both are strings, and the `??` fallback renders the
+ * failure as a plausible-looking error rather than a crash. It is visible only by refusing an update
+ * and reading what comes back.
+ *
+ * The first two cases below guard the direction of RISK in the change — that swapping the property
+ * cannot lose a plain `Message`, and cannot blank out the `'Unknown error'` fallback. The last case
+ * is the only one that fails if a resolver is switched back, and it has to read the source to do it:
+ * any test that restates what a resolver reads stays green through the regression, which is exactly
+ * how this survived (a create-path test proved nothing about update).
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { BaseEntityResult } from '@memberjunction/core';
+
+/** The shape a validation refusal leaves: `Message` untouched, reasons in `Errors`. */
+function refusedByValidation(...messages: string[]): BaseEntityResult {
+    const result = new BaseEntityResult();
+    result.Success = false;
+    result.Errors = messages.map((Message) => ({
+        Source: 'SomeField',
+        Message,
+        Value: null,
+        Type: 'Failure',
+    })) as unknown as BaseEntityResult['Errors'];
+    return result;
+}
+
+/** Exactly what the update/delete resolvers hand to `GraphQLError`, fallback included. */
+const asReported = (r: BaseEntityResult) => r.CompleteMessage ?? 'Unknown error';
+
+describe('switching the update/delete throws to CompleteMessage', () => {
+    it('does NOT lose a plain Message — it is a superset, not a replacement', () => {
+        // The risk in the change: a non-validation failure (a provider/SQL error) sets `Message` and
+        // no `Errors`. The new property must still report it.
+        const result = new BaseEntityResult();
+        result.Success = false;
+        result.Message = 'Timeout expired while saving.';
+
+        expect(asReported(result)).toBe('Timeout expired while saving.');
+    });
+
+    it('still falls back to "Unknown error" when there is genuinely nothing to say', () => {
+        // The other direction: if CompleteMessage returned '' rather than undefined for an empty
+        // result, `??` would not fire and the user would get a blank error.
+        expect(asReported(new BaseEntityResult())).toBe('Unknown error');
+    });
+
+    it('carries the validation prose that "Unknown error" used to replace', () => {
+        const prose = 'Record what this contract says instead of the standard clause.';
+        const result = refusedByValidation(prose);
+
+        expect(result.Message, 'a refusal leaves Message unset — this is why reading it failed').toBeFalsy();
+        expect(asReported(result)).toBe(prose);
+    });
+});
+
+describe('ResolverBase selects CompleteMessage on every write-refusal throw', () => {
+    const source = readFileSync(fileURLToPath(new URL('../generic/ResolverBase.ts', import.meta.url)), 'utf8');
+
+    it('no refusal throw reads the bare LatestResult.Message', () => {
+        // `\b` so the longer `CompleteMessage` does not match.
+        const offenders = source
+            .split('\n')
+            .map((line, i) => ({ line: line.trim(), n: i + 1 }))
+            .filter(({ line }) => /LatestResult\??\.Message\b/.test(line));
+
+        expect(
+            offenders,
+            `these lines still read the bare Message:\n${offenders.map((o) => `  ${o.n}: ${o.line}`).join('\n')}`,
+        ).toEqual([]);
+    });
+
+    it('keeps the three error codes distinct — the fix must not have collapsed the paths', () => {
+        for (const code of ['CREATE_ENTITY_ERROR', 'SAVE_ENTITY_ERROR', 'DELETE_ENTITY_ERROR']) {
+            expect(source, code).toContain(code);
+        }
+    });
+});