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

package/src/broadcast/providers/AWSIoTCoreBroadcastProvider.ts

@@ -0,0 +1,180 @@
+import { createHash, createHmac } from 'node:crypto';
+import { RegisterClass } from '@memberjunction/global';
+import { UserInfo } from '@memberjunction/core';
+import {
+    BaseCacheInvalidationBroadcastProvider,
+    CacheBroadcastNegotiationResult,
+    CacheInvalidationBroadcastTopology,
+} from '../BaseCacheInvalidationBroadcastProvider.js';
+import type {
+    CacheInvalidationNotification,
+    CacheInvalidationPayload,
+} from '../../generic/CacheInvalidationResolver.js';
+
+/**
+ * Envelope published to an AWS IoT Core MQTT role topic.
+ */
+export interface AWSIoTCoreTopicMessage {
+    Topic: string;
+    QoS: 0 | 1;
+    Event: CacheInvalidationNotification;
+}
+
+/**
+ * Transport callback used by {@link AWSIoTCoreBroadcastProvider} to publish a shaped
+ * invalidation notification to an AWS IoT Core MQTT topic.
+ */
+export type AWSIoTCoreTopicPublisher = (message: AWSIoTCoreTopicMessage) => Promise<void>;
+
+/**
+ * Topology 3 Cloud Multiplexer Provider for **AWS IoT Core MQTT over WebSockets** (`'AWSIoTCore'`).
+ *
+ * Offloads per-client WebSocket connection management and message fan-out from MJServer
+ * to AWS IoT Core's managed MQTT message broker:
+ * - Each authenticated browser client calls `NegotiateCacheBroadcastConnection` to obtain
+ *   a SigV4-presigned `wss://<endpoint>/mqtt` URL and its authorized MQTT topic list
+ *   (`<topicPrefix>/roles/<RoleID>`).
+ * - When an entity mutation occurs, MJServer shapes the invalidation payload once per
+ *   authorized role on the entity and publishes to `<topicPrefix>/roles/<RoleID>`.
+ */
+@RegisterClass(BaseCacheInvalidationBroadcastProvider, 'AWSIoTCore')
+export class AWSIoTCoreBroadcastProvider extends BaseCacheInvalidationBroadcastProvider {
+    private _topicPublisher: AWSIoTCoreTopicPublisher | null = null;
+
+    public override get Topology(): CacheInvalidationBroadcastTopology {
+        return 'AWSIoTCore';
+    }
+
+    /**
+     * Installs a custom MQTT topic publisher (e.g., AWS SDK `IoTDataPlaneClient` adapter or test spy).
+     */
+    public SetTopicPublisher(publisher: AWSIoTCoreTopicPublisher | null): void {
+        this._topicPublisher = publisher;
+    }
+
+    /**
+     * Computes the MQTT topic filters (`<topicPrefix>/roles/<roleId>`) for a user's roles.
+     */
+    public GetAuthorizedTopicsForUser(user: UserInfo): string[] {
+        const prefix = (this._config.awsIoTCore?.topicPrefix || 'mj/cache').replace(/\/+$/, '');
+        const roles = user.UserRoles ?? [];
+        const topics: string[] = [];
+        for (const r of roles) {
+            const roleId = (r.RoleID ?? '').trim().toLowerCase();
+            if (roleId.length > 0) {
+                topics.push(`${prefix}/roles/${roleId}`);
+            }
+        }
+        topics.sort();
+        return topics;
+    }
+
+    protected override async OnInvalidationRecorded(payload: CacheInvalidationPayload): Promise<void> {
+        const prefix = (this._config.awsIoTCore?.topicPrefix || 'mj/cache').replace(/\/+$/, '');
+        const entity = this.ResolveEntityForPayload(payload);
+        if (!entity) {
+            return;
+        }
+
+        for (const perm of entity.Permissions) {
+            if (!perm.CanRead) continue;
+            const roleId = (perm.RoleID ?? '').trim().toLowerCase();
+            if (!roleId) continue;
+
+            const syntheticRoleHolder = { UserRoles: [{ RoleID: roleId }] };
+            const shaped = this.ShapeEventForSubscriber(payload, syntheticRoleHolder, entity);
+            const message: AWSIoTCoreTopicMessage = {
+                Topic: `${prefix}/roles/${roleId}`,
+                QoS: 1,
+                Event: shaped,
+            };
+
+            if (this._topicPublisher) {
+                await this._topicPublisher(message);
+            }
+        }
+    }
+
+    public override async NegotiateClientConnection(
+        user: UserInfo,
+        defaultGraphQLWsUrl = '/graphql'
+    ): Promise<CacheBroadcastNegotiationResult> {
+        const endpoint = (this._config.awsIoTCore?.endpoint ?? '').replace(/^https?:\/\//i, '').replace(/\/+$/, '');
+        const region = this._config.awsIoTCore?.region || 'us-east-1';
+        const ttlSeconds = this._config.awsIoTCore?.tokenTtlSeconds ?? 3600;
+        const expiresAtMs = Date.now() + ttlSeconds * 1000;
+        const topics = this.GetAuthorizedTopicsForUser(user);
+
+        if (!endpoint) {
+            return {
+                Provider: this.Topology,
+                Url: defaultGraphQLWsUrl,
+                Groups: topics,
+                ExpiresAt: new Date(expiresAtMs).toISOString(),
+                ServerProcessID: this.ServerProcessID,
+                CurrentSequence: this.CurrentSequence,
+            };
+        }
+
+        const accessKeyId = this._config.awsIoTCore?.accessKeyId;
+        const secretAccessKey = this._config.awsIoTCore?.secretAccessKey;
+        const presignedUrl =
+            accessKeyId && secretAccessKey
+                ? this.buildSigV4PresignedMqttUrl(endpoint, region, accessKeyId, secretAccessKey, ttlSeconds)
+                : `wss://${endpoint}/mqtt`;
+
+        return {
+            Provider: this.Topology,
+            Url: presignedUrl,
+            Groups: topics,
+            ExpiresAt: new Date(expiresAtMs).toISOString(),
+            ServerProcessID: this.ServerProcessID,
+            CurrentSequence: this.CurrentSequence,
+        };
+    }
+
+    private buildSigV4PresignedMqttUrl(
+        host: string,
+        region: string,
+        accessKeyId: string,
+        secretAccessKey: string,
+        expiresSeconds: number
+    ): string {
+        const now = new Date();
+        const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, '');
+        const dateStamp = amzDate.slice(0, 8);
+        const service = 'iotdevicegateway';
+        const credentialScope = `${dateStamp}/${region}/${service}/aws4_request`;
+        const queryParams = [
+            `X-Amz-Algorithm=AWS4-HMAC-SHA256`,
+            `X-Amz-Credential=${encodeURIComponent(`${accessKeyId}/${credentialScope}`)}`,
+            `X-Amz-Date=${amzDate}`,
+            `X-Amz-Expires=${expiresSeconds}`,
+            `X-Amz-SignedHeaders=host`,
+        ].join('&');
+
+        const canonicalRequest = [
+            'GET',
+            '/mqtt',
+            queryParams,
+            `host:${host}\n`,
+            'host',
+            createHash('sha256').update('').digest('hex'),
+        ].join('\n');
+
+        const stringToSign = [
+            'AWS4-HMAC-SHA256',
+            amzDate,
+            credentialScope,
+            createHash('sha256').update(canonicalRequest).digest('hex'),
+        ].join('\n');
+
+        const kDate = createHmac('sha256', `AWS4${secretAccessKey}`).update(dateStamp).digest();
+        const kRegion = createHmac('sha256', kDate).update(region).digest();
+        const kService = createHmac('sha256', kRegion).update(service).digest();
+        const kSigning = createHmac('sha256', kService).update('aws4_request').digest();
+        const signature = createHmac('sha256', kSigning).update(stringToSign).digest('hex');
+
+        return `wss://${host}/mqtt?${queryParams}&X-Amz-Signature=${signature}`;
+    }
+}

