@unifiedcommerce/core 0.0.4 → 0.1.1

package/src/modules/webhooks/hook.ts

@@ -1,34 +0,0 @@
-import type { AfterHook } from "../../kernel/hooks/types.js";
-
-/**
- * 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

@@ -1,278 +0,0 @@
-import { eq, and, lte, isNull, or, desc, sql } from "drizzle-orm";
-import type { TxContext } from "../../../kernel/database/tx-context.js";
-import type {
-  DrizzleDatabase,
-  DbOrTx,
-} from "../../../kernel/database/drizzle-db.js";
-import { webhookEndpoints, webhookDeliveries } from "../schema.js";
-
-// 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

@@ -1,56 +0,0 @@
-import {
-  boolean,
-  index,
-  integer,
-  jsonb,
-  pgTable,
-  text,
-  timestamp,
-  uuid,
-} from "drizzle-orm/pg-core";
-import { organization } from "../../auth/auth-schema.js";
-
-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

@@ -1,117 +0,0 @@
-import { resolveOrgId } from "../../auth/org.js";
-import type { Actor } from "../../auth/types.js";
-import { CommerceNotFoundError, CommerceValidationError } from "../../kernel/errors.js";
-import { Err, Ok, type Result } from "../../kernel/result.js";
-import type { TxContext } from "../../kernel/database/tx-context.js";
-import type { WebhooksRepository, WebhookEndpoint } from "./repository/index.js";
-
-/**
- * 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

@@ -1,6 +0,0 @@
-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

@@ -1,71 +0,0 @@
-/**
- * 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

@@ -1,52 +0,0 @@
-import type { TaskDefinition } from "../../kernel/jobs/types.js";
-import { WebhookDeliveryWorker } from "./worker.js";
-import type { WebhooksRepository } from "./repository/index.js";
-
-/**
- * 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 },
-  },
-};