@decocms/blocks 7.28.0-beta.5 → 7.28.1

package/src/cms/draftSource.test.ts

@@ -1,258 +0,0 @@
-import { beforeEach, describe, expect, it } from "vitest";
-
-import {
-  clearDraftCache,
-  DEFAULT_PREVIEW_API_DOMAINS,
-  isDraftHostAllowed,
-  isDraftPreviewEnabled,
-  parseDraftPointer,
-  previewApiOriginForHost,
-  resolveDraftDecofile,
-  setDraftPreviewHosts,
-} from "./draftSource";
-
-const ENV_ON = { DECO_ALLOWED_PREVIEW_HOSTS: "preview.example" };
-
-function jsonResponse(body: unknown, init?: ResponseInit): Response {
-  return new Response(JSON.stringify(body), {
-    status: 200,
-    headers: { "content-type": "application/json" },
-    ...init,
-  });
-}
-
-beforeEach(() => {
-  clearDraftCache();
-});
-
-describe("parseDraftPointer", () => {
-  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.example@b@c")).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("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();
-  });
-});
-
-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("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("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("gating", () => {
-  it("is on iff an allowed host is configured — API domains have defaults", () => {
-    expect(isDraftPreviewEnabled(ENV_ON)).toBe(true);
-    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 exactly the token's validated origin", async () => {
-    const calls: string[] = [];
-    const blocks = await resolveDraftDecofile({
-      pointer: "abc.preview-studio.decocms.com@v1",
-      env: ENV_ON,
-      fetchImpl: (async (url: string) => {
-        calls.push(String(url));
-        return jsonResponse({ "pages-home": { title: "draft" } });
-      }) as unknown as typeof fetch,
-    });
-
-    expect(blocks).toEqual({ "pages-home": { title: "draft" } });
-    expect(calls).toEqual(["https://abc.preview-studio.decocms.com/_sandbox/decofile"]);
-  });
-
-  it("is inert without a host allowlist — no fetch at all", async () => {
-    let called = false;
-    const blocks = await resolveDraftDecofile({
-      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);
-  });
-
-  it("caches by version — one fetch per version, not per request", async () => {
-    let fetches = 0;
-    const fetchImpl = (async () => {
-      fetches++;
-      return jsonResponse({ n: fetches });
-    }) as unknown as typeof fetch;
-    const P = "abc.preview-studio.decocms.com";
-
-    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: `${P}@v2`, env: ENV_ON, fetchImpl });
-    expect(fetches).toBe(2);
-  });
-
-  it("bounds the cache so multi-MB decofiles can't accumulate", async () => {
-    let fetches = 0;
-    const fetchImpl = (async () => {
-      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: `${P}@${v}`, env: ENV_ON, fetchImpl });
-    }
-    expect(fetches).toBe(4);
-    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 unreachable / non-2xx / unparseable", async () => {
-    const P = "abc.preview-studio.decocms.com";
-    for (const fetchImpl of [
-      async () => {
-        throw new Error("ECONNREFUSED");
-      },
-      async () => new Response("nope", { status: 404 }),
-      async () =>
-        new Response("<html>not json</html>", {
-          status: 200,
-          headers: { "content-type": "text/html" },
-        }),
-    ]) {
-      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",
-    ]);
-  });
-});
-
-describe("site-block preview hosts", () => {
-  it("enables the feature from the site block alone — no env needed", () => {
-    setDraftPreviewHosts(["fila.vtex.app", "LOCALHOST:3100", 42, "  "]);
-    try {
-      expect(isDraftPreviewEnabled({})).toBe(true);
-      expect(isDraftHostAllowed("fila.vtex.app", {})).toBe(true);
-      // Sanitized: lowercased, non-strings and blanks dropped.
-      expect(isDraftHostAllowed("localhost:3100", {})).toBe(true);
-      expect(isDraftHostAllowed("evil.example", {})).toBe(false);
-    } finally {
-      setDraftPreviewHosts([]);
-    }
-  });
-
-  it("env REPLACES the block hosts when set — the operational escape hatch", () => {
-    setDraftPreviewHosts(["fila.vtex.app"]);
-    try {
-      const env = { DECO_ALLOWED_PREVIEW_HOSTS: "other.example" };
-      expect(isDraftHostAllowed("other.example", env)).toBe(true);
-      // Not merged: env is a kill switch / override, so the block value must
-      // not survive alongside it.
-      expect(isDraftHostAllowed("fila.vtex.app", env)).toBe(false);
-    } finally {
-      setDraftPreviewHosts([]);
-    }
-  });
-});

package/src/cms/draftSource.ts

