@decocms/blocks 7.0.0

package/src/sdk/cookie.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+import {
+  deleteResponseCookie,
+  getCookies,
+  setResponseCookie,
+} from "./cookie";
+
+describe("getCookies", () => {
+  it("returns an empty object when no Cookie header is present", () => {
+    expect(getCookies(new Headers())).toEqual({});
+  });
+
+  it("parses a single cookie", () => {
+    const h = new Headers({ cookie: "session=abc" });
+    expect(getCookies(h)).toEqual({ session: "abc" });
+  });
+
+  it("parses multiple cookies separated by '; '", () => {
+    const h = new Headers({ cookie: "a=1; b=2; c=3" });
+    expect(getCookies(h)).toEqual({ a: "1", b: "2", c: "3" });
+  });
+
+  it("URL-decodes values", () => {
+    const h = new Headers({ cookie: "u=hello%20world" });
+    expect(getCookies(h)).toEqual({ u: "hello world" });
+  });
+
+  it("falls back to the raw value when decoding fails", () => {
+    // Lone '%' is invalid in URL encoding.
+    const h = new Headers({ cookie: "x=100%" });
+    expect(getCookies(h)).toEqual({ x: "100%" });
+  });
+
+  it("ignores entries without an '='", () => {
+    const h = new Headers({ cookie: "garbage; ok=yes" });
+    expect(getCookies(h)).toEqual({ ok: "yes" });
+  });
+
+  it("trims whitespace around names", () => {
+    const h = new Headers({ cookie: " a=1; b=2 " });
+    expect(getCookies(h)).toEqual({ a: "1", b: "2" });
+  });
+});
+
+describe("setResponseCookie", () => {
+  it("appends a Set-Cookie header with the cookie name and value", () => {
+    const h = new Headers();
+    setResponseCookie(h, { name: "session", value: "abc" });
+    expect(h.get("set-cookie")).toBe("session=abc");
+  });
+
+  it("serializes maxAge, path, secure, httpOnly, sameSite, domain", () => {
+    const h = new Headers();
+    setResponseCookie(h, {
+      name: "session",
+      value: "abc",
+      maxAge: 3600,
+      path: "/",
+      domain: "example.com",
+      secure: true,
+      httpOnly: true,
+      sameSite: "Lax",
+    });
+    const value = h.get("set-cookie")!;
+    expect(value).toContain("session=abc");
+    expect(value).toContain("Max-Age=3600");
+    expect(value).toContain("Domain=example.com");
+    expect(value).toContain("Path=/");
+    expect(value).toContain("Secure");
+    expect(value).toContain("HttpOnly");
+    expect(value).toContain("SameSite=Lax");
+  });
+
+  it("serializes expires as a UTC string", () => {
+    const h = new Headers();
+    const date = new Date("2030-01-01T00:00:00Z");
+    setResponseCookie(h, { name: "x", value: "y", expires: date });
+    expect(h.get("set-cookie")).toContain(`Expires=${date.toUTCString()}`);
+  });
+
+  it("appends multiple cookies (does not overwrite the first)", () => {
+    const h = new Headers();
+    setResponseCookie(h, { name: "a", value: "1" });
+    setResponseCookie(h, { name: "b", value: "2" });
+    // Headers.getAll isn't standard; getSetCookie() is the modern API.
+    const all = (h as any).getSetCookie?.() as string[] | undefined;
+    if (all) {
+      expect(all).toEqual(["a=1", "b=2"]);
+    } else {
+      // Fallback: the combined header value should mention both.
+      const v = h.get("set-cookie")!;
+      expect(v).toContain("a=1");
+      expect(v).toContain("b=2");
+    }
+  });
+});
+
+describe("deleteResponseCookie", () => {
+  it("emits a Set-Cookie that expires immediately", () => {
+    const h = new Headers();
+    deleteResponseCookie(h, "session", { path: "/" });
+    const value = h.get("set-cookie")!;
+    expect(value).toContain("session=");
+    expect(value).toContain("Max-Age=0");
+    expect(value).toContain(`Expires=${new Date(0).toUTCString()}`);
+    expect(value).toContain("Path=/");
+  });
+});

