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

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,19 @@
+/**
+ * @fileoverview Realtime session events + mid-session identity verification — module barrel.
+ * @module @memberjunction/server/realtimeSessions
+ */
+export * from './sessionAccess.js';
+export * from './subscriptionAuthorization.js';
+export * from './RealtimeSessionEventService.js';
+export * from './verificationPolicy.js';
+export * from './verificationCore.js';
+export * from './SlidingWindowRateLimiter.js';
+export * from './verificationPages.js';
+export * from './verificationWorkflow.js';
+export * from './sessionConfigStamps.js';
+export * from './SessionVerificationPortsBase.js';
+export * from './RealtimeSessionVerificationService.js';
+export * from './RealtimeVerifyRouter.js';
+export * from './ownedRealtimeSession.js';
+export * from './RecordingAssemblyScheduler.js';
+//# 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;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iCAAiC,CAAC"}

package/dist/realtimeSessions/index.js

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Realtime session events + mid-session identity verification — module barrel.
+ * @module @memberjunction/server/realtimeSessions
+ */
+export * from './sessionAccess.js';
+export * from './subscriptionAuthorization.js';
+export * from './RealtimeSessionEventService.js';
+export * from './verificationPolicy.js';
+export * from './verificationCore.js';
+export * from './SlidingWindowRateLimiter.js';
+export * from './verificationPages.js';
+export * from './verificationWorkflow.js';
+export * from './sessionConfigStamps.js';
+export * from './SessionVerificationPortsBase.js';
+export * from './RealtimeSessionVerificationService.js';
+export * from './RealtimeVerifyRouter.js';
+export * from './ownedRealtimeSession.js';
+export * from './RecordingAssemblyScheduler.js';
+//# 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;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iCAAiC,CAAC"}

package/dist/realtimeSessions/ownedRealtimeSession.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview The ownership gate for client-direct realtime session writes: the GraphQL mutations of
+ * `RealtimeClientSessionResolver` and the recording REST routes both load the session through
+ * {@link LoadOwnedRealtimeSession}, so "may this caller write to this session?" is decided in one place.
+ *
+ * @module @memberjunction/server/realtimeSessions
+ */
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import type { MJAIAgentSessionEntity } from '@memberjunction/core-entities';
+/** The session does not exist, or the caller cannot read it. */
+export declare class RealtimeSessionNotFoundError extends Error {
+    readonly AgentSessionID: string;
+    constructor(AgentSessionID: string);
+}
+/** The session exists but belongs to another user. */
+export declare class RealtimeSessionOwnershipError extends Error {
+    readonly AgentSessionID: string;
+    constructor(AgentSessionID: string);
+}
+/**
+ * Loads a session under the caller's identity and enforces ownership (`UserID === contextUser.ID`). It
+ * deliberately does NOT reject `Closed` sessions: the final channel-state flush and the recording terminal
+ * signal legitimately arrive after the session closed. A scoped-anonymous widget guest owns the session it
+ * minted, so the same check covers it; loading as the caller also applies the entity's row-level security.
+ *
+ * @throws RealtimeSessionNotFoundError when the row does not load
+ * @throws RealtimeSessionOwnershipError when the caller is not the owner (logged with both user ids)
+ */
+export declare function LoadOwnedRealtimeSession(agentSessionId: string, contextUser: UserInfo, provider: IMetadataProvider): Promise<MJAIAgentSessionEntity>;
+//# sourceMappingURL=ownedRealtimeSession.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ownedRealtimeSession.d.ts","sourceRoot":"","sources":["../../src/realtimeSessions/ownedRealtimeSession.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,iBAAiB,EAAY,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAE7E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAI5E,gEAAgE;AAChE,qBAAa,4BAA6B,SAAQ,KAAK;aACvB,cAAc,EAAE,MAAM;gBAAtB,cAAc,EAAE,MAAM;CAIrD;AAED,sDAAsD;AACtD,qBAAa,6BAA8B,SAAQ,KAAK;aACxB,cAAc,EAAE,MAAM;gBAAtB,cAAc,EAAE,MAAM;CAIrD;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC1C,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,QAAQ,EACrB,QAAQ,EAAE,iBAAiB,GAC5B,OAAO,CAAC,sBAAsB,CAAC,CAYjC"}

