@tokenoftrust/storefront-runner 4.9.2 → 4.10.0

package/apps/storefront/src/lib/customers/contactVault/envelope.ts

@@ -0,0 +1,166 @@
+/**
+ * Contact vault envelope: AES-256-GCM under a per-tenant, per-purpose HKDF subkey of one keyring
+ * key. The AAD binds tenant, stage, record id, key id and the immutable `notAfter`, so a row read
+ * under any other binding fails its tag and reads as absent.
+ *
+ * The keyring is the `ORDER_CONTACT_VAULT_KEYRING` Worker secret: JSON
+ * `{ active: <kid>, keys: { <kid>: <base64 of 32 bytes> } }`. Errors carry fixed codes only —
+ * never a key, nonce, ciphertext or plaintext value.
+ */
+
+export type VaultPurpose = "order-contact" | "contact-message";
+
+export interface VaultKeyring {
+  active: string;
+  keys: ReadonlyMap<string, Uint8Array>;
+}
+
+export interface VaultBinding {
+  purpose: VaultPurpose;
+  tenantId: string;
+  stage: string;
+  recordId: string;
+  notAfter: string;
+}
+
+export interface SealedEnvelope {
+  keyId: string;
+  nonce: string;
+  ciphertext: string;
+}
+
+export class VaultKeyUnavailableError extends Error {
+  readonly code = "vault-key-unavailable";
+  constructor() {
+    super("vault-key-unavailable");
+    this.name = "VaultKeyUnavailableError";
+  }
+}
+
+const KID = /^[A-Za-z0-9._-]{1,32}$/;
+const HKDF_SALT = new TextEncoder().encode("tot-contact-vault/v1");
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+function fromBase64(value: string): Uint8Array | null {
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
+  let binary: string;
+  try {
+    binary = atob(value);
+  } catch (error) {
+    if (error instanceof DOMException && error.name === "InvalidCharacterError") return null;
+    throw error;
+  }
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+
+function toBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+/** Parse the keyring secret, or null when it is absent or malformed in any way. */
+export function parseVaultKeyring(raw: string | undefined | null): VaultKeyring | null {
+  if (typeof raw !== "string" || raw.trim() === "") return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    if (error instanceof SyntaxError) return null;
+    throw error;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const { active, keys } = parsed as { active?: unknown; keys?: unknown };
+  if (typeof active !== "string" || !KID.test(active)) return null;
+  if (!keys || typeof keys !== "object" || Array.isArray(keys)) return null;
+  const map = new Map<string, Uint8Array>();
+  for (const [kid, value] of Object.entries(keys as Record<string, unknown>)) {
+    if (!KID.test(kid) || typeof value !== "string") return null;
+    const bytes = fromBase64(value);
+    if (!bytes || bytes.length !== 32) return null;
+    map.set(kid, bytes);
+  }
+  if (!map.has(active)) return null;
+  return { active, keys: map };
+}
+
+/** Canonical AAD bytes: fixed key order, so equal bindings always produce equal AAD. */
+export function vaultAad(binding: VaultBinding, keyId: string): Uint8Array {
+  return encoder.encode(JSON.stringify({
+    v: 1,
+    purpose: binding.purpose,
+    tenantId: binding.tenantId,
+    stage: binding.stage,
+    recordId: binding.recordId,
+    keyId,
+    notAfter: binding.notAfter,
+  }));
+}
+
+async function subkey(keyring: VaultKeyring, keyId: string, binding: VaultBinding): Promise<CryptoKey> {
+  const ikm = keyring.keys.get(keyId);
+  if (!ikm) throw new VaultKeyUnavailableError();
+  const base = await crypto.subtle.importKey("raw", ikm as BufferSource, "HKDF", false, ["deriveKey"]);
+  return crypto.subtle.deriveKey(
+    { name: "HKDF", hash: "SHA-256", salt: HKDF_SALT, info: encoder.encode(`${binding.purpose}|${binding.tenantId}`) },
+    base,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"],
+  );
+}
+
+/** Seal a JSON value under the keyring's active key. */
+export async function sealVaultRecord(
+  keyring: VaultKeyring | null,
+  binding: VaultBinding,
+  value: unknown,
+): Promise<SealedEnvelope> {
+  if (!keyring) throw new VaultKeyUnavailableError();
+  const keyId = keyring.active;
+  const key = await subkey(keyring, keyId, binding);
+  const nonce = crypto.getRandomValues(new Uint8Array(12));
+  const sealed = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv: nonce, additionalData: vaultAad(binding, keyId) as BufferSource },
+    key,
+    encoder.encode(JSON.stringify(value)),
+  );
+  return { keyId, nonce: toBase64(nonce), ciphertext: toBase64(new Uint8Array(sealed)) };
+}
+
+/**
+ * Open a sealed record. Null when the binding, nonce or ciphertext does not authenticate — callers
+ * report that as not-found. A missing keyring or key id throws {@link VaultKeyUnavailableError}.
+ */
+export async function openVaultRecord(
+  keyring: VaultKeyring | null,
+  binding: VaultBinding,
+  envelope: SealedEnvelope,
+): Promise<unknown | null> {
+  if (!keyring) throw new VaultKeyUnavailableError();
+  const key = await subkey(keyring, envelope.keyId, binding);
+  const nonce = fromBase64(envelope.nonce);
+  const ciphertext = fromBase64(envelope.ciphertext);
+  if (!nonce || nonce.length !== 12 || !ciphertext) return null;
+  let plain: ArrayBuffer;
+  try {
+    plain = await crypto.subtle.decrypt(
+      { name: "AES-GCM", iv: nonce as BufferSource, additionalData: vaultAad(binding, envelope.keyId) as BufferSource },
+      key,
+      ciphertext as BufferSource,
+    );
+  } catch (error) {
+    // AES-GCM reports a failed tag (wrong binding, key or bytes) as OperationError; anything else is a fault.
+    if (error instanceof DOMException && error.name === "OperationError") return null;
+    throw error;
+  }
+  try {
+    return JSON.parse(decoder.decode(plain));
+  } catch (error) {
+    if (error instanceof SyntaxError) return null;
+    throw error;
+  }
+}

