@inkeep/agents-sdk 0.41.2 → 0.43.0

package/README.md

@@ -58,7 +58,7 @@ const token = await credentials.get('MY_TOKEN'); // Returns 'env-token'
 | Type | Description | Requirements |
 |------|-------------|--------------|
 | `memory` | In-memory storage with env var fallback | None (default) |
-| `keychain` | OS keychain storage | `keytar` package |
+| `keychain` | OS keychain storage | `@napi-rs/keyring` package |
 | `nango` | OAuth credential management | `@nangohq/node`, `@nangohq/types` |
 | `custom` | Your own implementation | Implement `CredentialStore` interface |
 
@@ -117,6 +117,359 @@ tracer.startActiveSpan('my-operation', (span) => {
 | `ConsoleTelemetryProvider` | Logs to console | None |
 | Custom OpenTelemetry | Full observability | `@opentelemetry/*` packages |
 
+## Webhook Triggers with Signature Verification
+
+Webhook triggers allow your agents to be invoked by external services like GitHub, Slack, Stripe, and Zendesk. The SDK provides flexible HMAC signature verification to ensure webhook requests are authentic.
+
+### Basic Webhook Trigger
+
+Create a simple webhook trigger without signature verification:
+
+```typescript
+import { trigger, credentialReference } from '@inkeep/agents-sdk';
+
+export const myWebhook = trigger({
+  id: 'github-webhook',
+  name: 'GitHub Webhook',
+  description: 'Triggered by GitHub push events',
+});
+```
+
+### Webhook Signature Verification
+
+Different webhook providers use different signature patterns. The SDK supports all common patterns through flexible configuration.
+
+#### Quick Examples
+
+**GitHub Webhooks:**
+
+```typescript
+import { trigger, credentialReference } from '@inkeep/agents-sdk';
+
+export const githubWebhook = trigger({
+  id: 'github-webhook',
+  name: 'GitHub Webhook',
+  description: 'Verified GitHub webhook',
+  signingSecretCredentialReference: credentialReference({
+    id: 'github-webhook-secret',
+  }),
+  signatureVerification: {
+    algorithm: 'sha256',
+    encoding: 'hex',
+    signature: {
+      source: 'header',
+      key: 'X-Hub-Signature-256',
+      prefix: 'sha256=',
+    },
+    signedComponents: [
+      {
+        source: 'body',
+        required: true,
+      },
+    ],
+    componentJoin: {
+      strategy: 'concatenate',
+      separator: '',
+    },
+  },
+});
+```
+
+**Slack Webhooks:**
+
+```typescript
+export const slackWebhook = trigger({
+  id: 'slack-webhook',
+  name: 'Slack Webhook',
+  description: 'Verified Slack webhook',
+  signingSecretCredentialReference: credentialReference({
+    id: 'slack-signing-secret',
+  }),
+  signatureVerification: {
+    algorithm: 'sha256',
+    encoding: 'hex',
+    signature: {
+      source: 'header',
+      key: 'X-Slack-Signature',
+      prefix: 'v0=',
+    },
+    signedComponents: [
+      {
+        source: 'literal',
+        value: 'v0',
+        required: true,
+      },
+      {
+        source: 'header',
+        key: 'X-Slack-Request-Timestamp',
+        required: true,
+      },
+      {
+        source: 'body',
+        required: true,
+      },
+    ],
+    componentJoin: {
+      strategy: 'concatenate',
+      separator: ':',
+    },
+  },
+});
+```
+
+**Zendesk Webhooks:**
+
+```typescript
+export const zendeskWebhook = trigger({
+  id: 'zendesk-webhook',
+  name: 'Zendesk Webhook',
+  description: 'Verified Zendesk webhook',
+  signingSecretCredentialReference: credentialReference({
+    id: 'zendesk-signing-secret',
+  }),
+  signatureVerification: {
+    algorithm: 'sha256',
+    encoding: 'base64',
+    signature: {
+      source: 'header',
+      key: 'X-Zendesk-Webhook-Signature',
+    },
+    signedComponents: [
+      {
+        source: 'header',
+        key: 'X-Zendesk-Webhook-Signature-Timestamp',
+        required: true,
+      },
+      {
+        source: 'body',
+        required: true,
+      },
+    ],
+    componentJoin: {
+      strategy: 'concatenate',
+      separator: '',
+    },
+  },
+});
+```
+
+**Stripe Webhooks:**
+
+```typescript
+export const stripeWebhook = trigger({
+  id: 'stripe-webhook',
+  name: 'Stripe Webhook',
+  description: 'Verified Stripe webhook',
+  signingSecretCredentialReference: credentialReference({
+    id: 'stripe-webhook-secret',
+  }),
+  signatureVerification: {
+    algorithm: 'sha256',
+    encoding: 'hex',
+    signature: {
+      source: 'header',
+      key: 'Stripe-Signature',
+      regex: 'v1=([a-f0-9]+)',
+    },
+    signedComponents: [
+      {
+        source: 'header',
+        key: 'Stripe-Signature',
+        regex: 't=([0-9]+)',
+        required: true,
+      },
+      {
+        source: 'body',
+        required: true,
+      },
+    ],
+    componentJoin: {
+      strategy: 'concatenate',
+      separator: '.',
+    },
+  },
+});
+```
+
+### Configuration Reference
+
+#### SignatureVerificationConfig
+
+The `signatureVerification` object configures how webhook signatures are verified.
+
+**Fields:**
+
+- `algorithm` - HMAC algorithm: `'sha256'` | `'sha512'` | `'sha384'` | `'sha1'` | `'md5'`
+  - **Recommended:** `'sha256'` (most secure and widely supported)
+  - **Warning:** `'sha1'` and `'md5'` are cryptographically weak and only supported for legacy systems
+
+- `encoding` - Signature encoding: `'hex'` | `'base64'`
+  - **Default:** `'hex'` (used by most providers)
+
+- `signature` - Where and how to extract the signature from the request
+
+- `signedComponents` - Array of components that make up the signed data
+
+- `componentJoin` - How to join multiple components before verification
+
+- `validation` (optional) - Advanced validation options
+
+#### Signature Source
+
+The `signature` field specifies where to find the signature in the webhook request.
+
+**Fields:**
+
+- `source` - Location: `'header'` | `'query'` | `'body'`
+  - `'header'` - Extract from HTTP header (most common)
+  - `'query'` - Extract from URL query parameter
+  - `'body'` - Extract from request body using JMESPath
+
+- `key` - Identifier for the signature:
+  - For headers: Header name (e.g., `'X-Hub-Signature-256'`)
+  - For query params: Parameter name (e.g., `'signature'`)
+  - For body: JMESPath expression (e.g., `'signature'` or `'headers."X-Signature"'`)
+
+- `prefix` (optional) - Prefix to strip from signature (e.g., `'sha256='`, `'v0='`)
+
+- `regex` (optional) - Regular expression with capture group for complex formats (e.g., `'v1=([a-f0-9]+)'`)
+
+#### Signed Components
+
+The `signedComponents` array specifies what data was signed by the webhook provider. Components are joined in order using the `componentJoin` configuration.
+
+**Component Fields:**
+
+- `source` - Component location: `'header'` | `'body'` | `'literal'`
+  - `'header'` - Extract from HTTP header
+  - `'body'` - Extract from request body (uses entire body as string)
+  - `'literal'` - Use a fixed string value
+
+- `key` (optional) - Identifier:
+  - For headers: Header name (e.g., `'X-Slack-Request-Timestamp'`)
+  - For body: JMESPath expression (e.g., `'data.timestamp'`)
+  - Not used for literal components
+
+- `value` (optional) - Static string value (only for `source: 'literal'`)
+
+- `regex` (optional) - Regex with capture group to extract part of the value
+
+- `required` - Whether component must be present (default: `true`)
+  - If `false`, missing components are treated as empty strings
+
+#### Component Join
+
+The `componentJoin` field specifies how to combine multiple signed components.
+
+**Fields:**
+
+- `strategy` - Join strategy: `'concatenate'` (only option currently)
+
+- `separator` - String to insert between components:
+  - `''` (empty) - Direct concatenation (GitHub, Zendesk)
+  - `':'` - Colon separator (Slack)
+  - `'.'` - Dot separator (Stripe)
+
+#### Advanced Validation Options
+
+The optional `validation` field provides fine-grained control over verification behavior.
+
+**Fields:**
+
+- `headerCaseSensitive` (default: `false`) - Whether header names are case-sensitive
+  - `false` - Case-insensitive matching (HTTP standard, recommended)
+  - `true` - Exact case match required
+
+- `allowEmptyBody` (default: `true`) - Whether to allow requests with empty bodies
+  - `true` - Empty bodies are valid (some webhooks send header-only verification requests)
+  - `false` - Reject requests with empty bodies
+
+- `normalizeUnicode` (default: `false`) - Whether to normalize Unicode to NFC form
+  - `false` - Use raw body bytes
+  - `true` - Normalize to NFC before verification (handles different Unicode representations)
+
+**Example with validation options:**
+
+```typescript
+signatureVerification: {
+  algorithm: 'sha256',
+  encoding: 'hex',
+  signature: {
+    source: 'header',
+    key: 'X-Signature',
+  },
+  signedComponents: [{ source: 'body', required: true }],
+  componentJoin: { strategy: 'concatenate', separator: '' },
+  validation: {
+    headerCaseSensitive: true,
+    allowEmptyBody: false,
+    normalizeUnicode: true,
+  },
+},
+```
+
+### Migration from Legacy `signingSecret`
+
+**Breaking Change:** The legacy `signingSecret` parameter has been removed. All triggers must use credential references and the new `signatureVerification` configuration.
+
+**Before (deprecated):**
+
+```typescript
+export const webhook = trigger({
+  id: 'my-webhook',
+  signingSecret: 'my-secret-key', // ❌ No longer supported
+});
+```
+
+**After (current):**
+
+```typescript
+export const webhook = trigger({
+  id: 'my-webhook',
+  signingSecretCredentialReference: credentialReference({
+    id: 'webhook-secret',
+  }),
+  signatureVerification: {
+    algorithm: 'sha256',
+    encoding: 'hex',
+    signature: {
+      source: 'header',
+      key: 'X-Hub-Signature-256',
+      prefix: 'sha256=',
+    },
+    signedComponents: [{ source: 'body', required: true }],
+    componentJoin: { strategy: 'concatenate', separator: '' },
+  },
+});
+```
+
+### Security Best Practices
+
+1. **Always use credential references** - Never hardcode signing secrets in your code
+2. **Use strong algorithms** - Prefer `sha256` or stronger; avoid `sha1` and `md5`
+3. **Validate all webhooks** - Always configure signature verification for production webhooks
+4. **Use HTTPS** - Always receive webhooks over HTTPS to prevent man-in-the-middle attacks
+5. **Rotate secrets regularly** - Update signing secrets periodically
+6. **Monitor failed verifications** - Failed signature checks may indicate an attack
+
+### Troubleshooting
+
+**Signature verification always fails:**
+
+1. Verify your signing secret is correct in the credential store
+2. Check that the `algorithm` matches what the provider uses
+3. Verify the `encoding` (hex vs base64)
+4. Ensure `signedComponents` match what the provider actually signs
+5. Check the `separator` in `componentJoin`
+6. For body-based components, ensure you're not modifying the raw body
+
+**Provider-specific tips:**
+
+- **GitHub:** Requires `prefix: 'sha256='` and signs only the raw body
+- **Slack:** Signs three components with colons: `v0:{timestamp}:{body}`
+- **Stripe:** Uses regex extraction for both signature and timestamp from the same header
+- **Zendesk:** Uses base64 encoding instead of hex
+
 ## API Reference
 
 ### Builders
@@ -124,6 +477,7 @@ tracer.startActiveSpan('my-operation', (span) => {
 - `agent()` - Create an agent (top-level container with multiple sub-agents)
 - `subAgent()` - Create a sub-agent configuration
 - `tool()` - Create a tool configuration
+- `trigger()` - Create a webhook trigger configuration
 - `mcpServer()` - Create an MCP server configuration
 - `mcpTool()` - Create an MCP tool
 - `dataComponent()` - Create a data component
@@ -190,7 +544,7 @@ The SDK has minimal required dependencies. Advanced features require optional pa
 | Feature | Required Packages |
 |---------|------------------|
 | Nango credentials | `@nangohq/node`, `@nangohq/types` |
-| Keychain storage | `keytar` |
+| Keychain storage | `@napi-rs/keyring` |
 | OpenTelemetry | `@opentelemetry/api`, `@opentelemetry/sdk-node` |
 
 Install only what you need:

package/dist/agent.d.ts

@@ -1,3 +1,4 @@
+import { Trigger, TriggerInterface } from "./trigger.js";
 import { AgentConfig, AgentInterface, AllDelegateInputInterface, GenerateOptions, MessageInput, ModelSettings, RunResult, StreamResponse, SubAgentInterface, subAgentTeamAgentInterface } from "./types.js";
 import { AgentStopWhen, FullAgentDefinition, StatusUpdateSettings } from "@inkeep/agents-core";
 
@@ -19,102 +20,112 @@ declare class Agent implements AgentInterface {
   private statusUpdateSettings?;
   private prompt?;
   private stopWhen?;
+  private triggers;
+  private triggerMap;
   constructor(config: AgentConfig);
   /**
-   * Set or update the configuration (tenantId, projectId and apiUrl)
-   * This is used by the CLI to inject configuration from inkeep.config.ts
-   */
+  * Set or update the configuration (tenantId, projectId and apiUrl)
+  * This is used by the CLI to inject configuration from inkeep.config.ts
+  */
   setConfig(tenantId: string, projectId: string, apiUrl: string): void;
   /**
-   * Convert the Agent to FullAgentDefinition format for the new agent endpoint
-   */
+  * Convert the Agent to FullAgentDefinition format for the new agent endpoint
+  */
   toFullAgentDefinition(): Promise<FullAgentDefinition>;
   /**
-   * Initialize all tools in all agents (especially IPCTools that need MCP server URLs)
-   */
+  * Initialize all tools in all agents (especially IPCTools that need MCP server URLs)
+  */
   private initializeAllTools;
   /**
-   * Initialize the agent and all agents in the backend using the new agent endpoint
-   */
+  * Initialize the agent and all agents in the backend using the new agent endpoint
+  */
   init(): Promise<void>;
   /**
-   * Generate a response using the default agent
-   */
+  * Generate a response using the default agent
+  */
   generate(input: MessageInput, options?: GenerateOptions): Promise<string>;
   /**
-   * Stream a response using the default agent
-   */
+  * Stream a response using the default agent
+  */
   stream(input: MessageInput, options?: GenerateOptions): Promise<StreamResponse>;
   /**
-   * Alias for stream() method for consistency with naming patterns
-   */
+  * Alias for stream() method for consistency with naming patterns
+  */
   generateStream(input: MessageInput, options?: GenerateOptions): Promise<StreamResponse>;
   /**
-   * Run with a specific agent from the agent
-   */
+  * Run with a specific agent from the agent
+  */
   runWith(subAgentId: string, input: MessageInput, options?: GenerateOptions): Promise<RunResult>;
   /**
-   * Get an agent by name (unified method for all agent types)
-   */
+  * Get an agent by name (unified method for all agent types)
+  */
   getSubAgent(name: string): SubAgentInterface | undefined;
   /**
-   * Add an agent to the agent
-   */
+  * Add an agent to the agent
+  */
   addSubAgent(agent: SubAgentInterface): void;
   /**
-   * Remove an agent from the agent
-   */
+  * Remove an agent from the agent
+  */
   removeSubAgent(id: string): boolean;
   /**
-   * Get all agents in the agent
-   */
+  * Get all agents in the agent
+  */
   getSubAgents(): SubAgentInterface[];
   /**
-   * Get all agent ids (unified method for all agent types)
-   */
+  * Get all agent ids (unified method for all agent types)
+  */
   getSubAgentIds(): string[];
   /**
-   * Set the default agent
-   */
+  * Set the default agent
+  */
   setDefaultSubAgent(agent: SubAgentInterface): void;
   /**
-   * Get the default agent
-   */
+  * Get the default agent
+  */
   getDefaultSubAgent(): SubAgentInterface | undefined;
   /**
-   * Get the agent ID
-   */
+  * Get all triggers for this agent
+  */
+  getTriggers(): Record<string, Trigger>;
+  /**
+  * Add one or more triggers to the agent at runtime
+  */
+  addTrigger(...triggers: TriggerInterface[]): void;
+  /**
+  * Get the agent ID
+  */
   getId(): string;
   getName(): string;
   getDescription(): string | undefined;
   getTenantId(): string;
   /**
-   * Get the agent's model settingsuration
-   */
+  * Get the agent's model settingsuration
+  */
   getModels(): typeof this.models;
   /**
-   * Set the agent's model settingsuration
-   */
+  * Set the agent's model settingsuration
+  */
   setModels(models: typeof this.models): void;
   /**
-   * Get the agent's prompt configuration
-   */
+  * Get the agent's prompt configuration
+  */
   getPrompt(): string | undefined;
   /**
-   * Get the agent's stopWhen configuration
-   */
+  * Get the agent's stopWhen configuration
+  */
   getStopWhen(): AgentStopWhen;
   /**
-   * Get the agent's status updates configuration
-   */
+  * Get the agent's status updates configuration
+  */
   getStatusUpdateSettings(): StatusUpdateSettings | undefined;
   /**
-   * Get the summarizer model from the agent's model settings
-   */
+  * Get the summarizer model from the agent's model settings
+  */
   getSummarizerModel(): ModelSettings | undefined;
   /**
-   * Get agent statistics
-   */
+  * Get agent statistics
+  */
   getStats(): {
     agentCount: number;
     defaultSubAgent: string | null;
@@ -126,61 +137,61 @@ declare class Agent implements AgentInterface {
     headers?: Record<string, string>;
   }): subAgentTeamAgentInterface;
   /**
-   * Validate the agent configuration
-   */
+  * Validate the agent configuration
+  */
   validate(): {
     valid: boolean;
     errors: string[];
   };
   private _init;
   /**
-   * Type guard to check if an agent is an internal AgentInterface
-   */
+  * Type guard to check if an agent is an internal AgentInterface
+  */
   isInternalAgent(agent: AllDelegateInputInterface): agent is SubAgentInterface;
   /**
-   * Get project-level model settingsuration defaults
-   */
+  * Get project-level model settingsuration defaults
+  */
   private getProjectModelDefaults;
   /**
-   * Get project-level stopWhen configuration defaults
-   */
+  * Get project-level stopWhen configuration defaults
+  */
   private getProjectStopWhenDefaults;
   /**
-   * Apply model inheritance hierarchy: Project -> Agent -> Agent
-   */
+  * Apply model inheritance hierarchy: Project -> Agent -> Agent
+  */
   private applyModelInheritance;
   /**
-   * Apply stopWhen inheritance hierarchy: Project -> Agent -> Agent
-   */
+  * Apply stopWhen inheritance hierarchy: Project -> Agent -> Agent
+  */
   private applyStopWhenInheritance;
   /**
-   * Propagate agent-level model settings to agents (supporting partial inheritance)
-   */
+  * Propagate agent-level model settings to agents (supporting partial inheritance)
+  */
   private propagateModelSettingsToAgent;
   /**
-   * Immediately propagate agent-level models to all agents during construction
-   */
+  * Immediately propagate agent-level models to all agents during construction
+  */
   private propagateImmediateModelSettings;
   /**
-   * Execute agent using the backend system instead of local runner
-   */
+  * Execute agent using the backend system instead of local runner
+  */
   private executeWithBackend;
   /**
-   * Parse streaming response in SSE format
-   */
+  * Parse streaming response in SSE format
+  */
   private parseStreamingResponse;
   /**
-   * Normalize input messages to the expected format
-   */
+  * Normalize input messages to the expected format
+  */
   private normalizeMessages;
 }
 /**
- * Helper function to create agent - OpenAI style
- */
+* Helper function to create agent - OpenAI style
+*/
 declare function agent(config: AgentConfig): Agent;
 /**
- * Factory function to create agent from configuration file
- */
+* Factory function to create agent from configuration file
+*/
 declare function generateAgent(configPath: string): Promise<Agent>;
 //#endregion
 export { Agent, agent, generateAgent };