@tokenoftrust/storefront-runner 2.4.53 → 2.4.54

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

@@ -32,10 +32,34 @@
  * compute one FOR either. `rawCustomerId` is accepted and simply unused;
  * see `docs/private-apps/order-forward-contract.md` for the full rationale.
  */
-import { OrdersStore, type OrderLineItem, type OrderStatus, type Order } from "./ordersStore.js";
+import { OrdersStore, ScrappyOrderLedger, type OrderLineItem, type OrderStatus, type Order } from "./ordersStore.js";
 import { emitWebhookEvent } from "../../webhooks/emit.js";
 import type { WebhookTopic } from "../../webhooks/deliveryStore.js";
 import type { Queryable } from "../../d1/catalog.js";
+import {
+  createLocalJWKSet,
+  decodeJwt,
+  decodeProtectedHeader,
+  errors as joseErrors,
+  jwtVerify,
+  type JSONWebKeySet,
+  type JWK,
+  type JWTPayload,
+} from "jose";
+import {
+  admitCallerToken,
+  canonicalJson,
+  sha256Hex,
+  type CallerTokenRefusal,
+  type CommerceStage,
+  type FulfillmentState,
+  type PaymentState,
+} from "@tot/public-runtime";
+import {
+  normalizeCommerceEvent,
+  payloadExposesPrivateIdentity,
+  type CommerceCommandName,
+} from "./orderMapper.js";
 
 /** One reconciled order, as tot-foxycart forwards it. See the contract doc for the wire (JSON) shape. */
 export interface OrderForwardInput {
@@ -123,3 +147,181 @@ export async function receiveForwardedOrder(db: Queryable, input: OrderForwardIn
 
   return { order, previousStatus, emitted };
 }
+
+export interface CommerceCallerConfig {
+  jwks: JSONWebKeySet;
+  trustedIssuers: readonly string[];
+  expectedAudience: string;
+  activeKids: readonly string[];
+  now: string;
+}
+
+export type SignedCommerceRefusal = CallerTokenRefusal | "version" | "malformed" | "totals" | "private" | "replay";
+
+export type SignedCommerceResult =
+  | {
+      ok: true;
+      duplicate: boolean;
+      payment: PaymentState;
+      fulfillment: FulfillmentState;
+      eventVersion: number;
+      command: CommerceCommandName;
+      stage: CommerceStage;
+      currency: string;
+      tenantId: string;
+    }
+  | { ok: false; status: number; reason: SignedCommerceRefusal | "order commit failed" };
+
+function isStage(value: unknown): value is CommerceStage {
+  return value === "preview" || value === "publication";
+}
+
+function publicJwk(key: { kid?: string; kty?: string; crv?: string; use?: string; alg?: string; x?: string }): Record<string, string> {
+  return {
+    kty: key.kty ?? "",
+    crv: key.crv ?? "",
+    kid: key.kid ?? "",
+    ...(key.use ? { use: key.use } : {}),
+    ...(key.alg ? { alg: key.alg } : {}),
+    ...(key.x ? { x: key.x } : {}),
+  };
+}
+
+function expiresAtIso(exp: unknown): string {
+  if (typeof exp !== "number" || !Number.isFinite(exp)) return "";
+  return new Date(exp * 1000).toISOString();
+}
+
+/** Verify a caller-owned EdDSA JWT against the trusted public JWKS. No shared secret. */
+export async function verifySignedCommerceToken(
+  token: string,
+  config: CommerceCallerConfig,
+  binding: { tenantId: string; stage: CommerceStage },
+): Promise<{ ok: true; issuer: string; jti: string; digest: string } | { ok: false; reason: CallerTokenRefusal | "version" }> {
+  if (token.split(".").length !== 3) {
+    const admitted = admitCallerToken({
+      token: { scheme: "shared-secret" },
+      trustedIssuers: config.trustedIssuers,
+      expectedAudience: config.expectedAudience,
+      activeKids: config.activeKids,
+      now: config.now,
+      tenantId: binding.tenantId,
+      stage: binding.stage,
+    });
+    return admitted.ok ? { ok: false, reason: "shared-secret" } : admitted;
+  }
+
+  let kid = "";
+  try {
+    const header = decodeProtectedHeader(token);
+    kid = typeof header.kid === "string" ? header.kid : "";
+  } catch {
+    return { ok: false, reason: "signature" };
+  }
+
+  const match = config.jwks.keys?.find((key) => key.kid === kid);
+  let signatureValid = false;
+  let payload: JWTPayload | null = null;
+  if (match) {
+    try {
+      const verified = await jwtVerify(token, createLocalJWKSet({ keys: [publicJwk(match) as JWK] }), {
+        currentDate: new Date(config.now),
+      });
+      signatureValid = true;
+      payload = verified.payload;
+    } catch (error) {
+      if (error instanceof joseErrors.JWTExpired || error instanceof joseErrors.JWTClaimValidationFailed) {
+        signatureValid = true;
+        try {
+          payload = decodeJwt(token);
+        } catch {
+          payload = null;
+        }
+      }
+    }
+  }
+
+  const claims = payload ?? {};
+  const stage = isStage(claims.stage) ? claims.stage : binding.stage;
+  const audience = typeof claims.aud === "string" ? claims.aud : "";
+  const admitted = admitCallerToken({
+    token: {
+      scheme: "asymmetric-jwks",
+      signatureValid,
+      kid,
+      issuer: typeof claims.iss === "string" ? claims.iss : "",
+      audience,
+      expiresAt: expiresAtIso(claims.exp),
+      jti: typeof claims.jti === "string" ? claims.jti : "",
+      tenantId: typeof claims.tenantId === "string" ? claims.tenantId : "",
+      stage: isStage(claims.stage) ? claims.stage : stage,
+    },
+    trustedIssuers: config.trustedIssuers,
+    expectedAudience: config.expectedAudience,
+    activeKids: config.activeKids,
+    now: config.now,
+    tenantId: binding.tenantId,
+    stage: binding.stage,
+  });
+  if (!isStage(claims.stage)) return { ok: false, reason: admitted.ok ? "stage" : admitted.reason === "signature" ? "signature" : "stage" };
+  if (!admitted.ok) return admitted;
+  if (claims.ver !== 1) return { ok: false, reason: "version" };
+  if (typeof claims.digest !== "string" || claims.digest === "") return { ok: false, reason: "signature" };
+  return { ok: true, issuer: typeof claims.iss === "string" ? claims.iss : "", jti: typeof claims.jti === "string" ? claims.jti : "", digest: claims.digest };
+}
+
+/** Signed-native intake. The order row and its outbox row commit together. */
+export async function receiveSignedCommerceOrder(
+  db: Queryable,
+  body: unknown,
+  token: string,
+  config: CommerceCallerConfig,
+): Promise<SignedCommerceResult> {
+  if (body === null || typeof body !== "object" || Array.isArray(body)) {
+    return { ok: false, status: 400, reason: "malformed" };
+  }
+  const record = body as Record<string, unknown>;
+  if (typeof record.tenantId !== "string" || record.tenantId.trim() === "") {
+    return { ok: false, status: 401, reason: "tenant" };
+  }
+  if (!isStage(record.stage)) return { ok: false, status: 401, reason: "stage" };
+  if (!("event" in record)) return { ok: false, status: 400, reason: "malformed" };
+
+  const verified = await verifySignedCommerceToken(token, config, {
+    tenantId: record.tenantId,
+    stage: record.stage,
+  });
+  if (!verified.ok) return { ok: false, status: 401, reason: verified.reason };
+  if (payloadExposesPrivateIdentity(body)) return { ok: false, status: 400, reason: "private" };
+
+  const envelope = { tenantId: record.tenantId, stage: record.stage, event: record.event };
+  const digest = await sha256Hex(canonicalJson(envelope));
+  if (digest !== verified.digest) return { ok: false, status: 401, reason: "signature" };
+
+  const event = normalizeCommerceEvent(record.event);
+  if (event === "malformed" || event === "totals") return { ok: false, status: 400, reason: event };
+
+  try {
+    const committed = await new ScrappyOrderLedger(db).commit({
+      tenantId: record.tenantId,
+      stage: record.stage,
+      event,
+      now: config.now,
+      replay: { issuer: verified.issuer, jti: verified.jti },
+    });
+    if (!committed.ok) return { ok: false, status: 401, reason: "replay" };
+    return {
+      ok: true,
+      duplicate: committed.duplicate,
+      payment: committed.snapshot.payment,
+      fulfillment: committed.snapshot.fulfillment,
+      eventVersion: committed.snapshot.eventVersion,
+      command: event.command,
+      stage: record.stage,
+      currency: committed.snapshot.currency,
+      tenantId: record.tenantId,
+    };
+  } catch {
+    return { ok: false, status: 500, reason: "order commit failed" };
+  }
+}

package/apps/storefront/src/lib/apps/orders/orderMapper.ts

@@ -10,6 +10,24 @@
  */
 import { customerHash } from "./customerHash.js";
 import type { FoxyOrder, FoxyOrderLineItem } from "./foxyOrderClient.js";
+import {
+  COMPLIANCE_STATES,
+  FULFILLMENT_STATES,
+  LABEL_STATES,
+  PAYMENT_STATES,
+  STOCK_STATES,
+  decideCommerceCommand,
+  publicCommerceEvent,
+  totalsMatch,
+  type CommerceEvidence,
+  type ComplianceState,
+  type FulfillmentState,
+  type LabelState,
+  type MinorTotals,
+  type PaymentState,
+  type PublicCommerceEvent,
+  type StockState,
+} from "@tot/public-runtime";
 
 export type ContractOrderStatus = "created" | "fulfilled" | "cancelled";
 
@@ -89,3 +107,306 @@ export async function toContractOrder(order: FoxyOrder, ctx: ToContractOrderCont
     createdAt: toIsoDateTime(order.orderedAt),
   };
 }