@@ -1,284 +0,0 @@
-/**
- * Draft preview — pull-based decofile override.
- *
- * 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: 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 `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 `?__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 {
-  /** 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;
-}
-
-/** 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 `<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 [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 };
-}
-
-/**
- * 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().toLowerCase())
-    .filter(Boolean);
-  return configured.length > 0 ? configured : DEFAULT_PREVIEW_API_DOMAINS;
-}
-
-/**
- * Validate the token's authority against the configured domains and derive the
- * fetch origin, or null if no domain admits it.
- *
- * 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 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 declared by the site itself (the global `site` block's `previewHosts`),
- * installed once at setup time by the framework binding.
- *
- * MUST be fed from the setup-time base blocks, never from `loadBlocks()` at
- * request time: the request path merges the draft override, and an allowlist
- * readable through the override could be rewritten by the very draft it gates.
- */
-// globalThis-backed, like the block loader itself: bundlers can duplicate
-// this module across graphs, and a plain module variable set in one instance
-// is invisible to the others. (The MIDDLEWARE runtime is a separate world
-// even so — which is why the page-side gate is the authoritative one and the
-// middleware only hard-gates when the env override is present.)
-const G = globalThis as { __decoDraftHosts?: string[] };
-
-/** Install the site-declared preview hosts. Called by the framework binding at setup. */
-export function setDraftPreviewHosts(hosts: readonly unknown[]): void {
-  G.__decoDraftHosts = hosts
-    .filter((h): h is string => typeof h === "string")
-    .map((h) => h.trim().toLowerCase())
-    .filter(Boolean);
-}
-
-/**
- * Hosts allowed to render drafts.
- *
- * The site block is the expected source — the opt-in lives in the repo,
- * reviewed in a PR, versioned with branches. `DECO_ALLOWED_PREVIEW_HOSTS`
- * REPLACES it when set: an operational escape hatch (kill a bad value without
- * a deploy, add a machine-specific port) — not the primary configuration.
- */
-function readAllowedHosts(env: Record<string, string | undefined>): string[] {
-  const fromEnv = (env.DECO_ALLOWED_PREVIEW_HOSTS ?? "")
-    .split(",")
-    .map((s) => s.trim().toLowerCase())
-    .filter(Boolean);
-  return fromEnv.length > 0 ? fromEnv : (G.__decoDraftHosts ?? []);
-}
-
-/**
- * Whether `host` (as seen on the request) may render drafts.
- *
- * 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 {
-  byVersion.delete(version);
-  byVersion.set(version, blocks);
-  while (byVersion.size > MAX_CACHED_VERSIONS) {
-    const oldest = byVersion.keys().next().value;
-    if (oldest === undefined) break;
-    byVersion.delete(oldest);
-  }
-}
-
-/** Test seam — drops every cached version. */
-export function clearDraftCache(): void {
-  byVersion.clear();
-}
-
-export interface ResolveDraftOptions {
-  /** Raw `<host[:port]>@<version>` token from the request. */
-  pointer: string | null | undefined;
-  /** Defaults to `process.env`. */
-  env?: Record<string, string | undefined>;
-  /** Defaults to global `fetch`. Injected in tests. */
-  fetchImpl?: typeof fetch;
-}
-
-/**
- * Resolve a draft token to a decofile, or null to render published content.
- *
- * 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 = envOrProcess(options.env);
-  if (readAllowedHosts(env).length === 0) return null;
-
-  const parsed = parseDraftPointer(options.pointer);
-  if (!parsed) return null;
-
-  const cached = byVersion.get(parsed.version);
-  if (cached) return cached;
-
-  const origin = previewApiOriginForHost(parsed.host, env);
-  if (!origin) return null;
-
-  const doFetch = options.fetchImpl ?? fetch;
-  let res: Response;
-  try {
-    res = await doFetch(`${origin}/_sandbox/decofile`, { cache: "no-store" });
-  } catch {
-    return null;
-  }
-  if (!res.ok) return null;
-
-  let blocks: Record<string, unknown>;
-  try {
-    blocks = (await res.json()) as Record<string, unknown>;
-  } catch {
-    return null;
-  }
-
-  cacheDraft(parsed.version, blocks);
-  return blocks;
-}
-
-// ---------------------------------------------------------------------------
-// Request binding (dependency-injected by the framework binding)
-// ---------------------------------------------------------------------------
-
-type DraftOverrideGetter = () => Record<string, unknown> | null | undefined;
-
-let getDraftOverride: DraftOverrideGetter = () => undefined;
-
-/**
- * Inject the request-scoped draft getter.
- *
- * 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).
- * Never called → returns undefined → `loadBlocks()` behaves exactly as before.
- */
-export function setDraftOverrideGetter(getter: DraftOverrideGetter): void {
-  getDraftOverride = getter;
-}
-
-/** The current request's draft blocks, if a binding registered one. */
-export function getRequestDraftOverride(): Record<string, unknown> | null | undefined {
-  return getDraftOverride();
-}