@hookflo/tern 1.0.0 → 1.0.2

package/README.md

@@ -1,20 +1,38 @@
-# Tern
+# Tern - Algorithm Agnostic Webhook Verification Framework
 
-A robust, scalable webhook verification framework supporting multiple platforms and signature algorithms. Built with TypeScript for maximum type safety and developer experience.
+A robust, algorithm-agnostic webhook verification framework that supports multiple platforms with accurate signature verification and payload retrieval.
 
+[![npm version](https://img.shields.io/npm/v/@hookflo/tern)](https://www.npmjs.com/package/@hookflo/tern)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Tern is a zero-dependency TypeScript framework for robust webhook verification across multiple platforms and algorithms.
+
+<img width="1396" height="470" style="border-radius: 10px" alt="tern bird nature" src="https://github.com/user-attachments/assets/5f0da3e6-1aba-4f88-a9d7-9d8698845c39" />
 ## Features
 
-- **Algorithm-based verification**: Instead of platform-specific verifiers, use algorithm-based verifiers
-- **Platform configuration**: Each platform specifies which algorithm to use
-- **Extensible framework**: Easy to add new algorithms and platforms
-- **Most common algorithms**: HMAC-SHA256, HMAC-SHA1, HMAC-SHA512, and custom algorithms
-- **TypeScript support**: Full type safety and IntelliSense
-- **Zero dependencies**: Only uses Node.js built-in modules
+- **Algorithm Agnostic**: Decouples platform logic from signature verification — verify based on cryptographic algorithm, not hardcoded platform rules.
+Supports HMAC-SHA256, HMAC-SHA1, HMAC-SHA512, and custom algorithms
+
+- **Platform Specific**: Accurate implementations for Stripe, GitHub, Clerk, and other platforms
+- **Flexible Configuration**: Custom signature configurations for any webhook format
+- **Type Safe**: Full TypeScript support with comprehensive type definitions
+- **Framework Agnostic**: Works with Express.js, Next.js, Cloudflare Workers, and more
+
+## Why Tern?
+
+Most webhook verifiers are tightly coupled to specific platforms or hardcoded logic. Tern introduces a flexible, scalable, algorithm-first approach that:
+
+- Works across all major platforms
+- Supports custom signing logic
+- Keeps your code clean and modular
+- Avoids unnecessary dependencies
+- Is written in strict, modern TypeScript
 
 ## Installation
 
 ```bash
-npm install tern
+npm install @hookflo/tern
 ```
 
 ## Quick Start
@@ -22,375 +40,265 @@ npm install tern
 ### Basic Usage
 
 ```typescript
-import { WebhookVerificationService } from 'tern';
+import { WebhookVerificationService } from '@hookflo/tern';
 
-// Verify a GitHub webhook
+// Verify a Stripe webhook
 const result = await WebhookVerificationService.verifyWithPlatformConfig(
   request,
-  'github',
-  'your-github-secret',
-  300
+  'stripe',
+  'whsec_your_stripe_webhook_secret'
 );
 
 if (result.isValid) {
-  console.log('Webhook verified successfully:', result.payload);
+  console.log('Webhook verified!', result.payload);
 } else {
-  console.error('Verification failed:', result.error);
+  console.log('Verification failed:', result.error);
 }
 ```
 
-### Token-based Authentication (Supabase, Custom)
+### Platform-Specific Configurations
 
 ```typescript
-// For platforms that use simple token-based auth
-const result = await WebhookVerificationService.verifyTokenBased(
-  request,
-  'your-webhook-id',
-  'your-webhook-token'
-);
-```
+import { WebhookVerificationService } from '@hookflo/tern';
 
-### Custom Signature Configuration
+// Stripe webhook
+const stripeConfig = {
+  platform: 'stripe',
+  secret: 'whsec_your_stripe_webhook_secret',
+  toleranceInSeconds: 300,
+};
 
-```typescript
-import { WebhookVerificationService } from 'tern';
+// GitHub webhook
+const githubConfig = {
+  platform: 'github',
+  secret: 'your_github_webhook_secret',
+  toleranceInSeconds: 300,
+};
 
-const config = {
-  platform: 'custom',
-  secret: 'your-secret',
-  signatureConfig: {
-    algorithm: 'hmac-sha256',
-    headerName: 'x-signature',
-    headerFormat: 'prefixed',
-    prefix: 'sha256=',
-    payloadFormat: 'raw'
-  }
+// Clerk webhook
+const clerkConfig = {
+  platform: 'clerk',
+  secret: 'whsec_your_clerk_webhook_secret',
+  toleranceInSeconds: 300,
 };
 
-const result = await WebhookVerificationService.verify(request, config);
+const result = await WebhookVerificationService.verify(request, stripeConfig);
 ```
 
-## 🏗️ Supported Platforms
+## Supported Platforms
 
-### HMAC-SHA256 (Most Common)
-- **GitHub**: `x-hub-signature-256` with `sha256=` prefix
-- **Stripe**: `stripe-signature` with comma-separated format
-- **Clerk**: `svix-signature` with base64 encoding
-- **Dodo Payments**: `webhook-signature` with raw format
-- **Shopify**: `x-shopify-hmac-sha256`
-- **Vercel**: `x-vercel-signature`
-- **Polar**: `x-polar-signature`
+### Stripe
+- **Signature Format**: `t={timestamp},v1={signature}`
+- **Algorithm**: HMAC-SHA256
+- **Payload Format**: `{timestamp}.{body}`
 
-### Custom Algorithms
-- **Supabase**: Token-based authentication
-- **Clerk**: Custom base64 encoding
-- **Stripe**: Custom comma-separated format
+### GitHub
+- **Signature Format**: `sha256={signature}`
+- **Algorithm**: HMAC-SHA256
+- **Payload Format**: Raw body
 
-## 🔧 API Reference
+### Clerk
+- **Signature Format**: `v1,{signature}` (space-separated)
+- **Algorithm**: HMAC-SHA256 with base64 encoding
+- **Payload Format**: `{id}.{timestamp}.{body}`
 
-### WebhookVerificationService
+### Other Platforms
+- **Dodo Payments**: HMAC-SHA256
+- **Shopify**: HMAC-SHA256
+- **Vercel**: HMAC-SHA256
+- **Polar**: HMAC-SHA256
+- **Supabase**: Token-based authentication
 
-#### `verify(request: Request, config: WebhookConfig): Promise<WebhookVerificationResult>`
+## Custom Configurations
 
-Verify a webhook using a configuration object.
+### Custom HMAC-SHA256
 
 ```typescript
-const config = {
-  platform: 'github',
-  secret: 'your-secret',
-  toleranceInSeconds: 300
+const customConfig = {
+  platform: 'custom',
+  secret: 'your_custom_secret',
+  signatureConfig: {
+    algorithm: 'hmac-sha256',
+    headerName: 'x-custom-signature',
+    headerFormat: 'prefixed',
+    prefix: 'sha256=',
+    payloadFormat: 'raw',
+  },
 };
-
-const result = await WebhookVerificationService.verify(request, config);
-```
-
-#### `verifyWithPlatformConfig(request: Request, platform: WebhookPlatform, secret: string, toleranceInSeconds?: number): Promise<WebhookVerificationResult>`
-
-Verify a webhook using platform-specific configuration.
-
-```typescript
-const result = await WebhookVerificationService.verifyWithPlatformConfig(
-  request,
-  'stripe',
-  'your-stripe-secret',
-  300
-);
 ```
 
-#### `verifyTokenBased(request: Request, webhookId: string, webhookToken: string): Promise<WebhookVerificationResult>`
-
-Verify a webhook using simple token-based authentication.
+### Custom Timestamped Payload
 
 ```typescript
-const result = await WebhookVerificationService.verifyTokenBased(
-  request,
-  'your-webhook-id',
-  'your-webhook-token'
-);
+const timestampedConfig = {
+  platform: 'custom',
+  secret: 'your_custom_secret',
+  signatureConfig: {
+    algorithm: 'hmac-sha256',
+    headerName: 'x-webhook-signature',
+    headerFormat: 'raw',
+    timestampHeader: 'x-webhook-timestamp',
+    timestampFormat: 'unix',
+    payloadFormat: 'timestamped',
+  },
+};
 ```
 
-### Utility Functions
-
-#### `detectPlatformFromHeaders(headers: Headers): WebhookPlatform | null`
+## Framework Integration
 
-Automatically detect the platform from request headers.
+### Express.js
 
 ```typescript
-import { detectPlatformFromHeaders } from 'tern';
-
-const platform = detectPlatformFromHeaders(request.headers);
-if (platform) {
+app.post('/webhooks/stripe', async (req, res) => {
   const result = await WebhookVerificationService.verifyWithPlatformConfig(
-    request, platform, 'your-secret', 300
+    req,
+    'stripe',
+    process.env.STRIPE_WEBHOOK_SECRET
   );
-}
-```
-
-#### `getPlatformsUsingAlgorithm(algorithm: string): WebhookPlatform[]`
-
-Get all platforms that use a specific algorithm.
-
-```typescript
-import { WebhookVerificationService } from 'tern';
-
-const hmacPlatforms = WebhookVerificationService.getPlatformsUsingAlgorithm('hmac-sha256');
-// Returns: ['github', 'stripe', 'clerk', 'dodopayments', ...]
-```
-
-## 🎯 Usage Examples
-
-### Express.js Integration
-
-```typescript
-import express from 'express';
-import { WebhookVerificationService } from 'tern';
-
-const app = express();
-
-app.post('/webhook', async (req, res) => {
-  try {
-    const result = await WebhookVerificationService.verifyWithPlatformConfig(
-      req,
-      'github',
-      process.env.GITHUB_WEBHOOK_SECRET,
-      300
-    );
 
-    if (result.isValid) {
-      // Process the webhook
-      console.log('Webhook received:', result.payload);
-      res.status(200).json({ success: true });
-    } else {
-      res.status(401).json({ error: result.error });
-    }
-  } catch (error) {
-    res.status(500).json({ error: 'Internal server error' });
+  if (!result.isValid) {
+    return res.status(400).json({ error: result.error });
   }
+
+  // Process the webhook
+  console.log('Stripe event:', result.payload.type);
+  res.json({ received: true });
 });
 ```
 
 ### Next.js API Route
 
 ```typescript
-// pages/api/webhook.ts
-import { NextApiRequest, NextApiResponse } from 'next';
-import { WebhookVerificationService } from 'tern';
-
-export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+// pages/api/webhooks/github.js
+export default async function handler(req, res) {
   if (req.method !== 'POST') {
     return res.status(405).json({ error: 'Method not allowed' });
   }
 
-  try {
-    const result = await WebhookVerificationService.verifyWithPlatformConfig(
-      req as any,
-      'stripe',
-      process.env.STRIPE_WEBHOOK_SECRET,
-      300
-    );
+  const result = await WebhookVerificationService.verifyWithPlatformConfig(
+    req,
+    'github',
+    process.env.GITHUB_WEBHOOK_SECRET
+  );
 
-    if (result.isValid) {
-      // Handle the webhook
-      console.log('Stripe webhook:', result.payload);
-      res.status(200).json({ received: true });
-    } else {
-      res.status(401).json({ error: result.error });
-    }
-  } catch (error) {
-    res.status(500).json({ error: 'Internal server error' });
+  if (!result.isValid) {
+    return res.status(400).json({ error: result.error });
   }
+
+  // Handle GitHub webhook
+  const event = req.headers['x-github-event'];
+  console.log('GitHub event:', event);
+  
+  res.json({ received: true });
 }
 ```
 
-### Platform Detection
+### Cloudflare Workers
 
 ```typescript
-import { detectPlatformFromHeaders, WebhookVerificationService } from 'tern';
+addEventListener('fetch', event => {
+  event.respondWith(handleRequest(event.request));
+});
 
-async function handleWebhook(request: Request) {
-  const platform = detectPlatformFromHeaders(request.headers);
-  
-  if (!platform) {
-    throw new Error('Unknown webhook platform');
-  }
+async function handleRequest(request) {
+  if (request.url.includes('/webhooks/clerk')) {
+    const result = await WebhookVerificationService.verifyWithPlatformConfig(
+      request,
+      'clerk',
+      CLERK_WEBHOOK_SECRET
+    );
 
-  const secret = getSecretForPlatform(platform); // Your secret management
-  const result = await WebhookVerificationService.verifyWithPlatformConfig(
-    request,
-    platform,
-    secret,
-    300
-  );
+    if (!result.isValid) {
+      return new Response(JSON.stringify({ error: result.error }), {
+        status: 400,
+        headers: { 'Content-Type': 'application/json' }
+      });
+    }
 
-  return result;
+    // Process Clerk webhook
+    console.log('Clerk event:', result.payload.type);
+    return new Response(JSON.stringify({ received: true }));
+  }
 }
 ```
 
-### Custom Platform Integration
-
-```typescript
-import { WebhookVerificationService } from 'tern';
-
-const customConfig = {
-  platform: 'custom',
-  secret: 'your-custom-secret',
-  signatureConfig: {
-    algorithm: 'hmac-sha256',
-    headerName: 'x-custom-signature',
-    headerFormat: 'raw',
-    payloadFormat: 'raw'
-  }
-};
+## API Reference
 
-const result = await WebhookVerificationService.verify(request, customConfig);
-```
+### WebhookVerificationService
 
-## 🔧 Adding New Platforms
+#### `verify(request: Request, config: WebhookConfig): Promise<WebhookVerificationResult>`
 
-### Step 1: Add Platform Type
+Verifies a webhook using the provided configuration.
 
-```typescript
-// In your project, extend the types
-declare module 'tern' {
-  interface WebhookPlatform {
-    'your-platform': 'your-platform';
-  }
-}
-```
+#### `verifyWithPlatformConfig(request: Request, platform: WebhookPlatform, secret: string, toleranceInSeconds?: number): Promise<WebhookVerificationResult>`
 
-### Step 2: Use Custom Configuration
+Simplified verification using platform-specific configurations.
 
-```typescript
-const config = {
-  platform: 'custom',
-  secret: 'your-secret',
-  signatureConfig: {
-    algorithm: 'hmac-sha256', // or 'custom'
-    headerName: 'x-your-signature',
-    headerFormat: 'raw',
-    payloadFormat: 'raw'
-  }
-};
-```
+#### `verifyTokenBased(request: Request, webhookId: string, webhookToken: string): Promise<WebhookVerificationResult>`
 
-## 📊 Platform Support Matrix
+Verifies token-based webhooks (like Supabase).
 
-| Platform | Algorithm | Header | Format |
-|----------|-----------|--------|--------|
-| GitHub | HMAC-SHA256 | `x-hub-signature-256` | `sha256=...` |
-| Stripe | HMAC-SHA256 | `stripe-signature` | `t=...,v1=...` |
-| Clerk | Custom | `svix-signature` | Base64 |
-| Supabase | Token-based | `x-webhook-token` | Simple |
-| Shopify | HMAC-SHA256 | `x-shopify-hmac-sha256` | Raw |
-| Vercel | HMAC-SHA256 | `x-vercel-signature` | Raw |
-| Polar | HMAC-SHA256 | `x-polar-signature` | Raw |
+### Types
 
-## 🔍 Error Handling
+#### `WebhookVerificationResult`
 
 ```typescript
-try {
-  const result = await WebhookVerificationService.verifyWithPlatformConfig(
-    request,
-    'github',
-    'your-secret',
-    300
-  );
-
-  if (!result.isValid) {
-    console.error('Verification failed:', result.error);
-    return res.status(401).json({ error: result.error });
-  }
-
-  // Process webhook
-  console.log('Webhook verified:', result.payload);
-} catch (error) {
-  console.error('Verification error:', error);
-  return res.status(500).json({ error: 'Internal server error' });
+interface WebhookVerificationResult {
+  isValid: boolean;
+  error?: string;
+  platform: WebhookPlatform;
+  payload?: any;
+  metadata?: {
+    timestamp?: string;
+    id?: string | null;
+    [key: string]: any;
+  };
 }
 ```
 
-## 🧪 Testing
+#### `WebhookConfig`
 
 ```typescript
-import { WebhookVerificationService } from 'tern';
-
-// Create a mock request
-const mockRequest = new Request('http://localhost/webhook', {
-  method: 'POST',
-  headers: {
-    'x-hub-signature-256': 'sha256=abc123',
-    'content-type': 'application/json'
-  },
-  body: JSON.stringify({ test: 'data' })
-});
+interface WebhookConfig {
+  platform: WebhookPlatform;
+  secret: string;
+  toleranceInSeconds?: number;
+  signatureConfig?: SignatureConfig;
+}
+```
 
-const result = await WebhookVerificationService.verifyWithPlatformConfig(
-  mockRequest,
-  'github',
-  'test-secret',
-  300
-);
+## Testing
 
-console.log('Test result:', result);
+Run the test suite:
+
+```bash
+npm test
 ```
 
-## 📈 Performance
+Run examples:
 
-- **Zero dependencies**: Only uses Node.js built-in modules
-- **Optimized algorithms**: Efficient HMAC verification
-- **Timing-safe comparisons**: Prevents timing attacks
-- **Minimal overhead**: Lightweight and fast
+```bash
+npm run examples
+```
 
-## 🔒 Security Features
+## Examples
 
-- **Timing-safe comparisons**: Prevents timing attacks
-- **Proper validation**: Comprehensive input validation
-- **Secure defaults**: Secure by default configuration
-- **Algorithm flexibility**: Support for multiple signature algorithms
+See the [examples.ts](./src/examples.ts) file for comprehensive usage examples.
 
-## 🤝 Contributing
+## Contributing
 
 1. Fork the repository
 2. Create a feature branch
 3. Make your changes
-4. Add tests
+4. Add tests for new functionality
 5. Submit a pull request
 
 ## 📄 License
 
-MIT License - see LICENSE file for details.
-
-## 🆘 Support
-
-- **Issues**: [GitHub Issues](https://github.com/yourusername/tern/issues)
-- **Documentation**: [GitHub Wiki](https://github.com/yourusername/tern/wiki)
-- **Discussions**: [GitHub Discussions](https://github.com/yourusername/tern/discussions)
+MIT License - see [LICENSE](./LICENSE) for details.
 
-## 🚀 Roadmap
+## 🔗 Links
 
-- [ ] RSA-SHA256 support
-- [ ] Ed25519 support
-- [ ] Performance optimizations
-- [ ] More platform integrations
-- [ ] Built-in rate limiting
-- [ ] Monitoring and metrics 
+- [Documentation](./USAGE.md)
+- [Framework Summary](./FRAMEWORK_SUMMARY.md)
+- [Issues](https://github.com/your-repo/tern/issues)

package/dist/examples.d.ts

@@ -1,28 +1,8 @@
-export declare function exampleBasicUsage(request: Request): Promise<import("./types").WebhookVerificationResult>;
-export declare function exampleTokenBased(request: Request): Promise<import("./types").WebhookVerificationResult>;
-export declare function exampleCustomSignature(request: Request): Promise<import("./types").WebhookVerificationResult>;
-export declare function examplePlatformDetection(request: Request): Promise<import("./types").WebhookVerificationResult>;
-export declare function exampleErrorHandling(request: Request): Promise<{
-    success: boolean;
-    error: string | undefined;
-    payload?: undefined;
-} | {
-    success: boolean;
-    payload: any;
-    error?: undefined;
-}>;
-export declare function exampleBatchVerification(request: Request): Promise<({
-    platform: string;
-    success: boolean;
-    result: import("./types").WebhookVerificationResult;
-    error?: undefined;
-} | {
-    platform: string;
-    success: boolean;
-    error: string;
-    result?: undefined;
-})[]>;
-export declare function exampleExpressIntegration(): any;
-export declare function exampleNextJsApiRoute(): (req: any, res: any) => Promise<any>;
-export declare function exampleCustomPlatform(request: Request): Promise<import("./types").WebhookVerificationResult>;
-export declare function exampleHelperMethods(): void;
+export declare function examplePlatformSpecific(): Promise<void>;
+export declare function exampleCustomSignature(): Promise<void>;
+export declare function exampleSimplifiedPlatform(): Promise<void>;
+export declare function exampleTokenBased(): Promise<void>;
+export declare function exampleErrorHandling(): Promise<void>;
+export declare function examplePlatformInfo(): void;
+export declare function exampleRealWorldUsage(): Promise<void>;
+export declare function runAllExamples(): Promise<void>;