@decocms/nextjs 7.28.2 → 8.0.0

package/src/draftMiddleware.test.ts

@@ -0,0 +1,147 @@
+import { NextRequest, NextResponse } from "next/server";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { DRAFT_COOKIE } from "./draft";
+import { applyDraft, prepareDraft, rewriteToDraftRoute } from "./draftMiddleware";
+
+beforeEach(() => {
+  // The middleware is host-gated; these tests run as the allowed host.
+  process.env.DECO_ALLOWED_PREVIEW_HOSTS = "site.example";
+});
+afterEach(() => {
+  delete process.env.DECO_ALLOWED_PREVIEW_HOSTS;
+});
+
+function request(url: string, cookie?: string): NextRequest {
+  const req = new NextRequest(new URL(url), {
+    headers: cookie ? { cookie: `${DRAFT_COOKIE}=${cookie}` } : {},
+  });
+  return req;
+}
+
+describe("prepareDraft", () => {
+  it("reads the pointer from the param", () => {
+    expect(prepareDraft(request("https://site.example/p?__draft=abc.localhost@v1")).pointer).toBe(
+      "abc.localhost@v1",
+    );
+  });
+
+  it("reads the pointer from the cookie on a plain navigation", () => {
+    expect(prepareDraft(request("https://site.example/p", "abc.localhost@v1")).pointer).toBe(
+      "abc.localhost@v1",
+    );
+  });
+
+  it("passes through when no env override is set — the page gate is authoritative", () => {
+    // The site-block hosts live in the server-components graph; middleware
+    // can't see them, so without the env kill switch it must not block.
+    delete process.env.DECO_ALLOWED_PREVIEW_HOSTS;
+    const req = request("https://anything.example/p?__draft=abc.localhost@v1");
+    expect(prepareDraft(req).pointer).toBe("abc.localhost@v1");
+  });
+
+  it("is inert on a host outside the allowlist — the production domain", () => {
+    // Same build, different Host: no cookie, no rewrite, nothing touched.
+    const req = request("https://fila.com.br/p?__draft=abc@v1");
+    process.env.DECO_ALLOWED_PREVIEW_HOSTS = "fila.vtex.app";
+    expect(prepareDraft(req)).toEqual({ pointer: null, setCookie: null, clearCookie: false });
+    expect(rewriteToDraftRoute(req, prepareDraft(req))).toBeNull();
+  });
+
+  it("ignores a client-supplied draft header — the page owns the decision", () => {
+    // There is no request-header path any more; the page reads searchParams
+    // and cookies itself, so a forged header is simply not an input.
+    const req = new NextRequest(new URL("https://site.example/p"), {
+      headers: { "x-deco-draft": "attacker.localhost@v1" },
+    });
+    expect(prepareDraft(req).pointer).toBeNull();
+  });
+});
+
+describe("applyDraft", () => {
+  it("sets a partitioned cross-site cookie when entering draft mode", () => {
+    const decision = prepareDraft(request("https://site.example/p?__draft=abc.localhost@v1"));
+    const res = applyDraft(NextResponse.next(), decision);
+
+    const setCookie = res.headers.get("set-cookie") ?? "";
+    expect(setCookie).toContain(`${DRAFT_COOKIE}=abc.localhost%40v1`);
+    // The preview iframe is cross-site, so these attributes are what make the
+    // cookie survive at all — not hardening extras.
+    expect(setCookie).toMatch(/SameSite=None/i);
+    expect(setCookie).toMatch(/Secure/i);
+    expect(setCookie).toMatch(/Partitioned/i);
+    expect(setCookie).toMatch(/HttpOnly/i);
+  });
+
+  it("marks a draft response uncacheable and unindexable", () => {
+    // With the pointer in a cookie, draft and published share a URL — a CDN
+    // keyed on URL alone would serve unpublished content to a real visitor.
+    const decision = prepareDraft(request("https://site.example/p", "abc.localhost@v1"));
+    const res = applyDraft(NextResponse.next(), decision);
+
+    expect(res.headers.get("cache-control")).toBe("no-store, private");
+    expect(res.headers.get("vary")).toBe("Cookie");
+    expect(res.headers.get("x-robots-tag")).toBe("noindex, nofollow");
+  });
+
+  it("leaves an ordinary response completely untouched", () => {
+    const decision = prepareDraft(request("https://site.example/p"));
+    const res = applyDraft(NextResponse.next(), decision);
+
+    expect(res.headers.get("cache-control")).toBeNull();
+    expect(res.headers.get("vary")).toBeNull();
+    expect(res.headers.get("x-robots-tag")).toBeNull();
+    expect(res.headers.get("set-cookie")).toBeNull();
+  });
+
+  it("clears the cookie on ?__draft=off", () => {
+    const decision = prepareDraft(
+      request("https://site.example/p?__draft=off", "abc.localhost@v1"),
+    );
+    expect(decision.clearCookie).toBe(true);
+
+    const res = applyDraft(NextResponse.next(), decision);
+    const setCookie = res.headers.get("set-cookie") ?? "";
+    // Deletion is a set with an immediate expiry.
+    expect(setCookie).toContain(DRAFT_COOKIE);
+    expect(setCookie).toMatch(/Max-Age=0|Expires=Thu, 01 Jan 1970/i);
+    // And the response is not treated as a draft render.
+    expect(res.headers.get("cache-control")).toBeNull();
+  });
+});
+
+describe("rewriteToDraftRoute", () => {
+  it("rewrites a drafted request onto the dynamic draft route", () => {
+    const req = request("https://site.example/blog/hello?__draft=abc.localhost@v1");
+    const res = rewriteToDraftRoute(req, prepareDraft(req));
+    const target = new URL(res?.headers.get("x-middleware-rewrite") ?? "");
+    expect(target.pathname).toBe("/_draft/blog/hello");
+    // The pointer must survive: the draft page reads it from searchParams.
+    expect(target.searchParams.get("__draft")).toBe("abc.localhost@v1");
+  });
+
+  it("rewrites a cookie-only navigation too", () => {
+    const req = request("https://site.example/blog/hello", "abc.localhost@v1");
+    const res = rewriteToDraftRoute(req, prepareDraft(req));
+    expect(new URL(res?.headers.get("x-middleware-rewrite") ?? "").pathname).toBe(
+      "/_draft/blog/hello",
+    );
+  });
+
+  it("leaves an ordinary request alone — ISR must not be disturbed", () => {
+    // The whole point: only drafted requests go dynamic. A shopper's request
+    // must reach the real, statically rendered route untouched.
+    const req = request("https://site.example/blog/hello");
+    expect(rewriteToDraftRoute(req, prepareDraft(req))).toBeNull();
+  });
+
+  it("never nests the prefix when middleware re-runs on the rewritten URL", () => {
+    const req = request("https://site.example/_draft/blog/hello?__draft=abc.localhost@v1");
+    expect(rewriteToDraftRoute(req, prepareDraft(req))).toBeNull();
+  });
+
+  it("does not rewrite when leaving draft mode", () => {
+    const req = request("https://site.example/blog/hello?__draft=off", "abc.localhost@v1");
+    expect(rewriteToDraftRoute(req, prepareDraft(req))).toBeNull();
+  });
+});

