@tokenoftrust/storefront-runner 1.4.0 → 1.4.2-rc.0

package/apps/storefront/src/lib/dev/cockpitStore.ts

@@ -3,20 +3,12 @@
  * cockpit page, its /api/dev/* routes, and the CLI sign-in-code mint all share, so
  * they never disagree about the developer's store.
  *
- * REGRESSION FIXED (8500 <tenant>/cockpit): the page and the mint used to derive
- * the store purely from the session's FIRST membership
- * (`session.tenants?.[0]?.resource ?? session.resource`), ignoring the store the
- * request URL actually named. An invite to `/<tenantB>/cockpit` therefore rendered —
- * and minted a `tot login --code … && tot start` for — whatever store happened to be
- * listed first in the session, "losing track of the store" for any developer who
- * belongs to more than one.
- *
  * Rule: the URL wins WHEN THE VIEWER CAN ACCESS IT. The middleware has already
  * resolved the request's host/path to `locals.tenant` (the trusted, authenticated
  * store seam — never client body input), so when that is a SPECIFIC store (not the
  * public marketing home) and the signed-in developer holds a membership for it (or a
  * live staff admission), that store is authoritative. Otherwise we fall back to the
- * session's own first store (the generic-host `/cockpit` case, unchanged), and for an
+ * session's own first store (the generic-host `/cockpit` case), and for an
  * anonymous viewer to the path store's branding, else the caller-supplied `?tenant=`.
  *
  * Access is gated with the SAME primitive (`viewerCanAccess`) the vendor dashboard

package/apps/storefront/src/lib/dev/devDraft.ts

@@ -1,6 +1,6 @@
 /**
  * Per-developer DRAFT overlay for the /dev live preview — the signed token + KV key
- * contract behind decision `draft-overlay-same-origin` (workstream 8500-dev-live-preview).
+ * contract for the same-origin draft overlay.
  *
  * WHAT A DRAFT IS: when the /dev page's onscreen AI loop edits the developer's site
  * (`/api/content-edit/ai-edit`), the edited artifacts land in TENANT_CACHE KV under

package/apps/storefront/src/lib/dev/previewStatus.ts

@@ -1,41 +1,29 @@
 /**
  * Read whether a tenant appDomain's store is SET UP — its forge repo is provisioned —
  * from the credential-free MCP preview-status seam (tot-mcp
- * GET /internal/preview-status; legacy alias /internal/dev-access/preview-status). The
+ * GET /internal/preview-status; alias /internal/dev-access/preview-status). The
  * seam answers `{ tenant, app, repo, provisioned, previewReleased }`.
  *
- * This is the cockpit's own small reader — self-contained, mirroring `cliSignInCode.ts`
- * (same MCP-origin + service-secret seam) rather than importing another cluster's copy,
- * so the two stay decoupled (the same reason `cliSignInCode` duplicates its transport).
- * It gates the CLI sign-in-code mint + the /cockpit setup fastpath so a developer whose
+ * This is the cockpit's own small reader over the same MCP-origin + service-secret seam
+ * `cliSignInCode.ts` uses. It gates the CLI sign-in-code mint + the /cockpit setup
+ * fastpath so a developer whose
  * store isn't provisioned yet gets an honest "not set up" state instead of a
  * `tot login --code … && tot start` command that would die at checkout on
- * "Repo <owner>-main is not provisioned" (James's 2026-07-19 first-run failure).
+ * "Repo <owner>-main is not provisioned".
  *
  *   - MCP host  ← the ORIGIN of MCP_APP_BINDING_URL (one source, so this read hits the
  *                 SAME MCP tier the sign-in-code mint does).
  *   - auth      ← header x-mcp-service-secret: MCP_SERVICE_SHARED_SECRET.
  *
  * Fail-closed but non-blocking by design: an UNCONFIGURED seam (no URL/secret) →
- * { configured:false } so callers keep today's behavior (no regression); any non-2xx /
+ * { configured:false } so callers keep the default behavior; any non-2xx /
  * transport / parse fault → { configured:true, ok:false } so a caller can distinguish
  * "definitely not provisioned" (ok + provisioned:false) from "couldn't tell". Never throws.
  */
 import { readEnv } from "@/lib/env";
+import { FetchHttpTransport, type HttpGetTransport } from "@/lib/http/fetchTransport";
 
