@tokenoftrust/storefront-runner 4.7.1 → 4.7.2

package/apps/storefront/env.d.ts

@@ -159,6 +159,12 @@ declare global {
        * the pinned render.
        */
       apiBasePath: string;
+      /**
+       * The origin the viewer addressed: `https://<viewer host>` for an
+       * authenticated CDN forward (ADR 0013 Tier 3), else the request URL's own
+       * origin. Same-origin checks compare `Origin` against THIS.
+       */
+      requestOrigin?: string;
       /**
        * True when this request was admitted to a store that is NOT public on this
        * host (a login-gated host, tenant without `access.public`) — by session,

package/apps/storefront/migrations-apps/0020_contact_messages.sql

@@ -0,0 +1,18 @@
+-- Visitor contact-form messages, tenant-keyed, retained 365 days.
+CREATE TABLE contact_messages (
+ id TEXT PRIMARY KEY NOT NULL,
+ tenant_id TEXT NOT NULL,
+ name TEXT NOT NULL DEFAULT '',
+ email TEXT NOT NULL,
+ phone TEXT NOT NULL DEFAULT '',
+ message TEXT NOT NULL,
+ 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
+);
+CREATE INDEX idx_contact_messages_tenant_created ON contact_messages(tenant_id,created_at);
+CREATE INDEX idx_contact_messages_tenant_status ON contact_messages(tenant_id,status);
+CREATE INDEX idx_contact_messages_created ON contact_messages(created_at);

package/apps/storefront/src/lib/access/admin/adminShell.ts

@@ -23,6 +23,7 @@ export const ADMIN_SHELL_CONFIG = {
     { id: "reporting", label: "Reporting", icon: "i-chart" },
     { id: "ai-workflows", label: "AI Workflows", icon: "i-workflows" },
     { id: "blog", label: "Blog", icon: "i-file" },
+    { id: "messages", label: "Messages", icon: "i-user" },
     { id: "publish", label: "Publish", icon: "i-export" },
     { id: "integrations", label: "Integrations", icon: "i-workflows" },
     { id: "settings", label: "Settings", icon: "i-gear" },

package/apps/storefront/src/lib/access/rate/kvWindow.ts

@@ -51,3 +51,38 @@ export async function checkRateLimit(
     return { allowed: true };
   }
 }
+
+export type ClosedRateLimitVerdict =
+  | { allowed: true }
+  | { allowed: false; reason: "limited" | "unavailable" };
+
+/**
+ * The same fixed window, FAIL-CLOSED: no KV binding, or a KV read/write error,
+ * refuses with `reason: "unavailable"` instead of admitting. For public writes
+ * whose abuse is not low-stakes (a stored visitor message), where an unthrottled
+ * window is worse than a refused request.
+ */
+export async function checkRateLimitClosed(
+  kv: KVNamespace | undefined,
+  key: string,
+  opts: RateLimitOptions,
+  nowMs: number = Date.now(),
+): Promise<ClosedRateLimitVerdict> {
+  if (!kv) return { allowed: false, reason: "unavailable" };
+  let count: number;
+  const bucketKey = `${key}:${windowBucket(opts.windowSeconds, nowMs)}`;
+  try {
+    const raw = await kv.get(bucketKey);
+    const current = raw == null ? 0 : Number.parseInt(raw, 10);
+    count = Number.isFinite(current) && current >= 0 ? current : 0;
+  } catch {
+    return { allowed: false, reason: "unavailable" };
+  }
+  if (count >= opts.maxRequests) return { allowed: false, reason: "limited" };
+  try {
+    await kv.put(bucketKey, String(count + 1), { expirationTtl: opts.windowSeconds });
+  } catch {
+    return { allowed: false, reason: "unavailable" };
+  }
+  return { allowed: true };
+}

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

@@ -0,0 +1,154 @@
+/**
+ * `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
+ * 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 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>;
+}
+
+export const CONTACT_RETENTION_DAYS = 365;
+export const CONTACT_LIST_LIMIT = 200;
+
+export type ContactMessageStatus = "unread" | "read";
+
+export interface NewContactMessage {
+  id: string;
+  tenantId: string;
+  name: string;
+  email: string;
+  phone: string;
+  message: string;
+  pagePath: string | null;
+}
+
+export interface ContactMessage {
+  id: string;
+  name: string;
+  email: string;
+  phone: string;
+  message: string;
+  pagePath: string | null;
+  status: ContactMessageStatus;
+  createdAt: string;
+  readAt: string | null;
+}
+
+interface ContactMessageRow {
+  id: string;
+  name: string;
+  email: string;
+  phone: string;
+  message: 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,
+  };
+}
+
+export class ContactMessagesStore {
+  constructor(
+    private readonly db: ContactDb,
+    private readonly now: () => Date = () => new Date(),
+  ) {}
+
+  async insert(input: NewContactMessage): Promise<void> {
+    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)`,
+      input.id,
+      input.tenantId,
+      input.name,
+      input.email,
+      input.phone,
+      input.message,
+      input.pagePath,
+      this.now().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 = ?
+        ORDER BY created_at DESC, id DESC
+        LIMIT ?`,
+      tenantId,
+      CONTACT_LIST_LIMIT,
+    );
+    return rows.map(toMessage);
+  }
+
+  async unreadCount(tenantId: string): Promise<number> {
+    const row = await this.db.first<{ n: number }>(
+      `SELECT COUNT(*) AS n FROM contact_messages WHERE tenant_id = ? AND status = 'unread'`,
+      tenantId,
+    );
+    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> {
+    const rows = await this.db.all<{ id: string }>(
+      `UPDATE contact_messages
+          SET status = 'read', read_at = COALESCE(read_at, ?)
+        WHERE tenant_id = ? AND id = ?
+        RETURNING id`,
+      this.now().toISOString(),
+      tenantId,
+      id,
+    );
+    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;
+  }
+}
+
+/**
+ * Delete every message older than the retention window, across all tenants.
+ * Returns the number of rows removed.
+ */
+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();
+  const rows = await db.all<{ id: string }>(
+    `DELETE FROM contact_messages WHERE created_at < ? RETURNING id`,
+    cutoff,
+  );
+  return rows.length;
+}

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

