@edge-markets/connect-node 1.8.0 → 1.10.0

package/dist/index.mjs

@@ -19,23 +19,39 @@ import {
   getEnvironmentConfig
 } from "@edge-markets/connect";
 
+// src/edge-user-client.ts
+import { EdgeFeatureUnavailableError as EdgeFeatureUnavailableError2 } from "@edge-markets/connect";
+
 // src/transfer-helpers.ts
 import {
+  EdgeFeatureUnavailableError,
   EdgeValidationError
 } from "@edge-markets/connect";
 import crypto from "crypto";
 var DEFAULT_MIN_AMOUNT = "1.00";
 var DEFAULT_MAX_AMOUNT = "10000.00";
-function normalizeMoneyAmount(value) {
-  const cents = parseMoneyToCents(value, "amount");
+var CONNECT_TRANSFER_DIRECTIONS = {
+  debit: "user_to_partner",
+  credit: "partner_to_user"
+};
+function getConnectTransferDirection(type) {
+  if (type !== "debit" && type !== "credit") {
+    throw new EdgeValidationError("Invalid Connect transfer type", {
+      type: ['Must be "debit" or "credit"']
+    });
+  }
+  return CONNECT_TRANSFER_DIRECTIONS[type];
+}
+function normalizeMoneyAmount(value, options = {}) {
+  const cents = parseMoneyToCents(value, "amount", options);
   const dollars = cents / 100n;
   const remainder = cents % 100n;
   return `${dollars.toString()}.${remainder.toString().padStart(2, "0")}`;
 }
-function validateTransferAmount(value, limits = {}) {
-  const amount = parseMoneyToCents(value, "amount");
-  const min = parseMoneyToCents(limits.min ?? DEFAULT_MIN_AMOUNT, "min");
-  const max = parseMoneyToCents(limits.max ?? DEFAULT_MAX_AMOUNT, "max");
+function validateTransferAmount(value, limits = {}, options = {}) {
+  const amount = parseMoneyToCents(value, "amount", options);
+  const min = parseMoneyToCents(limits.min ?? DEFAULT_MIN_AMOUNT, "min", { allowNumber: true });
+  const max = parseMoneyToCents(limits.max ?? DEFAULT_MAX_AMOUNT, "max", { allowNumber: true });
   const errors = {};
   if (min <= 0n) errors.min = ["Minimum amount must be greater than 0"];
   if (max < min) errors.max = ["Maximum amount must be greater than or equal to minimum amount"];
@@ -83,7 +99,29 @@ function assertSameTransferIntent(existing, requested) {
     throw new EdgeValidationError("Transfer intent does not match existing idempotent transfer", errors);
   }
 }
+function fingerprintTransferIntent(intent) {
+  return crypto.createHash("sha256").update(
+    JSON.stringify({
+      type: intent.type,
+      amount: normalizeMoneyAmount(intent.amount),
+      category: intent.category ?? null
+    })
+  ).digest("hex");
+}
+function moneyAmountsEqual(left, right, options = {}) {
+  return normalizeMoneyAmount(left, options) === normalizeMoneyAmount(right, options);
+}
+function mapTransferStatusToPartnerState(status, mapping) {
+  const partnerState = mapping[status];
+  if (!partnerState) {
+    throw new EdgeValidationError("Unsupported transfer status", {
+      status: [`Unsupported status: ${status}`]
+    });
+  }
+  return partnerState;
+}
 async function startTransferVerification(client, options) {
+  assertTransferFeatureAvailable();
   const origin = typeof options.origin === "string" ? options.origin.trim() : "";
   if (!origin) {
     throw new EdgeValidationError("Verification origin is required", {
@@ -103,9 +141,22 @@ async function startTransferVerification(client, options) {
   const verificationSession = await client.createVerificationSession(transferId, { origin });
   return { transfer, verificationSession };
 }
-function parseMoneyToCents(value, field) {
+function assertTransferFeatureAvailable() {
+  if (!isTransferFeatureAvailable()) {
+    throw new EdgeFeatureUnavailableError();
+  }
+}
+function isTransferFeatureAvailable() {
+  return false;
+}
+function parseMoneyToCents(value, field, options = {}) {
   let input;
   if (typeof value === "number") {
+    if (options.allowNumber === false) {
+      throw new EdgeValidationError("Money amount must be a string in strict mode", {
+        [field]: ['Pass a decimal string like "25.00"']
+      });
+    }
     if (!Number.isFinite(value)) {
       throw new EdgeValidationError("Money amount must be finite", { [field]: ["Must be a finite number"] });
     }
@@ -219,6 +270,7 @@ var EdgeUserClient = class {
     return this.server._apiRequest("GET", "/balance", this.accessToken);
   }
   async initiateTransfer(options) {
+    assertTransferFeatureAvailable2();
     validateTransferOptions(options);
     const body = {
       type: options.type,
@@ -231,13 +283,16 @@ var EdgeUserClient = class {
     return this.server._apiRequest("POST", "/transfer", this.accessToken, body);
   }
   async startTransferVerification(options) {
+    assertTransferFeatureAvailable2();
     return startTransferVerification(this, options);
   }
   async getTransfer(transferId) {
+    assertTransferFeatureAvailable2();
     validateTransferId(transferId);
     return this.server._apiRequest("GET", `/transfer/${encodeURIComponent(transferId)}`, this.accessToken);
   }
   async listTransfers(params) {
+    assertTransferFeatureAvailable2();
     const queryParams = new URLSearchParams();
     if (params?.limit) queryParams.set("limit", String(params.limit));
     if (params?.offset) queryParams.set("offset", String(params.offset));
@@ -250,11 +305,11 @@ var EdgeUserClient = class {
     return this.server._apiRequest("DELETE", "/consent", this.accessToken);
   }
   /**
-   * Creates an EDGE-hosted transfer verification session.
-   * Returns a `verificationUrl` to open in an iframe or popup.
-   * The handoff token is single-use and expires in 120 seconds.
+   * Reserved for a future transfer release.
+   * Currently throws EdgeFeatureUnavailableError before validation or network I/O.
    */
   async createVerificationSession(transferId, options) {
+    assertTransferFeatureAvailable2();
     validateTransferId(transferId);
     return this.server._apiRequest(
       "POST",
@@ -264,10 +319,11 @@ var EdgeUserClient = class {
     );
   }
   /**
-   * Polls the status of a verification session.
-   * Use as an alternative to postMessage events.
+   * Reserved for a future transfer release.
+   * Currently throws EdgeFeatureUnavailableError before validation or network I/O.
    */
   async getVerificationSessionStatus(transferId, sessionId) {
+    assertTransferFeatureAvailable2();
     validateTransferId(transferId);
     return this.server._apiRequest(
       "GET",
@@ -276,6 +332,14 @@ var EdgeUserClient = class {
     );
   }
 };
+function assertTransferFeatureAvailable2() {
+  if (!isTransferFeatureAvailable2()) {
+    throw new EdgeFeatureUnavailableError2();
+  }
+}
+function isTransferFeatureAvailable2() {
+  return false;
+}
 
 // src/mle.ts
 import { randomUUID, randomBytes, createCipheriv, createDecipheriv, publicEncrypt, privateDecrypt, constants } from "crypto";
@@ -417,6 +481,7 @@ function validateMtlsConfig(config) {
 import { EdgeAuthenticationError, EdgeValidationError as EdgeValidationError3 } from "@edge-markets/connect";
 var EdgeUserSession = class {
   constructor(options) {
+    this.refreshPromise = null;
     if (!options.edge?.forUser || !options.edge?.refreshTokens) {
       throw new EdgeValidationError3("EdgeUserSession requires an EdgeConnectServer instance", {
         edge: ["Provide edge.forUser and edge.refreshTokens"]
@@ -445,29 +510,44 @@ var EdgeUserSession = class {
     this.refreshSkewMs = options.refreshSkewMs ?? 6e4;
     this.now = options.now ?? Date.now;
     this.onRefresh = options.onRefresh;
+    this.onEvent = options.onEvent;
+    this.singleFlightRefresh = options.singleFlightRefresh ?? true;
   }
   async getValidTokens(options = {}) {
     const tokens = await this.loadTokens();
     if (!options.forceRefresh && tokens.expiresAt > this.now() + this.refreshSkewMs) {
       return tokens;
     }
-    const refreshed = await this.edge.refreshTokens(tokens.refreshToken);
-    await this.saveTokens(refreshed, true);
-    await this.onRefresh?.(refreshed);
-    return refreshed;
+    if (this.singleFlightRefresh) {
+      if (!this.refreshPromise) {
+        this.refreshPromise = this.refreshTokens(tokens).finally(() => {
+          this.refreshPromise = null;
+        });
+      }
+      return this.refreshPromise;
+    }
+    return this.refreshTokens(tokens);
   }
   async getClient(options = {}) {
     const tokens = await this.getValidTokens(options);
     return this.edge.forUser(tokens.accessToken);
   }
-  async withClient(callback) {
-    const tokens = await this.getValidTokens();
+  async withClient(callback, options = {}) {
+    const tokens = await this.getValidTokens(options);
     return callback(this.edge.forUser(tokens.accessToken), tokens);
   }
   async saveTokens(tokens, refreshed = false) {
     validateTokens(tokens);
     const value = this.tokenVault ? this.tokenVault.encryptTokens(tokens) : tokens;
     await this.tokenStore.save(this.subjectId, value, { tokens, refreshed });
+    await this.emit({
+      type: "session.saved",
+      subjectId: this.subjectId,
+      refreshed,
+      encrypted: typeof value === "string",
+      expiresAt: tokens.expiresAt,
+      scope: tokens.scope
+    });
   }
   async loadTokens() {
     const value = await this.tokenStore.load(this.subjectId);
@@ -484,11 +564,60 @@ var EdgeUserSession = class {
       }
       const tokens = this.tokenVault.decryptTokens(value);
       validateTokens(tokens);
+      await this.emitLoaded(tokens, true);
       return tokens;
     }
     validateTokens(value);
+    await this.emitLoaded(value, false);
     return value;
   }
+  async refreshTokens(currentTokens) {
+    await this.emit({
+      type: "session.refresh_started",
+      subjectId: this.subjectId,
+      expiresAt: currentTokens.expiresAt,
+      scope: currentTokens.scope
+    });
+    try {
+      const refreshed = await this.edge.refreshTokens(currentTokens.refreshToken);
+      const tokens = {
+        ...refreshed,
+        refreshToken: refreshed.refreshToken || currentTokens.refreshToken
+      };
+      await this.saveTokens(tokens, true);
+      await this.onRefresh?.(tokens);
+      await this.emit({
+        type: "session.refresh_succeeded",
+        subjectId: this.subjectId,
+        refreshed: true,
+        expiresAt: tokens.expiresAt,
+        scope: tokens.scope
+      });
+      return tokens;
+    } catch (error) {
+      await this.emit({
+        type: "session.refresh_failed",
+        subjectId: this.subjectId,
+        error: error instanceof Error ? error.message : "Unknown token refresh error"
+      });
+      throw error;
+    }
+  }
+  async emitLoaded(tokens, encrypted) {
+    await this.emit({
+      type: "session.loaded",
+      subjectId: this.subjectId,
+      encrypted,
+      expiresAt: tokens.expiresAt,
+      scope: tokens.scope
+    });
+  }
+  async emit(event) {
+    try {
+      await this.onEvent?.(event);
+    } catch {
+    }
+  }
 };
 function createEdgeUserSession(options) {
   return new EdgeUserSession(options);
@@ -540,8 +669,8 @@ var EdgeWebhookReconciler = class {
     if (!options.cursorStore?.load || !options.cursorStore?.save) {
       throw new Error("EdgeWebhookReconciler: cursorStore.load and cursorStore.save are required");
     }
-    if (!options.processEvent) {
-      throw new Error("EdgeWebhookReconciler: processEvent is required");
+    if (!options.processEvent && !options.inbox) {
+      throw new Error("EdgeWebhookReconciler: processEvent or inbox is required");
     }
     if (options.maxPages !== void 0 && (!Number.isInteger(options.maxPages) || options.maxPages <= 0)) {
       throw new Error("EdgeWebhookReconciler: maxPages must be a positive integer");
@@ -568,6 +697,8 @@ var EdgeWebhookReconciler = class {
   async runInternal() {
     let cursor = normalizeCursor(await this.options.cursorStore.load());
     let processed = 0;
+    let accepted = 0;
+    let duplicates = 0;
     let pages = 0;
     let hasMore = false;
     const maxPages = this.options.maxPages ?? DEFAULT_MAX_PAGES;
@@ -581,6 +712,7 @@ var EdgeWebhookReconciler = class {
       if (result.events.length === 0) {
         return {
           processed,
+          ...this.options.inbox ? { accepted, duplicates } : {},
           pages,
           ...cursor ? { cursor } : {},
           hasMore,
@@ -589,14 +721,23 @@ var EdgeWebhookReconciler = class {
         };
       }
       for (const event of result.events) {
-        await this.options.processEvent(event);
+        if (this.options.inbox) {
+          const acceptResult = await this.options.inbox.acceptSyncedEvent(event);
+          accepted++;
+          if (acceptResult.duplicate) duplicates++;
+          const processResult = await this.options.inbox.process(event.id);
+          if (processResult.processed) processed++;
+        } else {
+          await this.options.processEvent?.(event);
+          processed++;
+        }
         cursor = event.id;
         await this.options.cursorStore.save(cursor);
-        processed++;
       }
       if (!result.hasMore) {
         return {
           processed,
+          ...this.options.inbox ? { accepted, duplicates } : {},
           pages,
           ...cursor ? { cursor } : {},
           hasMore: false,
@@ -606,6 +747,7 @@ var EdgeWebhookReconciler = class {
     }
     return {
       processed,
+      ...this.options.inbox ? { accepted, duplicates } : {},
       pages,
       ...cursor ? { cursor } : {},
       hasMore,
@@ -1367,6 +1509,16 @@ function readEnvironment(env) {
   }
   return value;
 }
+function readBooleanEnv(env, name) {
+  const value = readEnv(env, name);
+  if (!value) return void 0;
+  const normalized = value.toLowerCase();
+  if (["true", "1", "yes"].includes(normalized)) return true;
+  if (["false", "0", "no"].includes(normalized)) return false;
+  throw new EdgeValidationError4(`Invalid ${name}`, {
+    [name]: ["Must be one of: true, false, 1, 0, yes, no"]
+  });
+}
 function readTimeout(env, override) {
   if (override !== void 0) return override;
   const value = readFirstEnv(env, ["EDGE_TIMEOUT_MS", "EDGE_REQUEST_TIMEOUT_MS"]);
@@ -1382,7 +1534,12 @@ function readTimeout(env, override) {
 function buildMtlsConfig(env, requireMtls, warnings) {
   const cert = readPemValue(env, "EDGE_MTLS_CERT", "EDGE_MTLS_CERT_PATH", warnings);
   const key = readPemValue(env, "EDGE_MTLS_KEY", "EDGE_MTLS_KEY_PATH", warnings);
-  const ca = readPemValue(env, "EDGE_MTLS_CA", "EDGE_MTLS_CA_PATH", warnings);
+  const serverCa = readPemValue(env, "EDGE_SERVER_CA_PEM", "EDGE_SERVER_CA_PEM_PATH", warnings);
+  const hasLegacyCa = !!readFirstEnv(env, ["EDGE_MTLS_CA", "EDGE_MTLS_CA_PATH"]);
+  if (serverCa && hasLegacyCa) {
+    warnings.push("EDGE_SERVER_CA_PEM and EDGE_MTLS_CA are both set; using EDGE_SERVER_CA_PEM");
+  }
+  const ca = serverCa || readPemValue(env, "EDGE_MTLS_CA", "EDGE_MTLS_CA_PATH", warnings);
   if (!cert && !key && !ca) {
     if (requireMtls) {
       throw new EdgeValidationError4("mTLS is required but no EDGE_MTLS_CERT or EDGE_MTLS_KEY was provided", {
@@ -1421,7 +1578,7 @@ function createEdgeConnectServerFromEnv(options = {}) {
   const environment = readEnvironment(env);
   const apiBaseUrl = readEnv(env, "EDGE_API_BASE_URL");
   const mtlsRequiredByTarget = inferMtlsRequirement(environment, apiBaseUrl);
-  const requireMtls = options.requireMtls ?? false;
+  const requireMtls = options.requireMtls ?? readBooleanEnv(env, "EDGE_REQUIRE_MTLS") ?? false;
   const mtls = buildMtlsConfig(env, requireMtls, warnings);
   const timeout = readTimeout(env, options.timeout);
   const clientId = readFirstEnv(env, ["EDGE_CLIENT_ID", "EDGE_CONNECT_CLIENT_ID"]) || "";
@@ -1476,6 +1633,7 @@ function createEdgeConnectServerFromEnv(options = {}) {
 import {
   EdgeConsentRequiredError as EdgeConsentRequiredError2,
   EdgeError as EdgeError2,
+  EdgeFeatureUnavailableError as EdgeFeatureUnavailableError3,
   EdgeIdentityVerificationError as EdgeIdentityVerificationError2,
   EdgeNetworkError as EdgeNetworkError2,
   EdgeValidationError as EdgeValidationError5
@@ -1501,6 +1659,9 @@ function toEdgeProblemJson(error) {
       fieldErrors: error.fieldErrors
     });
   }
+  if (error instanceof EdgeFeatureUnavailableError3) {
+    return problem(error, "Feature unavailable", error.statusCode ?? 501);
+  }
   if (error instanceof EdgeNetworkError2) {
     return problem(error, "EDGE network error", error.statusCode ?? 502);
   }
@@ -1530,8 +1691,229 @@ function edgeTitle(error) {
   return error.code.split("_").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
 }
 
+// src/http-helpers.ts
+import { EdgeValidationError as EdgeValidationError7 } from "@edge-markets/connect";
+
+// src/webhook-parser.ts
+import {
+  EDGE_WEBHOOK_EVENT_TYPES,
+  EdgeAuthenticationError as EdgeAuthenticationError3,
+  EdgeValidationError as EdgeValidationError6
+} from "@edge-markets/connect";
+
+// src/webhook-signing.ts
+import crypto2 from "crypto";
+function verifyWebhookSignature(header, body, secret, options = {}) {
+  if (typeof header !== "string" || typeof body !== "string" || typeof secret !== "string") {
+    return false;
+  }
+  const requestedTolerance = options.toleranceSeconds;
+  const toleranceSeconds = typeof requestedTolerance === "number" && Number.isFinite(requestedTolerance) && requestedTolerance >= 0 ? requestedTolerance : 300;
+  const parts = header.split(",").map((p) => p.trim());
+  const tPart = parts.find((p) => p.startsWith("t="));
+  const v1Part = parts.find((p) => p.startsWith("v1="));
+  if (!tPart || !v1Part) return false;
+  const timestamp = parseInt(tPart.slice(2), 10);
+  const signature = v1Part.slice(3);
+  if (isNaN(timestamp) || !signature) return false;
+  const now = Math.floor(Date.now() / 1e3);
+  if (Math.abs(now - timestamp) > toleranceSeconds) return false;
+  const signedContent = `${timestamp}.${body}`;
+  const expectedHmac = crypto2.createHmac("sha256", secret).update(signedContent).digest("hex");
+  try {
+    const sigBuf = Buffer.from(signature, "hex");
+    const expBuf = Buffer.from(expectedHmac, "hex");
+    if (sigBuf.length !== expBuf.length) return false;
+    return crypto2.timingSafeEqual(sigBuf, expBuf);
+  } catch {
+    return false;
+  }
+}
+
+// src/webhook-parser.ts
+var EVENT_TYPES = new Set(EDGE_WEBHOOK_EVENT_TYPES);
+var TRANSFER_TYPES = /* @__PURE__ */ new Set(["debit", "credit"]);
+function parseAndVerifyWebhook(options) {
+  const body = normalizeRawBody(options.rawBody);
+  const header = normalizeSignatureHeader(options.signatureHeader);
+  const signatureTimestamp = extractWebhookSignatureTimestamp(header);
+  if (!header || !signatureTimestamp) {
+    throw new EdgeAuthenticationError3("Missing or malformed EDGE webhook signature");
+  }
+  if (!verifyWebhookSignature(header, body, options.secret, { toleranceSeconds: options.toleranceSeconds })) {
+    throw new EdgeAuthenticationError3("Invalid EDGE webhook signature");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    throw new EdgeValidationError6("EDGE webhook body must be valid JSON", {
+      rawBody: ["Unable to parse JSON after signature verification"]
+    });
+  }
+  const event = validateEdgeWebhookEvent(parsed);
+  return {
+    event,
+    eventId: event.id,
+    eventType: event.type,
+    signatureTimestamp,
+    receivedAt: options.receivedAt ?? /* @__PURE__ */ new Date()
+  };
+}
+function extractWebhookSignatureTimestamp(header) {
+  const normalizedHeader = normalizeSignatureHeader(header);
+  if (!normalizedHeader) return void 0;
+  const part = normalizedHeader.split(",").map((value) => value.trim()).find((value) => value.startsWith("t="));
+  if (!part) return void 0;
+  const timestamp = Number(part.slice(2));
+  if (!Number.isInteger(timestamp) || timestamp <= 0) return void 0;
+  return timestamp;
+}
+function isEdgeWebhookEvent(value) {
+  try {
+    validateEdgeWebhookEvent(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function validateEdgeWebhookEvent(value) {
+  const errors = {};
+  if (!isRecord(value)) {
+    throw new EdgeValidationError6("EDGE webhook event must be an object", {
+      event: ["Expected JSON object"]
+    });
+  }
+  const id = value.id;
+  const type = value.type;
+  const createdAt = value.created_at;
+  const data = value.data;
+  if (typeof id !== "string" || !id.trim()) {
+    errors.id = ["Required string"];
+  }
+  if (typeof type !== "string" || !EVENT_TYPES.has(type)) {
+    errors.type = [`Must be one of: ${EDGE_WEBHOOK_EVENT_TYPES.join(", ")}`];
+  }
+  if (typeof createdAt !== "string" || !createdAt.trim() || Number.isNaN(Date.parse(createdAt))) {
+    errors.created_at = ["Required ISO 8601 timestamp string"];
+  }
+  if (!isRecord(data)) {
+    errors.data = ["Required object"];
+  }
+  if (Object.keys(errors).length === 0) {
+    validateKnownEventData(type, data, errors);
+  }
+  if (Object.keys(errors).length > 0) {
+    throw new EdgeValidationError6("Invalid EDGE webhook event", errors);
+  }
+  return value;
+}
+function validateKnownEventData(type, data, errors) {
+  switch (type) {
+    case "transfer.completed":
+      validateTransferEventData(data, "completed", errors);
+      return;
+    case "transfer.failed":
+      validateTransferEventData(data, "failed", errors);
+      if (data.reason !== void 0 && typeof data.reason !== "string") {
+        errors["data.reason"] = ["Must be a string when provided"];
+      }
+      return;
+    case "transfer.expired":
+      validateTransferEventData(data, "expired", errors);
+      return;
+    case "transfer.processing":
+      validateTransferEventData(data, "processing", errors);
+      return;
+    case "consent.revoked":
+      validateRequiredString(data, "userId", errors);
+      validateRequiredString(data, "clientId", errors);
+      validateRequiredIsoTimestamp(data, "revokedAt", errors);
+      return;
+    default: {
+      const exhaustive = type;
+      throw new EdgeValidationError6("Unsupported EDGE webhook event type", {
+        type: [`Unsupported event type: ${exhaustive}`]
+      });
+    }
+  }
+}
+function validateTransferEventData(data, status, errors) {
+  validateRequiredString(data, "transferId", errors);
+  if (data.status !== status) {
+    errors["data.status"] = [`Must be "${status}" for this event type`];
+  }
+  if (typeof data.type !== "string" || !TRANSFER_TYPES.has(data.type)) {
+    errors["data.type"] = ['Must be "debit" or "credit"'];
+  }
+  validateRequiredString(data, "amount", errors);
+}
+function validateRequiredString(data, field, errors) {
+  if (typeof data[field] !== "string" || !data[field].trim()) {
+    errors[`data.${field}`] = ["Required string"];
+  }
+}
+function validateRequiredIsoTimestamp(data, field, errors) {
+  if (typeof data[field] !== "string" || !data[field].trim() || Number.isNaN(Date.parse(data[field]))) {
+    errors[`data.${field}`] = ["Required ISO 8601 timestamp string"];
+  }
+}
+function normalizeRawBody(rawBody) {
+  if (typeof rawBody === "string") {
+    return rawBody;
+  }
+  if (Buffer.isBuffer(rawBody) || rawBody instanceof Uint8Array) {
+    return Buffer.from(rawBody).toString("utf8");
+  }
+  throw new EdgeValidationError6("EDGE webhook raw body is required", {
+    rawBody: ["Pass the raw UTF-8 request body, not a parsed JSON object"]
+  });
+}
+function normalizeSignatureHeader(header) {
+  if (Array.isArray(header)) {
+    return header.map((value) => value.trim()).filter(Boolean).join(",");
+  }
+  if (typeof header !== "string") return void 0;
+  const trimmed = header.trim();
+  return trimmed || void 0;
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+// src/http-helpers.ts
+function getEdgeWebhookRawBody(request) {
+  if (typeof request.rawBody === "string" || Buffer.isBuffer(request.rawBody) || request.rawBody instanceof Uint8Array) {
+    return request.rawBody;
+  }
+  throw new EdgeValidationError7("EDGE webhook raw body is required", {
+    rawBody: [
+      "Configure your framework to expose the raw UTF-8 request body before JSON parsing. Parsed JSON bodies cannot be used for HMAC verification."
+    ]
+  });
+}
+function getEdgeWebhookSignatureHeader(request, headerName = "x-edge-signature") {
+  const headers = request.headers ?? {};
+  const lowerHeaderName = headerName.toLowerCase();
+  for (const [name, value] of Object.entries(headers)) {
+    if (name.toLowerCase() === lowerHeaderName) {
+      if (typeof value === "string" || Array.isArray(value)) return value;
+      if (value === void 0 || value === null) return void 0;
+      return String(value);
+    }
+  }
+  return void 0;
+}
+function parseWebhookHttpRequest(options) {
+  return parseAndVerifyWebhook({
+    ...options,
+    rawBody: getEdgeWebhookRawBody(options.request),
+    signatureHeader: getEdgeWebhookSignatureHeader(options.request, options.signatureHeaderName)
+  });
+}
+
 // src/identity.ts
-import { EdgeValidationError as EdgeValidationError6 } from "@edge-markets/connect";
+import { EdgeValidationError as EdgeValidationError8 } from "@edge-markets/connect";
 var DEFAULT_IDENTITY_POLICY = {
   minNameScore: 70,
   minAddressScore: 65,
@@ -1559,7 +1941,7 @@ function buildVerifyIdentityPayload(profile) {
     errors.address = ["At least one address field is required"];
   }
   if (Object.keys(errors).length > 0) {
-    throw new EdgeValidationError6("Partner identity profile is incomplete", errors);
+    throw new EdgeValidationError8("Partner identity profile is incomplete", errors);
   }
   return payload;
 }
@@ -1596,7 +1978,7 @@ function validatePolicy(policy) {
   if (!isScore(policy.minNameScore)) errors.minNameScore = ["Must be between 0 and 100"];
   if (!isScore(policy.minAddressScore)) errors.minAddressScore = ["Must be between 0 and 100"];
   if (Object.keys(errors).length > 0) {
-    throw new EdgeValidationError6("Invalid identity policy", errors);
+    throw new EdgeValidationError8("Invalid identity policy", errors);
   }
 }
 function isScore(value) {
@@ -1612,9 +1994,155 @@ function firstNonEmpty(...values) {
   return "";
 }
 
+// src/session-store.ts
+import { EdgeValidationError as EdgeValidationError9 } from "@edge-markets/connect";
+function createSessionTokenRecord(subjectId, tokens, tokenVault, options = {}) {
+  const normalizedSubjectId = normalizeRequiredString(subjectId, "subjectId");
+  validateTokens2(tokens);
+  return {
+    subjectId: normalizedSubjectId,
+    encryptedTokens: tokenVault.encryptTokens(tokens),
+    expiresAt: normalizeSessionExpiresAt(tokens.expiresAt),
+    scopes: options.scopes ?? splitScopes(tokens.scope),
+    ...options.edgeUserId ? { edgeUserId: options.edgeUserId } : {},
+    ...options.keyId ? { keyId: options.keyId } : {},
+    ...options.metadata ? { metadata: options.metadata } : {}
+  };
+}
+function parseSessionTokenRecord(record) {
+  if (!isRecord2(record)) {
+    throw new EdgeValidationError9("EDGE session token record must be an object", {
+      record: ["Expected object"]
+    });
+  }
+  const subjectId = normalizeRequiredString(record.subjectId, "subjectId");
+  const encryptedTokens = normalizeRequiredString(record.encryptedTokens, "encryptedTokens");
+  const expiresAt = normalizeSessionExpiresAt(record.expiresAt);
+  const scopes = record.scopes === void 0 ? void 0 : normalizeScopes(record.scopes);
+  return {
+    subjectId,
+    encryptedTokens,
+    expiresAt,
+    ...scopes ? { scopes } : {},
+    ...typeof record.edgeUserId === "string" && record.edgeUserId.trim() ? { edgeUserId: record.edgeUserId.trim() } : {},
+    ...typeof record.keyId === "string" && record.keyId.trim() ? { keyId: record.keyId.trim() } : {},
+    ...isRecord2(record.metadata) ? { metadata: record.metadata } : {}
+  };
+}
+function encryptLegacySessionTokens(legacyRecord, tokenVault, options) {
+  const subjectId = normalizeRequiredString(options.subjectId || legacyRecord.subjectId, "subjectId");
+  const accessToken = normalizeRequiredString(legacyRecord.accessToken, "accessToken");
+  const refreshToken = normalizeRequiredString(legacyRecord.refreshToken, "refreshToken");
+  if (!options.allowPlaintext && !tokenVault.isEncrypted(accessToken) && !tokenVault.isEncrypted(refreshToken)) {
+    throw new EdgeValidationError9("Plaintext token migration requires allowPlaintext: true", {
+      allowPlaintext: ["Set allowPlaintext only inside an explicit migration path"]
+    });
+  }
+  const scope = normalizeScopeString(legacyRecord.scope ?? legacyRecord.scopes);
+  const tokens = {
+    accessToken,
+    refreshToken,
+    ...typeof legacyRecord.idToken === "string" && legacyRecord.idToken.trim() ? { idToken: legacyRecord.idToken.trim() } : {},
+    expiresIn: normalizeExpiresIn(legacyRecord.expiresIn),
+    expiresAt: normalizeSessionExpiresAt(legacyRecord.expiresAt),
+    scope
+  };
+  return createSessionTokenRecord(subjectId, tokens, tokenVault, {
+    scopes: splitScopes(scope),
+    ...legacyRecord.edgeUserId ? { edgeUserId: legacyRecord.edgeUserId } : {},
+    ...options.keyId ? { keyId: options.keyId } : {},
+    ...legacyRecord.metadata ? { metadata: legacyRecord.metadata } : {}
+  });
+}
+function normalizeSessionExpiresAt(value) {
+  if (value instanceof Date) {
+    const time = value.getTime();
+    if (!Number.isFinite(time) || time <= 0) {
+      throw new EdgeValidationError9("Invalid EDGE session expiresAt", {
+        expiresAt: ["Date must be valid"]
+      });
+    }
+    return time;
+  }
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      throw new EdgeValidationError9("Invalid EDGE session expiresAt", {
+        expiresAt: ["Required"]
+      });
+    }
+    if (/^\d+$/.test(trimmed)) {
+      return normalizeSessionExpiresAt(Number(trimmed));
+    }
+    const time = Date.parse(trimmed);
+    if (!Number.isNaN(time) && time > 0) return time;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    if (!Number.isInteger(value) || value <= 0) {
+      throw new EdgeValidationError9("Invalid EDGE session expiresAt", {
+        expiresAt: ["Must be a positive integer timestamp in milliseconds"]
+      });
+    }
+    if (value < 1e10) {
+      throw new EdgeValidationError9("Ambiguous EDGE session expiresAt", {
+        expiresAt: ["Use Unix milliseconds, not seconds"]
+      });
+    }
+    return value;
+  }
+  throw new EdgeValidationError9("Invalid EDGE session expiresAt", {
+    expiresAt: ["Use Unix milliseconds, ISO string, or Date"]
+  });
+}
+function normalizeExpiresIn(value) {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  }
+  return 600;
+}
+function normalizeScopeString(value) {
+  if (Array.isArray(value)) return normalizeScopes(value).join(" ");
+  if (typeof value === "string") return splitScopes(value).join(" ");
+  return "";
+}
+function normalizeScopes(value) {
+  if (Array.isArray(value)) {
+    return value.map((scope) => typeof scope === "string" ? scope.trim() : "").filter(Boolean);
+  }
+  if (typeof value === "string") {
+    return splitScopes(value);
+  }
+  throw new EdgeValidationError9("Invalid EDGE session scopes", {
+    scopes: ["Expected array or space-delimited string"]
+  });
+}
+function splitScopes(value) {
+  return value.split(/\s+/).map((scope) => scope.trim()).filter(Boolean);
+}
+function normalizeRequiredString(value, field) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new EdgeValidationError9("Invalid EDGE session token record", {
+      [field]: ["Required string"]
+    });
+  }
+  return value.trim();
+}
+function validateTokens2(tokens) {
+  normalizeRequiredString(tokens.accessToken, "accessToken");
+  normalizeRequiredString(tokens.refreshToken, "refreshToken");
+  normalizeSessionExpiresAt(tokens.expiresAt);
+  normalizeExpiresIn(tokens.expiresIn);
+  normalizeScopeString(tokens.scope);
+}
+function isRecord2(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
 // src/token-vault.ts
-import { EdgeValidationError as EdgeValidationError7 } from "@edge-markets/connect";
-import crypto2 from "crypto";
+import { EdgeValidationError as EdgeValidationError10 } from "@edge-markets/connect";
+import crypto3 from "crypto";
 var TOKEN_VAULT_VERSION = "edge_vault_v1";
 var IV_BYTES = 12;
 var TAG_BYTES = 16;
@@ -1626,7 +2154,7 @@ var EdgeTokenVault = class {
     for (const [index, key] of (options.previousKeys ?? []).entries()) {
       const normalized = normalizeVaultKey(key, `previousKeys[${index}]`);
       if (this.keysById.has(normalized.id)) {
-        throw new EdgeValidationError7("Duplicate token vault key ID", {
+        throw new EdgeValidationError10("Duplicate token vault key ID", {
           keyId: [`Duplicate key ID "${normalized.id}"`]
         });
       }
@@ -1635,9 +2163,9 @@ var EdgeTokenVault = class {
   }
   encryptTokens(tokens) {
     validateEdgeTokens(tokens);
-    const iv = crypto2.randomBytes(IV_BYTES);
+    const iv = crypto3.randomBytes(IV_BYTES);
     const aad = Buffer.from(`${TOKEN_VAULT_VERSION}.${this.currentKey.id}`, "utf8");
-    const cipher = crypto2.createCipheriv("aes-256-gcm", this.currentKey.key, iv);
+    const cipher = crypto3.createCipheriv("aes-256-gcm", this.currentKey.key, iv);
     cipher.setAAD(aad);
     const plaintext = Buffer.from(JSON.stringify(tokens), "utf8");
     const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
@@ -1654,12 +2182,12 @@ var EdgeTokenVault = class {
     const parsed = parseEnvelope(envelope);
     const key = this.keysById.get(parsed.keyId);
     if (!key) {
-      throw new EdgeValidationError7("Unknown token vault key ID", {
+      throw new EdgeValidationError10("Unknown token vault key ID", {
         keyId: [`No key configured for "${parsed.keyId}"`]
       });
     }
     try {
-      const decipher = crypto2.createDecipheriv("aes-256-gcm", key, parsed.iv);
+      const decipher = crypto3.createDecipheriv("aes-256-gcm", key, parsed.iv);
       decipher.setAAD(Buffer.from(`${TOKEN_VAULT_VERSION}.${parsed.keyId}`, "utf8"));
       decipher.setAuthTag(parsed.tag);
       const plaintext = Buffer.concat([decipher.update(parsed.ciphertext), decipher.final()]).toString("utf8");
@@ -1667,8 +2195,8 @@ var EdgeTokenVault = class {
       validateEdgeTokens(tokens);
       return tokens;
     } catch (error) {
-      if (error instanceof EdgeValidationError7) throw error;
-      throw new EdgeValidationError7("Failed to decrypt EDGE tokens", {
+      if (error instanceof EdgeValidationError10) throw error;
+      throw new EdgeValidationError10("Failed to decrypt EDGE tokens", {
         tokenEnvelope: ["Envelope is malformed, corrupted, or encrypted with a different key"]
       });
     }
@@ -1686,7 +2214,7 @@ function isEdgeTokenVaultEnvelope(value) {
 function normalizeVaultKey(input, fieldName) {
   const id = typeof input.id === "string" ? input.id.trim() : "";
   if (!id) {
-    throw new EdgeValidationError7("Token vault key ID is required", {
+    throw new EdgeValidationError10("Token vault key ID is required", {
       [`${fieldName}.id`]: ["Required"]
     });
   }
@@ -1717,7 +2245,7 @@ function normalizeKeyMaterial(input, fieldName) {
   }
   const key = candidates.find((candidate) => candidate.length === KEY_BYTES);
   if (!key) {
-    throw new EdgeValidationError7("Token vault key must decode to 32 bytes", {
+    throw new EdgeValidationError10("Token vault key must decode to 32 bytes", {
       [fieldName]: ["Provide a 32-byte key as base64, base64url, hex, Buffer, or Uint8Array"]
     });
   }
@@ -1748,18 +2276,18 @@ function validateEdgeTokens(tokens) {
     }
   }
   if (Object.keys(errors).length > 0) {
-    throw new EdgeValidationError7("Invalid EDGE token payload", errors);
+    throw new EdgeValidationError10("Invalid EDGE token payload", errors);
   }
 }
 function parseEnvelope(envelope) {
   if (typeof envelope !== "string") {
-    throw new EdgeValidationError7("Token envelope must be a string", {
+    throw new EdgeValidationError10("Token envelope must be a string", {
       tokenEnvelope: ["Expected string"]
     });
   }
   const parts = envelope.split(".");
   if (parts.length !== 5 || parts[0] !== TOKEN_VAULT_VERSION) {
-    throw new EdgeValidationError7("Invalid EDGE token vault envelope", {
+    throw new EdgeValidationError10("Invalid EDGE token vault envelope", {
       tokenEnvelope: [`Expected ${TOKEN_VAULT_VERSION}.<keyId>.<iv>.<tag>.<ciphertext>`]
     });
   }
@@ -1774,7 +2302,7 @@ function parseEnvelope(envelope) {
   if (tag.length !== TAG_BYTES) errors.tag = [`Must be ${TAG_BYTES} bytes`];
   if (ciphertext.length === 0) errors.ciphertext = ["Required"];
   if (Object.keys(errors).length > 0) {
-    throw new EdgeValidationError7("Invalid EDGE token vault envelope", errors);
+    throw new EdgeValidationError10("Invalid EDGE token vault envelope", errors);
   }
   return { keyId, iv, tag, ciphertext };
 }
@@ -1788,13 +2316,13 @@ function fromBase64Url2(value) {
 }
 
 // src/webhook-guards.ts
-import { EdgeValidationError as EdgeValidationError8 } from "@edge-markets/connect";
+import { EdgeValidationError as EdgeValidationError11 } from "@edge-markets/connect";
 function isTransferWebhookEvent(event) {
   return event.type.startsWith("transfer.");
 }
 function assertTransferEventMatchesIntent(event, intent) {
   if (!isTransferWebhookEvent(event)) {
-    throw new EdgeValidationError8("Webhook event is not a transfer event", {
+    throw new EdgeValidationError11("Webhook event is not a transfer event", {
       type: [`Received ${event.type}`]
     });
   }
@@ -1817,229 +2345,285 @@ function assertTransferEventMatchesIntent(event, intent) {
     }
   }
   if (Object.keys(errors).length > 0) {
-    throw new EdgeValidationError8("Webhook transfer event does not match expected transfer intent", errors);
-  }
-}
-
-// src/webhook-parser.ts
-import {
-  EDGE_WEBHOOK_EVENT_TYPES,
-  EdgeAuthenticationError as EdgeAuthenticationError3,
-  EdgeValidationError as EdgeValidationError9
-} from "@edge-markets/connect";
-
-// src/webhook-signing.ts
-import crypto3 from "crypto";
-function verifyWebhookSignature(header, body, secret, options = {}) {
-  if (typeof header !== "string" || typeof body !== "string" || typeof secret !== "string") {
-    return false;
-  }
-  const requestedTolerance = options.toleranceSeconds;
-  const toleranceSeconds = typeof requestedTolerance === "number" && Number.isFinite(requestedTolerance) && requestedTolerance >= 0 ? requestedTolerance : 300;
-  const parts = header.split(",").map((p) => p.trim());
-  const tPart = parts.find((p) => p.startsWith("t="));
-  const v1Part = parts.find((p) => p.startsWith("v1="));
-  if (!tPart || !v1Part) return false;
-  const timestamp = parseInt(tPart.slice(2), 10);
-  const signature = v1Part.slice(3);
-  if (isNaN(timestamp) || !signature) return false;
-  const now = Math.floor(Date.now() / 1e3);
-  if (Math.abs(now - timestamp) > toleranceSeconds) return false;
-  const signedContent = `${timestamp}.${body}`;
-  const expectedHmac = crypto3.createHmac("sha256", secret).update(signedContent).digest("hex");
-  try {
-    const sigBuf = Buffer.from(signature, "hex");
-    const expBuf = Buffer.from(expectedHmac, "hex");
-    if (sigBuf.length !== expBuf.length) return false;
-    return crypto3.timingSafeEqual(sigBuf, expBuf);
-  } catch {
-    return false;
+    throw new EdgeValidationError11("Webhook transfer event does not match expected transfer intent", errors);
   }
 }
+var assertWebhookMatchesTransfer = assertTransferEventMatchesIntent;
 
-// src/webhook-parser.ts
-var EVENT_TYPES = new Set(EDGE_WEBHOOK_EVENT_TYPES);
-var TRANSFER_TYPES = /* @__PURE__ */ new Set(["debit", "credit"]);
-function parseAndVerifyWebhook(options) {
-  const body = normalizeRawBody(options.rawBody);
-  const header = normalizeSignatureHeader(options.signatureHeader);
-  const signatureTimestamp = extractWebhookSignatureTimestamp(header);
-  if (!header || !signatureTimestamp) {
-    throw new EdgeAuthenticationError3("Missing or malformed EDGE webhook signature");
-  }
-  if (!verifyWebhookSignature(header, body, options.secret, { toleranceSeconds: options.toleranceSeconds })) {
-    throw new EdgeAuthenticationError3("Invalid EDGE webhook signature");
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(body);
-  } catch {
-    throw new EdgeValidationError9("EDGE webhook body must be valid JSON", {
-      rawBody: ["Unable to parse JSON after signature verification"]
+// src/webhook-inbox.ts
+import { EdgeValidationError as EdgeValidationError12 } from "@edge-markets/connect";
+import crypto4 from "crypto";
+var DEFAULT_PROCESSING_TIMEOUT_MS = 10 * 60 * 1e3;
+var EdgeWebhookInbox = class {
+  constructor(options) {
+    if (!options.store?.insert || !options.store?.find || !options.store?.markProcessing) {
+      throw new EdgeValidationError12("EdgeWebhookInbox store is incomplete", {
+        store: ["Provide insert, find, markProcessing, markProcessed, and markFailed callbacks"]
+      });
+    }
+    if (!options.store.markProcessed || !options.store.markFailed) {
+      throw new EdgeValidationError12("EdgeWebhookInbox store is incomplete", {
+        store: ["Provide markProcessed and markFailed callbacks"]
+      });
+    }
+    if (!options.processEvent) {
+      throw new EdgeValidationError12("EdgeWebhookInbox processEvent callback is required", {
+        processEvent: ["Required"]
+      });
+    }
+    if (options.processingTimeoutMs !== void 0 && (!Number.isFinite(options.processingTimeoutMs) || options.processingTimeoutMs <= 0)) {
+      throw new EdgeValidationError12("processingTimeoutMs must be positive", {
+        processingTimeoutMs: ["Must be greater than 0"]
+      });
+    }
+    this.store = options.store;
+    this.processEvent = options.processEvent;
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+    this.storeRawBody = options.storeRawBody ?? false;
+    this.processingTimeoutMs = options.processingTimeoutMs ?? DEFAULT_PROCESSING_TIMEOUT_MS;
+    this.onEvent = options.onEvent;
+  }
+  async accept(parsed) {
+    return this.acceptEvent(parsed.event, {
+      source: "live_webhook",
+      receivedAt: parsed.receivedAt,
+      signatureTimestamp: parsed.signatureTimestamp,
+      signatureHeader: void 0,
+      rawBody: void 0
     });
   }
-  const event = validateEdgeWebhookEvent(parsed);
-  return {
-    event,
-    eventId: event.id,
-    eventType: event.type,
-    signatureTimestamp,
-    receivedAt: options.receivedAt ?? /* @__PURE__ */ new Date()
-  };
-}
-function extractWebhookSignatureTimestamp(header) {
-  const normalizedHeader = normalizeSignatureHeader(header);
-  if (!normalizedHeader) return void 0;
-  const part = normalizedHeader.split(",").map((value) => value.trim()).find((value) => value.startsWith("t="));
-  if (!part) return void 0;
-  const timestamp = Number(part.slice(2));
-  if (!Number.isInteger(timestamp) || timestamp <= 0) return void 0;
-  return timestamp;
-}
-function isEdgeWebhookEvent(value) {
-  try {
-    validateEdgeWebhookEvent(value);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function validateEdgeWebhookEvent(value) {
-  const errors = {};
-  if (!isRecord(value)) {
-    throw new EdgeValidationError9("EDGE webhook event must be an object", {
-      event: ["Expected JSON object"]
+  async acceptRaw(parsed, rawBody, signatureHeader) {
+    return this.acceptEvent(parsed.event, {
+      source: "live_webhook",
+      receivedAt: parsed.receivedAt,
+      signatureTimestamp: parsed.signatureTimestamp,
+      signatureHeader,
+      rawBody: this.storeRawBody ? rawBody : void 0
     });
   }
-  const id = value.id;
-  const type = value.type;
-  const createdAt = value.created_at;
-  const data = value.data;
-  if (typeof id !== "string" || !id.trim()) {
-    errors.id = ["Required string"];
-  }
-  if (typeof type !== "string" || !EVENT_TYPES.has(type)) {
-    errors.type = [`Must be one of: ${EDGE_WEBHOOK_EVENT_TYPES.join(", ")}`];
-  }
-  if (typeof createdAt !== "string" || !createdAt.trim() || Number.isNaN(Date.parse(createdAt))) {
-    errors.created_at = ["Required ISO 8601 timestamp string"];
-  }
-  if (!isRecord(data)) {
-    errors.data = ["Required object"];
+  async acceptSyncedEvent(event, receivedAt = this.now()) {
+    return this.acceptEvent(event, {
+      source: "sync",
+      receivedAt,
+      signatureTimestamp: null,
+      signatureHeader: null,
+      rawBody: null
+    });
   }
-  if (Object.keys(errors).length === 0) {
-    validateKnownEventData(type, data, errors);
+  async process(eventId, options = {}) {
+    const normalizedEventId = normalizeEventId(eventId);
+    const existing = await this.store.find(normalizedEventId);
+    if (!existing) {
+      return { eventId: normalizedEventId, status: "failed", processed: false, skipped: true, reason: "not_found" };
+    }
+    if (existing.status === "processed" && !options.force) {
+      return {
+        eventId: normalizedEventId,
+        status: existing.status,
+        processed: false,
+        skipped: true,
+        reason: "already_processed",
+        record: existing
+      };
+    }
+    const now = this.now();
+    const processing = await this.store.markProcessing(normalizedEventId, { now });
+    if (!processing) {
+      return {
+        eventId: normalizedEventId,
+        status: existing.status,
+        processed: false,
+        skipped: true,
+        reason: "locked",
+        record: existing
+      };
+    }
+    await this.emit({
+      type: "webhook.processing_started",
+      eventId: normalizedEventId,
+      eventType: processing.eventType,
+      status: "processing",
+      source: processing.source,
+      attempts: processing.attempts
+    });
+    try {
+      await this.processEvent(processing.event, processing);
+      const processed = await this.store.markProcessed(normalizedEventId, { now: this.now() }) ?? processing;
+      await this.emit({
+        type: "webhook.processing_succeeded",
+        eventId: normalizedEventId,
+        eventType: processing.eventType,
+        status: "processed",
+        source: processing.source,
+        attempts: processed.attempts
+      });
+      return {
+        eventId: normalizedEventId,
+        status: "processed",
+        processed: true,
+        skipped: false,
+        record: processed
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown webhook processing error";
+      const failed = await this.store.markFailed(normalizedEventId, { now: this.now(), error: message }) ?? processing;
+      await this.emit({
+        type: "webhook.processing_failed",
+        eventId: normalizedEventId,
+        eventType: processing.eventType,
+        status: "failed",
+        source: processing.source,
+        attempts: failed.attempts,
+        error: message
+      });
+      throw error;
+    }
   }
-  if (Object.keys(errors).length > 0) {
-    throw new EdgeValidationError9("Invalid EDGE webhook event", errors);
+  async replay(eventId) {
+    return this.process(eventId, { force: true });
   }
-  return value;
-}
-function validateKnownEventData(type, data, errors) {
-  switch (type) {
-    case "transfer.completed":
-      validateTransferEventData(data, "completed", errors);
-      return;
-    case "transfer.failed":
-      validateTransferEventData(data, "failed", errors);
-      if (data.reason !== void 0 && typeof data.reason !== "string") {
-        errors["data.reason"] = ["Must be a string when provided"];
+  async recoverStaleProcessing() {
+    if (!this.store.list) {
+      return { recovered: 0, skipped: true, reason: "list_not_configured" };
+    }
+    if (!this.store.markPending) {
+      return { recovered: 0, skipped: true, reason: "mark_pending_not_configured" };
+    }
+    const updatedBefore = new Date(this.now().getTime() - this.processingTimeoutMs);
+    const records = await this.store.list({ status: "processing", updatedBefore, limit: 100 });
+    let recovered = 0;
+    for (const record of records) {
+      const next = await this.store.markPending(record.eventId, {
+        now: this.now(),
+        reason: "stale_processing_recovery"
+      });
+      if (next) {
+        recovered++;
+        await this.emit({
+          type: "webhook.recovered_stale",
+          eventId: record.eventId,
+          eventType: record.eventType,
+          status: next.status,
+          source: record.source,
+          attempts: next.attempts
+        });
       }
-      return;
-    case "transfer.expired":
-      validateTransferEventData(data, "expired", errors);
-      return;
-    case "transfer.processing":
-      validateTransferEventData(data, "processing", errors);
-      return;
-    case "consent.revoked":
-      validateRequiredString(data, "userId", errors);
-      validateRequiredString(data, "clientId", errors);
-      validateRequiredIsoTimestamp(data, "revokedAt", errors);
-      return;
-    default: {
-      const exhaustive = type;
-      throw new EdgeValidationError9("Unsupported EDGE webhook event type", {
-        type: [`Unsupported event type: ${exhaustive}`]
+    }
+    return { recovered, skipped: false };
+  }
+  async acceptEvent(event, options) {
+    const payloadFingerprint = fingerprintWebhookEvent(event);
+    const result = await this.store.insert({
+      eventId: event.id,
+      eventType: event.type,
+      event,
+      payloadFingerprint,
+      source: options.source,
+      receivedAt: options.receivedAt,
+      signatureTimestamp: options.signatureTimestamp ?? null,
+      signatureHeader: options.signatureHeader ?? null,
+      rawBody: options.rawBody ?? null
+    });
+    if (result.record.payloadFingerprint !== payloadFingerprint) {
+      await this.emit({
+        type: "webhook.payload_mismatch",
+        eventId: event.id,
+        eventType: event.type,
+        status: result.record.status,
+        source: options.source
+      });
+      throw new EdgeValidationError12("Duplicate webhook event payload does not match stored event", {
+        eventId: [event.id]
       });
     }
+    await this.emit({
+      type: result.inserted ? "webhook.accepted" : "webhook.duplicate",
+      eventId: event.id,
+      eventType: event.type,
+      status: result.record.status,
+      source: options.source,
+      attempts: result.record.attempts
+    });
+    return {
+      eventId: event.id,
+      eventType: event.type,
+      inserted: result.inserted,
+      duplicate: !result.inserted,
+      status: result.record.status,
+      record: result.record
+    };
   }
-}
-function validateTransferEventData(data, status, errors) {
-  validateRequiredString(data, "transferId", errors);
-  if (data.status !== status) {
-    errors["data.status"] = [`Must be "${status}" for this event type`];
-  }
-  if (typeof data.type !== "string" || !TRANSFER_TYPES.has(data.type)) {
-    errors["data.type"] = ['Must be "debit" or "credit"'];
+  async emit(event) {
+    try {
+      await this.onEvent?.(event);
+    } catch {
+    }
   }
-  validateRequiredString(data, "amount", errors);
+};
+function createWebhookInbox(options) {
+  return new EdgeWebhookInbox(options);
 }
-function validateRequiredString(data, field, errors) {
-  if (typeof data[field] !== "string" || !data[field].trim()) {
-    errors[`data.${field}`] = ["Required string"];
-  }
+function fingerprintWebhookEvent(event) {
+  return crypto4.createHash("sha256").update(stableStringify(event)).digest("hex");
 }
-function validateRequiredIsoTimestamp(data, field, errors) {
-  if (typeof data[field] !== "string" || !data[field].trim() || Number.isNaN(Date.parse(data[field]))) {
-    errors[`data.${field}`] = ["Required ISO 8601 timestamp string"];
+function normalizeEventId(eventId) {
+  if (typeof eventId !== "string" || !eventId.trim()) {
+    throw new EdgeValidationError12("Webhook event ID is required", {
+      eventId: ["Required"]
+    });
   }
+  return eventId.trim();
 }
-function normalizeRawBody(rawBody) {
-  if (typeof rawBody === "string") {
-    return rawBody;
+function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
   }
-  if (Buffer.isBuffer(rawBody) || rawBody instanceof Uint8Array) {
-    return Buffer.from(rawBody).toString("utf8");
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
   }
-  throw new EdgeValidationError9("EDGE webhook raw body is required", {
-    rawBody: ["Pass the raw UTF-8 request body, not a parsed JSON object"]
-  });
-}
-function normalizeSignatureHeader(header) {
-  if (Array.isArray(header)) {
-    return header.map((value) => value.trim()).filter(Boolean).join(",");
-  }
-  if (typeof header !== "string") return void 0;
-  const trimmed = header.trim();
-  return trimmed || void 0;
-}
-function isRecord(value) {
-  return !!value && typeof value === "object" && !Array.isArray(value);
+  return JSON.stringify(value);
 }
 
 // src/index.ts
 import {
+  EDGE_CONNECT_FEATURE_UNAVAILABLE_MESSAGE,
   EdgeApiError as EdgeApiError2,
   EdgeAuthenticationError as EdgeAuthenticationError4,
   EdgeConsentRequiredError as EdgeConsentRequiredError3,
   EdgeError as EdgeError3,
+  EdgeFeatureUnavailableError as EdgeFeatureUnavailableError4,
   EdgeIdentityVerificationError as EdgeIdentityVerificationError3,
   EdgeInsufficientScopeError as EdgeInsufficientScopeError2,
   EdgeNetworkError as EdgeNetworkError3,
   EdgeNotFoundError as EdgeNotFoundError2,
   EdgeTokenExchangeError as EdgeTokenExchangeError2,
-  EdgeValidationError as EdgeValidationError10,
+  EdgeValidationError as EdgeValidationError13,
   isApiError,
   isAuthenticationError,
   isConsentRequiredError,
   isEdgeError,
+  isFeatureUnavailableError,
   isIdentityVerificationError,
   isNetworkError
 } from "@edge-markets/connect";
 import {
+  ACTIVE_EDGE_SCOPES,
   EDGE_WEBHOOK_EVENT_TYPES as EDGE_WEBHOOK_EVENT_TYPES2,
   TRANSFER_CATEGORIES,
   getEnvironmentConfig as getEnvironmentConfig3,
   isProductionEnvironment
 } from "@edge-markets/connect";
 export {
+  ACTIVE_EDGE_SCOPES,
+  CONNECT_TRANSFER_DIRECTIONS,
+  EDGE_CONNECT_FEATURE_UNAVAILABLE_MESSAGE,
   EDGE_WEBHOOK_EVENT_TYPES2 as EDGE_WEBHOOK_EVENT_TYPES,
   EdgeApiError2 as EdgeApiError,
   EdgeAuthenticationError4 as EdgeAuthenticationError,
   EdgeConnectServer,
   EdgeConsentRequiredError3 as EdgeConsentRequiredError,
   EdgeError3 as EdgeError,
+  EdgeFeatureUnavailableError4 as EdgeFeatureUnavailableError,
   EdgeIdentityVerificationError3 as EdgeIdentityVerificationError,
   EdgeInsufficientScopeError2 as EdgeInsufficientScopeError,
   EdgeNetworkError3 as EdgeNetworkError,
@@ -2048,19 +2632,29 @@ export {
   EdgeTokenVault,
   EdgeUserClient,
   EdgeUserSession,
-  EdgeValidationError10 as EdgeValidationError,
+  EdgeValidationError13 as EdgeValidationError,
+  EdgeWebhookInbox,
   EdgeWebhookReconciler,
   TRANSFER_CATEGORIES,
   assertSameTransferIntent,
   assertTransferEventMatchesIntent,
+  assertWebhookMatchesTransfer,
   buildVerifyIdentityPayload,
   createEdgeConnectServerFromEnv,
   createEdgeTokenVault,
   createEdgeUserSession,
+  createSessionTokenRecord,
   createTransferIdempotencyKey,
+  createWebhookInbox,
   createWebhookReconciler,
+  encryptLegacySessionTokens,
   evaluateIdentityResult,
   extractWebhookSignatureTimestamp,
+  fingerprintTransferIntent,
+  fingerprintWebhookEvent,
+  getConnectTransferDirection,
+  getEdgeWebhookRawBody,
+  getEdgeWebhookSignatureHeader,
   getEnvironmentConfig3 as getEnvironmentConfig,
   isApiError,
   isAuthenticationError,
@@ -2068,12 +2662,18 @@ export {
   isEdgeError,
   isEdgeTokenVaultEnvelope,
   isEdgeWebhookEvent,
+  isFeatureUnavailableError,
   isIdentityVerificationError,
   isNetworkError,
   isProductionEnvironment,
   isTransferWebhookEvent,
+  mapTransferStatusToPartnerState,
+  moneyAmountsEqual,
   normalizeMoneyAmount,
+  normalizeSessionExpiresAt,
   parseAndVerifyWebhook,
+  parseSessionTokenRecord,
+  parseWebhookHttpRequest,
   startTransferVerification,
   toEdgeHttpError,
   toEdgeProblemJson,