@weaverse/next 0.1.0-alpha.13 → 0.1.0-alpha.15

package/src/server/configs.ts

@@ -0,0 +1,182 @@
+import type {
+  WeaverseNextBaseConfigs,
+  WeaverseNextRequestContext,
+} from '../types'
+
+const DEFAULT_WEAVERSE_HOST = 'https://studio.weaverse.io'
+const DEFAULT_WEAVERSE_API_BASE = 'https://api.weaverse.io'
+
+/**
+ * Weaverse-controlled apex domains the Studio bridge / data API may be served
+ * from (matched on the host itself and any subdomain). Kept in sync with
+ * Hydrogen's `isTrustedStudioHost`.
+ */
+const TRUSTED_STUDIO_DOMAINS = ['weaverse.io', 'weaverse.dev']
+
+/**
+ * Whether `host` is an origin we trust to resolve page/theme data. The
+ * `weaverseHost` query param is attacker-controllable, so a crafted
+ * `?weaverseHost=` must be rejected before it can point server-side fetches at
+ * an arbitrary origin (SSRF). Only `weaverse.io`/`weaverse.dev` and subdomains
+ * over https are trusted.
+ */
+function isTrustedStudioHost(host: string): boolean {
+  let parsed: URL
+  try {
+    parsed = new URL(host)
+  } catch {
+    return false
+  }
+  if (parsed.protocol !== 'https:') {
+    return false
+  }
+  let { hostname } = parsed
+  return TRUSTED_STUDIO_DOMAINS.some(
+    (domain) => hostname === domain || hostname.endsWith(`.${domain}`)
+  )
+}
+
+function toUrl(value: string | URL): URL | null {
+  try {
+    return typeof value === 'string'
+      ? new URL(value, 'http://localhost')
+      : value
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Extract the request search params from the explicit Next request context.
+ * Prefers `searchParams`, falls back to parsing `url`.
+ */
+export function getContextSearchParams(
+  context?: WeaverseNextRequestContext
+): URLSearchParams {
+  if (context?.searchParams) {
+    return new URLSearchParams(context.searchParams)
+  }
+  if (context?.url) {
+    let url = toUrl(context.url)
+    if (url) {
+      return new URLSearchParams(url.searchParams)
+    }
+  }
+  return new URLSearchParams()
+}
+
+/**
+ * Last value of a (possibly duplicated) query key. Matches Hydrogen's
+ * `getRequestQueries`, which assigns while iterating and so keeps the last
+ * occurrence — Studio appends its own control params, so a stale earlier value
+ * must not win.
+ */
+function lastParam(
+  searchParams: URLSearchParams,
+  key: string
+): string | undefined {
+  let values = searchParams.getAll(key)
+  return values.length ? values.at(-1) : undefined
+}
+
+function coerceBool(value: string | undefined): boolean {
+  return value === 'true'
+}
+
+function readEnv(
+  env: Record<string, string | undefined> | undefined,
+  key: string
+): string | undefined {
+  let fromConfig = env?.[key]
+  if (fromConfig !== undefined) {
+    return fromConfig
+  }
+  if (typeof process !== 'undefined' && process.env) {
+    return process.env[key]
+  }
+  return
+}
+
+/** Overrides used while resolving request-scoped Weaverse configuration. */
+export interface ResolveConfigsOptions {
+  /** Environment values; missing keys fall back to `process.env`. */
+  env?: Record<string, string | undefined>
+  /** Public data API base override. */
+  weaverseApiBase?: string
+  /** Studio origin override. */
+  weaverseHost?: string
+  /** Studio asset version override. */
+  weaverseVersion?: string
+}
+
+/**
+ * Derive Weaverse configs from the request context and env, close to Hydrogen's
+ * `getWeaverseConfigs`. Resolves the trusted host, public API base, design /
+ * preview / revision flags, and public env — but never resolves the final
+ * `projectId` (that priority chain, which may call an async resolver, lives in
+ * the server client). Query/env projectId candidates are returned for the
+ * client to combine with function/string inputs.
+ */
+export function getWeaverseNextConfigs(
+  context?: WeaverseNextRequestContext,
+  options: ResolveConfigsOptions = {}
+): WeaverseNextBaseConfigs {
+  let searchParams = getContextSearchParams(context)
+  let { env } = options
+
+  let queryHost = lastParam(searchParams, 'weaverseHost')
+  // A trusted query host is canonicalized to its origin before use, so a crafted
+  // `?weaverseHost=https://studio.weaverse.io/evil?x=1` can only ever resolve to
+  // `https://studio.weaverse.io` — never carrying an attacker path/query into the
+  // server-side API base.
+  let trustedUrlHost =
+    queryHost && isTrustedStudioHost(queryHost) ? new URL(queryHost).origin : ''
+
+  let configuredHost =
+    options.weaverseHost || readEnv(env, 'WEAVERSE_HOST') || ''
+  let weaverseHost = trustedUrlHost || configuredHost || DEFAULT_WEAVERSE_HOST
+
+  // Public data reads default to the edge proxy, but an explicit custom host
+  // (staging/self-hosted Weaverse) must stay the API base so those deployments
+  // don't fetch page/config data from the production proxy.
+  let weaverseApiBase =
+    trustedUrlHost ||
+    options.weaverseApiBase ||
+    readEnv(env, 'WEAVERSE_PUBLIC_API_BASE') ||
+    (configuredHost && configuredHost !== DEFAULT_WEAVERSE_HOST
+      ? configuredHost
+      : DEFAULT_WEAVERSE_API_BASE)
+
+  let isRevisionPreview =
+    context?.isRevisionPreview ?? searchParams.has('__revisionId')
+  let isDesignMode =
+    context?.isDesignMode ?? coerceBool(lastParam(searchParams, 'isDesignMode'))
+  let isPreviewMode =
+    context?.isPreviewMode ??
+    coerceBool(lastParam(searchParams, 'isPreviewMode'))
+
+  return {
+    queryProjectId: lastParam(searchParams, 'weaverseProjectId') || '',
+    envProjectId: readEnv(env, 'WEAVERSE_PROJECT_ID') || '',
+    weaverseHost,
+    weaverseApiBase,
+    weaverseApiKey:
+      lastParam(searchParams, 'weaverseApiKey') ||
+      readEnv(env, 'WEAVERSE_API_KEY') ||
+      '',
+    weaverseVersion:
+      lastParam(searchParams, 'weaverseVersion') ||
+      options.weaverseVersion ||
+      '',
+    isDesignMode,
+    isPreviewMode,
+    isRevisionPreview,
+    sectionType:
+      context?.sectionType || lastParam(searchParams, 'sectionType') || '',
+    publicEnv: {
+      PUBLIC_STORE_DOMAIN: readEnv(env, 'PUBLIC_STORE_DOMAIN') || '',
+      PUBLIC_STOREFRONT_API_TOKEN:
+        readEnv(env, 'PUBLIC_STOREFRONT_API_TOKEN') || '',
+    },
+  }
+}

package/src/server/normalize-page-url.ts

@@ -0,0 +1,65 @@
+import type { WeaverseNextRequestContext } from '../types'
+
+// Query params that influence Weaverse page resolution on the Builder:
+// revision previews, design-mode flags, design-mode draft item overrides,
+// and `weaverse*` control params (host, version, project id). Everything
+// else — utm_*, fbclid, gclid, storefront filters — is irrelevant to which
+// page the Builder returns and would otherwise fragment any fetch cache keyed
+// on the request body. `weaverseDraftItem` is the current draft item param;
+// `__weaverseDraftItem` is kept as a legacy compatibility alias.
+const KEPT_PARAM_RE =
+  /^(?:__revisionId|__weaverseDraftItem|isDesignMode|weaverse)/
+const DATA_SUFFIX = '.data'
+
+/**
+ * Normalize the storefront URL sent in the Builder page API request body.
+ *
+ * The Builder reads only the pathname (locale/type/handle fallback) and the
+ * Weaverse/Studio control params from this URL, so keep exactly those and drop
+ * tracking params. Params are sorted for a stable, cache-friendly string.
+ *
+ * Ported from `@weaverse/hydrogen`'s `normalizePageUrl`, but tolerant of a
+ * relative URL (Next route handlers may only know the pathname).
+ */
+export function normalizeNextPageUrl(url: string): string {
+  let parsed: URL
+  try {
+    parsed = new URL(url)
+  } catch {
+    try {
+      parsed = new URL(url, 'http://localhost')
+    } catch {
+      return url
+    }
+  }
+
+  let kept = [...parsed.searchParams].filter(([key]) => KEPT_PARAM_RE.test(key))
+  kept.sort(([a], [b]) => a.localeCompare(b))
+  let search = new URLSearchParams(kept).toString()
+
+  let { pathname } = parsed
+  if (pathname.endsWith(DATA_SUFFIX)) {
+    pathname = pathname.slice(0, -DATA_SUFFIX.length)
+  }
+  return `${parsed.origin}${pathname}${search ? `?${search}` : ''}`
+}
+
+/**
+ * Build an absolute-ish request URL string from the explicit request context,
+ * preferring `url`, then `pathname` + `searchParams`. Used as the input to
+ * {@link normalizeNextPageUrl}.
+ */
+export function resolveRequestUrl(
+  context?: WeaverseNextRequestContext
+): string {
+  if (context?.url) {
+    return typeof context.url === 'string'
+      ? context.url
+      : context.url.toString()
+  }
+  let pathname = context?.pathname || '/'
+  let search = context?.searchParams
+    ? new URLSearchParams(context.searchParams).toString()
+    : ''
+  return `http://localhost${pathname}${search ? `?${search}` : ''}`
+}

package/src/server/revalidate-handler.ts

@@ -0,0 +1,357 @@
+import type { PageType } from '@weaverse/schema'
+import { PageTypeSchema } from '@weaverse/schema'
+import {
+  ROUTE_CONTEXT_I18N_KEYS,
+  sanitizeRouteContextSearch,
+  type WeaverseNextRevalidateRouteContext,
+} from '../revalidate-item'
+import type {
+  WeaverseNextComponentData,
+  WeaverseNextI18n,
+  WeaverseNextRequestContext,
+  WeaverseNextServerClient,
+} from '../types'
+import { generateDataFromSchema } from '../utils'
+
+const NO_STORE_HEADERS = {
+  'Content-Type': 'application/json',
+  'Cache-Control': 'no-store',
+} as const
+
+const STATUS_OK = 200
+const STATUS_BAD_REQUEST = 400
+const STATUS_NOT_FOUND = 404
+const STATUS_UNPROCESSABLE = 422
+const STATUS_SERVER_ERROR = 500
+
+const MAX_PATHNAME_LENGTH = 2048
+const MAX_SEARCH_LENGTH = 8192
+const MAX_HANDLE_LENGTH = 512
+const MAX_I18N_FIELD_LENGTH = 256
+// ASCII control characters (C0 range + DEL) are never valid in a route path.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: rejecting control chars in untrusted pathnames is the intent.
+const CONTROL_CHAR_PATTERN = /[\u0000-\u001F\u007F]/
+
+/** Configuration for the App Router item-revalidation handler. */
+export interface WeaverseNextRevalidateHandlerConfig {
+  /**
+   * Reuse the app's server-client factory so the loader runs with the same
+   * component registry and commerce (storefront) context as page loads.
+   *
+   * The optional second argument is the validated, same-origin route context
+   * reconstructed from the request body. It is `undefined` for legacy bodies
+   * that carry no `routeContext`, so a one-argument `(request) => client`
+   * callback remains valid. Consumers must still source project ID, Studio
+   * host, API bases/keys, and env from server config — never from this
+   * browser-provided context.
+   */
+  getClient: (
+    request: Request,
+    requestContext?: WeaverseNextRequestContext
+  ) => Promise<WeaverseNextServerClient> | WeaverseNextServerClient
+}
+
+/** POST body accepted by the revalidate route. */
+export interface WeaverseNextRevalidateRequestBody {
+  /** Unsaved Studio item settings to pass to the registered component loader. */
+  draftItem: WeaverseNextComponentData
+  /** Public route identity used to reconstruct the loader request context. */
+  routeContext?: WeaverseNextRevalidateRouteContext
+}
+
+/**
+ * Whether a browser-provided pathname is safe to reconstruct a same-origin URL
+ * from. Rejects protocol-relative (`//`), absolute-URL, backslash, control
+ * character, query-in-path, and fragment-in-path inputs before any URL is
+ * built. Literal/encoded dot segments are allowed here and normalized later by
+ * the URL pathname setter.
+ */
+function isValidPathname(pathname: string): boolean {
+  if (!pathname || pathname.length > MAX_PATHNAME_LENGTH) {
+    return false
+  }
+  if (pathname[0] !== '/' || pathname.startsWith('//')) {
+    return false
+  }
+  if (pathname.includes('\\') || pathname.includes('?')) {
+    return false
+  }
+  if (pathname.includes('#') || CONTROL_CHAR_PATTERN.test(pathname)) {
+    return false
+  }
+  return true
+}
+
+/**
+ * Whether a value is a plain object (literal or `null`-prototype), the only
+ * i18n container the wire shape allows. Arrays, class instances, and other
+ * exotic objects are rejected so nothing exotic reaches field validation.
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return false
+  }
+  let proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
+
+/**
+ * Validate and pick the allowed i18n fields. Returns `undefined` for a valid
+ * empty result and `null` for malformed input so the handler can fail closed.
+ *
+ * The normative i18n shape carries only the {@link ROUTE_CONTEXT_I18N_KEYS}.
+ * Malformed input is rejected rather than silently narrowed: any unknown own
+ * key (nested object, extra string, anything), a non-plain container (array,
+ * class instance), or a known key whose value is not an optional string of at
+ * most {@link MAX_I18N_FIELD_LENGTH} characters fails closed.
+ */
+function sanitizeRouteContextI18n(
+  input: unknown
+): WeaverseNextI18n | undefined | null {
+  if (input === undefined) {
+    return
+  }
+  if (!isPlainObject(input)) {
+    return null
+  }
+  let source = input
+  let allowed = new Set<string>(ROUTE_CONTEXT_I18N_KEYS)
+  // Reject unknown own keys instead of dropping them, so a crafted context
+  // cannot smuggle extra properties past the trust boundary.
+  for (let key of Object.keys(source)) {
+    if (!allowed.has(key)) {
+      return null
+    }
+  }
+  let result: Record<string, string> = {}
+  for (let key of ROUTE_CONTEXT_I18N_KEYS) {
+    let value = source[key]
+    if (value === undefined) {
+      continue
+    }
+    if (typeof value !== 'string' || value.length > MAX_I18N_FIELD_LENGTH) {
+      return null
+    }
+    result[key] = value
+  }
+  return Object.keys(result).length ? result : undefined
+}
+
+/**
+ * Reconstruct a validated, same-origin {@link WeaverseNextRequestContext} from
+ * the untrusted route context. Returns `null` for any malformed field so the
+ * handler can answer `400 invalid-route-context` before creating a client. The
+ * endpoint origin is fixed first, then validated components are assigned, so
+ * the browser cannot change protocol, host, port, or credentials.
+ */
+function reconstructRouteContext(
+  request: Request,
+  routeContext: unknown
+): WeaverseNextRequestContext | null {
+  if (
+    typeof routeContext !== 'object' ||
+    routeContext === null ||
+    Array.isArray(routeContext)
+  ) {
+    return null
+  }
+  let { pathname, search, handle, pageType, i18n } = routeContext as Record<
+    string,
+    unknown
+  >
+
+  if (typeof pathname !== 'string' || !isValidPathname(pathname)) {
+    return null
+  }
+
+  if (typeof search !== 'string' || search.length > MAX_SEARCH_LENGTH) {
+    return null
+  }
+  let rawSearch = search
+  if (rawSearch.length && !rawSearch.startsWith('?')) {
+    return null
+  }
+
+  let sanitizedI18n = sanitizeRouteContextI18n(i18n)
+  if (sanitizedI18n === null) {
+    return null
+  }
+
+  let resolvedPageType: PageType | undefined
+  if (pageType !== undefined) {
+    let parsed = PageTypeSchema.safeParse(pageType)
+    if (!parsed.success) {
+      return null
+    }
+    resolvedPageType = parsed.data
+  }
+
+  let resolvedHandle: string | undefined
+  if (handle !== undefined) {
+    if (
+      typeof handle !== 'string' ||
+      !handle ||
+      handle.length > MAX_HANDLE_LENGTH
+    ) {
+      return null
+    }
+    resolvedHandle = handle
+  }
+
+  // Fix the endpoint origin first, then assign validated components. Reuse the
+  // URL's canonical pathname in both context fields so raw input never survives
+  // in only one place.
+  let endpointUrl = new URL(request.url)
+  let routeUrl = new URL(endpointUrl.origin)
+  routeUrl.pathname = pathname
+  routeUrl.search = sanitizeRouteContextSearch(rawSearch)
+  let canonicalPathname = routeUrl.pathname
+  let searchParams = routeUrl.searchParams
+
+  // Last value wins for duplicated Studio controls, matching
+  // `getWeaverseNextConfigs()` and its cache-mode resolution.
+  let lastParam = (key: string): string | undefined => {
+    let values = searchParams.getAll(key)
+    return values.length ? values.at(-1) : undefined
+  }
+
+  return {
+    pathname: canonicalPathname,
+    searchParams,
+    url: routeUrl,
+    // Headers come from the actual same-origin POST, never its JSON body.
+    headers: new Headers(request.headers),
+    ...(sanitizedI18n ? { i18n: sanitizedI18n } : {}),
+    ...(resolvedPageType ? { pageType: resolvedPageType } : {}),
+    ...(resolvedHandle ? { handle: resolvedHandle } : {}),
+    isDesignMode: lastParam('isDesignMode') === 'true',
+    isPreviewMode: lastParam('isPreviewMode') === 'true',
+    isRevisionPreview: searchParams.has('__revisionId'),
+    sectionType: lastParam('sectionType') || undefined,
+  }
+}
+
+function json(body: Record<string, unknown>, status: number) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: NO_STORE_HEADERS,
+  })
+}
+
+function parseDraftItem(payload: unknown): WeaverseNextComponentData | null {
+  if (typeof payload !== 'object' || payload === null) {
+    return null
+  }
+  let draftItem = (payload as { draftItem?: unknown }).draftItem
+  if (typeof draftItem !== 'object' || draftItem === null) {
+    return null
+  }
+  let { id, type } = draftItem as { id?: unknown; type?: unknown }
+  if (typeof id !== 'string' || !id || typeof type !== 'string' || !type) {
+    return null
+  }
+  return draftItem as WeaverseNextComponentData
+}
+
+/** App Router handler returned for Studio item revalidation requests. */
+export interface WeaverseNextRevalidateHandler {
+  /** Handle a Studio request to rerun one registered component loader. */
+  POST: (request: Request) => Promise<Response>
+}
+
+/**
+ * Create the Studio per-item revalidation route handler.
+ *
+ * Studio design-mode edits to loader-backed inputs (e.g. resource pickers) need
+ * fresh server loader data for a single item. Re-running it through
+ * `router.refresh()` re-applies the whole RSC tree — and the draft-item query
+ * rewrite changes the App Router page segment key, remounting the page and
+ * resetting scroll. This handler runs just the edited component's `loader`
+ * with the unsaved draft settings and returns the payload for an in-place
+ * client update (see the `2026-07-02--next-item-revalidation` spec).
+ *
+ * Security: only registered component types are executable, the handler never
+ * persists anything, and responses are `no-store`. Exposure is equivalent to
+ * the existing `weaverseDraftItem` URL param, which already lets any visitor
+ * run design-mode loaders with arbitrary draft settings.
+ *
+ * @example
+ * ```ts
+ * // app/api/weaverse/revalidate/route.ts
+ * export const { POST } = createWeaverseNextRevalidateHandler({
+ *   getClient: () => getWeaverseServerClient(Promise.resolve({})),
+ * })
+ * ```
+ */
+export function createWeaverseNextRevalidateHandler(
+  config: WeaverseNextRevalidateHandlerConfig
+): WeaverseNextRevalidateHandler {
+  return {
+    POST: async (request: Request) => {
+      let payload: unknown
+      try {
+        payload = await request.json()
+      } catch {
+        return json({ error: 'invalid-payload' }, STATUS_BAD_REQUEST)
+      }
+
+      let draftItem = parseDraftItem(payload)
+      if (!draftItem) {
+        return json({ error: 'invalid-payload' }, STATUS_BAD_REQUEST)
+      }
+
+      // Missing `routeContext` is valid legacy input; a present but malformed
+      // context is rejected at the trust boundary before any client is created.
+      let requestContext: WeaverseNextRequestContext | undefined
+      let body = payload as { routeContext?: unknown }
+      if (Object.hasOwn(body, 'routeContext')) {
+        let reconstructed = reconstructRouteContext(request, body.routeContext)
+        if (!reconstructed) {
+          return json({ error: 'invalid-route-context' }, STATUS_BAD_REQUEST)
+        }
+        requestContext = reconstructed
+      }
+
+      let client: WeaverseNextServerClient
+      try {
+        client = await config.getClient(request, requestContext)
+      } catch (error) {
+        console.error('❌ Revalidate handler getClient failed.', error)
+        return json({ error: 'client-init-failed' }, STATUS_SERVER_ERROR)
+      }
+
+      let component = client.components.find(
+        (candidate) => candidate?.schema?.type === draftItem.type
+      )
+      if (!component) {
+        return json({ error: 'unknown-component-type' }, STATUS_NOT_FOUND)
+      }
+      if (typeof component.loader !== 'function') {
+        return json({ error: 'missing-loader' }, STATUS_UNPROCESSABLE)
+      }
+
+      try {
+        // Same args shape as `runWeaverseComponentLoaders`, so component
+        // loaders behave identically between page load and revalidation.
+        let loaderData = await component.loader({
+          data: {
+            ...generateDataFromSchema(component.schema),
+            ...draftItem.data,
+          },
+          weaverse: client,
+          context: client.requestContext,
+          commerce: client.commerce,
+        })
+        return json({ loaderData: loaderData ?? null }, STATUS_OK)
+      } catch (error) {
+        console.error(
+          '❌ Item loader revalidation failed.',
+          draftItem.type,
+          draftItem.id,
+          error
+        )
+        return json({ error: 'loader-failed' }, STATUS_SERVER_ERROR)
+      }
+    },
+  }
+}