@tokenoftrust/storefront-runner 4.9.2 → 4.10.0

package/agency-kit/tools/lib/analytics-declaration.mjs

@@ -0,0 +1,299 @@
+// @ts-check
+/**
+ * The tenant `analytics.json` contract, for the surfaces that cannot load the platform's
+ * TypeScript: `tot validate`, the kit's validate-site, `scripts/tenant/validate.mjs` and
+ * materialize-tenant.
+ *
+ * The platform materializes the file with `materializeTenantAnalyticsDeclarations`
+ * (`packages/public-runtime/src/integration/tenant-analytics.ts`), which builds each destination
+ * through the reviewed adapter builder. This module reports the same `{ path, code }` set for any
+ * input; `agency-kit/tools/lib/fixtures/analytics-declarations.json` is run through both, so a
+ * drift on either side fails a test.
+ *
+ * Messages carry no value from the file — never an id, never a key's value — only the field path
+ * and a fixed explanation, so a finding is safe to print, log or forward.
+ *
+ * Pure: callers pass the file's text. `packages/cli/src/analytics-declaration.mjs` is a
+ * byte-identical copy (a test pins it).
+ */
+
+/** The tenant-owned file, at the tenant tree's root. */
+export const ANALYTICS_DECLARATION_FILE = "analytics.json";
+
+/** The current `analytics.json` contract version. */
+export const ANALYTICS_DECLARATION_SCHEMA_VERSION = 1;
+
+/** The stages a destination id may be declared for, in the platform's environment order. */
+export const ANALYTICS_STAGES = Object.freeze(["local", "candidate", "staged", "live"]);
+
+/** The `euUkVisitors` policies; `ask` is the default. */
+export const ANALYTICS_EU_UK_POLICIES = Object.freeze(["ask", "count-only", "full", "none"]);
+
+/**
+ * The first-class platform adapters a tenant may declare. Pinned against the platform's
+ * `PLATFORM_ADAPTERS` by `packages/public-runtime/tests/integration/tenant-analytics.test.ts`.
+ */
+export const ANALYTICS_ADAPTERS = Object.freeze([
+  Object.freeze({
+    adapterId: "platform.google-measurement",
+    maxDestinationsPerStage: 4,
+    idPattern: /^G-[A-Z0-9]{4,20}$/,
+    idLabel: "GA4 measurement id (e.g. G-XXXXXXX)",
+  }),
+  Object.freeze({
+    adapterId: "platform.meta-pixel",
+    maxDestinationsPerStage: 1,
+    idPattern: /^\d{10,20}$/,
+    idLabel: "Meta pixel id (10–20 digits)",
+  }),
+  Object.freeze({
+    adapterId: "platform.amplitude",
+    maxDestinationsPerStage: 1,
+    idPattern: /^(?=[a-f0-9]{32}$)(?=.*[a-f])[a-f0-9]+$/i,
+    idLabel: "Amplitude project API key (32 hexadecimal characters)",
+  }),
+]);
+
+const ANNOTATION_KEYS = ["$schema", "$comment", "$id"];
+const ROOT_KEYS = ["schemaVersion", "destinations", "euUkVisitors"];
+const DESTINATION_KEYS = ["adapter", "ids"];
+
+/**
+ * @typedef {Object} AnalyticsViolation
+ * @property {string} path  the offending field, e.g. `destinations[0].ids.live[1]`
+ * @property {string} code  a stable machine code, e.g. `format`, `unknown_field`
+ */
+
+/**
+ * @typedef {Object} AnalyticsFinding
+ * @property {string} path
+ * @property {string} code
+ * @property {string} message  value-free: the path, the code and a fixed explanation
+ * @property {string} remedy
+ */
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * @param {Record<string, unknown>} obj
+ * @param {readonly string[]} allowed
+ * @param {string} base
+ * @param {AnalyticsViolation[]} out
+ */
+function unknownKeys(obj, allowed, base, out) {
+  for (const key of Object.keys(obj)) {
+    if (allowed.includes(key) || ANNOTATION_KEYS.includes(key)) continue;
+    out.push({ path: base ? `${base}.${key}` : key, code: "unknown_field" });
+  }
+}
+
+/**
+ * The adapter builder's per-stage id rules, with its paths re-anchored under the destination.
+ * @param {Record<string, unknown>} ids
+ * @param {(typeof ANALYTICS_ADAPTERS)[number]} adapter
+ * @param {string} base  `destinations[i]`
+ * @param {AnalyticsViolation[]} out
+ */
+function stageIdViolations(ids, adapter, base, out) {
+  /** @type {Map<string, string[]>} */
+  const valid = new Map();
+  for (const [stage, raw] of Object.entries(ids)) {
+    const at = `${base}.ids.${stage}`;
+    if (!ANALYTICS_STAGES.includes(stage)) {
+      out.push({ path: at, code: "unknown_enum" });
+      continue;
+    }
+    if (!Array.isArray(raw)) {
+      out.push({ path: at, code: "type" });
+      continue;
+    }
+    if (raw.length === 0) {
+      out.push({ path: at, code: "empty" });
+      continue;
+    }
+    if (raw.length > adapter.maxDestinationsPerStage) {
+      out.push({ path: at, code: "too_many_destinations" });
+      continue;
+    }
+    let stageOk = true;
+    raw.forEach((id, index) => {
+      if (typeof id !== "string" || id.length === 0) {
+        out.push({ path: `${at}[${index}]`, code: "type" });
+        stageOk = false;
+        return;
+      }
+      if (!adapter.idPattern.test(id)) {
+        out.push({ path: `${at}[${index}]`, code: "format" });
+        stageOk = false;
+      }
+    });
+    if (!stageOk) continue;
+    if (new Set(raw).size !== raw.length) {
+      out.push({ path: at, code: "duplicate" });
+      continue;
+    }
+    valid.set(stage, /** @type {string[]} */ (raw));
+  }
+  const live = valid.get("live");
+  if (live === undefined) {
+    out.push({ path: `${base}.ids.live`, code: "required" });
+    return;
+  }
+  for (const stage of ANALYTICS_STAGES) {
+    if (stage === "live") continue;
+    (valid.get(stage) ?? []).forEach((id, index) => {
+      if (live.includes(id)) out.push({ path: `${base}.ids.${stage}[${index}]`, code: "non_live_reuses_live_id" });
+    });
+  }
+}
+
+/**
+ * Every violation in an already-parsed `analytics.json` value. `undefined`/`null` (no file) is
+ * the undeclared norm and has none.
+ * @param {unknown} value
+ * @returns {AnalyticsViolation[]}
+ */
+export function analyticsDeclarationViolations(value) {
+  /** @type {AnalyticsViolation[]} */
+  const out = [];
+  if (value === undefined || value === null) return out;
+  if (!isPlainObject(value)) {
+    out.push({ path: "(root)", code: "type" });
+    return out;
+  }
+  unknownKeys(value, ROOT_KEYS, "", out);
+  if ("euUkVisitors" in value && !ANALYTICS_EU_UK_POLICIES.includes(/** @type {string} */ (value.euUkVisitors))) {
+    out.push({ path: "euUkVisitors", code: "unknown_enum" });
+  }
+  if ("schemaVersion" in value && value.schemaVersion !== ANALYTICS_DECLARATION_SCHEMA_VERSION) {
+    out.push({ path: "schemaVersion", code: "unsupported_version" });
+  }
+  const destinations = value.destinations;
+  if (!Array.isArray(destinations)) {
+    out.push({ path: "destinations", code: "type" });
+    return out;
+  }
+  /** @type {Set<string>} */
+  const seenAdapters = new Set();
+  destinations.forEach((destination, index) => {
+    const base = `destinations[${index}]`;
+    if (!isPlainObject(destination)) {
+      out.push({ path: base, code: "type" });
+      return;
+    }
+    unknownKeys(destination, DESTINATION_KEYS, base, out);
+    const adapterId = destination.adapter;
+    if (typeof adapterId !== "string" || adapterId.length === 0) {
+      out.push({ path: `${base}.adapter`, code: "type" });
+      return;
+    }
+    const ids = destination.ids;
+    if (!isPlainObject(ids)) {
+      out.push({ path: `${base}.ids`, code: "type" });
+      return;
+    }
+    if (seenAdapters.has(adapterId)) {
+      out.push({ path: `${base}.adapter`, code: "duplicate" });
+      return;
+    }
+    seenAdapters.add(adapterId);
+    const adapter = ANALYTICS_ADAPTERS.find((a) => a.adapterId === adapterId);
+    if (!adapter) {
+      out.push({ path: `${base}.adapter`, code: "unknown_adapter" });
+      return;
+    }
+    stageIdViolations(ids, adapter, base, out);
+  });
+  return out;
+}
+
+/**
+ * Parse `analytics.json` text. Unparseable text is a `(root)` `invalid_json` violation, never an
+ * absent file: a declaration that cannot be read must refuse, not publish with no analytics.
+ * @param {string} text
+ * @returns {{ ok: true, value: unknown } | { ok: false, violations: AnalyticsViolation[] }}
+ */
+export function parseAnalyticsDeclaration(text) {
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch {
+    return { ok: false, violations: [{ path: "(root)", code: "invalid_json" }] };
+  }
+}
+
+const ADAPTER_IDS = ANALYTICS_ADAPTERS.map((a) => a.adapterId).join(", ");
+const ID_FORMATS = ANALYTICS_ADAPTERS.map((a) => `${a.adapterId}: ${a.idLabel}`).join("; ");
+
+/**
+ * A fixed, value-free explanation and remedy for a violation.
+ * @param {AnalyticsViolation} violation
+ * @returns {{ message: string, remedy: string }}
+ */
+export function analyticsViolationText({ path, code }) {
+  switch (code) {
+    case "invalid_json":
+      return { message: "analytics.json is not valid JSON", remedy: "fix the JSON syntax" };
+    case "type":
+      return {
+        message: "has the wrong type",
+        remedy: 'use { "schemaVersion": 1, "destinations": [{ "adapter": "<adapter id>", "ids": { "live": ["<id>"] } }] }',
+      };
+    case "unknown_field":
+      return { message: "is not an analytics.json field", remedy: "remove it; analytics.json is a closed contract" };
+    case "unknown_enum":
+      return path === "euUkVisitors"
+        ? { message: "is not an EU/UK visitor policy", remedy: `use one of: ${ANALYTICS_EU_UK_POLICIES.join(", ")}` }
+        : { message: "is not a stage", remedy: `use one of: ${ANALYTICS_STAGES.join(", ")}` };
+    case "unsupported_version":
+      return { message: "is not a supported schemaVersion", remedy: `set it to ${ANALYTICS_DECLARATION_SCHEMA_VERSION}` };
+    case "unknown_adapter":
+      return { message: "is not a first-class analytics adapter", remedy: `use one of: ${ADAPTER_IDS}` };
+    case "empty":
+      return { message: "names no destination id", remedy: "name at least one id, or remove the stage" };
+    case "too_many_destinations":
+      return { message: "names more destination ids than this adapter accepts per stage", remedy: "remove the extra ids" };
+    case "format":
+      return { message: "is not a valid destination id for this adapter", remedy: `use the adapter's id format (${ID_FORMATS})` };
+    case "duplicate":
+      return path.endsWith(".adapter")
+        ? { message: "names an adapter an earlier destination already names", remedy: "declare each adapter once, with all of its ids" }
+        : { message: "names the same destination id twice", remedy: "list each id once" };
+    case "required":
+      return { message: "has no valid live destination id", remedy: "declare a valid live id for every destination" };
+    case "non_live_reuses_live_id":
+      return {
+        message: "reuses a live destination id, so non-live traffic would reach the live property",
+        remedy: "use a separate test id, or leave the stage unset",
+      };
+    default:
+      return { message: "is invalid", remedy: "see docs/architecture/analytics-activation.md" };
+  }
+}
+
+/**
+ * Every violation in an `analytics.json` file's text. A file that is present but holds `null` is
+ * a `(root)` `type` violation: only an absent file declares nothing.
+ * @param {string} text
+ * @returns {AnalyticsViolation[]}
+ */
+export function analyticsDeclarationTextViolations(text) {
+  const parsed = parseAnalyticsDeclaration(text);
+  if (!parsed.ok) return [...parsed.violations];
+  if (parsed.value === null) return [{ path: "(root)", code: "type" }];
+  return analyticsDeclarationViolations(parsed.value);
+}
+
+/**
+ * Every finding in an `analytics.json` file's text, each value-free.
+ * @param {string} text
+ * @returns {AnalyticsFinding[]}
+ */
+export function analyticsDeclarationFindings(text) {
+  return analyticsDeclarationTextViolations(text).map((violation) => {
+    const { message, remedy } = analyticsViolationText(violation);
+    return { ...violation, message: `${violation.path}: [${violation.code}] ${message}`, remedy };
+  });
+}

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/cspStaticHashes.ts

