@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

package/apps/storefront/src/lib/integration/browserEnvironment.ts

@@ -0,0 +1,137 @@
+/**
+ * Storefront-side resolution of the renderer-owned four-stage browser
+ * environment (`@tot/public-runtime` `resolveBrowserEnvironment`). This is the ONE
+ * place request state is turned into the authoritative environment object; both
+ * document mounts (Layout.astro and `rawHtmlResponse`) serialize the result, so
+ * the object is identical in both by construction.
+ *
+ * The stage is derived from server facts only — `import.meta.env.DEV`, the request
+ * host, the resolved customization environment, and whether this is a per-change
+ * candidate render — never a client-supplied value. A candidate render is always
+ * `candidate` and never `live`; anything unresolved stays non-live.
+ */
+import {
+  resolveBrowserEnvironment,
+  resolveEnvironmentOnlyPlan,
+  type BrowserEnvironment,
+  type EffectivePlan,
+  type IntegrationSiteSurface,
+} from "@tot/public-runtime";
+import { isAdminPath } from "@/lib/auth/loginGate";
+
+/**
+ * The non-secret render revision: the commit SHA this build was cut from (baked at
+ * build time, the same value GET /health reports), or `"local"` when there is no
+ * git context (dev, vitest). Never a token or signed URL.
+ */
+function platformRevision(): string {
+  return typeof __GIT_SHA__ !== "undefined" && __GIT_SHA__ ? __GIT_SHA__ : "local";
+}
+
+/** A request host is local when it is served on loopback (`astro dev` or a local built Worker). */
+function isLocalHost(host: string): boolean {
+  return host.startsWith("localhost") || host.startsWith("127.0.0.1");
+}
+
+/**
+ * Map the resolved tenant + request path to a document surface. Admin/cockpit
+ * paths are `admin`; cart/checkout paths are `checkout`; a catalog tenant is
+ * `storefront`; a marketing tenant (no catalog) is `marketing`.
+ */
+export function deriveSiteSurface(input: {
+  catalog: boolean;
+  pathname: string;
+}): IntegrationSiteSurface {
+  // Admin + the cockpit control-plane panel (host-routed `/cockpit` or tenant-first
+  // `/<tenant>/cockpit`) are the `admin` surface.
+  if (isAdminPath(input.pathname) || /^\/(?:[^/]+\/)?cockpit(?:\/|$)/.test(input.pathname)) {
+    return "admin";
+  }
+  if (/^\/(checkout|cart)(\/|$)/.test(input.pathname)) return "checkout";
+  return input.catalog ? "storefront" : "marketing";
+}
+
+/**
+ * The normal (non-candidate) per-request environment object, computed once by the
+ * middleware. `astro dev` and a Worker served on localhost both resolve to `local`
+ * (their CSP-enforcement mode differs — report-only vs enforced — but that is a
+ * response-header concern, not part of this object).
+ */
+export function requestBrowserEnvironment(input: {
+  host: string;
+  isPreviewHost: boolean;
+  customizationEnv: "live" | "test";
+  canonicalHost: string;
+  siteSurface: IntegrationSiteSurface;
+}): BrowserEnvironment {
+  return resolveBrowserEnvironment({
+    dev: import.meta.env.DEV,
+    localHost: isLocalHost(input.host),
+    candidate: false,
+    previewHost: input.isPreviewHost,
+    customizationEnv: input.customizationEnv,
+    siteSurface: input.siteSurface,
+    canonicalHost: input.canonicalHost,
+    revision: platformRevision(),
+  });
+}
+
+/**
+ * CSP enforcement mode for this runtime — the axis that stays DISTINCT from the
+ * `local` stage. `astro dev` (Node) serves un-nonced Vite `<style>`/`<script>`, so a
+ * strict nonce policy would blank the site: it is REPORT-ONLY there (violations
+ * still surface). The built Worker is CSP-clean, so the strict policy is ENFORCED —
+ * including the built Worker run locally, which is how enforced CSP is proven.
+ * Report-only-dev and enforced-built-Worker are both correct; only the mode differs,
+ * never the four-stage environment object.
+ */
+export type CspEnforcementMode = "report-only" | "enforced";
+
+export function cspEnforcementMode(dev: boolean): CspEnforcementMode {
+  return dev ? "report-only" : "enforced";
+}
+
+/** The response header name that carries the mode: report-only in dev, enforced otherwise. */
+export function cspHeaderName(
+  dev: boolean,
+): "Content-Security-Policy-Report-Only" | "Content-Security-Policy" {
+  return dev ? "Content-Security-Policy-Report-Only" : "Content-Security-Policy";
+}
+
+/**
+ * The environment object for a per-change candidate render (the cockpit candidate
+ * renderer, the revision renderer, and the not-yet-built PR page). The stage is
+ * always `candidate` — never `live`, even when the underlying tenant is live — and
+ * `revision` is the candidate's own version identity (a versionId / head sha), a
+ * public, non-secret value.
+ */
+export function candidateBrowserEnvironment(input: {
+  canonicalHost: string;
+  revision: string;
+  siteSurface?: IntegrationSiteSurface;
+}): BrowserEnvironment {
+  return resolveBrowserEnvironment({
+    dev: import.meta.env.DEV,
+    localHost: false,
+    candidate: true,
+    previewHost: true,
+    customizationEnv: "test",
+    siteSurface: input.siteSurface ?? "marketing",
+    canonicalHost: input.canonicalHost,
+    revision: input.revision,
+  });
+}
+
+/**
+ * The resolved effective plan for a candidate render — the `candidate`-stage
+ * environment wrapped in an environment-only plan so `rawHtmlResponse` (the raw
+ * mount of the fixed-phase engine) renders the same renderer-owned phases a live
+ * page gets. No integration declarations are materialized on the candidate hot
+ * path, so this is environment-only until that wiring lands.
+ */
+export function candidateIntegrationPlan(
+  input: { canonicalHost: string; revision: string; siteSurface?: IntegrationSiteSurface },
+  tenantPublicId: string,
+): EffectivePlan {
+  return resolveEnvironmentOnlyPlan(candidateBrowserEnvironment(input), tenantPublicId);
+}

