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

package/src/realtimeSessions/RealtimeVerifyRouter.ts

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview The PUBLIC verify-link routes of mid-session identity verification.
+ *
+ * Mounted BEFORE the unified auth middleware (the person opening the emailed link — often on another
+ * device — holds no MJ token; the single-use token IS the capability).
+ *
+ * | Route | Effect |
+ * |---|---|
+ * | `GET  /realtime/verify/:token` | Renders a one-button confirmation page. **No side effects.** |
+ * | `POST /realtime/verify` (form field `token`) | Redeems the token; renders "You're verified" or the uniform failure page. |
+ *
+ * ## Why the redemption is a POST
+ *
+ * Mail scanners and link previewers GET every URL in a message. A GET that consumed the single-use token
+ * would let a scanner burn it before the human clicks. The magic-link redeem endpoint made the same
+ * choice. The human's click submits the form.
+ *
+ * ## What the responses reveal
+ *
+ * Nothing about any session. A malformed token, an unknown session, an expired link, a used link and a
+ * voided verification all render the SAME page with the SAME status; success is a bare "You're verified".
+ * Responses are `no-store`, never framed, sent with `Referrer-Policy: no-referrer` (the token is in the
+ * URL of the GET), and carry a CSP that forbids everything but the page's own inline style.
+ *
+ * @module @memberjunction/server/realtimeSessions
+ */
+
+import { Router, urlencoded, type Request, type Response } from 'express';
+import { rateLimit } from 'express-rate-limit';
+import { LogError } from '@memberjunction/core';
+import { configInfo } from '../config.js';
+import { RealtimeSessionVerificationService } from './RealtimeSessionVerificationService.js';
+import { BuildVerifyConfirmHtml, BuildVerifyErrorHtml, BuildVerifyFailureHtml, BuildVerifySuccessHtml } from './verificationPages.js';
+import { ApiRoute } from '../apiRoot.js';
+
+/** Mount path of the public verify routes. Under `/realtime`, which is already reserved against server extensions. */
+export const REALTIME_VERIFY_MOUNT_PATH = '/realtime/verify';
+
+/** Headers every verify response carries. */
+function setSecurityHeaders(res: Response): void {
+    res.setHeader('Cache-Control', 'no-store');
+    res.setHeader('Referrer-Policy', 'no-referrer');
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('X-Frame-Options', 'DENY');
+    res.setHeader(
+        'Content-Security-Policy',
+        "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'",
+    );
+}
+
+/** Sends an HTML page with the verify security headers. */
+function sendPage(res: Response, status: number, html: string): void {
+    setSecurityHeaders(res);
+    res.status(status).type('html').send(html);
+}
+
+/**
+ * Builds the public verify router. Mount at {@link REALTIME_VERIFY_MOUNT_PATH} BEFORE the auth
+ * middleware.
+ *
+ * @param service - the verification service (injectable for tests; defaults to the process singleton)
+ */
+export function CreateRealtimeVerifyRouter(
+    service: Pick<RealtimeSessionVerificationService, 'RedeemLink'> = RealtimeSessionVerificationService.Instance,
+): Router {
+    const limits = configInfo.realtime?.identityVerification?.rateLimits;
+    // The route is public and a redemption does a database read + write, so it is throttled per IP — the
+    // same posture as the magic-link redeem endpoint. The message is the failure page, not JSON: this
+    // route talks to a browser.
+    const limiter = rateLimit({
+        windowMs: limits?.redeemWindowMs ?? 60_000,
+        limit: limits?.redeemPerIp ?? 30,
+        standardHeaders: 'draft-7',
+        legacyHeaders: false,
+        handler: (_req: Request, res: Response) => sendPage(res, 429, BuildVerifyFailureHtml()),
+    });
+
+    const router = Router();
+
+    // SAFE: renders the confirmation button. Never consumes the token (see the module header).
+    router.get('/:token', limiter, (req: Request, res: Response) => {
+        const token = typeof req.params.token === 'string' ? req.params.token : '';
+        sendPage(res, 200, BuildVerifyConfirmHtml(token, ApiRoute(REALTIME_VERIFY_MOUNT_PATH)));
+    });
+
+    // The side-effecting redemption, gated by a human gesture.
+    router.post('/', limiter, urlencoded({ extended: false, limit: '4kb' }), async (req: Request, res: Response) => {
+        const body = (req.body ?? {}) as { token?: unknown };
+        const token = typeof body.token === 'string' ? body.token : '';
+        try {
+            const result = await service.RedeemLink(token, req.ip);
+            if (result.Success) {
+                sendPage(res, 200, BuildVerifySuccessHtml());
+            } else if (result.ErrorCode === 'persist_failed') {
+                // A server fault after a VALID token: the link is still redeemable, so say "try again".
+                sendPage(res, 500, BuildVerifyErrorHtml());
+            } else {
+                // 410 for every other refusal: the page and status are identical whether the token was unknown,
+                // malformed, expired or used, so the route cannot be used to probe sessions.
+                sendPage(res, 410, BuildVerifyFailureHtml());
+            }
+        } catch (error) {
+            LogError(`RealtimeVerifyRouter: redemption threw: ${error instanceof Error ? error.message : String(error)}`);
+            sendPage(res, 500, BuildVerifyErrorHtml());
+        }
+    });
+
+    return router;
+}