@@ -19,7 +19,7 @@ export const STATIC_SCRIPT_HASHES: readonly string[] = [
   "'sha256-YicfxUFBkKrQapZ/tzZKlaKTdNHgwVfv7y2Wa0NC6/k='",
   "'sha256-eIXWvAmxkr251LJZkjniEK5LcPF3NkapbJepohwYRIc='",
   "'sha256-elMLh/6Oubj8u9FRLwZLyRa6TqKikGs75mf0jfWcoxI='",
-  "'sha256-bANHtvoDkw4GnpBynM5Ib1cxdoDeNsGkPhPnDEphW3Y='",
+  "'sha256-MG9XnFVbN8UmLcNws9A8ckOhQJI+MnAKxpCI7oBMS3Q='",
 ];
 
 export const STATIC_STYLE_HASHES: readonly string[] = [

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/compliance/shared/visitorRegionCookie.ts

@@ -12,7 +12,7 @@
  *   - a CloudFront-forwarded Tier 3 request (its `cf` describes CloudFront, not the
  *     viewer);
  *   - no `request.cf` at all.
- * The page then keeps whatever class it already holds, or none (count-only).
+ * The page then keeps whatever class it already holds, or none (the EU/UK policy).
  *
  * The local dev loop's `request.cf` comes from the dev runtime's cached `cf.json`, which
  * describes the developer's own location. `?tot_region=eu|x|u` overrides it so both

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