vairified 0.7.0 → 0.8.0

package/dist/index.js

@@ -50,6 +50,14 @@ var OAuthError = class extends VairifiedError {
     this.errorCode = errorCode;
   }
 };
+var WebhookSignatureError = class extends VairifiedError {
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.name = "WebhookSignatureError";
+    this.reason = reason;
+  }
+};
 
 // src/http.ts
 var HttpTransport = class {
@@ -1520,9 +1528,207 @@ var Vairified = class {
     return `Vairified { env: '${this.env}', baseUrl: '${this.baseUrl}' }`;
   }
 };
+
+// src/webhooks/verify.ts
+var DEFAULT_TOLERANCE_SECONDS = 300;
+var SIGNATURE_HEADER = "X-Vairified-Signature";
+var encoder = new TextEncoder();
+function toBytes(body) {
+  return typeof body === "string" ? encoder.encode(body) : body;
+}
+function parseSignatureHeader(header) {
+  let timestamp = null;
+  let rawTimestamp = null;
+  let signature = null;
+  for (const part of header.split(",")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    const key = part.slice(0, eq).trim();
+    const value = part.slice(eq + 1).trim();
+    if (key === "t" && timestamp === null) {
+      if (!/^\d+$/.test(value)) {
+        throw new WebhookSignatureError(
+          "malformed_signature",
+          `${SIGNATURE_HEADER} carried a timestamp that is not an integer`
+        );
+      }
+      timestamp = Number(value);
+      rawTimestamp = value;
+    } else if (key === "v1" && signature === null) {
+      signature = value;
+    }
+  }
+  if (timestamp === null || rawTimestamp === null || signature === null) {
+    throw new WebhookSignatureError(
+      "malformed_signature",
+      `${SIGNATURE_HEADER} must carry both a 't' and a 'v1' part`
+    );
+  }
+  return { timestamp, rawTimestamp, signature };
+}
+var MAX_SIGNATURE_HEX = 64;
+function hexToBytes(hex) {
+  if (hex.length > MAX_SIGNATURE_HEX) {
+    throw new WebhookSignatureError(
+      "malformed_signature",
+      `${SIGNATURE_HEADER} carried a 'v1' value longer than a SHA-256 digest`
+    );
+  }
+  if (hex.length === 0 || hex.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(hex)) {
+    throw new WebhookSignatureError(
+      "malformed_signature",
+      `${SIGNATURE_HEADER} carried a 'v1' value that is not a hex digest`
+    );
+  }
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+function assertEnvelope(value) {
+  if (typeof value !== "object" || value === null) {
+    throw new WebhookSignatureError("malformed_body", "The webhook body is not a JSON object");
+  }
+  const o = value;
+  for (const field of ["event", "eventId", "timestamp"]) {
+    if (typeof o[field] !== "string") {
+      throw new WebhookSignatureError(
+        "malformed_body",
+        `The webhook body is missing a string '${field}'`
+      );
+    }
+  }
+}
+function assertKnownEventShape(event) {
+  const bad = (field) => {
+    throw new WebhookSignatureError(
+      "malformed_body",
+      `A '${event.event}' event is missing a valid '${field}'`
+    );
+  };
+  const data = event.data;
+  if (typeof data !== "object" || data === null) {
+    if (event.event === "member.status" || event.event === "rating.updated") bad("data");
+    return;
+  }
+  if (event.event === "member.status") {
+    if (typeof data.memberId !== "number") bad("data.memberId");
+    if (typeof data.isVairPlus !== "boolean") bad("data.isVairPlus");
+    if (typeof data.isAmbassador !== "boolean") bad("data.isAmbassador");
+  } else if (event.event === "rating.updated") {
+    if (typeof data.memberId !== "number") bad("data.memberId");
+    if (typeof data.sequence !== "string") bad("data.sequence");
+  }
+}
+async function verifyWebhook(rawBody, signatureHeader, secret, options = {}) {
+  const candidates = typeof secret === "string" ? [secret] : Array.isArray(secret) ? secret : [];
+  const secrets = candidates.filter(
+    (s) => typeof s === "string" && s.trim().length > 0
+  );
+  if (secrets.length === 0) {
+    throw new WebhookSignatureError(
+      "no_secret_configured",
+      "No usable signing secret was supplied"
+    );
+  }
+  if (!signatureHeader) {
+    throw new WebhookSignatureError(
+      "missing_signature",
+      `No ${SIGNATURE_HEADER} header was supplied`
+    );
+  }
+  const tolerance = options.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+  const now = options.nowSeconds ?? Math.floor(Date.now() / 1e3);
+  if (!Number.isFinite(tolerance) || tolerance < 0) {
+    throw new WebhookSignatureError(
+      "invalid_option",
+      "toleranceSeconds must be a finite, non-negative number"
+    );
+  }
+  if (!Number.isFinite(now)) {
+    throw new WebhookSignatureError("invalid_option", "nowSeconds must be a finite number");
+  }
+  const { timestamp, rawTimestamp, signature } = parseSignatureHeader(signatureHeader);
+  if (Math.abs(now - timestamp) > tolerance) {
+    throw new WebhookSignatureError(
+      "timestamp_out_of_tolerance",
+      `The delivery timestamp is outside the ${tolerance}s tolerance`
+    );
+  }
+  const signatureBytes = hexToBytes(signature);
+  const bodyBytes = toBytes(rawBody);
+  const prefix = encoder.encode(`${rawTimestamp}.`);
+  const signed = new Uint8Array(prefix.length + bodyBytes.length);
+  signed.set(prefix, 0);
+  signed.set(bodyBytes, prefix.length);
+  let matched = false;
+  for (const candidate of secrets) {
+    const key = await crypto.subtle.importKey(
+      "raw",
+      encoder.encode(candidate),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["verify"]
+    );
+    matched = await crypto.subtle.verify("HMAC", key, signatureBytes, signed) || matched;
+  }
+  if (!matched) {
+    throw new WebhookSignatureError(
+      "signature_mismatch",
+      "The webhook signature did not match any supplied secret"
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(
+      new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(
+        signed.subarray(prefix.length)
+      )
+    );
+  } catch {
+    throw new WebhookSignatureError("malformed_body", "The webhook body is not valid JSON");
+  }
+  assertEnvelope(parsed);
+  assertKnownEventShape(parsed);
+  return deepFreeze(parsed);
+}
+function deepFreeze(value) {
+  if (value === null || typeof value !== "object" || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const key of Object.getOwnPropertyNames(value)) {
+    deepFreeze(value[key]);
+  }
+  return value;
+}
+function isMemberStatusEvent(event) {
+  return event.event === "member.status";
+}
+function isConnectionRevokedEvent(event) {
+  return event.event === "connection.revoked";
+}
+function isRatingUpdatedEvent(event) {
+  return event.event === "rating.updated";
+}
+function isEventCreatedEvent(event) {
+  return event.event === "event.created";
+}
+function compareSequence(a, b) {
+  const x = BigInt(a);
+  const y = BigInt(b);
+  return x < y ? -1 : x > y ? 1 : 0;
+}
+function isNewerSequence(incoming, lastApplied) {
+  if (lastApplied === void 0 || lastApplied === null || lastApplied === "") return true;
+  return compareSequence(incoming, lastApplied) > 0;
+}
+function dedupeKey(event) {
+  return event.eventId;
+}
 export {
   AuthenticationError,
   DEFAULT_SCOPES,
+  DEFAULT_TOLERANCE_SECONDS,
   ENVIRONMENTS,
   LeaderboardResource,
   MatchBatchResult,
@@ -1545,11 +1751,20 @@ export {
   ValidationError,
   WebhookDeliveriesResult,
   WebhookDelivery,
+  WebhookSignatureError,
   WebhooksResource,
+  compareSequence,
+  dedupeKey,
   describeScope,
   describeScopes,
   generateState,
   getAuthorizationUrl,
-  validateScope
+  isConnectionRevokedEvent,
+  isEventCreatedEvent,
+  isMemberStatusEvent,
+  isNewerSequence,
+  isRatingUpdatedEvent,
+  validateScope,
+  verifyWebhook
 };
 //# sourceMappingURL=index.js.map