@memberjunction/server 3.2.0 → 3.3.0

package/src/auth/APIKeyScopeAuth.ts

@@ -0,0 +1,366 @@
+/**
+ * API Key Scope Authorization Utilities
+ * Provides utilities for checking API key scopes in resolvers
+ * @module @memberjunction/server
+ */
+
+import { AuthorizationError } from 'type-graphql';
+import { GetAPIKeyEngine, AuthorizationResult, AuthorizationRequest } from '@memberjunction/api-keys';
+import { UserInfo, RunView } from '@memberjunction/core';
+import { APIKeyEntity, APIApplicationEntity } from '@memberjunction/core-entities';
+
+/**
+ * Application names used by the API Key authorization system
+ */
+export type ApplicationName = 'MJAPI' | 'MCPServer' | 'A2AServer' | string;
+
+/**
+ * Options for scope authorization
+ */
+export interface ScopeAuthOptions {
+    /** The application making the request (default: 'MJAPI') */
+    applicationName?: ApplicationName;
+    /** Resource being accessed (e.g., entity name, action name) */
+    resource?: string;
+    /** Whether to throw an error on denied access (default: true) */
+    throwOnDenied?: boolean;
+}
+
+/**
+ * Result of scope authorization check
+ */
+export interface ScopeAuthResult {
+    /** Whether access is allowed */
+    Allowed: boolean;
+    /** Human-readable reason for the decision */
+    Reason?: string;
+    /** Whether scope checking was performed (false if no API key or enforcement disabled) */
+    Checked: boolean;
+    /** All rules evaluated during the check */
+    EvaluatedRules?: AuthorizationResult['EvaluatedRules'];
+}
+
+/**
+ * Check if an API key has the required scope for an operation.
+ *
+ * This function implements the three-tier permission model:
+ * 1. User Permissions - What the user can do (already checked by authentication)
+ * 2. Application Ceiling - Maximum scope the application allows
+ * 3. API Key Scopes - Specific scopes granted to this key
+ *
+ * @param apiKeyId - The API key ID from context.userPayload.apiKeyId
+ * @param scopePath - The scope path required (e.g., 'view:run', 'agent:execute')
+ * @param contextUser - The authenticated user from context.userPayload.userRecord
+ * @param options - Additional options for scope checking
+ * @returns ScopeAuthResult with authorization details
+ * @throws AuthorizationError if access is denied and throwOnDenied is true
+ *
+ * @example
+ * ```typescript
+ * // In a resolver
+ * async runView(@Ctx() ctx: AppContext): Promise<ViewResult> {
+ *   await CheckAPIKeyScope(
+ *     ctx.userPayload.apiKeyId,
+ *     'view:run',
+ *     ctx.userPayload.userRecord,
+ *     { resource: 'User' }
+ *   );
+ *   // ... proceed with operation
+ * }
+ * ```
+ */
+export async function CheckAPIKeyScope(
+    apiKeyId: string | undefined,
+    scopePath: string,
+    contextUser: UserInfo,
+    options: ScopeAuthOptions = {}
+): Promise<ScopeAuthResult> {
+    const {
+        applicationName = 'MJAPI',
+        resource = '*',
+        throwOnDenied = true
+    } = options;
+
+    // If no API key ID, not authenticated via API key - skip scope check
+    if (!apiKeyId) {
+        return {
+            Allowed: true,
+            Checked: false,
+            Reason: 'Not authenticated via API key'
+        };
+    }
+
+    const engine = GetAPIKeyEngine();
+
+    // Get the API key to find the user ID
+    const rv = new RunView();
+    const keyResult = await rv.RunView<APIKeyEntity>({
+        EntityName: 'MJ: API Keys',
+        ExtraFilter: `ID='${apiKeyId}'`,
+        ResultType: 'entity_object'
+    }, contextUser);
+
+    if (!keyResult.Success || keyResult.Results.length === 0) {
+        const result: ScopeAuthResult = {
+            Allowed: false,
+            Checked: true,
+            Reason: 'API key not found'
+        };
+        if (throwOnDenied) {
+            throw new AuthorizationError(result.Reason);
+        }
+        return result;
+    }
+
+    const apiKey = keyResult.Results[0];
+
+    // Get the application by name
+    const appResult = await rv.RunView<APIApplicationEntity>({
+        EntityName: 'MJ: API Applications',
+        ExtraFilter: `Name='${applicationName}'`,
+        ResultType: 'entity_object'
+    }, contextUser);
+
+    if (!appResult.Success || appResult.Results.length === 0) {
+        const result: ScopeAuthResult = {
+            Allowed: false,
+            Checked: true,
+            Reason: `Unknown application: ${applicationName}`
+        };
+        if (throwOnDenied) {
+            throw new AuthorizationError(result.Reason);
+        }
+        return result;
+    }
+
+    const app = appResult.Results[0];
+
+    if (!app.IsActive) {
+        const result: ScopeAuthResult = {
+            Allowed: false,
+            Checked: true,
+            Reason: `Application is not active: ${applicationName}`
+        };
+        if (throwOnDenied) {
+            throw new AuthorizationError(result.Reason);
+        }
+        return result;
+    }
+
+    // Build the authorization request
+    const request: AuthorizationRequest = {
+        APIKeyId: apiKeyId,
+        UserId: apiKey.UserID,
+        ApplicationId: app.ID,
+        ScopePath: scopePath,
+        Resource: resource
+    };
+
+    // Use the scope evaluator directly (since we already have the key ID)
+    const scopeEvaluator = engine.GetScopeEvaluator();
+    const authResult = await scopeEvaluator.EvaluateAccess(request, contextUser);
+
+    if (!authResult.Allowed && throwOnDenied) {
+        const scopeDisplay = resource !== '*' ? `${scopePath} (${resource})` : scopePath;
+        throw new AuthorizationError(
+            `API key does not have permission for scope: ${scopeDisplay}. ${authResult.Reason || ''}`
+        );
+    }
+
+    return {
+        Allowed: authResult.Allowed,
+        Reason: authResult.Reason,
+        Checked: true,
+        EvaluatedRules: authResult.EvaluatedRules
+    };
+}
+
+/**
+ * Check if an API key has the required scope and log usage.
+ *
+ * Same as CheckAPIKeyScope but also logs the authorization attempt.
+ * Use this for operations where you want detailed audit trails.
+ *
+ * @param apiKeyId - The API key ID from context.userPayload.apiKeyId
+ * @param scopePath - The scope path required
+ * @param contextUser - The authenticated user
+ * @param usageDetails - Details about the request for logging
+ * @param options - Additional options for scope checking
+ * @returns ScopeAuthResult with authorization details and optional log ID
+ */
+export async function CheckAPIKeyScopeAndLog(
+    apiKeyId: string | undefined,
+    scopePath: string,
+    contextUser: UserInfo,
+    usageDetails: {
+        endpoint: string;
+        method: string;
+        operationName?: string;
+        ipAddress?: string;
+        userAgent?: string;
+        statusCode?: number;
+        responseTimeMs?: number;
+    },
+    options: ScopeAuthOptions = {}
+): Promise<ScopeAuthResult & { LogId?: string }> {
+    const {
+        applicationName = 'MJAPI',
+        resource = '*',
+        throwOnDenied = true
+    } = options;
+
+    // If no API key ID, not authenticated via API key - skip scope check
+    if (!apiKeyId) {
+        return {
+            Allowed: true,
+            Checked: false,
+            Reason: 'Not authenticated via API key'
+        };
+    }
+
+    const engine = GetAPIKeyEngine();
+    const rv = new RunView();
+
+    // Get the API key
+    const keyResult = await rv.RunView<APIKeyEntity>({
+        EntityName: 'MJ: API Keys',
+        ExtraFilter: `ID='${apiKeyId}'`,
+        ResultType: 'entity_object'
+    }, contextUser);
+
+    if (!keyResult.Success || keyResult.Results.length === 0) {
+        const result: ScopeAuthResult & { LogId?: string } = {
+            Allowed: false,
+            Checked: true,
+            Reason: 'API key not found'
+        };
+        if (throwOnDenied) {
+            throw new AuthorizationError(result.Reason);
+        }
+        return result;
+    }
+
+    const apiKey = keyResult.Results[0];
+
+    // Get the application
+    const appResult = await rv.RunView<APIApplicationEntity>({
+        EntityName: 'MJ: API Applications',
+        ExtraFilter: `Name='${applicationName}'`,
+        ResultType: 'entity_object'
+    }, contextUser);
+
+    if (!appResult.Success || appResult.Results.length === 0) {
+        const result: ScopeAuthResult & { LogId?: string } = {
+            Allowed: false,
+            Checked: true,
+            Reason: `Unknown application: ${applicationName}`
+        };
+        if (throwOnDenied) {
+            throw new AuthorizationError(result.Reason);
+        }
+        return result;
+    }
+
+    const app = appResult.Results[0];
+
+    // Build the authorization request
+    const request: AuthorizationRequest = {
+        APIKeyId: apiKeyId,
+        UserId: apiKey.UserID,
+        ApplicationId: app.ID,
+        ScopePath: scopePath,
+        Resource: resource
+    };
+
+    // Evaluate access
+    const scopeEvaluator = engine.GetScopeEvaluator();
+    const authResult = await scopeEvaluator.EvaluateAccess(request, contextUser);
+
+    // Log the usage
+    const usageLogger = engine.GetUsageLogger();
+    const statusCode = usageDetails.statusCode ?? (authResult.Allowed ? 200 : 403);
+
+    let logId: string | undefined;
+    if (authResult.Allowed) {
+        logId = (await usageLogger.LogSuccess(
+            apiKeyId,
+            app.ID,
+            usageDetails.endpoint,
+            usageDetails.operationName || null,
+            usageDetails.method,
+            statusCode,
+            usageDetails.responseTimeMs || null,
+            resource,
+            authResult.EvaluatedRules,
+            usageDetails.ipAddress || null,
+            usageDetails.userAgent || null,
+            contextUser
+        )) || undefined;
+    } else {
+        logId = (await usageLogger.LogDenied(
+            apiKeyId,
+            app.ID,
+            usageDetails.endpoint,
+            usageDetails.operationName || null,
+            usageDetails.method,
+            statusCode,
+            usageDetails.responseTimeMs || null,
+            resource,
+            authResult.EvaluatedRules,
+            authResult.Reason,
+            usageDetails.ipAddress || null,
+            usageDetails.userAgent || null,
+            contextUser
+        )) || undefined;
+    }
+
+    if (!authResult.Allowed && throwOnDenied) {
+        const scopeDisplay = resource !== '*' ? `${scopePath} (${resource})` : scopePath;
+        throw new AuthorizationError(
+            `API key does not have permission for scope: ${scopeDisplay}. ${authResult.Reason || ''}`
+        );
+    }
+
+    return {
+        Allowed: authResult.Allowed,
+        Reason: authResult.Reason,
+        Checked: true,
+        EvaluatedRules: authResult.EvaluatedRules,
+        LogId: logId
+    };
+}
+
+/**
+ * Decorator-style function for common scope checks.
+ * Returns a function that can be used in resolvers.
+ *
+ * @param scopePath - The scope path required
+ * @param options - Additional options
+ * @returns A function that performs the scope check
+ *
+ * @example
+ * ```typescript
+ * const requireViewRun = RequireScope('view:run');
+ *
+ * // In resolver
+ * async runView(@Ctx() ctx: AppContext): Promise<ViewResult> {
+ *   await requireViewRun(ctx);
+ *   // ... proceed
+ * }
+ * ```
+ */
+export function RequireScope(scopePath: string, options: Omit<ScopeAuthOptions, 'resource'> = {}) {
+    return async (ctx: { userPayload: { apiKeyId?: string; userRecord: UserInfo } }, resource?: string) => {
+        await CheckAPIKeyScope(
+            ctx.userPayload.apiKeyId,
+            scopePath,
+            ctx.userPayload.userRecord,
+            { ...options, resource }
+        );
+    };
+}
+
+// Pre-built scope checkers for common operations
+export const RequireViewRun = RequireScope('view:run');
+export const RequireQueryRun = RequireScope('query:run');
+export const RequireAgentExecute = RequireScope('agent:execute');