@@ -0,0 +1,113 @@
+/**
+ * The public contact-form wire contract, shared by the Worker routes and any page
+ * block that submits to them. Browser-safe: no server imports.
+ *
+ *   GET  {apiBasePath}/api/contact/token  → 200 ContactTokenResponse
+ *                                            503 { ok:false, error:"unavailable" }
+ *   POST {apiBasePath}/api/contact        ← ContactSubmission (application/json, same origin)
+ *                                         → 200 { ok:true }
+ *                                           400 invalid_json | invalid_input (+ field)
+ *                                           403 forbidden_origin | invalid_token
+ *                                           413 too_large · 415 unsupported_media_type
+ *                                           429 rate_limited · 503 unavailable
+ *                                           500 store_failed (keep the visitor's text and retry)
+ *
+ * The token must be at least {@link CONTACT_TOKEN_MIN_AGE_MS} old and at most
+ * {@link CONTACT_TOKEN_MAX_AGE_MS} when the form is posted. `company` is the honeypot
+ * field: render it hidden from people and always send it empty.
+ */
+
+export const CONTACT_LIMITS = {
+  bodyBytes: 16_384,
+  name: 100,
+  email: 254,
+  phone: 32,
+  messageMin: 1,
+  message: 5000,
+} as const;
+
+export const CONTACT_TOKEN_MIN_AGE_MS = 3_000;
+export const CONTACT_TOKEN_MAX_AGE_MS = 2 * 60 * 60 * 1000;
+
+export interface ContactTokenResponse {
+  ok: true;
+  token: string;
+}
+
+export interface ContactSubmission {
+  token: string;
+  name?: string;
+  email: string;
+  phone?: string;
+  message: string;
+  company?: string;
+  challenge?: string;
+}
+
+export type ContactField = "name" | "email" | "phone" | "message";
+
+export type ContactErrorCode =
+  | "not_found"
+  | "invalid_json"
+  | "invalid_input"
+  | "forbidden_origin"
+  | "invalid_token"
+  | "too_large"
+  | "unsupported_media_type"
+  | "rate_limited"
+  | "unavailable"
+  | "store_failed";
+
+export type ContactSubmitResponse =
+  | { ok: true }
+  | { ok: false; error: ContactErrorCode; field?: ContactField };
+
+export interface ContactClientResult {
+  status: number;
+  body: ContactSubmitResponse;
+  /** True when the visitor should keep their text and may try again. */
+  retryable: boolean;
+}
+
+const RETRYABLE = new Set([429, 500, 503]);
+
+function apiUrl(apiBasePath: string, path: string): string {
+  return `${apiBasePath.replace(/\/+$/, "")}${path}`;
+}
+
+/** Fetch a fresh submit token. Call when the form is shown, not on submit. */
+export async function fetchContactToken(
+  apiBasePath: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<string> {
+  const res = await fetchImpl(apiUrl(apiBasePath, "/api/contact/token"), {
+    headers: { accept: "application/json" },
+    credentials: "same-origin",
+  });
+  if (!res.ok) throw new Error(`contact token unavailable (${res.status})`);
+  const body = (await res.json()) as Partial<ContactTokenResponse>;
+  if (body.ok !== true || typeof body.token !== "string") throw new Error("contact token malformed");
+  return body.token;
+}
+
+/** Post one submission. A transport failure throws; every HTTP outcome resolves. */
+export async function submitContactMessage(
+  apiBasePath: string,
+  submission: ContactSubmission,
+  fetchImpl: typeof fetch = fetch,
+): Promise<ContactClientResult> {
+  const res = await fetchImpl(apiUrl(apiBasePath, "/api/contact"), {
+    method: "POST",
+    headers: { "content-type": "application/json", accept: "application/json" },
+    credentials: "same-origin",
+    body: JSON.stringify(submission),
+  });
+  const text = await res.text();
+  let body: ContactSubmitResponse;
+  try {
+    body = JSON.parse(text) as ContactSubmitResponse;
+  } catch {
+    body = { ok: false, error: res.ok ? "store_failed" : "unavailable" };
+  }
+  return { status: res.status, body, retryable: RETRYABLE.has(res.status) };
+}

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

@@ -0,0 +1,145 @@
+/**
+ * Client logic for the admin Messages tab (`/api/admin/messages`).
+ *
+ * Every visitor-supplied value is written with `textContent`; nothing from a
+ * message is ever parsed as markup.
+ */
+
+interface InboxMessage {
+  id: string;
+  status: string;
+  name?: string | null;
+  email?: string | null;
+  phone?: string | null;
+  message?: string | null;
+  pagePath?: string | null;
+  createdAt: string;
+}
+
+interface ApiResult {
+  ok: boolean;
+  status: number;
+  data: { ok?: boolean; error?: string; messages?: InboxMessage[]; unread?: number };
+}
+
+const UNREADABLE = { ok: false, error: "unreadable_response" } as const;
+
+async function call(url: string, init?: RequestInit): Promise<ApiResult> {
+  const res = await fetch(url, init);
+  const text = await res.text();
+  let data: ApiResult["data"] = { ...UNREADABLE };
+  try {
+    data = JSON.parse(text) as ApiResult["data"];
+  } catch {
+    data = { ...UNREADABLE };
+  }
+  return { ok: res.ok && data.ok === true, status: res.status, data };
+}
+
+function setText(row: HTMLElement, field: string, value: string | null | undefined): void {
+  const el = row.querySelector<HTMLElement>(`[data-field="${field}"]`);
+  if (!el) return;
+  el.textContent = value || "";
+  el.hidden = !value;
+}
+
+export function initMessagesTab(root: HTMLElement): void {
+  const statusEl = root.querySelector<HTMLElement>("[data-messages-status]");
+  const panel = root.querySelector<HTMLElement>("[data-messages-panel]");
+  const list = root.querySelector<HTMLElement>("[data-messages-list]");
+  const empty = root.querySelector<HTMLElement>("[data-messages-empty]");
+  const unreadEl = root.querySelector<HTMLElement>("[data-messages-unread]");
+  const template = root.querySelector<HTMLTemplateElement>("template[data-messages-row]");
+  const refresh = root.querySelector<HTMLElement>("[data-messages-refresh]");
+  if (!statusEl || !panel || !list || !empty || !unreadEl || !template || !refresh) return;
+  let loaded = false;
+
+  const setStatus = (text: string, tone: "error" | null): void => {
+    statusEl.textContent = text;
+    if (tone) statusEl.setAttribute("data-tone", tone);
+    else statusEl.removeAttribute("data-tone");
+    statusEl.hidden = !text;
+  };
+
+  const renderRow = (message: InboxMessage): HTMLElement => {
+    const row = template.content.firstElementChild!.cloneNode(true) as HTMLElement;
+    row.dataset.messageId = message.id;
+    row.dataset.status = message.status;
+    setText(row, "name", message.name || "(no name)");
+    setText(row, "email", message.email);
+    setText(row, "phone", message.phone);
+    setText(row, "message", message.message);
+    setText(row, "pagePath", message.pagePath ? `Sent from ${message.pagePath}` : "");
+    const when = row.querySelector<HTMLElement>('[data-field="createdAt"]')!;
+    when.setAttribute("datetime", message.createdAt);
+    when.textContent = new Date(message.createdAt).toLocaleString();
+    row.querySelector<HTMLElement>('[data-field="unread"]')!.hidden = message.status !== "unread";
+    const readBtn = row.querySelector<HTMLButtonElement>('[data-message-action="read"]')!;
+    readBtn.hidden = message.status !== "unread";
+    readBtn.addEventListener("click", () => void act(row, "read"));
+    row
+      .querySelector<HTMLButtonElement>('[data-message-action="delete"]')!
+      .addEventListener("click", () => void act(row, "delete"));
+    return row;
+  };
+
+  const load = async (): Promise<void> => {
+    loaded = true;
+    setStatus("Loading messages…", null);
+    try {
+      const { ok, status, data } = await call("/api/admin/messages", {
+        headers: { accept: "application/json" },
+      });
+      if (!ok) {
+        setStatus(`Could not load messages (${data.error || status}).`, "error");
+        return;
+      }
+      const messages = data.messages ?? [];
+      list.replaceChildren(...messages.map(renderRow));
+      empty.hidden = messages.length !== 0;
+      unreadEl.textContent = `${data.unread ?? 0} unread`;
+      panel.hidden = false;
+      setStatus("", null);
+    } catch {
+      setStatus("Could not load messages: the request did not reach the server.", "error");
+    }
+  };
+
+  const act = async (row: HTMLElement, action: "read" | "delete"): Promise<void> => {
+    const id = row.dataset.messageId ?? "";
+    if (action === "delete" && !confirm("Delete this message? This cannot be undone.")) return;
+    const url = `/api/admin/messages/${encodeURIComponent(id)}`;
+    const init: RequestInit =
+      action === "delete"
+        ? { method: "DELETE" }
+        : {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ action: "read" }),
+          };
+    const buttons = row.querySelectorAll<HTMLButtonElement>("button");
+    buttons.forEach((b) => (b.disabled = true));
+    try {
+      const { ok, status, data } = await call(url, init);
+      if (!ok) {
+        setStatus(`Could not update the message (${data.error || status}).`, "error");
+        return;
+      }
+      await load();
+    } catch {
+      setStatus("Could not update the message: the request did not reach the server.", "error");
+    } finally {
+      buttons.forEach((b) => (b.disabled = false));
+    }
+  };
+
+  refresh.addEventListener("click", () => void load());
+  const loadIfShown = (): void => {
+    if (!loaded && document.documentElement.dataset.adminTab === "messages") void load();
+  };
+  new MutationObserver(loadIfShown).observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: ["data-admin-tab"],
+  });
+  loadIfShown();
+}

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