package/src/draftMiddleware.ts

@@ -0,0 +1,136 @@
+/**
+ * Draft preview — middleware half.
+ *
+ * Two composable calls, because sites already own their middleware and this
+ * must slot into it rather than replace it:
+ *
+ * ```ts
+ * // middleware.ts (Next <16) / proxy.ts (Next 16+)
+ * export function middleware(request: NextRequest) {
+ *   const decision = prepareDraft(request);
+ *   return applyDraft(NextResponse.next(), decision);
+ * }
+ * ```
+ *
+ * The middleware owns only the cookie and the cache/indexing headers — a
+ * Server Component can read cookies but cannot set them, so that part has to
+ * live here. The pointer itself is read by the page.
+ *
+ * Lives on its own subpath so middleware (edge runtime) never imports the root
+ * barrel, which pulls in the client component graph.
+ */
+
+import { isDraftHostAllowed } from "@decocms/blocks/cms";
+import { type NextRequest, NextResponse } from "next/server";
+import {
+  DRAFT_COOKIE,
+  DRAFT_COOKIE_OPTIONS,
+  type DraftMiddlewareDecision,
+  decideDraft,
+} from "./draft";
+
+/**
+ * Compute the draft decision for a request.
+ *
+ * Only the cookie and the response headers are the middleware's business now —
+ * the page reads the pointer itself from `searchParams` + `cookies()`, so
+ * nothing has to be forwarded through the request. That also means a draft
+ * still works on routes this middleware never matches.
+ */
+const INERT: DraftMiddlewareDecision = { pointer: null, setCookie: null, clearCookie: false };
+
+export function prepareDraft(request: NextRequest): DraftMiddlewareDecision {
+  // The AUTHORITATIVE host gate lives page-side (`ensureDraft`): the site
+  // block's `previewHosts` are installed in the server-components graph, and
+  // middleware runs in a separate module graph/runtime that never sees them.
+  // Middleware therefore hard-gates only on the env override — keeping
+  // DECO_ALLOWED_PREVIEW_HOSTS a full kill switch — and otherwise passes the
+  // decision through. Worst case on a non-preview host is a cookie the
+  // page-side gate then ignores; drafts never render there.
+  if (process.env.DECO_ALLOWED_PREVIEW_HOSTS) {
+    const host =
+      request.headers.get("x-forwarded-host") ??
+      request.headers.get("host") ??
+      request.nextUrl.host;
+    if (!isDraftHostAllowed(host)) return INERT;
+  }
+  return decideDraft(new URL(request.url), request.cookies.get(DRAFT_COOKIE)?.value ?? null);
+}
+
+/**
+ * URL prefix a drafted request is rewritten onto.
+ *
+ * The site must mount the matching route as `app/%5Fdraft/...` — URL-encoded.
+ * A literal `_draft/` directory is a Next "private folder", excluded from
+ * routing entirely, so the rewrite would fall through to whatever catch-all
+ * follows and 404. The encoded directory serves the same `/_draft` URL while
+ * staying routable.
+ */
+export const DRAFT_ROUTE_PREFIX = "/_draft";
+
+/**
+ * Rewrite a drafted request onto the dynamic draft route.
+ *
+ * This exists because `dynamic` / `revalidate` are STATIC route exports: a
+ * statically rendered page cannot become dynamic for one request. Making the
+ * real route dynamic to support drafts would cost every shopper their cached
+ * page, and — worse — a statically rendered draft would be cached and served to
+ * them. Rewriting sends only drafted requests to a route that is dynamic by
+ * construction, leaving ordinary traffic's ISR completely untouched.
+ *
+ * The original path is preserved in the rewritten pathname, so the draft route
+ * can resolve exactly the page the visitor asked for.
+ *
+ * Returns null when this request is not drafted, so callers fall through to
+ * their normal response.
+ */
+export function rewriteToDraftRoute(
+  request: NextRequest,
+  decision: DraftMiddlewareDecision,
+): NextResponse | null {
+  if (!decision.pointer) return null;
+  const url = request.nextUrl.clone();
+  // Already rewritten (Next re-runs middleware on the rewritten URL in some
+  // configurations) — never nest the prefix.
+  if (url.pathname.startsWith(`${DRAFT_ROUTE_PREFIX}/`)) return null;
+  url.pathname = `${DRAFT_ROUTE_PREFIX}${url.pathname}`;
+  return NextResponse.rewrite(url);
+}
+
+/**
+ * Apply the cookie and the cache/indexing headers a draft response requires.
+ *
+ * The caching headers are the difference between a preview and a **leak**.
+ * With the pointer in a cookie, a draft response and a published one share an
+ * identical URL, so a CDN keyed on URL alone would happily serve unpublished
+ * content to a real visitor. `no-store` is what actually prevents that;
+ * `Vary: Cookie` keeps any intermediary that *does* respect it from mixing the
+ * two; `X-Robots-Tag` keeps a leaked draft out of search results.
+ */
+export function applyDraft(
+  response: NextResponse,
+  decision: DraftMiddlewareDecision,
+): NextResponse {
+  if (decision.clearCookie) {
+    response.cookies.delete(DRAFT_COOKIE);
+  } else if (decision.setCookie) {
+    response.cookies.set(DRAFT_COOKIE, decision.setCookie, DRAFT_COOKIE_OPTIONS);
+  }
+
+  if (decision.pointer) {
+    response.headers.set("cache-control", "no-store, private");
+    response.headers.set("vary", "Cookie");
+    response.headers.set("x-robots-tag", "noindex, nofollow");
+  }
+
+  return response;
+}
+
+/**
+ * Convenience for sites with no middleware of their own: prepare, continue,
+ * apply. Sites that already have middleware should call the two halves
+ * directly so their own logic sits in between.
+ */
+export function draftMiddleware(request: NextRequest): NextResponse {
+  return applyDraft(NextResponse.next(), prepareDraft(request));
+}

