@tokenoftrust/storefront-runner 2.4.53 → 2.4.55

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,
+  };
+}