@optimizely-opal/opal-tool-ocp-sdk 0.0.0-beta.11 → 0.0.0-beta.13

package/README.md

@@ -7,10 +7,11 @@ A TypeScript SDK for building Opal tools in Optimizely Connect Platform. This SD
 ## Features
 
 - 🎯 **Decorator-based Tool Registration** - Use `@tool` and `@interaction` decorators to easily register functions
+- 🌐 **Global and Regular Function Modes** - SDK can be used in either global or organization-scoped mode
 - 🔧 **Type-safe Development** - Full TypeScript support with comprehensive type definitions  
-- 🏗️ **Abstract Base Classes** - Extend `ToolFunction` for standardized request processing
+- 🏗️ **Abstract Base Classes** - Extend `ToolFunction` or `GlobalToolFunction` for standardized request processing
 - 🔐 **Authentication Support** - OptiID authentication
-- 🛡️ **Authorization Support** - Bearer token tool authorization
+- 🛡️ **Authorization Support** - OptiID token tool authorization
 - 📝 **Parameter Validation** - Define and validate tool parameters with types
 - 🧪 **Comprehensive Testing** - Fully tested with Jest
 
@@ -28,7 +29,14 @@ yarn add @optimizely-opal/opal-tool-ocp-sdk
 
 ## Quick Start
 
-Create a tool function class by extending `ToolFunction` and registering your tools and interactions:
+The SDK supports two function modes:
+
+- **Regular Functions** (`ToolFunction`) - Organization-scoped functions that validate customer organization IDs
+- **Global Functions** (`GlobalToolFunction`) - Platform-wide functions that work across all organizations
+
+### Regular Tool Function
+
+Create a tool function class by extending `ToolFunction` for organization-scoped functionality:
 
 ```typescript
 import { ToolFunction, tool, interaction, ParameterType, InteractionResult, OptiIdAuthData } from '@optimizely-opal/opal-tool-ocp-sdk';
@@ -89,12 +97,12 @@ export class MyToolFunction extends ToolFunction {
       throw new Error('OptiID authentication required');
     }
 
-    const { customerId, instanceId, accessToken } = authData.credentials;
+    const { customer_id, instance_id, access_token } = authData.credentials;
     return {
       id: '456',
       title: params.title,
-      customerId,
-      instanceId
+      customer_id,
+      instance_id
     };
   }
 
@@ -112,10 +120,50 @@ export class MyToolFunction extends ToolFunction {
 }
 ```
 
-Your function class inherits a `perform()` method from `ToolFunction` that serves as the main entry point for handling all incoming requests. When called, the SDK automatically:
+### Global Tool Function
+
+Create a global tool function by extending `GlobalToolFunction` for platform-wide functionality:
+
+```typescript
+import { GlobalToolFunction, tool, interaction, ParameterType, InteractionResult, OptiIdAuthData } from '@optimizely-opal/opal-tool-ocp-sdk';
+
+export class MyGlobalToolFunction extends GlobalToolFunction {
+
+  @tool({
+    name: 'global_utility',
+    description: 'A utility tool available to all organizations',
+    endpoint: '/global-utility',
+    parameters: [
+      {
+        name: 'operation',
+        type: ParameterType.String,
+        description: 'The operation to perform',
+        required: true
+      }
+    ]
+  })
+  async globalUtility(params: { operation: string }, authData?: OptiIdAuthData) {
+    return {
+      result: `Performed ${params.operation} globally`,
+      organizationId: authData?.credentials.customer_id || 'unknown'
+    };
+  }
+}
+```
+
+### Function Modes
+
+The SDK operates in one of two modes based on the base class you extend:
+
+- **Regular Function Mode** (`ToolFunction`): All tools are organization-scoped and validate organization IDs
+- **Global Function Mode** (`GlobalToolFunction`): All tools are platform-wide.
+
+The discovery endpoint returns all tools registered within that function mode.
+
+Your function class inherits a `perform()` method from `ToolFunction` or `GlobalToolFunction` that serves as the main entry point for handling all incoming requests. When called, the SDK automatically:
 
 - **Routes requests** to your registered tools and interactions based on endpoints
