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

package/dist/realtimeSessions/RealtimeVerifyRouter.js

@@ -0,0 +1,99 @@
+/**
+ * @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 } 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) {
+    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, status, html) {
+    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 = RealtimeSessionVerificationService.Instance) {
+    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, res) => 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, res) => {
+        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, res) => {
+        const body = (req.body ?? {});
+        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;
+}
+//# sourceMappingURL=RealtimeVerifyRouter.js.map

package/dist/realtimeSessions/RealtimeVerifyRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RealtimeVerifyRouter.js","sourceRoot":"","sources":["../../src/realtimeSessions/RealtimeVerifyRouter.ts"],"names":[],"mappings":"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"}

package/dist/realtimeSessions/RecordingAssemblyScheduler.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @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, UserInfo } from '@memberjunction/core';
+import { BaseSingleton, IShutdownable } from '@memberjunction/global';
+import { AssembleRealtimeRecordingInput, AssembleRealtimeRecordingOutcome, IRealtimeRecordingLedger } 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;
+}
+/**
+ * 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 declare class RecordingAssemblyScheduler extends BaseSingleton<RecordingAssemblyScheduler> implements IShutdownable, IRecordingAssemblyScheduler {
+    private _options;
+    private _registered;
+    /** Pending timers keyed by lowercase session id. */
+    private readonly pending;
+    /** Lowercase ids of sessions with an assembly running in this process. */
+    private readonly running;
+    /** Sessions asked for again while running, with the ForcePartial to re-run with. */
+    private readonly rerun;
+    protected constructor();
+    /** Process-wide singleton accessor. */
+    static get Instance(): RecordingAssemblyScheduler;
+    /** Identifier surfaced in graceful-shutdown logs. */
+    readonly ShutdownName = "RecordingAssemblyScheduler";
+    /** Configures the scheduler and enables it; calling again replaces the configuration. */
+    Start(options: RecordingAssemblySchedulerOptions): void;
+    /**
+     * 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.
+     */
+    ScheduleAssembly(sessionID: string, delayMs: number, forcePartial: boolean): void;
+    /**
+     * 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.
+     */
+    Shutdown(): void;
+    private onTimer;
+    /** Runs the session's assembly, then any re-run requested meanwhile. Never rejects. */
+    private runUntilSettled;
+    /** One claim + assembly. Logs every failure with the session id; never throws. */
+    private runOnce;
+    private handleOutcome;
+}
+//# sourceMappingURL=RecordingAssemblyScheduler.d.ts.map

package/dist/realtimeSessions/RecordingAssemblyScheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordingAssemblyScheduler.d.ts","sourceRoot":"","sources":["../../src/realtimeSessions/RecordingAssemblyScheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,oBAAoB,EAAuB,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EAAE,aAAa,EAAE,aAAa,EAAoB,MAAM,wBAAwB,CAAC;AACxF,OAAO,EACkC,8BAA8B,EAAE,gCAAgC,EACrG,wBAAwB,EAC3B,MAAM,2BAA2B,CAAC;AAEnC,oCAAoC;AACpC,MAAM,WAAW,sBAAsB;IACnC,MAAM,IAAI,IAAI,CAAC;CAClB;AAED,sEAAsE;AACtE,MAAM,WAAW,sBAAsB;IACnC,oCAAoC;IACpC,GAAG,IAAI,MAAM,CAAC;IACd,uFAAuF;IACvF,UAAU,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,sBAAsB,CAAC;CAC7E;AAED,qEAAqE;AACrE,MAAM,WAAW,2BAA2B;IACxC;;;OAGG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,IAAI,CAAC;CACrF;AAED,2DAA2D;AAC3D,MAAM,WAAW,iCAAiC;IAC9C,0FAA0F;IAC1F,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,mDAAmD;IACnD,UAAU,EAAE,QAAQ,CAAC;IACrB,sFAAsF;IACtF,OAAO,EAAE,MAAM,MAAM,CAAC;IACtB,sDAAsD;IACtD,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,oBAAoB,EAAE,WAAW,EAAE,QAAQ,KAAK,wBAAwB,CAAC;IACnG,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,8BAA8B,KAAK,OAAO,CAAC,gCAAgC,CAAC,CAAC;IAChG,uDAAuD;IACvD,KAAK,CAAC,EAAE,sBAAsB,CAAC;CAClC;AAiBD;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,aAAa,CAAC,0BAA0B,CAAE,YAAW,aAAa,EAAE,2BAA2B;IAC3I,OAAO,CAAC,QAAQ,CAA4D;IAC5E,OAAO,CAAC,WAAW,CAAS;IAC5B,oDAAoD;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAC9D,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,oFAAoF;IACpF,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8B;IAEpD,SAAS;IAIT,uCAAuC;IACvC,WAAkB,QAAQ,IAAI,0BAA0B,CAEvD;IAED,qDAAqD;IACrD,SAAgB,YAAY,gCAAgC;IAE5D,yFAAyF;IAClF,KAAK,CAAC,OAAO,EAAE,iCAAiC,GAAG,IAAI;IAa9D;;;;;;;;;;OAUG;IACI,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,IAAI;IAqBxF;;;;OAIG;IACI,QAAQ,IAAI,IAAI;IASvB,OAAO,CAAC,OAAO;IAaf,uFAAuF;YACzE,eAAe;IAc7B,kFAAkF;YACpE,OAAO;IAuBrB,OAAO,CAAC,aAAa;CAkBxB"}

