@optimizely-opal/opal-tool-ocp-sdk 1.0.0-beta.1 → 1.0.0-beta.10

package/src/auth/AuthUtils.ts

@@ -1,23 +1,30 @@
-import { getAppContext, logger } from '@zaiusinc/app-sdk';
+import { getAppContext, logger, Request } from '@zaiusinc/app-sdk';
 import { getTokenVerifier } from './TokenVerifier';
 import { OptiIdAuthData } from '../types/Models';
+import { ToolError } from '../types/ToolError';
 
 /**
  * Validate the OptiID access token
  *
  * @param accessToken - The access token to validate
- * @returns true if the token is valid
+ * @throws {ToolError} If token validation fails
  */
-async function validateAccessToken(accessToken: string | undefined): Promise<boolean> {
+async function validateAccessToken(accessToken: string | undefined): Promise<void> {
   try {
     if (!accessToken) {
-      return false;
+      throw new ToolError('Forbidden', 403, 'OptiID access token is required');
     }
     const tokenVerifier = await getTokenVerifier();
-    return await tokenVerifier.verify(accessToken);
+    const isValid = await tokenVerifier.verify(accessToken);
+    if (!isValid) {
+      throw new ToolError('Forbidden', 403, 'Invalid OptiID access token');
+    }
   } catch (error) {
+    if (error instanceof ToolError) {
+      throw error;
+    }
     logger.error('OptiID token validation failed:', error);
-    return false;
+    throw new ToolError('Forbidden', 403, 'Token verification failed');
   }
 }
 
@@ -25,37 +32,70 @@ async function validateAccessToken(accessToken: string | undefined): Promise<boo
  * Extract and validate basic OptiID authentication data from request
  *
  * @param request - The incoming request
- * @returns object with authData and accessToken, or null if invalid
+ * @returns object with authData and accessToken, or null if auth is missing
  */
 export function extractAuthData(request: any): { authData: OptiIdAuthData; accessToken: string } | null {
   const authData = request?.bodyJSON?.auth as OptiIdAuthData;
+
+  if (!authData) {
+    return null;
+  }
+
+  if (authData?.provider?.toLowerCase() !== 'optiid') {
+    return null;
+  }
+
   const accessToken = authData?.credentials?.access_token;
-  if (!accessToken || authData?.provider?.toLowerCase() !== 'optiid') {
+  if (!accessToken) {
     return null;
   }
 
   return { authData, accessToken };
 }
 
+/**
+ * Extract and validate auth data with error throwing for authentication flow
+ *
+ * @param request - The incoming request
+ * @returns object with authData and accessToken
+ * @throws {ToolError} If auth data is invalid or missing
+ */
+function extractAndValidateAuthData(request: any): { authData: OptiIdAuthData; accessToken: string } {
+  const authData = request?.bodyJSON?.auth as OptiIdAuthData;
+
+  if (!authData) {
+    throw new ToolError('Forbidden', 403, 'Authentication data is required');
+  }
+
+  if (authData?.provider?.toLowerCase() !== 'optiid') {
+    throw new ToolError('Forbidden', 403, 'Only OptiID authentication provider is supported');
+  }
+
+  const accessToken = authData?.credentials?.access_token;
+  if (!accessToken) {
+    throw new ToolError('Forbidden', 403, 'OptiID access token is required');
+  }
+
+  return { authData, accessToken };
+}
+
 /**
  * Validate organization ID matches the app context
  *
  * @param customerId - The customer ID from the auth data
- * @returns true if the organization ID is valid
+ * @throws {ToolError} If organization ID is invalid or missing
  */
-function validateOrganizationId(customerId: string | undefined): boolean {
+function validateOrganizationId(customerId: string | undefined): void {
   if (!customerId) {
     logger.error('Organisation ID is required but not provided');
-    return false;
+    throw new ToolError('Forbidden', 403, 'Organization ID is required');
   }
 
   const appOrganisationId = getAppContext()?.account?.organizationId;
   if (customerId !== appOrganisationId) {
     logger.error(`Invalid organisation ID: expected ${appOrganisationId}, received ${customerId}`);
-    return false;
+    throw new ToolError('Forbidden', 403, 'Organization ID does not match');
   }
-
-  return true;
 }
 
 /**
@@ -73,45 +113,68 @@ function shouldSkipAuth(request: any): boolean {
  *
  * @param request - The incoming request
  * @param validateOrg - Whether to validate organization ID
- * @returns true if authentication succeeds
+ * @throws {ToolError} If authentication fails
  */
-async function authenticateRequest(request: any, validateOrg: boolean): Promise<boolean> {
+async function authenticateRequest(request: any, validateOrg: boolean): Promise<void> {
   if (shouldSkipAuth(request)) {
-    return true;
+    return;
   }
 
-  const authInfo = extractAuthData(request);
-  if (!authInfo) {
-    logger.error('OptiID token is required but not provided');
-    return false;
-  }
-
-  const { authData, accessToken } = authInfo;
+  const { authData, accessToken } = extractAndValidateAuthData(request);
 
   // Validate organization ID if required
-  if (validateOrg && !validateOrganizationId(authData.credentials?.customer_id)) {
-    return false;
+  if (validateOrg) {
+    validateOrganizationId(authData.credentials?.customer_id);
   }
 
-  return await validateAccessToken(accessToken);
+  await validateAccessToken(accessToken);
+}
+
+/**
+ * Authenticate internal requests using OptiID token from headers
+ * @param request The request object
+ * @returns true if authentication succeeds
+ */
+export async function authenticateInternalRequest(request: Request): Promise<void> {
+  try {
+    const headers = request.headers;
+    const optiIdToken = headers?.get('Authorization') || headers?.get('authorization');
+
+    if (!optiIdToken) {
+      logger.info('OptiID token is required in Authorization header for internal requests');
+      throw new ToolError('Unauthorized', 401, 'OptiID token is required');
+    }
+
+    // Validate the token using TokenVerifier directly
+    const tokenVerifier = await getTokenVerifier();
+    const isValidToken = await tokenVerifier.verify(optiIdToken);
+
+    if (!isValidToken) {
+      logger.info('Invalid OptiID token provided for internal request');
+      throw new ToolError('Unauthorized', 401, 'Invalid OptiID token');
+    }
+  } catch (error: any) {
+    logger.error('Internal request authentication failed:', error);
+    throw new ToolError('Unauthorized', 401, 'Internal request authentication failed');
+  }
 }
 
 /**
  * Authenticate a request for regular functions (with organization validation)
  *
  * @param request - The incoming request
- * @returns true if authentication and authorization succeed
+ * @throws {ToolError} If authentication or authorization fails
  */
-export async function authenticateRegularRequest(request: any): Promise<boolean> {
-  return await authenticateRequest(request, true);
+export async function authenticateRegularRequest(request: any): Promise<void> {
+  await authenticateRequest(request, true);
 }
 
 /**
  * Authenticate a request for global functions (without organization validation)
  *
  * @param request - The incoming request
- * @returns true if authentication succeeds
+ * @throws {ToolError} If authentication fails
  */
-export async function authenticateGlobalRequest(request: any): Promise<boolean> {
-  return await authenticateRequest(request, false);
+export async function authenticateGlobalRequest(request: any): Promise<void> {
+  await authenticateRequest(request, false);
 }

package/src/function/GlobalToolFunction.test.ts

@@ -22,12 +22,22 @@ jest.mock('@zaiusinc/app-sdk', () => ({
     }
   },
   Request: jest.fn().mockImplementation(() => ({})),
-  Response: jest.fn().mockImplementation((status, data) => ({
+  Response: jest.fn().mockImplementation((status, data, headers) => ({
     status,
     data,
     bodyJSON: data,
-    bodyAsU8Array: new Uint8Array()
+    bodyAsU8Array: new Uint8Array(),
+    headers
   })),
+  Headers: jest.fn().mockImplementation((entries) => {
+    const headers = new Map();
+    if (entries) {
+      for (const [key, value] of entries) {
+        headers.set(key, value);
+      }
+    }
+    return headers;
+  }),
   amendLogContext: jest.fn(),
   getAppContext: jest.fn(),
   logger: {
@@ -36,20 +46,23 @@ jest.mock('@zaiusinc/app-sdk', () => ({
     warn: jest.fn(),
     debug: jest.fn(),
   },
+  LogVisibility: {
+    Zaius: 'zaius'
+  },
 }));
 
 // Create a concrete implementation for testing
 class TestGlobalToolFunction extends GlobalToolFunction {
-  private mockReady: jest.MockedFunction<() => Promise<boolean>>;
+  private mockReady: jest.MockedFunction<() => Promise<{ ready: boolean; reason?: string }>>;
 
   public constructor(request?: any) {
     super(request || {});
     (this as any).request = request;
-    this.mockReady = jest.fn().mockResolvedValue(true);
+    this.mockReady = jest.fn().mockResolvedValue({ ready: true });
   }
 
   // Override the ready method with mock implementation for testing
-  protected ready(): Promise<boolean> {
+  protected ready(): Promise<{ ready: boolean; reason?: string }> {
     return this.mockReady();
   }
 
@@ -180,7 +193,7 @@ describe('GlobalToolFunction', () => {
       // Arrange
       const readyRequest = createReadyRequestWithAuth();
       globalToolFunction = new TestGlobalToolFunction(readyRequest);
-      globalToolFunction.getMockReady().mockResolvedValue(true);
+      globalToolFunction.getMockReady().mockResolvedValue({ ready: true });
 
       // Act
       const result = await globalToolFunction.perform();
@@ -195,7 +208,7 @@ describe('GlobalToolFunction', () => {
       // Arrange
       const readyRequest = createReadyRequestWithAuth();
       globalToolFunction = new TestGlobalToolFunction(readyRequest);
-      globalToolFunction.getMockReady().mockResolvedValue(false);
+      globalToolFunction.getMockReady().mockResolvedValue({ ready: false });
 
       // Act
       const result = await globalToolFunction.perform();
@@ -206,6 +219,21 @@ describe('GlobalToolFunction', () => {
       expect(mockProcessRequest).not.toHaveBeenCalled(); // Should not call service
     });
 
+    it('should return ready: false with reason when ready method returns false with reason', async () => {
+      // Arrange
+      const readyRequest = createReadyRequestWithAuth();
+      globalToolFunction = new TestGlobalToolFunction(readyRequest);
+      globalToolFunction.getMockReady().mockResolvedValue({ ready: false, reason: 'Missing API credentials' });
+
+      // Act
+      const result = await globalToolFunction.perform();
+
+      // Assert
+      expect(globalToolFunction.getMockReady()).toHaveBeenCalledTimes(1);
+      expect(result).toEqual(new Response(200, { ready: false, reason: 'Missing API credentials' }));
+      expect(mockProcessRequest).not.toHaveBeenCalled(); // Should not call service
+    });
+
     it('should handle ready method throwing an error', async () => {
       // Arrange
       const readyRequest = createReadyRequestWithAuth();
@@ -251,7 +279,7 @@ describe('GlobalToolFunction', () => {
         path: '/ready'
       };
       globalToolFunction = new TestGlobalToolFunction(readyRequestWithoutAuth);
-      globalToolFunction.getMockReady().mockResolvedValue(true);
+      globalToolFunction.getMockReady().mockResolvedValue({ ready: true });
 
       // Act
       const result = await globalToolFunction.perform();
@@ -344,7 +372,13 @@ describe('GlobalToolFunction', () => {
 
       const result = await globalToolFunction.perform();
 
-      expect(result).toEqual(new Response(403, { error: 'Forbidden' }));
+      expect(result.status).toBe(403);
+      expect(result.bodyJSON).toEqual({
+        title: 'Forbidden',
+        status: 403,
+        detail: 'Invalid OptiID access token',
+        instance: '/test'
+      });
       expect(mockGetTokenVerifier).toHaveBeenCalled();
       expect(mockTokenVerifier.verify).toHaveBeenCalledWith('valid-access-token');
       expect(mockProcessRequest).not.toHaveBeenCalled();
@@ -370,7 +404,13 @@ describe('GlobalToolFunction', () => {
 
       const result = await globalToolFunctionWithoutToken.perform();
 
-      expect(result).toEqual(new Response(403, { error: 'Forbidden' }));
+      expect(result.status).toBe(403);
+      expect(result.bodyJSON).toEqual({
+        title: 'Forbidden',
+        status: 403,
+        detail: 'OptiID access token is required',
+        instance: '/test'
+      });
       expect(mockGetTokenVerifier).not.toHaveBeenCalled();
       expect(mockProcessRequest).not.toHaveBeenCalled();
     });
@@ -392,7 +432,13 @@ describe('GlobalToolFunction', () => {
 
       const result = await globalToolFunctionWithDifferentProvider.perform();
 
-      expect(result).toEqual(new Response(403, { error: 'Forbidden' }));
+      expect(result.status).toBe(403);
+      expect(result.bodyJSON).toEqual({
+        title: 'Forbidden',
+        status: 403,
+        detail: 'Only OptiID authentication provider is supported',
+        instance: '/test'
+      });
       expect(mockGetTokenVerifier).not.toHaveBeenCalled();
       expect(mockProcessRequest).not.toHaveBeenCalled();
     });
@@ -411,7 +457,13 @@ describe('GlobalToolFunction', () => {
 
       const result = await globalToolFunctionWithoutAuth.perform();
 
-      expect(result).toEqual(new Response(403, { error: 'Forbidden' }));
+      expect(result.status).toBe(403);
+      expect(result.bodyJSON).toEqual({
+        title: 'Forbidden',
+        status: 403,
+        detail: 'Authentication data is required',
+        instance: '/test'
+      });
       expect(mockGetTokenVerifier).not.toHaveBeenCalled();
       expect(mockProcessRequest).not.toHaveBeenCalled();
     });
@@ -422,7 +474,13 @@ describe('GlobalToolFunction', () => {
 
       const result = await globalToolFunction.perform();
 
-      expect(result).toEqual(new Response(403, { error: 'Forbidden' }));
+      expect(result.status).toBe(403);
+      expect(result.bodyJSON).toEqual({
+        title: 'Forbidden',
+        status: 403,
+        detail: 'Token verification failed',
+        instance: '/test'
+      });
       expect(mockGetTokenVerifier).toHaveBeenCalled();
       expect(mockProcessRequest).not.toHaveBeenCalled();
     });
@@ -433,7 +491,13 @@ describe('GlobalToolFunction', () => {
 
       const result = await globalToolFunction.perform();
 
-      expect(result).toEqual(new Response(403, { error: 'Forbidden' }));
+      expect(result.status).toBe(403);
+      expect(result.bodyJSON).toEqual({
+        title: 'Forbidden',
+        status: 403,
+        detail: 'Token verification failed',
+        instance: '/test'
+      });
       expect(mockGetTokenVerifier).toHaveBeenCalled();
       expect(mockTokenVerifier.verify).toHaveBeenCalledWith('valid-access-token');
       expect(mockProcessRequest).not.toHaveBeenCalled();

package/src/function/GlobalToolFunction.ts

@@ -1,6 +1,9 @@
-import { GlobalFunction, Response, amendLogContext } from '@zaiusinc/app-sdk';
+import { GlobalFunction, Response, Headers, amendLogContext } from '@zaiusinc/app-sdk';
 import { authenticateGlobalRequest, extractAuthData } from '../auth/AuthUtils';
 import { toolsService } from '../service/Service';
+import { ToolLogger } from '../logging/ToolLogger';
+import { ToolError } from '../types/ToolError';
+import { ReadyResponse } from '../types/Models';
 
 /**
  * Abstract base class for global tool-based function execution
@@ -12,10 +15,10 @@ export abstract class GlobalToolFunction extends GlobalFunction {
    * Override this method to implement any required credentials and/or other configuration
    * exist and are valid. Reasonable caching should be utilized to prevent excessive requests to external resources.
    * @async
-   * @returns true if the opal function is ready to use
+   * @returns ReadyResponse containing ready status and optional reason when not ready
    */
-  protected ready(): Promise<boolean> {
-    return Promise.resolve(true);
+  protected ready(): Promise<ReadyResponse | boolean> {
+    return Promise.resolve({ ready: true });
   }
 
   /**
@@ -24,6 +27,8 @@ export abstract class GlobalToolFunction extends GlobalFunction {
    * @returns Response as the HTTP response
    */
   public async perform(): Promise<Response> {
+    const startTime = Date.now();
+
     // Extract customer_id from auth data for global context attribution
     const authInfo = extractAuthData(this.request);
     const customerId = authInfo?.authData?.credentials?.customer_id;
@@ -33,13 +38,43 @@ export abstract class GlobalToolFunction extends GlobalFunction {
       customerId: customerId || ''
     });
 
-    if (!(await this.authorizeRequest())) {
-      return new Response(403, { error: 'Forbidden' });
+    ToolLogger.logRequest(this.request);
+
+    const response = await this.handleRequest();
+    ToolLogger.logResponse(this.request, response, Date.now() - startTime);
+    return response;
+  }
+
+  private async handleRequest(): Promise<Response> {
+    try {
+      await this.authorizeRequest();
+    } catch (error) {
+      if (error instanceof ToolError) {
+        return new Response(
+          error.status,
+          error.toProblemDetails(this.request.path),
+          new Headers([['content-type', 'application/problem+json']])
+        );
+      }
+      // Fallback for unexpected errors
+      return new Response(
+        500,
+        {
+          title: 'Internal Server Error',
+          status: 500,
+          detail: 'An unexpected error occurred during authentication',
+          instance: this.request.path
+        },
+        new Headers([['content-type', 'application/problem+json']])
+      );
     }
 
     if (this.request.path === '/ready') {
-      const isReady = await this.ready();
-      return new Response(200, { ready: isReady });
+      const readyResult = await this.ready();
+      const readyResponse = typeof readyResult === 'boolean'
+        ? { ready: readyResult }
+        : readyResult;
+      return new Response(200, readyResponse);
     }
 
     return toolsService.processRequest(this.request, this);
@@ -48,9 +83,9 @@ export abstract class GlobalToolFunction extends GlobalFunction {
   /**
    * Authenticate the incoming request by validating only the OptiID token
    *
-   * @returns true if authentication succeeds
+   * @throws {ToolError} If authentication fails
    */
-  private async authorizeRequest(): Promise<boolean> {
-    return await authenticateGlobalRequest(this.request);
+  private async authorizeRequest(): Promise<void> {
+    await authenticateGlobalRequest(this.request);
   }
 }