@porulle/core 0.1.0

package/src/modules/webhooks/service.ts

@@ -0,0 +1,127 @@
+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(
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<WebhookEndpoint[]>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const endpoints = await this.repo.findAllEndpoints(orgId, ctx);
+    return Ok(endpoints);
+  }
+
+  async deleteEndpoint(
+    id: string,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<void>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const existing = await this.repo.findEndpointById(id, orgId, ctx);
+    if (!existing) {
+      return Err(new CommerceNotFoundError("Webhook endpoint not found."));
+    }
+
+    await this.repo.deleteEndpoint(id, ctx);
+    return Ok(undefined);
+  }
+
+  async getEndpointsForEvent(
+    eventName: string,
+    orgId: string,
+    ctx?: TxContext,
+  ): Promise<Result<WebhookEndpoint[]>> {
+    const endpoints = await this.repo.findEndpointsForEvent(eventName, orgId, 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,60 @@
+import type { TaskDefinition } from "../../kernel/jobs/types.js";
+import { WebhookDeliveryWorker } from "./worker.js";
+import type { WebhooksRepository } from "./repository/index.js";
+
+const WEBHOOK_DELIVERY_RETRY_BACKOFF = {
+  type: "exponential" as const,
+  delay: 2000,
+};
+
+/**
+ * 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, job }) {
+    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,
+      jobAttempt: job?.attemptNumber ?? 1,
+      jobMaxAttempts: job?.maxAttempts ?? 1,
+      retryBackoff: WEBHOOK_DELIVERY_RETRY_BACKOFF,
+    });
+
+    return { output: {} };
+  },
+
+  retries: {
+    attempts: 5,
+    backoff: WEBHOOK_DELIVERY_RETRY_BACKOFF,
+  },
+};

package/src/modules/webhooks/worker.ts

@@ -0,0 +1,171 @@
+import { signWebhookPayload } from "./signing.js";
+import { isPrivateIp } from "./ssrf-guard.js";
+import type { WebhooksRepository } from "./repository/index.js";
+import type { TaskRetryConfig } from "../../kernel/jobs/types.js";
+
+/**
+ * SSRF prevention: reject webhook URLs targeting private/internal hosts.
+ * Blocks RFC 1918, loopback, link-local, and common internal domains.
+ */
+const PRIVATE_HOST_PATTERNS = [
+  /^127\./, // loopback
+  /^10\./, // RFC 1918 class A
+  /^172\.(1[6-9]|2[0-9]|3[01])\./, // RFC 1918 class B
+  /^192\.168\./, // RFC 1918 class C
+  /^169\.254\./, // link-local / AWS IMDS
+  /^0\.0\.0\.0/, // unspecified
+  /^localhost$/i,
+  /\.local$/i,
+  /\.internal$/i,
+];
+
+function validateWebhookUrl(url: string): void {
+  const parsed = new URL(url);
+
+  if (process.env.NODE_ENV === "production" && parsed.protocol !== "https:") {
+    throw new Error("Webhook URLs must use HTTPS in production.");
+  }
+
+  const hostname = parsed.hostname;
+  for (const pattern of PRIVATE_HOST_PATTERNS) {
+    if (pattern.test(hostname)) {
+      throw new Error(`Webhook URLs cannot target private hosts: ${hostname}`);
+    }
+  }
+}
+
+/**
+ * Resolve the webhook URL hostname via DNS and verify the resolved IP is not
+ * private. This closes the DNS rebinding gap where a hostname initially
+ * resolves to a public IP but later rebinds to an internal address.
+ */
+async function validateResolvedIp(url: string): Promise<void> {
+  const { lookup } = await import("node:dns/promises");
+  const parsed = new URL(url);
+  const hostname = parsed.hostname.replace(/^\[|\]$/g, "");
+
+  // Skip DNS resolution for raw IP addresses — they are already checked
+  // by validateWebhookUrl via PRIVATE_HOST_PATTERNS.
+  const isIpLiteral = /^[\d.]+$/.test(hostname) || hostname.includes(":");
+  if (isIpLiteral) return;
+
+  try {
+    const { address } = await lookup(hostname);
+    if (isPrivateIp(address)) {
+      throw new Error(
+        `Webhook URL hostname "${hostname}" resolved to private IP ${address}`,
+      );
+    }
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("resolved to private")) {
+      throw err;
+    }
+    throw new Error(`Failed to resolve webhook URL hostname "${hostname}": ${err}`);
+  }
+}
+
+function deliveryBackoffDelayMs(
+  jobAttempt: number,
+  backoff: TaskRetryConfig["backoff"] | undefined,
+): number | undefined {
+  if (!backoff || jobAttempt >= Number.MAX_SAFE_INTEGER) return undefined;
+  if (backoff.type === "exponential") {
+    return backoff.delay * 2 ** (jobAttempt - 1);
+  }
+  return backoff.delay;
+}
+
+class HttpResponseWebhookError extends Error {
+  readonly status: number;
+
+  constructor(status: number) {
+    super(`Webhook delivery failed: HTTP ${status}`);
+    this.name = "HttpResponseWebhookError";
+    this.status = status;
+  }
+}
+
+interface WorkerDeps {
+  repository: WebhooksRepository;
+  fetchImpl?: typeof fetch;
+}
+
+export class WebhookDeliveryWorker {
+  private fetchImpl: typeof fetch;
+
+  constructor(private deps: WorkerDeps) {
+    this.fetchImpl = deps.fetchImpl ?? fetch;
+  }
+
+  async deliver(args: {
+    endpoint: { id: string; url: string; secret: string };
+    eventName: string;
+    payload: unknown;
+    /** Job runner attempt index (1-based). Defaults to 1 for non-job callers (e.g. inline enqueue). */
+    jobAttempt?: number;
+    /** Max attempts for this job; defaults to 1 when unknown so `nextRetryAt` is not set for standalone runs. */
+    jobMaxAttempts?: number;
+    /** Matches task retry backoff so delivery rows align with `commerce_jobs.waitUntil`. */
+    retryBackoff?: TaskRetryConfig["backoff"];
+  }): Promise<void> {
+    const jobAttempt = args.jobAttempt ?? 1;
+    const jobMaxAttempts = args.jobMaxAttempts ?? 1;
+
+    validateWebhookUrl(args.endpoint.url);
+    await validateResolvedIp(args.endpoint.url);
+
+    const signature = signWebhookPayload(args.endpoint.secret, args.payload);
+
+    try {
+      const response = await this.fetchImpl(args.endpoint.url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-commerce-signature": signature,
+          "x-commerce-event": args.eventName,
+        },
+        body: JSON.stringify(args.payload),
+        signal: AbortSignal.timeout(10_000),
+      });
+
+      const delayMs = deliveryBackoffDelayMs(jobAttempt, args.retryBackoff);
+      const willRetryJob = jobAttempt < jobMaxAttempts;
+
+      await this.deps.repository.createDelivery({
+        endpointId: args.endpoint.id,
+        eventName: args.eventName,
+        payload: args.payload,
+        statusCode: response.status,
+        attemptCount: jobAttempt,
+        ...(response.ok ? { deliveredAt: new Date() } : { failedAt: new Date() }),
+        ...(!response.ok && willRetryJob && delayMs !== undefined
+          ? { nextRetryAt: new Date(Date.now() + delayMs) }
+          : {}),
+      });
+
+      if (response.ok) return;
+
+      throw new HttpResponseWebhookError(response.status);
+    } catch (err) {
+      if (err instanceof HttpResponseWebhookError) {
+        throw err;
+      }
+
+      const delayMs = deliveryBackoffDelayMs(jobAttempt, args.retryBackoff);
+      const willRetryJob = jobAttempt < jobMaxAttempts;
+
+      await this.deps.repository.createDelivery({
+        endpointId: args.endpoint.id,
+        eventName: args.eventName,
+        payload: args.payload,
+        attemptCount: jobAttempt,
+        failedAt: new Date(),
+        ...(willRetryJob && delayMs !== undefined
+          ? { nextRetryAt: new Date(Date.now() + delayMs) }
+          : {}),
+      });
+
+      throw err;
+    }
+  }
+}