-export interface HttpGetTransport {
-  get(
-    url: string,
-    headers: Record<string, string>,
-  ): Promise<{ status: number; json(): Promise<unknown> }>;
-}
-
-export class FetchGetTransport implements HttpGetTransport {
-  async get(url: string, headers: Record<string, string>) {
-    const res = await fetch(url, { method: "GET", headers });
-    return { status: res.status, json: () => res.json() };
-  }
-}
+export type { HttpGetTransport };
 
 export interface TenantPreviewStatus {
   /** False when the seam isn't wired on this deploy (no URL/secret) — gate inactive. */
@@ -68,7 +56,7 @@ export async function readTenantPreviewStatus(
     return { configured: false, ok: false, reason: "bad-mcp-url" };
   }
 
-  const transport = deps.transport ?? new FetchGetTransport();
+  const transport = deps.transport ?? new FetchHttpTransport();
   const full = `${endpoint}?tenant=${encodeURIComponent(tenant.toLowerCase())}`;
   let res: { status: number; json(): Promise<unknown> };
   try {

package/apps/storefront/src/lib/dev/rendezvousBroker.ts

@@ -21,20 +21,14 @@
  */
 import { readEnv } from "@/lib/env";
 import { mintMcpClientAssertion, McpClientAssertionError } from "@/lib/auth/mcpClientAssertion";
+import { FetchHttpTransport, type HttpTransport } from "@/lib/http/fetchTransport";
+
+export type { HttpTransport };
 
 const JWT_BEARER_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
 /** The path whose audience the MCP binds EVERY rendezvous assertion to. */
 const RENDEZVOUS_AUDIENCE_PATH = "/oauth/device/rendezvous";
 
-/** Injectable transport so the broker calls unit-test with no network. */
-export interface HttpTransport {
-  post(
-    url: string,
-    headers: Record<string, string>,
-    body: unknown,
-  ): Promise<{ status: number; json(): Promise<unknown> }>;
-}
-
 // Bound every rendezvous call to the MCP. The MCP runs on AppRunner (scale-to-zero),
 // so the FIRST call after idle hits a cold instance that can take many seconds to
 // answer. Without a bound the storefront Worker's subrequest hangs and the browser's
@@ -44,20 +38,6 @@ export interface HttpTransport {
 // 502 ("having a moment — try again"); the retry lands on a now-warm MCP and succeeds.
 const RENDEZVOUS_FETCH_TIMEOUT_MS = 12_000;
 
-export class FetchHttpTransport implements HttpTransport {
-  async post(url: string, headers: Record<string, string>, body: unknown) {
-    const res = await fetch(url, {
-      method: "POST",
-      headers: { "Content-Type": "application/json", ...headers },
-      body: JSON.stringify(body),
-      // A timeout/abort rejects the fetch → callRendezvous's catch → a 502 the cockpit
-      // renders as a retryable error, instead of a hung request the browser gives up on.
-      signal: AbortSignal.timeout(RENDEZVOUS_FETCH_TIMEOUT_MS),
-    });
-    return { status: res.status, json: () => res.json() };
-  }
-}
-
 export interface RendezvousDeps {
   transport?: HttpTransport;
   /** Override the assertion minter in tests (defaults to the real private-key signer). */
@@ -97,7 +77,12 @@ async function callRendezvous(
 ): Promise<{ status: number; body: Record<string, unknown> }> {
   const mint = deps.mintAssertion ?? ((aud: string) => mintMcpClientAssertion(aud));
   const clientAssertion = await mint(target.audience);
-  const transport = deps.transport ?? new FetchHttpTransport();
+  const transport =
+    deps.transport ??
+    new FetchHttpTransport({
+      defaultHeaders: { "Content-Type": "application/json" },
+      timeoutMs: RENDEZVOUS_FETCH_TIMEOUT_MS,
+    });
   const res = await transport.post(
     `${target.origin}${path}`,
     {},

package/apps/storefront/src/lib/edgeCache.ts

@@ -66,6 +66,23 @@ export function pageCacheKey(
   return new Request(`${CACHE_ORIGIN}/${tenantId}/v${version}${pathname}${search}`);
 }
 
+/**
+ * Cache key for a digest-addressed static-bundle response (T2, ADR 0012).
+ * Keyed by `treeDigest` instead of the integer `cachever` `pageCacheKey` uses —
+ * a pointer flip to a NEW digest is a different key, so it is a clean cache
+ * miss (never a stale serve of the old digest); an unchanged digest keeps
+ * serving its warm entry across requests. Shares `getCachedPage`/
+ * `putCachedPage` with the page cache (both just take a Request key + Cache).
+ */
+export function staticBundleCacheKey(
+  tenantId: string,
+  digest: string,
+  pathname: string,
+  search: string,
+): Request {
+  return new Request(`${CACHE_ORIGIN}/${tenantId}/digest-${digest}${pathname}${search}`);
+}
+
 /** Current cache version for a tenant (defaults to 1). KV read is edge-cached. */
 export async function readCacheVersion(
   kv: KVNamespace,

package/apps/storefront/src/lib/env.ts

@@ -40,6 +40,44 @@ export async function readEnv(key: string): Promise<string | undefined> {
   return fromBuild(key);
 }
 
+/** The slice of the Workers ExecutionContext runAfterResponse needs — the
+ *  @astrojs/cloudflare adapter exposes it to routes as `locals.cfContext`. */
+export interface CfExecutionContextLike {
+  waitUntil(promise: Promise<unknown>): void;
+}
+
+/**
+ * Run `work` PAST the response — the request's `ExecutionContext.waitUntil`
+ * when the caller passes it, else a detached floating promise (dev/Node). For
+ * webhook RECEIVERS that must ACK fast: the upstream forwarder (tot-mcp
+ * gitea-webhook proxy) aborts its forward at 15s and Gitea bounds its delivery
+ * wait too, while a real reconcile takes tens of seconds — running it inside
+ * the request meant every healthy reconcile was killed mid-flight and recorded
+ * as `forward_failed` (a layer of Trello 13075, behind the auth fix).
+ *
+ * CALLERS MUST PASS `locals.cfContext` (the @astrojs/cloudflare adapter's
+ * per-request ExecutionContext, `createLocals: { cfContext: ctx }`): in the
+ * Workers runtime a merely-floating promise is CANCELLED the moment the
+ * response returns — an earlier revision here imported `waitUntil` from
+ * `cloudflare:workers` (not exported by this adapter/runtime version), silently
+ * degraded to the floating promise, and the async reconcile died unobserved
+ * right after its 202. The floating-promise branch is a DEV-ONLY fallback.
+ * Errors are the caller's to handle inside `work` (this never throws).
+ */
+export function runAfterResponse(
+  work: Promise<unknown>,
+  cfContext?: CfExecutionContextLike | null,
+): void {
+  const swallowed = work.catch(() => {});
+  if (cfContext && typeof cfContext.waitUntil === "function") {
+    cfContext.waitUntil(swallowed);
+    return;
+  }
+  // dev/Node only — in the Workers runtime this promise would be cancelled at
+  // response end, which is exactly the bug the parameter above exists to avoid.
+  void swallowed;
+}
+
 /** KV binding for the newsletter stub / tenant cache, if present in the runtime. */
 export async function readKv(binding: string): Promise<KVNamespace | undefined> {
   const w = await getWorkerEnv();
@@ -59,6 +97,19 @@ export async function readR2(binding: string): Promise<R2Bucket | undefined> {
   return (w?.[binding] as R2Bucket | undefined) ?? undefined;
 }
 
+/**
+ * Cloudflare Analytics Engine dataset binding (e.g. ACTIVITY_ANALYTICS), if
+ * present. Untyped (`unknown`) deliberately — the caller casts to its own
+ * minimal `writeDataPoint` shape (see `activity/store.ts`'s
+ * `AnalyticsEngineLike`) rather than this module taking a types dep. Absent in
+ * dev/Node and until the binding is provisioned; callers treat undefined as
+ * "analytics sink unavailable, skip it" (never an error).
+ */
+export async function readAnalytics(binding: string): Promise<unknown | undefined> {
+  const w = await getWorkerEnv();
+  return w?.[binding] ?? undefined;
+}
+
 /**
  * Cloudflare Queue producer binding (e.g. WEBHOOK_DELIVERY_QUEUE), if present.
  * Untyped (`unknown`) deliberately — callers cast to their own minimal

package/apps/storefront/src/lib/http/fetchTransport.ts

@@ -0,0 +1,63 @@
+/**
+ * The one shared `fetch`-backed HTTP transport seam used by the storefront's
+ * server-to-server clients. A transport is injectable so those clients unit-test
+ * with no network; this is the production implementation they default to.
+ *
+ * Both `post` and `get` return the minimal `{ status, json }` shape the callers
+ * read — never the raw `Response` — so a test stub and the real transport are
+ * interchangeable. `defaultHeaders` are merged under each call's own headers
+ * (per-call wins); `timeoutMs`, when set, aborts each request via
+ * `AbortSignal.timeout` so a hung subrequest becomes a fast, retryable failure.
+ */
+export interface HttpResponseLike {
+  status: number;
+  json(): Promise<unknown>;
+}
+
+export interface HttpTransport {
+  post(url: string, headers: Record<string, string>, body: unknown): Promise<HttpResponseLike>;
+}
+
+export interface HttpGetTransport {
+  get(url: string, headers: Record<string, string>): Promise<HttpResponseLike>;
+}
+
+export interface FetchHttpTransportOptions {
+  /** Merged UNDER each call's headers (a per-call header of the same name wins). */
+  defaultHeaders?: Record<string, string>;
+  /** When set, every request aborts after this many ms via `AbortSignal.timeout`. */
+  timeoutMs?: number;
+}
+
+export class FetchHttpTransport implements HttpTransport, HttpGetTransport {
+  private readonly defaultHeaders: Record<string, string>;
+  private readonly timeoutMs?: number;
+
+  constructor(options: FetchHttpTransportOptions = {}) {
+    this.defaultHeaders = options.defaultHeaders ?? {};
+    this.timeoutMs = options.timeoutMs;
+  }
+
+  private signal(): AbortSignal | undefined {
+    return this.timeoutMs != null ? AbortSignal.timeout(this.timeoutMs) : undefined;
+  }
+
+  async post(url: string, headers: Record<string, string>, body: unknown): Promise<HttpResponseLike> {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { ...this.defaultHeaders, ...headers },
+      body: JSON.stringify(body),
+      signal: this.signal(),
+    });
+    return { status: res.status, json: () => res.json() };
+  }
+
+  async get(url: string, headers: Record<string, string>): Promise<HttpResponseLike> {
+    const res = await fetch(url, {
+      method: "GET",
+      headers: { ...this.defaultHeaders, ...headers },
+      signal: this.signal(),
+    });
+    return { status: res.status, json: () => res.json() };
+  }
+}

package/apps/storefront/src/lib/i18n.ts

@@ -0,0 +1,25 @@
+// Human-readable, in-language display names for the reader language switcher,
+// keyed by BCP-47 primary subtag. Unmapped codes fall back to the uppercased code.
+const LANGUAGE_LABELS: Record<string, string> = {
+  en: "English",
+  es: "Español",
+  fr: "Français",
+  de: "Deutsch",
+  it: "Italiano",
+  pt: "Português",
+  nl: "Nederlands",
+  sv: "Svenska",
+  pl: "Polski",
+  ru: "Русский",
+  ja: "日本語",
+  ko: "한국어",
+  zh: "中文",
+  ar: "العربية",
+  hi: "हिन्दी",
+  tr: "Türkçe",
+};
+
+export function languageLabel(code: string): string {
+  const primary = code.toLowerCase().split(/[-_]/)[0] ?? code;
+  return LANGUAGE_LABELS[primary] ?? code.toUpperCase();
+}

package/apps/storefront/src/lib/jsonld.ts

@@ -81,6 +81,124 @@ export function breadcrumbLd(
   };
 }
 
+/** Words in rendered HTML — tags/entities stripped. Feeds `BlogPosting.wordCount`. */
+export function wordCount(html: string): number {
+  const text = html
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&[a-z#0-9]+;/gi, " ");
+  return text.match(/\S+/g)?.length ?? 0;
+}
+
+/** The subset of a blog post `blogPostingLd` reads — kept structural so the
+ *  builder doesn't couple `jsonld.ts` to the blog module. */
+export interface BlogPostingInput {
+  title: string;
+  description: string;
+  publishedAt: string;
+  modifiedAt: string;
+  author: string;
+  categories: string[];
+  tags: string[];
+  contentHtml: string;
+  inLanguage?: string;
+  featuredImage?: { src: string; alt?: string; width?: number; height?: number };
+}
+
+/**
+ * Enriched `BlogPosting` graph (B1.6): adds `wordCount`, `articleSection`,
+ * `keywords`, `inLanguage` (default "en"), an `author.url`, and an `ImageObject`
+ * `image` with dimensions — on top of the baseline
+ * headline/description/dates/publisher.
+ */
+export function blogPostingLd(
+  post: BlogPostingInput,
+  opts: { url: string; canonicalBase: string; publisherName: string; authorUrl?: string },
+) {
+  const { url, canonicalBase, publisherName, authorUrl } = opts;
+  const image = post.featuredImage
+    ? {
+        "@type": "ImageObject",
+        url: new URL(post.featuredImage.src, canonicalBase + "/").toString(),
+        ...(post.featuredImage.alt ? { caption: post.featuredImage.alt } : {}),
+        ...(post.featuredImage.width ? { width: post.featuredImage.width } : {}),
+        ...(post.featuredImage.height ? { height: post.featuredImage.height } : {}),
+      }
+    : undefined;
+  return {
+    "@context": "https://schema.org",
+    "@type": "BlogPosting",
+    headline: post.title,
+    description: post.description,
+    url,
+    mainEntityOfPage: url,
+    datePublished: post.publishedAt,
+    dateModified: post.modifiedAt,
+    author: {
+      "@type": "Person",
+      name: post.author,
+      ...(authorUrl ? { url: authorUrl } : {}),
+    },
+    publisher: { "@type": "Organization", name: publisherName, url: canonicalBase },
+    wordCount: wordCount(post.contentHtml),
+    ...(post.categories[0] ? { articleSection: post.categories[0] } : {}),
+    ...(post.tags.length ? { keywords: post.tags.join(", ") } : {}),
+    inLanguage: post.inLanguage ?? "en",
+    ...(image ? { image } : {}),
+  };
+}
+
+/**
+ * `CollectionPage` + embedded `ItemList` for a category/tag/author archive
+ * (B1.2/B1.3 opt in — this composes with them without requiring their routes
+ * exist yet). `items` are already absolute URLs.
+ */
+export function collectionPageLd(opts: {
+  name: string;
+  url: string;
+  description?: string;
+  items: { title: string; url: string }[];
+}) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "CollectionPage",
+    name: opts.name,
+    url: opts.url,
+    ...(opts.description ? { description: opts.description } : {}),
+    mainEntity: {
+      "@type": "ItemList",
+      numberOfItems: opts.items.length,
+      itemListElement: opts.items.map((it, i) => ({
+        "@type": "ListItem",
+        position: i + 1,
+        name: it.title,
+        url: it.url,
+      })),
+    },
+  };
+}
+
+/**
+ * `Person` graph for an author page (B1.3) — the E-E-A-T signal Google weights
+ * for author authority. `sameAs` carries the author's social-profile URLs.
+ */
+export function personLd(opts: {
+  name: string;
+  url?: string;
+  description?: string;
+  sameAs?: string[];
+  image?: string;
+}) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "Person",
+    name: opts.name,
+    ...(opts.url ? { url: opts.url } : {}),
+    ...(opts.description ? { description: opts.description } : {}),
+    ...(opts.sameAs && opts.sameAs.length ? { sameAs: opts.sameAs } : {}),
+    ...(opts.image ? { image: opts.image } : {}),
+  };
+}
+
 export function productLd(
   p: CatalogProduct,
   tenant: TenantConfig,

package/apps/storefront/src/lib/monitoring/manifest.ts

@@ -1,21 +1,21 @@
 /**
- * Monitoring contract (spec §F16 — monitors, alerts, operator runbooks).
+ * Monitoring contract (monitors, alerts, operator runbooks).
  *
  * This is the CHECKED-IN source of truth for "what do we watch, at what
  * threshold, at what severity, and which runbook fires when it trips." It is
- * deliberately data, not wiring: Phase 1 ships the *contract* so operators can
+ * deliberately data, not wiring: this file ships the *contract* so operators can
  * see coverage and reviewers can diff it; the actual alert providers (Cloudflare
  * Health Checks / Workers metrics / Logpush alerts / a RUM sink) are provisioned
- * out-of-band and each monitor records whether it is `in-code` today or still
+ * out-of-band and each monitor records whether it is `in-code` or still
  * `needs-external` / `needs-secret`.
  *
  * Signal sources are named against real code where it exists in this repo
  * (`/health` → lib/health.ts, CSP → pages/api/csp-report.ts + CSP_REPORT_PATH,
  * commerce events → lib/analytics). Signals owned by sibling units are referenced
- * by CONTRACT NAME, not imported — Core Web Vitals come from F14's RUM beacon,
- * and age-verification / restricted-state denials come from F12's compliance
- * evidence signals. This file does not edit or depend on those units; when they
- * land, point the corresponding monitor's `observe` at the real sink.
+ * by CONTRACT NAME, not imported — Core Web Vitals come from the RUM beacon,
+ * and age-verification / restricted-state denials come from the compliance
+ * evidence signals. This file does not edit or depend on those units; point the
+ * corresponding monitor's `observe` at the real sink where one exists.
  *
  * The companion operator doc renders this for humans and lists the external
  * wiring/secrets checklist: docs/epics/sample-store-migration/monitoring-and-runbooks.md.
@@ -89,9 +89,9 @@ export interface Monitor {
 }
 
 /**
- * The ten launch-critical monitors from spec §F16. Order is presentation order.
- * Thresholds are the go-live defaults; tune against the 24h post-cutover soak
- * (T10) and record any change here — this file is the audit trail.
+ * The ten launch-critical monitors. Order is presentation order.
+ * Thresholds are defaults; tune against the 24h post-cutover soak
+ * and record any change here — this file is the audit trail.
  */
 export const MONITORS: readonly Monitor[] = [
   {
@@ -264,7 +264,7 @@ export const MONITORS: readonly Monitor[] = [
 ] as const;
 
 /**
- * The monitors §F16 requires by name. The test asserts MONITORS covers exactly
+ * The monitors this contract requires by name. The test asserts MONITORS covers exactly
  * these — so dropping or misnaming one fails CI, and adding a new monitor is a
  * deliberate edit here.
  */

package/apps/storefront/src/lib/newsletter/confirmationEmail.ts

@@ -0,0 +1,30 @@
+/**
+ * Double-opt-in confirmation mail — STUB (N2).
+ *
+ * The storefront Worker sends no email itself: every existing "email" flow is
+ * delegated over HTTP to tot20, and there is no bulk/marketing sender in-repo
+ * (docs/plans/2026-08-22-newsletter-send-spike.md §1). Wiring the real send is
+ * the ESP-pipeline unit N4's job — it replaces the body of this function with a
+ * transactional send (confirm link in the body). Until then we only LOG intent,
+ * and never let a send failure fail the subscribe (the pending row + returned
+ * token are the durable state; the mail is a follow-up).
+ */
+
+export interface ConfirmationEmailRequest {
+  email: string;
+  collection: string;
+  /** Absolute confirm URL the recipient clicks: `…/api/newsletter/confirm?token=…`. */
+  confirmUrl: string;
+}
+
+/**
+ * N4 REPLACES THIS with a real ESP send. Today: log the intent and return.
+ * Best-effort by contract — callers do not await deliverability, and this never
+ * throws.
+ */
+export async function sendConfirmationEmail(req: ConfirmationEmailRequest): Promise<void> {
+  console.log(
+    `[newsletter] confirmation email STUB — would send to ${req.email} ` +
+      `(collection: ${req.collection}) confirm: ${req.confirmUrl}`,
+  );
+}

package/apps/storefront/src/lib/newsletter/consent.ts

@@ -0,0 +1,23 @@
+/**
+ * Consent-record primitives for the newsletter double-opt-in flow (N2).
+ *
+ * `randomToken` mints the opaque per-subscriber secret that both the confirm and
+ * (N3) unsubscribe links carry — Web Crypto only (no `node:*`) so it runs
+ * identically in the Worker and in tests. `hashConsentIp` is the GDPR-safe IP
+ * record: we store `sha256(ip + ":" + salt)`, NEVER the raw IP (repo convention:
+ * opaque hashes only, cf. `apps/orders/customerHash.ts`).
+ */
+import { sha256Hex } from "@tot/public-runtime";
+
+/** 32 bytes of CSPRNG entropy, hex-encoded — an opaque, unguessable link token. */
+export function randomToken(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(32));
+  let hex = "";
+  for (const b of bytes) hex += b.toString(16).padStart(2, "0");
+  return hex;
+}
+
+/** Salted one-way hash of the client IP — the consent record's IP evidence. */
+export function hashConsentIp(ip: string, salt: string): Promise<string> {
+  return sha256Hex(`${ip}:${salt}`);
+}