@unifiedcommerce/core 0.0.1

package/src/modules/webhooks/hook.ts

@@ -0,0 +1,34 @@
+import type { AfterHook } from "../../kernel/hooks/types";
+
+/**
+ * Webhook delivery hook — enqueues delivery jobs instead of blocking.
+ *
+ * Previously, this hook made synchronous HTTP calls to each webhook endpoint
+ * inside the request handler, blocking the response for seconds if endpoints
+ * were slow or down.
+ *
+ * Now it enqueues a background job per endpoint. The job runner delivers
+ * asynchronously with retries. The HTTP response returns immediately.
+ */
+export const deliverWebhooks: AfterHook<unknown> = async ({ result, operation, context }) => {
+  const eventName = `${String(context.context.moduleName ?? "unknown")}.${operation}`;
+  const webhooksService = context.services.webhooks as {
+    getEndpointsForEvent(event: string): Promise<{ ok: boolean; value: Array<{ id: string; url: string; secret: string }> }>;
+  };
+
+  const endpoints = await webhooksService.getEndpointsForEvent(eventName);
+  if (!endpoints.ok) return;
+
+  for (const endpoint of endpoints.value) {
+    await context.jobs.enqueue("webhooks/deliver", {
+      endpointId: endpoint.id,
+      endpointUrl: endpoint.url,
+      endpointSecret: endpoint.secret,
+      eventName,
+      payload: result,
+    }, {
+      maxAttempts: 5,
+      queue: "webhooks",
+    });
+  }
+};

package/src/modules/webhooks/repository/index.ts

