@optimizely-opal/opal-tool-ocp-sdk 0.0.0-beta.1 → 0.0.0-beta.10

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "@optimizely-opal/opal-tool-ocp-sdk",
-  "version": "0.0.0-beta.1",
+  "version": "0.0.0-beta.10",
   "description": "OCP SDK for Opal tool",
   "scripts": {
+    "validate-deps": "node scripts/validate-deps.js",
+    "prebuild": "yarn run validate-deps",
     "build": "yarn tsc",
     "build-watch": "tsc -w",
     "lint": "npx eslint 'src/**/*.ts'",
@@ -49,10 +51,15 @@
     "rimraf": "^6.0.1",
     "ts-jest": "^29.3.2",
     "tslint": "^6.1.3",
-    "typescript": "^5.8.2"
+    "typescript": "^5.8.2",
+    "@zaiusinc/node-sdk": "^2.0.0",
+    "@zaiusinc/app-sdk": "^2.2.4-devmg.1"
   },
   "dependencies": {
-    "@zaiusinc/app-sdk": "2.2.2",
+    "jose": "^6.1.0",
     "reflect-metadata": "^0.2.2"
+  },
+  "peerDependencies": {
+    "@zaiusinc/app-sdk": "^2.2.4-devmg.1"
   }
 }

package/src/auth/TokenVerifier.test.ts