package/src/broadcast/providers/AzureWebPubSubBroadcastProvider.ts

@@ -0,0 +1,182 @@
+import { createHmac } from 'node:crypto';
+import { RegisterClass } from '@memberjunction/global';
+import { UserInfo } from '@memberjunction/core';
+import {
+    BaseCacheInvalidationBroadcastProvider,
+    CacheBroadcastNegotiationResult,
+    CacheInvalidationBroadcastTopology,
+} from '../BaseCacheInvalidationBroadcastProvider.js';
+import type {
+    CacheInvalidationNotification,
+    CacheInvalidationPayload,
+} from '../../generic/CacheInvalidationResolver.js';
+
+/**
+ * Envelope published to an Azure Web PubSub role group.
+ */
+export interface AzureWebPubSubGroupMessage {
+    HubName: string;
+    GroupName: string;
+    Event: CacheInvalidationNotification;
+}
+
+/**
+ * Transport callback used by {@link AzureWebPubSubBroadcastProvider} to deliver a shaped
+ * invalidation notification to an Azure Web PubSub group.
+ */
+export type AzureWebPubSubGroupPublisher = (message: AzureWebPubSubGroupMessage) => Promise<void>;
+
+/**
+ * Topology 3 Cloud Multiplexer Provider for **Azure Web PubSub** (`'AzureWebPubSub'`).
+ *
+ * Offloads per-client WebSocket connection management and message fan-out from MJServer
+ * to Azure Web PubSub:
+ * - Each authenticated browser client calls `NegotiateCacheBroadcastConnection` to receive
+ *   a short-lived, HMAC-signed JWT access token scoped to its authorized role groups (`mj-role-<RoleID>`).
+ * - When an entity mutation occurs, MJServer shapes the invalidation payload once per
+ *   authorized role group on the entity and publishes a single group broadcast to Azure Web PubSub,
+ *   which fans the message out to thousands of connected browsers in C++ edge infrastructure.
+ */
+@RegisterClass(BaseCacheInvalidationBroadcastProvider, 'AzureWebPubSub')
+export class AzureWebPubSubBroadcastProvider extends BaseCacheInvalidationBroadcastProvider {
+    private _groupPublisher: AzureWebPubSubGroupPublisher | null = null;
+
+    public override get Topology(): CacheInvalidationBroadcastTopology {
+        return 'AzureWebPubSub';
+    }
+
+    /**
+     * Installs a custom group publisher (e.g., Azure WebPubSubServiceClient adapter or test spy).
+     * When unset and an HTTP endpoint + accessKey are configured, defaults to the Azure Web PubSub
+     * REST Data Plane API (`POST /api/hubs/{hub}/groups/{group}/:send`).
+     */
+    public SetGroupPublisher(publisher: AzureWebPubSubGroupPublisher | null): void {
+        this._groupPublisher = publisher;
+    }
+
+    /**
+     * Computes the Azure Web PubSub group names (`mj-role-<roleId>`) for a user's roles.
+     */
+    public GetAuthorizedGroupsForUser(user: UserInfo): string[] {
+        const roles = user.UserRoles ?? [];
+        const groups: string[] = [];
+        for (const r of roles) {
+            const roleId = (r.RoleID ?? '').trim().toLowerCase();
+            if (roleId.length > 0) {
+                groups.push(`mj-role-${roleId}`);
+            }
+        }
+        groups.sort();
+        return groups;
+    }
+
+    protected override async OnInvalidationRecorded(payload: CacheInvalidationPayload): Promise<void> {
+        const hubName = this._config.azureWebPubSub?.hubName || 'mj_cache_hub';
+        const entity = this.ResolveEntityForPayload(payload);
+        if (!entity) {
+            return;
+        }
+
+        // Group entity permissions by RoleID and shape once per authorized role
+        for (const perm of entity.Permissions) {
+            if (!perm.CanRead) continue;
+            const roleId = (perm.RoleID ?? '').trim().toLowerCase();
+            if (!roleId) continue;
+
+            const syntheticRoleHolder = { UserRoles: [{ RoleID: roleId }] };
+            const shaped = this.ShapeEventForSubscriber(payload, syntheticRoleHolder, entity);
+            const message: AzureWebPubSubGroupMessage = {
+                HubName: hubName,
+                GroupName: `mj-role-${roleId}`,
+                Event: shaped,
+            };
+
+            if (this._groupPublisher) {
+                await this._groupPublisher(message);
+            } else if (this._config.azureWebPubSub?.endpoint && this._config.azureWebPubSub?.accessKey) {
+                await this.publishViaRestApi(message);
+            }
+        }
+    }
+
+    public override async NegotiateClientConnection(
+        user: UserInfo,
+        defaultGraphQLWsUrl = '/graphql'
+    ): Promise<CacheBroadcastNegotiationResult> {
+        const endpoint = (this._config.azureWebPubSub?.endpoint ?? '').replace(/\/+$/, '');
+        const hubName = this._config.azureWebPubSub?.hubName || 'mj_cache_hub';
+        const accessKey = this._config.azureWebPubSub?.accessKey || '';
+        const ttlMinutes = this._config.azureWebPubSub?.tokenTtlMinutes ?? 60;
+        const expiresAtMs = Date.now() + ttlMinutes * 60 * 1000;
+        const groups = this.GetAuthorizedGroupsForUser(user);
+
+        if (!endpoint) {
+            return {
+                Provider: this.Topology,
+                Url: defaultGraphQLWsUrl,
+                Groups: groups,
+                ExpiresAt: new Date(expiresAtMs).toISOString(),
+                ServerProcessID: this.ServerProcessID,
+                CurrentSequence: this.CurrentSequence,
+            };
+        }
+
+        const wsEndpoint = endpoint.replace(/^http:/i, 'ws:').replace(/^https:/i, 'wss:');
+        const audience = `${endpoint}/client/hubs/${hubName}`;
+        const token = accessKey
+            ? this.mintJwtToken(audience, user.ID, groups, Math.floor(expiresAtMs / 1000), accessKey)
+            : undefined;
+        const url = token
+            ? `${wsEndpoint}/client/hubs/${hubName}?access_token=${encodeURIComponent(token)}`
+            : `${wsEndpoint}/client/hubs/${hubName}`;
+
+        return {
+            Provider: this.Topology,
+            Url: url,
+            Token: token,
+            Groups: groups,
+            ExpiresAt: new Date(expiresAtMs).toISOString(),
+            ServerProcessID: this.ServerProcessID,
+            CurrentSequence: this.CurrentSequence,
+        };
+    }
+
+    private mintJwtToken(
+        audience: string,
+        subject: string,
+        groups: string[],
+        expSeconds: number,
+        secret: string
+    ): string {
+        const header = Buffer.from(JSON.stringify({ alg: 'HS256', typ: 'JWT' })).toString('base64url');
+        const claims = Buffer.from(
+            JSON.stringify({
+                aud: audience,
+                sub: subject,
+                iat: Math.floor(Date.now() / 1000),
+                exp: expSeconds,
+                role: groups.map((g) => `webpubsub.joinLeaveGroup.${g}`),
+            })
+        ).toString('base64url');
+        const signingInput = `${header}.${claims}`;
+        const signature = createHmac('sha256', secret).update(signingInput).digest('base64url');
+        return `${signingInput}.${signature}`;
+    }
+
+    private async publishViaRestApi(message: AzureWebPubSubGroupMessage): Promise<void> {
+        const endpoint = (this._config.azureWebPubSub?.endpoint ?? '').replace(/\/+$/, '');
+        const accessKey = this._config.azureWebPubSub?.accessKey ?? '';
+        if (!endpoint || !accessKey) return;
+
+        const targetUrl = `${endpoint}/api/hubs/${encodeURIComponent(message.HubName)}/groups/${encodeURIComponent(message.GroupName)}/:send?api-version=2024-01-01`;
+        const token = this.mintJwtToken(targetUrl, 'mj-server', [], Math.floor(Date.now() / 1000) + 300, accessKey);
+        await fetch(targetUrl, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(message.Event),
+        });
+    }
+}