-- **Handles authentication** and bearer token validation before calling your methods  
+- **Handles authentication** and OptiID token validation before calling your methods  
 - **Provides discovery** at `/discovery` endpoint for OCP platform integration
 - **Returns proper HTTP responses** with correct status codes and JSON formatting
 
@@ -129,6 +177,28 @@ Tools are functions that can be discovered and executed through the OCP platform
 - Define parameters with types and validation
 - Can require authentication
 - Return structured responses
+- Are automatically registered based on the function mode you choose
+
+### Function Modes
+
+#### Regular Functions (`ToolFunction`)
+
+Regular functions are scoped to specific organizations and validate that requests come from the same organization:
+
+- Validate OptiID organization ID matches the function's organization context
+- All tools within the function are organization-scoped
+- **Per-Organization Configuration**: Can implement organization-specific configuration, authentication credentials, and API keys since they're tied to a single organization
+- **Per-Organization Authentication**: Can store and use organization-specific authentication tokens, connection strings, and other sensitive data securely
+
+#### Global Functions (`GlobalToolFunction`)
+
+Global functions work across all organizations without organization validation:
+
+- Accept OptiID authentication
+- All tools within the function are platform-wide
+- **No Per-Organization Configuration**: Cannot implement per-organization configuration since they work across all organizations
+- **No Per-Organization Authentication**: Cannot store organization-specific credentials or authentication data
+- **Global Discovery**: Have a global discovery URL that can be used by any organization without requiring them to install the app first
 
 ### Interactions
 