package/src/realtimeSessions/RecordingAssemblyScheduler.ts

@@ -0,0 +1,234 @@
+/**
+ * @fileoverview Per-session timers that assemble a client-direct realtime recording from its shard ledger
+ * off the request path.
+ *
+ * The recording REST routes only record shards and the terminal signal; they never decode. When a route
+ * learns a session is ready (every expected shard present) it asks for an assembly now; when shards are
+ * missing it asks for one after the grace period, forced to `Partial`. This scheduler turns those requests
+ * into at most one pending timer and at most one running assembly per session in this process.
+ *
+ * Correctness across processes does not depend on it: every run starts with the ledger's atomic
+ * `ClaimAssembly`, so of two instances (or two timers) only the claim winner assembles. The per-session
+ * guard here only avoids wasted claims. A run that dies with the process leaves the session `Assembling`,
+ * and the session janitor's stale re-claim is the backstop for that and for any request dropped here.
+ *
+ * @module @memberjunction/server/realtimeSessions
+ */
+import { DatabaseProviderBase, LogError, LogStatus, UserInfo } from '@memberjunction/core';
+import { BaseSingleton, IShutdownable, ShutdownRegistry } from '@memberjunction/global';
+import {
+    AssembleRealtimeRecordingFromLedger, AssembleRealtimeRecordingInput, AssembleRealtimeRecordingOutcome,
+    IRealtimeRecordingLedger, SqlRealtimeRecordingLedger,
+} from '@memberjunction/ai-agents';
+
+/** A cancellable one-shot timer. */
+export interface RecordingAssemblyTimer {
+    Cancel(): void;
+}
+
+/** Time source of the scheduler; injectable so tests can drive it. */
+export interface RecordingAssemblyClock {
+    /** Milliseconds since the epoch. */
+    Now(): number;
+    /** Runs `callback` once after `delayMs`. The timer must not keep the process alive. */
+    StartTimer(callback: () => void, delayMs: number): RecordingAssemblyTimer;
+}
+
+/** The narrow scheduling contract the recording routes depend on. */
+export interface IRecordingAssemblyScheduler {
+    /**
+     * Requests an assembly of `sessionID` after `delayMs`. `forcePartial` assembles what exists even when
+     * shards are missing (the grace period ran out). See {@link RecordingAssemblyScheduler.ScheduleAssembly}.
+     */
+    ScheduleAssembly(sessionID: string, delayMs: number, forcePartial: boolean): void;
+}
+
+/** What {@link RecordingAssemblyScheduler.Start} needs. */
+export interface RecordingAssemblySchedulerOptions {
+    /** The server's own provider; assembly is server-owned background work, not a request. */
+    Provider: DatabaseProviderBase;
+    /** The user assembly runs as (the system user). */
+    SystemUser: UserInfo;
+    /** Grace before a `Deferred` (incomplete) assembly is retried as forced `Partial`. */
+    GraceMs: () => number;
+    /** Defaults to {@link SqlRealtimeRecordingLedger}. */
+    CreateLedger?: (provider: DatabaseProviderBase, contextUser: UserInfo) => IRealtimeRecordingLedger;
+    /** Defaults to {@link AssembleRealtimeRecordingFromLedger}. */
+    Assemble?: (input: AssembleRealtimeRecordingInput) => Promise<AssembleRealtimeRecordingOutcome>;
+    /** Defaults to `Date.now` and unref'd `setTimeout`. */
+    Clock?: RecordingAssemblyClock;
+}
+
+interface PendingAssembly {
+    DueAt: number;
+    ForcePartial: boolean;
+    Timer: RecordingAssemblyTimer;
+}
+
+const NODE_CLOCK: RecordingAssemblyClock = {
+    Now: () => Date.now(),
+    StartTimer: (callback, delayMs) => {
+        const handle = setTimeout(callback, delayMs);
+        handle.unref?.();
+        return { Cancel: () => clearTimeout(handle) };
+    },
+};
+
+/**
+ * Process-wide scheduler of recording assemblies (see the file overview). Call {@link Start} once at
+ * server startup; requests made before it (or after {@link Shutdown}) are logged and dropped, leaving the
+ * session to the janitor.
+ */
+export class RecordingAssemblyScheduler extends BaseSingleton<RecordingAssemblyScheduler> implements IShutdownable, IRecordingAssemblyScheduler {
+    private _options: Required<RecordingAssemblySchedulerOptions> | null = null;
+    private _registered = false;
+    /** Pending timers keyed by lowercase session id. */
+    private readonly pending = new Map<string, PendingAssembly>();
+    /** Lowercase ids of sessions with an assembly running in this process. */
+    private readonly running = new Set<string>();
+    /** Sessions asked for again while running, with the ForcePartial to re-run with. */
+    private readonly rerun = new Map<string, boolean>();
+
+    protected constructor() {
+        super();
+    }
+
+    /** Process-wide singleton accessor. */
+    public static get Instance(): RecordingAssemblyScheduler {
+        return super.getInstance<RecordingAssemblyScheduler>();
+    }
+
+    /** Identifier surfaced in graceful-shutdown logs. */
+    public readonly ShutdownName = 'RecordingAssemblyScheduler';
+
+    /** Configures the scheduler and enables it; calling again replaces the configuration. */
+    public Start(options: RecordingAssemblySchedulerOptions): void {
+        this._options = {
+            CreateLedger: (provider, contextUser) => new SqlRealtimeRecordingLedger(provider, contextUser),
+            Assemble: AssembleRealtimeRecordingFromLedger,
+            Clock: NODE_CLOCK,
+            ...options,
+        };
+        if (!this._registered) {
+            ShutdownRegistry.Instance.Register(this);
+            this._registered = true;
+        }
+    }
+
+    /**
+     * Requests an assembly of `sessionID` after `delayMs`. One pending timer per session: a request
+     * replaces the pending one only when it would fire sooner (at the same time, the merged request keeps
+     * `forcePartial` if either had it). A timer that fires while the session's previous run is still going
+     * is remembered and run right after it, never alongside it.
+     *
+     * Trade-off: a sooner un-forced request replaces a pending forced one. If that run comes back
+     * `Deferred` (still incomplete), the forced `Partial` is re-scheduled a full grace from then, so a
+     * forced Partial can land up to ~2× the grace after the first terminal signal. Accepted: the sooner
+     * run completes the recording outright whenever the missing shards did arrive.
+     */
+    public ScheduleAssembly(sessionID: string, delayMs: number, forcePartial: boolean): void {
+        const options = this._options;
+        if (!options) {
+            LogError(`RecordingAssemblyScheduler: not running; dropped the assembly request for session ${sessionID} (the session janitor will assemble it)`);
+            return;
+        }
+        const key = sessionID.toLowerCase();
+        const dueAt = options.Clock.Now() + Math.max(0, delayMs);
+        const existing = this.pending.get(key);
+        if (existing && existing.DueAt < dueAt) {
+            return;
+        }
+        if (existing && existing.DueAt === dueAt) {
+            existing.ForcePartial = existing.ForcePartial || forcePartial;
+            return;
+        }
+        existing?.Timer.Cancel();
+        const timer = options.Clock.StartTimer(() => this.onTimer(key, sessionID), dueAt - options.Clock.Now());
+        this.pending.set(key, { DueAt: dueAt, ForcePartial: forcePartial, Timer: timer });
+    }
+
+    /**
+     * Cancels every pending timer and stops accepting requests until the next {@link Start}. A running
+     * assembly is not awaited: if the process exits under it, the session stays `Assembling` and the
+     * janitor's stale re-claim finishes it. Idempotent.
+     */
+    public Shutdown(): void {
+        for (const entry of this.pending.values()) {
+            entry.Timer.Cancel();
+        }
+        this.pending.clear();
+        this.rerun.clear();
+        this._options = null;
+    }
+
+    private onTimer(key: string, sessionID: string): void {
+        const entry = this.pending.get(key);
+        if (!entry) {
+            return;
+        }
+        this.pending.delete(key);
+        if (this.running.has(key)) {
+            this.rerun.set(key, (this.rerun.get(key) ?? false) || entry.ForcePartial);
+            return;
+        }
+        void this.runUntilSettled(key, sessionID, entry.ForcePartial);
+    }
+
+    /** Runs the session's assembly, then any re-run requested meanwhile. Never rejects. */
+    private async runUntilSettled(key: string, sessionID: string, forcePartial: boolean): Promise<void> {
+        this.running.add(key);
+        try {
+            let next: boolean | undefined = forcePartial;
+            while (next !== undefined) {
+                await this.runOnce(sessionID, next);
+                next = this.rerun.get(key);
+                this.rerun.delete(key);
+            }
+        } finally {
+            this.running.delete(key);
+        }
+    }
+
+    /** One claim + assembly. Logs every failure with the session id; never throws. */
+    private async runOnce(sessionID: string, forcePartial: boolean): Promise<void> {
+        const options = this._options;
+        if (!options) {
+            LogStatus(`RecordingAssemblyScheduler: shut down before session ${sessionID} could assemble; the session janitor will assemble it`);
+            return;
+        }
+        try {
+            const ledger = options.CreateLedger(options.Provider, options.SystemUser);
+            const version = await ledger.ClaimAssembly(sessionID, null);
+            if (version === null) {
+                LogStatus(`RecordingAssemblyScheduler: session ${sessionID} not claimable (assembled, assembling elsewhere, or failed); skipping`);
+                return;
+            }
+            const outcome = await options.Assemble({
+                SessionID: sessionID, Version: version, Ledger: ledger,
+                ContextUser: options.SystemUser, Provider: options.Provider, ForcePartial: forcePartial,
+            });
+            this.handleOutcome(sessionID, version, outcome, options);
+        } catch (error) {
+            LogError(`RecordingAssemblyScheduler: assembly of session ${sessionID} failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+
+    private handleOutcome(
+        sessionID: string,
+        version: number,
+        outcome: AssembleRealtimeRecordingOutcome,
+        options: Required<RecordingAssemblySchedulerOptions>,
+    ): void {
+        if (outcome === 'Deferred') {
+            // Incomplete and not forced: give missing shards the grace period, then assemble what exists.
+            LogStatus(`RecordingAssemblyScheduler: session ${sessionID} (version ${version}) is missing shards; assembling as Partial after the grace period`);
+            this.ScheduleAssembly(sessionID, options.GraceMs(), true);
+            return;
+        }
+        if (outcome === 'Retry') {
+            LogError(`RecordingAssemblyScheduler: assembly of session ${sessionID} (version ${version}) hit a transient error; the session janitor re-claims it later`);
+            return;
+        }
+        LogStatus(`RecordingAssemblyScheduler: session ${sessionID} (version ${version}) assembly finished: ${outcome}`);
+    }
+}

package/src/realtimeSessions/SessionVerificationPortsBase.ts

@@ -0,0 +1,189 @@
+/**
+ * @fileoverview {@link SessionVerificationPortsBase} — the config-free half of the production
+ * {@link VerificationPorts}: reading and writing a session, publishing `identity.verified`, and the
+ * audit entry. Everything that depends on server configuration (the settings, the service principal,
+ * the mail provider) is left abstract.
+ *
+ * The split exists so the DB-facing behaviour can be exercised with real sessions by anything that
+ * cannot — or must not — load the server's configuration at import time (the integration-test bundle
+ * subclasses it with captured email and a fixed principal). `RuntimeVerificationPorts`, in
+ * `RealtimeSessionVerificationService.ts`, is the production subclass that supplies the configuration.
+ *
+ * ## Which identity performs the writes, and why
+ *
+ * Reads of the session for **authorization** run as the CALLER, so row-level security is the first gate
+ * (a widget guest cannot even load another guest's session). Every **write** of server-decided state
+ * runs as a service principal ({@link SessionVerificationPortsBase.ResolveServiceUser}), inside
+ * `RunWithTrustedSessionConfigWrites`. That is not a convenience: the session owner can already `Update`
+ * their own session row, which is exactly why `MJAIAgentSessionEntityServer` refuses owner writes to
+ * `identityVerification` and `maxSessionDeadlineIso`. Server-decided state must be written by the server,
+ * after the caller was authorized, in a scope no remote caller can enter. The verify link has no caller
+ * identity at all (the token is the capability), so it needs the service principal for its reads too.
+ *
+ * @module @memberjunction/server/realtimeSessions
+ */
+
+import { LogError, Metadata, type IMetadataProvider, type UserInfo } from '@memberjunction/core';
+import { RunWithTrustedSessionConfigWrites } from '@memberjunction/core-entities-server';
+import type { MJAuditLogEntity } from '@memberjunction/core-entities';
+import type { IdentityVerifiedEventPayload } from '@memberjunction/ai-core-plus';
+import { LoadSessionForAccess, type LoadedSessionForAccess } from './sessionAccess.js';
+import { RealtimeSessionEventService } from './RealtimeSessionEventService.js';
+import {
+    type ConfigMutation,
+    type ConfigMutationResult,
+    type OutboundEmail,
+    type SessionSnapshot,
+    type VerificationAuditEntry,
+    type VerificationCaller,
+    type VerificationPorts,
+    type VerificationSettings,
+} from './verificationWorkflow.js';
+
+/** The seeded audit-log type (see `metadata/audit-log-types/.realtime-session-audit-types.json`). */
+export const REALTIME_IDENTITY_VERIFIED_AUDIT_TYPE = 'Realtime Identity Verified';
+
+const AUDIT_LOG_ENTITY = 'MJ: Audit Logs';
+const SESSION_ENTITY_NAME = 'MJ: AI Agent Sessions';
+
+
+/** Reduces a loaded session to the snapshot the workflow reasons about. */
+function toSnapshot(loaded: LoadedSessionForAccess): SessionSnapshot {
+    const { Session } = loaded;
+    return {
+        AgentSessionID: Session.ID,
+        OwnerUserID: Session.UserID,
+        ConversationExternalID: loaded.ConversationExternalID,
+        Status: Session.Status,
+        ConfigRaw: Session.Config_,
+        // `__mj_CreatedAt` is the row's creation instant — i.e. the session start. It is read-only and
+        // set by the database, so a client cannot move it.
+        StartedAtMs: Session.__mj_CreatedAt instanceof Date ? Session.__mj_CreatedAt.getTime() : Date.now(),
+    };
+}
+
+
+/**
+ * The session-facing {@link VerificationPorts}, minus configuration. Subclasses supply the settings, the
+ * service principal and the mail delivery.
+ */
+export abstract class SessionVerificationPortsBase implements VerificationPorts {
+    /** The live settings. */
+    public abstract GetSettings(): VerificationSettings;
+
+    /** Delivers an email. Must not throw; reports failure in the result. */
+    public abstract SendEmail(email: OutboundEmail): Promise<{ Success: boolean; ErrorMessage?: string }>;
+
+    /** The principal state writes (and the link caller's reads) run as; null when none is available. */
+    protected abstract ResolveServiceUser(): UserInfo | null;
+
+    public Now(): number {
+        return Date.now();
+    }
+
+    public async LoadSession(agentSessionId: string, caller: VerificationCaller): Promise<SessionSnapshot | null> {
+        const reader = this.readerFor(caller);
+        if (!reader) {
+            return null;
+        }
+        const loaded = await LoadSessionForAccess(agentSessionId, reader.User, reader.Provider);
+        return loaded ? toSnapshot(loaded) : null;
+    }
+
+    public async MutateSessionConfig<T>(
+        agentSessionId: string,
+        caller: VerificationCaller,
+        mutate: ConfigMutation<T>,
+    ): Promise<ConfigMutationResult<T>> {
+        const writer = this.writerFor(caller);
+        if (!writer) {
+            return { Persisted: false, ErrorMessage: 'No service principal is available to record verification state.' };
+        }
+        try {
+            const loaded = await LoadSessionForAccess(agentSessionId, writer.User, writer.Provider);
+            if (!loaded) {
+                return { Persisted: false, ErrorMessage: `Session ${agentSessionId} could not be read.` };
+            }
+            const session = toSnapshot(loaded);
+            const { NextConfigRaw, Outcome } = mutate(session);
+            if (NextConfigRaw === null) {
+                return { Session: session, Outcome, Persisted: false };
+            }
+            loaded.Session.Config_ = NextConfigRaw;
+            const saved = await RunWithTrustedSessionConfigWrites(() => loaded.Session.Save());
+            if (!saved) {
+                const detail = loaded.Session.LatestResult?.CompleteMessage ?? 'unknown error';
+                LogError(`RealtimeSessionVerification: saving session ${agentSessionId} failed: ${detail}`);
+                return { Session: session, Outcome, Persisted: false, ErrorMessage: detail };
+            }
+            return { Session: session, Outcome, Persisted: true };
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            LogError(`RealtimeSessionVerification: updating session ${agentSessionId} threw: ${message}`);
+            return { Persisted: false, ErrorMessage: message };
+        }
+    }
+
+    public PublishVerified(
+        routing: { AgentSessionID: string; OwnerUserID: string; ScopeKey: string | null },
+        payload: IdentityVerifiedEventPayload,
+    ): { Success: boolean; ErrorMessage?: string } {
+        return RealtimeSessionEventService.Instance.PublishRouted(routing, 'identity.verified', payload);
+    }
+
+    public async WriteAudit(entry: VerificationAuditEntry): Promise<void> {
+        const writer = this.ResolveServiceUser();
+        const provider = Metadata.Provider; // global-provider-ok: server-side audit write under the server's single default provider
+        const type = provider?.AuditLogTypes?.find((t) => t.Name?.trim().toLowerCase() === REALTIME_IDENTITY_VERIFIED_AUDIT_TYPE.toLowerCase());
+        const sessionEntityId = provider?.EntityByName(SESSION_ENTITY_NAME)?.ID;
+        if (!writer || !type) {
+            // The audit type ships as metadata (a release seed); without it, fall back to the server log so
+            // the verification is still recorded somewhere durable-ish rather than silently unaudited.
+            LogError(
+                `RealtimeSessionVerification: audit entry not written for session ${entry.AgentSessionID} ` +
+                    `(${writer ? `audit log type '${REALTIME_IDENTITY_VERIFIED_AUDIT_TYPE}' is not seeded` : 'no service principal'}): ` +
+                    `${entry.Email} via ${entry.Method}.`,
+            );
+            return;
+        }
+        try {
+            const row = await provider.GetEntityObject<MJAuditLogEntity>(AUDIT_LOG_ENTITY, writer);
+            row.NewRecord();
+            row.UserID = entry.OwnerUserID;
+            row.AuditLogTypeID = type.ID;
+            row.Status = 'Success';
+            row.EntityID = sessionEntityId ?? null;
+            row.RecordID = entry.AgentSessionID;
+            row.Description = `Realtime session verified ${entry.Email} by ${entry.Method === 'link' ? 'emailed link' : 'typed code'}.`;
+            row.Details = JSON.stringify({
+                email: entry.Email,
+                method: entry.Method,
+                ipAddress: entry.ClientIp ?? null,
+                maxSessionDeadlineIso: entry.MaxSessionDeadlineIso ?? null,
+            });
+            if (!(await row.Save())) {
+                LogError(`RealtimeSessionVerification: audit row save failed for session ${entry.AgentSessionID}: ${row.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+            }
+        } catch (error) {
+            LogError(`RealtimeSessionVerification: audit write threw for session ${entry.AgentSessionID}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+
+    /** The identity + provider an authorization read runs under. */
+    private readerFor(caller: VerificationCaller): { User: UserInfo; Provider: IMetadataProvider } | null {
+        if (caller.Kind === 'principal') {
+            return { User: caller.ContextUser, Provider: caller.Provider };
+        }
+        const user = this.ResolveServiceUser();
+        return user ? { User: user, Provider: Metadata.Provider } : null; // global-provider-ok: public verify route has no request-scoped provider
+    }
+
+    /** The identity + provider a state write runs under: always the service principal. */
+    private writerFor(caller: VerificationCaller): { User: UserInfo; Provider: IMetadataProvider } | null {
+        const user = this.ResolveServiceUser();
+        if (!user) {
+            return null;
+        }
+        return { User: user, Provider: caller.Kind === 'principal' ? caller.Provider : Metadata.Provider }; // global-provider-ok: public verify route has no request-scoped provider
+    }
+}

package/src/realtimeSessions/SlidingWindowRateLimiter.ts

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview A small in-memory sliding-window rate limiter keyed by string, with an injectable
+ * clock so it is deterministic under test.
+ *
+ * Used for the limits that the HTTP-layer `express-rate-limit` cannot express because the request is a
+ * GraphQL mutation (per IP / per email domain / per recipient on verification sends, and per session on
+ * code attempts). The HTTP verify route uses `express-rate-limit` directly, the same way the widget
+ * and magic-link routers do.
+ *
+ * **Per-instance, best-effort.** State is in process memory, so with several server replicas each
+ * enforces its own budget. That is the same trade the widget mint limiter makes. The limits that must
+ * hold across replicas — sends per session and code attempts per verification — are NOT here: they are
+ * persisted on the session (`identityVerification`) and enforced from the database.
+ *
+ * @module @memberjunction/server/realtimeSessions
+ */
+
+/** Outcome of {@link SlidingWindowRateLimiter.TryConsume}. */
+export interface RateLimitDecision {
+    /** True when the event fits the budget (and was counted). */
+    Allowed: boolean;
+    /** When refused, ms until the oldest counted event leaves the window. 0 when allowed. */
+    RetryAfterMs: number;
+}
+
+/** Construction options. */
+export interface SlidingWindowRateLimiterOptions {
+    /** Events allowed per key per window. A limit of 0 or less disables the limiter (everything allowed). */
+    Limit: number;
+    /** Window length in ms. */
+    WindowMs: number;
+    /** Upper bound on distinct keys held in memory; the oldest-seen keys are evicted past it. Default 10 000. */
+    MaxKeys?: number;
+}
+
+/** Default bound on distinct keys held. */
+const DEFAULT_MAX_KEYS = 10_000;
+
+/**
+ * Counts events per key over a sliding window.
+ *
+ * Memory is bounded two ways: a key's timestamps older than the window are dropped whenever the key is
+ * touched, and when the number of keys exceeds `MaxKeys` the least-recently-inserted keys are evicted
+ * (an evicted key simply starts a fresh window — the limiter fails open by forgetting, never closed).
+ */
+export class SlidingWindowRateLimiter {
+    private readonly events = new Map<string, number[]>();
+    private readonly maxKeys: number;
+
+    constructor(private readonly options: SlidingWindowRateLimiterOptions) {
+        this.maxKeys = options.MaxKeys ?? DEFAULT_MAX_KEYS;
+    }
+
+    /**
+     * Counts one event for `key` if the budget allows.
+     *
+     * @param key - what is being limited (an IP, a domain, a session id…); callers normalise it
+     * @param nowMs - the current time, epoch ms
+     */
+    public TryConsume(key: string, nowMs: number): RateLimitDecision {
+        if (this.options.Limit <= 0) {
+            return { Allowed: true, RetryAfterMs: 0 };
+        }
+        const windowStart = nowMs - this.options.WindowMs;
+        const live = (this.events.get(key) ?? []).filter((t) => t > windowStart);
+        if (live.length >= this.options.Limit) {
+            this.store(key, live);
+            return { Allowed: false, RetryAfterMs: Math.max(0, live[0] + this.options.WindowMs - nowMs) };
+        }
+        live.push(nowMs);
+        this.store(key, live);
+        return { Allowed: true, RetryAfterMs: 0 };
+    }
+
+    /** Number of keys currently tracked (exposed for tests and diagnostics). */
+    public get TrackedKeyCount(): number {
+        return this.events.size;
+    }
+
+    /** Re-inserts `key` (moving it to the newest position) and evicts the oldest keys past the bound. */
+    private store(key: string, timestamps: number[]): void {
+        this.events.delete(key);
+        this.events.set(key, timestamps);
+        while (this.events.size > this.maxKeys) {
+            const oldest = this.events.keys().next();
+            if (oldest.done) {
+                break;
+            }
+            this.events.delete(oldest.value);
+        }
+    }
+}

package/src/realtimeSessions/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Realtime session events + mid-session identity verification — module barrel.
+ * @module @memberjunction/server/realtimeSessions
+ */
+export * from './sessionAccess.js';
+export * from './subscriptionAuthorization.js';
+export * from './RealtimeSessionEventService.js';
+export * from './verificationPolicy.js';
+export * from './verificationCore.js';
+export * from './SlidingWindowRateLimiter.js';
+export * from './verificationPages.js';
+export * from './verificationWorkflow.js';
+export * from './sessionConfigStamps.js';
+export * from './SessionVerificationPortsBase.js';
+export * from './RealtimeSessionVerificationService.js';
+export * from './RealtimeVerifyRouter.js';
+export * from './ownedRealtimeSession.js';
+export * from './RecordingAssemblyScheduler.js';