@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/site/wire.ts

@@ -0,0 +1,125 @@
+import type { EntryRecord, FieldDecl, Id, MediaRecord, PageRecord } from '../elements'
+import type { SiteManifest } from './types'
+
+/** A page's or an entry's SEO settings as the platform stores them. `ogImage` is a media id whose record is in the reply's `media`. */
+export type ReplySeo = { title: string | null; description: string | null; ogTitle: string | null; ogDescription: string | null; ogImage: Id | null; canonical: string | null; noindex: boolean }
+/** The document a reply is for, as stored, with the columns the site needs to place it. */
+export type ReplyDocument = {
+  kind: 'page' | 'entry'
+  id: string
+  slug: string
+  key?: string
+  pageType?: string
+  collection?: string
+  route?: string
+  /** A page's title, as editors name it. Absent for an entry. */
+  title?: string
+  seo: ReplySeo | null
+  /** The layouts the document renders inside, outermost first. */
+  layoutChain: string[]
+  stored: unknown
+}
+/** A Single as stored, with its declaration when the platform's manifest does not declare it: a Single made on the platform. */
+export type StoredSingle = { stored: unknown; declaration?: FieldDecl }
+export type DocumentReply = {
+  status: 'ok'
+  /** `manifestHash` of the manifest the platform holds. */
+  manifest: string
+  document: ReplyDocument
+  layouts: Record<string, unknown>
+  singles: Record<string, StoredSingle>
+  media: Record<string, MediaRecord>
+  pages: Record<string, PageRecord>
+  /** By `entryKey(collection, id)`. */
+  entries: Record<string, EntryRecord>
+  /** By `queryKey(collection, query)`. */
+  queries: Record<string, { ids: Id[]; total: number }>
+  /** By `inverseKey(collection, field, id)`. */
+  inverses: Record<string, Id[]>
+  tags: string[]
+  /** The language answered, when the tenant has languages. A tenant with none answers without it. */
+  locale?: string
+  /** A draft read in a translated language only: by document key, the overlay keys that fell back to another language or to the original. */
+  fallbacks?: Record<string, string[]>
+  /** A tenant with languages only: the active languages, other than the original and the default, whose own overlay of this document holds copy (ruling R2). */
+  translated?: string[]
+}
+export type MissingReply = { status: 'missing'; manifest: string; tags: string[] }
+export type Reply = DocumentReply | MissingReply
+/** A media reference the platform hydrated on egress: an absolute url, never a bare id. */
+export type SeoMedia = { alt: string; url: null | string }
+
+/** The seven days `openingHoursSpecification` addresses, spelled the way schema.org wants them. */
+export type OpeningHoursDay = 'friday' | 'monday' | 'saturday' | 'sunday' | 'thursday' | 'tuesday' | 'wednesday'
+
+/**
+ * One day's hours, as stored. `opens`/`closes` are 24-hour `HH:MM`, the format schema.org's own
+ * `opens`/`closes` properties expect, so the emitter never converts. Both are null while `closed`
+ * is true, or while the row is not yet filled in.
+ */
+export type OpeningHoursRow = {
+  closed: boolean
+  closes: null | string
+  day: OpeningHoursDay
+  opens: null | string
+}
+
+/** The organisation half of the site-wide SEO singleton, for JSON-LD and contact metadata. */
+export type SeoOrganisation = {
+  address: null | string
+  email: null | string
+  /**
+   * Free-text hours typed before the structured editor existed ("Mo-Fr 07:00-17:00", "7am-5pm
+   * daily", anything). Never parsed and not shown in the dashboard's editor. It is read only as a
+   * fallback: the organisation JSON-LD emits it verbatim when `openingHours` is empty.
+   */
+  legacyOpeningHours: null | string
+  legalName: null | string
+  logo: null | SeoMedia
+  /** Empty means "not set", as for every other absent field here, not "closed every day". */
+  openingHours: OpeningHoursRow[]
+  phone: null | string
+  sameAs: string[]
+}
+
+/** The site-wide SEO settings, as `/site` answers them. */
+export type SiteReply = {
+  allowIndexing: boolean
+  bingVerification: null | string
+  description: null | string
+  googleVerification: null | string
+  locale: null | string
+  ogImage: null | SeoMedia
+  organisation: null | SeoOrganisation
+  siteName: null | string
+  titleTemplate: null | string
+  twitterCard: 'summary' | 'summary_large_image'
+  twitterHandle: null | string
+  /**
+   * The languages a tenant has configured: the original, the default for a visitor no rule places, the active languages and the
+   * countries mapped to an active language. Absent from a reply when the tenant has no language settings.
+   */
+  languages?: {
+    original: string
+    default: string
+    active: { id: string; prefix: string; name: string }[]
+    /** The prefixes of languages a visitor cannot reach, those inactive or preparing: the proxy sends their addresses to the default's. Absent from a platform before plan 4. */
+    inactive?: { id: string; prefix: string }[]
+    countries: Record<string, string>
+  } | null
+}
+export type SitemapReply = { entries: { path: string; lastModified: string | null; /** A tenant with languages only: the active languages to list this entry in. */ languages?: string[] }[] }
+
+/** JSON with every object's keys sorted, so two equal manifests serialise identically wherever they were built. */
+export const canonicalJson = (value: unknown): string =>
+  JSON.stringify(value, (_key, v: unknown) =>
+    v && typeof v === 'object' && !Array.isArray(v) ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, (v as Record<string, unknown>)[k]])) : v)
+/**
+ * `sha256:<hex>` of a manifest's canonical JSON. The platform sends the hash of the manifest it holds
+ * on every reply, and a site whose own hash differs knows the platform has not yet caught up with a
+ * deploy. Web Crypto, so it runs in Node, the edge and a browser alike.
+ */
+export async function manifestHash(manifest: SiteManifest): Promise<string> {
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(canonicalJson(manifest)))
+  return 'sha256:' + [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('')
+}

