@decocms/blocks 7.28.0-beta.1 → 7.28.0-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.28.0-beta.1",
+  "version": "7.28.0-beta.3",
   "type": "module",
   "engines": {
     "node": ">=24"

package/src/cms/applySectionConventions.ts

@@ -6,23 +6,20 @@
  * registerSectionsSync, setAsyncRenderingConfig, registerCacheableSections,
  * registerLayoutSections, registerSeoSections, and registerSection.
  */
-import {
-  registerSection,
-  registerSectionsSync,
-} from "./registry";
-import {
-  type CacheableSectionInput,
-  registerCacheableSections,
-  registerLayoutSections,
-} from "./sectionLoaders";
+import { registerSection, registerSectionsSync } from "./registry";
 import {
   type AsyncRenderingConfig,
+  getAsyncRenderingConfig,
   registerEagerSections,
   registerNeverDeferSections,
   registerSeoSections,
   setAsyncRenderingConfig,
-  getAsyncRenderingConfig,
 } from "./resolve";
+import {
+  type CacheableSectionInput,
+  registerCacheableSections,
+  registerLayoutSections,
+} from "./sectionLoaders";
 
 export interface SectionMetaEntry {
   eager?: boolean;
@@ -96,8 +93,7 @@ export function applySectionConventions(input: ApplySectionConventionsInput): vo
   // it, asyncConfig stays null, `useAsync` is false in resolveDecoPage, and
   // even editor-marked ⚡ sections render eagerly. (The default foldThreshold is
   // Infinity, so position-based deferral stays off unless a site opts in.)
-  const existing: Partial<AsyncRenderingConfig> =
-    getAsyncRenderingConfig() ?? {};
+  const existing: Partial<AsyncRenderingConfig> = getAsyncRenderingConfig() ?? {};
   setAsyncRenderingConfig({
     ...existing,
     alwaysEager: [...(existing.alwaysEager ?? []), ...eagerSections],

package/src/cms/blockSource.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+import { djb2Hex } from "../sdk/djb2";
 import {
   BundledBlockSource,
   computeRevision,
@@ -8,7 +9,6 @@ import {
   revisionKey,
   snapshotKey,
 } from "./blockSource";
-import { djb2Hex } from "../sdk/djb2";
 
 describe("computeRevision", () => {
   it("matches loader.ts computeRevision (djb2Hex of JSON.stringify)", () => {

package/src/cms/client.browserBundle.test.ts

@@ -1,7 +1,7 @@
-import { describe, expect, it } from "vitest";
 import { execFileSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
 
 const here = dirname(fileURLToPath(import.meta.url));
 // esbuild's JS API relies on `new TextEncoder().encode("") instanceof

package/src/cms/client.ts

@@ -49,8 +49,6 @@ export {
   registerSectionsSync,
   setResolvedComponent,
 } from "./registry";
-export type { SectionLoaderFn } from "./sectionLoaders";
-export { compose, withDevice, withMobile, withSearchParam, withSectionLoader } from "./sectionMixins";
 export type {
   ActionConfig,
   AppSchemas,
@@ -72,3 +70,11 @@ export {
   registerMatcherSchema,
   registerMatcherSchemas,
 } from "./schema";
+export type { SectionLoaderFn } from "./sectionLoaders";
+export {
+  compose,
+  withDevice,
+  withMobile,
+  withSearchParam,
+  withSectionLoader,
+} from "./sectionMixins";

package/src/cms/draftSource.test.ts

@@ -1,17 +1,16 @@
 import { beforeEach, describe, expect, it } from "vitest";
 
 import {
-  buildDraftOrigin,
   clearDraftCache,
+  DEFAULT_PREVIEW_API_DOMAINS,
+  isDraftHostAllowed,
   isDraftPreviewEnabled,
   parseDraftPointer,
+  previewApiOriginForHost,
   resolveDraftDecofile,
 } from "./draftSource";
 
-const ENV_ON = {
-  DECO_DRAFT_PREVIEW: "1",
-  DECO_SANDBOX_ORIGIN_SUFFIXES: ".preview-studio.decocms.com",
-};
+const ENV_ON = { DECO_ALLOWED_PREVIEW_HOSTS: "preview.example" };
 
 function jsonResponse(body: unknown, init?: ResponseInit): Response {
   return new Response(JSON.stringify(body), {
@@ -26,69 +25,99 @@ beforeEach(() => {
 });
 
 describe("parseDraftPointer", () => {
-  it("parses handle@version", () => {
-    expect(parseDraftPointer("gimenes-abc123@ff00")).toEqual({
-      handle: "gimenes-abc123",
-      version: "ff00",
+  it("parses authority@version, lowercasing the authority", () => {
+    expect(parseDraftPointer("ABC.Preview-Studio.decocms.com@FF00")).toEqual({
+      host: "abc.preview-studio.decocms.com",
+      version: "FF00",
+    });
+  });
+
+  it("keeps an explicit port on the authority", () => {
+    expect(parseDraftPointer("abc.localhost:60534@v1")).toEqual({
+      host: "abc.localhost:60534",
+      version: "v1",
     });
   });
 
   it("rejects more than one @", () => {
     // A naive split("@") accepts this and silently uses the first two
     // segments — the exact hole found while spiking the fetch path.
-    expect(parseDraftPointer("a@b@c")).toBeNull();
+    expect(parseDraftPointer("a.example@b@c")).toBeNull();
   });
 
-  it("rejects a handle that could escape the authority", () => {
-    expect(parseDraftPointer("evil.com/x@v1")).toBeNull();
-    expect(parseDraftPointer("user:pw@v1")).toBeNull();
-    expect(parseDraftPointer("a/../b@v1")).toBeNull();
-    expect(parseDraftPointer(".leading-dot@v1")).toBeNull();
+  it("rejects anything that could escape the authority", () => {
+    // No scheme, no path, no userinfo — the token carries an authority only,
+    // so `javascript:`/`file:`/full URLs fail structurally at parse time.
+    expect(parseDraftPointer("https://evil.example@v1")).toBeNull();
+    expect(parseDraftPointer("evil.example/x@v1")).toBeNull();
+    expect(parseDraftPointer("a.example:80:80@v1")).toBeNull();
+    expect(parseDraftPointer("a.example:abc@v1")).toBeNull();
+    expect(parseDraftPointer(".leading.dot@v1")).toBeNull();
+    expect(parseDraftPointer("bare-label@v1")).toBeNull();
   });
 
-  it("rejects empty halves and missing input", () => {
-    expect(parseDraftPointer("@v1")).toBeNull();
-    expect(parseDraftPointer("handle@")).toBeNull();
-    expect(parseDraftPointer("handle")).toBeNull();
+  it("validates the version charset — it becomes a cache key", () => {
+    expect(parseDraftPointer("a.example@")).toBeNull();
+    expect(parseDraftPointer(`a.example@${"x".repeat(65)}`)).toBeNull();
+    expect(parseDraftPointer("a.example@v 1")).toBeNull();
     expect(parseDraftPointer(null)).toBeNull();
-    expect(parseDraftPointer("")).toBeNull();
   });
 });
 
-describe("buildDraftOrigin", () => {
-  it("builds https from the configured suffix", () => {
-    expect(buildDraftOrigin("abc", [".preview-studio.decocms.com"])).toBe(
+describe("previewApiOriginForHost", () => {
+  it("admits authorities under the default deco domains", () => {
+    expect(previewApiOriginForHost("abc.preview-studio.decocms.com", {})).toBe(
       "https://abc.preview-studio.decocms.com",
     );
+    expect(previewApiOriginForHost("abc.local.studio.decocms.com", {})).toBe(
+      "https://abc.local.studio.decocms.com",
+    );
+    expect(previewApiOriginForHost("abc.localhost:60534", {})).toBe("http://abc.localhost:60534");
   });
 
-  it("uses http for a localhost suffix (local e2e)", () => {
-    expect(buildDraftOrigin("abc", [".localhost:3200"])).toBe("http://abc.localhost:3200");
+  it("rejects hosts outside the domains — the token proposes, config disposes", () => {
+    expect(previewApiOriginForHost("evil.example", {})).toBeNull();
+    // Dot-prefixed suffixes guarantee a label boundary: a lookalike domain
+    // that merely ends with the same characters cannot pass.
+    expect(previewApiOriginForHost("evil-preview-studio.decocms.com", {})).toBeNull();
+    // The domain itself (no label in front) is not a draft host.
+    expect(previewApiOriginForHost("preview-studio.decocms.com", {})).toBeNull();
   });
 
-  it("returns null with no configured suffix — never guesses an origin", () => {
-    expect(buildDraftOrigin("abc", [])).toBeNull();
+  it("allows an explicit port only under localhost-ish domains", () => {
+    // A public-domain token must not steer the fetch at odd ports.
+    expect(previewApiOriginForHost("abc.preview-studio.decocms.com:8500", {})).toBeNull();
+  });
+
+  it("honours a configured override instead of the defaults", () => {
+    const env = { DECO_PREVIEW_API_DOMAINS: ".staging.example" };
+    expect(previewApiOriginForHost("abc.staging.example", env)).toBe("https://abc.staging.example");
+    expect(previewApiOriginForHost("abc.preview-studio.decocms.com", env)).toBeNull();
   });
 });
 
-describe("isDraftPreviewEnabled", () => {
-  it("needs both the flag and a suffix", () => {
+describe("gating", () => {
+  it("is on iff an allowed host is configured — API domains have defaults", () => {
     expect(isDraftPreviewEnabled(ENV_ON)).toBe(true);
-    expect(isDraftPreviewEnabled({ DECO_DRAFT_PREVIEW: "1" })).toBe(false);
-    expect(
-      isDraftPreviewEnabled({
-        DECO_SANDBOX_ORIGIN_SUFFIXES: ".preview-studio.decocms.com",
-      }),
-    ).toBe(false);
     expect(isDraftPreviewEnabled({})).toBe(false);
   });
+
+  it("matches request hosts verbatim, port included, case-insensitively", () => {
+    const env = { DECO_ALLOWED_PREVIEW_HOSTS: "fila.vtex.app, localhost:3100" };
+    expect(isDraftHostAllowed("FILA.VTEX.APP", env)).toBe(true);
+    expect(isDraftHostAllowed("localhost:3100", env)).toBe(true);
+    expect(isDraftHostAllowed("fila.com.br", env)).toBe(false);
+    expect(isDraftHostAllowed("localhost", env)).toBe(false);
+    expect(isDraftHostAllowed(null, env)).toBe(false);
+    expect(isDraftHostAllowed("fila.vtex.app", {})).toBe(false);
+  });
 });
 
 describe("resolveDraftDecofile", () => {
-  it("fetches the sandbox decofile and returns it", async () => {
+  it("fetches exactly the token's validated origin", async () => {
     const calls: string[] = [];
     const blocks = await resolveDraftDecofile({
-      pointer: "abc@v1",
+      pointer: "abc.preview-studio.decocms.com@v1",
       env: ENV_ON,
       fetchImpl: (async (url: string) => {
         calls.push(String(url));
@@ -100,17 +129,30 @@ describe("resolveDraftDecofile", () => {
     expect(calls).toEqual(["https://abc.preview-studio.decocms.com/_sandbox/decofile"]);
   });
 
-  it("is inert unless explicitly enabled — no fetch at all", async () => {
+  it("is inert without a host allowlist — no fetch at all", async () => {
     let called = false;
     const blocks = await resolveDraftDecofile({
-      pointer: "abc@v1",
-      env: { DECO_SANDBOX_ORIGIN_SUFFIXES: ".preview-studio.decocms.com" },
+      pointer: "abc.preview-studio.decocms.com@v1",
+      env: {},
       fetchImpl: (async () => {
         called = true;
         return jsonResponse({});
       }) as unknown as typeof fetch,
     });
+    expect(blocks).toBeNull();
+    expect(called).toBe(false);
+  });
 
+  it("refuses a parseable token whose origin no domain admits — no fetch", async () => {
+    let called = false;
+    const blocks = await resolveDraftDecofile({
+      pointer: "abc.evil.example@v1",
+      env: ENV_ON,
+      fetchImpl: (async () => {
+        called = true;
+        return jsonResponse({});
+      }) as unknown as typeof fetch,
+    });
     expect(blocks).toBeNull();
     expect(called).toBe(false);
   });
@@ -121,13 +163,14 @@ describe("resolveDraftDecofile", () => {
       fetches++;
       return jsonResponse({ n: fetches });
     }) as unknown as typeof fetch;
+    const P = "abc.preview-studio.decocms.com";
 
-    const a = await resolveDraftDecofile({ pointer: "abc@v1", env: ENV_ON, fetchImpl });
-    const b = await resolveDraftDecofile({ pointer: "abc@v1", env: ENV_ON, fetchImpl });
+    const a = await resolveDraftDecofile({ pointer: `${P}@v1`, env: ENV_ON, fetchImpl });
+    const b = await resolveDraftDecofile({ pointer: `${P}@v1`, env: ENV_ON, fetchImpl });
     expect(fetches).toBe(1);
     expect(b).toBe(a);
 
-    await resolveDraftDecofile({ pointer: "abc@v2", env: ENV_ON, fetchImpl });
+    await resolveDraftDecofile({ pointer: `${P}@v2`, env: ENV_ON, fetchImpl });
     expect(fetches).toBe(2);
   });
 
@@ -137,65 +180,50 @@ describe("resolveDraftDecofile", () => {
       fetches++;
       return jsonResponse({ n: fetches });
     }) as unknown as typeof fetch;
+    const P = "abc.preview-studio.decocms.com";
 
     for (const v of ["v1", "v2", "v3", "v4"]) {
-      await resolveDraftDecofile({ pointer: `abc@${v}`, env: ENV_ON, fetchImpl });
+      await resolveDraftDecofile({ pointer: `${P}@${v}`, env: ENV_ON, fetchImpl });
     }
     expect(fetches).toBe(4);
-
-    // v1 was evicted (cap is 3), so it must re-fetch rather than serve stale.
-    await resolveDraftDecofile({ pointer: "abc@v1", env: ENV_ON, fetchImpl });
-    expect(fetches).toBe(5);
-
-    // v4 is still resident.
-    await resolveDraftDecofile({ pointer: "abc@v4", env: ENV_ON, fetchImpl });
-    expect(fetches).toBe(5);
+    await resolveDraftDecofile({ pointer: `${P}@v1`, env: ENV_ON, fetchImpl });
+    expect(fetches).toBe(5); // v1 evicted (cap 3) — re-fetch, never stale
+    await resolveDraftDecofile({ pointer: `${P}@v4`, env: ENV_ON, fetchImpl });
+    expect(fetches).toBe(5); // v4 resident
   });
 
-  it("degrades to published on a malformed pointer, without fetching", async () => {
-    let called = false;
-    const blocks = await resolveDraftDecofile({
-      pointer: "a@b@c",
-      env: ENV_ON,
-      fetchImpl: (async () => {
-        called = true;
-        return jsonResponse({});
-      }) as unknown as typeof fetch,
-    });
-    expect(blocks).toBeNull();
-    expect(called).toBe(false);
-  });
-
-  it("degrades to published on a non-2xx sandbox", async () => {
-    const blocks = await resolveDraftDecofile({
-      pointer: "abc@v1",
-      env: ENV_ON,
-      fetchImpl: (async () => new Response("nope", { status: 404 })) as unknown as typeof fetch,
-    });
-    expect(blocks).toBeNull();
-  });
-
-  it("degrades to published when the sandbox is unreachable", async () => {
-    const blocks = await resolveDraftDecofile({
-      pointer: "abc@v1",
-      env: ENV_ON,
-      fetchImpl: (async () => {
+  it("degrades to published on unreachable / non-2xx / unparseable", async () => {
+    const P = "abc.preview-studio.decocms.com";
+    for (const fetchImpl of [
+      async () => {
         throw new Error("ECONNREFUSED");
-      }) as unknown as typeof fetch,
-    });
-    expect(blocks).toBeNull();
-  });
-
-  it("degrades to published on an unparseable body", async () => {
-    const blocks = await resolveDraftDecofile({
-      pointer: "abc@v1",
-      env: ENV_ON,
-      fetchImpl: (async () =>
+      },
+      async () => new Response("nope", { status: 404 }),
+      async () =>
         new Response("<html>not json</html>", {
           status: 200,
           headers: { "content-type": "text/html" },
-        })) as unknown as typeof fetch,
-    });
-    expect(blocks).toBeNull();
+        }),
+    ]) {
+      clearDraftCache();
+      expect(
+        await resolveDraftDecofile({
+          pointer: `${P}@v1`,
+          env: ENV_ON,
+          fetchImpl: fetchImpl as unknown as typeof fetch,
+        }),
+      ).toBeNull();
+    }
+  });
+});
+
+// DEFAULT_PREVIEW_API_DOMAINS is part of the public contract — pin it.
+describe("DEFAULT_PREVIEW_API_DOMAINS", () => {
+  it("ships the deco-operated origins, dot-prefixed", () => {
+    expect(DEFAULT_PREVIEW_API_DOMAINS).toEqual([
+      ".preview-studio.decocms.com",
+      ".local.studio.decocms.com",
+      ".localhost",
+    ]);
   });
 });

package/src/cms/draftSource.ts

@@ -1,94 +1,167 @@
 /**
  * Draft preview — pull-based decofile override.
  *
- * A Studio sandbox serves the working-tree draft at
+ * A Studio preview serves the working-tree draft at
  * `GET <origin>/_sandbox/decofile`; a production site pulls it and renders its
  * own real pages against it. This replaces pushing the decofile into a POST
  * body, which only deco's own runtime honours — Next.js and most frameworks
  * render on GET only.
  *
- * This module is the framework-agnostic half: pointer parsing, origin
- * construction, fetching, and version caching. Binding a resolved draft to a
+ * This module is the framework-agnostic half: token parsing, origin
+ * validation, fetching, and version caching. Binding a resolved draft to a
  * request is framework-specific (see `@decocms/nextjs`'s draft wiring) and
  * reaches this module through {@link setDraftOverrideGetter} — the same
  * dependency-injection shape as `setFastDeployKVGetter`, so `blocks` keeps its
  * zero-dependency direction.
  *
- * Inert unless BOTH `DECO_DRAFT_PREVIEW=1` and `DECO_SANDBOX_ORIGIN_SUFFIXES`
- * are set, mirroring Fast Deploy's opt-in: upgrading the package must never be
- * enough to start fetching from the network and rendering unpublished content.
+ * Inert unless `DECO_ALLOWED_PREVIEW_HOSTS` names the request's host: upgrading
+ * the package must never be enough to start fetching from the network and
+ * rendering unpublished content. Host-scoping (rather than a boolean) exists
+ * because one deployment commonly serves several domains — the preview domain
+ * may render drafts while the production domain, on the same build, must
+ * ignore a `?__draft=` entirely.
  */
 
-/** A parsed `<handle>@<version>` draft pointer. */
+/**
+ * A parsed `?__draft=` token: `<host[:port]>@<version>`.
+ *
+ * The token carries the AUTHORITY of the draft content API, never a scheme or
+ * path — a full URL would be an SSRF vector, and the scheme is derived from
+ * the matched domain instead. Reserved evolution: a future signed token uses a
+ * distinguishable prefix (e.g. `s1.`), so this strict two-part parse rejects
+ * it cleanly rather than half-reading it.
+ */
 export interface DraftPointer {
-  /** Sandbox handle — the subdomain under a configured origin suffix. */
-  handle: string;
-  /** Content version (the daemon's ETag). Immutable, so safe to cache on. */
+  /** Content-API authority, e.g. `abc.preview-studio.decocms.com` or `abc.localhost:60534`. */
+  host: string;
+  /** Opaque content version (the server's ETag). Immutable → safe cache key. */
   version: string;
 }
 
-/**
- * Sandbox handles are `[a-z0-9-]`, always leading with an alphanumeric.
- *
- * Validated BEFORE the handle is interpolated into an authority, so it cannot
- * smuggle `/`, `@`, `:` or userinfo into the URL and redirect the fetch at some
- * other host.
- */
-const HANDLE_RE = /^[a-zA-Z0-9][a-zA-Z0-9-]*$/;
+/** Lowercase DNS hostname, at least two labels (a bare label can't match any domain). */
+const HOST_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
+const PORT_RE = /^[0-9]{1,5}$/;
+const VERSION_RE = /^[A-Za-z0-9._-]{1,64}$/;
 
 /**
- * Parse `<handle>@<version>`.
- *
- * Requires EXACTLY one `@`: a naive `split("@")` accepts `a@b@c` and silently
- * uses the first two segments, which is how a malformed pointer sneaks past
- * validation. Returns null on anything unexpected — callers fall back to
- * published content.
+ * Parse `<host[:port]>@<version>`. Null on anything unexpected — callers fall
+ * back to published content. Requires EXACTLY one `@`: a naive split accepts
+ * `a@b@c` and silently uses the first two segments.
  */
 export function parseDraftPointer(raw: string | null | undefined): DraftPointer | null {
   if (!raw) return null;
   const parts = raw.split("@");
   if (parts.length !== 2) return null;
-  const [handle, version] = parts;
-  if (!handle || !version) return null;
-  if (!HANDLE_RE.test(handle)) return null;
-  return { handle, version };
+  const [authority, version] = parts;
+  if (!authority || !version || !VERSION_RE.test(version)) return null;
+
+  const [host, port, extra] = authority.toLowerCase().split(":");
+  if (extra !== undefined) return null;
+  if (!host || !HOST_RE.test(host)) return null;
+  if (port !== undefined && !PORT_RE.test(port)) return null;
+
+  return { host: port === undefined ? host : `${host}:${port}`, version };
 }
 
-/** Configured suffixes, e.g. `.preview-studio.decocms.com,.localhost:3200`. */
-function readSuffixes(env: Record<string, string | undefined>): string[] {
-  return (env.DECO_SANDBOX_ORIGIN_SUFFIXES ?? "")
+/**
+ * Domains the draft content API may live under — deco-operated, so shipping
+ * them as defaults adds no SSRF surface. `DECO_PREVIEW_API_DOMAINS` overrides
+ * the whole list when set. Entries are dot-prefixed suffixes, which guarantees
+ * a label boundary on match (`evil-preview-studio.decocms.com` cannot pass).
+ */
+export const DEFAULT_PREVIEW_API_DOMAINS = [
+  ".preview-studio.decocms.com",
+  ".local.studio.decocms.com",
+  ".localhost",
+];
+
+function readApiDomains(env: Record<string, string | undefined>): string[] {
+  const configured = (env.DECO_PREVIEW_API_DOMAINS ?? "")
     .split(",")
-    .map((s) => s.trim())
+    .map((s) => s.trim().toLowerCase())
     .filter(Boolean);
+  return configured.length > 0 ? configured : DEFAULT_PREVIEW_API_DOMAINS;
 }
 
 /**
- * Build the sandbox origin for a handle.
+ * Validate the token's authority against the configured domains and derive the
+ * fetch origin, or null if no domain admits it.
  *
- * The origin comes from CONFIGURED suffixes, never from caller input, so there
- * is no SSRF surface to defend and no allowlist to keep correct. A `localhost`
- * suffix (local e2e) speaks http; everything else is https.
+ * The token proposes, configuration disposes: only the hostname-suffix match
+ * decides, so a caller can steer WHICH label under your domains, never which
+ * domains. Scheme is derived — http for localhost-ish domains, https
+ * otherwise — and an explicit port is allowed only there, so a public-domain
+ * token cannot aim at odd ports.
  */
-export function buildDraftOrigin(handle: string, suffixes: string[]): string | null {
-  const suffix = suffixes[0];
-  if (!suffix) return null;
-  if (!HANDLE_RE.test(handle)) return null;
-  const scheme = suffix.includes("localhost") ? "http" : "https";
-  return `${scheme}://${handle}${suffix}`;
+export function previewApiOriginForHost(
+  authority: string,
+  env?: Record<string, string | undefined>,
+): string | null {
+  const [host, port] = authority.toLowerCase().split(":");
+  if (!host) return null;
+  const domain = readApiDomains(envOrProcess(env)).find(
+    (d) => host.length > d.length && host.endsWith(d),
+  );
+  if (!domain) return null;
+  const local = domain.includes("localhost");
+  if (port !== undefined && !local) return null;
+  return `${local ? "http" : "https"}://${host}${port === undefined ? "" : `:${port}`}`;
+}
+
+/** Hosts allowed to render drafts (`DECO_ALLOWED_PREVIEW_HOSTS`, comma list). */
+function readAllowedHosts(env: Record<string, string | undefined>): string[] {
+  return (env.DECO_ALLOWED_PREVIEW_HOSTS ?? "")
+    .split(",")
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean);
 }
 
 /**
- * Version cache.
+ * Whether `host` (as seen on the request) may render drafts.
  *
- * Bounded on purpose: a decofile is routinely multi-megabyte, so an unbounded
- * map keyed by version would grow with every save until the process died.
- * Keyed by version (content-addressed), so a hit is always correct.
+ * Compared against `DECO_ALLOWED_PREVIEW_HOSTS` verbatim, port included —
+ * local dev is `localhost:3100`, not `localhost`. The header is spoofable by a
+ * direct-to-origin request, but the draft id is the actual capability;
+ * host-scoping bounds blast radius (production domains stay inert), it is not
+ * a secret.
+ */
+export function isDraftHostAllowed(
+  host: string | null | undefined,
+  env?: Record<string, string | undefined>,
+): boolean {
+  if (!host) return false;
+  return readAllowedHosts(envOrProcess(env)).includes(host.trim().toLowerCase());
+}
+
+/**
+ * True when any host is allowed to preview. A plain env read — callers use it
+ * to gate BEFORE touching dynamic APIs (`cookies()`/`headers()`), so an
+ * unconfigured site never loses static/ISR rendering. The per-request host
+ * match happens later, in `isDraftHostAllowed`.
+ */
+export function isDraftPreviewEnabled(env?: Record<string, string | undefined>): boolean {
+  return readAllowedHosts(envOrProcess(env)).length > 0;
+}
+
+function envOrProcess(
+  env?: Record<string, string | undefined>,
+): Record<string, string | undefined> {
+  return (
+    env ??
+    (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ??
+    {}
+  );
+}
+
+/**
+ * Version cache. Bounded on purpose: a decofile is routinely multi-megabyte,
+ * so an unbounded map keyed by version would grow with every save until the
+ * process died. Content-addressed, so a hit is always correct.
  */
 const MAX_CACHED_VERSIONS = 3;
 const byVersion = new Map<string, Record<string, unknown>>();
 
 function cacheDraft(version: string, blocks: Record<string, unknown>): void {
-  // Re-insert to make this the most recently used key.
   byVersion.delete(version);
   byVersion.set(version, blocks);
   while (byVersion.size > MAX_CACHED_VERSIONS) {
@@ -104,7 +177,7 @@ export function clearDraftCache(): void {
 }
 
 export interface ResolveDraftOptions {
-  /** Raw `<handle>@<version>` pointer from the request. */
+  /** Raw `<host[:port]>@<version>` token from the request. */
   pointer: string | null | undefined;
   /** Defaults to `process.env`. */
   env?: Record<string, string | undefined>;
@@ -113,23 +186,17 @@ export interface ResolveDraftOptions {
 }
 
 /**
- * Resolve a draft pointer to a decofile, or null to render published content.
+ * Resolve a draft token to a decofile, or null to render published content.
  *
- * Null on every failure path — disabled, malformed pointer, unreachable
- * sandbox, non-2xx — because a draft that cannot be resolved must degrade to
- * published rather than break the page. Callers that need to *tell the user*
- * the draft failed should check {@link isDraftPreviewEnabled} and surface it
- * themselves; silently showing published content while the user believes they
- * are looking at a draft is the failure mode worth avoiding.
+ * Null on every failure path — disabled, malformed token, disallowed origin,
+ * unreachable, non-2xx — because a draft that cannot be resolved must degrade
+ * to published rather than break the page.
  */
 export async function resolveDraftDecofile(
   options: ResolveDraftOptions,
 ): Promise<Record<string, unknown> | null> {
-  const env =
-    options.env ??
-    (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ??
-    {};
-  if (env.DECO_DRAFT_PREVIEW !== "1") return null;
+  const env = envOrProcess(options.env);
+  if (readAllowedHosts(env).length === 0) return null;
 
   const parsed = parseDraftPointer(options.pointer);
   if (!parsed) return null;
@@ -137,7 +204,7 @@ export async function resolveDraftDecofile(
   const cached = byVersion.get(parsed.version);
   if (cached) return cached;
 
-  const origin = buildDraftOrigin(parsed.handle, readSuffixes(env));
+  const origin = previewApiOriginForHost(parsed.host, env);
   if (!origin) return null;
 
   const doFetch = options.fetchImpl ?? fetch;
@@ -160,15 +227,6 @@ export async function resolveDraftDecofile(
   return blocks;
 }
 
-/** True when the feature is switched on and configured. Inert otherwise. */
-export function isDraftPreviewEnabled(env?: Record<string, string | undefined>): boolean {
-  const e =
-    env ??
-    (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ??
-    {};
-  return e.DECO_DRAFT_PREVIEW === "1" && readSuffixes(e).length > 0;
-}
-
 // ---------------------------------------------------------------------------
 // Request binding (dependency-injected by the framework binding)
 // ---------------------------------------------------------------------------
@@ -182,10 +240,8 @@ let getDraftOverride: DraftOverrideGetter = () => undefined;
  *
  * Binding a value to "the current request" is framework-specific and `blocks`
  * must not know about any framework: `@decocms/nextjs` backs this with React
- * `cache()` (App Router has no AsyncLocalStorage request scope of its own —
- * `RequestContext.run` is never entered there). Bindings that do have an ALS
- * request scope can back it with that instead. Never called → returns
- * undefined → `loadBlocks()` behaves exactly as before.
+ * `cache()` (App Router has no AsyncLocalStorage request scope of its own).
+ * Never called → returns undefined → `loadBlocks()` behaves exactly as before.
  */
 export function setDraftOverrideGetter(getter: DraftOverrideGetter): void {
   getDraftOverride = getter;

package/src/cms/index.ts

@@ -14,11 +14,13 @@ export {
 } from "./blockSource";
 export type { DraftPointer, ResolveDraftOptions } from "./draftSource";
 export {
-  buildDraftOrigin,
   clearDraftCache,
+  DEFAULT_PREVIEW_API_DOMAINS,
   getRequestDraftOverride,
+  isDraftHostAllowed,
   isDraftPreviewEnabled,
   parseDraftPointer,
+  previewApiOriginForHost,
   resolveDraftDecofile,
   setDraftOverrideGetter,
 } from "./draftSource";

package/src/cms/loader.test.ts

@@ -82,12 +82,12 @@ describe("matchPath", () => {
     });
 
     it("matches with an optional prefix before a literal segment", () => {
-      expect(
-        matchPath("/{granado/}?campanhas/*", "/granado/campanhas/destaques-2023"),
-      ).toEqual({ "0": "destaques-2023" });
-      expect(
-        matchPath("/{granado/}?campanhas/*", "/campanhas/destaques-2023"),
-      ).toEqual({ "0": "destaques-2023" });
+      expect(matchPath("/{granado/}?campanhas/*", "/granado/campanhas/destaques-2023")).toEqual({
+        "0": "destaques-2023",
+      });
+      expect(matchPath("/{granado/}?campanhas/*", "/campanhas/destaques-2023")).toEqual({
+        "0": "destaques-2023",
+      });
     });
 
     it("matches an optional suffix group present and absent", () => {
@@ -112,9 +112,7 @@ describe("matchPath", () => {
       // biome-ignore lint/performance/noDelete: restoring exact global state
       delete g.URLPattern;
       try {
-        expect(() => matchPath("/foo/:slug", "/foo/bar")).toThrow(
-          /URLPattern.*Node\.js >= 24/s,
-        );
+        expect(() => matchPath("/foo/:slug", "/foo/bar")).toThrow(/URLPattern.*Node\.js >= 24/s);
       } finally {
         if (saved !== undefined) g.URLPattern = saved;
       }

package/src/cms/registry.test.ts

@@ -1,11 +1,11 @@
-import { describe, expect, it, beforeEach } from "vitest";
+import { beforeEach, describe, expect, it } from "vitest";
 import {
-  registerSection,
-  registerSectionsSync,
+  getResolvedComponent,
   getSection,
   getSectionOptions,
   getSyncComponent,
-  getResolvedComponent,
+  registerSection,
+  registerSectionsSync,
 } from "./registry";
 
 // Reset globalThis.__deco between tests to avoid cross-test pollution
@@ -34,44 +34,36 @@ describe("registerSection + getSection", () => {
 describe("registerSection with options", () => {
   it("stores loadingFallback in section options", () => {
     const fallback = () => null;
-    registerSection(
-      "site/sections/Shelf.tsx",
-      async () => ({ default: () => null }),
-      { loadingFallback: fallback },
-    );
+    registerSection("site/sections/Shelf.tsx", async () => ({ default: () => null }), {
+      loadingFallback: fallback,
+    });
 
     const opts = getSectionOptions("site/sections/Shelf.tsx");
     expect(opts?.loadingFallback).toBe(fallback);
   });
 
   it("stores clientOnly flag in section options", () => {
-    registerSection(
-      "site/sections/Analytics.tsx",
-      async () => ({ default: () => null }),
-      { clientOnly: true },
-    );
+    registerSection("site/sections/Analytics.tsx", async () => ({ default: () => null }), {
+      clientOnly: true,
+    });
 
     const opts = getSectionOptions("site/sections/Analytics.tsx");
     expect(opts?.clientOnly).toBe(true);
   });
 
   it("clientOnly defaults to undefined when not set", () => {
-    registerSection(
-      "site/sections/Normal.tsx",
-      async () => ({ default: () => null }),
-      { loadingFallback: () => null },
-    );
+    registerSection("site/sections/Normal.tsx", async () => ({ default: () => null }), {
+      loadingFallback: () => null,
+    });
 
     const opts = getSectionOptions("site/sections/Normal.tsx");
     expect(opts?.clientOnly).toBeUndefined();
   });
 
   it("clientOnly false is preserved", () => {
-    registerSection(
-      "site/sections/Explicit.tsx",
-      async () => ({ default: () => null }),
-      { clientOnly: false },
-    );
+    registerSection("site/sections/Explicit.tsx", async () => ({ default: () => null }), {
+      clientOnly: false,
+    });
 
     const opts = getSectionOptions("site/sections/Explicit.tsx");
     expect(opts?.clientOnly).toBe(false);

package/src/cms/registry.ts

@@ -1,8 +1,6 @@
 import type { ComponentType } from "react";
 
-export type OnBeforeResolveProps = (
-  props: Record<string, unknown>,
-) => Record<string, unknown>;
+export type OnBeforeResolveProps = (props: Record<string, unknown>) => Record<string, unknown>;
 
 export type SectionModule = {
   default: ComponentType<any>;
@@ -35,8 +33,7 @@ if (!G.__deco.sectionRegistry) G.__deco.sectionRegistry = {};
 if (!G.__deco.sectionOptions) G.__deco.sectionOptions = {};
 if (!G.__deco.resolvedComponents) G.__deco.resolvedComponents = {};
 if (!G.__deco.syncComponents) G.__deco.syncComponents = {};
-if (!G.__deco.onBeforeResolvePropsRegistry)
-  G.__deco.onBeforeResolvePropsRegistry = {};
+if (!G.__deco.onBeforeResolvePropsRegistry) G.__deco.onBeforeResolvePropsRegistry = {};
 
 const registry: Record<string, RegistryEntry> = G.__deco.sectionRegistry;
 const sectionOptions: Record<string, SectionOptions> = G.__deco.sectionOptions;
@@ -194,9 +191,7 @@ export function registerSectionsSync(sections: Record<string, SyncSectionEntry>)
     ];
     const component =
       typeof raw === "function" ||
-      (raw != null &&
-        typeof raw === "object" &&
-        REACT_WRAPPERS.includes((raw as any).$$typeof))
+      (raw != null && typeof raw === "object" && REACT_WRAPPERS.includes((raw as any).$$typeof))
         ? raw
         : undefined;
     if (!component) {
@@ -229,17 +224,12 @@ export function getSyncComponent(key: string): ComponentType<any> | undefined {
  * BEFORE the resolution engine resolves them. Use to extract metadata from
  * resolvable structures that would be lost after resolution.
  */
-export function registerOnBeforeResolveProps(
-  sectionKey: string,
-  fn: OnBeforeResolveProps,
-): void {
+export function registerOnBeforeResolveProps(sectionKey: string, fn: OnBeforeResolveProps): void {
   onBeforeResolvePropsRegistry[sectionKey] = fn;
 }
 
 /** Get the registered onBeforeResolveProps for a section, if any. */
-export function getOnBeforeResolveProps(
-  sectionKey: string,
-): OnBeforeResolveProps | undefined {
+export function getOnBeforeResolveProps(sectionKey: string): OnBeforeResolveProps | undefined {
   return onBeforeResolvePropsRegistry[sectionKey];
 }
 

package/src/cms/resolve.test.ts

@@ -20,6 +20,10 @@ vi.mock("./registry", () => ({
   getOnBeforeResolveProps: vi.fn(),
 }));
 
+import { normalizeUrlsInObject } from "../sdk/normalizeUrls";
+import { findPageByPath } from "./loader";
+import { getSection } from "./registry";
+import type { AsyncRenderingConfig, DeferredSection } from "./resolve";
 import {
   clearCommerceLoaders,
   DEFAULT_FOLD_THRESHOLD,
@@ -29,8 +33,8 @@ import {
   registerCommerceLoader,
   registerEagerSections,
   registerNeverDeferSections,
-  resolveDeferredSectionFull,
   resolveDecoPage,
+  resolveDeferredSectionFull,
   resolvePageSeoBlock,
   resolveSectionsList,
   resolveValue,
@@ -39,10 +43,6 @@ import {
   WELL_KNOWN_TYPES,
 } from "./resolve";
 import { runSingleSectionLoader } from "./sectionLoaders";
-import { normalizeUrlsInObject } from "../sdk/normalizeUrls";
-import { findPageByPath } from "./loader";
-import { getSection } from "./registry";
-import type { AsyncRenderingConfig, DeferredSection } from "./resolve";
 
 describe("resolveDeferredSectionFull", () => {
   it("resolves a deferred section and preserves index", async () => {
@@ -217,14 +217,10 @@ describe("commerce loader auto-injects URL search params as props", () => {
       return null;
     });
 
-    await resolveValue(
-      { __resolveType: KEY, slug: "sabonete" },
-      undefined,
-      {
-        url: "https://store.com/produto/sabonete/p?skuId=12345&size=M",
-        path: "/produto/sabonete/p",
-      },
-    );
+    await resolveValue({ __resolveType: KEY, slug: "sabonete" }, undefined, {
+      url: "https://store.com/produto/sabonete/p?skuId=12345&size=M",
+      path: "/produto/sabonete/p",
+    });
 
     expect(calls).toHaveLength(1);
     expect(calls[0]).toMatchObject({
@@ -243,11 +239,10 @@ describe("commerce loader auto-injects URL search params as props", () => {
       return null;
     });
 
-    await resolveValue(
-      { __resolveType: KEY, skuId: "cms-locked-sku" },
-      undefined,
-      { url: "https://store.com/p?skuId=url-value", path: "/p" },
-    );
+    await resolveValue({ __resolveType: KEY, skuId: "cms-locked-sku" }, undefined, {
+      url: "https://store.com/p?skuId=url-value",
+      path: "/p",
+    });
 
     expect(calls[0]?.skuId).toBe("cms-locked-sku");
   });
@@ -358,7 +353,10 @@ describe("commerce loader resolves legacy .ts-suffixed resolveType", () => {
     await resolveValue(
       { __resolveType: "shopify/loaders/ProductDetailsPage.ts", slug: "oversize-t-shirt-123" },
       undefined,
-      { url: "https://store.com/products/oversize-t-shirt-123", path: "/products/oversize-t-shirt-123" },
+      {
+        url: "https://store.com/products/oversize-t-shirt-123",
+        path: "/products/oversize-t-shirt-123",
+      },
     );
 
     expect(calls).toHaveLength(1);
@@ -509,9 +507,9 @@ describe("isEagerRequest — programmatic fetch detection", () => {
   });
 
   it("falls back to matcherCtx.headers when no Request is present", () => {
-    expect(
-      isEagerRequest({ userAgent: HUMAN_UA, headers: { "sec-fetch-dest": "empty" } }),
-    ).toBe(true);
+    expect(isEagerRequest({ userAgent: HUMAN_UA, headers: { "sec-fetch-dest": "empty" } })).toBe(
+      true,
+    );
   });
 
   it("a request with no Sec-Fetch headers stays deferred (no UA bot, no override)", () => {

package/src/cms/resolve.ts

@@ -1,10 +1,3 @@
-import {
-  type ActionConfig,
-  inferLoaderTags,
-  type LoaderConfig,
-  registerActionSchemas,
-  registerLoaderSchemas,
-} from "./schema";
 import { getMatchersOverride, getRuleOverrideId, hasMatchersOverride } from "../matchers/override";
 import { getMeter, MetricNames, withTracing } from "../middleware/observability";
 import { djb2Hex } from "../sdk/djb2";
@@ -13,6 +6,13 @@ import { withInflightTimeout } from "../sdk/inflightTimeout";
 import { normalizeUrlsInObject } from "../sdk/normalizeUrls";
 import { findPageByPath, loadBlocks } from "./loader";
 import { getOnBeforeResolveProps, getSection, registerOnBeforeResolveProps } from "./registry";
+import {
+  type ActionConfig,
+  inferLoaderTags,
+  type LoaderConfig,
+  registerActionSchemas,
+  registerLoaderSchemas,
+} from "./schema";
 import { isLayoutSection, markSectionDegraded, runSingleSectionLoader } from "./sectionLoaders";
 
 // globalThis-backed: share state across Vite server function split modules
@@ -227,7 +227,7 @@ function isEagerSection(key: string): boolean {
  * during hydration (search filters, configurators, etc.).
  */
 export function registerNeverDeferSections(keys: string[]): void {
-  const set: Set<string> = G.__deco.neverDeferSectionKeys ??= new Set();
+  const set: Set<string> = (G.__deco.neverDeferSectionKeys ??= new Set());
   for (const k of keys) set.add(k);
 }
 
@@ -342,8 +342,7 @@ function hasForceEagerParam(ctx?: MatcherContext): boolean {
  */
 function isProgrammaticFetch(ctx?: MatcherContext): boolean {
   if (ctx?.isClientNavigation) return false;
-  const dest = ctx?.request?.headers.get("sec-fetch-dest") ??
-    ctx?.headers?.["sec-fetch-dest"];
+  const dest = ctx?.request?.headers.get("sec-fetch-dest") ?? ctx?.headers?.["sec-fetch-dest"];
   return dest === "empty";
 }
 
@@ -354,8 +353,7 @@ function isProgrammaticFetch(ctx?: MatcherContext): boolean {
  * to gate both section deferral and page-SEO commerce resolution.
  */
 export function isEagerRequest(ctx?: MatcherContext): boolean {
-  return isBot(ctx?.userAgent) || hasForceEagerParam(ctx) ||
-    isProgrammaticFetch(ctx);
+  return isBot(ctx?.userAgent) || hasForceEagerParam(ctx) || isProgrammaticFetch(ctx);
 }
 
 /**
@@ -735,7 +733,9 @@ function evaluateVariantRule(
   const already = ctx.flags?.find((f) => f.name === meta.name && f.pct === meta.pct);
   if (already) return already.value;
 
-  const stored = parseSegmentCookie(ctx.cookies?.[SEGMENT_COOKIE]).find((f) => f.name === meta.name);
+  const stored = parseSegmentCookie(ctx.cookies?.[SEGMENT_COOKIE]).find(
+    (f) => f.name === meta.name,
+  );
   // pct === -1 marks a classic-deco segment without a fingerprint — honor it
   // (stay sticky) instead of re-rolling. A stale fingerprint re-rolls.
   const useStored = stored && (stored.pct === -1 || stored.pct === meta.pct);
@@ -1264,9 +1264,7 @@ function resolvesToCommerceLoader(value: unknown, depth = 0): boolean {
  * serialized into the HTML. Lightweight literal props (title, description,
  * canonical, …) are preserved.
  */
-function stripCommerceLoaderProps(
-  rawProps: Record<string, unknown>,
-): Record<string, unknown> {
+function stripCommerceLoaderProps(rawProps: Record<string, unknown>): Record<string, unknown> {
   const out: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(rawProps)) {
     if (resolvesToCommerceLoader(v)) continue;
@@ -1785,8 +1783,7 @@ function deriveCommerceSeoFromJsonLD(seo: PageSeo, props: Record<string, unknown
   const configJsonLD = props.configJsonLD as
     | { ignoreStructuredData?: boolean; removeVideos?: boolean }
     | undefined;
-  const ignore =
-    props.ignoreStructuredData === true || configJsonLD?.ignoreStructuredData === true;
+  const ignore = props.ignoreStructuredData === true || configJsonLD?.ignoreStructuredData === true;
   if (ignore || isEmpty) return;
 
   seo.jsonLDs = [

package/src/cms/schema.ts

@@ -1089,10 +1089,7 @@ export interface ComposeMetaOptions {
   framework?: string;
 }
 
-export function composeMeta(
-  siteMeta: MetaResponse,
-  options?: ComposeMetaOptions,
-): MetaResponse {
+export function composeMeta(siteMeta: MetaResponse, options?: ComposeMetaOptions): MetaResponse {
   // Idempotency guard. composeMeta is NOT structurally idempotent — it appends
   // the framework section refs to `root.sections.anyOf` (and `__SECTION_REF__`),
   // so composing an already-composed meta a second time duplicates those refs.

package/src/cms/sectionMixins.test.ts

@@ -17,8 +17,7 @@ import {
 // request must opt in by setting this flag — and `compose` must propagate
 // it whenever any input has it.
 const isRequestDependent = (fn: unknown): boolean =>
-  typeof fn === "function" &&
-  (fn as { __requestDependent?: boolean }).__requestDependent === true;
+  typeof fn === "function" && (fn as { __requestDependent?: boolean }).__requestDependent === true;
 
 const makeReq = (url = "https://store.example/foo?q=hello") =>
   new Request(url, { headers: { "user-agent": "vitest" } });
@@ -87,12 +86,10 @@ describe("withSectionLoader", () => {
 
   it("composes alongside mixins: mixins run first, then the section loader sees the enriched props", async () => {
     const seen: Array<Record<string, unknown>> = [];
-    const sectionLoader = vi.fn(
-      async (props: Record<string, unknown>) => {
-        seen.push({ ...props });
-        return { ...props, sectionLoaderRan: true };
-      },
-    );
+    const sectionLoader = vi.fn(async (props: Record<string, unknown>) => {
+      seen.push({ ...props });
+      return { ...props, sectionLoaderRan: true };
+    });
 
     const composed = compose(
       withSearchParam(),
@@ -154,7 +151,14 @@ describe("request-dependent tagging (#206)", () => {
   });
 
   it("compose does NOT set the flag when no input is request-dependent", () => {
-    expect(isRequestDependent(compose(async (p) => p, async (p) => p))).toBe(false);
+    expect(
+      isRequestDependent(
+        compose(
+          async (p) => p,
+          async (p) => p,
+        ),
+      ),
+    ).toBe(false);
   });
 
   it("empty compose() is not request-dependent", () => {

package/src/cms/sectionMixins.ts

@@ -135,9 +135,7 @@ export function compose(...mixins: SectionLoaderFn[]): SectionLoaderFn {
  * });
  * ```
  */
-export function withSectionLoader(
-  modImport: () => Promise<unknown>,
-): SectionLoaderFn {
+export function withSectionLoader(modImport: () => Promise<unknown>): SectionLoaderFn {
   return async (props, req, ctx) => {
     const mod = (await modImport()) as { loader?: unknown } | undefined;
     const loader = mod?.loader;