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

package/src/__tests__/scalabilityDatabaseIntegration.test.ts

@@ -0,0 +1,207 @@
+import 'reflect-metadata';
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+import sql from 'mssql';
+import { RunViewParams, RunViewResult, SetProvider, UserInfo } from '@memberjunction/core';
+import { GenericDatabaseProvider, UserCache } from '@memberjunction/generic-database-provider';
+import { SQLServerDataProvider, SQLServerProviderConfigData } from '@memberjunction/sqlserver-dataprovider';
+import {
+    CacheInvalidationBroadcastManager,
+    SequencedRoleBucketBroadcastProvider,
+} from '../broadcast/index.js';
+
+const IT_DB_NAME = process.env.MJ_IT_DB;
+
+describe.skipIf(!IT_DB_NAME)('MJServer Scalability Architecture — Live SQL Server Integration', () => {
+    let pool: sql.ConnectionPool;
+    let sharedProvider: SQLServerDataProvider;
+    let sysUser: UserInfo;
+
+    beforeAll(async () => {
+        pool = new sql.ConnectionPool({
+            server: process.env.MJ_IT_HOST || 'localhost',
+            port: parseInt(process.env.MJ_IT_PORT || '1433', 10),
+            database: IT_DB_NAME,
+            user: process.env.MJ_IT_USER || 'sa',
+            password: process.env.MJ_IT_PASSWORD || 'GHWUc7QKZNT8GQiqnJHdEPonPcukY2WA',
+            options: {
+                encrypt: false,
+                trustServerCertificate: true,
+            },
+        });
+        await pool.connect();
+
+        sharedProvider = new SQLServerDataProvider();
+        const config = new SQLServerProviderConfigData(pool, '__mj', 0);
+        await sharedProvider.Config(config);
+        SetProvider(sharedProvider);
+        await UserCache.Instance.Refresh(sharedProvider, 0);
+
+        const foundUser =
+            UserCache.Instance.GetSystemUser() ||
+            UserCache.Instance.Users.find((u) => u.IsActive && u.Type === 'Owner') ||
+            UserCache.Instance.Users[0];
+        if (!foundUser) {
+            throw new Error(`No user found in ${IT_DB_NAME}`);
+        }
+        sysUser = foundUser;
+    }, 60_000);
+
+    afterAll(async () => {
+        if (pool?.connected) {
+            await pool.close();
+        }
+    });
+
+    it('creates per-request SQLServerDataProvider with zero-copy prototype-delegated metadata shell and lazy transaction queues', async () => {
+        const reqProvider = new SQLServerDataProvider();
+        const reqConfig = new SQLServerProviderConfigData(
+            pool,
+            '__mj',
+            0,
+            undefined,
+            undefined,
+            false // ignoreExistingMetadata = false -> reuses shared metadata shell
+        );
+        await reqProvider.Config(reqConfig);
+
+        // Verify lazy RxJS Subjects are NOT allocated on a read-only request provider
+        const internal = reqProvider as unknown as {
+            _sqlQueue$: unknown;
+            _transactionState$: unknown;
+        };
+
+        expect(internal._sqlQueue$).toBeNull();
+        expect(internal._transactionState$).toBeNull();
+
+        // Verify zero-copy prototype delegation to shared metadata
+        expect(Object.getPrototypeOf(reqProvider.AllMetadata)).toBe(sharedProvider.AllMetadata);
+        expect(reqProvider.Entities.length).toBeGreaterThan(50);
+        expect(reqProvider.Entities).toBe(sharedProvider.Entities);
+    });
+
+    it('coalesces 10 concurrent identical InternalRunView calls against SQL Server into a single SQL execution and isolates result mutations', async () => {
+        // Warm up the view column order cache for vwEntities (must return >=1 row so sortViewRowKeys caches sys.columns)
+        await sharedProvider.RunView(
+            {
+                EntityName: 'MJ: Entities',
+                ExtraFilter: "Name = 'MJ: Entities'",
+                ResultType: 'simple',
+                IgnoreMaxRows: true,
+            },
+            sysUser
+        );
+
+        const executeSpy = vi.spyOn(sharedProvider, 'ExecuteSQL');
+        const internalRunner = sharedProvider as unknown as {
+            InternalRunView<T>(params: RunViewParams, contextUser?: UserInfo): Promise<RunViewResult<T>>;
+        };
+
+        try {
+            const concurrentCount = 10;
+            const promises = Array.from({ length: concurrentCount }, () =>
+                internalRunner.InternalRunView<Record<string, unknown>>(
+                    {
+                        EntityName: 'MJ: Entities',
+                        ExtraFilter: "SchemaName = '__mj' AND Name LIKE 'MJ: %'",
+                        OrderBy: 'Name ASC',
+                        IgnoreMaxRows: true,
+                        ResultType: 'simple',
+                    },
+                    sysUser
+                )
+            );
+
+            const results = await Promise.all(promises);
+
+            // Only 1 physical SQL execution should have been issued for the 10 identical concurrent views
+            expect(executeSpy).toHaveBeenCalledTimes(1);
+
+            for (const res of results) {
+                expect(res.Success).toBe(true);
+                expect(res.Results.length).toBeGreaterThan(0);
+            }
+
+            // Mutating caller 0's result array or row object must not affect caller 1's result
+            const originalName = results[1].Results[0].Name;
+            const originalLength = results[1].Results.length;
+            results[0].Results[0].Name = 'MUTATED_IN_CALLER_0';
+            results[0].Results.pop();
+
+            expect(results[1].Results[0].Name).toBe(originalName);
+            expect(results[0].Results.length).toBe(originalLength - 1);
+            expect(results[1].Results.length).toBe(originalLength);
+        } finally {
+            executeSpy.mockRestore();
+        }
+    });
+
+    it('bounds concurrent SQL executions in RunViews to MaxConcurrentViewsPerBatch', async () => {
+        let activeCount = 0;
+        let maxObservedConcurrency = 0;
+
+        const originalExecuteSQL = sharedProvider.ExecuteSQL.bind(sharedProvider);
+        const executeSpy = vi.spyOn(sharedProvider, 'ExecuteSQL').mockImplementation(async (query, params, options, contextUser) => {
+            activeCount++;
+            if (activeCount > maxObservedConcurrency) {
+                maxObservedConcurrency = activeCount;
+            }
+            try {
+                return await originalExecuteSQL(query, params, options, contextUser);
+            } finally {
+                activeCount--;
+            }
+        });
+
+        try {
+            const batchParams = Array.from({ length: 16 }, (_, idx) => ({
+                EntityName: 'MJ: Entities',
+                ExtraFilter: `SchemaName = '__mj' AND UserViewMaxRows IS NULL AND ${idx} = ${idx}`,
+                IgnoreMaxRows: true,
+                ResultType: 'simple' as const,
+            }));
+
+            const batchResults = await sharedProvider.RunViews(batchParams, sysUser);
+            expect(batchResults).toHaveLength(16);
+            for (const r of batchResults) {
+                expect(r.Success).toBe(true);
+            }
+            expect(maxObservedConcurrency).toBeLessThanOrEqual(GenericDatabaseProvider.MaxConcurrentViewsPerBatch);
+            expect(maxObservedConcurrency).toBeGreaterThan(1);
+        } finally {
+            executeSpy.mockRestore();
+        }
+    });
+
+    it('sequences and shapes cache invalidation broadcasts against live entity metadata and replays delta catch-up', async () => {
+        const provider = CacheInvalidationBroadcastManager.Instance.Configure({
+            provider: 'SequencedRoleBucket',
+            ringBufferSize: 500,
+        }) as SequencedRoleBucketBroadcastProvider;
+        expect(provider).toBeInstanceOf(SequencedRoleBucketBroadcastProvider);
+
+        const baseSeq = provider.CurrentSequence;
+        const entityInfo = sharedProvider.Entities.find((e) => e.Name === 'MJ: Entities');
+        expect(entityInfo).toBeDefined();
+
+        const published = provider.RecordInvalidation({
+            entityName: 'MJ: Entities',
+            primaryKeyValues: JSON.stringify([{ FieldName: 'ID', Value: entityInfo!.ID }]),
+            action: 'save',
+            sourceServerId: 'it-server-node-1',
+            timestamp: new Date(),
+            recordData: JSON.stringify({ ID: entityInfo!.ID, Name: entityInfo!.Name }),
+        });
+
+        expect(published.sequence).toBe(baseSeq + 1);
+        expect(provider.CurrentSequence).toBe(baseSeq + 1);
+
+        // Verify delta catch-up shapes payload for sysUser against real MJ: Entities metadata
+        const catchUp = provider.GetChangesSince(baseSeq, sysUser);
+        expect(catchUp.RequiresFullRefresh).toBe(false);
+        expect(catchUp.CurrentSequence).toBe(baseSeq + 1);
+        expect(catchUp.Events).toHaveLength(1);
+        expect(catchUp.Events[0].EntityName).toBe('MJ: Entities');
+        expect(catchUp.Events[0].Sequence).toBe(baseSeq + 1);
+        expect(catchUp.Events[0].RecordData).toContain(entityInfo!.Name);
+    });
+});