@@ -0,0 +1,112 @@
+/**
+ * Server-side parsing of one contact-form submission: a byte-capped body read,
+ * field caps, and header-injection stripping. Pure apart from reading the body.
+ */
+import { CONTACT_LIMITS, type ContactField } from "./contract.js";
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const SINGLE_LINE_STRIP = /[\r\n\0]/g;
+const NUL = /\0/g;
+
+export type BodyRead = { ok: true; text: string } | { ok: false; reason: "too_large" };
+
+/** Read the body, refusing as soon as it exceeds `maxBytes`. */
+export async function readCappedBody(request: Request, maxBytes: number = CONTACT_LIMITS.bodyBytes): Promise<BodyRead> {
+  const declared = Number(request.headers.get("content-length") ?? "");
+  if (Number.isFinite(declared) && declared > maxBytes) return { ok: false, reason: "too_large" };
+  if (!request.body) return { ok: true, text: "" };
+  const reader = request.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel();
+      return { ok: false, reason: "too_large" };
+    }
+    chunks.push(value);
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return { ok: true, text: new TextDecoder().decode(bytes) };
+}
+
+export interface ParsedContactFields {
+  name: string;
+  email: string;
+  phone: string;
+  message: string;
+}
+
+export type FieldParse = { ok: true; fields: ParsedContactFields } | { ok: false; field: ContactField };
+
+/** Remove CR, LF and NUL, then trim: these values may later reach mail headers. */
+export function singleLine(value: string): string {
+  return value.replace(SINGLE_LINE_STRIP, "").trim();
+}
+
+function stringField(body: Record<string, unknown>, key: string): string | undefined {
+  const value = body[key];
+  if (value === undefined || value === null) return "";
+  return typeof value === "string" ? value : undefined;
+}
+
+export function parseContactFields(body: Record<string, unknown>): FieldParse {
+  const rawName = stringField(body, "name");
+  const rawEmail = stringField(body, "email");
+  const rawPhone = stringField(body, "phone");
+  const rawMessage = stringField(body, "message");
+  if (rawName === undefined) return { ok: false, field: "name" };
+  if (rawEmail === undefined) return { ok: false, field: "email" };
+  if (rawPhone === undefined) return { ok: false, field: "phone" };
+  if (rawMessage === undefined) return { ok: false, field: "message" };
+
+  const name = singleLine(rawName);
+  const email = singleLine(rawEmail).toLowerCase();
+  const phone = singleLine(rawPhone);
+  const message = rawMessage.replace(NUL, "").trim();
+
+  if (name.length > CONTACT_LIMITS.name) return { ok: false, field: "name" };
+  if (email.length > CONTACT_LIMITS.email || !EMAIL_RE.test(email)) return { ok: false, field: "email" };
+  if (phone.length > CONTACT_LIMITS.phone) return { ok: false, field: "phone" };
+  if (message.length < CONTACT_LIMITS.messageMin || message.length > CONTACT_LIMITS.message) {
+    return { ok: false, field: "message" };
+  }
+  return { ok: true, fields: { name, email, phone, message } };
+}
+
+/** True when the honeypot field carries anything. */
+export function honeypotFilled(body: Record<string, unknown>): boolean {
+  const value = body.company;
+  if (value === undefined || value === null) return false;
+  return typeof value !== "string" || value.trim() !== "";
+}
+
+export type ChallengeVerdict = { ok: true } | { ok: false };
+
+/**
+ * The bot-challenge seam. Turnstile verification plugs in here; until then every
+ * submission passes.
+ */
+export async function verifyChallenge(_input: {
+  tenantId: string;
+  challenge: string | undefined;
+  request: Request;
+}): Promise<ChallengeVerdict> {
+  return { ok: true };
+}
+
+/** The submitting page's path from Referer, when it is same-origin. */
+export function sameOriginPagePath(request: Request, expectedOrigin: string): string | null {
+  const referer = request.headers.get("referer");
+  if (!referer || !URL.canParse(referer)) return null;
+  const url = new URL(referer);
+  if (url.origin !== expectedOrigin) return null;
+  return url.pathname.slice(0, 512);
+}

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

