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

package/src/__tests__/serverExtensionReservedRoots.test.ts

@@ -37,22 +37,88 @@ describe('coreReservedServerExtensionRoots', () => {
             exportedStringConst('auth/AuthProviderCatalogRouter.ts', 'AUTH_CATALOG_MOUNT_PATH'),
             exportedStringConst('auth/magicLink/MagicLinkRouter.ts', 'MAGIC_LINK_MOUNT_PATH'),
             exportedStringConst('realtimeWidget/WidgetRouter.ts', 'WIDGET_MOUNT_PATH'),
-            exportedStringConst('telephony/TwilioTelephonyRouter.ts', 'TWILIO_TELEPHONY_MOUNT_PATH'),
-            exportedStringConst('telephony/VonageTelephonyRouter.ts', 'VONAGE_TELEPHONY_MOUNT_PATH'),
-            exportedStringConst('telephony/TeamsMeetingsRouter.ts', 'TEAMS_MEETINGS_MOUNT_PATH'),
         ]);
     });
 
     it('includes the literal pre-auth paths serve() registers without a constant', () => {
         const indexSrc = readFileSync(join(SRC, 'index.ts'), 'utf8');
         for (const path of CORE_STATIC_RESERVED_SERVER_EXTENSION_ROOTS) {
-            // /health is the prefix for /health/extensions
-            const needle = path === '/health' ? '/health/extensions' : path;
-            expect(indexSrc, `${path} missing from serve()`).toContain(`'${needle}'`);
+            if (path === '/health') {
+                expect(indexSrc, `${path} missing from serve()`).toContain("'/health/extensions'");
+            } else if (path === '/realtime') {
+                expect(indexSrc, `${path} missing from serve()`).toMatch(/REALTIME_SDP_EXCHANGE_PATH|'\/realtime'/);
+            } else if (path === '/realtime-proxy') {
+                expect(indexSrc, `${path} missing from serve()`).toContain('/realtime-proxy');
+            } else {
+                expect(indexSrc, `${path} missing from serve()`).toContain(`'${path}'`);
+            }
         }
         expect(indexContainsLiteralPath('/healthcheck')).toBe(true);
     });
 
