@tokenoftrust/storefront-runner 2.4.50 → 2.4.52

package/apps/storefront/src/lib/admin/viewmodels/orders.ts

@@ -8,6 +8,9 @@
 
 export type OrderPaymentState = "authorized" | "captured" | "refunded";
 
+/** Display risk. `unknown` is absent evidence, not a low-risk clearance. */
+export type OrderRiskLevel = "low" | "medium" | "high" | "unknown";
+
 export type OrderShipState = "ready_to_ship" | "hold_review_required" | "unfulfilled" | "completed";
 
 /** The exact merchant-facing language the shell contract requires. */
@@ -54,7 +57,35 @@ export interface OrderRow {
   shipState: OrderShipState;
   blocker: string | null;
   nextStep: string;
-  riskLevel: "low" | "medium" | "high";
+  riskLevel: OrderRiskLevel;
+}
+
+/** One independent readiness fact. Source and as-of belong to this column only. */
+export interface OrderReadinessColumn {
+  key: "payment" | "tax" | "verification" | "risk" | "stock" | "fulfillment";
+  state: string;
+  source: string;
+  asOf: string | null;
+}
+
+/** Release is held unless every block is empty. `held` is not inferred from payment capture. */
+export interface OrderRelease {
+  state: "held" | "ready";
+  ready: boolean;
+  blocks: readonly string[];
+}
+
+/** Storewide, filtered, and page money are separate scopes. Refunds are not values. */
+export interface OrderMoneyScope {
+  count: number;
+  valueMinor: number;
+  refundMinor: number;
+}
+
+export interface OrderAccounting {
+  storewide: OrderMoneyScope;
+  filter: OrderMoneyScope;
+  page: OrderMoneyScope;
 }
 
 export interface OrderDetail extends OrderRow {
@@ -64,6 +95,9 @@ export interface OrderDetail extends OrderRow {
   shipping: number;
   estimatedTax: number;
   taxesAndFees: number;
+  /** Present when the order was assessed. Absent on the mock book. */
+  columns?: OrderReadinessColumn[];
+  release?: OrderRelease;
 }
 
 export type OrderQueueKey = "needs_attention" | "ready_to_ship" | "unfulfilled" | "all" | "completed";
@@ -89,4 +123,6 @@ export interface OrdersViewModel {
   rows: OrderRow[];
   detailsById: Record<string, OrderDetail>;
   today: OrdersTodaySummary;
+  /** Set by a scrappy book query. Never copied from the current page alone. */
+  accounting?: OrderAccounting;
 }

package/apps/storefront/src/lib/commerce/finalCartAuthorization.ts

@@ -0,0 +1,234 @@
+/**
+ * Final-cart authorization decision. Payment is admitted only when the caller
+ * token, the bound cart, fresh evidence, the verification seam, and mirror stock
+ * all agree. Catalog availability and a browser confirmation are not authority.
+ */
+import {
+  admitCallerToken,
+  assertMinor,
+  decideCommerceCommand,
+  finalCartDigest,
+  finalCartStillBound,
+  sumMinor,
+  type CallerToken,
+  type CommerceEvidence,
+  type CommerceStage,
+  type EvidenceState,
+  type FinalCartBinding,
+  type FulfillmentState,
+  type LabelState,
+  type PaymentState,
+  type StockState,
+} from "@tot/public-runtime";
+import { readMirrorAuthority, VERIFICATION_PROVIDER_OWNER, type ReserveHold } from "@/lib/inventory/allocations.js";
+
+export interface SeamView {
+  status: "clear" | "absent" | "blocked";
+  failedClosed?: boolean;
+  codes?: readonly string[];
+}
+
+export interface FinalCartRequest {
+  now: string;
+  routedTenantId: string;
+  quoted: FinalCartBinding;
+  presented: FinalCartBinding;
+  evidence: CommerceEvidence | null;
+  seam: SeamView | null;
+  catalogAvailable: boolean;
+  browserConfirmed: boolean;
+  token: CallerToken | null;
+  trustedIssuers: readonly string[];
+  expectedAudience: string;
+  activeKids: readonly string[];
+  authorities: readonly unknown[];
+  payment?: PaymentState;
+  stock?: StockState;
+  fulfillment?: FulfillmentState;
+  label?: LabelState;
+}
+
+export type FinalCartDecision =
+  | {
+      ok: true;
+      digest: string;
+      expiresAt: string;
+      amountMinor: number;
+      holds: ReserveHold[];
+      issuer: string;
+      jti: string;
+      tenantId: string;
+      stage: CommerceStage;
+    }
+  | { ok: false; finding: string; owner?: string };
+
+const EVIDENCE_FIELDS = ["verification", "tax", "risk", "stock"] as const;
+
+function sortedLines(cart: FinalCartBinding) {
+  return [...cart.lines].sort(
+    (left, right) => left.sku.localeCompare(right.sku) || left.unitMinor - right.unitMinor || left.quantity - right.quantity,
+  );
+}
+
+function cartFinding(quoted: FinalCartBinding, presented: FinalCartBinding, routedTenantId: string): string | null {
+  if (quoted.tenantId !== routedTenantId || presented.tenantId !== routedTenantId || quoted.tenantId !== presented.tenantId) {
+    return "tenant-changed";
+  }
+  if (quoted.stage !== presented.stage) return "stage-changed";
+  if (quoted.currency !== presented.currency) return "currency-changed";
+  if (quoted.destinationDigest !== presented.destinationDigest) return "destination-changed";
+  const left = sortedLines(quoted);
+  const right = sortedLines(presented);
+  if (left.length !== right.length || left.some((line, index) => line.sku !== right[index]?.sku)) return "product-changed";
+  if (left.some((line, index) => line.unitMinor !== right[index]?.unitMinor)) return "price-changed";
+  if (left.some((line, index) => line.quantity !== right[index]?.quantity)) return "quantity-changed";
+  if (quoted.verificationExpiresAt !== presented.verificationExpiresAt || quoted.taxExpiresAt !== presented.taxExpiresAt) {
+    return "evidence-window-changed";
+  }
+  return null;
+}
+
+function evidenceFinding(evidence: CommerceEvidence | null): string | null {
+  if (!evidence) return "missing-evidence";
+  for (const field of EVIDENCE_FIELDS) {
+    const state: EvidenceState | string = evidence[field];
+    if (state === "fresh") continue;
+    if (state === "UNKNOWN") return `evidence-${field}-unknown`;
+    if (state === "stale" || state === "unreadable" || state === "absent") return `evidence-${field}-${state}`;
+    return `evidence-${field}-unreadable`;
+  }
+  return null;
+}
+
+function seamFinding(seam: SeamView | null): { finding: string; owner?: string } | null {
+  if (!seam || seam.status === "absent") return { finding: "verification-seam-absent" };
+  if (seam.status === "clear") return null;
+  const codes = (seam.codes ?? []).filter((code) => /^[a-z0-9_-]+$/.test(code));
+  if (seam.failedClosed && codes.some((code) => code === "verification_unconfigured" || code === "ruleset_unavailable")) {
+    return { finding: "verification-provider-unconfigured", owner: VERIFICATION_PROVIDER_OWNER };
+  }
+  return { finding: codes[0] ? `verification-refused:${codes[0]}` : "verification-refused" };
+}
+
+function isCatalogShape(value: unknown): boolean {
+  return value == null || (typeof value === "object" && value !== null && "available" in value && !("provider" in value));
+}
+
+function commandFinding(reason: string): string {
+  switch (reason) {
+    case "stock":
+      return "stock-unknown";
+    case "fulfillment":
+      return "fulfillment-refused";
+    case "reconcile":
+      return "payment-reconcile";
+    case "payment":
+      return "payment-refused";
+    default:
+      return "evidence-refused";
+  }
+}
+
+function earlierExpiry(left: string, right: string): string {
+  return left <= right ? left : right;
+}
+
+/** Deny with one specific finding, or clear a mirror hold for each sku. */
+export async function evaluateFinalCart(input: FinalCartRequest): Promise<FinalCartDecision> {
+  if (input.browserConfirmed && (!input.token || input.token.scheme !== "asymmetric-jwks" || !input.token.signatureValid)) {
+    return { ok: false, finding: "browser-not-authority" };
+  }
+  if (!input.token) return { ok: false, finding: "signature" };
+  const admitted = admitCallerToken({
+    token: input.token,
+    trustedIssuers: input.trustedIssuers,
+    expectedAudience: input.expectedAudience,
+    activeKids: input.activeKids,
+    now: input.now,
+    tenantId: input.routedTenantId,
+    stage: input.presented.stage,
+  });
+  if (!admitted.ok) return { ok: false, finding: admitted.reason };
+
+  const changed = cartFinding(input.quoted, input.presented, input.routedTenantId);
+  if (changed) return { ok: false, finding: changed };
+
+  if (input.presented.lines.length < 1) return { ok: false, finding: "malformed-request" };
+
+  const evidence = evidenceFinding(input.evidence);
+  if (evidence) return { ok: false, finding: evidence };
+
+  const expiresAt = earlierExpiry(input.presented.verificationExpiresAt, input.presented.taxExpiresAt);
+  if (
+    input.presented.verificationExpiresAt <= input.now ||
+    input.presented.taxExpiresAt <= input.now ||
+    expiresAt <= input.now
+  ) {
+    return { ok: false, finding: "evidence-expired" };
+  }
+
+  let digest: string;
+  let amountMinor: number;
+  try {
+    for (const line of input.presented.lines) {
+      assertMinor(line.quantity, "quantity");
+      assertMinor(line.unitMinor, "unitMinor");
+    }
+    amountMinor = sumMinor(input.presented.lines.map((line) => line.unitMinor * line.quantity));
+    digest = await finalCartDigest(input.presented);
+    const quotedDigest = await finalCartDigest(input.quoted);
+    if (!finalCartStillBound(quotedDigest, digest, input.now, expiresAt)) return { ok: false, finding: "cart-unbound" };
+  } catch {
+    return { ok: false, finding: "malformed-request" };
+  }
+
+  const seam = seamFinding(input.seam);
+  if (seam) return { ok: false, finding: seam.finding, ...(seam.owner ? { owner: seam.owner } : {}) };
+
+  const command = decideCommerceCommand({
+    command: "authorize-final-cart",
+    payment: input.payment ?? "pending",
+    stock: input.stock ?? "unallocated",
+    fulfillment: input.fulfillment ?? "held",
+    label: input.label ?? "none",
+    evidence: input.evidence!,
+    providerOutcome: null,
+  });
+  if (!command.admit) return { ok: false, finding: commandFinding(command.reason) };
+
+  const quantities = new Map<string, number>();
+  for (const line of input.presented.lines) {
+    quantities.set(line.sku, (quantities.get(line.sku) ?? 0) + line.quantity);
+  }
+  const holds: ReserveHold[] = [];
+  for (const sku of [...quantities.keys()].sort()) {
+    const quantity = quantities.get(sku)!;
+    const named =
+      input.authorities.find((value) => {
+        if (!value || typeof value !== "object") return false;
+        return (value as { sku?: unknown }).sku === sku;
+      }) ?? (quantities.size === 1 ? (input.authorities[0] ?? null) : null);
+    if (named && typeof named === "object" && "provider" in named && (named as { provider: unknown }).provider !== "mirror") {
+      return { ok: false, finding: "authority-unavailable" };
+    }
+    const mirror = readMirrorAuthority(named);
+    if (!mirror || mirror.sku !== sku) {
+      return { ok: false, finding: input.catalogAvailable && isCatalogShape(named) ? "catalog-not-authority" : "authority-unavailable" };
+    }
+    if (mirror.onHand < quantity) return { ok: false, finding: "stock-unavailable" };
+    holds.push({ sku, locationId: mirror.locationId, quantity, onHand: mirror.onHand });
+  }
+
+  if (input.token.scheme !== "asymmetric-jwks") return { ok: false, finding: "shared-secret" };
+  return {
+    ok: true,
+    digest,
+    expiresAt,
+    amountMinor,
+    holds,
+    issuer: input.token.issuer,
+    jti: input.token.jti,
+    tenantId: input.routedTenantId,
+    stage: input.presented.stage,
+  };
+}