From f9c02ed23b2e9939160f8e8ed768396b5aefa197 Mon Sep 17 00:00:00 2001
From: gimenes <tlgimenes@gmail.com>
Date: Thu, 8 Oct 2026 14:57:03 -0300
Subject: [PATCH] feat(hosted): delivery bucket settings, store and CDN purge

Adds the hosted delivery bucket settings (R2/S3), `deliveryStore` (read/write release objects with ETag handling) and `deliveryPurge` (CDN purge with one retry), plus shared test helpers. Nothing calls them yet; the routes land in #10/#11. A temporary knip `ignoreIssues` entry for `apps/api/src/hosted/*.ts` (unused exports only) is removed in PR 11 of this track.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNwbSEePYNcY5YCgqZURig
---
 apps/api/src/file-storage/upload-policy.ts |   2 +-
 apps/api/src/hosted/delivery-purge.test.ts | 169 +++++++++++++++
 apps/api/src/hosted/delivery-purge.ts      |  98 +++++++++
 apps/api/src/hosted/delivery-store.test.ts |  61 ++++++
 apps/api/src/hosted/delivery-store.ts      | 219 +++++++++++++++++++
 apps/api/src/hosted/hosted-test-helpers.ts | 234 +++++++++++++++++++++
 apps/api/src/settings/resolve-config.ts    |  15 +-
 apps/api/src/settings/types.ts             |  20 ++
 knip.jsonc                                 |   4 +-
 9 files changed, 819 insertions(+), 3 deletions(-)
 create mode 100644 apps/api/src/hosted/delivery-purge.test.ts
 create mode 100644 apps/api/src/hosted/delivery-purge.ts
 create mode 100644 apps/api/src/hosted/delivery-store.test.ts
 create mode 100644 apps/api/src/hosted/delivery-store.ts
 create mode 100644 apps/api/src/hosted/hosted-test-helpers.ts

diff --git a/apps/api/src/file-storage/upload-policy.ts b/apps/api/src/file-storage/upload-policy.ts
index 14aa4195c4..05678d0664 100644
--- a/apps/api/src/file-storage/upload-policy.ts
+++ b/apps/api/src/file-storage/upload-policy.ts
@@ -33,7 +33,7 @@ export const MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
  *     browsers do NOT execute scripts when SVG is loaded as a pure image.
  *   - Top-level navigation, `<object>`, `<iframe>` (e.g. opening the
  *     asset URL in a new tab) DOES execute scripts, but in the CDN
- *     origin (e.g. `decoims.com`), not the app's. As long as the CDN
+ *     origin (e.g. `assets.decocms.com`), not the app's. As long as the CDN
  *     domain doesn't share cookies/auth with the app, the blast radius
  *     is limited to "the SVG can phone home as the visitor."
  * If you ever serve assets from the same eTLD+1 as the app, remove SVG