package/src/runtime/commerce.ts

@@ -0,0 +1,158 @@
+import type { Actor } from "../auth/types.js";
+import type { CommerceConfig } from "../config/types.js";
+import type { Kernel } from "./kernel.js";
+import { createKernel } from "./kernel.js";
+import { ensureDefaultOrg, setBootDefaultOrgId } from "../auth/org.js";
+import { setBootStrictOrgResolution } from "../auth/strict-org-resolution.js";
+import { createAuth, type AuthInstance } from "../auth/setup.js";
+import { createLogger, type Logger } from "./logger.js";
+import { createLocalAPI, type CommerceLocalAPI, type LocalAPIOptions } from "../kernel/local-api.js";
+
+/**
+ * The commerce instance returned by `createCommerce()`.
+ *
+ * This is the headless, framework-agnostic entry point.
+ * No HTTP server, no Hono — just typed services and a local API.
+ *
+ * ## Usage with Next.js App Router:
+ *
+ * ```typescript
+ * // lib/commerce.ts
+ * import { createCommerce } from "@porulle/core";
+ * import config from "../commerce.config.js";
+ *
+ * export const commerce = await createCommerce(config);
+ *
+ * // app/products/page.tsx (Server Component)
+ * import { commerce } from "@/lib/commerce";
+ *
+ * export default async function ProductsPage() {
+ *   const products = await commerce.api.catalog.list({ limit: 20 });
+ *   if (!products.ok) return <div>Error</div>;
+ *   return <ProductGrid items={products.value.items} />;
+ * }
+ * ```
+ *
+ * ## Usage with TanStack Start:
+ *
+ * ```typescript
+ * // app/routes/products.tsx
+ * import { createServerFn } from "@tanstack/start";
+ * import { commerce } from "../lib/commerce.js";
+ *
+ * const getProducts = createServerFn("GET", async () => {
+ *   return commerce.api.catalog.list({ limit: 20 });
+ * });
+ * ```
+ *
+ * ## Usage with SvelteKit:
+ *
+ * ```typescript
+ * // src/lib/server/commerce.ts
+ * import { createCommerce } from "@porulle/core";
+ * import config from "./commerce.config.js";
+ * export const commerce = await createCommerce(config);
+ *
+ * // src/routes/products/+page.server.ts
+ * import { commerce } from "$lib/server/commerce";
+ * export async function load() {
+ *   const products = await commerce.api.catalog.list({ limit: 20 });
+ *   return { products: products.ok ? products.value : { items: [] } };
+ * }
+ * ```
+ */
+export interface CommerceInstance {
+  /** Proxy-based local API — auto-injects actor/tx to every service call */
+  api: CommerceLocalAPI;
+
+  /** Raw kernel for advanced usage (hooks, database, config) */
+  kernel: Kernel;
+
+  /** Drizzle database instance for direct queries */
+  db: unknown;
+
+  /** Auth instance (Better Auth) for session management */
+  auth: AuthInstance;
+
+  /** Logger */
+  logger: Logger;
+
+  /**
+   * Create a scoped API for a specific user/actor.
+   * Use this in authenticated routes to scope data access.
+   *
+   * ```typescript
+   * // In a Next.js server action:
+   * const userApi = commerce.withActor({
+   *   type: "user", userId: session.userId, ...
+   * });
+   * const orders = await userApi.orders.list({ limit: 10 });
+   * // Only returns orders for this user's org
+   * ```
+   */
+  withActor(actor: Actor): CommerceLocalAPI;
+
+  /**
+   * Create a scoped API within a database transaction.
+   *
+   * ```typescript
+   * await commerce.kernel.database.transaction(async (tx) => {
+   *   const txApi = commerce.withTransaction(tx, actor);
+   *   await txApi.inventory.adjust({ entityId, adjustment: -1, reason: "sold" });
+   *   await txApi.orders.create({ ... });
+   * });
+   * ```
+   */
+  withTransaction(tx: unknown, actor?: Actor | null): CommerceLocalAPI;
+}
+
+/**
+ * Create a headless commerce instance.
+ *
+ * This is the primary entry point for using UnifiedCommerce without an HTTP server.
+ * It initializes the kernel, database, auth, and returns a local API that works
+ * exactly like the REST API but without HTTP overhead.
+ *
+ * The Hono server (`createServer`) is optional — use it only when you need
+ * a standalone HTTP API. For Next.js, TanStack Start, SvelteKit, Nuxt, etc.,
+ * use `createCommerce()` directly.
+ */
+export async function createCommerce(
+  config: CommerceConfig,
+): Promise<CommerceInstance> {
+  const kernel = createKernel(config);
+
+  setBootStrictOrgResolution(config.auth?.strictOrgResolution === true);
+
+  // Register the config-driven org ID so resolveOrgId() can use it
+  // without requiring every service to have config access.
+  if (config.auth?.defaultOrganizationId) {
+    setBootDefaultOrgId(config.auth.defaultOrganizationId);
+  } else {
+    // Legacy fallback: auto-create org_default for deployments
+    // that haven't migrated to seed-based org creation yet.
+    await ensureDefaultOrg(kernel.database.db, config.storeName);
+  }
+
+  const auth = createAuth(kernel.database, config);
+  const logger = createLogger(config);
+
+  // Default API: no actor (public access), no transaction
+  const api = createLocalAPI(kernel);
+
+  return {
+    api,
+    kernel,
+    db: kernel.database.db,
+    auth,
+    logger,
+
+    withActor(actor: Actor): CommerceLocalAPI {
+      return createLocalAPI(kernel, { actor });
+    },
+
+    withTransaction(tx: unknown, actor?: Actor | null): CommerceLocalAPI {
+      return createLocalAPI(kernel, { actor: actor ?? null, tx });
+    },
+  };
+}

