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

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

@@ -1,255 +1,50 @@
 /**
- * Chrome model — typed props for the reusable, tenant-agnostic site-chrome
- * components (AnnouncementBar, UtilityNav, SiteHeader, NavDropdown/MegaMenu,
- * SiteFooter). Chrome is a STANDARD component set skinned by theme tokens, never
- * hand-built per tenant page. A tenant's chrome is data (`chrome.json`) that
- * populates these shapes; the wrapping mechanism (see lib/rawChrome.ts) surrounds
- * body-only page fragments with the rendered chrome.
+ * Chrome model — re-export of `@tot/public-runtime`'s chrome schema
+ * (packages/public-runtime/src/chrome.ts). Moved there so
+ * `@tot/private-controlplane`'s write-side `ArtifactValidator` for
+ * `tenants/<id>/content/chrome.json`
+ * (packages/private-controlplane/src/customization-chrome.ts) can validate
+ * against the SAME schema without the renderer importing the control-plane
+ * package (the `renderer-no-controlplane` fence,
+ * apps/storefront/.dependency-cruiser.cjs, runs the other way: packages may
+ * depend on `@tot/public-runtime`, the renderer must never import
+ * `@tot/private-controlplane`). This file is kept as the renderer's stable
+ * import path — every existing `./model.js` import keeps resolving unchanged.
  */