package/src/sdk/cookie.ts

@@ -0,0 +1,129 @@
+export function getCookie(name: string): string {
+  return (
+    globalThis.window?.document?.cookie?.split("; ").reduce((r, v) => {
+      const parts = v.split("=");
+      return parts[0] === name ? decodeURIComponent(parts[1]) : r;
+    }, "") ?? ""
+  );
+}
+
+export function setCookie(name: string, value: string, days: number) {
+  const expires = new Date(Date.now() + days * 864e5).toUTCString();
+  if (globalThis?.window?.document) {
+    globalThis.window.document.cookie =
+      name + "=" + encodeURIComponent(value) + "; expires=" + expires + "; path=/";
+  }
+}
+
+export function deleteCookie(name: string) {
+  if (globalThis?.window?.document) {
+    globalThis.window.document.cookie = name + "=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/";
+  }
+}
+
+export function getServerSideCookie(req: Request, name: string): string {
+  const cookie = req.headers
+    .get("cookie")
+    ?.split(";")
+    .find((c) => c.trim().startsWith(name))
+    ?.split("=")[1];
+  return cookie ? decodeURIComponent(cookie) : "";
+}
+
+export function decodeCookie(cookieValue: string): any {
+  try {
+    return JSON.parse(decodeURIComponent(cookieValue));
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Server-side cookie helpers — Web-platform / Workers-friendly.
+//
+// These mirror the surface area of Deno's `@std/http/cookie`, which deco
+// storefronts depended on heavily before TanStack/Workers migration. Sites
+// can now import from "@decocms/start/sdk/cookie" instead of shipping a
+// per-site shim or pulling JSR.
+// ---------------------------------------------------------------------------
+
+export interface Cookie {
+  name: string;
+  value: string;
+  expires?: Date | number;
+  maxAge?: number;
+  domain?: string;
+  path?: string;
+  secure?: boolean;
+  httpOnly?: boolean;
+  sameSite?: "Strict" | "Lax" | "None";
+}
+
+/**
+ * Parse all cookies from a Request's `Cookie` header into a plain object.
+ * Returns `{}` when no cookies are present. Values are URL-decoded.
+ *
+ * Equivalent to `getCookies(req.headers)` from `@std/http/cookie`.
+ */
+export function getCookies(headers: Headers): Record<string, string> {
+  const cookie = headers.get("cookie");
+  if (!cookie) return {};
+  const out: Record<string, string> = {};
+  for (const pair of cookie.split(/;\s*/)) {
+    const eq = pair.indexOf("=");
+    if (eq === -1) continue;
+    const name = pair.slice(0, eq).trim();
+    if (!name) continue;
+    const value = pair.slice(eq + 1).trim();
+    try {
+      out[name] = decodeURIComponent(value);
+    } catch {
+      out[name] = value;
+    }
+  }
+  return out;
+}
+
+/**
+ * Serialize a cookie spec and append a `Set-Cookie` header to a Response's
+ * `Headers`. Equivalent to `setCookie(headers, cookie)` from `@std/http/cookie`.
+ *
+ * Note: this uses `headers.append`, not `set`, so multiple cookies stack
+ * correctly (a single `Set-Cookie` header cannot represent multiple cookies).
+ */
+export function setResponseCookie(headers: Headers, cookie: Cookie): void {
+  const parts = [`${cookie.name}=${cookie.value}`];
+  if (cookie.expires !== undefined) {
+    const date = cookie.expires instanceof Date
+      ? cookie.expires
+      : new Date(cookie.expires);
+    parts.push(`Expires=${date.toUTCString()}`);
+  }
+  if (cookie.maxAge !== undefined) parts.push(`Max-Age=${cookie.maxAge}`);
+  if (cookie.domain) parts.push(`Domain=${cookie.domain}`);
+  if (cookie.path) parts.push(`Path=${cookie.path}`);
+  if (cookie.secure) parts.push("Secure");
+  if (cookie.httpOnly) parts.push("HttpOnly");
+  if (cookie.sameSite) parts.push(`SameSite=${cookie.sameSite}`);
+  headers.append("Set-Cookie", parts.join("; "));
+}
+
+/**
+ * Append a delete instruction (`Max-Age=0` + epoch `Expires`) for a cookie.
+ * `path` and `domain` should match the original `setResponseCookie` call to
+ * actually clear the cookie in the browser.
+ */
+export function deleteResponseCookie(
+  headers: Headers,
+  name: string,
+  attributes: { path?: string; domain?: string } = {},
+): void {
+  setResponseCookie(headers, {
+    name,
+    value: "",
+    expires: new Date(0),
+    maxAge: 0,
+    path: attributes.path,
+    domain: attributes.domain,
+  });
+}

package/src/sdk/crypto.ts

@@ -0,0 +1,185 @@
+/**
+ * Secret decryption for CMS encrypted values.
+ *
+ * CMS blocks store sensitive values (API keys, tokens) encrypted with AES-CBC.
+ * The encryption key is stored in the DECO_CRYPTO_KEY environment variable
+ * as a base64-encoded JSON: { key: number[], iv: number[] }
+ *
+ * Usage:
+ *   import { decryptSecret, resolveSecret } from "@decocms/start/sdk/crypto";
+ *
+ *   // Decrypt a hex-encoded encrypted string
+ *   const apiKey = await decryptSecret("888fafd937dd...");
+ *
+ *   // Or resolve a CMS secret block (handles all formats)
+ *   const apiKey = await resolveSecret(block.apiKey, "RESEND_API_KEY");
+ */
+
+const textDecoder = new TextDecoder();
+const textEncoder = new TextEncoder();
+
+// Cache the imported key
+let cachedKey: Promise<{ key: CryptoKey; iv: Uint8Array }> | null = null;
+
+function hexToBytes(hex: string): Uint8Array {
+	const bytes = new Uint8Array(hex.length / 2);
+	for (let i = 0; i < hex.length; i += 2) {
+		bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+	}
+	return bytes;
+}
+
+/**
+ * Get the AES key from DECO_CRYPTO_KEY environment variable.
+ * Returns null if not set.
+ */
+function getKeyFromEnv(): Promise<{ key: CryptoKey; iv: Uint8Array }> | null {
+	const envKey = getEnvVar("DECO_CRYPTO_KEY");
+	if (!envKey) return null;
+
+	return cachedKey ??= (async () => {
+		const parsed = JSON.parse(atob(envKey));
+		const keyBytes = new Uint8Array(
+			Array.isArray(parsed.key) ? parsed.key : Object.values(parsed.key),
+		);
+		const iv = new Uint8Array(
+			Array.isArray(parsed.iv) ? parsed.iv : Object.values(parsed.iv),
+		);
+
+		const importedKey = await crypto.subtle.importKey(
+			"raw",
+			keyBytes.buffer,
+			"AES-CBC",
+			false,
+			["decrypt"],
+		);
+
+		return { key: importedKey, iv };
+	})();
+}
+
+/**
+ * Check if the crypto key is available.
+ */
+export function hasCryptoKey(): boolean {
+	return !!getEnvVar("DECO_CRYPTO_KEY");
+}
+
+/**
+ * Decrypt a hex-encoded AES-CBC encrypted string.
+ * Requires DECO_CRYPTO_KEY environment variable.
+ *
+ * @returns The decrypted string, or null if decryption fails.
+ */
+export async function decryptSecret(encryptedHex: string): Promise<string | null> {
+	const keyPromise = getKeyFromEnv();
+	if (!keyPromise) {
+		return null;
+	}
+
+	try {
+		const { key, iv } = await keyPromise;
+		const encryptedBytes = hexToBytes(encryptedHex);
+		const decrypted = await crypto.subtle.decrypt(
+			{ name: "AES-CBC", iv } as AesCbcParams,
+			key,
+			encryptedBytes as unknown as BufferSource,
+		);
+		return textDecoder.decode(new Uint8Array(decrypted));
+	} catch (e) {
+		console.warn("[crypto] Failed to decrypt secret:", (e as Error).message);
+		return null;
+	}
+}
+
+// In-memory cache for resolved secrets
+const secretCache = new Map<string, string | null>();
+
+/**
+ * Resolve a CMS secret value from multiple sources.
+ *
+ * Resolution order:
+ * 1. Plain string → use directly
+ * 2. Object with .get() → call .get() (old Secret loader pattern)
+ * 3. Object with .encrypted → decrypt using DECO_CRYPTO_KEY
+ * 4. Environment variable (envVarName) → fallback
+ *
+ * @param value - The secret value from CMS block (string | { encrypted } | { get })
+ * @param envVarName - Optional env var name to use as fallback (e.g. "RESEND_API_KEY")
+ * @returns The resolved secret string, or null if not available
+ */
+export async function resolveSecret(
+	value: unknown,
+	envVarName?: string,
+): Promise<string | null> {
+	// 1. Plain string
+	if (typeof value === "string" && value.length > 0) {
+		return value;
+	}
+
+	if (value && typeof value === "object") {
+		const obj = value as Record<string, any>;
+
+		// 2. Secret object with .get()
+		if (typeof obj.get === "function") {
+			const result = obj.get();
+			if (typeof result === "string" && result.length > 0) return result;
+		}
+
+		// 3. Encrypted secret
+		if (typeof obj.encrypted === "string" && obj.encrypted.length > 0) {
+			const cacheKey = obj.encrypted;
+			if (secretCache.has(cacheKey)) return secretCache.get(cacheKey)!;
+
+			const decrypted = await decryptSecret(obj.encrypted);
+			// Only cache successful decryptions — null would block env var fallback
+			if (decrypted) {
+				secretCache.set(cacheKey, decrypted);
+				return decrypted;
+			}
+		}
+	}
+
+	// 4. Environment variable fallback
+	if (envVarName) {
+		const envValue = getEnvVar(envVarName);
+		if (envValue) return envValue;
+	}
+
+	return null;
+}
+
+/**
+ * Get an environment variable, checking process.env first, then .dev.vars file.
+ * Cloudflare Workers dev mode stores env vars in .dev.vars but they're only
+ * accessible via the `env` binding inside request handlers. During setup.ts
+ * (module-level init), we need to read the file directly.
+ */
+function getEnvVar(name: string): string | undefined {
+	// 1. process.env (works in Node, may work in Workers with nodejs_compat)
+	if (typeof process !== "undefined" && process.env?.[name]) {
+		return process.env[name];
+	}
+
+	// 2. Read .dev.vars file (Cloudflare Workers dev mode)
+	try {
+		const fs = require("node:fs");
+		const path = require("node:path");
+		const devVarsPath = path.resolve(".dev.vars");
+		if (fs.existsSync(devVarsPath)) {
+			const content = fs.readFileSync(devVarsPath, "utf-8");
+			for (const line of content.split("\n")) {
+				const trimmed = line.trim();
+				if (trimmed.startsWith("#") || !trimmed.includes("=")) continue;
+				const eqIdx = trimmed.indexOf("=");
+				const key = trimmed.slice(0, eqIdx).trim();
+				const val = trimmed.slice(eqIdx + 1).trim();
+				if (key === name) return val;
+			}
+		}
+	} catch {
+		// fs not available (e.g., pure Worker runtime) — ignore
+	}
+
+	return undefined;
+}

package/src/sdk/csp.ts

@@ -0,0 +1,59 @@
+/**
+ * Content Security Policy header utilities.
+ *
+ * Sets frame-ancestors to allow the Deco admin to embed the
+ * storefront in an iframe for live preview.
+ */
+
+const DEFAULT_ADMIN_ORIGINS = ["https://admin.deco.cx", "https://deco.cx", "https://localhost:*"];
+
+export interface CSPOptions {
+  /** Additional origins allowed to frame the storefront. */
+  extraOrigins?: string[];
+  /**
+   * Deco admin origins. Defaults to admin.deco.cx + localhost.
+   * Set to empty array to disallow all external framing.
+   */
+  adminOrigins?: string[];
+}
+
+/**
+ * Set Content-Security-Policy frame-ancestors header on a Response.
+ *
+ * This is required for the Deco admin live preview iframe to work.
+ * Also removes X-Frame-Options if present (CSP supersedes it).
+ *
+ * @example
+ * ```ts
+ * import { setCSPHeaders } from "@decocms/start/sdk/csp";
+ *
+ * // In middleware:
+ * const response = await next();
+ * setCSPHeaders(response);
+ * return response;
+ * ```
+ */
+export function setCSPHeaders(response: Response, options?: CSPOptions): void {
+  const origins = [
+    "'self'",
+    ...(options?.adminOrigins ?? DEFAULT_ADMIN_ORIGINS),
+    ...(options?.extraOrigins ?? []),
+  ];
+
+  response.headers.set("Content-Security-Policy", `frame-ancestors ${origins.join(" ")}`);
+
+  response.headers.delete("X-Frame-Options");
+}
+
+/**
+ * Build the CSP header value string without applying it.
+ * Useful when constructing headers in route definitions.
+ */
+export function buildCSPHeaderValue(options?: CSPOptions): string {
+  const origins = [
+    "'self'",
+    ...(options?.adminOrigins ?? DEFAULT_ADMIN_ORIGINS),
+    ...(options?.extraOrigins ?? []),
+  ];
+  return `frame-ancestors ${origins.join(" ")}`;
+}

package/src/sdk/djb2.ts

@@ -0,0 +1,20 @@
+/**
+ * DJB2 hash — a fast, non-cryptographic hash function.
+ *
+ * Used for ETags, cache keys, and content fingerprinting throughout the framework.
+ * Produces consistent unsigned 32-bit integers.
+ */
+
+/** Compute a DJB2 hash and return the raw unsigned 32-bit integer. */
+export function djb2(str: string): number {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = ((hash << 5) + hash + str.charCodeAt(i)) | 0;
+  }
+  return hash >>> 0;
+}
+
+/** Compute a DJB2 hash and return a base-36 string. */
+export function djb2Hex(str: string): string {
+  return djb2(str).toString(36);
+}

package/src/sdk/encoding.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import {
+  decodeBase64,
+  decodeBase64Url,
+  encodeBase64,
+  encodeBase64Url,
+} from "./encoding";
+
+describe("encodeBase64 / decodeBase64", () => {
+  it("round-trips ASCII strings", () => {
+    const data = "hello, world";
+    const b64 = encodeBase64(data);
+    expect(b64).toBe("aGVsbG8sIHdvcmxk");
+    const decoded = new TextDecoder().decode(decodeBase64(b64));
+    expect(decoded).toBe(data);
+  });
+
+  it("round-trips multi-byte UTF-8", () => {
+    const data = "São Paulo — café ☕";
+    const b64 = encodeBase64(data);
+    const decoded = new TextDecoder().decode(decodeBase64(b64));
+    expect(decoded).toBe(data);
+  });
+
+  it("accepts Uint8Array input", () => {
+    const bytes = new Uint8Array([1, 2, 3, 4, 5]);
+    const b64 = encodeBase64(bytes);
+    expect(decodeBase64(b64)).toEqual(bytes);
+  });
+
+  it("accepts ArrayBuffer input", () => {
+    const buf = new Uint8Array([255, 254, 253]).buffer;
+    const b64 = encodeBase64(buf);
+    expect(Array.from(decodeBase64(b64))).toEqual([255, 254, 253]);
+  });
+
+  it("handles inputs larger than the chunking window", () => {
+    // 0x8000 + 7 bytes — forces the chunking branch.
+    const bytes = new Uint8Array(0x8000 + 7);
+    for (let i = 0; i < bytes.length; i++) bytes[i] = i & 0xff;
+    const b64 = encodeBase64(bytes);
+    expect(decodeBase64(b64)).toEqual(bytes);
+  });
+});
+
+describe("encodeBase64Url / decodeBase64Url", () => {
+  it("uses URL-safe alphabet and strips padding", () => {
+    // Inputs that produce '+', '/', and padding under standard base64.
+    const bytes = new Uint8Array([251, 255, 191, 251, 239, 254]);
+    const standard = encodeBase64(bytes);
+    const url = encodeBase64Url(bytes);
+    // Every '+' becomes '-', '/' becomes '_', trailing '=' is stripped.
+    expect(url).toBe(
+      standard.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""),
+    );
+    expect(url).not.toContain("+");
+    expect(url).not.toContain("/");
+    expect(url).not.toContain("=");
+  });
+
+  it("round-trips through the URL-safe pair", () => {
+    const data = new Uint8Array(64);
+    for (let i = 0; i < data.length; i++) data[i] = (i * 7) & 0xff;
+    expect(decodeBase64Url(encodeBase64Url(data))).toEqual(data);
+  });
+
+  it("decodes inputs missing their padding", () => {
+    // 'a' = 0x61. encodeBase64('a') = 'YQ==', URL form drops to 'YQ'.
+    expect(new TextDecoder().decode(decodeBase64Url("YQ"))).toBe("a");
+  });
+});

