@mymehq/sdk 3.3.1 → 3.4.0

package/dist/index.d.ts

@@ -352,4 +352,56 @@ declare class ConflictError extends MymeError {
     constructor(current: ConflictSnapshot, ancestor: ConflictSnapshot, conflictingFields: string[], clientPatch: Record<string, unknown>);
 }
 
-export { type ClientConfig, type ConflictAutoMergeListener, type ConflictAutoMergedEvent, type ConflictData, ConflictError, type ConflictResolver, type ConflictStrategy, ForbiddenError, type ItemWithExtensions, type ListFilters, type MetadataInput, MymeClient, MymeError, NotFoundError, type SearchFilters, UnauthorizedError, type UpdateOptions, ValidationError };
+/**
+ * Reason a webhook signature did not validate. Receivers should treat
+ * any non-`valid` result as "do not trust this delivery".
+ *
+ * - `malformed` — the signature header was missing, empty, or not in
+ *   the `t=<unix>,v1=<hex>` form.
+ * - `too_old` — the parsed timestamp is outside the tolerance window
+ *   (default: more than 300s in the past, or more than 60s in the
+ *   future to allow for mild clock skew).
+ * - `mismatch` — the recomputed HMAC did not match the provided hex.
+ */
+type WebhookVerifyReason = "malformed" | "too_old" | "mismatch";
+interface WebhookVerifyResult {
+    valid: boolean;
+    reason?: WebhookVerifyReason;
+}
+interface VerifyWebhookSignatureInput {
+    /** The `X-Myme-Signature` header value as received. */
+    header: string | null | undefined;
+    /** The raw HTTP request body, exactly as received (pre-JSON-parse). */
+    rawBody: string;
+    /** The webhook secret shared with the Myme server. */
+    secret: string;
+    /**
+     * Maximum age (seconds in the past) to accept. Default 300 (5 min).
+     * Matches the documented platform contract.
+     */
+    tolerance?: number;
+    /**
+     * Maximum future skew (seconds) to tolerate. Default 60 — matches
+     * the documented platform contract. Timestamps further ahead than
+     * this are rejected as `too_old` (name is legacy; it captures
+     * "outside the acceptable window").
+     */
+    futureSkew?: number;
+    /**
+     * Injection point for tests. Defaults to `Date.now() / 1000`.
+     */
+    nowSeconds?: () => number;
+}
+/**
+ * Verify a webhook signature produced by the Myme server. The server
+ * emits `X-Myme-Signature: t=<unix>,v1=<hex-sha256>` where the HMAC
+ * signs `<timestamp>.<raw-body>`.
+ *
+ * Pass the raw body string exactly as received (before JSON.parse) and
+ * the same `secret` configured on the webhook. Returns a structured
+ * result so receivers can log the failure reason without retrying on
+ * a permanently-malformed payload.
+ */
+declare function verifyWebhookSignature(input: VerifyWebhookSignatureInput): WebhookVerifyResult;
+
+export { type ClientConfig, type ConflictAutoMergeListener, type ConflictAutoMergedEvent, type ConflictData, ConflictError, type ConflictResolver, type ConflictStrategy, ForbiddenError, type ItemWithExtensions, type ListFilters, type MetadataInput, MymeClient, MymeError, NotFoundError, type SearchFilters, UnauthorizedError, type UpdateOptions, ValidationError, type VerifyWebhookSignatureInput, type WebhookVerifyReason, type WebhookVerifyResult, verifyWebhookSignature };

package/dist/index.js

@@ -760,6 +760,37 @@ var MymeClient = class {
     }
   }
 };
+
+// src/webhooks.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var STRIPE_HEADER_RE = /^t=(\d+),v1=([0-9a-f]+)$/;
+function verifyWebhookSignature(input) {
+  const tolerance = input.tolerance ?? 300;
+  const futureSkew = input.futureSkew ?? 60;
+  const nowSeconds = input.nowSeconds ?? (() => Math.floor(Date.now() / 1e3));
+  const header = input.header?.trim() ?? "";
+  const match = STRIPE_HEADER_RE.exec(header);
+  if (!match?.[1] || !match[2]) {
+    return { valid: false, reason: "malformed" };
+  }
+  const timestamp = match[1];
+  const providedSig = match[2];
+  const ts = Number(timestamp);
+  const now = nowSeconds();
+  if (now - ts > tolerance || ts - now > futureSkew) {
+    return { valid: false, reason: "too_old" };
+  }
+  const computedSig = createHmac("sha256", input.secret).update(`${timestamp}.${input.rawBody}`).digest("hex");
+  if (computedSig.length !== providedSig.length) {
+    return { valid: false, reason: "mismatch" };
+  }
+  const computedBuf = Buffer.from(computedSig, "utf8");
+  const providedBuf = Buffer.from(providedSig, "utf8");
+  if (!timingSafeEqual(computedBuf, providedBuf)) {
+    return { valid: false, reason: "mismatch" };
+  }
+  return { valid: true };
+}
 export {
   ConflictError,
   ForbiddenError,
@@ -767,5 +798,6 @@ export {
   MymeError,
   NotFoundError,
   UnauthorizedError,
-  ValidationError
+  ValidationError,
+  verifyWebhookSignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mymehq/sdk",
-  "version": "3.3.1",
+  "version": "3.4.0",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -16,7 +16,7 @@
     "dist"
   ],
   "dependencies": {
-    "@mymehq/shared": "3.3.1"
+    "@mymehq/shared": "3.4.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",