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

package/src/logging/ToolLogger.ts

@@ -0,0 +1,177 @@
+import { logger, LogVisibility } from '@zaiusinc/app-sdk';
+import * as App from '@zaiusinc/app-sdk';
+
+/**
+ * Utility class for logging Opal tool requests and responses with security considerations
+ */
+export class ToolLogger {
+  private static readonly SENSITIVE_FIELDS = [
+    // Authentication / secrets
+    'password',
+    'pass',
+    'secret',
+    'key',
+    'token',
+    'auth',
+    'credentials',
+    'access_token',
+    'refresh_token',
+    'api_key',
+    'private_key',
+    'client_secret',
+    'session_token',
+    'authorization',
+
+    // Payment-related
+    'card_number',
+    'credit_card',
+    'cvv',
+    'expiry_date',
+
+    // Personal info
+    'ssn', // social security number
+    'nid', // national ID
+    'passport',
+    'dob', // date of birth
+    'email',
+    'phone',
+    'address',
+
+    // Misc / environment
+    'otp',
+    'pin',
+    'security_answer',
+    'security_question',
+    'signing_key',
+    'encryption_key',
+    'jwt',
+    'bearer_token'
+  ];
+
+  private static readonly MAX_PARAM_LENGTH = 100;
+  private static readonly MAX_ARRAY_ITEMS = 10;
+
+  /**
+   * Redacts sensitive data from an object
+   */
+  private static redactSensitiveData(data: any, maxDepth = 5): any {
+    if (maxDepth <= 0) {
+      return '[MAX_DEPTH_EXCEEDED]';
+    }
+
+    if (data === null || data === undefined) {
+      return data;
+    }
+
+    if (typeof data === 'string') {
+      return data.length > this.MAX_PARAM_LENGTH
+        ? `${data.substring(0, this.MAX_PARAM_LENGTH)}... (truncated, ${data.length} chars total)`
+        : data;
+    }
+
+    if (typeof data === 'number' || typeof data === 'boolean') {
+      return data;
+    }
+
+    if (Array.isArray(data)) {
+      const truncated = data.slice(0, this.MAX_ARRAY_ITEMS);
+      const result = truncated.map((item) => this.redactSensitiveData(item, maxDepth - 1));
+      if (data.length > this.MAX_ARRAY_ITEMS) {
+        result.push(`... (${data.length - this.MAX_ARRAY_ITEMS} more items truncated)`);
+      }
+      return result;
+    }
+
+    if (typeof data === 'object') {
+      const result: any = {};
+      for (const [key, value] of Object.entries(data)) {
+        // Check if this field contains sensitive data
+        const isSensitive = this.isSensitiveField(key);
+
+        if (isSensitive) {
+          result[key] = '[REDACTED]';
+        } else {
+          result[key] = this.redactSensitiveData(value, maxDepth - 1);
+        }
+      }
+      return result;
+    }
+
+    return data;
+  }
+
+  /**
+   * Checks if a field name is considered sensitive
+   */
+  private static isSensitiveField(fieldName: string): boolean {
+    const lowerKey = fieldName.toLowerCase();
+    return this.SENSITIVE_FIELDS.some((sensitiveField) =>
+      lowerKey.includes(sensitiveField)
+    );
+  }
+
+  /**
+   * Creates a summary of request parameters
+   */
+  private static createParameterSummary(params: any): any {
+    if (!params) {
+      return null;
+    }
+
+    return this.redactSensitiveData(params);
+  }
+
+  /**
+   * Calculates content length of response data
+   */
+  private static calculateContentLength(response?: App.Response) {
+    if (!response) {
+      return 0;
+    }
+
+    try {
+      return response.bodyAsU8Array?.length || 'unknown';
+    } catch {
+      return 'unknown';
+    }
+  }
+
+  /**
+   * Logs an incoming request
+   */
+  public static logRequest(
+    req: App.Request,
+  ): void {
+    const params = req.bodyJSON && req.bodyJSON.parameters ? req.bodyJSON.parameters : req.bodyJSON;
+    const requestLog = {
+      event: 'opal_tool_request',
+      path: req.path,
+      parameters: this.createParameterSummary(params)
+    };
+
+    // Log with Zaius audience so developers only see requests for accounts they have access to
+    logger.info(LogVisibility.Zaius, JSON.stringify(requestLog));
+  }
+
+  /**
+   * Logs a successful response
+   */
+  public static logResponse(
+    req: App.Request,
+    response: App.Response,
+    processingTimeMs?: number
+  ): void {
+    const responseLog = {
+      event: 'opal_tool_response',
+      path: req.path,
+      duration: processingTimeMs ? `${processingTimeMs}ms` : undefined,
+      status: response.status,
+      contentType: response.headers?.get('content-type') || 'unknown',
+      contentLength: this.calculateContentLength(response),
+      success: response.status >= 200 && response.status < 300
+    };
+
+    // Log with Zaius audience so developers only see requests for accounts they have access to
+    logger.info(LogVisibility.Zaius, JSON.stringify(responseLog));
+  }
+}

