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

package/src/realtimeSessions/README.md

@@ -0,0 +1,179 @@
+# Realtime session events and identity verification
+
+Server side of two related capabilities of a realtime agent session:
+
+1. **Session events** — a typed, authorized channel from the server to the session's own client
+   (`RealtimeSessionEvents` subscription). Apps publish with `RealtimeSessionEventService`.
+2. **Mid-session identity verification** — a person (often an anonymous widget guest) proves they control
+   an email address *without leaving the conversation*. The server emails a one-time link and a typed
+   code, records the verification on the session, extends the session's limits, and publishes
+   `identity.verified`.
+
+The event contract (types, payload map, wire format) is framework-neutral and lives in
+`@memberjunction/ai-core-plus` (`realtime-session-events.ts`). Everything here is server-only.
+
+Verification **never creates an MJ user and never changes the session's principal** (decision D6): the
+session stays owned by whoever started it; verification only attaches a verified identity and relaxes the
+session's limits.
+
+## Flow
+
+```
+client                     MJServer                                   inbox
+  │  RequestRealtimeSessionVerification(sessionId, name, email)
+  ├──────────────────────────▶ policy + limits → store HASHED pending on Session.Config
+  │                            └─ email {link, code} ────────────────────▶ person
+  │  (subscription open: RealtimeSessionEvents(sessionId))
+  │                                       link opened (any device)  ◀──────┤
+  │                            GET  /realtime/verify/:token  → confirm page (NO side effects)
+  │                            POST /realtime/verify         → redeem (single use)
+  │  — or, same device —
+  ├─ SubmitRealtimeSessionVerificationCode(sessionId, code) ─▶ redeem (single use)
+  │                            mark verified · extend deadline · audit · publish identity.verified
+  ◀──────────────── event: identity.verified (only to the session's owner)
+```
+
+Event delivery has **no replay**. A client that was disconnected when the event fired recovers with
+`RealtimeSessionVerificationStatus(sessionId)` (and by reading the session).
+
+## Operations
+
+| Operation | Kind | Auth | Notes |
+|---|---|---|---|
+| `RequestRealtimeSessionVerification(agentSessionId, name, email)` | mutation | session's own principal | `email` is `@NoLog`. Sends the email. |
+| `SubmitRealtimeSessionVerificationCode(agentSessionId, code)` | mutation | session's own principal | `code` is `@NoLog`. Spaces/dashes ignored. |
+| `RealtimeSessionVerificationStatus(agentSessionId)` | query | session's own principal | The durable backstop for a missed event. |
+| `RealtimeSessionEvents(agentSessionId)` | subscription | session's own principal | See *Authorization*. |
+| `GET /realtime/verify/:token` | HTTP, **public** | the token is the capability | Renders a one-button confirmation page. Never consumes the token. |
+| `POST /realtime/verify` (form field `token`) | HTTP, **public** | the token is the capability | Redeems. Per-IP rate limited. |
+
+Every verification result carries a machine-readable `ErrorCode` (`invalid_email`, `consumer_domain`,
+`domain_blocked`, `rate_limited`, `send_limit_reached`, `invalid_code`, `attempts_exhausted`,
+`code_expired`, `session_not_found`, `session_closed`, `verification_unavailable`, …).
+
+The routes are only mounted, and the operations only act, when `realtime.identityVerification.enabled` is true
+**and** a `communicationProvider` is configured **and** an `hmacSecret` of at least 16 characters is set. Without the
+secret the feature reports itself unavailable (fail closed) and logs why at startup.
+
+The browser-side transport for the three operations and the subscription is `GraphQLRealtimeSessionClient` in
+`@memberjunction/graphql-dataprovider`.
+
+## Authorization
+
+The principal comes from the **server-authenticated** context (`userPayload.userRecord`), never from an
+argument. An id argument only selects *which of the caller's own sessions*.
+
+A caller may use a session when `AIAgentSession.UserID` equals their user (`UUIDsEqual`). Widget guests all
+share one Anonymous user, so for an anonymous/magic-link principal that is **not enough**: the guest's
+signed per-session scope (`MagicLinkScope.ResourceID`) must equal the session's conversation `ExternalID`.
+An anonymous principal with no scope is refused outright.
+
+- Refusals are uniform ("session not found") whether the session is missing or simply not yours, so ids
+  cannot be probed.
+- The subscription is authorized **twice**: when it opens, and again per event (each event carries an
+  owner/scope snapshot of its session), so a replicated event from another instance is judged like a local one.
+- State changes (`identityVerification`, `maxSessionDeadlineIso` on `AIAgentSession.Config`) are written by a
+  **service principal** inside a trusted-write scope, and `MJAIAgentSessionEntityServer` refuses any other
+  write to those keys — the session owner can update their own session row, so without that guard they
+  could forge verification or move their own deadline.
+
+## Policy knobs
+
+Set per deployment in `mj.config.cjs` → `realtime.identityVerification.policy`, and per agent/channel in the
+config cascade (`channels.config.IdentityVerification`, plus `session.unverifiedMaxSeconds` /
+`session.verifiedMaxSeconds`). The cascade layer is **snapshotted onto the session at mint**, so the rules a
+person is held to are fixed server-side and cannot be chosen later.
+
+| Knob | Default | Meaning |
+|---|---|---|
+| `requireBusinessDomain` | `false` | Refuse consumer mailbox providers (`consumer_domain`). |
+| `consumerDomains` | curated list (`DEFAULT_CONSUMER_EMAIL_DOMAINS`) | Overrides the curated list. An empty list is treated as absent. |
+| `blockedDomains` | `[]` | Always refused (`domain_blocked`). Matches subdomains. |
+| `linkTtlMinutes` | 30 (1–1440) | Lifetime of the link and code. |
+| `maxSendsPerSession` | 3 (1–20) | Verification emails one session may trigger (persisted, exact). |
+| `maxCodeAttempts` | 5 (1–10) | Wrong codes before the pending verification is voided. |
+| `unverifiedMaxSeconds` | none | Absolute session cap until verified. Applies to **any** principal. |
+| `verifiedMaxSeconds` | none | Cap after verification, measured from session start. Only ever *extends*. |
+
+Server-wide limits (`realtime.identityVerification.rateLimits`, in memory, per instance; `0` disables):
+`perIpSends`, `perEmailDomainSends`, `perEmailSends` over `sendWindowMs`; `perSessionCodeAttempts` over
+`codeAttemptWindowMs`; `redeemPerIp` over `redeemWindowMs`.
+
+Other settings: `communicationProvider`, `fromAddress`, `publicBaseUrl` (defaults like magic links),
+`contextUserForVerification` (the service principal; falls back to the system user), and:
+
+- `hmacSecret` (env `MJ_REALTIME_VERIFICATION_SECRET`): **required**. The server-only key the typed code is HMAC'd
+  under before it is stored. Never sent to a client or written to a session. Rotating it voids pending verifications only.
+- `deliveryMode`: `send` (default) delivers the email. `dry-run` builds and logs the message through the communication
+  provider **without delivering it**, for rehearsal and integration environments — the integration bundle reads the
+  link and code from the `MJ: Communication Logs` row. Never use it in production.
+
+## Security properties
+
+- **Hashed at rest, and the code hash is keyed.** The token and the code are never stored raw: a SHA-256 of the
+  token (256 random bits) and an **HMAC-SHA-256 of the code under the server-only `hmacSecret`**, salted and bound to the
+  session. The keying is what protects a six-digit code: the session's owner — the very person being verified — can
+  read their own `Session.Config`, and an unkeyed hash of a six-digit code is reversible offline in about a million
+  guesses, which would bypass the attempt cap and the inbox entirely. Verification compares digests with
+  `timingSafeEqual`.
+- **Single use, expiring.** Redemption clears the pending verification; an expired or used token is
+  refused. A wrong code consumes an attempt; the cap voids the verification.
+- **Scanner-safe link.** `GET` renders a confirmation button; only the human's `POST` consumes the token,
+  so mail scanners and previewers cannot burn it.
+- **Leak-free pages.** Every refusal (unknown, malformed, expired, used, voided) renders the same page with
+  the same status. Responses are `no-store`, `no-referrer`, never framed, with a CSP that forbids all but
+  the page's own inline style.
+- **Uniform errors.** Missing and not-yours sessions are indistinguishable.
+- **Bounded.** Per-IP, per-email-domain and per-address send limits; per-session code-attempt limit; a body
+  size limit on the public POST; the in-memory limiters are size-bounded.
+- **Audited.** A successful verification writes an `MJ: Audit Logs` row of type
+  *Realtime Identity Verified* (seeded by `metadata/audit-log-types`). If that type has not been seeded the
+  entry is written to the server log instead of being dropped silently.
+- **No principal change.** No user is created or switched.
+
+## Limitations to know about
+
+- **The email body is logged by the communication engine.** `CommunicationEngine.SendSingleMessage` writes an
+  `MJ: Communication Logs` row whose `MessageContent` contains the full body — here, the live link and code (the same
+  is already true of magic-link emails). Keep read access to that entity restricted to administrators. A principal who
+  can read it can redeem a verification for an address they do not control; `deliveryMode: 'dry-run'` makes that the
+  intended way to read the email, which is why it must never be used in production.
+
+- Rate limiters are per process. Across replicas the in-memory limits are best-effort; per-session send and
+  attempt counts are persisted and exact.
+- Single-use redemption is serialised per session in one process. Across replicas it is best-effort (there
+  is no compare-and-swap on a JSON column without a schema change).
+- The session janitor enforces `maxSessionDeadlineIso`; it closes with its normal `Janitor` reason (there
+  is no dedicated close reason, which would need a schema change).
+- Events have no replay (see *Flow*).
+
+## Publishing an event from an app
+
+```ts
+import { RealtimeSessionEventService } from '@memberjunction/server/realtime-sessions';
+
+const result = await RealtimeSessionEventService.Instance.Publish({
+    AgentSessionID, Type: 'identity.verified', Payload, ContextUser, Provider,
+});
+if (!result.Success) { /* result.ErrorMessage — Publish never throws */ }
+```
+
+Add new event types by extending `RealtimeSessionEventPayloadMap` (declaration merging) in
+`@memberjunction/ai-core-plus`; clients must ignore types they do not know.
+
+## Where things are
+
+| File | Role |
+|---|---|
+| `sessionAccess.ts`, `subscriptionAuthorization.ts` | The authorization decision and its subscription/event gates (pure, decorator-free). |
+| `RealtimeSessionEventService.ts` | Publisher + cross-instance fan-out hook. |
+| `verificationPolicy.ts`, `verificationCore.ts` | Policy resolution; token/code/state/hash/expiry logic (pure). |
+| `verificationWorkflow.ts` | The operations, written against injected ports. |
+| `SessionVerificationPortsBase.ts` | Config-free production ports (session IO, trusted writes, publish, audit). |
+| `RealtimeSessionVerificationService.ts` | Binds the ports to server configuration; process singleton. |
+| `RealtimeVerifyRouter.ts`, `verificationPages.ts` | The public routes and their pages. |
+| `sessionConfigStamps.ts` | What session start stamps (policy snapshot, unverified cap, inherited identity). |
+| `core.ts` | The configuration-free surface, published as `@memberjunction/server/realtime-sessions`. |
+
+The GraphQL resolvers are `../resolvers/RealtimeSessionVerificationResolver.ts` and
+`../resolvers/RealtimeSessionEventsResolver.ts`.