@@ -0,0 +1,83 @@
+/**
+ * Server-signed minimum-time-to-submit token for the contact form.
+ *
+ * `issueContactToken` signs `{ tenant, issuedAt }` with HMAC-SHA256 under
+ * `CONTACT_FORM_TOKEN_SECRET`; `verifyContactToken` accepts it only for the same
+ * tenant, between {@link CONTACT_TOKEN_MIN_AGE_MS} and {@link CONTACT_TOKEN_MAX_AGE_MS}
+ * after issue. A script that posts without first loading the form, or posts
+ * faster than a person can type, is refused. Web Crypto only.
+ *
+ * Wire form: `v1.<base64url(JSON payload)>.<base64url(HMAC)>`.
+ */
+import { CONTACT_TOKEN_MAX_AGE_MS, CONTACT_TOKEN_MIN_AGE_MS } from "./contract.js";
+
+const VERSION = "v1";
+const encoder = new TextEncoder();
+
+export type ContactTokenVerdict =
+  | { ok: true }
+  | { ok: false; reason: "malformed" | "bad_signature" | "wrong_tenant" | "too_early" | "expired" };
+
+function base64url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function fromBase64url(text: string): Uint8Array<ArrayBuffer> | undefined {
+  if (!/^[A-Za-z0-9_-]+$/.test(text) || text.length % 4 === 1) return undefined;
+  const bin = atob(text.replace(/-/g, "+").replace(/_/g, "/"));
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+function hmacKey(secret: string, usage: "sign" | "verify"): Promise<CryptoKey> {
+  return crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [usage]);
+}
+
+function signedBytes(payload: string): Uint8Array<ArrayBuffer> {
+  return new Uint8Array(encoder.encode(`contact-form:${VERSION}:${payload}`));
+}
+
+export async function issueContactToken(
+  secret: string,
+  tenantId: string,
+  nowMs: number = Date.now(),
+): Promise<string> {
+  const payload = base64url(encoder.encode(JSON.stringify({ tenant: tenantId, issuedAt: nowMs })));
+  const mac = await crypto.subtle.sign("HMAC", await hmacKey(secret, "sign"), signedBytes(payload));
+  return `${VERSION}.${payload}.${base64url(new Uint8Array(mac))}`;
+}
+
+export async function verifyContactToken(
+  secret: string,
+  token: string,
+  tenantId: string,
+  nowMs: number = Date.now(),
+): Promise<ContactTokenVerdict> {
+  const parts = token.split(".");
+  if (parts.length !== 3 || parts[0] !== VERSION) return { ok: false, reason: "malformed" };
+  const [, payload, sig] = parts as [string, string, string];
+  const sigBytes = fromBase64url(sig);
+  const payloadBytes = fromBase64url(payload);
+  if (!sigBytes || !payloadBytes) return { ok: false, reason: "malformed" };
+
+  const valid = await crypto.subtle.verify("HMAC", await hmacKey(secret, "verify"), sigBytes, signedBytes(payload));
+  if (!valid) return { ok: false, reason: "bad_signature" };
+
+  let claims: { tenant?: unknown; issuedAt?: unknown };
+  try {
+    claims = JSON.parse(new TextDecoder().decode(payloadBytes)) as typeof claims;
+  } catch {
+    return { ok: false, reason: "malformed" };
+  }
+  if (typeof claims.issuedAt !== "number" || !Number.isFinite(claims.issuedAt)) {
+    return { ok: false, reason: "malformed" };
+  }
+  if (claims.tenant !== tenantId) return { ok: false, reason: "wrong_tenant" };
+  const age = nowMs - claims.issuedAt;
+  if (age < CONTACT_TOKEN_MIN_AGE_MS) return { ok: false, reason: "too_early" };
+  if (age > CONTACT_TOKEN_MAX_AGE_MS) return { ok: false, reason: "expired" };
+  return { ok: true };
+}

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

