@tokenoftrust/storefront-runner 6.0.2 → 6.1.1

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

@@ -650,6 +650,7 @@ function applyToOrder(state: WorkspaceState, order: WorkspaceOrder, command: Wor
     if (!state.carrierAccountConfigured) return refuse("carrier-account");
     const decision = decideCommerceCommand({
       command: "purchase-label",
+      shipTo: order.ownerDestination ? "present" : "absent",
       payment: order.payment,
       stock: order.stock,
       fulfillment: order.fulfillment,
@@ -729,6 +730,7 @@ function applyToOrder(state: WorkspaceState, order: WorkspaceOrder, command: Wor
     if (order.adultSignature !== "accepted") return refuse("adult-signature");
     const decision = decideCommerceCommand({
       command: "hand-off",
+      shipTo: order.ownerDestination ? "present" : "absent",
       payment: order.payment,
       stock: order.stock,
       fulfillment: order.fulfillment,

package/apps/storefront/src/lib/fulfillment/fulfillmentService.ts

@@ -29,9 +29,10 @@ import {
   type PaymentState,
   type ProviderOutcome,
   type StockState,
+  type OrderContactState,
 } from "@tot/public-runtime";
 import { readD1 } from "@/lib/publication/shared/env";
-import { terminalTransitionExpiryStatement } from "@/lib/orders/vault/orderContactVault.js";
+import { readOrderContactAvailability, terminalTransitionExpiryStatement } from "@/lib/orders/vault/orderContactVault.js";
 import { decideAdminApiAccess } from "@/lib/access/auth/adminApiGuard";
 import { readViewerSession } from "@/lib/access/auth/route";
 import type { SessionRecord } from "@/lib/access/auth/session";
@@ -149,6 +150,7 @@ export type FulfillmentResult<T> =
   | { ok: false; code: string; holds?: readonly ReleaseHold[] };
 
 interface LoadedOrder {
+  shipTo: OrderContactState;
   sourceAuthority: AuthorityRow|null;
   sourceHolds: SourceReadiness[];
   order: {
@@ -947,6 +949,7 @@ export class FulfillmentService {
 
   private readiness(state: LoadedOrder): ReadinessInput {
     return {
+      shipTo: state.shipTo,
       sourceHolds: state.sourceHolds,
       payment: state.order.payment,
       stock: state.order.stock,
@@ -1387,7 +1390,11 @@ export class FulfillmentService {
     try { sourceAuthority=await this.db.get<AuthorityRow & Record<string,unknown>>(`SELECT * FROM commerce_source_authority WHERE tenant_id=? AND stage=? AND source=? AND source_order_id=?`,[tenantId,stage,order.source,order.sourceOrderId]) ?? null;
       sourceHolds=sourceAuthority?.order_id!==order.orderId?["source-authority-unavailable"]:authorityHolds(sourceAuthority,this.now());
     }catch{sourceHolds=["source-authority-unreadable"];}
+    const contacts = await readOrderContactAvailability({
+      all: (sql, ...params) => this.db.all(sql, params),
+    }, { tenantId, stage, orderIds: [orderId], now: new Date(this.now()) });
     const loaded: LoadedOrder = {
+      shipTo: contacts.get(orderId)?.shipTo ?? "unreadable",
       sourceAuthority,sourceHolds,
       order,
       evidence,
@@ -1428,7 +1435,7 @@ export class FulfillmentService {
     const readiness = this.readiness(loaded);
     const holds = releaseHolds(readiness);
     loaded.view.holds = holds;
-    if(sourceHolds.length&&order.fulfillment==="ready")loaded.view.fulfillment="held";
+    if(holds.length&&order.fulfillment==="ready")loaded.view.fulfillment="held";
     loaded.view.canRelease = canRelease(readiness) && !loaded.shipment;
     loaded.view.canHandOff = handoffRefusal(readiness) === null && loaded.shipment?.handoffState !== "handed_off";
     loaded.view.shipment = loaded.shipment
@@ -1558,6 +1565,8 @@ function projectedFromSnapshot(
   if (snapshot.fulfillment === "cancelled" || payment === "voided" || payment === "refunded") return "cancelled";
   if (snapshot.fulfillment === "UNKNOWN") return "UNKNOWN";
   const holds = releaseHolds({
+    // Source disposition is independent of contact delivery; commands re-read the vault.
+    shipTo: "present",
     payment,
     stock: snapshot.stock,
     fulfillment: "ready",

package/apps/storefront/src/lib/fulfillment/readiness.ts

@@ -16,6 +16,7 @@ import {
   type PaymentState,
   type ProviderOutcome,
   type StockState,
+  type OrderContactState,
 } from "@tot/public-runtime";
 import type { SourceReadiness } from "../orders/data/sourceAuthorityStore.js";
 import { COMPLIANCE_RULE_PROFILES } from "@/config/compliance/rulesets";
@@ -42,6 +43,10 @@ export const RELEASE_HOLDS = [
   "stock-unknown",
   "stock-unconfirmed",
   "fulfillment-unknown",
+  "ship-to-absent",
+  "ship-to-expired",
+  "ship-to-erased",
+  "ship-to-unreadable",
 ] as const;
 
 export type ReleaseHold = (typeof RELEASE_HOLDS)[number];
@@ -54,6 +59,7 @@ export interface CarrierPolicy {
 }
 
 export interface ReadinessInput {
+  shipTo?: OrderContactState;
   sourceHolds?: readonly SourceReadiness[];
   payment: PaymentState;
   stock: StockState;
@@ -100,6 +106,10 @@ export function releaseHolds(input: ReadinessInput): ReleaseHold[] {
   else if (!paymentIsCaptured(input.payment)) add(holds, "payment-not-captured");
   if (input.stock === "UNKNOWN") add(holds, "stock-unknown");
   else if (input.stock !== "confirmed") add(holds, "stock-unconfirmed");
+  if (input.shipTo !== "present" && input.shipTo !== "restricted") {
+    add(holds, input.shipTo === "absent" ? "ship-to-absent" : input.shipTo === "expired" ? "ship-to-expired" :
+      input.shipTo === "erased" ? "ship-to-erased" : "ship-to-unreadable");
+  }
   return holds;
 }
 
@@ -107,7 +117,7 @@ export function canRelease(input: ReadinessInput): boolean {
   return input.fulfillment === "ready" && releaseHolds(input).length === 0;
 }
 
-export function handoffRefusal(input: ReadinessInput): ReleaseHold | "adult-signature" | "label" | "reconcile" | "fulfillment" | "evidence" | "payment" | "stock" | "reuse" | null {
+export function handoffRefusal(input: ReadinessInput): ReleaseHold | "adult-signature" | "label" | "reconcile" | "fulfillment" | "evidence" | "payment" | "stock" | "reuse" | "ship-to" | null {
   const holds = releaseHolds(input);
   if (holds.length > 0) return holds[0] ?? "fulfillment";
   const decision = decideCommerceCommand({
@@ -118,6 +128,7 @@ export function handoffRefusal(input: ReadinessInput): ReleaseHold | "adult-sign
     label: input.label,
     evidence: input.evidence,
     providerOutcome: input.providerOutcome,
+    shipTo: input.shipTo,
   });
   if (!decision.admit) return decision.reason === "admitted" ? "fulfillment" : decision.reason;
   if (input.adultSignatureRequired && input.adultSignature !== "accepted") return "adult-signature";

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

@@ -14,16 +14,21 @@
  */
 import type {
   CheckoutOrderDetail,
-  CheckoutOrderDetailResponse,
+  CheckoutOrderSummary,
   CheckoutOrderListFilters,
   CheckoutOrderListResponse,
   CommerceActor,
   CommerceRole,
   CommerceScope,
   CommerceStage,
+  CheckoutOrderCustomer,
+  OrderContactAvailability,
+  OrderContactState,
 } from "@tot/public-runtime";
-import { readOwnerAddress } from "@tot/public-runtime";
+import { actorMayCommand, readOwnerAddress } from "@tot/public-runtime";
 import type { CustomizationEnv } from "@tot/public-runtime";
+import { contactReaderAuthority } from "@/lib/access/auth/contactReaderAuthority";
+import type { SessionRecord } from "@/lib/access/auth/session";
 
 /** Fetch shape we depend on — the platform `fetch`, injectable for tests. */
 export type FetchLike = (
@@ -107,26 +112,83 @@ export function commerceStageForCustomization(env: CustomizationEnv): CommerceSt
   return env === "live" ? "publication" : "preview";
 }
 
-/** Owner reads private order fields. An admitted member is a caller. Everyone else is denied. */
+/** Private ownership comes from tenant membership, independently of staff operational capability. */
 export function commerceActorForAdmin(input: {
   tenantId: string;
   stage: CommerceStage;
-  owner: boolean;
+  record: SessionRecord | null | undefined;
+  nowSeconds: number;
   admitted: boolean;
 }): CommerceActor {
-  const role: CommerceRole = !input.admitted ? "denied" : input.owner ? "owner" : "caller";
+  const privateOwner = contactReaderAuthority(input.record, input.tenantId, input.nowSeconds).kind === "owner";
+  const role: CommerceRole = !input.admitted ? "denied" : privateOwner ? "owner" : "caller";
   return { role, tenantId: input.tenantId, stage: input.stage };
 }
 
 /** Drop the address unless this actor may read it for this tenant and stage. */
-export function projectCheckoutOrder<T extends { shippingAddress?: unknown }>(
+export function projectCheckoutOrder<T extends { shippingAddress?: unknown; customer?: CheckoutOrderCustomer; contactAvailability?: OrderContactAvailability }>(
   order: T,
   actor: CommerceActor,
   resource: CommerceScope,
 ): T {
+  const unknown: OrderContactAvailability = { identity: "unreadable", email: "unreadable", shipTo: "unreadable" };
+  const availability = order.contactAvailability ?? {
+    ...unknown,
+    shipTo: Object.hasOwn(order, "shippingAddress") ? addressAvailability(order.shippingAddress) : "unreadable",
+  };
   const read = readOwnerAddress(actor, resource, () => order.shippingAddress ?? null);
-  if (read.ok) return order;
-  return { ...order, shippingAddress: null };
+  if (read.ok) return { ...order, contactAvailability: availability };
+  const restricted = (state: OrderContactState): OrderContactState => state === "present" ? "restricted" : state;
+  const projected: Record<string, unknown> = { ...order };
+  for (const key of ["customerName", "customerEmail", "email", "phone", "name", "line1", "line2", "postalCode"]) delete projected[key];
+  return {
+    ...projected,
+    shippingAddress: null,
+    ...(order.customer ? { customer: { id: null, name: "Checkout customer" } } : {}),
+    contactAvailability: actorMayCommand(actor, resource) ? {
+      identity: restricted(availability.identity), email: restricted(availability.email), shipTo: restricted(availability.shipTo),
+    } : unknown,
+  } as T;
+}
+
+function addressAvailability(value: unknown): OrderContactState {
+  if (value === null) return "absent";
+  if (!isRecord(value)) return "unreadable";
+  return ["line1", "city", "country"].every((key) => typeof value[key] === "string" && value[key].trim() !== "") ? "present" : "unreadable";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+const SUMMARY_FIELDS = ["id", "placedAt", "currency", "customer", "contactAvailability", "itemsSummary", "itemCount", "total", "payment", "fulfillment", "blocker", "verification"];
+const DETAIL_FIELDS = [...SUMMARY_FIELDS, "lineItems", "totals", "shippingAddress", "verificationDetail"];
+
+/** Refuse an unsupported upstream body before any raw contact aliases reach an admin response. */
+function frozenOrder(value: unknown, detail: true): value is CheckoutOrderDetail;
+function frozenOrder(value: unknown, detail: false): value is CheckoutOrderSummary;
+function frozenOrder(value: unknown, detail: boolean): boolean {
+  if (!isRecord(value) || Object.keys(value).some((key) => !(detail ? DETAIL_FIELDS : SUMMARY_FIELDS).includes(key))) return false;
+  if (!["id", "placedAt", "currency", "itemsSummary"].every((key) => typeof value[key] === "string")) return false;
+  if (!isRecord(value.customer) || typeof value.customer.name !== "string" ||
+    !(value.customer.id === null || typeof value.customer.id === "string") ||
+    Object.keys(value.customer).some((key) => key !== "id" && key !== "name")) return false;
+  if (typeof value.total !== "number" || !Number.isFinite(value.total) || !Number.isInteger(value.itemCount)) return false;
+  if (!["authorized", "captured", "refunded"].includes(String(value.payment)) ||
+    !["unfulfilled", "ready_to_ship", "hold_review_required", "completed"].includes(String(value.fulfillment))) return false;
+  if (value.blocker !== null && typeof value.blocker !== "string") return false;
+  if (value.verification !== null && !isRecord(value.verification)) return false;
+  const availability = value.contactAvailability;
+  if (availability !== undefined && (!isRecord(availability) ||
+    !["identity", "email", "shipTo"].every((key) => typeof availability[key] === "string" &&
+      ["present", "restricted", "absent", "expired", "erased", "unreadable"].includes(availability[key])) ||
+    Object.keys(availability).some((key) => !["identity", "email", "shipTo"].includes(key)))) return false;
+  return !detail || (Array.isArray(value.lineItems) && isRecord(value.totals) && isRecord(value.verificationDetail) &&
+    (value.shippingAddress === null || isRecord(value.shippingAddress)));
+}
+
+function unsupportedBody(): OrderApiError {
+  return new OrderApiError("bad_gateway", 502);
 }
 
 /** Build the list querystring: appDomain (required) + any provided filters. */
@@ -151,12 +213,12 @@ export function createCheckoutOrderClient(
   const base = config.baseUrl.replace(/\/+$/, "");
   const headers = { authorization: `Bearer ${config.bearer}` };
 
-  async function getJson<T>(url: string): Promise<T> {
+  async function getJson(url: string): Promise<unknown> {
     const res = await doFetch(url, { method: "GET", headers });
     const body = await res.text();
     if (!res.ok) throw toError(res.status, body);
     try {
-      return JSON.parse(body) as T;
+      return JSON.parse(body) as unknown;
     } catch {
       throw new OrderApiError("unexpected", res.status, "malformed JSON");
     }
@@ -165,14 +227,22 @@ export function createCheckoutOrderClient(
   return {
     async listOrders(filters) {
       const qs = listQuery(config.appDomain, filters);
-      return getJson<CheckoutOrderListResponse>(`${base}/commerce/orders?${qs}`);
+      const body = await getJson(`${base}/commerce/orders?${qs}`);
+      if (!isRecord(body) || !Array.isArray(body.orders) || !body.orders.every((order): order is CheckoutOrderSummary => frozenOrder(order, false)) ||
+        !isRecord(body.page) || Object.keys(body).some((key) => key !== "orders" && key !== "page")) throw unsupportedBody();
+      const page = body.page;
+      if (typeof page.limit !== "number" || !(page.cursor === null || typeof page.cursor === "string") ||
+        !(page.nextCursor === null || typeof page.nextCursor === "string") || !(page.total === null || typeof page.total === "number") ||
+        Object.keys(page).some((key) => !["limit", "cursor", "nextCursor", "total"].includes(key))) throw unsupportedBody();
+      return { orders: body.orders, page: { limit: page.limit, cursor: page.cursor, nextCursor: page.nextCursor, total: page.total } };
     },
     async getOrder(orderId) {
       const qs = new URLSearchParams({ appDomain: config.appDomain }).toString();
-      const { order } = await getJson<CheckoutOrderDetailResponse>(
+      const body = await getJson(
         `${base}/commerce/orders/${encodeURIComponent(orderId)}?${qs}`,
       );
-      return order;
+      if (!isRecord(body) || !frozenOrder(body.order, true) || Object.keys(body).some((key) => key !== "order")) throw unsupportedBody();
+      return body.order;
     },
   };
 }

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

@@ -9,8 +9,8 @@
  * the only per-tenant record for that tenant. A tenant on its own FoxyCart store reads that
  * store's partner API with `FOXY_ORDER_API_KEY`.
  *
- * The ledger carries no customer identity and no address (the intake refuses both), so a ledger
- * order names no customer and has no shipping address here.
+ * Contact values stay in the encrypted vault. Order reads carry only its presence metadata;
+ * authorized contact routes retrieve the private values separately.
  */
 import type {
   CheckoutOrderDetail,
@@ -24,6 +24,7 @@ import type {
   CommerceStage,
   CustomizationEnv,
   PaymentState,
+  OrderContactAvailability,
 } from "@tot/public-runtime";
 import { evidencePermitsRelease, paginateOrders } from "@tot/public-runtime";
 import { commerceStageForEnv } from "@/lib/fulfillment/fulfillmentService";
@@ -31,6 +32,7 @@ import { readD1, readEnv } from "@/lib/publication/shared/env";
 import { fromD1, type Queryable } from "@/lib/catalog/d1/catalog.js";
 import { ScrappyOrderLedger, type CommerceOrderBookEntry } from "../data/ordersStore.js";
 import { foldCommerceEvents, type CommerceSourceEvent } from "../data/orderMapper.js";
+import { readOrderContactAvailability } from "../vault/orderContactVault.js";
 import {
   OrderApiError,
   createCheckoutOrderClient,
@@ -115,7 +117,9 @@ export async function resolveOrderSource(
   if (checkout === "shared-test-store") {
     const db = await deps.readLedgerDb();
     if (!db) return { kind: "not-connected", checkout, gap: "ledger-unavailable" };
-    const book = ledgerOrderBook(new ScrappyOrderLedger(db), { tenantId, stage });
+    const book = ledgerOrderBook(new ScrappyOrderLedger(db), { tenantId, stage }, {
+      readContactAvailability: (orderIds) => readOrderContactAvailability(db, { tenantId, stage, orderIds, now: new Date() }),
+    });
     return { kind: "ledger", checkout, scope: { tenantId, stage }, client: book.client, status: book.status };
   }
 
@@ -212,7 +216,7 @@ interface LedgerOrder {
   detail: CheckoutOrderDetail;
 }
 
-function ledgerOrder(entry: CommerceOrderBookEntry): LedgerOrder {
+function ledgerOrder(entry: CommerceOrderBookEntry, contactAvailability: OrderContactAvailability): LedgerOrder {
   const placedAt = isoInstant(entry.placedAt);
   const snapshot = entry.events.length > 0 ? foldCommerceEvents(entry.events) : null;
   // The order row is the state of record: provider events and fulfillment commands both write it.
@@ -231,10 +235,12 @@ function ledgerOrder(entry: CommerceOrderBookEntry): LedgerOrder {
     state = "completed";
     blocker = "Cancelled";
   } else if (fulfillment === "UNKNOWN") state = "unfulfilled";
-  else if (fulfillment === "ready" && releasable) state = "ready_to_ship";
+  else if (fulfillment === "ready" && releasable &&
+    (contactAvailability.shipTo === "present" || contactAvailability.shipTo === "restricted")) state = "ready_to_ship";
   else {
     state = "hold_review_required";
-    blocker = payment !== "captured" ? "Payment capture" : evidencePermitsRelease(evidence) ? "Manual review" : "Evidence review";
+    blocker = payment !== "captured" ? "Payment capture" : !evidencePermitsRelease(evidence) ? "Evidence review" :
+      contactAvailability.shipTo !== "present" && contactAvailability.shipTo !== "restricted" ? "Ship-to address" : "Manual review";
   }
 
   const itemCount = lines.reduce((sum, line) => sum + line.quantity, 0);
@@ -252,6 +258,7 @@ function ledgerOrder(entry: CommerceOrderBookEntry): LedgerOrder {
     placedAt,
     currency: entry.currency,
     customer: { id: null, name: "Checkout customer" },
+    contactAvailability,
     itemsSummary,
     itemCount,
     total: toMajor(totals.totalMinor),
@@ -320,16 +327,22 @@ const PAYMENT_CONFIRMATION_GRACE_MS = PAYMENT_CONFIRMATION_GRACE_MINUTES * 60 *
 export function ledgerOrderBook(
   ledger: Pick<ScrappyOrderLedger, "readOrderBook">,
   scope: { tenantId: string; stage: CommerceStage },
+  options: { readContactAvailability?: (orderIds: readonly string[]) => Promise<ReadonlyMap<string, OrderContactAvailability>> } = {},
 ): { client: CheckoutOrderClient; status: (now?: Date) => Promise<LedgerSyncStatus> } {
   let loaded: Promise<{ orders: LedgerOrder[]; unconfirmed: CommerceOrderBookEntry[] }> | null = null;
   const load = () =>
-    (loaded ??= ledger.readOrderBook(scope.tenantId, scope.stage).then((book) => {
+    (loaded ??= ledger.readOrderBook(scope.tenantId, scope.stage).then(async (book) => {
       const paid = book.filter((entry) => entry.source !== "scrappy");
       const confirmed = new Set(
         paid.flatMap((entry) => entry.events.map((event: CommerceSourceEvent) => event.admissionReference)).filter(Boolean),
       );
+      let availability: ReadonlyMap<string, OrderContactAvailability> = new Map();
+      try { availability = await options.readContactAvailability?.(paid.map((entry) => entry.orderId)) ?? availability; }
+      catch { /* A failed presence read cannot clear shipment readiness. */ }
       return {
-        orders: paid.map(ledgerOrder),
+        orders: paid.map((entry) => ledgerOrder(entry, availability.get(entry.orderId) ?? {
+          identity: "unreadable", email: "unreadable", shipTo: "unreadable",
+        })),
         unconfirmed: book.filter((entry) => entry.source === "scrappy" && !confirmed.has(entry.orderId)),
       };
     }));

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

@@ -26,7 +26,9 @@ import type {
   PublicCommerceEvent,
   StockState,
   TenantConfig,
+  OrderContactState,
 } from "@tot/public-runtime";
+import { projectCheckoutOrder } from "../orderClient";
 import {
   actorMayCommand,
   decideCommerceCommand,
@@ -158,6 +160,7 @@ export type AuthorityState = "fresh" | "expired" | "unreadable" | "absent";
 
 /** One commerce order. Columns do not borrow each other's state, source, or as-of. */
 export interface ScrappyOrderRecord {
+  shipTo?: OrderContactState;
   id: string;
   placedAt: string;
   tenantId: string;
@@ -264,6 +267,7 @@ function deriveRisk(
 
 function deriveNextStep(fulfillment: OrderShipState, blocker: string | null): string {
   if (fulfillment === "hold_review_required") {
+    if (blocker === "Ship-to address") return "Review address";
     return blocker === "Payment capture" ? "Capture payment" : "Review risk";
   }
   if (fulfillment === "completed") return "View record";
@@ -348,6 +352,7 @@ export function releaseOf(order: ScrappyOrderRecord): OrderRelease {
   if (!evidencePermitsRelease(evidence)) blocks.push("evidence");
   if (order.stock.state !== "confirmed" && !blocks.includes("stock")) blocks.push("stock");
   if (order.fulfillment.state !== "ready" && !blocks.includes("fulfillment")) blocks.push("fulfillment");
+  if (!usableContact(order.shipTo)) blocks.push("ship-to");
 
   const decision = decideCommerceCommand({
     command: "hand-off",
@@ -357,6 +362,7 @@ export function releaseOf(order: ScrappyOrderRecord): OrderRelease {
     label: order.label,
     evidence,
     providerOutcome: order.providerOutcome,
+    shipTo: order.shipTo,
   });
   if (!decision.admit) {
     if (decision.reason === "payment" && !blocks.includes("payment") && !blocks.includes("refund")) blocks.push("payment");
@@ -383,6 +389,7 @@ function checkoutRecord(order: CheckoutOrderSummary, scope: CommerceScope): Scra
     tenantId: scope.tenantId,
     stage: scope.stage,
     currency: order.currency,
+    shipTo: order.contactAvailability?.shipTo,
     payment: { state: payment, source: "checkout-order", asOf: order.placedAt },
     tax: readSourcedEvidence(order.verification, "tax"),
     verification: readSourcedEvidence(order.verification, "verification"),
@@ -415,14 +422,16 @@ export function assessCheckoutOrder(order: CheckoutOrderSummary, scope: Commerce
 
 export function mapSummaryToRow(s: CheckoutOrderSummary): OrderRow {
   const verificationMissing = s.verification == null;
-  const shipState: OrderShipState = verificationMissing ? "hold_review_required" : s.fulfillment;
-  const blocker = s.blocker ?? (verificationMissing ? "Verification unknown" : null);
+  const addressMissing = !usableContact(s.contactAvailability?.shipTo);
+  const addressHold = s.fulfillment !== "completed" && addressMissing;
+  const shipState: OrderShipState = verificationMissing || addressHold ? "hold_review_required" : s.fulfillment;
+  const blocker = s.blocker ?? (verificationMissing ? "Verification unknown" : addressHold ? "Ship-to address" : null);
   return {
     id: s.id,
     placedAt: s.placedAt,
     customerId: s.customer.id ?? "",
     customerName: s.customer.name,
-    customerNote: "",
+    customerNote: contactPresenceCopy(s.contactAvailability?.identity, "Customer identity"),
     itemsSummary: s.itemsSummary,
     productId: "",
     total: s.total,
@@ -434,6 +443,21 @@ export function mapSummaryToRow(s: CheckoutOrderSummary): OrderRow {
   };
 }
 
+function usableContact(state: OrderContactState | undefined): boolean {
+  return state === "present" || state === "restricted";
+}
+
+function contactPresenceCopy(state: OrderContactState | undefined, subject: string): string {
+  switch (state) {
+    case "present": return `${subject} is on file in the private contact vault. Viewing details requires owner access or a support grant.`;
+    case "restricted": return `${subject} is on file; you do not have access to view its details.`;
+    case "absent": return `${subject} is not on file.`;
+    case "expired": return `${subject} has expired under the contact retention policy.`;
+    case "erased": return `${subject} has been erased.`;
+    default: return `${subject} availability could not be verified. Try again shortly.`;
+  }
+}
+
 function paymentValue(payment: CheckoutOrderPayment): string {
   if (payment === "captured") return "Captured";
   if (payment === "refunded") return "Refunded";
@@ -489,13 +513,11 @@ function deriveReadinessChecks(d: CheckoutOrderDetail, scope: CommerceScope): Or
     {
       key: "address",
       label: "Address",
-      value: d.shippingAddress ? "Serviceable" : "Unknown",
-      detail: d.shippingAddress
-        ? "An address is on the order."
-        : "No address is on the order.",
-      tone: d.shippingAddress ? "green" : "amber",
+      value: d.contactAvailability?.shipTo ?? (d.shippingAddress ? "present" : "Unknown"),
+      detail: contactPresenceCopy(d.contactAvailability?.shipTo ?? (d.shippingAddress ? "present" : undefined), "Ship-to address"),
+      tone: usableContact(d.contactAvailability?.shipTo) || (!d.contactAvailability && d.shippingAddress) ? "green" : "amber",
       action: "View address",
-      blocking: false,
+      blocking: !usableContact(d.contactAvailability?.shipTo) && !(!d.contactAvailability && d.shippingAddress),
     },
     columnCheck(column("risk"), {
       label: "Risk",
@@ -623,6 +645,7 @@ export function emptyOrdersViewModel(targetTenant: string, timeZone: string = DE
 }
 
 export interface GetOrdersViewModelOptions {
+  actor?: CommerceActor;
   targetTenant: string;
   scope: CommerceScope;
   client: CheckoutOrderClient;
@@ -698,12 +721,15 @@ async function readOrdersToday(client: CheckoutOrderClient, now: Date, timeZone:
 
 export async function getOrdersViewModelResult(opts: GetOrdersViewModelOptions): Promise<OrdersLoadResult> {
   try {
-    const { orders, page } = await opts.client.listOrders(opts.filters);
+    const listed = await opts.client.listOrders(opts.filters);
+    const actor = opts.actor ?? { ...opts.scope, role: "caller" as const };
+    const orders = listed.orders.map((order) => projectCheckoutOrder(order, actor, opts.scope));
+    const page = listed.page;
     const details: Record<string, CheckoutOrderDetail> = {};
     await Promise.all(
       orders.map(async (o) => {
         try {
-          details[o.id] = await opts.client.getOrder(o.id);
+          details[o.id] = projectCheckoutOrder(await opts.client.getOrder(o.id), actor, opts.scope);
         } catch {
           /* detail unavailable — row still renders from its summary */
         }

package/apps/storefront/src/lib/orders/vault/orderContactVault.ts

@@ -18,6 +18,7 @@
  * Nothing here logs. Errors and outcomes carry fixed codes only; fact_id never leaves this module.
  */
 import type { Queryable, QueryStatement } from "../../catalog/d1/catalog.js";
+import type { OrderContactAvailability, OrderContactState } from "@tot/public-runtime";
 import { VaultKeyUnavailableError, type DataKeyPurpose, type EncryptionContext, type KmsClient } from "@/lib/customers/contactVault/kms.js";
 import {
   activeKey,
@@ -600,6 +601,96 @@ const ORDER_JOIN_SELECT = `SELECT v.*, o.placed_at AS order_placed_at, o.fulfill
   FROM scrappy_commerce_orders o
   JOIN order_contact_vault v ON v.tenant_id = o.tenant_id AND v.stage = o.stage AND v.order_id = o.order_id`;
 
+const AVAILABILITY_GROUPS = ["identity", "email", "ship"] as const;
+const AVAILABILITY_CHUNK_SIZE = 80;
+
+/** Structural envelope presence only; authentication belongs to an audited contact read. */
+function envelopePresentSql(column: string): string {
+  return `(typeof(${column}) = 'text' AND length(${column}) >= 40 AND length(${column}) % 4 = 0
+    AND rtrim(${column}, '=') NOT GLOB '*[^A-Za-z0-9+/]*'
+    AND length(${column}) - length(rtrim(${column}, '=')) <= 2)`;
+}
+
+function completeGroupSql(group: typeof AVAILABILITY_GROUPS[number]): string {
+  const required = group === "identity" ? "name_ct" : group === "email" ? "email_ct" : "ship_line1_ct";
+  const encrypted = LAYOUT[group].sealed.map((column) => column === required
+    ? envelopePresentSql(`v.${column}`)
+    : `(v.${column} IS NULL OR ${envelopePresentSql(`v.${column}`)})`);
+  if (group === "ship") {
+    encrypted.push(...["ship_city", "ship_country"].map((column) => `(typeof(v.${column}) = 'text' AND length(trim(v.${column})) > 0)`));
+  }
+  return `(${encrypted.join(" AND ")})`;
+}
+
+const AVAILABILITY_SELECT = `SELECT o.order_id, o.placed_at AS order_placed_at,
+    o.fulfillment_state AS order_fulfillment_state, (${correlatedTerminalSql("o")}) AS order_terminal_at,
+    v.order_id IS NOT NULL AS vault_present, v.erased_at IS NOT NULL AS erased,
+    EXISTS (SELECT 1 FROM order_contact_markers m
+      WHERE m.tenant_id = o.tenant_id AND m.stage = o.stage AND m.order_id = o.order_id) AS marked,
+    EXISTS (SELECT 1 FROM contact_vault_data_keys k
+      WHERE k.tenant_id = v.tenant_id AND k.stage = v.stage AND k.purpose = 'order-contact' AND k.kid = v.order_kid
+        AND typeof(k.wrapped_key) = 'text' AND length(trim(k.wrapped_key)) > 0
+        AND typeof(k.kms_key_arn) = 'text' AND length(trim(k.kms_key_arn)) > 0) AS key_present,
+    v.time_scale, v.ship_country, v.ship_region,
+    ${AVAILABILITY_GROUPS.flatMap((group) => [
+      // Sentinel columns let the shared retention reader see presence without selecting values.
+      `CASE WHEN ${hasDataSql(group, "v.")} THEN 1 END AS ${LAYOUT[group].sealed[0]}`,
+      `${completeGroupSql(group)} AS ${group}_complete`,
+      ...["ceiling", "expires_at", "floor_until"].map((suffix) => `v.${group}_${suffix}`),
+    ]).join(",\n    ")}
+  FROM scrappy_commerce_orders o
+  LEFT JOIN order_contact_vault v ON v.tenant_id = o.tenant_id AND v.stage = o.stage AND v.order_id = o.order_id`;
+
+function uniformAvailability(state: OrderContactState): OrderContactAvailability {
+  return { identity: state, email: state, shipTo: state };
+}
+
+function contactAvailability(row: VaultRow, input: {
+  tenantId: string; stage: VaultStage; now: Date; policy: RetentionPolicy;
+}): OrderContactAvailability {
+  if (Number(row.vault_present) !== 1) return uniformAvailability(Number(row.marked) === 1 ? "expired" : "absent");
+  const times = orderTimes(row.order_placed_at, row.order_fulfillment_state, row.order_terminal_at);
+  if (times === "order-time-unreadable" || !Number.isFinite(input.now.getTime())) return uniformAvailability("unreadable");
+  const states = groupStates(row, input.tenantId, input.stage, times, input.now, input.policy);
+  const state = (group: typeof AVAILABILITY_GROUPS[number]): OrderContactState => {
+    const current = states[group];
+    if (!current.sealed && Number(row.erased) === 1) return "erased";
+    if (!current.expiresAt) return "unreadable";
+    if (!isGroupReadable(input.now, current.expiresAt, text(row, `${group}_ceiling`)) ||
+      (input.stage === "preview" && input.now.getTime() >= Date.parse(previewDeleteAt(times.placedAt, input.policy)))) return "expired";
+    if (!current.sealed) return "absent";
+    if (Number(row.key_present) !== 1 || Number(row[`${group}_complete`]) !== 1) return "unreadable";
+    return current.readable ? "present" : "unreadable";
+  };
+  return { identity: state("identity"), email: state("email"), shipTo: state("ship") };
+}
+
+/** Retained contact presence for a bounded order set; no decrypt, audit write, or private values. */
+export async function readOrderContactAvailability(
+  db: { all<T extends Record<string, unknown>>(sql: string, ...params: unknown[]): Promise<T[]> },
+  input: { tenantId: string; stage: VaultStage; orderIds: readonly string[]; now: Date; policy?: RetentionPolicy },
+): Promise<ReadonlyMap<string, OrderContactAvailability>> {
+  const orderIds = [...new Set(input.orderIds)];
+  const result = new Map(orderIds.map((id) => [id, uniformAvailability("absent")]));
+  const policy = input.policy ?? RETENTION_POLICY;
+  try {
+    for (let start = 0; start < orderIds.length; start += AVAILABILITY_CHUNK_SIZE) {
+      const chunk = orderIds.slice(start, start + AVAILABILITY_CHUNK_SIZE);
+      const rows = await db.all<VaultRow>(
+        `${AVAILABILITY_SELECT} WHERE o.tenant_id = ? AND o.stage = ? AND o.order_id IN (${chunk.map(() => "?").join(", ")})`,
+        input.tenantId, input.stage, ...chunk,
+      );
+      for (const row of rows) {
+        const id = text(row, "order_id");
+        if (id !== null && chunk.includes(id)) result.set(id, contactAvailability(row, { ...input, policy }));
+      }
+    }
+    return result;
+  } catch {
+    return new Map(orderIds.map((id) => [id, uniformAvailability("unreadable")]));
+  }
+}
+
 interface Viewable {
   groups: Group[];
   views: Partial<Record<Group, GroupView>>;

package/apps/storefront/src/pages/api/admin/orders/[id].ts

@@ -7,6 +7,7 @@
  */
 import type { APIContext } from "astro";
 import { requireAdminApiEntry } from "@/lib/access/auth/adminApiGuard";
+import { readViewerSession } from "@/lib/access/auth/route";
 import { commerceActorForAdmin, OrderApiError, projectCheckoutOrder } from "@/lib/orders/admin/orderClient";
 import { resolveOrderSource, workerOrderSourceDeps } from "@/lib/orders/admin/orderSource";
 import { admitSharedStoreTenant } from "@/lib/checkout/commerce/sharedStoreAdmission";
@@ -47,7 +48,8 @@ export async function GET(context: APIContext): Promise<Response> {
     const actor = commerceActorForAdmin({
       tenantId: scope.tenantId,
       stage: scope.stage,
-      owner: access.entry.isOwnerViewer,
+      record: await readViewerSession(context),
+      nowSeconds: Math.floor(Date.now() / 1000),
       admitted: access.entry.admitted,
     });
     const order = projectCheckoutOrder(await source.client.getOrder(orderId), actor, scope);

package/apps/storefront/src/pages/api/admin/orders.ts

@@ -11,7 +11,8 @@
  */
 import type { APIContext } from "astro";
 import { requireAdminApiEntry } from "@/lib/access/auth/adminApiGuard";
-import { OrderApiError } from "@/lib/orders/admin/orderClient";
+import { readViewerSession } from "@/lib/access/auth/route";
+import { commerceActorForAdmin, OrderApiError, projectCheckoutOrder } from "@/lib/orders/admin/orderClient";
 import { resolveOrderSource, workerOrderSourceDeps } from "@/lib/orders/admin/orderSource";
 import { admitSharedStoreTenant } from "@/lib/checkout/commerce/sharedStoreAdmission";
 import { assessCheckoutOrder, parseOrderFilters } from "@/lib/orders/admin/services/orders";
@@ -51,10 +52,11 @@ export async function GET(context: APIContext): Promise<Response> {
 
   try {
     const data = await source.client.listOrders(filters);
-    const orders = data.orders.map((order) => ({
-      ...order,
-      readiness: assessCheckoutOrder(order, source.scope),
-    }));
+    const actor = commerceActorForAdmin({ ...source.scope, record: await readViewerSession(context), nowSeconds: Math.floor(Date.now() / 1000), admitted: access.entry.admitted });
+    const orders = data.orders.map((raw) => {
+      const order = projectCheckoutOrder(raw, actor, source.scope);
+      return { ...order, readiness: assessCheckoutOrder(order, source.scope) };
+    });
     return new Response(JSON.stringify({ ...data, orders }), { headers: JSON_HEADERS });
   } catch (err) {
     if (err instanceof OrderApiError) return jsonError(err.code, err.status);

package/package.json

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

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

@@ -27,6 +27,15 @@ export interface CheckoutOrderCustomer {
   name: string;
 }
 
+/** Operational presence only. No customer or address values cross this boundary. */
+export type OrderContactState = "present" | "absent" | "restricted" | "expired" | "erased" | "unreadable";
+
+export interface OrderContactAvailability {
+  identity: OrderContactState;
+  email: OrderContactState;
+  shipTo: OrderContactState;
+}
+
 /** A row in the orders list. All fields populated by U1 EXCEPT `verification`. */
 export interface CheckoutOrderSummary {
   /** Order / transaction id (string). */
@@ -35,6 +44,8 @@ export interface CheckoutOrderSummary {
   placedAt: string;
   currency: string;
   customer: CheckoutOrderCustomer;
+  /** Sealed contact availability, independent of permission to read its values. */
+  contactAvailability?: OrderContactAvailability;
   /** Human one-liner, e.g. "Vape Pen Starter Kit +1 more". */
   itemsSummary: string;
   itemCount: number;
@@ -300,6 +311,8 @@ export type CommerceCommand =
   | "reconcile";
 
 export interface CommerceCommandInput {
+  /** Current server-read presence; shipment commands fail closed when it is unknown. */
+  shipTo?: OrderContactState;
   command: CommerceCommand;
   payment: PaymentState;
   stock: StockState;
@@ -311,7 +324,7 @@ export interface CommerceCommandInput {
 
 export interface CommerceCommandDecision {
   admit: boolean;
-  reason: "admitted" | "evidence" | "payment" | "stock" | "fulfillment" | "label" | "reconcile" | "reuse";
+  reason: "admitted" | "evidence" | "payment" | "stock" | "fulfillment" | "label" | "reconcile" | "reuse" | "ship-to";
   restock: false;
   releaseReservation: boolean;
   blindRepurchase: false;
@@ -601,6 +614,7 @@ export function decideCommerceCommand(input: CommerceCommandInput): CommerceComm
       if (input.stock !== "confirmed") return deny("stock");
       if (input.fulfillment !== "ready") return deny("fulfillment");
       if (input.label !== "none" && input.label !== "voided") return deny("label");
+      if (input.shipTo !== "present" && input.shipTo !== "restricted") return deny("ship-to");
       return allow();
     case "print-label":
       if (input.fulfillment === "cancelled") return deny("fulfillment");
@@ -613,6 +627,7 @@ export function decideCommerceCommand(input: CommerceCommandInput): CommerceComm
       if (input.stock !== "confirmed") return deny("stock");
       if (input.fulfillment !== "ready") return deny("fulfillment");
       if (input.label !== "purchased" && input.label !== "printed") return deny("label");
+      if (input.shipTo !== "present" && input.shipTo !== "restricted") return deny("ship-to");
       return allow();
     default: {
       const unreachable: never = input.command;