@memberjunction/server 5.51.0 → 6.1.0-edge.0

package/src/__tests__/sessionUserClone.test.ts

@@ -0,0 +1,161 @@
+/**
+ * CloneUserForSessionContext tests.
+ *
+ * FAIL-OPEN GUARD: the clone must carry EVERY restricting per-session context
+ * (TenantContext, MagicLinkScope, APIKeyActingContext, APIKeyRowFilters, ...) —
+ * a lossy clone silently DROPS a restriction, which fails open. These tests also
+ * pin the mechanism note in sessionUserClone.ts: if a refactor converts UserInfo
+ * backing fields to #private fields or flips class-field emit semantics, the
+ * spread-based clone breaks and these tests catch it.
+ *
+ * The other direction matters too: stamping the clone must never write through
+ * to the source, because the source is very often the SHARED process-wide
+ * UserCache instance (same-instant cross-request aliasing).
+ */
+import { describe, it, expect } from 'vitest';
+import { UserInfo } from '@memberjunction/core';
+import type { APIKeyRowFilterBinding } from '@memberjunction/core';
+import { CloneUserForSessionContext } from '../auth/sessionUserClone.js';
+
+const USER_ID = 'U0000000-0000-0000-0000-000000000001';
+
+function buildSourceUser(): UserInfo {
+  const user = new UserInfo(null, {
+    ID: USER_ID,
+    Name: 'Test User',
+    Email: 'test@example.com',
+    IsActive: true,
+    Type: 'User',
+    UserRoles: [
+      { UserID: USER_ID, RoleID: 'R0000000-0000-0000-0000-000000000001', Role: 'Developer' },
+      { UserID: USER_ID, RoleID: 'R0000000-0000-0000-0000-000000000002', Role: 'Integration' },
+    ],
+  });
+  user.TenantContext = { TenantID: 'tenant-1', Source: 'header' };
+  user.MagicLinkScope = { ResourceID: 'res-1', ResourceType: 'Reports' };
+  user.APIKeyActingContext = {
+    ActingOrganizationID: 'ORG00000-0000-0000-0000-000000000001',
+    ActingCompanyIDs: ['c1', 'c2'],
+  };
+  user.APIKeyRowFilters = [
+    { EntityID: 'E0000000-0000-0000-0000-000000000001', PermissionType: 'Read', FilterID: 'F0000000-0000-0000-0000-000000000001' },
+  ];
+  user.ReturningVisitorContext = { VisitorKey: 'vk-1' };
+  user.WidgetGuestContext = { WidgetID: 'W0000000-0000-0000-0000-000000000001' };
+  user.IsMagicLinkAnonymous = true;
+  return user;
+}
+
+describe('CloneUserForSessionContext', () => {
+  it('returns a distinct UserInfo instance preserving identity fields', () => {
+    const source = buildSourceUser();
+    const clone = CloneUserForSessionContext(source);
+
+    expect(clone).not.toBe(source);
+    expect(clone).toBeInstanceOf(UserInfo);
+    expect(clone.ID).toBe(USER_ID);
+    expect(clone.Email).toBe('test@example.com');
+    expect(clone.Name).toBe('Test User');
+    expect(clone.IsActive).toBe(true);
+  });
+
+  it('preserves UserRoles (same length, same role IDs)', () => {
+    const source = buildSourceUser();
+    const clone = CloneUserForSessionContext(source);
+
+    expect(clone.UserRoles).toHaveLength(source.UserRoles.length);
+    expect(clone.UserRoles.map(r => r.RoleID)).toEqual(source.UserRoles.map(r => r.RoleID));
+  });
+
+  it('preserves TenantContext — dropping it would unscope the tenant [fail-open]', () => {
+    const source = buildSourceUser();
+    const clone = CloneUserForSessionContext(source);
+
+    expect(clone.TenantContext).toEqual({ TenantID: 'tenant-1', Source: 'header' });
+  });
+
+  it('preserves MagicLinkScope — dropping it would widen a resource-pinned share [fail-open]', () => {
+    const source = buildSourceUser();
+    const clone = CloneUserForSessionContext(source);
+
+    expect(clone.MagicLinkScope).toEqual({ ResourceID: 'res-1', ResourceType: 'Reports' });
+  });
+
+  it('preserves APIKeyActingContext — dropping it would collapse acting-scoped filters [fail-open]', () => {
+    const source = buildSourceUser();
+    const clone = CloneUserForSessionContext(source);
+
+    expect(clone.APIKeyActingContext).toEqual({
+      ActingOrganizationID: 'ORG00000-0000-0000-0000-000000000001',
+      ActingCompanyIDs: ['c1', 'c2'],
+    });
+  });
+
+  it('preserves APIKeyRowFilters — dropping them would lift the key ceiling entirely [fail-open]', () => {
+    const source = buildSourceUser();
+    const clone = CloneUserForSessionContext(source);
+
+    expect(clone.APIKeyRowFilters).toEqual(source.APIKeyRowFilters);
+    expect(clone.APIKeyRowFilters).toHaveLength(1);
+  });
+
+  it('preserves ReturningVisitorContext, WidgetGuestContext, and IsMagicLinkAnonymous', () => {
+    const source = buildSourceUser();
+    const clone = CloneUserForSessionContext(source);
+
+    expect(clone.ReturningVisitorContext).toEqual({ VisitorKey: 'vk-1' });
+    expect(clone.WidgetGuestContext).toEqual({ WidgetID: 'W0000000-0000-0000-0000-000000000001' });
+    expect(clone.IsMagicLinkAnonymous).toBe(true);
+  });
+
+  it('stamping new contexts on the clone does NOT write through to the source', () => {
+    const source = buildSourceUser();
+    const clone = CloneUserForSessionContext(source);
+
+    const newBindings: APIKeyRowFilterBinding[] = [
+      { EntityID: 'E0000000-0000-0000-0000-000000000099', PermissionType: 'Update', FilterID: 'F0000000-0000-0000-0000-000000000099' },
+    ];
+    clone.TenantContext = { TenantID: 'tenant-OTHER', Source: 'custom' };
+    clone.MagicLinkScope = { ResourceID: 'res-OTHER', ResourceType: 'Dashboards' };
+    clone.APIKeyActingContext = { ActingOrganizationID: 'ORG-OTHER' };
+    clone.APIKeyRowFilters = newBindings;
+    clone.IsMagicLinkAnonymous = false;
+
+    // The source (potentially the shared UserCache instance) must be untouched
+    expect(source.TenantContext).toEqual({ TenantID: 'tenant-1', Source: 'header' });
+    expect(source.MagicLinkScope).toEqual({ ResourceID: 'res-1', ResourceType: 'Reports' });
+    expect(source.APIKeyActingContext?.ActingOrganizationID).toBe('ORG00000-0000-0000-0000-000000000001');
+    expect(source.APIKeyRowFilters).toHaveLength(1);
+    expect(source.APIKeyRowFilters?.[0].FilterID).toBe('F0000000-0000-0000-0000-000000000001');
+    expect(source.IsMagicLinkAnonymous).toBe(true);
+  });
+
+  it('clearing contexts on the clone does NOT clear them on the source', () => {
+    const source = buildSourceUser();
+    const clone = CloneUserForSessionContext(source);
+
+    clone.TenantContext = undefined;
+    clone.APIKeyActingContext = undefined;
+    clone.APIKeyRowFilters = undefined;
+
+    expect(source.TenantContext).toBeDefined();
+    expect(source.APIKeyActingContext).toBeDefined();
+    expect(source.APIKeyRowFilters).toBeDefined();
+  });
+
+  it('does not invent contexts on a clone of a context-free user', () => {
+    const source = new UserInfo(null, {
+      ID: USER_ID,
+      Email: 'plain@example.com',
+      UserRoles: [],
+    });
+    const clone = CloneUserForSessionContext(source);
+
+    expect(clone.TenantContext).toBeUndefined();
+    expect(clone.MagicLinkScope).toBeUndefined();
+    expect(clone.APIKeyActingContext).toBeUndefined();
+    expect(clone.APIKeyRowFilters).toBeUndefined();
+    expect(clone.IsMagicLinkAnonymous).toBe(false);
+    expect(clone.UserRoles).toEqual([]);
+  });
+});

