@tokenoftrust/storefront-runner 1.3.4-rc.3 → 1.4.0

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

@@ -58,3 +58,15 @@ export async function readR2(binding: string): Promise<R2Bucket | undefined> {
   const w = await getWorkerEnv();
   return (w?.[binding] as R2Bucket | undefined) ?? undefined;
 }
+
+/**
+ * Cloudflare Queue producer binding (e.g. WEBHOOK_DELIVERY_QUEUE), if present.
+ * Untyped (`unknown`) deliberately — callers cast to their own minimal
+ * queue-shape interface (see `webhooks/cloudflareQueueDispatcher.ts`'s
+ * `CloudflareQueueSender`) rather than this module taking a types dep on a
+ * specific binding's shape.
+ */
+export async function readQueue(binding: string): Promise<unknown | undefined> {
+  const w = await getWorkerEnv();
+  return w?.[binding] ?? undefined;
+}

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

@@ -9,8 +9,13 @@ export function organizationLd(tenant: TenantConfig, base: string) {
   // Logo sourced from the migrated brand assets (og image / logo), so the
   // Organization schema reflects the real merchant brand, not a generic favicon.
   const brand = tenant.theme_tokens?.brand;
-  const logo =
-    brand?.ogImage ?? brand?.logoLight ?? new URL("/favicon.svg", base + "/").toString();
+  // Absolutize the logo: schema.org wants an absolute URL, and tenant brand
+  // assets are stored as site-relative paths (e.g. /tenants/<id>/brand/og.svg).
+  // new URL() leaves an already-absolute value untouched.
+  const logo = new URL(
+    brand?.ogImage ?? brand?.logoLight ?? "/favicon.svg",
+    base + "/",
+  ).toString();
   return {
     "@context": "https://schema.org",
     "@type": "Organization",
@@ -97,10 +102,11 @@ export function productLd(
     url,
   }));
 
-  const ratingMf = p.metafields.find(
-    (m) => m.namespace === "reviews" && m.key === "rating",
-  );
-
+  // NO aggregateRating/review here — those are emitted ONLY from real sourced
+  // numbers by reviewLd(), which callers merge over this Product graph. Emitting
+  // a rating from a bare `reviews.rating` metafield (with a placeholder count)
+  // fabricates rich-result markup for stores with no real reviews (e.g. PVC),
+  // which violates the review-markup policy (docs/architecture/review-markup-policy.md).
   return {
     "@context": "https://schema.org",
     "@type": "Product",
@@ -121,17 +127,6 @@ export function productLd(
         : "https://schema.org/OutOfStock",
       offers,
     },
-    ...(ratingMf
-      ? {
-          aggregateRating: {
-            "@type": "AggregateRating",
-            ratingValue: ratingMf.value,
-            bestRating: "5",
-            // ASSUMPTION: review count placeholder; real capture is Phase 2.
-            ratingCount: 24,
-          },
-        }
-      : {}),
   };
 }
 

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

@@ -0,0 +1,37 @@
+/**
+ * Shopper membership eligibility — the request-scoped seam that resolves whether
+ * the current shopper is a member, and which tier (F10).
+ *
+ * Phase 1 storefronts have NO shopper-login/account source (member accounts are
+ * a Phase-2 managed-checkout capability), so this resolves anonymous
+ * (`{ isMember: false }`) by default. The pricing engine in
+ * `@tot/public-runtime` is real and unit-tested regardless; member pricing only
+ * RENDERS once a real eligibility signal flows through here.
+ *
+ * Production wires the signal from the resolved account claim (e.g. a
+ * member-tier cookie/JWT set by the Phase-2 login), so the whole storefront gets
+ * member pricing by threading one function — no per-page auth logic.
+ */
+import type { MemberContext } from "@tot/public-runtime";
+import { ANONYMOUS_MEMBER } from "@tot/public-runtime";
+
+/**
+ * The minimal membership signal a request carries. Phase 1 never populates it;
+ * production derives it from the shopper's resolved account (a member-tier
+ * claim). Kept tiny + framework-free so it is trivially testable.
+ */
+export interface MembershipSignal {
+  /** The shopper's membership tier id, if they are a signed-in member. */
+  memberTierId?: string | null;
+}
+
+/**
+ * Resolve the shopper's {@link MemberContext} from an optional membership signal.
+ * No signal (Phase 1, or an anonymous shopper) → non-member.
+ */
+export function resolveMemberContext(signal?: MembershipSignal | null): MemberContext {
+  if (signal?.memberTierId) {
+    return { isMember: true, tierId: signal.memberTierId };
+  }
+  return ANONYMOUS_MEMBER;
+}

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