package/dist/realtimeSessions/ownedRealtimeSession.js

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview The ownership gate for client-direct realtime session writes: the GraphQL mutations of
+ * `RealtimeClientSessionResolver` and the recording REST routes both load the session through
+ * {@link LoadOwnedRealtimeSession}, so "may this caller write to this session?" is decided in one place.
+ *
+ * @module @memberjunction/server/realtimeSessions
+ */
+import { LogError } from '@memberjunction/core';
+import { UUIDsEqual } from '@memberjunction/global';
+const SESSION_ENTITY = 'MJ: AI Agent Sessions';
+/** The session does not exist, or the caller cannot read it. */
+export class RealtimeSessionNotFoundError extends Error {
+    constructor(AgentSessionID) {
+        super(`Realtime session ${AgentSessionID} not found`);
+        this.AgentSessionID = AgentSessionID;
+        this.name = 'RealtimeSessionNotFoundError';
+    }
+}
+/** The session exists but belongs to another user. */
+export class RealtimeSessionOwnershipError extends Error {
+    constructor(AgentSessionID) {
+        super('Not authorized: you do not own this realtime session');
+        this.AgentSessionID = AgentSessionID;
+        this.name = 'RealtimeSessionOwnershipError';
+    }
+}
+/**
+ * Loads a session under the caller's identity and enforces ownership (`UserID === contextUser.ID`). It
+ * deliberately does NOT reject `Closed` sessions: the final channel-state flush and the recording terminal
+ * signal legitimately arrive after the session closed. A scoped-anonymous widget guest owns the session it
+ * minted, so the same check covers it; loading as the caller also applies the entity's row-level security.
+ *
+ * @throws RealtimeSessionNotFoundError when the row does not load
+ * @throws RealtimeSessionOwnershipError when the caller is not the owner (logged with both user ids)
+ */
+export async function LoadOwnedRealtimeSession(agentSessionId, contextUser, provider) {
+    const session = await provider.GetEntityObject(SESSION_ENTITY, contextUser);
+    if (!(await session.Load(agentSessionId))) {
+        throw new RealtimeSessionNotFoundError(agentSessionId);
+    }
+    if (!UUIDsEqual(session.UserID, contextUser.ID)) {
+        LogError(`LoadOwnedRealtimeSession: ownership check failed — user ${contextUser.ID} attempted to operate on session ${agentSessionId} owned by ${session.UserID}`);
+        throw new RealtimeSessionOwnershipError(agentSessionId);
+    }
+    return session;
+}
+//# sourceMappingURL=ownedRealtimeSession.js.map

package/dist/realtimeSessions/ownedRealtimeSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ownedRealtimeSession.js","sourceRoot":"","sources":["../../src/realtimeSessions/ownedRealtimeSession.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAqB,QAAQ,EAAY,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGpD,MAAM,cAAc,GAAG,uBAAuB,CAAC;AAE/C,gEAAgE;AAChE,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IACnD,YAA4B,cAAsB;QAC9C,KAAK,CAAC,oBAAoB,cAAc,YAAY,CAAC,CAAC;QAD9B,mBAAc,GAAd,cAAc,CAAQ;QAE9C,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC/C,CAAC;CACJ;AAED,sDAAsD;AACtD,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IACpD,YAA4B,cAAsB;QAC9C,KAAK,CAAC,sDAAsD,CAAC,CAAC;QADtC,mBAAc,GAAd,cAAc,CAAQ;QAE9C,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAChD,CAAC;CACJ;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC1C,cAAsB,EACtB,WAAqB,EACrB,QAA2B;IAE3B,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,eAAe,CAAyB,cAAc,EAAE,WAAW,CAAC,CAAC;IACpG,IAAI,CAAC,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,4BAA4B,CAAC,cAAc,CAAC,CAAC;IAC3D,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,CAAC,EAAE,CAAC;QAC9C,QAAQ,CACJ,2DAA2D,WAAW,CAAC,EAAE,oCAAoC,cAAc,aAAa,OAAO,CAAC,MAAM,EAAE,CAC3J,CAAC;QACF,MAAM,IAAI,6BAA6B,CAAC,cAAc,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,OAAO,CAAC;AACnB,CAAC"}

package/dist/realtimeSessions/sessionAccess.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @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>;
+/**
+ * Reads an already-loaded session's conversation `ExternalID` (the anonymous scope id) under `contextUser`;
+ * null when there is no conversation or it cannot be read (logged). For callers that loaded the session
+ * through another gate and only need the scope half of {@link AuthorizeSessionAccess}'s subject.
+ */
+export declare function LoadSessionConversationExternalID(session: MJAIAgentSessionEntity, contextUser: UserInfo, provider: IMetadataProvider): Promise<string | 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;AAED;;;;GAIG;AACH,wBAAsB,iCAAiC,CACnD,OAAO,EAAE,sBAAsB,EAC/B,WAAW,EAAE,QAAQ,EACrB,QAAQ,EAAE,iBAAiB,GAC5B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAexB"}