package/src/__tests__/sessionUserClone.test.ts

@@ -43,6 +43,7 @@ function buildSourceUser(): UserInfo {
   user.ReturningVisitorContext = { VisitorKey: 'vk-1' };
   user.WidgetGuestContext = { WidgetID: 'W0000000-0000-0000-0000-000000000001' };
   user.IsMagicLinkAnonymous = true;
+  user.AnonymousVisitorID = 'visitor-sid-1';
   return user;
 }
 
@@ -99,13 +100,14 @@ describe('CloneUserForSessionContext', () => {
     expect(clone.APIKeyRowFilters).toHaveLength(1);
   });
 
-  it('preserves ReturningVisitorContext, WidgetGuestContext, and IsMagicLinkAnonymous', () => {
+  it('preserves ReturningVisitorContext, WidgetGuestContext, IsMagicLinkAnonymous, and AnonymousVisitorID', () => {
     const source = buildSourceUser();
     const clone = CloneUserForSessionContext(source);
 
     expect(clone.ReturningVisitorContext).toEqual({ VisitorKey: 'vk-1' });
     expect(clone.WidgetGuestContext).toEqual({ WidgetID: 'W0000000-0000-0000-0000-000000000001' });
     expect(clone.IsMagicLinkAnonymous).toBe(true);
+    expect(clone.AnonymousVisitorID).toBe('visitor-sid-1');
   });
 
   it('stamping new contexts on the clone does NOT write through to the source', () => {
@@ -120,6 +122,7 @@ describe('CloneUserForSessionContext', () => {
     clone.APIKeyActingContext = { ActingOrganizationID: 'ORG-OTHER' };
     clone.APIKeyRowFilters = newBindings;
     clone.IsMagicLinkAnonymous = false;
+    clone.AnonymousVisitorID = 'visitor-sid-OTHER';
 
     // The source (potentially the shared UserCache instance) must be untouched
     expect(source.TenantContext).toEqual({ TenantID: 'tenant-1', Source: 'header' });
@@ -128,6 +131,7 @@ describe('CloneUserForSessionContext', () => {
     expect(source.APIKeyRowFilters).toHaveLength(1);
     expect(source.APIKeyRowFilters?.[0].FilterID).toBe('F0000000-0000-0000-0000-000000000001');
     expect(source.IsMagicLinkAnonymous).toBe(true);
+    expect(source.AnonymousVisitorID).toBe('visitor-sid-1');
   });
 
   it('clearing contexts on the clone does NOT clear them on the source', () => {

package/src/__tests__/startupSweepOrder.test.ts

@@ -0,0 +1,40 @@
+/**
+ * `SweepInterruptedRuns` closes out run artifacts a dead process left open. It is only sound
+ * BEFORE anything in this process can start a run: a run started first is still in flight when
+ * the sweep looks, so the sweep marks a live run "killed" and the wizard and active-operations
+ * panel report a failure for work that is still going.
+ *
+ * Booting the server is far too heavy for a unit test, so this pins the order in the source:
+ * the sweep is awaited before the scheduler, the integration sync worker (whose Start() polls
+ * immediately), the HTTP listener, and pending RSU work.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const source = readFileSync(join(__dirname, '..', 'index.ts'), 'utf8')
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/^\s*\/\/.*$/gm, '');
+
+function at(needle: string): number {
+    const i = source.indexOf(needle);
+    expect(i, `not found in index.ts: ${needle}`).toBeGreaterThan(-1);
+    return i;
+}
+
+describe('startup: the interrupted-run sweep runs before anything can start a run', () => {
+    const sweep = () => at('await SweepInterruptedRuns(');
+
+    it.each([
+        ['the scheduled jobs service', 'scheduledJobsService.Start()'],
+        ['the integration sync worker', 'integrationSyncWorker.Start()'],
+        ['the HTTP listener', 'httpServer.listen('],
+        ['pending RSU work', 'processRSUPendingWork().catch('],
+    ])('precedes %s', (_label, needle) => {
+        expect(sweep()).toBeLessThan(at(needle));
+    });
+
+    it('is called exactly once', () => {
+        expect(source.split('await SweepInterruptedRuns(').length - 1).toBe(1);
+    });
+});

package/src/__tests__/unifiedAuth.test.ts

@@ -263,6 +263,34 @@ describe('createUnifiedAuthMiddleware', () => {
     });
   });
 
+  describe('x-mj-timezone header', () => {
+    beforeEach(() => {
+      setupSuccessfulAuth();
+    });
+
+    async function payloadFor(headers: Record<string, string>) {
+      const req = makeMockReq({ headers: { authorization: 'Bearer valid-token', ...headers } });
+      await middleware(req, makeMockRes(), vi.fn());
+      return req.userPayload!;
+    }
+
+    it('carries a valid IANA zone on the user payload', async () => {
+      expect((await payloadFor({ 'x-mj-timezone': 'Pacific/Auckland' })).TimeZone).toBe('Pacific/Auckland');
+    });
+
+    it('drops an invalid zone, so callers fall back to UTC', async () => {
+      expect((await payloadFor({ 'x-mj-timezone': 'Mars/Olympus_Mons' })).TimeZone).toBeUndefined();
+      expect((await payloadFor({ 'x-mj-timezone': "UTC'; DROP TABLE x;--" })).TimeZone).toBeUndefined();
+      expect((await payloadFor({ 'x-mj-timezone': '' })).TimeZone).toBeUndefined();
+    });
+
+    it('leaves the payload exactly as before when the header is absent', async () => {
+      const payload = await payloadFor({});
+      expect(payload.TimeZone).toBeUndefined();
+      expect(Object.keys(payload)).not.toContain('TimeZone');
+    });
+  });
+
   describe('Authentication failures', () => {
     it('should return 401 when no authorization header is provided, quietly (no stack-trace log)', async () => {
       mockGetReadOnlyDS.mockReturnValue(MOCK_POOL);

package/src/__tests__/widgetGuestElevation.test.ts

@@ -155,6 +155,8 @@ describe('widgetGuestElevation — elevateUserPayload', () => {
     expect(elevated.isSystemUser).toBe(true);
     // The session id MUST be preserved so progress/streaming still routes to the guest's websocket.
     expect(elevated.sessionId).toBe('sess-123');
+    // The guest it stands in for, so conversation writes can stay the guest's (MJ#4791).
+    expect(elevated.ElevatedFrom).toBe(guestPayload.userRecord);
   });
 
   it('does not mutate the original guest payload', () => {

package/src/agentSessions/SessionJanitor.ts

@@ -647,9 +647,9 @@ export class SessionJanitor extends BaseSingleton<SessionJanitor> implements ISh
 
     /**
      * Gives a status-less session with ledger shards back a `Pending` status so it can be claimed (the
-     * claim only takes Pending/Partial/stale Assembling). The status is lost when a `BaseEntity.Save` of
-     * the session (e.g. its close) loaded the row before a shard or terminal proc wrote it and saved
-     * after: `spUpdate` rewrites every column, so it puts back the stale NULL status and counts.
+     * claim only takes Pending/Partial/stale Assembling). That is how statuses were lost before #6010
+     * made the ledger columns not updatable through an entity save (a stale `Save` of the session, e.g. its
+     * close, put back the NULL status and counts). The restore stays for rows hit before then.
      *
      * The terminal proc is the existing way to set a NULL status to `Pending`. It is stamped with the
      * counts the session still stores, or 0 for a NULL count (the proc accepts any count over NULL), and

package/src/agentSessions/SessionManager.ts

@@ -13,6 +13,7 @@ import { WriteReturningVisitorRecap } from './ReturningVisitorRecap.js';
 import { SessionRunIDVerifier, SessionRunIDs } from './SessionRunIDVerifier.js';
 import { ResolveScopedAnonymousRunUser } from '../realtimeWidget/widgetGuestElevation.js';
 import { RecordingAssemblyScheduler } from '../realtimeSessions/RecordingAssemblyScheduler.js';
+import { ResolveSessionScopeIdentity } from '../realtimeSessions/sessionAccess.js';
 
 /** Entity names — centralised so the `MJ:`-prefix convention is applied in exactly one place. */
 const SESSION_ENTITY = 'MJ: AI Agent Sessions';
@@ -153,11 +154,13 @@ export class SessionManager {
     /**
      * Authorize and create a new session. Flow:
      * 1. `CanRun` check on the agent — denied → {@link SessionAuthorizationError}, no row written.
-     * 2. Resolve the conversation (use the supplied one, or create+link a fresh Conversation).
+     * 2. Resolve the conversation (use the supplied one, or create+link a fresh Conversation). An anonymous
+     *    caller may only supply a conversation stamped with its own scope identity.
      * 3. Persist the `AIAgentSession` as `Active`, stamped with this host and `LastActiveAt = now`.
      *
      * @returns the saved {@link MJAIAgentSessionEntity}.
-     * @throws {SessionAuthorizationError} when the user may not run the agent.
+     * @throws {SessionAuthorizationError} when the user may not run the agent, or an anonymous caller supplies a
+     *   conversation that is not its own.
      * @throws {Error} when conversation creation or session save fails.
      */
     public async CreateSession(
@@ -166,6 +169,9 @@ export class SessionManager {
         provider: IMetadataProvider,
     ): Promise<MJAIAgentSessionEntity> {
         await this.assertCanRun(input.agentID, contextUser);
+        if (input.conversationID && contextUser.IsMagicLinkAnonymous) {
+            await this.assertAnonymousOwnsConversation(input.conversationID, contextUser, provider);
+        }
 
         const conversationID = input.conversationID
             ?? await this.createConversation(input, contextUser, provider);
@@ -448,6 +454,23 @@ export class SessionManager {
 
     // ----- internals -------------------------------------------------------------------------
 
+    /**
+     * Throws {@link SessionAuthorizationError} unless the anonymous caller owns the conversation it wants to bind a
+     * new session to: the conversation, read as the caller, loads, and its `ExternalID` equals the caller's scope
+     * identity ({@link ResolveSessionScopeIdentity}). A caller with no scope identity is refused. Every anonymous
+     * visitor shares one Anonymous user, so row-level security alone may let one visitor read another's
+     * conversation; without this check the new session row and its relays would point into that conversation.
+     */
+    private async assertAnonymousOwnsConversation(conversationID: string, contextUser: UserInfo, provider: IMetadataProvider): Promise<void> {
+        const conversation = await provider.GetEntityObject<MJConversationEntity>(CONVERSATION_ENTITY, contextUser);
+        const loaded = await conversation.Load(conversationID);
+        const scopeIdentity = ResolveSessionScopeIdentity(contextUser);
+        if (!loaded || !scopeIdentity || conversation.ExternalID !== scopeIdentity) {
+            LogError(`SessionManager.CreateSession: refused anonymous user ${contextUser.ID} binding a session to conversation ${conversationID} (${loaded ? 'not its own' : 'not readable'}).`);
+            throw new SessionAuthorizationError('Not authorized to start a session on this conversation.');
+        }
+    }
+
     /** Throws {@link SessionAuthorizationError} unless the user has `CanRun` on the agent. */
     private async assertCanRun(agentID: string, contextUser: UserInfo): Promise<void> {
         const canRun = await AIAgentPermissionHelper.HasPermission(agentID, contextUser, 'run');
@@ -468,13 +491,13 @@ export class SessionManager {
         conversation.NewRecord();
         conversation.UserID = input.userID;
         conversation.Name = 'Agent Session';
-        // For a magic-link-anonymous principal (e.g. a public web-widget voice guest), stamp the
-        // session's conversation with the signed per-session scope so the Widget Guest RLS filters
-        // ({{ScopeResourceID}}) isolate this session — and everything chained to it (AI Agent
-        // Sessions via ConversationID, Session Channels via the session) — from other guests
-        // sharing the Anonymous UserID. No-op for named principals (no scope → default ExternalID).
-        if (contextUser.MagicLinkScope?.ResourceID) {
-            conversation.ExternalID = contextUser.MagicLinkScope.ResourceID;
+        // Stamp the scope identity AuthorizeSessionAccess compares against (one rule, one place:
+        // ResolveSessionScopeIdentity) — the token's resource scope when it has one, else an anonymous
+        // visitor's mj_sid. This isolates anonymous visitors that share the Anonymous UserID, and keeps
+        // the {{ScopeResourceID}} RLS filters matching the visitor's own rows. No-op for unscoped named principals.
+        const scopeIdentity = ResolveSessionScopeIdentity(contextUser);
+        if (scopeIdentity) {
+            conversation.ExternalID = scopeIdentity;
         }
 
         // Returning-visitor memory (RV1/RV2/RV4) for the VOICE path: the widget guest token carries the
@@ -539,9 +562,9 @@ export class SessionManager {
     }
 
     /**
-     * Loads a session entity by ID, returning null when it cannot be loaded. The server entity
-     * (`MJAIAgentSessionEntityServer`) keeps the lifecycle saves that follow from writing back the
-     * recording ledger's columns (#5294).
+     * Loads a session entity by ID, returning null when it cannot be loaded. The lifecycle saves that
+     * follow cannot write back the recording ledger's columns: those have `AllowUpdateAPI=0`, so they are
+     * not parameters of `spUpdateAIAgentSession` (#5294, #6010).
      */
     private async loadSession(
         agentSessionID: string,

package/src/auth/AuthProviderCatalogRouter.ts

@@ -13,6 +13,7 @@ import { rateLimit } from 'express-rate-limit';
 import { LogError, type PublicAuthProviderCatalog } from '@memberjunction/core';
 import { AuthProviderEngine } from './AuthProviderEngine.js';
 import { EMPTY_PUBLIC_LOGIN_SCREEN, LoginScreenEngine } from './LoginScreenEngine.js';
+import { AttachLocalDevAuthRoutes } from './localDevAuth.js';
 
 /** Mount path for the public catalog router. */
 export const AUTH_CATALOG_MOUNT_PATH = '/auth';
@@ -98,6 +99,8 @@ export function CreateAuthProviderCatalogRouter(): Router {
     }
   });
 
+  AttachLocalDevAuthRoutes(router);
+
   return router;
 }
 

package/src/auth/index.ts

@@ -2,7 +2,7 @@ import { JwtHeader, SigningKeyCallback, JwtPayload } from 'jsonwebtoken';
 import { configInfo } from '../config.js';
 import { UserCache } from '@memberjunction/generic-database-provider';
 import sql from 'mssql';
-import { DatabaseProviderBase, Metadata, RoleInfo, UserInfo } from '@memberjunction/core';
+import { DatabaseProviderBase, LogError, Metadata, RoleInfo, UserInfo } from '@memberjunction/core';
 import { NewUserBase } from './newUsers.js';
 import { MJGlobal } from '@memberjunction/global';
 import { MJUserEntity, MJUserEntityType } from '@memberjunction/core-entities';
@@ -254,11 +254,63 @@ export const VerifyUserRecord = async (
 ): Promise<UserInfo | undefined> => {
   if (!email) return undefined;
 
-  // FindUser, not Users.find: a user this process has not loaded yet (created seconds ago on
-  // another server) is looked up in the database instead of being treated as nonexistent.
-  let user = await UserCache.Instance.FindUser({ Email: email });
+  // Collect ALL matches rather than taking .find()'s first hit. Two User rows can share an email
+  // case-insensitively (see the duplicate-provisioning path below), and .find() then resolved to
+  // whichever row happened to sit earlier in UserCache.Instance.Users — i.e. database row order.
+  // That order changes when the cache is rebuilt, so an MJAPI restart silently moved a user onto a
+  // different record: their conversations, artifacts, items shared with them and their profile
+  // picture (UserImageURL lives on the User row) all vanished at once, and came back if the order
+  // flipped again. Observed in production 2026-09-15. Resolution must not depend on row order.
+  const emailMatches = UserCache.Instance.Users.filter((u) => {
+    if (!u.Email || u.Email.trim() === '') {
+      // this condition should never occur. If it doesn throw a console error including the user id
+      // DB requires non-null but this is just an extra check and we could in theory have a blank string in the DB
+      console.error(`SYSTEM METADATA ISSUE: User ${u.ID} has no email address`);
+      return false;
+    } else return u.Email.toLowerCase().trim() === email.toLowerCase().trim();
+  });
+
+  if (emailMatches.length > 1) {
+    // Deterministic tie-break by ID so every process and every restart agrees, and a LOUD error
+    // because this is a data problem an operator has to resolve — silently picking a row is what
+    // made it look like data loss to the customer. Sorting by ID is arbitrary but stable; the point
+    // is that it never changes, not that it picks the "right" one.
+    emailMatches.sort((a, b) => a.ID.localeCompare(b.ID));
+    LogError(
+      `AMBIGUOUS LOGIN: ${emailMatches.length} User records share the email '${email}' ` +
+        `(case-insensitively): ${emailMatches.map((u) => `${u.ID} (${u.Email})`).join(', ')}. ` +
+        `Resolving to ${emailMatches[0].ID} by stable ID order. Until the duplicates are merged, ` +
+        `content owned by the other records is invisible to this login. Find every affected user ` +
+        `with: SELECT LOWER(Email), COUNT(*) FROM __mj.[User] GROUP BY LOWER(Email) HAVING COUNT(*) > 1`
+    );
+  }
+
+  // Nothing cached: ask FindUser, which reads the database for a user this process has not loaded
+  // yet (created seconds ago on another server) instead of treating them as nonexistent.
+  let user = emailMatches[0] ?? (await UserCache.Instance.FindUser({ Email: email }));
 
   if (!user) {
+    // REFRESH THE CACHE BEFORE PROVISIONING. This block used to sit AFTER the auto-create below,
+    // gated on `!user`, so it could only ever run when creation had already failed or was not
+    // attempted. That made it dead code in the exact case it exists to handle: a user who IS in the
+    // database but is NOT yet in this process's UserCache. Users provisioned out of band (an admin,
+    // an invite, a direct insert) are absent from the cache until it is rebuilt, so the lookup above
+    // missed and auto-create minted a SECOND record for someone who already had one — which is how
+    // the duplicate emails that Fix 1 above has to tolerate get created in the first place.
+    // Observed in production: three users created 2026-09-14 18:18, a duplicate for one of them
+    // created 2026-09-15 01:38 on that user's next sign-in.
+    //
+    // The recursive call passes attemptCacheUpdateIfNeeded=false, so the second pass skips straight
+    // to auto-create if the refreshed cache still has no match. Auto-provisioning of genuinely new
+    // users is therefore unchanged — it just no longer runs before we have looked properly.
+    if (configInfo.userHandling.updateCacheWhenNotFound && dataSource && attemptCacheUpdateIfNeeded) {
+      console.warn(`User ${email} not found in cache. Updating cache in attempt to find the user...`);
+
+      await refreshUserCache();
+
+      return VerifyUserRecord(email, firstName, lastName, requestDomain, dataSource, false);
+    }
+
     // NOTE: `requestDomain` (parsed from the spoofable `Origin` header) is deliberately NOT part of
     // this condition. It was previously required here, which meant a non-browser client sending no
     // Origin could never auto-provision while an attacker simply forged one — it gated entry without
@@ -313,14 +365,6 @@ export const VerifyUserRecord = async (
       }
     }
 
-    if (!user && configInfo.userHandling.updateCacheWhenNotFound && dataSource && attemptCacheUpdateIfNeeded) {
-      // if we get here that means in the above, if we were attempting to create a new user, it did not work, or it wasn't attempted and we have a config that asks us to auto update the cache
-      console.warn(`User ${email} not found in cache. Updating cache in attempt to find the user...`);
-
-      await refreshUserCache();
-
-      return VerifyUserRecord(email, firstName, lastName, requestDomain, dataSource, false); // try one more time but do not update cache next time if not found
-    }
   }
 
   return user;

package/src/auth/initializeProviders.ts

@@ -1,8 +1,35 @@
 import { configInfo } from '../config.js';
 import { AuthProviderConfig, LogError, LogStatus, LogStatusEx, UserInfo, type IMetadataProvider } from '@memberjunction/core';
-import { AuthProviderFactory } from '@memberjunction/auth-providers';
+import { AuthProviderFactory, LocalDevProvider } from '@memberjunction/auth-providers';
 import { AuthProviderEngine } from './AuthProviderEngine.js';
 
+/**
+ * Returns true when local development auth is enabled via `MJ_DEV_AUTH_ENABLED=true`
+ * or `configInfo.devAuth?.enabled === true`.
+ */
+export function IsLocalDevAuthEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  const rawEnv = env.MJ_DEV_AUTH_ENABLED?.trim().toLowerCase();
+  if (rawEnv === 'true' || rawEnv === '1') {
+    return true;
+  }
+  if (rawEnv === 'false' || rawEnv === '0') {
+    return false;
+  }
+  return configInfo?.devAuth?.enabled === true;
+}
+
+/**
+ * Enforces the production safety invariant: throws a fatal error if local dev auth
+ * is enabled while `NODE_ENV === 'production'`.
+ */
+export function AssertLocalDevAuthAllowed(env: NodeJS.ProcessEnv = process.env): void {
+  if (IsLocalDevAuthEnabled(env) && env.NODE_ENV?.trim().toLowerCase() === 'production') {
+    throw new Error(
+      '[SECURITY] Local dev auth (MJ_DEV_AUTH_ENABLED) is strictly forbidden when NODE_ENV=production. Refusing to start.'
+    );
+  }
+}
+
 /**
  * Initialize authentication providers from configuration.
  *
@@ -15,6 +42,8 @@ import { AuthProviderEngine } from './AuthProviderEngine.js';
  * connection and a system user exist.
  */
 export function InitializeAuthProviders(): void {
+  AssertLocalDevAuthAllowed();
+
   const factory = AuthProviderFactory.Instance;
 
   // Clear any existing providers
@@ -40,6 +69,19 @@ export function InitializeAuthProviders(): void {
     }
   }
 
+  if (IsLocalDevAuthEnabled()) {
+    configInfo.authProviders = configInfo.authProviders ?? [];
+    if (!configInfo.authProviders.some((p) => p.type === 'local' || p.name === 'local')) {
+      const localConfig = LocalDevProvider.ConfigFromEnvironment({
+        ...process.env,
+        MJ_DEV_AUTH_ENABLED: 'true',
+      });
+      if (localConfig) {
+        configInfo.authProviders.push(localConfig);
+      }
+    }
+  }
+
   // Initialize providers from authProviders config
   if (configInfo.authProviders && configInfo.authProviders.length > 0) {
     for (const providerConfig of configInfo.authProviders) {