package/src/broadcast/providers/GCPPubSubBroadcastProvider.ts

@@ -0,0 +1,169 @@
+import { createHmac } from 'node:crypto';
+import { RegisterClass } from '@memberjunction/global';
+import { UserInfo } from '@memberjunction/core';
+import {
+    BaseCacheInvalidationBroadcastProvider,
+    CacheBroadcastNegotiationResult,
+    CacheInvalidationBroadcastTopology,
+} from '../BaseCacheInvalidationBroadcastProvider.js';
+import type {
+    CacheInvalidationNotification,
+    CacheInvalidationPayload,
+} from '../../generic/CacheInvalidationResolver.js';
+
+/**
+ * Envelope published to a Google Cloud Pub/Sub role topic.
+ */
+export interface GCPPubSubTopicMessage {
+    ProjectId: string;
+    TopicName: string;
+    Attributes: {
+        roleId: string;
+        entityName: string;
+        action: string;
+        sequence: string;
+    };
+    Event: CacheInvalidationNotification;
+}
+
+/**
+ * Transport callback used by {@link GCPPubSubBroadcastProvider} to publish a shaped
+ * invalidation notification to Google Cloud Pub/Sub.
+ */
+export type GCPPubSubTopicPublisher = (message: GCPPubSubTopicMessage) => Promise<void>;
+
+/**
+ * Topology 3 Cloud Multiplexer Provider for **Google Cloud Pub/Sub + Cloud Run WebSockets** (`'GCPPubSub'`).
+ *
+ * Offloads per-client WebSocket connection management and message fan-out from MJServer
+ * to a Google Cloud Pub/Sub + Cloud Run WebSocket fan-out gateway:
+ * - Each authenticated browser client calls `NegotiateCacheBroadcastConnection` to obtain
+ *   a signed gateway token and its authorized Pub/Sub role subscription attributes
+ *   (`projects/<projectId>/topics/<topicPrefix>-role-<RoleID>`).
+ * - When an entity mutation occurs, MJServer shapes the invalidation payload once per
+ *   authorized role on the entity and publishes a message with Pub/Sub filtering attributes.
+ */
+@RegisterClass(BaseCacheInvalidationBroadcastProvider, 'GCPPubSub')
+export class GCPPubSubBroadcastProvider extends BaseCacheInvalidationBroadcastProvider {
+    private _topicPublisher: GCPPubSubTopicPublisher | null = null;
+
+    public override get Topology(): CacheInvalidationBroadcastTopology {
+        return 'GCPPubSub';
+    }
+
+    /**
+     * Installs a custom Google Cloud Pub/Sub topic publisher (e.g., `@google-cloud/pubsub` adapter or test spy).
+     */
+    public SetTopicPublisher(publisher: GCPPubSubTopicPublisher | null): void {
+        this._topicPublisher = publisher;
+    }
+
+    /**
+     * Computes the fully-qualified GCP Pub/Sub topic names for a user's roles.
+     */
+    public GetAuthorizedTopicsForUser(user: UserInfo): string[] {
+        const projectId = this._config.gcpPubSub?.projectId || 'mj-default-project';
+        const prefix = this._config.gcpPubSub?.topicPrefix || 'mj-cache';
+        const roles = user.UserRoles ?? [];
+        const topics: string[] = [];
+        for (const r of roles) {
+            const roleId = (r.RoleID ?? '').trim().toLowerCase();
+            if (roleId.length > 0) {
+                topics.push(`projects/${projectId}/topics/${prefix}-role-${roleId}`);
+            }
+        }
+        topics.sort();
+        return topics;
+    }
+
+    protected override async OnInvalidationRecorded(payload: CacheInvalidationPayload): Promise<void> {
+        const projectId = this._config.gcpPubSub?.projectId || 'mj-default-project';
+        const prefix = this._config.gcpPubSub?.topicPrefix || 'mj-cache';
+        const entity = this.ResolveEntityForPayload(payload);
+        if (!entity) {
+            return;
+        }
+
+        for (const perm of entity.Permissions) {
+            if (!perm.CanRead) continue;
+            const roleId = (perm.RoleID ?? '').trim().toLowerCase();
+            if (!roleId) continue;
+
+            const syntheticRoleHolder = { UserRoles: [{ RoleID: roleId }] };
+            const shaped = this.ShapeEventForSubscriber(payload, syntheticRoleHolder, entity);
+            const message: GCPPubSubTopicMessage = {
+                ProjectId: projectId,
+                TopicName: `projects/${projectId}/topics/${prefix}-role-${roleId}`,
+                Attributes: {
+                    roleId,
+                    entityName: payload.entityName,
+                    action: payload.action,
+                    sequence: String(payload.sequence ?? 0),
+                },
+                Event: shaped,
+            };
+
+            if (this._topicPublisher) {
+                await this._topicPublisher(message);
+            }
+        }
+    }
+
+    public override async NegotiateClientConnection(
+        user: UserInfo,
+        defaultGraphQLWsUrl = '/graphql'
+    ): Promise<CacheBroadcastNegotiationResult> {
+        const gatewayUrl = (this._config.gcpPubSub?.gatewayUrl ?? '').replace(/\/+$/, '');
+        const signingSecret = this._config.gcpPubSub?.signingSecret || '';
+        const ttlSeconds = this._config.gcpPubSub?.tokenTtlSeconds ?? 3600;
+        const expiresAtMs = Date.now() + ttlSeconds * 1000;
+        const topics = this.GetAuthorizedTopicsForUser(user);
+
+        if (!gatewayUrl) {
+            return {
+                Provider: this.Topology,
+                Url: defaultGraphQLWsUrl,
+                Groups: topics,
+                ExpiresAt: new Date(expiresAtMs).toISOString(),
+                ServerProcessID: this.ServerProcessID,
+                CurrentSequence: this.CurrentSequence,
+            };
+        }
+
+        const wsGatewayUrl = gatewayUrl.replace(/^http:/i, 'ws:').replace(/^https:/i, 'wss:');
+        const token = signingSecret
+            ? this.mintGatewayToken(user.ID, topics, Math.floor(expiresAtMs / 1000), signingSecret)
+            : undefined;
+        const url = token ? `${wsGatewayUrl}?token=${encodeURIComponent(token)}` : wsGatewayUrl;
+
+        return {
+            Provider: this.Topology,
+            Url: url,
+            Token: token,
+            Groups: topics,
+            ExpiresAt: new Date(expiresAtMs).toISOString(),
+            ServerProcessID: this.ServerProcessID,
+            CurrentSequence: this.CurrentSequence,
+        };
+    }
+
+    private mintGatewayToken(
+        subject: string,
+        topics: string[],
+        expSeconds: number,
+        secret: string
+    ): string {
+        const header = Buffer.from(JSON.stringify({ alg: 'HS256', typ: 'JWT' })).toString('base64url');
+        const claims = Buffer.from(
+            JSON.stringify({
+                sub: subject,
+                iat: Math.floor(Date.now() / 1000),
+                exp: expSeconds,
+                topics,
+            })
+        ).toString('base64url');
+        const signingInput = `${header}.${claims}`;
+        const signature = createHmac('sha256', secret).update(signingInput).digest('base64url');
+        return `${signingInput}.${signature}`;
+    }
+}