package/dist/realtimeSessions/sessionAccess.js

@@ -0,0 +1,94 @@
+/**
+ * @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 { LogError } from '@memberjunction/core';
+import { IsValidUUID, UUIDsEqual } from '@memberjunction/global';
+/** Entity names, centralised so the `MJ: ` prefix convention lives in one place. */
+const SESSION_ENTITY = 'MJ: AI Agent Sessions';
+const CONVERSATION_ENTITY = 'MJ: Conversations';
+/**
+ * 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 function AuthorizeSessionAccess(subject, principal) {
+    if (!principal?.ID || !subject.SessionUserID || !UUIDsEqual(subject.SessionUserID, principal.ID)) {
+        return { Allowed: false, Reason: 'not_owner' };
+    }
+    const scopeId = principal.MagicLinkScope?.ResourceID;
+    if (!scopeId) {
+        // An anonymous principal without a per-session scope is indistinguishable from every other
+        // anonymous principal: owning "the Anonymous user's" session proves nothing.
+        return principal.IsMagicLinkAnonymous ? { Allowed: false, Reason: 'scope_missing' } : { Allowed: true };
+    }
+    // Scope ids are opaque base64url strings (case-significant), so compare exactly — not UUIDsEqual.
+    return subject.ConversationExternalID === scopeId ? { Allowed: true } : { Allowed: false, Reason: 'scope_mismatch' };
+}
+/**
+ * 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 async function LoadSessionForAccess(agentSessionId, contextUser, provider) {
+    if (!IsValidUUID(agentSessionId)) {
+        return null;
+    }
+    const session = await provider.GetEntityObject(SESSION_ENTITY, contextUser);
+    if (!(await session.Load(agentSessionId))) {
+        return null;
+    }
+    return { Session: session, ConversationExternalID: await LoadSessionConversationExternalID(session, contextUser, provider) };
+}
+/**
+ * Reads an already-loaded session's conversation `ExternalID` (the anonymous scope id) under `contextUser`;
+ * null when there is no conversation or it cannot be read (logged). For callers that loaded the session
+ * through another gate and only need the scope half of {@link AuthorizeSessionAccess}'s subject.
+ */
+export async function LoadSessionConversationExternalID(session, contextUser, provider) {
+    if (!session.ConversationID) {
+        return null;
+    }
+    try {
+        const conversation = await provider.GetEntityObject(CONVERSATION_ENTITY, contextUser);
+        if (!(await conversation.Load(session.ConversationID))) {
+            return null;
+        }
+        return conversation.ExternalID ?? null;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        LogError(`LoadSessionForAccess: could not read conversation ${session.ConversationID} of session ${session.ID}: ${message}`);
+        return null;
+    }
+}
+//# sourceMappingURL=sessionAccess.js.map

package/dist/realtimeSessions/sessionAccess.js.map

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