+    it('structurally guarantees every pre-auth app.use / app.get / app.post mount in index.ts is reserved', () => {
+        const indexSrc = readFileSync(join(SRC, 'index.ts'), 'utf8');
+        const authMiddlewareIndex = indexSrc.indexOf('app.use(createUnifiedAuthMiddleware');
+        expect(authMiddlewareIndex).toBeGreaterThan(0);
+        const preAuthSrc = indexSrc.substring(0, authMiddlewareIndex);
+
+        const mountRegex = /app\.(?:use|get|post)\s*\(\s*([^,\s)]+)/g;
+        const reservedRoots = coreReservedServerExtensionRoots('/');
+
+        // Explicit allowlist of known non-path middleware mounts (e.g. app.use(mw), app.use(cors()), app.use(compression(...)))
+        const knownNonPathTokens = [
+            'cors',
+            'express.',
+            'compression',
+            'cookieParser',
+            'createUnifiedAuthMiddleware',
+            'mw',
+        ];
+        const isKnownNonPath = (t: string): boolean =>
+            knownNonPathTokens.some(k => t === k || t.startsWith(k));
+
+        // Strip single-line and multi-line comments so comments like `app.use(...)` are not treated as code
+        const cleanPreAuthSrc = preAuthSrc.replace(/\/\*[\s\S]*?\*\/|\/\/.*/g, '');
+
+        let match: RegExpExecArray | null;
+        const mountedTokens: string[] = [];
+        while ((match = mountRegex.exec(cleanPreAuthSrc)) !== null) {
+            mountedTokens.push(match[1].trim());
+        }
+
+        expect(mountedTokens.length).toBeGreaterThan(0);
+
+        const knownConstants: Record<string, string> = {
+            REALTIME_SDP_EXCHANGE_PATH: '/realtime',
+            MAGIC_LINK_MOUNT_PATH: '/magic-link',
+            WIDGET_MOUNT_PATH: '/widget',
+            AUTH_CATALOG_MOUNT_PATH: '/auth',
+        };
+
+        for (const token of mountedTokens) {
+            const isLiteralPath = token.startsWith("'") || token.startsWith('"') || token.startsWith('`');
+            const isPathConstant = /^[A-Z0-9_]+_PATH$/.test(token) || token in knownConstants;
+            if (!isLiteralPath && !isPathConstant) {
+                if (isKnownNonPath(token)) {
+                    continue;
+                }
+                throw new Error(`Unrecognized pre-auth mount argument '${token}' in index.ts. If this is a non-path middleware, add it to knownNonPathTokens; if it is a route, reserve its prefix or map its constant.`);
+            }
+
+            let pathPrefix: string;
+            if (isLiteralPath) {
+                pathPrefix = token.slice(1, -1);
+            } else if (token in knownConstants) {
+                pathPrefix = knownConstants[token];
+            } else {
+                throw new Error(`Unrecognized pre-auth mount constant '${token}' in index.ts. If this is a new pre-auth route, map its constant or reserve its prefix.`);
+            }
+
+            const isCovered = reservedRoots.some(root => pathPrefix === root || pathPrefix.startsWith(`${root}/`));
+            expect(isCovered, `Pre-auth mount '${pathPrefix}' (from token '${token}') must be covered by reserved roots`).toBe(true);
+        }
+    });
+
     it('includes graphqlRootPath and every core mount', () => {
         const roots = coreReservedServerExtensionRoots('/api');
         expect(roots).toEqual(
@@ -61,14 +127,13 @@ describe('coreReservedServerExtensionRoots', () => {
                 '/auth',
                 '/magic-link',
                 '/widget',
-                '/telephony/twilio',
-                '/telephony/vonage',
-                '/meetings/teams',
                 '/healthcheck',
                 '/esignature',
                 '/media',
                 '/oauth',
                 '/health',
+                '/realtime',
+                '/realtime-proxy',
             ])
         );
     });