@@ -0,0 +1,302 @@
+/**
+ * Monitoring contract (spec §F16 — 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
+ * 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
+ * `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.
+ *
+ * The companion operator doc renders this for humans and lists the external
+ * wiring/secrets checklist: docs/epics/sample-store-migration/monitoring-and-runbooks.md.
+ * RUNBOOK.md §6–§8 hold the incident runbooks these monitors dispatch to.
+ */
+
+/**
+ * Alert severity, in escalation order.
+ * - `page`     — wake someone now; launch-critical, customer-blocking.
+ * - `critical` — same-business-hours; degraded but not fully down, or a
+ *                compliance/legal risk that must be resolved before more sales.
+ * - `warning`  — investigate; a spike or trend that predicts a `critical`.
+ * - `info`     — record only; useful for post-incident context, no alert.
+ */
+export type Severity = "page" | "critical" | "warning" | "info";
+
+/** What each monitor watches, grouped so a dashboard can lane them. */
+export type MonitorCategory =
+  | "availability"
+  | "commerce"
+  | "compliance"
+  | "catalog"
+  | "performance"
+  | "security";
+
+/**
+ * Provisioning status of a monitor — the honest "is this actually alerting?"
+ * flag so a green manifest never implies coverage we don't have.
+ * - `in-code`        — the signal is emitted by code in THIS repo; only a log
+ *                      or metric alert rule needs attaching.
+ * - `needs-external` — depends on an external provider/probe/sink that must be
+ *                      configured (Cloudflare Health Check, Logpush alert, RUM).
+ * - `needs-secret`   — additionally blocked on a credential/token being set.
+ */
+export type WiringStatus = "in-code" | "needs-external" | "needs-secret";
+
+/**
+ * Stable ids for the six incident runbooks (RUNBOOK.md §7). Every monitor names
+ * the runbook an operator opens when it fires, so detection → response is a
+ * lookup, not archaeology.
+ */
+export type RunbookId =
+  | "checkout-down"
+  | "catalog-stale"
+  | "bad-price"
+  | "compliance-provider-down"
+  | "tax-shipping-outage"
+  | "bad-content-policy";
+
+export interface Monitor {
+  /** Stable kebab-case id; also the alert name. Never renamed once shipped. */
+  id: string;
+  /** One-line human title for dashboards/alerts. */
+  title: string;
+  category: MonitorCategory;
+  /** Where the signal comes from and how a monitor reads it. */
+  signal: {
+    /** The emitter — code symbol/path in this repo, or a named sibling contract. */
+    source: string;
+    /** How the alert observes it: probe, Worker metric, log filter, RUM, webhook. */
+    observe: string;
+  };
+  /** The alarm condition in plain, checkable terms (thresholds are launch defaults). */
+  threshold: string;
+  severity: Severity;
+  /** Which incident runbook to run when this fires. */
+  runbook: RunbookId;
+  wiring: WiringStatus;
+  /** External dependency, secret name, or sibling-unit signal reference. */
+  notes?: string;
+}
+
+/**
+ * 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.
+ */
+export const MONITORS: readonly Monitor[] = [
+  {
+    id: "uptime",
+    title: "Storefront uptime / liveness",
+    category: "availability",
+    signal: {
+      source: "GET /health (lib/health.ts — answered before tenant/gate/cache)",
+      observe: "external synthetic probe hits /health across regions; expects 200 {status:'ok'}",
+    },
+    threshold: "2 consecutive probe failures (or >1% of probes failing over 5m)",
+    severity: "page",
+    runbook: "checkout-down",
+    wiring: "needs-external",
+    notes:
+      "Wire a Cloudflare Health Check (or external uptime monitor) per production host. " +
+      "/health also returns the live commit .sha — use it to confirm which build is up during an incident.",
+  },
+  {
+    id: "page-errors",
+    title: "Page / Worker errors (5xx + unhandled exceptions)",
+    category: "availability",
+    signal: {
+      source: "Cloudflare Worker exceptions + non-2xx responses from middleware/index.ts render path",
+      observe: "Workers 'Errors' metric + Logpush; alert on error-rate over the request baseline",
+    },
+    threshold: "5xx rate > 1% over 5m, or any sustained unhandled-exception stream",
+    severity: "critical",
+    runbook: "bad-content-policy",
+    wiring: "needs-external",
+    notes:
+      "A spike isolated to one route usually points at a bad publish/content artifact (see bad-content-policy); " +
+      "a broad spike is an availability event (checkout-down).",
+  },
+  {
+    id: "checkout-failures",
+    title: "Checkout failures (add-to-cart / checkout handoff)",
+    category: "commerce",
+    signal: {
+      source:
+        "Signed add-to-cart + cross-origin checkout POST (F11; lib/checkoutCommerce.ts, checkoutCspAdditions)",
+      observe:
+        "Worker logs on the signed add-to-cart path + checkout-host success beacon; alert on failure ratio",
+    },
+    threshold: "checkout-start error ratio > 2% over 10m, or add-to-cart 5xx > 1% over 5m",
+    severity: "page",
+    runbook: "checkout-down",
+    wiring: "needs-external",
+    notes:
+      "Checkout completes on the store's cross-origin cart/checkout host, so full funnel coverage needs a beacon " +
+      "from that host too. Storefront-side we can only see the signed handoff; a CSP formAction/frameSrc block " +
+      "also surfaces here as csp-violations.",
+  },
+  {
+    id: "age-verification-failures",
+    title: "Age-verification failures",
+    category: "compliance",
+    signal: {
+      source:
+        "F12 compliance 'age-verification' evidence signal (AgeGate / IsolatedAgeGate → ToT verification)",
+      observe: "F12 evidence signal + ToT verification provider errors; alert on error/timeout rate, not on user-declines",
+    },
+    threshold: "verification provider error/timeout rate > 5% over 10m (distinct from legitimate fail-age outcomes)",
+    severity: "critical",
+    runbook: "compliance-provider-down",
+    wiring: "needs-external",
+    notes:
+      "Reference F12's signal by name; do NOT read the compliance internals here. Distinguish PROVIDER failure " +
+      "(page/critical — we can't legally sell) from a shopper genuinely failing age (expected, not an alert). " +
+      "Pre-launch config-coherence gate is in-repo: GET /api/evidence.json (assembleEvidenceReport → age_gate).",
+  },
+  {
+    id: "restricted-state-denials",
+    title: "Restricted-state / shipping denials (anomaly)",
+    category: "compliance",
+    signal: {
+      source:
+        "F12 compliance 'restricted-state denial' signal (StateEligibilityNotice / ShippingRestrictionNotice / complianceFloor)",
+      observe: "F12 evidence signal counted per state; alert on ANOMALOUS spike vs baseline, not on absolute count",
+    },
+    threshold: "denial rate for a state jumps >3x its 7-day baseline over 1h (mis-configured rule, not normal traffic)",
+    severity: "warning",
+    runbook: "bad-content-policy",
+    wiring: "needs-external",
+    notes:
+      "Denials are EXPECTED (that's the control working). This monitor catches a mis-configured restriction " +
+      "rule that suddenly blocks a legal state — a spike, not a level. Reference F12's signal by name. " +
+      "Pre-launch config-coherence gate is in-repo: GET /api/evidence.json (jurisdiction/excise signals).",
+  },
+  {
+    id: "catalog-sync-failures",
+    title: "Catalog sync failures",
+    category: "catalog",
+    signal: {
+      source: "Migration incremental sync (packages/migration) + F17 catalog graduation job",
+      observe: "sync-job exit status + migration report (errors/skipped); alert on failed or missed run",
+    },
+    threshold: "any sync job fails, OR no successful sync within the expected cadence window (default 1h)",
+    severity: "warning",
+    runbook: "catalog-stale",
+    wiring: "needs-external",
+    notes:
+      "Escalate to critical once a store is on a live source (F17): a failed sync means the catalog is drifting " +
+      "from the merchant source. Depends on F17 defining the launch cadence.",
+  },
+  {
+    id: "inventory-mismatch",
+    title: "Inventory mismatch (oversell risk)",
+    category: "catalog",
+    signal: {
+      source: "F17 inventory-freshness mismatch alarm (storefront-shown vs source-of-truth stock)",
+      observe: "reconciliation check comparing served inventory to the merchant/hosted source",
+    },
+    threshold: "any product served in-stock while source says out-of-stock, or staleness > sync cadence + grace",
+    severity: "critical",
+    runbook: "catalog-stale",
+    wiring: "needs-external",
+    notes:
+      "Overselling regulated goods is a launch-blocker. This alarm is the one F16 defines but F17 FEEDS with real " +
+      "data — until F17 lands it is a contract only.",
+  },
+  {
+    id: "payment-failures",
+    title: "Payment failures",
+    category: "commerce",
+    signal: {
+      source: "Payment provider on the checkout host (external to the storefront Worker)",
+      observe: "payment provider dashboard/webhooks; alert on declined/error rate vs baseline",
+    },
+    threshold: "payment error rate (non-decline gateway errors) > 3% over 15m",
+    severity: "page",
+    runbook: "checkout-down",
+    wiring: "needs-external",
+    notes:
+      "Owned by the checkout/payment provider, not this Worker. Separate genuine card declines (expected) from " +
+      "gateway/integration errors (alert). Coordinate the provider webhook wiring with F11/F17 owners.",
+  },
+  {
+    id: "csp-violations",
+    title: "CSP violations",
+    category: "security",
+    signal: {
+      source: "POST /api/csp-report (CSP_REPORT_PATH / CSP_REPORT_GROUP) — logs '[csp-report]'",
+      observe: "log-based alert on '[csp-report]' volume; CSP is ENFORCED in prod (middleware sets Content-Security-Policy)",
+    },
+    threshold: "sustained new-violation stream (> baseline) — esp. on checkout/widget origins after a publish",
+    severity: "warning",
+    runbook: "bad-content-policy",
+    wiring: "in-code",
+    notes:
+      "Emitter already ships (pages/api/csp-report.ts). Only a log-volume alert rule needs attaching. A spike after " +
+      "a tenant publish means a script/style/frame origin needs adding to the allowlist — or a blocked injection.",
+  },
+  {
+    id: "core-web-vitals",
+    title: "Core Web Vitals (LCP / INP / CLS)",
+    category: "performance",
+    signal: {
+      source: "F14 RUM beacon (web-vitals: LCP, INP, CLS) — Real User Monitoring",
+      observe: "RUM sink p75 per metric per key template (home, PLP, PDP, checkout entry)",
+    },
+    threshold: "p75 regresses past 'good': LCP > 2.5s, INP > 200ms, CLS > 0.1 (sustained over 1h)",
+    severity: "warning",
+    runbook: "bad-content-policy",
+    wiring: "needs-external",
+    notes:
+      "Reference F14's RUM signal by name; do NOT edit F14's analytics files. Cloudflare Web Analytics " +
+      "(PUBLIC_CF_ANALYTICS_TOKEN, injected in Layout.astro) gives field CWV today; F14's beacon gives per-template detail.",
+  },
+] as const;
+
+/**
+ * The monitors §F16 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.
+ */
+export const REQUIRED_MONITOR_IDS = [
+  "uptime",
+  "page-errors",
+  "checkout-failures",
+  "age-verification-failures",
+  "restricted-state-denials",
+  "catalog-sync-failures",
+  "inventory-mismatch",
+  "payment-failures",
+  "csp-violations",
+  "core-web-vitals",
+] as const;
+
+/** The six incident runbooks in RUNBOOK.md §7 that monitors dispatch to. */
+export const RUNBOOK_IDS: readonly RunbookId[] = [
+  "checkout-down",
+  "catalog-stale",
+  "bad-price",
+  "compliance-provider-down",
+  "tax-shipping-outage",
+  "bad-content-policy",
+] as const;
+
+/** Lookup a monitor by id (undefined if absent). */
+export function getMonitor(id: string): Monitor | undefined {
+  return MONITORS.find((m) => m.id === id);
+}
+
+/** Monitors still needing external wiring or a secret before they alert. */
+export function monitorsNeedingWiring(): readonly Monitor[] {
+  return MONITORS.filter((m) => m.wiring !== "in-code");
+}

