@tokenoftrust/storefront-runner 2.4.47 → 2.4.49

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

@@ -1,19 +1,15 @@
 /**
- * Order READ DTO — the FROZEN v1 contract shape the storefront consumes from
- * the checkout order API's `GET /commerce/orders[/:orderId]` (card 8585). Kept in
- * `@tot/public-runtime` (types only, no secrets, edge-safe) so the server-side
- * order client, the Orders admin route, and the view-model mapping
- * all code against one source of truth.
+ * Admin order-list DTO plus the commerce contract.
  *
- * Authoritative API shape lives with the checkout order service; this file
- * freezes the storefront-facing v1 DTO.
+ * `CheckoutOrder*` is the list shape the orders workspace reads. Null
+ * verification is absent evidence, not clearance. It is not the commerce
+ * state machine and it is not the measured Foxy read body.
  *
- * READ-ONLY (scope-locks): no write/mutation shapes here. Two fields are
- * ENRICHED-later by U4 (the tot20 identity/age join) and are `null`/`[]` until
- * then — `verification` (summary) and `verificationDetail` (detail). Consumers
- * MUST tolerate that (render risk "pending", readiness/evidence empty) so no
- * contract change is needed when U4 lands.
+ * Commerce money is integer minor units. Payment, compliance, stock,
+ * fulfillment, and label are independent. Public events carry no customer
+ * identifier and no address. Caller admission is asymmetric JWKS only.
  */
+import { sha256Hex } from "./hash.js";
 
 /** Payment state of an order. */
 export type CheckoutOrderPayment = "authorized" | "captured" | "refunded";
@@ -49,13 +45,12 @@ export interface CheckoutOrderSummary {
   /** Why the order is held, or null. */
   blocker: string | null;
   /**
-   * Identity/age verification summary — ENRICHED by U4 (tot20 join). `null` from
-   * U1; consumers render risk as "pending" until it is filled.
+   * Verification summary. Null is absent evidence, not a pass and not clearance.
    */
   verification: CheckoutOrderVerification | null;
 }
 
