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

package/README.md

@@ -10,7 +10,7 @@ A TypeScript SDK for building Opal tools in Optimizely Connect Platform. This SD
 - 🔧 **Type-safe Development** - Full TypeScript support with comprehensive type definitions  
 - 🏗️ **Abstract Base Classes** - Extend `ToolFunction` for standardized request processing
 - 🔐 **Authentication Support** - OptiID authentication
-- 🛡️ **Authorization Support** - OptiID token tool authorization
+- 🛡️ **Authorization Support** - Bearer token tool authorization
 - 📝 **Parameter Validation** - Define and validate tool parameters with types
 - 🧪 **Comprehensive Testing** - Fully tested with Jest
 
@@ -115,7 +115,7 @@ 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:
 
 - **Routes requests** to your registered tools and interactions based on endpoints
-- **Handles authentication** and OptiID token validation before calling your methods  
+- **Handles authentication** and bearer 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
 
@@ -169,18 +169,29 @@ interface AuthRequirementConfig {
 }
 ```
 
-#### OptiID Token Authorization
+#### Bearer Token Support
 
-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.
+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.
 
 **Token Validation:**
-- The SDK extracts and validates OptiID tokens from the request body
-- Validation includes verifying that requests come from the same organization
-- If validation fails, returns HTTP 403 Unauthorized before reaching your handler methods
-- No additional configuration needed - validation is handled automatically
+- 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
 
 ```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',
@@ -204,6 +215,15 @@ 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
@@ -220,6 +240,8 @@ 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
 
 #### `@tool(config: ToolConfig)`
@@ -257,10 +279,11 @@ Abstract base class for OCP functions:
 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.
+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.
 
 ### Models
 
@@ -384,6 +407,11 @@ 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({
@@ -545,6 +573,12 @@ 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/function/ToolFunction.d.ts

@@ -18,11 +18,14 @@ export declare abstract class ToolFunction extends Function {
      */
     perform(): Promise<Response>;
     /**
-     * Authenticate the incoming request by validating the OptiID token and organization ID
+     * Validates the bearer token for authorization.
      *
-     * @throws true if authentication succeeds
+     * This method provides a default implementation that accepts all tokens.
+     * Subclasses can override this method to implement custom bearer token validation logic.
+     *
+     * @param _bearerToken - The bearer token extracted from the Authorization header
+     * @returns true if the token is valid and the request should proceed, false to return 403 Forbidden
      */
-    private authorizeRequest;
-    private validateAccessToken;
+    protected validateBearerToken(_bearerToken: string): boolean;
 }
 //# sourceMappingURL=ToolFunction.d.ts.map

package/dist/function/ToolFunction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ToolFunction.d.ts","sourceRoot":"","sources":["../../src/function/ToolFunction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAA0C,MAAM,mBAAmB,CAAC;AAK/F;;;GAGG;AACH,8BAAsB,YAAa,SAAQ,QAAQ;IAEjD;;;;;OAKG;IACH,SAAS,CAAC,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;IAInC;;;;OAIG;IACU,OAAO,IAAI,OAAO,CAAC,QAAQ,CAAC;IAczC;;;;OAIG;YACW,gBAAgB;YA2BhB,mBAAmB;CAalC"}
+{"version":3,"file":"ToolFunction.d.ts","sourceRoot":"","sources":["../../src/function/ToolFunction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAmB,MAAM,mBAAmB,CAAC;AAGxE;;;GAGG;AACH,8BAAsB,YAAa,SAAQ,QAAQ;IAEjD;;;;;OAKG;IACH,SAAS,CAAC,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;IAInC;;;;OAIG;IACU,OAAO,IAAI,OAAO,CAAC,QAAQ,CAAC;IAezC;;;;;;;;OAQG;IACH,SAAS,CAAC,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;CAG7D"}

package/dist/function/ToolFunction.js

@@ -3,7 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ToolFunction = void 0;
 const app_sdk_1 = require("@zaiusinc/app-sdk");
 const Service_1 = require("../service/Service");
-const TokenVerifier_1 = require("../auth/TokenVerifier");
 /**
  * Abstract base class for tool-based function execution
  * Provides a standard interface for processing requests through registered tools
@@ -25,7 +24,8 @@ class ToolFunction extends app_sdk_1.Function {
      */
     async perform() {
         (0, app_sdk_1.amendLogContext)({ opalThreadId: this.request.headers.get('x-opal-thread-id') || '' });
-        if (!(await this.authorizeRequest())) {
+        const bearerToken = Service_1.toolsService.extractBearerToken(this.request.headers);
+        if (bearerToken && !this.validateBearerToken(bearerToken)) {
             return new app_sdk_1.Response(403, { error: 'Forbidden' });
         }
         if (this.request.path === '/ready') {
@@ -36,45 +36,16 @@ class ToolFunction extends app_sdk_1.Function {
         return Service_1.toolsService.processRequest(this.request, this);
     }
     /**
-     * Authenticate the incoming request by validating the OptiID token and organization ID
+     * Validates the bearer token for authorization.
      *
-     * @throws true if authentication succeeds
+     * This method provides a default implementation that accepts all tokens.
+     * Subclasses can override this method to implement custom bearer token validation logic.
+     *
+     * @param _bearerToken - The bearer token extracted from the Authorization header
+     * @returns true if the token is valid and the request should proceed, false to return 403 Forbidden
      */
-    async authorizeRequest() {
-        if (this.request.path === '/discovery' || this.request.path === '/ready') {
-            return true;
-        }
-        app_sdk_1.logger.debug('Authorizing request:', this.request.bodyJSON);
-        const authData = this.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 false;
-        }
-        const customerId = authData.credentials?.customer_id;
-        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 await this.validateAccessToken(accessToken);
-    }
-    async 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;
-        }
+    validateBearerToken(_bearerToken) {
+        return true;
     }
 }
 exports.ToolFunction = ToolFunction;

package/dist/function/ToolFunction.js.map

@@ -1 +1 @@
-{"version":3,"file":"ToolFunction.js","sourceRoot":"","sources":["../../src/function/ToolFunction.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ToolFunction.js","sourceRoot":"","sources":["../../src/function/ToolFunction.ts"],"names":[],"mappings":";;;AAAA,+CAAwE;AACxE,gDAAkD;AAElD;;;GAGG;AACH,MAAsB,YAAa,SAAQ,kBAAQ;IAEjD;;;;;OAKG;IACO,KAAK;QACb,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,OAAO;QAClB,IAAA,yBAAe,EAAC,EAAE,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACtF,MAAM,WAAW,GAAG,sBAAY,CAAC,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC1E,IAAI,WAAW,IAAI,CAAC,IAAI,CAAC,mBAAmB,CAAC,WAAW,CAAC,EAAE,CAAC;YAC1D,OAAO,IAAI,kBAAQ,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;QACnD,CAAC;QAED,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACnC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;YACnC,OAAO,IAAI,kBAAQ,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;QAC/C,CAAC;QACD,4EAA4E;QAC5E,OAAO,sBAAY,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACzD,CAAC;IAED;;;;;;;;OAQG;IACO,mBAAmB,CAAC,YAAoB;QAChD,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AA5CD,oCA4CC"}