@porulle/core 0.6.0 → 0.7.0

package/dist/runtime/server.js

@@ -1,11 +1,13 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import { cors } from "hono/cors";
 import { csrf } from "hono/csrf";
+import { HTTPException } from "hono/http-exception";
 import { bodyLimit } from "hono/body-limit";
 import { rateLimiter } from "hono-rate-limiter";
 import { createHash } from "node:crypto";
 import { createClientIpResolver } from "./client-ip.js";
 import { authMiddleware } from "../auth/middleware.js";
+import { CommerceCsrfError } from "../kernel/errors.js";
 import { createRestRoutes } from "../interfaces/rest/index.js";
 import { createCustomerPortalRoutes } from "../interfaces/rest/customer-portal.js";
 import { createCommerce } from "./commerce.js";
@@ -138,11 +140,41 @@ export async function createServer(config) {
         maxAge: 86400,
     }));
     // ─── CSRF Protection (F14) ──────────────────────────────────────────
-    app.use("/api/*", csrf({
+    // CSRF defends cookie/session auth, where the browser attaches the credential
+    // ambiently. API-key (x-api-key) and bearer-token requests carry an explicit,
+    // non-ambient credential and are not CSRF-attackable, so the guard is skipped
+    // for them — otherwise a bodyless server-to-server POST (no Origin, no JSON
+    // content-type, e.g. /publish or /archive from the SDK) trips CSRF and 403s
+    // for no security benefit.
+    const csrfGuard = csrf({
         origin: trustedOrigins.length > 0
             ? trustedOrigins
             : (process.env.NODE_ENV === "production" ? [] : ["http://localhost:*"]),
-    }));
+    });
+    app.use("/api/*", async (c, next) => {
+        const authenticatedByKey = !!c.req.header("x-api-key") ||
+            /^Bearer\s+/i.test(c.req.header("authorization") ?? "");
+        if (authenticatedByKey)
+            return next();
+        // Run only the CSRF origin check here; invoke the real downstream afterwards
+        // so a genuine 403 from a route handler can't be misattributed to CSRF.
+        let passedCsrf = false;
+        try {
+            await csrfGuard(c, async () => {
+                passedCsrf = true;
+            });
+        }
+        catch (err) {
+            if (err instanceof HTTPException && err.status === 403) {
+                throw new CommerceCsrfError("Origin check failed: the request Origin is not in the trusted origins allowlist. " +
+                    "Browser clients must send a trusted Origin; server-to-server callers should authenticate with an API key (x-api-key).");
+            }
+            throw err;
+        }
+        if (!passedCsrf)
+            return;
+        return next();
+    });
     // ─── Body Size Limit (F6) ──────────────────────────────────────────
     // Media uploads (phone photos are 3–8MB) get their own larger limit and are
     // exempt from the global 1MB limit. Everything else stays at 1MB.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/interfaces/rest/routes/orders.ts

@@ -1,7 +1,8 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import type { Kernel } from "../../../runtime/kernel.js";
-import { changeOrderStatusRoute, listOrdersRoute, orderLookupRoute, getOrderRoute, getOrderFulfillmentsRoute } from "../schemas/orders.js";
+import { changeOrderStatusRoute, listOrdersRoute, orderLookupRoute, getOrderRoute, getOrderFulfillmentsRoute, createOrderRoute, refundOrderRoute, captureOrderRoute } from "../schemas/orders.js";
 import { type AppEnv, isUUID, mapErrorToResponse, mapErrorToStatus, parsePagination } from "../utils.js";
+import type { CreateOrderInput } from "../../../modules/orders/service.js";
 
 export function orderRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
