@beignet/core 0.0.32 → 0.0.33

package/src/webhooks/index.ts

@@ -105,11 +105,72 @@ export interface DefineWebhookOptions<
 /**
  * Options accepted by `verifyWebhook(...)`.
  */
-export interface VerifyWebhookOptions {
+export interface VerifyWebhookOptions<
+  AllowUnknownEvents extends boolean = boolean,
+> {
   verifier?: WebhookVerifier;
-  allowUnknownEvents?: boolean;
+  allowUnknownEvents?: AllowUnknownEvents;
 }
 
+type InferWebhookVerificationResult<
+  TWebhook extends WebhookDef<string, WebhookEventSchemas>,
+  AllowUnknownEvents extends boolean,
+> = true extends AllowUnknownEvents
+  ? InferWebhookEvent<TWebhook> | WebhookEvent
+  : InferWebhookEvent<TWebhook>;
+
+/**
+ * Timestamp formats accepted by the generic HMAC webhook verifier.
+ */
+export type HmacWebhookTimestampFormat =
+  | "unix-seconds"
+  | "unix-milliseconds"
+  | "iso8601";
+
+/**
+ * Timestamp source and tolerance for generic HMAC replay protection.
+ */
+export type HmacWebhookTimestampOptions =
+  | {
+      /**
+       * Header that carries the provider event timestamp.
+       */
+      header: string;
+      payloadPath?: never;
+      /**
+       * Timestamp format.
+       *
+       * @default "unix-seconds"
+       */
+      format?: HmacWebhookTimestampFormat;
+      /**
+       * Maximum absolute clock skew between the event timestamp and receipt.
+       *
+       * @default 300
+       */
+      toleranceSec?: number;
+    }
+  | {
+      header?: never;
+      /**
+       * Dot path used to read the provider event timestamp from the JSON
+       * payload.
+       */
+      payloadPath: string;
+      /**
+       * Timestamp format.
+       *
+       * @default "unix-seconds"
+       */
+      format?: HmacWebhookTimestampFormat;
+      /**
+       * Maximum absolute clock skew between the event timestamp and receipt.
+       *
+       * @default 300
+       */
+      toleranceSec?: number;
+    };
+
 /**
  * Options for the in-memory webhook verifier.
  */
@@ -163,6 +224,10 @@ export interface CreateHmacWebhookVerifierOptions {
    * @default "type"
    */
   eventTypePath?: string;
+  /**
+   * Optional timestamp source used to reject replayed generic HMAC webhooks.
+   */
+  timestamp?: HmacWebhookTimestampOptions;
 }
 
 /**
@@ -250,11 +315,12 @@ export function defineWebhook<
  */
 export async function verifyWebhook<
   TWebhook extends WebhookDef<string, WebhookEventSchemas>,
+  AllowUnknownEvents extends boolean = false,
 >(
   webhook: TWebhook,
   input: VerifyWebhookInput,
-  options: VerifyWebhookOptions = {},
-): Promise<InferWebhookEvent<TWebhook> | WebhookEvent> {
+  options: VerifyWebhookOptions<AllowUnknownEvents> = {},
+): Promise<InferWebhookVerificationResult<TWebhook, AllowUnknownEvents>> {
   validateWebhook(webhook);
   const verifier = options.verifier ?? webhook.verifier;
   if (!verifier) {
@@ -285,17 +351,26 @@ export async function verifyWebhook<
  */
 export async function parseWebhookEvent<
   TWebhook extends WebhookDef<string, WebhookEventSchemas>,
+  AllowUnknownEvents extends boolean = false,
 >(
   webhook: TWebhook,
   event: WebhookEvent,
-  options: Pick<VerifyWebhookOptions, "allowUnknownEvents"> = {},
-): Promise<InferWebhookEvent<TWebhook> | WebhookEvent> {
+  options: Pick<
+    VerifyWebhookOptions<AllowUnknownEvents>,
+    "allowUnknownEvents"
+  > = {},
+): Promise<InferWebhookVerificationResult<TWebhook, AllowUnknownEvents>> {
   validateWebhook(webhook);
   validateEvent(webhook, event);
 
   const schema = webhook.events[event.type];
   if (!schema) {
-    if (options.allowUnknownEvents ?? true) return event;
+    if (options.allowUnknownEvents === true) {
+      return event as InferWebhookVerificationResult<
+        TWebhook,
+        AllowUnknownEvents
+      >;
+    }
     throw new WebhookVerificationError({
       message: `Webhook "${webhook.name}" received unknown event type "${event.type}".`,
       webhookName: webhook.name,
@@ -320,7 +395,7 @@ export async function parseWebhookEvent<
   return {
     ...event,
     payload: result.value,
-  };
+  } as InferWebhookVerificationResult<TWebhook, AllowUnknownEvents>;
 }
 
 /**
@@ -373,6 +448,7 @@ export function createHmacWebhookVerifier(
   const algorithm = options.algorithm ?? "SHA-256";
   const eventIdPath = options.eventIdPath ?? "id";
   const eventTypePath = options.eventTypePath ?? "type";
+  const timestamp = normalizeHmacTimestampOptions(options.timestamp);
 
   return {
     async verify(input) {
@@ -396,6 +472,12 @@ export function createHmacWebhookVerifier(
       }
 
       const payload = parseJsonBody(input.rawBody);
+      const createdAt = validateHmacTimestamp({
+        input,
+        payload,
+        provider: options.provider,
+        timestamp,
+      });
       const id = readStringPath(payload, eventIdPath);
       const type = readStringPath(payload, eventTypePath);
 
@@ -418,6 +500,7 @@ export function createHmacWebhookVerifier(
         id,
         type,
         provider: options.provider,
+        ...(createdAt ? { createdAt } : {}),
         payload,
         raw: payload,
       };
@@ -502,7 +585,7 @@ function parseJsonBody(rawBody: WebhookRawBody): unknown {
   }
 }
 
-function readStringPath(input: unknown, path: string): string | undefined {
+function readPath(input: unknown, path: string): unknown {
   let value = input;
   for (const segment of path.split(".")) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -511,9 +594,155 @@ function readStringPath(input: unknown, path: string): string | undefined {
     value = (value as Record<string, unknown>)[segment];
   }
 
+  return value;
+}
+
+function readStringPath(input: unknown, path: string): string | undefined {
+  const value = readPath(input, path);
   return typeof value === "string" && value.length > 0 ? value : undefined;
 }
 
+type NormalizedHmacTimestampOptions =
+  | {
+      source: "header";
+      key: string;
+      format: HmacWebhookTimestampFormat;
+      toleranceSec: number;
+    }
+  | {
+      source: "payload";
+      path: string;
+      format: HmacWebhookTimestampFormat;
+      toleranceSec: number;
+    };
+
+function normalizeHmacTimestampOptions(
+  timestamp: HmacWebhookTimestampOptions | undefined,
+): NormalizedHmacTimestampOptions | undefined {
+  if (!timestamp) return undefined;
+
+  const format = timestamp.format ?? "unix-seconds";
+  if (
+    format !== "unix-seconds" &&
+    format !== "unix-milliseconds" &&
+    format !== "iso8601"
+  ) {
+    throw new WebhookOptionsError(
+      "Webhook HMAC timestamp format must be unix-seconds, unix-milliseconds, or iso8601.",
+    );
+  }
+  const toleranceSec = timestamp.toleranceSec ?? 300;
+  if (!Number.isInteger(toleranceSec) || toleranceSec <= 0) {
+    throw new WebhookOptionsError(
+      "Webhook HMAC timestamp toleranceSec must be a positive integer.",
+    );
+  }
+
+  if ("header" in timestamp) {
+    if (!timestamp.header) {
+      throw new WebhookOptionsError(
+        "Webhook HMAC timestamp header is required.",
+      );
+    }
+
+    return {
+      source: "header",
+      key: normalizeHeaderName(timestamp.header),
+      format,
+      toleranceSec,
+    };
+  }
+
+  if (!timestamp.payloadPath) {
+    throw new WebhookOptionsError(
+      "Webhook HMAC timestamp payloadPath is required.",
+    );
+  }
+
+  return {
+    source: "payload",
+    path: timestamp.payloadPath,
+    format,
+    toleranceSec,
+  };
+}
+
+function validateHmacTimestamp(args: {
+  input: VerifyWebhookInput;
+  payload: unknown;
+  provider: string | undefined;
+  timestamp: NormalizedHmacTimestampOptions | undefined;
+}): Date | undefined {
+  const { timestamp } = args;
+  if (!timestamp) return undefined;
+
+  const value =
+    timestamp.source === "header"
+      ? args.input.headers?.[timestamp.key]
+      : readPath(args.payload, timestamp.path);
+
+  if (value === undefined || value === null || value === "") {
+    throw new WebhookVerificationError({
+      message:
+        timestamp.source === "header"
+          ? `Missing ${timestamp.key} header.`
+          : `Webhook payload is missing timestamp at "${timestamp.path}".`,
+      provider: args.provider,
+      code: "missing_timestamp",
+    });
+  }
+
+  const createdAt = parseHmacTimestampValue(
+    value,
+    timestamp.format,
+    args.provider,
+  );
+  const receivedAt = args.input.receivedAt ?? new Date();
+  const skewMs = Math.abs(receivedAt.getTime() - createdAt.getTime());
+  if (skewMs > timestamp.toleranceSec * 1000) {
+    throw new WebhookVerificationError({
+      message: `Webhook timestamp is outside the ${timestamp.toleranceSec}s tolerance.`,
+      provider: args.provider,
+      code: "timestamp_outside_tolerance",
+    });
+  }
+
+  return createdAt;
+}
+
+function parseHmacTimestampValue(
+  value: unknown,
+  format: HmacWebhookTimestampFormat,
+  provider: string | undefined,
+): Date {
+  const fail = () =>
+    new WebhookVerificationError({
+      message: "Webhook timestamp is invalid.",
+      provider,
+      code: "invalid_timestamp",
+    });
+
+  let millis: number;
+  if (format === "iso8601") {
+    if (typeof value !== "string") throw fail();
+    millis = Date.parse(value);
+  } else {
+    const numeric =
+      typeof value === "number"
+        ? value
+        : typeof value === "string"
+          ? Number(value)
+          : Number.NaN;
+    if (!Number.isFinite(numeric)) throw fail();
+    millis = format === "unix-seconds" ? numeric * 1000 : numeric;
+  }
+
+  if (!Number.isFinite(millis)) throw fail();
+  const date = new Date(millis);
+  if (Number.isNaN(date.getTime())) throw fail();
+  return date;
+}
+
 async function hmacHex(
   algorithm: CreateHmacWebhookVerifierOptions["algorithm"],
   secret: string,