@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/04-REFERENCE/platforms/versori/platforms-versori-webhook-connection-security.md

@@ -1,681 +1,681 @@
-# Versori Webhook Connection-Based Security
-
-**Platform:** Versori
-**Security Pattern:** Connection-Level Authentication
-**Level:** Recommended
-**Last Updated:** 2025-10-28
-
----
-
-## Overview
-
-This guide explains **connection-based webhook security** in Versori - how to authenticate webhook endpoints at the platform level BEFORE your workflow code runs.
-
-### Connection-Based Security Pattern
-
-```typescript
-export const myWebhook = webhook('my-webhook', {
-  connection: 'my-webhook-auth', // Versori validates BEFORE code runs
-  response: { mode: 'sync' },
-}).then(
-  http('process', { connection: 'fluent' }, async ctx => {
-    // No validation needed - if we got here, auth passed!
-    // Business logic...
-  })
-);
-```
-
-### Benefits
-
-| Benefit                | Description                                                    |
-| ---------------------- | -------------------------------------------------------------- |
-| **Security at Edge**   | Validation happens at platform level before workflow execution |
-| **No Code Changes**    | Rotate keys by updating connection, not code                   |
-| **Resource Efficient** | Failed auth requests never consume workflow resources          |
-| **Consistent Pattern** | Same approach across all webhooks                              |
-| **Easier Testing**     | Clear separation: connection config vs business logic          |
-| **Better Logging**     | Platform logs all auth attempts automatically                  |
-
----
-
-## How It Works
-
-### Request Flow
-
-```
-┌─────────────────┐
-│  External       │
-│  System/Client  │
-└────────┬────────┘
-         │
-         │ POST /webhook/my-endpoint
-         │ Headers:
-         │   (as configured on the connection)
-         │ Body: { "data": "..." }
-         │
-         ▼
-   ┌────────────────────────────────────┐
-   │  Versori Platform (Edge Layer)     │
-   │                                    │
-   │  1. Connection-based authentication│
-   │  2. Load connection: my-webhook-auth│
-   │  3. Compare values (constant time) │
-   │                                    │
-   │  ✓ Valid?   → Continue to workflow │
-   │  ✗ Invalid? → Return 401/403       │
-   └────────┬───────────────────────────┘
-            │
-            │ ✅ Only valid requests proceed
-            ▼
-   ┌────────────────────────────────────┐
-   │  Your Workflow Code                │
-   │                                    │
-   │  - No auth validation needed       │
-   │  - Focus on business logic         │
-   │  - Process request data            │
-   └────────────────────────────────────┘
-```
-
-### Security Guarantee
-
-If your workflow code executes, authentication has already succeeded. **No manual validation required.**
-
----
-
-## Setup Guide
-
-### Step 1: Create API Key Connection
-
-1. **Navigate to Versori Dashboard**
-   - Go to your workspace
-   - Click **Connections** in sidebar
-   - Click **Add Connection**
-
-2. **Configure Connection**
-   - **Name**: `my-webhook-auth` (choose descriptive name)
-   - **Description**: `API key authentication for my-webhook endpoint`
-   - **Type**: `API Key Authentication`
-
-3. **Authentication**
-   - Configure auth on the connection (no inline headers or variables)
-
-4. **Save Connection**
-   - Click **Save**
-   - Note the connection name for use in code
-
-### Step 2: Generate Secure API Keys
-
-**Generate cryptographically secure keys (64+ characters recommended):**
-
-```bash
-# Node.js
-node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
-
-# Output example:
-# 7f3e9a2b1c8d6e4f5a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f
-
-# Python
-python3 -c "import secrets; print(secrets.token_hex(32))"
-
-# OpenSSL
-openssl rand -hex 32
-```
-
-**Key Requirements:**
-
-- Minimum 32 characters (64+ recommended)
-- Cryptographically random (don't make up keys!)
-- Alphanumeric (hex format is ideal)
-- Unique per environment (dev/staging/prod)
-- Unique per client (don't share keys between systems)
-
-### Step 3: Use Connection in Webhook Definition
-
-```typescript
-import { webhook, http } from '@versori/run';
-
-export const mySecureWebhook = webhook('my-webhook', {
-  connection: 'my-webhook-auth', // ✅ Reference connection by name
-  response: { mode: 'sync' },
-}).then(
-  http('process-data', { connection: 'fluent_commerce' }, async ctx => {
-    const { log, data } = ctx;
-
-    // ✅ Authentication already validated by Versori
-    // No manual checks needed!
-
-    log.info('Processing authenticated request', {
-      dataSize: JSON.stringify(data).length,
-    });
-
-    // Your business logic here
-    return {
-      success: true,
-      message: 'Request processed',
-      timestamp: new Date().toISOString(),
-    };
-  })
-);
-```
-
-### Step 4: Test the Webhook
-
-```bash
-# Test (auth handled by connection)
-curl -X POST https://your-workspace.versori.run/my-webhook \
-  -H "Content-Type: application/json" \
-  -d '{"test": "data"}'
-# Expected: 200 OK with workflow response when using valid connection
-```
-
----
-
-## Common Patterns
-
-### Pattern 1: Single Webhook, Single Connection
-
-**Use Case:** One webhook endpoint with one API key
-
-```typescript
-// Connection: 'order-webhook-auth'
-export const orderWebhook = webhook('order-ingestion', {
-  connection: 'order-webhook-auth',
-  response: { mode: 'sync' },
-}).then(
-  http('process-order', { connection: 'fluent_commerce' }, async ctx => {
-    // Process order...
-  })
-);
-```
-
-**Setup:**
-
-- Create 1 connection: `order-webhook-auth`
-- Use in 1 webhook definition
-
-### Pattern 2: Multiple Webhooks, Shared Connection
-
-**Use Case:** Multiple webhooks sharing same API key (same partner/client)
-
-```typescript
-// Connection: 'partner-api-auth' (shared)
-
-export const orderWebhook = webhook('orders', {
-  connection: 'partner-api-auth', // Shared connection
-  response: { mode: 'sync' },
-}).then(
-  http('process-order', { connection: 'fluent' }, async ctx => {
-    // Process order...
-  })
-);
-
-export const inventoryWebhook = webhook('inventory', {
-  connection: 'partner-api-auth', // Same connection
-  response: { mode: 'sync' },
-}).then(
-  http('process-inventory', { connection: 'fluent' }, async ctx => {
-    // Process inventory...
-  })
-);
-
-export const statusWebhook = webhook('status', {
-  connection: 'partner-api-auth', // Same connection
-  response: { mode: 'sync' },
-}).then(
-  http('query-status', { connection: 'fluent' }, async ctx => {
-    // Query status...
-  })
-);
-```
-
-**Setup:**
-
-- Create 1 connection: `partner-api-auth`
-- Use in 3 webhooks
-- All webhooks accept same API key
-- Easy to rotate: update 1 connection, affects all webhooks
-
-### Pattern 3: Multiple Webhooks, Different Connections
-
-**Use Case:** Different partners/clients need different API keys
-
-```typescript
-// Connections: 'partner-a-auth', 'partner-b-auth', 'partner-c-auth'
-
-export const partnerAWebhook = webhook('partner-a-orders', {
-  connection: 'partner-a-auth', // Partner A's key
-  response: { mode: 'sync' },
-}).then(
-  http('process', { connection: 'fluent' }, async ctx => {
-    // Partner A logic...
-  })
-);
-
-export const partnerBWebhook = webhook('partner-b-orders', {
-  connection: 'partner-b-auth', // Partner B's key
-  response: { mode: 'sync' },
-}).then(
-  http('process', { connection: 'fluent' }, async ctx => {
-    // Partner B logic...
-  })
-);
-
-export const partnerCWebhook = webhook('partner-c-orders', {
-  connection: 'partner-c-auth', // Partner C's key
-  response: { mode: 'sync' },
-}).then(
-  http('process', { connection: 'fluent' }, async ctx => {
-    // Partner C logic...
-  })
-);
-```
-
-**Setup:**
-
-- Create 3 connections: one per partner
-- Each webhook uses its partner's connection
-- Isolate security: compromised key only affects one partner
-- Rotate independently per partner
-
-### Pattern 4: Custom Header Names
-
-**Use Case:** Partner requires custom header
-
-```typescript
-// Connection: 'partner-auth'
-// Header: 'X-Partner-Token' (configured in Versori connection)
-
-export const partnerWebhook = webhook('partner-integration', {
-  connection: 'partner-auth', // Uses X-Partner-Token header
-  response: { mode: 'sync' },
-}).then(
-  http('process', { connection: 'fluent' }, async ctx => {
-    // Process...
-  })
-);
-```
-
-**Setup in Versori:**
-Configure partner-specific authentication on the connection (e.g., `X-Partner-Token`).
-
-**Partner's Request:**
-
-```bash
-curl -X POST https://workspace.versori.run/partner-integration \
-  -H "X-Partner-Token: abc123xyz" \
-  -H "Content-Type: application/json" \
-  -d '{"data": "..."}'
-```
-
----
-
-## Key Rotation
-
-### Zero-Downtime Key Rotation
-
-**Problem:** Need to rotate API key without breaking active integrations
-
-**Solution:** Dual-connection pattern (support old + new keys during transition)
-
-#### Step 1: Create New Connection
-
-```
-Use a new connection `my-webhook-auth-v2` with updated authentication settings.
-```
-
-#### Step 2: Update Webhook to Support Both Keys
-
-```typescript
-// Temporarily accept BOTH old and new keys
-// Note: This requires custom validation (see Advanced Patterns)
-
-export const myWebhook = webhook('my-webhook', {
-  // Remove connection temporarily for dual-key support
-  response: { mode: 'sync' },
-})
-  .then(
-    fn('validate-dual-keys', async ctx => {
-      const { request } = ctx;
-      const req = request();
-      const providedKey = req.headers.get('x-api-key');
-
-      // Accept either old or new key during transition
-      const validKeys = [
-        '<old-key>', // Get from old connection
-        '<new-key>', // Get from new connection
-      ];
-
-      if (!validKeys.some(k => constantTimeEqual(providedKey, k))) {
-        return new Response(JSON.stringify({ error: 'Unauthorized' }), {
-          status: 401,
-          headers: { 'Content-Type': 'application/json' },
-        });
-      }
-
-      return ctx.data;
-    })
-  )
-  .then(
-    http('process', { connection: 'fluent' }, async ctx => {
-      // Business logic...
-    })
-  );
-
-// Helper function for constant-time string comparison (timing attack prevention)
-function constantTimeEqual(a: string, b: string): boolean {
-  if (a.length !== b.length) return false;
-  let result = 0;
-  for (let i = 0; i < a.length; i++) {
-    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
-  }
-  return result === 0;
-}
-```
-
-#### Step 3: Notify Partners
-
-```
-Subject: API Key Rotation - Action Required
-
-We are rotating API keys for enhanced security.
-
-CURRENT KEY: abc123...
-REPLACEMENT KEY: xyz789...
-
-Please update your integration by 2025-11-15.
-
-Both keys will work until 2025-11-30.
-After that date, only the new key will be accepted.
-
-Update your requests:
-curl -X POST https://workspace.versori.run/webhook \
-  -H "x-api-key: xyz789..." \
-  -H "Content-Type: application/json" \
-  -d '{...}'
-```
-
-#### Step 4: Monitor Transition
-
-```typescript
-// Add logging to track which key is used
-fn('validate-dual-keys', async ctx => {
-  const providedKey = ctx.request().headers.get('x-api-key');
-
-  if (constantTimeEqual(providedKey, '<old-key>')) {
-    ctx.log.warn('Old API key used - please upgrade', {
-      keyPrefix: providedKey.substring(0, 8),
-    });
-  } else if (constantTimeEqual(providedKey, '<new-key>')) {
-    ctx.log.info('New API key used');
-  }
-
-  // ... validation
-});
-```
-
-#### Step 5: Remove Old Key
-
-After transition period:
-
-```typescript
-// Remove dual-key validation, switch back to connection-based
-
-export const myWebhook = webhook('my-webhook', {
-  connection: 'my-webhook-auth-v2', // Only new key
-  response: { mode: 'sync' },
-}).then(
-  http('process', { connection: 'fluent' }, async ctx => {
-    // Business logic...
-  })
-);
-```
-
----
-
-## Troubleshooting
-
-### Issue 1: "401 Unauthorized" on valid requests
-
-**Symptoms:**
-
-- Webhook always returns 401
-- You're certain the API key is correct
-
-**Possible Causes:**
-
-1. **Header name mismatch**
-
-   ```
-   ❌ Wrong:   Connection expects 'x-api-key', partner sends 'X-API-Key'
-   ✅ Correct: Match case and format exactly
-   ```
-
-2. **Whitespace in API key**
-
-   ```
-   ❌ Wrong:   Key has trailing space: "abc123 "
-   ✅ Correct: Trim key value in connection config
-   ```
-
-3. **Connection not linked to webhook**
-
-   ```typescript
-   ❌ Wrong:   webhook('my-webhook', {})  // Missing connection
-   ✅ Correct: webhook('my-webhook', { connection: 'my-webhook-auth' })
-   ```
-
-4. **Connection doesn't exist**
-   ```
-   ❌ Wrong:   Connection name typo: 'my-webohok-auth'
-   ✅ Correct: Verify exact name in Versori Dashboard
-   ```
-
-### Issue 2: Webhook works without authentication
-
-**Symptoms:**
-
-- Webhook accepts requests without API key
-- No 401 errors on invalid keys
-
-**Cause:** Connection not configured in webhook definition
-
-**Solution:**
-
-```typescript
-// ❌ WRONG - No auth
-export const myWebhook = webhook('my-webhook', {
-  response: { mode: 'sync' },
-});
-
-// ✅ CORRECT - With auth
-export const myWebhook = webhook('my-webhook', {
-  connection: 'my-webhook-auth', // ← Add this!
-  response: { mode: 'sync' },
-});
-```
-
-### Issue 3: "Connection not found" error
-
-**Symptoms:**
-
-- Deployment fails
-- Error: "Connection 'xyz' not found"
-
-**Cause:** Connection hasn't been created in Versori Dashboard
-
-**Solution:**
-
-1. Go to Versori Dashboard → Connections
-2. Create connection with exact name referenced in code
-3. Redeploy workflow
-
-### Issue 4: Can't test locally
-
-**Symptoms:**
-
-- Can't run webhook locally with API key validation
-
-**Solution:**
-For local development, temporarily disable connection-based auth:
-
-```typescript
-// Development mode
-const isDevelopment = process.env.NODE_ENV === 'development';
-
-export const myWebhook = webhook('my-webhook', {
-  connection: isDevelopment ? undefined : 'my-webhook-auth', // Conditional
-  response: { mode: 'sync' },
-})
-  .then(
-    fn('optional-local-validation', async ctx => {
-      if (isDevelopment) {
-        ctx.log.warn('Running in development mode - auth disabled');
-      }
-      return ctx.data;
-    })
-  )
-  .then(
-    http('process', { connection: 'fluent' }, async ctx => {
-      // Business logic...
-    })
-  );
-```
-
----
-
-## Security Considerations
-
-### What Connection-Based Auth Protects Against
-
-✅ **Unauthorized access** - No valid key = rejected at platform
-✅ **Resource exhaustion** - Failed auth never hits workflow
-✅ **Code injection** - Validation happens before code execution
-✅ **Information disclosure** - No error details leak from code
-
-### What It Does NOT Protect Against
-
-❌ **Replay attacks** - Same request can be sent multiple times
-❌ **Key compromise** - If key leaks, attacker has full access
-❌ **Man-in-the-middle** - Without HTTPS (Versori enforces HTTPS)
-❌ **Request tampering** - No signature validation (consider adding)
-
-### Enhancing Security
-
-**Layer 1: Connection-based auth (this guide)**
-
-```typescript
-webhook('my-webhook', {
-  connection: 'my-webhook-auth', // API key validation
-});
-```
-
-**Layer 2: Add request validation**
-
-```typescript
-.then(fn('validate-request', async (ctx) => {
-  const { data } = ctx;
-
-  // Check required fields
-  if (!data.id || !data.timestamp) {
-    return new Response(
-      JSON.stringify({ error: 'Missing required fields' }),
-      { status: 400 }
-    );
-  }
-
-  // Check timestamp (prevent replay of old requests)
-  const requestTime = new Date(data.timestamp).getTime();
-  const now = Date.now();
-  const maxAge = 5 * 60 * 1000; // 5 minutes
-
-  if (now - requestTime > maxAge) {
-    return new Response(
-      JSON.stringify({ error: 'Request expired' }),
-      { status: 400 }
-    );
-  }
-
-  return ctx.data;
-}))
-```
-
-**Layer 3: Add cryptographic signatures (for Fluent webhooks)**
-
-```typescript
-import { WebhookValidationService } from '@fluentcommerce/fc-connect-sdk';
-
-.then(fn('validate-signature', async (ctx) => {
-  const { request, vars } = ctx;
-  const req = request();
-
-  const signature = req.headers.get('fluent-signature');
-  const publicKey = vars?.FLUENT_WEBHOOK_PUBLIC_KEY;
-
-  const validator = new WebhookValidationService({ publicKey });
-  const result = validator.validateWebhook(
-    JSON.stringify(ctx.data),
-    signature,
-    'sha512'
-  );
-
-  if (!result.isValid) {
-    return new Response(
-      JSON.stringify({ error: 'Invalid signature' }),
-      { status: 403 }
-    );
-  }
-
-  return ctx.data;
-}))
-```
-
----
-
-## Summary
-
-### Quick Reference
-
-| Task                          | Action                                                                     |
-| ----------------------------- | -------------------------------------------------------------------------- |
-| **Secure a webhook**          | Add `connection: 'name'` to webhook definition                             |
-| **Create connection**         | Versori Dashboard → Connections → Add Connection                           |
-| **Generate API key**          | `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"` |
-| **Rotate key**                | Update connection value in Versori Dashboard                               |
-| **Share key across webhooks** | Use same connection name in multiple webhooks                              |
-| **Isolate keys per partner**  | Create separate connection for each partner                                |
-| **Custom header name**        | Set "Header Name" in connection config                                     |
-| **Test authentication**       | Try requests with valid/invalid/missing keys                               |
-
-### Benefits Recap
-
-✅ **Security at platform level** - Validation before code execution
-✅ **No code changes for rotation** - Update connection, not code
-✅ **Resource efficient** - Failed auth never consumes workflow resources
-✅ **Consistent pattern** - Same approach across all webhooks
-✅ **Easy testing** - Clear separation of concerns
-✅ **Better monitoring** - Platform logs all auth attempts
-
-### Related Documentation
-
-- `Webhook Validation (Cryptographic Signatures)`
-- [Versori Platform Integration](./modules/platforms-versori-01-introduction.md)
-- [Connection Management](./modules/platforms-versori-05-connections.md)
-- [Security Best Practices](./modules/platforms-versori-08-best-practices.md)
-
----
-
-**Questions?**
-
-- Check [Versori Documentation](https://docs.versori.com) for platform-specific details
-- See template examples in `docs/01-TEMPLATES/versori/workflows/`
-- Contact your Fluent Commerce integration team
-
----
-
-**Document Version:** 2.0 (Final - Connection-Based Only)
-**Maintained By:** FC Connect SDK Team
-
-**Changelog:**
-
-- v2.0: **Cleanup** - Removed OLD/NEW comparison language
-- v1.0: Initial version
+# Versori Webhook Connection-Based Security
+
+**Platform:** Versori
+**Security Pattern:** Connection-Level Authentication
+**Level:** Recommended
+**Last Updated:** 2025-10-28
+
+---
+
+## Overview
+
+This guide explains **connection-based webhook security** in Versori - how to authenticate webhook endpoints at the platform level BEFORE your workflow code runs.
+
+### Connection-Based Security Pattern
+
+```typescript
+export const myWebhook = webhook('my-webhook', {
+  connection: 'my-webhook-auth', // Versori validates BEFORE code runs
+  response: { mode: 'sync' },
+}).then(
+  http('process', { connection: 'fluent' }, async ctx => {
+    // No validation needed - if we got here, auth passed!
+    // Business logic...
+  })
+);
+```
+
+### Benefits
+
+| Benefit                | Description                                                    |
+| ---------------------- | -------------------------------------------------------------- |
+| **Security at Edge**   | Validation happens at platform level before workflow execution |
+| **No Code Changes**    | Rotate keys by updating connection, not code                   |
+| **Resource Efficient** | Failed auth requests never consume workflow resources          |
+| **Consistent Pattern** | Same approach across all webhooks                              |
+| **Easier Testing**     | Clear separation: connection config vs business logic          |
+| **Better Logging**     | Platform logs all auth attempts automatically                  |
+
+---
+
+## How It Works
+
+### Request Flow
+
+```
+┌─────────────────┐
+│  External       │
+│  System/Client  │
+└────────┬────────┘
+         │
+         │ POST /webhook/my-endpoint
+         │ Headers:
+         │   (as configured on the connection)
+         │ Body: { "data": "..." }
+         │
+         ▼
+   ┌────────────────────────────────────┐
+   │  Versori Platform (Edge Layer)     │
+   │                                    │
+   │  1. Connection-based authentication│
+   │  2. Load connection: my-webhook-auth│
+   │  3. Compare values (constant time) │
+   │                                    │
+   │  ✓ Valid?   → Continue to workflow │
+   │  ✗ Invalid? → Return 401/403       │
+   └────────┬───────────────────────────┘
+            │
+            │ ✅ Only valid requests proceed
+            ▼
+   ┌────────────────────────────────────┐
+   │  Your Workflow Code                │
+   │                                    │
+   │  - No auth validation needed       │
+   │  - Focus on business logic         │
+   │  - Process request data            │
+   └────────────────────────────────────┘
+```
+
+### Security Guarantee
+
+If your workflow code executes, authentication has already succeeded. **No manual validation required.**
+
+---
+
+## Setup Guide
+
+### Step 1: Create API Key Connection
+
+1. **Navigate to Versori Dashboard**
+   - Go to your workspace
+   - Click **Connections** in sidebar
+   - Click **Add Connection**
+
+2. **Configure Connection**
+   - **Name**: `my-webhook-auth` (choose descriptive name)
+   - **Description**: `API key authentication for my-webhook endpoint`
+   - **Type**: `API Key Authentication`
+
+3. **Authentication**
+   - Configure auth on the connection (no inline headers or variables)
+
+4. **Save Connection**
+   - Click **Save**
+   - Note the connection name for use in code
+
+### Step 2: Generate Secure API Keys
+
+**Generate cryptographically secure keys (64+ characters recommended):**
+
+```bash
+# Node.js
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+
+# Output example:
+# 7f3e9a2b1c8d6e4f5a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f
+
+# Python
+python3 -c "import secrets; print(secrets.token_hex(32))"
+
+# OpenSSL
+openssl rand -hex 32
+```
+
+**Key Requirements:**
+
+- Minimum 32 characters (64+ recommended)
+- Cryptographically random (don't make up keys!)
+- Alphanumeric (hex format is ideal)
+- Unique per environment (dev/staging/prod)
+- Unique per client (don't share keys between systems)
+
+### Step 3: Use Connection in Webhook Definition
+
+```typescript
+import { webhook, http } from '@versori/run';
+
+export const mySecureWebhook = webhook('my-webhook', {
+  connection: 'my-webhook-auth', // ✅ Reference connection by name
+  response: { mode: 'sync' },
+}).then(
+  http('process-data', { connection: 'fluent_commerce' }, async ctx => {
+    const { log, data } = ctx;
+
+    // ✅ Authentication already validated by Versori
+    // No manual checks needed!
+
+    log.info('Processing authenticated request', {
+      dataSize: JSON.stringify(data).length,
+    });
+
+    // Your business logic here
+    return {
+      success: true,
+      message: 'Request processed',
+      timestamp: new Date().toISOString(),
+    };
+  })
+);
+```
+
+### Step 4: Test the Webhook
+
+```bash
+# Test (auth handled by connection)
+curl -X POST https://your-workspace.versori.run/my-webhook \
+  -H "Content-Type: application/json" \
+  -d '{"test": "data"}'
+# Expected: 200 OK with workflow response when using valid connection
+```
+
+---
+
+## Common Patterns
+
+### Pattern 1: Single Webhook, Single Connection
+
+**Use Case:** One webhook endpoint with one API key
+
+```typescript
+// Connection: 'order-webhook-auth'
+export const orderWebhook = webhook('order-ingestion', {
+  connection: 'order-webhook-auth',
+  response: { mode: 'sync' },
+}).then(
+  http('process-order', { connection: 'fluent_commerce' }, async ctx => {
+    // Process order...
+  })
+);
+```
+
+**Setup:**
+
+- Create 1 connection: `order-webhook-auth`
+- Use in 1 webhook definition
+
+### Pattern 2: Multiple Webhooks, Shared Connection
+
+**Use Case:** Multiple webhooks sharing same API key (same partner/client)
+
+```typescript
+// Connection: 'partner-api-auth' (shared)
+
+export const orderWebhook = webhook('orders', {
+  connection: 'partner-api-auth', // Shared connection
+  response: { mode: 'sync' },
+}).then(
+  http('process-order', { connection: 'fluent' }, async ctx => {
+    // Process order...
+  })
+);
+
+export const inventoryWebhook = webhook('inventory', {
+  connection: 'partner-api-auth', // Same connection
+  response: { mode: 'sync' },
+}).then(
+  http('process-inventory', { connection: 'fluent' }, async ctx => {
+    // Process inventory...
+  })
+);
+
+export const statusWebhook = webhook('status', {
+  connection: 'partner-api-auth', // Same connection
+  response: { mode: 'sync' },
+}).then(
+  http('query-status', { connection: 'fluent' }, async ctx => {
+    // Query status...
+  })
+);
+```
+
+**Setup:**
+
+- Create 1 connection: `partner-api-auth`
+- Use in 3 webhooks
+- All webhooks accept same API key
+- Easy to rotate: update 1 connection, affects all webhooks
+
+### Pattern 3: Multiple Webhooks, Different Connections
+
+**Use Case:** Different partners/clients need different API keys
+
+```typescript
+// Connections: 'partner-a-auth', 'partner-b-auth', 'partner-c-auth'
+
+export const partnerAWebhook = webhook('partner-a-orders', {
+  connection: 'partner-a-auth', // Partner A's key
+  response: { mode: 'sync' },
+}).then(
+  http('process', { connection: 'fluent' }, async ctx => {
+    // Partner A logic...
+  })
+);
+
+export const partnerBWebhook = webhook('partner-b-orders', {
+  connection: 'partner-b-auth', // Partner B's key
+  response: { mode: 'sync' },
+}).then(
+  http('process', { connection: 'fluent' }, async ctx => {
+    // Partner B logic...
+  })
+);
+
+export const partnerCWebhook = webhook('partner-c-orders', {
+  connection: 'partner-c-auth', // Partner C's key
+  response: { mode: 'sync' },
+}).then(
+  http('process', { connection: 'fluent' }, async ctx => {
+    // Partner C logic...
+  })
+);
+```
+
+**Setup:**
+
+- Create 3 connections: one per partner
+- Each webhook uses its partner's connection
+- Isolate security: compromised key only affects one partner
+- Rotate independently per partner
+
+### Pattern 4: Custom Header Names
+
+**Use Case:** Partner requires custom header
+
+```typescript
+// Connection: 'partner-auth'
+// Header: 'X-Partner-Token' (configured in Versori connection)
+
+export const partnerWebhook = webhook('partner-integration', {
+  connection: 'partner-auth', // Uses X-Partner-Token header
+  response: { mode: 'sync' },
+}).then(
+  http('process', { connection: 'fluent' }, async ctx => {
+    // Process...
+  })
+);
+```
+
+**Setup in Versori:**
+Configure partner-specific authentication on the connection (e.g., `X-Partner-Token`).
+
+**Partner's Request:**
+
+```bash
+curl -X POST https://workspace.versori.run/partner-integration \
+  -H "X-Partner-Token: abc123xyz" \
+  -H "Content-Type: application/json" \
+  -d '{"data": "..."}'
+```
+
+---
+
+## Key Rotation
+
+### Zero-Downtime Key Rotation
+
+**Problem:** Need to rotate API key without breaking active integrations
+
+**Solution:** Dual-connection pattern (support old + new keys during transition)
+
+#### Step 1: Create New Connection
+
+```
+Use a new connection `my-webhook-auth-v2` with updated authentication settings.
+```
+
+#### Step 2: Update Webhook to Support Both Keys
+
+```typescript
+// Temporarily accept BOTH old and new keys
+// Note: This requires custom validation (see Advanced Patterns)
+
+export const myWebhook = webhook('my-webhook', {
+  // Remove connection temporarily for dual-key support
+  response: { mode: 'sync' },
+})
+  .then(
+    fn('validate-dual-keys', async ctx => {
+      const { request } = ctx;
+      const req = request();
+      const providedKey = req.headers.get('x-api-key');
+
+      // Accept either old or new key during transition
+      const validKeys = [
+        '<old-key>', // Get from old connection
+        '<new-key>', // Get from new connection
+      ];
+
+      if (!validKeys.some(k => constantTimeEqual(providedKey, k))) {
+        return new Response(JSON.stringify({ error: 'Unauthorized' }), {
+          status: 401,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+
+      return ctx.data;
+    })
+  )
+  .then(
+    http('process', { connection: 'fluent' }, async ctx => {
+      // Business logic...
+    })
+  );
+
+// Helper function for constant-time string comparison (timing attack prevention)
+function constantTimeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return result === 0;
+}
+```
+
+#### Step 3: Notify Partners
+
+```
+Subject: API Key Rotation - Action Required
+
+We are rotating API keys for enhanced security.
+
+CURRENT KEY: abc123...
+REPLACEMENT KEY: xyz789...
+
+Please update your integration by 2025-11-15.
+
+Both keys will work until 2025-11-30.
+After that date, only the new key will be accepted.
+
+Update your requests:
+curl -X POST https://workspace.versori.run/webhook \
+  -H "x-api-key: xyz789..." \
+  -H "Content-Type: application/json" \
+  -d '{...}'
+```
+
+#### Step 4: Monitor Transition
+
+```typescript
+// Add logging to track which key is used
+fn('validate-dual-keys', async ctx => {
+  const providedKey = ctx.request().headers.get('x-api-key');
+
+  if (constantTimeEqual(providedKey, '<old-key>')) {
+    ctx.log.warn('Old API key used - please upgrade', {
+      keyPrefix: providedKey.substring(0, 8),
+    });
+  } else if (constantTimeEqual(providedKey, '<new-key>')) {
+    ctx.log.info('New API key used');
+  }
+
+  // ... validation
+});
+```
+
+#### Step 5: Remove Old Key
+
+After transition period:
+
+```typescript
+// Remove dual-key validation, switch back to connection-based
+
+export const myWebhook = webhook('my-webhook', {
+  connection: 'my-webhook-auth-v2', // Only new key
+  response: { mode: 'sync' },
+}).then(
+  http('process', { connection: 'fluent' }, async ctx => {
+    // Business logic...
+  })
+);
+```
+
+---
+
+## Troubleshooting
+
+### Issue 1: "401 Unauthorized" on valid requests
+
+**Symptoms:**
+
+- Webhook always returns 401
+- You're certain the API key is correct
+
+**Possible Causes:**
+
+1. **Header name mismatch**
+
+   ```
+   ❌ Wrong:   Connection expects 'x-api-key', partner sends 'X-API-Key'
+   ✅ Correct: Match case and format exactly
+   ```
+
+2. **Whitespace in API key**
+
+   ```
+   ❌ Wrong:   Key has trailing space: "abc123 "
+   ✅ Correct: Trim key value in connection config
+   ```
+
+3. **Connection not linked to webhook**
+
+   ```typescript
+   ❌ Wrong:   webhook('my-webhook', {})  // Missing connection
+   ✅ Correct: webhook('my-webhook', { connection: 'my-webhook-auth' })
+   ```
+
+4. **Connection doesn't exist**
+   ```
+   ❌ Wrong:   Connection name typo: 'my-webohok-auth'
+   ✅ Correct: Verify exact name in Versori Dashboard
+   ```
+
+### Issue 2: Webhook works without authentication
+
+**Symptoms:**
+
+- Webhook accepts requests without API key
+- No 401 errors on invalid keys
+
+**Cause:** Connection not configured in webhook definition
+
+**Solution:**
+
+```typescript
+// ❌ WRONG - No auth
+export const myWebhook = webhook('my-webhook', {
+  response: { mode: 'sync' },
+});
+
+// ✅ CORRECT - With auth
+export const myWebhook = webhook('my-webhook', {
+  connection: 'my-webhook-auth', // ← Add this!
+  response: { mode: 'sync' },
+});
+```
+
+### Issue 3: "Connection not found" error
+
+**Symptoms:**
+
+- Deployment fails
+- Error: "Connection 'xyz' not found"
+
+**Cause:** Connection hasn't been created in Versori Dashboard
+
+**Solution:**
+
+1. Go to Versori Dashboard → Connections
+2. Create connection with exact name referenced in code
+3. Redeploy workflow
+
+### Issue 4: Can't test locally
+
+**Symptoms:**
+
+- Can't run webhook locally with API key validation
+
+**Solution:**
+For local development, temporarily disable connection-based auth:
+
+```typescript
+// Development mode
+const isDevelopment = process.env.NODE_ENV === 'development';
+
+export const myWebhook = webhook('my-webhook', {
+  connection: isDevelopment ? undefined : 'my-webhook-auth', // Conditional
+  response: { mode: 'sync' },
+})
+  .then(
+    fn('optional-local-validation', async ctx => {
+      if (isDevelopment) {
+        ctx.log.warn('Running in development mode - auth disabled');
+      }
+      return ctx.data;
+    })
+  )
+  .then(
+    http('process', { connection: 'fluent' }, async ctx => {
+      // Business logic...
+    })
+  );
+```
+
+---
+
+## Security Considerations
+
+### What Connection-Based Auth Protects Against
+
+✅ **Unauthorized access** - No valid key = rejected at platform
+✅ **Resource exhaustion** - Failed auth never hits workflow
+✅ **Code injection** - Validation happens before code execution
+✅ **Information disclosure** - No error details leak from code
+
+### What It Does NOT Protect Against
+
+❌ **Replay attacks** - Same request can be sent multiple times
+❌ **Key compromise** - If key leaks, attacker has full access
+❌ **Man-in-the-middle** - Without HTTPS (Versori enforces HTTPS)
+❌ **Request tampering** - No signature validation (consider adding)
+
+### Enhancing Security
+
+**Layer 1: Connection-based auth (this guide)**
+
+```typescript
+webhook('my-webhook', {
+  connection: 'my-webhook-auth', // API key validation
+});
+```
+
+**Layer 2: Add request validation**
+
+```typescript
+.then(fn('validate-request', async (ctx) => {
+  const { data } = ctx;
+
+  // Check required fields
+  if (!data.id || !data.timestamp) {
+    return new Response(
+      JSON.stringify({ error: 'Missing required fields' }),
+      { status: 400 }
+    );
+  }
+
+  // Check timestamp (prevent replay of old requests)
+  const requestTime = new Date(data.timestamp).getTime();
+  const now = Date.now();
+  const maxAge = 5 * 60 * 1000; // 5 minutes
+
+  if (now - requestTime > maxAge) {
+    return new Response(
+      JSON.stringify({ error: 'Request expired' }),
+      { status: 400 }
+    );
+  }
+
+  return ctx.data;
+}))
+```
+
+**Layer 3: Add cryptographic signatures (for Fluent webhooks)**
+
+```typescript
+import { WebhookValidationService } from '@fluentcommerce/fc-connect-sdk';
+
+.then(fn('validate-signature', async (ctx) => {
+  const { request, vars } = ctx;
+  const req = request();
+
+  const signature = req.headers.get('fluent-signature');
+  const publicKey = vars?.FLUENT_WEBHOOK_PUBLIC_KEY;
+
+  const validator = new WebhookValidationService({ publicKey });
+  const result = validator.validateWebhook(
+    JSON.stringify(ctx.data),
+    signature,
+    'sha512'
+  );
+
+  if (!result.isValid) {
+    return new Response(
+      JSON.stringify({ error: 'Invalid signature' }),
+      { status: 403 }
+    );
+  }
+
+  return ctx.data;
+}))
+```
+
+---
+
+## Summary
+
+### Quick Reference
+
+| Task                          | Action                                                                     |
+| ----------------------------- | -------------------------------------------------------------------------- |
+| **Secure a webhook**          | Add `connection: 'name'` to webhook definition                             |
+| **Create connection**         | Versori Dashboard → Connections → Add Connection                           |
+| **Generate API key**          | `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"` |
+| **Rotate key**                | Update connection value in Versori Dashboard                               |
+| **Share key across webhooks** | Use same connection name in multiple webhooks                              |
+| **Isolate keys per partner**  | Create separate connection for each partner                                |
+| **Custom header name**        | Set "Header Name" in connection config                                     |
+| **Test authentication**       | Try requests with valid/invalid/missing keys                               |
+
+### Benefits Recap
+
+✅ **Security at platform level** - Validation before code execution
+✅ **No code changes for rotation** - Update connection, not code
+✅ **Resource efficient** - Failed auth never consumes workflow resources
+✅ **Consistent pattern** - Same approach across all webhooks
+✅ **Easy testing** - Clear separation of concerns
+✅ **Better monitoring** - Platform logs all auth attempts
+
+### Related Documentation
+
+- `Webhook Validation (Cryptographic Signatures)`
+- [Versori Platform Integration](./modules/platforms-versori-01-introduction.md)
+- [Connection Management](./modules/platforms-versori-05-connections.md)
+- [Security Best Practices](./modules/platforms-versori-08-best-practices.md)
+
+---
+
+**Questions?**
+
+- Check [Versori Documentation](https://docs.versori.com) for platform-specific details
+- See template examples in `docs/01-TEMPLATES/versori/workflows/`
+- Contact your Fluent Commerce integration team
+
+---
+
+**Document Version:** 2.0 (Final - Connection-Based Only)
+**Maintained By:** FC Connect SDK Team
+
+**Changelog:**
+
+- v2.0: **Cleanup** - Removed OLD/NEW comparison language
+- v1.0: Initial version