package/dist/realtimeSessions/RecordingAssemblyScheduler.js

@@ -0,0 +1,173 @@
+/**
+ * @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 { LogError, LogStatus } from '@memberjunction/core';
+import { BaseSingleton, ShutdownRegistry } from '@memberjunction/global';
+import { AssembleRealtimeRecordingFromLedger, SqlRealtimeRecordingLedger, } from '@memberjunction/ai-agents';
+const NODE_CLOCK = {
+    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 {
+    constructor() {
+        super();
+        this._options = null;
+        this._registered = false;
+        /** Pending timers keyed by lowercase session id. */
+        this.pending = new Map();
+        /** Lowercase ids of sessions with an assembly running in this process. */
+        this.running = new Set();
+        /** Sessions asked for again while running, with the ForcePartial to re-run with. */
+        this.rerun = new Map();
+        /** Identifier surfaced in graceful-shutdown logs. */
+        this.ShutdownName = 'RecordingAssemblyScheduler';
+    }
+    /** Process-wide singleton accessor. */
+    static get Instance() {
+        return super.getInstance();
+    }
+    /** Configures the scheduler and enables it; calling again replaces the configuration. */
+    Start(options) {
+        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.
+     */
+    ScheduleAssembly(sessionID, delayMs, forcePartial) {
+        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.
+     */
+    Shutdown() {
+        for (const entry of this.pending.values()) {
+            entry.Timer.Cancel();
+        }
+        this.pending.clear();
+        this.rerun.clear();
+        this._options = null;
+    }
+    onTimer(key, sessionID) {
+        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. */
+    async runUntilSettled(key, sessionID, forcePartial) {
+        this.running.add(key);
+        try {
+            let next = 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. */
+    async runOnce(sessionID, forcePartial) {
+        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)}`);
+        }
+    }
+    handleOutcome(sessionID, version, outcome, options) {
+        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}`);
+    }
+}
+//# sourceMappingURL=RecordingAssemblyScheduler.js.map

package/dist/realtimeSessions/RecordingAssemblyScheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordingAssemblyScheduler.js","sourceRoot":"","sources":["../../src/realtimeSessions/RecordingAssemblyScheduler.ts"],"names":[],"mappings":"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"}

package/dist/realtimeSessions/SessionVerificationPortsBase.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @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 { type UserInfo } from '@memberjunction/core';
+import type { IdentityVerifiedEventPayload } from '@memberjunction/ai-core-plus';
+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 declare const REALTIME_IDENTITY_VERIFIED_AUDIT_TYPE = "Realtime Identity Verified";
+/**
+ * The session-facing {@link VerificationPorts}, minus configuration. Subclasses supply the settings, the
+ * service principal and the mail delivery.
+ */
+export declare abstract class SessionVerificationPortsBase implements VerificationPorts {
+    /** The live settings. */
+    abstract GetSettings(): VerificationSettings;
+    /** Delivers an email. Must not throw; reports failure in the result. */
+    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;
+    Now(): number;
+    LoadSession(agentSessionId: string, caller: VerificationCaller): Promise<SessionSnapshot | null>;
+    MutateSessionConfig<T>(agentSessionId: string, caller: VerificationCaller, mutate: ConfigMutation<T>): Promise<ConfigMutationResult<T>>;
+    PublishVerified(routing: {
+        AgentSessionID: string;
+        OwnerUserID: string;
+        ScopeKey: string | null;
+    }, payload: IdentityVerifiedEventPayload): {
+        Success: boolean;
+        ErrorMessage?: string;
+    };
+    WriteAudit(entry: VerificationAuditEntry): Promise<void>;
+    /** The identity + provider an authorization read runs under. */
+    private readerFor;
+    /** The identity + provider a state write runs under: always the service principal. */
+    private writerFor;
+}
+//# sourceMappingURL=SessionVerificationPortsBase.d.ts.map

package/dist/realtimeSessions/SessionVerificationPortsBase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionVerificationPortsBase.d.ts","sourceRoot":"","sources":["../../src/realtimeSessions/SessionVerificationPortsBase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAA8C,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAGjG,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,8BAA8B,CAAC;AAGjF,OAAO,EACH,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAC5B,MAAM,2BAA2B,CAAC;AAEnC,qGAAqG;AACrG,eAAO,MAAM,qCAAqC,+BAA+B,CAAC;AAsBlF;;;GAGG;AACH,8BAAsB,4BAA6B,YAAW,iBAAiB;IAC3E,yBAAyB;aACT,WAAW,IAAI,oBAAoB;IAEnD,wEAAwE;aACxD,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAErG,oGAAoG;IACpG,SAAS,CAAC,QAAQ,CAAC,kBAAkB,IAAI,QAAQ,GAAG,IAAI;IAEjD,GAAG,IAAI,MAAM;IAIP,WAAW,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAShG,mBAAmB,CAAC,CAAC,EAC9B,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC;IA8B5B,eAAe,CAClB,OAAO,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,EACjF,OAAO,EAAE,4BAA4B,GACtC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE;IAIjC,UAAU,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCrE,gEAAgE;IAChE,OAAO,CAAC,SAAS;IAQjB,sFAAsF;IACtF,OAAO,CAAC,SAAS;CAOpB"}

package/dist/realtimeSessions/SessionVerificationPortsBase.js

@@ -0,0 +1,149 @@
+/**
+ * @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 } from '@memberjunction/core';
+import { RunWithTrustedSessionConfigWrites } from '@memberjunction/core-entities-server';
+import { LoadSessionForAccess } from './sessionAccess.js';
+import { RealtimeSessionEventService } from './RealtimeSessionEventService.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) {
+    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 class SessionVerificationPortsBase {
+    Now() {
+        return Date.now();
+    }
+    async LoadSession(agentSessionId, caller) {
+        const reader = this.readerFor(caller);
+        if (!reader) {
+            return null;
+        }
+        const loaded = await LoadSessionForAccess(agentSessionId, reader.User, reader.Provider);
+        return loaded ? toSnapshot(loaded) : null;
+    }
+    async MutateSessionConfig(agentSessionId, caller, mutate) {
+        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 };
+        }
+    }
+    PublishVerified(routing, payload) {
+        return RealtimeSessionEventService.Instance.PublishRouted(routing, 'identity.verified', payload);
+    }
+    async WriteAudit(entry) {
+        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(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. */
+    readerFor(caller) {
+        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. */
+    writerFor(caller) {
+        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
+    }
+}
+//# sourceMappingURL=SessionVerificationPortsBase.js.map

package/dist/realtimeSessions/SessionVerificationPortsBase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionVerificationPortsBase.js","sourceRoot":"","sources":["../../src/realtimeSessions/SessionVerificationPortsBase.ts"],"names":[],"mappings":"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"}