@unifiedcommerce/core 0.0.1

package/src/modules/webhooks/worker.ts

@@ -0,0 +1,134 @@
+import { signWebhookPayload } from "./signing";
+import { isPrivateIp } from "./ssrf-guard";
+import type { WebhooksRepository } from "./repository";
+
+/**
+ * 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}`);
+  }
+}
+
+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;
+  }): Promise<void> {
+    // SSRF prevention: validate URL string patterns + resolved DNS IP
+    validateWebhookUrl(args.endpoint.url);
+    await validateResolvedIp(args.endpoint.url);
+
+    let attempt = 0;
+    const maxAttempts = 3;
+
+    while (attempt < maxAttempts) {
+      attempt += 1;
+      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),
+        });
+
+        await this.deps.repository.createDelivery({
+          endpointId: args.endpoint.id,
+          eventName: args.eventName,
+          payload: args.payload,
+          statusCode: response.status,
+          attemptCount: attempt,
+          ...(response.ok ? { deliveredAt: new Date() } : {}),
+          ...(!response.ok ? { failedAt: new Date() } : {}),
+          ...(!response.ok && attempt < maxAttempts
+            ? { nextRetryAt: new Date(Date.now() + 2 ** attempt * 1000) }
+            : {}),
+        });
+
+        if (response.ok) return;
+      } catch {
+        await this.deps.repository.createDelivery({
+          endpointId: args.endpoint.id,
+          eventName: args.eventName,
+          payload: args.payload,
+          attemptCount: attempt,
+          failedAt: new Date(),
+          ...(attempt < maxAttempts
+            ? { nextRetryAt: new Date(Date.now() + 2 ** attempt * 1000) }
+            : {}),
+        });
+      }
+    }
+  }
+}

package/src/runtime/commerce.ts

@@ -0,0 +1,145 @@
+import type { Actor } from "../auth/types";
+import type { CommerceConfig } from "../config/types";
+import type { Kernel } from "./kernel";
+import { createKernel } from "./kernel";
+import { ensureDefaultOrg } from "../auth/org";
+import { createAuth, type AuthInstance } from "../auth/setup";
+import { createLogger, type Logger } from "./logger";
+import { createLocalAPI, type CommerceLocalAPI, type LocalAPIOptions } from "../kernel/local-api";
+
+/**
+ * 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 "@unifiedcommerce/core";
+ * import config from "../commerce.config";
+ *
+ * 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";
+ *
+ * const getProducts = createServerFn("GET", async () => {
+ *   return commerce.api.catalog.list({ limit: 20 });
+ * });
+ * ```
+ *
+ * ## Usage with SvelteKit:
+ *
+ * ```typescript
+ * // src/lib/server/commerce.ts
+ * import { createCommerce } from "@unifiedcommerce/core";
+ * import config from "./commerce.config";
+ * 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);
+  await ensureDefaultOrg(kernel.database.db);
+  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.ts

@@ -0,0 +1,419 @@
+import type {
+  CommerceConfig,
+  MCPResource,
+  MCPTool,
+} from "../config/types";
+import { HookRegistry, type HookHandler } from "../kernel/hooks/registry";
+import {
+  createDatabaseConnection,
+  type DatabaseAdapter,
+} from "../kernel/database/adapter";
+import type { PluginDb } from "../kernel/database/plugin-types";
+
+import { CatalogServiceImpl } from "../modules/catalog/service";
+import { CatalogRepository } from "../modules/catalog/repository";
+import { InventoryRepository } from "../modules/inventory/repository";
+import { CartRepository } from "../modules/cart/repository";
+import { OrdersRepository } from "../modules/orders/repository";
+import { CustomersRepository } from "../modules/customers/repository";
+import { PricingRepository } from "../modules/pricing/repository";
+import { PromotionsRepository } from "../modules/promotions/repository";
+import { FulfillmentRepository } from "../modules/fulfillment/repository";
+import { WebhooksRepository } from "../modules/webhooks/repository";
+import { MediaRepository } from "../modules/media/repository";
+import type { DrizzleDatabase } from "../kernel/database/drizzle-db";
+import { InventoryService } from "../modules/inventory/service";
+import { MediaService } from "../modules/media/service";
+import { CartService } from "../modules/cart/service";
+import { OrderService } from "../modules/orders/service";
+import { PaymentsService } from "../modules/payments/service";
+import { FulfillmentService } from "../modules/fulfillment/service";
+import { CustomerService } from "../modules/customers/service";
+import { WebhookService } from "../modules/webhooks/service";
+import { AnalyticsService } from "../modules/analytics/service";
+import { DrizzleAnalyticsAdapter } from "../modules/analytics/drizzle-adapter";
+import { BUILTIN_ANALYTICS_MODELS } from "../modules/analytics/models";
+import { PricingService } from "../modules/pricing/service";
+import { PromotionService } from "../modules/promotions/service";
+import { TaxService } from "../modules/tax/service";
+import { ShippingService } from "../modules/shipping/service";
+import { SearchService } from "../modules/search/service";
+import { WebhookDeliveryWorker } from "../modules/webhooks/worker";
+import {
+  createAuditService,
+  type AuditService,
+} from "../modules/audit/service";
+import { OrganizationService } from "../modules/organization/service";
+import { createLogger } from "../utils/logger";
+import { withTiming } from "../kernel/service-timing";
+import { extendOrderStateMachine } from "../kernel/state-machine/machine";
+import { DEFAULT_ORG_ID } from "../auth/org";
+import { deliverWebhooks } from "../modules/webhooks/hook";
+// Analytics event recording hooks removed (RFC-006): source tables ARE the events.
+// The DrizzleAnalyticsAdapter queries orders/inventory directly via SQL.
+import { syncToSearchIndex } from "../modules/search/hooks";
+import { auditHooks } from "../modules/audit/hooks";
+import { sendOrderStatusEmail } from "../hooks/order-emails";
+import { DrizzleJobsAdapter } from "../kernel/jobs/drizzle-adapter";
+
+export interface WebhookDeliveryPayload {
+  endpoint: { id: string; url: string; secret: string };
+  eventName: string;
+  payload: unknown;
+}
+
+export interface Kernel {
+  config: CommerceConfig;
+  hooks: HookRegistry;
+  database: DatabaseAdapter;
+  services: {
+    catalog: CatalogServiceImpl;
+    inventory: InventoryService;
+    media: MediaService;
+    cart: CartService;
+    orders: OrderService;
+    payments: PaymentsService;
+    fulfillment: FulfillmentService;
+    customers: CustomerService;
+    webhooks: WebhookService & {
+      enqueueDelivery(payload: WebhookDeliveryPayload): Promise<void>;
+    };
+    analytics: AnalyticsService;
+    pricing: PricingService;
+    promotions: PromotionService;
+    tax: TaxService;
+    shipping: ShippingService;
+    search: SearchService;
+    audit: AuditService;
+    email: CommerceConfig["email"];
+    organization: OrganizationService;
+  };
+  mcpTools: MCPTool[];
+  mcpResources: MCPResource[];
+  logger: ReturnType<typeof createLogger>;
+  getMCPActor(): {
+    type: "api_key";
+    userId: string;
+    email: null;
+    name: string;
+    vendorId: null;
+    organizationId: string;
+    role: string;
+    permissions: string[];
+  };
+}
+
+const requiredServiceKeys = [
+  "catalog",
+  "inventory",
+  "media",
+  "cart",
+  "orders",
+  "payments",
+  "fulfillment",
+  "customers",
+  "webhooks",
+  "analytics",
+  "pricing",
+  "promotions",
+  "tax",
+  "shipping",
+  "search",
+  "audit",
+] as const satisfies Array<keyof Kernel["services"]>;
+
+function assertServicesReady(
+  services: Partial<Kernel["services"]>,
+): asserts services is Kernel["services"] {
+  for (const key of requiredServiceKeys) {
+    if (services[key] === undefined) {
+      throw new Error(`Kernel service "${String(key)}" was not initialized.`);
+    }
+  }
+}
+
+function registerConfiguredHooks(
+  config: CommerceConfig,
+  hooks: HookRegistry,
+): void {
+  for (const [entityType, entityConfig] of Object.entries(
+    config.entities ?? {},
+  )) {
+    const entityHooks = entityConfig.hooks ?? {};
+    for (const [hookName, handlers] of Object.entries(entityHooks)) {
+      hooks.registerConfigHooks(
+        `catalog.${entityType}.${hookName}`,
+        handlers ?? [],
+      );
+    }
+  }
+
+  for (const [moduleName, moduleConfig] of [
+    ["cart", config.cart],
+    ["checkout", config.checkout],
+    ["orders", config.orders],
+    ["inventory", config.inventory],
+  ] as const) {
+    const hooksObject = moduleConfig?.hooks;
+    if (!hooksObject) continue;
+    for (const [hookName, handlers] of Object.entries(hooksObject)) {
+      const normalizedHandlers: HookHandler[] = Array.isArray(handlers)
+        ? (handlers as unknown as HookHandler[])
+        : [];
+      hooks.registerConfigHooks(
+        `${moduleName}.${hookName}`,
+        normalizedHandlers,
+      );
+    }
+  }
+
+  // Webhook delivery (async via job queue) — 14 event types
+  hooks.append("orders.afterCreate", deliverWebhooks);
+  hooks.append("orders.afterStatusChange", deliverWebhooks);
+  hooks.append("orders.afterStatusChange", sendOrderStatusEmail as (...args: unknown[]) => unknown);
+  hooks.append("catalog.afterCreate", deliverWebhooks);
+  hooks.append("catalog.afterUpdate", deliverWebhooks);
+  hooks.append("catalog.afterDelete", deliverWebhooks);
+  hooks.append("inventory.afterAdjust", deliverWebhooks);
+  hooks.append("customers.afterCreate", deliverWebhooks);
+  hooks.append("customers.afterUpdate", deliverWebhooks);
+  hooks.append("pricing.afterCreate", deliverWebhooks);
+  hooks.append("pricing.afterUpdate", deliverWebhooks);
+  hooks.append("promotions.afterCreate", deliverWebhooks);
+  hooks.append("promotions.afterUpdate", deliverWebhooks);
+  hooks.append("fulfillment.afterCreate", deliverWebhooks);
+  hooks.append("cart.afterAddItem", deliverWebhooks);
+
+  // Analytics: no event recording hooks needed (RFC-006).
+  // The DrizzleAnalyticsAdapter queries source tables directly via SQL.
+
+  // Search index sync
+  hooks.append("catalog.afterCreate", syncToSearchIndex);
+  hooks.append("catalog.afterUpdate", syncToSearchIndex);
+
+  // Auto-audit — records every create/update/delete across all modules
+  for (const [key, handler] of Object.entries(auditHooks)) {
+    hooks.append(key, handler);
+  }
+}
+
+export function createKernel(config: CommerceConfig): Kernel {
+  const hooks = new HookRegistry();
+  const logger = createLogger("kernel");
+  hooks.setLogger(logger as unknown as { error: (obj: Record<string, unknown>, msg: string) => void });
+
+  if (!config.storage) {
+    throw new Error(
+      "Storage adapter is required. Configure `storage` in defineConfig (for example: localStorageAdapter for development, or s3StorageAdapter/r2StorageAdapter for object storage).",
+    );
+  }
+
+  const database = createDatabaseConnection({
+    adapter: config.databaseAdapter ?? {
+      provider: config.database.provider,
+      db: {},
+      async transaction<T>(fn: (tx: unknown) => Promise<T>): Promise<T> {
+        return fn({});
+      },
+    },
+  });
+  const mcpTools: MCPTool[] = [];
+  const mcpResources: MCPResource[] = [];
+
+  const services: Partial<Kernel["services"]> = {
+    email: config.email,
+    organization: new OrganizationService(database.db),
+  };
+
+  const serviceContainer = services as Record<string, unknown>;
+
+  // Expose database on service container so plugin hooks can access it
+  serviceContainer.database = database;
+
+  const db = database.db as DrizzleDatabase;
+
+  // Expose jobs adapter on service container so plugins can enqueue background work
+  const jobsAdapter = new DrizzleJobsAdapter(db, new Map());
+  serviceContainer.jobs = jobsAdapter;
+
+  const pricingRepository = new PricingRepository(db);
+  const promotionsRepository = new PromotionsRepository(db);
+
+  services.tax = new TaxService({ adapter: config.tax?.adapter });
+  services.payments = new PaymentsService(config.payments);
+
+  const customersRepository = new CustomersRepository(db);
+  services.customers = new CustomerService({
+    repository: customersRepository,
+  });
+
+  const webhooksRepository = new WebhooksRepository(db);
+  const webhookWorker = new WebhookDeliveryWorker({
+    repository: webhooksRepository,
+  });
+  services.webhooks = Object.assign(
+    new WebhookService({
+      repository: webhooksRepository,
+    }),
+    {
+      async enqueueDelivery(payload: WebhookDeliveryPayload) {
+        await webhookWorker.deliver(payload);
+      },
+    },
+  );
+
+  const inventoryRepository = new InventoryRepository(db);
+  services.inventory = new InventoryService({
+    repository: inventoryRepository,
+    hooks,
+    config,
+    services: serviceContainer,
+    database,
+  });
+
+  const catalogRepository = new CatalogRepository(db);
+  services.catalog = new CatalogServiceImpl({
+    repository: catalogRepository,
+    hooks,
+    config,
+    services: serviceContainer,
+  });
+
+  services.search = new SearchService({
+    catalogRepository: catalogRepository,
+    ...(config.search?.adapter ? { adapter: config.search.adapter } : {}),
+    ...(config.search?.defaultFacets
+      ? { defaultFacets: config.search.defaultFacets }
+      : {}),
+  });
+
+  const cartRepository = new CartRepository(db);
+  services.cart = new CartService({
+    repository: cartRepository,
+    catalogRepository: catalogRepository,
+    hooks,
+    config,
+    services: serviceContainer,
+  });
+
+  const ordersRepository = new OrdersRepository(db);
+  services.orders = new OrderService({
+    repository: ordersRepository,
+    hooks,
+    services: serviceContainer,
+    kernel: { database: database as { db: PluginDb } },
+    ...(config.orders?.customTransitions
+      ? { stateMachine: extendOrderStateMachine(config.orders.customTransitions) }
+      : {}),
+  });
+
+  const fulfillmentRepository = new FulfillmentRepository(db);
+  services.fulfillment = new FulfillmentService({
+    repository: fulfillmentRepository,
+    ordersRepository: ordersRepository,
+    inventoryService: services.inventory,
+  });
+
+  services.pricing = new PricingService({
+    repository: pricingRepository,
+    catalogRepository: catalogRepository,
+  });
+
+  services.promotions = new PromotionService({
+    repository: promotionsRepository,
+    catalogRepository: catalogRepository,
+    ordersRepository: ordersRepository,
+  });
+
+  // AnalyticsService — always uses DrizzleAnalyticsAdapter (direct SQL).
+  // Plugins add their own models via the analyticsModels manifest slot.
+  const analyticsAdapter = new DrizzleAnalyticsAdapter(db);
+  for (const model of BUILTIN_ANALYTICS_MODELS) {
+    analyticsAdapter.registerModel(model);
+  }
+  services.analytics = new AnalyticsService({
+    adapter: analyticsAdapter,
+    config,
+  });
+
+  services.shipping = new ShippingService({
+    config,
+    catalogRepository: catalogRepository,
+  });
+
+  const mediaRepository = new MediaRepository(db);
+  services.media = new MediaService({
+    repository: mediaRepository,
+    catalogRepository: catalogRepository,
+    storage: config.storage,
+  });
+
+  services.audit = createAuditService(db);
+
+  assertServicesReady(services);
+
+  // Service method observability: wrap each service in a timing proxy
+  // that logs slow calls (>100ms) and failed calls with duration.
+  // Disabled in test environment to avoid noisy logs.
+  if (process.env.NODE_ENV !== "test") {
+    const timedLogger = logger as unknown as { info: (o: Record<string, unknown>, m: string) => void; error: (o: Record<string, unknown>, m: string) => void };
+    const serviceKeys = Object.keys(services) as Array<keyof typeof services>;
+    for (const key of serviceKeys) {
+      const svc = services[key];
+      if (svc && typeof svc === "object" && key !== "email") {
+        (services as Record<string, unknown>)[key] = withTiming(
+          svc as object,
+          key,
+          timedLogger,
+        );
+      }
+    }
+  }
+
+  registerConfiguredHooks(config, hooks);
+
+  const kernel: Kernel = {
+    config,
+    hooks,
+    database,
+    services,
+    mcpTools,
+    mcpResources,
+    logger,
+    getMCPActor() {
+      return {
+        type: "api_key",
+        userId: "mcp-agent",
+        email: null,
+        name: "MCP Agent",
+        vendorId: null,
+        organizationId: DEFAULT_ORG_ID,
+        role: "ai_agent",
+        permissions: config.auth?.roles?.ai_agent?.permissions ?? [
+          "catalog:read",
+          "catalog:create",
+          "inventory:read",
+          "inventory:adjust",
+          "orders:read",
+          "cart:create",
+          "cart:update",
+          "mcp:access",
+        ],
+      };
+    },
+  };
+
+  // Register plugin hooks from config.hooks flat map
+  for (const [key, handlers] of Object.entries(config.hooks ?? {})) {
+    for (const handler of handlers) {
+      hooks.append(key, handler as HookHandler);
+    }
+  }
+
+  // Register plugin analytics models from config.analytics.models
+  for (const model of config.analytics?.models ?? []) {
+    services.analytics.registerModel(model);
+  }
+
+  return kernel;
+}