@edge-markets/connect-node 1.7.0 → 1.8.0

package/README.md

@@ -10,7 +10,10 @@ Server SDK for EDGE Connect token exchange and API calls.
 - 🛡️ **Typed errors** - Specific error classes for each scenario
 - 📝 **TypeScript first** - Complete type definitions
 - 🪝 **Webhook signature verification** - Constant-time HMAC-SHA256 with replay protection
+- ✅ **Webhook parsing + validation** - Verify raw bodies and fail closed on malformed event payloads
 - 🔁 **Webhook reconciliation** - Cursor-based sync for catching missed events
+- 🔐 **Token vault** - Versioned AES-256-GCM token encryption with key rotation
+- ⚙️ **Env config helper** - Build SDK config from standard EDGE env vars
 
 ## Installation
 
@@ -25,14 +28,11 @@ yarn add @edge-markets/connect-node
 ## Quick Start
 
 ```typescript
-import { EdgeConnectServer } from '@edge-markets/connect-node'
+import { createEdgeConnectServerFromEnv } from '@edge-markets/connect-node'
 
-// Create instance once (reuse for all requests)
-const edge = new EdgeConnectServer({
-  clientId: process.env.EDGE_CLIENT_ID!,
-  clientSecret: process.env.EDGE_CLIENT_SECRET!,
-  environment: 'staging',
-})
+// Create instance once (reuse for all requests). Reads EDGE_CLIENT_ID,
+// EDGE_CLIENT_SECRET, EDGE_ENVIRONMENT, optional mTLS and partner sync env vars.
+const { server: edge } = createEdgeConnectServerFromEnv()
 
 // Exchange code from EdgeLink for tokens
 const tokens = await edge.exchangeCode(code, codeVerifier)
@@ -51,6 +51,48 @@ Never expose your client secret to browsers or client-side code.
 
 ## Configuration
 
+### From environment variables
+
+Most partner backends should use `createEdgeConnectServerFromEnv()` so mTLS
+PEM handling, partner sync credentials, URL overrides, and timeout parsing are
+consistent across integrations.
+
+```typescript
+import { createEdgeConnectServerFromEnv } from '@edge-markets/connect-node'
+
+const { server: edge, capabilities, warnings } = createEdgeConnectServerFromEnv({
+  requireMtls: process.env.NODE_ENV === 'production',
+})
+
+warnings.forEach((warning) => logger.warn(warning))
+
+if (!capabilities.webhookSyncConfigured) {
+  logger.warn('EDGE webhook sync is not configured; set EDGE_PARTNER_CLIENT_ID and EDGE_PARTNER_CLIENT_SECRET')
+}
+```
+
+Supported environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `EDGE_CLIENT_ID` | User-facing OAuth client ID |
+| `EDGE_CLIENT_SECRET` | User-facing OAuth client secret |
+| `EDGE_ENVIRONMENT` | `production`, `staging`, `sandbox`, or `development` |
+| `EDGE_API_BASE_URL` | Optional Connect API override |
+| `EDGE_OAUTH_BASE_URL` | Optional OAuth/token URL override |
+| `EDGE_PARTNER_API_BASE_URL` | Optional partner dashboard API override |
+| `EDGE_PARTNER_CLIENT_ID` | Partner machine-to-machine client ID for webhook sync |
+| `EDGE_PARTNER_CLIENT_SECRET` | Partner machine-to-machine client secret for webhook sync |
+| `EDGE_MTLS_CERT` / `EDGE_MTLS_CERT_PATH` | Client certificate PEM or file path |
+| `EDGE_MTLS_KEY` / `EDGE_MTLS_KEY_PATH` | Client private key PEM or file path |
+| `EDGE_MTLS_CA` / `EDGE_MTLS_CA_PATH` | Optional extra server trust root PEM or file path |
+| `EDGE_TIMEOUT_MS` | Optional request timeout in milliseconds |
+
+Use inline PEMs with escaped newlines (`\n`) or file paths. If both are set,
+the inline value wins and the helper returns a warning.
+
+### Manual configuration
+
 ```typescript
 interface EdgeConnectServerConfig {
   clientId: string              // Your user-facing OAuth client ID
@@ -59,6 +101,7 @@ interface EdgeConnectServerConfig {
 
   // Optional
   apiBaseUrl?: string           // Custom API URL (dev only)
+  partnerApiBaseUrl?: string    // Custom partner dashboard API URL (dev only)
   oauthBaseUrl?: string         // Custom OAuth URL (dev only)
   timeout?: number              // Request timeout (default: 30000ms)
   retry?: RetryConfig           // Retry configuration
@@ -72,6 +115,11 @@ interface EdgeConnectServerConfig {
   partnerClientId?: string
   partnerClientSecret?: string
 
+  // By default the SDK derives partnerApiBaseUrl from apiBaseUrl by replacing
+  // /connect/v1 with /v1. For example:
+  // https://connect-staging.edgeboost.io/connect/v1
+  // -> https://connect-staging.edgeboost.io/v1
+
   // Optional: Message Level Encryption (Connect endpoints only)
   mle?: {
     enabled: boolean
@@ -81,6 +129,14 @@ interface EdgeConnectServerConfig {
     partnerKeyId: string        // Your key ID (kid) expected in response headers
     strictResponseEncryption?: boolean // default true
   }
+
+  // Optional: Mutual TLS client authentication
+  mtls?: {
+    enabled: boolean
+    cert: string                // Your client certificate PEM
+    key: string                 // Your client private key PEM
+    ca?: string | string[]      // Additional server trust roots, if EDGE provides them
+  }
 }
 ```
 
@@ -103,6 +159,34 @@ const edge = new EdgeConnectServer({
 
 When enabled, the SDK sends `X-Edge-MLE: v1`, encrypts request bodies, and decrypts encrypted Connect responses.
 
+### Mutual TLS (mTLS)
+
+Use `mtls` when EDGE has issued your partner backend a client certificate and key:
+
+```typescript
+const edge = new EdgeConnectServer({
+  clientId: process.env.EDGE_CLIENT_ID!,
+  clientSecret: process.env.EDGE_CLIENT_SECRET!,
+  environment: 'staging',
+  mtls: {
+    enabled: true,
+    cert: process.env.EDGE_MTLS_CERT!,
+    key: process.env.EDGE_MTLS_KEY!,
+  },
+})
+```
+
+`cert` and `key` authenticate your backend to EDGE Connect. They are client
+authentication material and must stay on your server.
+
+`ca` is optional server trust material. Public EDGE Connect gateways such as
+`https://connect.edgeboost.io` and `https://connect-staging.edgeboost.io` use
+public certificates, so most partners should omit `ca`. If EDGE provides a
+private server CA for a non-public endpoint, pass it as `ca`; the SDK appends it
+to Node's default public trust roots instead of replacing them.
+
+Do not disable TLS verification and do not set `NODE_TLS_REJECT_UNAUTHORIZED=0`.
+
 ## Token Exchange
 
 After EdgeLink completes, exchange the code for tokens:
@@ -134,6 +218,36 @@ export async function POST(req: Request) {
 }
 ```
 
+### Encrypting stored tokens
+
+Store access and refresh tokens encrypted at rest. `EdgeTokenVault` gives
+partners a stable AES-256-GCM envelope with key IDs and key rotation support;
+you still choose the database table and user mapping.
+
+```typescript
+import { createEdgeTokenVault } from '@edge-markets/connect-node'
+
+const tokenVault = createEdgeTokenVault({
+  currentKey: {
+    id: process.env.EDGE_TOKEN_ENCRYPTION_KEY_ID ?? '2026-06',
+    key: process.env.EDGE_TOKEN_ENCRYPTION_KEY!, // 32 bytes as base64, base64url, or hex
+  },
+  previousKeys: [
+    // { id: '2026-05', key: process.env.EDGE_TOKEN_ENCRYPTION_KEY_2026_05! },
+  ],
+})
+
+const tokens = await edge.exchangeCode(code, codeVerifier)
+await db.edgeConnections.upsert({
+  userId,
+  encryptedTokens: tokenVault.encryptTokens(tokens),
+})
+
+const connection = await db.edgeConnections.get(userId)
+const decrypted = tokenVault.decryptTokens(connection.encryptedTokens)
+const client = edge.forUser(decrypted.accessToken)
+```
+
 ## Token Refresh
 
 Refresh tokens before they expire:
@@ -237,13 +351,13 @@ fail, expire, or when a user revokes consent. The SDK provides two helpers:
 **signature verification** for the live HTTP delivery channel, and a
 **reconciliation sync method** for the cron-driven safety net.
 
-### Verify webhook signatures
+### Parse and verify webhook deliveries
 
 Every webhook arrives with an `X-Edge-Signature` header in `t=...,v1=...`
 format — HMAC-SHA256 over `${timestamp}.${rawBody}` keyed by your webhook
-secret. Use `verifyWebhookSignature` to check it. The function does
-constant-time comparison and rejects events older than 5 minutes by default
-to prevent replay attacks.
+secret. Use `parseAndVerifyWebhook` to verify the signature, parse JSON, and
+runtime-validate the typed event envelope in one step. The helper rejects
+events older than 5 minutes by default to prevent replay attacks.
 
 > ⚠️ **The `body` argument MUST be the raw request bytes**, not a parsed
 > object that you re-stringified. `JSON.stringify(req.body)` reorders keys
@@ -251,7 +365,7 @@ to prevent replay attacks.
 > raw body via your framework's raw-body middleware.
 
 ```typescript
-import { verifyWebhookSignature, type EdgeWebhookEvent } from '@edge-markets/connect-node'
+import { parseAndVerifyWebhook } from '@edge-markets/connect-node'
 import express from 'express'
 
 const app = express()
@@ -261,14 +375,13 @@ app.post(
   // 👇 Critical: this gives you req.body as a Buffer, not a parsed object
   express.raw({ type: 'application/json' }),
   (req, res) => {
-    const ok = verifyWebhookSignature(
-      req.headers['x-edge-signature'] as string,
-      req.body.toString('utf8'),
-      process.env.EDGE_WEBHOOK_SECRET!,
-    )
-    if (!ok) return res.status(401).send('invalid signature')
+    const { event, eventId, signatureTimestamp } = parseAndVerifyWebhook({
+      rawBody: req.body,
+      signatureHeader: req.headers['x-edge-signature'],
+      secret: process.env.EDGE_WEBHOOK_SECRET!,
+    })
 
-    const event: EdgeWebhookEvent = JSON.parse(req.body.toString('utf8'))
+    // Store eventId + signatureTimestamp in your durable inbox if you use one.
     // Process asynchronously and return 200 immediately — see "Best Practices"
     void processEdgeEvent(event)
     res.status(200).send('ok')
@@ -283,26 +396,36 @@ app.post(
 const app = await NestFactory.create(AppModule, { rawBody: true })
 
 // edge-webhook.controller.ts
-import { Controller, Post, Req, HttpCode, type RawBodyRequest } from '@nestjs/common'
+import { Controller, Post, Req, HttpCode, UnauthorizedException, type RawBodyRequest } from '@nestjs/common'
 import type { Request } from 'express'
-import { verifyWebhookSignature } from '@edge-markets/connect-node'
+import { EdgeAuthenticationError, parseAndVerifyWebhook } from '@edge-markets/connect-node'
 
 @Controller('webhooks')
 export class EdgeWebhookController {
   @Post('edge')
   @HttpCode(200)
   handle(@Req() req: RawBodyRequest<Request>) {
-    const ok = verifyWebhookSignature(
-      req.headers['x-edge-signature'] as string,
-      req.rawBody?.toString('utf8') ?? '',
-      process.env.EDGE_WEBHOOK_SECRET!,
-    )
-    if (!ok) throw new UnauthorizedException('invalid signature')
-    // ...
+    try {
+      const { event } = parseAndVerifyWebhook({
+        rawBody: req.rawBody ?? Buffer.from(''),
+        signatureHeader: req.headers['x-edge-signature'],
+        secret: process.env.EDGE_WEBHOOK_SECRET!,
+      })
+      void processEdgeEvent(event)
+    } catch (error) {
+      if (error instanceof EdgeAuthenticationError) {
+        throw new UnauthorizedException('invalid signature')
+      }
+      throw error
+    }
   }
 }
 ```
 
+`verifyWebhookSignature` remains exported for advanced integrations, but
+`parseAndVerifyWebhook` is the recommended default because it fails closed on
+unknown event types, malformed payloads, and parsed-body mistakes.
+
 ### Type-safe event handling with `EdgeWebhookEvent`
 
 `EdgeWebhookEvent` is a discriminated union over `event.type`. Switching
@@ -342,7 +465,7 @@ function processEdgeEvent(event: EdgeWebhookEvent) {
 number, to preserve decimal precision — parse it with a decimal-aware
 library on your side.
 
-### Reconcile missed events with `syncWebhookEvents`
+### Reconcile missed events with `createWebhookReconciler`
 
 Even with retries and a dead-letter queue, network or partner outages can
 drop webhook events. Run `syncWebhookEvents` from a cron (every ~5 minutes
@@ -354,32 +477,34 @@ This method requires the partner-level credentials (`partnerClientId` /
 handles a 401 by refreshing the token once and retrying.
 
 ```typescript
-import { EdgeConnectServer } from '@edge-markets/connect-node'
+import { createEdgeConnectServerFromEnv } from '@edge-markets/connect-node'
 
-const edge = new EdgeConnectServer({
-  clientId: process.env.EDGE_CLIENT_ID!,
-  clientSecret: process.env.EDGE_CLIENT_SECRET!,
-  environment: 'staging',
-  partnerClientId: process.env.EDGE_PARTNER_CLIENT_ID!,
-  partnerClientSecret: process.env.EDGE_PARTNER_CLIENT_SECRET!,
+const { server: edge } = createEdgeConnectServerFromEnv()
+
+const reconciler = edge.createWebhookReconciler({
+  cursorStore: {
+    load: () => db.cursors.get('edge_webhook_sync'),
+    save: (cursor) => db.cursors.set('edge_webhook_sync', cursor),
+  },
+  processEvent: processEdgeEvent, // same idempotent handler as live webhooks
+  limit: 100,
+  maxPages: 10,
 })
 
 async function reconcile() {
-  let cursor = await db.cursors.get('edge') // your stored watermark
-  while (true) {
-    const { events, hasMore } = await edge.syncWebhookEvents({ afterEventId: cursor })
-    for (const event of events) {
-      await processEdgeEvent(event) // same idempotent handler as live webhooks
-      cursor = event.id
-    }
-    if (events.length > 0) await db.cursors.set('edge', cursor!)
-    if (!hasMore) break
-  }
+  const result = await reconciler.run()
+  logger.info('EDGE webhook reconciliation complete', result)
 }
 
 setInterval(reconcile, 5 * 60 * 1000)
 ```
 
+The reconciler saves the cursor only after `processEvent(event)` succeeds and
+skips overlapping runs on the same instance. You provide cursor storage and
+the idempotent event handler; the SDK owns pagination and cursor advancement.
+
+If you need full control, `edge.syncWebhookEvents()` remains available.
+
 The server enforces a **30-day lookback**. If your cursor is older than 30
 days, you will receive events from 30 days ago — re-bootstrap from a known
 good state via `getTransfer` if you have been offline for longer.
@@ -396,6 +521,11 @@ good state via `getTransfer` if you have been offline for longer.
 4. **Run reconciliation as a backstop** — webhooks are the fast path,
    `syncWebhookEvents` is the safety net. They share the same handler.
 
+`syncWebhookEvents` uses the same SDK mTLS transport as user-scoped API
+calls, fetches and caches the partner `client_credentials` token internally,
+retries transient sync failures with the SDK retry policy, and redacts token
+material from observability hooks.
+
 ## Error Handling
 
 ```typescript