@edge-markets/connect-node 1.6.1 → 1.8.0

package/README.md

@@ -9,6 +9,11 @@ Server SDK for EDGE Connect token exchange and API calls.
 - 📡 **Full API client** - User, balance, transfers via `forUser()` pattern
 - 🛡️ **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
 
@@ -23,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)
@@ -49,20 +51,75 @@ 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 OAuth client ID
-  clientSecret: string          // Your OAuth client secret (keep secret!)
+  clientId: string              // Your user-facing OAuth client ID
+  clientSecret: string          // Your user-facing OAuth client secret (keep secret!)
   environment: EdgeEnvironment  // 'production' | 'staging' | 'sandbox'
-  
+
   // 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
   onRequest?: (info) => void    // Hook called before each request
   onResponse?: (info) => void   // Hook called after each response
 
+  // Optional: Partner-level credentials for non-user-scoped endpoints.
+  // Required ONLY when calling syncWebhookEvents — the rest of the SDK
+  // works without them. These are a DIFFERENT OAuth client than clientId
+  // (machine-to-machine, not user-facing).
+  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
@@ -72,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
+  }
 }
 ```
 
@@ -94,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:
@@ -125,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:
@@ -195,7 +318,10 @@ const session = await client.createVerificationSession(transfer.transferId, {
 // 3. Listen for the postMessage event from the iframe (or poll
 //    getVerificationSessionStatus) to learn when verification completes.
 //    A `transfer.completed` webhook will be delivered to your configured
-//    webhook URL once the transfer settles.
+//    webhook URL once the transfer settles. For browser-crash recovery,
+//    your backend should also reconcile against
+//    GET /v1/partner/webhooks/events/sync using a dashboard
+//    client_credentials token from POST /connect/oauth/token.
 
 // Get transfer status
 const status = await client.getTransfer(transfer.transferId)
@@ -218,6 +344,188 @@ await client.revokeConsent()
 await db.edgeConnections.delete(userId)
 ```
 
+## Webhooks
+
+EDGE Connect delivers webhook events to your server when transfers complete,
+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.
+
+### 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 `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
+> and silently breaks verification with no diagnostic. Always capture the
+> raw body via your framework's raw-body middleware.
+
+```typescript
+import { parseAndVerifyWebhook } from '@edge-markets/connect-node'
+import express from 'express'
+
+const app = express()
+
+app.post(
+  '/webhooks/edge',
+  // 👇 Critical: this gives you req.body as a Buffer, not a parsed object
+  express.raw({ type: 'application/json' }),
+  (req, res) => {
+    const { event, eventId, signatureTimestamp } = parseAndVerifyWebhook({
+      rawBody: req.body,
+      signatureHeader: req.headers['x-edge-signature'],
+      secret: process.env.EDGE_WEBHOOK_SECRET!,
+    })
+
+    // 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')
+  },
+)
+```
+
+#### NestJS
+
+```typescript
+// main.ts
+const app = await NestFactory.create(AppModule, { rawBody: true })
+
+// edge-webhook.controller.ts
+import { Controller, Post, Req, HttpCode, UnauthorizedException, type RawBodyRequest } from '@nestjs/common'
+import type { Request } from 'express'
+import { EdgeAuthenticationError, parseAndVerifyWebhook } from '@edge-markets/connect-node'
+
+@Controller('webhooks')
+export class EdgeWebhookController {
+  @Post('edge')
+  @HttpCode(200)
+  handle(@Req() req: RawBodyRequest<Request>) {
+    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
+narrows `event.data` automatically — no casts required.
+
+```typescript
+import type { EdgeWebhookEvent } from '@edge-markets/connect-node'
+
+function processEdgeEvent(event: EdgeWebhookEvent) {
+  switch (event.type) {
+    case 'transfer.completed':
+      // event.data is { transferId, status: 'completed', type, amount }
+      creditWallet(event.data.transferId, event.data.amount)
+      break
+    case 'transfer.failed':
+      // event.data.reason is `string | undefined`
+      logFailure(event.data.transferId, event.data.reason ?? 'unknown')
+      break
+    case 'transfer.expired':
+      cancelPending(event.data.transferId)
+      break
+    case 'transfer.processing':
+      // @experimental — reserved for ledger dual-write hand-off
+      break
+    case 'consent.revoked':
+      deactivateLink(event.data.userId, event.data.clientId)
+      break
+    default: {
+      const _exhaustive: never = event
+      return _exhaustive
+    }
+  }
+}
+```
+
+`event.data.amount` is intentionally a `string` (e.g. `'100.00'`), not a
+number, to preserve decimal precision — parse it with a decimal-aware
+library on your side.
+
+### 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
+is typical) to catch anything your primary receiver missed.
+
+This method requires the partner-level credentials (`partnerClientId` /
+`partnerClientSecret`) on `EdgeConnectServer`. It uses the OAuth
+`client_credentials` grant, caches the partner token internally, and
+handles a 401 by refreshing the token once and retrying.
+
+```typescript
+import { createEdgeConnectServerFromEnv } from '@edge-markets/connect-node'
+
+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() {
+  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.
+
+### Best practices
+
+1. **Verify signatures first** — reject mis-signed events with 401 before
+   doing any work.
+2. **Return 200 immediately** — process events asynchronously. EDGE retries
+   on non-2xx and on responses slower than 10s.
+3. **Be idempotent** — the same event may be delivered more than once
+   (at-least-once delivery). Key your wallet credit / status update on
+   `event.id` or `event.data.transferId`.
+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