@decocms/apps 1.11.1 → 1.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps",
-  "version": "1.11.1",
+  "version": "1.12.1",
   "type": "module",
   "description": "Deco commerce apps for TanStack Start - Shopify, VTEX, commerce types, analytics utils",
   "exports": {

package/vtex/client.ts

@@ -4,6 +4,7 @@
  */
 
 import { RequestContext } from "@decocms/start/sdk/requestContext";
+import { sanitizeOutboundCookieHeader, warnDroppedCookies } from "./utils/cookieSanitizer";
 import { type FetchCacheOptions, fetchWithCache } from "./utils/fetchCache";
 import { ANONYMOUS_COOKIE, SESSION_COOKIE } from "./utils/intelligentSearch";
 import { parseSegment, SEGMENT_COOKIE_NAME } from "./utils/segment";
@@ -276,14 +277,31 @@ export async function vtexCachedFetch<T>(
  * This mirrors deco-cx/deco's `proxySetCookie(response.headers, ctx.response.headers)`.
  */
 export async function vtexFetchWithCookies<T>(path: string, init?: RequestInit): Promise<T> {
-	// Auto-inject request cookies from RequestContext
+	// Auto-inject request cookies from RequestContext.
+	//
+	// We sanitize the forwarded Cookie header before sending it to VTEX:
+	// the janus gateway returns 503 (empty body) on any cookie value that
+	// isn't strict ASCII per RFC 6265. Third-party analytics tags that write
+	// raw UTF-8 into document.cookie (e.g. category names with accents) will
+	// otherwise poison every checkout call for the affected user. The drop
+	// report is emitted via warnDroppedCookies() so we have observability the
+	// next time a tag misbehaves.
 	const existingHeaders = init?.headers as Record<string, string> | undefined;
 	if (!existingHeaders?.cookie) {
 		const ctx = RequestContext.current;
-		const cookies = ctx?.request.headers.get("cookie");
-		if (cookies) {
-			init = { ...init, headers: { ...existingHeaders, cookie: cookies } };
+		const raw = ctx?.request.headers.get("cookie");
+		if (raw) {
+			const { cookies, dropped } = sanitizeOutboundCookieHeader(raw);
+			if (dropped.length) warnDroppedCookies(dropped, vtexHost());
+			if (cookies) {
+				init = { ...init, headers: { ...existingHeaders, cookie: cookies } };
+			}
 		}
+	} else {
+		// Caller passed an explicit cookie — sanitize it too.
+		const { cookies, dropped } = sanitizeOutboundCookieHeader(existingHeaders.cookie);
+		if (dropped.length) warnDroppedCookies(dropped, vtexHost());
+		init = { ...init, headers: { ...existingHeaders, cookie: cookies } };
 	}
 
 	const response = await vtexFetchResponse(path, init);

package/vtex/utils/authHelpers.ts

@@ -7,27 +7,20 @@
  * TanStack Start's Vite plugin only transforms source files.
  */
 import { getVtexConfig } from "../client";
+import { extractVtexCookies } from "./cookieSanitizer";
 
 const DOMAIN_RE = /;\s*domain=[^;]*/gi;
 
-const VTEX_COOKIE_PREFIXES = [
-	"vtex_session=",
-	"vtex_segment=",
-	"VtexIdclientAutCookie",
-	"checkout.vtex.com",
-	"CheckoutOrderFormOwnership",
-];
-
 /**
  * Extract VTEX-relevant cookies from a raw Cookie header string.
- * Filters out analytics/CF cookies that can cause VTEX 503 errors.
+ *
+ * Strict allowlist: drops any cookie not on `VTEX_COOKIE_PREFIXES`, plus
+ * any cookie whose value contains non-ASCII bytes (which would otherwise
+ * make VTEX's janus gateway return 503 Service Unavailable). Both filters
+ * live in `./cookieSanitizer` — this is a thin compatibility wrapper.
  */
 export function extractVtexCookiesFromHeader(raw: string): string {
-	return raw
-		.split(";")
-		.map((c) => c.trim())
-		.filter((c) => VTEX_COOKIE_PREFIXES.some((prefix) => c.startsWith(prefix)))
-		.join("; ");
+	return extractVtexCookies(raw);
 }
 
 /**

package/vtex/utils/cookieSanitizer.ts

@@ -0,0 +1,173 @@
+/**
+ * Outbound cookie sanitization for VTEX API calls.
+ *
+ * VTEX's janus gateway strictly enforces RFC 6265: any cookie value containing
+ * non-ASCII bytes causes the gateway to return `503 Service Unavailable` with
+ * an empty body, before the request reaches the backing service. This is
+ * deterministic — a single poisoned cookie (e.g. an analytics tag writing a
+ * category name with accents into `document.cookie` without encoding) can
+ * break every checkout call for a user.
+ *
+ * This module provides two filters:
+ *
+ * - `sanitizeOutboundCookieHeader()` — drops cookies whose value contains
+ *   non-ASCII bytes or that look malformed. Default for cookie forwarding
+ *   in `vtexFetchWithCookies`. Safe to apply to any cookie payload.
+ *
+ * - `extractVtexCookies()` — allowlist mode. Drops anything that isn't on
+ *   `VTEX_COOKIE_PREFIXES`. Use when calling endpoints that have no business
+ *   seeing the user's full cookie soup (e.g. logout, masterdata, profile).
+ *
+ * The allowlist is the canonical list of cookie name prefixes that VTEX APIs
+ * actually consume. It lives here so it's the single source of truth for the
+ * package — both `getVtexCookies()` (cookies.ts) and
+ * `extractVtexCookiesFromHeader()` (authHelpers.ts) delegate to this module.
+ */
+
+/**
+ * Cookie name prefixes that are VTEX-relevant and safe to forward to
+ * `*.vtexcommercestable.com.br` / `*.myvtex.com` / `secure.<storefront>` APIs.
+ */
+export const VTEX_COOKIE_PREFIXES: readonly string[] = [
+	"VtexIdclientAutCookie",
+	"checkout.vtex.com",
+	"CheckoutOrderFormOwnership",
+	"vtex_session",
+	"vtex_segment",
+	"vtex_is_",
+	"janus_sid",
+];
+
+export type DropReason = "non_ascii" | "not_in_allowlist" | "malformed";
+
+export interface DroppedCookie {
+	name: string;
+	reason: DropReason;
+}
+
+export interface CookieSanitizeResult {
+	/** Cookie header string ready to forward (may be empty). */
+	cookies: string;
+	/** Cookies that were filtered out, with the reason per cookie. */
+	dropped: DroppedCookie[];
+}
+
+export interface CookieSanitizeOptions {
+	/**
+	 * When true, additionally enforces an allowlist: only cookies whose name
+	 * starts with one of `VTEX_COOKIE_PREFIXES` are kept.
+	 * @default false
+	 */
+	allowlist?: boolean;
+}
+
+/**
+ * Cookie pairs are `name=value`, where `name` (token) must be visible ASCII
+ * with no separators, and `value` must be ASCII (`0x20–0x7E`) per RFC 6265.
+ * We intentionally allow `=` inside the value (some VTEX cookies are
+ * URL-encoded JWTs).
+ */
+const TOKEN_RE = /^[!#$%&'*+\-.0-9A-Z^_`a-z|~]+$/;
+const ASCII_VALUE_RE = /^[\x20-\x7E]*$/;
+
+/**
+ * Filter a `Cookie:` request header so it's safe to forward to a VTEX origin.
+ *
+ * Drops:
+ *   - pairs without `=` (malformed)
+ *   - pairs whose name isn't a valid HTTP token (malformed)
+ *   - pairs whose value contains non-ASCII bytes (`non_ascii`)
+ *   - when `opts.allowlist` is true: pairs not on `VTEX_COOKIE_PREFIXES`
+ *     (`not_in_allowlist`)
+ *
+ * Returns the cleaned header plus a per-cookie drop report so callers can
+ * log/observe which cookies were removed.
+ *
+ * @example
+ * ```ts
+ * const { cookies, dropped } = sanitizeOutboundCookieHeader(
+ *   request.headers.get("cookie") ?? "",
+ * );
+ * if (dropped.length) console.warn("[vtex] dropped cookies", dropped);
+ * fetch(vtexUrl, { headers: { cookie: cookies } });
+ * ```
+ */
+export function sanitizeOutboundCookieHeader(
+	raw: string,
+	opts: CookieSanitizeOptions = {},
+): CookieSanitizeResult {
+	if (!raw) return { cookies: "", dropped: [] };
+
+	const kept: string[] = [];
+	const dropped: DroppedCookie[] = [];
+	const allowlist = opts.allowlist === true;
+
+	for (const segment of raw.split(";")) {
+		const pair = segment.trim();
+		if (!pair) continue;
+
+		const eq = pair.indexOf("=");
+		if (eq <= 0) {
+			dropped.push({ name: pair.slice(0, 32), reason: "malformed" });
+			continue;
+		}
+
+		const name = pair.slice(0, eq);
+		const value = pair.slice(eq + 1);
+
+		if (!TOKEN_RE.test(name)) {
+			dropped.push({ name, reason: "malformed" });
+			continue;
+		}
+
+		if (!ASCII_VALUE_RE.test(value)) {
+			dropped.push({ name, reason: "non_ascii" });
+			continue;
+		}
+
+		if (allowlist && !VTEX_COOKIE_PREFIXES.some((p) => name.startsWith(p))) {
+			dropped.push({ name, reason: "not_in_allowlist" });
+			continue;
+		}
+
+		kept.push(`${name}=${value}`);
+	}
+
+	return { cookies: kept.join("; "), dropped };
+}
+
+/**
+ * Allowlist convenience wrapper — keep only VTEX-prefixed, ASCII-clean cookies.
+ *
+ * Equivalent to `sanitizeOutboundCookieHeader(raw, { allowlist: true }).cookies`.
+ */
+export function extractVtexCookies(raw: string): string {
+	return sanitizeOutboundCookieHeader(raw, { allowlist: true }).cookies;
+}
+
+/**
+ * Track which cookie names we've already warned about to avoid spamming
+ * the worker logs. Process-scoped — Cloudflare Workers reset this on each
+ * isolate restart, which is exactly the cadence we want.
+ */
+const _warned = new Set<string>();
+
+/**
+ * Emit a structured `console.warn` for each dropped cookie, deduped by
+ * `name+reason` for the lifetime of the worker isolate. Call sites pass an
+ * arbitrary `host` label so we can correlate in logs.
+ */
+export function warnDroppedCookies(dropped: DroppedCookie[], host: string): void {
+	if (dropped.length === 0) return;
+	for (const d of dropped) {
+		const key = `${host}::${d.name}::${d.reason}`;
+		if (_warned.has(key)) continue;
+		_warned.add(key);
+		console.warn(`[vtex.cookie.dropped] host=${host} name=${d.name} reason=${d.reason}`);
+	}
+}
+
+/** Reset the dedup set — exposed for tests. */
+export function _resetCookieWarnDedupForTests(): void {
+	_warned.clear();
+}

package/vtex/utils/cookies.ts

@@ -121,29 +121,22 @@ export const proxySetCookie = (from: Headers, to: Headers, toDomain?: URL | stri
 export const CHECKOUT_DATA_ACCESS_COOKIE = "CheckoutDataAccess";
 export const VTEX_CHKO_AUTH = "Vtex_CHKO_Auth";
 
-/**
- * Cookie name prefixes that are VTEX-relevant.
- * Used by getVtexCookies() to filter request cookies before forwarding
- * to VTEX APIs — avoids undici non-ASCII warnings from other cookies.
- */
-export const VTEX_COOKIE_PREFIXES = [
-	"VtexIdclientAutCookie",
-	"checkout.vtex",
-	"CheckoutOrderFormOwnership",
-	"vtex_is_",
-];
+// Re-export the canonical allowlist from cookieSanitizer so consumers that
+// previously imported it from this module keep working. The single source
+// of truth lives in cookieSanitizer.ts.
+export { VTEX_COOKIE_PREFIXES } from "./cookieSanitizer";
+
+import { extractVtexCookies } from "./cookieSanitizer";
 
 /**
  * Filter a request's cookies to only VTEX-relevant ones.
- * Prevents undici non-ASCII header warnings when forwarding cookies to VTEX APIs.
+ *
+ * Strict allowlist: drops any cookie not on `VTEX_COOKIE_PREFIXES` plus any
+ * cookie whose value contains non-ASCII bytes (which would make VTEX's
+ * janus gateway return 503).
  */
 export function getVtexCookies(request: Request): string {
-	const raw = request.headers.get("cookie") ?? "";
-	return raw
-		.split(";")
-		.map((c) => c.trim())
-		.filter((c) => VTEX_COOKIE_PREFIXES.some((p) => c.startsWith(p)))
-		.join("; ");
+	return extractVtexCookies(request.headers.get("cookie") ?? "");
 }
 
 /**

package/vtex/utils/sitemap.ts

@@ -1,9 +1,14 @@
 /**
- * VTEX Sitemap utility.
+ * VTEX Sitemap utilities.
  *
- * Fetches product and category URLs from VTEX's sitemap API
- * and converts them to SitemapEntry format for composition
- * with the CMS sitemap generator.
+ * Two flavors:
+ * - `getVtexSitemapEntries()` — flatten VTEX sub-sitemaps into a single
+ *   `SitemapEntry[]` list, for composition with the CMS sitemap generator.
+ * - `createVtexSitemapProxy()` — proxy `/sitemap.xml` and `/sitemap/*`
+ *   straight from VTEX's commerce-stable origin, preserving the sitemap-index
+ *   shape (so crawlers stay within Google's per-file size limit). This is the
+ *   right choice when the storefront has no native sitemap renderer and just
+ *   needs to expose VTEX's existing crawl tree to the public hostname.
  */
 
 import { getVtexConfig, vtexFetchResponse, vtexHost } from "../client";
@@ -131,3 +136,147 @@ function rewriteUrl(url: string, vtexSitemapHost: string, origin: string): strin
 		return url.replace(`https://${vtexSitemapHost}`, origin);
 	}
 }
+
+// ---------------------------------------------------------------------------
+// VTEX sitemap proxy factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true if `pathname` is one of the proxied sitemap paths
+ * (`/sitemap.xml` or any `/sitemap/*` sub-sitemap).
+ */
+export function isVtexSitemapPath(pathname: string): boolean {
+	return pathname === "/sitemap.xml" || pathname.startsWith("/sitemap/");
+}
+
+export interface VtexSitemapProxyConfig {
+	/**
+	 * Extra `<sitemap>` entries to inject into the root sitemap index
+	 * (`/sitemap.xml` only — sub-sitemaps are passed through untouched).
+	 *
+	 * Useful for site-managed sitemaps such as a static search-result
+	 * index (`sitemap-busca.xml`) that VTEX doesn't generate.
+	 *
+	 * Each value is normalized to an absolute URL on the storefront
+	 * origin: leading-slash paths become `${origin}${path}`, and bare
+	 * names become `${origin}/${name}`. Absolute URLs are used as-is.
+	 *
+	 * @example ["/sitemap-busca.xml"]
+	 */
+	extraSitemaps?: string[];
+
+	/**
+	 * VTEX environment for the upstream sitemap fetch.
+	 * @default "vtexcommercestable"
+	 */
+	environment?: "vtexcommercestable" | "vtexcommercebeta";
+
+	/**
+	 * `Cache-Control` header to set on proxied responses. The default
+	 * favors edge caching (Cloudflare honors `s-maxage`) with a long
+	 * stale-while-revalidate window so a slow VTEX origin never blocks
+	 * crawlers.
+	 *
+	 * @default "public, s-maxage=3600, stale-while-revalidate=86400"
+	 */
+	cacheControl?: string;
+
+	/**
+	 * Optional fetch override — primarily for tests. Defaults to the
+	 * platform `fetch`.
+	 */
+	fetchImpl?: typeof fetch;
+}
+
+const DEFAULT_SITEMAP_CACHE_CONTROL = "public, s-maxage=3600, stale-while-revalidate=86400";
+
+function normalizeExtraSitemap(entry: string, origin: string): string {
+	if (entry.startsWith("http://") || entry.startsWith("https://")) return entry;
+	const path = entry.startsWith("/") ? entry : `/${entry}`;
+	return `${origin}${path}`;
+}
+
+/**
+ * Creates a sitemap proxy handler that mirrors VTEX's `/sitemap.xml`
+ * (and sub-sitemaps) onto the storefront origin.
+ *
+ * Returns a function compatible with `createDecoWorkerEntry`'s
+ * `proxyHandler`: it returns `null` for non-sitemap paths, so it
+ * composes naturally with other proxy handlers
+ * (`createVtexCheckoutProxy`, custom logic, etc.).
+ *
+ * The VTEX account is read from the `configureVtex(...)` call done at
+ * worker startup — no per-call account configuration is needed.
+ *
+ * @example
+ * ```ts
+ * import { createVtexSitemapProxy } from "@decocms/apps/vtex/utils/sitemap";
+ * import {
+ *   createVtexCheckoutProxy,
+ *   shouldProxyToVtex,
+ * } from "@decocms/apps/vtex/utils/proxy";
+ *
+ * const proxySitemap = createVtexSitemapProxy({
+ *   extraSitemaps: ["/sitemap-busca.xml"], // optional, site-managed
+ * });
+ * const proxyCheckout = createVtexCheckoutProxy({ ... });
+ *
+ * createDecoWorkerEntry(serverEntry, {
+ *   proxyHandler: async (request, url) => {
+ *     const sitemap = await proxySitemap(request, url);
+ *     if (sitemap) return sitemap;
+ *
+ *     if (!shouldProxyToVtex(url.pathname)) return null;
+ *     return proxyCheckout(request, url);
+ *   },
+ * });
+ * ```
+ */
+export function createVtexSitemapProxy(
+	config: VtexSitemapProxyConfig = {},
+): (request: Request, url: URL) => Promise<Response | null> {
+	const environment = config.environment ?? "vtexcommercestable";
+	const cacheControl = config.cacheControl ?? DEFAULT_SITEMAP_CACHE_CONTROL;
+	const extraSitemaps = config.extraSitemaps ?? [];
+	const fetchImpl = config.fetchImpl ?? fetch;
+
+	return async (_request: Request, url: URL): Promise<Response | null> => {
+		if (!isVtexSitemapPath(url.pathname)) return null;
+
+		// vtexHost() reads the configured account from configureVtex().
+		const vtexSitemapHost = vtexHost(environment);
+		const target = `https://${vtexSitemapHost}${url.pathname}`;
+
+		try {
+			const resp = await fetchImpl(target);
+			if (!resp.ok) {
+				console.error(`[vtex-sitemap] VTEX returned ${resp.status} for ${url.pathname}`);
+				return new Response("Sitemap temporarily unavailable", { status: 502 });
+			}
+
+			let xml = await resp.text();
+			xml = xml.replaceAll(`https://${vtexSitemapHost}`, url.origin);
+
+			if (url.pathname === "/sitemap.xml" && extraSitemaps.length > 0) {
+				const extraEntries = extraSitemaps
+					.map(
+						(s) =>
+							`  <sitemap>\n    <loc>${normalizeExtraSitemap(s, url.origin)}</loc>\n  </sitemap>`,
+					)
+					.join("\n");
+				xml = xml.replace("</sitemapindex>", `${extraEntries}\n</sitemapindex>`);
+			}
+
+			return new Response(xml, {
+				status: 200,
+				headers: {
+					"Content-Type": "application/xml; charset=utf-8",
+					"Cache-Control": cacheControl,
+				},
+			});
+		} catch (err) {
+			console.error("[vtex-sitemap] Failed to proxy VTEX sitemap:", err);
+			return new Response("Sitemap temporarily unavailable", { status: 502 });
+		}
+	};
+}