package/src/index.ts

@@ -8,6 +8,31 @@ export {
 export { DecoPageRenderer } from "./DecoPageRenderer";
 export { DecoRootLayout, type DecoRootLayoutProps } from "./DecoRootLayout";
 export { DeferredSectionBoundary } from "./DeferredSection";
+export {
+  buildExitUrl,
+  buildShareUrl,
+  DraftPreviewBadge,
+  type DraftPreviewBadgeProps,
+} from "./DraftPreviewBadge";
+export { DraftPreviewIndicator } from "./DraftPreviewIndicator";
+export {
+  DRAFT_COOKIE,
+  DRAFT_COOKIE_OPTIONS,
+  DRAFT_PARAM,
+  type DraftMiddlewareDecision,
+  type DraftSearchParams,
+  decideDraft,
+  ensureDraft,
+  getActiveDraftPointer,
+  registerDraftOverride,
+  selectDraftPointer,
+} from "./draft";
+export {
+  applyDraft,
+  DRAFT_ROUTE_PREFIX,
+  prepareDraft,
+  rewriteToDraftRoute,
+} from "./draftMiddleware";
 export {
   decofileGET,
   decofilePOST,

package/src/setup.ts

@@ -38,7 +38,7 @@
  * deploys must ship the directory alongside the server bundle).
  */
 import type { ApplySectionConventionsInput } from "@decocms/blocks/cms";
-import { applySectionConventions, loadBlocks } from "@decocms/blocks/cms";
+import { applySectionConventions, loadBlocks, setDraftPreviewHosts } from "@decocms/blocks/cms";
 import { loadDecofileDirectory } from "@decocms/blocks/cms/loadDecofileDirectory";
 import { createSiteSetup, type SiteSetupOptions } from "@decocms/blocks/setup";
 
@@ -110,9 +110,29 @@ export interface NextSetupOptions {
  * instead, nothing imports the JSON, so edits invalidate nothing and dev
  * serves stale content until a full restart.
  */
+/**
+ * Install the site block's `previewHosts` as the draft-preview allowlist.
+ *
+ * Reads the BASE blocks handed to setup — never `loadBlocks()` at request
+ * time, where the draft override is merged in: an allowlist readable through
+ * the override could be rewritten by the very draft it gates.
+ * `DECO_ALLOWED_PREVIEW_HOSTS` remains an operational override that replaces
+ * this list when set.
+ */
+function installPreviewHosts(blocks: Record<string, unknown> | undefined): void {
+  const site = blocks?.site as { previewHosts?: unknown } | undefined;
+  if (Array.isArray(site?.previewHosts)) setDraftPreviewHosts(site.previewHosts);
+}
+
 export function createNextSetup(options: NextSetupOptions): () => Promise<void> {
   let setupPromise: Promise<void> | null = null;
 
+  // Draft preview opt-in from the repo: read SYNCHRONOUSLY at createNextSetup
+  // time (module evaluation), not inside the lazy ensureSetup — pages call
+  // `ensureDraft` BEFORE they resolve CMS content, so hosts installed lazily
+  // would arrive after the gate already said no on the first request.
+  installPreviewHosts(options.blocks);
+
   return function ensureSetup(): Promise<void> {
     setupPromise ??= (async () => {
       const dirBlocks =
@@ -120,6 +140,8 @@ export function createNextSetup(options: NextSetupOptions): () => Promise<void>
           ? {}
           : await loadDecofileDirectory(options.blocksDir ?? ".deco/blocks");
       const blocks = { ...dirBlocks, ...options.blocks };
+      // Covers the blocksDir mode, where blocks only exist after the fs read.
+      installPreviewHosts(blocks);
 
       createSiteSetup({
         sections: options.sections,