package/dist/realtimeSessions/sessionConfigStamps.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview What the session-start path stamps into a new realtime session's `Config` for identity
+ * verification: the policy snapshot, the unverified duration cap, and any verified identity carried
+ * forward from the session being resumed.
+ *
+ * Split in two so the decision is testable without a database:
+ *
+ * - {@link BuildMintConfigStamps} — **pure**. Given the resolved realtime config, the existing `Config`
+ *   and an optional inherited identity, returns the `Config` to write (or `null` when there is nothing
+ *   to stamp).
+ * - {@link LoadInheritedVerifiedIdentity} — the one read: the prior session's verified identity, only
+ *   when the new caller is authorized on that prior session.
+ *
+ * Everything stamped here lives under server-authoritative keys (`identityVerification`,
+ * `maxSessionDeadlineIso`); the caller writes it inside `RunWithTrustedSessionConfigWrites`.
+ *
+ * ## Resume after the cap
+ *
+ * If an unverified session hits its cap before the person verifies, the janitor closes it. A verify link
+ * redeemed afterwards still records the verification on that (closed) session, and a **new** session
+ * started with `lastSessionId` pointing at it inherits the verified identity (and, with it, the
+ * `verifiedMaxSeconds` cap instead of the unverified one). Inheritance requires the same ownership/scope
+ * authorization as any other access to the prior session, so a stranger cannot adopt someone else's
+ * verification by naming their session id.
+ *
+ * @module @memberjunction/server/realtimeSessions
+ */
+import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { type VerifiedIdentity } from './verificationCore.js';
+/** The `Config` to persist at session start. */
+export interface MintConfigStampPlan {
+    NextConfigRaw: string;
+}
+/**
+ * Decides what to stamp into a freshly created session's `Config`.
+ *
+ * - **Policy snapshot.** The cascade's verification layer (`channels.config.IdentityVerification` plus the
+ *   duration caps) is copied onto the session, so the rules a person is held to are fixed at mint,
+ *   server-side, and cannot be chosen by the caller later.
+ * - **Duration cap.** When the cascade configures `unverifiedMaxSeconds` (or, for a session that inherited
+ *   a verified identity, `verifiedMaxSeconds`), the session's absolute deadline is set to now + cap —
+ *   applied to ANY principal, not only widget guests — and never loosens a tighter deadline already
+ *   stamped (the widget voice cap).
+ * - **Inherited identity.** A verified identity carried forward from the resumed session.
+ *
+ * @param args.EffectiveRealtime - `EffectiveConfig.realtime` of the resolved config (any shape; read defensively)
+ * @param args.ExistingConfigRaw - the session's current `Config`
+ * @param args.InheritedVerified - verified identity from the session being resumed, if any
+ * @param args.NowMs - the current time, epoch ms
+ * @returns the `Config` to write, or `null` when nothing needs stamping
+ */
+export declare function BuildMintConfigStamps(args: {
+    EffectiveRealtime: unknown;
+    ExistingConfigRaw: string | null;
+    InheritedVerified?: VerifiedIdentity;
+    NowMs: number;
+}): MintConfigStampPlan | null;
+/**
+ * The verified identity of the session being resumed, when the caller may inherit it.
+ *
+ * Reads the prior session as the caller and requires {@link AuthorizeSessionAccess} to allow it; any
+ * failure (no such session, not the caller's, unreadable) yields `undefined` — inheritance is a
+ * convenience and must never block a session start.
+ *
+ * @param lastSessionId - the `lastSessionId` the client supplied at start
+ * @param contextUser - the starting caller
+ * @param provider - request-scoped provider
+ */
+export declare function LoadInheritedVerifiedIdentity(lastSessionId: string | undefined, contextUser: UserInfo, provider: IMetadataProvider): Promise<VerifiedIdentity | undefined>;
+//# sourceMappingURL=sessionConfigStamps.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sessionConfigStamps.d.ts","sourceRoot":"","sources":["../../src/realtimeSessions/sessionConfigStamps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAOxE,OAAO,EAKH,KAAK,gBAAgB,EACxB,MAAM,uBAAuB,CAAC;AAE/B,gDAAgD;AAChD,MAAM,WAAW,mBAAmB;IAChC,aAAa,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IACxC,iBAAiB,EAAE,OAAO,CAAC;IAC3B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,iBAAiB,CAAC,EAAE,gBAAgB,CAAC;IACrC,KAAK,EAAE,MAAM,CAAC;CACjB,GAAG,mBAAmB,GAAG,IAAI,CAkB7B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,6BAA6B,CAC/C,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,WAAW,EAAE,QAAQ,EACrB,QAAQ,EAAE,iBAAiB,GAC5B,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAgBvC"}