package/src/agentSessions/SessionManager.ts

@@ -79,7 +79,8 @@ const HEARTBEAT_MIN_WRITE_INTERVAL_MS = 3_000;
  * correct identity/provider and never pin the process-global provider.
  *
  * The only in-memory state it holds is a small per-session last-heartbeat-write timestamp map used
- * purely to coalesce {@link Heartbeat} writes; it carries no user or provider state across calls.
+ * purely to coalesce {@link Heartbeat} writes, plus the injected {@link RealtimeClientSessionService}
+ * used by {@link finalizeObservabilityRuns}; it carries no user or provider state across calls.
  *
  * Responsibilities:
  * - **Create** — authorize (`CanRun`), optionally mint a Conversation, persist an `Active` session.
@@ -96,6 +97,29 @@ export class SessionManager {
     /** session ID (lowercased) → epoch ms of its last persisted `LastActiveAt` write. */
     private heartbeatLastWrite = new Map<string, number>();
 
+    /**
+     * The {@link RealtimeClientSessionService} used to finalize a closing session's co-agent
+     * observability runs (see {@link finalizeObservabilityRuns}). Defaults to a fresh instance for
+     * callers that don't own a shared one (e.g. `SessionJanitor`, telephony services) — but a caller
+     * that itself created the co-agent's `AIPromptRun` writes through its OWN `RealtimeClientSessionService`
+     * (currently only `RealtimeClientSessionResolver`) MUST pass that same instance here. Otherwise
+     * finalize's internal per-run write-chain cleanup runs against a different object than the one that
+     * accumulated the chain, silently no-op'ing on the live instance (see the constructor param doc).
+     */
+    private readonly realtimeClientSessionService: RealtimeClientSessionService;
+
+    /**
+     * @param realtimeClientSessionService The shared {@link RealtimeClientSessionService} instance to
+     *   finalize observability runs through. Pass the SAME instance your resolver/service used to create
+     *   and write to the session's co-agent `AIAgentRun`/`AIPromptRun` (e.g.
+     *   `RealtimeClientSessionResolver`'s own field) so `CloseSession` can correctly clean up that
+     *   instance's per-run state. Omit only when this `SessionManager` never closes a client-direct
+     *   voice session it also originated observability writes for.
+     */
+    constructor(realtimeClientSessionService?: RealtimeClientSessionService) {
+        this.realtimeClientSessionService = realtimeClientSessionService ?? new RealtimeClientSessionService();
+    }
+
     /**
      * Authorize and create a new session. Flow:
      * 1. `CanRun` check on the agent — denied → {@link SessionAuthorizationError}, no row written.
@@ -235,7 +259,7 @@ export class SessionManager {
             // for a scoped anonymous session, so an owner-initiated (or error) close must finalize
             // under it too — the caller's role holds no grants on the AI run entities. Janitor and
             // shutdown sweeps already close as the system user and pass through unchanged.
-            await new RealtimeClientSessionService().FinalizeCoAgentRun(
+            await this.realtimeClientSessionService.FinalizeCoAgentRun(
                 config.coAgentRunID ?? null,
                 config.promptRunID ?? null,
                 ResolveScopedAnonymousRunUser(contextUser),

package/src/auth/actingContextResolver.ts

@@ -0,0 +1,56 @@
+/**
+ * Deployment extension point for the API-key acting context (plan §5.8).
+ *
+ * MJ defines the CARRIER and the CONTRACT for `{{Acting*}}` row-filter tokens
+ * (`UserInfo.APIKeyActingContext`); the VALUES are deployment-specific — a
+ * verified session token, a server-side session lookup, a trusted upstream
+ * assertion. A deployment registers a resolver at startup and `context.ts`
+ * invokes it after API-key validation, stamping the result onto the CLONED
+ * per-request UserInfo.
+ *
+ * TRUST BOUNDARY (load-bearing): the resolver runs server-side and its return
+ * value flows straight into row-filter SQL token substitution. Resolver
+ * implementations MUST derive every value server-side — never from a
+ * client-supplied header, argument, or GraphQL variable. A client-settable
+ * acting context is a total bypass of API-key row filtering. Validation of the
+ * value SHAPES (GUID / bounded identifier) happens downstream in
+ * `APIKeyEngine.Authorize()` and fails closed, but shape validation cannot
+ * detect a forged-but-well-formed value — provenance is the resolver's job.
+ */
+import type { IncomingMessage } from 'http';
+import type { APIKeyActingContext, UserInfo } from '@memberjunction/core';
+
+/**
+ * Resolves the acting context for one API-key request. Return `undefined` when
+ * the request carries no acting identity — filters requiring `{{Acting*}}`
+ * tokens then fail closed (match nothing / deny) by design.
+ *
+ * @param req - The incoming HTTP request (undefined on transports without one, e.g. WebSocket connects)
+ * @param user - The per-request session UserInfo (already cloned; safe to read, do not mutate)
+ * @param apiKeyId - The validated API key's ID
+ */
+export type APIKeyActingContextResolver = (
+  req: IncomingMessage | undefined,
+  user: UserInfo,
+  apiKeyId: string
+) => Promise<APIKeyActingContext | undefined> | APIKeyActingContext | undefined;
+
+let registeredResolver: APIKeyActingContextResolver | undefined;
+
+/**
+ * Registers the deployment's acting-context resolver. Call once at server
+ * startup, before requests are served. Registering again replaces the previous
+ * resolver (last write wins); pass `undefined` to clear.
+ */
+export function RegisterAPIKeyActingContextResolver(fn: APIKeyActingContextResolver | undefined): void {
+  registeredResolver = fn;
+}
+
+/**
+ * Returns the registered acting-context resolver, or `undefined` when the
+ * deployment has not registered one (the default — API-key sessions then carry
+ * no acting context, and any filter requiring `{{Acting*}}` tokens fails closed).
+ */
+export function GetAPIKeyActingContextResolver(): APIKeyActingContextResolver | undefined {
+  return registeredResolver;
+}

package/src/auth/index.ts

@@ -10,6 +10,7 @@ import { AuthProviderFactory } from '@memberjunction/auth-providers';
 import { initializeAuthProviders } from './initializeProviders.js';
 
 export * from './APIKeyScopeAuth.js';
+export * from './actingContextResolver.js';
 
 // This is a hard-coded forever constant due to internal migrations
 

package/src/auth/sessionUserClone.ts

@@ -0,0 +1,50 @@
+/**
+ * Clone-before-stamp helper for per-session UserInfo state.
+ *
+ * The resolved userRecord for a request is very often the SHARED, process-wide
+ * UserCache instance. Any per-session context stamped onto it in place —
+ * TenantContext, MagicLinkScope, APIKeyActingContext — leaks to every other
+ * concurrent session of the same user THE INSTANT it is written; this is
+ * same-moment cross-request aliasing, not a cache-staleness problem. The
+ * magic-link path has always cloned for exactly this reason (see
+ * buildMagicLinkSessionUser in context.ts); this helper makes that rule a
+ * single shared primitive so every per-session stamp goes through the same
+ * clone.
+ *
+ * MECHANISM NOTE (load-bearing, tested): the spread `{ ...user }` captures the
+ * `_`-prefixed backing fields (enumerable own properties under
+ * useDefineForClassFields:false) but NOT the public getters; UserInfo's
+ * constructor then copies via BaseInfo.copyInitData, which assigns only keys
+ * that already exist on the fresh instance (hasOwnProperty guard). Roles need
+ * the explicit UserRoles hand-off because the constructor reads
+ * `initData.UserRoles || initData._UserRoles`. If a refactor converts backing
+ * fields to #private fields or a tsconfig change flips class-field semantics,
+ * this clone silently drops context — the sessionUserClone unit tests exist to
+ * catch precisely that, because dropping a RESTRICTING context fails open.
+ */
+import { Metadata, UserInfo } from '@memberjunction/core';
+
+/**
+ * Returns a fresh UserInfo carrying the same identity, fields, roles, and all
+ * per-session contexts as the input. Safe to stamp additional per-session
+ * state on the clone; never stamp the input itself.
+ */
+export function CloneUserForSessionContext(user: UserInfo): UserInfo {
+  const md = Metadata.Provider; // global-provider-ok: server-side session construction under the server's single default provider, same as buildMagicLinkSessionUser
+  const clone = new UserInfo(md, {
+    ...user,
+    _UserRoles: undefined,
+    UserRoles: user.UserRoles,
+  });
+  // Object-valued per-session contexts ride through the spread as backing
+  // fields; re-stamp them explicitly anyway so the clone's correctness does
+  // not depend on field-emit semantics staying frozen forever.
+  clone.TenantContext = user.TenantContext;
+  clone.MagicLinkScope = user.MagicLinkScope;
+  clone.ReturningVisitorContext = user.ReturningVisitorContext;
+  clone.WidgetGuestContext = user.WidgetGuestContext;
+  clone.IsMagicLinkAnonymous = user.IsMagicLinkAnonymous;
+  clone.APIKeyActingContext = user.APIKeyActingContext;
+  clone.APIKeyRowFilters = user.APIKeyRowFilters;
+  return clone;
+}

package/src/context.ts

@@ -1,10 +1,13 @@
 import { IncomingMessage } from 'http';
+import { createHash, timingSafeEqual } from 'crypto';
 import { default as jwt } from 'jsonwebtoken';
 import 'reflect-metadata';
 import { Subject, firstValueFrom } from 'rxjs';
 import { AuthenticationError, AuthorizationError } from 'type-graphql';
 import sql from 'mssql';
 import { getSigningKeys, getSystemUser, getValidationOptions, verifyUserRecord, extractUserInfoFromPayload } from './auth/index.js';
+import { CloneUserForSessionContext } from './auth/sessionUserClone.js';
+import { GetAPIKeyActingContextResolver } from './auth/actingContextResolver.js';
 import { TokenExpiredError, AuthProviderFactory } from '@memberjunction/auth-providers';
 import { authCache } from './cache.js';
 import { userEmailMap, apiKey, mj_core_schema } from './config.js';
@@ -319,7 +322,13 @@ const verifyAsync = async (issuer: string, token: string): Promise<jwt.JwtPayloa
       return;
     }
 
