@optimizely-opal/opal-tool-ocp-sdk 1.0.0-OCP-1442.6 → 1.0.0-OCP-1449.1

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();
     });
@@ -374,4 +420,224 @@ describe('ToolFunction', () => {
       expect(toolFunction.getRequest()).toBe(mockRequest);
     });
   });
+
+  describe('internal request authentication', () => {
+    beforeEach(() => {
+      // Reset mocks before each test
+      jest.clearAllMocks();
+      setupAuthMocks();
+    });
+
+    it('should use internal authentication for /overrides endpoint', 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;
+          })
+        }
+      };
+
+      mockProcessRequest.mockResolvedValue(mockResponse);
+      const toolFunctionOverrides = new TestToolFunction(overridesRequest);
+      const result = await toolFunctionOverrides.perform();
+
+      expect(result).toBe(mockResponse);
+      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',
+        headers: {
+          get: jest.fn().mockImplementation((name: string) => {
+            if (name === 'x-opal-thread-id') return 'test-thread-id';
+            return null;
+          })
+        }
+      };
+
+      mockProcessRequest.mockResolvedValue(mockResponse);
+      const toolFunctionRegular = new TestToolFunction(regularRequest);
+      const result = await toolFunctionRegular.perform();
+
+      expect(result).toBe(mockResponse);
+      expect(mockProcessRequest).toHaveBeenCalledWith(regularRequest, toolFunctionRegular);
+    });
+
+    it('should handle internal authentication with valid 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();
+
+      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();
+
+      expect(result).toBe(mockResponse);
+      expect(mockProcessRequest).toHaveBeenCalledWith(overridesRequest, toolFunctionOverrides);
+    });
+
+    it('should fail internal authentication when token verification fails', async () => {
+      // Mock token verifier to return false for invalid token
+      mockTokenVerifier.verify.mockResolvedValue(false);
+
+      const overridesRequest = {
+        path: '/overrides',
+        method: 'DELETE',
+        bodyJSON: {},
+        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();
+
+      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 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: {},
+        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();
+
+      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 fail internal authentication when headers object is missing', 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 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();
+    });
+  });
 });

package/src/function/ToolFunction.ts