@@ -548,6 +548,36 @@ 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.
+// `notifyStatus` (pending | sent | failed) and `notifyAttempts` belong to the
+// owner-notification sender. Rows are retained for 365 days (`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(),
+    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),
+  },
+  (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),
+  }),
+);
+
 // Idempotent per-digest send log so a re-triggered digest can't double-send.
 // Keyed on `(tenant_id, collection, digest_id)` (e.g. `the-build-2026-W34`);
 // `postSlugs` is a JSON array of the slugs included in that digest.

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

@@ -3,12 +3,12 @@
  * path-scoped Tier 3 behaviors (ADR 0013: sign-in, the commerce and compliance
  * APIs, search, the dashboard). The public static path never reaches here.
  *
- * CloudFront supplies three headers a viewer cannot set: the tenant id and an
+ * CloudFront supplies four headers a viewer cannot set: the tenant id and an
  * HMAC over it are origin custom headers (CloudFront replaces any viewer-sent
- * header of the same name), and the viewer's Host is copied by the behavior's
- * viewer-request function, which overwrites any viewer-sent value. The HMAC is
- * the only trust anchor: without a valid one none of the three is read and the
- * request is routed by its own Host like any other.
+ * header of the same name), and the viewer's Host and IP are copied by the
+ * behavior's viewer-request function, which overwrites any viewer-sent value. The
+ * HMAC is the only trust anchor: without a valid one none of the four is read and
+ * the request is routed by its own Host like any other.
  *
  * The node-side mirror that computes the header value for a distribution is
  * scripts/publish/lib/worker-tier3.mjs `cdnOriginAuthValue`; both are pinned to
