vairified 0.7.0 → 0.8.0

package/README.md

@@ -255,6 +255,148 @@ const result = await client.matches.tournamentImport({
 console.log(`Imported ${result.matchesImported} matches, ${result.ghostPlayersCreated} ghosts`);
 ```
 
+## Receiving Webhooks
+
+`verifyWebhook()` checks a delivery's signature and hands it back typed. It takes no client
+and no API key — a webhook receiver is an inbound HTTP handler, and often never calls the
+Partner API at all.
+
+**Verify on your server, never in a browser or a mobile app.** The signing secret is what
+proves a delivery came from us; anything that ships to a user's device can be read out of it.
+
+```ts
+import { verifyWebhook, isMemberStatusEvent, WebhookSignatureError } from 'vairified';
+
+const event = await verifyWebhook(
+  rawBody,                              // the exact bytes — see below
+  request.headers['x-vairified-signature'],
+  process.env.VAIR_WEBHOOK_SECRET,
+);
+
+if (isMemberStatusEvent(event)) {
+  await entitlements.set(event.data.memberId, {
+    vairPlus: event.data.isVairPlus,
+    ambassador: event.data.isAmbassador,
+  });
+}
+```
+
+It is `async` — **`await` it.** Verification uses Web Crypto, which has no synchronous HMAC.
+The function never returns a boolean, precisely so that a forgotten `await` cannot be read as
+"the signature was fine".
+
+### Capture the raw body
+
+The signature covers **the bytes we sent**. A body that has been parsed and re-serialised is
+not those bytes — key order, whitespace and number formatting all move — so every signature
+fails. In Express, that means reaching for `express.raw()` on the webhook route specifically,
+even when the rest of the app uses `express.json()`:
+
+```ts
+import express from 'express';
+import { verifyWebhook, WebhookSignatureError, dedupeKey } from 'vairified';
+
+const app = express();
+
+app.post('/webhooks/vairified', express.raw({ type: 'application/json' }), async (req, res) => {
+  let event;
+  try {
+    event = await verifyWebhook(req.body, req.get('X-Vairified-Signature'), [
+      process.env.VAIR_WEBHOOK_SECRET,
+      process.env.VAIR_WEBHOOK_SECRET_PREVIOUS,   // see "Rotating the secret"
+    ]);
+  } catch (err) {
+    if (err instanceof WebhookSignatureError) return res.sendStatus(400);
+    throw err;
+  }
+
+  // Respond first, work afterwards — a slow handler is retried as a failure.
+  res.sendStatus(200);
+  await queue.add(dedupeKey(event), event);
+});
+
+app.use(express.json());   // everything else
+```
+
+In a Fetch-based runtime (Workers, Deno, Bun, Next.js route handlers) `await request.text()`
+already gives you the raw body; pass it straight in. `rawBody` accepts a `string` or a
+`Uint8Array`.
+
+### Handling what arrives
+
+```ts
+const event = await verifyWebhook(rawBody, signatureHeader, process.env.VAIR_WEBHOOK_SECRET);
+
+if (isMemberStatusEvent(event)) {
+  // membership or ambassador standing changed
+} else if (isRatingUpdatedEvent(event)) {
+  // a new rating, as a full per-sport snapshot
+} else if (isConnectionRevokedEvent(event)) {
+  // the member disconnected your app — stop reading their data
+} else if (isEventCreatedEvent(event)) {
+  // a new event was published
+}
+// Anything else is an event type this version does not know about. It still
+// verified, and arrives as the plain envelope — ignore it, or log it.
+```
+
+An event type the package does not recognise **verifies successfully and is handed over
+as-is**, and so does an unfamiliar value inside one it does recognise. Both grow on the API's
+schedule rather than this package's, and refusing one would break a working receiver over a
+change that is not a break.
+
+### Ordering and duplicates
+
+Delivery is at-least-once, and deliveries can arrive out of order.
+
+```ts
+if (isRatingUpdatedEvent(event)) {
+  const last = await store.get(event.data.memberId);
+  if (last && !isNewerSequence(event.data.sequence, last)) return;   // stale — skip it
+  await store.put(event.data.memberId, event.data.sequence);
+}
+```
+
+- **`sequence` is an unpadded decimal string, so do not compare it as one.** `'10000000' >
+  '9999999'` is `false`, which would discard every later delivery for that member from the
+  first power-of-ten crossing onward. `isNewerSequence()` and `compareSequence()` compare as
+  integers.
+- **Deduplicate with `dedupeKey(event)`**, which returns the id from the *signed body*. The
+  `X-Vairified-Event-Id` header carries the same value but is outside the signature, so a
+  replayed delivery can present a fresh one and header-based deduplication admits it every
+  time.
+
+### Rotating the secret
+
+`secret` accepts an array, and any one match verifies:
+
+```ts
+const event = await verifyWebhook(rawBody, signatureHeader, [
+  process.env.VAIR_WEBHOOK_SECRET,
+  process.env.VAIR_WEBHOOK_SECRET_PREVIOUS,
+]);
+```
+
+Deliveries queued before you rotated were signed with the **old** secret and keep arriving for
+hours afterwards. A verifier that knows only the new one discards them silently, so keep the
+previous secret configured until the retry tail has drained.
+
+### Why a delivery was refused
+
+Every refusal is a `WebhookSignatureError` with a `reason` you can branch on:
+
+| `reason` | Means |
+|---|---|
+| `no_secret_configured` | Your configuration, not an attack — almost always an unset environment variable. |
+| `invalid_option` | A tolerance or clock you passed in was not usable. |
+| `missing_signature` | No `X-Vairified-Signature` header. |
+| `malformed_signature` | The header was present but unparseable, or had no `t` / `v1`. |
+| `timestamp_out_of_tolerance` | The delivery's clock and yours disagree by more than the window (5 minutes by default, applied in both directions). |
+| `signature_mismatch` | The body does not match the signature under any secret supplied. |
+| `malformed_body` | The body was not JSON, or a field a partner gates access on was missing or the wrong type. |
+
+The message never contains the secret or either digest.
+
 ## Webhook Deliveries
 
 Inspect recent webhook delivery attempts for your app:

package/dist/index.cjs

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   AuthenticationError: () => AuthenticationError,
   DEFAULT_SCOPES: () => DEFAULT_SCOPES,
+  DEFAULT_TOLERANCE_SECONDS: () => DEFAULT_TOLERANCE_SECONDS,
   ENVIRONMENTS: () => ENVIRONMENTS,
   LeaderboardResource: () => LeaderboardResource,
   MatchBatchResult: () => MatchBatchResult,
@@ -44,12 +45,21 @@ __export(index_exports, {
   ValidationError: () => ValidationError,
   WebhookDeliveriesResult: () => WebhookDeliveriesResult,
   WebhookDelivery: () => WebhookDelivery,
+  WebhookSignatureError: () => WebhookSignatureError,
   WebhooksResource: () => WebhooksResource,
+  compareSequence: () => compareSequence,
+  dedupeKey: () => dedupeKey,
   describeScope: () => describeScope,
   describeScopes: () => describeScopes,
   generateState: () => generateState,
   getAuthorizationUrl: () => getAuthorizationUrl,
-  validateScope: () => validateScope
+  isConnectionRevokedEvent: () => isConnectionRevokedEvent,
+  isEventCreatedEvent: () => isEventCreatedEvent,
+  isMemberStatusEvent: () => isMemberStatusEvent,
+  isNewerSequence: () => isNewerSequence,
+  isRatingUpdatedEvent: () => isRatingUpdatedEvent,
+  validateScope: () => validateScope,
+  verifyWebhook: () => verifyWebhook
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -105,6 +115,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 {
@@ -1575,10 +1593,208 @@ 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;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthenticationError,
   DEFAULT_SCOPES,
+  DEFAULT_TOLERANCE_SECONDS,
   ENVIRONMENTS,
   LeaderboardResource,
   MatchBatchResult,
@@ -1601,11 +1817,20 @@ var Vairified = class {
   ValidationError,
   WebhookDeliveriesResult,
   WebhookDelivery,
+  WebhookSignatureError,
   WebhooksResource,
+  compareSequence,
+  dedupeKey,
   describeScope,
   describeScopes,
   generateState,
   getAuthorizationUrl,
-  validateScope
+  isConnectionRevokedEvent,
+  isEventCreatedEvent,
+  isMemberStatusEvent,
+  isNewerSequence,
+  isRatingUpdatedEvent,
+  validateScope,
+  verifyWebhook
 });
 //# sourceMappingURL=index.cjs.map