@apollo-deploy/tesseract 0.1.0

package/templates/typescript/webhook-handler.hbs

@@ -0,0 +1,447 @@
+/**
+ * @generated
+ * This file was automatically generated by sdk-forge.
+ * DO NOT MODIFY THIS FILE DIRECTLY.
+ */
+
+import type {
+{{#each webhookImports}}
+  {{this}},
+{{/each}}
+} from '../types/index.js';
+
+// ── Webhook Event Map ────────────────────────────────
+
+/**
+ * Maps webhook event names to their typed payload.
+ */
+export interface WebhookEventMap {
+{{#each webhooks}}
+  {{#if summary}}
+  /** {{summary}} */
+  {{/if}}
+  '{{name}}': {{payloadType}};
+{{/each}}
+}
+
+export type WebhookEventName = keyof WebhookEventMap;
+
+// ── Webhook Handler Types ────────────────────────────
+
+/**
+ * A typed handler function for a specific webhook event.
+ */
+export type WebhookHandler<E extends WebhookEventName> = (
+  payload: WebhookEventMap[E],
+  meta: WebhookMeta,
+) => void | Promise<void>;
+
+/**
+ * Metadata about the incoming webhook request.
+ */
+export interface WebhookMeta {
+  /** Raw headers from the webhook request */
+  headers: Record<string, string | string[] | undefined>;
+  /** Timestamp when the webhook was received */
+  receivedAt: number;
+  /** The webhook event name */
+  eventName: string;
+  /** Unique delivery ID for deduplication (if provided by the sender) */
+  deliveryId?: string;
+}
+
+/**
+ * Options for webhook signature verification.
+ */
+export interface WebhookVerifyOptions {
+  /**
+   * The raw request body as a string or Buffer for signature verification.
+   * Must be the unmodified body before JSON parsing.
+   */
+  rawBody: string | ArrayBuffer;
+  /** The signature header value from the incoming request */
+  signature: string;
+  /** The shared secret used for HMAC verification */
+  secret: string;
+  /** Hash algorithm for HMAC (default: "sha256") */
+  algorithm?: string;
+  /** Signature encoding format (default: "hex") */
+  encoding?: 'hex' | 'base64';
+  /**
+   * Tolerance window in milliseconds for timestamp-based replay protection.
+   * When set, the `timestamp` field is required and requests outside
+   * the tolerance window are rejected. Default: 0 (disabled).
+   */
+  toleranceMs?: number;
+  /**
+   * Unix timestamp (seconds) from the webhook request for replay protection.
+   * Required when `toleranceMs` is set.
+   */
+  timestamp?: number;
+}
+
+// ── Webhook Configuration ────────────────────────────
+
+/**
+ * Configuration options for the webhook registry.
+ */
+export interface WebhookRegistryConfig {
+  /**
+   * Custom signature verification function.
+   * When provided, replaces the built-in HMAC verifier entirely.
+   * Return `true` if the signature is valid.
+   */
+  verify?: (options: WebhookVerifyOptions) => boolean | Promise<boolean>;
+  /**
+   * Called when a handler throws an error during dispatch.
+   * By default, handler errors are collected and re-thrown as an AggregateError.
+   * Return `true` to swallow the error, or `false`/`void` to collect it.
+   */
+  onHandlerError?: (error: unknown, eventName: string, handler: WebhookHandler<any>) => boolean | void;
+  /**
+   * Maximum number of handlers allowed per event.
+   * Prevents accidental handler accumulation. Default: 100.
+   */
+  maxHandlersPerEvent?: number;
+  /**
+   * Per-handler timeout in milliseconds. Handlers that exceed this
+   * duration will have their promise rejected. Default: 0 (no timeout).
+   */
+  handlerTimeoutMs?: number;
+  /**
+   * Custom function to extract the event name from the raw payload.
+   * When provided, the `eventName` argument to `dispatch` is ignored
+   * and this function determines the event name instead.
+   */
+  resolveEventName?: (payload: unknown, meta: WebhookMeta) => string | undefined;
+  /**
+   * Custom function to transform the raw payload before it reaches handlers.
+   * Useful for unwrapping envelopes or normalizing data structures.
+   */
+  transformPayload?: (payload: unknown, eventName: string) => unknown;
+}
+
+// ── Webhook Registry ─────────────────────────────────
+
+/**
+ * Registry for typed webhook event handlers.
+ * Provides type-safe handler registration and dispatch.
+ */
+export interface WebhookRegistry {
+  /**
+   * Register a handler for a specific webhook event.
+   * Multiple handlers can be registered per event.
+   */
+  on<E extends WebhookEventName>(event: E, handler: WebhookHandler<E>): void;
+
+  /**
+   * Register a one-time handler that automatically unregisters after the first invocation.
+   */
+  once<E extends WebhookEventName>(event: E, handler: WebhookHandler<E>): void;
+
+  /**
+   * Remove a previously registered handler.
+   */
+  off<E extends WebhookEventName>(event: E, handler: WebhookHandler<E>): void;
+
+  /**
+   * Remove all handlers for a specific event, or all handlers if no event is specified.
+   */
+  removeAll(event?: WebhookEventName): void;
+
+  /**
+   * Dispatch a webhook event to all registered handlers.
+   * Returns a promise that resolves when all handlers have completed.
+   * Throws an AggregateError if any handlers fail (unless `onHandlerError` swallows them).
+   */
+  dispatch(eventName: string, payload: unknown, meta: WebhookMeta): Promise<void>;
+
+  /**
+   * Check whether any handlers are registered for the given event.
+   */
+  has(event: WebhookEventName): boolean;
+
+  /**
+   * Return the list of event names that have at least one handler registered.
+   */
+  eventNames(): WebhookEventName[];
+
+  /**
+   * Return the number of handlers registered for a given event.
+   */
+  listenerCount(event: WebhookEventName): number;
+
+  /**
+   * Verify a webhook signature using HMAC (or a custom verifier).
+   * Returns `true` if the signature is valid.
+   */
+  verify(options: WebhookVerifyOptions): Promise<boolean>;
+}
+
+/**
+ * Create a typed webhook handler registry.
+ *
+ * @example
+ * ```typescript
+ * const webhooks = createWebhookRegistry({
+ *   handlerTimeoutMs: 5000,
+ *   onHandlerError: (err, event) => {
+ *     console.error(`Handler failed for ${event}:`, err);
+ *     return true; // swallow the error
+ *   },
+ * });
+ *
+ * webhooks.on('orderCreated', async (payload, meta) => {
+ *   console.log('New order:', payload.id);
+ * });
+ *
+ * // One-time handler
+ * webhooks.once('systemReady', (payload) => {
+ *   console.log('System is ready');
+ * });
+ *
+ * // In your webhook endpoint handler:
+ * app.post('/webhooks', async (req, res) => {
+ *   const isValid = await webhooks.verify({
+ *     rawBody: req.rawBody,
+ *     signature: req.headers['x-webhook-signature'] as string,
+ *     secret: process.env.WEBHOOK_SECRET!,
+ *     toleranceMs: 5 * 60 * 1000, // 5 minute replay window
+ *     timestamp: parseInt(req.headers['x-webhook-timestamp'] as string, 10),
+ *   });
+ *   if (!isValid) return res.status(401).send('Invalid signature');
+ *
+ *   await webhooks.dispatch(req.body.event, req.body.data, {
+ *     headers: req.headers,
+ *     receivedAt: Date.now(),
+ *     eventName: req.body.event,
+ *     deliveryId: req.headers['x-webhook-id'] as string,
+ *   });
+ *   res.status(200).send('OK');
+ * });
+ * ```
+ */
+export function createWebhookRegistry(config: WebhookRegistryConfig = {}): WebhookRegistry {
+  const handlers = new Map<string, Set<WebhookHandler<any>>>();
+  const onceHandlers = new WeakSet<WebhookHandler<any>>();
+  const maxPerEvent = config.maxHandlersPerEvent ?? 100;
+
+  function getOrCreate(event: string): Set<WebhookHandler<any>> {
+    let set = handlers.get(event);
+    if (!set) {
+      set = new Set();
+      handlers.set(event, set);
+    }
+    return set;
+  }
+
+  function wrapWithTimeout<E extends WebhookEventName>(
+    handler: WebhookHandler<E>,
+    timeoutMs: number,
+  ): (payload: WebhookEventMap[E], meta: WebhookMeta) => Promise<void> {
+    return (payload, meta) => {
+      return new Promise<void>((resolve, reject) => {
+        const timer = setTimeout(
+          () => reject(new Error(`Webhook handler timed out after ${timeoutMs}ms`)),
+          timeoutMs,
+        );
+        try {
+          const result = handler(payload, meta);
+          if (result instanceof Promise) {
+            result.then(resolve, reject).finally(() => clearTimeout(timer));
+          } else {
+            clearTimeout(timer);
+            resolve();
+          }
+        } catch (err) {
+          clearTimeout(timer);
+          reject(err);
+        }
+      });
+    };
+  }
+
+  return {
+    on<E extends WebhookEventName>(event: E, handler: WebhookHandler<E>): void {
+      const set = getOrCreate(event);
+      if (set.size >= maxPerEvent) {
+        throw new Error(
+          `Maximum handler limit (${maxPerEvent}) reached for event "${String(event)}". ` +
+          'Remove existing handlers or increase maxHandlersPerEvent.',
+        );
+      }
+      set.add(handler as WebhookHandler<any>);
+    },
+
+    once<E extends WebhookEventName>(event: E, handler: WebhookHandler<E>): void {
+      const set = getOrCreate(event);
+      if (set.size >= maxPerEvent) {
+        throw new Error(
+          `Maximum handler limit (${maxPerEvent}) reached for event "${String(event)}".`,
+        );
+      }
+      onceHandlers.add(handler as WebhookHandler<any>);
+      set.add(handler as WebhookHandler<any>);
+    },
+
+    off<E extends WebhookEventName>(event: E, handler: WebhookHandler<E>): void {
+      const set = handlers.get(event);
+      if (set) {
+        set.delete(handler as WebhookHandler<any>);
+        onceHandlers.delete(handler as WebhookHandler<any>);
+        if (set.size === 0) handlers.delete(event);
+      }
+    },
+
+    removeAll(event?: WebhookEventName): void {
+      if (event !== undefined) {
+        handlers.delete(event);
+      } else {
+        handlers.clear();
+      }
+    },
+
+    async dispatch(eventName: string, payload: unknown, meta: WebhookMeta): Promise<void> {
+      // Allow config to override event name resolution
+      const resolvedName = config.resolveEventName
+        ? config.resolveEventName(payload, meta)
+        : eventName;
+
+      if (resolvedName === undefined) return;
+
+      const eventHandlers = handlers.get(resolvedName);
+      if (!eventHandlers || eventHandlers.size === 0) return;
+
+      // Allow config to transform the payload
+      const resolvedPayload = config.transformPayload
+        ? config.transformPayload(payload, resolvedName)
+        : payload;
+
+      const errors: unknown[] = [];
+      // Snapshot handlers to avoid mutation during iteration
+      const snapshot = Array.from(eventHandlers);
+
+      const promises: Promise<void>[] = [];
+      for (const handler of snapshot) {
+        // Clean up once-handlers before invocation
+        if (onceHandlers.has(handler)) {
+          eventHandlers.delete(handler);
+          onceHandlers.delete(handler);
+          if (eventHandlers.size === 0) handlers.delete(resolvedName);
+        }
+
+        try {
+          const timeoutMs = config.handlerTimeoutMs ?? 0;
+          const fn = timeoutMs > 0
+            ? wrapWithTimeout(handler, timeoutMs)
+            : handler;
+
+          const result = fn(resolvedPayload, meta);
+          if (result instanceof Promise) {
+            promises.push(
+              result.catch((err) => {
+                const swallow = config.onHandlerError?.(err, resolvedName, handler);
+                if (swallow !== true) errors.push(err);
+              }),
+            );
+          }
+        } catch (err) {
+          const swallow = config.onHandlerError?.(err, resolvedName, handler);
+          if (swallow !== true) errors.push(err);
+        }
+      }
+
+      if (promises.length > 0) {
+        await Promise.all(promises);
+      }
+
+      if (errors.length === 1) {
+        throw errors[0];
+      }
+      if (errors.length > 1) {
+        throw new AggregateError(errors, `${errors.length} webhook handler(s) failed for "${resolvedName}"`);
+      }
+    },
+
+    has(event: WebhookEventName): boolean {
+      const set = handlers.get(event);
+      return set !== undefined && set.size > 0;
+    },
+
+    eventNames(): WebhookEventName[] {
+      return Array.from(handlers.keys()) as WebhookEventName[];
+    },
+
+    listenerCount(event: WebhookEventName): number {
+      return handlers.get(event)?.size ?? 0;
+    },
+
+    async verify(options: WebhookVerifyOptions): Promise<boolean> {
+      // Replay protection: reject if timestamp is outside tolerance window
+      if (options.toleranceMs && options.toleranceMs > 0) {
+        if (options.timestamp === undefined) return false;
+        const age = Math.abs(Date.now() - options.timestamp * 1000);
+        if (age > options.toleranceMs) return false;
+      }
+
+      // Delegate to custom verifier if provided
+      if (config.verify) {
+        return config.verify(options);
+      }
+
+      const algorithm = options.algorithm ?? 'sha256';
+      const encoding = options.encoding ?? 'hex';
+
+      try {
+        const encoder = new TextEncoder();
+        const hashName = `SHA-${algorithm.replace(/^sha-?/i, '')}`;
+        const key = await crypto.subtle.importKey(
+          'raw',
+          encoder.encode(options.secret),
+          { name: 'HMAC', hash: hashName },
+          false,
+          ['sign'],
+        );
+
+        const body = typeof options.rawBody === 'string'
+          ? encoder.encode(options.rawBody)
+          : new Uint8Array(options.rawBody);
+
+        const signatureBuffer = await crypto.subtle.sign('HMAC', key, body);
+        const signatureBytes = new Uint8Array(signatureBuffer);
+
+        let computed: string;
+        if (encoding === 'base64') {
+          // Convert to base64
+          let binary = '';
+          for (let i = 0; i < signatureBytes.length; i++) {
+            binary += String.fromCharCode(signatureBytes[i]!);
+          }
+          computed = btoa(binary);
+        } else {
+          computed = Array.from(signatureBytes)
+            .map((b) => b.toString(16).padStart(2, '0'))
+            .join('');
+        }
+
+        // Strip common algorithm prefixes from the provided signature
+        const expected = options.signature
+          .replace(/^sha256=/, '')
+          .replace(/^sha512=/, '')
+          .replace(/^sha1=/, '');
+
+        // Constant-time comparison — return false early only on length mismatch
+        // (length itself is not secret information)
+        if (computed.length !== expected.length) return false;
+
+        let mismatch = 0;
+        for (let i = 0; i < computed.length; i++) {
+          mismatch |= computed.charCodeAt(i) ^ expected.charCodeAt(i);
+        }
+        return mismatch === 0;
+      } catch {
+        return false;
+      }
+    },
+  };
+}