@tokenoftrust/storefront-runner 4.9.1 → 4.9.3

package/apps/storefront/migrations-apps/0021_contact_vault.sql

@@ -0,0 +1,162 @@
+-- Contact vault: order customer contact and contact-form messages are stored only as AES-256-GCM
+-- envelopes (src/lib/orders/vault/envelope.ts) in expiring rows. One transaction per file.
+--
+-- The plaintext scrappy_order_addresses table is dropped only when it is empty: the guard row's
+-- CHECK fails on any other count and aborts the whole file.
+CREATE TABLE `_gv_vault_guard` (`n` integer NOT NULL CHECK (`n` = 0));
+--> statement-breakpoint
+INSERT INTO `_gv_vault_guard` (`n`) SELECT COUNT(*) FROM `scrappy_order_addresses`;
+--> statement-breakpoint
+DROP TABLE `_gv_vault_guard`;
+--> statement-breakpoint
+DROP TABLE `scrappy_order_addresses`;
+--> statement-breakpoint
+CREATE TABLE `order_contact_vault` (
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (stage IN ('preview', 'publication')),
+  `order_id` text NOT NULL,
+  `key_id` text NOT NULL,
+  `nonce` text NOT NULL,
+  `ciphertext` text NOT NULL,
+  `not_after` text NOT NULL,
+  `expires_at` text NOT NULL CHECK (`expires_at` <= `not_after`),
+  `sealed_at` text NOT NULL,
+  `sealed_jti` text NOT NULL,
+  PRIMARY KEY (`tenant_id`, `stage`, `order_id`),
+  FOREIGN KEY (`tenant_id`, `stage`, `order_id`) REFERENCES `scrappy_commerce_orders` (`tenant_id`, `stage`, `order_id`)
+);
+--> statement-breakpoint
+CREATE INDEX `idx_order_contact_vault_expires` ON `order_contact_vault` (`expires_at`);
+--> statement-breakpoint
+CREATE INDEX `idx_order_contact_vault_key` ON `order_contact_vault` (`key_id`);
+--> statement-breakpoint
+CREATE TRIGGER `order_contact_vault_retention_only_shrinks`
+BEFORE UPDATE ON `order_contact_vault`
+WHEN NEW.`expires_at` > OLD.`expires_at`
+  OR NEW.`not_after` IS NOT OLD.`not_after`
+  OR NEW.`key_id` IS NOT OLD.`key_id`
+  OR NEW.`nonce` IS NOT OLD.`nonce`
+  OR NEW.`ciphertext` IS NOT OLD.`ciphertext`
+  OR NEW.`tenant_id` IS NOT OLD.`tenant_id`
+  OR NEW.`stage` IS NOT OLD.`stage`
+  OR NEW.`order_id` IS NOT OLD.`order_id`
+BEGIN
+  SELECT RAISE(ABORT, 'vault-immutable');
+END;
+--> statement-breakpoint
+CREATE TABLE `order_contact_tombstones` (
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (stage IN ('preview', 'publication')),
+  `order_id` text NOT NULL,
+  `reason` text NOT NULL CHECK (`reason` IN ('purged', 'erased')),
+  `at` text NOT NULL,
+  `not_after` text NOT NULL,
+  PRIMARY KEY (`tenant_id`, `stage`, `order_id`)
+);
+--> statement-breakpoint
+CREATE INDEX `idx_order_contact_tombstones_not_after` ON `order_contact_tombstones` (`not_after`);
+--> statement-breakpoint
+CREATE TABLE `contact_access_audit` (
+  `audit_id` text NOT NULL PRIMARY KEY,
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (stage IN ('preview', 'publication')),
+  `record_kind` text NOT NULL CHECK (`record_kind` IN ('order-contact', 'contact-message')),
+  `record_id` text NOT NULL,
+  `at` text NOT NULL,
+  `actor_id` text NOT NULL,
+  `actor_role` text NOT NULL CHECK (`actor_role` IN ('owner', 'staff')),
+  `reason_code` text,
+  `ticket_ref` text,
+  `action` text NOT NULL CHECK (`action` IN ('read', 'list', 'erase')),
+  `outcome` text NOT NULL CHECK (`outcome` = 'admitted'),
+  CHECK (`actor_role` = 'owner' OR (`reason_code` IS NOT NULL AND `ticket_ref` IS NOT NULL))
+);
+--> statement-breakpoint
+CREATE INDEX `idx_contact_access_audit_quota` ON `contact_access_audit` (`tenant_id`, `actor_id`, `actor_role`, `at`);
+--> statement-breakpoint
+CREATE TRIGGER `contact_access_audit_no_update`
+BEFORE UPDATE ON `contact_access_audit`
+BEGIN
+  SELECT RAISE(ABORT, 'append-only');
+END;
+--> statement-breakpoint
+CREATE TRIGGER `contact_access_audit_no_delete`
+BEFORE DELETE ON `contact_access_audit`
+BEGIN
+  SELECT RAISE(ABORT, 'append-only');
+END;
+--> statement-breakpoint
+-- contact_messages: every pre-existing row is kept as a legacy row (plaintext in legacy_* until
+-- the rollout seals it) under stage publication; new rows are written sealed only.
+CREATE TABLE `contact_messages_sealed` (
+  `id` text PRIMARY KEY NOT NULL,
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (stage IN ('preview', 'publication')),
+  `key_id` text,
+  `nonce` text,
+  `ciphertext` text,
+  `not_after` text NOT NULL,
+  `expires_at` text NOT NULL CHECK (`expires_at` <= `not_after`),
+  `page_path` text,
+  `status` text NOT NULL DEFAULT 'unread' CHECK (`status` IN ('unread', 'read')),
+  `created_at` text NOT NULL,
+  `read_at` text,
+  `notify_status` text NOT NULL DEFAULT 'pending' CHECK (`notify_status` IN ('pending', 'sent', 'failed')),
+  `notify_attempts` integer NOT NULL DEFAULT 0,
+  `legacy_name` text,
+  `legacy_email` text,
+  `legacy_phone` text,
+  `legacy_message` text,
+  CHECK (
+    (`key_id` IS NOT NULL AND `nonce` IS NOT NULL AND `ciphertext` IS NOT NULL
+      AND `legacy_name` IS NULL AND `legacy_email` IS NULL AND `legacy_phone` IS NULL AND `legacy_message` IS NULL)
+    OR (`key_id` IS NULL AND `nonce` IS NULL AND `ciphertext` IS NULL
+      AND `legacy_email` IS NOT NULL AND `legacy_message` IS NOT NULL)
+  )
+);
+--> statement-breakpoint
+INSERT INTO `contact_messages_sealed`
+  (`id`, `tenant_id`, `stage`, `not_after`, `expires_at`, `page_path`, `status`, `created_at`, `read_at`,
+   `notify_status`, `notify_attempts`, `legacy_name`, `legacy_email`, `legacy_phone`, `legacy_message`)
+SELECT `id`, `tenant_id`, 'publication',
+       strftime('%Y-%m-%dT%H:%M:%fZ', `created_at`, '+365 days'),
+       strftime('%Y-%m-%dT%H:%M:%fZ', `created_at`, '+365 days'),
+       `page_path`, `status`, `created_at`, `read_at`, `notify_status`, `notify_attempts`,
+       `name`, `email`, `phone`, `message`
+FROM `contact_messages`;
+--> statement-breakpoint
+DROP TABLE `contact_messages`;
+--> statement-breakpoint
+ALTER TABLE `contact_messages_sealed` RENAME TO `contact_messages`;
+--> statement-breakpoint
+CREATE INDEX `idx_contact_messages_tenant_stage_created` ON `contact_messages` (`tenant_id`, `stage`, `created_at`);
+--> statement-breakpoint
+CREATE INDEX `idx_contact_messages_tenant_stage_status` ON `contact_messages` (`tenant_id`, `stage`, `status`);
+--> statement-breakpoint
+CREATE INDEX `idx_contact_messages_expires` ON `contact_messages` (`expires_at`);
+--> statement-breakpoint
+CREATE INDEX `idx_contact_messages_legacy` ON `contact_messages` (`id`) WHERE `ciphertext` IS NULL;
+--> statement-breakpoint
+CREATE TRIGGER `contact_messages_no_plaintext_insert`
+BEFORE INSERT ON `contact_messages`
+WHEN NEW.`legacy_name` IS NOT NULL OR NEW.`legacy_email` IS NOT NULL
+  OR NEW.`legacy_phone` IS NOT NULL OR NEW.`legacy_message` IS NOT NULL
+BEGIN
+  SELECT RAISE(ABORT, 'plaintext-refused');
+END;
+--> statement-breakpoint
+CREATE TRIGGER `contact_messages_no_plaintext_update`
+BEFORE UPDATE ON `contact_messages`
+WHEN (NEW.`legacy_name` IS NOT NULL AND NEW.`legacy_name` IS NOT OLD.`legacy_name`)
+  OR (NEW.`legacy_email` IS NOT NULL AND NEW.`legacy_email` IS NOT OLD.`legacy_email`)
+  OR (NEW.`legacy_phone` IS NOT NULL AND NEW.`legacy_phone` IS NOT OLD.`legacy_phone`)
+  OR (NEW.`legacy_message` IS NOT NULL AND NEW.`legacy_message` IS NOT OLD.`legacy_message`)
+  OR NEW.`expires_at` > OLD.`expires_at`
+  OR NEW.`not_after` IS NOT OLD.`not_after`
+  OR (OLD.`ciphertext` IS NOT NULL AND (NEW.`ciphertext` IS NOT OLD.`ciphertext`
+    OR NEW.`key_id` IS NOT OLD.`key_id` OR NEW.`nonce` IS NOT OLD.`nonce`))
+  OR NEW.`tenant_id` IS NOT OLD.`tenant_id`
+  OR NEW.`stage` IS NOT OLD.`stage`
+BEGIN
+  SELECT RAISE(ABORT, 'vault-immutable');
+END;