package/src/auth/index.ts

@@ -12,6 +12,7 @@ import { initializeAuthProviders } from './initializeProviders.js';
 export { TokenExpiredError } from './tokenExpiredError.js';
 export { IAuthProvider } from './IAuthProvider.js';
 export { AuthProviderFactory } from './AuthProviderFactory.js';
+export * from './APIKeyScopeAuth.js';
 
 // This is a hard-coded forever constant due to internal migrations
 

package/src/context.ts

@@ -13,9 +13,10 @@ import { GetReadOnlyDataSource, GetReadWriteDataSource } from './util.js';
 import { v4 as uuidv4 } from 'uuid';
 import e from 'express';
 import { DatabaseProviderBase } from '@memberjunction/core';
-import { SQLServerDataProvider, SQLServerProviderConfigData } from '@memberjunction/sqlserver-dataprovider';
+import { SQLServerDataProvider, SQLServerProviderConfigData, UserCache } from '@memberjunction/sqlserver-dataprovider';
 import { AuthProviderFactory } from './auth/AuthProviderFactory.js';
 import { Metadata } from '@memberjunction/core';
+import { GetAPIKeyEngine } from '@memberjunction/api-keys';
 
 const verifyAsync = async (issuer: string, token: string): Promise<jwt.JwtPayload> =>
   new Promise((resolve, reject) => {
@@ -41,20 +42,83 @@ const verifyAsync = async (issuer: string, token: string): Promise<jwt.JwtPayloa
     });
   });
 