@@ -19,16 +19,20 @@ import { timingSafeEqual } from "@/lib/activity/ingestAuth";
 export const CDN_TENANT_HEADER = "x-tot-cdn-tenant";
 export const CDN_AUTH_HEADER = "x-tot-cdn-origin-auth";
 export const CDN_VIEWER_HOST_HEADER = "x-tot-viewer-host";
+export const CDN_VIEWER_IP_HEADER = "x-tot-viewer-ip";
 const AUTH_VERSION = "v1";
 
 export interface CdnForward {
   tenantId: string;
   /** The Host the viewer addressed — the public origin the request belongs to. */
   viewerHost: string;
+  /** The viewer's IP as CloudFront saw it; absent when the forward carries none. */
+  viewerIp?: string;
 }
 
 const HOST_SHAPE = /^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?(?::\d{1,5})?$/i;
 const TENANT_SHAPE = /^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/i;
+const IP_SHAPE = /^(?:\d{1,3}(?:\.\d{1,3}){3}|[0-9a-f]{0,4}(?::[0-9a-f]{0,4}){2,7}(?::\d{1,3}(?:\.\d{1,3}){3})?)$/i;
 
 /** `v1.<hex HMAC-SHA256(secret, "cdn-origin:v1:" + tenantId)>`. */
 export async function cdnOriginAuthValue(secret: string, tenantId: string): Promise<string> {
@@ -60,7 +64,26 @@ export async function verifyCdnForward(
   } catch {
     return null;
   }
-  return { tenantId, viewerHost };
+  const viewerIp = headers.get(CDN_VIEWER_IP_HEADER)?.trim() ?? "";
+  return IP_SHAPE.test(viewerIp) ? { tenantId, viewerHost, viewerIp } : { tenantId, viewerHost };
+}
+
+/**
+ * The visitor's IP, for keying per-visitor limits. On a verified CloudFront forward it is
+ * the viewer IP the distribution's function supplied; `cf-connecting-ip` there is the
+ * CloudFront edge, shared by every visitor behind it. Otherwise — a Cloudflare-served
+ * request, or a viewer-IP header with no valid forward proof — it is `cf-connecting-ip`,
+ * which Cloudflare sets and a client cannot. The first `x-forwarded-for` hop is the
+ * local dev fallback. Never throws.
+ */
+export async function requestClientIp(headers: Headers, cdnOriginSecret: string | undefined): Promise<string> {
+  const forward = await verifyCdnForward(headers, cdnOriginSecret);
+  if (forward?.viewerIp) return forward.viewerIp;
+  const cf = headers.get("cf-connecting-ip");
+  if (cf) return cf;
+  const xff = headers.get("x-forwarded-for");
+  if (xff) return xff.split(",")[0]!.trim();
+  return "unknown";
 }
 
 const FORM_CONTENT_TYPES = ["application/x-www-form-urlencoded", "multipart/form-data", "text/plain"];

