@optimizely-opal/opal-tool-ocp-sdk 1.0.0-beta.2 → 1.0.0-beta.4

package/src/auth/AuthUtils.ts

@@ -1,23 +1,30 @@
 import { getAppContext, logger } 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,39 @@ 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;
-  }
-
-  const authInfo = extractAuthData(request);
-  if (!authInfo) {
-    logger.error('OptiID token is required but not provided');
-    return false;
+    return;
   }
 
-  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 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,6 +46,9 @@ jest.mock('@zaiusinc/app-sdk', () => ({
     warn: jest.fn(),
     debug: jest.fn(),
   },
+  LogVisibility: {
+    Zaius: 'zaius'
+  },
 }));
 
 // Create a concrete implementation for testing
@@ -344,7 +357,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 +389,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 +417,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 +442,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 +459,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 +476,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,8 @@
-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';
 
 /**
  * Abstract base class for global tool-based function execution
@@ -24,6 +26,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,8 +37,35 @@ 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') {
@@ -48,9 +79,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);
   }
 }

package/src/function/ToolFunction.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,6 +46,9 @@ jest.mock('@zaiusinc/app-sdk', () => ({
     warn: jest.fn(),
     debug: jest.fn(),
   },
+  LogVisibility: {
+    Zaius: 'zaius'
+  },
 }));
 
 // Create a concrete implementation for testing
@@ -248,7 +261,13 @@ describe('ToolFunction', () => {
 
       const result = await toolFunction.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();
@@ -274,7 +293,13 @@ describe('ToolFunction', () => {
 
       const result = await toolFunctionWithDifferentOrgId.perform();
 
-      expect(result).toEqual(new Response(403, { error: 'Forbidden' }));
+      expect(result.status).toBe(403);
+      expect(result.bodyJSON).toEqual({
+        title: 'Forbidden',
+        status: 403,
+        detail: 'Organization ID does not match',
+        instance: '/test'
+      });
       expect(mockGetAppContext).toHaveBeenCalled();
       expect(mockProcessRequest).not.toHaveBeenCalled();
     });
@@ -299,7 +324,13 @@ describe('ToolFunction', () => {
 
       const result = await toolFunctionWithoutToken.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();
     });
@@ -324,7 +355,13 @@ describe('ToolFunction', () => {
 
       const result = await toolFunctionWithoutCustomerId.perform();
 
-      expect(result).toEqual(new Response(403, { error: 'Forbidden' }));
+      expect(result.status).toBe(403);
+      expect(result.bodyJSON).toEqual({
+        title: 'Forbidden',
+        status: 403,
+        detail: 'Organization ID is required',
+        instance: '/test'
+      });
       expect(mockGetTokenVerifier).not.toHaveBeenCalled();
       expect(mockProcessRequest).not.toHaveBeenCalled();
     });
@@ -343,7 +380,13 @@ describe('ToolFunction', () => {
 
       const result = await toolFunctionWithoutAuth.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();
     });
@@ -354,7 +397,13 @@ describe('ToolFunction', () => {
 
       const result = await toolFunction.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();
     });

package/src/function/ToolFunction.ts

@@ -1,6 +1,8 @@
-import { Function, Response, amendLogContext } from '@zaiusinc/app-sdk';
+import { Function, Response, Headers, amendLogContext } from '@zaiusinc/app-sdk';
 import { authenticateRegularRequest } from '../auth/AuthUtils';
 import { toolsService } from '../service/Service';
+import { ToolLogger } from '../logging/ToolLogger';
+import { ToolError } from '../types/ToolError';
 
 /**
  * Abstract base class for tool-based function execution
@@ -19,20 +21,56 @@ export abstract class ToolFunction extends Function {
   }
 
   /**
-   * Process the incoming request using the tools service
+   * Process the incoming request with logging
    *
    * @returns Response as the HTTP response
    */
   public async perform(): Promise<Response> {
+    const startTime = Date.now();
     amendLogContext({ opalThreadId: this.request.headers.get('x-opal-thread-id') || '' });
-    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;
+  }
+
+  /**
+   * Handle the core request processing logic
+   *
+   * @returns Response as the HTTP 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 });
     }
+
     // Pass 'this' as context so decorated methods can use the existing instance
     return toolsService.processRequest(this.request, this);
   }
@@ -40,9 +78,9 @@ export abstract class ToolFunction extends Function {
   /**
    * Authenticate the incoming request by validating the OptiID token and organization ID
    *
-   * @returns true if authentication succeeds
+   * @throws {ToolError} If authentication fails
    */
-  private async authorizeRequest(): Promise<boolean> {
-    return await authenticateRegularRequest(this.request);
+  private async authorizeRequest(): Promise<void> {
+    await authenticateRegularRequest(this.request);
   }
 }

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './function/ToolFunction';
 export * from './function/GlobalToolFunction';
 export * from './types/Models';
+export * from './types/ToolError';
 export * from './decorator/Decorator';
 export * from './auth/TokenVerifier';
 export { Tool, Interaction, InteractionResult } from './service/Service';