@@ -1,7 +1,8 @@
-import { Function, Response, amendLogContext } from '@zaiusinc/app-sdk';
-import { authenticateRegularRequest } from '../auth/AuthUtils';
+import { Function, Response, Headers, 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';
 
 /**
  * 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,15 @@ 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> {
+    // 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)
+      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/logging/ToolLogger.test.ts

@@ -32,6 +32,7 @@ describe('ToolLogger', () => {
   const createMockRequest = (overrides: any = {}): App.Request => {
     const defaultRequest = {
       path: '/test-tool',
+      method: 'POST',
       bodyJSON: {
         parameters: {
           name: 'test',
@@ -96,6 +97,7 @@ describe('ToolLogger', () => {
       const expectedLog = {
         event: 'opal_tool_request',
         path: '/test-tool',
+        method: 'POST',
         parameters: {
           name: 'test',
           value: 'data'
@@ -118,6 +120,7 @@ describe('ToolLogger', () => {
       expectJsonLog({
         event: 'opal_tool_request',
         path: '/test-tool',
+        method: 'POST',
         parameters: null
       });
     });
@@ -135,6 +138,7 @@ describe('ToolLogger', () => {
       expectJsonLog({
         event: 'opal_tool_request',
         path: '/test-tool',
+        method: 'POST',
         parameters: {
           name: 'direct',
           action: 'test'
@@ -167,6 +171,7 @@ describe('ToolLogger', () => {
       expectJsonLog({
         event: 'opal_tool_request',
         path: '/test-tool',
+        method: 'POST',
         parameters: {
           username: 'john',
           password: '[REDACTED]',
@@ -204,6 +209,7 @@ describe('ToolLogger', () => {
       expectJsonLog({
         event: 'opal_tool_request',
         path: '/test-tool',
+        method: 'POST',
         parameters: {
           PASSWORD: '[REDACTED]',
           API_KEY: '[REDACTED]',
@@ -232,6 +238,7 @@ describe('ToolLogger', () => {
       expectJsonLog({
         event: 'opal_tool_request',
         path: '/test-tool',
+        method: 'POST',
         parameters: {
           description: `${'a'.repeat(100)}... (truncated, 150 chars total)`,
           short_field: 'normal'
@@ -255,6 +262,7 @@ describe('ToolLogger', () => {
       expectJsonLog({
         event: 'opal_tool_request',
         path: '/test-tool',
+        method: 'POST',
         parameters: {
           items: [
             ...largeArray.slice(0, 10),
@@ -291,6 +299,7 @@ describe('ToolLogger', () => {
       expectJsonLog({
         event: 'opal_tool_request',
         path: '/test-tool',
+        method: 'POST',
         parameters: {
           user: {
             name: 'John',
@@ -328,6 +337,7 @@ describe('ToolLogger', () => {
       expectJsonLog({
         event: 'opal_tool_request',
         path: '/test-tool',
+        method: 'POST',
         parameters: {
           nullValue: null,
           emptyString: '',
@@ -353,6 +363,7 @@ describe('ToolLogger', () => {
       expectJsonLog({
         event: 'opal_tool_request',
         path: '/test-tool',
+        method: 'POST',
         parameters: {
           credentials: '[REDACTED]',
           public_list: ['item1', 'item2']
@@ -381,6 +392,7 @@ describe('ToolLogger', () => {
       expectJsonLog({
         event: 'opal_tool_request',
         path: '/test-tool',
+        method: 'POST',
         parameters: {
           auth: '[REDACTED]',
           public_config: {
@@ -496,7 +508,9 @@ describe('ToolLogger', () => {
       // First item: deeply nested object with inner parts replaced by placeholder
       expect(items[0]).toEqual({
         level2: {
-          level3: '[MAX_DEPTH_EXCEEDED]'
+          level3: {
+            level4: '[MAX_DEPTH_EXCEEDED]'
+          }
         }
       });
 
@@ -509,7 +523,9 @@ describe('ToolLogger', () => {
       // Fourth item: another deeply nested object with inner parts replaced by placeholder
       expect(items[3]).toEqual({
         level2: {
-          level3: '[MAX_DEPTH_EXCEEDED]'
+          level3: {
+            level4: '[MAX_DEPTH_EXCEEDED]'
+          }
         }
       });
     });
@@ -694,6 +710,7 @@ describe('ToolLogger', () => {
       expectJsonLog({
         event: 'opal_tool_request',
         path: '/test-tool',
+        method: 'POST',
         parameters: {}
       });
     });
@@ -712,6 +729,7 @@ describe('ToolLogger', () => {
       expectJsonLog({
         event: 'opal_tool_request',
         path: '/test-tool',
+        method: 'POST',
         parameters: {
           field: 'value'
         }
@@ -738,6 +756,7 @@ describe('ToolLogger', () => {
       expectJsonLog({
         event: 'opal_tool_request',
         path: '/test-tool',
+        method: 'POST',
         parameters: {
           string: 'text',
           number: 42,
@@ -749,5 +768,102 @@ describe('ToolLogger', () => {
         }
       });
     });
+
+    it('should handle tool override request with enhanced parameter descriptions', () => {
+      const overrideRequest = {
+        tools: [
+          {
+            name: 'calculate_experiment_runtime',
+            description: 'OVERRIDDEN: Enhanced experiment runtime calculator with advanced features',
+            parameters: [
+              {
+                name: 'BCR',
+                type: 'number',
+                description: 'OVERRIDDEN: Enhanced baseline conversion rate with validation',
+                required: true
+              },
+              {
+                name: 'MDE',
+                type: 'number',
+                description: 'OVERRIDDEN: Enhanced minimum detectable effect calculation',
+                required: true
+              },
+              {
+                name: 'sigLevel',
+                type: 'number',
+                description: 'OVERRIDDEN: Enhanced statistical significance level',
+                required: true
+              },
+              {
+                name: 'numVariations',
+                type: 'number',
+                description: 'OVERRIDDEN: Enhanced number of variations handling',
+                required: true
+              },
+              {
+                name: 'dailyVisitors',
+                type: 'number',
+                description: 'OVERRIDDEN: Enhanced daily visitor count with forecasting',
+                required: true
+              }
+            ]
+          }
+          // Note: NOT including calculate_sample_size in override
+        ]
+      };
+
+      const req = createMockRequest({
+        path: '/overrides',
+        bodyJSON: overrideRequest
+      });
+
+      ToolLogger.logRequest(req);
+
+      expectJsonLog({
+        event: 'opal_tool_request',
+        path: '/overrides',
+        method: 'POST',
+        parameters: {
+          tools: [
+            {
+              name: 'calculate_experiment_runtime',
+              description: 'OVERRIDDEN: Enhanced experiment runtime calculator with advanced features',
+              parameters: [
+                {
+                  name: 'BCR',
+                  type: 'number',
+                  description: 'OVERRIDDEN: Enhanced baseline conversion rate with validation',
+                  required: true
+                },
+                {
+                  name: 'MDE',
+                  type: 'number',
+                  description: 'OVERRIDDEN: Enhanced minimum detectable effect calculation',
+                  required: true
+                },
+                {
+                  name: 'sigLevel',
+                  type: 'number',
+                  description: 'OVERRIDDEN: Enhanced statistical significance level',
+                  required: true
+                },
+                {
+                  name: 'numVariations',
+                  type: 'number',
+                  description: 'OVERRIDDEN: Enhanced number of variations handling',
+                  required: true
+                },
+                {
+                  name: 'dailyVisitors',
+                  type: 'number',
+                  description: 'OVERRIDDEN: Enhanced daily visitor count with forecasting',
+                  required: true
+                }
+              ]
+            }
+          ]
+        }
+      });
+    });
   });
 });

package/src/logging/ToolLogger.ts

@@ -75,7 +75,7 @@ export class ToolLogger {
 
     if (Array.isArray(data)) {
       const truncated = data.slice(0, this.MAX_ARRAY_ITEMS);
-      const result = truncated.map((item) => this.redactSensitiveData(item, maxDepth - 1));
+      const result = truncated.map((item) => this.redactSensitiveData(item, maxDepth));
       if (data.length > this.MAX_ARRAY_ITEMS) {
         result.push(`... (${data.length - this.MAX_ARRAY_ITEMS} more items truncated)`);
       }
@@ -146,6 +146,7 @@ export class ToolLogger {
     const requestLog = {
       event: 'opal_tool_request',
       path: req.path,
+      method: req.method,
       parameters: this.createParameterSummary(params)
     };