package/src/runtime/kernel-modules.ts

@@ -0,0 +1,66 @@
+import type { AppModule } from "../kernel/module/index.js";
+import { topoSortModules } from "../kernel/module/index.js";
+import { auditModule } from "../modules/audit/index.js";
+import { analyticsModule } from "../modules/analytics/module.js";
+import { cartModule } from "../modules/cart/module.js";
+import { catalogModule } from "../modules/catalog/module.js";
+import { customersModule } from "../modules/customers/index.js";
+import { fulfillmentModule } from "../modules/fulfillment/module.js";
+import { inventoryModule } from "../modules/inventory/module.js";
+import { mediaModule } from "../modules/media/index.js";
+import { ordersModule } from "../modules/orders/module.js";
+import { organizationModule } from "../modules/organization/index.js";
+import { paymentsModule } from "../modules/payments/module.js";
+import { pricingModule } from "../modules/pricing/index.js";
+import { promotionsModule } from "../modules/promotions/module.js";
+import { searchModule } from "../modules/search/module.js";
+import { shippingModule } from "../modules/shipping/module.js";
+import { taxModule } from "../modules/tax/module.js";
+import { webhooksModule } from "../modules/webhooks/index.js";
+
+export const KERNEL_ALL_MODULES = {
+  audit: auditModule,
+  webhooks: webhooksModule,
+  media: mediaModule,
+  organization: organizationModule,
+  customers: customersModule,
+  pricing: pricingModule,
+  catalog: catalogModule,
+  inventory: inventoryModule,
+  cart: cartModule,
+  orders: ordersModule,
+  fulfillment: fulfillmentModule,
+  promotions: promotionsModule,
+  search: searchModule,
+  shipping: shippingModule,
+  tax: taxModule,
+  payments: paymentsModule,
+  analytics: analyticsModule,
+} as const;
+
+/** Strip symmetric/lazy manifest edges so topo sort reflects constructor-safe ordering. */
+export function kernelModulesForTopoSort(): Record<string, AppModule> {
+  return {
+    ...KERNEL_ALL_MODULES,
+    catalog: { ...catalogModule, dependencies: [] },
+    promotions: {
+      ...promotionsModule,
+      dependencies: ["catalog"],
+    },
+    orders: {
+      ...ordersModule,
+      dependencies: [
+        "cart",
+        "inventory",
+        "payments",
+        "pricing",
+        "fulfillment",
+        "tax",
+      ],
+    },
+  } as unknown as Record<string, AppModule>;
+}
+
+export function kernelModuleInstantiationOrder(): readonly string[] {
+  return topoSortModules(kernelModulesForTopoSort());
+}