@@ -169,29 +239,19 @@ interface AuthRequirementConfig {
 }
 ```
 
-#### Bearer Token Support
+#### OptiID Token Authorization
 
-The SDK automatically extracts Bearer tokens from the `authorization` header for tool authorization. When users register tools in Opal, they can specify a Bearer token that Opal will include in requests to validate the tool's identity.
+The SDK automatically handles OptiID token validation for tool authorization. OptiID tokens provide both user authentication and authorization for tools, ensuring that only authenticated users with proper permissions can access your tools.
 
 **Token Validation:**
-- Bearer tokens are extracted from the `authorization: Bearer <token>` header
-- Empty strings and `undefined` tokens are treated as missing (no validation performed)
-- **Optionally override** the `validateBearerToken(token: string): boolean` method to implement custom validation logic
-- The default implementation returns `true` (accepts all tokens) - override if you need custom authorization
-- If validation fails, returns HTTP 403 Forbidden before reaching your handler methods
+- The SDK extracts and validates OptiID tokens from the request body
+- **Regular Tools**: Validation includes verifying that requests come from the same organization as the tool
+- **Global Tools**: Token validation occurs but organization ID matching is skipped
+- If validation fails, returns HTTP 403 Unauthorized before reaching your handler methods
+- No additional configuration needed - validation is handled automatically
 
 ```typescript
 export class MyToolFunction extends ToolFunction {
-  // Optional: Override this method to implement custom bearer token validation
-  protected override validateBearerToken(token: string): boolean {
-    // If you don't need bearer token validation, don't override this method
-    // The default implementation returns true
-    
-    // For custom validation, compare against expected token
-    const expectedToken = process.env.OPAL_TOOL_TOKEN;
-    return token === expectedToken;
-  }
-
   @tool({
     name: 'secure_tool',
     description: 'Tool that validates requests from Opal',
@@ -215,15 +275,6 @@ export class MyToolFunction extends ToolFunction {
 }
 ```
 
-**Bearer Token Usage:**
-- Set by users when registering tools in Opal
-- Used to authorize tool requests from Opal instances  
-- Validates that requests are coming from trusted Opal sources
-- **Optionally override** the `validateBearerToken(token: string): boolean` method for custom authorization
-- Default implementation accepts all tokens - override for security
-- If validation fails, returns HTTP 403 Forbidden before reaching your handler methods
-
-
 ## API Reference
 
 ### Handler Function Signatures
@@ -240,7 +291,6 @@ async handlerMethod(
 - **params**: The input parameters for tools, or interaction data for webhooks
 - **authData**: Available when OptiID user authentication is configured and successful
 
-**Note**: Bearer token validation is handled automatically by the base class. If a bearer token is present and fails validation, the request is rejected before reaching your handler methods.
 
 ### Decorators
 
@@ -273,17 +323,29 @@ interface InteractionConfig {
 
 #### `ToolFunction`
 
-Abstract base class for OCP functions:
+Abstract base class for organization-scoped OCP functions:
 
 ```typescript
 export abstract class ToolFunction extends Function {
   protected ready(): Promise<boolean>;
   public async perform(): Promise<Response>;
-  protected validateBearerToken(token: string): boolean;
 }
 ```
 
-Extend this class and implement your OCP function. The `perform` method automatically routes requests to registered tools and handles bearer token validation. **You can optionally override the `validateBearerToken` method** to define custom bearer token authorization for your tools.
+Extend this class for regular tools that validate organization IDs. The `perform` method automatically routes requests to registered tools and enforces organization validation.
+
+#### `GlobalToolFunction`
+
+Abstract base class for global OCP functions:
+
+```typescript
+export abstract class GlobalToolFunction extends GlobalFunction {
+  protected ready(): Promise<boolean>;
+  public async perform(): Promise<Response>;
+}
+```
+
+Extend this class for tools that work across organizations. The `perform` method routes requests to registered tools but skips organization validation for tools.
 
 ### Models
 
@@ -302,7 +364,14 @@ The SDK automatically provides two important endpoints:
 
 ### Discovery Endpoint (`/discovery`)
 
-Returns all registered tools in the proper OCP format for platform integration:
+Returns all registered tools in the proper OCP format for platform integration. The discovery endpoint returns all tools registered within the function, regardless of their individual configuration:
+
+- **Regular Functions** (`ToolFunction`): Returns all tools with organization-scoped behavior
+- **Global Functions** (`GlobalToolFunction`): Returns all tools with platform-wide behavior
+
+All tools within a function operate in the same mode - there is no mixing of global and organization-scoped tools within a single function.
+
+Example response for a regular function and global function:
 
 ```json
 {
@@ -407,11 +476,6 @@ yarn lint
 import { ToolFunction, tool, interaction, ParameterType, OptiIdAuthData, InteractionResult } from '@optimizely-opal/opal-ocp-sdk';
 
 export class AuthenticatedFunction extends ToolFunction {
-  // Optional: Override this method for custom bearer token validation
-  protected override validateBearerToken(token: string): boolean {
-    const expectedToken = process.env.OPAL_TOOL_TOKEN;
-    return token === expectedToken;
-  }
 
   // OptiID authentication example
   @tool({
@@ -424,9 +488,9 @@ export class AuthenticatedFunction extends ToolFunction {
   async secureOperation(params: unknown, authData?: OptiIdAuthData) {
     if (!authData) throw new Error('OptiID authentication required');
     
-    const { customerId, accessToken } = authData.credentials;
+    const { customer_id, access_token } = authData.credentials;
     // Use OptiID credentials for API calls
-    return { success: true, customerId };
+    return { success: true, customer_id };
   }
 
   // Interaction with authentication example
@@ -439,11 +503,11 @@ export class AuthenticatedFunction extends ToolFunction {
       return new InteractionResult('Authentication required for webhook processing');
     }
 
-    const { customerId } = authData.credentials;
+    const { customer_id } = authData.credentials;
     
     // Process webhook data with authentication context
     return new InteractionResult(
-      `Webhook processed for customer ${customerId}: ${data.eventType}`,
+      `Webhook processed for customer ${customer_id}: ${data.eventType}`,
       `https://app.example.com/events/${data.eventId}`
     );
   }
@@ -461,7 +525,8 @@ src/
 │   ├── index.ts
 │   ├── TaskTool.ts
 │   └── NotificationTool.ts
-└── MyToolFunction.ts
+├── MyToolFunction.ts
+└── MyGlobalToolFunction.ts
 ```
 
 **tools/TaskTool.ts:**
@@ -573,12 +638,6 @@ import { ToolFunction } from '@optimizely-opal/opal-ocp-sdk';
 import * from './tools';
 
 export class MyToolFunction extends ToolFunction {
-
-  // Optional: Override this method for custom bearer token validation
-  protected override validateBearerToken(token: string): boolean {
-    const expectedToken = process.env.OPAL_TOOL_TOKEN;
-    return token === expectedToken;
-  }
 }
 ```
 

package/dist/auth/AuthUtils.d.ts

@@ -0,0 +1,26 @@
+import { OptiIdAuthData } from '../types/Models';
+/**
+ * Extract and validate basic OptiID authentication data from request
+ *
+ * @param request - The incoming request
+ * @returns object with authData and accessToken, or null if invalid
+ */
+export declare function extractAuthData(request: any): {
+    authData: OptiIdAuthData;
+    accessToken: string;
+} | null;
+/**
+ * Authenticate a request for regular functions (with organization validation)
+ *
+ * @param request - The incoming request
+ * @returns true if authentication and authorization succeed
+ */
+export declare function authenticateRegularRequest(request: any): Promise<boolean>;
+/**
+ * Authenticate a request for global functions (without organization validation)
+ *
+ * @param request - The incoming request
+ * @returns true if authentication succeeds
+ */
+export declare function authenticateGlobalRequest(request: any): Promise<boolean>;
+//# sourceMappingURL=AuthUtils.d.ts.map

package/dist/auth/AuthUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthUtils.d.ts","sourceRoot":"","sources":["../../src/auth/AuthUtils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAqBjD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,GAAG,GAAG;IAAE,QAAQ,EAAE,cAAc,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAStG;AA4DD;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAE/E;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAE9E"}

package/dist/auth/AuthUtils.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractAuthData = extractAuthData;
+exports.authenticateRegularRequest = authenticateRegularRequest;
+exports.authenticateGlobalRequest = authenticateGlobalRequest;
+const app_sdk_1 = require("@zaiusinc/app-sdk");
+const TokenVerifier_1 = require("./TokenVerifier");
+/**
+ * Validate the OptiID access token
+ *
+ * @param accessToken - The access token to validate
+ * @returns true if the token is valid
+ */
+async function validateAccessToken(accessToken) {
+    try {
+        if (!accessToken) {
+            return false;
+        }
+        const tokenVerifier = await (0, TokenVerifier_1.getTokenVerifier)();
+        return await tokenVerifier.verify(accessToken);
+    }
+    catch (error) {
+        app_sdk_1.logger.error('OptiID token validation failed:', error);
+        return false;
+    }
+}
+/**
+ * Extract and validate basic OptiID authentication data from request
+ *
+ * @param request - The incoming request
+ * @returns object with authData and accessToken, or null if invalid
+ */
+function extractAuthData(request) {
+    const authData = request?.bodyJSON?.auth;
+    const accessToken = authData?.credentials?.access_token;
+    if (!accessToken || authData?.provider?.toLowerCase() !== 'optiid') {
+        app_sdk_1.logger.error('OptiID token is required but not provided');
+        return null;
+    }
+    return { authData, accessToken };
+}
+/**
+ * Validate organization ID matches the app context
+ *
+ * @param customerId - The customer ID from the auth data
+ * @returns true if the organization ID is valid
+ */
+function validateOrganizationId(customerId) {
+    if (!customerId) {
+        app_sdk_1.logger.error('Organisation ID is required but not provided');
+        return false;
+    }
+    const appOrganisationId = (0, app_sdk_1.getAppContext)()?.account?.organizationId;
+    if (customerId !== appOrganisationId) {
+        app_sdk_1.logger.error(`Invalid organisation ID: expected ${appOrganisationId}, received ${customerId}`);
+        return false;
+    }
+    return true;
+}
+/**
+ * Check if a request should skip authentication (discovery/ready endpoints)
+ *
+ * @param request - The incoming request
+ * @returns true if auth should be skipped
+ */
+function shouldSkipAuth(request) {
+    return request.path === '/discovery' || request.path === '/ready';
+}
+/**
+ * Core authentication flow - extracts auth data and validates token
+ *
+ * @param request - The incoming request
+ * @param validateOrg - Whether to validate organization ID
+ * @returns true if authentication succeeds
+ */
+async function authenticateRequest(request, validateOrg) {
+    if (shouldSkipAuth(request)) {
+        return true;
+    }
+    const authInfo = extractAuthData(request);
+    if (!authInfo) {
+        return false;
+    }
+    const { authData, accessToken } = authInfo;
+    // Validate organization ID if required
+    if (validateOrg && !validateOrganizationId(authData.credentials?.customer_id)) {
+        return false;
+    }
+    return await validateAccessToken(accessToken);
+}
+/**
+ * Authenticate a request for regular functions (with organization validation)
+ *
+ * @param request - The incoming request
+ * @returns true if authentication and authorization succeed
+ */
+async function authenticateRegularRequest(request) {
+    return await authenticateRequest(request, true);
+}
+/**
+ * Authenticate a request for global functions (without organization validation)
+ *
+ * @param request - The incoming request
+ * @returns true if authentication succeeds
+ */
+async function authenticateGlobalRequest(request) {
+    return await authenticateRequest(request, false);
+}
+//# sourceMappingURL=AuthUtils.js.map

package/dist/auth/AuthUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthUtils.js","sourceRoot":"","sources":["../../src/auth/AuthUtils.ts"],"names":[],"mappings":";;AA6BA,0CASC;AAkED,gEAEC;AAQD,8DAEC;AApHD,+CAA0D;AAC1D,mDAAmD;AAGnD;;;;;GAKG;AACH,KAAK,UAAU,mBAAmB,CAAC,WAA+B;IAChE,IAAI,CAAC;QACH,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,aAAa,GAAG,MAAM,IAAA,gCAAgB,GAAE,CAAC;QAC/C,OAAO,MAAM,aAAa,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IACjD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,gBAAM,CAAC,KAAK,CAAC,iCAAiC,EAAE,KAAK,CAAC,CAAC;QACvD,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAgB,eAAe,CAAC,OAAY;IAC1C,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,EAAE,IAAsB,CAAC;IAC3D,MAAM,WAAW,GAAG,QAAQ,EAAE,WAAW,EAAE,YAAY,CAAC;IACxD,IAAI,CAAC,WAAW,IAAI,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,QAAQ,EAAE,CAAC;QACnE,gBAAM,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC1D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;AACnC,CAAC;AAED;;;;;GAKG;AACH,SAAS,sBAAsB,CAAC,UAA8B;IAC5D,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,gBAAM,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;QAC7D,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,iBAAiB,GAAG,IAAA,uBAAa,GAAE,EAAE,OAAO,EAAE,cAAc,CAAC;IACnE,IAAI,UAAU,KAAK,iBAAiB,EAAE,CAAC;QACrC,gBAAM,CAAC,KAAK,CAAC,qCAAqC,iBAAiB,cAAc,UAAU,EAAE,CAAC,CAAC;QAC/F,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,SAAS,cAAc,CAAC,OAAY;IAClC,OAAO,OAAO,CAAC,IAAI,KAAK,YAAY,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC;AACpE,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,mBAAmB,CAAC,OAAY,EAAE,WAAoB;IACnE,IAAI,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IAC1C,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,QAAQ,CAAC;IAE3C,uCAAuC;IACvC,IAAI,WAAW,IAAI,CAAC,sBAAsB,CAAC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,EAAE,CAAC;QAC9E,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,MAAM,mBAAmB,CAAC,WAAW,CAAC,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,0BAA0B,CAAC,OAAY;IAC3D,OAAO,MAAM,mBAAmB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AAClD,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,yBAAyB,CAAC,OAAY;IAC1D,OAAO,MAAM,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AACnD,CAAC"}

package/dist/auth/AuthUtils.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=AuthUtils.test.d.ts.map

package/dist/auth/AuthUtils.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthUtils.test.d.ts","sourceRoot":"","sources":["../../src/auth/AuthUtils.test.ts"],"names":[],"mappings":""}