+
+export const COMMERCE_COMMANDS = ["observe", "capture", "refund", "cancel"] as const;
+export type CommerceCommandName = (typeof COMMERCE_COMMANDS)[number];
+
+const PRIVATE_COMMERCE_KEYS = new Set([
+  "customer",
+  "customerEmail",
+  "customerName",
+  "email",
+  "phone",
+  "line1",
+  "line2",
+  "postalCode",
+  "shippingAddress",
+  "billingAddress",
+  "address",
+  "firstName",
+  "lastName",
+  "name",
+]);
+
+const UNKNOWN_EVIDENCE: CommerceEvidence = {
+  verification: "UNKNOWN",
+  tax: "UNKNOWN",
+  risk: "UNKNOWN",
+  stock: "UNKNOWN",
+};
+
+export interface CommerceSourceEvent {
+  eventVersion: number;
+  command: CommerceCommandName;
+  orderId: string;
+  sourceEventId: string;
+  source: string;
+  sourceOrderId: string;
+  placedAt: string;
+  currency: string;
+  payment: PaymentState;
+  compliance: ComplianceState;
+  stock: StockState;
+  fulfillment: FulfillmentState;
+  label: LabelState;
+  totals: MinorTotals;
+  verificationDetail: CommerceEvidence;
+}
+
+export interface CommerceSnapshot {
+  orderId: string;
+  source: string;
+  sourceOrderId: string;
+  placedAt: string;
+  currency: string;
+  payment: PaymentState;
+  compliance: ComplianceState;
+  stock: StockState;
+  fulfillment: FulfillmentState;
+  label: LabelState;
+  totals: MinorTotals;
+  verificationDetail: CommerceEvidence;
+  eventVersion: number;
+  amountMinor: number;
+}
+
+export interface StoredCommercePayload {
+  source: CommerceSourceEvent;
+  public: PublicCommerceEvent;
+}
+
+export function payloadExposesPrivateIdentity(value: unknown): boolean {
+  if (value === null || typeof value !== "object") return false;
+  if (Array.isArray(value)) return value.some((item) => payloadExposesPrivateIdentity(item));
+  return Object.entries(value as Record<string, unknown>).some(
+    ([key, child]) => PRIVATE_COMMERCE_KEYS.has(key) || payloadExposesPrivateIdentity(child),
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function commandOf(value: Record<string, unknown>): CommerceCommandName | null {
+  const command = value.command ?? value.type;
+  if (command === "observe" || command === "order.observed") return "observe";
+  if (command === "capture" || command === "order.captured") return "capture";
+  if (command === "refund" || command === "order.refunded") return "refund";
+  if (command === "cancel" || command === "order.cancelled") return "cancel";
+  return null;
+}
+
+function readTotals(value: unknown): MinorTotals | null {
+  if (!isRecord(value)) return null;
+  const totals = {
+    subtotalMinor: value.subtotalMinor,
+    shippingMinor: value.shippingMinor,
+    taxMinor: value.taxMinor,
+    totalMinor: value.totalMinor,
+  };
+  if (
+    typeof totals.subtotalMinor !== "number" ||
+    typeof totals.shippingMinor !== "number" ||
+    typeof totals.taxMinor !== "number" ||
+    typeof totals.totalMinor !== "number"
+  ) {
+    return null;
+  }
+  return totals as MinorTotals;
+}
+
+function readEvidence(value: unknown): CommerceEvidence {
+  if (!isRecord(value)) return { ...UNKNOWN_EVIDENCE };
+  const pick = (key: keyof CommerceEvidence): CommerceEvidence[keyof CommerceEvidence] => {
+    const found = value[key];
+    if (found === "fresh" || found === "UNKNOWN" || found === "stale" || found === "unreadable" || found === "absent") {
+      return found;
+    }
+    return "UNKNOWN";
+  };
+  return {
+    verification: pick("verification"),
+    tax: pick("tax"),
+    risk: pick("risk"),
+    stock: pick("stock"),
+  };
+}
+
+/** Narrow a signed commerce body to the source event, or a refusal reason. */
+export function normalizeCommerceEvent(value: unknown): CommerceSourceEvent | "malformed" | "totals" {
+  if (!isRecord(value)) return "malformed";
+  const command = commandOf(value);
+  const eventVersion = value.eventVersion;
+  const orderId = value.orderId;
+  const sourceEventId = value.sourceEventId;
+  const placedAt = value.placedAt;
+  const currency = value.currency;
+  if (command === null) return "malformed";
+  if (typeof eventVersion !== "number" || !Number.isSafeInteger(eventVersion) || eventVersion < 1) return "malformed";
+  if (typeof orderId !== "string" || orderId.trim() === "" || orderId.includes("\n")) return "malformed";
+  if (typeof sourceEventId !== "string" || sourceEventId.trim() === "" || sourceEventId.includes("\n")) return "malformed";
+  if (typeof placedAt !== "string" || placedAt.trim() === "") return "malformed";
+  if (typeof currency !== "string" || currency.trim() === "") return "malformed";
+  const totals = readTotals(value.totals);
+  if (totals === null) return "malformed";
+  if (!totalsMatch(totals)) return "totals";
+  const payment = typeof value.payment === "string" ? value.payment : "UNKNOWN";
+  const compliance = typeof value.compliance === "string" ? value.compliance : "UNKNOWN";
+  const stock = typeof value.stock === "string" ? value.stock : "unallocated";
+  const fulfillment = typeof value.fulfillment === "string" ? value.fulfillment : "held";
+  const label = typeof value.label === "string" ? value.label : "none";
+  if (!(PAYMENT_STATES as readonly string[]).includes(payment)) return "malformed";
+  if (!(COMPLIANCE_STATES as readonly string[]).includes(compliance)) return "malformed";
+  if (!(STOCK_STATES as readonly string[]).includes(stock)) return "malformed";
+  if (!(FULFILLMENT_STATES as readonly string[]).includes(fulfillment)) return "malformed";
+  if (!(LABEL_STATES as readonly string[]).includes(label)) return "malformed";
+  return {
+    eventVersion,
+    command,
+    orderId,
+    sourceEventId,
+    source: typeof value.source === "string" && value.source.trim() !== "" ? value.source : "foxycart",
+    sourceOrderId: typeof value.sourceOrderId === "string" && value.sourceOrderId.trim() !== "" ? value.sourceOrderId : orderId,
+    placedAt,
+    currency,
+    payment: payment as PaymentState,
+    compliance: compliance as ComplianceState,
+    stock: stock as StockState,
+    fulfillment: fulfillment as FulfillmentState,
+    label: label as LabelState,
+    totals,
+    verificationDetail: readEvidence(value.verificationDetail),
+  };
+}
+
+export function toPublicCommerceSnapshot(snapshot: CommerceSnapshot): PublicCommerceEvent {
+  return publicCommerceEvent({
+    eventVersion: snapshot.eventVersion,
+    orderId: snapshot.orderId,
+    placedAt: snapshot.placedAt,
+    currency: snapshot.currency,
+    payment: snapshot.payment,
+    compliance: snapshot.compliance,
+    stock: snapshot.stock,
+    fulfillment: snapshot.fulfillment,
+    label: snapshot.label,
+    totals: snapshot.totals,
+    verificationDetail: snapshot.verificationDetail,
+  });
+}
+
+export function packCommercePayload(source: CommerceSourceEvent, snapshot: CommerceSnapshot): StoredCommercePayload {
+  return { source, public: toPublicCommerceSnapshot(snapshot) };
+}
+
+/**
+ * Version-sorted fold. Arrival order does not matter. A capture older than a
+ * cancel cannot put payment back to captured or clear the cancellation.
+ */
+export function foldCommerceEvents(events: readonly CommerceSourceEvent[]): CommerceSnapshot {
+  const unique = new Map<string, CommerceSourceEvent>();
+  for (const event of events) unique.set(`${event.source}\n${event.sourceEventId}`, event);
+  const sorted = [...unique.values()].sort((left, right) => {
+    if (left.eventVersion !== right.eventVersion) return left.eventVersion - right.eventVersion;
+    const rank = { observe: 0, capture: 1, refund: 2, cancel: 3 };
+    if (rank[left.command] !== rank[right.command]) return rank[left.command] - rank[right.command];
+    return left.sourceEventId < right.sourceEventId ? -1 : left.sourceEventId > right.sourceEventId ? 1 : 0;
+  });
+  const seed = sorted[0];
+  if (seed === undefined) throw new Error("commerce fold requires an event");
+
+  let placedAt = seed.placedAt;
+  let currency = seed.currency;
+  let payment: PaymentState = "UNKNOWN";
+  let compliance: ComplianceState = "UNKNOWN";
+  let stock: StockState = "unallocated";
+  let fulfillment: FulfillmentState = "held";
+  let label: LabelState = "none";
+  let totals = seed.totals;
+  let verificationDetail: CommerceEvidence = { ...UNKNOWN_EVIDENCE };
+  let paymentVersion = 0;
+  let fulfillmentVersion = 0;
+  let detailVersion = 0;
+
+  for (const event of sorted) {
+    if (event.eventVersion >= detailVersion) {
+      placedAt = event.placedAt;
+      currency = event.currency;
+      compliance = event.compliance;
+      label = event.label;
+      totals = event.totals;
+      verificationDetail = event.verificationDetail;
+      stock = event.stock;
+      detailVersion = event.eventVersion;
+    }
+    if (event.command === "observe" && event.eventVersion >= paymentVersion) {
+      payment = event.payment;
+      paymentVersion = event.eventVersion;
+    }
+    if (event.command === "observe" && event.eventVersion >= fulfillmentVersion) {
+      fulfillment = event.fulfillment;
+      fulfillmentVersion = event.eventVersion;
+    }
+    if (event.command === "capture" && event.eventVersion >= paymentVersion) {
+      payment = "captured";
+      paymentVersion = event.eventVersion;
+    }
+    if (event.command === "refund" && event.eventVersion >= paymentVersion) {
+      const decision = decideCommerceCommand({
+        command: "refund",
+        payment,
+        stock,
+        fulfillment,
+        label,
+        evidence: verificationDetail,
+        providerOutcome: null,
+      });
+      if (decision.admit) payment = "refunded";
+      else if (decision.reason === "reconcile") payment = "refund_unknown";
+      paymentVersion = event.eventVersion;
+    }
+    if (event.command === "cancel" && event.eventVersion >= fulfillmentVersion) {
+      const decision = decideCommerceCommand({
+        command: "cancel",
+        payment,
+        stock,
+        fulfillment,
+        label,
+        evidence: verificationDetail,
+        providerOutcome: null,
+      });
+      if (decision.admit) {
+        fulfillment = "cancelled";
+        fulfillmentVersion = event.eventVersion;
+        if (decision.releaseReservation) stock = "released";
+        if (
+          event.eventVersion >= paymentVersion &&
+          payment !== "refunded" &&
+          payment !== "refund_unknown" &&
+          payment !== "refund_requested"
+        ) {
+          payment = "voided";
+          paymentVersion = event.eventVersion;
+        }
+      }
+    }
+  }
+
+  const eventVersion = sorted.reduce((max, event) => Math.max(max, event.eventVersion), 1);
+  return {
+    orderId: seed.orderId,
+    source: seed.source,
+    sourceOrderId: seed.sourceOrderId,
+    placedAt,
+    currency,
+    payment,
+    compliance,
+    stock,
+    fulfillment,
+    label,
+    totals,
+    verificationDetail,
+    eventVersion,
+    amountMinor: totals.totalMinor,
+  };
+}

package/apps/storefront/src/lib/apps/orders/ordersStore.ts

@@ -10,7 +10,22 @@
  * `AppRegistryService` uses, so this runs unchanged against real D1 in the
  * Worker and an in-memory `node:sqlite` in tests.
  */
-import type { Queryable } from "../../d1/catalog.js";
+import type { Queryable, QueryStatement } from "../../d1/catalog.js";
+import {
+  canonicalJson,
+  idempotencyKey,
+  paginateOrders,
+  sha256Hex,
+  type CommerceStage,
+  type PaymentState,
+} from "@tot/public-runtime";
+import {
+  foldCommerceEvents,
+  packCommercePayload,
+  type CommerceSnapshot,
+  type CommerceSourceEvent,
+  type StoredCommercePayload,
+} from "./orderMapper.js";
 
 export type OrderStatus = "created" | "fulfilled" | "refunded" | "cancelled";
 
@@ -179,3 +194,318 @@ export class OrdersStore {
     return row ? toDomain(row) : null;
   }
 }
+
+interface CommerceOrderRow {
+  tenant_id: string;
+  stage: string;
+  order_id: string;
+  source: string;
+  source_order_id: string;
+  currency: string;
+  placed_at: string;
+  payment_state: PaymentState;
+  compliance_state: CommerceSnapshot["compliance"];
+  stock_state: CommerceSnapshot["stock"];
+  fulfillment_state: CommerceSnapshot["fulfillment"];
+  label_state: CommerceSnapshot["label"];
+  amount_minor: number;
+  event_version: number;
+}
+
+export interface CommerceOrderQueryRow {
+  id: string;
+  placedAt: string;
+  payment: PaymentState;
+  fulfillment: CommerceSnapshot["fulfillment"];
+  amountMinor: number;
+  eventVersion: number;
+}
+
+export interface CommerceAggregate {
+  count: number;
+  amountMinor: number;
+  byPayment: Partial<Record<PaymentState, number>>;
+}
+
+export interface CommitCommerceInput {
+  tenantId: string;
+  stage: CommerceStage;
+  event: CommerceSourceEvent;
+  now: string;
+  replay?: { issuer: string; jti: string };
+}
+
+export type CommitCommerceResult =
+  | { ok: true; duplicate: boolean; snapshot: CommerceSnapshot; outboxId: string }
+  | { ok: false; reason: "replay" };
+
+async function atomic(db: Queryable, statements: readonly QueryStatement[]): Promise<void> {
+  if (typeof db.batch === "function") {
+    await db.batch(statements);
+    return;
+  }
+  await db.exec("BEGIN");
+  try {
+    for (const statement of statements) await db.run(statement.sql, ...(statement.params ?? []));
+    await db.exec("COMMIT");
+  } catch (error) {
+    await db.exec("ROLLBACK");
+    throw error;
+  }
+}
+
+function constraintTable(error: unknown): string | null {
+  if (!(error instanceof Error)) return null;
+  const match = /scrappy_[a-z_]+/.exec(error.message);
+  return match ? match[0] : null;
+}
+
+/** Durable commerce projection. Order, inbox, outbox, and caller replay commit together. */
+export class ScrappyOrderLedger {
+  constructor(private readonly db: Queryable) {}
+
+  async commit(input: CommitCommerceInput): Promise<CommitCommerceResult> {
+    const { tenantId, stage, event, now } = input;
+    if (input.replay) {
+      const seen = await this.db.first<{ jti: string }>(
+        `SELECT jti FROM scrappy_caller_replay WHERE tenant_id = ? AND stage = ? AND issuer = ? AND jti = ?`,
+        tenantId,
+        stage,
+        input.replay.issuer,
+        input.replay.jti,
+      );
+      if (seen) return { ok: false, reason: "replay" };
+    }
+
+    const existing = await this.db.first<{ outbox_id: string; payload: string }>(
+      `SELECT outbox_id, payload FROM scrappy_commerce_outbox
+        WHERE tenant_id = ? AND stage = ? AND source = ? AND source_event_id = ?`,
+      tenantId,
+      stage,
+      event.source,
+      event.sourceEventId,
+    );
+    if (existing) {
+      if (input.replay) {
+        try {
+          await this.insertReplay(input);
+        } catch (error) {
+          if (constraintTable(error) === "scrappy_caller_replay") return { ok: false, reason: "replay" };
+          throw error;
+        }
+      }
+      const snapshot = await this.readSnapshot(tenantId, stage, event.orderId, event);
+      return { ok: true, duplicate: true, snapshot, outboxId: existing.outbox_id };
+    }
+
+    const priorRows = await this.db.all<{ payload: string }>(
+      `SELECT payload FROM scrappy_commerce_outbox WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+      tenantId,
+      stage,
+      event.orderId,
+    );
+    const prior: CommerceSourceEvent[] = [];
+    for (const row of priorRows) {
+      const parsed = JSON.parse(row.payload) as StoredCommercePayload;
+      prior.push(parsed.source);
+    }
+    const snapshot = foldCommerceEvents([...prior, event]);
+    const packed = packCommercePayload(event, snapshot);
+    const key = idempotencyKey(tenantId, stage, event.source, event.sourceEventId);
+    const outboxId = (await sha256Hex(key)).slice(0, 32);
+    const digest = await sha256Hex(canonicalJson(event));
+    const statements: QueryStatement[] = [];
+    if (input.replay) {
+      statements.push({
+        sql: `INSERT INTO scrappy_caller_replay (tenant_id, stage, issuer, jti, seen_at) VALUES (?,?,?,?,?)`,
+        params: [tenantId, stage, input.replay.issuer, input.replay.jti, now],
+      });
+    }
+    statements.push(
+      {
+        sql: `INSERT INTO scrappy_commerce_orders (
+                tenant_id, stage, order_id, source, source_order_id, currency, placed_at,
+                payment_state, compliance_state, stock_state, fulfillment_state, label_state,
+                amount_minor, event_version
+              ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+              ON CONFLICT(tenant_id, stage, order_id) DO UPDATE SET
+                source = excluded.source,
+                source_order_id = excluded.source_order_id,
+                currency = excluded.currency,
+                placed_at = excluded.placed_at,
+                payment_state = excluded.payment_state,
+                compliance_state = excluded.compliance_state,
+                stock_state = excluded.stock_state,
+                fulfillment_state = excluded.fulfillment_state,
+                label_state = excluded.label_state,
+                amount_minor = excluded.amount_minor,
+                event_version = excluded.event_version`,
+        params: [
+          tenantId,
+          stage,
+          snapshot.orderId,
+          snapshot.source,
+          snapshot.sourceOrderId,
+          snapshot.currency,
+          snapshot.placedAt,
+          snapshot.payment,
+          snapshot.compliance,
+          snapshot.stock,
+          snapshot.fulfillment,
+          snapshot.label,
+          snapshot.amountMinor,
+          snapshot.eventVersion,
+        ],
+      },
+      {
+        sql: `INSERT INTO scrappy_commerce_inbox (
+                tenant_id, stage, source, source_event_id, event_version, idempotency_key, payload_digest, received_at
+              ) VALUES (?,?,?,?,?,?,?,?)`,
+        params: [tenantId, stage, event.source, event.sourceEventId, event.eventVersion, key, digest, now],
+      },
+      {
+        sql: `INSERT INTO scrappy_commerce_outbox (
+                outbox_id, tenant_id, stage, order_id, source, source_event_id, event_version,
+                event_type, payload, available_at, attempt_count, state
+              ) VALUES (?,?,?,?,?,?,?,?,?,?,0,'pending')`,
+        params: [
+          outboxId,
+          tenantId,
+          stage,
+          snapshot.orderId,
+          event.source,
+          event.sourceEventId,
+          event.eventVersion,
+          "order.observed",
+          JSON.stringify(packed),
+          now,
+        ],
+      },
+    );
+
+    try {
+      await atomic(this.db, statements);
+    } catch (error) {
+      const table = constraintTable(error);
+      if (table === "scrappy_caller_replay") return { ok: false, reason: "replay" };
+      if (table === "scrappy_commerce_inbox" || table === "scrappy_commerce_outbox") {
+        const raced = await this.db.first<{ outbox_id: string }>(
+          `SELECT outbox_id FROM scrappy_commerce_outbox
+            WHERE tenant_id = ? AND stage = ? AND source = ? AND source_event_id = ?`,
+          tenantId,
+          stage,
+          event.source,
+          event.sourceEventId,
+        );
+        if (raced) {
+          const snapshotNow = await this.readSnapshot(tenantId, stage, event.orderId, event);
+          return { ok: true, duplicate: true, snapshot: snapshotNow, outboxId: raced.outbox_id };
+        }
+      }
+      throw error;
+    }
+    return { ok: true, duplicate: false, snapshot, outboxId };
+  }
+
+  async queryOrders(
+    tenantId: string,
+    stage: CommerceStage,
+    limit: number,
+    cursor: string | null,
+  ): Promise<{ orders: CommerceOrderQueryRow[]; nextCursor: string | null; invalidCursor: boolean }> {
+    const rows = await this.db.all<CommerceOrderRow>(
+      `SELECT * FROM scrappy_commerce_orders WHERE tenant_id = ? AND stage = ?`,
+      tenantId,
+      stage,
+    );
+    const orders = rows.map((row) => ({
+      id: row.order_id,
+      placedAt: row.placed_at,
+      payment: row.payment_state,
+      fulfillment: row.fulfillment_state,
+      amountMinor: row.amount_minor,
+      eventVersion: row.event_version,
+    }));
+    return paginateOrders(orders, limit, cursor);
+  }
+
+  async aggregateOrders(tenantId: string, stage: CommerceStage): Promise<CommerceAggregate> {
+    const rows = await this.db.all<{ payment_state: PaymentState; n: number; amount: number | null }>(
+      `SELECT payment_state, COUNT(*) AS n, SUM(amount_minor) AS amount
+         FROM scrappy_commerce_orders WHERE tenant_id = ? AND stage = ?
+        GROUP BY payment_state`,
+      tenantId,
+      stage,
+    );
+    const byPayment: Partial<Record<PaymentState, number>> = {};
+    let count = 0;
+    let amountMinor = 0;
+    for (const row of rows) {
+      const n = Number(row.n);
+      byPayment[row.payment_state] = n;
+      count += n;
+      amountMinor += Number(row.amount ?? 0);
+    }
+    return { count, amountMinor, byPayment };
+  }
+
+  /** Reset one outbox row for this tenant and stage. Does not write another order. */
+  async replayOutbox(tenantId: string, stage: CommerceStage, outboxId: string, now: string): Promise<boolean> {
+    const row = await this.db.first<{ outbox_id: string }>(
+      `SELECT outbox_id FROM scrappy_commerce_outbox WHERE outbox_id = ? AND tenant_id = ? AND stage = ?`,
+      outboxId,
+      tenantId,
+      stage,
+    );
+    if (!row) return false;
+    await this.db.run(
+      `UPDATE scrappy_commerce_outbox
+          SET state = 'pending', available_at = ?, attempt_count = 0
+        WHERE outbox_id = ? AND tenant_id = ? AND stage = ?`,
+      now,
+      outboxId,
+      tenantId,
+      stage,
+    );
+    return true;
+  }
+
+  async readOrder(tenantId: string, stage: CommerceStage, orderId: string): Promise<CommerceOrderRow | null> {
+    return this.db.first<CommerceOrderRow>(
+      `SELECT * FROM scrappy_commerce_orders WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+      tenantId,
+      stage,
+      orderId,
+    );
+  }
+
+  private async insertReplay(input: CommitCommerceInput): Promise<void> {
+    if (!input.replay) return;
+    await atomic(this.db, [
+      {
+        sql: `INSERT INTO scrappy_caller_replay (tenant_id, stage, issuer, jti, seen_at) VALUES (?,?,?,?,?)`,
+        params: [input.tenantId, input.stage, input.replay.issuer, input.replay.jti, input.now],
+      },
+    ]);
+  }
+
+  private async readSnapshot(
+    tenantId: string,
+    stage: CommerceStage,
+    orderId: string,
+    event: CommerceSourceEvent,
+  ): Promise<CommerceSnapshot> {
+    const rows = await this.db.all<{ payload: string }>(
+      `SELECT payload FROM scrappy_commerce_outbox WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+      tenantId,
+      stage,
+      orderId,
+    );
+    const events: CommerceSourceEvent[] = [];
+    for (const row of rows) {
+      const parsed = JSON.parse(row.payload) as StoredCommercePayload;
+      if (parsed.source) events.push(parsed.source);
+    }
+    return foldCommerceEvents(events.length > 0 ? events : [event]);
+  }
+}

package/apps/storefront/src/lib/webhooks/deliveryEngine.ts

@@ -22,11 +22,13 @@
  * public target can't 302 its way to an internal one; either case never
  * reads as `delivered`.
  */
-import { WebhookDeliveryStore, type WebhookDelivery, type WebhookEvent, type WebhookTopic } from "./deliveryStore.js";
+import { WebhookDeliveryStore, ScrappyCommerceOutbox, type CommerceOutboxDue, type WebhookDelivery, type WebhookEvent, type WebhookTopic } from "./deliveryStore.js";
 import type { AppInstall } from "../apps/registryService.js";
 import { buildCloudEventEnvelope } from "./events.js";
 import { computeBackoffDelaySeconds, MAX_DELIVERY_ATTEMPTS, type AttemptOutcome } from "./dispatcher.js";
 import { validateWebhookEndpoint } from "./endpointGuard.js";
+import { COMMERCE_SCHEDULER } from "@tot/public-runtime";
+import type { Queryable } from "../d1/catalog.js";
 
 /** Bounded per-attempt timeout — a hung receiver must not hold a dispatcher slot open indefinitely. */
 const DEFAULT_TIMEOUT_MS = 10_000;
@@ -277,3 +279,110 @@ async function postWithTimeout(
     clearTimeout(timer);
   }
 }
+
+const COMMERCE_PRIVATE_KEYS = new Set([
+  "customer",
+  "customerEmail",
+  "customerName",
+  "email",
+  "phone",
+  "line1",
+  "line2",
+  "postalCode",
+  "shippingAddress",
+  "billingAddress",
+  "address",
+  "firstName",
+  "lastName",
+  "name",
+]);
+
+function commercePayloadHasPrivateIdentity(value: unknown): boolean {
+  if (value === null || typeof value !== "object") return false;
+  if (Array.isArray(value)) return value.some((item) => commercePayloadHasPrivateIdentity(item));
+  return Object.entries(value as Record<string, unknown>).some(
+    ([key, child]) => COMMERCE_PRIVATE_KEYS.has(key) || commercePayloadHasPrivateIdentity(child),
+  );
+}
+
+function publicCommercePayload(payload: string): Record<string, unknown> | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(payload);
+  } catch {
+    return null;
+  }
+  if (commercePayloadHasPrivateIdentity(parsed)) return null;
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const body = parsed as Record<string, unknown>;
+  const event = body.public;
+  if (event === null || typeof event !== "object" || Array.isArray(event)) return null;
+  if ((event as Record<string, unknown>).type !== "order.observed") return null;
+  return event as Record<string, unknown>;
+}
+
+export type CommerceSweepResult =
+  | { ok: true; delivered: number; retried: number; dead: number }
+  | { ok: false; reason: "scheduler" };
+
+export type CommerceDeliver = (event: Record<string, unknown>) => Promise<void>;
+
+/**
+ * Deliver due commerce outbox rows. A scheduler other than the declared alarm
+ * leaves every row pending.
+ */
+export async function sweepDurableCommerce(input: {
+  db: Queryable;
+  scheduler: string;
+  now: string;
+  deliver?: CommerceDeliver;
+}): Promise<CommerceSweepResult> {
+  if (input.scheduler !== COMMERCE_SCHEDULER) return { ok: false, reason: "scheduler" };
+  const port = new ScrappyCommerceOutbox(input.db);
+  const due = await port.due(input.now);
+  let delivered = 0;
+  let retried = 0;
+  let dead = 0;
+  const tenants: { tenantId: string; stage: string }[] = [];
+  const seenTenant = (tenantId: string, stage: string) => {
+    if (!tenants.some((item) => item.tenantId === tenantId && item.stage === stage)) {
+      tenants.push({ tenantId, stage });
+    }
+  };
+  for (const row of due) {
+    seenTenant(row.tenant_id, row.stage);
+    const outcome = await settleCommerceRow(port, row, input.now, input.deliver);
+    if (outcome === "delivered") delivered += 1;
+    else if (outcome === "retried") retried += 1;
+    else dead += 1;
+  }
+  for (const tenant of tenants) await port.noteCursor(tenant.tenantId, tenant.stage, input.now);
+  return { ok: true, delivered, retried, dead };
+}
+
+async function settleCommerceRow(
+  port: ScrappyCommerceOutbox,
+  row: CommerceOutboxDue,
+  now: string,
+  deliver: CommerceDeliver | undefined,
+): Promise<"delivered" | "retried" | "dead"> {
+  const event = publicCommercePayload(row.payload);
+  if (!event) {
+    await port.markDead(row.outbox_id);
+    return "dead";
+  }
+  try {
+    if (deliver) await deliver(event);
+    await port.markDelivered(row.outbox_id);
+    return "delivered";
+  } catch {
+    const next = row.attempt_count + 1;
+    if (next >= MAX_DELIVERY_ATTEMPTS) {
+      await port.markDead(row.outbox_id, next);
+      return "dead";
+    }
+    const availableAt = new Date(Date.parse(now) + computeBackoffDelaySeconds(next) * 1000).toISOString();
+    await port.markRetry(row.outbox_id, next, availableAt);
+    return "retried";
+  }
+}

package/apps/storefront/src/lib/webhooks/deliveryStore.ts

@@ -665,3 +665,73 @@ export class WebhookDeliveryStore {
     return toDomain(await this.mustFindDeliveryRow(deliveryId));
   }
 }
+
+export interface CommerceOutboxDue {
+  outbox_id: string;
+  tenant_id: string;
+  stage: string;
+  payload: string;
+  attempt_count: number;
+  available_at: string;
+}
+
+/** Due commerce outbox rows. The order ledger owns the insert; this port owns sweep progress. */
+export class ScrappyCommerceOutbox {
+  constructor(private readonly db: Queryable) {}
+
+  async due(now: string): Promise<CommerceOutboxDue[]> {
+    const rows = await this.db.all<CommerceOutboxDue>(
+      `SELECT outbox_id, tenant_id, stage, payload, attempt_count, available_at
+         FROM scrappy_commerce_outbox
+        WHERE state = 'pending' AND available_at <= ?
+        ORDER BY available_at`,
+      now,
+    );
+    return rows.map((row) => ({ ...row, attempt_count: Number(row.attempt_count) }));
+  }
+
+  async markDelivered(outboxId: string): Promise<void> {
+    await this.db.run(
+      `UPDATE scrappy_commerce_outbox SET state = 'delivered' WHERE outbox_id = ? AND state = 'pending'`,
+      outboxId,
+    );
+  }
+
+  async markRetry(outboxId: string, attemptCount: number, availableAt: string): Promise<void> {
+    await this.db.run(
+      `UPDATE scrappy_commerce_outbox
+          SET state = 'pending', attempt_count = ?, available_at = ?
+        WHERE outbox_id = ? AND state = 'pending'`,
+      attemptCount,
+      availableAt,
+      outboxId,
+    );
+  }
+
+  async markDead(outboxId: string, attemptCount?: number): Promise<void> {
+    if (attemptCount === undefined) {
+      await this.db.run(
+        `UPDATE scrappy_commerce_outbox SET state = 'dead' WHERE outbox_id = ? AND state = 'pending'`,
+        outboxId,
+      );
+      return;
+    }
+    await this.db.run(
+      `UPDATE scrappy_commerce_outbox
+          SET state = 'dead', attempt_count = ?
+        WHERE outbox_id = ? AND state = 'pending'`,
+      attemptCount,
+      outboxId,
+    );
+  }
+
+  async noteCursor(tenantId: string, stage: string, cursor: string): Promise<void> {
+    await this.db.run(
+      `INSERT INTO scrappy_sweep_cursor (tenant_id, stage, cursor) VALUES (?,?,?)
+       ON CONFLICT(tenant_id, stage) DO UPDATE SET cursor = excluded.cursor`,
+      tenantId,
+      stage,
+      cursor,
+    );
+  }
+}

package/apps/storefront/src/lib/webhooks/getDispatcher.ts

@@ -15,15 +15,16 @@
  * design-resolution + entry-wiring context).
  */
 import { WebhookDeliveryStore } from "./deliveryStore.js";
-import { attemptDelivery } from "./deliveryEngine.js";
+import { attemptDelivery, sweepDurableCommerce, type CommerceDeliver, type CommerceSweepResult } from "./deliveryEngine.js";
 import { InMemoryDispatcher, type AttemptDeliveryFn, type WebhookDispatcher } from "./dispatcher.js";
 import { CloudflareQueueDispatcher, type CloudflareQueueSender } from "./cloudflareQueueDispatcher.js";
 import { AppRegistryService } from "../apps/registryService.js";
 import { D1CredentialStore } from "../apps/credentials.js";
 import { DEFAULT_APP_GATEWAY_KID, APP_GATEWAY_KID_ENV } from "../apps/gatewayKeys.js";
 import { json } from "../apps/registryAccess.js";
-import { fromD1 } from "../d1/catalog.js";
+import { fromD1, type Queryable } from "../d1/catalog.js";
 import { readD1, readEnv, readQueue } from "../env.js";
+import { COMMERCE_SCHEDULER } from "@tot/public-runtime";
 
 /** Binding name `getDispatcher()` checks to pick the Cloudflare Queues adapter. Not yet declared in `wrangler.toml`. */
 export const WEBHOOK_QUEUE_BINDING = "WEBHOOK_DELIVERY_QUEUE";
@@ -47,3 +48,29 @@ export async function getDispatcher(): Promise<WebhookDispatcher | Response> {
   if (queueSender) return new CloudflareQueueDispatcher(queueSender);
   return new InMemoryDispatcher(attempt);
 }
+
+/**
+ * Commerce work is already durable when it is saved. This dispatcher only
+ * sweeps that outbox, and only when the declared scheduler is configured.
+ * It never falls back to an in-memory queue.
+ */
+export class CommerceAlarmDispatcher {
+  constructor(
+    private readonly db: Queryable,
+    private readonly scheduler: string,
+  ) {}
+
+  async enqueue(): Promise<void> {}
+
+  sweep(now: string, deliver?: CommerceDeliver): Promise<CommerceSweepResult> {
+    return sweepDurableCommerce({ db: this.db, scheduler: this.scheduler, now, deliver });
+  }
+}
+
+export async function getReliableDispatcher(): Promise<CommerceAlarmDispatcher | Response> {
+  const scheduler = await readEnv("SCRAPPY_COMMERCE_SCHEDULER");
+  if (scheduler !== COMMERCE_SCHEDULER) return json({ error: "commerce scheduler not configured" }, 503);
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  if (!d1) return json({ error: "commerce scheduler not configured" }, 503);
+  return new CommerceAlarmDispatcher(fromD1(d1), scheduler);
+}

package/package.json

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