package/src/realtimeSessions/RealtimeSessionEventService.ts

@@ -0,0 +1,274 @@
+/**
+ * @fileoverview Server-side publisher for **realtime session events** — the hook an app (or MJ itself)
+ * calls to push a typed event into ONE live realtime session.
+ *
+ * The wire contract (event types, payload shapes, parsing) lives in `@memberjunction/ai-core-plus`
+ * (`realtime-session-events.ts`). This module owns the transport: it publishes onto MJServer's
+ * existing PubSub (`PubSubManager`) so the `RealtimeSessionEvents` GraphQL subscription can deliver it.
+ *
+ * ## Routing is part of the payload
+ *
+ * Every published event carries a snapshot of who may see it — the session's owner (`OwnerUserID`) and
+ * the session's anonymous scope id (`ScopeKey`). The subscription filter compares that snapshot with
+ * the **connection's** authenticated identity, so a subscriber who guesses another session's id still
+ * receives nothing. These two fields are server-internal: the GraphQL notification type does not
+ * expose them.
+ *
+ * ## Multiple server instances
+ *
+ * PubSub is in-process. Behind a load balancer the browser's WebSocket can live on a different replica
+ * than the one that handled the verification link. {@link RealtimeSessionEventService.SetReplicationHook}
+ * lets the host fan events out (the server wires it to Redis when `REDIS_URL` is set, exactly as it does
+ * for push-status updates), and {@link RealtimeSessionEventService.PublishReplicated} republishes an event
+ * that arrived from another instance.
+ *
+ * @example
+ * ```ts
+ * // From an Open App's server code, after it finished some work for a live session:
+ * await RealtimeSessionEventService.Instance.Publish({
+ *     AgentSessionID: sessionId,
+ *     Type: 'acme.quote.ready',
+ *     Payload: { QuoteID: quote.ID },
+ *     ContextUser: systemUser,
+ * });
+ * ```
+ *
+ * @module @memberjunction/server/realtimeSessions
+ */
+
+import { IMetadataProvider, LogError, Metadata, UserInfo } from '@memberjunction/core';
+import { BaseSingleton, MJGlobal } from '@memberjunction/global';
+import {
+    SerializeRealtimeSessionEvent,
+    type RealtimeSessionEventPayload,
+    type RealtimeSessionEventType,
+} from '@memberjunction/ai-core-plus';
+import { PubSubManager } from '../generic/PubSubManager.js';
+import { LoadSessionForAccess } from './sessionAccess.js';
+
+/** The PubSub topic every realtime session event is published on. */
+export const REALTIME_SESSION_EVENTS_TOPIC = 'REALTIME_SESSION_EVENTS';
+
+/**
+ * What is actually published on {@link REALTIME_SESSION_EVENTS_TOPIC}: the wire event plus the
+ * server-internal routing snapshot.
+ */
+export type RealtimeSessionEventTopicPayload = {
+    Type: string;
+    AgentSessionID: string;
+    OccurredAt: string;
+    /** The event payload, JSON-encoded. */
+    PayloadJson: string;
+    /** `AIAgentSession.UserID` — compared with the subscriber connection's user. Server-internal. */
+    OwnerUserID: string;
+    /** `Conversation.ExternalID` — compared with the subscriber's signed scope. Server-internal. */
+    ScopeKey: string | null;
+    /**
+     * `MJGlobal.ProcessUUID` of the instance that first published the event; lets an instance drop its
+     * own message when it echoes back from the replication bus.
+     */
+    SourceServerId?: string;
+};
+
+/** Who may receive an event, resolved from the session at publish time. */
+export interface RealtimeSessionEventRouting {
+    /** The session the event is addressed to. */
+    AgentSessionID: string;
+    /** The session's owner. */
+    OwnerUserID: string;
+    /** The session conversation's `ExternalID` (anonymous scope id), or null. */
+    ScopeKey: string | null;
+}
+
+/** Input to {@link RealtimeSessionEventService.Publish}. */
+export interface PublishRealtimeSessionEventInput<T extends RealtimeSessionEventType> {
+    /** The session to address. */
+    AgentSessionID: string;
+    /** Event type — a key of `RealtimeSessionEventPayloadMap`. */
+    Type: T;
+    /** Type-specific data; must be JSON-serializable. */
+    Payload: RealtimeSessionEventPayload<T>;
+    /**
+     * The identity to read the session under. Server-side publishers pass a system/service user — the
+     * session row is being addressed by the server, not on a caller's behalf.
+     */
+    ContextUser: UserInfo;
+    /** Provider to read the session with. Defaults to the process-global provider (server bootstrap use). */
+    Provider?: IMetadataProvider;
+}
+
+/** Outcome of a publish. A failure is never silent: it is also logged. */
+export interface PublishRealtimeSessionEventResult {
+    /** True when the event was handed to the PubSub. */
+    Success: boolean;
+    /** Why it was not, when it was not. */
+    ErrorMessage?: string;
+}
+
+/** Called for every locally-published event so the host can replicate it to other instances. */
+export type RealtimeSessionEventReplicationHook = (payload: RealtimeSessionEventTopicPayload) => void;
+
+/**
+ * Publishes realtime session events. A {@link BaseSingleton}: there is one publisher per process, and
+ * the replication hook is process-wide state.
+ */
+export class RealtimeSessionEventService extends BaseSingleton<RealtimeSessionEventService> {
+    private replicationHook: RealtimeSessionEventReplicationHook | undefined;
+
+    protected constructor() {
+        super();
+    }
+
+    /** The process-wide instance. */
+    public static get Instance(): RealtimeSessionEventService {
+        return super.getInstance<RealtimeSessionEventService>();
+    }
+
+    /**
+     * Publishes an event to one live session. Reads the session to snapshot its owner and scope, so the
+     * caller never supplies (and can never get wrong) who may receive the event.
+     *
+     * Does not require the session to be open: an event for a closed session simply reaches no
+     * subscriber.
+     *
+     * @returns a result rather than throwing — event delivery is best-effort, durable state lives
+     *   elsewhere (the verification status query is the backstop for a missed `identity.verified`).
+     */
+    public async Publish<T extends RealtimeSessionEventType>(
+        input: PublishRealtimeSessionEventInput<T>,
+    ): Promise<PublishRealtimeSessionEventResult> {
+        try {
+            const provider = input.Provider ?? Metadata.Provider; // global-provider-ok: documented last-resort fallback for server-bootstrap publishers
+            const loaded = await LoadSessionForAccess(input.AgentSessionID, input.ContextUser, provider);
+            if (!loaded) {
+                return this.fail(`Realtime session ${input.AgentSessionID} not found; event '${input.Type}' not published.`);
+            }
+            return this.PublishRouted(
+                {
+                    AgentSessionID: loaded.Session.ID,
+                    OwnerUserID: loaded.Session.UserID,
+                    ScopeKey: loaded.ConversationExternalID,
+                },
+                input.Type,
+                input.Payload,
+            );
+        } catch (error) {
+            return this.fail(`Publishing '${input.Type}' to session ${input.AgentSessionID} failed: ${errorText(error)}`);
+        }
+    }
+
+    /**
+     * Publishes an event when the caller already holds the session's routing (the verification service
+     * has just loaded the session, so it must not pay a second read).
+     */
+    public PublishRouted<T extends RealtimeSessionEventType>(
+        routing: RealtimeSessionEventRouting,
+        type: T,
+        payload: RealtimeSessionEventPayload<T>,
+    ): PublishRealtimeSessionEventResult {
+        const wire = SerializeRealtimeSessionEvent({
+            Type: type,
+            AgentSessionID: routing.AgentSessionID,
+            OccurredAt: new Date().toISOString(),
+            Payload: payload,
+        });
+        const topicPayload: RealtimeSessionEventTopicPayload = {
+            ...wire,
+            OwnerUserID: routing.OwnerUserID,
+            ScopeKey: routing.ScopeKey,
+            SourceServerId: MJGlobal.Instance.ProcessUUID,
+        };
+        if (!PubSubManager.Instance.PubSubEngine) {
+            return this.fail(`PubSub is not configured; event '${type}' for session ${routing.AgentSessionID} not published.`);
+        }
+        PubSubManager.Instance.Publish(REALTIME_SESSION_EVENTS_TOPIC, topicPayload);
+        this.replicate(topicPayload);
+        return { Success: true };
+    }
+
+    /**
+     * Republishes an event that arrived from another server instance onto THIS instance's local topic
+     * only (never back through the replication hook, so there is no loop). The subscription filter still
+     * decides who receives it — a replica has no say in who sees what.
+     */
+    public PublishReplicated(payload: RealtimeSessionEventTopicPayload): void {
+        PubSubManager.Instance.Publish(REALTIME_SESSION_EVENTS_TOPIC, payload);
+    }
+
+    /**
+     * Registers (or, with no argument, clears) the cross-instance fan-out hook. Inversion of control:
+     * this module must not know that Redis exists.
+     */
+    public SetReplicationHook(hook?: RealtimeSessionEventReplicationHook): void {
+        this.replicationHook = hook;
+    }
+
+    /** Hands a locally-published event to the replication hook, never letting a bus failure break local delivery. */
+    private replicate(payload: RealtimeSessionEventTopicPayload): void {
+        if (!this.replicationHook) {
+            return;
+        }
+        try {
+            this.replicationHook(payload);
+        } catch (error) {
+            // Replication is an optimisation over the durable status query; local delivery already happened.
+            LogError(`RealtimeSessionEventService: replication hook failed: ${errorText(error)}`);
+        }
+    }
+
+    private fail(message: string): PublishRealtimeSessionEventResult {
+        LogError(`RealtimeSessionEventService: ${message}`);
+        return { Success: false, ErrorMessage: message };
+    }
+}
+
+/**
+ * Validates an event received from the cross-instance message bus before it is republished locally.
+ *
+ * The bus carries messages from other processes, so every field is type-checked. Fails closed: an event
+ * with no routing identity can never be delivered safely, so it is dropped.
+ *
+ * @param raw - the JSON text taken off the bus
+ * @param localServerId - this process's `MJGlobal.ProcessUUID`, used to drop our own echo
+ * @returns the event to republish, or `null` to drop it
+ */
+export function ParseReplicatedRealtimeSessionEvent(raw: string, localServerId: string): RealtimeSessionEventTopicPayload | null {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch {
+        return null; // not JSON: nothing to deliver
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        return null;
+    }
+    const record = parsed as Record<string, unknown>;
+    const { Type, AgentSessionID, OccurredAt, PayloadJson, OwnerUserID, ScopeKey, SourceServerId } = record;
+    if (SourceServerId === localServerId) {
+        return null; // our own message, echoed back
+    }
+    const requiredStrings = [Type, AgentSessionID, OccurredAt, PayloadJson, OwnerUserID];
+    if (requiredStrings.some((value) => typeof value !== 'string' || value.length === 0)) {
+        return null; // includes a missing owner: fail closed
+    }
+    if (ScopeKey !== null && ScopeKey !== undefined && typeof ScopeKey !== 'string') {
+        return null;
+    }
+    if (SourceServerId !== undefined && typeof SourceServerId !== 'string') {
+        return null;
+    }
+    return {
+        Type: Type as string,
+        AgentSessionID: AgentSessionID as string,
+        OccurredAt: OccurredAt as string,
+        PayloadJson: PayloadJson as string,
+        OwnerUserID: OwnerUserID as string,
+        ScopeKey: typeof ScopeKey === 'string' ? ScopeKey : null,
+        SourceServerId: typeof SourceServerId === 'string' ? SourceServerId : undefined,
+    };
+}
+
+/** Message text of an unknown thrown value. */
+function errorText(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+}