@@ -81,10 +146,13 @@ describe('coreReservedServerExtensionRoots', () => {
         expect(validateServerExtensionRootPath('/esignature', extra)).toMatch(/reserved prefix/);
         expect(validateServerExtensionRootPath('/media', extra)).toMatch(/reserved prefix/);
         expect(validateServerExtensionRootPath('/widget', extra)).toMatch(/reserved prefix/);
-        expect(validateServerExtensionRootPath('/telephony', extra)).toMatch(/reserved prefix/);
-        expect(validateServerExtensionRootPath('/meetings/teams', extra)).toMatch(/reserved prefix/);
+        expect(validateServerExtensionRootPath('/realtime', extra)).toMatch(/reserved prefix/);
+        expect(validateServerExtensionRootPath('/realtime-proxy', extra)).toMatch(/reserved prefix/);
+        expect(validateServerExtensionRootPath('/Realtime', extra)).toMatch(/reserved prefix/);
         expect(validateServerExtensionRootPath('/checkout', extra)).toBeNull();
         expect(validateServerExtensionRootPath('/healthcare', extra)).toBeNull();
+        expect(validateServerExtensionRootPath('/telephony/twilio', extra)).toBeNull();
+        expect(validateServerExtensionRootPath('/meetings/teams', extra)).toBeNull();
     });
 
     it('reserves a non-default graphqlRootPath and its nested paths', () => {

package/src/__tests__/visitorIdentity.resolve.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Script the identity lookup's rows and capture what it asked for; everything else in core is real
+// (CompositeKey in particular — the record-id shape under test is its ToCompactURLSegment).
+const runViewMock = vi.fn();
+vi.mock('@memberjunction/core', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@memberjunction/core')>();
+    return {
+        ...actual,
+        RunView: class MockRunView {
+            RunView = runViewMock;
+        },
+    };
+});
+
+import { resolveIdentityByEmail } from '../realtimeWidget/visitorIdentity.js';
+import type { EntityInfo, IMetadataProvider, UserInfo } from '@memberjunction/core';
+
+type LookupParams = { EntityName: string; ExtraFilter: string; Fields: string[] };
+
+function makeProvider(entityInfo: { ID: string; PrimaryKeys: Array<{ Name: string }> } | undefined): IMetadataProvider {
+    return { EntityByName: () => entityInfo as unknown as EntityInfo } as unknown as IMetadataProvider;
+}
+const user = { ID: 'u1' } as unknown as UserInfo;
+function lastParams(): LookupParams {
+    return runViewMock.mock.calls[runViewMock.mock.calls.length - 1][0] as LookupParams;
+}
+
+describe('resolveIdentityByEmail — the configured identity entity can have ANY primary key', () => {
+    beforeEach(() => runViewMock.mockReset());
+
+    it('selects the real key column and returns its bare value for a single non-ID key', async () => {
+        runViewMock.mockResolvedValue({ Success: true, Results: [{ individual_id: 4711 }] });
+        const provider = makeProvider({ ID: 'ent-persons', PrimaryKeys: [{ Name: 'individual_id' }] });
+        const out = await resolveIdentityByEmail('ada@example.com', user, provider, { entityName: 'Persons', emailField: 'EmailAddress' });
+        expect(lastParams().Fields).toEqual(['individual_id']);
+        expect(lastParams().ExtraFilter).toBe("EmailAddress = 'ada@example.com'");
+        expect(out).toEqual({ entityId: 'ent-persons', recordId: '4711' });
+    });
+
+    it('selects EVERY key column and carries a composite key as a full segment, not its first column', async () => {
+        runViewMock.mockResolvedValue({ Success: true, Results: [{ OrderID: '11055', LineNo: 3 }] });
+        const provider = makeProvider({ ID: 'ent-lines', PrimaryKeys: [{ Name: 'OrderID' }, { Name: 'LineNo' }] });
+        const out = await resolveIdentityByEmail('x@y.com', user, provider, { entityName: 'Order Lines' });
+        expect(lastParams().Fields).toEqual(['OrderID', 'LineNo']);
+        expect(out).toEqual({ entityId: 'ent-lines', recordId: 'OrderID|11055||LineNo|3' });
+    });
+
+    it('stays anonymous when no row matches or a key column is null', async () => {
+        const provider = makeProvider({ ID: 'ent-users', PrimaryKeys: [{ Name: 'ID' }] });
+        runViewMock.mockResolvedValue({ Success: true, Results: [] });
+        expect(await resolveIdentityByEmail('none@y.com', user, provider)).toBeUndefined();
+        runViewMock.mockResolvedValue({ Success: true, Results: [{ ID: null }] });
+        expect(await resolveIdentityByEmail('null@y.com', user, provider)).toBeUndefined();
+    });
+
+    it('stays anonymous when the configured entity is not in metadata', async () => {
+        expect(await resolveIdentityByEmail('a@b.com', user, makeProvider(undefined), { entityName: 'Nope' })).toBeUndefined();
+        expect(runViewMock).not.toHaveBeenCalled();
+    });
+});

package/src/agentSessions/SessionJanitor.ts

@@ -285,7 +285,7 @@ export class SessionJanitor extends BaseSingleton<SessionJanitor> implements ISh
                 if (fetchedCount < SWEEP_PAGE_SIZE) {
                     break;
                 }
-                afterKey = CompositeKey.FromID(lastFetchedId);
+                afterKey = CompositeKey.FromID(lastFetchedId); // first-pk-ok: keyset AfterKey on SESSION_ENTITY = MJ: AI Agent Sessions, a core entity keyed by ID
                 continue;
             }
             // Batch-load every channel for this whole page of sessions in ONE query, then hand each