package/apps/storefront/src/lib/access/auth/contactReaderAuthority.ts

@@ -0,0 +1,64 @@
+/**
+ * Who may read customer contact data on THIS tenant, and on what authority.
+ *
+ * `isOwnerViewer` is not membership: a ToT-staff selection carries a capability, and a selection
+ * whose capability is `owner` makes `isOwnerViewer` true (loginGate `sessionHostCapability`). Contact
+ * reads must tell the two apart, because reading order and customer PII is grant-required for staff
+ * (guidance://access-authority) while an owner reads their own store's data. So:
+ *
+ *   owner — a `tenants[]` membership for this host, or a session scoped to this host
+ *           (`record.resource === host`), whose role is owner or admin. A staff selection never
+ *           counts, whatever its capability.
+ *   staff — no owner standing, but a live staff selection for this host. Staff still need a live
+ *           `customer-contact-read` grant ({@link resolveContactReadGrant}) and a reason.
+ *   none  — anything else.
+ */
+import type { SessionRecord } from "./session.js";
+import { normalizeMemberships, staffAdmits } from "@/lib/access/dashboard/tenantSelection";
+import { isOwnerCapability } from "@/lib/access/shared/capability";
+import { resolveNamedSubjectGrant, type ViewerShipGrantDeps } from "@/lib/access/shared/viewerGrant";
+
+export type ContactReaderAuthority =
+  | { kind: "owner"; actorId: string }
+  | { kind: "staff"; actorId: string; email: string }
+  | { kind: "none" };
+
+const ACTOR_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+
+export function contactReaderAuthority(
+  record: SessionRecord | null | undefined,
+  hostResource: string,
+  nowSeconds: number,
+): ContactReaderAuthority {
+  const host = (hostResource ?? "").trim();
+  if (!record || !host) return { kind: "none" };
+  const actorId = typeof record.subject === "string" && ACTOR_ID.test(record.subject) ? record.subject : null;
+  if (!actorId) return { kind: "none" };
+
+  const membership = normalizeMemberships(record.tenants).find((t) => t.resource === host);
+  const scoped = record.resource === host ? (record.capability ?? "").trim() : "";
+  if (isOwnerCapability(membership?.role) || isOwnerCapability(scoped)) return { kind: "owner", actorId };
+
+  const staffScope = Array.isArray(record.staff) && record.staff.length > 0;
+  if (staffScope && staffAdmits({ selection: record.staffSelection, nowSeconds }, host)) {
+    return { kind: "staff", actorId, email: record.email };
+  }
+  return { kind: "none" };
+}
+
+export const CONTACT_READ_CAPABILITY = "customer-contact-read";
+
+/**
+ * The staff principal's LIVE owner-consented `customer-contact-read` grant over `tenant`, read from
+ * the tot-mcp subject-capability seam (contract: decision gv-contact-vault-ownership). True only on
+ * an explicit `200 { capability: "customer-contact-read" }`. Unconfigured, any non-2xx, a timeout,
+ * an unparseable body or any other capability is false. No cache: a revoke takes effect on the next
+ * read. Never throws.
+ */
+export async function resolveContactReadGrant(
+  email: string | null | undefined,
+  tenant: string | null | undefined,
+  deps: ViewerShipGrantDeps = {},
+): Promise<boolean> {
+  return resolveNamedSubjectGrant(email, tenant, CONTACT_READ_CAPABILITY, deps);
+}