package/src/broadcast/providers/SequencedRoleBucketBroadcastProvider.ts

@@ -0,0 +1,57 @@
+import { RegisterClass } from '@memberjunction/global';
+import { UserInfo } from '@memberjunction/core';
+import {
+    BaseCacheInvalidationBroadcastProvider,
+    CacheBroadcastNegotiationResult,
+    CacheInvalidationBroadcastManager,
+    CacheInvalidationBroadcastTopology,
+} from '../BaseCacheInvalidationBroadcastProvider.js';
+import type { CacheInvalidationPayload } from '../../generic/CacheInvalidationResolver.js';
+
+/**
+ * Default MemberJunction cache invalidation broadcast provider (`'SequencedRoleBucket'`).
+ *
+ * Combines:
+ * - **Topology 1 (Monotonic Sequence Ring Buffer + HTTP Header Piggybacking)**:
+ *   Every mutation assigns a monotonic `Sequence` integer, stores the event in a bounded ring buffer,
+ *   and piggybacks `X-MJ-Cache-Seq` and `X-MJ-Server-ID` onto GraphQL HTTP responses so clients can
+ *   detect and recover missed invalidations via `GetCacheInvalidationsSince` in a single delta query.
+ * - **Topology 2 (Role-Fingerprint $O(\text{Roles})$ Evaluation & Shaping Memoizer)**:
+ *   Memoizes entity-level read permission (`CanRead`) and row-level security key-withholding
+ *   (`ReadIsRowFiltered`) once per unique role fingerprint (`RoleID` set) per event instead of
+ *   re-evaluating permissions $N$ times across all connected WebSocket clients.
+ *
+ * Zero external cloud infrastructure is required.
+ */
+@RegisterClass(BaseCacheInvalidationBroadcastProvider, 'SequencedRoleBucket')
+export class SequencedRoleBucketBroadcastProvider extends BaseCacheInvalidationBroadcastProvider {
+    public override get Topology(): CacheInvalidationBroadcastTopology {
+        return 'SequencedRoleBucket';
+    }
+
+    protected override async OnInvalidationRecorded(_payload: CacheInvalidationPayload): Promise<void> {
+        // In-process GraphQL WebSocket subscriptions read directly from PubSub + role-bucket memoizer;
+        // no external cloud multiplexer dispatch is needed in SequencedRoleBucket mode.
+    }
+
+    public override async NegotiateClientConnection(
+        user: UserInfo,
+        defaultGraphQLWsUrl = '/graphql'
+    ): Promise<CacheBroadcastNegotiationResult> {
+        const fingerprint = this.GetRoleFingerprint(user);
+        const expiresAt = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+        return {
+            Provider: this.Topology,
+            Url: defaultGraphQLWsUrl,
+            Groups: [fingerprint],
+            ExpiresAt: expiresAt,
+            ServerProcessID: this.ServerProcessID,
+            CurrentSequence: this.CurrentSequence,
+        };
+    }
+}
+
+// Ensure the default provider factory is always registered even if ClassFactory lookup happens early.
+CacheInvalidationBroadcastManager.Instance.RegisterDefaultProviderFactory(
+    () => new SequencedRoleBucketBroadcastProvider()
+);

package/src/cache.ts

@@ -1,8 +1,9 @@
 import { LRUCache } from 'lru-cache';
+import type jwt from 'jsonwebtoken';
 
 const oneHourMs = 60 * 60 * 1000;
 
-export const AuthCache = new LRUCache({
+export const AuthCache = new LRUCache<string, jwt.JwtPayload | boolean>({
   max: 50000,
   ttl: oneHourMs,
   ttlAutopurge: false,