package/apps/storefront/src/lib/integration/managedInstallDeclarations.ts

@@ -0,0 +1,72 @@
+/**
+ * Materialize active managed-analytics installs into the render plane's existing
+ * declaration seam. `app_installs` owns status/manifest and MAX(seq) owns the
+ * active public config; candidates and drafts are never read here.
+ */
+import {
+  ENVIRONMENT_SCHEMA_VERSION,
+  buildPlatformAdapterDeclaration,
+  validateIntegrationManifest,
+  type IntegrationDeclarationInput,
+} from "@tot/public-runtime";
+import { AppVersionStore } from "../apps/appVersionStore.js";
+import type { Queryable } from "../d1/catalog.js";
+
+const MANAGED_KIND = "managed-analytics-v1";
+
+interface ActiveManagedRow {
+  install_id: string;
+  app_id: string;
+  app_version: string;
+  manifest: string;
+}
+
+/**
+ * Return only declarations whose canonical row, current immutable activation,
+ * and reviewed platform-adapter rebuild agree. Malformed/stale rows fail closed
+ * individually; an unavailable database is handled by the caller as no effects.
+ */
+export async function loadActiveManagedInstallDeclarations(
+  db: Queryable,
+  tenantPublicId: string,
+): Promise<IntegrationDeclarationInput[]> {
+  const rows = await db.all<ActiveManagedRow>(
+    `SELECT install_id, app_id, app_version, manifest
+       FROM app_installs
+      WHERE tenant_id = ? AND managed_kind = ? AND status = 'active'
+      ORDER BY install_id`,
+    tenantPublicId,
+    MANAGED_KIND,
+  );
+  const versions = new AppVersionStore(db);
+  const declarations: IntegrationDeclarationInput[] = [];
+  for (const row of rows) {
+    try {
+      const manifest = validateIntegrationManifest(JSON.parse(row.manifest) as unknown);
+      const current = await versions.currentVersion(row.install_id);
+      if (!manifest.ok || !current || current.tenantId !== tenantPublicId) continue;
+      if (current.appVersion !== row.app_version || current.facets.appVersion !== row.app_version) continue;
+      if (current.facets.digest !== manifest.value.app.digest || manifest.value.app.id !== row.app_id) continue;
+      const destinationId = current.facets.publicConfig["destinationId"];
+      if (typeof destinationId !== "string") continue;
+      const built = buildPlatformAdapterDeclaration({
+        adapterId: row.app_id,
+        ids: { live: destinationId },
+        tenantPublicId,
+        environment: {
+          schemaVersion: ENVIRONMENT_SCHEMA_VERSION,
+          siteSurface: "storefront",
+          environment: "live",
+          canonicalHost: tenantPublicId,
+          revision: `managed-live:${current.seq}`,
+        },
+      });
+      if (!built.ok || built.declaration.manifest.app.digest !== manifest.value.app.digest) continue;
+      declarations.push({ ...built.declaration, ref: `managed-install:${row.install_id}` });
+    } catch {
+      // Persisted JSON/version corruption must disable this install, never widen
+      // CSP or partially materialize a subscription.
+    }
+  }
+  return declarations;
+}