package/src/realtimeSessions/RealtimeSessionVerificationService.ts

@@ -0,0 +1,168 @@
+/**
+ * @fileoverview `RealtimeSessionVerificationService` — the production wiring of mid-session identity
+ * verification: the real {@link VerificationPorts} (session read/write, email, event publish, audit)
+ * behind a process-wide singleton the GraphQL resolver and the public verify route both call.
+ *
+ * The decisions live in `verificationWorkflow.ts`; this file is deliberately thin glue. See that
+ * module's header for the operation table, what verification does and does not do, and the
+ * concurrency contract; see `README.md` in this folder for the end-to-end flow and security model.
+ *
+ * The session-facing half of the ports (reads, trusted writes, event publish, audit — and the reasoning
+ * for which identity performs which) is {@link SessionVerificationPortsBase}; this file adds the server
+ * configuration to it.
+ *
+ * @module @memberjunction/server/realtimeSessions
+ */
+
+import type { UserInfo } from '@memberjunction/core';
+import { BaseSingleton, TrimTrailingSlashes } from '@memberjunction/global';
+import { CommunicationEngine } from '@memberjunction/communication-engine';
+import { Message } from '@memberjunction/communication-types';
+import { UserCache } from '@memberjunction/generic-database-provider';
+import { configInfo } from '../config.js';
+import { ResolveConfiguredPrincipal } from '../auth/principals.js';
+import { SessionVerificationPortsBase } from './SessionVerificationPortsBase.js';
+import { ReadIdentityVerificationPolicyLayer } from './verificationPolicy.js';
+import {
+    RealtimeSessionVerificationWorkflow,
+    type OutboundEmail,
+    type PrincipalCaller,
+    type VerificationOperationResult,
+    type VerificationSettings,
+} from './verificationWorkflow.js';
+import { ConfiguredPublicUrl } from '../apiRoot.js';
+
+/** Purpose label for principal-resolution diagnostics. */
+const PRINCIPAL_PURPOSE = 'RealtimeVerification';
+
+/** The base URL emailed links are built from: explicit setting, else the server's public URL (same derivation magic links use). */
+function resolvePublicBaseUrl(explicit: string | undefined): string | undefined {
+    const candidate =
+        explicit?.trim() || ConfiguredPublicUrl();
+    return candidate ? TrimTrailingSlashes(candidate) : undefined;
+}
+
+/** The shortest `hmacSecret` accepted. */
+const MIN_HMAC_SECRET_LENGTH = 16;
+
+/** True when the configured HMAC secret is long enough to protect the stored code hash. */
+function hasUsableHmacSecret(secret: string | undefined): boolean {
+    return !!secret && secret.length >= MIN_HMAC_SECRET_LENGTH;
+}
+
+/** Reads the live settings from server config. */
+function readSettings(): VerificationSettings {
+    const cfg = configInfo.realtime?.identityVerification;
+    const limits = cfg?.rateLimits;
+    return {
+        // A feature that cannot send mail, or cannot protect the codes it issues, is not available — whatever `enabled` says.
+        Enabled: !!cfg?.enabled && !!cfg.communicationProvider && hasUsableHmacSecret(cfg.hmacSecret),
+        CodeHashKey: cfg?.hmacSecret ?? '',
+        PolicyDefaults: ReadIdentityVerificationPolicyLayer(cfg?.policy),
+        PublicBaseUrl: resolvePublicBaseUrl(cfg?.publicBaseUrl),
+        RateLimits: {
+            SendWindowMs: limits?.sendWindowMs ?? 3_600_000,
+            PerIpSends: limits?.perIpSends ?? 10,
+            PerEmailDomainSends: limits?.perEmailDomainSends ?? 30,
+            PerEmailSends: limits?.perEmailSends ?? 3,
+            CodeAttemptWindowMs: limits?.codeAttemptWindowMs ?? 600_000,
+            PerSessionCodeAttempts: limits?.perSessionCodeAttempts ?? 10,
+        },
+    };
+}
+
+/**
+ * The production ports: {@link SessionVerificationPortsBase} plus the server configuration — the settings
+ * read from `realtime.identityVerification`, the configured service principal, and delivery through the
+ * configured communication provider. Exported for tests and for hosts that want to compose their own
+ * workflow around them; application code should use {@link RealtimeSessionVerificationService}.
+ */
+export class RuntimeVerificationPorts extends SessionVerificationPortsBase {
+    public GetSettings(): VerificationSettings {
+        return readSettings();
+    }
+
+    public async SendEmail(email: OutboundEmail): Promise<{ Success: boolean; ErrorMessage?: string }> {
+        const cfg = configInfo.realtime?.identityVerification;
+        const user = this.ResolveServiceUser();
+        if (!cfg?.communicationProvider || !user) {
+            return { Success: false, ErrorMessage: 'No communication provider or service principal is configured.' };
+        }
+        try {
+            const engine = CommunicationEngine.Instance;
+            await engine.Config(false, user);
+            const message = new Message();
+            // Rehearsal mode: the engine builds and LOGS the message but never delivers it (see the config docs).
+            message.DryRun = cfg.deliveryMode === 'dry-run';
+            message.From = cfg.fromAddress ?? '';
+            message.To = email.To;
+            message.Subject = email.Subject;
+            message.Body = email.Text;
+            message.HTMLBody = email.Html;
+            const result = await engine.SendSingleMessage(cfg.communicationProvider, 'Email', message);
+            return result?.Success ? { Success: true } : { Success: false, ErrorMessage: result?.Error ?? 'unknown provider error' };
+        } catch (error) {
+            return { Success: false, ErrorMessage: error instanceof Error ? error.message : String(error) };
+        }
+    }
+
+
+    /** The configured service principal (see {@link SessionVerificationPortsBase}). */
+    protected ResolveServiceUser(): UserInfo | null {
+        const configured = configInfo.realtime?.identityVerification?.contextUserForVerification;
+        return ResolveConfiguredPrincipal(configured, PRINCIPAL_PURPOSE) ?? UserCache.Instance.GetSystemUser() ?? null;
+    }
+}
+
+/**
+ * The process-wide verification service. Call it from the `RealtimeSessionVerificationResolver`
+ * (authenticated principal) and the public `/realtime/verify` router (link capability).
+ */
+export class RealtimeSessionVerificationService extends BaseSingleton<RealtimeSessionVerificationService> {
+    private workflow: RealtimeSessionVerificationWorkflow | undefined;
+
+    protected constructor() {
+        super();
+    }
+
+    /** The process-wide instance. */
+    public static get Instance(): RealtimeSessionVerificationService {
+        return super.getInstance<RealtimeSessionVerificationService>();
+    }
+
+    /** Whether verification is switched on and able to send mail. */
+    public get IsEnabled(): boolean {
+        return readSettings().Enabled;
+    }
+
+    /** See {@link RealtimeSessionVerificationWorkflow.RequestVerification}. */
+    public RequestVerification(
+        input: { AgentSessionID: string; Name: string; Email: string },
+        caller: PrincipalCaller,
+    ): Promise<VerificationOperationResult> {
+        return this.getWorkflow().RequestVerification(input, caller);
+    }
+
+    /** See {@link RealtimeSessionVerificationWorkflow.SubmitCode}. */
+    public SubmitCode(input: { AgentSessionID: string; Code: string }, caller: PrincipalCaller): Promise<VerificationOperationResult> {
+        return this.getWorkflow().SubmitCode(input, caller);
+    }
+
+    /** See {@link RealtimeSessionVerificationWorkflow.RedeemLink}. */
+    public RedeemLink(token: string, clientIp?: string): Promise<VerificationOperationResult> {
+        return this.getWorkflow().RedeemLink(token, { Kind: 'link', ClientIp: clientIp });
+    }
+
+    /** See {@link RealtimeSessionVerificationWorkflow.GetStatus}. */
+    public GetStatus(input: { AgentSessionID: string }, caller: PrincipalCaller): Promise<VerificationOperationResult> {
+        return this.getWorkflow().GetStatus(input, caller);
+    }
+
+    /** The workflow is created on first use so its limiters pick up the loaded config. */
+    private getWorkflow(): RealtimeSessionVerificationWorkflow {
+        if (!this.workflow) {
+            this.workflow = new RealtimeSessionVerificationWorkflow(new RuntimeVerificationPorts());
+        }
+        return this.workflow;
+    }
+}