package/apps/storefront/src/lib/access/shared/viewerGrant.ts

@@ -108,6 +108,36 @@ async function resolveRawViewerCapability(
   return "preview-access";
 }
 
+/**
+ * Whether `email` holds a LIVE owner-consented grant of exactly `capability` over `appDomain`,
+ * asked of the same subject-capability seam with the capability named. True only on an explicit
+ * `200 { capability: <capability> }`; unconfigured, any non-2xx, a timeout, an unparseable body or
+ * any other answer is false. No cache: a revoke takes effect on the next call. Never throws.
+ */
+export async function resolveNamedSubjectGrant(
+  email: string | null | undefined,
+  appDomain: string | null | undefined,
+  capability: "customer-contact-read",
+  deps: ViewerShipGrantDeps = {},
+): Promise<boolean> {
+  const subject = (email ?? "").trim().toLowerCase();
+  const tenant = (appDomain ?? "").trim();
+  if (!subject || !tenant) return false;
+  try {
+    const outcome = await callMcpService({
+      method: "GET",
+      path: "/internal/dev-access/subject-capability",
+      query: { subject, tenant, app: "storefront", capability },
+      transport: deps.transport ?? new FetchShipGrantTransport(),
+    });
+    if (outcome.kind !== "ok") return false;
+    const payload = (await outcome.json()) as Record<string, unknown> | null;
+    return payload?.capability === capability;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Resolve the viewer's LIVE ship capability over `appDomain`. Returns the granted
  * `Capability` — `"ship-on-behalf"` ONLY on an explicit `200 { capability:

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

@@ -0,0 +1,80 @@
+/**
+ * The contact access audit (`contact_access_audit`, append-only): every read, list and erase of
+ * sealed customer contact writes its row BEFORE anything is decrypted. Staff rows carry the
+ * 30-per-hour quota in the same statement, so concurrent reads can never pass it together.
+ * Rows hold opaque ids, codes and times only — never a contact field.
+ */
+
+export type VaultStage = "preview" | "publication";
+
+export const STAFF_READS_PER_HOUR = 30;
+const HOUR_MS = 3_600_000;
+
+export interface ContactActor {
+  actorId: string;
+  role: "owner" | "staff";
+  reasonCode?: string;
+  ticketRef?: string;
+}
+
+export interface AuditStatement {
+  sql: string;
+  params: readonly unknown[];
+}
+
+/** The SQL surface the audit needs; D1's `fromD1` and the sqlite test harness both satisfy it. */
+export interface AuditDb {
+  all<T = Record<string, unknown>>(sql: string, ...params: unknown[]): Promise<T[]>;
+}
+
+/**
+ * The audit insert. RETURNING tells admitted from refused (quota, or `requireRow` absent); an
+ * error means the audit could not be written.
+ */
+export function auditStatement(input: {
+  auditId: string;
+  tenantId: string;
+  stage: VaultStage;
+  recordKind: "order-contact" | "contact-message";
+  recordId: string;
+  actor: ContactActor;
+  action: "read" | "list" | "erase";
+  now: Date;
+  requireRow?: AuditStatement;
+}): AuditStatement {
+  const { auditId, tenantId, stage, recordKind, recordId, actor, action, now } = input;
+  const hourAgo = new Date(now.getTime() - HOUR_MS).toISOString();
+  const params: unknown[] = [
+    auditId, tenantId, stage, recordKind, recordId, now.toISOString(), actor.actorId, actor.role,
+    actor.role === "staff" ? actor.reasonCode ?? null : null,
+    actor.role === "staff" ? actor.ticketRef ?? null : null,
+    action,
+    actor.role, tenantId, actor.actorId, hourAgo, STAFF_READS_PER_HOUR,
+  ];
+  const requireRow = input.requireRow ? ` AND EXISTS (${input.requireRow.sql})` : "";
+  if (input.requireRow) params.push(...input.requireRow.params);
+  return {
+    sql: `INSERT INTO contact_access_audit
+            (audit_id, tenant_id, stage, record_kind, record_id, at, actor_id, actor_role, reason_code, ticket_ref, action, outcome)
+          SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'admitted'
+          WHERE (? = 'owner' OR (SELECT COUNT(*) FROM contact_access_audit
+                  WHERE tenant_id = ? AND actor_id = ? AND actor_role = 'staff' AND at > ?) < ?)${requireRow}
+          RETURNING audit_id`,
+    params,
+  };
+}
+
+/** Run the audit insert alone: "admitted", "quota" (no row inserted) or "unavailable" (error). */
+export async function admitAudit(db: AuditDb, statement: AuditStatement): Promise<"admitted" | "quota" | "unavailable"> {
+  try {
+    const rows = await db.all(statement.sql, ...statement.params);
+    return rows.length === 1 ? "admitted" : "quota";
+  } catch {
+    return "unavailable";
+  }
+}
+
+/** The same insert without RETURNING, for use inside a batch whose later statements check the row. */
+export function batchAuditStatement(statement: AuditStatement): AuditStatement {
+  return { sql: statement.sql.replace(/\s*RETURNING audit_id$/, ""), params: statement.params };
+}

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();
+}