package/apps/storefront/src/lib/integration/nonceStamp.ts

@@ -0,0 +1,49 @@
+/**
+ * Per-response CSP-nonce stamping (ADR 0018 nonce non-serialization; ext-kernel-04).
+ *
+ * The renderer emits a nonce-free template: every platform inline tag and the CSP
+ * header carry {@link INTEGRATION_NONCE_PLACEHOLDER}, never a live nonce. This is
+ * what the edge cache stores — a nonce-free artifact. At serve time (a cold render
+ * OR a warm cache hit) this stamps ONE fresh per-response nonce into both the HTML
+ * body and the CSP header, so every response gets a fresh, matching nonce/CSP pair
+ * and no nonce is ever reused across responses.
+ */
+import { INTEGRATION_NONCE_PLACEHOLDER, stampNonce } from "@tot/public-runtime";
+
+const CSP_HEADERS = [
+  "content-security-policy",
+  "content-security-policy-report-only",
+] as const;
+
+/** A fresh, non-guessable per-response nonce. */
+export function freshNonce(): string {
+  return crypto.randomUUID();
+}
+
+/**
+ * Replace the nonce placeholder with a fresh `nonce` in a response's CSP header(s)
+ * and — for an HTML response — its body. Non-HTML responses keep their (streamed)
+ * body untouched; their CSP header is still stamped. A response with no placeholder
+ * (a static-bundle body, an API JSON) is returned effectively unchanged.
+ */
+export async function stampResponseNonce(
+  response: Response,
+  nonce: string,
+): Promise<Response> {
+  for (const header of CSP_HEADERS) {
+    const value = response.headers.get(header);
+    if (value && value.includes(INTEGRATION_NONCE_PLACEHOLDER)) {
+      response.headers.set(header, stampNonce(value, nonce));
+    }
+  }
+
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!contentType.includes("text/html")) return response;
+
+  const body = await response.text();
+  return new Response(stampNonce(body, nonce), {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+}

package/apps/storefront/src/lib/integration/tenantDeclarations.ts

@@ -0,0 +1,116 @@
+/**
+ * Tenant-local integration declaration materialization (ext-kernel-09).
+ *
+ * This is the ONE production seam that turns a tenant's OWN declared, exact-version
+ * integrations into the already-materialized {@link IntegrationDeclarationInput} set
+ * the render hot path consumes. The interim marketing bridge
+ * ({@link resolveInterimBridgePlan}) resolves that set into the effective plan the
+ * fixed-phase engine serves — refusing a regulated tenant, resolving an eligible
+ * unregulated one — so a declared tenant boots its integration on-by-default
+ * (consent-gated) with no page edit and no vendor branch.
+ *
+ * A tenant with no declaration returns the empty set, so the bridge resolves an
+ * environment-only plan and the request is byte-identical to non-integration
+ * behavior (zero cost). The declarations are already materialized in tenant config
+ * (the manifest, the resolved public config, the set of asset paths present for the
+ * version); this loader only reads them, fail-closed — resolution is the bridge's
+ * job, materialization is config's, and the two never blur.
+ */
+import type { IntegrationDeclarationInput, IntegrationManifest, TenantConfig } from "@tot/public-runtime";
+
+const NO_DECLARATIONS: readonly IntegrationDeclarationInput[] = Object.freeze([]);
+
+/**
+ * Read a tenant's already-materialized tenant-local declarations. Returns the empty
+ * set (never throws) when the tenant declares none or the field is malformed — an
+ * undeclared tenant must resolve to the environment-only plan, never an error.
+ */
+export function loadTenantIntegrationDeclarations(
+  tenant: Pick<TenantConfig, "integrations">,
+): readonly IntegrationDeclarationInput[] {
+  const declared = tenant.integrations;
+  if (!Array.isArray(declared) || declared.length === 0) return NO_DECLARATIONS;
+  return declared;
+}
+
+// ---------------------------------------------------------------------------
+// Demo tenant-local declaration — a same-origin sandbox analytics adapter.
+//
+// Seeded on the unregulated marketing demo/home tenants so a preview deploy
+// DEMONSTRABLY materializes a real integration on-by-default: its exact-version
+// entry module (committed under `public/apps/…`, so always materialized and served
+// same-origin) flows the declaration → interim bridge → effective plan → boot
+// descriptor → lifecycle import. Loading is consent-gated (purpose `analytics`,
+// held back under the default-deny snapshot until granted), and the declared
+// beacon origin reaches the strict CSP via `cspNeeds`. A regulated tenant carrying
+// the same declaration is still REFUSED by the bridge.
+// ---------------------------------------------------------------------------
+
+/** The demo adapter's app id — a same-origin, sandbox-tier marketing analytics adapter. */
+export const DEMO_ANALYTICS_APP_ID = "tot.demo.analytics";
+/** The demo adapter's exact pinned version. */
+export const DEMO_ANALYTICS_VERSION = "0.1.0";
+/**
+ * The same-origin, exact-version entry module the lifecycle runtime dynamically
+ * imports. Committed under `apps/storefront/public/apps/…` so it is served verbatim
+ * at this root-absolute URL and is ALWAYS materialized (no R2 pointer needed).
+ */
+export const DEMO_ANALYTICS_ENTRY_URL = `/apps/${DEMO_ANALYTICS_APP_ID}/${DEMO_ANALYTICS_VERSION}/entry.js`;
+/** The beacon endpoint the demo declaration reserves in CSP (`connect-src`). */
+export const DEMO_ANALYTICS_BEACON_ORIGIN = "https://demo-analytics.tokenoftrust.com";
+
+/** The demo adapter's shared browser manifest (ext-kernel-01 v2). */
+const DEMO_ANALYTICS_MANIFEST: IntegrationManifest = {
+  schemaVersion: 2,
+  app: {
+    id: DEMO_ANALYTICS_APP_ID,
+    name: "ToT Demo Analytics",
+    version: DEMO_ANALYTICS_VERSION,
+    digest: `sha256:${DEMO_ANALYTICS_APP_ID}-${DEMO_ANALYTICS_VERSION}`,
+    publisher: "Token of Trust",
+  },
+  compatibility: { storefrontBrowserContract: ">=2.0.0 <3.0.0", configurationSchemaVersion: 1 },
+  browser: {
+    executionTier: "sandbox",
+    entry: { asset: DEMO_ANALYTICS_ENTRY_URL, format: "module", phase: "document.deferred" },
+    contributions: [],
+    dependencies: [],
+    publicConfigSchema: {
+      type: "object",
+      additionalProperties: false,
+      required: ["siteId"],
+      properties: { siteId: { type: "string" } },
+    },
+    consent: {
+      purposes: ["analytics"],
+      loadWhen: "all-declared-purposes-eligible",
+      unknownState: "block",
+    },
+    // Same-origin entry loads under the strict base `'self'`; the declared beacon
+    // origin is the advanced exact source the compiler folds into `connect-src`.
+    csp: { profiles: [], sources: { "connect-src": [DEMO_ANALYTICS_BEACON_ORIGIN] } },
+    permissions: { events: ["storefront.page.viewed.v1"], data: [], actions: [], domIntent: "none" },
+    performanceBudget: {
+      maxTransferredBytes: 20000,
+      maxAdditionalRequests: 1,
+      maxMainThreadMilliseconds: 20,
+      mustBeAsyncOrDeferred: true,
+    },
+  },
+  server: { topics: [], secretRequirements: [] },
+  assurance: { requestedClassification: "baseline", regulatedTenantDefault: "disabled-until-certified" },
+  configurationMigrations: [],
+};
+
+/**
+ * The demo tenant-local declaration seeded on the unregulated marketing demo tenants.
+ * `materializedAssets` names the committed same-origin entry module, so the resolver's
+ * fail-closed materialized-asset check passes without any R2/publish step.
+ */
+export const DEMO_ANALYTICS_DECLARATION: IntegrationDeclarationInput = {
+  origin: "tenant-local",
+  ref: "config/tenants:demo-analytics",
+  manifest: DEMO_ANALYTICS_MANIFEST,
+  publicConfig: { siteId: "tot-demo" },
+  materializedAssets: [DEMO_ANALYTICS_ENTRY_URL],
+};

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/membership/eligibility.ts

@@ -1,6 +1,6 @@
 /**
  * Shopper membership eligibility — the request-scoped seam that resolves whether
- * the current shopper is a member, and which tier (F10).
+ * the current shopper is a member, and which tier.
  *
  * Phase 1 storefronts have NO shopper-login/account source (member accounts are
  * a Phase-2 managed-checkout capability), so this resolves anonymous

package/apps/storefront/src/lib/membership/model.ts

@@ -11,8 +11,7 @@
  * a tier explicitly asserts `real: true`, the widget marks its figures as
  * illustrative ("e.g." affordance + a group-level "Illustrative figures" label)
  * so example numbers are never presented as a live offer. This mirrors the
- * platform-owned / never-faked discipline of the compliance widgets (decision
- * `compliance-widgets-platform-owned`).
+ * platform-owned / never-faked discipline of the compliance widgets.
  */
 
 /**

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.
+ *
+ * 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'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.
+ *
+ * `randomToken` mints the opaque per-subscriber secret that both the confirm and
+ * 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}`);
+}