@tokenoftrust/storefront-runner 6.4.0 → 6.5.1

package/apps/storefront/src/lib/integrations/webhooks/orderFulfilledClaim.ts

@@ -0,0 +1,75 @@
+/**
+ * `order.fulfilled` is claimed once per order across its two producers: the fulfillment handoff
+ * and the order-forward receiver. The claim is keyed (tenant, stage, source, source order id,
+ * topic); each producer writes its claim and its gated event rows in one batch, and only the
+ * producer whose claim carries its event id writes the event.
+ */
+import type { CommerceStage } from "@tot/public-runtime";
+import type { CommerceEventStatement } from "./deliveryStore.js";
+
+export interface OrderFulfilledClaimKey {
+  tenantId: string;
+  stage: CommerceStage;
+  source: string;
+  sourceOrderId: string;
+}
+
+/** The forward contract's `env` mapped to a commerce stage; any other value claims and emits nothing. */
+export function forwardStage(env: string): CommerceStage | null {
+  if (env === "production") return "publication";
+  if (env === "sandbox") return "preview";
+  return null;
+}
+
+/** The handoff's claim: written only when no claim exists and `gate` holds (the handoff's CAS committed). */
+export function handoffClaimStatement(
+  key: OrderFulfilledClaimKey,
+  eventId: string,
+  now: string,
+  gate: CommerceEventStatement,
+): CommerceEventStatement {
+  return {
+    sql: `INSERT INTO commerce_event_claims
+        (tenant_id, stage, source, source_order_id, topic, event_id, claimed_by, claimed_at)
+      SELECT ?, ?, ?, ?, 'order.fulfilled', ?, 'handoff', ?
+      WHERE NOT EXISTS (
+          SELECT 1 FROM commerce_event_claims
+          WHERE tenant_id = ? AND stage = ? AND source = ? AND source_order_id = ? AND topic = 'order.fulfilled'
+        ) AND (${gate.sql})`,
+    params: [
+      key.tenantId,
+      key.stage,
+      key.source,
+      key.sourceOrderId,
+      eventId,
+      now,
+      key.tenantId,
+      key.stage,
+      key.source,
+      key.sourceOrderId,
+      ...gate.params,
+    ],
+  };
+}
+
+/** The forward receiver's claim. */
+export function forwardClaimStatement(key: OrderFulfilledClaimKey, eventId: string, now: string): CommerceEventStatement {
+  return {
+    sql: `INSERT OR IGNORE INTO commerce_event_claims
+        (tenant_id, stage, source, source_order_id, topic, event_id, claimed_by, claimed_at)
+      VALUES (?, ?, ?, ?, 'order.fulfilled', ?, 'forward', ?)`,
+    params: [key.tenantId, key.stage, key.source, key.sourceOrderId, eventId, now],
+  };
+}
+
+/** Event gate: the claim for `key` carries `eventId`. */
+export function claimedByEventGate(key: OrderFulfilledClaimKey, eventId: string): CommerceEventStatement {
+  return {
+    sql: `EXISTS (
+        SELECT 1 FROM commerce_event_claims
+        WHERE tenant_id = ? AND stage = ? AND source = ? AND source_order_id = ? AND topic = 'order.fulfilled'
+          AND event_id = ?
+      )`,
+    params: [key.tenantId, key.stage, key.source, key.sourceOrderId, eventId],
+  };
+}

package/apps/storefront/src/lib/orders/data/orderForwardReceiver.ts

@@ -21,6 +21,11 @@
  *     corresponding topic — e.g. -> `cancelled`, which V1 has no topic for)
  *     -> no emit; the row still updates, silently.
  *
+ * `order.fulfilled` is claimed once per order (`orderFulfilledClaim.ts`) under the key the signed
+ * intake and the fulfillment handoff use: (tenant, stage from `env`, `foxycart`, external order id).
+ * The claim, the event and its deliveries commit in one batch; a forward whose order is already
+ * claimed writes nothing, and an `env` other than production or sandbox emits no `order.fulfilled`.
+ *
  * Customer identity: `rawCustomerId` is optional (tot-foxycart's own
  * order-forward payload doesn't always carry one — mirrors `FoxyOrder`'s
  * own optional `customerEmail`). This receiver never derives, stores, or