+/**
+ * Request context for API key usage logging.
+ */
+export interface RequestContext {
+  /** The API endpoint path (e.g., '/graphql', '/mcp') */
+  endpoint: string;
+  /** HTTP method (e.g., 'POST', 'GET') */
+  method: string;
+  /** GraphQL operation name if available */
+  operationName?: string;
+  /** Client IP address */
+  ipAddress?: string;
+  /** User-Agent header */
+  userAgent?: string;
+}
+
 export const getUserPayload = async (
   bearerToken: string,
   sessionId = 'default',
   dataSources: DataSourceInfo[],
   requestDomain?: string,
-  requestApiKey?: string 
+  systemApiKey?: string,
+  userApiKey?: string,
+  requestContext?: RequestContext
 ): Promise<UserPayload> => {
   try {
     const readOnlyDataSource = GetReadOnlyDataSource(dataSources, { allowFallbackToReadWrite: true });
     const readWriteDataSource = GetReadWriteDataSource(dataSources);
 
-    if (requestApiKey && requestApiKey != String(undefined)) {
-      // use requestApiKey for auth
-      if (requestApiKey === apiKey) {
+    // Check for user API key first (X-API-Key header with mj_sk_* format)
+    // This authenticates as the specific user who owns the API key
+    if (userApiKey && userApiKey !== String(undefined)) {
+      // Use system user as context for validation operations
+      const systemUser = await getSystemUser(readOnlyDataSource);
+      const apiKeyEngine = GetAPIKeyEngine();
+      const validationResult = await apiKeyEngine.ValidateAPIKey(
+        {
+          RawKey: userApiKey,
+          ApplicationName: 'MJAPI', // Check if key is bound to this application
+          Endpoint: requestContext?.endpoint ?? '/api',
+          Method: requestContext?.method ?? 'POST',
+          Operation: requestContext?.operationName ?? null,
+          StatusCode: 200, // Auth succeeded if we get here
+          ResponseTimeMs: undefined, // Not available at auth time
+          IPAddress: requestContext?.ipAddress ?? null,
+          UserAgent: requestContext?.userAgent ?? null,
+        },
+        systemUser
+      );
+
+      if (validationResult.IsValid && validationResult.User) {
+        // 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(
+          u => u.ID === validationResult.User.ID
+        );
+
+        // Use cached user if available, otherwise fall back to the validation result
+        const userRecord = cachedUser || validationResult.User;
+
+        return {
+          userRecord,
+          email: userRecord.Email,
+          sessionId,
+          apiKeyId: validationResult.APIKeyId,
+          apiKeyHash: validationResult.APIKeyHash,
+        };
+      }
+
+      // MJ API key validation failed - use generic message to prevent enumeration
+      throw new AuthenticationError('Invalid API key');
+    }
+
+    // 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) {
         const systemUser = await getSystemUser(readOnlyDataSource);
         return {
           userRecord: systemUser,
@@ -64,7 +128,7 @@ export const getUserPayload = async (
           apiKey,
         };
       }
-      throw new AuthenticationError('Invalid API key provided');
+      throw new AuthenticationError('Invalid system API key');
     }
 
     const token = bearerToken.replace('Bearer ', '');
@@ -144,8 +208,13 @@ export const contextFunction =
     const requestDomain = url.parse(req.headers.origin || '');
     const sessionId = sessionIdRaw ? sessionIdRaw.toString() : '';
     const bearerToken = req.headers.authorization ?? '';
-    const apiKey = String(req.headers['x-mj-api-key']);
-    
+
+    // Two types of API keys:
+    // - x-mj-api-key: System API key for system-level operations (authenticates as system user)
+    // - X-API-Key: User API key (mj_sk_*) for user-authenticated operations
+    const systemApiKey = String(req.headers['x-mj-api-key']);
+    const userApiKey = String(req.headers['x-api-key']);
+
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const reqAny = req as any;
     const operationName: string | undefined = reqAny.body?.operationName;
@@ -153,12 +222,25 @@ export const contextFunction =
       console.log({ operationName, variables: reqAny.body?.variables || undefined });
     }
 
+    // Build request context for API key logging
+    // Note: responseTimeMs is not available at auth time, only endpoint/method/ip/ua
+    const expressReq = req as e.Request;
+    const requestContext: RequestContext = {
+      endpoint: expressReq.path || expressReq.url || '/api',
+      method: expressReq.method || 'POST',
+      operationName: operationName,
+      ipAddress: expressReq.ip || expressReq.socket?.remoteAddress || undefined,
+      userAgent: req.headers['user-agent'] as string | undefined,
+    };
+
     const userPayload = await getUserPayload(
       bearerToken,
       sessionId,
       dataSources,
       requestDomain?.hostname ? requestDomain.hostname : undefined,
-      apiKey 
+      systemApiKey,
+      userApiKey,
+      requestContext
     );
 
     if (Metadata.Provider.Entities.length === 0 ) {