@sendora/sdk 1.2.0 → 2.1.0

package/src/webhook-verify.ts

@@ -33,11 +33,13 @@ const decoder = new TextDecoder();
 
 /**
  * Checks a webhook request came from Sendora and answers its event, typed
- * by `event`. The header is `Sendora-Signature: t=<unix seconds>,v1=<hex>`,
- * the hex an HMAC-SHA256 with your secret over `<t>.<raw body>`; the
- * timestamp is inside the signed text, so a captured request cannot be
- * replayed after the tolerance. Throws `SendoraError` with
- * `invalid_signature` or `stale_signature`.
+ * by `event`. The header is `Sendora-Signature: t=<unix seconds>,v1=<hex>[,v1=<hex>]`,
+ * one hex per live secret of the webhook, each an HMAC-SHA256 with that
+ * secret over `<t>.<raw body>`; the one your secret produces is enough, so
+ * a secret being rolled in verifies as well as the old one. The timestamp
+ * is inside the signed text, so a captured request cannot be replayed
+ * after the tolerance. Throws `SendoraError` with `invalid_signature` or
+ * `stale_signature`.
  *
  * @example
  * const event = await verifyWebhook({
@@ -72,36 +74,55 @@ export async function verifyWebhook(input: VerifyWebhookInput): Promise<WebhookE
     false,
     ['verify'],
   );
-  if (!(await crypto.subtle.verify('HMAC', key, signature.mac, signed))) {
-    throw invalidSignature('The signature does not match the body.');
+  // Every signature is checked, so the time taken says nothing about which one matched.
+  let matched = false;
+  for (const mac of signature.macs) {
+    matched = (await crypto.subtle.verify('HMAC', key, mac, signed)) || matched;
+  }
+  if (!matched) {
+    throw invalidSignature('No signature in the header matches the body under this secret.');
   }
   return parseEvent(decoder.decode(body));
 }
 
+/** The timestamp and every `v1` value, one per live secret of the webhook. */
 function parseSignature(header: string | null | undefined): {
   timestamp: number;
-  mac: Uint8Array<ArrayBuffer>;
+  macs: Uint8Array<ArrayBuffer>[];
 } {
   if (typeof header !== 'string' || header === '') {
     throw invalidSignature('The request carries no Sendora-Signature header.');
   }
-  const parts = new Map<string, string>();
+  let timestamp: number | undefined;
+  const macs: Uint8Array<ArrayBuffer>[] = [];
   for (const part of header.split(',')) {
     const separator = part.indexOf('=');
-    if (separator > 0) {
-      parts.set(part.slice(0, separator).trim(), part.slice(separator + 1).trim());
+    if (separator <= 0) {
+      continue;
+    }
+    const name = part.slice(0, separator).trim();
+    const value = part.slice(separator + 1).trim();
+    if (name === 't') {
+      timestamp = Number(value);
+    } else if (name === 'v1') {
+      if (!MAC_HEX.test(value)) {
+        throw invalidSignature('The Sendora-Signature header is malformed.');
+      }
+      macs.push(bytesOf(value));
     }
   }
-  const timestamp = Number(parts.get('t'));
-  const hex = parts.get('v1');
-  if (!Number.isInteger(timestamp) || hex === undefined || !MAC_HEX.test(hex)) {
+  if (timestamp === undefined || !Number.isInteger(timestamp) || macs.length === 0) {
     throw invalidSignature('The Sendora-Signature header is malformed.');
   }
-  const mac = new Uint8Array(hex.length / 2);
-  for (let i = 0; i < mac.length; i += 1) {
-    mac[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return { timestamp, macs };
+}
+
+function bytesOf(hex: string): Uint8Array<ArrayBuffer> {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i += 1) {
+    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
   }
-  return { timestamp, mac };
+  return bytes;
 }
 
 function parseEvent(text: string): WebhookEvent {

package/src/webhooks.ts

@@ -2,6 +2,7 @@ import { paginate } from './pagination.ts';
 import type { Transport } from './transport.ts';
 import type {
   CreatedWebhook,
+  CreatedWebhookSecret,
   CreateWebhookRequest,
   Delivery,
   DeliveryPage,
@@ -74,6 +75,34 @@ export class WebhooksResource {
     });
   }
 
+  /**
+   * Adds a second live secret and answers its value once. Every delivery
+   * then carries one signature per live secret, the newest first, so
+   * switch your receiver to the new secret and delete the old one; a third
+   * is refused with `secret_limit`.
+   *
+   *
+   * const { secret, secretId } = await sendora.webhooks.createSecret(webhookId);
+   */
+  createSecret(webhookId: string, options: RequestOptions = {}): Promise<CreatedWebhookSecret> {
+    return this.#transport.request<CreatedWebhookSecret>({
+      method: 'POST',
+      path: `/v1/webhooks/${encodeURIComponent(webhookId)}/secrets`,
+      idempotent: false,
+      signal: options.signal,
+    });
+  }
+
+  /** Deletes a secret; deliveries are no longer signed with it. The last live secret is refused (`last_secret`). */
+  deleteSecret(webhookId: string, secretId: string, options: RequestOptions = {}): Promise<void> {
+    return this.#transport.request<undefined>({
+      method: 'DELETE',
+      path: `/v1/webhooks/${encodeURIComponent(webhookId)}/secrets/${encodeURIComponent(secretId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
   /**
    * One page of the events handed to the webhook, newest first, with the
    * outcome of the last attempt; `status` narrows to `pending`,