@@ -36,7 +41,8 @@ import { SourceAuthorityStore } from "./sourceAuthorityStore.js";
 import { SourceAuthorityError, parseSourceWire, exactKeys, digestJson, type BeginAck, type ResultAck, type AuthorityCode, isRecord, isSourceId } from "./sourceAuthorityContract.js";
 import { OrdersStore, ScrappyOrderLedger, type OrderLineItem, type OrderStatus, type Order } from "./ordersStore.js";
 import { emitWebhookEvent } from "../../integrations/webhooks/emit.js";
-import type { WebhookTopic } from "../../integrations/webhooks/deliveryStore.js";
+import { commerceEventStatements, commerceTargetsQuery, type WebhookTopic } from "../../integrations/webhooks/deliveryStore.js";
+import { claimedByEventGate, forwardClaimStatement, forwardStage, type OrderFulfilledClaimKey } from "../../integrations/webhooks/orderFulfilledClaim.js";
 import type { Queryable } from "../../catalog/d1/catalog.js";
 import {
   createLocalJWKSet,
@@ -125,7 +131,11 @@ function topicsFor(previousStatus: OrderStatus | null, status: OrderStatus): Web
  * verified the request's HMAC signature — this function never re-checks
  * authenticity and must never be reached from an unverified request.
  */
-export async function receiveForwardedOrder(db: Queryable, input: OrderForwardInput): Promise<OrderForwardResult> {
+export async function receiveForwardedOrder(
+  db: Queryable,
+  input: OrderForwardInput,
+  options: { notify?: (tenantId: string, deliveryIds: string[]) => void | Promise<void> } = {},
+): Promise<OrderForwardResult> {
   const store = new OrdersStore(db);
   // input.rawCustomerId is intentionally not read here — see the module doc's
   // "Customer identity" note for why no hash is derived from it.
@@ -142,14 +152,65 @@ export async function receiveForwardedOrder(db: Queryable, input: OrderForwardIn
     createdAt: input.createdAt ?? new Date().toISOString(),
   });
 
-  const emitted = topicsFor(previousStatus, input.status);
-  for (const topic of emitted) {
+  const emitted: WebhookTopic[] = [];
+  for (const topic of topicsFor(previousStatus, input.status)) {
+    if (topic === "order.fulfilled") {
+      if (await emitClaimedOrderFulfilled(db, input, order, options.notify)) emitted.push(topic);
+      continue;
+    }
     await emitWebhookEvent(topic, input.tenantId, toOrderData(order), {});
+    emitted.push(topic);
   }
 
   return { order, previousStatus, emitted };
 }
 
+/** Claims `order.fulfilled` for this order and, only under that claim, writes its event and deliveries. */
+async function emitClaimedOrderFulfilled(
+  db: Queryable,
+  input: OrderForwardInput,
+  order: Order,
+  notify: ((tenantId: string, deliveryIds: string[]) => void | Promise<void>) | undefined,
+): Promise<boolean> {
+  const stage = forwardStage(input.env);
+  if (!stage) return false;
+  if (!db.batch) throw new Error("Atomic D1 batch support is required.");
+  const key: OrderFulfilledClaimKey = {
+    tenantId: input.tenantId,
+    stage,
+    source: "foxycart",
+    sourceOrderId: input.externalOrderId,
+  };
+  const eventId = crypto.randomUUID();
+  const now = new Date().toISOString();
+  const targets = commerceTargetsQuery(input.tenantId, "order.fulfilled");
+  const installs = await db.all<{ install_id: string }>(targets.sql, ...targets.params);
+  const deliveries = installs.map((row) => ({ installId: row.install_id, deliveryId: crypto.randomUUID() }));
+  await db.batch([
+    forwardClaimStatement(key, eventId, now),
+    ...commerceEventStatements({
+      eventId,
+      tenantId: input.tenantId,
+      topic: "order.fulfilled",
+      payload: toOrderData(order),
+      gate: claimedByEventGate(key, eventId),
+      targets: deliveries,
+      now,
+    }),
+  ]);
+  const written = await db.first<{ ok: number }>(`SELECT 1 AS ok FROM webhook_events WHERE id = ?`, eventId);
+  if (!written) return false;
+  const committed = await db.all<{ delivery_id: string }>(`SELECT delivery_id FROM webhook_deliveries WHERE event_id = ?`, eventId);
+  if (notify && committed.length > 0) {
+    try {
+      await notify(input.tenantId, committed.map((row) => row.delivery_id));
+    } catch {
+      // The committed deliveries stay pending; the tenant commerce alarm redelivers them.
+    }
+  }
+  return true;
+}
+
 export interface CommerceCallerConfig {
   expectedStage: CommerceStage;
   jwks: JSONWebKeySet;

package/apps/storefront/src/pages/products/[handle].astro

@@ -33,6 +33,7 @@ import {
   DEFAULT_STACKING_POLICY,
   readReviewAggregate,
   resolveProductDetails,
+  tenantPublicOrigin,
 } from "@tot/public-runtime";
 import type {
   ProductPurchaseOption,
@@ -268,6 +269,7 @@ if (commerce || sampleHandoff) {
                     tenantId: commerceTenantId(tenant),
                     currency: tenant.currency,
                     contentVersionId: Astro.locals.browserEnvironment.environment === "live" ? undefined : Astro.locals.contentVersionId,
+                    publicOrigin: tenantPublicOrigin(tenant),
                   }),
                 ] as const;
               }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "6.4.0",
+  "version": "6.5.1",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/src/checkout.ts

@@ -172,6 +172,32 @@ export interface BuildVariantCartPayloadOptions {
    * A publication page and a shared-channel preview omit it. Never taken from the form.
    */
   contentVersionId?: string;
+  /**
+   * The tenant's canonical public origin (`tenantPublicOrigin`), from server-side tenant config.
+   * A root-relative catalog image is signed as an absolute URL on it, so the checkout can load it
+   * and no page rewrite of the relative path can break the signature. Never a request value.
+   */
+  publicOrigin?: string;
+}
+
+/** `https://<canonicalDomain>` from server-side tenant config; undefined when it is not a bare host. */
+export function tenantPublicOrigin(tenant: Pick<TenantConfig, "canonicalDomain">): string | undefined {
+  const host = tenant.canonicalDomain?.trim().toLowerCase();
+  return host && /^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?(?::\d{1,5})?$/.test(host) ? `https://${host}` : undefined;
+}
+
+/**
+ * A root-relative image resolved against the public origin. Absolute and protocol-relative values,
+ * and any that fail to parse or would resolve onto another origin, are signed as they are.
+ */
+function cartImageUrl(image: string, publicOrigin: string | undefined): string {
+  if (!publicOrigin || !image.startsWith("/") || image.startsWith("//")) return image;
+  try {
+    const resolved = new URL(image, publicOrigin);
+    return resolved.origin === new URL(publicOrigin).origin ? resolved.href : image;
+  } catch {
+    return image;
+  }
 }
 
 /** Declared public serving substrate (ADR 0013 `serving.provider`). */
@@ -527,11 +553,12 @@ export function cartFieldsForVariant(
   product: CatalogProduct,
   variant: CatalogVariant,
   purchaseOption?: ProductPurchaseOption,
-  opts?: { signedPrice?: number; tenantId?: string; currency?: string; contentVersionId?: string },
+  opts?: { signedPrice?: number; tenantId?: string; currency?: string; contentVersionId?: string; publicOrigin?: string },
 ): { code: string; fields: CartField[] } {
   const code = cartLineCode(variant);
-  const image = product.images.find((i) => i.id === variant.image_id)?.url ??
+  const catalogImage = product.images.find((i) => i.id === variant.image_id)?.url ??
     product.images[0]?.url;
+  const image = catalogImage ? cartImageUrl(catalogImage, opts?.publicOrigin) : undefined;
   // The signed price is either the caller's member-adjusted EFFECTIVE price
   // (F11b — the single signed source of truth, computed server-side from the
   // shopper's resolved eligibility) or, absent that, the list/subscription price.
@@ -762,7 +789,10 @@ export async function buildVariantCartPayload(
     product,
     variant,
     opts.purchaseOption,
-    { signedPrice: opts.signedPrice, tenantId: opts.tenantId, currency: opts.currency, contentVersionId: opts.contentVersionId },
+    {
+      signedPrice: opts.signedPrice, tenantId: opts.tenantId, currency: opts.currency,
+      contentVersionId: opts.contentVersionId, publicOrigin: opts.publicOrigin,
+    },
   );
   const signed = opts.mode === "signed";
   if (signed && !opts.secret) {
@@ -796,7 +826,15 @@ export interface CartSubmissionField {
 
 export type CartEnforcement =
   | { ok: true; fields: CartSubmissionField[]; paymentAuthorized: false }
-  | { ok: false; code: CartDenialCode; message: string; paymentAuthorized: false };
+  | {
+    ok: false; code: CartDenialCode; message: string; paymentAuthorized: false;
+    /**
+     * Base names of the signed fields that failed verification or were missing, for the operator
+     * log. Names only, never a value, hash or the secret; a name that is not a plain field name is
+     * reported as `(unrecognized)`.
+     */
+    failedFields: string[];
+  };
 
 interface ParsedCartField {
   rawName: string;
@@ -839,12 +877,26 @@ function parseSubmittedField(rawName: string, value: string): ParsedCartField {
   return { rawName, baseName: rawName, value, open: false, passthrough: false };
 }
 
-function denial(code: CartDenialCode): CartEnforcement {
+const MAX_REPORTED_CART_FIELDS = 20;
+
+/**
+ * A submitted base name safe to log. Native and internal names are reported as-is; any other
+ * (a variant option) only when it is a short letters-only label, so a crafted name can never
+ * carry digits, an address or markup into the log.
+ */
+function reportedFieldName(baseName: string): string {
+  if ((NATIVE_CART_FIELDS as readonly string[]).includes(baseName) ||
+    (INTERNAL_CART_FIELDS as readonly string[]).includes(baseName)) return baseName;
+  return /^[A-Za-z][A-Za-z _.-]{0,63}$/.test(baseName) ? baseName : "(unrecognized)";
+}
+
+function denial(code: CartDenialCode, failedFields: Iterable<string> = []): CartEnforcement {
   return {
     ok: false,
     code,
     message: CART_DENIAL_MESSAGE[code],
     paymentAuthorized: false,
+    failedFields: [...new Set([...failedFields].map(reportedFieldName))].slice(0, MAX_REPORTED_CART_FIELDS),
   };
 }
 
@@ -875,14 +927,15 @@ export async function enforceCartSubmission(input: {
   const byBase = new Map<string, ParsedCartField>();
   for (const field of parsed) {
     if (field.passthrough) continue;
-    if (byBase.has(field.baseName)) return denial("signature");
+    if (byBase.has(field.baseName)) return denial("signature", [field.baseName]);
     byBase.set(field.baseName, field);
   }
 
   const codeField = byBase.get("code");
-  if (!codeField || !codeField.value) return denial("signature");
+  if (!codeField || !codeField.value) return denial("signature", ["code"]);
 
   const failures = new Set<CartDenialCode>();
+  const failedFields = new Set<string>();
   const signed = input.mode === "signed";
   const secret = input.secret ?? "";
 
@@ -894,10 +947,16 @@ export async function enforceCartSubmission(input: {
   };
 
   if (signed) {
-    if (!(await hashOk(codeField))) failures.add("signature");
+    if (!(await hashOk(codeField))) {
+      failures.add("signature");
+      failedFields.add("code");
+    }
     for (const field of byBase.values()) {
       if (field.baseName === "code") continue;
-      if (!(await hashOk(field))) failures.add(specificCode(field.baseName));
+      if (!(await hashOk(field))) {
+        failures.add(specificCode(field.baseName));
+        failedFields.add(field.baseName);
+      }
     }
   }
 
@@ -911,13 +970,16 @@ export async function enforceCartSubmission(input: {
   if (!quantityField || !quantityAllowed(quantityField.value)) failures.add("quantity");
   if (signed) {
     for (const required of ["name", "currency"]) {
-      if (!byBase.get(required)) failures.add("signature");
+      if (!byBase.get(required)) {
+        failures.add("signature");
+        failedFields.add(required);
+      }
     }
   }
 
   const order: CartDenialCode[] = ["tenant", "price", "quantity", "signature"];
   for (const code of order) {
-    if (failures.has(code)) return denial(code);
+    if (failures.has(code)) return denial(code, failedFields);
   }
 
   return {

package/packages/public-runtime/src/membership.ts

@@ -282,6 +282,8 @@ export interface MemberSignedCartPayloadOptions {
   currency?: string;
   /** Candidate content pin the preview page rendered. Omitted for publication and the shared channel. */
   contentVersionId?: string;
+  /** Tenant public origin a relative image is signed on (see {@link BuildVariantCartPayloadOptions.publicOrigin}). */
+  publicOrigin?: string;
 }
 
 /**
@@ -318,6 +320,7 @@ export async function buildMemberSignedCartPayload(
     tenantId: opts.tenantId,
     currency: opts.currency,
     contentVersionId: opts.contentVersionId,
+    publicOrigin: opts.publicOrigin,
   });
 }