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

package/src/service/Service.test.ts

@@ -71,6 +71,11 @@ jest.mock('@zaiusinc/app-sdk', () => {
   };
 });
 
+// Mock the authenticateInternalRequest function
+jest.mock('../auth/AuthUtils', () => ({
+  authenticateInternalRequest: jest.fn().mockResolvedValue(undefined)
+}));
+
 // Get the mocked kvStore for use in tests
 const { storage } = jest.requireMock('@zaiusinc/app-sdk');
 const mockKvStore = storage.kvStore;
@@ -250,8 +255,7 @@ describe('ToolsService', () => {
           endpoint: '/second-tool',
           http_method: 'POST',
           auth_requirements: [
-            { provider: 'oauth2', scope_bundle: 'calendar', required: true },
-            { provider: 'OptiID', scope_bundle: 'default', required: true }
+            { provider: 'oauth2', scope_bundle: 'calendar', required: true }
           ]
         });
       });
@@ -408,95 +412,55 @@ describe('ToolsService', () => {
         );
       });
 
-      it('should return 500 error in RFC 9457 format when tool handler throws a regular error', async () => {
+      it('should throw error when tool handler throws a regular error', async () => {
         const errorMessage = 'Tool execution failed';
         jest.mocked(mockTool.handler).mockRejectedValueOnce(new Error(errorMessage));
 
         const mockRequest = createMockRequest();
-        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)
-        );
+        await expect(toolsService.processRequest(mockRequest, mockToolFunction))
+          .rejects.toThrow(errorMessage);
       });
 
-      it('should return 500 error with generic message when error has no message', async () => {
+      it('should throw when tool handler throws object without message', async () => {
         jest.mocked(mockTool.handler).mockRejectedValueOnce({});
 
         const mockRequest = createMockRequest();
-        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');
+        await expect(toolsService.processRequest(mockRequest, mockToolFunction))
+          .rejects.toEqual({});
       });
 
-      it('should return custom status code when tool handler throws ToolError', async () => {
+      it('should throw ToolError 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)
-        );
+        await expect(toolsService.processRequest(mockRequest, mockToolFunction))
+          .rejects.toThrow(toolError);
       });
 
-      it('should return ToolError without detail field when detail is not provided', async () => {
+      it('should throw ToolError without detail 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');
+        await expect(toolsService.processRequest(mockRequest, mockToolFunction))
+          .rejects.toThrow(toolError);
+        expect(toolError.status).toBe(400);
       });
 
-      it('should default to 500 when ToolError is created without status', async () => {
+      it('should throw ToolError with default 500 status when 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');
+        await expect(toolsService.processRequest(mockRequest, mockToolFunction))
+          .rejects.toThrow(toolError);
+        expect(toolError.status).toBe(500);
       });
     });
 
@@ -594,7 +558,7 @@ describe('ToolsService', () => {
         );
       });
 
-      it('should return 500 error in RFC 9457 format when interaction handler throws a regular error', async () => {
+      it('should throw error when interaction handler throws a regular error', async () => {
         const errorMessage = 'Interaction execution failed';
         jest.mocked(mockInteraction.handler).mockRejectedValueOnce(new Error(errorMessage));
 
@@ -603,23 +567,11 @@ describe('ToolsService', () => {
           bodyJSON: { data: { param1: 'test-value' } }
         });
 
-        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)
-        );
+        await expect(toolsService.processRequest(interactionRequest, mockToolFunction))
+          .rejects.toThrow(errorMessage);
       });
 