@@ -0,0 +1,152 @@
+import { TokenVerifier } from './TokenVerifier';
+
+// Test constants
+const TEST_ISSUER = 'https://prep.login.optimizely.com/oauth2/default';
+const TEST_JWKS_URI = 'https://prep.login.optimizely.com/oauth2/v1/keys';
+
+// Mock fetch globally
+global.fetch = jest.fn();
+
+describe('TokenVerifier', () => {
+  beforeEach(() => {
+    // Reset fetch mock
+    (global.fetch as jest.Mock).mockReset();
+
+    // Reset singleton instance for each test
+    (TokenVerifier as any).instance = null;
+  });
+
+  describe('getInitializedInstance', () => {
+    it('should initialize successfully', async () => {
+      // Mock fetch for OAuth2 authorization server discovery
+      (global.fetch as jest.Mock).mockResolvedValue({
+        ok: true,
+        json: jest.fn().mockResolvedValue({
+          issuer: TEST_ISSUER,
+          jwks_uri: TEST_JWKS_URI
+        })
+      });
+
+      const tokenVerifier = await TokenVerifier.getInitializedInstance();
+      expect(tokenVerifier).toBeInstanceOf(TokenVerifier);
+    });
+
+    it('should throw error when discovery document is invalid', async () => {
+      (global.fetch as jest.Mock).mockResolvedValue({
+        ok: true,
+        json: jest.fn().mockResolvedValue({
+          // Missing issuer and jwks_uri
+        })
+      });
+
+      await expect(TokenVerifier.getInitializedInstance()).rejects.toThrow(
+        'Invalid discovery document: missing issuer or jwks_uri'
+      );
+    });
+
+    it('should throw error when discovery endpoint is unreachable', async () => {
+      (global.fetch as jest.Mock).mockResolvedValue({
+        ok: false,
+        status: 404,
+        statusText: 'Not Found'
+      });
+
+      await expect(TokenVerifier.getInitializedInstance()).rejects.toThrow(
+        'Failed to fetch discovery document: 404 Not Found'
+      );
+    });
+  });
+
+  describe('token verification', () => {
+    let tokenVerifier: TokenVerifier;
+
+    beforeEach(async () => {
+      // Mock successful initialization
+      (global.fetch as jest.Mock).mockResolvedValue({
+        ok: true,
+        json: jest.fn().mockResolvedValue({
+          issuer: TEST_ISSUER,
+          jwks_uri: TEST_JWKS_URI
+        })
+      });
+
+      tokenVerifier = await TokenVerifier.getInitializedInstance();
+    });
+
+    it('should throw error for empty token', async () => {
+      await expect(tokenVerifier.verify('')).rejects.toThrow(
+        'Token cannot be null or empty'
+      );
+    });
+
+    it('should throw error for undefined token', async () => {
+      await expect(tokenVerifier.verify(undefined)).rejects.toThrow(
+        'Token cannot be null or empty'
+      );
+    });
+
+    it('should throw error for whitespace-only token', async () => {
+      await expect(tokenVerifier.verify('   ')).rejects.toThrow(
+        'Token cannot be null or empty'
+      );
+    });
+
+    it('should return false for invalid token format', async () => {
+      const result = await tokenVerifier.verify('invalid.jwt.token');
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('singleton pattern', () => {
+    it('should return same instance when called multiple times', async () => {
+      // Mock successful initialization
+      (global.fetch as jest.Mock).mockResolvedValue({
+        ok: true,
+        json: jest.fn().mockResolvedValue({
+          issuer: TEST_ISSUER,
+          jwks_uri: TEST_JWKS_URI
+        })
+      });
+
+      const instance1 = await TokenVerifier.getInitializedInstance();
+      const instance2 = await TokenVerifier.getInitializedInstance();
+      expect(instance1).toBe(instance2);
+    });
+    it('should call correct prod OAuth2 authorization server discovery URL', async () => {
+      const fetchSpy = jest.spyOn(global, 'fetch').mockResolvedValue({
+        ok: true,
+        json: jest.fn().mockResolvedValue({
+          issuer: TEST_ISSUER,
+          jwks_uri: TEST_JWKS_URI
+        })
+      } as unknown as Response);
+
+      await TokenVerifier.getInitializedInstance();
+
+      expect(fetchSpy).toHaveBeenCalledWith(
+        'https://login.optimizely.com/oauth2/default/.well-known/oauth-authorization-server'
+      );
+    });
+
+    it('should call correct prep OAuth2 authorization server discovery URL', async () => {
+      // Set environment variable to staging
+      process.env.environment = 'staging';
+
+      const fetchSpy = jest.spyOn(global, 'fetch').mockResolvedValue({
+        ok: true,
+        json: jest.fn().mockResolvedValue({
+          issuer: TEST_ISSUER,
+          jwks_uri: TEST_JWKS_URI
+        })
+      } as unknown as Response);
+
+      await TokenVerifier.getInitializedInstance();
+
+      expect(fetchSpy).toHaveBeenCalledWith(
+        'https://prep.login.optimizely.com/oauth2/default/.well-known/oauth-authorization-server'
+      );
+
+    });
+  });
+
+});

package/src/auth/TokenVerifier.ts

@@ -0,0 +1,145 @@
+import { jwtVerify, createRemoteJWKSet } from 'jose';
+import { logger } from '@zaiusinc/app-sdk';
+
+/**
+ * Default JWKS cache expiration time in milliseconds (1 hour)
+ */
+const DEFAULT_JWKS_EXPIRES_IN = 60 * 60 * 1000;
+
+/**
+ * Default clock skew tolerance in seconds
+ */
+const DEFAULT_LEEWAY = 30;
+
+/**
+ * Expected JWT audience for token validation
+ */
+const AUDIENCE = 'api://default';
+
+/**
+ * Prep Base URL for Optimizely OAuth2 endpoints
+ */
+const PREP_BASE_URL = 'https://prep.login.optimizely.com/oauth2/default';
+
+/**
+ * Prod Base URL for Optimizely OAuth2 endpoints
+ */
+const PROD_BASE_URL = 'https://login.optimizely.com/oauth2/default';
+
+interface DiscoveryDocument {
+  issuer: string;
+  jwks_uri: string;
+  [key: string]: any;
+}
+
+export class TokenVerifier {
+  private static instance: TokenVerifier | null = null;
+  private jwksUri?: string;
+  private issuer?: string;
+  private jwks?: ReturnType<typeof createRemoteJWKSet>;
+  private initialized: boolean = false;
+
+  /**
+   * Verify the provided Optimizely JWT token string
+   * @param token JWT token string to verify
+   * @returns boolean true if verification successful, false otherwise
+   * @throws Error if token is null, empty, or verifier is not properly configured
+   */
+  public async verify(token: string | undefined): Promise<boolean> {
+    if (!token || token.trim().length === 0) {
+      throw new Error('Token cannot be null or empty');
+    }
+
+    return this.verifyToken(token);
+  }
+
+  private static getInstance(): TokenVerifier {
+    if (!TokenVerifier.instance) {
+      TokenVerifier.instance = new TokenVerifier();
+    }
+    return TokenVerifier.instance;
+  }
+
+  /**
+   * Get singleton instance of TokenVerifier and ensure it's initialized
+   * @returns Promise<TokenVerifier> - initialized singleton instance
+   */
+  public static async getInitializedInstance(): Promise<TokenVerifier> {
+    const instance = TokenVerifier.getInstance();
+    if (!instance.initialized) {
+      await instance.initialize();
+    }
+    return instance;
+  }
+
+  /**
+   * Initialize the TokenVerifier with discovery document from well-known endpoint
+   */
+  private async initialize(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+
+    try {
+      // Use prep URL when environment variable is set to 'staging', otherwise use prod
+      const environment = process.env.environment || 'production';
+      const baseUrl = environment === 'staging' ? PREP_BASE_URL : PROD_BASE_URL;
+      const discoveryDocument = await this.fetchDiscoveryDocument(baseUrl);
+      this.issuer = discoveryDocument.issuer;
+      this.jwksUri = discoveryDocument.jwks_uri;
+      this.jwks = createRemoteJWKSet(new URL(this.jwksUri), {
+        cacheMaxAge: DEFAULT_JWKS_EXPIRES_IN,
+        cooldownDuration: DEFAULT_JWKS_EXPIRES_IN
+      });
+      this.initialized = true;
+      logger.info(`TokenVerifier initialized with issuer: ${this.issuer} (environment: ${environment})`);
+    } catch (error) {
+      logger.error('Failed to initialize TokenVerifier', error);
+      // Re-throw the original error to preserve specific error messages for tests
+      throw error;
+    }
+  }
+
+  /**
+   * Fetch discovery document from well-known endpoint
+   */
+  private async fetchDiscoveryDocument(baseUrl: string): Promise<DiscoveryDocument> {
+    const wellKnownUrl = `${baseUrl}/.well-known/oauth-authorization-server`;
+
+    const response = await fetch(wellKnownUrl);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch discovery document: ${response.status} ${response.statusText}`);
+    }
+    const discoveryDocument = await response.json() as DiscoveryDocument;
+    if (!discoveryDocument.issuer || !discoveryDocument.jwks_uri) {
+      throw new Error('Invalid discovery document: missing issuer or jwks_uri');
+    }
+
+    return discoveryDocument;
+  }
+
+  private async verifyToken(token: string): Promise<boolean> {
+    if (!this.initialized) {
+      throw new Error('TokenVerifier not initialized. Call initialize() first.');
+    }
+
+    if (!this.jwks || !this.issuer) {
+      throw new Error('TokenVerifier not properly configured.');
+    }
+
+    try {
+      await jwtVerify(token, this.jwks, {
+        issuer: this.issuer,
+        audience: AUDIENCE,
+        clockTolerance: DEFAULT_LEEWAY,
+      });
+      return true;
+    } catch (error) {
+      logger.error('Token verification failed:', error);
+      return false;
+    }
+  }
+
+}
+
+export const getTokenVerifier = async (): Promise<TokenVerifier> => TokenVerifier.getInitializedInstance();

package/src/decorator/Decorator.test.ts

@@ -519,5 +519,131 @@ describe('Decorators', () => {
       );
     });
   });
+
+  describe('handler instance context', () => {
+    it('should allow tool handler to call class methods', async () => {
+      class TestClass {
+        private getValue() {
+          return 'class-method-called';
+        }
+
+        @tool({
+          name: 'instanceMethodTest',
+          description: 'Test calling class methods',
+          parameters: [],
+          endpoint: '/instance-method-test'
+        })
+        public async instanceMethodTest(_params: any) {
+          return { result: this.getValue() };
+        }
+      }
+
+      // Get the registered handler
+      const mockedRegisterTool = jest.mocked(toolsService.registerTool);
+      const registerToolCall = mockedRegisterTool.mock.calls.find((call) => call[0] === 'instanceMethodTest');
+      const registeredHandler = registerToolCall![2];
+
+      // Call the handler
+      const result = await registeredHandler(undefined as any, {}, {});
+
+      // Should be able to call class methods through 'this'
+      expect((result as any).result).toBe('class-method-called');
+      expect(TestClass).toBeDefined();
+    });
+
+    it('should allow interaction handler to call class methods', async () => {
+      class TestClass {
+        private processData() {
+          return 'interaction-processed';
+        }
+
+        @interaction({
+          name: 'instanceInteractionTest',
+          endpoint: '/instance-interaction-test'
+        })
+        public async instanceInteractionTest(_data: any) {
+          return { message: this.processData() };
+        }
+      }
+
+      // Get the registered handler
+      const mockedRegisterInteraction = jest.mocked(toolsService.registerInteraction);
+      const registerInteractionCall = mockedRegisterInteraction.mock.calls.find(
+        (call) => call[0] === 'instanceInteractionTest'
+      );
+      const registeredHandler = registerInteractionCall![1];
+
+      // Call the handler
+      const result = await registeredHandler(undefined as any, {});
+
+      // Should be able to call class methods through 'this'
+      expect((result as any).message).toBe('interaction-processed');
+      expect(TestClass).toBeDefined();
+    });
+
+    it('should handle invalid functionContext gracefully for tool', async () => {
+      class TestClass {
+        private getValue() {
+          return 'class-method-called';
+        }
+
+        @tool({
+          name: 'invalidContextTest',
+          description: 'Test handling invalid context',
+          parameters: [],
+          endpoint: '/invalid-context-test'
+        })
+        public async invalidContextTest(_params: any) {
+          return { result: this.getValue() };
+        }
+      }
+
+      // Get the registered handler
+      const mockedRegisterTool = jest.mocked(toolsService.registerTool);
+      const registerToolCall = mockedRegisterTool.mock.calls.find((call) => call[0] === 'invalidContextTest');
+      const registeredHandler = registerToolCall![2];
+
+      // Call the handler with an invalid functionContext (truthy but wrong type)
+      // This should trigger the instanceof check and create a new instance instead
+      const invalidContext = { notAnInstance: true, someOtherProperty: 'invalid' };
+      const result = await registeredHandler(invalidContext as any, {}, {});
+
+      // Should still work by creating a new instance
+      expect((result as any).result).toBe('class-method-called');
+      expect(TestClass).toBeDefined();
+    });
+
+    it('should handle invalid functionContext gracefully for interaction', async () => {
+      class TestClass {
+        private processData() {
+          return 'interaction-processed';
+        }
+
+        @interaction({
+          name: 'invalidContextInteractionTest',
+          endpoint: '/invalid-context-interaction-test'
+        })
+        public async invalidContextInteractionTest(_data: any) {
+          return { message: this.processData() };
+        }
+      }
+
+      // Get the registered handler
+      const mockedRegisterInteraction = jest.mocked(toolsService.registerInteraction);
+      const registerInteractionCall = mockedRegisterInteraction.mock.calls.find(
+        (call) => call[0] === 'invalidContextInteractionTest'
+      );
+      const registeredHandler = registerInteractionCall![1];
+
+      // Call the handler with an invalid functionContext (truthy but wrong type)
+      // This should trigger the instanceof check and create a new instance instead
+      const invalidContext = { notAnInstance: true, someOtherProperty: 'invalid' };
+      const result = await registeredHandler(invalidContext as any, {});
+
+      // Should still work by creating a new instance
+      expect((result as any).message).toBe('interaction-processed');
+      expect(TestClass).toBeDefined();
+    });
+  });
 });
 

package/src/decorator/Decorator.ts

@@ -42,9 +42,10 @@ export interface InteractionConfig {
 /**
  * Decorator for registering tool functions
  * Immediately registers the tool with the global ToolsService
+ * The handler will have access to 'this' context when called
  */
 export function tool(config: ToolConfig) {
-  return function(_target: any, _propertyKey: string, descriptor: PropertyDescriptor) {
+  return function(target: any, _propertyKey: string, descriptor: PropertyDescriptor) {
     // Convert parameter configs to Parameter instances
     const parameters = (config.parameters || []).map((p) =>
       new Parameter(p.name, p.type, p.description, p.required)
@@ -55,11 +56,24 @@ export function tool(config: ToolConfig) {
       new AuthRequirement(a.provider, a.scopeBundle, a.required)
     );
 
+    const originalMethod = descriptor.value;
+
+    const boundHandler = function(functionContext: any, params: any, authData: any) {
+      // Check if we're being called from within a ToolFunction instance context
+      // If so, use that instance; otherwise create a new one
+      const instance = (functionContext && functionContext instanceof target.constructor) ?
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+        functionContext : new target.constructor();
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+      return originalMethod.call(instance, params, authData);
+    };
+
     // Immediately register with global ToolsService
     toolsService.registerTool(
       config.name,
       config.description,
-      descriptor.value,
+      boundHandler,
       parameters,
       config.endpoint,
       authRequirements
@@ -70,13 +84,27 @@ export function tool(config: ToolConfig) {
 /**
  * Decorator for registering interaction functions
  * Immediately registers the interaction with the global ToolsService
+ * The handler will have access to 'this' context when called
  */
 export function interaction(config: InteractionConfig) {
-  return function(_target: any, _propertyKey: string, descriptor: PropertyDescriptor) {
+  return function(target: any, _propertyKey: string, descriptor: PropertyDescriptor) {
+    const originalMethod = descriptor.value;
+
+    const boundHandler = function(functionContext: any, data: any, authData?: any) {
+      // Check if we're being called from within a ToolFunction instance context
+      // If so, use that instance; otherwise create a new one
+      const instance = (functionContext && functionContext instanceof target.constructor) ?
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+        functionContext : new target.constructor();
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+      return originalMethod.call(instance, data, authData);
+    };
+
     // Immediately register with global ToolsService
     toolsService.registerInteraction(
       config.name,
-      descriptor.value,
+      boundHandler,
       config.endpoint
     );
   };