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

package/src/function/GlobalToolFunction.test.ts

@@ -2,11 +2,14 @@ import { GlobalToolFunction } from './GlobalToolFunction';
 import { toolsService } from '../service/Service';
 import { Response, getAppContext } from '@zaiusinc/app-sdk';
 import { getTokenVerifier } from '../auth/TokenVerifier';
+import { ToolError } from '../types/ToolError';
+import { authenticateGlobalRequest } from '../auth/AuthUtils';
 
 // Mock the dependencies
 jest.mock('../service/Service', () => ({
   toolsService: {
     processRequest: jest.fn(),
+    requiresOptiIdAuth: jest.fn(),
   },
 }));
 
@@ -14,6 +17,12 @@ jest.mock('../auth/TokenVerifier', () => ({
   getTokenVerifier: jest.fn(),
 }));
 
+jest.mock('../auth/AuthUtils', () => ({
+  authenticateGlobalRequest: jest.fn().mockResolvedValue(undefined),
+  authenticateInternalRequest: jest.fn().mockResolvedValue(undefined),
+  extractAuthData: jest.fn().mockReturnValue(null),
+}));
+
 jest.mock('@zaiusinc/app-sdk', () => ({
   GlobalFunction: class {
     protected request: any;
@@ -180,6 +189,7 @@ describe('GlobalToolFunction', () => {
       // Assert
       expect(result).toBe(mockResponse);
       expect(mockGetTokenVerifier).not.toHaveBeenCalled(); // Should not verify token for discovery
+      // processRequest is called without authValidator (auth handled internally)
       expect(mockProcessRequest).toHaveBeenCalledWith(discoveryRequest, globalToolFunction);
     });
   });
@@ -292,278 +302,168 @@ describe('GlobalToolFunction', () => {
   });
 
   describe('perform', () => {
-    it('should execute successfully with valid token (no organization validation)', 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 globalToolFunction.perform();
 
       expect(result).toBe(mockResponse);
-      expect(mockGetTokenVerifier).toHaveBeenCalled();
-      expect(mockTokenVerifier.verify).toHaveBeenCalledWith('valid-access-token');
-      // Note: getAppContext should NOT be called for global functions
-      expect(mockGetAppContext).not.toHaveBeenCalled();
+      // processRequest is called with request and context (no authValidator)
       expect(mockProcessRequest).toHaveBeenCalledWith(mockRequest, globalToolFunction);
     });
+  });
 
-    it('should execute successfully even with different organization ID', async () => {
-      // Update mock request with different customer_id (should still work for global functions)
-      const requestWithDifferentOrgId = {
-        ...mockRequest,
-        bodyJSON: {
-          ...mockRequest.bodyJSON,
-          auth: {
-            ...mockRequest.bodyJSON.auth,
-            credentials: {
-              ...mockRequest.bodyJSON.auth.credentials,
-              customer_id: 'completely-different-org-456'
-            }
-          }
+  describe('inheritance', () => {
+    it('should be an instance of GlobalFunction', () => {
+      // Assert
+      expect(globalToolFunction).toBeInstanceOf(GlobalToolFunction);
+    });
+
+    it('should have access to the request property', () => {
+      // Assert
+      expect(globalToolFunction.getRequest()).toBe(mockRequest);
+    });
+  });
+
+  describe('system paths routing', () => {
+    beforeEach(() => {
+      jest.clearAllMocks();
+    });
+
+    it('should forward /overrides to processRequest directly', 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;
+          })
         }
       };
 
-      const globalToolFunctionWithDifferentOrgId = new TestGlobalToolFunction(requestWithDifferentOrgId);
-      mockTokenVerifier.verify.mockResolvedValue(true);
       mockProcessRequest.mockResolvedValue(mockResponse);
-
-      const result = await globalToolFunctionWithDifferentOrgId.perform();
+      const globalFunc = new TestGlobalToolFunction(overridesRequest);
+      const result = await globalFunc.perform();
 
       expect(result).toBe(mockResponse);
-      expect(mockGetTokenVerifier).toHaveBeenCalled();
-      expect(mockTokenVerifier.verify).toHaveBeenCalledWith('valid-access-token');
-      // Note: Should NOT validate organization ID for global functions
-      expect(mockGetAppContext).not.toHaveBeenCalled();
-      expect(mockProcessRequest).toHaveBeenCalledWith(requestWithDifferentOrgId, globalToolFunctionWithDifferentOrgId);
+      // /overrides is forwarded directly to processRequest (auth handled there)
+      expect(mockProcessRequest).toHaveBeenCalledWith(overridesRequest, globalFunc);
     });
 
-    it('should execute successfully even without customer_id', async () => {
-      // Create request without customer_id (should still work for global functions)
-      const requestWithoutCustomerId = {
+    it('should forward tool endpoints to processRequest', async () => {
+      const toolRequest = {
         ...mockRequest,
-        bodyJSON: {
-          ...mockRequest.bodyJSON,
-          auth: {
-            ...mockRequest.bodyJSON.auth,
-            credentials: {
-              ...mockRequest.bodyJSON.auth.credentials,
-              customer_id: undefined
-            }
-          }
+        path: '/some-tool',
+        headers: {
+          get: jest.fn().mockImplementation((name: string) => {
+            if (name === 'x-opal-thread-id') return 'test-thread-id';
+            return null;
+          })
         }
       };
 
-      const globalToolFunctionWithoutCustomerId = new TestGlobalToolFunction(requestWithoutCustomerId);
-      mockTokenVerifier.verify.mockResolvedValue(true);
+      // Tool does not require OptiID auth
+      (toolsService.requiresOptiIdAuth as jest.Mock).mockReturnValue(false);
       mockProcessRequest.mockResolvedValue(mockResponse);
 
-      const result = await globalToolFunctionWithoutCustomerId.perform();
+      const globalFunc = new TestGlobalToolFunction(toolRequest);
+      const result = await globalFunc.perform();
 
       expect(result).toBe(mockResponse);
-      expect(mockGetTokenVerifier).toHaveBeenCalled();
-      expect(mockTokenVerifier.verify).toHaveBeenCalledWith('valid-access-token');
-      expect(mockGetAppContext).not.toHaveBeenCalled();
-      expect(mockProcessRequest).toHaveBeenCalledWith(requestWithoutCustomerId, globalToolFunctionWithoutCustomerId);
+      expect(mockProcessRequest).toHaveBeenCalledWith(toolRequest, globalFunc);
     });
+  });
 
-    it('should return 403 response with invalid token', async () => {
-      // Setup mock token verifier to return false
-      mockTokenVerifier.verify.mockResolvedValue(false);
-
-      const result = await globalToolFunction.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();
+  describe('error formatting', () => {
+    beforeEach(() => {
+      jest.clearAllMocks();
     });
 
-    it('should return 403 response when access token is missing', async () => {
-      // Create request without access token
-      const requestWithoutToken = {
+    it('should format ToolError as RFC 9457 response when processRequest throws ToolError', async () => {
+      const toolRequest = {
         ...mockRequest,
-        bodyJSON: {
-          ...mockRequest.bodyJSON,
-          auth: {
-            ...mockRequest.bodyJSON.auth,
-            credentials: {
-              ...mockRequest.bodyJSON.auth.credentials,
-              access_token: undefined
-            }
-          }
+        path: '/some-tool',
+        headers: {
+          get: jest.fn().mockImplementation((name: string) => {
+            if (name === 'x-opal-thread-id') return 'test-thread-id';
+            return null;
+          })
         }
       };
 
-      const globalToolFunctionWithoutToken = new TestGlobalToolFunction(requestWithoutToken);
+      const toolError = new ToolError('Resource not found', 404, 'The requested resource does not exist');
+      mockProcessRequest.mockRejectedValue(toolError);
+      (toolsService.requiresOptiIdAuth as jest.Mock).mockReturnValue(false);
 
-      const result = await globalToolFunctionWithoutToken.perform();
+      const globalFunc = new TestGlobalToolFunction(toolRequest);
+      const result = await globalFunc.perform();
 
-      expect(result.status).toBe(403);
+      expect(result.status).toBe(404);
       expect(result.bodyJSON).toEqual({
-        title: 'Forbidden',
-        status: 403,
-        detail: 'OptiID access token is required',
-        instance: '/test'
+        title: 'Resource not found',
+        status: 404,
+        detail: 'The requested resource does not exist',
+        instance: '/some-tool'
       });
-      expect(mockGetTokenVerifier).not.toHaveBeenCalled();
-      expect(mockProcessRequest).not.toHaveBeenCalled();
     });
 
-    it('should return 403 response when provider is not OptiID', async () => {
-      // Create request with different provider
-      const requestWithDifferentProvider = {
+    it('should format generic Error as 500 RFC 9457 response when processRequest throws', async () => {
+      const toolRequest = {
         ...mockRequest,
-        bodyJSON: {
-          ...mockRequest.bodyJSON,
-          auth: {
-            ...mockRequest.bodyJSON.auth,
-            provider: 'SomeOtherProvider'
-          }
+        path: '/some-tool',
+        headers: {
+          get: jest.fn().mockImplementation((name: string) => {
+            if (name === 'x-opal-thread-id') return 'test-thread-id';
+            return null;
+          })
         }
       };
 
-      const globalToolFunctionWithDifferentProvider = new TestGlobalToolFunction(requestWithDifferentProvider);
+      mockProcessRequest.mockRejectedValue(new Error('Database connection failed'));
+      (toolsService.requiresOptiIdAuth as jest.Mock).mockReturnValue(false);
 
-      const result = await globalToolFunctionWithDifferentProvider.perform();
+      const globalFunc = new TestGlobalToolFunction(toolRequest);
+      const result = await globalFunc.perform();
 
-      expect(result.status).toBe(403);
+      expect(result.status).toBe(500);
       expect(result.bodyJSON).toEqual({
-        title: 'Forbidden',
-        status: 403,
-        detail: 'Only OptiID authentication provider is supported',
-        instance: '/test'
+        title: 'Internal Server Error',
+        status: 500,
+        detail: 'Database connection failed',
+        instance: '/some-tool'
       });
-      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 = {
+    it('should format ToolError from authorization failure as RFC 9457 response', async () => {
+      const toolRequest = {
         ...mockRequest,
-        bodyJSON: {
-          parameters: mockRequest.bodyJSON.parameters,
-          environment: mockRequest.bodyJSON.environment
+        path: '/some-tool',
+        headers: {
+          get: jest.fn().mockImplementation((name: string) => {
+            if (name === 'x-opal-thread-id') return 'test-thread-id';
+            return null;
+          })
         }
       };
 
-      const globalToolFunctionWithoutAuth = new TestGlobalToolFunction(requestWithoutAuth);
-
-      const result = await globalToolFunctionWithoutAuth.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 globalToolFunction.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();
-    });
-
-    it('should return 403 response when token validation throws an error', async () => {
-      // Setup mock token verifier to throw an error
-      mockTokenVerifier.verify.mockRejectedValue(new Error('Token validation failed'));
+      const authError = new ToolError('Unauthorized', 403, 'Invalid access token');
+      (toolsService.requiresOptiIdAuth as jest.Mock).mockReturnValue(true);
+      jest.mocked(authenticateGlobalRequest).mockRejectedValue(authError);
 
-      const result = await globalToolFunction.perform();
+      const globalFunc = new TestGlobalToolFunction(toolRequest);
+      const result = await globalFunc.perform();
 
       expect(result.status).toBe(403);
       expect(result.bodyJSON).toEqual({
-        title: 'Forbidden',
+        title: 'Unauthorized',
         status: 403,
-        detail: 'Token verification failed',
-        instance: '/test'
+        detail: 'Invalid access token',
+        instance: '/some-tool'
       });
-      expect(mockGetTokenVerifier).toHaveBeenCalled();
-      expect(mockTokenVerifier.verify).toHaveBeenCalledWith('valid-access-token');
       expect(mockProcessRequest).not.toHaveBeenCalled();
     });
   });
-
-  describe('inheritance', () => {
-    it('should be an instance of GlobalFunction', () => {
-      // Assert
-      expect(globalToolFunction).toBeInstanceOf(GlobalToolFunction);
-    });
-
-    it('should have access to the request property', () => {
-      // Assert
-      expect(globalToolFunction.getRequest()).toBe(mockRequest);
-    });
-  });
-
-  describe('authentication differences from ToolFunction', () => {
-    it('should NOT validate organization ID (unlike ToolFunction)', async () => {
-      // This test demonstrates the key difference between GlobalToolFunction and ToolFunction
-      // GlobalToolFunction should work with any customer_id, while ToolFunction requires matching org ID
-
-      const requestWithRandomOrgId = {
-        ...mockRequest,
-        bodyJSON: {
-          ...mockRequest.bodyJSON,
-          auth: {
-            ...mockRequest.bodyJSON.auth,
-            credentials: {
-              ...mockRequest.bodyJSON.auth.credentials,
-              customer_id: 'random-org-999' // This would fail in ToolFunction but should work here
-            }
-          }
-        }
-      };
-
-      const globalToolFunctionWithRandomOrgId = new TestGlobalToolFunction(requestWithRandomOrgId);
-      mockTokenVerifier.verify.mockResolvedValue(true);
-      mockProcessRequest.mockResolvedValue(mockResponse);
-
-      const result = await globalToolFunctionWithRandomOrgId.perform();
-
-      // Should succeed even with different org ID
-      expect(result).toBe(mockResponse);
-      expect(mockGetTokenVerifier).toHaveBeenCalled();
-      expect(mockTokenVerifier.verify).toHaveBeenCalledWith('valid-access-token');
-      // Crucially: getAppContext should NOT be called (no org validation)
-      expect(mockGetAppContext).not.toHaveBeenCalled();
-      expect(mockProcessRequest).toHaveBeenCalledWith(requestWithRandomOrgId, globalToolFunctionWithRandomOrgId);
-    });
-
-    it('should only require valid OptiID token (no organization constraints)', async () => {
-      // Test that only token validation is performed, no org validation
-      mockTokenVerifier.verify.mockResolvedValue(true);
-      mockProcessRequest.mockResolvedValue(mockResponse);
-
-      const result = await globalToolFunction.perform();
-
-      expect(result).toBe(mockResponse);
-      expect(mockGetTokenVerifier).toHaveBeenCalled();
-      expect(mockTokenVerifier.verify).toHaveBeenCalledWith('valid-access-token');
-
-      // Key assertion: getAppContext should never be called for global functions
-      expect(mockGetAppContext).not.toHaveBeenCalled();
-      expect(mockProcessRequest).toHaveBeenCalledWith(mockRequest, globalToolFunction);
-    });
-  });
 });

package/src/function/GlobalToolFunction.ts

@@ -1,9 +1,9 @@
-import { GlobalFunction, Response, Headers, amendLogContext } from '@zaiusinc/app-sdk';
-import { authenticateGlobalRequest, extractAuthData } from '../auth/AuthUtils';
+import { GlobalFunction, Response, amendLogContext } from '@zaiusinc/app-sdk';
+import { authenticateGlobalRequest, authenticateInternalRequest, extractAuthData } 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 global tool-based function execution
@@ -30,8 +30,8 @@ export abstract class GlobalToolFunction extends GlobalFunction {
     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;
+    const optiIdCredentials = extractAuthData(this.request);
+    const customerId = optiIdCredentials?.customer_id;
 
     amendLogContext({
       opalThreadId: this.request.headers.get('x-opal-thread-id') || '',
@@ -46,29 +46,6 @@ export abstract class GlobalToolFunction extends GlobalFunction {
   }
 
   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'
@@ -77,15 +54,38 @@ export abstract class GlobalToolFunction extends GlobalFunction {
       return new Response(200, readyResponse);
     }
 
-    return toolsService.processRequest(this.request, this);
+    try {
+      await this.authorizeRequest();
+
+      return await toolsService.processRequest(this.request, this);
+    } catch (error) {
+      return formatErrorResponse(error, this.request.path);
+    }
   }
 
   /**
-   * Authenticate the incoming request by validating only the OptiID token
+   * Authenticate the incoming request based on the endpoint
+   * - /discovery: No auth required
+   * - /overrides: Internal auth (header-based token)
+   * - Tools/interactions: Global auth if OptiID is required
    *
    * @throws {ToolError} If authentication fails
    */
   private async authorizeRequest(): Promise<void> {
-    await authenticateGlobalRequest(this.request);
+    // 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);
+      return;
+    }
+
+    // Tool/interaction endpoints - authenticate only if OptiID is required
+    if (toolsService.requiresOptiIdAuth(this.request.path)) {
+      await authenticateGlobalRequest(this.request);
+    }
   }
 }