-    const verifyOptions: jwt.VerifyOptions = {};
+    const verifyOptions: jwt.VerifyOptions = {
+      // SECURITY: explicitly pin the accepted signature algorithms to the asymmetric family.
+      // The signing key here comes from the issuer's JWKS (an RSA/EC public key), so without an
+      // explicit allow-list a future key-format change or library regression could reintroduce
+      // classic `alg=none` / RS256->HS256 confusion attacks. Pinning fails such tokens closed.
+      algorithms: ['RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512', 'PS256'],
+    };
     if (Array.isArray(options.audience)) {
       verifyOptions.audience = options.audience as [string, ...string[]];
     } else {
@@ -367,7 +376,8 @@ export const getUserPayload = async (
   requestDomain?: string,
   systemApiKey?: string,
   userApiKey?: string,
-  requestContext?: RequestContext
+  requestContext?: RequestContext,
+  req?: IncomingMessage
 ): Promise<UserPayload> => {
   try {
     const readOnlyDataSource = GetReadOnlyDataSource(dataSources, { allowFallbackToReadWrite: true });
@@ -394,7 +404,7 @@ export const getUserPayload = async (
         systemUser
       );
 
-      if (validationResult.IsValid && validationResult.User) {
+      if (validationResult.IsValid && validationResult.User && validationResult.APIKeyId) {
         // Get the user from UserCache to ensure UserRoles is properly populated
         // The validationResult.User from APIKeyEngine doesn't include UserRoles
         const cachedUser = UserCache.Instance.Users.find(
@@ -402,7 +412,32 @@ export const getUserPayload = async (
         );
 
         // Use cached user if available, otherwise fall back to the validation result
-        const userRecord = cachedUser || validationResult.User;
+        const resolvedUser = cachedUser || validationResult.User;
+
+        // ALWAYS clone before stamping per-session state: the resolved user is
+        // very often the SHARED UserCache instance, and stamping it in place
+        // leaks one session's row-filter bindings / acting context to every
+        // concurrent session of the same user (same pattern as
+        // buildMagicLinkSessionUser — see sessionUserClone.ts).
+        const userRecord = CloneUserForSessionContext(resolvedUser);
+
+        // Row-filter bindings for this key, rebuilt PER REQUEST from the
+        // APIKeysEngineBase cache (staleness envelope = scopeCacheTTLMs, same
+        // as scope enforcement). Consumed by
+        // EntityInfo.GetEffectiveRowFilterWhereClause at every RLS enforcement
+        // point — outside the role-RLS exemption. Throws (fail closed) if the
+        // engine's base cache has not loaded yet.
+        userRecord.APIKeyRowFilters = apiKeyEngine.GetRowFilterBindingsForKey(validationResult.APIKeyId);
+
+        // Acting context: values are deployment-supplied via the registered
+        // resolver (plan §5.8) — server-derived only, never client input. No
+        // resolver (the default) means no acting context, and any filter
+        // requiring {{Acting*}} tokens fails closed.
+        const actingResolver = GetAPIKeyActingContextResolver();
+        if (actingResolver) {
+          userRecord.APIKeyActingContext =
+            (await actingResolver(req, userRecord, validationResult.APIKeyId)) ?? undefined;
+        }
 
         return {
           userRecord,
@@ -420,7 +455,13 @@ export const getUserPayload = async (
     // Check for system API key (x-mj-api-key header)
     // This authenticates as the system user for system-level operations
     if (systemApiKey && systemApiKey != String(undefined)) {
-      if (systemApiKey === apiKey) {
+      // SECURITY: compare the superadmin system API key in constant time. A plain `===`
+      // short-circuits on the first differing byte, leaking a timing side-channel that could
+      // be used to recover the key byte-by-byte. Hash both sides to fixed-length digests so
+      // timingSafeEqual never throws on length mismatch and the comparison is length-agnostic.
+      const systemKeyDigest = createHash('sha256').update(String(systemApiKey)).digest();
+      const providedKeyDigest = createHash('sha256').update(String(apiKey)).digest();
+      if (timingSafeEqual(systemKeyDigest, providedKeyDigest)) {
         const systemUser = await getSystemUser(readOnlyDataSource);
         return {
           userRecord: systemUser,
@@ -622,7 +663,8 @@ export function createUnifiedAuthMiddleware(
         requestDomain,
         systemApiKey,
         userApiKey,
-        requestContext
+        requestContext,
+        req
       );
 
       if (!userPayload) {