@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/webhook-validation/readme.md

@@ -1,239 +1,239 @@
-# Webhook Validation Learning Path
-
-**Secure Webhook Authentication for Fluent Commerce Rubix**
-
-The FC Connect SDK provides cryptographic webhook validation to ensure webhooks from Fluent Commerce Rubix workflows are authentic, untampered, and trustworthy. Whether you're building Versori connectors, Express.js APIs, or serverless functions, the SDK handles signature verification automatically.
-
-## Quick Start
-
-```typescript
-import {
-  WebhookValidationService,
-  createConsoleLogger,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// ✅ Simple: Use console logger directly
-const logger = createConsoleLogger();
-
-// ✅ Versori: Pass Versori log directly (no wrapper needed)
-// const logger = ctx.log;
-
-const validator = new WebhookValidationService(
-  {
-    strictValidation: true,
-  },
-  logger
-);
-
-const result = await validator.validateWebhook(
-  rawBody, // Raw request body as string
-  headers, // Request headers object
-  publicKey // Public key from Fluent Commerce
-);
-
-if (!result.isValid) {
-  console.error('Invalid webhook:', result.error);
-  // Reject the webhook
-}
-
-// Process valid webhook
-console.log('Valid webhook using:', result.algorithm);
-```
-
-**That's it.** The SDK auto-detects signature type, verifies authenticity, and returns validation results.
-
----
-
-## What You'll Learn
-
-This guide teaches you how to validate webhooks from Fluent Commerce Rubix workflows using cryptographic signatures. By the end, you'll understand:
-
-- How webhook signature validation works (SHA512, MD5 algorithms)
-- Auto-detection patterns for signature headers
-- Versori platform integration patterns
-- Express.js and Node.js webhook endpoints
-- Configuration options and factory methods
-- Error handling and troubleshooting
-- Security best practices for webhook validation
-
-## Learning Path Overview
-
-This guide is organized into **9 progressive modules**. Follow them in order for the best learning experience:
-
-| Module                                           | Topic                                                                      | Level        | Estimated Time |
-| ------------------------------------------------ | -------------------------------------------------------------------------- | ------------ | -------------- |
-| [Module 1](./modules/webhook-validation-01-foundations.md)          | **Foundations** - How webhook validation works, algorithms, security model | Beginner     | 20 minutes     |
-| [Module 2](./modules/webhook-validation-02-quick-start.md)          | **Quick Start** - Basic usage, auto-detection, first validation            | Beginner     | 15 minutes     |
-| [Module 3](./modules/webhook-validation-03-versori-integration.md)  | **Versori Integration** - Versori webhook patterns, connection-based auth  | Intermediate | 25 minutes     |
-| [Module 4](./modules/webhook-validation-04-platform-integration.md) | **Platform Integration** - Express.js, serverless, other frameworks        | Intermediate | 30 minutes     |
-| [Module 5](./modules/webhook-validation-05-configuration.md)        | **Configuration** - All options, factory methods, custom configs           | Intermediate | 20 minutes     |
-| [Module 6](./modules/webhook-validation-06-error-handling.md)       | **Error Handling** - Validation results, common errors, debugging          | Intermediate | 25 minutes     |
-| [Module 7](./modules/webhook-validation-07-api-reference.md)        | **API Reference** - Complete interfaces, TypeScript types, FAQ             | Reference    | As needed      |
-| [Module 8](./modules/webhook-validation-08-rubix-webhooks.md)       | **Rubix Webhooks** - Rubix HTTP Call webhook validation patterns           | Intermediate | 20 minutes     |
-| [Module 9](./modules/webhook-validation-09-rubix-event-vs-http-call.md)  | **Event vs HTTP Call** - Distinguish webhook types, choose validation method | Intermediate | 15 minutes     |
-
-**Total learning time:** ~3.2 hours for complete mastery
-
----
-
-## Quick Navigation
-
-### By Use Case
-
-- **First time validating webhooks?** → Start with [Module 1: Foundations](./modules/webhook-validation-01-foundations.md)
-- **Need working code now?** → Jump to [Module 2: Quick Start](./modules/webhook-validation-02-quick-start.md)
-- **Building Versori connector?** → See [Module 3: Versori Integration](./modules/webhook-validation-03-versori-integration.md)
-- **Validating Rubix webhooks?** → Check [Module 9: Event vs HTTP Call](./modules/webhook-validation-09-rubix-event-vs-http-call.md) first!
-- **Validating Rubix HTTP Call webhooks?** → Check [Module 8: Rubix Webhooks](./modules/webhook-validation-08-rubix-webhooks.md)
-- **Using Express.js?** → Check [Module 4: Platform Integration](./modules/webhook-validation-04-platform-integration.md)
-- **Validation failing?** → Review [Module 6: Error Handling](./modules/webhook-validation-06-error-handling.md)
-- **Need specific config?** → Browse [Module 7: API Reference](./modules/webhook-validation-07-api-reference.md)
-
-### By Platform
-
-| Platform        | Complexity | Recommended Module                               | Example                                               |
-| --------------- | ---------- | ------------------------------------------------ | ----------------------------------------------------- |
-| **Versori**     | Low        | [Module 3](./modules/webhook-validation-03-versori-integration.md)  | [Common Patterns](./examples/common-patterns.ts)   |
-| **Express.js**  | Medium     | [Module 4](./modules/webhook-validation-04-platform-integration.md) | [Common Patterns](./examples/common-patterns.ts)   |
-| **Next.js API** | Medium     | [Module 4](./modules/webhook-validation-04-platform-integration.md) | [Common Patterns](./examples/common-patterns.ts)     |
-| **AWS Lambda**  | Medium     | [Module 4](./modules/webhook-validation-04-platform-integration.md) | [Common Patterns](./examples/common-patterns.ts)     |
-| **Standalone**  | Low        | [Module 2](./modules/webhook-validation-02-quick-start.md)          | [basic-validation.ts](./examples/common-patterns.ts) |
-
----
-
-## Quick Reference
-
-For quick lookups, see:
-
-- [Quick Reference Cheat Sheet](../advanced-services/advanced-services-quick-reference.md) - All patterns on one page
-- [Common Patterns](./examples/common-patterns.ts) - Copy-paste ready snippets
-- [Troubleshooting](./modules/webhook-validation-06-error-handling.md#common-errors) - Error messages and fixes
-
----
-
-## Prerequisites
-
-Before starting this guide, you should:
-
-1. Have the SDK installed: `npm install @fluentcommerce/fc-connect-sdk@latest  # v0.1.27+`
-2. Have Fluent Commerce public key for webhook validation
-3. Understand basic webhook concepts (HTTP requests, headers, signatures)
-4. (Optional) Familiarity with cryptographic signatures (RSA, SHA, MD5)
-
-**New to the SDK?** Start with the [Getting Started Guide](../../00-START-HERE/getting-started.md) first.
-
----
-
-## Key Concepts at a Glance
-
-### Before: Manual Signature Verification
-
-```typescript
-// Complex crypto operations, header parsing, algorithm selection
-const crypto = require('crypto');
-const signature = headers['fluent-signature'] || headers['flex.signature'];
-const verify = crypto.createVerify('SHA512withRSA');
-verify.update(rawBody);
-const isValid = verify.verify(publicKey, signature, 'base64');
-```
-
-### After: SDK Auto-Detection
-
-```typescript
-// SDK handles everything automatically
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-if (!result.isValid) throw new Error('Invalid webhook');
-```
-
----
-
-## Why Validate Webhooks?
-
-Webhook validation ensures:
-
-- **Authenticity**: Webhook is genuinely from Fluent Commerce
-- **Integrity**: Payload hasn't been tampered with in transit
-- **Security**: Signature validation (replay protection requires additional timestamp validation) and malicious requests
-- **Trust**: Only process verified, trusted webhook data
-
-**Without validation**, your system could process:
-
-- Malicious payloads disguised as Fluent webhooks
-- Modified data from man-in-the-middle attacks
-- Replay attacks with stale webhook data
-- Unauthorized requests from bad actors
-
----
-
-## Webhook Validation Scope
-
-The SDK's `validateWebhook()` method is designed for **Fluent Commerce Rubix workflows** but technically works with **any system that implements RSA signature verification** with compatible algorithms (SHA512withRSA or MD5withRSA).
-
-**Key Requirement:** You must have access to the **public key** that matches the private key used to sign the webhook.
-
-**Common Use Cases:**
-- ✅ Fluent Commerce Rubix workflows (primary use case)
-- ✅ Any system using RSA signatures with SHA512 or MD5
-- ❌ Third-party webhooks using HMAC (Shopify, GitHub, Stripe) - requires manual validation
-
----
-
-## Supported Signature Algorithms
-
-The SDK supports both Fluent Commerce signature standards:
-
-| Algorithm         | Header             | Use Case                                       |
-| ----------------- | ------------------ | ---------------------------------------------- |
-| **SHA512withRSA** | `fluent-signature` | Rubix workflows (default)               |
-| **MD5withRSA**    | `flex.signature`   | Flex workflows |
-
-**Auto-detection**: The SDK automatically selects the correct algorithm based on which header is present.
-
----
-
-## Best Practices
-
-1. **Always validate** before processing webhook data (Module 1)
-2. **Use auto-detection** - let SDK choose algorithm (Module 2)
-3. **Enable strict validation** in production (Module 5)
-4. **Store public keys securely** in environment variables (Module 1)
-5. **Log validation failures** for security monitoring (Module 6)
-6. **Return 401** for invalid signatures (Module 4)
-7. **Use raw request body** - never parse before validation (Module 2)
-
----
-
-## Security Notes
-
-- This service validates webhooks from **Fluent Commerce Rubix workflows only**
-- Public keys are environment-specific (production, sandbox, UAT)
-- Always use HTTPS for webhook endpoints in production
-- Never log or expose raw signature values
-- Rotate public keys periodically per security policy
-- Monitor validation failures for potential attacks
-
----
-
-## Getting Help
-
-- **Quick answers:** [Quick Reference](../advanced-services/advanced-services-quick-reference.md)
-- **Troubleshooting:** [Module 6: Error Handling](./modules/webhook-validation-06-error-handling.md)
-- **Examples:** [`examples/`](./examples/)
-- **API Reference:** [Module 7](./modules/webhook-validation-07-api-reference.md)
-
----
-
-## Next Steps
-
-**New to webhook validation?** Start with [Module 1: Foundations](./modules/webhook-validation-01-foundations.md)
-
-**Already familiar?** Jump to specific topics:
-
-- [Versori Integration](./modules/webhook-validation-03-versori-integration.md)
-- [Platform Integration](./modules/webhook-validation-04-platform-integration.md)
-- [Error Handling](./modules/webhook-validation-06-error-handling.md)
-- [API Reference](./modules/webhook-validation-07-api-reference.md)
-
----
-
-**Remember:** Webhook validation is **essential for security**. Never process unvalidated webhooks in production.
+# Webhook Validation Learning Path
+
+**Secure Webhook Authentication for Fluent Commerce Rubix**
+
+The FC Connect SDK provides cryptographic webhook validation to ensure webhooks from Fluent Commerce Rubix workflows are authentic, untampered, and trustworthy. Whether you're building Versori connectors, Express.js APIs, or serverless functions, the SDK handles signature verification automatically.
+
+## Quick Start
+
+```typescript
+import {
+  WebhookValidationService,
+  createConsoleLogger,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// ✅ Simple: Use console logger directly
+const logger = createConsoleLogger();
+
+// ✅ Versori: Pass Versori log directly (no wrapper needed)
+// const logger = ctx.log;
+
+const validator = new WebhookValidationService(
+  {
+    strictValidation: true,
+  },
+  logger
+);
+
+const result = await validator.validateWebhook(
+  rawBody, // Raw request body as string
+  headers, // Request headers object
+  publicKey // Public key from Fluent Commerce
+);
+
+if (!result.isValid) {
+  console.error('Invalid webhook:', result.error);
+  // Reject the webhook
+}
+
+// Process valid webhook
+console.log('Valid webhook using:', result.algorithm);
+```
+
+**That's it.** The SDK auto-detects signature type, verifies authenticity, and returns validation results.
+
+---
+
+## What You'll Learn
+
+This guide teaches you how to validate webhooks from Fluent Commerce Rubix workflows using cryptographic signatures. By the end, you'll understand:
+
+- How webhook signature validation works (SHA512, MD5 algorithms)
+- Auto-detection patterns for signature headers
+- Versori platform integration patterns
+- Express.js and Node.js webhook endpoints
+- Configuration options and factory methods
+- Error handling and troubleshooting
+- Security best practices for webhook validation
+
+## Learning Path Overview
+
+This guide is organized into **9 progressive modules**. Follow them in order for the best learning experience:
+
+| Module                                           | Topic                                                                      | Level        | Estimated Time |
+| ------------------------------------------------ | -------------------------------------------------------------------------- | ------------ | -------------- |
+| [Module 1](./modules/webhook-validation-01-foundations.md)          | **Foundations** - How webhook validation works, algorithms, security model | Beginner     | 20 minutes     |
+| [Module 2](./modules/webhook-validation-02-quick-start.md)          | **Quick Start** - Basic usage, auto-detection, first validation            | Beginner     | 15 minutes     |
+| [Module 3](./modules/webhook-validation-03-versori-integration.md)  | **Versori Integration** - Versori webhook patterns, connection-based auth  | Intermediate | 25 minutes     |
+| [Module 4](./modules/webhook-validation-04-platform-integration.md) | **Platform Integration** - Express.js, serverless, other frameworks        | Intermediate | 30 minutes     |
+| [Module 5](./modules/webhook-validation-05-configuration.md)        | **Configuration** - All options, factory methods, custom configs           | Intermediate | 20 minutes     |
+| [Module 6](./modules/webhook-validation-06-error-handling.md)       | **Error Handling** - Validation results, common errors, debugging          | Intermediate | 25 minutes     |
+| [Module 7](./modules/webhook-validation-07-api-reference.md)        | **API Reference** - Complete interfaces, TypeScript types, FAQ             | Reference    | As needed      |
+| [Module 8](./modules/webhook-validation-08-rubix-webhooks.md)       | **Rubix Webhooks** - Rubix HTTP Call webhook validation patterns           | Intermediate | 20 minutes     |
+| [Module 9](./modules/webhook-validation-09-rubix-event-vs-http-call.md)  | **Event vs HTTP Call** - Distinguish webhook types, choose validation method | Intermediate | 15 minutes     |
+
+**Total learning time:** ~3.2 hours for complete mastery
+
+---
+
+## Quick Navigation
+
+### By Use Case
+
+- **First time validating webhooks?** → Start with [Module 1: Foundations](./modules/webhook-validation-01-foundations.md)
+- **Need working code now?** → Jump to [Module 2: Quick Start](./modules/webhook-validation-02-quick-start.md)
+- **Building Versori connector?** → See [Module 3: Versori Integration](./modules/webhook-validation-03-versori-integration.md)
+- **Validating Rubix webhooks?** → Check [Module 9: Event vs HTTP Call](./modules/webhook-validation-09-rubix-event-vs-http-call.md) first!
+- **Validating Rubix HTTP Call webhooks?** → Check [Module 8: Rubix Webhooks](./modules/webhook-validation-08-rubix-webhooks.md)
+- **Using Express.js?** → Check [Module 4: Platform Integration](./modules/webhook-validation-04-platform-integration.md)
+- **Validation failing?** → Review [Module 6: Error Handling](./modules/webhook-validation-06-error-handling.md)
+- **Need specific config?** → Browse [Module 7: API Reference](./modules/webhook-validation-07-api-reference.md)
+
+### By Platform
+
+| Platform        | Complexity | Recommended Module                               | Example                                               |
+| --------------- | ---------- | ------------------------------------------------ | ----------------------------------------------------- |
+| **Versori**     | Low        | [Module 3](./modules/webhook-validation-03-versori-integration.md)  | [Common Patterns](./examples/common-patterns.ts)   |
+| **Express.js**  | Medium     | [Module 4](./modules/webhook-validation-04-platform-integration.md) | [Common Patterns](./examples/common-patterns.ts)   |
+| **Next.js API** | Medium     | [Module 4](./modules/webhook-validation-04-platform-integration.md) | [Common Patterns](./examples/common-patterns.ts)     |
+| **AWS Lambda**  | Medium     | [Module 4](./modules/webhook-validation-04-platform-integration.md) | [Common Patterns](./examples/common-patterns.ts)     |
+| **Standalone**  | Low        | [Module 2](./modules/webhook-validation-02-quick-start.md)          | [basic-validation.ts](./examples/common-patterns.ts) |
+
+---
+
+## Quick Reference
+
+For quick lookups, see:
+
+- [Quick Reference Cheat Sheet](../advanced-services/advanced-services-quick-reference.md) - All patterns on one page
+- [Common Patterns](./examples/common-patterns.ts) - Copy-paste ready snippets
+- [Troubleshooting](./modules/webhook-validation-06-error-handling.md#common-errors) - Error messages and fixes
+
+---
+
+## Prerequisites
+
+Before starting this guide, you should:
+
+1. Have the SDK installed: `npm install @fluentcommerce/fc-connect-sdk@latest  # v0.1.27+`
+2. Have Fluent Commerce public key for webhook validation
+3. Understand basic webhook concepts (HTTP requests, headers, signatures)
+4. (Optional) Familiarity with cryptographic signatures (RSA, SHA, MD5)
+
+**New to the SDK?** Start with the [Getting Started Guide](../../00-START-HERE/getting-started.md) first.
+
+---
+
+## Key Concepts at a Glance
+
+### Before: Manual Signature Verification
+
+```typescript
+// Complex crypto operations, header parsing, algorithm selection
+const crypto = require('crypto');
+const signature = headers['fluent-signature'] || headers['flex.signature'];
+const verify = crypto.createVerify('SHA512withRSA');
+verify.update(rawBody);
+const isValid = verify.verify(publicKey, signature, 'base64');
+```
+
+### After: SDK Auto-Detection
+
+```typescript
+// SDK handles everything automatically
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+if (!result.isValid) throw new Error('Invalid webhook');
+```
+
+---
+
+## Why Validate Webhooks?
+
+Webhook validation ensures:
+
+- **Authenticity**: Webhook is genuinely from Fluent Commerce
+- **Integrity**: Payload hasn't been tampered with in transit
+- **Security**: Signature validation (replay protection requires additional timestamp validation) and malicious requests
+- **Trust**: Only process verified, trusted webhook data
+
+**Without validation**, your system could process:
+
+- Malicious payloads disguised as Fluent webhooks
+- Modified data from man-in-the-middle attacks
+- Replay attacks with stale webhook data
+- Unauthorized requests from bad actors
+
+---
+
+## Webhook Validation Scope
+
+The SDK's `validateWebhook()` method is designed for **Fluent Commerce Rubix workflows** but technically works with **any system that implements RSA signature verification** with compatible algorithms (SHA512withRSA or MD5withRSA).
+
+**Key Requirement:** You must have access to the **public key** that matches the private key used to sign the webhook.
+
+**Common Use Cases:**
+- ✅ Fluent Commerce Rubix workflows (primary use case)
+- ✅ Any system using RSA signatures with SHA512 or MD5
+- ❌ Third-party webhooks using HMAC (Shopify, GitHub, Stripe) - requires manual validation
+
+---
+
+## Supported Signature Algorithms
+
+The SDK supports both Fluent Commerce signature standards:
+
+| Algorithm         | Header             | Use Case                                       |
+| ----------------- | ------------------ | ---------------------------------------------- |
+| **SHA512withRSA** | `fluent-signature` | Rubix workflows (default)               |
+| **MD5withRSA**    | `flex.signature`   | Flex workflows |
+
+**Auto-detection**: The SDK automatically selects the correct algorithm based on which header is present.
+
+---
+
+## Best Practices
+
+1. **Always validate** before processing webhook data (Module 1)
+2. **Use auto-detection** - let SDK choose algorithm (Module 2)
+3. **Enable strict validation** in production (Module 5)
+4. **Store public keys securely** in environment variables (Module 1)
+5. **Log validation failures** for security monitoring (Module 6)
+6. **Return 401** for invalid signatures (Module 4)
+7. **Use raw request body** - never parse before validation (Module 2)
+
+---
+
+## Security Notes
+
+- This service validates webhooks from **Fluent Commerce Rubix workflows only**
+- Public keys are environment-specific (production, sandbox, UAT)
+- Always use HTTPS for webhook endpoints in production
+- Never log or expose raw signature values
+- Rotate public keys periodically per security policy
+- Monitor validation failures for potential attacks
+
+---
+
+## Getting Help
+
+- **Quick answers:** [Quick Reference](../advanced-services/advanced-services-quick-reference.md)
+- **Troubleshooting:** [Module 6: Error Handling](./modules/webhook-validation-06-error-handling.md)
+- **Examples:** [`examples/`](./examples/)
+- **API Reference:** [Module 7](./modules/webhook-validation-07-api-reference.md)
+
+---
+
+## Next Steps
+
+**New to webhook validation?** Start with [Module 1: Foundations](./modules/webhook-validation-01-foundations.md)
+
+**Already familiar?** Jump to specific topics:
+
+- [Versori Integration](./modules/webhook-validation-03-versori-integration.md)
+- [Platform Integration](./modules/webhook-validation-04-platform-integration.md)
+- [Error Handling](./modules/webhook-validation-06-error-handling.md)
+- [API Reference](./modules/webhook-validation-07-api-reference.md)
+
+---
+
+**Remember:** Webhook validation is **essential for security**. Never process unvalidated webhooks in production.