@tokenoftrust/storefront-runner 4.9.2 → 4.9.3

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

@@ -0,0 +1,96 @@
+/**
+ * The order contact a merchant needs to ship and support an order, as the signed contact command
+ * carries it (decision gv-contact-vault-command-contract-v1b). A strict allowlist: any extra or
+ * missing key, wrong type or out-of-range length is malformed.
+ */
+
+export interface ContactAddress {
+  name?: string;
+  company?: string;
+  line1: string;
+  line2?: string;
+  city: string;
+  region?: string;
+  postalCode?: string;
+  country: string;
+}
+
+export interface OrderContact {
+  customer: { name: string; email: string; phone: string };
+  shipTo: ContactAddress;
+  billTo: ContactAddress;
+}
+
+export interface OrderContactCommand extends OrderContact {
+  orderId: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function exact(value: Record<string, unknown>, required: readonly string[], optional: readonly string[] = []): boolean {
+  const keys = Object.keys(value);
+  return required.every((key) => keys.includes(key)) && keys.every((key) => required.includes(key) || optional.includes(key));
+}
+
+function text(value: unknown, min: number, max: number): value is string {
+  return typeof value === "string" && value.length >= min && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value);
+}
+
+const ADDRESS_REQUIRED = ["line1", "city", "country"] as const;
+const ADDRESS_OPTIONAL = ["name", "company", "line2", "region", "postalCode"] as const;
+const ADDRESS_LIMITS: Record<string, [number, number]> = {
+  name: [0, 200], company: [0, 200], line1: [1, 200], line2: [0, 200], city: [1, 100], region: [0, 100], postalCode: [0, 20],
+};
+
+function readAddress(value: unknown): ContactAddress | null {
+  if (!isRecord(value) || !exact(value, ADDRESS_REQUIRED, ADDRESS_OPTIONAL)) return null;
+  if (typeof value.country !== "string" || !/^[A-Z]{2}$/.test(value.country)) return null;
+  const out: Record<string, string> = { country: value.country };
+  for (const [key, [min, max]] of Object.entries(ADDRESS_LIMITS)) {
+    if (value[key] === undefined) continue;
+    if (!text(value[key], min, max)) return null;
+    out[key] = value[key] as string;
+  }
+  return out as unknown as ContactAddress;
+}
+
+/** Narrow the command's `contact` member, or null when it is not exactly the contract shape. */
+export function readOrderContactCommand(value: unknown): OrderContactCommand | null {
+  if (!isRecord(value) || !exact(value, ["kind", "v", "orderId", "customer", "shipTo", "billTo"])) return null;
+  if (value.kind !== "order-contact" || value.v !== 1) return null;
+  if (!text(value.orderId, 1, 128) || value.orderId.trim() === "") return null;
+  const customer = value.customer;
+  if (!isRecord(customer) || !exact(customer, ["name", "email", "phone"])) return null;
+  if (!text(customer.name, 1, 200) || !text(customer.email, 3, 254) || !customer.email.includes("@") || !text(customer.phone, 0, 40)) {
+    return null;
+  }
+  const shipTo = readAddress(value.shipTo);
+  const billTo = readAddress(value.billTo);
+  if (!shipTo || !billTo) return null;
+  return {
+    orderId: value.orderId,
+    customer: { name: customer.name, email: customer.email, phone: customer.phone },
+    shipTo,
+    billTo,
+  };
+}
+
+/** The sealed plaintext: the contact without the order id, which the AAD already binds. */
+export function orderContactPlaintext(command: OrderContactCommand): OrderContact {
+  return { customer: command.customer, shipTo: command.shipTo, billTo: command.billTo };
+}
+
+/** Deep structural equality of two contacts, for the duplicate-resend check. */
+export function sameOrderContact(left: unknown, right: OrderContact): boolean {
+  return JSON.stringify(canonical(left)) === JSON.stringify(canonical(right));
+}
+
+function canonical(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (isRecord(value)) {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+  }
+  return value;
+}

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

