@memberjunction/server 6.2.0-edge.2 → 6.2.0-edge.4

package/dist/realtimeSessions/RealtimeVerifyRouter.js

@@ -0,0 +1,98 @@
+/**
+ * @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';
+/** 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, 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/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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"}

package/dist/realtimeSessions/SlidingWindowRateLimiter.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @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;
+}
+/**
+ * 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 declare class SlidingWindowRateLimiter {
+    private readonly options;
+    private readonly events;
+    private readonly maxKeys;
+    constructor(options: SlidingWindowRateLimiterOptions);
+    /**
+     * 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
+     */
+    TryConsume(key: string, nowMs: number): RateLimitDecision;
+    /** Number of keys currently tracked (exposed for tests and diagnostics). */
+    get TrackedKeyCount(): number;
+    /** Re-inserts `key` (moving it to the newest position) and evicts the oldest keys past the bound. */
+    private store;
+}
+//# sourceMappingURL=SlidingWindowRateLimiter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SlidingWindowRateLimiter.d.ts","sourceRoot":"","sources":["../../src/realtimeSessions/SlidingWindowRateLimiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAC9B,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAC;IACjB,yFAAyF;IACzF,YAAY,EAAE,MAAM,CAAC;CACxB;AAED,4BAA4B;AAC5B,MAAM,WAAW,+BAA+B;IAC5C,yGAAyG;IACzG,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,6GAA6G;IAC7G,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAKD;;;;;;GAMG;AACH,qBAAa,wBAAwB;IAIrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAEJ,OAAO,EAAE,+BAA+B;IAIrE;;;;;OAKG;IACI,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB;IAehE,4EAA4E;IAC5E,IAAW,eAAe,IAAI,MAAM,CAEnC;IAED,qGAAqG;IACrG,OAAO,CAAC,KAAK;CAWhB"}

package/dist/realtimeSessions/SlidingWindowRateLimiter.js

@@ -0,0 +1,69 @@
+/**
+ * @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
+ */
+/** 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 {
+    constructor(options) {
+        this.options = options;
+        this.events = new Map();
+        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
+     */
+    TryConsume(key, nowMs) {
+        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). */
+    get TrackedKeyCount() {
+        return this.events.size;
+    }
+    /** Re-inserts `key` (moving it to the newest position) and evicts the oldest keys past the bound. */
+    store(key, timestamps) {
+        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);
+        }
+    }
+}
+//# sourceMappingURL=SlidingWindowRateLimiter.js.map

package/dist/realtimeSessions/SlidingWindowRateLimiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SlidingWindowRateLimiter.js","sourceRoot":"","sources":["../../src/realtimeSessions/SlidingWindowRateLimiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAoBH,2CAA2C;AAC3C,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEhC;;;;;;GAMG;AACH,MAAM,OAAO,wBAAwB;IAIjC,YAA6B,OAAwC;QAAxC,YAAO,GAAP,OAAO,CAAiC;QAHpD,WAAM,GAAG,IAAI,GAAG,EAAoB,CAAC;QAIlD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAC;IACvD,CAAC;IAED;;;;;OAKG;IACI,UAAU,CAAC,GAAW,EAAE,KAAa;QACxC,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;YAC1B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;QAC9C,CAAC;QACD,MAAM,WAAW,GAAG,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;QAClD,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC;QACzE,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACpC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YACtB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,GAAG,KAAK,CAAC,EAAE,CAAC;QAClG,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACjB,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACtB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;IAC9C,CAAC;IAED,4EAA4E;IAC5E,IAAW,eAAe;QACtB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC5B,CAAC;IAED,qGAAqG;IAC7F,KAAK,CAAC,GAAW,EAAE,UAAoB;QAC3C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;YACrC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;YACzC,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;gBACd,MAAM;YACV,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC;IACL,CAAC;CACJ"}

package/dist/realtimeSessions/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @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';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/realtimeSessions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,oBAAoB,CAAC;AACnC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kCAAkC,CAAC;AACjD,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,mCAAmC,CAAC;AAClD,cAAc,yCAAyC,CAAC;AACxD,cAAc,2BAA2B,CAAC"}

package/dist/realtimeSessions/index.js