package/src/service/Service.test.ts

@@ -11,11 +11,30 @@ jest.mock('@zaiusinc/app-sdk', () => ({
   Function: class {
     public constructor(public request: any) {}
   },
-  Response: jest.fn().mockImplementation((status, data) => ({
+  Headers: class {
+    public constructor(headers: string[][] = []) {
+      this.headers = {};
+      headers.forEach(([name, value]) => {
+        this.headers[name.toLowerCase()] = value;
+      });
+    }
+    public headers: { [key: string]: string };
+    public set(name: string, value: string) {
+      this.headers[name.toLowerCase()] = value;
+    }
+    public get(name: string) {
+      return this.headers[name.toLowerCase()];
+    }
+    public has(name: string) {
+      return name.toLowerCase() in this.headers;
+    }
+  },
+  Response: jest.fn().mockImplementation((status, data, headers) => ({
     status,
     data,
     bodyJSON: data,
-    bodyAsU8Array: new Uint8Array()
+    bodyAsU8Array: new Uint8Array(),
+    headers: headers || { get: jest.fn(), has: jest.fn(), set: jest.fn() }
   }))
 }));
 
@@ -522,15 +541,25 @@ describe('ToolsService', () => {
 
     describe('edge cases', () => {
       it('should handle request with null bodyJSON', async () => {
+        // Create a tool without required parameters
+        const toolWithoutRequiredParams = {
+          name: 'no_required_params_tool',
+          description: 'Tool without required parameters',
+          handler: jest.fn().mockResolvedValue({ result: 'success' }),
+          parameters: [], // No parameters defined
+          endpoint: '/no-required-params-tool'
+        };
+
         toolsService.registerTool(
-          mockTool.name,
-          mockTool.description,
-          mockTool.handler,
-          mockTool.parameters,
-          mockTool.endpoint
+          toolWithoutRequiredParams.name,
+          toolWithoutRequiredParams.description,
+          toolWithoutRequiredParams.handler,
+          toolWithoutRequiredParams.parameters,
+          toolWithoutRequiredParams.endpoint
         );
 
         const requestWithNullBody = createMockRequest({
+          path: '/no-required-params-tool',
           bodyJSON: null,
           body: null
         });
@@ -538,19 +567,29 @@ describe('ToolsService', () => {
         const response = await toolsService.processRequest(requestWithNullBody, mockToolFunction);
 
         expect(response.status).toBe(200);
-        expect(mockTool.handler).toHaveBeenCalledWith(mockToolFunction, null, undefined);
+        expect(toolWithoutRequiredParams.handler).toHaveBeenCalledWith(mockToolFunction, null, undefined);
       });
 
       it('should handle request with undefined bodyJSON', async () => {
+        // Create a tool without required parameters
+        const toolWithoutRequiredParams = {
+          name: 'no_required_params_tool_2',
+          description: 'Tool without required parameters',
+          handler: jest.fn().mockResolvedValue({ result: 'success' }),
+          parameters: [], // No parameters defined
+          endpoint: '/no-required-params-tool-2'
+        };
+
         toolsService.registerTool(
-          mockTool.name,
-          mockTool.description,
-          mockTool.handler,
-          mockTool.parameters,
-          mockTool.endpoint
+          toolWithoutRequiredParams.name,
+          toolWithoutRequiredParams.description,
+          toolWithoutRequiredParams.handler,
+          toolWithoutRequiredParams.parameters,
+          toolWithoutRequiredParams.endpoint
         );
 
         const requestWithUndefinedBody = createMockRequest({
+          path: '/no-required-params-tool-2',
           bodyJSON: undefined,
           body: undefined
         });
@@ -558,7 +597,7 @@ describe('ToolsService', () => {
         const response = await toolsService.processRequest(requestWithUndefinedBody, mockToolFunction);
 
         expect(response.status).toBe(200);
-        expect(mockTool.handler).toHaveBeenCalledWith(mockToolFunction, undefined, undefined);
+        expect(toolWithoutRequiredParams.handler).toHaveBeenCalledWith(mockToolFunction, undefined, undefined);
       });
 
       it('should extract auth data from bodyJSON when body exists', async () => {
@@ -657,5 +696,107 @@ describe('ToolsService', () => {
         );
       });
     });
+
+    describe('parameter validation', () => {
+      beforeEach(() => {
+        jest.clearAllMocks();
+      });
+
+      it('should validate parameters and return 400 for invalid types', async () => {
+        // Register a tool with specific parameter types
+        const toolWithTypedParams = {
+          name: 'typed_tool',
+          description: 'Tool with typed parameters',
+          handler: jest.fn().mockResolvedValue({ result: 'success' }),
+          parameters: [
+            new Parameter('name', ParameterType.String, 'User name', true),
+            new Parameter('age', ParameterType.Integer, 'User age', true),
+            new Parameter('active', ParameterType.Boolean, 'Is active', false)
+          ],
+          endpoint: '/typed-tool'
+        };
+
+        toolsService.registerTool(
+          toolWithTypedParams.name,
+          toolWithTypedParams.description,
+          toolWithTypedParams.handler,
+          toolWithTypedParams.parameters,
+          toolWithTypedParams.endpoint
+        );
+
+        // Send invalid parameter types
+        const invalidRequest = createMockRequest({
+          path: '/typed-tool',
+          bodyJSON: {
+            parameters: {
+              name: 123, // should be string
+              age: '25', // should be integer
+              active: 'true' // should be boolean
+            }
+          }
+        });
+
+        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');
+
+        // Verify the handler was not called
+        expect(toolWithTypedParams.handler).not.toHaveBeenCalled();
+      });
+
+      it('should skip validation for tools with no parameter definitions', async () => {
+        const toolWithoutParams = {
+          name: 'no_params_tool',
+          description: 'Tool without parameters',
+          handler: jest.fn().mockResolvedValue({ result: 'success' }),
+          parameters: [], // No parameters defined
+          endpoint: '/no-params-tool'
+        };
+
+        toolsService.registerTool(
+          toolWithoutParams.name,
+          toolWithoutParams.description,
+          toolWithoutParams.handler,
+          toolWithoutParams.parameters,
+          toolWithoutParams.endpoint
+        );
+
+        // Send request with any data (should be ignored)
+        const request = createMockRequest({
+          path: '/no-params-tool',
+          bodyJSON: {
+            parameters: {
+              unexpected: 'value'
+            }
+          }
+        });
+
+        const response = await toolsService.processRequest(request, mockToolFunction);
+
+        expect(response.status).toBe(200);
+        expect(toolWithoutParams.handler).toHaveBeenCalledWith(
+          mockToolFunction,
+          { unexpected: 'value' },
+          undefined
+        );
+      });
+    });
   });
 });

package/src/service/Service.ts

@@ -1,9 +1,10 @@
 /* eslint-disable max-classes-per-file */
 import { AuthRequirement, Parameter } from '../types/Models';
 import * as App from '@zaiusinc/app-sdk';
-import { logger } from '@zaiusinc/app-sdk';
+import { logger, Headers } 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
@@ -173,6 +174,23 @@ export class ToolsService {
             params = req.bodyJSON;
           }
 
+          // Validate parameters before calling the handler (only if tool has parameter definitions)
+          if (func.parameters && func.parameters.length > 0) {
+            const validationResult = ParameterValidator.validate(params, func.parameters);
+            if (!validationResult.isValid) {
+              return new App.Response(400, {
+                title: 'One or more validation errors occurred.',
+                status: 400,
+                detail: "See 'errors' field for details.",
+                instance: func.endpoint,
+                errors: validationResult.errors.map((error) => ({
+                  field: error.field,
+                  message: error.message
+                }))
+              }, new Headers([['content-type', 'application/problem+json']]));
+            }
+          }
+
           // Extract auth data from body JSON
           const authData = req.bodyJSON ? req.bodyJSON.auth : undefined;