@@ -0,0 +1,278 @@
+import { eq, and, lte, isNull, or, desc, sql } from "drizzle-orm";
+import type { TxContext } from "../../../kernel/database/tx-context";
+import type {
+  DrizzleDatabase,
+  DbOrTx,
+} from "../../../kernel/database/drizzle-db";
+import { webhookEndpoints, webhookDeliveries } from "../schema";
+
+// Infer types from Drizzle schema
+export type WebhookEndpoint = typeof webhookEndpoints.$inferSelect;
+export type WebhookEndpointInsert = typeof webhookEndpoints.$inferInsert;
+export type WebhookDelivery = typeof webhookDeliveries.$inferSelect;
+export type WebhookDeliveryInsert = typeof webhookDeliveries.$inferInsert;
+
+/**
+ * WebhooksRepository provides type-safe database operations for webhooks.
+ *
+ * This repository manages webhook endpoints and their delivery tracking.
+ * All methods support an optional TxContext parameter for transaction participation.
+ */
+export class WebhooksRepository {
+  constructor(private readonly db: DrizzleDatabase) {}
+
+  private getDb(ctx?: TxContext): DbOrTx {
+    return (ctx?.tx as DbOrTx | undefined) ?? this.db;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Webhook Endpoints
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  async findEndpointById(
+    id: string,
+    ctx?: TxContext,
+  ): Promise<WebhookEndpoint | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(webhookEndpoints)
+      .where(eq(webhookEndpoints.id, id));
+    return rows[0];
+  }
+
+  async findAllEndpoints(ctx?: TxContext): Promise<WebhookEndpoint[]> {
+    const db = this.getDb(ctx);
+    return db.select().from(webhookEndpoints);
+  }
+
+  async findActiveEndpoints(ctx?: TxContext): Promise<WebhookEndpoint[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(webhookEndpoints)
+      .where(eq(webhookEndpoints.isActive, true));
+  }
+
+  async findEndpointsForEvent(
+    eventName: string,
+    ctx?: TxContext,
+  ): Promise<WebhookEndpoint[]> {
+    const active = await this.findActiveEndpoints(ctx);
+    // Filter endpoints that subscribe to this event
+    return active.filter((endpoint) => {
+      const events = endpoint.events as string[];
+      return events.includes(eventName) || events.includes("*");
+    });
+  }
+
+  async createEndpoint(
+    data: WebhookEndpointInsert,
+    ctx?: TxContext,
+  ): Promise<WebhookEndpoint> {
+    const db = this.getDb(ctx);
+    const rows = await db.insert(webhookEndpoints).values(data).returning();
+    return rows[0]!;
+  }
+
+  async updateEndpoint(
+    id: string,
+    data: Partial<Omit<WebhookEndpointInsert, "id">>,
+    ctx?: TxContext,
+  ): Promise<WebhookEndpoint | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(webhookEndpoints)
+      .set(data)
+      .where(eq(webhookEndpoints.id, id))
+      .returning();
+    return rows[0];
+  }
+
+  async deleteEndpoint(id: string, ctx?: TxContext): Promise<boolean> {
+    const db = this.getDb(ctx);
+    const result = await db
+      .delete(webhookEndpoints)
+      .where(eq(webhookEndpoints.id, id))
+      .returning();
+    return result.length > 0;
+  }
+
+  async activateEndpoint(
+    id: string,
+    ctx?: TxContext,
+  ): Promise<WebhookEndpoint | undefined> {
+    return this.updateEndpoint(id, { isActive: true }, ctx);
+  }
+
+  async deactivateEndpoint(
+    id: string,
+    ctx?: TxContext,
+  ): Promise<WebhookEndpoint | undefined> {
+    return this.updateEndpoint(id, { isActive: false }, ctx);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Webhook Deliveries
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  async findDeliveryById(
+    id: string,
+    ctx?: TxContext,
+  ): Promise<WebhookDelivery | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(webhookDeliveries)
+      .where(eq(webhookDeliveries.id, id));
+    return rows[0];
+  }
+
+  async findDeliveriesByEndpointId(
+    endpointId: string,
+    options?: { limit?: number },
+    ctx?: TxContext,
+  ): Promise<WebhookDelivery[]> {
+    const db = this.getDb(ctx);
+    let query = db
+      .select()
+      .from(webhookDeliveries)
+      .where(eq(webhookDeliveries.endpointId, endpointId))
+      .orderBy(desc(webhookDeliveries.createdAt))
+      .$dynamic();
+
+    if (options?.limit !== undefined) {
+      query = query.limit(options.limit);
+    }
+
+    return query;
+  }
+
+  async findPendingDeliveries(ctx?: TxContext): Promise<WebhookDelivery[]> {
+    const db = this.getDb(ctx);
+    const now = new Date();
+
+    return db
+      .select()
+      .from(webhookDeliveries)
+      .where(
+        and(
+          isNull(webhookDeliveries.deliveredAt),
+          isNull(webhookDeliveries.failedAt),
+          or(
+            isNull(webhookDeliveries.nextRetryAt),
+            lte(webhookDeliveries.nextRetryAt, now),
+          ),
+        ),
+      )
+      .orderBy(webhookDeliveries.createdAt);
+  }
+
+  async findFailedDeliveries(
+    endpointId?: string,
+    ctx?: TxContext,
+  ): Promise<WebhookDelivery[]> {
+    const db = this.getDb(ctx);
+
+    if (endpointId) {
+      return db
+        .select()
+        .from(webhookDeliveries)
+        .where(
+          and(
+            eq(webhookDeliveries.endpointId, endpointId),
+            sql`${webhookDeliveries.failedAt} IS NOT NULL`,
+          ),
+        )
+        .orderBy(desc(webhookDeliveries.failedAt));
+    }
+
+    return db
+      .select()
+      .from(webhookDeliveries)
+      .where(sql`${webhookDeliveries.failedAt} IS NOT NULL`)
+      .orderBy(desc(webhookDeliveries.failedAt));
+  }
+
+  async createDelivery(
+    data: WebhookDeliveryInsert,
+    ctx?: TxContext,
+  ): Promise<WebhookDelivery> {
+    const db = this.getDb(ctx);
+    const rows = await db.insert(webhookDeliveries).values(data).returning();
+    return rows[0]!;
+  }
+
+  async updateDelivery(
+    id: string,
+    data: Partial<Omit<WebhookDeliveryInsert, "id">>,
+    ctx?: TxContext,
+  ): Promise<WebhookDelivery | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(webhookDeliveries)
+      .set(data)
+      .where(eq(webhookDeliveries.id, id))
+      .returning();
+    return rows[0];
+  }
+
+  async markDelivered(
+    id: string,
+    statusCode: number,
+    ctx?: TxContext,
+  ): Promise<WebhookDelivery | undefined> {
+    return this.updateDelivery(
+      id,
+      {
+        statusCode,
+        deliveredAt: new Date(),
+        nextRetryAt: null,
+      },
+      ctx,
+    );
+  }
+
+  async markFailed(
+    id: string,
+    statusCode: number | null,
+    nextRetryAt?: Date,
+    ctx?: TxContext,
+  ): Promise<WebhookDelivery | undefined> {
+    const delivery = await this.findDeliveryById(id, ctx);
+    if (!delivery) return undefined;
+
+    const data: Partial<WebhookDeliveryInsert> = {
+      statusCode: statusCode ?? undefined,
+      attemptCount: delivery.attemptCount + 1,
+    };
+
+    if (nextRetryAt) {
+      data.nextRetryAt = nextRetryAt;
+    } else {
+      data.failedAt = new Date();
+      data.nextRetryAt = null;
+    }
+
+    return this.updateDelivery(id, data, ctx);
+  }
+
+  async deleteDelivery(id: string, ctx?: TxContext): Promise<boolean> {
+    const db = this.getDb(ctx);
+    const result = await db
+      .delete(webhookDeliveries)
+      .where(eq(webhookDeliveries.id, id))
+      .returning();
+    return result.length > 0;
+  }
+
+  async deleteDeliveriesByEndpointId(
+    endpointId: string,
+    ctx?: TxContext,
+  ): Promise<void> {
+    const db = this.getDb(ctx);
+    await db
+      .delete(webhookDeliveries)
+      .where(eq(webhookDeliveries.endpointId, endpointId));
+  }
+}

