@tokenoftrust/storefront-runner 4.9.2 → 4.9.3

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

@@ -1,6 +1,6 @@
 /**
  * Orders workspace actions. Every button in the order detail answers: it opens the part of the
- * order it names, moves to the tab that resolves it, loads the owner-only address, or says why
+ * order it names, moves to the tab that resolves it, loads the customer contact details, or says why
  * nothing can be done from here. `planOrderAction` decides on the server; `mountOrderActions`
  * carries the plan out in the browser. Neither ever leaves a click without a visible result.
  */
@@ -78,8 +78,8 @@ function blockerPlan(input: OrderActionInput): OrderActionPlan {
   return { kind: "tab", target: "fulfillment", message: `${input.blocker}: holds are worked in the Fulfillment tab.` };
 }
 
-/** Owner address response, as stored. Only these fields are shown, in this order. */
-const ADDRESS_FIELDS = ["name", "line1", "line2", "city", "region", "postalCode", "country"] as const;
+/** Address fields shown, in this order. Anything else in a response is dropped. */
+const ADDRESS_FIELDS = ["name", "company", "line1", "line2", "city", "region", "postalCode", "country"] as const;
 
 export function addressLines(address: unknown): string[] {
   if (address === null || typeof address !== "object" || Array.isArray(address)) return [];
@@ -92,16 +92,44 @@ export function addressLines(address: unknown): string[] {
   return lines;
 }
 
-export const ADDRESS_NONE =
-  "No ship-to address is stored for this order. The checkout confirmation carries none and the order ledger keeps no customer data.";
-export const ADDRESS_DENIED = "Only the store owner can view a ship-to address.";
-export const ADDRESS_FAILED = "The address could not be loaded. Try again.";
+export const CONTACT_NONE =
+  "No customer contact details are on file for this order. They are kept for a limited time and are gone once expired or erased.";
+export const CONTACT_DENIED = "You cannot view customer contact details for this order.";
+export const CONTACT_GRANT_REQUIRED = "The store owner has not granted ToT support access to customer contact details.";
+export const CONTACT_QUOTA = "The hourly limit for reading customer contact details has been reached. Try again later.";
+export const CONTACT_UNAVAILABLE = "Customer contact details are temporarily unavailable. Try again shortly.";
+export const CONTACT_FAILED = "The contact details could not be loaded. Try again.";
+export const CONTACT_ERASED = "Customer contact details were erased.";
+export const ERASE_FAILED = "The contact details could not be erased. Try again.";
+export const ERASE_CONFIRM =
+  "Permanently erase this customer's name, email, phone and addresses? This cannot be undone and the details cannot be recovered.";
+export const TICKET_INVALID = "Enter a ticket reference of letters, digits, dot, dash or underscore, up to 64 characters.";
+
+const TICKET_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+
+/** Support-read reason codes, as the server accepts them. */
+export const SUPPORT_REASONS: readonly { code: string; label: string }[] = [
+  { code: "customer-request", label: "Customer request" },
+  { code: "delivery-issue", label: "Delivery issue" },
+  { code: "payment-dispute", label: "Payment dispute" },
+  { code: "compliance-review", label: "Compliance review" },
+  { code: "merchant-request", label: "Merchant request" },
+];
 
 export interface OrderActionDeps {
   fetch: typeof fetch;
   /** The fulfillment API root for the selected store, or null when this page cannot reach it. */
   api: string | null;
   navigate: (tab: string) => boolean;
+  /** Asks the person to confirm an irreversible action. */
+  confirm: (message: string) => boolean;
+}
+
+interface OrderContact {
+  customer: unknown;
+  shipTo: unknown;
+  billTo: unknown;
+  expiresAt: unknown;
 }
 
 function show(note: HTMLElement | null, lines: readonly string[]): void {
@@ -110,24 +138,191 @@ function show(note: HTMLElement | null, lines: readonly string[]): void {
   note.hidden = false;
 }
 
-async function loadAddress(orderId: string, note: HTMLElement | null, deps: OrderActionDeps): Promise<void> {
-  if (!deps.api) {
-    show(note, [ADDRESS_FAILED]);
-    return;
+function node<K extends keyof HTMLElementTagNameMap>(tag: K, text = "", className = ""): HTMLElementTagNameMap[K] {
+  const element = document.createElement(tag);
+  if (text) element.textContent = text;
+  if (className) element.className = className;
+  return element;
+}
+
+function parseContact(body: unknown): OrderContact | null {
+  if (body === null || typeof body !== "object" || Array.isArray(body)) return null;
+  const record = body as Record<string, unknown>;
+  if (record.customer === null || typeof record.customer !== "object") return null;
+  if (record.shipTo === null || typeof record.shipTo !== "object") return null;
+  if (record.billTo === null || typeof record.billTo !== "object") return null;
+  return { customer: record.customer, shipTo: record.shipTo, billTo: record.billTo, expiresAt: record.expiresAt };
+}
+
+function customerLines(customer: unknown): string[] {
+  if (customer === null || typeof customer !== "object") return [];
+  const record = customer as Record<string, unknown>;
+  return (["name", "email", "phone"] as const).flatMap((key) => {
+    const value = record[key];
+    return typeof value === "string" && value.trim() !== "" ? [value.trim()] : [];
+  });
+}
+
+function keptUntil(expiresAt: unknown): string | null {
+  if (typeof expiresAt !== "string") return null;
+  const date = new Date(expiresAt);
+  if (Number.isNaN(date.getTime())) return null;
+  return `Contact details kept until ${date.toLocaleDateString(undefined, { year: "numeric", month: "short", day: "numeric" })}.`;
+}
+
+function group(label: string, lines: readonly string[]): HTMLElement {
+  const wrap = node("div", "", "orders-contact-group");
+  wrap.append(node("strong", label), ...lines.map((line) => node("span", line)));
+  return wrap;
+}
+
+async function readJson(response: Response): Promise<unknown> {
+  try {
+    return await response.json();
+  } catch (error) {
+    // A body that is not JSON shows the status message for this response; anything else is a fault.
+    if (error instanceof SyntaxError) return null;
+    throw error;
+  }
+}
+
+function errorCode(body: unknown): string {
+  if (body !== null && typeof body === "object" && typeof (body as { error?: unknown }).error === "string") {
+    return (body as { error: string }).error;
   }
-  show(note, ["Loading address…"]);
+  return "";
+}
+
+type ContactVia = "owner" | "support";
+
+interface ContactView {
+  orderId: string;
+  panel: HTMLElement;
+  deps: OrderActionDeps;
+}
+
+/** Turn any contact response into what the panel shows: the details, a reason form, or why there are none. */
+async function settleContact(response: Response, via: ContactVia, view: ContactView): Promise<void> {
+  const { panel } = view;
+  if (response.status === 404) return show(panel, [CONTACT_NONE]);
+  if (response.status === 429) return show(panel, [CONTACT_QUOTA]);
+  if (response.status === 503) return show(panel, [CONTACT_UNAVAILABLE]);
+  if (response.status === 401 || response.status === 403) {
+    const code = errorCode(await readJson(response));
+    if (code === "support-read-required") return renderReasonForm(view);
+    if (code === "grant-required") return show(panel, [CONTACT_GRANT_REQUIRED]);
+    return show(panel, [CONTACT_DENIED]);
+  }
+  if (!response.ok) return show(panel, [CONTACT_FAILED]);
+  const contact = parseContact(await readJson(response));
+  if (!contact) return show(panel, [CONTACT_FAILED]);
+  renderContact(contact, via, view);
+}
+
+function renderContact(contact: OrderContact, via: ContactVia, view: ContactView): void {
+  const { panel } = view;
+  const status = node("p", "", "orders-contact-status");
+  status.setAttribute("role", "status");
+  status.hidden = true;
+  const children: HTMLElement[] = [
+    group("Customer", customerLines(contact.customer)),
+    group("Ship to", addressLines(contact.shipTo)),
+    group("Bill to", addressLines(contact.billTo)),
+  ];
+  const until = keptUntil(contact.expiresAt);
+  if (until) children.push(node("small", until));
+  if (via === "owner") {
+    const erase = node("button", "Erase contact details", "btn");
+    erase.type = "button";
+    erase.setAttribute("data-orders-contact-erase", "");
+    erase.addEventListener("click", () => void eraseContact(view, erase, status));
+    children.push(erase);
+  }
+  children.push(status);
+  panel.replaceChildren(...children);
+  panel.hidden = false;
+}
+
+async function eraseContact(view: ContactView, button: HTMLButtonElement, status: HTMLElement): Promise<void> {
+  const { deps, orderId, panel } = view;
+  if (!deps.api) return show(status, [ERASE_FAILED]);
+  if (!deps.confirm(ERASE_CONFIRM)) return;
+  button.disabled = true;
   try {
     const response = await deps.fetch(`${deps.api}/orders/${encodeURIComponent(orderId)}/address`, {
+      method: "DELETE",
       credentials: "same-origin",
       cache: "no-store",
     });
-    if (response.status === 404) return show(note, [ADDRESS_NONE]);
-    if (response.status === 401 || response.status === 403) return show(note, [ADDRESS_DENIED]);
-    if (!response.ok) return show(note, [ADDRESS_FAILED]);
-    const lines = addressLines(await response.json());
-    show(note, lines.length ? lines : [ADDRESS_NONE]);
+    const body = response.ok ? await readJson(response) : null;
+    if (response.ok && (body as { erased?: unknown } | null)?.erased === true) return show(panel, [CONTACT_ERASED]);
+    if (response.status === 404) return show(panel, [CONTACT_NONE]);
+    button.disabled = false;
+    show(status, [ERASE_FAILED]);
   } catch {
-    show(note, [ADDRESS_FAILED]);
+    button.disabled = false;
+    show(status, [ERASE_FAILED]);
+  }
+}
+
+function renderReasonForm(view: ContactView): void {
+  const { deps, orderId, panel } = view;
+  const form = node("form", "", "orders-contact-reason");
+  form.noValidate = true;
+  const select = node("select");
+  select.setAttribute("aria-label", "Reason for reading customer contact details");
+  select.required = true;
+  for (const reason of SUPPORT_REASONS) select.append(Object.assign(document.createElement("option"), { value: reason.code, textContent: reason.label }));
+  const ticket = node("input");
+  ticket.type = "text";
+  ticket.maxLength = 64;
+  ticket.autocomplete = "off";
+  ticket.placeholder = "Ticket reference";
+  ticket.setAttribute("aria-label", "Support ticket reference");
+  const submit = node("button", "Read contact details", "btn primary");
+  submit.type = "submit";
+  const status = node("p", "", "orders-contact-status");
+  status.setAttribute("role", "status");
+  status.hidden = true;
+  form.append(node("span", "Reading customer contact details as ToT support needs a reason and a ticket. Every read is recorded."), select, ticket, submit, status);
+  form.addEventListener("submit", (event) => {
+    event.preventDefault();
+    if (!deps.api) return show(status, [CONTACT_FAILED]);
+    const ticketRef = ticket.value.trim();
+    if (!TICKET_PATTERN.test(ticketRef)) return show(status, [TICKET_INVALID]);
+    submit.disabled = true;
+    void (async () => {
+      try {
+        const response = await deps.fetch(`${deps.api}/orders/${encodeURIComponent(orderId)}/contact/support-read`, {
+          method: "POST",
+          credentials: "same-origin",
+          cache: "no-store",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ reasonCode: select.value, ticketRef }),
+        });
+        await settleContact(response, "support", view);
+      } catch {
+        submit.disabled = false;
+        show(status, [CONTACT_FAILED]);
+      }
+    })();
+  });
+  panel.replaceChildren(form);
+  panel.hidden = false;
+}
+
+async function loadContact(orderId: string, panel: HTMLElement | null, deps: OrderActionDeps): Promise<void> {
+  if (!panel) return;
+  if (!deps.api) return show(panel, [CONTACT_FAILED]);
+  show(panel, ["Loading contact details…"]);
+  try {
+    const response = await deps.fetch(`${deps.api}/orders/${encodeURIComponent(orderId)}/address`, {
+      credentials: "same-origin",
+      cache: "no-store",
+    });
+    await settleContact(response, "owner", { orderId, panel, deps });
+  } catch {
+    show(panel, [CONTACT_FAILED]);
   }
 }
 
@@ -157,12 +352,27 @@ export function mountOrderActions(root: HTMLElement, deps: OrderActionDeps): voi
     } else if (kind === "tab") {
       show(note, [deps.navigate(target) ? message : `${message} The ${target} tab is not available to this account.`]);
     } else if (kind === "address") {
-      void loadAddress(orderId, record.querySelector<HTMLElement>(target) ?? note, deps);
+      void loadContact(orderId, record.querySelector<HTMLElement>(target) ?? note, deps);
     } else {
       show(note, [message || "Nothing can be done from here."]);
     }
   };
 