diff --git a/apps/api/src/hosted/delivery-purge.test.ts b/apps/api/src/hosted/delivery-purge.test.ts
new file mode 100644
index 0000000000..2ea228ed0e
--- /dev/null
+++ b/apps/api/src/hosted/delivery-purge.test.ts
@@ -0,0 +1,169 @@
+import { describe, expect, it } from "bun:test";
+import { createDeliveryPurge } from "./delivery-purge";
+import { CACHE_LATEST, CACHE_REVISION, CACHE_DRAFT } from "./delivery-store";
+
+const KEY = "sites/acme/latest.json";
+
+function fakeFetch(responses: Array<{ status: number; success: boolean }>) {
+  const calls: Array<{ url: string; init: RequestInit }> = [];
+  const fn = (async (url: string, init: RequestInit) => {
+    calls.push({ url, init });
+    const r = responses[Math.min(calls.length - 1, responses.length - 1)]!;
+    return new Response(JSON.stringify({ success: r.success }), {
+      status: r.status,
+    });
+  }) as unknown as typeof fetch;
+  return { fn, calls };
+}
+
+describe("cache headers", () => {
+  it("lets the edge hold latest.json 1 h while every reader revalidates", () => {
+    expect(CACHE_LATEST).toBe(
+      "public, max-age=0, s-maxage=3600, must-revalidate",
+    );
+    expect(CACHE_REVISION).toBe("public, max-age=31536000, immutable");
+    expect(CACHE_DRAFT).toBe("no-cache, max-age=0, must-revalidate");
+  });
+});
+
+describe("createDeliveryPurge", () => {
+  it("purges exactly the object's public URL on the zone", async () => {
+    const f = fakeFetch([{ status: 200, success: true }]);
+    await createDeliveryPurge({
+      zoneId: "zone1",
+      apiToken: "tok",
+      fetch: f.fn,
+    }).purge(KEY);
+    expect(f.calls).toHaveLength(1);
+    expect(f.calls[0]!.url).toBe(
+      "https://api.cloudflare.com/client/v4/zones/zone1/purge_cache",
+    );
+    expect(f.calls[0]!.init.method).toBe("POST");
+    expect(
+      (f.calls[0]!.init.headers as Record<string, string>).authorization,
+    ).toBe("Bearer tok");
+    expect(JSON.parse(f.calls[0]!.init.body as string)).toEqual({
+      files: ["https://delivery.decocms.com/sites/acme/latest.json"],
+    });
+  });
+
+  it("uses the configured public delivery origin", async () => {
+    const f = fakeFetch([{ status: 200, success: true }]);
+    await createDeliveryPurge({
+      zoneId: "zone1",
+      apiToken: "tok",
+      publicOrigin: "http://localhost:9999/",
+      fetch: f.fn,
+    }).purge(KEY);
+    expect(JSON.parse(f.calls[0]!.init.body as string)).toEqual({
+      files: ["http://localhost:9999/sites/acme/latest.json"],
+    });
+  });
+
+  it("retries a failed attempt once and succeeds when the retry does", async () => {
+    const f = fakeFetch([
+      { status: 503, success: false },
+      { status: 200, success: true },
+    ]);
+    await createDeliveryPurge({
+      zoneId: "z",
+      apiToken: "t",
+      fetch: f.fn,
+    }).purge(KEY);
+    expect(f.calls).toHaveLength(2);
+  });
+
+  it("fails when both attempts fail: exactly two calls", async () => {
+    const f = fakeFetch([
+      { status: 503, success: false },
+      { status: 502, success: false },
+      { status: 200, success: true },
+    ]);
+    await expect(
+      createDeliveryPurge({ zoneId: "z", apiToken: "t", fetch: f.fn }).purge(
+        KEY,
+      ),
+    ).rejects.toThrow("HTTP 502");
+    expect(f.calls).toHaveLength(2);
+  });
+
+  it("fails when Cloudflare answers 200 without success (twice)", async () => {
+    const f = fakeFetch([{ status: 200, success: false }]);
+    await expect(
+      createDeliveryPurge({ zoneId: "z", apiToken: "t", fetch: f.fn }).purge(
+        KEY,
+      ),
+    ).rejects.toThrow("HTTP 200");
+    expect(f.calls).toHaveLength(2);
+  });
+
+  it("counts a timed-out attempt as failed and retries it once", async () => {
+    let calls = 0;
+    const hangOnce = ((_url: string, init: RequestInit) => {
+      calls++;
+      if (calls > 1) {
+        return Promise.resolve(
+          new Response(JSON.stringify({ success: true }), { status: 200 }),
+        );
+      }
+      return new Promise<Response>((_resolve, reject) => {
+        init.signal?.addEventListener("abort", () =>
+          reject(init.signal?.reason),
+        );
+      });
+    }) as unknown as typeof fetch;
+    await createDeliveryPurge({
+      zoneId: "z",
+      apiToken: "t",
+      fetch: hangOnce,
+      timeoutMs: 20,
+    }).purge(KEY);
+    expect(calls).toBe(2);
+  });
+
+  it("fails when both attempts time out: exactly two calls", async () => {
+    let calls = 0;
+    const hanging = ((_url: string, init: RequestInit) => {
+      calls++;
+      return new Promise<Response>((_resolve, reject) => {
+        init.signal?.addEventListener("abort", () =>
+          reject(init.signal?.reason),
+        );
+      });
+    }) as unknown as typeof fetch;
+    await expect(
+      createDeliveryPurge({
+        zoneId: "z",
+        apiToken: "t",
+        fetch: hanging,
+        timeoutMs: 20,
+      }).purge(KEY),
+    ).rejects.toThrow("timed out after 20 ms");
+    expect(calls).toBe(2);
+  });
+
+  it("bounds each attempt with a timeout signal by default", async () => {
+    const f = fakeFetch([{ status: 200, success: true }]);
+    await createDeliveryPurge({
+      zoneId: "z",
+      apiToken: "t",
+      fetch: f.fn,
+    }).purge(KEY);
+    expect(f.calls[0]!.init.signal).toBeInstanceOf(AbortSignal);
+  });
+
+  it("skips with a warning when unconfigured", async () => {
+    const warnings: string[] = [];
+    const f = fakeFetch([{ status: 200, success: true }]);
+    await createDeliveryPurge({
+      zoneId: undefined,
+      apiToken: "t",
+      fetch: f.fn,
+      warn: (m) => warnings.push(m),
+    }).purge(KEY);
+    expect(f.calls).toHaveLength(0);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("not configured");
+    expect(warnings[0]).toContain(KEY);
+  });
+});
diff --git a/apps/api/src/hosted/delivery-purge.ts b/apps/api/src/hosted/delivery-purge.ts
new file mode 100644
index 0000000000..1d7b938905
--- /dev/null
+++ b/apps/api/src/hosted/delivery-purge.ts
@@ -0,0 +1,98 @@
+/**
+ * Purging latest.json from Cloudflare's edge after Studio rewrites it.
+ *
+ * latest.json is served `s-maxage=3600`: the edge may hold it up to an hour.
+ * Every write (Publish, Make current) is followed by a purge of that
+ * URL through the zone's purge_cache API, so the new pointer is seen at once.
+ * Each attempt has a 5 s timeout and a failed attempt is retried exactly once
+ * (two attempts at most). If both fail, the operation fails: Studio shows it
+ * and the user retries from there. The hour bounds staleness.
+ */
+
+import { getSettings } from "@/settings";
+import { DELIVERY_ORIGIN } from "./delivery-store";
+
+export interface DeliveryPurge {
+  /** Purges the public URL of the delivery object `key`; throws on failure. */
+  purge(key: string): Promise<void>;
+}
+
+/** How long one purge attempt may take before it counts as failed. */
+const PURGE_TIMEOUT_MS = 5000;
+
+/** One attempt plus exactly one retry. */
+const PURGE_ATTEMPTS = 2;
+
+export function createDeliveryPurge(config: {
+  zoneId: string | undefined;
+  apiToken: string | undefined;
+  publicOrigin?: string;
+  fetch?: typeof fetch;
+  timeoutMs?: number;
+  warn?: (message: string) => void;
+}): DeliveryPurge {
+  const { zoneId, apiToken } = config;
+  if (!zoneId || !apiToken) {
+    const warn = config.warn ?? console.warn;
+    return {
+      async purge(key) {
+        warn(
+          `hosted delivery: Cloudflare purge not configured; skipped purging ${key} (the edge may serve the previous copy for up to 1 h)`,
+        );
+      },
+    };
+  }
+  const doFetch = config.fetch ?? fetch;
+  const timeoutMs = config.timeoutMs ?? PURGE_TIMEOUT_MS;
+  const origin = new URL(config.publicOrigin ?? DELIVERY_ORIGIN).origin;
+  const endpoint = `https://api.cloudflare.com/client/v4/zones/${encodeURIComponent(zoneId)}/purge_cache`;
+  return {
+    async purge(key) {
+      const url = `${origin}/${key}`;
+      const attempt = async () => {
+        let res: Response;
+        try {
+          res = await doFetch(endpoint, {
+            method: "POST",
+            headers: {
+              authorization: `Bearer ${apiToken}`,
+              "content-type": "application/json",
+            },
+            body: JSON.stringify({ files: [url] }),
+            signal: AbortSignal.timeout(timeoutMs),
+          });
+        } catch (error) {
+          const name = (error as { name?: string } | null)?.name;
+          throw new Error(
+            name === "TimeoutError"
+              ? `purge ${url}: timed out after ${timeoutMs} ms`
+              : `purge ${url}: ${error instanceof Error ? error.message : String(error)}`,
+          );
+        }
+        const body = (await res.json().catch(() => null)) as {
+          success?: unknown;
+        } | null;
+        if (!res.ok || body?.success !== true) {
+          throw new Error(`purge ${url}: HTTP ${res.status}`);
+        }
+      };
+      for (let i = 1; ; i++) {
+        try {
+          return await attempt();
+        } catch (error) {
+          if (i >= PURGE_ATTEMPTS) throw error;
+        }
+      }
+    },
+  };
+}
+
+/** The configured purge; unconfigured (local/dev/tests) it skips with a warning. */
+export function deliveryPurge(): DeliveryPurge {
+  const s = getSettings();
+  return createDeliveryPurge({
+    zoneId: s.cfDeliveryZoneId,
+    apiToken: s.cfPurgeApiToken,
+    publicOrigin: s.deliveryPublicOrigin,
+  });
+}
diff --git a/apps/api/src/hosted/delivery-store.test.ts b/apps/api/src/hosted/delivery-store.test.ts
new file mode 100644
index 0000000000..3080a176ae
--- /dev/null
+++ b/apps/api/src/hosted/delivery-store.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, it } from "bun:test";
+import {
+  bareEtag,
+  deliveryKeys,
+  listRevisionShas,
+  newDraftSlug,
+} from "./delivery-store";
+import { memoryDeliveryStore } from "./hosted-test-helpers";
+
+const SHA = "a".repeat(40);
+
+describe("deliveryKeys", () => {
+  it("builds the three object keys under the site's prefix", () => {
+    const slug = newDraftSlug();
+    expect(deliveryKeys.latest("acme")).toBe("sites/acme/latest.json");
+    expect(deliveryKeys.revision("acme", SHA)).toBe(
+      `sites/acme/revisions/${SHA}.json`,
+    );
+    expect(deliveryKeys.draft("acme", slug)).toBe(
+      `sites/acme/drafts/${slug}.json`,
+    );
+  });
+
+  it("refuses a site, revision or slug that could leave the prefix", () => {
+    expect(() => deliveryKeys.latest("../acme")).toThrow();
+    expect(() => deliveryKeys.latest("Acme")).toThrow();
+    expect(() => deliveryKeys.revision("acme", "main")).toThrow();
+    expect(() => deliveryKeys.revision("acme", "A".repeat(40))).toThrow();
+    expect(() => deliveryKeys.draft("acme", "x/../y")).toThrow();
+  });
+});
+
+describe("newDraftSlug", () => {
+  it("is 22 base64url characters and unique", () => {
+    const a = newDraftSlug();
+    expect(a).toMatch(/^[A-Za-z0-9_-]{22}$/);
+    expect(newDraftSlug()).not.toBe(a);
+  });
+});
+
+describe("bareEtag", () => {
+  it("drops the quotes and the weak prefix", () => {
+    expect(bareEtag('"abc"')).toBe("abc");
+    expect(bareEtag('W/"abc"')).toBe("abc");
+    expect(bareEtag(null)).toBeNull();
+  });
+});
+
+describe("listRevisionShas", () => {
+  it("lists only the site's revision objects", async () => {
+    const { store } = memoryDeliveryStore();
+    await store.putJson(deliveryKeys.revision("acme", SHA), {}, "x");
+    await store.putJson(deliveryKeys.latest("acme"), {}, "x");
+    await store.putJson(
+      deliveryKeys.revision("acme-2", "b".repeat(40)),
+      {},
+      "x",
+    );
+    expect([...(await listRevisionShas(store, "acme"))]).toEqual([SHA]);
+  });
+});
diff --git a/apps/api/src/hosted/delivery-store.ts b/apps/api/src/hosted/delivery-store.ts
new file mode 100644
index 0000000000..2805dbb7ca
--- /dev/null
+++ b/apps/api/src/hosted/delivery-store.ts
@@ -0,0 +1,219 @@
+/**
+ * The hosted Deco CMS delivery bucket: an R2 bucket served read-only at
+ * `https://delivery.decocms.com`, written by Studio through R2's S3 API.
+ *
+ *   sites/<site>/latest.json             { revision, schemaHash, publishedAt }
+ *   sites/<site>/revisions/<sha>.json    { revision, schemaHash, blocks }
+ *   sites/<site>/drafts/<slug>.json      { set, delete }
+ *
+ * Keys are only ever built here, from a validated site slug, commit sha or
+ * draft slug, so no caller can address anything outside its site's prefix.
+ */
+
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  ListObjectsV2Command,
+  PutObjectCommand,
+  S3Client,
+} from "@aws-sdk/client-s3";
+import { isValidSiteSlug } from "@decocms/shared/site-slug";
+import { getSettings } from "@/settings";
+
+export const DELIVERY_ORIGIN = "https://delivery.decocms.com";
+
+/** A git commit sha (SHA-1): a revision id. */
+const COMMIT_SHA_RE = /^[0-9a-f]{40}$/;
+/** 16 random bytes, base64url without padding. */
+const DRAFT_SLUG_RE = /^[A-Za-z0-9_-]{22}$/;
+
+/**
+ * The edge holds latest.json up to 1 h (purged after every write); browsers
+ * and servers revalidate on every read, so no unchecked stale pointer is used.
+ */
+export const CACHE_LATEST = "public, max-age=0, s-maxage=3600, must-revalidate";
+export const CACHE_REVISION = "public, max-age=31536000, immutable";
+export const CACHE_DRAFT = "no-cache, max-age=0, must-revalidate";
+
+export function isCommitSha(value: string): boolean {
+  return COMMIT_SHA_RE.test(value);
+}
+
+function siteKey(site: string): string {
+  if (!isValidSiteSlug(site)) throw new Error(`invalid site id: ${site}`);
+  return `sites/${site}`;
+}
+
+export const deliveryKeys = {
+  latest: (site: string) => `${siteKey(site)}/latest.json`,
+  revisions: (site: string) => `${siteKey(site)}/revisions/`,
+  revision: (site: string, sha: string) => {
+    if (!isCommitSha(sha)) throw new Error(`invalid revision: ${sha}`);
+    return `${siteKey(site)}/revisions/${sha}.json`;
+  },
+  draft: (site: string, slug: string) => {
+    if (!DRAFT_SLUG_RE.test(slug)) throw new Error("invalid draft slug");
+    return `${siteKey(site)}/drafts/${slug}.json`;
+  },
+};
+
+/** A new draft slug: unguessable, since holding its URL is the read grant. */
+export function newDraftSlug(): string {
+  return Buffer.from(crypto.getRandomValues(new Uint8Array(16))).toString(
+    "base64url",
+  );
+}
+
+/** An ETag without its quotes (and weak prefix), as the draft pointer carries it. */
+export function bareEtag(etag: string | null | undefined): string | null {
+  if (!etag) return null;
+  return etag.replace(/^W\//, "").replace(/^"|"$/g, "");
+}
+
+export interface StoredObject {
+  text: string;
+  etag: string | null;
+}
+
+/** The four object operations the hosted features need. */
+export interface DeliveryStore {
+  putJson(
+    key: string,
+    value: unknown,
+    cacheControl: string,
+  ): Promise<{ etag: string | null }>;
+  /** The object, or null when there is none. */
+  get(key: string): Promise<StoredObject | null>;
+  delete(key: string): Promise<void>;
+  /** Every key under `prefix`, paging through the whole listing. */
+  listKeys(prefix: string): Promise<string[]>;
+}
+
+/** The commit shas that have a revision object for `site`: one paged listing. */
+export async function listRevisionShas(
+  store: DeliveryStore,
+  site: string,
+): Promise<Set<string>> {
+  const prefix = deliveryKeys.revisions(site);
+  const shas = new Set<string>();
+  for (const key of await store.listKeys(prefix)) {
+    const sha = key.slice(prefix.length).replace(/\.json$/, "");
+    if (isCommitSha(sha)) shas.add(sha);
+  }
+  return shas;
+}
+
+export async function getJson(
+  store: DeliveryStore,
+  key: string,
+): Promise<{ value: unknown; etag: string | null } | null> {
+  const object = await store.get(key);
+  if (!object) return null;
+  return { value: JSON.parse(object.text) as unknown, etag: object.etag };
+}
+
+function isNotFound(error: unknown): boolean {
+  const e = error as { name?: string; $metadata?: { httpStatusCode?: number } };
+  return e?.name === "NoSuchKey" || e?.$metadata?.httpStatusCode === 404;
+}
+
+function createS3DeliveryStore(config: {
+  endpoint: string;
+  bucket: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+}): DeliveryStore {
+  const client = new S3Client({
+    endpoint: config.endpoint,
+    region: "auto",
+    credentials: {
+      accessKeyId: config.accessKeyId,
+      secretAccessKey: config.secretAccessKey,
+    },
+    forcePathStyle: true,
+  });
+  const Bucket = config.bucket;
+  return {
+    async putJson(key, value, cacheControl) {
+      const res = await client.send(
+        new PutObjectCommand({
+          Bucket,
+          Key: key,
+          Body: Buffer.from(JSON.stringify(value), "utf-8"),
+          ContentType: "application/json; charset=utf-8",
+          CacheControl: cacheControl,
+        }),
+      );
+      return { etag: res.ETag ?? null };
+    },
+    async get(key) {
+      try {
+        const res = await client.send(
+          new GetObjectCommand({ Bucket, Key: key }),
+        );
+        const text = (await res.Body?.transformToString("utf-8")) ?? "";
+        return { text, etag: res.ETag ?? null };
+      } catch (error) {
+        if (isNotFound(error)) return null;
+        throw error;
+      }
+    },
+    async delete(key) {
+      await client.send(new DeleteObjectCommand({ Bucket, Key: key }));
+    },
+    async listKeys(prefix) {
+      const keys: string[] = [];
+      let token: string | undefined;
+      do {
+        const res = await client.send(
+          new ListObjectsV2Command({
+            Bucket,
+            Prefix: prefix,
+            ContinuationToken: token,
+          }),
+        );
+        for (const object of res.Contents ?? []) {
+          if (object.Key) keys.push(object.Key);
+        }
+        token = res.IsTruncated ? res.NextContinuationToken : undefined;
+      } while (token);
+      return keys;
+    },
+  };
+}
+
+let cached: DeliveryStore | null | undefined;
+
+/** The configured delivery bucket, or null when this Studio has none. */
+export function deliveryStore(): DeliveryStore | null {
+  if (cached !== undefined) return cached;
+  const s = getSettings();
+  const endpoint =
+    s.deliveryR2Endpoint ??
+    (s.deliveryR2AccountId
+      ? `https://${s.deliveryR2AccountId}.r2.cloudflarestorage.com`
+      : undefined);
+  cached =
+    endpoint &&
+    s.deliveryR2Bucket &&
+    s.deliveryR2AccessKeyId &&
+    s.deliveryR2SecretAccessKey
+      ? createS3DeliveryStore({
+          endpoint,
+          bucket: s.deliveryR2Bucket,
+          accessKeyId: s.deliveryR2AccessKeyId,
+          secretAccessKey: s.deliveryR2SecretAccessKey,
+        })
+      : null;
+  return cached;
+}
+
+/**
+ * A draft's pointer target without scheme or version
+ * (`delivery.decocms.com/sites/<site>/drafts/<slug>.json`), the form the SDK's
+ * `?__draft=<pointer>@<version>` carries.
+ */
+export function draftPointerTarget(site: string, slug: string): string {
+  const origin = new URL(getSettings().deliveryPublicOrigin ?? DELIVERY_ORIGIN);
+  return `${origin.host}/${deliveryKeys.draft(site, slug)}`;
+}
diff --git a/apps/api/src/hosted/hosted-test-helpers.ts b/apps/api/src/hosted/hosted-test-helpers.ts
new file mode 100644
index 0000000000..646676ac62
--- /dev/null
+++ b/apps/api/src/hosted/hosted-test-helpers.ts
@@ -0,0 +1,234 @@
+/**
+ * In-memory stand-ins for the hosted tests: a delivery bucket, the org KV and
+ * a one-branch-plus-commits git repository behind `RepoContentClient`.
+ */
+
+import { createHash } from "node:crypto";
+import type { RepoRef } from "@decocms/shared/git-providers";
+import {
+  type FileChange,
+  type RepoContentClient,
+  type RepoInsightsClient,
+  RepoWriteConflict,
+  type TreeEntry,
+} from "@/git-providers";
+import type { KVStorage } from "@/storage/kv";
+import type { DeliveryPurge } from "./delivery-purge";
+import type { DeliveryStore } from "./delivery-store";
+
+export function memoryDeliveryStore() {
+  const objects = new Map<
+    string,
+    { text: string; etag: string; cacheControl: string }
+  >();
+  const log: string[] = [];
+  let n = 0;
+  const store: DeliveryStore = {
+    async putJson(key, value, cacheControl) {
+      const etag = `"etag${++n}"`;
+      objects.set(key, { text: JSON.stringify(value), etag, cacheControl });
+      log.push(`put ${key}`);
+      return { etag };
+    },
+    async get(key) {
+      const o = objects.get(key);
+      return o ? { text: o.text, etag: o.etag } : null;
+    },
+    async delete(key) {
+      objects.delete(key);
+      log.push(`delete ${key}`);
+    },
+    async listKeys(prefix) {
+      return [...objects.keys()].filter((k) => k.startsWith(prefix)).sort();
+    },
+  };
+  /** Logs `purge <key>` into the same log; `failPurge` makes it throw. */
+  const purgeState = { fail: false };
+  const purge: DeliveryPurge = {
+    async purge(key) {
+      log.push(`purge ${key}`);
+      if (purgeState.fail) throw new Error("purge failed");
+    },
+  };
+  return {
+    store,
+    objects,
+    log,
+    purge,
+    failPurge: (fail: boolean) => {
+      purgeState.fail = fail;
+    },
+  };
+}
+
+export function memoryKv(): KVStorage {
+  const data = new Map<string, Record<string, unknown>>();
+  return {
+    get: async (org, key) => data.get(`${org}\0${key}`) ?? null,
+    set: async (org, key, value) => {
+      data.set(`${org}\0${key}`, structuredClone(value));
+    },
+    delete: async (org, key) => {
+      data.delete(`${org}\0${key}`);
+    },
+  };
+}
+
+function blobSha(content: string): string {
+  const bytes = Buffer.from(content, "utf-8");
+  return createHash("sha1")
+    .update(`blob ${bytes.length}\0`)
+    .update(bytes)
+    .digest("hex");
+}
+
+const REPO: RepoRef = {
+  provider: "github",
+  host: "github.com",
+  path: "acme/site",
+};
+
+/** A repository with one branch, `main`, whose commits are file maps. */
+export function fakeRepo(files: Record<string, string>) {
+  const blobs = new Map<string, string>();
+  const commits = new Map<string, Map<string, string>>();
+  // Each commit is dated now (tests move the clock with setSystemTime).
+  const history: Array<{ sha: string; message: string; date: string }> = [];
+  let head = "";
+  let n = 0;
+  const commit = (tree: Map<string, string>, message: string) => {
+    const sha = createHash("sha1").update(`commit ${++n}`).digest("hex");
+    for (const content of tree.values()) blobs.set(blobSha(content), content);
+    commits.set(sha, tree);
+    history.unshift({ sha, message, date: new Date().toISOString() });
+    head = sha;
+    return sha;
+  };
+  commit(new Map(Object.entries(files)), "initial");
+
+  const treeAt = (ref: string) => {
+    const tree = commits.get(ref === "main" ? head : ref);
+    if (!tree) throw new Error(`no commit ${ref}`);
+    return tree;
+  };
+
+  const client: RepoContentClient = {
+    repo: REPO,
+    getDefaultBranch: async () => "main",
+    getBranch: async (branch) => (branch === "main" ? { sha: head } : null),
+    searchBranches: async () => ({
+      branches: [],
+      totalCount: 0,
+      nextCursor: null,
+    }),
+    getArchive: async () => null,
+    listDecofileEntries: async (treeish, packagePath) => {
+      const prefix = packagePath ? `${packagePath}/.deco/` : ".deco/";
+      return [...treeAt(treeish)]
+        .filter(([path]) => path.startsWith(prefix))
+        .map(
+          ([path, content]): TreeEntry => ({
+            path,
+            sha: blobSha(content),
+            type: "blob",
+            size: Buffer.byteLength(content),
+          }),
+        );
+    },
+    getEntriesAtPaths: async (treeish, paths) => {
+      const tree = treeAt(treeish);
+      return new Map(
+        paths.flatMap((path) => {
+          const content = tree.get(path);
+          return content === undefined
+            ? []
+            : [[path, { path, sha: blobSha(content), type: "blob" as const }]];
+        }),
+      );
+    },
+    readBlob: async (sha) => {
+      const content = blobs.get(sha);
+      if (content === undefined) throw new Error(`no blob ${sha}`);
+      return content;
+    },
+    readFileAtRef: async (ref, path) => treeAt(ref).get(path) ?? null,
+    commitFiles: async ({ branch, message, expectedHead, changes }) => {
+      if (branch !== "main") throw new Error("only main");
+      if (expectedHead !== null && expectedHead !== head) {
+        throw new RepoWriteConflict("head moved");
+      }
+      const tree = new Map(treeAt(head));
+      for (const change of changes as FileChange[]) {
+        if ("deleted" in change) tree.delete(change.path);
+        else if ("content" in change) tree.set(change.path, change.content);
+      }
+      return { sha: commit(tree, message) };
+    },
+    createBranch: async () => {},
+    forceBranchHead: async () => {},
+    mergeBranches: async () => null,
+    createChangeRequest: async () => {
+      throw new Error("unused");
+    },
+    findOpenChangeRequest: async () => null,
+    compare: async () => ({ aheadBy: 0, behindBy: 0 }),
+    compareDetailed: async () => {
+      throw new Error("unused");
+    },
+  };
+
+  return {
+    client,
+    head: () => head,
+    history,
+    filesAt: (ref: string) => Object.fromEntries(treeAt(ref)),
+    /** A commit made behind Studio's back (another writer). */
+    pushDirect: (
+      changes: Record<string, string | null>,
+      message = "direct",
+    ) => {
+      const tree = new Map(treeAt(head));
+      for (const [path, content] of Object.entries(changes)) {
+        if (content === null) tree.delete(path);
+        else tree.set(path, content);
+      }
+      return commit(tree, message);
+    },
+  };
+}
+
+/** `listCommits` over a fake repo's history, paged by offset; counts calls. */
+export function fakeInsights(
+  history: ReadonlyArray<{ sha: string; message: string; date: string }>,
+) {
+  const calls: Array<{ cursor: string | null; limit: number }> = [];
+  const client = {
+    listCommits: async ({
+      cursor,
+      limit = 50,
+    }: {
+      cursor?: string | null;
+      limit?: number;
+    }) => {
+      calls.push({ cursor: cursor ?? null, limit });
+      const from = cursor ? Number(cursor) : 0;
+      const items = history.slice(from, from + limit).map((c) => ({
+        sha: c.sha,
+        date: c.date,
+        message: c.message,
+        author: { name: "Ana", email: null, login: null },
+      }));
+      return {
+        items,
+        nextCursor: from + limit < history.length ? String(from + limit) : null,
+      };
+    },
+  } as unknown as RepoInsightsClient;
+  return { client, calls };
+}
+
+/** The schemaHash test vector shared with @decocms/blocks `deco content`. */
+export const SCHEMA_TEXT =
+  '{\n  "version": "8.1.0-next.7",\n  "blocksMajor": 8,\n  "definitions": { "seo": { "type": "object", "title": "Seo" } },\n  "root": {}\n}\n';
+export const SCHEMA_HASH =
+  "00b083655ee7af02aa92dbff85e402857bb1e50c253a579dbab23498a7842c98";
diff --git a/apps/api/src/settings/resolve-config.ts b/apps/api/src/settings/resolve-config.ts
index 3ee12e5019..994b299569 100644
--- a/apps/api/src/settings/resolve-config.ts
+++ b/apps/api/src/settings/resolve-config.ts
@@ -462,12 +462,25 @@ export function resolveConfig(
     // two can't drift). Set S3_TENANT_ENDPOINT only for a non-AWS S3 store.
     s3TenantEndpoint: envVars.S3_TENANT_ENDPOINT,
     s3TenantPublicUrlBase:
-      envVars.S3_TENANT_PUBLIC_URL_BASE || "https://decoims.com",
+      envVars.S3_TENANT_PUBLIC_URL_BASE || "https://assets.decocms.com",
     awsS3TenantRoleArn: envVars.AWS_S3_TENANT_ROLE_ARN,
     awsS3TenantProvisionerAccessKeyId:
       envVars.AWS_S3_TENANT_PROVISIONER_ACCESS_KEY_ID,
     awsS3TenantProvisionerSecretAccessKey:
       envVars.AWS_S3_TENANT_PROVISIONER_SECRET_ACCESS_KEY,
+
+    // Hosted Deco CMS (Blocks v8): the delivery bucket and site tokens.
+    // Unset = the hosted features answer "not configured".
+    deliveryR2AccountId: envVars.DELIVERY_R2_ACCOUNT_ID,
+    deliveryR2AccessKeyId: envVars.DELIVERY_R2_ACCESS_KEY_ID,
+    deliveryR2SecretAccessKey: envVars.DELIVERY_R2_SECRET_ACCESS_KEY,
+    deliveryR2Bucket: envVars.DELIVERY_R2_BUCKET,
+    // test-only: a local S3 store and the origin that serves it.
+    deliveryR2Endpoint: envVars.DELIVERY_R2_ENDPOINT,
+    deliveryPublicOrigin: envVars.DELIVERY_PUBLIC_ORIGIN,
+    siteTokenSigningKey: envVars.DECO_SITE_TOKEN_SIGNING_KEY,
+    cfDeliveryZoneId: envVars.CF_DELIVERY_ZONE_ID,
+    cfPurgeApiToken: envVars.CF_PURGE_API_TOKEN,
   };
 
   // A feature gate is only as trustworthy as this secret. `mintGatewayJwt`
diff --git a/apps/api/src/settings/types.ts b/apps/api/src/settings/types.ts
index 9f1c660985..07905d8a0c 100644
--- a/apps/api/src/settings/types.ts
+++ b/apps/api/src/settings/types.ts
@@ -328,6 +328,26 @@ export interface Settings {
   awsS3TenantRoleArn: string | undefined;
   awsS3TenantProvisionerAccessKeyId: string | undefined;
   awsS3TenantProvisionerSecretAccessKey: string | undefined;
+
+  // Hosted Deco CMS (Blocks v8). The R2 bucket behind delivery.decocms.com,
+  // written through its S3 API; the endpoint derives from the account id.
+  deliveryR2AccountId: string | undefined;
+  deliveryR2AccessKeyId: string | undefined;
+  deliveryR2SecretAccessKey: string | undefined;
+  deliveryR2Bucket: string | undefined;
+  /** test-only: overrides `https://<account>.r2.cloudflarestorage.com`. */
+  deliveryR2Endpoint: string | undefined;
+  /** test-only: overrides `https://delivery.decocms.com` in draft pointers. */
+  deliveryPublicOrigin: string | undefined;
+  /** Ed25519 private key (base64 PKCS8) that signs site tokens. */
+  siteTokenSigningKey: string | undefined;
+  /**
+   * The Cloudflare zone serving the delivery bucket and a token with Zone →
+   * Cache Purge on it: latest.json is purged after every write. Unset = the
+   * purge is skipped with a warning (local/dev/tests).
+   */
+  cfDeliveryZoneId: string | undefined;
+  cfPurgeApiToken: string | undefined;
 }
 
 export interface CliFlags {
diff --git a/knip.jsonc b/knip.jsonc
index 648d876dea..a51ca17395 100644
--- a/knip.jsonc
+++ b/knip.jsonc
@@ -76,6 +76,8 @@
   "ignoreDependencies": ["@types/*"],
   // TODO(@camudo): Remove this config once I fix all unused type exports
   "ignoreIssues": {
-    "**/*": ["types"]
+    "**/*": ["types"],
+    // Temporary (split stack): hosted modules land before their routes (removed when /_sandbox/rpc lands).
+    "apps/api/src/hosted/*.ts": ["exports"]
   }
 }