-      it('should return custom status code when interaction handler throws ToolError', async () => {
+      it('should throw ToolError when interaction handler throws ToolError', async () => {
         const toolError = new ToolError('Webhook validation failed', 400, 'Invalid signature');
         jest.mocked(mockInteraction.handler).mockRejectedValueOnce(toolError);
 
@@ -628,29 +580,26 @@ describe('ToolsService', () => {
           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)
-        );
+        await expect(toolsService.processRequest(interactionRequest, mockToolFunction))
+          .rejects.toThrow(toolError);
       });
     });
 
     describe('error cases', () => {
-      it('should return 404 when no matching tool or interaction is found', async () => {
+      it('should throw ToolError with 404 when no matching tool or interaction is found', async () => {
         const unknownRequest = createMockRequest({ path: '/unknown-endpoint' });
-        const response = await toolsService.processRequest(unknownRequest, mockToolFunction);
 
-        expect(response.status).toBe(404);
+        await expect(toolsService.processRequest(unknownRequest, mockToolFunction))
+          .rejects.toThrow(ToolError);
+
+        try {
+          await toolsService.processRequest(unknownRequest, mockToolFunction);
+        } catch (error) {
+          expect(error).toBeInstanceOf(ToolError);
+          expect((error as ToolError).status).toBe(404);
+          // ToolError prepends status to message
+          expect((error as ToolError).message).toContain('Function not found');
+        }
       });
 
       it('should handle tool with OptiID auth requirements', async () => {
@@ -840,7 +789,7 @@ describe('ToolsService', () => {
         jest.clearAllMocks();
       });
 
-      it('should validate parameters and return 400 for invalid types', async () => {
+      it('should throw ToolError with 400 for invalid parameter types', async () => {
         // Register a tool with specific parameter types
         const toolWithTypedParams = {
           name: 'typed_tool',
@@ -874,26 +823,25 @@ describe('ToolsService', () => {
           }
         });
 
-        const response = await toolsService.processRequest(invalidRequest, mockToolFunction);
-
-        expect(response.status).toBe(400);
-
-        // Expect RFC 9457 Problem Details format
-        expect(response.bodyJSON).toHaveProperty('title', 'One or more validation errors occurred.');
-        expect(response.bodyJSON).toHaveProperty('status', 400);
-        expect(response.bodyJSON).toHaveProperty('detail', 'See \'errors\' field for details.');
-        expect(response.bodyJSON).toHaveProperty('instance', '/typed-tool');
-        expect(response.bodyJSON).toHaveProperty('errors');
-        expect(response.bodyJSON.errors).toHaveLength(3);
-
-        // Check error structure - field and message
-        const errors = response.bodyJSON.errors;
-        expect(errors[0]).toHaveProperty('field', 'name');
-        expect(errors[0]).toHaveProperty('message', "Parameter 'name' must be a string, but received number");
-
-        // Check that the content type is set to application/problem+json for RFC 9457 compliance
-        expect(response.headers).toBeDefined();
-        expect(response.headers.get('content-type')).toBe('application/problem+json');
+        await expect(toolsService.processRequest(invalidRequest, mockToolFunction))
+          .rejects.toThrow(ToolError);
+
+        try {
+          await toolsService.processRequest(invalidRequest, mockToolFunction);
+        } catch (error) {
+          expect(error).toBeInstanceOf(ToolError);
+          const toolError = error as ToolError;
+          expect(toolError.status).toBe(400);
+          // The ToolError has title property, message includes more details
+          expect(toolError.toProblemDetails('/typed-tool')).toMatchObject({
+            title: 'One or more validation errors occurred.',
+            status: 400
+          });
+          expect(toolError.errors).toHaveLength(3);
+          expect(toolError.errors![0]).toHaveProperty('field', 'name');
+          expect(toolError.errors![0].message)
+            .toBe("Parameter 'name' must be a string, but received number");
+        }
 
         // Verify the handler was not called
         expect(toolWithTypedParams.handler).not.toHaveBeenCalled();

package/src/service/Service.ts

@@ -2,13 +2,13 @@
 import { AuthRequirement, IslandResponse, Parameter } from '../types/Models';
 import { ToolError } from '../types/ToolError';
 import * as App from '@zaiusinc/app-sdk';
-import { logger, Headers, getAppContext } from '@zaiusinc/app-sdk';
+import { logger, getAppContext } from '@zaiusinc/app-sdk';
 import { ToolFunction } from '../function/ToolFunction';
 import { GlobalToolFunction } from '../function/GlobalToolFunction';
 import { ParameterValidator } from '../validation/ParameterValidator';
 
 /**
- * Default OptiID authentication requirement that will be enforced for all tools
+ * Default OptiID authentication requirement added when tool doesn't specify any auth
  */
 const DEFAULT_OPTIID_AUTH = new AuthRequirement('OptiID', 'default', true);
 
@@ -219,50 +219,35 @@ export class ToolsService {
   }
 
   /**
-   * Enforce OptiID authentication for tools by ensuring OptiID auth requirement is present
+   * Apply default auth requirements if none are specified
    * @param authRequirements Original authentication requirements
-   * @returns Enforced authentication requirements with OptiID
+   * @returns Auth requirements with default OptiID if none specified, otherwise unchanged
    */
-  private enforceOptiIdAuth(authRequirements?: AuthRequirement[]): AuthRequirement[] {
-    const hasOptiIdProvider = authRequirements
-      && authRequirements.some((auth) => auth.provider.toLowerCase() === 'optiid');
-
-    if (hasOptiIdProvider) {
-      return authRequirements;
+  private withDefaultAuthRequirements(authRequirements?: AuthRequirement[]): AuthRequirement[] {
+    // Only add default OptiID if no auth requirements are specified
+    if (!authRequirements || authRequirements.length === 0) {
+      return [DEFAULT_OPTIID_AUTH];
     }
 
-    return [...(authRequirements || []), DEFAULT_OPTIID_AUTH];
+    // Respect developer's choice - return as-is
+    return authRequirements;
   }
 
   /**
-   * Format an error as RFC 9457 Problem Details response
-   * @param error The error to format
-   * @param instance URI reference identifying the specific occurrence
-   * @returns RFC 9457 compliant Response
+   * Check if an endpoint requires OptiID authentication
+   * Tools: Check auth requirements for OptiID provider
+   * Interactions: Always require OptiID
+   * @param endpoint The endpoint path to check
+   * @returns true if the endpoint requires OptiID auth
    */
-  private formatErrorResponse(error: any, instance: string): App.Response {
-    let status = 500;
-    let problemDetails: Record<string, unknown>;
-
-    if (error instanceof ToolError) {
-      // Use ToolError's status and format
-      status = error.status;
-      problemDetails = error.toProblemDetails(instance);
-    } else {
-      // Convert regular errors to RFC 9457 format with 500 status
-      problemDetails = {
-        title: 'Internal Server Error',
-        status: 500,
-        detail: error.message || 'An unexpected error occurred',
-        instance
-      };
+  public requiresOptiIdAuth(endpoint: string): boolean {
+    const func = this.functions.get(endpoint);
+    if (func) {
+      return func.authRequirements.some((auth) => auth.provider.toLowerCase() === 'optiid');
     }
-
-    return new App.Response(
-      status,
-      problemDetails,
-      new Headers([['content-type', 'application/problem+json']])
-    );
+    // Interactions always require OptiID
+    const interaction = this.interactions.get(endpoint);
+    return !!interaction;
   }
 
   /**
@@ -272,7 +257,7 @@ export class ToolsService {
    * @param handler Function implementing the tool
    * @param parameters List of parameters for the tool
    * @param endpoint API endpoint for the tool
-   * @param authRequirements Authentication requirements (optional)
+   * @param authRequirements Authentication requirements (optional - defaults to OptiID if not specified)
    */
   public registerTool<TAuthData>(
     name: string,
@@ -286,15 +271,14 @@ export class ToolsService {
     endpoint: string,
     authRequirements?: AuthRequirement[]
   ): void {
-    // Enforce OptiID authentication for all tools
-    const enforcedAuthRequirements = this.enforceOptiIdAuth(authRequirements);
+    const resolvedAuthRequirements = this.withDefaultAuthRequirements(authRequirements);
     const func = new Tool<TAuthData>(
       name,
       description,
       parameters,
       endpoint,
       handler,
-      enforcedAuthRequirements
+      resolvedAuthRequirements
     );
     this.functions.set(endpoint, func);
   }
@@ -327,61 +311,43 @@ export class ToolsService {
       return await this.handleDiscoveryRequest(functionContext);
     }
 
-    // Handle overrides endpoint
+    // Handle overrides endpoint (auth handled by function layer)
     if (req.path === '/overrides') {
       return await this.handleOverridesRequest(req, functionContext);
     }
 
     // Handle regular tool functions
+    // Auth is already validated by the function layer
     const func = this.functions.get(req.path);
     if (func) {
-      try {
-        let params;
-        if (req.bodyJSON && req.bodyJSON.parameters) {
-          params = req.bodyJSON.parameters;
-        } else {
-          params = req.bodyJSON;
-        }
-
-        // Validate parameters before calling the handler (only if tool has parameter definitions)
-        // ParameterValidator.validate() throws ToolError if validation fails
-        if (func.parameters && func.parameters.length > 0) {
-          ParameterValidator.validate(params, func.parameters, func.endpoint);
-        }
+      const params = req.bodyJSON?.parameters ?? req.bodyJSON;
 
-        // Extract auth data from body JSON
-        const authData = req.bodyJSON ? req.bodyJSON.auth : undefined;
-        const result = await func.handler(functionContext, params, authData);
-        return new App.Response(200, result);
-      } catch (error: any) {
-        logger.error(`Error in function ${func.name}:`, error);
-        return this.formatErrorResponse(error, func.endpoint);
+      // Validate parameters before calling the handler (only if tool has parameter definitions)
+      // ParameterValidator.validate() throws ToolError if validation fails
+      if (func.parameters && func.parameters.length > 0) {
+        ParameterValidator.validate(params, func.parameters, func.endpoint);
       }
+
+      // Extract auth data from body JSON
+      const authData = req.bodyJSON?.auth;
+      const result = await func.handler(functionContext, params, authData);
+      return new App.Response(200, result);
     }
 
     // Handle interactions
+    // Auth is already validated by the function layer
     const interaction = this.interactions.get(req.path);
     if (interaction) {
-      try {
-        let params;
-        if (req.bodyJSON && req.bodyJSON.data) {
-          params = req.bodyJSON.data;
-        } else {
-          params = req.bodyJSON;
-        }
+      const params = req.bodyJSON?.data ?? req.bodyJSON;
 
-        // Extract auth data from body JSON
-        const authData = req.bodyJSON ? req.bodyJSON.auth : undefined;
+      // Extract auth data from body JSON
+      const authData = req.bodyJSON?.auth;
 
-        const result = await interaction.handler(functionContext, params, authData);
-        return new App.Response(200, result);
-      } catch (error: any) {
-        logger.error(`Error in function ${interaction.name}:`, error);
-        return this.formatErrorResponse(error, interaction.endpoint);
-
-      }
+      const result = await interaction.handler(functionContext, params, authData);
+      return new App.Response(200, result);
     }
-    return new App.Response(404, 'Function not found');
+
+    throw new ToolError('Function not found', 404);
   }
 
   /**

package/src/utils/ErrorFormatter.ts

@@ -0,0 +1,31 @@
+import { Response, Headers } from '@zaiusinc/app-sdk';
+import { ToolError } from '../types/ToolError';
+
+/**
+ * Format an error as RFC 9457 Problem Details response
+ * @param error The error to format (ToolError or generic Error)
+ * @param instance URI reference identifying the specific occurrence (typically request path)
+ * @returns RFC 9457 compliant Response
+ */
+export function formatErrorResponse(error: unknown, instance: string): Response {
+  if (error instanceof ToolError) {
+    return new Response(
+      error.status,
+      error.toProblemDetails(instance),
+      new Headers([['content-type', 'application/problem+json']])
+    );
+  }
+
+  // Fallback for generic errors
+  const message = error instanceof Error ? error.message : 'An unexpected error occurred';
+  return new Response(
+    500,
+    {
+      title: 'Internal Server Error',
+      status: 500,
+      detail: message,
+      instance
+    },
+    new Headers([['content-type', 'application/problem+json']])
+  );
+}