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

package/dist/realtimeSessions/sessionAccess.js

@@ -0,0 +1,90 @@
+/**
+ * @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 loadConversationExternalID(session, contextUser, provider) };
+}
+/** Reads the session conversation's `ExternalID`; null when there is no conversation or it cannot be read. */
+async function loadConversationExternalID(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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAqB,QAAQ,EAAY,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGjE,oFAAoF;AACpF,MAAM,cAAc,GAAG,uBAAuB,CAAC;AAC/C,MAAM,mBAAmB,GAAG,mBAAmB,CAAC;AA8BhD;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAClC,OAA6B,EAC7B,SAAoD;IAEpD,IAAI,CAAC,SAAS,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,aAAa,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,aAAa,EAAE,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC;QAC/F,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IACnD,CAAC;IACD,MAAM,OAAO,GAAG,SAAS,CAAC,cAAc,EAAE,UAAU,CAAC;IACrD,IAAI,CAAC,OAAO,EAAE,CAAC;QACX,2FAA2F;QAC3F,6EAA6E;QAC7E,OAAO,SAAS,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC5G,CAAC;IACD,kGAAkG;IAClG,OAAO,OAAO,CAAC,sBAAsB,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;AACzH,CAAC;AAUD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACtC,cAAsB,EACtB,WAAqB,EACrB,QAA2B;IAE3B,IAAI,CAAC,WAAW,CAAC,cAAc,CAAC,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,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,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,CAAC;AAC1H,CAAC;AAED,8GAA8G;AAC9G,KAAK,UAAU,0BAA0B,CACrC,OAA+B,EAC/B,WAAqB,EACrB,QAA2B;IAE3B,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,IAAI,CAAC;QACD,MAAM,YAAY,GAAG,MAAM,QAAQ,CAAC,eAAe,CAAuB,mBAAmB,EAAE,WAAW,CAAC,CAAC;QAC5G,IAAI,CAAC,CAAC,MAAM,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC;YACrD,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,OAAO,YAAY,CAAC,UAAU,IAAI,IAAI,CAAC;IAC3C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,QAAQ,CAAC,qDAAqD,OAAO,CAAC,cAAc,eAAe,OAAO,CAAC,EAAE,KAAK,OAAO,EAAE,CAAC,CAAC;QAC7H,OAAO,IAAI,CAAC;IAChB,CAAC;AACL,CAAC"}

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

package/dist/realtimeSessions/sessionConfigStamps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionConfigStamps.js","sourceRoot":"","sources":["../../src/realtimeSessions/sessionConfigStamps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,EACH,mDAAmD,EACnD,mCAAmC,EACnC,sBAAsB,GACzB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACH,iBAAiB,EACjB,6BAA6B,EAC7B,8BAA8B,GAGjC,MAAM,uBAAuB,CAAC;AAO/B;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAKrC;IACG,MAAM,KAAK,GAAG,mDAAmD,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAC1F,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IAChD,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACxC,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,MAAM,aAAa,GAAG,6BAA6B,CAAC,IAAI,CAAC,iBAAiB,EAAE,mCAAmC,CAAC,CAAC;IACjH,MAAM,KAAK,GAA8B;QACrC,GAAG,aAAa;QAChB,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvC,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1E,CAAC;IACF,MAAM,UAAU,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,kBAAkB,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC;IAClI,MAAM,gBAAgB,GAAG,iBAAiB,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,uBAAuB,CAAC,CAAC;IAC5F,MAAM,WAAW,GAAG,UAAU;QAC1B,CAAC,CAAC,sBAAsB,CAAC,OAAO,gBAAgB,KAAK,QAAQ,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS,EAAE,IAAI,CAAC,KAAK,GAAG,UAAU,GAAG,IAAI,CAAC;QAC7H,CAAC,CAAC,SAAS,CAAC;IAChB,OAAO,EAAE,aAAa,EAAE,8BAA8B,CAAC,IAAI,CAAC,iBAAiB,EAAE,KAAK,EAAE,WAAW,CAAC,EAAE,CAAC;AACzG,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,6BAA6B,CAC/C,aAAiC,EACjC,WAAqB,EACrB,QAA2B;IAE3B,IAAI,CAAC,aAAa,EAAE,CAAC;QACjB,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,oBAAoB,CAAC,aAAa,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;IAC/E,IAAI,CAAC,KAAK,EAAE,CAAC;QACT,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,MAAM,QAAQ,GAAG,sBAAsB,CACnC,EAAE,aAAa,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,sBAAsB,EAAE,KAAK,CAAC,sBAAsB,EAAE,EAC7F,WAAW,CACd,CAAC;IACF,IAAI,QAAQ,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;QAC7B,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,OAAO,6BAA6B,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,mCAAmC,CAAC,CAAC,QAAQ,CAAC;AAC9G,CAAC"}

package/dist/realtimeSessions/subscriptionAuthorization.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview The authorization of the `RealtimeSessionEvents` subscription, free of GraphQL schema
+ * decorators and server configuration so it can be exercised — and reused — without loading either.
+ *
+ * It is applied twice on purpose (see `RealtimeSessionEventsResolver`): once when the subscription is
+ * opened ({@link AuthorizeRealtimeSessionSubscription}) and once for every event
+ * ({@link RealtimeSessionEventsFilter}). In neither check does a client-supplied value decide who
+ * receives anything: `agentSessionId` only selects WHICH of the caller's own sessions to listen to; the
+ * identity it is checked against comes from the server-authenticated connection context.
+ *
+ * @module @memberjunction/server/realtimeSessions
+ */
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import type { UserPayload } from '../types.js';
+import { type LoadedSessionForAccess } from './sessionAccess.js';
+import type { RealtimeSessionEventTopicPayload } from './RealtimeSessionEventService.js';
+/**
+ * Arguments of the subscription. `agentSessionId` is camelCase because it is the GraphQL argument name
+ * graphql-js hands to `subscribe` and to the filter — it is the wire contract, not an API of ours.
+ */
+export interface RealtimeSessionEventsArgs {
+    agentSessionId?: string;
+}
+/**
+ * The slice of the WebSocket connection context the authorization reads. `userPayload` is camelCase to
+ * match `AppContext.userPayload`, the member graphql-ws populates and every resolver already destructures.
+ */
+export interface RealtimeSessionEventsContext {
+    userPayload?: UserPayload;
+}
+/**
+ * Per-event filter. Exported because it is the security-critical gate and must be testable in isolation.
+ *
+ * An event reaches a subscriber only when BOTH hold:
+ * 1. it is addressed to the session the subscriber asked for, and
+ * 2. the event's owner/scope snapshot passes {@link AuthorizeSessionAccess} for the connection's
+ *    authenticated principal.
+ *
+ * Fails closed: a missing connection identity, a missing owner on the event, or a missing argument never matches.
+ */
+export declare function RealtimeSessionEventsFilter(data: {
+    payload: RealtimeSessionEventTopicPayload;
+    args: RealtimeSessionEventsArgs;
+    context: RealtimeSessionEventsContext | undefined;
+}): boolean;
+/** Dependencies of {@link AuthorizeRealtimeSessionSubscription}, injectable for tests. */
+export interface SubscriptionAuthorizationDeps {
+    /** Loads a session under the caller's identity. */
+    LoadSession: (agentSessionId: string, user: UserInfo, provider: IMetadataProvider) => Promise<LoadedSessionForAccess | null>;
+    /** The provider to read with (a WebSocket context carries no request-scoped providers). */
+    GetProvider: () => IMetadataProvider;
+}
+/** Production dependencies. */
+export declare const DEFAULT_SUBSCRIPTION_AUTHORIZATION_DEPS: SubscriptionAuthorizationDeps;
+/**
+ * Subscribe-time authorization: loads the session as the connection's principal and requires
+ * {@link AuthorizeSessionAccess} to allow it. Throws {@link REFUSAL_MESSAGE} (uniformly) otherwise.
+ *
+ * @param args - the subscription arguments
+ * @param context - the connection context (server-authenticated)
+ * @param deps - injectable dependencies (tests)
+ * @returns the validated session id
+ */
+export declare function AuthorizeRealtimeSessionSubscription(args: RealtimeSessionEventsArgs, context: RealtimeSessionEventsContext | undefined, deps?: SubscriptionAuthorizationDeps): Promise<string>;
+//# sourceMappingURL=subscriptionAuthorization.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptionAuthorization.d.ts","sourceRoot":"","sources":["../../src/realtimeSessions/subscriptionAuthorization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,iBAAiB,EAAsB,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEvF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAgD,KAAK,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC/G,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,kCAAkC,CAAC;AAEzF;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACtC,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,4BAA4B;IACzC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC7B;AAUD;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IAC9C,OAAO,EAAE,gCAAgC,CAAC;IAC1C,IAAI,EAAE,yBAAyB,CAAC;IAChC,OAAO,EAAE,4BAA4B,GAAG,SAAS,CAAC;CACrD,GAAG,OAAO,CAUV;AAED,0FAA0F;AAC1F,MAAM,WAAW,6BAA6B;IAC1C,mDAAmD;IACnD,WAAW,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,iBAAiB,KAAK,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAC;IAC7H,2FAA2F;IAC3F,WAAW,EAAE,MAAM,iBAAiB,CAAC;CACxC;AAED,+BAA+B;AAC/B,eAAO,MAAM,uCAAuC,EAAE,6BAGrD,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAsB,oCAAoC,CACtD,IAAI,EAAE,yBAAyB,EAC/B,OAAO,EAAE,4BAA4B,GAAG,SAAS,EACjD,IAAI,GAAE,6BAAuE,GAC9E,OAAO,CAAC,MAAM,CAAC,CAmBjB"}

package/dist/realtimeSessions/subscriptionAuthorization.js

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview The authorization of the `RealtimeSessionEvents` subscription, free of GraphQL schema
+ * decorators and server configuration so it can be exercised — and reused — without loading either.
+ *
+ * It is applied twice on purpose (see `RealtimeSessionEventsResolver`): once when the subscription is
+ * opened ({@link AuthorizeRealtimeSessionSubscription}) and once for every event
+ * ({@link RealtimeSessionEventsFilter}). In neither check does a client-supplied value decide who
+ * receives anything: `agentSessionId` only selects WHICH of the caller's own sessions to listen to; the
+ * identity it is checked against comes from the server-authenticated connection context.
+ *
+ * @module @memberjunction/server/realtimeSessions
+ */
+import { LogError, Metadata } from '@memberjunction/core';
+import { IsValidUUID, UUIDsEqual } from '@memberjunction/global';
+import { AuthorizeSessionAccess, LoadSessionForAccess } from './sessionAccess.js';
+/** Why a subscription request was refused (logged; the client always gets the same message). */
+const REFUSAL_MESSAGE = 'Realtime session not found.';
+/** The principal the connection authenticated as, or undefined. */
+function connectionPrincipal(context) {
+    return context?.userPayload?.userRecord;
+}
+/**
+ * Per-event filter. Exported because it is the security-critical gate and must be testable in isolation.
+ *
+ * An event reaches a subscriber only when BOTH hold:
+ * 1. it is addressed to the session the subscriber asked for, and
+ * 2. the event's owner/scope snapshot passes {@link AuthorizeSessionAccess} for the connection's
+ *    authenticated principal.
+ *
+ * Fails closed: a missing connection identity, a missing owner on the event, or a missing argument never matches.
+ */
+export function RealtimeSessionEventsFilter(data) {
+    const { payload, args, context } = data;
+    if (typeof args?.agentSessionId !== 'string' || !payload?.AgentSessionID || !UUIDsEqual(payload.AgentSessionID, args.agentSessionId)) {
+        return false;
+    }
+    const decision = AuthorizeSessionAccess({ SessionUserID: payload.OwnerUserID, ConversationExternalID: payload.ScopeKey }, connectionPrincipal(context));
+    return decision.Allowed;
+}
+/** Production dependencies. */
+export const DEFAULT_SUBSCRIPTION_AUTHORIZATION_DEPS = {
+    LoadSession: LoadSessionForAccess,
+    GetProvider: () => Metadata.Provider, // global-provider-ok: a WebSocket subscription context has no per-request providers
+};
+/**
+ * Subscribe-time authorization: loads the session as the connection's principal and requires
+ * {@link AuthorizeSessionAccess} to allow it. Throws {@link REFUSAL_MESSAGE} (uniformly) otherwise.
+ *
+ * @param args - the subscription arguments
+ * @param context - the connection context (server-authenticated)
+ * @param deps - injectable dependencies (tests)
+ * @returns the validated session id
+ */
+export async function AuthorizeRealtimeSessionSubscription(args, context, deps = DEFAULT_SUBSCRIPTION_AUTHORIZATION_DEPS) {
+    const principal = connectionPrincipal(context);
+    const agentSessionId = args?.agentSessionId;
+    if (!principal || typeof agentSessionId !== 'string' || !IsValidUUID(agentSessionId)) {
+        throw new Error(REFUSAL_MESSAGE);
+    }
+    const loaded = await deps.LoadSession(agentSessionId, principal, deps.GetProvider());
+    if (!loaded) {
+        throw new Error(REFUSAL_MESSAGE);
+    }
+    const decision = AuthorizeSessionAccess({ SessionUserID: loaded.Session.UserID, ConversationExternalID: loaded.ConversationExternalID }, principal);
+    if (decision.Allowed === false) {
+        LogError(`RealtimeSessionEvents: refused subscription by user ${principal.ID} to session ${agentSessionId} (${decision.Reason}).`);
+        throw new Error(REFUSAL_MESSAGE);
+    }
+    return agentSessionId;
+}
+//# sourceMappingURL=subscriptionAuthorization.js.map

package/dist/realtimeSessions/subscriptionAuthorization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptionAuthorization.js","sourceRoot":"","sources":["../../src/realtimeSessions/subscriptionAuthorization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAqB,QAAQ,EAAE,QAAQ,EAAY,MAAM,sBAAsB,CAAC;AACvF,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEjE,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAA+B,MAAM,oBAAoB,CAAC;AAmB/G,gGAAgG;AAChG,MAAM,eAAe,GAAG,6BAA6B,CAAC;AAEtD,mEAAmE;AACnE,SAAS,mBAAmB,CAAC,OAAiD;IAC1E,OAAO,OAAO,EAAE,WAAW,EAAE,UAAkC,CAAC;AACpE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,2BAA2B,CAAC,IAI3C;IACG,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACxC,IAAI,OAAO,IAAI,EAAE,cAAc,KAAK,QAAQ,IAAI,CAAC,OAAO,EAAE,cAAc,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,cAAc,EAAE,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC;QACnI,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,MAAM,QAAQ,GAAG,sBAAsB,CACnC,EAAE,aAAa,EAAE,OAAO,CAAC,WAAW,EAAE,sBAAsB,EAAE,OAAO,CAAC,QAAQ,EAAE,EAChF,mBAAmB,CAAC,OAAO,CAAC,CAC/B,CAAC;IACF,OAAO,QAAQ,CAAC,OAAO,CAAC;AAC5B,CAAC;AAUD,+BAA+B;AAC/B,MAAM,CAAC,MAAM,uCAAuC,GAAkC;IAClF,WAAW,EAAE,oBAAoB;IACjC,WAAW,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,oFAAoF;CAC7H,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,oCAAoC,CACtD,IAA+B,EAC/B,OAAiD,EACjD,OAAsC,uCAAuC;IAE7E,MAAM,SAAS,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC/C,MAAM,cAAc,GAAG,IAAI,EAAE,cAAc,CAAC;IAC5C,IAAI,CAAC,SAAS,IAAI,OAAO,cAAc,KAAK,QAAQ,IAAI,CAAC,WAAW,CAAC,cAAc,CAAC,EAAE,CAAC;QACnF,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;IACrC,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,cAAc,EAAE,SAAS,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IACrF,IAAI,CAAC,MAAM,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;IACrC,CAAC;IACD,MAAM,QAAQ,GAAG,sBAAsB,CACnC,EAAE,aAAa,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,sBAAsB,EAAE,MAAM,CAAC,sBAAsB,EAAE,EAC/F,SAAS,CACZ,CAAC;IACF,IAAI,QAAQ,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;QAC7B,QAAQ,CAAC,uDAAuD,SAAS,CAAC,EAAE,eAAe,cAAc,KAAK,QAAQ,CAAC,MAAM,IAAI,CAAC,CAAC;QACnI,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,cAAc,CAAC;AAC1B,CAAC"}