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

package/src/function/ToolFunction.test.ts

@@ -2,11 +2,14 @@ import { ToolFunction } from './ToolFunction';
 import { toolsService } from '../service/Service';
 import { Response, getAppContext } from '@zaiusinc/app-sdk';
 import { getTokenVerifier } from '../auth/TokenVerifier';
+import { ToolError } from '../types/ToolError';
+import { authenticateRegularRequest } from '../auth/AuthUtils';
 
 // Mock the dependencies
 jest.mock('../service/Service', () => ({
   toolsService: {
     processRequest: jest.fn(),
+    requiresOptiIdAuth: jest.fn(),
   },
 }));
 
@@ -14,6 +17,11 @@ jest.mock('../auth/TokenVerifier', () => ({
   getTokenVerifier: jest.fn(),
 }));
 
+jest.mock('../auth/AuthUtils', () => ({
+  authenticateRegularRequest: jest.fn().mockResolvedValue(undefined),
+  authenticateInternalRequest: jest.fn().mockResolvedValue(undefined),
+}));
+
 jest.mock('@zaiusinc/app-sdk', () => ({
   Function: class {
     protected request: any;
@@ -257,172 +265,16 @@ describe('ToolFunction', () => {
   });
 
   describe('perform', () => {
-    it('should execute successfully with valid token and matching organization', async () => {
-      // Setup mock token verifier to return true for valid token
-      mockTokenVerifier.verify.mockResolvedValue(true);
+    it('should call processRequest and return its result', async () => {
+      // Setup mock to return a response
       mockProcessRequest.mockResolvedValue(mockResponse);
 
       const result = await toolFunction.perform();
 
       expect(result).toBe(mockResponse);
-      expect(mockGetTokenVerifier).toHaveBeenCalled();
-      expect(mockTokenVerifier.verify).toHaveBeenCalledWith('valid-access-token');
-      expect(mockGetAppContext).toHaveBeenCalled();
+      // processRequest is called with request and context (no authValidator)
       expect(mockProcessRequest).toHaveBeenCalledWith(mockRequest, toolFunction);
     });
-
-    it('should return 403 response with invalid token', async () => {
-      // Setup mock token verifier to return false
-      mockTokenVerifier.verify.mockResolvedValue(false);
-
-      const result = await toolFunction.perform();
-
-      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();
-    });
-
-    it('should return 403 response when organization ID does not match', async () => {
-      // Update mock request with different customer_id
-      const requestWithDifferentOrgId = {
-        ...mockRequest,
-        bodyJSON: {
-          ...mockRequest.bodyJSON,
-          auth: {
-            ...mockRequest.bodyJSON.auth,
-            credentials: {
-              ...mockRequest.bodyJSON.auth.credentials,
-              customer_id: 'different-org-123'
-            }
-          }
-        }
-      };
-
-      const toolFunctionWithDifferentOrgId = new TestToolFunction(requestWithDifferentOrgId);
-
-      const result = await toolFunctionWithDifferentOrgId.perform();
-
-      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();
-    });
-
-    it('should return 403 response when access token is missing', async () => {
-      // Create request without access token
-      const requestWithoutToken = {
-        ...mockRequest,
-        bodyJSON: {
-          ...mockRequest.bodyJSON,
-          auth: {
-            ...mockRequest.bodyJSON.auth,
-            credentials: {
-              ...mockRequest.bodyJSON.auth.credentials,
-              access_token: undefined
-            }
-          }
-        }
-      };
-
-      const toolFunctionWithoutToken = new TestToolFunction(requestWithoutToken);
-
-      const result = await toolFunctionWithoutToken.perform();
-
-      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();
-    });
-
-    it('should return 403 response when organisation id is missing', async () => {
-      // Create request without customer_id
-      const requestWithoutCustomerId = {
-        ...mockRequest,
-        bodyJSON: {
-          ...mockRequest.bodyJSON,
-          auth: {
-            ...mockRequest.bodyJSON.auth,
-            credentials: {
-              ...mockRequest.bodyJSON.auth.credentials,
-              customer_id: undefined
-            }
-          }
-        }
-      };
-
-      const toolFunctionWithoutCustomerId = new TestToolFunction(requestWithoutCustomerId);
-
-      const result = await toolFunctionWithoutCustomerId.perform();
-
-      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();
-    });
-
-    it('should return 403 response when auth structure is missing', async () => {
-      // Create request without auth structure
-      const requestWithoutAuth = {
-        ...mockRequest,
-        bodyJSON: {
-          parameters: mockRequest.bodyJSON.parameters,
-          environment: mockRequest.bodyJSON.environment
-        }
-      };
-
-      const toolFunctionWithoutAuth = new TestToolFunction(requestWithoutAuth);
-
-      const result = await toolFunctionWithoutAuth.perform();
-
-      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();
-    });
-
-    it('should return 403 response when token verifier initialization fails', async () => {
-      // Setup mock to fail during token verifier initialization
-      mockGetTokenVerifier.mockRejectedValue(new Error('Failed to initialize token verifier'));
-
-      const result = await toolFunction.perform();
-
-      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();
-    });
   });
 
   describe('inheritance', () => {
@@ -437,21 +289,18 @@ describe('ToolFunction', () => {
     });
   });
 
-  describe('internal request authentication', () => {
+  describe('system paths routing', () => {
     beforeEach(() => {
-      // Reset mocks before each test
       jest.clearAllMocks();
-      setupAuthMocks();
     });
 
-    it('should use internal authentication for /overrides endpoint', async () => {
+    it('should forward /overrides to processRequest directly', async () => {
       const overridesRequest = {
         path: '/overrides',
         method: 'DELETE',
         bodyJSON: {},
         headers: {
           get: jest.fn().mockImplementation((name: string) => {
-            if (name === 'Authorization' || name === 'authorization') return 'internal-token';
             if (name === 'x-opal-thread-id') return 'test-thread-id';
             return null;
           })
@@ -463,39 +312,14 @@ describe('ToolFunction', () => {
       const result = await toolFunctionOverrides.perform();
 
       expect(result).toBe(mockResponse);
+      // /overrides is forwarded directly to processRequest (auth handled there)
       expect(mockProcessRequest).toHaveBeenCalledWith(overridesRequest, toolFunctionOverrides);
     });
 
-    it('should throw ToolError when internal authentication fails for /overrides endpoint', async () => {
-      const overridesRequest = {
-        path: '/overrides',
-        method: 'DELETE',
-        bodyJSON: {},
-        headers: {
-          get: jest.fn().mockImplementation((name: string) => {
-            if (name === 'x-opal-thread-id') return 'test-thread-id';
-            return null; // No Authorization header
-          })
-        }
-      };
-
-      const toolFunctionOverrides = new TestToolFunction(overridesRequest);
-      const result = await toolFunctionOverrides.perform();
-
-      expect(result.status).toBe(401);
-      expect(result.bodyJSON).toEqual({
-        title: 'Unauthorized',
-        status: 401,
-        detail: 'Internal request authentication failed',
-        instance: '/overrides'
-      });
-      expect(mockProcessRequest).not.toHaveBeenCalled();
-    });
-
-    it('should use regular authentication for non-overrides endpoints', async () => {
-      const regularRequest = {
-        ...mockRequest,
-        path: '/regular-tool',
+    it('should forward /discovery to processRequest directly', async () => {
+      const discoveryRequest = {
+        path: '/discovery',
+        method: 'GET',
         headers: {
           get: jest.fn().mockImplementation((name: string) => {
             if (name === 'x-opal-thread-id') return 'test-thread-id';
@@ -505,136 +329,101 @@ describe('ToolFunction', () => {
       };
 
       mockProcessRequest.mockResolvedValue(mockResponse);
-      const toolFunctionRegular = new TestToolFunction(regularRequest);
-      const result = await toolFunctionRegular.perform();
+      const toolFunctionDiscovery = new TestToolFunction(discoveryRequest);
+      const result = await toolFunctionDiscovery.perform();
 
       expect(result).toBe(mockResponse);
-      expect(mockProcessRequest).toHaveBeenCalledWith(regularRequest, toolFunctionRegular);
+      expect(mockProcessRequest).toHaveBeenCalledWith(discoveryRequest, toolFunctionDiscovery);
     });
 
-    it('should handle internal authentication with valid Authorization header', async () => {
-      const overridesRequest = {
-        path: '/overrides',
-        method: 'PATCH',
-        bodyJSON: {
-          functions: [
-            {
-              name: 'test_tool',
-              description: 'Updated description'
-            }
-          ]
-        },
+    it('should forward tool endpoints to processRequest', async () => {
+      const toolRequest = {
+        ...mockRequest,
+        path: '/some-tool',
         headers: {
           get: jest.fn().mockImplementation((name: string) => {
-            if (name === 'Authorization') return 'valid-internal-token';
             if (name === 'x-opal-thread-id') return 'test-thread-id';
             return null;
           })
         }
       };
 
+      // Tool does not require OptiID auth
+      (toolsService.requiresOptiIdAuth as jest.Mock).mockReturnValue(false);
       mockProcessRequest.mockResolvedValue(mockResponse);
-      const toolFunctionOverrides = new TestToolFunction(overridesRequest);
-      const result = await toolFunctionOverrides.perform();
 
-      expect(result).toBe(mockResponse);
-      expect(mockProcessRequest).toHaveBeenCalledWith(overridesRequest, toolFunctionOverrides);
-    });
-
-    it('should handle internal authentication with lowercase authorization header', async () => {
-      const overridesRequest = {
-        path: '/overrides',
-        method: 'PATCH',
-        bodyJSON: {
-          functions: [
-            {
-              name: 'test_tool',
-              description: 'Updated description'
-            }
-          ]
-        },
-        headers: {
-          get: jest.fn().mockImplementation((name: string) => {
-            if (name === 'authorization') return 'valid-internal-token';
-            if (name === 'x-opal-thread-id') return 'test-thread-id';
-            return null;
-          })
-        }
-      };
-
-      mockProcessRequest.mockResolvedValue(mockResponse);
-      const toolFunctionOverrides = new TestToolFunction(overridesRequest);
-      const result = await toolFunctionOverrides.perform();
+      const toolFunctionTest = new TestToolFunction(toolRequest);
+      const result = await toolFunctionTest.perform();
 
       expect(result).toBe(mockResponse);
-      expect(mockProcessRequest).toHaveBeenCalledWith(overridesRequest, toolFunctionOverrides);
+      expect(mockProcessRequest).toHaveBeenCalledWith(toolRequest, toolFunctionTest);
     });
+  });
 
-    it('should fail internal authentication when token verification fails', async () => {
-      // Mock token verifier to return false for invalid token
-      mockTokenVerifier.verify.mockResolvedValue(false);
+  describe('error formatting', () => {
+    beforeEach(() => {
+      jest.clearAllMocks();
+    });
 
-      const overridesRequest = {
-        path: '/overrides',
-        method: 'DELETE',
-        bodyJSON: {},
+    it('should format ToolError as RFC 9457 response when processRequest throws ToolError', async () => {
+      const toolRequest = {
+        ...mockRequest,
+        path: '/some-tool',
         headers: {
           get: jest.fn().mockImplementation((name: string) => {
-            if (name === 'Authorization') return 'invalid-token';
             if (name === 'x-opal-thread-id') return 'test-thread-id';
             return null;
           })
         }
       };
 
-      const toolFunctionOverrides = new TestToolFunction(overridesRequest);
-      const result = await toolFunctionOverrides.perform();
+      const toolError = new ToolError('Resource not found', 404, 'The requested resource does not exist');
+      mockProcessRequest.mockRejectedValue(toolError);
+      (toolsService.requiresOptiIdAuth as jest.Mock).mockReturnValue(false);
 
-      expect(result.status).toBe(401);
+      const toolFunctionTest = new TestToolFunction(toolRequest);
+      const result = await toolFunctionTest.perform();
+
+      expect(result.status).toBe(404);
       expect(result.bodyJSON).toEqual({
-        title: 'Unauthorized',
-        status: 401,
-        detail: 'Internal request authentication failed',
-        instance: '/overrides'
+        title: 'Resource not found',
+        status: 404,
+        detail: 'The requested resource does not exist',
+        instance: '/some-tool'
       });
-      expect(mockProcessRequest).not.toHaveBeenCalled();
     });
 
-    it('should fail internal authentication when token verifier throws error', async () => {
-      // Mock token verifier to throw an error
-      mockTokenVerifier.verify.mockRejectedValue(new Error('Token service unavailable'));
-
-      const overridesRequest = {
-        path: '/overrides',
-        method: 'DELETE',
-        bodyJSON: {},
+    it('should format generic Error as 500 RFC 9457 response when processRequest throws', async () => {
+      const toolRequest = {
+        ...mockRequest,
+        path: '/some-tool',
         headers: {
           get: jest.fn().mockImplementation((name: string) => {
-            if (name === 'Authorization') return 'some-token';
             if (name === 'x-opal-thread-id') return 'test-thread-id';
             return null;
           })
         }
       };
 
-      const toolFunctionOverrides = new TestToolFunction(overridesRequest);
-      const result = await toolFunctionOverrides.perform();
+      mockProcessRequest.mockRejectedValue(new Error('Database connection failed'));
+      (toolsService.requiresOptiIdAuth as jest.Mock).mockReturnValue(false);
+
+      const toolFunctionTest = new TestToolFunction(toolRequest);
+      const result = await toolFunctionTest.perform();
 
-      expect(result.status).toBe(401);
+      expect(result.status).toBe(500);
       expect(result.bodyJSON).toEqual({
-        title: 'Unauthorized',
-        status: 401,
-        detail: 'Internal request authentication failed',
-        instance: '/overrides'
+        title: 'Internal Server Error',
+        status: 500,
+        detail: 'Database connection failed',
+        instance: '/some-tool'
       });
-      expect(mockProcessRequest).not.toHaveBeenCalled();
     });
 
-    it('should fail internal authentication when headers object is missing', async () => {
-      const overridesRequest = {
-        path: '/overrides',
-        method: 'DELETE',
-        bodyJSON: {},
+    it('should format ToolError from authorization failure as RFC 9457 response', async () => {
+      const toolRequest = {
+        ...mockRequest,
+        path: '/some-tool',
         headers: {
           get: jest.fn().mockImplementation((name: string) => {
             if (name === 'x-opal-thread-id') return 'test-thread-id';
@@ -643,15 +432,19 @@ describe('ToolFunction', () => {
         }
       };
 
-      const toolFunctionOverrides = new TestToolFunction(overridesRequest);
-      const result = await toolFunctionOverrides.perform();
+      const authError = new ToolError('Unauthorized', 403, 'Invalid access token');
+      (toolsService.requiresOptiIdAuth as jest.Mock).mockReturnValue(true);
+      jest.mocked(authenticateRegularRequest).mockRejectedValue(authError);
+
+      const toolFunctionTest = new TestToolFunction(toolRequest);
+      const result = await toolFunctionTest.perform();
 
-      expect(result.status).toBe(401);
+      expect(result.status).toBe(403);
       expect(result.bodyJSON).toEqual({
         title: 'Unauthorized',
-        status: 401,
-        detail: 'Internal request authentication failed',
-        instance: '/overrides'
+        status: 403,
+        detail: 'Invalid access token',
+        instance: '/some-tool'
       });
       expect(mockProcessRequest).not.toHaveBeenCalled();
     });

package/src/function/ToolFunction.ts

@@ -1,9 +1,9 @@
-import { Function, Response, Headers, amendLogContext } from '@zaiusinc/app-sdk';
+import { Function, Response, amendLogContext } from '@zaiusinc/app-sdk';
 import { authenticateRegularRequest, authenticateInternalRequest } from '../auth/AuthUtils';
 import { toolsService } from '../service/Service';
 import { ToolLogger } from '../logging/ToolLogger';
-import { ToolError } from '../types/ToolError';
 import { ReadyResponse } from '../types/Models';
+import { formatErrorResponse } from '../utils/ErrorFormatter';
 
 /**
  * Abstract base class for tool-based function execution
@@ -44,29 +44,6 @@ export abstract class ToolFunction extends Function {
    * @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 readyResult = await this.ready();
       const readyResponse = typeof readyResult === 'boolean'
@@ -75,21 +52,38 @@ export abstract class ToolFunction extends Function {
       return new Response(200, readyResponse);
     }
 
-    // Pass 'this' as context so decorated methods can use the existing instance
-    return toolsService.processRequest(this.request, this);
+    try {
+      await this.authorizeRequest();
+
+      // Pass 'this' as context so decorated methods can use the existing instance
+      return await toolsService.processRequest(this.request, this);
+    } catch (error) {
+      return formatErrorResponse(error, this.request.path);
+    }
   }
 
   /**
-   * Authenticate the incoming request by validating the OptiID token and organization ID
+   * Authenticate the incoming request based on the endpoint
+   * - /discovery: No auth required
+   * - /overrides: Internal auth (header-based token)
+   * - Tools/interactions: Regular auth if OptiID is required
    *
    * @throws {ToolError} If authentication fails
    */
   private async authorizeRequest(): Promise<void> {
+    // Discovery endpoint doesn't require auth
+    if (this.request.path === '/discovery') {
+      return;
+    }
+
     // Use internal authentication for overrides endpoint (header-based token)
     if (this.request.path === '/overrides') {
       await authenticateInternalRequest(this.request);
-    } else {
-      // Use regular authentication for other endpoints (body-based token with org validation)
+      return;
+    }
+
+    // Tool/interaction endpoints - authenticate only if OptiID is required
+    if (toolsService.requiresOptiIdAuth(this.request.path)) {
       await authenticateRegularRequest(this.request);
     }
   }