package/apps/storefront/src/middleware/index.ts

@@ -154,6 +154,7 @@ async function serveRequest(
   seen.cdnForwarded = !!cdn;
   if (cdn) host = cdn.viewerHost;
   const origin = cdn ? `https://${cdn.viewerHost}` : url.origin;
+  locals.requestOrigin = origin;
   const crossSite = crossSiteFormRefusal(request, origin);
   if (crossSite) return crossSite;
 

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

@@ -0,0 +1,29 @@
+/**
+ * `GET /api/contact/token` — a fresh signed submit token for this tenant's
+ * contact form (`lib/engagement/contact/submitToken.ts`). Without
+ * `CONTACT_FORM_TOKEN_SECRET` the form cannot work, so this answers 503 rather
+ * than handing out an unsigned token.
+ */
+import type { APIContext } from "astro";
+import { readEnv } from "@/lib/publication/shared/env";
+import { issueContactToken } from "@/lib/engagement/contact/submitToken";
+
+export const prerender = false;
+
+const HEADERS = {
+  "content-type": "application/json; charset=utf-8",
+  "cache-control": "no-store",
+  "x-robots-tag": "noindex, nofollow",
+};
+
+export async function GET(context: APIContext): Promise<Response> {
+  const tenantId = context.locals?.tenant?.tenant_id;
+  if (!tenantId) return new Response(JSON.stringify({ ok: false, error: "not_found" }), { status: 404, headers: HEADERS });
+  const secret = await readEnv("CONTACT_FORM_TOKEN_SECRET");
+  if (!secret) {
+    console.log(`[contact] tenant=${tenantId} outcome=token_no_secret`);
+    return new Response(JSON.stringify({ ok: false, error: "unavailable" }), { status: 503, headers: HEADERS });
+  }
+  const token = await issueContactToken(secret, tenantId);
+  return new Response(JSON.stringify({ ok: true, token }), { headers: HEADERS });
+}

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

@@ -0,0 +1,134 @@
+/**
+ * `POST /api/contact` — a visitor message from a store's contact form, stored in
+ * `STOREFRONT_APPS_DB` for the owner's /admin Messages inbox. The wire contract is
+ * `lib/engagement/contact/contract.ts`.
+ *
+ * The tenant is `locals.tenant`, never the body. The request must be same-origin
+ * JSON carrying a signed submit token (`GET /api/contact/token`) of the right age
+ * for this tenant. A filled honeypot, and any submission to a store that is not
+ * 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.
+ */
+import type { APIContext } from "astro";
+import { readD1, readEnv, readKv } from "@/lib/publication/shared/env";
+import { fromD1 } from "@/lib/catalog/d1/catalog";
+import { checkRateLimitClosed } from "@/lib/access/rate/kvWindow";
+import { hashConsentIp } from "@/lib/engagement/newsletter/consent";
+import { ContactMessagesStore } from "@/lib/engagement/contact/contactMessages";
+import { verifyContactToken } from "@/lib/engagement/contact/submitToken";
+import { requestClientIp } from "@/lib/publication/shared/cdnForward";
+import {
+  honeypotFilled,
+  parseContactFields,
+  readCappedBody,
+  sameOriginPagePath,
+  verifyChallenge,
+} from "@/lib/engagement/contact/submission";
+import type { ContactErrorCode, ContactField, ContactSubmitResponse } from "@/lib/engagement/contact/contract";
+
+export const prerender = false;
+
+const CONTACT_RATE_WINDOW_SECONDS = 3600;
+const CONTACT_RATE_MAX_PER_WINDOW = 10;
+
+const HEADERS = {
+  "content-type": "application/json; charset=utf-8",
+  "cache-control": "no-store",
+  "x-robots-tag": "noindex, nofollow",
+};
+
+function respond(body: ContactSubmitResponse, status = 200): Response {
+  return new Response(JSON.stringify(body), { status, headers: HEADERS });
+}
+
+function log(tenantId: string, submissionId: string, outcome: string): void {
+  console.log(`[contact] tenant=${tenantId} submission=${submissionId} outcome=${outcome}`);
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  const tenantId = context.locals?.tenant?.tenant_id;
+  if (!tenantId) return respond({ ok: false, error: "not_found" }, 404);
+  const submissionId = crypto.randomUUID();
+  const { request } = context;
+  const refuse = (outcome: string, error: ContactErrorCode, status: number, field?: ContactField): Response => {
+    log(tenantId, submissionId, outcome);
+    return respond(field ? { ok: false, error, field } : { ok: false, error }, status);
+  };
+  const accept = (outcome: string): Response => {
+    log(tenantId, submissionId, outcome);
+    return respond({ ok: true });
+  };
+
+  const expectedOrigin = context.locals.requestOrigin ?? new URL(request.url).origin;
+  if (request.headers.get("origin") !== expectedOrigin) {
+    return refuse("forbidden_origin", "forbidden_origin", 403);
+  }
+  const contentType = (request.headers.get("content-type") ?? "").toLowerCase();
+  if (!contentType.startsWith("application/json")) {
+    return refuse("unsupported_media_type", "unsupported_media_type", 415);
+  }
+
+  const read = await readCappedBody(request);
+  if (!read.ok) return refuse("too_large", "too_large", 413);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(read.text);
+  } catch {
+    return refuse("invalid_json", "invalid_json", 400);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return refuse("invalid_json", "invalid_json", 400);
+  }
+  const body = parsed as Record<string, unknown>;
+
+  if (honeypotFilled(body)) return accept("honeypot");
+
+  const fields = parseContactFields(body);
+  if (!fields.ok) return refuse("invalid_input", "invalid_input", 400, fields.field);
+
+  const secret = await readEnv("CONTACT_FORM_TOKEN_SECRET");
+  if (!secret) return refuse("no_token_secret", "unavailable", 503);
+  const token = typeof body.token === "string" ? body.token : "";
+  const verdict = await verifyContactToken(secret, token, tenantId);
+  if (!verdict.ok) return refuse(`token_${verdict.reason}`, "invalid_token", 403);
+
+  const challenge = await verifyChallenge({
+    tenantId,
+    challenge: typeof body.challenge === "string" ? body.challenge : undefined,
+    request,
+  });
+  if (!challenge.ok) return refuse("challenge_failed", "invalid_token", 403);
+
+  if (context.locals.storeNotPublic || context.locals.customizationEnv !== "live") {
+    return accept("not_public");
+  }
+
+  const kv = await readKv("TENANT_CACHE");
+  const ip = await requestClientIp(request.headers, await readEnv("CDN_ORIGIN_SECRET"));
+  const ipKey = await hashConsentIp(ip, `contact-rate:${secret}`);
+  const limit = await checkRateLimitClosed(kv, `contact:${tenantId}:${ipKey}`, {
+    windowSeconds: CONTACT_RATE_WINDOW_SECONDS,
+    maxRequests: CONTACT_RATE_MAX_PER_WINDOW,
+  });
+  if (!limit.allowed) {
+    return limit.reason === "limited"
+      ? refuse("rate_limited", "rate_limited", 429)
+      : refuse("no_rate_limiter", "unavailable", 503);
+  }
+
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  if (!d1) return refuse("no_database", "unavailable", 503);
+
+  try {
+    await new ContactMessagesStore(fromD1(d1)).insert({
+      id: submissionId,
+      tenantId,
+      ...fields.fields,
+      pagePath: sameOriginPagePath(request, expectedOrigin),
+    });
+  } catch (err) {
+    return refuse(`store_failed:${err instanceof Error ? err.name : "unknown"}`, "store_failed", 500);
+  }
+  return accept("stored");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "4.7.1",
+  "version": "4.7.2",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",