package/dist/realtimeSessions/sessionConfigStamps.js

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview What the session-start path stamps into a new realtime session's `Config` for identity
+ * verification: the policy snapshot, the unverified duration cap, and any verified identity carried
+ * forward from the session being resumed.
+ *
+ * Split in two so the decision is testable without a database:
+ *
+ * - {@link BuildMintConfigStamps} — **pure**. Given the resolved realtime config, the existing `Config`
+ *   and an optional inherited identity, returns the `Config` to write (or `null` when there is nothing
+ *   to stamp).
+ * - {@link LoadInheritedVerifiedIdentity} — the one read: the prior session's verified identity, only
+ *   when the new caller is authorized on that prior session.
+ *
+ * Everything stamped here lives under server-authoritative keys (`identityVerification`,
+ * `maxSessionDeadlineIso`); the caller writes it inside `RunWithTrustedSessionConfigWrites`.
+ *
+ * ## Resume after the cap
+ *
+ * If an unverified session hits its cap before the person verifies, the janitor closes it. A verify link
+ * redeemed afterwards still records the verification on that (closed) session, and a **new** session
+ * started with `lastSessionId` pointing at it inherits the verified identity (and, with it, the
+ * `verifiedMaxSeconds` cap instead of the unverified one). Inheritance requires the same ownership/scope
+ * authorization as any other access to the prior session, so a stranger cannot adopt someone else's
+ * verification by naming their session id.
+ *
+ * @module @memberjunction/server/realtimeSessions
+ */
+import { AuthorizeSessionAccess, LoadSessionForAccess } from './sessionAccess.js';
+import { ExtractIdentityVerificationPolicyFromRealtimeConfig, ReadIdentityVerificationPolicyLayer, TightenSessionDeadline, } from './verificationPolicy.js';
+import { ParseConfigObject, ReadIdentityVerificationState, WriteIdentityVerificationState, } from './verificationCore.js';
+/**
+ * Decides what to stamp into a freshly created session's `Config`.
+ *
+ * - **Policy snapshot.** The cascade's verification layer (`channels.config.IdentityVerification` plus the
+ *   duration caps) is copied onto the session, so the rules a person is held to are fixed at mint,
+ *   server-side, and cannot be chosen by the caller later.
+ * - **Duration cap.** When the cascade configures `unverifiedMaxSeconds` (or, for a session that inherited
+ *   a verified identity, `verifiedMaxSeconds`), the session's absolute deadline is set to now + cap —
+ *   applied to ANY principal, not only widget guests — and never loosens a tighter deadline already
+ *   stamped (the widget voice cap).
+ * - **Inherited identity.** A verified identity carried forward from the resumed session.
+ *
+ * @param args.EffectiveRealtime - `EffectiveConfig.realtime` of the resolved config (any shape; read defensively)
+ * @param args.ExistingConfigRaw - the session's current `Config`
+ * @param args.InheritedVerified - verified identity from the session being resumed, if any
+ * @param args.NowMs - the current time, epoch ms
+ * @returns the `Config` to write, or `null` when nothing needs stamping
+ */
+export function BuildMintConfigStamps(args) {
+    const layer = ExtractIdentityVerificationPolicyFromRealtimeConfig(args.EffectiveRealtime);
+    const hasPolicy = Object.keys(layer).length > 0;
+    if (!hasPolicy && !args.InheritedVerified) {
+        return null;
+    }
+    const existingState = ReadIdentityVerificationState(args.ExistingConfigRaw, ReadIdentityVerificationPolicyLayer);
+    const state = {
+        ...existingState,
+        ...(hasPolicy ? { Policy: layer } : {}),
+        ...(args.InheritedVerified ? { Verified: args.InheritedVerified } : {}),
+    };
+    const capSeconds = args.InheritedVerified ? (layer.verifiedMaxSeconds ?? layer.unverifiedMaxSeconds) : layer.unverifiedMaxSeconds;
+    const existingDeadline = ParseConfigObject(args.ExistingConfigRaw)['maxSessionDeadlineIso'];
+    const deadlineIso = capSeconds
+        ? TightenSessionDeadline(typeof existingDeadline === 'string' ? existingDeadline : undefined, args.NowMs + capSeconds * 1000)
+        : undefined;
+    return { NextConfigRaw: WriteIdentityVerificationState(args.ExistingConfigRaw, state, deadlineIso) };
+}
+/**
+ * The verified identity of the session being resumed, when the caller may inherit it.
+ *
+ * Reads the prior session as the caller and requires {@link AuthorizeSessionAccess} to allow it; any
+ * failure (no such session, not the caller's, unreadable) yields `undefined` — inheritance is a
+ * convenience and must never block a session start.
+ *
+ * @param lastSessionId - the `lastSessionId` the client supplied at start
+ * @param contextUser - the starting caller
+ * @param provider - request-scoped provider
+ */
+export async function LoadInheritedVerifiedIdentity(lastSessionId, contextUser, provider) {
+    if (!lastSessionId) {
+        return undefined;
+    }
+    const prior = await LoadSessionForAccess(lastSessionId, contextUser, provider);
+    if (!prior) {
+        return undefined;
+    }
+    const decision = AuthorizeSessionAccess({ SessionUserID: prior.Session.UserID, ConversationExternalID: prior.ConversationExternalID }, contextUser);
+    if (decision.Allowed === false) {
+        return undefined;
+    }
+    return ReadIdentityVerificationState(prior.Session.Config_, ReadIdentityVerificationPolicyLayer).Verified;
+}
+//# sourceMappingURL=sessionConfigStamps.js.map