-/** U4-filled verification summary (shape reserved; opaque to U1/U2/U3). */
+/** Verification summary carried on the admin list. Null stays null. */
 export interface CheckoutOrderVerification {
   riskLevel?: string;
   [k: string]: unknown;
@@ -87,7 +82,7 @@ export interface CheckoutOrderShippingAddress {
   name: string;
 }
 
-/** U4-filled per-order verification detail; `readinessChecks`/`evidenceTimeline` empty from U1. */
+/** Per-order verification detail. An empty timeline is not clearance. */
 export interface CheckoutOrderVerificationDetail {
   readinessChecks: unknown[];
   evidenceTimeline: unknown[];
@@ -135,3 +130,594 @@ export interface CheckoutOrderListFilters {
   /** Opaque cursor from a prior page's `nextCursor`. */
   cursor?: string;
 }
+
+/**
+ * Measured `GET /commerce/orders` body at Foxy `origin/main`
+ * `0d6037d563f5f33a057e7797b925455cefd1d90f` (`buildOrderPayload`).
+ * Offset paging. Not a cursor page. No translator into `CheckoutOrder*`.
+ */
+export interface MeasuredFoxyOrderRead {
+  source: "foxycart";
+  externalId: string;
+  externalNumber: string;
+  orderedAt: string;
+  currency: string;
+  status: string;
+  customerEmail?: string;
+  customerName?: string;
+  subtotal: number;
+  shipping: number;
+  tax: number;
+  total: number;
+  shippingAddress: MeasuredFoxyAddress | null;
+  billingAddress: MeasuredFoxyAddress | null;
+  paymentRef: string;
+  paymentMetadata: Record<string, unknown>;
+  lineItems: readonly MeasuredFoxyLine[];
+  exciseTax: { amount: number; status: string | null };
+}
+
+export interface MeasuredFoxyAddress {
+  firstName: string;
+  lastName: string;
+  company: string;
+  line1: string;
+  line2: string | null;
+  locality: string;
+  regionCode: string;
+  postalCode: string;
+  countryCode: string;
+}
+
+export interface MeasuredFoxyLine {
+  sku: string;
+  name: string;
+  quantity: number;
+  unitPrice: number;
+  totalPrice?: number;
+  options: Record<string, unknown>;
+  flavor?: string;
+}
+
+export interface MeasuredFoxyOrderList {
+  orders: readonly MeasuredFoxyOrderRead[];
+  limit: number;
+  offset: number;
+  total: number;
+  hasMore: boolean;
+}
+
+export const COMMERCE_STAGES = ["preview", "publication"] as const;
+export type CommerceStage = (typeof COMMERCE_STAGES)[number];
+
+export const PAYMENT_STATES = [
+  "UNKNOWN",
+  "pending",
+  "authorized",
+  "captured",
+  "capture_unknown",
+  "voided",
+  "refund_requested",
+  "refunded",
+  "refund_unknown",
+] as const;
+export type PaymentState = (typeof PAYMENT_STATES)[number];
+
+export const COMPLIANCE_STATES = ["UNKNOWN", "pending", "fresh", "stale", "unreadable", "refused"] as const;
+export type ComplianceState = (typeof COMPLIANCE_STATES)[number];
+
+export const STOCK_STATES = ["UNKNOWN", "unallocated", "reserved", "confirmed", "released", "expired"] as const;
+export type StockState = (typeof STOCK_STATES)[number];
+
+export const FULFILLMENT_STATES = ["UNKNOWN", "held", "ready", "handed_off", "cancelled"] as const;
+export type FulfillmentState = (typeof FULFILLMENT_STATES)[number];
+
+export const LABEL_STATES = [
+  "UNKNOWN",
+  "none",
+  "intent",
+  "purchased",
+  "printed",
+  "void_requested",
+  "voided",
+] as const;
+export type LabelState = (typeof LABEL_STATES)[number];
+
+export const EVIDENCE_STATES = ["fresh", "UNKNOWN", "stale", "unreadable", "absent"] as const;
+export type EvidenceState = (typeof EVIDENCE_STATES)[number];
+
+export const PROVIDER_OUTCOMES = ["intent", "accepted", "unknown", "voided", "refunded"] as const;
+export type ProviderOutcome = (typeof PROVIDER_OUTCOMES)[number];
+
+export const COMMERCE_SCHEDULER = "tenant-pipeline-alarm";
+
+/** Same path patterns as `WORKER_TIER3_PATH_PATTERNS`. Both providers, both phases. */
+export const WORKER_ROUTE_PATTERNS = [
+  "/api/*",
+  "/auth/*",
+  "/dashboard",
+  "/dashboard/*",
+  "/search",
+  "/cart",
+] as const;
+
+export const SCRAPPY_ORDERS_FIXTURE_DOMAIN = "scrappy-orders-v1";
+export const FINAL_CART_DOMAIN = "scrappy-final-cart-v1";
+export const CALLER_TOKEN_MAX_LIFETIME_MS = 15 * 60 * 1000;
+
+export interface CommerceEvidence {
+  verification: EvidenceState;
+  tax: EvidenceState;
+  risk: EvidenceState;
+  stock: EvidenceState;
+}
+
+export interface MinorTotals {
+  subtotalMinor: number;
+  shippingMinor: number;
+  taxMinor: number;
+  totalMinor: number;
+}
+
+export interface PublicCommerceEvent {
+  eventVersion: number;
+  type: "order.observed";
+  orderId: string;
+  placedAt: string;
+  currency: string;
+  payment: PaymentState;
+  compliance: ComplianceState;
+  stock: StockState;
+  fulfillment: FulfillmentState;
+  label: LabelState;
+  totals: MinorTotals;
+  verificationDetail: CommerceEvidence;
+}
+
+export type CommerceRole = "owner" | "caller" | "denied";
+
+export interface CommerceActor {
+  role: CommerceRole;
+  tenantId: string;
+  stage: CommerceStage;
+}
+
+export interface CommerceScope {
+  tenantId: string;
+  stage: CommerceStage;
+}
+
+export type CommerceCommand =
+  | "authorize-final-cart"
+  | "allocate"
+  | "refund"
+  | "cancel"
+  | "purchase-label"
+  | "print-label"
+  | "hand-off"
+  | "reconcile";
+
+export interface CommerceCommandInput {
+  command: CommerceCommand;
+  payment: PaymentState;
+  stock: StockState;
+  fulfillment: FulfillmentState;
+  label: LabelState;
+  evidence: CommerceEvidence;
+  providerOutcome: ProviderOutcome | null;
+}
+
+export interface CommerceCommandDecision {
+  admit: boolean;
+  reason: "admitted" | "evidence" | "payment" | "stock" | "fulfillment" | "label" | "reconcile" | "reuse";
+  restock: false;
+  releaseReservation: boolean;
+  blindRepurchase: false;
+}
+
+export interface FinalCartLine {
+  sku: string;
+  quantity: number;
+  unitMinor: number;
+}
+
+export interface FinalCartBinding {
+  tenantId: string;
+  stage: CommerceStage;
+  currency: string;
+  lines: readonly FinalCartLine[];
+  destinationDigest: string;
+  verificationExpiresAt: string;
+  taxExpiresAt: string;
+}
+
+export interface AsymmetricCallerToken {
+  scheme: "asymmetric-jwks";
+  signatureValid: boolean;
+  kid: string;
+  issuer: string;
+  audience: string;
+  expiresAt: string;
+  jti: string;
+  tenantId: string;
+  stage: CommerceStage;
+}
+
+export type CallerToken = AsymmetricCallerToken | { scheme: "shared-secret" };
+
+export type CallerTokenRefusal =
+  | "shared-secret"
+  | "signature"
+  | "kid"
+  | "issuer"
+  | "audience"
+  | "expired"
+  | "lifetime"
+  | "jti"
+  | "tenant"
+  | "stage";
+
+export function evidencePermitsRelease(evidence: CommerceEvidence): boolean {
+  return (
+    evidence.verification === "fresh" &&
+    evidence.tax === "fresh" &&
+    evidence.risk === "fresh" &&
+    evidence.stock === "fresh"
+  );
+}
+
+export function paymentIsCaptured(payment: PaymentState): boolean {
+  return payment === "captured";
+}
+
+export function fulfillmentIsHandedOff(fulfillment: FulfillmentState): boolean {
+  return fulfillment === "handed_off";
+}
+
+export function assertMinor(value: number, label: string): number {
+  if (!Number.isSafeInteger(value)) throw new Error(`${label} is not a minor-unit integer`);
+  return value;
+}
+
+export function sumMinor(values: readonly number[]): number {
+  let total = 0;
+  for (const value of values) {
+    assertMinor(value, "amount");
+    total += value;
+  }
+  if (!Number.isSafeInteger(total)) throw new Error("minor-unit sum overflowed");
+  return total;
+}
+
+export function totalsMatch(totals: MinorTotals): boolean {
+  return (
+    sumMinor([totals.subtotalMinor, totals.shippingMinor, totals.taxMinor]) ===
+    assertMinor(totals.totalMinor, "totalMinor")
+  );
+}
+
+export function canonicalJson(value: unknown): string {
+  if (value === undefined) throw new Error("canonical JSON rejects undefined");
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+  const record = value as Record<string, unknown>;
+  const keys = Object.keys(record).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+}
+
+export async function digestCommerceFixture(document: Record<string, unknown>): Promise<string> {
+  const rest: Record<string, unknown> = {};
+  for (const key of Object.keys(document)) {
+    if (key !== "digest") rest[key] = document[key];
+  }
+  return sha256Hex(`${SCRAPPY_ORDERS_FIXTURE_DOMAIN}\n${canonicalJson(rest)}`);
+}
+
+export function idempotencyKey(
+  tenantId: string,
+  stage: CommerceStage,
+  source: string,
+  sourceEventId: string,
+): string {
+  return `${tenantId}\n${stage}\n${source}\n${sourceEventId}`;
+}
+
+export function allocationIdentity(input: {
+  tenantId: string;
+  stage: CommerceStage;
+  orderId: string;
+  sku: string;
+  locationId: string;
+}): string {
+  return `${input.tenantId}\n${input.stage}\n${input.orderId}\n${input.sku}\n${input.locationId}`;
+}
+
+function deny(
+  reason: CommerceCommandDecision["reason"],
+  releaseReservation = false,
+): CommerceCommandDecision {
+  return { admit: false, reason, restock: false, releaseReservation, blindRepurchase: false };
+}
+
+function allow(releaseReservation = false): CommerceCommandDecision {
+  return { admit: true, reason: "admitted", restock: false, releaseReservation, blindRepurchase: false };
+}
+
+/** Compliance state is not an input. Evidence that is not fresh never clears. */
+export function decideCommerceCommand(input: CommerceCommandInput): CommerceCommandDecision {
+  switch (input.command) {
+    case "reconcile":
+      return allow();
+    case "authorize-final-cart":
+      if (!evidencePermitsRelease(input.evidence)) return deny("evidence");
+      if (input.stock === "UNKNOWN") return deny("stock");
+      if (input.fulfillment === "cancelled") return deny("fulfillment");
+      if (input.payment === "capture_unknown") return deny("reconcile");
+      if (
+        input.payment === "refunded" ||
+        input.payment === "voided" ||
+        input.payment === "refund_requested" ||
+        input.payment === "refund_unknown"
+      ) {
+        return deny("payment");
+      }
+      return allow();
+    case "allocate":
+      if (!evidencePermitsRelease(input.evidence)) return deny("evidence");
+      if (input.stock === "UNKNOWN") return deny("stock");
+      if (input.fulfillment === "cancelled" || input.fulfillment === "handed_off") return deny("fulfillment");
+      return allow();
+    case "refund":
+      if (input.payment === "capture_unknown" || input.payment === "refund_unknown") return deny("reconcile");
+      if (input.payment !== "captured" && input.payment !== "refund_requested") return deny("payment");
+      return allow();
+    case "cancel":
+      if (input.fulfillment === "handed_off" || input.fulfillment === "UNKNOWN" || input.fulfillment === "cancelled") {
+        return deny("fulfillment");
+      }
+      if (input.payment === "capture_unknown") return deny("reconcile");
+      return allow(input.stock === "reserved" || input.stock === "confirmed");
+    case "purchase-label":
+      if (
+        input.label === "UNKNOWN" ||
+        input.label === "intent" ||
+        input.label === "void_requested" ||
+        input.providerOutcome === "unknown" ||
+        input.providerOutcome === "intent"
+      ) {
+        return deny("reconcile");
+      }
+      if (input.label === "purchased" || input.label === "printed") return deny("reuse");
+      if (!evidencePermitsRelease(input.evidence)) return deny("evidence");
+      if (input.payment !== "captured") return deny("payment");
+      if (input.stock !== "confirmed") return deny("stock");
+      if (input.fulfillment !== "ready") return deny("fulfillment");
+      if (input.label !== "none" && input.label !== "voided") return deny("label");
+      return allow();
+    case "print-label":
+      if (input.fulfillment === "cancelled") return deny("fulfillment");
+      if (input.label === "purchased" || input.label === "printed") return allow();
+      return deny("label");
+    case "hand-off":
+      if (input.providerOutcome === "unknown" || input.providerOutcome === "intent") return deny("reconcile");
+      if (!evidencePermitsRelease(input.evidence)) return deny("evidence");
+      if (input.payment !== "captured") return deny("payment");
+      if (input.stock !== "confirmed") return deny("stock");
+      if (input.fulfillment !== "ready") return deny("fulfillment");
+      if (input.label !== "purchased" && input.label !== "printed") return deny("label");
+      return allow();
+    default: {
+      const unreachable: never = input.command;
+      throw new Error(`unknown commerce command ${String(unreachable)}`);
+    }
+  }
+}
+
+export function actorMayCommand(actor: CommerceActor, resource: CommerceScope): boolean {
+  return (
+    (actor.role === "owner" || actor.role === "caller") &&
+    actor.tenantId === resource.tenantId &&
+    actor.stage === resource.stage
+  );
+}
+
+export function actorMayReadPrivate(actor: CommerceActor, resource: CommerceScope): boolean {
+  return actor.role === "owner" && actor.tenantId === resource.tenantId && actor.stage === resource.stage;
+}
+
+export function readOwnerAddress<T>(
+  actor: CommerceActor,
+  resource: CommerceScope,
+  read: () => T,
+): { ok: true; address: T } | { ok: false; reason: "denied" } {
+  if (!actorMayReadPrivate(actor, resource)) return { ok: false, reason: "denied" };
+  return { ok: true, address: read() };
+}
+
+export function admitTrackingRead(input: {
+  actor: CommerceActor;
+  resource: CommerceScope;
+  trackingUrl: string;
+  allowedHosts: readonly string[];
+}): { ok: true } | { ok: false; reason: "denied" | "malformed-url" | "authority" } {
+  if (!actorMayReadPrivate(input.actor, input.resource)) return { ok: false, reason: "denied" };
+  let url: URL;
+  try {
+    url = new URL(input.trackingUrl);
+  } catch {
+    return { ok: false, reason: "malformed-url" };
+  }
+  if (url.protocol !== "https:" || url.username !== "" || url.password !== "") {
+    return { ok: false, reason: "authority" };
+  }
+  if (!input.allowedHosts.includes(url.host)) return { ok: false, reason: "authority" };
+  return { ok: true };
+}
+
+export function publicCommerceEvent(
+  input: {
+    eventVersion: number;
+    orderId: string;
+    placedAt: string;
+    currency: string;
+    payment: PaymentState;
+    compliance: ComplianceState;
+    stock: StockState;
+    fulfillment: FulfillmentState;
+    label: LabelState;
+    totals: MinorTotals;
+    verificationDetail: CommerceEvidence;
+  } & Record<string, unknown>,
+): PublicCommerceEvent {
+  if (!Number.isSafeInteger(input.eventVersion) || input.eventVersion < 1) {
+    throw new Error("eventVersion must be a positive integer");
+  }
+  if (!totalsMatch(input.totals)) throw new Error("totals do not match minor units");
+  return {
+    eventVersion: input.eventVersion,
+    type: "order.observed",
+    orderId: input.orderId,
+    placedAt: input.placedAt,
+    currency: input.currency,
+    payment: input.payment,
+    compliance: input.compliance,
+    stock: input.stock,
+    fulfillment: input.fulfillment,
+    label: input.label,
+    totals: {
+      subtotalMinor: input.totals.subtotalMinor,
+      shippingMinor: input.totals.shippingMinor,
+      taxMinor: input.totals.taxMinor,
+      totalMinor: input.totals.totalMinor,
+    },
+    verificationDetail: {
+      verification: input.verificationDetail.verification,
+      tax: input.verificationDetail.tax,
+      risk: input.verificationDetail.risk,
+      stock: input.verificationDetail.stock,
+    },
+  };
+}
+
+function encodeCursor(order: { placedAt: string; id: string }): string {
+  if (order.placedAt.includes("\n") || order.id.includes("\n")) {
+    throw new Error("cursor fields reject newlines");
+  }
+  const bytes = new TextEncoder().encode(`${order.placedAt}\n${order.id}`);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+}
+
+function decodeCursor(cursor: string): { placedAt: string; id: string } | null {
+  try {
+    const padded = cursor.replaceAll("-", "+").replaceAll("_", "/") + "===".slice((cursor.length + 3) % 4);
+    const binary = atob(padded);
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    const text = new TextDecoder().decode(bytes);
+    const split = text.indexOf("\n");
+    if (split <= 0 || split === text.length - 1) return null;
+    return { placedAt: text.slice(0, split), id: text.slice(split + 1) };
+  } catch {
+    return null;
+  }
+}
+
+export function paginateOrders<T extends { id: string; placedAt: string }>(
+  orders: readonly T[],
+  limit: number,
+  cursor: string | null,
+): { orders: T[]; nextCursor: string | null; invalidCursor: boolean } {
+  if (!Number.isSafeInteger(limit) || limit < 1) throw new Error("limit must be a positive integer");
+  const sorted = [...orders].sort((left, right) => {
+    if (left.placedAt !== right.placedAt) return left.placedAt < right.placedAt ? 1 : -1;
+    if (left.id === right.id) return 0;
+    return left.id < right.id ? 1 : -1;
+  });
+  let start = 0;
+  if (cursor !== null) {
+    const decoded = decodeCursor(cursor);
+    const index = decoded === null ? -1 : sorted.findIndex((order) => order.id === decoded.id && order.placedAt === decoded.placedAt);
+    if (index < 0) return { orders: [], nextCursor: null, invalidCursor: true };
+    start = index + 1;
+  }
+  const page = sorted.slice(start, start + limit);
+  const last = page[page.length - 1];
+  const nextCursor = page.length === limit && start + limit < sorted.length && last !== undefined ? encodeCursor(last) : null;
+  return { orders: page, nextCursor, invalidCursor: false };
+}
+
+export async function finalCartDigest(cart: FinalCartBinding): Promise<string> {
+  const lines = [...cart.lines].sort(
+    (left, right) => left.sku.localeCompare(right.sku) || left.unitMinor - right.unitMinor || left.quantity - right.quantity,
+  );
+  for (const line of lines) {
+    assertMinor(line.quantity, "quantity");
+    assertMinor(line.unitMinor, "unitMinor");
+    if (line.quantity < 1) throw new Error("quantity must be positive");
+  }
+  return sha256Hex(
+    `${FINAL_CART_DOMAIN}\n${canonicalJson({
+      currency: cart.currency,
+      destinationDigest: cart.destinationDigest,
+      lines,
+      stage: cart.stage,
+      taxExpiresAt: cart.taxExpiresAt,
+      tenantId: cart.tenantId,
+      verificationExpiresAt: cart.verificationExpiresAt,
+    })}`,
+  );
+}
+
+export function finalCartStillBound(
+  boundDigest: string,
+  actualDigest: string,
+  now: string,
+  expiresAt: string,
+): boolean {
+  return boundDigest === actualDigest && expiresAt > now;
+}
+
+export function admitCallerToken(input: {
+  token: CallerToken;
+  trustedIssuers: readonly string[];
+  expectedAudience: string;
+  activeKids: readonly string[];
+  now: string;
+  tenantId: string;
+  stage: CommerceStage;
+}): { ok: true; replayKey: string } | { ok: false; reason: CallerTokenRefusal } {
+  if (input.token.scheme !== "asymmetric-jwks") return { ok: false, reason: "shared-secret" };
+  const token = input.token;
+  if (!token.signatureValid) return { ok: false, reason: "signature" };
+  if (!input.activeKids.includes(token.kid)) return { ok: false, reason: "kid" };
+  if (!input.trustedIssuers.includes(token.issuer)) return { ok: false, reason: "issuer" };
+  if (token.audience !== input.expectedAudience) return { ok: false, reason: "audience" };
+  const expiresAt = Date.parse(token.expiresAt);
+  const now = Date.parse(input.now);
+  if (!Number.isFinite(expiresAt) || !Number.isFinite(now) || expiresAt <= now) return { ok: false, reason: "expired" };
+  if (expiresAt - now > CALLER_TOKEN_MAX_LIFETIME_MS) return { ok: false, reason: "lifetime" };
+  if (token.jti.trim() === "") return { ok: false, reason: "jti" };
+  if (token.tenantId !== input.tenantId) return { ok: false, reason: "tenant" };
+  if (token.stage !== input.stage) return { ok: false, reason: "stage" };
+  return { ok: true, replayKey: `${token.issuer}\n${token.jti}` };
+}
+
+function matchWorkerPattern(path: string, pattern: string): boolean {
+  const expression = `^${pattern
+    .split("*")
+    .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+    .join(".*")}$`;
+  return new RegExp(expression).test(path);
+}
+
+export function commerceApiOrigin(
+  provider: string,
+  phase: string,
+  path: string,
+): "worker" | "storage" | "refuse" {
+  if (provider !== "cloudflare" && provider !== "cloudfront") return "refuse";
+  if (phase !== "preview" && phase !== "publication") return "refuse";
+  if (WORKER_ROUTE_PATTERNS.some((pattern) => matchWorkerPattern(path, pattern))) return "worker";
+  return "storage";
+}