package/src/modules/webhooks/schema.ts

@@ -0,0 +1,56 @@
+import {
+  boolean,
+  index,
+  integer,
+  jsonb,
+  pgTable,
+  text,
+  timestamp,
+  uuid,
+} from "drizzle-orm/pg-core";
+import { organization } from "../../auth/auth-schema";
+
+export const webhookEndpoints = pgTable(
+  "webhook_endpoints",
+  {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    url: text("url").notNull(),
+    secret: text("secret").notNull(),
+    events: jsonb("events").$type<string[]>().notNull(),
+    isActive: boolean("is_active").notNull().default(true),
+    metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
+  },
+  (table) => ({
+    orgIdx: index("idx_webhook_endpoints_org").on(table.organizationId),
+  }),
+);
+
+/**
+ * Tracks processed incoming webhook events for idempotency.
+ * Prevents double-processing when Stripe (or other providers) retry delivery.
+ */
+export const processedWebhookEvents = pgTable("processed_webhook_events", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  eventId: text("event_id").notNull().unique(),
+  provider: text("provider").notNull(), // "stripe", "paypal", etc.
+  eventType: text("event_type").notNull(),
+  processedAt: timestamp("processed_at", { withTimezone: true }).defaultNow().notNull(),
+});
+
+export const webhookDeliveries = pgTable("webhook_deliveries", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  endpointId: uuid("endpoint_id")
+    .references(() => webhookEndpoints.id)
+    .notNull(),
+  eventName: text("event_name").notNull(),
+  payload: jsonb("payload").notNull(),
+  statusCode: integer("status_code"),
+  attemptCount: integer("attempt_count").notNull().default(0),
+  nextRetryAt: timestamp("next_retry_at", { withTimezone: true }),
+  deliveredAt: timestamp("delivered_at", { withTimezone: true }),
+  failedAt: timestamp("failed_at", { withTimezone: true }),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+});

package/src/modules/webhooks/service.ts