package/src/sdk/encoding.ts

@@ -0,0 +1,47 @@
+/**
+ * Web-platform base64 / base64url helpers.
+ *
+ * Replaces the surface area of Deno's `@std/encoding/base64` so deco
+ * storefronts on TanStack/Workers can drop the per-site shim.
+ *
+ * All implementations use the global `btoa` / `atob` (available in Workers,
+ * browsers, and Node 16+) so there is zero runtime dependency.
+ */
+
+function toBytes(data: ArrayBuffer | Uint8Array | string): Uint8Array {
+  if (typeof data === "string") return new TextEncoder().encode(data);
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  return data;
+}
+
+export function encodeBase64(data: ArrayBuffer | Uint8Array | string): string {
+  const bytes = toBytes(data);
+  // Build the binary string in chunks to avoid blowing the call stack on
+  // large inputs (`String.fromCharCode(...bytes)` spreads the entire array).
+  let bin = "";
+  const CHUNK = 0x8000;
+  for (let i = 0; i < bytes.byteLength; i += CHUNK) {
+    bin += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(bin);
+}
+
+export function decodeBase64(b64: string): Uint8Array {
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+export function encodeBase64Url(data: ArrayBuffer | Uint8Array | string): string {
+  return encodeBase64(data)
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+export function decodeBase64Url(b64url: string): Uint8Array {
+  const padded = b64url.replace(/-/g, "+").replace(/_/g, "/");
+  const padLen = (4 - (padded.length % 4)) % 4;
+  return decodeBase64(padded + "=".repeat(padLen));
+}

package/src/sdk/env.ts

@@ -0,0 +1,31 @@
+/**
+ * Centralized environment detection for @decocms/start.
+ *
+ * Works in Cloudflare Workers (wrangler dev), Node, and Vite SSR.
+ * Evaluates lazily on first call so it picks up env vars set after module load.
+ */
+
+let _isDev: boolean | null = null;
+
+/**
+ * Returns `true` when running in a development environment.
+ *
+ * Detection order:
+ *  1. `import.meta.env.DEV`  — Vite build-time constant (reliable in Workers/Miniflare)
+ *  2. `NODE_ENV=development` — standard Node/Vite convention
+ *
+ * The result is memoised after the first evaluation.
+ */
+export function isDevMode(): boolean {
+  if (_isDev !== null) return _isDev;
+
+  const env = typeof globalThis.process !== "undefined" ? globalThis.process.env : undefined;
+
+  // Vite statically replaces import.meta.env.DEV at build time (true in dev, false in prod).
+  // In Miniflare/Workers, process.env is unavailable, so this is the reliable signal.
+  const vitaDev = !!(import.meta as unknown as { env?: { DEV?: boolean } }).env?.DEV;
+
+  _isDev = vitaDev || env?.NODE_ENV === "development" || env?.DECO_PREVIEW === "true";
+
+  return _isDev;
+}