+  // Contact details are not kept in the page once another order is selected.
+  const detailRoot = root.querySelector<HTMLElement>("[data-orders-detail-root]");
+  if (detailRoot && typeof MutationObserver !== "undefined") {
+    new MutationObserver(() => {
+      for (const record of detailRoot.querySelectorAll<HTMLElement>("[data-orders-detail-record]")) {
+        if (record.dataset.ordersDetailRecord === detailRoot.dataset.adminSelectedId) continue;
+        const panel = record.querySelector<HTMLElement>("[data-orders-address]");
+        if (panel && !panel.hidden) {
+          panel.replaceChildren();
+          panel.hidden = true;
+        }
+      }
+    }).observe(detailRoot, { attributes: true, attributeFilter: ["data-admin-selected-id"] });
+  }
+
   root.addEventListener("click", (event) => {
     const origin = event.target instanceof Element ? event.target : null;
     const button = origin?.closest<HTMLElement>("[data-orders-action]");

package/apps/storefront/src/lib/orders/data/commerceCallerConfig.ts

@@ -0,0 +1,37 @@
+/**
+ * The signed caller configuration both signed intakes verify against (order-forward's commerce
+ * events and order-contact's contact commands): the expected stage plus the caller JWKS, trusted
+ * issuers, audience and active kids. Null when any part is absent or malformed — callers answer 503.
+ */
+import { readEnv } from "@/lib/publication/shared/env";
+import type { CommerceCallerConfig } from "./orderForwardReceiver.js";
+
+function callerList(value: string): string[] {
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter((item) => item !== "");
+}
+
+export async function readCommerceCallerConfig(now: Date): Promise<CommerceCallerConfig | null> {
+  const expectedStage = await readEnv("COMMERCE_STAGE");
+  if (expectedStage !== "preview" && expectedStage !== "publication") return null;
+  const jwksRaw = await readEnv("COMMERCE_CALLER_JWKS");
+  const issuersRaw = await readEnv("COMMERCE_CALLER_ISSUERS");
+  const audience = await readEnv("COMMERCE_CALLER_AUDIENCE");
+  const kidsRaw = await readEnv("COMMERCE_CALLER_ACTIVE_KIDS");
+  if (!jwksRaw || !issuersRaw || !audience || !kidsRaw) return null;
+  let jwks: CommerceCallerConfig["jwks"];
+  try {
+    jwks = JSON.parse(jwksRaw) as CommerceCallerConfig["jwks"];
+  } catch (error) {
+    if (error instanceof SyntaxError) return null;
+    throw error;
+  }
+  const trustedIssuers = callerList(issuersRaw);
+  const activeKids = callerList(kidsRaw);
+  if (trustedIssuers.length === 0 || activeKids.length === 0 || !Array.isArray(jwks.keys) || jwks.keys.length === 0) {
+    return null;
+  }
+  return { expectedStage, jwks, trustedIssuers, expectedAudience: audience, activeKids, now: now.toISOString() };
+}

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

@@ -159,7 +159,13 @@ export interface CommerceCallerConfig {
   now: string;
 }
 
-export type SignedCommerceRefusal = CallerTokenRefusal | "version" | "malformed" | "totals" | "private" | "replay";
+export type SignedCommerceRefusal = CallerTokenRefusal | "version" | "use" | "malformed" | "totals" | "private" | "replay";
+
+/**
+ * The `use` claim separates the two signed intakes: a commerce token carries none, and the
+ * order-contact route requires exactly "order-contact". Each route refuses the other's tokens.
+ */
+export type SignedCallerUse = "order-contact";
 
 export type SignedCommerceResult =
   | { ok:true; authorityAck:BeginAck|ResultAck; tenantId:string; stage:CommerceStage }
@@ -200,8 +206,8 @@ function expiresAtIso(exp: unknown): string {
 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" }> {
+  binding: { tenantId: string; stage: CommerceStage; use?: SignedCallerUse },
+): Promise<{ ok: true; issuer: string; jti: string; digest: string } | { ok: false; reason: CallerTokenRefusal | "version" | "use" }> {
   if(!isStage(config.expectedStage)||binding.stage!==config.expectedStage)return {ok:false,reason:"stage"};
   if (token.split(".").length !== 3) {
     const admitted = admitCallerToken({
@@ -272,6 +278,7 @@ export async function verifySignedCommerceToken(
   if (!admitted.ok) return admitted;
   if(typeof claims.exp!=="number"||claims.exp-Math.floor(Date.parse(config.now)/1000)>60)return {ok:false,reason:"lifetime"};
   if (claims.ver !== 1) return { ok: false, reason: "version" };
+  if (binding.use === undefined ? claims.use !== undefined : claims.use !== binding.use) return { ok: false, reason: "use" };
   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 };
 }

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

@@ -113,6 +113,11 @@ export async function toContractOrder(order: FoxyOrder, ctx: ToContractOrderCont
 export const COMMERCE_COMMANDS = ["observe", "capture", "refund", "cancel"] as const;
 export type CommerceCommandName = (typeof COMMERCE_COMMANDS)[number];
 
+/**
+ * Keys that identify a customer. Any of them, at any depth, refuses a commerce payload: contact
+ * arrives only through the signed order-contact command. `country` and `region` are not listed —
+ * they are the coarse destination every provider cart carries.
+ */
 export const PRIVATE_COMMERCE_KEYS = new Set([
   "customer",
   "customerEmail",
@@ -121,9 +126,13 @@ export const PRIVATE_COMMERCE_KEYS = new Set([
   "phone",
   "line1",
   "line2",
+  "city",
+  "company",
   "postalCode",
   "shippingAddress",
   "billingAddress",
+  "shipTo",
+  "billTo",
   "address",
   "firstName",
   "lastName",

package/apps/storefront/src/lib/orders/data/sourceAuthorityContract.ts

@@ -129,7 +129,8 @@ export type AuthorityCode =
   | "source-authority-unavailable"
   | "source-sync-pending"
   | "authority-budget"
-  | "control-identity-conflict";
+  | "control-identity-conflict"
+  | "use";
 export class SourceAuthorityError extends Error {
   constructor(readonly code: AuthorityCode) {
     super(code);

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

@@ -0,0 +1,61 @@
+/**
+ * The signed order-contact command (decision gv-contact-vault-command-contract-v1b): the only
+ * inbound path for a customer's contact. Body `{tenantId, stage, contact}` exactly; the caller token
+ * must carry `use: "order-contact"` and a digest of the canonical body. The commerce intake refuses
+ * these tokens and keeps refusing every private key in its own events.
+ */
+import { canonicalJson, sha256Hex } from "@tot/public-runtime";
+import type { Queryable } from "../../catalog/d1/catalog.js";
+import { verifySignedCommerceToken, type CommerceCallerConfig } from "../data/orderForwardReceiver.js";
+import type { VaultKeyring } from "@/lib/customers/contactVault/envelope.js";
+import { readOrderContactCommand } from "./orderContact.js";
+import { sealOrderContact, type SealOutcome } from "./orderContactVault.js";
+import { type VaultStage } from "@/lib/customers/contactVault/contactAudit.js";
+
+export type ContactIntakeResult =
+  | { ok: true; duplicate: boolean; tenantId: string; stage: VaultStage }
+  | { ok: false; status: number; reason: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isStage(value: unknown): value is VaultStage {
+  return value === "preview" || value === "publication";
+}
+
+export async function receiveOrderContact(
+  db: Queryable,
+  keyring: VaultKeyring | null,
+  body: unknown,
+  token: string,
+  config: CommerceCallerConfig,
+): Promise<ContactIntakeResult> {
+  if (!isStage(config.expectedStage)) return { ok: false, status: 503, reason: "vault-unavailable" };
+  if (!isRecord(body)) return { ok: false, status: 400, reason: "malformed" };
+  const { tenantId, stage, contact } = body;
+  if (typeof tenantId !== "string" || tenantId.trim() === "") return { ok: false, status: 401, reason: "tenant" };
+  if (!isStage(stage)) return { ok: false, status: 401, reason: "stage" };
+  const verified = await verifySignedCommerceToken(token, config, { tenantId, stage, use: "order-contact" });
+  if (!verified.ok) return { ok: false, status: 401, reason: verified.reason };
+  const keys = Object.keys(body);
+  if (keys.length !== 3 || !["tenantId", "stage", "contact"].every((key) => keys.includes(key))) {
+    return { ok: false, status: 400, reason: "malformed" };
+  }
+  if ((await sha256Hex(canonicalJson({ tenantId, stage, contact }))) !== verified.digest) {
+    return { ok: false, status: 401, reason: "signature" };
+  }
+  const command = readOrderContactCommand(contact);
+  if (!command) return { ok: false, status: 400, reason: "malformed" };
+  const sealed: SealOutcome = await sealOrderContact(db, keyring, {
+    tenantId,
+    stage,
+    command,
+    issuer: verified.issuer,
+    jti: verified.jti,
+    now: new Date(config.now),
+  });
+  return sealed.ok
+    ? { ok: true, duplicate: sealed.duplicate, tenantId, stage }
+    : { ok: false, status: sealed.status, reason: sealed.reason };
+}

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

@@ -0,0 +1,99 @@
+/**
+ * The admission every order-contact admin route runs before it touches the vault: the owner gate,
+ * then the owner-or-staff split (contactReaderAuthority), then — for staff — a reason, a ticket and a
+ * LIVE owner-consented customer-contact-read grant. The tenant comes from the routed host and the
+ * stage from the routed customization environment, never from the request.
+ */
+import type { APIContext } from "astro";
+import { requireAdminApiEntry } from "@/lib/access/auth/adminApiGuard";
+import { readViewerSession } from "@/lib/access/auth/route";
+import { contactReaderAuthority, resolveContactReadGrant } from "@/lib/access/auth/contactReaderAuthority";
+import { readD1 } from "@/lib/publication/shared/env";
+import { fromD1, type Queryable } from "@/lib/catalog/d1/catalog.js";
+import { commerceStageForEnv } from "@/lib/fulfillment/fulfillmentService";
+import type { VaultKeyring } from "@/lib/customers/contactVault/envelope.js";
+import { loadVaultKeyring } from "./keyringEnv.js";
+import { type ContactActor, type VaultStage } from "@/lib/customers/contactVault/contactAudit.js";
+
+export const SUPPORT_REASON_CODES = [
+  "customer-request",
+  "delivery-issue",
+  "payment-dispute",
+  "compliance-review",
+  "merchant-request",
+] as const;
+const TICKET_REF = /^[A-Za-z0-9._-]{1,64}$/;
+
+export function contactJson(body: unknown, status: number): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+      "x-robots-tag": "noindex, nofollow",
+    },
+  });
+}
+
+/** A support reason from a request body, or null when it is not exactly {reasonCode, ticketRef}. */
+export function readSupportReason(body: unknown): { reasonCode: string; ticketRef: string } | null {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return null;
+  const record = body as Record<string, unknown>;
+  const keys = Object.keys(record);
+  if (keys.length !== 2 || !keys.includes("reasonCode") || !keys.includes("ticketRef")) return null;
+  const { reasonCode, ticketRef } = record;
+  if (typeof reasonCode !== "string" || !(SUPPORT_REASON_CODES as readonly string[]).includes(reasonCode)) return null;
+  if (typeof ticketRef !== "string" || !TICKET_REF.test(ticketRef)) return null;
+  return { reasonCode, ticketRef };
+}
+
+export type ContactRoute =
+  | { ok: false; response: Response }
+  | { ok: true; db: Queryable; keyring: VaultKeyring | null; tenantId: string; stage: VaultStage; actor: ContactActor };
+
+export async function openContactRoute(
+  context: APIContext,
+  expect: "owner" | "staff",
+  body?: unknown,
+): Promise<ContactRoute> {
+  const refuse = (error: string, status: number): ContactRoute => ({ ok: false, response: contactJson({ error }, status) });
+  const url = new URL(context.request.url);
+  if (url.searchParams.has("tenant") || url.searchParams.has("tenantId") || url.searchParams.has("stage")) {
+    return refuse("denied", 403);
+  }
+  const access = await requireAdminApiEntry(context, { requireOwner: true });
+  if (!access.ok) return refuse(access.reason, access.status);
+  const host = context.locals.tenant?.appDomain?.trim() ?? "";
+  const authority = contactReaderAuthority(await readViewerSession(context), host, Math.floor(Date.now() / 1000));
+  if (authority.kind === "none") return refuse("denied", 403);
+
+  let actor: ContactActor;
+  if (expect === "owner") {
+    if (authority.kind === "staff") return refuse("support-read-required", 403);
+    actor = { actorId: authority.actorId, role: "owner" };
+  } else {
+    if (authority.kind === "owner") return refuse("use-owner-route", 403);
+    const reason = readSupportReason(body);
+    if (!reason) return refuse("malformed", 400);
+    if (!(await resolveContactReadGrant(authority.email, host))) return refuse("grant-required", 403);
+    actor = { actorId: authority.actorId, role: "staff", ...reason };
+  }
+
+  const stage = commerceStageForEnv(context.locals.customizationEnv);
+  if (!stage) return refuse("stage-unknown", 409);
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  if (!d1) return refuse("unavailable", 503);
+  return { ok: true, db: fromD1(d1), keyring: await loadVaultKeyring(), tenantId: host, stage, actor };
+}
+
+/** Read a request's JSON body, or undefined when it is absent or not JSON. */
+export async function readRequestJson(request: Request): Promise<unknown> {
+  const raw = await request.text();
+  if (raw.length > 4096) return undefined;
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    if (error instanceof SyntaxError) return undefined;
+    throw error;
+  }
+}

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

@@ -0,0 +1,7 @@
+/** The Worker's contact vault keyring, from the declared `ORDER_CONTACT_VAULT_KEYRING` secret only. */
+import { readEnv } from "@/lib/publication/shared/env";
+import { parseVaultKeyring, type VaultKeyring } from "@/lib/customers/contactVault/envelope.js";
+
+export async function loadVaultKeyring(): Promise<VaultKeyring | null> {
+  return parseVaultKeyring(await readEnv("ORDER_CONTACT_VAULT_KEYRING"));
+}