@@ -0,0 +1,117 @@
+import { resolveOrgId } from "../../auth/org";
+import type { Actor } from "../../auth/types";
+import { CommerceNotFoundError, CommerceValidationError } from "../../kernel/errors";
+import { Err, Ok, type Result } from "../../kernel/result";
+import type { TxContext } from "../../kernel/database/tx-context";
+import type { WebhooksRepository, WebhookEndpoint } from "./repository";
+
+/**
+ * Checks whether a URL points to a private/internal IP address.
+ * Blocks: loopback (127.x), link-local (169.254.x), private (10.x, 172.16-31.x, 192.168.x),
+ * cloud metadata (169.254.169.254, metadata.google.internal), and localhost.
+ */
+function isPrivateUrl(urlStr: string): boolean {
+  try {
+    const parsed = new URL(urlStr);
+    // Strip IPv6 brackets: URL.hostname returns "[::1]" not "::1"
+    const hostname = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+
+    // Loopback (IPv4 + IPv6)
+    if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1") return true;
+    if (hostname.endsWith(".localhost")) return true;
+
+    // IPv6 loopback and link-local patterns
+    if (hostname.startsWith("::ffff:")) return true; // IPv6-mapped IPv4 (e.g., ::ffff:127.0.0.1)
+    if (hostname.startsWith("fe80:")) return true;   // IPv6 link-local
+    if (hostname === "::") return true;               // Unspecified address
+
+    // Cloud metadata endpoints
+    if (hostname === "169.254.169.254") return true;
+    if (hostname === "metadata.google.internal") return true;
+
+    // Private IP ranges (RFC 1918 + link-local)
+    const parts = hostname.split(".").map(Number);
+    if (parts.length === 4 && parts.every((n) => !isNaN(n))) {
+      const [a, b] = parts;
+      if (a === 10) return true;
+      if (a === 172 && b !== undefined && b >= 16 && b <= 31) return true;
+      if (a === 192 && b === 168) return true;
+      if (a === 169 && b === 254) return true;
+      if (a === 127) return true;   // Full 127.0.0.0/8 range
+      if (a === 0) return true;
+    }
+
+    return false;
+  } catch {
+    return true; // Invalid URLs are blocked
+  }
+}
+
+interface WebhookServiceDeps {
+  repository: WebhooksRepository;
+}
+
+export class WebhookService {
+  private readonly repo: WebhooksRepository;
+
+  constructor(private deps: WebhookServiceDeps) {
+    this.repo = deps.repository;
+  }
+
+  async createEndpoint(
+    input: {
+      url: string;
+      secret: string;
+      events: string[];
+      metadata?: Record<string, unknown>;
+    },
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<WebhookEndpoint>> {
+    if (isPrivateUrl(input.url)) {
+      return Err(
+        new CommerceValidationError(
+          "Webhook URL must not point to a private or internal address.",
+        ),
+      );
+    }
+
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+
+    const endpoint = await this.repo.createEndpoint(
+      {
+        organizationId: orgId,
+        url: input.url,
+        secret: input.secret,
+        events: input.events,
+        isActive: true,
+        metadata: input.metadata ?? {},
+      },
+      ctx,
+    );
+    return Ok(endpoint);
+  }
+
+  async listEndpoints(ctx?: TxContext): Promise<Result<WebhookEndpoint[]>> {
+    const endpoints = await this.repo.findAllEndpoints(ctx);
+    return Ok(endpoints);
+  }
+
+  async deleteEndpoint(id: string, ctx?: TxContext): Promise<Result<void>> {
+    const existing = await this.repo.findEndpointById(id, ctx);
+    if (!existing) {
+      return Err(new CommerceNotFoundError("Webhook endpoint not found."));
+    }
+
+    await this.repo.deleteEndpoint(id, ctx);
+    return Ok(undefined);
+  }
+
+  async getEndpointsForEvent(
+    eventName: string,
+    ctx?: TxContext,
+  ): Promise<Result<WebhookEndpoint[]>> {
+    const endpoints = await this.repo.findEndpointsForEvent(eventName, ctx);
+    return Ok(endpoints);
+  }
+}

package/src/modules/webhooks/signing.ts

@@ -0,0 +1,6 @@
+import { createHmac } from "node:crypto";
+
+export function signWebhookPayload(secret: string, payload: unknown): string {
+  const body = typeof payload === "string" ? payload : JSON.stringify(payload);
+  return createHmac("sha256", secret).update(body).digest("hex");
+}

package/src/modules/webhooks/ssrf-guard.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared SSRF prevention utilities.
+ *
+ * Used by both webhook delivery (DNS rebinding check) and connector URL
+ * validation (store URL check) to reject private/internal IP addresses.
+ */
+
+/**
+ * Returns true if the given IP address falls within a private, loopback,
+ * link-local, or otherwise non-routable range.
+ */
+export function isPrivateIp(ip: string): boolean {
+  // IPv6 loopback / link-local / mapped
+  if (ip === "::1" || ip === "::") return true;
+  if (ip.startsWith("fe80:")) return true;
+
+  // IPv6-mapped IPv4 (e.g. ::ffff:127.0.0.1) — extract the IPv4 portion
+  const mappedMatch = ip.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+  if (mappedMatch) {
+    return isPrivateIpv4(mappedMatch[1]!);
+  }
+
+  return isPrivateIpv4(ip);
+}
+
+function isPrivateIpv4(ip: string): boolean {
+  const parts = ip.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((n) => isNaN(n))) return false;
+
+  const [a, b] = parts;
+  if (a === undefined || b === undefined) return false;
+
+  if (a === 127) return true;            // loopback 127.0.0.0/8
+  if (a === 10) return true;             // RFC 1918 class A
+  if (a === 172 && b >= 16 && b <= 31) return true; // RFC 1918 class B
+  if (a === 192 && b === 168) return true; // RFC 1918 class C
+  if (a === 169 && b === 254) return true; // link-local / AWS IMDS
+  if (a === 0) return true;              // unspecified
+
+  return false;
+}
+
+/**
+ * Checks whether a URL string points to a private/internal IP address or
+ * hostname. This performs a string-level check only (no DNS resolution).
+ *
+ * For DNS rebinding protection, use `isPrivateIp` after resolving the hostname.
+ */
+export function isPrivateUrl(urlStr: string): boolean {
+  try {
+    const parsed = new URL(urlStr);
+    const hostname = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+
+    // Direct hostname matches
+    if (hostname === "localhost" || hostname.endsWith(".localhost")) return true;
+    if (hostname === "::1" || hostname === "::") return true;
+    if (hostname.startsWith("::ffff:")) return true;
+    if (hostname.startsWith("fe80:")) return true;
+    if (hostname.endsWith(".local")) return true;
+    if (hostname.endsWith(".internal")) return true;
+
+    // Cloud metadata endpoints
+    if (hostname === "169.254.169.254") return true;
+    if (hostname === "metadata.google.internal") return true;
+
+    // Check if hostname is a raw IP in private ranges
+    return isPrivateIpv4(hostname);
+  } catch {
+    return true; // Invalid URLs are blocked
+  }
+}

