@memberjunction/server 5.39.0 → 5.40.1

package/src/generic/ResolverBase.ts

@@ -587,7 +587,16 @@ export class ResolverBase {
 
     // first check permissions, the logged in user must have read permissions on the entity to run the view
     if (entityInfo) {
-      const userInfo = UserCache.Users.find((u) => u.Email.toLowerCase().trim() === userPayload.email.toLowerCase().trim()); // get the user record from MD so we have ROLES attached, don't use the one from payload directly
+      // Prefer the authenticated session's payload user WHEN it carries roles — that is the
+      // authoritative per-session identity (and, for magic-link sessions, carries claims-based
+      // synthesized roles that are deliberately NOT persisted to the shared UserCache). For
+      // normal users the payload user IS the UserCache user, so this is a no-op; we only diverge
+      // for per-session synthesized identities. Fall back to the cache lookup when the payload
+      // user has no roles attached (older/edge auth paths).
+      const payloadUser = this.GetUserFromPayload(userPayload);
+      const userInfo = (payloadUser && payloadUser.UserRoles && payloadUser.UserRoles.length > 0)
+        ? payloadUser
+        : UserCache.Users.find((u) => u.Email.toLowerCase().trim() === userPayload.email.toLowerCase().trim());
       if (!userInfo) {
         throw new Error(`User ${userPayload.email} not found in metadata`);
       }
@@ -709,7 +718,12 @@ export class ResolverBase {
       await this.CheckAPIKeyScopeAuthorization('view:run', viewInfo.Entity, userPayload);
 
       const md = provider
-      const user = UserCache.Users.find((u) => u.Email.toLowerCase().trim() === userPayload?.email.toLowerCase().trim());
+      // Prefer the authenticated session's payload user — it is the authoritative per-request
+      // identity and (for magic-link sessions) carries the per-session resource scope / synthesized
+      // roles that drive RLS. The cached lookup is a fallback for paths where the payload user
+      // isn't populated. For normal users the two are the same instance, so this is a no-op.
+      const user = this.GetUserFromPayload(userPayload)
+        ?? UserCache.Users.find((u) => u.Email.toLowerCase().trim() === userPayload?.email.toLowerCase().trim());
       if (!user) throw new Error(`User ${userPayload?.email} not found in metadata`);
 
       const entityInfo = md.Entities.find((e) => e.Name === viewInfo.Entity);
@@ -823,8 +837,14 @@ export class ResolverBase {
       // Fix #1: Get user info only once for all queries
       let contextUser: UserInfo | null = null;
       if (params[0]?.userPayload?.email) {
-        const userEmail = params[0].userPayload.email.toLowerCase().trim();
-        const user = UserCache.Users.find(u => u.Email.toLowerCase().trim() === userEmail);
+        const userPayload = params[0].userPayload;
+        const userEmail = userPayload.email.toLowerCase().trim();
+        // Prefer the authenticated session's payload user — it is the authoritative per-request
+        // identity and (for magic-link sessions) carries the per-session resource scope / synthesized
+        // roles that drive RLS. The cached lookup is a fallback for paths where the payload user
+        // isn't populated. For normal users the two are the same instance, so this is a no-op.
+        const user = this.GetUserFromPayload(userPayload)
+          ?? UserCache.Users.find(u => u.Email.toLowerCase().trim() === userEmail);
         if (!user) {
           throw new Error(`User ${userEmail} not found in metadata`);
         }
@@ -921,7 +941,9 @@ export class ResolverBase {
       if (!entityInfo) throw new Error(`Entity ${entityName} not found in metadata`);
 
       if (entityInfo.AuditRecordAccess) {
-        const userInfo = UserCache.Users.find((u) => u.Email.toLowerCase().trim() === userPayload?.email.toLowerCase().trim());
+        // Prefer the per-session payload user (the actual actor for this request) over the cache lookup.
+        const userInfo = this.GetUserFromPayload(userPayload)
+          ?? UserCache.Users.find((u) => u.Email.toLowerCase().trim() === userPayload?.email.toLowerCase().trim());
         const auditLogTypeName = 'Record Accessed';
         const auditLogType = md.AuditLogTypes.find((a) => a.Name.trim().toLowerCase() === auditLogTypeName.trim().toLowerCase());
 
@@ -939,7 +961,11 @@ export class ResolverBase {
     const md = provider;
     const entityInfo = md.Entities.find((e) => e.Name.trim().toLowerCase() === entityName.trim().toLowerCase());
     if (!entityInfo) throw new Error(`Entity ${entityName} not found in metadata`);
-    const user = UserCache.Users.find((u) => u.Email.toLowerCase().trim() === userPayload?.email.toLowerCase().trim());
+    // Prefer the authenticated session's payload user — it is the authoritative per-request identity
+    // and (for magic-link sessions) carries the per-session resource scope / synthesized roles that
+    // the RLS WHERE clause (e.g. {{ScopeResourceID}}) depends on. Cache lookup is the fallback.
+    const user = this.GetUserFromPayload(userPayload)
+      ?? UserCache.Users.find((u) => u.Email.toLowerCase().trim() === userPayload?.email.toLowerCase().trim());
     if (!user) throw new Error(`User ${userPayload?.email} not found in metadata`);
 
     return entityInfo.GetUserRowLevelSecurityWhereClause(user, type, returnPrefix);
@@ -957,7 +983,9 @@ export class ResolverBase {
   ): Promise<any> {
     try {
       const md = provider;
-      const userInfo = UserCache.Users.find((u) => u.Email.toLowerCase().trim() === userPayload?.email.toLowerCase().trim());
+      // Prefer the per-session payload user (the actual actor for this request) over the cache lookup.
+      const userInfo = this.GetUserFromPayload(userPayload)
+        ?? UserCache.Users.find((u) => u.Email.toLowerCase().trim() === userPayload?.email.toLowerCase().trim());
       const authorization = authorizationName
         ? md.Authorizations.find((a) => a.Name.trim().toLowerCase() === authorizationName.trim().toLowerCase())
         : null;

package/src/index.ts

@@ -35,6 +35,8 @@ import { auditResolversForUndecoratedArgs } from './logging/bootAudit.js';
 import createMSSQLConfig from './orm.js';
 import { setupRESTEndpoints } from './rest/setupRESTEndpoints.js';
 import { createOAuthCallbackHandler } from './rest/OAuthCallbackHandler.js';
+import { createSignatureWebhookHandler } from './rest/SignatureWebhookHandler.js';
+import { createMagicLinkHandler, registerMagicLinkAuthProvider, MAGIC_LINK_MOUNT_PATH } from './auth/magicLink/index.js';
 
 import { resolve } from 'node:path';
 import { DataSourceInfo, raiseEvent } from './types.js';
@@ -111,6 +113,8 @@ export * from './resolvers/SearchKnowledgeResolver.js';
 export * from './resolvers/SearchKnowledgeStreamResolver.js';
 export * from './resolvers/AvailableSearchProvidersResolver.js';
 export * from './resolvers/FetchEntityVectorsResolver.js';
+export * from './resolvers/RunClusterAnalysisResolver.js';
+export * from './resolvers/GenerateSeedTaxonomyResolver.js';
 export * from './resolvers/PipelineProgressResolver.js';
 export * from './resolvers/IntegrationProgressResolver.js';
 export * from './resolvers/ClientToolRequestResolver.js';
@@ -925,6 +929,24 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     console.log('[OAuth] Callback route registered at /oauth/callback');
   }
 
+  // ─── eSignature webhook (unauthenticated, registered BEFORE auth) ─────
+  // Called by external signature providers (DocuSign Connect, etc.) without an MJ bearer token.
+  // The provider DRIVER verifies the payload signature/HMAC; MJ auth does not apply here.
+  app.use('/esignature', cors<cors.CorsRequest>(), createSignatureWebhookHandler());
+  console.log('[eSignature] Webhook route registered at /esignature/webhook/:driverKey');
+
+  // ─── Magic-link routes (MJ-issued, app-scoped external access) ───────────
+  // Public router (JWKS + redeem) mounts BEFORE the auth middleware; the
+  // authenticated invite-creation router mounts AFTER it (see below).
+  let magicLinkAuthenticatedRouter: ReturnType<typeof createMagicLinkHandler>['authenticatedRouter'] | undefined;
+  if (configInfo.magicLink?.enabled) {
+    const { publicRouter, authenticatedRouter } = createMagicLinkHandler(oauthPublicUrl, configInfo.magicLink);
+    magicLinkAuthenticatedRouter = authenticatedRouter;
+    registerMagicLinkAuthProvider(oauthPublicUrl, configInfo.magicLink);
+    app.use(MAGIC_LINK_MOUNT_PATH, cors<cors.CorsRequest>(), publicRouter);
+    console.log(`[MagicLink] Public routes registered at ${MAGIC_LINK_MOUNT_PATH}/redeem and ${MAGIC_LINK_MOUNT_PATH}/jwks.json`);
+  }
+
   // ─── Global CORS (before auth so 401 responses include CORS headers) ─────
   // Without this, the browser blocks 401 responses from the auth middleware
   // because they lack Access-Control-Allow-Origin headers, preventing the
@@ -966,6 +988,12 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     console.log('[OAuth] Authenticated routes registered at /oauth/status, /oauth/initiate, and /oauth/exchange');
   }
 
+  // ─── Magic-link authenticated route (invite creation) ─────────────────────
+  if (magicLinkAuthenticatedRouter) {
+    app.use(MAGIC_LINK_MOUNT_PATH, cors<cors.CorsRequest>(), magicLinkAuthenticatedRouter);
+    console.log(`[MagicLink] Authenticated route registered at ${MAGIC_LINK_MOUNT_PATH}/create`);
+  }
+
   // ─── REST API endpoints (auth already handled by unified middleware) ─────
   const restApiConfig = {
     enabled: configInfo.restApiOptions?.enabled ?? false,

package/src/resolvers/CurrentUserContextResolver.ts

@@ -1,9 +1,15 @@
 /**
  * Resolver for the `CurrentUserTenantContext` GraphQL query.
  *
- * Returns the server-set `TenantContext` from the authenticated user's `UserInfo`.
- * This is populated by post-auth middleware (e.g., BCSaaS's `bcTenantContextMiddleware`)
- * and serialized as JSON so the client can auto-stamp `UserInfo.TenantContext`.
+ * Returns the server-set `TenantContext` for the authenticated user, serialized
+ * as JSON so the client can auto-stamp `UserInfo.TenantContext`.
+ *
+ * **Resolution order:**
+ * 1. Request-scoped context (`userPayload.__bcResolvedTenantContext`) — set by
+ *    post-auth middleware on the per-request UserPayload. Immune to race conditions
+ *    when concurrent requests share the same cached UserInfo object.
+ * 2. Fallback to `userRecord.TenantContext` — for middleware that stamps UserInfo
+ *    directly (vanilla MJ deployments or non-BCSaaS middleware).
  *
  * On the client, `GraphQLDataProvider.GetCurrentUser()` batches this query alongside
  * `CurrentUser` — making plugins stack-layer agnostic without any client-side code.
@@ -16,6 +22,9 @@ import { GraphQLJSONObject } from 'graphql-type-json';
 import { AppContext } from '../types.js';
 import { ResolverBase } from '../generic/ResolverBase.js';
 
+/** Well-known key for request-scoped TenantContext on UserPayload */
+const RESOLVED_TENANT_CONTEXT_KEY = '__bcResolvedTenantContext';
+
 @Resolver()
 export class CurrentUserContextResolver extends ResolverBase {
   @Query(() => GraphQLJSONObject, {
@@ -27,13 +36,20 @@ export class CurrentUserContextResolver extends ResolverBase {
   ): Promise<Record<string, unknown> | null> {
     await this.CheckAPIKeyScopeAuthorization('user:read', '*', context.userPayload);
 
+    // Prefer request-scoped context (set by BCSaaS middleware on userPayload).
+    // This avoids race conditions with concurrent requests mutating the shared
+    // UserInfo.TenantContext on the same cached UserInfo object from UserCache.
+    const requestScoped = (context.userPayload as Record<string, unknown>)[RESOLVED_TENANT_CONTEXT_KEY];
+    if (requestScoped && typeof requestScoped === 'object') {
+      return { ...(requestScoped as Record<string, unknown>) };
+    }
+
+    // Fallback: read from the shared UserInfo (vanilla MJ / non-BCSaaS middleware)
     const userRecord = context.userPayload.userRecord;
     if (!userRecord?.TenantContext) {
       return null;
     }
 
-    // Serialize the full TenantContext (which may be an extended type like BCTenantContext).
-    // JSON serialization captures all enumerable properties including those from subtypes.
     return { ...userRecord.TenantContext } as Record<string, unknown>;
   }
 }

package/src/resolvers/EntityResolver.ts

@@ -1,10 +1,22 @@
 import { EntityPermissionType, IRunViewProvider } from '@memberjunction/core';
 import { AppContext } from '../types.js';
-import { Arg, Ctx, Query, Resolver, InputType, Field } from 'type-graphql';
+import { Arg, Ctx, Query, Resolver } from 'type-graphql';
 import { MJEntity_, MJEntityResolverBase } from '../generated/generated.js';
-import sql from 'mssql';
 import { GetReadOnlyProvider } from '../util.js';
 
+const VALID_SCHEMA_NAME = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+function sanitizeSchemaNames(names: string[]): string[] {
+  return names.filter((s) => VALID_SCHEMA_NAME.test(s));
+}
+
+function buildSchemaInClause(columnName: string, schemas: string[], negate: boolean): string {
+  const sanitized = sanitizeSchemaNames(schemas);
+  if (sanitized.length === 0) return '';
+  const operator = negate ? 'NOT IN' : 'IN';
+  return `${columnName} ${operator} (${sanitized.map((s) => `'${s}'`).join(',')})`;
+}
+
 @Resolver(MJEntity_)
 export class EntityResolver extends MJEntityResolverBase {
   @Query(() => [MJEntity_])
@@ -17,9 +29,9 @@ export class EntityResolver extends MJEntityResolverBase {
     const provider = GetReadOnlyProvider(providers, { allowFallbackToReadWrite: true });
     const rlsWhere = this.getRowLevelSecurityWhereClause(provider, 'Entities', userPayload, EntityPermissionType.Read, ' WHERE');
     const includeSchemaSQL =
-      IncludeSchemas && IncludeSchemas.length > 0 ? `SchemaName IN (${IncludeSchemas.map((s) => `'${s}'`).join(',')})` : '';
+      IncludeSchemas && IncludeSchemas.length > 0 ? buildSchemaInClause('SchemaName', IncludeSchemas, false) : '';
     const excludeSchemaSQL =
-      ExcludeSchemas && ExcludeSchemas.length > 0 ? `SchemaName NOT IN (${ExcludeSchemas.map((s) => `'${s}'`).join(',')})` : '';
+      ExcludeSchemas && ExcludeSchemas.length > 0 ? buildSchemaInClause('SchemaName', ExcludeSchemas, true) : '';
     let schemaSQL = '';
     if (includeSchemaSQL) schemaSQL = includeSchemaSQL;
     if (excludeSchemaSQL) {
@@ -32,7 +44,7 @@ export class EntityResolver extends MJEntityResolverBase {
       if (totalWhere) totalWhere = `${totalWhere} AND ${rlsWhere}`;
       else totalWhere = ` ${rlsWhere}`;
     }
-    const rv = provider as any as IRunViewProvider;
+    const rv = provider as IRunViewProvider;
     const result = await rv.RunView({
       EntityName: 'MJ: Entities',
       ExtraFilter: totalWhere,

package/src/resolvers/GenerateSeedTaxonomyResolver.ts

@@ -0,0 +1,90 @@
+import { Resolver, Mutation, Arg, Ctx, ObjectType, Field, Int } from 'type-graphql';
+import { AppContext } from '../types.js';
+import { LogError, LogStatus } from '@memberjunction/core';
+import { ResolverBase } from '../generic/ResolverBase.js';
+import { TagEngine, SeedTaxonomyResult } from '@memberjunction/tag-engine';
+
+/* ───── GraphQL output ───── */
+
+@ObjectType()
+export class GenerateSeedTaxonomyResult {
+    @Field()
+    Success: boolean;
+
+    @Field({ nullable: true })
+    ErrorMessage?: string;
+
+    /** How the taxonomy was produced: 'clustering' or 'prompt-fallback'. */
+    @Field({ nullable: true })
+    Method?: string;
+
+    /** Number of content items sampled / considered. */
+    @Field(() => Int)
+    SampleSize: number;
+
+    /**
+     * JSON-serialized array of SeedTaxonomyNode (the proposed, NON-persisted tree).
+     * Kept as a JSON string to keep the GraphQL schema simple, mirroring
+     * RunClusterAnalysis's *JSON fields.
+     */
+    @Field()
+    NodesJSON: string;
+}
+
+/* ───── Resolver ───── */
+
+@Resolver()
+export class GenerateSeedTaxonomyResolver extends ResolverBase {
+    /**
+     * Propose a hierarchical tag taxonomy for a content source WITHOUT persisting
+     * anything. Thin wrapper over {@link TagEngine.generateSeedTaxonomy}.
+     *
+     * @param sourceID   The ContentSource ID whose items seed the taxonomy.
+     * @param sampleSize Max number of content items to consider (defaults to 200 when <= 0).
+     */
+    @Mutation(() => GenerateSeedTaxonomyResult)
+    async GenerateSeedTaxonomy(
+        @Arg('sourceID', () => String) sourceID: string,
+        @Arg('sampleSize', () => Int, { nullable: true }) sampleSize: number,
+        @Ctx() { userPayload }: AppContext = {} as AppContext
+    ): Promise<GenerateSeedTaxonomyResult> {
+        try {
+            const currentUser = this.GetUserFromPayload(userPayload);
+            if (!currentUser) {
+                return this.errorResult('Unable to determine current user');
+            }
+            if (!sourceID || sourceID.trim().length === 0) {
+                return this.errorResult('sourceID is required');
+            }
+
+            LogStatus(`GenerateSeedTaxonomy: sourceID=${sourceID} sampleSize=${sampleSize ?? 'default'}`);
+
+            const result: SeedTaxonomyResult = await TagEngine.Instance.generateSeedTaxonomy(
+                sourceID,
+                sampleSize ?? 0,
+                currentUser
+            );
+
+            return {
+                Success: true,
+                Method: result.Method,
+                SampleSize: result.SampleSize,
+                NodesJSON: JSON.stringify(result.Nodes),
+                ErrorMessage: result.Message,
+            };
+        } catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            LogError(`GenerateSeedTaxonomy mutation failed: ${msg}`);
+            return this.errorResult(msg);
+        }
+    }
+
+    private errorResult(message: string): GenerateSeedTaxonomyResult {
+        return {
+            Success: false,
+            ErrorMessage: message,
+            SampleSize: 0,
+            NodesJSON: '[]',
+        };
+    }
+}

package/src/resolvers/RunClusterAnalysisResolver.ts

@@ -0,0 +1,249 @@
+import { Resolver, Mutation, Arg, Ctx, ObjectType, InputType, Field, Float, Int } from 'type-graphql';
+import { AppContext } from '../types.js';
+import { LogError, LogStatus, UserInfo, IMetadataProvider } from '@memberjunction/core';
+import { ResolverBase } from '../generic/ResolverBase.js';
+import { GetReadWriteProvider } from '../util.js';
+import {
+    ClusteringEngine,
+    EntityDocumentVectorSource,
+    ClusterConfig,
+    ClusterAlgorithm,
+    ClusterDistanceMetric,
+} from '@memberjunction/clustering-engine';
+
+/* ───── GraphQL input ───── */
+
+@InputType()
+export class RunClusterAnalysisInput {
+    @Field({ nullable: true })
+    EntityName?: string;
+
+    @Field({ nullable: true })
+    EntityID?: string;
+
+    @Field({ nullable: true })
+    EntityDocumentID?: string;
+
+    /**
+     * Multi-entity clustering: one or more Entity Document IDs whose vectors are
+     * merged into a single analysis. Takes precedence over EntityDocumentID when
+     * non-empty. All selected docs must share the same embedding model (the engine
+     * hard-blocks mismatches).
+     */
+    @Field(() => [String], { nullable: true })
+    EntityDocumentIDs?: string[];
+
+    /** Legend mode: color points by 'cluster' (default) or 'entity'. */
+    @Field({ nullable: true })
+    ColorBy?: string;
+
+    /** Clustering algorithm: 'kmeans' or 'dbscan'. */
+    @Field({ nullable: true })
+    Algorithm?: string;
+
+    /** Number of clusters for K-Means. */
+    @Field(() => Int, { nullable: true })
+    K?: number;
+
+    /** Epsilon neighbourhood radius for DBSCAN. */
+    @Field(() => Float, { nullable: true })
+    Epsilon?: number;
+
+    /** Minimum points to form a dense region in DBSCAN. */
+    @Field(() => Int, { nullable: true })
+    MinPoints?: number;
+
+    /** Distance metric: 'cosine', 'euclidean' or 'dotproduct'. */
+    @Field({ nullable: true })
+    DistanceMetric?: string;
+
+    /** Maximum number of records to fetch for clustering. */
+    @Field(() => Int, { nullable: true })
+    MaxRecords?: number;
+
+    /** Optional SQL-style filter applied by the vector source. */
+    @Field({ nullable: true })
+    Filter?: string;
+
+    /** When true, runs the optional LLM cluster-naming step. */
+    @Field({ nullable: true })
+    NameClusters?: boolean;
+
+    /** Number of dimensions for the projected layout (2 or 3). Defaults to 2. */
+    @Field(() => Int, { nullable: true })
+    Dimensions?: number;
+
+    /**
+     * When supplied, the result is persisted as an `MJ: Cluster Analysis` row
+     * with this Name and the returned `AnalysisID` is populated.
+     */
+    @Field({ nullable: true })
+    PersistName?: string;
+}
+
+/* ───── GraphQL output ───── */
+
+@ObjectType()
+export class RunClusterAnalysisResult {
+    @Field()
+    Success: boolean;
+
+    @Field({ nullable: true })
+    ErrorMessage?: string;
+
+    /** Number of clusters discovered. */
+    @Field(() => Int)
+    ClusterCount: number;
+
+    /** Number of records that were clustered. */
+    @Field(() => Int)
+    RecordCount: number;
+
+    /** Number of outlier points (DBSCAN only). */
+    @Field(() => Int)
+    OutlierCount: number;
+
+    /** Silhouette score (-1 .. 1). */
+    @Field(() => Float)
+    SilhouetteScore: number;
+
+    /** Wall-clock computation time in milliseconds. */
+    @Field(() => Float)
+    ComputationTimeMs: number;
+
+    /** JSON-serialized {@link ClusterMetrics}. */
+    @Field()
+    MetricsJSON: string;
+
+    /** JSON-serialized array of {@link ClusterInfo}. */
+    @Field()
+    ClustersJSON: string;
+
+    /** JSON-serialized array of {@link ClusterPoint} (can be large). */
+    @Field()
+    PointsJSON: string;
+
+    /** The persisted `MJ: Cluster Analysis` ID when a PersistName was supplied. */
+    @Field({ nullable: true })
+    AnalysisID?: string;
+}
+
+/* ───── Resolver ───── */
+
+@Resolver()
+export class RunClusterAnalysisResolver extends ResolverBase {
+    @Mutation(() => RunClusterAnalysisResult)
+    async RunClusterAnalysis(
+        @Arg('input', () => RunClusterAnalysisInput) input: RunClusterAnalysisInput,
+        @Ctx() context: AppContext = {} as AppContext
+    ): Promise<RunClusterAnalysisResult> {
+        try {
+            const currentUser = this.GetUserFromPayload(context.userPayload);
+            if (!currentUser) {
+                return this.errorResult('Unable to determine current user');
+            }
+
+            // Per-request provider so reads/writes use this user's connection +
+            // security context (multi-user safe), not the process global.
+            const provider = GetReadWriteProvider(context.providers) as unknown as IMetadataProvider;
+            const config = this.buildConfig(input);
+            const engine = new ClusteringEngine();
+            const vectorSource = new EntityDocumentVectorSource(currentUser, provider);
+
+            LogStatus(
+                `RunClusterAnalysis: algorithm=${config.Algorithm} entity=${config.EntityName ?? config.EntityID ?? config.EntityDocumentID}`
+            );
+
+            const result = await engine.RunPipeline(config, vectorSource, currentUser);
+
+            let analysisID: string | undefined;
+            if (input.PersistName && input.PersistName.trim().length > 0) {
+                analysisID = await this.persistAnalysis(engine, result, config, input.PersistName.trim(), currentUser, provider);
+            }
+
+            return {
+                Success: true,
+                ClusterCount: result.Metrics.ClusterCount,
+                RecordCount: result.Metrics.RecordCount,
+                OutlierCount: result.Metrics.OutlierCount,
+                SilhouetteScore: result.Metrics.SilhouetteScore,
+                ComputationTimeMs: result.Metrics.ComputationTimeMs,
+                MetricsJSON: JSON.stringify(result.Metrics),
+                ClustersJSON: JSON.stringify(result.Clusters),
+                PointsJSON: JSON.stringify(result.Points),
+                AnalysisID: analysisID,
+            };
+        } catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            LogError(`RunClusterAnalysis mutation failed: ${msg}`);
+            return this.errorResult(msg);
+        }
+    }
+
+    /** Build a {@link ClusterConfig} from the GraphQL input, applying defaults. */
+    private buildConfig(input: RunClusterAnalysisInput): ClusterConfig {
+        return {
+            EntityName: input.EntityName ?? '',
+            EntityID: input.EntityID ?? '',
+            EntityDocumentID: input.EntityDocumentID ?? '',
+            EntityDocumentIDs: (input.EntityDocumentIDs ?? []).filter((id) => !!id && id.trim().length > 0),
+            ColorBy: input.ColorBy === 'entity' ? 'entity' : 'cluster',
+            Algorithm: this.normalizeAlgorithm(input.Algorithm),
+            K: input.K ?? 4,
+            Epsilon: input.Epsilon ?? 0.3,
+            MinPoints: input.MinPoints ?? 3,
+            DistanceMetric: this.normalizeMetric(input.DistanceMetric),
+            MaxRecords: input.MaxRecords ?? 500,
+            Filter: input.Filter ?? '',
+            NameClusters: input.NameClusters ?? false,
+            Dimensions: input.Dimensions === 3 ? 3 : 2,
+        };
+    }
+
+    /** Coerce a raw algorithm string to a supported {@link ClusterAlgorithm}. */
+    private normalizeAlgorithm(value: string | undefined): ClusterAlgorithm {
+        return value?.toLowerCase() === 'dbscan' ? 'dbscan' : 'kmeans';
+    }
+
+    /** Coerce a raw metric string to a supported {@link ClusterDistanceMetric}. */
+    private normalizeMetric(value: string | undefined): ClusterDistanceMetric {
+        const v = value?.toLowerCase();
+        if (v === 'euclidean' || v === 'dotproduct') {
+            return v;
+        }
+        return 'cosine';
+    }
+
+    /** Persist the result and return the new analysis ID (or undefined on failure). */
+    private async persistAnalysis(
+        engine: ClusteringEngine,
+        result: Awaited<ReturnType<ClusteringEngine['RunPipeline']>>,
+        config: ClusterConfig,
+        persistName: string,
+        currentUser: UserInfo,
+        provider?: IMetadataProvider
+    ): Promise<string | undefined> {
+        const owner = { Name: persistName, UserID: currentUser.ID };
+        const savedID = await engine.SaveAnalysis(result, config, owner, currentUser, provider);
+        if (!savedID) {
+            LogError(`RunClusterAnalysis: failed to persist analysis "${persistName}".`);
+            return undefined;
+        }
+        return savedID;
+    }
+
+    private errorResult(message: string): RunClusterAnalysisResult {
+        return {
+            Success: false,
+            ErrorMessage: message,
+            ClusterCount: 0,
+            RecordCount: 0,
+            OutlierCount: 0,
+            SilhouetteScore: 0,
+            ComputationTimeMs: 0,
+            MetricsJSON: '{}',
+            ClustersJSON: '[]',
+            PointsJSON: '[]',
+        };
+    }
+}

package/src/resolvers/UserResolver.ts

@@ -1,9 +1,45 @@
-import { AppContext, Arg, Ctx, Int, Query, Resolver } from '@memberjunction/server';
-import { MJUser_, MJUserResolverBase } from '../generated/generated.js';
+import { AppContext, Arg, Ctx, FieldResolver, Int, PubSub, PubSubEngine, Query, Resolver, Root } from '@memberjunction/server';
+import { UUIDsEqual } from '@memberjunction/global';
+import { MJUser_, MJUserRole_, MJUserResolverBase } from '../generated/generated.js';
 import { GetReadOnlyProvider } from '../util.js';
 
 @Resolver(MJUser_)
 export class UserResolver extends MJUserResolverBase {
+
+  /**
+   * Roles for the current user row.
+   *
+   * Overrides the generated field resolver to support ANONYMOUS magic-link sessions: those
+   * resolve to a shared Anonymous principal that holds NO roles in the database (by design —
+   * persisting them would let anonymous sessions accrete privileges across links). The roles
+   * are synthesized per-request in {@link buildMagicLinkSessionUser} and live only on the
+   * request's `UserInfo`. For the session's OWN user row we serve those synthesized roles
+   * directly, skipping the generated DB query (which returns empty) and its `MJ: User Roles`
+   * read-permission check (which the restricted anon role wouldn't pass). Every other case —
+   * named users, named magic-link users, listing other users' roles — falls through to the
+   * generated resolver unchanged, so there is no behavioral or security change off this path.
+   */
+  @FieldResolver(() => [MJUserRole_])
+  async MJUserRoles_UserIDArray(@Root() mjuser_: MJUser_, @Ctx() context: AppContext, @PubSub() pubSub: PubSubEngine) {
+    const sessionUser = context.userPayload?.userRecord;
+    if (sessionUser?.IsMagicLinkAnonymous && UUIDsEqual(mjuser_.ID, sessionUser.ID)) {
+      const now = new Date();
+      // Build rows with the entity's RAW field names, then run them through the same
+      // name→code-name mapping the generated resolver uses (e.g. __mj_CreatedAt →
+      // _mj__CreatedAt). Returning raw names directly trips GraphQL's non-nullable check.
+      const rows = (sessionUser.UserRoles ?? []).map((r: { UserID: string; RoleID: string; RoleName?: string; Role?: string }) => ({
+        ID: sessionUser.ID,
+        UserID: r.UserID,
+        RoleID: r.RoleID,
+        User: sessionUser.Name,
+        Role: r.RoleName ?? r.Role,
+        __mj_CreatedAt: now,
+        __mj_UpdatedAt: now,
+      }));
+      return this.ArrayMapFieldNamesToCodeNames('MJ: User Roles', rows, sessionUser);
+    }
+    return super.MJUserRoles_UserIDArray(mjuser_, context, pubSub);
+  }
   @Query(() => MJUser_)
   async CurrentUser(@Ctx() context: AppContext) {
     // Check API key scope authorization for user read (self)