package/src/switcher/LanguageSwitcher.tsx

@@ -0,0 +1,42 @@
+'use client'
+
+import { createContext, createElement, useContext, type ReactNode } from 'react'
+import { LANGUAGE_COOKIE, type LanguageLinks } from '../languages/routing'
+
+const LanguageContext = createContext<LanguageLinks | null>(null)
+
+/** Wraps a page rendered in a language site (`render(read, links)`): the page's language and its address in each active one. */
+export function LanguageProvider({ value, children }: { value: LanguageLinks; children?: ReactNode }) {
+  return createElement(LanguageContext.Provider, { value }, children)
+}
+
+/** The page's language and its addresses, or null outside a language site's page. */
+export const useLanguage = (): LanguageLinks | null => useContext(LanguageContext)
+
+/** Remembers a visitor's choice for a year, on the whole site: the proxy reads it on `/` (`u90_lang`). */
+export function rememberLanguage(id: string, doc: Document = document): void {
+  doc.cookie = `${LANGUAGE_COOKIE}=${encodeURIComponent(id)}; Path=/; Max-Age=31536000; SameSite=Lax`
+}
+
+/**
+ * The site's language switcher: the same page in every active language, each by its own name, the one shown marked current.
+ * A plain link, so the next page is a full load and its `<html lang>` is its own. Nothing outside a language site's page, or
+ * with one language. In draft mode its links carry the language in `u90-locale` rather than a prefix (`pageBody` builds them).
+ */
+export function LanguageSwitcher({ label = 'Language', className }: { label?: string; className?: string }) {
+  const value = useLanguage()
+  if (!value || value.links.length < 2) return null
+  return (
+    <nav aria-label={label} className={className}>
+      <ul>
+        {value.links.map((link) => (
+          <li key={link.id}>
+            <a href={link.href} hrefLang={link.id} lang={link.id} aria-current={link.id === value.current ? 'true' : undefined} onClick={() => rememberLanguage(link.id)}>
+              {link.name}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  )
+}

package/src/test-preview/README.md

@@ -0,0 +1,90 @@
+# Existing-deployment test previews
+
+This capability uses a site's current renderer with signed branch content and test feature actions. Install it once on the site; opening a workspace never builds or deploys the site.
+
+## Site installation
+
+Keep the site's normal production `PLATFORM_URL`, `PAYLOAD_API_KEY`, and `SITE_URL`. A trustworthy identity must change on every deployed build, including same-commit redeployments: prefer Vercel's `VERCEL_DEPLOYMENT_ID`, then its generated `VERCEL_URL`; other hosts must inject a unique `U90_TEST_PREVIEW_BUILD_ID` (or pass the same `buildId` option to createU90 and the guard). A commit SHA or a constant environment label is insufficient. Without an identity, capabilities report unsupported and entry refuses. The production service key authenticates only the fixed source trust URL and the private Proxy/build-cookie attestations. It is never sent to a session's branch URL.
+
+Mount the existing `u90.handlers.GET` and `POST` at `app/api/u90/[...u90]/route.ts`. This includes:
+
+- `GET /api/u90/test-preview?token=<signed-site-session>&path=<same-site-path>`: enables draft and stores the signed session in `u90-preview-token`, the existing HTTP-only Secure preview cookie. Test-prefixed cookies are retained for the browser session without a maxAge, so signed expiry leaves an explicit refusal marker until exit, re-entry, or browser-session end. Ordinary draft cookies retain their existing twelve-hour maxAge. An ancillary `u90-test-preview-binding` HTTP-only Secure cookie authenticates the actual Next bypass value, the session hash, canonical site origin and deployed build identity; it expires with the signed session. No revalidation secret is accepted or required. Redirects with `u90test=1` to detect failed cookie setup.
+- `GET /api/u90/test-preview-capabilities`: requires authenticated evidence that the guard ran for this request.
+- `GET /api/u90/exit-preview`: removes the preview cookie, ancillary binding cookie and Next draft bypass through the existing cleanup adapter, including when the signed session is expired. The validated same-site exit destination loses only the reserved `u90test` landing marker; other query values and the fragment remain intact.
+
+Install the guard **first** in `proxy.ts`, with coverage for **all paths**, including every API and server action. An excluded path is outside this guard. If there are no later Proxy steps:
+
+```ts
+import { testPreviewProxy } from '@unitninety/site-kit/test-preview/server'
+export const proxy = testPreviewProxy()
+export const config = { matcher: '/:path*' }
+```
+
+To compose existing Proxy steps:
+
+```ts
+import { NextResponse } from 'next/server'
+import { testPreviewProxy } from '@unitninety/site-kit/test-preview/server'
+
+export const proxy = testPreviewProxy({
+  env: {
+    PLATFORM_URL: process.env.PLATFORM_URL,
+    PAYLOAD_API_KEY: process.env.PAYLOAD_API_KEY,
+    SITE_URL: process.env.SITE_URL,
+    VERCEL_DEPLOYMENT_ID: process.env.VERCEL_DEPLOYMENT_ID,
+    VERCEL_URL: process.env.VERCEL_URL,
+    U90_TEST_PREVIEW_BUILD_ID: process.env.U90_TEST_PREVIEW_BUILD_ID,
+  },
+  next: async (request, testContext) => {
+    // Test content reads its languages and links from the branch. Skip production
+    // redirect/language snapshots and any custom Proxy side effects in this mode.
+    if (testContext) return NextResponse.next({ request: { headers: request.headers } })
+    // Run existing steps with this sanitized request, preserving its forwarded headers.
+    return NextResponse.next({ request: { headers: request.headers } })
+  },
+})
+export const config = { matcher: '/:path*' }
+```
+
+Always preserve the sanitized forwarded request headers on next/rewrite responses. Native Next may expose an internal localhost origin behind a reverse proxy. Attestations therefore bind the configured trusted `SITE_URL` origin plus the exact pathname/query, method, cookie header and expiry. Forwarded host and user Origin never select this trust boundary. The guard strips incoming attestations, signs a short-lived request-bound attestation using the server credential, and never emits it as an ordinary response header. A capability/entry route reached without the guard refuses even if the caller sends a guessed marker.
+
+Connect the bridge to the same configured runtime:
+
+```tsx
+<U90Bridge testPreview={u90.testPreview}>{children}</U90Bridge>
+```
+
+Server integrations can call `await u90.testPreview()` to decide whether to show a disabled test placeholder. The returned context includes a private signed token: do not serialize it. Client components can read `useEditing().testPreview` from `@unitninety/site-kit/bridge`; it is only a boolean and can safely disable a custom QuoteForm or third-party integration.
+
+## Wire contract
+
+The source must implement `GET {configured PLATFORM_URL}/api/u90/test-preview/trust`, authenticated by its existing site service key, returning exactly:
+
+```ts
+{ version: 1, issuerPublicKey: string, tenantPublicId: string,
+  siteOrigin: string, mediaKey: string }
+```
+
+Trust must bind the authenticated tenant and canonical site origin. The runtime fetch has a total five-second deadline, a 16 KiB body limit, no redirects, one in-flight fetch and one cached trust record per runtime connection, expiring after five minutes. Every session verification uses current epoch seconds and Task 1's Ed25519 protocol. Invalid/expired test prefixes refuse; they never become ordinary draft tokens.
+
+Capabilities return:
+
+```ts
+{ version: 1, protocol: 'u90tp1', guard: true, supported: boolean,
+  reason?: 'build_identity_unavailable' | 'draft_binding_unavailable' | 'draft_mode_check_unavailable',
+  actions: readonly string[], manifestHash: string, deploymentId: string | null }
+```
+
+`actions` are supported POST paths: `/api/u90/features/v1/session`, `/verify`, `/feedback`, `/ask-ai/messages`, and `/ask-ai/messages/:id/rating` (the latter four relative to the same feature prefix). Reads allow config, search and validated conversation recovery. `deploymentId` is the selected unique deployed-build identity, otherwise null. Unsupported capabilities return `supported: false`, a setup reason, and an empty action list. The controller must require `supported: true`; guard presence alone is insufficient. Commit SHA is never used for the safety binding. [Vercel documents its unique deployment identifier as available at build and runtime](https://vercel.com/docs/environment-variables/system-environment-variables). Compare `manifestHash` with the branch's copied declaration before allowing editing.
+
+`createTestPreviewRuntime({ env, fetch?, now?, trustTimeoutMs? }).resolve(token)` returns `TestPreviewContext | null`; null means an ordinary credential, and invalid test credentials throw `TestPreviewRefused`. `now` is integer epoch seconds. `testPreviewProxy` accepts the same options plus `next(request, context)`; defaults use the three site environment variables. `createU90` shares its runtime between reads/handlers and accepts `testPreview: {now?, trustTimeoutMs?, buildId?}` for controlled adapters.
+
+Custom test-aware draft adapters must provide `draft()` and `draftEnabled()`, plus entry-only `draftBinding()` (returns the actual bypass value after enabling draft) and `enableDraftBinding(binding, maxAge)`. `disableDraft()` must clear both preview cookies and the Next bypass. These added adapter methods are optional in the public type for compatibility; the shipped native adapter implements them. `draftEnabled()` is a cookie-free lightweight boolean check that runs inside a Next `use cache` scope. An injected custom `draft` adapter without `draftEnabled` is unsupported: authenticated capabilities report `reason: "draft_mode_check_unavailable"`, no editable actions, and entry refuses before enabling draft. All public reads, including site/languages/page/metadata, and feature handlers refuse test-prefixed credentials even when no test options or binding overrides were supplied. Ordinary legacy credentials still work. Only the legacy `html()` root-attribute helper retains its published-only, no-draft behavior via a private language reader; it cannot establish an editable test. The native production path retains its cache-scoped check and never calls `cookies()`.
+
+## Limits and browser behavior
+
+Test mode blocks unadapted API routes, server actions, non-read methods outside the named feature actions, and standard analytics routes. Existing downstream CSP policies remain in force alongside the preview policy. Media paths additionally carry the shared sandbox/script prohibition in the Proxy itself, including default Next continuations, so the media response cannot inherit page script permissions. Its page CSP limits network connections to this site, frames and form submissions to none, and its parent frame to the verified branch. Framework scripts/styles/assets and HTTPS images remain available. Verified branch read replies rewrite only their own branch media namespace to the source media key before page/entry/site/SEO images are emitted. The resulting credential-free source path supports Next image optimizer follow-up requests that carry no browser cookie. In active test mode, the media gateway permits only this source key or the session's own branch key; it forwards no site credentials and never follows redirects.
+
+The guard does not sandbox arbitrary custom server code, custom GET routes, side effects hidden in rendering, or routes omitted from its matcher. Audit those integrations and use disabled placeholders. The next callback must skip custom side effects for test context.
+
+Embedded Canvas previews require Next's `__prerender_bypass`, `u90-preview-token`, and `u90-test-preview-binding` cookies. Verified test visitor-session issuance and rotation also use host-only HttpOnly/Secure/SameSite=None cookies; production visitor cookies retain SameSite=Lax. Next creates its bypass cookie without a partitioned flag. Browsers that block third-party cookies may refuse iframe setup; use a top-level test tab or an explicit browser cookie allowance. Entry's `u90test=1` landing marker refuses when the signed cookie is missing, and a signed cookie without a valid bypass/build/session binding also refuses. On a live redeploy, an old binding refuses even if an obsolete bypass cookie is nonempty; enter a new test session against the updated renderer. No cross-browser iframe guarantee is made without browser testing. Expired sessions require a new entry; branch data and edits remain intact.

package/src/test-preview/binding.ts

@@ -0,0 +1,54 @@
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto'
+import type { Env } from '../server/read'
+import type { TestPreviewOptions } from './runtime'
+
+export const PREVIEW_BINDING_COOKIE = 'u90-test-preview-binding'
+/** Host identity must change on every deployed build, including redeploys of the same commit. */
+export function previewBuildId(
+  options: Pick<TestPreviewOptions, 'env' | 'buildId'>,
+): string | null {
+  const value =
+    options.env.VERCEL_DEPLOYMENT_ID ??
+    options.env.VERCEL_URL ??
+    options.buildId ??
+    options.env.U90_TEST_PREVIEW_BUILD_ID
+  return typeof value === 'string' && value.trim().length > 0 && value.length <= 512
+    ? value.trim()
+    : null
+}
+export function createDraftBinding(
+  env: Env,
+  buildId: string,
+  token: string,
+  bypass: string,
+): string {
+  if (!env.PAYLOAD_API_KEY || !env.SITE_URL || !buildId || !bypass)
+    throw new Error('Test preview build binding unavailable')
+  const tokenHash = createHash('sha256').update(token).digest('base64url')
+  const message = JSON.stringify([
+    'u90-test-preview-binding-v1',
+    new URL(env.SITE_URL).origin,
+    buildId,
+    bypass,
+    tokenHash,
+  ])
+  return 'u90tb1.' + createHmac('sha256', env.PAYLOAD_API_KEY).update(message).digest('base64url')
+}
+export function verifyDraftBinding(
+  env: Env,
+  buildId: string | null,
+  token: string,
+  bypass: string | null,
+  binding: string | null,
+): boolean {
+  try {
+    if (!buildId || !bypass || !binding || !/^u90tb1\.[A-Za-z0-9_-]{43}$/.test(binding))
+      return false
+    const expected = createDraftBinding(env, buildId, token, bypass)
+    const a = Buffer.from(binding),
+      b = Buffer.from(expected)
+    return a.length === b.length && timingSafeEqual(a, b)
+  } catch {
+    return false
+  }
+}

package/src/test-preview/bridge.ts

@@ -0,0 +1,16 @@
+import type { NextAdapters } from '../server/adapters'
+import type { TestPreviewContext } from './runtime'
+/** Server-only adapter; returns just safe client props, never the signed session. */
+export async function resolveBridgePreview(options: {
+  platformOrigin: string
+  draft: NextAdapters['draft']
+  resolve: (token: string | null) => Promise<TestPreviewContext | null>
+}) {
+  const draft = await options.draft()
+  const context = await options.resolve(draft.token)
+  return {
+    editing: context ? true : draft.enabled && options.platformOrigin !== '',
+    platformOrigin: context?.platformOrigin ?? options.platformOrigin,
+    testPreview: !!context,
+  }
+}

package/src/test-preview/guard.ts

@@ -0,0 +1,186 @@
+import { MEDIA_SANDBOX } from './media'
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import { PREVIEW_BINDING_COOKIE, previewBuildId, verifyDraftBinding } from './binding'
+import { NextResponse } from 'next/server'
+import { matchAskAiRoute } from '../features/server/http'
+import type { Env } from '../server/read'
+import {
+  createTestPreviewRuntime,
+  EXPECTED_PREVIEW_PARAM,
+  previewResponseHeaders,
+  requestPreviewToken,
+  requestCookie,
+  type TestPreviewOptions,
+  type TestPreviewContext,
+} from './runtime'
+export const GUARD_HEADER = 'x-u90-test-preview-guard'
+export const TEST_PREVIEW_ACTIONS = [
+  '/api/u90/features/v1/session',
+  '/api/u90/features/v1/verify',
+  '/api/u90/features/v1/feedback',
+  '/api/u90/features/v1/ask-ai/messages',
+  '/api/u90/features/v1/ask-ai/messages/:id/rating',
+] as const
+export type TestPreviewCapabilities = {
+  version: 1
+  protocol: 'u90tp1'
+  guard: true
+  supported: boolean
+  reason?:
+    'build_identity_unavailable' | 'draft_binding_unavailable' | 'draft_mode_check_unavailable'
+  actions: readonly string[]
+  manifestHash: string
+  deploymentId: string | null
+}
+// Native Next may expose an internal localhost origin behind a reverse proxy.
+// Bind the configured trusted public origin and exact route/query, never forwarded host.
+const attestationUrl = (request: Request, env: Env) => {
+  const url = new URL(request.url)
+  return new URL(env.SITE_URL!).origin + url.pathname + url.search
+}
+const hmac = (request: Request, env: Env, expires: number) =>
+  createHmac('sha256', env.PAYLOAD_API_KEY!)
+    .update(
+      JSON.stringify([
+        request.method,
+        attestationUrl(request, env),
+        request.headers.get('cookie'),
+        expires,
+      ]),
+    )
+    .digest('base64url')
+export function verifyGuardAttestation(
+  request: Request,
+  env: Env,
+  now = Math.floor(Date.now() / 1000),
+): boolean {
+  try {
+    if (!env.PAYLOAD_API_KEY || !env.SITE_URL) return false
+    const value = request.headers.get(GUARD_HEADER) ?? ''
+    const [time, signature, extra] = value.split('.')
+    const expires = Number(time)
+    if (
+      extra !== undefined ||
+      !Number.isSafeInteger(expires) ||
+      expires <= now ||
+      expires > now + 60 ||
+      !/^[A-Za-z0-9_-]{43}$/.test(signature ?? '')
+    )
+      return false
+    const a = Buffer.from(signature),
+      b = Buffer.from(hmac(request, env, expires))
+    return a.length === b.length && timingSafeEqual(a, b)
+  } catch {
+    return false
+  }
+}
+export function previewCsp(parent: string): string {
+  return `default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' https: data: blob:; font-src 'self' data:; media-src 'self'; connect-src 'self'; frame-src 'none'; object-src 'none'; base-uri 'self'; form-action 'none'; frame-ancestors ${parent}`
+}
+/** Install first, with a matcher covering every path. `next` composes later Proxy steps using sanitized request headers. */
+export function testPreviewProxy(
+  options: TestPreviewOptions & {
+    next?: (request: Request, context: TestPreviewContext | null) => Response | Promise<Response>
+  } = {
+    env: {
+      PLATFORM_URL: process.env.PLATFORM_URL,
+      PAYLOAD_API_KEY: process.env.PAYLOAD_API_KEY,
+      SITE_URL: process.env.SITE_URL,
+      VERCEL_DEPLOYMENT_ID: process.env.VERCEL_DEPLOYMENT_ID,
+      VERCEL_URL: process.env.VERCEL_URL,
+      U90_TEST_PREVIEW_BUILD_ID: process.env.U90_TEST_PREVIEW_BUILD_ID,
+    },
+  },
+) {
+  const runtime = createTestPreviewRuntime(options)
+  const now = options.now ?? (() => Math.floor(Date.now() / 1000))
+  return async (incoming: Request): Promise<Response> => {
+    const headers = new Headers(incoming.headers)
+    headers.delete(GUARD_HEADER)
+    const request = new Request(incoming, { headers })
+    const url = new URL(request.url)
+    const path = url.pathname
+    const setup = [
+      '/api/u90/test-preview',
+      '/api/u90/test-preview-capabilities',
+      '/api/u90/exit-preview',
+    ].includes(path)
+    const refused = () =>
+      new Response(
+        'Test preview refused. Open a new test session; allow preview cookies or use a top-level test tab.',
+        { status: 403, headers: previewResponseHeaders },
+      )
+    let delegated = false
+    try {
+      // Recovery and capability checks remain reachable with expired credentials.
+      const context = setup ? null : await runtime.resolve(requestPreviewToken(request))
+      if (!setup && url.searchParams.get(EXPECTED_PREVIEW_PARAM) === '1' && !context)
+        return refused()
+      if (context) {
+        // A nonempty bypass is insufficient: Next rotates its opaque value on every build.
+        // Entry binds the actual bypass to the host-unique deployment and signed session.
+        if (
+          !verifyDraftBinding(
+            options.env,
+            previewBuildId(options),
+            context.token,
+            requestCookie(request, '__prerender_bypass'),
+            requestCookie(request, PREVIEW_BINDING_COOKIE),
+          )
+        )
+          return refused()
+        let decoded = path
+        for (let i = 0; i < 3 && decoded.includes('%'); i++) decoded = decodeURIComponent(decoded)
+        if (decoded.includes('%')) return refused()
+        const normalized = new URL(decoded.replaceAll('\\', '/'), url.origin).pathname.toLowerCase()
+        const read = request.method === 'GET' || request.method === 'HEAD'
+        const featureRead =
+          ['/api/u90/features/v1/config', '/api/u90/features/v1/search'].includes(path) ||
+          matchAskAiRoute(request.method, url)?.operation === 'conversation'
+        const featureWrite =
+          request.method === 'POST' &&
+          ([
+            '/api/u90/features/v1/session',
+            '/api/u90/features/v1/verify',
+            '/api/u90/features/v1/feedback',
+          ].includes(path) ||
+            !!matchAskAiRoute(request.method, url))
+        const media = /^\/api\/u90\/media\//.test(path)
+        if (
+          request.headers.has('next-action') ||
+          /(?:^|\/)(?:analytics|_vercel|_next\/analytics)(?:\/|$)/i.test(normalized) ||
+          (/^\/api(?:\/|$)/.test(normalized) &&
+            !((read && (featureRead || media)) || featureWrite)) ||
+          (!read && !featureWrite)
+        )
+          return refused()
+      }
+      if (setup && request.method !== 'GET') return refused()
+      if (options.env.PAYLOAD_API_KEY && (setup || context)) {
+        const expires = now() + 60
+        headers.set(GUARD_HEADER, `${expires}.${hmac(request, options.env, expires)}`)
+      }
+      const forwarded = new Request(request, { headers })
+      delegated = true
+      const response = await (options.next
+        ? options.next(forwarded, context)
+        : NextResponse.next({ request: { headers } }))
+      // Attestation is an internal request header, never a response header.
+      response.headers.delete(GUARD_HEADER)
+      if (context || setup)
+        for (const [key, value] of Object.entries(previewResponseHeaders))
+          response.headers.set(key, value)
+      if (context) {
+        // Multiple CSP policies intersect. Preserve downstream restrictions, and carry the
+        // media sandbox even when NextResponse.next() has not seen the eventual media response.
+        if (/^\/api\/u90\/media\//.test(path))
+          response.headers.append('content-security-policy', MEDIA_SANDBOX)
+        response.headers.append('content-security-policy', previewCsp(context.platformOrigin))
+      }
+      return response
+    } catch (error) {
+      if (delegated) throw error
+      return refused()
+    }
+  }
+}

package/src/test-preview/media.ts

@@ -0,0 +1,23 @@
+import type { TestPreviewContext } from './runtime'
+
+/** Restrictive policy for source media, shared by the gateway and Proxy continuation. */
+export const MEDIA_SANDBOX = "sandbox; default-src 'none'; script-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
+
+/** Translate only this verified branch namespace in JSON replies. URLs contain no session credential. */
+export function sourceMediaPaths<T>(value: T, context: TestPreviewContext): T {
+  const branchPrefix = `/api/u90/media/${context.claims.branchMediaKey}/`
+  const sourcePrefix = `/api/u90/media/${context.trust.mediaKey}/`
+  const visit = (input: unknown): unknown => {
+    if (typeof input === 'string') {
+      for (const prefix of [branchPrefix, context.platformOrigin + branchPrefix]) {
+        if (input.startsWith(prefix)) return sourcePrefix + input.slice(prefix.length)
+      }
+      return input
+    }
+    if (Array.isArray(input)) return input.map(visit)
+    if (input !== null && typeof input === 'object')
+      return Object.fromEntries(Object.entries(input).map(([key, child]) => [key, visit(child)]))
+    return input
+  }
+  return visit(value) as T
+}

package/src/test-preview/protocol.d.mts

@@ -0,0 +1,67 @@
+/** Canonical Ed25519 DER keys encoded as unpadded base64url. */
+export interface PreviewKeyPair {
+  privateKey: string
+  publicKey: string
+}
+
+export interface EnvironmentCertificate {
+  version: 1
+  environmentId: string
+  platformOrigin: string
+  sourceOrigin: string
+  publicKey: string
+  /** Integer epoch seconds. */
+  issuedAt: number
+  /** Integer epoch seconds; at most 604800 seconds after issuance. */
+  expiresAt: number
+}
+
+interface BasePreviewClaims {
+  version: 1
+  tenantPublicId: string
+  nonce: string
+  /** Integer epoch seconds. */
+  issuedAt: number
+  /** Integer epoch seconds; at most 900 seconds after issuance. */
+  expiresAt: number
+}
+
+export interface ReferencePreviewClaims extends BasePreviewClaims {
+  purpose: 'reference'
+  siteOrigin?: never
+  branchMediaKey?: never
+}
+
+export interface SitePreviewClaims extends BasePreviewClaims {
+  purpose: 'site'
+  siteOrigin: string
+  branchMediaKey: string
+}
+
+export type PreviewClaims = ReferencePreviewClaims | SitePreviewClaims
+
+export interface VerifyPreviewSessionOptions {
+  issuerPublicKey: string
+  purpose: PreviewClaims['purpose']
+  sourceOrigin?: string
+  platformOrigin?: string
+  siteOrigin?: string
+  tenantPublicId?: string
+  /** Override current time using integer epoch seconds. */
+  now?: number
+}
+
+export function generatePreviewKeyPair(): PreviewKeyPair
+export function signEnvironmentCertificate(claims: EnvironmentCertificate, privateKey: string): string
+export function verifyEnvironmentCertificate(
+  certificate: string,
+  publicKey: string,
+  options?: { now?: number },
+): EnvironmentCertificate
+export function signPreviewSession(claims: PreviewClaims, certificate: string, privateKey: string): string
+export function verifyPreviewSession(
+  token: string,
+  options: VerifyPreviewSessionOptions,
+): { certificate: EnvironmentCertificate; claims: PreviewClaims }
+/** Includes malformed test-prefixed credentials that must fail closed. */
+export function isTestPreviewToken(value: unknown): boolean