@@ -59,6 +60,40 @@ export function orderRoutes(kernel: Kernel) {
     return c.json({ data: result.value });
   });
 
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(createOrderRoute, async (c) => {
+    const body = c.req.valid("json") as CreateOrderInput;
+    const result = await kernel.services.orders.create(body, c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value }, 201);
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(refundOrderRoute, async (c) => {
+    const body = c.req.valid("json") as { amount?: number; reason?: string } | undefined;
+    const result = await kernel.services.orders.refund(
+      c.req.param("id"),
+      c.get("actor"),
+      body?.reason ?? "refunded",
+      undefined,
+      body?.amount !== undefined ? { amount: body.amount } : undefined,
+    );
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(captureOrderRoute, async (c) => {
+    const body = c.req.valid("json") as { amount?: number } | undefined;
+    const result = await kernel.services.orders.capture(
+      c.req.param("id"),
+      c.get("actor"),
+      body?.amount !== undefined ? { amount: body.amount } : undefined,
+    );
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
   // @ts-expect-error -- openapi() enforces strict response typing but our handler
   // returns union responses (200 | 400 | 404). The route definition documents the
   // contract; the handler returns dynamic status.

package/src/interfaces/rest/schemas/orders.ts

@@ -12,6 +12,45 @@ export const ChangeOrderStatusBodySchema = z.object({
   reason: z.string().optional().openapi({ example: "Payment verified" }),
 }).openapi("ChangeOrderStatusRequest");
 
+export const RefundOrderBodySchema = z.object({
+  // Minor units (e.g. cents). Omit to refund the full captured amount.
+  amount: z.number().int().positive().optional().openapi({ example: 1575 }),
+  reason: z.string().optional().openapi({ example: "Customer returned item" }),
+}).openapi("RefundOrderRequest");
+
+export const CaptureOrderBodySchema = z.object({
+  // Minor units. Omit to capture the full authorized amount.
+  amount: z.number().int().positive().optional().openapi({ example: 1575 }),
+}).openapi("CaptureOrderRequest");
+
+const CreateOrderLineItemSchema = z.object({
+  entityId: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+  entityType: z.string().min(1).openapi({ example: "product" }),
+  variantId: z.uuid().optional(),
+  sku: z.string().optional(),
+  title: z.string().min(1).openapi({ example: "Ceylon Black Tea 250g" }),
+  quantity: z.number().int().positive().openapi({ example: 2 }),
+  unitPrice: z.number().int().nonnegative().openapi({ example: 1250 }),
+  totalPrice: z.number().int().nonnegative().openapi({ example: 2500 }),
+  taxAmount: z.number().int().nonnegative().optional(),
+  discountAmount: z.number().int().nonnegative().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+export const CreateOrderBodySchema = z.object({
+  customerId: z.uuid().optional(),
+  currency: z.string().min(3).max(3).openapi({ example: "USD" }),
+  subtotal: z.number().int().nonnegative().openapi({ example: 2500 }),
+  taxTotal: z.number().int().nonnegative().openapi({ example: 200 }),
+  shippingTotal: z.number().int().nonnegative().openapi({ example: 500 }),
+  discountTotal: z.number().int().nonnegative().optional().openapi({ example: 0 }),
+  grandTotal: z.number().int().nonnegative().openapi({ example: 3200 }),
+  paymentIntentId: z.string().optional(),
+  paymentMethodId: z.string().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  lineItems: z.array(CreateOrderLineItemSchema).min(1),
+}).openapi("CreateOrderRequest");
+
 // ─── Response Schemas ───────────────────────────────────────────────────────
 
 export const OrderDataResponseSchema = OrderResponse;
@@ -101,6 +140,71 @@ export const getOrderFulfillmentsRoute = createRoute({
   },
 });
 
+export const createOrderRoute = createRoute({
+  method: "post",
+  path: "/",
+  tags: ["Orders"],
+  summary: "Create a draft / manual order",
+  description: "Operator-created order (phone / POS / manual) with line items and totals, optionally without immediate payment.",
+  request: {
+    body: {
+      content: { "application/json": { schema: CreateOrderBodySchema } },
+      required: true,
+    },
+  },
+  responses: {
+    201: {
+      content: { "application/json": { schema: OrderDataResponseSchema } },
+      description: "Order created.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const refundOrderRoute = createRoute({
+  method: "post",
+  path: "/{id}/refund",
+  tags: ["Orders"],
+  summary: "Refund an order's payment",
+  description: "Refunds the captured payment via the payment adapter and transitions the order to `refunded`. Omit `amount` for a full refund.",
+  request: {
+    params: OrderIdParam,
+    body: {
+      content: { "application/json": { schema: RefundOrderBodySchema } },
+      required: false,
+    },
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: OrderDataResponseSchema } },
+      description: "Order refunded.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const captureOrderRoute = createRoute({
+  method: "post",
+  path: "/{id}/capture",
+  tags: ["Orders"],
+  summary: "Capture an authorized payment",
+  description: "Captures the authorized payment via the payment adapter and records `amountCaptured`. Omit `amount` for a full capture.",
+  request: {
+    params: OrderIdParam,
+    body: {
+      content: { "application/json": { schema: CaptureOrderBodySchema } },
+      required: false,
+    },
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: OrderDataResponseSchema } },
+      description: "Payment captured.",
+    },
+    ...errorResponses,
+  },
+});
+
 export const changeOrderStatusRoute = createRoute({
   method: "patch",
   path: "/{id}/status",

package/src/kernel/error-mapper.ts

@@ -7,6 +7,7 @@ const statusByCode: Record<string, ContentfulStatusCode> = {
   NOT_FOUND: 404,
   VALIDATION_FAILED: 422,
   FORBIDDEN: 403,
+  CSRF_ORIGIN_REJECTED: 403,
   CONFLICT: 409,
   INVALID_TRANSITION: 422,
   ORG_RESOLUTION_FAILED: 503,

package/src/kernel/errors.ts

@@ -43,6 +43,17 @@ export class CommerceForbiddenError extends Error implements CommerceError {
   }
 }
 
+export class CommerceCsrfError extends Error implements CommerceError {
+  code = "CSRF_ORIGIN_REJECTED" as const;
+  constructor(
+    message: string,
+    public details?: unknown,
+  ) {
+    super(message);
+    this.name = "CommerceCsrfError";
+  }
+}
+
 export class CommerceConflictError extends Error implements CommerceError {
   code = "CONFLICT" as const;
   constructor(

package/src/modules/catalog/entity-service.ts

@@ -181,13 +181,22 @@ export class EntityService {
     }
     if (options?.includeCategories) hydrated.categories = await this.repo.findEntityCategories(entity.id, ctx);
     if (options?.includeBrands) hydrated.brands = await this.repo.findEntityBrands(entity.id, ctx);
-    if (options?.includeMedia) hydrated.media = [];
+    if (options?.includeMedia) {
+      const mediaService = this.deps.services.media as {
+        listEntityMedia?: (
+          entityId: string,
+          opts?: { orgId?: string },
+        ) => Promise<{ ok: boolean; value?: CatalogEntityHydrated["media"] }>;
+      } | undefined;
+      const mediaResult = await mediaService?.listEntityMedia?.(entity.id, { orgId: entity.organizationId });
+      hydrated.media = mediaResult?.ok && mediaResult.value ? mediaResult.value : [];
+    }
     if (options?.includePricing) {
       try {
-        const pricingService = this.deps.services.pricing as { listPrices: (filter: { entityId: string }) => Promise<{ ok: boolean; value?: { prices: Array<{ currency: string; amount: number; compareAtAmount?: number | null }> } }> };
+        const pricingService = this.deps.services.pricing as { listPrices: (filter: { entityId: string }) => Promise<{ ok: boolean; value?: { prices: Array<{ id: string; currency: string; amount: number; compareAtAmount?: number | null; createdAt: Date }> } }> };
         const priceResult = await pricingService.listPrices({ entityId: entity.id });
         if (priceResult.ok && priceResult.value) {
-          hydrated.pricing = priceResult.value.prices.map((p) => ({ currency: p.currency, amount: p.amount, compareAtAmount: p.compareAtAmount ?? null }));
+          hydrated.pricing = priceResult.value.prices.map((p) => ({ id: p.id, currency: p.currency, amount: p.amount, compareAtAmount: p.compareAtAmount ?? null, createdAt: p.createdAt }));
         }
       } catch {}
     }
@@ -435,6 +444,21 @@ export class EntityService {
 
   async generateVariants(entityId: string, strategy: VariantGenerationStrategy, actor: Actor | null, ctx?: TxContext): Promise<Result<Variant[]>> {
     assertPermission(actor, "catalog:update");
+    // Guard the strategy: a missing/malformed body (e.g. a bodyless SDK call that
+    // skips JSON validation) must be a 422, not a 500 from dereferencing an
+    // undefined strategy.
+    const mode = (strategy as { mode?: unknown } | null | undefined)?.mode;
+    if (mode !== "all" && mode !== "manual" && mode !== "matrix") {
+      return Err(new CommerceValidationError(
+        'A variant generation strategy is required: { "mode": "all" } | { "mode": "manual", "combinations": [...] } | { "mode": "matrix", "matrix": { "include"?, "exclude"? } }.',
+      ));
+    }
+    if (strategy.mode === "manual" && !Array.isArray(strategy.combinations)) {
+      return Err(new CommerceValidationError('strategy.combinations (string[][]) is required for mode "manual".'));
+    }
+    if (strategy.mode === "matrix" && (!strategy.matrix || typeof strategy.matrix !== "object")) {
+      return Err(new CommerceValidationError('strategy.matrix is required for mode "matrix".'));
+    }
     const entity = await this.repo.findEntityById(entityId, ctx);
     if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
     const entityOptionTypes = await this.repo.findOptionTypesByEntityId(entityId, ctx);

package/src/modules/catalog/schemas.ts

@@ -71,7 +71,21 @@ export const CreateVariantBodySchema = z.object({
   price: z.number().optional().openapi({ example: 34.99 }),
 }).openapi("CreateVariantBody");
 
-export const GenerateVariantsBodySchema = z.object({}).passthrough().openapi("GenerateVariantsBody");
+const VariantMatrixRuleSchema = z.object({
+  include: z.array(z.array(z.string())).optional().openapi({ example: [["red", "small"]] }),
+  exclude: z.array(z.array(z.string())).optional().openapi({ example: [["red", "large"]] }),
+});
+
+export const GenerateVariantsBodySchema = z
+  .discriminatedUnion("mode", [
+    z.object({ mode: z.literal("all") }),
+    z.object({
+      mode: z.literal("manual"),
+      combinations: z.array(z.array(z.string())).openapi({ example: [["red", "small"]] }),
+    }),
+    z.object({ mode: z.literal("matrix"), matrix: VariantMatrixRuleSchema }),
+  ])
+  .openapi("GenerateVariantsBody");
 
 // ─── Derived Input Types ─────────────────────────────────────────────────────
 

package/src/modules/catalog/service.ts

@@ -105,8 +105,8 @@ export interface CatalogEntityHydrated extends SellableEntity {
   optionTypes?: Array<OptionType & { values: OptionValue[] }>;
   categories?: EntityCategory[];
   brands?: EntityBrand[];
-  media?: Array<{ mediaAssetId: string; role: string; variantId?: string }>;
-  pricing?: Array<{ currency: string; amount: number; compareAtAmount?: number | null }>;
+  media?: Array<{ mediaAssetId: string; role: string; sortOrder: number; variantId: string | null; url: string; alt: string | null; contentType: string }>;
+  pricing?: Array<{ id: string; currency: string; amount: number; compareAtAmount?: number | null; createdAt: Date }>;
 }
 
 export interface CatalogService {

package/src/modules/media/service.ts

@@ -28,6 +28,16 @@ export interface AttachMediaInput {
   sortOrder?: number;
 }
 
+export interface AttachedMedia {
+  mediaAssetId: string;
+  role: string;
+  sortOrder: number;
+  variantId: string | null;
+  url: string;
+  alt: string | null;
+  contentType: string;
+}
+
 interface MediaServiceDeps {
   repository: MediaRepository;
   catalogRepository: CatalogRepository;
@@ -234,4 +244,34 @@ export class MediaService {
 
     return Ok(undefined);
   }
+
+  /**
+   * Media attached to an entity, resolved to public URLs and ordered by
+   * sortOrder. Powers catalog `?include=media` hydration. Returns entity-level
+   * links only unless a specific variantId is requested.
+   */
+  async listEntityMedia(
+    entityId: string,
+    opts?: { variantId?: string; orgId?: string },
+    ctx?: TxContext,
+  ): Promise<Result<AttachedMedia[]>> {
+    const links = await this.repo.findEntityMedia(entityId, opts?.variantId, ctx);
+    const out: AttachedMedia[] = [];
+    for (const link of links) {
+      const asset = await this.repo.findAssetById(link.mediaAssetId, ctx, opts?.orgId);
+      if (!asset) continue;
+      const urlResult = await this.deps.storage.getUrl(asset.storageKey);
+      out.push({
+        mediaAssetId: link.mediaAssetId,
+        role: link.role,
+        sortOrder: link.sortOrder,
+        variantId: link.variantId ?? null,
+        url: urlResult.ok ? urlResult.value : "",
+        alt: asset.alt ?? null,
+        contentType: asset.contentType,
+      });
+    }
+    out.sort((a, b) => a.sortOrder - b.sortOrder);
+    return Ok(out);
+  }
 }

package/src/modules/orders/service.ts

@@ -78,6 +78,11 @@ export interface ChangeStatusInput {
   orderId: string;
   newStatus: OrderState;
   reason?: string;
+  /**
+   * Explicit refund amount (minor units) for a `refunded` transition. Clamped
+   * to the captured amount. Omit to refund the full captured amount.
+   */
+  refundAmount?: number;
 }
 
 export interface OrderServiceDeps {
@@ -540,10 +545,14 @@ export class OrderService {
           | undefined;
 
         if (payments?.refund) {
-          const refundAmount = Math.min(
+          const maxRefund = Math.min(
             order.grandTotal,
             order.amountCaptured ?? order.grandTotal,
           );
+          const refundAmount =
+            input.refundAmount != null
+              ? Math.min(input.refundAmount, maxRefund)
+              : maxRefund;
           await payments.refund(
             paymentIntentId,
             refundAmount,
@@ -675,14 +684,88 @@ export class OrderService {
     actor: Actor | null,
     reason = "refunded",
     ctx?: TxContext,
+    opts?: { amount?: number },
   ): Promise<Result<HydratedOrder>> {
     return this.changeStatus(
-      { orderId, newStatus: "refunded", reason },
+      {
+        orderId,
+        newStatus: "refunded",
+        reason,
+        ...(opts?.amount != null ? { refundAmount: opts.amount } : {}),
+      },
       actor,
       ctx,
     );
   }
 
+  /**
+   * Capture an authorized payment for an order via the payment adapter and
+   * record the captured amount. Does not transition order status — capture is a
+   * payment operation, not a fulfillment one.
+   */
+  async capture(
+    orderId: string,
+    actor: Actor | null,
+    opts?: { amount?: number },
+    ctx?: TxContext,
+  ): Promise<Result<HydratedOrder>> {
+    const orgId = resolveOrgId(actor);
+    const order = await this.repo.findById(orgId, orderId, ctx);
+    if (!order) return Err(new CommerceNotFoundError("Order not found."));
+
+    try {
+      assertPermission(actor, "orders:update");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+
+    const paymentIntentId =
+      ((order as Record<string, unknown>).paymentIntentId as string | undefined) ??
+      ((order.metadata as Record<string, unknown> | null)?.paymentIntentId as
+        | string
+        | undefined);
+    if (!paymentIntentId) {
+      return Err(
+        new CommerceValidationError("Order has no authorized payment to capture."),
+      );
+    }
+
+    const payments = this.deps.services.payments as
+      | {
+          capture(
+            paymentIntentId: string,
+            amount?: number,
+            paymentMethodId?: string,
+          ): Promise<{ ok: boolean; value?: { amountCaptured?: number }; error?: unknown }>;
+        }
+      | undefined;
+    if (!payments?.capture) {
+      return Err(
+        new CommerceValidationError("No payment adapter configured for capture."),
+      );
+    }
+
+    const paymentMethodId = (order as Record<string, unknown>).paymentMethodId as
+      | string
+      | undefined;
+    const captureResult = await payments.capture(
+      paymentIntentId,
+      opts?.amount,
+      paymentMethodId,
+    );
+    if (!captureResult.ok) {
+      return Err(toCommerceError(captureResult.error));
+    }
+
+    const amountCaptured =
+      captureResult.value?.amountCaptured ?? opts?.amount ?? order.grandTotal;
+    await this.repo.update(orderId, { amountCaptured }, ctx);
+
+    const refreshed = await this.repo.findById(orgId, orderId, ctx);
+    const hydrated = await this.hydrateOrder(refreshed ?? order, ctx);
+    return Ok(hydrated);
+  }
+
   async getStatusHistory(
     orderId: string,
     actor?: Actor | null,

package/src/modules/pricing/service.ts

@@ -129,6 +129,11 @@ function quantityRangeWidth(
   return Number.MAX_SAFE_INTEGER;
 }
 
+function sameNaturalKeyDate(a: Date | null | undefined, b: Date | null | undefined): boolean {
+  if (a == null || b == null) return (a ?? null) === (b ?? null);
+  return a.getTime() === b.getTime();
+}
+
 function compareBasePriceSpecificity(
   a: Price,
   b: Price,
@@ -229,7 +234,30 @@ export class PricingService {
       validUntil: input.validUntil ?? null,
     };
 
-    const record = await this.repo.createPrice(priceData, ctx);
+    // Upsert on the natural key. "Set base price" is idempotent per
+    // (org, entity, variant, currency, customerGroup, qty range, validity):
+    // a repeat call replaces the existing row's amount instead of appending a
+    // shadow row that the resolver would then tie-break on createdAt.
+    const existing = (
+      await this.repo.findPricesByEntityId(orgId, input.entityId, ctx)
+    ).find(
+      (p) =>
+        p.currency === priceData.currency &&
+        p.variantId === (priceData.variantId ?? null) &&
+        p.customerGroupId === (priceData.customerGroupId ?? null) &&
+        p.minQuantity === (priceData.minQuantity ?? null) &&
+        p.maxQuantity === (priceData.maxQuantity ?? null) &&
+        sameNaturalKeyDate(p.validFrom, priceData.validFrom ?? null) &&
+        sameNaturalKeyDate(p.validUntil, priceData.validUntil ?? null),
+    );
+
+    const record = existing
+      ? (await this.repo.updatePrice(
+          existing.id,
+          { amount: priceData.amount, metadata: priceData.metadata },
+          ctx,
+        )) ?? existing
+      : await this.repo.createPrice(priceData, ctx);
 
     const afterHooks = this.deps.hooks.resolve(
       "pricing.afterCreate",

package/src/runtime/server.ts

@@ -2,6 +2,7 @@ import { Hono } from "hono";
 import { OpenAPIHono } from "@hono/zod-openapi";
 import { cors } from "hono/cors";
 import { csrf } from "hono/csrf";
+import { HTTPException } from "hono/http-exception";
 import { bodyLimit } from "hono/body-limit";
 import { rateLimiter } from "hono-rate-limiter";
 import { createHash } from "node:crypto";
@@ -10,6 +11,7 @@ import type { Actor } from "../auth/types.js";
 import type { AuthInstance } from "../auth/setup.js";
 import type { CommerceConfig } from "../config/types.js";
 import { authMiddleware } from "../auth/middleware.js";
+import { CommerceCsrfError } from "../kernel/errors.js";
 import { createRestRoutes } from "../interfaces/rest/index.js";
 import { createCustomerPortalRoutes } from "../interfaces/rest/customer-portal.js";
 import { createKernel } from "./kernel.js";
@@ -178,11 +180,42 @@ export async function createServer(config: CommerceConfig) {
   }));
 
   // ─── CSRF Protection (F14) ──────────────────────────────────────────
-  app.use("/api/*", csrf({
+  // CSRF defends cookie/session auth, where the browser attaches the credential
+  // ambiently. API-key (x-api-key) and bearer-token requests carry an explicit,
+  // non-ambient credential and are not CSRF-attackable, so the guard is skipped
+  // for them — otherwise a bodyless server-to-server POST (no Origin, no JSON
+  // content-type, e.g. /publish or /archive from the SDK) trips CSRF and 403s
+  // for no security benefit.
+  const csrfGuard = csrf({
     origin: trustedOrigins.length > 0
       ? trustedOrigins
       : (process.env.NODE_ENV === "production" ? [] : ["http://localhost:*"]),
-  }));
+  });
+  app.use("/api/*", async (c, next) => {
+    const authenticatedByKey =
+      !!c.req.header("x-api-key") ||
+      /^Bearer\s+/i.test(c.req.header("authorization") ?? "");
+    if (authenticatedByKey) return next();
+
+    // Run only the CSRF origin check here; invoke the real downstream afterwards
+    // so a genuine 403 from a route handler can't be misattributed to CSRF.
+    let passedCsrf = false;
+    try {
+      await csrfGuard(c, async () => {
+        passedCsrf = true;
+      });
+    } catch (err) {
+      if (err instanceof HTTPException && err.status === 403) {
+        throw new CommerceCsrfError(
+          "Origin check failed: the request Origin is not in the trusted origins allowlist. " +
+            "Browser clients must send a trusted Origin; server-to-server callers should authenticate with an API key (x-api-key).",
+        );
+      }
+      throw err;
+    }
+    if (!passedCsrf) return;
+    return next();
+  });
 
   // ─── Body Size Limit (F6) ──────────────────────────────────────────
   // Media uploads (phone photos are 3–8MB) get their own larger limit and are