@unitninety/site-kit 0.0.0-stage → 1.6.1

package/src/test-preview/protocol.mjs

@@ -0,0 +1,222 @@
+import { createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify } from 'node:crypto'
+import { isIP } from 'node:net'
+
+const MAX_TOKEN_BYTES = 8192
+const CERTIFICATE_PREFIX = 'u90tc1'
+const SESSION_PREFIX = 'u90tp1'
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const CERTIFICATE_FIELDS = ['version', 'environmentId', 'platformOrigin', 'sourceOrigin', 'publicKey', 'issuedAt', 'expiresAt']
+const SESSION_FIELDS = ['version', 'purpose', 'tenantPublicId', 'nonce', 'issuedAt', 'expiresAt']
+
+function invalid() {
+  throw new Error('Invalid test preview credential')
+}
+
+// Prevent crypto/parser errors from exposing supplied credential or key material.
+function bounded(operation) {
+  try {
+    return operation()
+  } catch {
+    return invalid()
+  }
+}
+
+function record(value, fields) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) invalid()
+  const keys = Object.keys(value)
+  if (keys.length !== fields.length || fields.some(field => !Object.hasOwn(value, field))) invalid()
+  return value
+}
+
+function shortString(value) {
+  if (typeof value !== 'string' || value.length < 1 || value.length > 256 || value.trim() !== value || /[\u0000-\u001f\u007f]/.test(value)) invalid()
+}
+
+function integer(value) {
+  if (!Number.isSafeInteger(value) || value < 0) invalid()
+}
+
+function lifetime(value, maximum, now) {
+  integer(value.issuedAt)
+  integer(value.expiresAt)
+  if (value.expiresAt <= value.issuedAt || value.expiresAt - value.issuedAt > maximum) invalid()
+  if (now !== undefined) {
+    integer(now)
+    if (value.issuedAt > now || value.expiresAt <= now) invalid()
+  }
+}
+
+function privateIPv4(address) {
+  const [a, b] = address.split('.').map(Number)
+  return a === 0 || a === 10 || a === 127 || a >= 224 ||
+    (a === 100 && b >= 64 && b <= 127) || (a === 169 && b === 254) ||
+    (a === 172 && b >= 16 && b <= 31) || (a === 192 && (b === 168 || b === 0)) ||
+    (a === 198 && (b === 18 || b === 19))
+}
+
+function privateIPv6(address) {
+  const halves = address.split('::')
+  const left = halves[0] ? halves[0].split(':') : []
+  const right = halves.length === 2 && halves[1] ? halves[1].split(':') : []
+  const groups = [...left, ...Array(8 - left.length - right.length).fill('0'), ...right].map(group => parseInt(group, 16))
+  // URL canonicalization renders IPv4-mapped literals in hexadecimal form.
+  if (groups.slice(0, 5).every(group => group === 0) && (groups[5] === 0xffff || groups[5] === 0)) {
+    return privateIPv4(`${groups[6] >> 8}.${groups[6] & 255}.${groups[7] >> 8}.${groups[7] & 255}`)
+  }
+  return (groups[0] & 0xfe00) === 0xfc00 || (groups[0] & 0xffc0) === 0xfe80 ||
+    (groups[0] & 0xffc0) === 0xfec0 || (groups[0] & 0xff00) === 0xff00
+}
+
+function origin(value) {
+  if (typeof value !== 'string' || value.length > 2048) invalid()
+  const url = new URL(value)
+  if (url.protocol !== 'https:' || url.username || url.password || url.origin !== value) invalid()
+  const hostname = url.hostname.replace(/^\[|\]$/g, '')
+  const localName = hostname.replace(/\.$/, '')
+  if (localName === 'localhost' || localName.endsWith('.localhost')) invalid()
+  const family = isIP(hostname)
+  if ((family === 4 && privateIPv4(hostname)) || (family === 6 && privateIPv6(hostname))) invalid()
+}
+
+function base64url(value, maximum = MAX_TOKEN_BYTES) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > maximum || !/^[A-Za-z0-9_-]+$/.test(value)) invalid()
+  const bytes = Buffer.from(value, 'base64url')
+  if (bytes.toString('base64url') !== value) invalid()
+  return bytes
+}
+
+function key(value, type) {
+  const der = base64url(value, 4096)
+  const options = { key: der, format: 'der', type }
+  const parsed = type === 'pkcs8' ? createPrivateKey(options) : createPublicKey(options)
+  if (parsed.asymmetricKeyType !== 'ed25519' || !parsed.export({ format: 'der', type }).equals(der)) invalid()
+  return parsed
+}
+
+function validateCertificate(value, now) {
+  record(value, CERTIFICATE_FIELDS)
+  if (value.version !== 1 || typeof value.environmentId !== 'string' || !UUID.test(value.environmentId)) invalid()
+  origin(value.platformOrigin)
+  origin(value.sourceOrigin)
+  if (value.platformOrigin === value.sourceOrigin) invalid()
+  key(value.publicKey, 'spki')
+  lifetime(value, 604800, now)
+  return value
+}
+
+function validateClaims(value, certificate, now) {
+  if (!value || typeof value !== 'object') invalid()
+  const fields = value.purpose === 'site' ? [...SESSION_FIELDS, 'siteOrigin', 'branchMediaKey'] : SESSION_FIELDS
+  record(value, fields)
+  if (value.version !== 1 || (value.purpose !== 'site' && value.purpose !== 'reference')) invalid()
+  shortString(value.tenantPublicId)
+  if (typeof value.nonce !== 'string' || !UUID.test(value.nonce)) invalid()
+  if (value.purpose === 'site') {
+    origin(value.siteOrigin)
+    shortString(value.branchMediaKey)
+  }
+  lifetime(value, 900, now)
+  if (value.issuedAt < certificate.issuedAt || value.expiresAt > certificate.expiresAt) invalid()
+  return value
+}
+
+// Both signer and verifier consume exactly these bytes, including the protocol
+// prefix. Sorting recursively gives a single encoding for the signed envelope.
+function canonical(value) {
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map(field => `${JSON.stringify(field)}:${canonical(value[field])}`).join(',')}}`
+  }
+  return JSON.stringify(value)
+}
+
+function encode(prefix, payload, privateKey) {
+  const encoded = Buffer.from(canonical(payload)).toString('base64url')
+  const signedBytes = Buffer.from(`${prefix}.${encoded}`)
+  const signature = sign(null, signedBytes, privateKey).toString('base64url')
+  const token = `${prefix}.${encoded}.${signature}`
+  if (Buffer.byteLength(token) > MAX_TOKEN_BYTES) invalid()
+  return token
+}
+
+function decode(token, prefix) {
+  if (typeof token !== 'string' || Buffer.byteLength(token) > MAX_TOKEN_BYTES) invalid()
+  const parts = token.split('.')
+  if (parts.length !== 3 || parts[0] !== prefix) invalid()
+  const bytes = base64url(parts[1])
+  // Preserve a leading BOM so decoding cannot turn noncanonical bytes into JSON.
+  const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes)
+  const payload = JSON.parse(text)
+  if (canonical(payload) !== text) invalid()
+  const signature = base64url(parts[2])
+  if (signature.length !== 64) invalid()
+  return { payload, signature, signedBytes: Buffer.from(`${prefix}.${parts[1]}`) }
+}
+
+function verifySignature(envelope, publicKey) {
+  if (!verify(null, envelope.signedBytes, publicKey, envelope.signature)) invalid()
+}
+
+export function generatePreviewKeyPair() {
+  return bounded(() => {
+    const pair = generateKeyPairSync('ed25519', {
+      privateKeyEncoding: { type: 'pkcs8', format: 'der' },
+      publicKeyEncoding: { type: 'spki', format: 'der' },
+    })
+    return { privateKey: pair.privateKey.toString('base64url'), publicKey: pair.publicKey.toString('base64url') }
+  })
+}
+
+export function signEnvironmentCertificate(claims, privateKey) {
+  return bounded(() => encode(CERTIFICATE_PREFIX, validateCertificate(claims), key(privateKey, 'pkcs8')))
+}
+
+export function verifyEnvironmentCertificate(certificate, publicKey, options = {}) {
+  return bounded(() => {
+    const now = options.now === undefined ? Math.floor(Date.now() / 1000) : options.now
+    const envelope = decode(certificate, CERTIFICATE_PREFIX)
+    verifySignature(envelope, key(publicKey, 'spki'))
+    return validateCertificate(envelope.payload, now)
+  })
+}
+
+export function signPreviewSession(claims, certificate, privateKey) {
+  return bounded(() => {
+    // The branch can inspect its certificate but does not possess the issuer's
+    // public key here. Issuer verification is mandatory at the receiving side.
+    const environment = validateCertificate(decode(certificate, CERTIFICATE_PREFIX).payload)
+    const parsedKey = key(privateKey, 'pkcs8')
+    if (createPublicKey(parsedKey).export({ type: 'spki', format: 'der' }).toString('base64url') !== environment.publicKey) invalid()
+    validateClaims(claims, environment)
+    return encode(SESSION_PREFIX, { certificate, claims }, parsedKey)
+  })
+}
+
+export function verifyPreviewSession(token, options) {
+  return bounded(() => {
+    if (!options || (options.purpose !== 'reference' && options.purpose !== 'site')) invalid()
+    const now = options.now === undefined ? Math.floor(Date.now() / 1000) : options.now
+    const envelope = decode(token, SESSION_PREFIX)
+    record(envelope.payload, ['certificate', 'claims'])
+    const certificate = verifyEnvironmentCertificate(envelope.payload.certificate, options.issuerPublicKey, { now })
+    verifySignature(envelope, key(certificate.publicKey, 'spki'))
+    const claims = validateClaims(envelope.payload.claims, certificate, now)
+    if (claims.purpose !== options.purpose) invalid()
+    for (const [field, expected] of [
+      ['sourceOrigin', certificate.sourceOrigin], ['platformOrigin', certificate.platformOrigin],
+      ['siteOrigin', claims.purpose === 'site' ? claims.siteOrigin : undefined], ['tenantPublicId', claims.tenantPublicId],
+    ]) {
+      if (Object.hasOwn(options, field)) {
+        if (field === 'tenantPublicId') shortString(options[field])
+        else origin(options[field])
+        if (options[field] !== expected) invalid()
+      }
+    }
+    return { certificate, claims }
+  })
+}
+
+export function isTestPreviewToken(value) {
+  // Detect malformed prefixed credentials too, so callers can refuse them
+  // instead of passing them through legacy draft/production authentication.
+  return typeof value === 'string' && value.startsWith(SESSION_PREFIX)
+}

package/src/test-preview/runtime.ts

@@ -0,0 +1,168 @@
+import { createHash } from 'node:crypto'
+import { z } from 'zod'
+import { readBoundedJSON } from '../features/server/http'
+import type { Env } from '../server/read'
+import {
+  isTestPreviewToken,
+  verifyPreviewSession,
+  type EnvironmentCertificate,
+  type SitePreviewClaims,
+} from './protocol.mjs'
+
+const TrustSchema = z.strictObject({
+  version: z.literal(1),
+  issuerPublicKey: z.string().min(1).max(1024),
+  tenantPublicId: z.string().min(1).max(256),
+  siteOrigin: z.string().url(),
+  mediaKey: z
+    .string()
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/)
+    .max(256)
+    .refine((value) => !value.includes('..')),
+})
+export type TestPreviewTrust = z.infer<typeof TrustSchema>
+export type TestPreviewContext = {
+  token: string
+  platformOrigin: string
+  siteOrigin: string
+  environmentId: string
+  visitorCookieName: string
+  certificate: EnvironmentCertificate
+  claims: SitePreviewClaims
+  trust: TestPreviewTrust
+}
+export type TestPreviewOptions = {
+  env: Env
+  fetch?: typeof fetch
+  now?: () => number
+  buildId?: string
+  trustTimeoutMs?: number
+}
+export class TestPreviewRefused extends Error {
+  constructor() {
+    super('Test preview is unavailable or expired')
+  }
+}
+export const previewResponseHeaders = {
+  'cache-control': 'no-store',
+  'referrer-policy': 'no-referrer',
+  'x-robots-tag': 'noindex, nofollow',
+}
+export const EXPECTED_PREVIEW_PARAM = 'u90test'
+/** Cookie parsing refuses duplicates rather than choosing an attacker-controlled value. */
+export function requestCookie(request: Request, name: string): string | null {
+  const prefix = name + '='
+  const values = (request.headers.get('cookie') ?? '')
+    .split(';')
+    .map((value) => value.trim())
+    .filter((value) => value.startsWith(prefix))
+  if (values.length > 1) throw new TestPreviewRefused()
+  return values[0]?.slice(prefix.length) ?? null
+}
+export function requestPreviewToken(request: Request): string | null {
+  return requestCookie(request, 'u90-preview-token')
+}
+
+export function createTestPreviewRuntime(options: TestPreviewOptions) {
+  const now = options.now ?? (() => Math.floor(Date.now() / 1000))
+  let cached: { trust: TestPreviewTrust; expiresAt: number } | undefined
+  let pending: Promise<TestPreviewTrust> | undefined
+  const getTrust = async (): Promise<TestPreviewTrust> => {
+    if (cached && now() < cached.expiresAt) return cached.trust
+    if (pending) return pending
+    pending = (async () => {
+      const { env } = options
+      if (!env.PLATFORM_URL || !env.PAYLOAD_API_KEY || !env.SITE_URL) throw new TestPreviewRefused()
+      const source = new URL(env.PLATFORM_URL),
+        site = new URL(env.SITE_URL)
+      if (
+        source.protocol !== 'https:' ||
+        source.username ||
+        source.password ||
+        source.search ||
+        source.hash ||
+        site.protocol !== 'https:'
+      )
+        throw new TestPreviewRefused()
+      const controller = new AbortController()
+      let response: Response | undefined
+      let timer: ReturnType<typeof setTimeout> | undefined
+      try {
+        const timeout = new Promise<never>((_, reject) => {
+          timer = setTimeout(() => {
+            controller.abort()
+            reject(new TestPreviewRefused())
+          }, options.trustTimeoutMs ?? 5000)
+        })
+        const trust = await Promise.race([
+          timeout,
+          (async () => {
+            response = await (options.fetch ?? fetch)(
+              `${env.PLATFORM_URL!.replace(/\/+$/, '')}/api/u90/test-preview/trust`,
+              {
+                headers: { authorization: `Bearer ${env.PAYLOAD_API_KEY}` },
+                cache: 'no-store',
+                redirect: 'error',
+                signal: controller.signal,
+              },
+            )
+            if (!response.ok || response.status >= 300) throw new TestPreviewRefused()
+            const parsed = TrustSchema.parse(
+              await readBoundedJSON(response, 16384, controller.signal),
+            )
+            if (parsed.siteOrigin !== site.origin) throw new TestPreviewRefused()
+            return parsed
+          })(),
+        ])
+        cached = { trust, expiresAt: now() + 300 }
+        return trust
+      } finally {
+        clearTimeout(timer)
+      }
+    })().finally(() => {
+      pending = undefined
+    })
+    return pending
+  }
+  return {
+    async resolve(token: string | null): Promise<TestPreviewContext | null> {
+      if (!isTestPreviewToken(token)) return null
+      try {
+        const trust = await getTrust()
+        const verified = verifyPreviewSession(token!, {
+          issuerPublicKey: trust.issuerPublicKey,
+          purpose: 'site',
+          sourceOrigin: new URL(options.env.PLATFORM_URL!).origin,
+          siteOrigin: trust.siteOrigin,
+          tenantPublicId: trust.tenantPublicId,
+          now: now(),
+        })
+        const claims = verified.claims as SitePreviewClaims
+        return {
+          ...verified,
+          claims,
+          trust,
+          token: token!,
+          platformOrigin: verified.certificate.platformOrigin,
+          siteOrigin: claims.siteOrigin,
+          environmentId: verified.certificate.environmentId,
+          visitorCookieName:
+            'u90_feature_test_' +
+            createHash('sha256')
+              .update(
+                verified.certificate.environmentId +
+                  '\n' +
+                  verified.certificate.platformOrigin +
+                  '\n' +
+                  claims.tenantPublicId,
+              )
+              .digest('hex')
+              .slice(0, 32),
+        }
+      } catch {
+        throw new TestPreviewRefused()
+      }
+    },
+  }
+}
+export type TestPreviewRuntime = ReturnType<typeof createTestPreviewRuntime>

package/src/test-preview/server.ts

@@ -0,0 +1,10 @@
+export { testPreviewProxy, TEST_PREVIEW_ACTIONS, type TestPreviewCapabilities } from './guard'
+export {
+  createTestPreviewRuntime,
+  TestPreviewRefused,
+  EXPECTED_PREVIEW_PARAM,
+  type TestPreviewContext,
+  type TestPreviewTrust,
+  type TestPreviewOptions,
+  type TestPreviewRuntime,
+} from './runtime'

package/src/testing/fake.ts

@@ -0,0 +1,148 @@
+import { applyOverlay, newDocumentId, seed, type DocumentDecl, type OverlayValues } from '../elements'
+import { hasTranslatedCopy, type SiteLanguages } from '../languages/routing'
+import { assemble, manifestFrom, manifestHash, replyFrom, type Reply, type ReplySeo, type ReplyTarget, type RouteRead, type Site, type SiteReply } from '../site'
+import type { RedirectsReply } from '../redirects/wire'
+import { seedCtx, seedEntry, seedSite, type Store } from '../site/store'
+
+export type { RouteRead }
+const assembled = (site: Site, store: Store, target: ReplyTarget, draft: boolean): RouteRead =>
+  assemble(site, replyFrom(site, store, target, ''), { draft, target, stale: false, defaults: null })
+/** A route read against a store, assembled as the site assembles a platform's reply. */
+export const routeRead = (site: Site, store: Store, pathname: string, draft: boolean): RouteRead => assembled(site, store, { route: pathname }, draft)
+/**
+ * `/entry/:collection/:slug` of the read contract, as the site assembles it: independent of whether
+ * the collection has a public route, so a routeless collection (coastline's `sectors`) is readable too.
+ */
+export const entryRead = (site: Site, store: Store, collection: string, slug: string, draft: boolean): RouteRead =>
+  assembled(site, store, { entry: { collection, slug } }, draft)
+
+/**
+ * The read contract, in-process: `/api/u90/v1/*` answered with replies built from a store, as the
+ * platform answers. `manifest` overrides the hash it reports, to play a platform behind a deploy.
+ * `failSite` makes `/site` answer 500, to play a platform whose site-wide SEO cannot be read.
+ * `redirects` are the rules `/redirects` answers with; `setRedirects` replaces them.
+ * `languages` plays a platform whose site has them (an object) or none (null); left out, the fake accepts any `locale` and answers the base, as before languages.
+ */
+export async function createFakePlatform(site: Site, store?: Store, opts: { manifest?: string; failSite?: boolean; redirects?: RedirectsReply['rules']; languages?: SiteLanguages | null } = {}) {
+  const s = store ?? (await seedSite(site))
+  const manifest = opts.manifest ?? (await manifestHash(manifestFrom(site)))
+  const revalidated: string[] = []
+  let redirects: RedirectsReply['rules'] = opts.redirects ?? []
+  const ctx = seedCtx(s.media)
+  /** Undefined until languages are given: the fake then answers any `locale` with the base, as it did before languages. */
+  let languages: SiteLanguages | null | undefined = opts.languages
+  /** By document key, then by locale. */
+  const translations = new Map<string, Map<string, OverlayValues>>()
+  /** The overlay layers of a read, most preferred first, as plan 1's `languageChain` lists them; null for a locale this site cannot answer. */
+  const chainOf = (requested: string | null): { locale: string | null; layers: string[] } | null => {
+    if (languages === undefined) return { locale: null, layers: [] }
+    if (languages === null) return requested === null ? { locale: null, layers: [] } : null
+    const locale = requested ?? languages.default
+    if (!languages.active.some((language) => language.id === locale)) return null
+    return { locale, layers: [locale, languages.default].filter((id, at, all) => id !== languages!.original && all.indexOf(id) === at) }
+  }
+  /** As the platform answers it (ruling R2): the active languages, other than the original and the default, whose own translation of `document` holds copy. */
+  const translatedOf = (document: string): string[] =>
+    languages ? languages.active.map((l) => l.id).filter((id) => id !== languages!.default && id !== languages!.original && hasTranslatedCopy(translations.get(document)?.get(id))) : []
+  /** A sitemap entry with its languages, as the platform lists them, for a site with languages. */
+  const withLanguages = (entry: { path: string; lastModified: string | null }, document: string) =>
+    languages ? { ...entry, languages: languages.active.map((l) => l.id).filter((id) => id === languages!.default || id === languages!.original || translatedOf(document).includes(id)) } : entry
+  const layoutDecl: DocumentDecl = { kind: 'layout', blocks: { container: 'u90/zone', allow: Object.keys(site.schema.blocks) } }
+  /** The store with the layers laid over every page, layout and Single; the store itself is never changed. */
+  const overlaid = (layers: string[]): Store => {
+    if (layers.length === 0) return s
+    const of = (doc: string) => layers.flatMap((locale) => { const values = translations.get(doc)?.get(locale); return values ? [values] : [] })
+    const pages = new Map([...s.pages].map(([k, p]) => {
+      const blocks = p.key ? site.pages[p.key]?.blocks : p.pageType ? site.pageTypes[p.pageType]?.blocks : undefined
+      return [k, blocks ? { ...p, doc: applyOverlay(site.schema, { kind: 'page', blocks }, p.doc, `page:${p.id}`, of(`page:${p.id}`)).doc } : p]
+    }))
+    const layouts = new Map([...s.layouts].map(([k, l]) => [k, { ...l, doc: applyOverlay(site.schema, layoutDecl, l.doc, `layout:${k}`, of(`layout:${k}`)).doc }]))
+    const singles = new Map([...s.singles].map(([k, v]) => [k, { doc: applyOverlay(site.schema, { kind: 'single', key: k }, v.doc, `single:${k}`, of(`single:${k}`)).doc as { value: unknown } }]))
+    return { ...s, pages, layouts, singles }
+  }
+  const json = (body: unknown, status = 200) => new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } })
+  /**
+   * `/site` by default: an indexed site, with the manifest's title template and nothing else set.
+   * The real platform answers `allowIndexing: false` for a tenant that has not saved SEO settings;
+   * `setSite` plays that tenant.
+   */
+  const settings: SiteReply = { allowIndexing: true, siteName: null, titleTemplate: site.seo.titleTemplate ?? null, description: null, ogImage: null, locale: null, twitterCard: 'summary_large_image', twitterHandle: null, googleVerification: null, bingVerification: null, organisation: null }
+  /** The read contract carries `Authorization: Bearer` on every read (spec §4): checked before dispatch, regardless of whether the path resolves. */
+  const fetchImpl: typeof fetch = async (input, init) => {
+    const url = new URL(input instanceof URL ? input.href : typeof input === 'string' ? input : input.url)
+    const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined))
+    if (!headers.get('authorization')?.startsWith('Bearer ')) return json({ error: 'unauthorised' }, 401)
+    // With no languages given, `locale` is accepted and the base answered. With languages, a `locale` must name an active one, and the layers [requested, default] are laid over pages, layouts and Singles; entries are not overlaid.
+    const draft = url.searchParams.get('draft') === '1'
+    if (draft && !headers.get('x-u90-preview-token')) return json({ error: 'preview token' }, 401)
+    const p = url.pathname.replace(/^.*\/api\/u90\/v1/, '')
+    const chain = chainOf(url.searchParams.get('locale') || null)
+    const reads = p === '/route' || p.startsWith('/page/') || p.startsWith('/entry/')
+    if (reads && chain === null) return json({ error: 'Unknown language.' }, 400)
+    const view = chain ? overlaid(chain.layers) : s
+    // A site with languages hears which language answered, as the platform says it, and which languages have copy of the document (ruling R2).
+    const answer = (reply: Reply) =>
+      json(reply.status === 'ok' && chain?.locale ? { ...reply, locale: chain.locale, ...(languages ? { translated: translatedOf(`${reply.document.kind}:${reply.document.id}`) } : {}) } : reply)
+    if (p === '/route') return answer(replyFrom(site, view, { route: url.searchParams.get('path') ?? '/' }, manifest))
+    if (p.startsWith('/page/')) return answer(replyFrom(site, view, { page: decodeURIComponent(p.slice(6)) }, manifest))
+    if (p.startsWith('/entry/')) {
+      // The read client encodes both segments (and a URL's pathname keeps them encoded), so a
+      // non-ASCII slug arrives as `caf%C3%A9`; decoded after the split, so an encoded `/` stays in its segment.
+      let segments: string[]
+      try { segments = p.split('/').slice(2).map(decodeURIComponent) } catch { return json({ error: 'malformed path' }, 400) }
+      return answer(replyFrom(site, view, { entry: { collection: segments[0], slug: segments[1] } }, manifest))
+    }
+    if (p === '/site') return opts.failSite ? json({ error: 'site settings unavailable' }, 500) : json(languages ? { ...settings, languages } : settings)
+    if (p === '/sitemap') {
+      // As the platform does: nothing while indexing is off, and no document whose own SEO says noindex.
+      if (!settings.allowIndexing) return json({ entries: [] })
+      // A site with languages lists each entry in the languages it has copy in (ruling R2).
+      const entries = [...s.entries.values()].flatMap((e) => (site.collections[e.collection]?.route && !e.seo?.noindex ? [withLanguages({ path: site.collections[e.collection].route!.replace(':slug', e.slug), lastModified: null }, `entry:${e.id}`)] : []))
+      return json({ entries: [...[...s.pages.values()].filter((x) => !x.seo?.noindex).map((x) => withLanguages({ path: x.route, lastModified: null }, `page:${x.id}`)), ...entries] })
+    }
+    if (p === '/redirects') return json({ rules: redirects, generatedAt: new Date().toISOString() })
+    if (p === '/revalidate') { const body = (await (init?.body ? new Response(init.body) : (input as Request)).json()) as { tags: string[] }; revalidated.push(...body.tags); return json({ ok: true }) }
+    return json({ error: 'not found' }, 404)
+  }
+  return {
+    fetch: fetchImpl, store: s, revalidated, manifest,
+    async addEntry(collection: string, slug: string, fields: Record<string, unknown>, blocks?: unknown[]) {
+      await seedEntry(site, s, ctx, collection, slug, fields, blocks)
+    },
+    async addPage(pageType: string, slug: string, blocks?: unknown[], title?: string) {
+      const t = site.pageTypes[pageType]
+      if (!t) throw new Error(`No page type named "${pageType}".`)
+      const id = newDocumentId()
+      const doc = await seed(site.schema, { kind: 'page', blocks: t.blocks }, blocks, ctx, `page:${id}`)
+      s.pages.set(id, { id, slug, route: t.route.replace(':slug', slug), layout: t.layout, pageType, title: title ?? slug, doc })
+      return id
+    },
+    setStored(kind: 'page' | 'layout' | 'single', id: string, pointer: string, value: unknown) {
+      if (!/^\/[^/]+(\/[^/]+)*$/.test(pointer)) throw new Error(`"${pointer}" is not a valid pointer: expected a leading "/" and at least one segment, e.g. "/blocks/0/headline".`)
+      const entry = kind === 'page' ? s.pages.get(id) : kind === 'layout' ? s.layouts.get(id) : s.singles.get(id)
+      if (!entry) throw new Error(`No ${kind} named "${id}" is stored.`)
+      const segs = pointer.split('/').slice(1); let node: any = entry.doc
+      for (const seg of segs.slice(0, -1)) {
+        if (node === null || typeof node !== 'object' || !(seg in node)) throw new Error(`"${pointer}" has no node at "${seg}" (in ${kind} "${id}").`)
+        node = node[seg]
+      }
+      node[segs.at(-1)!] = value
+    },
+    setSeo(target: { page: string } | { entry: { collection: string; slug: string } }, seo: ReplySeo) {
+      const doc = 'page' in target ? s.pages.get(target.page) : [...s.entries.values()].find((e) => e.collection === target.entry.collection && e.slug === target.entry.slug)
+      if (!doc) throw new Error(`Nothing stored for ${JSON.stringify(target)}.`)
+      doc.seo = seo
+    },
+    setSite(changes: Partial<SiteReply>) { Object.assign(settings, changes) },
+    /** Replaces the rules `/redirects` answers with. */
+    setRedirects(next: RedirectsReply['rules']) { redirects = next },
+    /** Plays a platform whose site has these languages; null plays one whose site has none. */
+    setLanguages(next: SiteLanguages | null) { languages = next },
+    /** Stores one language's overlay of a page (`page:<id>`), layout (`layout:<key>`) or Single (`single:<key>`). */
+    setTranslation(document: string, locale: string, values: OverlayValues) {
+      const byLocale = translations.get(document) ?? new Map<string, OverlayValues>()
+      byLocale.set(locale, values)
+      translations.set(document, byLocale)
+    },
+  }
+}

package/src/testing/index.ts

@@ -0,0 +1,2 @@
+export { seedSite, seedCtx, seedEntry, type Store, type StoredPage } from './seed'
+export { createFakePlatform, routeRead, entryRead, type RouteRead } from './fake'

package/src/testing/seed.ts

@@ -0,0 +1,2 @@
+/** The defaults store moved to `site/store.ts`, where the read path and the fake both take it from. */
+export * from '../site/store'