package/src/modules/webhooks/tasks.ts

@@ -0,0 +1,52 @@
+import type { TaskDefinition } from "../../kernel/jobs/types";
+import { WebhookDeliveryWorker } from "./worker";
+import type { WebhooksRepository } from "./repository";
+
+/**
+ * Background task for async webhook delivery.
+ *
+ * Instead of blocking the HTTP response with inline webhook HTTP calls,
+ * the deliverWebhooks hook enqueues this task. The job runner picks it up
+ * and delivers asynchronously with retries.
+ */
+export const webhookDeliveryTask: TaskDefinition<{
+  endpointId: string;
+  endpointUrl: string;
+  endpointSecret: string;
+  eventName: string;
+  payload: unknown;
+}> = {
+  slug: "webhooks/deliver",
+
+  async handler({ input, ctx }) {
+    const webhooksService = ctx.services.webhooks as {
+      repository?: WebhooksRepository;
+    };
+
+    // Build a minimal worker — the repository is needed for delivery tracking
+    const repository = webhooksService?.repository;
+    if (!repository) {
+      ctx.logger.warn("Webhook delivery skipped: no webhooks repository available");
+      return { output: {} };
+    }
+
+    const worker = new WebhookDeliveryWorker({ repository });
+
+    await worker.deliver({
+      endpoint: {
+        id: input.endpointId,
+        url: input.endpointUrl,
+        secret: input.endpointSecret,
+      },
+      eventName: input.eventName,
+      payload: input.payload,
+    });
+
+    return { output: {} };
+  },
+
+  retries: {
+    attempts: 5,
+    backoff: { type: "exponential", delay: 2000 },
+  },
+};