@@ -0,0 +1,369 @@
+/**
+ * The order contact vault: one sealed contact per order, in `order_contact_vault`
+ * (migrations-apps/0021). Every effect is one statement or one D1 batch, so a check and its write
+ * can never be split by a concurrent intake, erase or purge:
+ *
+ *  - seal: a conditional vault insert plus a replay row recorded only when THIS command sealed;
+ *    every refused outcome writes nothing.
+ *  - read: the audit row commits (with the staff quota in the same statement) before any decrypt.
+ *  - erase: audit, tombstone and delete commit together.
+ *  - purge: tombstone and delete expired rows together, so a purged contact cannot be resealed.
+ *
+ * Nothing here logs. Errors and outcomes carry fixed codes only.
+ */
+import type { Queryable, QueryStatement } from "../../catalog/d1/catalog.js";
+import {
+  openVaultRecord,
+  sealVaultRecord,
+  VaultKeyUnavailableError,
+  type VaultBinding,
+  type VaultKeyring,
+} from "@/lib/customers/contactVault/envelope.js";
+import { expiresAtFor, isReadable, notAfterFrom, readInstant, terminalExpiryFrom } from "@/lib/customers/contactVault/retention.js";
+import { orderContactPlaintext, sameOrderContact, type OrderContact, type OrderContactCommand } from "./orderContact.js";
+import {
+  admitAudit,
+  auditStatement,
+  batchAuditStatement,
+  type ContactActor,
+  type VaultStage,
+} from "@/lib/customers/contactVault/contactAudit.js";
+
+export type SealOutcome =
+  | { ok: true; status: 200; duplicate: boolean }
+  | {
+      ok: false;
+      status: 401 | 409 | 410 | 503;
+      reason: "replay" | "order-unknown" | "order-time-unreadable" | "contact-conflict" | "contact-expired" | "contact-erased" | "vault-key-unavailable";
+    };
+
+export type ReadOutcome =
+  | { ok: true; contact: OrderContact; expiresAt: string }
+  | { ok: false; status: 404 | 429 | 503; reason: "not-found" | "quota" | "audit-unavailable" | "vault-key-unavailable" };
+
+export type EraseOutcome =
+  | { ok: true }
+  | { ok: false; status: 404 | 429 | 503; reason: "not-found" | "quota" | "audit-unavailable" };
+
+interface OrderRow {
+  placed_at: unknown;
+  fulfillment_state: unknown;
+}
+
+interface VaultRow {
+  key_id: string;
+  nonce: string;
+  ciphertext: string;
+  not_after: string;
+  expires_at: string;
+  sealed_jti: string;
+}
+
+const TERMINAL_AT_SQL = `SELECT MIN(at) AS at FROM scrappy_shipment_audit
+  WHERE tenant_id = ? AND stage = ? AND order_id = ?
+    AND ((kind = 'transition' AND to_state = 'handed_off') OR (kind = 'pending-cancel' AND to_state = 'confirmed'))`;
+
+function binding(tenantId: string, stage: VaultStage, orderId: string, notAfter: string): VaultBinding {
+  return { purpose: "order-contact", tenantId, stage, recordId: orderId, notAfter };
+}
+
+function requireBatch(db: Queryable): NonNullable<Queryable["batch"]> {
+  if (!db.batch) throw new Error("D1 batch is unavailable");
+  return db.batch.bind(db);
+}
+
+/** When the order became terminal, `null` when it is not terminal, or "unreadable". */
+async function terminalAt(db: Queryable, tenantId: string, stage: VaultStage, orderId: string, fulfillment: unknown): Promise<Date | null | "unreadable"> {
+  if (fulfillment !== "handed_off" && fulfillment !== "cancelled") return null;
+  const row = await db.first<{ at: unknown }>(TERMINAL_AT_SQL, tenantId, stage, orderId);
+  return readInstant(row?.at) ?? "unreadable";
+}
+
+/** The order's not_after and expiry, derived from the order row alone. */
+export async function orderRetention(
+  db: Queryable,
+  tenantId: string,
+  stage: VaultStage,
+  orderId: string,
+): Promise<{ notAfter: string; expiresAt: string } | "order-unknown" | "order-time-unreadable"> {
+  const order = await db.first<OrderRow>(
+    `SELECT placed_at, fulfillment_state FROM scrappy_commerce_orders WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+    tenantId, stage, orderId,
+  );
+  if (!order) return "order-unknown";
+  const placed = readInstant(order.placed_at);
+  if (!placed) return "order-time-unreadable";
+  const terminal = await terminalAt(db, tenantId, stage, orderId, order.fulfillment_state);
+  if (terminal === "unreadable") return "order-time-unreadable";
+  const notAfter = notAfterFrom(placed);
+  return { notAfter, expiresAt: expiresAtFor(notAfter, terminal) };
+}
+
+/** Seal one order's contact from a verified contact command. */
+export async function sealOrderContact(
+  db: Queryable,
+  keyring: VaultKeyring | null,
+  input: { tenantId: string; stage: VaultStage; command: OrderContactCommand; issuer: string; jti: string; now: Date },
+): Promise<SealOutcome> {
+  const { tenantId, stage, command, issuer, jti, now } = input;
+  const orderId = command.orderId;
+  const nowIso = now.toISOString();
+  const sealedJti = `${issuer}:${jti}`;
+  const seen = await db.first(
+    `SELECT 1 AS seen FROM scrappy_caller_replay WHERE tenant_id = ? AND stage = ? AND issuer = ? AND jti = ?`,
+    tenantId, stage, issuer, jti,
+  );
+  if (seen) return { ok: false, status: 401, reason: "replay" };
+  const retention = await orderRetention(db, tenantId, stage, orderId);
+  if (retention === "order-unknown") return { ok: false, status: 409, reason: "order-unknown" };
+  if (retention === "order-time-unreadable") return { ok: false, status: 409, reason: "order-time-unreadable" };
+  const existing = await classifyExisting(db, keyring, tenantId, stage, command, sealedJti);
+  if (existing) return existing;
+  if (nowIso >= retention.expiresAt) return { ok: false, status: 410, reason: "contact-expired" };
+
+  let sealed;
+  try {
+    sealed = await sealVaultRecord(keyring, binding(tenantId, stage, orderId, retention.notAfter), orderContactPlaintext(command));
+  } catch (error) {
+    if (error instanceof VaultKeyUnavailableError) return { ok: false, status: 503, reason: "vault-key-unavailable" };
+    throw error;
+  }
+  const statements: QueryStatement[] = [
+    {
+      sql: `INSERT INTO order_contact_vault
+              (tenant_id, stage, order_id, key_id, nonce, ciphertext, not_after, expires_at, sealed_at, sealed_jti)
+            SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
+            WHERE EXISTS (SELECT 1 FROM scrappy_commerce_orders WHERE tenant_id = ? AND stage = ? AND order_id = ?)
+              AND NOT EXISTS (SELECT 1 FROM order_contact_tombstones WHERE tenant_id = ? AND stage = ? AND order_id = ?)
+              AND ? < ?
+            ON CONFLICT (tenant_id, stage, order_id) DO NOTHING`,
+      params: [
+        tenantId, stage, orderId, sealed.keyId, sealed.nonce, sealed.ciphertext, retention.notAfter, retention.expiresAt, nowIso, sealedJti,
+        tenantId, stage, orderId,
+        tenantId, stage, orderId,
+        nowIso, retention.expiresAt,
+      ],
+    },
+    {
+      sql: `INSERT INTO scrappy_caller_replay (tenant_id, stage, issuer, jti, seen_at)
+            SELECT ?, ?, ?, ?, ?
+            WHERE EXISTS (SELECT 1 FROM order_contact_vault WHERE tenant_id = ? AND stage = ? AND order_id = ? AND sealed_jti = ?)`,
+      params: [tenantId, stage, issuer, jti, nowIso, tenantId, stage, orderId, sealedJti],
+    },
+  ];
+  try {
+    await requireBatch(db)(statements);
+  } catch (error) {
+    // The only conflict the batch can raise is the replay key: this jti committed concurrently
+    // elsewhere. Anything else is a fault the sender must retry, never a replay.
+    const replayed = await db.first(
+      `SELECT 1 AS seen FROM scrappy_caller_replay WHERE tenant_id = ? AND stage = ? AND issuer = ? AND jti = ?`,
+      tenantId, stage, issuer, jti,
+    );
+    if (replayed) return { ok: false, status: 401, reason: "replay" };
+    throw error;
+  }
+  const after = await classifyExisting(db, keyring, tenantId, stage, command, sealedJti);
+  if (after) return after;
+  const again = await orderRetention(db, tenantId, stage, orderId);
+  if (again === "order-unknown") return { ok: false, status: 409, reason: "order-unknown" };
+  return { ok: false, status: 410, reason: "contact-expired" };
+}
+
+/** Classify an order that already has a vault row or a tombstone, or null when it has neither. */
+async function classifyExisting(
+  db: Queryable,
+  keyring: VaultKeyring | null,
+  tenantId: string,
+  stage: VaultStage,
+  command: OrderContactCommand,
+  sealedJti: string,
+): Promise<SealOutcome | null> {
+  const row = await db.first<VaultRow>(
+    `SELECT key_id, nonce, ciphertext, not_after, expires_at, sealed_jti FROM order_contact_vault
+     WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+    tenantId, stage, command.orderId,
+  );
+  if (row) {
+    if (row.sealed_jti === sealedJti) return { ok: true, status: 200, duplicate: false };
+    let stored: unknown | null;
+    try {
+      stored = await openVaultRecord(keyring, binding(tenantId, stage, command.orderId, row.not_after), {
+        keyId: row.key_id, nonce: row.nonce, ciphertext: row.ciphertext,
+      });
+    } catch (error) {
+      if (error instanceof VaultKeyUnavailableError) return { ok: false, status: 503, reason: "vault-key-unavailable" };
+      throw error;
+    }
+    return stored !== null && sameOrderContact(stored, orderContactPlaintext(command))
+      ? { ok: true, status: 200, duplicate: true }
+      : { ok: false, status: 409, reason: "contact-conflict" };
+  }
+  const tomb = await db.first<{ reason: string }>(
+    `SELECT reason FROM order_contact_tombstones WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+    tenantId, stage, command.orderId,
+  );
+  if (tomb) return { ok: false, status: 410, reason: tomb.reason === "erased" ? "contact-erased" : "contact-expired" };
+  return null;
+}
+
+/** Read one order's contact. The audit row commits before anything is decrypted. */
+export async function readOrderContact(
+  db: Queryable,
+  keyring: VaultKeyring | null,
+  input: { tenantId: string; stage: VaultStage; orderId: string; actor: ContactActor; auditId: string; now: Date },
+): Promise<ReadOutcome> {
+  const { tenantId, stage, orderId, actor, auditId, now } = input;
+  const admitted = await admitAudit(db, auditStatement({
+    auditId, tenantId, stage, recordKind: "order-contact", recordId: orderId, actor, action: "read", now,
+  }));
+  if (admitted === "quota") return { ok: false, status: 429, reason: "quota" };
+  if (admitted === "unavailable") return { ok: false, status: 503, reason: "audit-unavailable" };
+  const row = await db.first<VaultRow>(
+    `SELECT key_id, nonce, ciphertext, not_after, expires_at, sealed_jti FROM order_contact_vault
+     WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+    tenantId, stage, orderId,
+  );
+  if (!row || !isReadable(now, row.expires_at, row.not_after)) return { ok: false, status: 404, reason: "not-found" };
+  let opened: unknown | null;
+  try {
+    opened = await openVaultRecord(keyring, binding(tenantId, stage, orderId, row.not_after), {
+      keyId: row.key_id, nonce: row.nonce, ciphertext: row.ciphertext,
+    });
+  } catch (error) {
+    if (error instanceof VaultKeyUnavailableError) return { ok: false, status: 503, reason: "vault-key-unavailable" };
+    throw error;
+  }
+  if (opened === null || typeof opened !== "object") return { ok: false, status: 404, reason: "not-found" };
+  return { ok: true, contact: opened as OrderContact, expiresAt: row.expires_at < row.not_after ? row.expires_at : row.not_after };
+}
+
+/** Erase one order's contact: audit, tombstone and delete in one batch. */
+export async function eraseOrderContact(
+  db: Queryable,
+  input: { tenantId: string; stage: VaultStage; orderId: string; actor: ContactActor; auditId: string; now: Date },
+): Promise<EraseOutcome> {
+  const { tenantId, stage, orderId, actor, auditId, now } = input;
+  const nowIso = now.toISOString();
+  const exists = await db.first(
+    `SELECT 1 AS present FROM order_contact_vault WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+    tenantId, stage, orderId,
+  );
+  if (!exists) return { ok: false, status: 404, reason: "not-found" };
+  const rowSql = `SELECT 1 FROM order_contact_vault WHERE tenant_id = ? AND stage = ? AND order_id = ?`;
+  const audit = auditStatement({
+    auditId, tenantId, stage, recordKind: "order-contact", recordId: orderId, actor, action: "erase", now,
+    requireRow: { sql: rowSql, params: [tenantId, stage, orderId] },
+  });
+  const statements: QueryStatement[] = [
+    batchAuditStatement(audit),
+    {
+      sql: `INSERT INTO order_contact_tombstones (tenant_id, stage, order_id, reason, at, not_after)
+            SELECT tenant_id, stage, order_id, 'erased', ?, not_after FROM order_contact_vault
+            WHERE tenant_id = ? AND stage = ? AND order_id = ?
+              AND EXISTS (SELECT 1 FROM contact_access_audit WHERE audit_id = ?)
+            ON CONFLICT (tenant_id, stage, order_id) DO UPDATE SET reason = 'erased', at = excluded.at`,
+      params: [nowIso, tenantId, stage, orderId, auditId],
+    },
+    {
+      sql: `DELETE FROM order_contact_vault WHERE tenant_id = ? AND stage = ? AND order_id = ?
+              AND EXISTS (SELECT 1 FROM contact_access_audit WHERE audit_id = ?)`,
+      params: [tenantId, stage, orderId, auditId],
+    },
+  ];
+  try {
+    await requireBatch(db)(statements);
+  } catch {
+    return { ok: false, status: 503, reason: "audit-unavailable" };
+  }
+  const audited = await db.first(`SELECT 1 AS present FROM contact_access_audit WHERE audit_id = ?`, auditId);
+  if (audited) return { ok: true };
+  const still = await db.first(`SELECT 1 AS present FROM order_contact_vault WHERE tenant_id = ? AND stage = ? AND order_id = ?`, tenantId, stage, orderId);
+  return still ? { ok: false, status: 429, reason: "quota" } : { ok: false, status: 404, reason: "not-found" };
+}
+
+/** The statement that shortens an order's contact retention when the order becomes terminal. */
+export function terminalExpiryStatement(tenantId: string, stage: VaultStage, orderId: string, terminalAt: Date): { sql: string; params: unknown[] } {
+  return {
+    sql: `UPDATE order_contact_vault SET expires_at = MIN(expires_at, ?)
+          WHERE tenant_id = ? AND stage = ? AND order_id = ? AND expires_at > ?`,
+    params: [terminalExpiryFrom(terminalAt), tenantId, stage, orderId, terminalExpiryFrom(terminalAt)],
+  };
+}
+
+/**
+ * The same shortening for a fulfillment transition's own batch: it applies only when the order row
+ * reached a terminal state at exactly `version`, so a refused transition changes nothing.
+ */
+export function terminalTransitionExpiryStatement(
+  order: { tenantId: string; stage: VaultStage; orderId: string },
+  version: number,
+  terminalAt: Date,
+): { sql: string; params: unknown[] } {
+  const expiry = terminalExpiryFrom(terminalAt);
+  return {
+    sql: `UPDATE order_contact_vault SET expires_at = ?
+      WHERE tenant_id = ? AND stage = ? AND order_id = ? AND expires_at > ?
+        AND EXISTS (
+          SELECT 1 FROM scrappy_commerce_orders
+          WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
+            AND fulfillment_state IN ('handed_off', 'cancelled')
+        )`,
+    params: [expiry, order.tenantId, order.stage, order.orderId, expiry, order.tenantId, order.stage, order.orderId, version],
+  };
+}
+
+export interface PurgeCounts {
+  purged: number;
+  tombstonesRemoved: number;
+  shortened: number;
+}
+
+/**
+ * Purge expired order contacts. One batch tombstones and deletes every expired row (same `now`), so
+ * a later resend of a purged contact meets the tombstone. Then terminal orders still holding a
+ * longer expiry are shortened: to 180 days after their audited terminal time, or 180 days after
+ * now when no terminal time was audited (the ledger path), never later than they already were.
+ */
+export async function purgeOrderContacts(db: Queryable, now: Date, limit = 500): Promise<PurgeCounts> {
+  if (Number.isNaN(now.getTime())) throw new Error("vault purge: unreadable clock");
+  const nowIso = now.toISOString();
+  const before = await db.first<{ n: number }>(
+    `SELECT COUNT(*) AS n FROM order_contact_vault WHERE expires_at <= ? OR not_after <= ?`, nowIso, nowIso,
+  );
+  const tombsBefore = await db.first<{ n: number }>(`SELECT COUNT(*) AS n FROM order_contact_tombstones WHERE not_after <= ?`, nowIso);
+  await requireBatch(db)([
+    {
+      sql: `INSERT INTO order_contact_tombstones (tenant_id, stage, order_id, reason, at, not_after)
+            SELECT tenant_id, stage, order_id, 'purged', ?, not_after FROM order_contact_vault
+            WHERE expires_at <= ? OR not_after <= ?
+            ON CONFLICT (tenant_id, stage, order_id) DO NOTHING`,
+      params: [nowIso, nowIso, nowIso],
+    },
+    { sql: `DELETE FROM order_contact_vault WHERE expires_at <= ? OR not_after <= ?`, params: [nowIso, nowIso] },
+    { sql: `DELETE FROM order_contact_tombstones WHERE not_after <= ?`, params: [nowIso] },
+  ]);
+  const terminal = await db.all<{ tenant_id: string; stage: VaultStage; order_id: string; expires_at: string; at: string | null }>(
+    `SELECT v.tenant_id, v.stage, v.order_id, v.expires_at,
+            (SELECT MIN(a.at) FROM scrappy_shipment_audit a
+              WHERE a.tenant_id = v.tenant_id AND a.stage = v.stage AND a.order_id = v.order_id
+                AND ((a.kind = 'transition' AND a.to_state = 'handed_off') OR (a.kind = 'pending-cancel' AND a.to_state = 'confirmed'))) AS at
+     FROM order_contact_vault v
+     JOIN scrappy_commerce_orders o ON o.tenant_id = v.tenant_id AND o.stage = v.stage AND o.order_id = v.order_id
+     WHERE o.fulfillment_state IN ('handed_off', 'cancelled')
+     LIMIT ?`,
+    limit,
+  );
+  const updates: QueryStatement[] = [];
+  for (const row of terminal) {
+    const at = readInstant(row.at) ?? now;
+    const statement = terminalExpiryStatement(row.tenant_id, row.stage, row.order_id, at);
+    if (terminalExpiryFrom(at) < row.expires_at) updates.push(statement);
+  }
+  if (updates.length > 0) await requireBatch(db)(updates);
+  return {
+    purged: Number(before?.n ?? 0),
+    tombstonesRemoved: Number(tombsBefore?.n ?? 0),
+    shortened: updates.length,
+  };
+}

package/apps/storefront/src/lib/publication/d1/schema-apps.ts

@@ -550,31 +550,42 @@ export const newsletterSubscribers = sqliteTable(
 
 // --- Contact messages -------------------------------------------------------
 // Visitor messages from a store's contact form, written here FIRST so a message is
-// never lost to a mail failure. `tenantId` comes from the routed tenant, never a
-// client body; every read and write is scoped by it. `status`: unread | read.
+// never lost to a mail failure. `tenantId` comes from the routed tenant and `stage`
+// (preview | publication) from the routed customization environment, never a client
+// body; every read and write is scoped by both. The visitor's name, email, phone and
+// message exist only as a contact vault envelope (`keyId`, `nonce`, `ciphertext`;
+// lib/customers/contactVault/envelope.ts) whose AAD binds tenant, stage, id and `notAfter`.
+// `legacy*` hold plaintext only on rows from before migrations-apps/0021 until they
+// are sealed; triggers refuse writing any of them. `status`: unread | read.
 // `notifyStatus` (pending | sent | failed) and `notifyAttempts` belong to the
-// owner-notification sender. Rows are retained for 365 days (`purgeExpiredContactMessages`).
-// Timestamps are ISO-8601 text.
+// owner-notification sender. Rows are unreadable and purged at `expiresAt`
+// (`purgeExpiredContactMessages`). Timestamps are ISO-8601 text.
 export const contactMessages = sqliteTable(
   "contact_messages",
   {
     id: text("id").primaryKey(),
     tenantId: text("tenant_id").notNull(),
-    name: text("name").notNull().default(""),
-    email: text("email").notNull(),
-    phone: text("phone").notNull().default(""),
-    message: text("message").notNull(),
+    stage: text("stage").notNull(),
+    keyId: text("key_id"),
+    nonce: text("nonce"),
+    ciphertext: text("ciphertext"),
+    notAfter: text("not_after").notNull(),
+    expiresAt: text("expires_at").notNull(),
     pagePath: text("page_path"),
     status: text("status").notNull().default("unread"),
     createdAt: text("created_at").notNull(),
     readAt: text("read_at"),
     notifyStatus: text("notify_status").notNull().default("pending"),
     notifyAttempts: integer("notify_attempts").notNull().default(0),
+    legacyName: text("legacy_name"),
+    legacyEmail: text("legacy_email"),
+    legacyPhone: text("legacy_phone"),
+    legacyMessage: text("legacy_message"),
   },
   (t) => ({
-    idxContactTenantCreated: index("idx_contact_messages_tenant_created").on(t.tenantId, t.createdAt),
-    idxContactTenantStatus: index("idx_contact_messages_tenant_status").on(t.tenantId, t.status),
-    idxContactCreated: index("idx_contact_messages_created").on(t.createdAt),
+    idxContactTenantStageCreated: index("idx_contact_messages_tenant_stage_created").on(t.tenantId, t.stage, t.createdAt),
+    idxContactTenantStageStatus: index("idx_contact_messages_tenant_stage_status").on(t.tenantId, t.stage, t.status),
+    idxContactExpires: index("idx_contact_messages_expires").on(t.expiresAt),
   }),
 );
 

package/apps/storefront/src/lib/publication/shared/routedApiParam.ts

@@ -4,6 +4,9 @@ const ROUTES = {
   "pipeline-job": { path: /^\/api\/pipeline\/jobs\/([A-Za-z0-9._:-]{1,128})\/?$/, param: "jobId" },
   "fulfillment-order": { path: /^\/api\/admin\/fulfillment\/orders\/([A-Za-z0-9._:-]{1,128})\/?$/, param: "id" },
   "fulfillment-address": { path: /^\/api\/admin\/fulfillment\/orders\/([A-Za-z0-9._:-]{1,128})\/address\/?$/, param: "id" },
+  "fulfillment-contact-support-read": { path: /^\/api\/admin\/fulfillment\/orders\/([A-Za-z0-9._:-]{1,128})\/contact\/support-read\/?$/, param: "id" },
+  "fulfillment-contact-support-erase": { path: /^\/api\/admin\/fulfillment\/orders\/([A-Za-z0-9._:-]{1,128})\/contact\/support-erase\/?$/, param: "id" },
+  "message-support-read": { path: /^\/api\/admin\/messages\/([0-9a-f-]{36})\/support-read\/?$/, param: "id" },
 } as const;
 
 export type RoutedApiKind = keyof typeof ROUTES;

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

@@ -1,33 +1,36 @@
 import { routedApiParam } from "@/lib/publication/shared/routedApiParam";
 /**
- * Owner-only retrieval of a stored ship-to address.
- * The read runs only after the owner gate admits the caller.
+ * Owner retrieval and erase of an order's customer contact (name, email, phone, ship-to, bill-to)
+ * from the contact vault. ToT staff are refused here (403 support-read-required) and use the
+ * reason-and-grant routes under ./contact/. Every read and erase is audited before it acts.
  */
 import type { APIContext } from "astro";
-import { requireAdminApiEntry } from "@/lib/access/auth/adminApiGuard";
-import {
-  fulfillmentResultResponse,
-  isOpaqueId,
-  openFulfillment,
-} from "@/lib/fulfillment/fulfillmentService";
+import { isOpaqueId } from "@/lib/fulfillment/fulfillmentService";
+import { contactJson, openContactRoute } from "@/lib/orders/vault/contactRoutes";
+import { eraseOrderContact, readOrderContact } from "@/lib/orders/vault/orderContactVault";
 
 export const prerender = false;
 
 export async function GET(context: APIContext): Promise<Response> {
-  const access = await requireAdminApiEntry(context, { requireOwner: true });
-  if (!access.ok) {
-    return new Response(JSON.stringify({ error: access.reason }), {
-      status: access.status,
-      headers: {
-        "content-type": "application/json; charset=utf-8",
-        "cache-control": "no-store",
-        "x-robots-tag": "noindex, nofollow",
-      },
-    });
-  }
   const orderId = routedApiParam(context, "fulfillment-address");
-  if (!orderId || !isOpaqueId(orderId)) return fulfillmentResultResponse({ ok: false, code: "not-found" }, () => ({}));
-  const opened = await openFulfillment(context);
-  if (!opened.ok) return opened.response;
-  return fulfillmentResultResponse(await opened.service.readAddress(opened.actor, orderId), (address) => address);
+  if (!orderId || !isOpaqueId(orderId)) return contactJson({ error: "not-found" }, 404);
+  const route = await openContactRoute(context, "owner");
+  if (!route.ok) return route.response;
+  const read = await readOrderContact(route.db, route.keyring, {
+    tenantId: route.tenantId, stage: route.stage, orderId, actor: route.actor, auditId: crypto.randomUUID(), now: new Date(),
+  });
+  if (!read.ok) return contactJson({ error: read.reason }, read.status);
+  return contactJson({ ...read.contact, expiresAt: read.expiresAt }, 200);
+}
+
+export async function DELETE(context: APIContext): Promise<Response> {
+  const orderId = routedApiParam(context, "fulfillment-address");
+  if (!orderId || !isOpaqueId(orderId)) return contactJson({ error: "not-found" }, 404);
+  const route = await openContactRoute(context, "owner");
+  if (!route.ok) return route.response;
+  const erased = await eraseOrderContact(route.db, {
+    tenantId: route.tenantId, stage: route.stage, orderId, actor: route.actor, auditId: crypto.randomUUID(), now: new Date(),
+  });
+  if (!erased.ok) return contactJson({ error: erased.reason }, erased.status);
+  return contactJson({ erased: true }, 200);
 }

package/apps/storefront/src/pages/api/contact.ts

@@ -9,6 +9,10 @@
  * public, gets the success response and stores nothing. A missing secret, KV or D1
  * binding refuses with 503; the rate limiter fails closed. Responses never echo
  * input, and logs carry only tenant, submission id and outcome.
+ *
+ * The message is stored only as a contact vault envelope under the routed stage
+ * (`customizationEnv` live = publication, test = preview). An unknown stage refuses
+ * 409 and a missing or unreadable vault keyring refuses 503, both before any write.
  */
 import type { APIContext } from "astro";
 import { readD1, readEnv, readKv } from "@/lib/publication/shared/env";
@@ -16,6 +20,9 @@ import { fromD1 } from "@/lib/catalog/d1/catalog";
 import { checkRateLimit } from "@/lib/access/rate/kvWindow";
 import { hashConsentIp } from "@/lib/engagement/newsletter/consent";
 import { ContactMessagesStore } from "@/lib/engagement/contact/contactMessages";
+import { commerceStageForEnv } from "@/lib/fulfillment/fulfillmentService";
+import { loadVaultKeyring } from "@/lib/orders/vault/keyringEnv";
+import { VaultKeyUnavailableError } from "@/lib/customers/contactVault/envelope.js";
 import { verifyContactToken } from "@/lib/engagement/contact/submitToken";
 import { requestClientIp } from "@/lib/publication/shared/cdnForward";
 import {
@@ -100,9 +107,9 @@ export async function POST(context: APIContext): Promise<Response> {
   });
   if (!challenge.ok) return refuse("challenge_failed", "invalid_token", 403);
 
-  if (context.locals.storeNotPublic || context.locals.customizationEnv !== "live") {
-    return accept("not_public");
-  }
+  const stage = commerceStageForEnv(context.locals.customizationEnv);
+  if (!stage) return refuse("stage_unknown", "stage-unknown", 409);
+  if (context.locals.storeNotPublic) return accept("not_public");
 
   const kv = await readKv("TENANT_CACHE");
   const ip = await requestClientIp(request.headers, await readEnv("CDN_ORIGIN_SECRET"));
@@ -120,14 +127,19 @@ export async function POST(context: APIContext): Promise<Response> {
   const d1 = await readD1("STOREFRONT_APPS_DB");
   if (!d1) return refuse("no_database", "unavailable", 503);
 
+  const keyring = await loadVaultKeyring();
+  if (!keyring) return refuse("vault_key_unavailable", "unavailable", 503);
+
   try {
-    await new ContactMessagesStore(fromD1(d1)).insert({
+    await new ContactMessagesStore(fromD1(d1), keyring).insert({
       id: submissionId,
       tenantId,
+      stage,
       ...fields.fields,
       pagePath: sameOriginPagePath(request, expectedOrigin),
     });
   } catch (err) {
+    if (err instanceof VaultKeyUnavailableError) return refuse("vault_key_unavailable", "unavailable", 503);
     return refuse(`store_failed:${err instanceof Error ? err.name : "unknown"}`, "store_failed", 500);
   }
   return accept("stored");