package/apps/storefront/src/lib/privacy/emailHint.ts

@@ -6,7 +6,16 @@ function maskPart(part: string): string {
   return `${part.slice(0, 1)}...${part.slice(-1)}`;
 }
 
-/** Display-only email hint for URLs/log-safe UX. Never returns the full address. */
+/**
+ * Display-only email hint for URLs/log-safe UX. Never returns the full address:
+ * the LOCAL part — the personal identifier — is always masked. The DOMAIN is shown
+ * in full for recognition value ("that's my work address"): a corporate domain is
+ * org-level, not personal data on its own, and the masked local part keeps this from
+ * being a clean, greppable address in a URL/log. Kept within the current GDPR posture
+ * (see the mask-level decision in auth/magic + the signed-in cockpit, which shows the
+ * FULL address from the validated session — never from a URL). Masks with `.` (not `*`)
+ * so the hint round-trips back through normalizeEmailHint's SAFE_HINT_RE.
+ */
 export function redactEmailForHint(email: string): string | null {
   const raw = String(email || "").trim().toLowerCase();
   const at = raw.indexOf("@");
@@ -15,10 +24,9 @@ export function redactEmailForHint(email: string): string | null {
   const domain = raw.slice(at + 1);
   const parts = domain.split(".").filter(Boolean);
   if (parts.length < 2) return null;
-  const suffix = parts.pop();
-  const registrable = parts.join(".");
-  if (!suffix || !registrable) return null;
-  return `${maskPart(local)}@${maskPart(registrable)}.${suffix}`;
+  const suffix = parts[parts.length - 1];
+  if (!suffix || !local) return null;
+  return `${maskPart(local)}@${domain}`;
 }
 
 /**