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

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

@@ -0,0 +1,358 @@
+/**
+ * Field-Level Security at the GraphQL read boundary, for `MJ: Record Changes`.
+ *
+ * `MapFieldNamesToCodeNames` is where denied fields are stripped and encrypted ones masked on
+ * every single-record return path. It is also where the audit trail would otherwise walk straight
+ * out: Record Changes has field security switched OFF, so the denied-set logic sitting beside this
+ * is a no-op for it, and its `ChangesJSON` carries another entity's old and new values verbatim.
+ *
+ * These tests cover the resolver half specifically — the provider half (RunView, both cache paths)
+ * and the projection semantics themselves live in MJCore's
+ * `fieldSecurity.recordChanges.test.ts`.
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+// ─── Hoisted mocks (same preamble as resolverBase.fls.test.ts) ─────────────
+vi.mock('@memberjunction/sqlserver-dataprovider', () => ({
+    SQLServerDataProvider: class {},
+}));
+
+vi.mock('@memberjunction/generic-database-provider', () => ({
+    UserCache: { get Users() { return []; } },
+}));
+
+vi.mock('cloudevents', () => ({
+    CloudEvent: class {},
+    httpTransport: () => () => undefined,
+    emitterFor: () => () => undefined,
+}));
+
+vi.mock('type-graphql', () => ({
+    Resolver:           () => () => undefined,
+    Mutation:           () => () => undefined,
+    Query:              () => () => undefined,
+    Subscription:       () => () => undefined,
+    Ctx:                () => () => undefined,
+    Arg:                () => () => undefined,
+    PubSub:             () => () => undefined,
+    Root:               () => () => undefined,
+    ObjectType:         () => () => undefined,
+    InputType:          () => () => undefined,
+    Field:              () => () => undefined,
+    FieldResolver:      () => () => undefined,
+    Int:                () => undefined,
+    Float:              () => undefined,
+    registerEnumType:   () => undefined,
+}));
+
+vi.mock('graphql', () => ({
+    GraphQLError: class extends Error {
+        constructor(msg: string) { super(msg); }
+    },
+}));
+
+vi.mock('mssql', () => ({}));
+
+vi.mock('@memberjunction/api-keys', () => ({
+    GetAPIKeyEngine: vi.fn(),
+}));
+
+vi.mock('@memberjunction/encryption', () => ({
+    EncryptionEngine: { Instance: {} },
+}));
+
+// Unlike the sibling FLS suite, these tests actually RUN the mapper, so the mock has to answer
+// MapFieldName. Identity is correct here: none of the fixture's field names need bridging.
+vi.mock('@memberjunction/graphql-dataprovider', () => ({
+    FieldMapper: class {
+        public MapFieldName(name: string): string { return name; }
+        static Instance = { MapFieldsFromCodeNamesToDBNames: vi.fn() };
+    },
+}));
+
+vi.mock('../generic/PubSubManager.js', () => ({
+    PubSubManager: class { static Instance = { publish: vi.fn() }; },
+}));
+
+vi.mock('../generic/PushStatusResolver.js', () => ({
+    PUSH_STATUS_UPDATES_TOPIC: 'test-push-topic',
+    PushStatusNotification: class {},
+    PushStatusResolver: class {},
+}));
+
+vi.mock('../generic/CacheInvalidationResolver.js', () => ({
+    CACHE_INVALIDATION_TOPIC: 'test-cache-topic',
+}));
+
+vi.mock('../generic/RunViewResolver.js', () => ({
+    RunViewByIDInput: class {},
+    RunViewByNameInput: class {},
+    RunDynamicViewInput: class {},
+}));
+
+vi.mock('../generic/DeleteOptionsInput.js', () => ({
+    DeleteOptionsInput: class {},
+}));
+
+vi.mock('../types.js', () => ({
+    RunViewGenericParams: class {},
+}));
+
+vi.mock('@memberjunction/core', async () => {
+    const actual = await vi.importActual<typeof import('@memberjunction/core')>('@memberjunction/core');
+    return {
+        ...actual,
+        LogError: vi.fn(),
+        LogStatus: vi.fn(),
+    };
+});
+
+vi.mock('@memberjunction/core-entities', () => ({}));
+
+// ─── Import after mocks ──────────────────────────────────────────────────
+import { ResolverBase } from '../generic/ResolverBase';
+import { EntityInfo, IMetadataProvider, RecordChangesEntityName, UserInfo, UserRoleInfo } from '@memberjunction/core';
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────
+
+const HR_ROLE_ID = 'A0000000-0000-0000-0000-000000000001';
+const INTERN_ROLE_ID = 'A0000000-0000-0000-0000-000000000003';
+const EMPLOYEES_ENTITY_ID = 'E0000000-0000-0000-0000-0000000000E1';
+const RECORD_CHANGES_ENTITY_ID = 'E0000000-0000-0000-0000-0000000000E3';
+
+function openTo(fieldId: string, roles: string[] = [HR_ROLE_ID, INTERN_ROLE_ID]): Record<string, unknown>[] {
+    return roles.map((roleId, i) => ({
+        ID: `${fieldId}-open-${i}`,
+        EntityFieldID: fieldId,
+        RoleID: roleId,
+        ReadAccess: 'Allow',
+        UpdateAccess: 'Allow',
+        CreateAccess: 'Allow',
+    }));
+}
+
+/** The entity the audit rows are ABOUT — `Salary` readable only by HR. */
+function employeesEntity(): EntityInfo {
+    return new EntityInfo({
+        ID: EMPLOYEES_ENTITY_ID,
+        Name: 'Employees',
+        SchemaName: 'dbo',
+        BaseTable: 'Employee',
+        BaseView: 'vwEmployees',
+        IncludeInAPI: true,
+        EnableFieldLevelSecurity: true,
+        Permissions: [
+            { EntityID: EMPLOYEES_ENTITY_ID, RoleID: HR_ROLE_ID, CanRead: true },
+            { EntityID: EMPLOYEES_ENTITY_ID, RoleID: INTERN_ROLE_ID, CanRead: true },
+        ],
+        Fields: [
+            { ID: 'e-f-id', EntityID: EMPLOYEES_ENTITY_ID, Sequence: 1, Name: 'ID', Entity: 'Employees', Type: 'uniqueidentifier', IsPrimaryKey: true },
+            { ID: 'e-f-name', EntityID: EMPLOYEES_ENTITY_ID, Sequence: 2, Name: 'Name', Entity: 'Employees', Type: 'nvarchar', EntityFieldPermissions: openTo('e-f-name') },
+            { ID: 'e-f-salary', EntityID: EMPLOYEES_ENTITY_ID, Sequence: 3, Name: 'Salary', Entity: 'Employees', Type: 'money', EntityFieldPermissions: openTo('e-f-salary', [HR_ROLE_ID]) },
+        ],
+    });
+}
+
+/** The audit entity — field security OFF, which is the default and the point of the exercise. */
+function recordChangesEntity(): EntityInfo {
+    return new EntityInfo({
+        ID: RECORD_CHANGES_ENTITY_ID,
+        Name: RecordChangesEntityName,
+        SchemaName: '__mj',
+        BaseTable: 'RecordChange',
+        BaseView: 'vwRecordChanges',
+        IncludeInAPI: true,
+        EnableFieldLevelSecurity: false,
+        Permissions: [],
+        Fields: [
+            { ID: 'rc-f-id', EntityID: RECORD_CHANGES_ENTITY_ID, Sequence: 1, Name: 'ID', Entity: RecordChangesEntityName, Type: 'uniqueidentifier', IsPrimaryKey: true },
+            { ID: 'rc-f-entityid', EntityID: RECORD_CHANGES_ENTITY_ID, Sequence: 2, Name: 'EntityID', Entity: RecordChangesEntityName, Type: 'uniqueidentifier' },
+            { ID: 'rc-f-changesjson', EntityID: RECORD_CHANGES_ENTITY_ID, Sequence: 3, Name: 'ChangesJSON', Entity: RecordChangesEntityName, Type: 'nvarchar' },
+            { ID: 'rc-f-desc', EntityID: RECORD_CHANGES_ENTITY_ID, Sequence: 4, Name: 'ChangesDescription', Entity: RecordChangesEntityName, Type: 'nvarchar' },
+            { ID: 'rc-f-full', EntityID: RECORD_CHANGES_ENTITY_ID, Sequence: 5, Name: 'FullRecordJSON', Entity: RecordChangesEntityName, Type: 'nvarchar' },
+        ],
+    });
+}
+
+function buildUser(roleIds: string[], id = 'user-1'): UserInfo {
+    const u = new UserInfo();
+    u.ID = id;
+    u.Name = 'Test User';
+    u.Email = `${id}@test.com`;
+    u.IsActive = true;
+    (u as unknown as Record<string, unknown>)['_UserRoles'] =
+        roleIds.map(rid => new UserRoleInfo({ UserID: id, RoleID: rid, Role: `Role-${rid}` }));
+    return u;
+}
+
+/** Answers only what the mapper and the projector ask of a provider. */
+function testProvider(entities: EntityInfo[]): IMetadataProvider {
+    return {
+        get Entities() { return entities; },
+        EntityByName: (name: string) => entities.find(e => e.Name.trim().toLowerCase() === name?.trim().toLowerCase()),
+        EntityByID: (id: string) => entities.find(e => e.ID?.trim().toLowerCase() === id?.trim().toLowerCase()),
+    } as unknown as IMetadataProvider;
+}
+
+const SALARY_CHANGES_JSON = JSON.stringify({
+    Name: { field: 'Name', oldValue: 'Ada', newValue: 'Ada L' },
+    Salary: { field: 'Salary', oldValue: 100000, newValue: 120000 },
+});
+
+function changeRow(): Record<string, unknown> {
+    return {
+        ID: 'rc-1',
+        EntityID: EMPLOYEES_ENTITY_ID,
+        ChangesJSON: SALARY_CHANGES_JSON,
+        ChangesDescription: 'Salary changed from 100000 to 120000',
+        FullRecordJSON: JSON.stringify({ ID: 'emp-1', Name: 'Ada L', Salary: 120000 }),
+    };
+}
+
+/** Exposes the protected mapping and write-guard boundaries. */
+class TestResolver extends ResolverBase {
+    public MapOne(dataObject: Record<string, unknown>, user: UserInfo, provider: IMetadataProvider): Promise<Record<string, unknown>> {
+        return this.MapFieldNamesToCodeNames(RecordChangesEntityName, dataObject, user, provider);
+    }
+    public MapMany(rows: Record<string, unknown>[], user: UserInfo, provider: IMetadataProvider): Promise<Record<string, unknown>[]> {
+        return this.ArrayMapFieldNamesToCodeNames(RecordChangesEntityName, rows, user, provider);
+    }
+    public StripPayload(
+        entityInfo: EntityInfo, user: UserInfo,
+        input: { OldValues___?: Array<{ Key: string; Value: unknown }> } & Record<string, unknown>,
+        clientNewValues: Record<string, unknown>, provider: IMetadataProvider
+    ): boolean {
+        return this.StripRecordChangePayloadFromClientInput(entityInfo, user, input, clientNewValues, provider);
+    }
+}
+
+/** The shape UpdateRecord builds before applying the guards. */
+function clientPayload(fields: Record<string, unknown>, oldValues?: Array<{ Key: string; Value: unknown }>) {
+    const input: { OldValues___?: Array<{ Key: string; Value: unknown }> } & Record<string, unknown> = { ...fields };
+    if (oldValues) {
+        input.OldValues___ = oldValues;
+    }
+    return { input, clientNewValues: { ...fields } };
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────
+
+describe('MapFieldNamesToCodeNames — Record Changes payload security', () => {
+    let resolver: TestResolver;
+    let provider: IMetadataProvider;
+
+    beforeEach(() => {
+        resolver = new TestResolver();
+        provider = testProvider([employeesEntity(), recordChangesEntity()]);
+    });
+
+    it('narrows ChangesJSON and withholds ChangesDescription for a restricted caller', async () => {
+        const mapped = await resolver.MapOne(changeRow(), buildUser([INTERN_ROLE_ID]), provider);
+
+        expect(JSON.parse(mapped['ChangesJSON'] as string)).not.toHaveProperty('Salary');
+        expect(JSON.parse(mapped['ChangesJSON'] as string)).toHaveProperty('Name');
+        expect('ChangesDescription' in mapped).toBe(false);
+        expect(JSON.parse(mapped['FullRecordJSON'] as string)).not.toHaveProperty('Salary');
+    });
+
+    it('returns the full payload for a caller with no denials on the target entity', async () => {
+        const mapped = await resolver.MapOne(changeRow(), buildUser([HR_ROLE_ID]), provider);
+
+        expect(JSON.parse(mapped['ChangesJSON'] as string)).toHaveProperty('Salary');
+        expect(mapped['ChangesDescription']).toBe('Salary changed from 100000 to 120000');
+    });
+
+    it('does not modify the caller-supplied row — resolvers pass the cache its own objects', async () => {
+        const row = changeRow();
+        const snapshot = { ...row };
+        await resolver.MapOne(row, buildUser([INTERN_ROLE_ID]), provider);
+        expect(row).toEqual(snapshot);
+    });
+
+    it('applies the same treatment through the array form', async () => {
+        const mapped = await resolver.MapMany([changeRow(), changeRow()], buildUser([INTERN_ROLE_ID]), provider);
+
+        for (const row of mapped) {
+            expect(JSON.parse(row['ChangesJSON'] as string)).not.toHaveProperty('Salary');
+            expect('ChangesDescription' in row).toBe(false);
+        }
+    });
+
+    it('is a no-op with no context user', async () => {
+        const mapped = await resolver.MapOne(changeRow(), undefined as unknown as UserInfo, provider);
+        expect(mapped['ChangesDescription']).toBe('Salary changed from 100000 to 120000');
+    });
+});
+
+/**
+ * The write half. Without it the read projection destroys the thing it protects: a restricted
+ * caller is handed a NARROWED ChangesJSON, that value hydrates a client entity as an ordinary
+ * loaded value, and GenerateSaveSQL writes every SP-parameter field — so saving the record for any
+ * reason (editing Comments, say) would overwrite the stored audit payload with the narrowed one.
+ */
+describe('StripRecordChangePayloadFromClientInput (write guard)', () => {
+    let resolver: TestResolver;
+    let provider: IMetadataProvider;
+    let rcEntity: EntityInfo;
+
+    beforeEach(() => {
+        resolver = new TestResolver();
+        rcEntity = recordChangesEntity();
+        provider = testProvider([employeesEntity(), rcEntity]);
+    });
+
+    it('refuses every payload column a restricted caller sends back', () => {
+        const { input, clientNewValues } = clientPayload({
+            ID: 'rc-1',
+            Comments: 'looks fine',
+            ChangesJSON: JSON.stringify({ Name: { field: 'Name', oldValue: 'Ada', newValue: 'Ada L' } }), // narrowed
+            FullRecordJSON: JSON.stringify({ ID: 'emp-1', Name: 'Ada L' }),                               // narrowed
+        });
+
+        const forcedTruthLoad = resolver.StripPayload(rcEntity, buildUser([INTERN_ROLE_ID]), input, clientNewValues, provider);
+
+        expect(forcedTruthLoad).toBe(true);
+        expect(clientNewValues).toEqual({ ID: 'rc-1', Comments: 'looks fine' });
+        expect(input).not.toHaveProperty('ChangesJSON');
+        expect(input).not.toHaveProperty('FullRecordJSON');
+    });
+
+    it('leaves the edit the user actually made alone', () => {
+        const { input, clientNewValues } = clientPayload({ ID: 'rc-1', Comments: 'reviewed' });
+        resolver.StripPayload(rcEntity, buildUser([INTERN_ROLE_ID]), input, clientNewValues, provider);
+        expect(clientNewValues['Comments']).toBe('reviewed');
+    });
+
+    it('drops payload entries from OldValues so a narrowed value cannot read as a conflict', () => {
+        const { input, clientNewValues } = clientPayload(
+            { ID: 'rc-1', Comments: 'reviewed' },
+            [{ Key: 'ID', Value: 'rc-1' }, { Key: 'ChangesJSON', Value: '{"Name":{}}' }, { Key: 'Comments', Value: '' }]
+        );
+        resolver.StripPayload(rcEntity, buildUser([INTERN_ROLE_ID]), input, clientNewValues, provider);
+        expect(input.OldValues___).toEqual([{ Key: 'ID', Value: 'rc-1' }, { Key: 'Comments', Value: '' }]);
+    });
+
+    it('forces the truth-load even when the client sent no payload key at all', () => {
+        // 'MJ: Record Changes' has TrackRecordChanges off, so a client sending OldValues would
+        // otherwise hydrate from those values and never read what the database holds.
+        const { input, clientNewValues } = clientPayload({ ID: 'rc-1', Comments: 'x' }, [{ Key: 'ID', Value: 'rc-1' }]);
+        expect(resolver.StripPayload(rcEntity, buildUser([INTERN_ROLE_ID]), input, clientNewValues, provider)).toBe(true);
+    });
+
+    it('does NOT interfere with a caller who carries no denials anywhere', () => {
+        const payload = JSON.stringify({ Salary: { field: 'Salary', oldValue: 1, newValue: 2 } });
+        const { input, clientNewValues } = clientPayload({ ID: 'rc-1', ChangesJSON: payload });
+
+        const forcedTruthLoad = resolver.StripPayload(rcEntity, buildUser([HR_ROLE_ID]), input, clientNewValues, provider);
+
+        expect(forcedTruthLoad).toBe(false);
+        expect(clientNewValues['ChangesJSON']).toBe(payload);
+    });
+
+    it('does not apply to any other entity', () => {
+        const employees = employeesEntity();
+        const { input, clientNewValues } = clientPayload({ ID: 'e-1', ChangesJSON: '{}' });
+        expect(resolver.StripPayload(employees, buildUser([INTERN_ROLE_ID]), input, clientNewValues, provider)).toBe(false);
+        expect(clientNewValues['ChangesJSON']).toBe('{}');
+    });
+});

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

@@ -0,0 +1,101 @@
+/**
+ * What a write-refusal GraphQLError carries BESIDES its message.
+ *
+ * PR #3973 made the refusal's prose (`CompleteMessage`) reach the client. This is the structural
+ * half: a `Validate()` / `ValidateAsync()` refusal names the offending FIELD in each
+ * `ValidationErrorInfo.Source`, and the client's form can only paint that field red if the wire says
+ * which field. `RefusalExtensions` adds `extensions.validationErrors` for exactly that; the message
+ * is untouched. Written from the expected behaviour: the client (GraphQLDataProvider.Save) reads
+ * `response.errors[0].extensions.validationErrors` and hands it to `DeserializeValidationErrors`.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { BaseEntityResult } from '@memberjunction/core';
+import { DeserializeValidationErrors, ValidationErrorInfo, ValidationErrorType } from '@memberjunction/global';
+import { RefusalExtensions } from '../generic/refusalExtensions';
+
+function refused(...errors: ValidationErrorInfo[]): BaseEntityResult {
+    const result = new BaseEntityResult();
+    result.Success = false;
+    result.Errors = errors;
+    return result;
+}
+
+describe('RefusalExtensions', () => {
+    it('always carries the code and entity name the client already depends on', () => {
+        expect(RefusalExtensions('SAVE_ENTITY_ERROR', 'MJ: Tag Scopes', undefined)).toEqual({
+            code: 'SAVE_ENTITY_ERROR',
+            entityName: 'MJ: Tag Scopes',
+        });
+    });
+
+    it('omits validationErrors (not an empty array) when the refusal had no structured errors', () => {
+        // A SQL / provider failure sets Message and no Errors. A client must be able to tell
+        // "validation said no" from "the database said no" by the KEY being absent.
+        const dbFailure = new BaseEntityResult();
+        dbFailure.Success = false;
+        dbFailure.Message = 'Timeout expired while saving.';
+        const ext = RefusalExtensions('CREATE_ENTITY_ERROR', 'Widgets', dbFailure);
+        expect(ext).toEqual({ code: 'CREATE_ENTITY_ERROR', entityName: 'Widgets' });
+        expect('validationErrors' in ext).toBe(false);
+        expect('messageIncludesValidationErrors' in ext).toBe(false);
+    });
+
+    it('carries every field-named reason as a plain, JSON-safe object', () => {
+        const ext = RefusalExtensions(
+            'SAVE_ENTITY_ERROR',
+            'MJ: Tag Scopes',
+            refused(
+                new ValidationErrorInfo('TagID', 'Cannot add TagScope row for tag "Global" because it is marked IsGlobal=1.', 'abc'),
+                new ValidationErrorInfo('', 'Record-level note', null, ValidationErrorType.Warning),
+            ),
+        );
+        expect(ext.validationErrors).toEqual([
+            { Source: 'TagID', Message: 'Cannot add TagScope row for tag "Global" because it is marked IsGlobal=1.', Value: 'abc', Type: 'Failure' },
+            { Source: '', Message: 'Record-level note', Value: null, Type: 'Warning' },
+        ]);
+        // The server states that the message it throws (CompleteMessage) already renders these — the
+        // client must never have to infer that from the text.
+        expect(ext.messageIncludesValidationErrors).toBe(true);
+        // What GraphQL actually ships is JSON: the payload must survive it unchanged.
+        expect(JSON.parse(JSON.stringify(ext))).toEqual(ext);
+    });
+
+    it('is what the client rehydrates: DeserializeValidationErrors(extensions.validationErrors) round-trips', () => {
+        const original = [new ValidationErrorInfo('Amount', 'Amount must be positive', -5)];
+        const ext = RefusalExtensions('SAVE_ENTITY_ERROR', 'Orders', refused(...original));
+        const wire = JSON.parse(JSON.stringify(ext)) as { validationErrors?: unknown };
+        expect(DeserializeValidationErrors(wire.validationErrors)).toEqual(original);
+    });
+
+    it('does not alter the message the throw already carries — CompleteMessage stays the prose', () => {
+        const result = refused(new ValidationErrorInfo('TagID', 'No such Tag exists.', 'abc'));
+        // The resolver throws `CompleteMessage ?? 'Unknown error'` and attaches RefusalExtensions;
+        // both come from the same result, and the prose must remain a superset of the structured text.
+        expect(result.CompleteMessage).toContain('No such Tag exists.');
+        expect(RefusalExtensions('SAVE_ENTITY_ERROR', 'MJ: Tag Scopes', result).validationErrors?.[0].Message).toBe('No such Tag exists.');
+    });
+});
+
+describe('ResolverBase attaches RefusalExtensions on every LatestResult-backed refusal throw', () => {
+    const lines = readFileSync(fileURLToPath(new URL('../generic/ResolverBase.ts', import.meta.url)), 'utf8').split('\n');
+
+    it('each `LatestResult?.CompleteMessage ??` throw passes RefusalExtensions within the next two lines', () => {
+        const throws = lines
+            .map((line, i) => ({ line, n: i + 1 }))
+            .filter(({ line }) => /throw new GraphQLError\(entityObject\.LatestResult\?\.CompleteMessage \?\?/.test(line));
+        expect(throws.length, 'create, update and delete refusals').toBe(3);
+        for (const { n } of throws) {
+            const window = lines.slice(n, n + 2).join('\n');
+            expect(window, `throw at line ${n} must attach RefusalExtensions`).toMatch(/extensions:\s*RefusalExtensions\(/);
+        }
+    });
+
+    it('keeps the three error codes distinct and passes LatestResult, not a literal extensions object', () => {
+        const source = lines.join('\n');
+        for (const code of ['CREATE_ENTITY_ERROR', 'SAVE_ENTITY_ERROR', 'DELETE_ENTITY_ERROR']) {
+            expect(source).toMatch(new RegExp(`RefusalExtensions\\('${code}', entityName, entityObject\\.LatestResult\\)`));
+        }
+    });
+});

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/config.ts

@@ -539,11 +539,17 @@ const telephonySchema = z.object({
   teams: teamsMeetingsSchema.optional(),
 }).passthrough();
 
+const realtimeSchema = z.object({
+  /** Master switch. When false (default), the WebRTC SDP broker router is not mounted. */
+  enabled: zodBooleanWithTransforms().default(false),
+}).passthrough();
+
 const configInfoSchema = z.object({
   userHandling: userHandlingInfoSchema,
   magicLink: magicLinkSchema.optional().default({}),
   widget: widgetSchema.optional().default({}),
   telephony: telephonySchema.optional().default({}),
+  realtime: realtimeSchema.optional().default({}),
   databaseSettings: databaseSettingsInfoSchema,
   viewingSystem: viewingSystemInfoSchema.optional(),
   restApiOptions: restApiOptionsSchema.optional().default({}),
@@ -598,6 +604,7 @@ export type UserHandlingInfo = z.infer<typeof userHandlingInfoSchema>;
 export type MagicLinkConfig = z.infer<typeof magicLinkSchema>;
 export type WidgetConfig = z.infer<typeof widgetSchema>;
 export type TelephonyConfig = z.infer<typeof telephonySchema>;
+export type RealtimeConfig = z.infer<typeof realtimeSchema>;
 export type TwilioTelephonyConfig = z.infer<typeof twilioTelephonySchema>;
 export type VonageTelephonyConfig = z.infer<typeof vonageTelephonySchema>;
 export type RingCentralTelephonyConfig = z.infer<typeof ringcentralTelephonySchema>;
@@ -744,6 +751,11 @@ export const DEFAULT_SERVER_CONFIG: Partial<ConfigInfo> = {
     maxConcurrentRuns: 3
   },
 
+  // Realtime WebRTC SDP broker defaults (off by default)
+  realtime: {
+    enabled: parseBooleanEnv(process.env.MJ_REALTIME_ENABLED),
+  },
+
   // Telemetry defaults — on unless the operator turns it off via MJ_TELEMETRY_ENABLED.
   //
   // The env read lives HERE rather than in telemetrySchema for the same reason as