@@ -0,0 +1,17 @@
+/**
+ * @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';
+//# sourceMappingURL=index.js.map

package/dist/realtimeSessions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/realtimeSessions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,oBAAoB,CAAC;AACnC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kCAAkC,CAAC;AACjD,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,mCAAmC,CAAC;AAClD,cAAc,yCAAyC,CAAC;AACxD,cAAc,2BAA2B,CAAC"}

package/dist/realtimeSessions/sessionAccess.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview Who may see and act on ONE realtime session.
+ *
+ * One pure decision ({@link AuthorizeSessionAccess}) shared by everything that addresses a live
+ * session on behalf of a caller: the `RealtimeSessionEvents` subscription (at subscribe time AND for
+ * every delivered event), the verification mutations, and the status query. Keeping it in one place
+ * is what stops "who owns this session?" from being re-derived — slightly differently — in each.
+ *
+ * ## The two ownership rules
+ *
+ * 1. **Owner.** The session's `UserID` must be the caller's user.
+ * 2. **Scope.** A *named* user is fully identified by (1). An **anonymous widget guest** is not:
+ *    every guest authenticates as the one shared Anonymous user, so (1) alone would let any guest
+ *    address any other guest's session. What separates guests is the signed per-session scope in
+ *    their token (`MagicLinkScope.ResourceID`), which `SessionManager` stamps onto the session's
+ *    Conversation as `ExternalID`. So a principal that carries a scope must match it, and an
+ *    anonymous principal that carries NO scope is refused outright — it cannot be told apart from
+ *    every other anonymous principal.
+ *
+ * The decision is deliberately pure (no I/O) so it can be applied identically to a freshly loaded
+ * row at subscribe time and to the owner/scope snapshot carried inside each published event.
+ *
+ * @module @memberjunction/server/realtimeSessions
+ */
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import type { MJAIAgentSessionEntity } from '@memberjunction/core-entities';
+/** What the decision needs to know about the session. */
+export interface SessionAccessSubject {
+    /** `AIAgentSession.UserID`. */
+    SessionUserID: string;
+    /**
+     * `Conversation.ExternalID` of the session's conversation — the signed per-session scope id for an
+     * anonymous guest. `null`/`undefined` when the conversation has none (a named user's session) or
+     * could not be loaded.
+     */
+    ConversationExternalID: string | null | undefined;
+}
+/** What the decision needs to know about the caller (a subset of `UserInfo`). */
+export interface SessionAccessPrincipal {
+    /** The caller's user id. */
+    ID: string;
+    /** True for the shared-Anonymous-user principal of a public-widget guest. */
+    IsMagicLinkAnonymous?: boolean;
+    /** The signed per-session scope carried by the caller's token, when any. */
+    MagicLinkScope?: {
+        ResourceID?: string;
+    } | undefined;
+}
+/** Why access was refused. Callers log the reason; clients get a uniform refusal. */
+export type SessionAccessRefusal = 'not_owner' | 'scope_missing' | 'scope_mismatch';
+/** Outcome of {@link AuthorizeSessionAccess}. */
+export type SessionAccessDecision = {
+    Allowed: true;
+} | {
+    Allowed: false;
+    Reason: SessionAccessRefusal;
+};
+/**
+ * Decides whether `principal` may address the session described by `subject`.
+ *
+ * Fails closed: anything that cannot be positively matched is refused.
+ *
+ * @param subject - owner + scope of the session
+ * @param principal - the authenticated caller (from the server-built `UserInfo`, never from client args)
+ */
+export declare function AuthorizeSessionAccess(subject: SessionAccessSubject, principal: SessionAccessPrincipal | null | undefined): SessionAccessDecision;
+/** A session row together with the one fact about its conversation the decision needs. */
+export interface LoadedSessionForAccess {
+    /** The session entity, loaded under the caller's own identity (so RLS applied to the read). */
+    Session: MJAIAgentSessionEntity;
+    /** The session's conversation `ExternalID` (anonymous scope id), or null. */
+    ConversationExternalID: string | null;
+}
+/**
+ * Loads a session (and its conversation's scope id) under `contextUser`'s identity.
+ *
+ * Loading as the caller — rather than as a privileged user — means the entity layer's row-level
+ * security (`Widget Guest: Own Agent Sessions`, `UI: Own Agent Sessions`) is the FIRST gate; the
+ * explicit {@link AuthorizeSessionAccess} check that follows is defence in depth.
+ *
+ * @returns the loaded session, or `null` when the id is malformed, the row does not exist, or the
+ *   caller cannot read it. Failure to read the conversation yields `ConversationExternalID: null`,
+ *   which {@link AuthorizeSessionAccess} then treats as "no scope to match" (refused for a scoped caller).
+ */
+export declare function LoadSessionForAccess(agentSessionId: string, contextUser: UserInfo, provider: IMetadataProvider): Promise<LoadedSessionForAccess | null>;
+//# sourceMappingURL=sessionAccess.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sessionAccess.d.ts","sourceRoot":"","sources":["../../src/realtimeSessions/sessionAccess.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,iBAAiB,EAAY,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAE7E,OAAO,KAAK,EAAE,sBAAsB,EAAwB,MAAM,+BAA+B,CAAC;AAMlG,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACjC,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,sBAAsB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACrD;AAED,iFAAiF;AACjF,MAAM,WAAW,sBAAsB;IACnC,4BAA4B;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,6EAA6E;IAC7E,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,4EAA4E;IAC5E,cAAc,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;CACxD;AAED,qFAAqF;AACrF,MAAM,MAAM,oBAAoB,GAAG,WAAW,GAAG,eAAe,GAAG,gBAAgB,CAAC;AAEpF,iDAAiD;AACjD,MAAM,MAAM,qBAAqB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAEzG;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAClC,OAAO,EAAE,oBAAoB,EAC7B,SAAS,EAAE,sBAAsB,GAAG,IAAI,GAAG,SAAS,GACrD,qBAAqB,CAYvB;AAED,0FAA0F;AAC1F,MAAM,WAAW,sBAAsB;IACnC,+FAA+F;IAC/F,OAAO,EAAE,sBAAsB,CAAC;IAChC,6EAA6E;IAC7E,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACtC,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,QAAQ,EACrB,QAAQ,EAAE,iBAAiB,GAC5B,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CASxC"}