package/apps/storefront/src/lib/customers/contactVault/retention.ts

@@ -0,0 +1,44 @@
+/**
+ * Contact vault retention. `notAfter` is the hard ceiling bound into the AAD: 365 days after the
+ * order was placed (or the message was received). Once an order is terminal (handed off or
+ * cancelled) its contact expires 180 days after that, never later than `notAfter`.
+ */
+
+export const CONTACT_RETENTION_DAYS = 365;
+export const TERMINAL_RETENTION_DAYS = 180;
+const DAY_MS = 86_400_000;
+
+const ISO_INSTANT = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:?\d{2})$/;
+
+/** A strict ISO instant with an explicit zone and real calendar fields, or null. */
+export function readInstant(value: unknown): Date | null {
+  if (typeof value !== "string") return null;
+  const match = ISO_INSTANT.exec(value);
+  if (!match) return null;
+  const [year, month, day, hour, minute, second] = match.slice(1, 7).map((part) => Number(part ?? 0));
+  const calendar = new Date(Date.UTC(year!, month! - 1, day!));
+  if (calendar.getUTCMonth() !== month! - 1 || calendar.getUTCDate() !== day! || hour! > 23 || minute! > 59 || second! > 59) return null;
+  const parsed = new Date(value);
+  return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+
+export function notAfterFrom(start: Date): string {
+  return new Date(start.getTime() + CONTACT_RETENTION_DAYS * DAY_MS).toISOString();
+}
+
+/** The expiry for a record whose ceiling is `notAfter`, given the order's terminal time if any. */
+export function expiresAtFor(notAfter: string, terminalAt: Date | null): string {
+  if (!terminalAt) return notAfter;
+  const terminal = new Date(terminalAt.getTime() + TERMINAL_RETENTION_DAYS * DAY_MS).toISOString();
+  return terminal < notAfter ? terminal : notAfter;
+}
+
+/** True while a record may still be read: strictly before both its expiry and its ceiling. */
+export function isReadable(now: Date, expiresAt: string, notAfter: string): boolean {
+  const iso = now.toISOString();
+  return iso < expiresAt && iso < notAfter;
+}
+
+export function terminalExpiryFrom(at: Date): string {
+  return new Date(at.getTime() + TERMINAL_RETENTION_DAYS * DAY_MS).toISOString();
+}

package/apps/storefront/src/lib/engagement/contact/contactMessages.ts

@@ -1,20 +1,41 @@
 /**
  * `contact_messages` store — visitor messages from a store's contact form, kept in
- * `STOREFRONT_APPS_DB`. Pure over a minimal SQL seam, so the Worker runs it
+ * `STOREFRONT_APPS_DB` (migrations-apps/0021). Pure over a minimal SQL seam, so the Worker runs it
  * against D1 and tests against `node:sqlite`.
  *
- * Every method takes the tenant id and scopes its SQL by it: an id belonging to
- * another tenant is indistinguishable from an id that does not exist. The caller
- * resolves `tenantId` from the routed tenant, never from a request body.
+ * The visitor's name, email, phone and message exist at rest only as one contact vault envelope
+ * (`lib/customers/contactVault/envelope.ts`, purpose `contact-message`) whose AAD binds tenant, stage, message
+ * id and the immutable `not_after`. A row still holding legacy plaintext is never read; the rollout
+ * and the hourly sweep seal it ({@link sealLegacyContactMessages}).
+ *
+ * Every method takes the tenant id and the routed stage and scopes its SQL by both: an id belonging
+ * to another tenant or stage is indistinguishable from an id that does not exist. Every read writes
+ * its `contact_access_audit` row before anything is decrypted. Nothing here logs.
  */
+import {
+  openVaultRecord,
+  sealVaultRecord,
+  VaultKeyUnavailableError,
+  type VaultBinding,
+  type VaultKeyring,
+} from "@/lib/customers/contactVault/envelope.js";
+import { isReadable, notAfterFrom } from "@/lib/customers/contactVault/retention.js";
+import { admitAudit, auditStatement, type ContactActor, type VaultStage } from "@/lib/customers/contactVault/contactAudit.js";
+
+interface QueryStatement {
+  sql: string;
+  params?: readonly unknown[];
+}
+
 /** The SQL surface this store needs; D1's `fromD1` and the test harness both satisfy it. */
 export interface ContactDb {
   all<T = Record<string, unknown>>(sql: string, ...params: unknown[]): Promise<T[]>;
   first<T = Record<string, unknown>>(sql: string, ...params: unknown[]): Promise<T | null>;
   run(sql: string, ...params: unknown[]): Promise<void>;
+  /** D1 executes a batch sequentially inside one implicit transaction. */
+  batch?(statements: readonly QueryStatement[]): Promise<void>;
 }
 
-export const CONTACT_RETENTION_DAYS = 365;
 export const CONTACT_LIST_LIMIT = 200;
 
 export type ContactMessageStatus = "unread" | "read";
@@ -22,6 +43,7 @@ export type ContactMessageStatus = "unread" | "read";
 export interface NewContactMessage {
   id: string;
   tenantId: string;
+  stage: VaultStage;
   name: string;
   email: string;
   phone: string;
@@ -41,114 +63,269 @@ export interface ContactMessage {
   readAt: string | null;
 }
 
-interface ContactMessageRow {
+export type ContactRefusal =
+  | { ok: false; status: 404; reason: "not-found" }
+  | { ok: false; status: 429; reason: "quota" }
+  | { ok: false; status: 503; reason: "audit-unavailable" | "vault-key-unavailable" };
+
+export type ListOutcome = { ok: true; messages: ContactMessage[] } | ContactRefusal;
+export type SupportReadOutcome = { ok: true; message: ContactMessage } | ContactRefusal;
+export type EraseOutcome = { ok: true } | ContactRefusal;
+
+interface SealedRow {
   id: string;
-  name: string;
-  email: string;
-  phone: string;
-  message: string;
+  key_id: string;
+  nonce: string;
+  ciphertext: string;
+  not_after: string;
+  expires_at: string;
   page_path: string | null;
   status: string;
   created_at: string;
   read_at: string | null;
 }
 
-function toMessage(row: ContactMessageRow): ContactMessage {
-  return {
-    id: row.id,
-    name: row.name,
-    email: row.email,
-    phone: row.phone,
-    message: row.message,
-    pagePath: row.page_path,
-    status: row.status === "read" ? "read" : "unread",
-    createdAt: row.created_at,
-    readAt: row.read_at,
-  };
+interface ContactPlaintext {
+  name: string;
+  email: string;
+  phone: string;
+  message: string;
+}
+
+const SEALED_COLUMNS = "id, key_id, nonce, ciphertext, not_after, expires_at, page_path, status, created_at, read_at";
+/** A row the store may act on: sealed, and strictly before both its expiry and its ceiling. */
+const READABLE = "ciphertext IS NOT NULL AND ? < expires_at AND ? < not_after";
+
+function binding(tenantId: string, stage: VaultStage, id: string, notAfter: string): VaultBinding {
+  return { purpose: "contact-message", tenantId, stage, recordId: id, notAfter };
+}
+
+function requireBatch(db: ContactDb): NonNullable<ContactDb["batch"]> {
+  if (!db.batch) throw new Error("D1 batch is unavailable");
+  return db.batch.bind(db);
+}
+
+function asPlaintext(value: unknown): ContactPlaintext | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const v = value as Record<string, unknown>;
+  const fields = [v.name, v.email, v.phone, v.message];
+  if (!fields.every((f) => typeof f === "string")) return null;
+  return { name: v.name as string, email: v.email as string, phone: v.phone as string, message: v.message as string };
 }
 
 export class ContactMessagesStore {
   constructor(
     private readonly db: ContactDb,
+    private readonly keyring: VaultKeyring | null,
     private readonly now: () => Date = () => new Date(),
   ) {}
 
+  /** Seal and store one message. Throws {@link VaultKeyUnavailableError} (writing nothing) without a keyring. */
   async insert(input: NewContactMessage): Promise<void> {
+    const created = this.now();
+    const notAfter = notAfterFrom(created);
+    const plaintext: ContactPlaintext = { name: input.name, email: input.email, phone: input.phone, message: input.message };
+    const sealed = await sealVaultRecord(this.keyring, binding(input.tenantId, input.stage, input.id, notAfter), plaintext);
     await this.db.run(
       `INSERT INTO contact_messages
-         (id, tenant_id, name, email, phone, message, page_path, status, created_at, notify_status, notify_attempts)
-       VALUES (?, ?, ?, ?, ?, ?, ?, 'unread', ?, 'pending', 0)`,
+         (id, tenant_id, stage, key_id, nonce, ciphertext, not_after, expires_at, page_path, status, created_at, notify_status, notify_attempts)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'unread', ?, 'pending', 0)`,
       input.id,
       input.tenantId,
-      input.name,
-      input.email,
-      input.phone,
-      input.message,
+      input.stage,
+      sealed.keyId,
+      sealed.nonce,
+      sealed.ciphertext,
+      notAfter,
+      notAfter,
       input.pagePath,
-      this.now().toISOString(),
+      created.toISOString(),
     );
   }
 
-  /** Newest first, capped at {@link CONTACT_LIST_LIMIT}. */
-  async list(tenantId: string): Promise<ContactMessage[]> {
-    const rows = await this.db.all<ContactMessageRow>(
-      `SELECT id, name, email, phone, message, page_path, status, created_at, read_at
-         FROM contact_messages
-        WHERE tenant_id = ?
+  /** The owner inbox: one `list` audit row commits, then newest first, capped at {@link CONTACT_LIST_LIMIT}. */
+  async list(tenantId: string, stage: VaultStage, actor: ContactActor, auditId: string): Promise<ListOutcome> {
+    if (!this.keyring) return { ok: false, status: 503, reason: "vault-key-unavailable" };
+    const now = this.now();
+    const admitted = await admitAudit(this.db, auditStatement({
+      auditId, tenantId, stage, recordKind: "contact-message", recordId: "*", actor, action: "list", now,
+    }));
+    if (admitted === "quota") return { ok: false, status: 429, reason: "quota" };
+    if (admitted === "unavailable") return { ok: false, status: 503, reason: "audit-unavailable" };
+    const iso = now.toISOString();
+    const rows = await this.db.all<SealedRow>(
+      `SELECT ${SEALED_COLUMNS} FROM contact_messages
+        WHERE tenant_id = ? AND stage = ? AND ${READABLE}
         ORDER BY created_at DESC, id DESC
         LIMIT ?`,
-      tenantId,
-      CONTACT_LIST_LIMIT,
+      tenantId, stage, iso, iso, CONTACT_LIST_LIMIT,
+    );
+    const messages: ContactMessage[] = [];
+    for (const row of rows) {
+      const message = await this.open(tenantId, stage, row, now);
+      if (message) messages.push(message);
+    }
+    return { ok: true, messages };
+  }
+
+  /**
+   * ToT support reads one message. The caller has already proven a live staff selection and a live
+   * owner-consented grant; the audit row (with the staff quota in the same statement) commits first.
+   */
+  async supportRead(tenantId: string, stage: VaultStage, id: string, actor: ContactActor, auditId: string): Promise<SupportReadOutcome> {
+    if (!this.keyring) return { ok: false, status: 503, reason: "vault-key-unavailable" };
+    const now = this.now();
+    const admitted = await admitAudit(this.db, auditStatement({
+      auditId, tenantId, stage, recordKind: "contact-message", recordId: id, 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 iso = now.toISOString();
+    const row = await this.db.first<SealedRow>(
+      `SELECT ${SEALED_COLUMNS} FROM contact_messages WHERE tenant_id = ? AND stage = ? AND id = ? AND ${READABLE}`,
+      tenantId, stage, id, iso, iso,
     );
-    return rows.map(toMessage);
+    const message = row ? await this.open(tenantId, stage, row, now) : null;
+    return message ? { ok: true, message } : { ok: false, status: 404, reason: "not-found" };
   }
 
-  async unreadCount(tenantId: string): Promise<number> {
+  async unreadCount(tenantId: string, stage: VaultStage): Promise<number> {
+    const iso = this.now().toISOString();
     const row = await this.db.first<{ n: number }>(
-      `SELECT COUNT(*) AS n FROM contact_messages WHERE tenant_id = ? AND status = 'unread'`,
-      tenantId,
+      `SELECT COUNT(*) AS n FROM contact_messages WHERE tenant_id = ? AND stage = ? AND status = 'unread' AND ${READABLE}`,
+      tenantId, stage, iso, iso,
     );
     return Number(row?.n ?? 0);
   }
 
-  /** True when the tenant owns a message with this id (now marked read). */
-  async markRead(tenantId: string, id: string): Promise<boolean> {
+  /** True when the tenant holds a readable message with this id in this stage (now marked read). */
+  async markRead(tenantId: string, stage: VaultStage, id: string): Promise<boolean> {
+    const iso = this.now().toISOString();
     const rows = await this.db.all<{ id: string }>(
       `UPDATE contact_messages
           SET status = 'read', read_at = COALESCE(read_at, ?)
-        WHERE tenant_id = ? AND id = ?
+        WHERE tenant_id = ? AND stage = ? AND id = ? AND ${READABLE}
         RETURNING id`,
-      this.now().toISOString(),
-      tenantId,
-      id,
+      iso, tenantId, stage, id, iso, iso,
     );
     return rows.length > 0;
   }
 
-  /** True when the tenant owned a message with this id (now deleted). */
-  async delete(tenantId: string, id: string): Promise<boolean> {
-    const rows = await this.db.all<{ id: string }>(
-      `DELETE FROM contact_messages WHERE tenant_id = ? AND id = ? RETURNING id`,
-      tenantId,
-      id,
-    );
-    return rows.length > 0;
+  /** Erase one sealed message: its audit row and its delete commit in one batch, or neither does. */
+  async erase(tenantId: string, stage: VaultStage, id: string, actor: ContactActor, auditId: string): Promise<EraseOutcome> {
+    const now = this.now();
+    const rowSql = `SELECT 1 FROM contact_messages WHERE tenant_id = ? AND stage = ? AND id = ? AND ciphertext IS NOT NULL`;
+    const exists = await this.db.first(rowSql, tenantId, stage, id);
+    if (!exists) return { ok: false, status: 404, reason: "not-found" };
+    const audit = auditStatement({
+      auditId, tenantId, stage, recordKind: "contact-message", recordId: id, actor, action: "erase", now,
+      requireRow: { sql: rowSql, params: [tenantId, stage, id] },
+    });
+    const statements: QueryStatement[] = [
+      { sql: audit.sql.replace(/\s*RETURNING audit_id$/, ""), params: audit.params },
+      {
+        sql: `DELETE FROM contact_messages WHERE tenant_id = ? AND stage = ? AND id = ? AND ciphertext IS NOT NULL
+                AND EXISTS (SELECT 1 FROM contact_access_audit WHERE audit_id = ?)`,
+        params: [tenantId, stage, id, auditId],
+      },
+    ];
+    try {
+      await requireBatch(this.db)(statements);
+    } catch {
+      return { ok: false, status: 503, reason: "audit-unavailable" };
+    }
+    const audited = await this.db.first(`SELECT 1 AS present FROM contact_access_audit WHERE audit_id = ?`, auditId);
+    if (audited) return { ok: true };
+    const still = await this.db.first(rowSql, tenantId, stage, id);
+    return still ? { ok: false, status: 429, reason: "quota" } : { ok: false, status: 404, reason: "not-found" };
+  }
+
+  /** Decrypt one row, or null when it is past retention or does not authenticate under its binding. */
+  private async open(tenantId: string, stage: VaultStage, row: SealedRow, now: Date): Promise<ContactMessage | null> {
+    if (!isReadable(now, row.expires_at, row.not_after)) return null;
+    const opened = await openVaultRecord(this.keyring, binding(tenantId, stage, row.id, row.not_after), {
+      keyId: row.key_id, nonce: row.nonce, ciphertext: row.ciphertext,
+    }).catch((error: unknown) => {
+      if (error instanceof VaultKeyUnavailableError) return null;
+      throw error;
+    });
+    const plain = asPlaintext(opened);
+    if (!plain) return null;
+    return {
+      id: row.id,
+      ...plain,
+      pagePath: row.page_path,
+      status: row.status === "read" ? "read" : "unread",
+      createdAt: row.created_at,
+      readAt: row.read_at,
+    };
   }
 }
 
 /**
- * Delete every message older than the retention window, across all tenants.
- * Returns the number of rows removed.
+ * Delete every message at or past its expiry or its ceiling, across all tenants and stages (legacy
+ * rows included). Returns the number of rows removed. An unreadable clock throws.
  */
-export async function purgeExpiredContactMessages(
-  db: ContactDb,
-  now: Date = new Date(),
-  retentionDays: number = CONTACT_RETENTION_DAYS,
-): Promise<number> {
-  const cutoff = new Date(now.getTime() - retentionDays * 86_400_000).toISOString();
+export async function purgeExpiredContactMessages(db: ContactDb, now: Date): Promise<number> {
+  if (Number.isNaN(now.getTime())) throw new Error("contact message purge: unreadable clock");
+  const iso = now.toISOString();
   const rows = await db.all<{ id: string }>(
-    `DELETE FROM contact_messages WHERE created_at < ? RETURNING id`,
-    cutoff,
+    `DELETE FROM contact_messages WHERE expires_at <= ? OR not_after <= ? RETURNING id`,
+    iso, iso,
   );
   return rows.length;
 }
+
+interface LegacyRow {
+  id: string;
+  tenant_id: string;
+  stage: VaultStage;
+  not_after: string;
+  legacy_name: string | null;
+  legacy_email: string | null;
+  legacy_phone: string | null;
+  legacy_message: string | null;
+}
+
+/**
+ * Seal up to `limit` rows still holding legacy plaintext (oldest id first), across all tenants.
+ * Each row is one statement: the envelope is written and every `legacy_*` column nulled together,
+ * only while the row is still unsealed. `remaining` counts the unsealed rows left.
+ */
+export async function sealLegacyContactMessages(
+  db: ContactDb,
+  keyring: VaultKeyring,
+  now: Date,
+  limit: number,
+): Promise<{ sealed: number; remaining: number }> {
+  if (Number.isNaN(now.getTime())) throw new Error("contact message sealing: unreadable clock");
+  const rows = await db.all<LegacyRow>(
+    `SELECT id, tenant_id, stage, not_after, legacy_name, legacy_email, legacy_phone, legacy_message
+       FROM contact_messages WHERE ciphertext IS NULL
+      ORDER BY id LIMIT ?`,
+    Math.max(0, Math.floor(limit)),
+  );
+  let sealed = 0;
+  for (const row of rows) {
+    const plaintext: ContactPlaintext = {
+      name: row.legacy_name ?? "",
+      email: row.legacy_email ?? "",
+      phone: row.legacy_phone ?? "",
+      message: row.legacy_message ?? "",
+    };
+    const envelope = await sealVaultRecord(keyring, binding(row.tenant_id, row.stage, row.id, row.not_after), plaintext);
+    const changed = await db.all<{ id: string }>(
+      `UPDATE contact_messages
+          SET key_id = ?, nonce = ?, ciphertext = ?,
+              legacy_name = NULL, legacy_email = NULL, legacy_phone = NULL, legacy_message = NULL
+        WHERE id = ? AND ciphertext IS NULL
+        RETURNING id`,
+      envelope.keyId, envelope.nonce, envelope.ciphertext, row.id,
+    );
+    sealed += changed.length;
+  }
+  const left = await db.first<{ n: number }>(
+    `SELECT COUNT(*) AS n FROM contact_messages WHERE ciphertext IS NULL`,
+  );
+  return { sealed, remaining: Number(left?.n ?? 0) };
+}

package/apps/storefront/src/lib/engagement/contact/contract.ts

@@ -8,6 +8,7 @@
  *                                         → 200 { ok:true }
  *                                           400 invalid_json | invalid_input (+ field)
  *                                           403 forbidden_origin | invalid_token
+ *                                           409 stage-unknown (the store's stage could not be resolved)
  *                                           413 too_large · 415 unsupported_media_type
  *                                           429 rate_limited · 503 unavailable
  *                                           500 store_failed (keep the visitor's text and retry)
@@ -56,6 +57,7 @@ export type ContactErrorCode =
   | "unsupported_media_type"
   | "rate_limited"
   | "unavailable"
+  | "stage-unknown"
   | "store_failed";
 
 export type ContactSubmitResponse =

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

@@ -104,7 +104,6 @@ export async function projectCommerceOrder(
           }
         : {}),
       lines,
-      address: null,
       compliance: trusted ? snapshot.compliance : "UNKNOWN",
       stock: trusted && snapshot.payment === "captured" ? "confirmed" : "UNKNOWN",
       fulfillment: