@optimizely-opal/opal-tool-ocp-sdk 1.0.0-beta.3 → 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: {
@@ -347,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();
@@ -373,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();
     });
@@ -395,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();
     });
@@ -414,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();
     });
@@ -425,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();
     });
@@ -436,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,7 +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
@@ -44,8 +45,27 @@ export abstract class GlobalToolFunction extends GlobalFunction {
   }
 
   private async handleRequest(): Promise<Response> {
-    if (!(await this.authorizeRequest())) {
-      return new Response(403, { error: 'Forbidden' });
+    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') {
@@ -59,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: {
@@ -251,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();
@@ -277,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();
     });
@@ -302,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();
     });
@@ -327,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();
     });
@@ -346,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();
     });
@@ -357,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,7 +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
@@ -42,8 +43,27 @@ export abstract class ToolFunction extends Function {
    * @returns Response as the HTTP response
    */
   private async handleRequest(): Promise<Response> {
-    if (!(await this.authorizeRequest())) {
-      return new Response(403, { error: 'Forbidden' });
+    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') {
@@ -58,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';

package/src/service/Service.test.ts

@@ -1,5 +1,6 @@
 import { toolsService, Tool, Interaction } from './Service';
 import { Parameter, ParameterType, AuthRequirement, OptiIdAuthDataCredentials, OptiIdAuthData } from '../types/Models';
+import { ToolError } from '../types/ToolError';
 import { ToolFunction } from '../function/ToolFunction';
 import { logger } from '@zaiusinc/app-sdk';
 
@@ -370,7 +371,7 @@ describe('ToolsService', () => {
         );
       });
 
-      it('should return 500 error when tool handler throws an error', async () => {
+      it('should return 500 error in RFC 9457 format when tool handler throws a regular error', async () => {
         const errorMessage = 'Tool execution failed';
         jest.mocked(mockTool.handler).mockRejectedValueOnce(new Error(errorMessage));
 
@@ -378,6 +379,13 @@ describe('ToolsService', () => {
         const response = await toolsService.processRequest(mockRequest, mockToolFunction);
 
         expect(response.status).toBe(500);
+        expect(response.bodyJSON).toEqual({
+          title: 'Internal Server Error',
+          status: 500,
+          detail: errorMessage,
+          instance: mockTool.endpoint
+        });
+        expect(response.headers.get('content-type')).toBe('application/problem+json');
         expect(logger.error).toHaveBeenCalledWith(
           `Error in function ${mockTool.name}:`,
           expect.any(Error)
@@ -391,6 +399,67 @@ describe('ToolsService', () => {
         const response = await toolsService.processRequest(mockRequest, mockToolFunction);
 
         expect(response.status).toBe(500);
+        expect(response.bodyJSON).toEqual({
+          title: 'Internal Server Error',
+          status: 500,
+          detail: 'An unexpected error occurred',
+          instance: mockTool.endpoint
+        });
+        expect(response.headers.get('content-type')).toBe('application/problem+json');
+      });
+
+      it('should return custom status code when tool handler throws ToolError', async () => {
+        const toolError = new ToolError('Resource not found', 404, 'The requested task does not exist');
+        jest.mocked(mockTool.handler).mockRejectedValueOnce(toolError);
+
+        const mockRequest = createMockRequest();
+        const response = await toolsService.processRequest(mockRequest, mockToolFunction);
+
+        expect(response.status).toBe(404);
+        expect(response.bodyJSON).toEqual({
+          title: 'Resource not found',
+          status: 404,
+          detail: 'The requested task does not exist',
+          instance: mockTool.endpoint
+        });
+        expect(response.headers.get('content-type')).toBe('application/problem+json');
+        expect(logger.error).toHaveBeenCalledWith(
+          `Error in function ${mockTool.name}:`,
+          expect.any(ToolError)
+        );
+      });
+
+      it('should return ToolError without detail field when detail is not provided', async () => {
+        const toolError = new ToolError('Bad request', 400);
+        jest.mocked(mockTool.handler).mockRejectedValueOnce(toolError);
+
+        const mockRequest = createMockRequest();
+        const response = await toolsService.processRequest(mockRequest, mockToolFunction);
+
+        expect(response.status).toBe(400);
+        expect(response.bodyJSON).toEqual({
+          title: 'Bad request',
+          status: 400,
+          instance: mockTool.endpoint
+        });
+        expect(response.bodyJSON).not.toHaveProperty('detail');
+        expect(response.headers.get('content-type')).toBe('application/problem+json');
+      });
+
+      it('should default to 500 when ToolError is created without status', async () => {
+        const toolError = new ToolError('Database error');
+        jest.mocked(mockTool.handler).mockRejectedValueOnce(toolError);
+
+        const mockRequest = createMockRequest();
+        const response = await toolsService.processRequest(mockRequest, mockToolFunction);
+
+        expect(response.status).toBe(500);
+        expect(response.bodyJSON).toEqual({
+          title: 'Database error',
+          status: 500,
+          instance: mockTool.endpoint
+        });
+        expect(response.headers.get('content-type')).toBe('application/problem+json');
       });
     });
 
@@ -488,7 +557,7 @@ describe('ToolsService', () => {
         );
       });
 
-      it('should return 500 error when interaction handler throws an error', async () => {
+      it('should return 500 error in RFC 9457 format when interaction handler throws a regular error', async () => {
         const errorMessage = 'Interaction execution failed';
         jest.mocked(mockInteraction.handler).mockRejectedValueOnce(new Error(errorMessage));
 
@@ -500,11 +569,43 @@ describe('ToolsService', () => {
         const response = await toolsService.processRequest(interactionRequest, mockToolFunction);
 
         expect(response.status).toBe(500);
+        expect(response.bodyJSON).toEqual({
+          title: 'Internal Server Error',
+          status: 500,
+          detail: errorMessage,
+          instance: mockInteraction.endpoint
+        });
+        expect(response.headers.get('content-type')).toBe('application/problem+json');
         expect(logger.error).toHaveBeenCalledWith(
           `Error in function ${mockInteraction.name}:`,
           expect.any(Error)
         );
       });
+
+      it('should return custom status code when interaction handler throws ToolError', async () => {
+        const toolError = new ToolError('Webhook validation failed', 400, 'Invalid signature');
+        jest.mocked(mockInteraction.handler).mockRejectedValueOnce(toolError);
+
+        const interactionRequest = createMockRequest({
+          path: '/test-interaction',
+          bodyJSON: { data: { param1: 'test-value' } }
+        });
+
+        const response = await toolsService.processRequest(interactionRequest, mockToolFunction);
+
+        expect(response.status).toBe(400);
+        expect(response.bodyJSON).toEqual({
+          title: 'Webhook validation failed',
+          status: 400,
+          detail: 'Invalid signature',
+          instance: mockInteraction.endpoint
+        });
+        expect(response.headers.get('content-type')).toBe('application/problem+json');
+        expect(logger.error).toHaveBeenCalledWith(
+          `Error in function ${mockInteraction.name}:`,
+          expect.any(ToolError)
+        );
+      });
     });
 
     describe('error cases', () => {