-
-/** A navigation/footer link. `external` opens off-site; `badge` shows e.g. "NEW". */
-export interface ChromeLink {
-  label: string;
-  href: string;
-  external?: boolean;
-  badge?: string;
-}
-
-/** One column of a mega-menu panel. */
-export interface MegaColumn {
-  title?: string;
-  links: ChromeLink[];
-}
-
-/**
- * A primary-nav item. A plain link (no children/columns), a single-column
- * dropdown (`children`), or a multi-column mega-menu (`columns`). `badge` marks
- * it (e.g. "NEW"); `flag` gives it the emphasized/highlighted treatment.
- */
-export interface ChromeNavItem {
-  label: string;
-  href: string;
-  badge?: string;
-  flag?: boolean;
-  children?: ChromeLink[];
-  columns?: MegaColumn[];
-}
-
-export interface SocialLink {
-  label: string;
-  href: string;
-  /** Optional inline-SVG path data (single <path d="…">) — no external images. */
-  iconPath?: string;
-}
-
-export interface ChromeLogo {
-  src: string;
-  alt: string;
-  width?: number;
-  height?: number;
-}
-
-/** A marketing conversion CTA (header-actions / footer, non-commerce tenants). */
-export interface ChromeCta {
-  label: string;
-  href: string;
-  variant?: "primary" | "secondary" | "ghost";
-}
-
-export interface FooterColumn {
-  title: string;
-  links: ChromeLink[];
-}
-
-export interface FooterNewsletter {
-  title?: string;
-  body?: string;
-  /** Form action (defaults to /api/newsletter). */
-  action?: string;
-  placeholder?: string;
-  /** Hidden `source` field value (e.g. "footer"). */
-  source?: string;
-  /** When true, render the "I confirm I am 21+" age-attestation checkbox (regulated tenants). */
-  ageAttestation?: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// TenantChrome — the FULL per-tenant chrome config (content only) that drives the
-// canonical RAW chrome wrapper (unit F3, see lib/rawChrome.ts). It is the superset
-// the three vape tenants need: bigd/giant (marquee announce + flat nav + utility
-// social) and PVC (dismissible rotating bar + mega panels + member cue + age gate +
-// trust marks). A tenant authors this as `chrome.json`; the renderer turns it into
-// the wrapper document that the rawMarketingHtml splice pipeline surrounds body-only
-// page fragments with. CONTENT ONLY — every color/space/type comes from theme
-// tokens via the platform-shipped stylesheet (decision raw-chrome-single-stylesheet);
-// this config carries no styling. The same file also feeds SiteChrome (getChrome);
-// the two consumers read overlapping-but-distinct field subsets.
-// ---------------------------------------------------------------------------
-
-/** A brand identity: an image wordmark/logo, OR a text wordmark of styled spans. */
-export interface ChromeBrand {
-  /** Link target (defaults to "/"). */
-  href?: string;
-  /** Accessible name (aria-label / img alt), e.g. "Prime Vapor Club". */
-  label: string;
-  /** Image wordmark. Preferred when present and a valid src. */
-  logo?: ChromeLogo;
-  /**
-   * Text wordmark rendered as inline spans (e.g. PVC's `Prime`/`Vapor`/`Club`),
-   * each span optionally given a class the theme styles. Used when there's no logo
-   * image (placeholder brand — brief §9 Q15).
-   */
-  wordmark?: { text: string; className?: string }[];
-  /** Marks the brand as a stand-in for a pending real logo (adds data-placeholder). */
-  placeholder?: boolean;
-}
-
-/** Header search affordance (progressive GET form). Omit to hide search. */
-export interface ChromeSearch {
-  /** Form action (defaults to "/search"). */
-  action?: string;
-  placeholder?: string;
-  /** sr-only label (defaults to "Search"). */
-  label?: string;
-}
-
-/** The persistent member-price cue for guests (regulated/membership tenants). */
-export interface ChromeMemberCue {
-  label: string;
-  href: string;
-}
-
-/** The thin utility bar above the header: minor links, locale chips, social, cue. */
-export interface ChromeUtilityNav {
-  links?: ChromeLink[];
-  /** Locale/currency chips shown on the right (e.g. "English", "United States (USD $)"). */
-  locale?: string[];
-  social?: SocialLink[];
-  /** Optional right-aligned member-price cue link. */
-  memberCue?: ChromeMemberCue;
-}
-
-/**
- * Announcement banner. Three variants map to the F2 stylesheet's classes:
- *   - "marquee": infinite horizontal scroll (bigd/giant `.announce-marquee`);
- *   - "bar": dismissible + optionally message-rotating promo bar (PVC `.announce-bar`);
- *   - "solid": a static single-line solid bar (`.announce`).
- */
-export interface ChromeAnnouncement {
-  variant: "marquee" | "bar" | "solid";
-  /** One or more messages. "bar" rotates through them when >1 and rotateMs set. */
-  messages: string[];
-  /** aria-label for the region (defaults to the first message). */
-  label?: string;
-  /** "bar" only — show a dismiss button (remembered via storageKey). */
-  dismissible?: boolean;
-  /** "bar" only — rotate messages every N ms (needs messages.length > 1). */
-  rotateMs?: number;
-  /** localStorage key remembering a dismissal (defaults to a stable derived key). */
-  storageKey?: string;
-}
-
-/**
- * 21+ age-gate interstitial config (regulated tenants). The F3 renderer (rawChrome.ts)
- * embeds this as JSON; the shared behavior JS mounts the gate inside a closed shadow
- * root — the same tamper-resistance pattern components/islands/IsolatedAgeGate.tsx
- * uses for component pages (unit C1) — so tenant CSS/JS can't reach the dialog.
- * Per decision compliance-widgets-platform-owned.
- */
-export interface ChromeAgeGate {
-  minAge: number;
-  /** localStorage key remembering a pass (defaults to a stable derived key). */
-  storageKey?: string;
-  title?: string;
-  lede?: string;
-  yesLabel?: string;
-  noLabel?: string;
-  denyText?: string;
-  /** Fine-print warning under the actions (e.g. the FDA nicotine line). */
-  fineText?: string;
-  /** Optional styled wordmark above the title (spans, like ChromeBrand.wordmark). */
-  mark?: { text: string; className?: string }[];
-}
-
-/** Footer brand block: identity + tagline/contact + optional inline newsletter. */
-export interface ChromeFooterBrand {
-  logo?: ChromeLogo;
-  wordmark?: { text: string; className?: string }[];
-  /** Tagline / contact HTML-free text (rendered with <br> on newlines). */
-  text?: string;
-}
-
-/** A footer trust mark: a small inline-SVG cue + label (e.g. "Secure checkout"). */
-export interface ChromeTrustMark {
-  /** Inner SVG markup (paths/rects/circles), viewBox 0 0 24 24. */
-  icon: string;
-  label: string;
-}
-
-/** The full footer content. */
-export interface ChromeFooter {
-  brand?: ChromeFooterBrand;
-  columns: FooterColumn[];
-  newsletter?: FooterNewsletter;
-  trustMarks?: ChromeTrustMark[];
-  /** Accepted-payment marks (text tokens, e.g. "VISA"). */
-  payments?: string[];
-  social?: SocialLink[];
-  /** The bold compliance/nicotine warning block. */
-  warning?: string;
-  /** Bottom bar: copyright + a legal note line. */
-  bottom?: { copyright?: string; note?: string };
-}
-
-/** Per-tenant <head> extras the wrapper links (the shared css is ALWAYS linked). */
-export interface ChromeHead {
-  /** Favicon href (image/png). */
-  favicon?: string;
-  /** Tenant theme stylesheet hrefs (token definitions), e.g. the *-navy.css theme. */
-  themeStylesheets?: string[];
-  /** <meta name="theme-color"> — a deliberately brand-fixed surface color. */
-  themeColor?: string;
-}
-
-export interface TenantChrome {
-  /**
-   * OPT-IN: render the canonical shared chrome for this tenant's RAW page
-   * fragments. Absent/false ⇒ the tenant keeps serving its hand-authored
-   * chrome.html (or a full document) unchanged — so a shipped tenant never flips
-   * to shared chrome until it explicitly adopts (units I1/I2/I3). Required so the
-   * cutover of a SHIPPED tenant stays a deliberate, gated step.
-   */
-  sharedChrome?: boolean;
-  /**
-   * OPT-IN: also link the shared commerce-MARKETING stylesheet
-   * (/shared/commerce-marketing.css, unit F5) into this tenant's wrapper — the
-   * raw-page BODY layer (page-hero / prose / callouts / value & tier cards /
-   * contact form / FAQ / CTA band) its content fragments repeat. Linked AFTER the
-   * chrome sheet so its page-level variants win. Absent/false ⇒ not linked, so a
-   * SHIPPED tenant that still carries its own page-local <style> never
-   * double-loads or silently flips until its integration unit strips that CSS and
-   * adopts (same gated-cutover discipline as `sharedChrome`).
-   */
-  sharedMarketingCss?: boolean;
-  /** <html lang> (defaults to "en"). */
-  lang?: string;
-  head?: ChromeHead;
-  /** Skip-link target/label overrides (defaults to "#main" / "Skip to main content"). */
-  skipLink?: { href?: string; label?: string };
-  /** FDA/compliance warning strip at the very top (e.g. the nicotine line). */
-  warningBar?: string;
-  announcement?: ChromeAnnouncement;
-  utilityNav?: ChromeUtilityNav;
-  brand: ChromeBrand;
-  search?: ChromeSearch;
-  /** Header-actions member-price cue (in addition to any utility-nav cue). */
-  memberCue?: ChromeMemberCue;
-  accountHref?: string;
-  cartHref?: string;
-  /** Primary nav — flat links and/or mega panels (ChromeNavItem.columns). */
-  nav: ChromeNavItem[];
-  ageGate?: ChromeAgeGate;
-  /** The compliance strip below the page body (e.g. the nicotine warning). */
-  complianceStrip?: string;
-  footer: ChromeFooter;
-}
+export {
+  type ChromeLink,
+  type MegaColumn,
+  type ChromeNavItem,
+  type SocialLink,
+  type ChromeLogo,
+  type ChromeCta,
+  type ChromeActionLink,
+  type FooterColumn,
+  type FooterNewsletter,
+  type ChromeBrand,
+  type ChromeSearch,
+  type ChromeUtilityNav,
+  type ChromeAnnouncement,
+  type ChromeAgeGate,
+  type ChromeFooterBrand,
+  type ChromeTrustMark,
+  type ChromeHead,
+  HEADER_VARIANTS,
+  type HeaderVariant,
+  FOOTER_VARIANTS,
+  type FooterVariant,
+  isHeaderVariant,
+  isFooterVariant,
+  InvalidChromeVariantError,
+  type ChromeHeader,
+  type ChromeFooter,
+  type ChromeConfig,
+  type ChromeAssignmentEntry,
+  type ChromeAssignments,
+  type ChromeAssignmentsValidationResult,
+  type ValidateChromeAssignmentsOptions,
+  normalizeChromePagePath,
+  validateChromeAssignments,
+  parseChromeAssignments,
+  resolveChromeAssignment,
+} from "@tot/public-runtime";

package/apps/storefront/src/lib/chrome/navCurrent.ts

@@ -0,0 +1,29 @@
+/**
+ * Exact-match "is this nav link the current page" check, for aria-current="page".
+ *
+ * Deliberately NOT prefix/startsWith matching: a parent section link (e.g.
+ * "/shop") must never be marked current just because the visitor is on a page
+ * nested under it (e.g. "/shop/widget") — only an exact path match counts.
+ * External links and hash-only in-page anchors (a nav href containing "#")
+ * never match: aria-current="page" identifies a distinct page, not a scroll
+ * position on the page already open.
+ *
+ * Both `currentPathname` and `href` are expected to already carry the same
+ * tenant base-path prefix (i.e. compare `Astro.url.pathname` against an
+ * href already run through `withBase`) — this function only normalizes
+ * trailing slashes, it does not resolve base paths itself.
+ */
+export function isCurrentNavHref(
+  currentPathname: string,
+  href: string,
+  external?: boolean,
+): boolean {
+  if (external || href.includes("#")) return false;
+  const hrefPath = href.split("?")[0] ?? href;
+  return normalizeNavPath(currentPathname) === normalizeNavPath(hrefPath);
+}
+
+function normalizeNavPath(pathname: string): string {
+  if (pathname.length > 1 && pathname.endsWith("/")) return pathname.slice(0, -1);
+  return pathname || "/";
+}

package/apps/storefront/src/lib/chrome/parseConfig.ts

@@ -1,34 +1,20 @@
 /**
- * Parse/validate a tenant's `chrome.json` as a raw-chrome `TenantChrome` config
- * (unit F3). This is the OPT-IN gate for the canonical shared chrome: it returns a
- * config ONLY when the tenant has explicitly set `sharedChrome: true` AND supplies
- * the minimum a wrapper needs (brand + nav + footer). Any other shape — a tenant
- * that hasn't adopted, or a half-authored file — returns null, so the caller keeps
- * serving the tenant's hand-authored chrome.html (or falls back cleanly) and a
- * shipped tenant never flips to shared chrome by accident. Adoption (authoring the
- * canonical config + removing chrome.html) is the tenant-integration units (I1/I2/I3).
+ * Fail-closed schema validation for a tenant's `chrome.json` — the ONE gate
+ * every consumer (the raw-chrome wrapper renderer, the token-styled
+ * <SiteHeader>/<SiteFooter> fallback) now parses through.
+ *
+ * Re-exports `@tot/public-runtime`'s {@link validateChromeConfig} /
+ * {@link parseChromeConfig} (packages/public-runtime/src/chrome.ts) — the
+ * validation logic itself lives there so
+ * `@tot/private-controlplane`'s write-side `ArtifactValidator` for
+ * `tenants/<id>/content/chrome.json`
+ * (packages/private-controlplane/src/customization-chrome.ts) can call the
+ * SAME check without the renderer importing the control-plane package. This
+ * file is kept as the renderer's stable import path — every existing
+ * `./parseConfig.js` import keeps resolving unchanged.
  */
-import type { TenantChrome } from "./model.js";
-
-function isObject(v: unknown): v is Record<string, unknown> {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-
-/**
- * Coerce parsed chrome.json into a `TenantChrome`, or null if it isn't an opted-in,
- * minimally-complete raw-chrome config. Trusts the authored (first-party) field
- * shapes beyond the required-key check — the renderer is defensive (escapes values,
- * guards every optional section), so a missing optional degrades rather than breaks.
- */
-export function parseChromeConfig(raw: unknown): TenantChrome | null {
-  if (!isObject(raw)) return null;
-  // Opt-in switch — absent/false means "not adopted; keep legacy chrome".
-  if (raw.sharedChrome !== true) return null;
-  // Minimum a wrapper needs to render something coherent.
-  const brand = raw.brand;
-  if (!isObject(brand) || typeof brand.label !== "string") return null;
-  if (!Array.isArray(raw.nav)) return null;
-  const footer = raw.footer;
-  if (!isObject(footer) || !Array.isArray(footer.columns)) return null;
-  return raw as unknown as TenantChrome;
-}
+export {
+  type ChromeConfigValidationResult,
+  validateChromeConfig,
+  parseChromeConfig,
+} from "@tot/public-runtime";

package/apps/storefront/src/lib/chrome/variant.ts

@@ -0,0 +1,39 @@
+/**
+ * Explicit header/footer variant assignment (fail-closed).
+ *
+ * A page declares its `headerVariant`/`footerVariant` via a Layout.astro prop
+ * (see layouts/Layout.astro) — NEVER inferred from the route, a CSS class, or
+ * the page title. `resolveHeaderVariant`/`resolveFooterVariant` apply the
+ * page's override over the tenant's chrome-config default and assert the
+ * result is a known variant, throwing `InvalidChromeVariantError` (actionable
+ * message, not a silent fallback) when it isn't.
+ */
+import {
+  FOOTER_VARIANTS,
+  HEADER_VARIANTS,
+  InvalidChromeVariantError,
+  isFooterVariant,
+  isHeaderVariant,
+  type FooterVariant,
+  type HeaderVariant,
+} from "./model.js";
+
+export function assertHeaderVariant(v: unknown): HeaderVariant {
+  if (!isHeaderVariant(v)) throw new InvalidChromeVariantError("header", v, HEADER_VARIANTS);
+  return v;
+}
+
+export function assertFooterVariant(v: unknown): FooterVariant {
+  if (!isFooterVariant(v)) throw new InvalidChromeVariantError("footer", v, FOOTER_VARIANTS);
+  return v;
+}
+
+/** The page's explicit override, if given and valid; else the chrome config's
+ * own declared variant. Always fails closed — never falls back silently. */
+export function resolveHeaderVariant(pageOverride: unknown, configDefault: unknown): HeaderVariant {
+  return assertHeaderVariant(pageOverride ?? configDefault);
+}
+
+export function resolveFooterVariant(pageOverride: unknown, configDefault: unknown): FooterVariant {
+  return assertFooterVariant(pageOverride ?? configDefault);
+}

package/apps/storefront/src/lib/commerce/checkoutHandoffCorrelation.ts

@@ -0,0 +1,105 @@
+/**
+ * Request-scoped mint of the checkout-correlation token at the checkout handoff
+ * (ext-commerce-10). This is the browser-`checkout.handoff` counterpart of the
+ * server-side order join (ext-commerce-04, `orderConversionD1.ts`): it calls the
+ * ext-commerce-03 mint (`correlationForHandoff`) so a token is carried through the
+ * managed (Foxy) checkout and echoed back on the verified order webhook, threading
+ * the browser handoff to its authoritative conversion end-to-end.
+ *
+ * Three properties hold by construction:
+ *
+ *   - ANALYTICS CONSENT IS REQUIRED (ADR 0023 Q3 `gate-legal-q3-correlation-token`).
+ *     The consent gate runs FIRST: when the shopper is not analytics-eligible the
+ *     token is never minted (the secret is not even read) and the handoff proceeds
+ *     UNATTRIBUTED. The correlation is never smuggled past a withheld consent.
+ *
+ *   - ENV-CONSISTENT. The token binds the request's own {@link IntegrationEnvironment}
+ *     stage (the renderer-owned `BrowserEnvironment.environment`, server-supplied,
+ *     never client-set), so a token minted here can only ever verify against an order
+ *     in the SAME tenant/stage — a candidate/staged token can never attribute a live
+ *     order, and the reverse.
+ *
+ *   - FAIL-SAFE TO UNATTRIBUTED. With no signing key configured
+ *     (`COMMERCE_CORRELATION_SECRET` unset — the expected state on any tier that has
+ *     not provisioned it, incl. preview) this returns an explicit unattributed
+ *     outcome. It NEVER throws and NEVER blocks checkout; an unattributed order is
+ *     recorded, not dropped.
+ */
+import {
+  correlationForHandoff,
+  CORRELATION_CONSENT_PURPOSE,
+  isPurposeEligible,
+  type ConsentSnapshot,
+  type HandoffCorrelation,
+  type IntegrationEnvironment,
+} from "@tot/public-runtime";
+import { readEnv } from "@/lib/env";
+
+/** The server-only correlation-signing key binding — distinct from the cart secret
+ * (key separation), and the SAME binding the order join verifies against. */
+export const CORRELATION_SECRET_ENV = "COMMERCE_CORRELATION_SECRET";
+
+/**
+ * The handoff mint outcome. The attributed branch is exactly the mint's
+ * {@link HandoffCorrelation} attributed shape (token + cart field + event
+ * correlation); the unattributed branch adds `secret-unavailable` to the pure gate's
+ * `analytics-consent-required`, so the caller can tell "consent withheld" from
+ * "no signing key" without either ever throwing.
+ */
+export type CheckoutHandoffCorrelation =
+  | Extract<HandoffCorrelation, { attributed: true }>
+  | { attributed: false; reason: "analytics-consent-required" | "secret-unavailable" };
+
+export interface CheckoutHandoffCorrelationInput {
+  /** The tenant, from trusted server execution context — never a client value. */
+  tenant: string;
+  /**
+   * The request's stage, from the renderer-owned `BrowserEnvironment.environment`.
+   * Server-supplied for env-consistency: the token can only verify against an order
+   * in this same stage.
+   */
+  environment: IntegrationEnvironment;
+  /** The shopper's live consent snapshot (parsed fail-closed by the caller). */
+  consent: ConsentSnapshot;
+  /** The opaque logical handoff event id the order join threads back to. */
+  eventId: string;
+  /** Bounded token lifetime; defaults to the mint's `DEFAULT_CORRELATION_TTL_SECONDS`. */
+  ttlSeconds?: number;
+  /** Injectable wall clock in ms (defaults to `Date.now()`) for deterministic tests. */
+  now?: number;
+}
+
+/**
+ * Resolve the correlation carry for one checkout handoff. Gates on analytics consent,
+ * then mints under the server-only secret. `readSecret` is injected (defaults to the
+ * env binding) so the mint is exercised in node with no Worker runtime. Never throws.
+ */
+export async function resolveCheckoutHandoffCorrelation(
+  input: CheckoutHandoffCorrelationInput,
+  readSecret: () => Promise<string | undefined> = () => readEnv(CORRELATION_SECRET_ENV),
+): Promise<CheckoutHandoffCorrelation> {
+  // Consent gate FIRST: a shopper who is not analytics-eligible is unattributed, and
+  // the signing secret is never even read for them.
+  if (!isPurposeEligible(input.consent, CORRELATION_CONSENT_PURPOSE)) {
+    return { attributed: false, reason: "analytics-consent-required" };
+  }
+
+  // Fail-safe: no signing key → the handoff proceeds UNATTRIBUTED. Expected wherever
+  // COMMERCE_CORRELATION_SECRET is unset (incl. preview); never a thrown error.
+  const secret = await readSecret();
+  if (!secret) return { attributed: false, reason: "secret-unavailable" };
+
+  // Consent is eligible and the secret is present, so the mint's own gate always
+  // takes the attributed branch here; the return is the token + cart field to carry.
+  return (await correlationForHandoff(
+    {
+      tenant: input.tenant,
+      environment: input.environment,
+      eventId: input.eventId,
+      ttlSeconds: input.ttlSeconds,
+      now: input.now,
+    },
+    input.consent,
+    secret,
+  )) as CheckoutHandoffCorrelation;
+}