@edge-markets/connect-node 1.7.0 → 1.9.0

package/README.md

@@ -10,7 +10,17 @@ 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
+- 📥 **Webhook inbox orchestration** - Durable accept/process/replay control flow with partner-owned storage
+- 🔐 **Token vault** - Versioned AES-256-GCM token encryption with key rotation
+- 🔄 **User sessions** - Token-store callbacks with refresh, encryption, and single-flight refresh protection
+- ⚙️ **Env config helper** - Build SDK config from standard EDGE env vars
+
+These helpers are framework-neutral: the SDK owns repeatable Connect mechanics
+such as token refresh, webhook validation, replay control flow, and transfer
+intent checks, while partner applications keep ownership of persistence, wallet
+mutation, admin authorization, and business rules.
 
 ## Installation
 
@@ -25,14 +35,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 +58,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 +108,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 +122,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 +136,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 +166,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,35 +225,76 @@ export async function POST(req: Request) {
 }
 ```
 
-## Token Refresh
+### Encrypting stored tokens
 
-Refresh tokens before they expire:
+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
-async function getValidAccessToken(userId: string): Promise<string> {
-  const connection = await db.edgeConnections.get(userId)
-  
-  // Refresh 5 minutes before expiry
-  const BUFFER = 5 * 60 * 1000
-  
-  if (Date.now() > connection.expiresAt.getTime() - BUFFER) {
-    const newTokens = await edge.refreshTokens(
-      decrypt(connection.refreshToken)
-    )
-    
-    await db.edgeConnections.update(userId, {
-      accessToken: encrypt(newTokens.accessToken),
-      refreshToken: encrypt(newTokens.refreshToken),
-      expiresAt: new Date(newTokens.expiresAt),
-    })
-    
-    return newTokens.accessToken
-  }
-  
-  return decrypt(connection.accessToken)
-}
+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 And User Sessions
+
+Use `EdgeUserSession` when you store encrypted tokens and want the SDK to
+handle decrypt-refresh-save-client lifecycle. You still own the database table
+and user mapping.
+
+```typescript
+const session = edge.createUserSession({
+  subjectId: userId,
+  tokenVault,
+  tokenStore: {
+    load: async (subjectId) => {
+      const row = await db.edgeConnections.get(subjectId)
+      return row?.encryptedTokens
+    },
+    save: async (subjectId, encryptedTokens, { tokens }) => {
+      await db.edgeConnections.update(subjectId, {
+        encryptedTokens,
+        expiresAt: new Date(tokens.expiresAt),
+      })
+    },
+  },
+  refreshSkewMs: 60_000,
+})
+
+const balance = await session.withClient((client) => client.getBalance())
+```
+
+`EdgeUserSession` refreshes near-expiry tokens, preserves refresh tokens when
+the token endpoint does not rotate them, saves the refreshed token envelope
+before returning a client, and single-flights concurrent refreshes on the same
+process. In horizontally scaled services, keep your storage callbacks
+idempotent or add DB-level optimistic locking.
+
+For migrations from split token columns, use `createSessionTokenRecord`,
+`parseSessionTokenRecord`, `normalizeSessionExpiresAt`, and
+`encryptLegacySessionTokens`. Plaintext migration requires an explicit
+`allowPlaintext: true` option so production request paths do not silently accept
+raw tokens.
+
 ## API Methods
 
 All user-scoped API methods live on `EdgeUserClient`, created via `edge.forUser(accessToken)`:
@@ -237,13 +369,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 +383,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 +393,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: EdgeWebhookEvent = JSON.parse(req.body.toString('utf8'))
+    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')
@@ -283,26 +414,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 +483,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 +495,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 +539,115 @@ 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.
+
+### Durable webhook inbox with `createWebhookInbox`
+
+For production integrations, accept a verified webhook into durable storage
+before returning `200`, then process it asynchronously. The SDK can own the
+state machine while your app owns the database callbacks and wallet mutation.
+
+```typescript
+import {
+  createWebhookInbox,
+  parseWebhookHttpRequest,
+} from '@edge-markets/connect-node'
+
+const inbox = createWebhookInbox({
+  store: {
+    insert: db.webhookInbox.insertIdempotently,
+    find: db.webhookInbox.find,
+    markProcessing: db.webhookInbox.markProcessing,
+    markProcessed: db.webhookInbox.markProcessed,
+    markFailed: db.webhookInbox.markFailed,
+    markPending: db.webhookInbox.markPending,
+    list: db.webhookInbox.list,
+  },
+  processEvent: async (event) => {
+    // Partner-owned business logic. Keep wallet mutation idempotent.
+    await processEdgeEvent(event)
+  },
+})
+
+app.post('/webhooks/edge', express.raw({ type: 'application/json' }), async (req, res) => {
+  const parsed = parseWebhookHttpRequest({
+    request: { headers: req.headers, rawBody: req.body },
+    secret: process.env.EDGE_WEBHOOK_SECRET!,
+  })
+
+  const accepted = await inbox.acceptRaw(
+    parsed,
+    Buffer.from(req.body).toString('utf8'),
+    String(req.headers['x-edge-signature'] ?? ''),
+  )
+
+  res.status(200).json({
+    received: true,
+    duplicate: accepted.duplicate,
+    status: accepted.status,
+  })
+
+  void inbox.process(accepted.eventId).catch((error) => {
+    logger.error('EDGE webhook processing failed', { eventId: accepted.eventId, error })
+  })
+})
+```
+
+The inbox statuses are `pending`, `processing`, `processed`, and `failed`.
+Duplicate `event.id` deliveries are idempotent if the payload fingerprint
+matches. A duplicate event ID with different payload fails closed.
+
+Sync reconciliation can use the same inbox path:
+
+```typescript
+const reconciler = edge.createWebhookReconciler({
+  cursorStore,
+  inbox,
+  limit: 100,
+})
+```
+
+The reconciler accepts each synced event into the inbox, processes it, and saves
+the cursor only after processing succeeds or the event is already processed.
+Use `inbox.replay(eventId)` for explicit admin replays and
+`inbox.recoverStaleProcessing()` to make crashed `processing` rows replayable.
+
+### Transfer safety helpers
+
+Use transfer helpers to avoid decimal and direction mistakes:
+
+```typescript
+import {
+  assertWebhookMatchesTransfer,
+  createTransferIdempotencyKey,
+  getConnectTransferDirection,
+  mapTransferStatusToPartnerState,
+  normalizeMoneyAmount,
+  validateTransferAmount,
+} from '@edge-markets/connect-node'
+
+const amount = validateTransferAmount(input.amount, { min: '1.00', max: '10000.00' }, { allowNumber: false })
+const idempotencyKey = createTransferIdempotencyKey({
+  partnerUserId: user.id,
+  type: 'debit',
+  amount,
+  category: 'sportsbook',
+  externalId: bet.id,
+})
+
+// debit = EDGE user to partner; credit = partner to EDGE user
+const direction = getConnectTransferDirection('debit')
+
+assertWebhookMatchesTransfer(event, {
+  transferId: localTransfer.edgeTransferId,
+  type: 'debit',
+  amount: localTransfer.amount,
+})
+```
+
 ## Error Handling
 
 ```typescript