@@ -311,7 +311,7 @@ export class SessionJanitor extends BaseSingleton<SessionJanitor> implements ISh
             if (fetchedCount < SWEEP_PAGE_SIZE) {
                 break; // partial page (by the SQL-matched set) => end of data
             }
-            afterKey = CompositeKey.FromID(lastFetchedId);
+            afterKey = CompositeKey.FromID(lastFetchedId); // first-pk-ok: keyset AfterKey on SESSION_ENTITY = MJ: AI Agent Sessions, a core entity keyed by ID
         }
         return closedCount;
     }

package/src/auth/exampleNewUserSubClass.ts

@@ -1,7 +1,7 @@
 import { RegisterClass } from '@memberjunction/global';
 import { Metadata, RunView, LogError, EntitySaveOptions } from '@memberjunction/core';
 import { NewUserBase } from './newUsers.js';
-import { UserCache } from '@memberjunction/generic-database-provider';
+import { ResolveConfiguredPrincipal } from './principals.js';
 import { configInfo } from '../config.js';
 import { MJUserEntity } from '@memberjunction/core-entities';
 
@@ -18,12 +18,15 @@ export class ExampleNewUserSubClass extends NewUserBase {
     try {
       const md = new Metadata(); // global-provider-ok: new-user creation runs in the JWT auth flow, before AppContext.providers is built
 
-      const contextUser = UserCache.Instance.Users.find(
-        (u) => u.Email.trim().toLowerCase() === configInfo?.userHandling?.contextUserForNewUserCreation?.trim().toLowerCase()
-      );
+      // Resolve through the shared ladder (`auth/principals.ts`) rather than matching a single
+      // column here. This example previously matched `Email` only, which meant that copying it —
+      // which is what the note above tells you to do — reproduced issue #4209 from the other
+      // direction: MJ's default names the system user by `Name` ('System'), and an Email-only
+      // lookup can never reach it.
+      const contextUser = ResolveConfiguredPrincipal(configInfo?.userHandling?.contextUserForNewUserCreation, 'NewUser');
       if (!contextUser) {
         LogError(
-          `Failed to load context user ${configInfo?.userHandling?.contextUserForNewUserCreation}, if you've not specified this on your config.json you must do so. This is the user that is contextually used for creating a new user record dynamically.`
+          'Failed to resolve a context user for new-user creation: userHandling.contextUserForNewUserCreation matched no user, and this deployment has neither a system user nor an active Owner to fall back to. This is the user whose context creates new user records dynamically.'
         );
         return undefined;
       }
@@ -61,7 +64,7 @@ export class ExampleNewUserSubClass extends NewUserBase {
         //p.Email = email;
         //p.Status = 'active';
         if (await p.Save()) {
-          personId = p.FirstPrimaryKey.Value; // if we had a strongly typed sub-class above, we could use this code p.ID;
+          personId = p.FirstPrimaryKey.Value; // first-pk-ok: sample code for a hypothetical ID-keyed Persons entity (see row['ID'] above); personId feeds User.LinkedEntityRecordID, a single-value link. With a strongly typed sub-class this would be p.ID
         } else {
           LogError(`Failed to create new person ${firstName} ${lastName} ${email}`);
         }

package/src/auth/magicLink/MagicLinkService.ts

@@ -30,6 +30,7 @@ import {
   type MJApplicationRoleEntity,
 } from '@memberjunction/core-entities';
 import { UserCache } from '@memberjunction/generic-database-provider';
+import { ResolveConfiguredPrincipal } from '../principals.js';
 import { CommunicationEngine } from '@memberjunction/communication-engine';
 import { Message } from '@memberjunction/communication-types';
 import { configInfo, type MagicLinkConfig } from '../../config.js';
@@ -698,14 +699,7 @@ export class MagicLinkService {
   /** Resolves the user whose context provisions magic-link users. */
   private resolveProvisioningContextUser(): UserInfo | null {
     const candidate = this.config.contextUserForProvisioning || configInfo.userHandling?.contextUserForNewUserCreation;
-    if (candidate) {
-      const byName = UserCache.Instance.UserByName(candidate);
-      if (byName) {
-        return byName;
-      }
-      LogError(`[MagicLink] Configured provisioning user '${candidate}' not found; falling back to an Owner.`);
-    }
-    return UserCache.Users.find((u) => u.Type?.trim().toLowerCase() === 'owner') ?? null;
+    return ResolveConfiguredPrincipal(candidate, 'MagicLink');
   }
 
   /** Sends the invite email via the configured communication provider. Best-effort. */

package/src/auth/newUsers.ts

@@ -1,27 +1,19 @@
 import { ApplicationInfo, DatabaseProviderBase, EntitySaveOptions, LogError, LogStatus, Metadata, RunView, RunViewResult, UserInfo } from "@memberjunction/core";
 import { RegisterClass } from "@memberjunction/global";
-import { UserCache } from "@memberjunction/generic-database-provider";
+import { ResolveConfiguredPrincipal } from "./principals.js";
 import { configInfo } from "../config.js";
 import { MJUserEntity, MJUserRoleEntity, MJUserApplicationEntity, MJUserApplicationEntityEntity, MJApplicationEntityType, MJApplicationEntityEntityType, UserInfoEngine } from "@memberjunction/core-entities";
 
 export class NewUserBase {
     public async createNewUser(firstName: string, lastName: string, email: string, linkedRecordType: string = 'None', linkedEntityId?: string, linkedEntityRecordId?: string): Promise<MJUserEntity | null> {
         try {
-            let contextUser: UserInfo | null = null;
-
-            const contextUserForNewUserCreation: string = configInfo?.userHandling?.contextUserForNewUserCreation;
-            if(contextUserForNewUserCreation){
-                contextUser = UserCache.Instance.UserByName(contextUserForNewUserCreation);
-            }
-
+            const contextUser: UserInfo | null = ResolveConfiguredPrincipal(
+                configInfo?.userHandling?.contextUserForNewUserCreation,
+                'NewUser',
+            );
             if (!contextUser) {
-                LogError(`Failed to load context user ${configInfo?.userHandling?.contextUserForNewUserCreation}, using an existing user with the Owner role instead`);
-
-                contextUser = UserCache.Users.find(user => user.Type.trim().toLowerCase() ==='owner')!;
-                if (!contextUser) {
-                    LogError(`No existing users found in the database with the Owner role, cannot create a new user`);
-                    return null;
-                }
+                LogError(`No system user or active Owner found in the database, cannot create a new user`);
+                return null;
             }
 
             const md: Metadata = new Metadata(); // global-provider-ok: new-user creation runs in the JWT auth flow, before AppContext.providers is built

package/src/auth/principals.ts

@@ -0,0 +1,257 @@
+import { LogError, UserInfo } from '@memberjunction/core';
+import { MJLruCache, UUIDsEqual } from '@memberjunction/global';
+import { UserCache } from '@memberjunction/generic-database-provider';
+
+/**
+ * Resolving the principal that server-side work runs as when there is no caller to run as.
+ *
+ * MJServer names such a principal in config in three places — `contextUserForNewUserCreation`,
+ * `contextUserForProvisioning` and `contextUserForLookup` — and, before issue #4209, each
+ * consumer hand-rolled its own lookup-and-fallback. There were six of those across the server in
+ * three mutually inconsistent variants, and two of them could not resolve the value MJ itself
+ * ships: the default is `'not.set@nowhere.com'`, the system user's EMAIL, while the lookup
+ * matched `Name` (which is `'System'`). The result was an error-level log line per magic-link
+ * redeem and provisioning attributed to whichever user happened to sort first as an Owner.
+ *
+ * This module is the single ladder those consumers share.
+ *
+ * Two exports, cased to tell them apart on sight: `ResolveConfiguredPrincipal` is the shell callers
+ * use (PascalCase, like the rest of MJServer's public surface), and `resolvePrincipalFrom` is the
+ * pure core it wraps — same ladder, no cache, no logging, which is what makes the ladder testable
+ * without a singleton or a database. The casing is the signal, not an oversight.
+ */
+
+/**
+ * The subset of a user this resolver reads. `UserInfo` satisfies it structurally, so callers pass
+ * `UserCache.Users` directly while tests pass plain objects — no cast, no singleton, no database.
+ */
+export type ResolvablePrincipal = Pick<UserInfo, 'ID' | 'Name' | 'Email' | 'Type' | 'IsActive'>;
+
+/** Which rung of the ladder produced the principal; `none` when no rung did. */
+export type PrincipalResolutionReason = 'name' | 'email' | 'system' | 'owner' | 'none';
+
+export interface PrincipalResolution<T extends ResolvablePrincipal> {
+    /** The principal to act as, or null when this deployment offers none. */
+    user: T | null;
+    reason: PrincipalResolutionReason;
+    /**
+     * Operator-facing diagnostic. Set ONLY when a configured candidate failed to resolve — an
+     * unset candidate is a deployment that never asked for a specific user, not a misconfiguration,
+     * and must not be reported as one.
+     */
+    warning?: string;
+}
+
+/** Case- and padding-insensitive comparison, for the `NCHAR`-padded and free-text columns alike. */
+function normalize(value: string | null | undefined): string {
+    return value?.trim().toLowerCase() ?? '';
+}
+
+/**
+ * The lowest-ID ACTIVE match, or undefined when there is none.
+ *
+ * Every rung that can match more than one user resolves through this, so it carries BOTH of the
+ * ladder's cross-cutting guarantees in one place instead of restating them per rung. Stating them
+ * per rung is how the `Name` and `Email` rungs came to be missing the second one while
+ * {@link resolvePrincipalFrom}'s own docstring claimed all four rungs had it.
+ *
+ * DETERMINISM. Ties go to the lowest ID rather than the first match. `UserCache.Users`
+ * comes from an `ORDER BY`-less `SELECT * FROM vwUsers` and is mutated in place at runtime
+ * (`Users.push`), so its order differs across boots AND within a process — which is exactly how
+ * `CreatedByUserID` became noise. A rung that resolves by array order is that same defect, one
+ * rung further down.
+ *
+ * `Name` is the rung this actually protects: it 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), but a hand-created or externally-synced row can.
+ *
+ * Plain `<` on the normalized strings rather than `localeCompare`: ordering by code point cannot
+ * shift with the process locale or the runtime's ICU build, and this ordering decides attribution.
+ *
+ * ACTIVE ONLY. A deactivated user is never a candidate, on any rung. The server acting as a
+ * disabled account is the failure this exists to prevent, and it is not less of one because an
+ * operator named that account in config — a setting outlives the person it names.
+ */
+function lowestActiveById<T extends ResolvablePrincipal>(matches: readonly T[]): T | undefined {
+    let lowest: T | undefined;
+    for (const match of matches) {
+        if (match.IsActive !== true) {
+            continue;
+        }
+        if (!lowest || normalize(match.ID) < normalize(lowest.ID)) {
+            lowest = match;
+        }
+    }
+    return lowest;
+}
+
+/**
+ * Resolves the principal a configured candidate names, falling back deterministically.
+ *
+ * The ladder, in order:
+ *  1. `Name`  — tried first so that every host resolving today resolves to the SAME user as
+ *               before. This is what makes adding the `Email` rung a compatible change rather
+ *               than a semantic one. ACTIVE only, which is that compatibility claim's one
+ *               deliberate exception: a host whose setting names a DEACTIVATED user stops
+ *               resolving to them. That is the point, not a casualty — see below.
+ *  2. `Email` — the identity column everywhere else in MJServer, and the only one the schema
+ *               makes unique (`UQ_User_Email`). This is the rung that resolves MJ's own default.
+ *               ACTIVE only, for the same reason.
+ *  3. System  — by ID, so it survives the system user being renamed. ACTIVE only.
+ *  4. Owner   — lowest ID among ACTIVE owners. A last resort, but still deterministic: the
+ *               previous "first Owner in cache order" made `CreatedByUserID` depend on the order
+ *               `SELECT * FROM vwUsers` happened to return, which is unstable across boots and
+ *               within a process.
+ *
+ * Every rung breaks ties by lowest ID ({@link lowestActiveById}), never by array position, and no rung
+ * returns an inactive user — the configured rungs included. An operator naming a user in config
+ * is the likeliest way to end up pointed at a disabled account (the admin whose address is in the
+ * setting leaves, and their account is deactivated), and honouring it would mean the server keeps
+ * provisioning as someone who no longer works there, silently and indefinitely. A guarantee that
+ * every rung holds except the two anyone actually configures is not a guarantee.
+ *
+ * Pure, and reports rather than logs, so the caller owns log volume and phrasing.
+ *
+ * @param candidate  the configured value; blank/undefined means "no preference", not an error
+ * @param users      the candidate pool, normally `UserCache.Users`
+ * @param systemUserId the deployment's system user ID (`UserCache.Instance.SYSTEM_USER_ID`)
+ */
+export function resolvePrincipalFrom<T extends ResolvablePrincipal>(
+    candidate: string | undefined,
+    users: readonly T[],
+    systemUserId: string,
+): PrincipalResolution<T> {
+    if (!Array.isArray(users)) {
+        throw new Error('resolvePrincipalFrom requires a user array; received ' + typeof users);
+    }
+    if (!systemUserId) {
+        throw new Error('resolvePrincipalFrom requires a system user ID to fall back to');
+    }
+
+    const wanted = normalize(candidate);
+
+    if (wanted) {
+        const byName = lowestActiveById(users.filter((u) => normalize(u.Name) === wanted));
+        if (byName) {
+            return { user: byName, reason: 'name' };
+        }
+        // Reached when `Name` matched nobody USABLE, which includes matching only deactivated
+        // rows: an inactive `Name` holder must not shadow an active `Email` holder. The ladder is
+        // looking for the user this string names, and an unusable match is not a reason to stop.
+        const byEmail = lowestActiveById(users.filter((u) => normalize(u.Email) === wanted));
+        if (byEmail) {
+            return { user: byEmail, reason: 'email' };
+        }
+    }
+
+    const fallback = resolveFallback(users, systemUserId);
+    if (!wanted) {
+        return fallback;
+    }
+    return {
+        ...fallback,
+        warning:
+            `Configured user '${candidate}' ${describeMiss(users, wanted)}; ` +
+            `falling back to ${describeFallback(fallback.reason)}.`,
+    };
+}
+
+/**
+ * Why a configured candidate yielded nothing. The two causes need opposite fixes, so the message
+ * has to tell them apart: "no such user" is a typo or the wrong column, while "matched, but
+ * deactivated" is a correctly spelled setting pointing at a disabled account. Reporting the second
+ * as the first sends the operator hunting for a typo in a value that is spelled right.
+ *
+ * Runs only once the configured rungs have already missed, so the extra pass is off the happy path.
+ */
+function describeMiss<T extends ResolvablePrincipal>(users: readonly T[], wanted: string): string {
+    const matchedButInactive = users.some((u) => normalize(u.Name) === wanted || normalize(u.Email) === wanted);
+    return matchedButInactive ? 'matched only INACTIVE users' : "matched no user's Name or Email";
+}
+
+/** The candidate-independent rungs: the system user, then the lowest-ID active Owner. */
+function resolveFallback<T extends ResolvablePrincipal>(
+    users: readonly T[],
+    systemUserId: string,
+): PrincipalResolution<T> {
+    // The one rung that states `IsActive` for itself: a lookup by ID matches at most one row, so
+    // there is no tie to break and nothing to route through `lowestActiveById`. It still needs the
+    // guard — this change makes the system user the SHIPPED DEFAULT, so it is the rung most hosts
+    // land on, and a host that deactivates it must fail loudly rather than act as it.
+    const system = users.find((u) => UUIDsEqual(u.ID, systemUserId) && u.IsActive === true);
+    if (system) {
+        return { user: system, reason: 'system' };
+    }
+
+    const owner = lowestActiveById(users.filter((u) => normalize(u.Type) === 'owner'));
+
+    return owner ? { user: owner, reason: 'owner' } : { user: null, reason: 'none' };
+}
+
+/**
+ * How many distinct `purpose :: candidate` problems the tracker below remembers at once.
+ *
+ * Candidates come from static config today, so the real cardinality is the number of settings
+ * (three) and this is never approached. It is published so the bound is testable rather than
+ * discovered.
+ */
+export const MAX_REPORTED_MISCONFIGURATIONS = 64;
+
+/**
+ * Misconfigurations already reported, keyed by purpose + candidate.
+ *
+ * A misconfigured setting is a static, boot-time fact, but the code that trips over it runs per
+ * request — which is how issue #4209 turned one wrong config value into an error-level line on
+ * every magic-link redeem. Saying it once per distinct problem keeps the diagnostic without
+ * burying real errors underneath it.
+ *
+ * An LRU rather than a `Set` + cap, because the two differ exactly where it matters. A capped
+ * `Set` stops admitting once it is full, so every candidate seen after that logs on EVERY call —
+ * which is #4209's per-request error line, reintroduced for precisely the dynamic caller the cap
+ * was added to defend against. The LRU bounds memory the same way but keeps de-duplicating: the
+ * worst case is one repeated line after a cold key ages out, not a permanent flood.
+ */
+const reportedMisconfigurations = new MJLruCache<string, true>({ maxSize: MAX_REPORTED_MISCONFIGURATIONS });
+
+/** Entries the tracker currently holds. Exists so the bound above can be asserted, not inferred. */
+export function ReportedMisconfigurationCount(): number {
+    return reportedMisconfigurations.Size;
+}
+
+/**
+ * Resolves the principal named by a config setting, reading the process-wide user cache.
+ *
+ * The impure shell over {@link resolvePrincipalFrom}: it supplies the cache and owns log volume.
+ *
+ * @param candidate the configured value; blank/undefined means "no preference", not an error
+ * @param purpose   short label for the setting being resolved (e.g. `'MagicLink'`), used both in
+ *                  the operator-facing message and to key de-duplication
+ * @returns the principal to act as, or null when this deployment offers none — callers MUST
+ *          handle null rather than assume a principal is always available
+ */
+export function ResolveConfiguredPrincipal(candidate: string | undefined, purpose: string): UserInfo | null {
+    const resolution = resolvePrincipalFrom(candidate, UserCache.Instance.Users, UserCache.Instance.SYSTEM_USER_ID);
+
+    if (resolution.warning) {
+        const key = `${purpose} :: ${candidate ?? ''}`;
+        // `Get` rather than `Has`: it refreshes recency, so a setting that keeps being hit stays
+        // suppressed and it is the settings nobody asks about any more that age out first.
+        if (reportedMisconfigurations.Get(key) === undefined) {
+            reportedMisconfigurations.Set(key, true);
+            LogError(`[${purpose}] ${resolution.warning}`);
+        }
+    }
+
+    return resolution.user;
+}
+
+function describeFallback(reason: PrincipalResolutionReason): string {
+    switch (reason) {
+        case 'system':
+            return 'the system user';
+        case 'owner':
+            return 'the lowest-ID active Owner';
+        default:
+            return 'no user at all — this deployment has neither a system user nor an active Owner';
+    }
+}