@unitninety/site-kit 0.0.0-stage → 1.6.1

package/src/preview-lock/server.ts

@@ -0,0 +1,416 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  createHmac,
+  randomBytes,
+  randomUUID,
+  timingSafeEqual,
+} from 'node:crypto'
+import { ACCESS_COOKIE, HANDOFF_QUERY, LOCK_ENDPOINT, LOCK_PATH, safeReturnTo } from './contracts'
+import type { PreviewLockAppearance, PreviewLockStatus } from './contracts'
+
+export type PreviewLockOptions = {
+  platformUrl: string
+  apiKey: string
+  revalidateSecret: string
+  fetch?: typeof fetch
+  publicAssets?: readonly string[]
+}
+export type PreviewLockGate =
+  | { kind: 'response'; response: Response }
+  | { kind: 'next'; headers: Headers; requestHeaders: Headers; url: string }
+const PRIVATE = {
+  'cache-control': 'private, no-store, max-age=0',
+  'x-robots-tag': 'noindex, nofollow, noarchive',
+  'referrer-policy': 'no-referrer',
+}
+const equal = (a: string, b: string) => {
+  const x = Buffer.from(a),
+    y = Buffer.from(b)
+  return x.length === y.length && timingSafeEqual(x, y)
+}
+const json = (body: unknown, status = 200, headers: Record<string, string> = {}) =>
+  Response.json(body, { status, headers: { ...PRIVATE, ...headers } })
+const unavailable = () =>
+  json({ ok: false, error: 'Preview verification is unavailable. Please try again.' }, 503)
+const tokenLike = (value: unknown): value is string =>
+  typeof value === 'string' && /^[A-Za-z0-9_.-]{1,4096}$/.test(value)
+function cookie(request: Request, name: string): string | null {
+  const values = (request.headers.get('cookie') ?? '')
+    .split(';')
+    .map((x) => x.trim())
+    .filter((x) => x.startsWith(name + '='))
+  if (values.length !== 1) return null
+  const value = values[0].slice(name.length + 1)
+  return tokenLike(value) ? value : null
+}
+function statusValue(raw: unknown): PreviewLockStatus {
+  if (!raw || typeof raw !== 'object') throw Error('Invalid status')
+  const v = raw as PreviewLockStatus
+  if (
+    !['open', 'locked'].includes(v.state) ||
+    typeof v.protected !== 'boolean' ||
+    (v.state === 'locked' && !v.protected)
+  )
+    throw Error('Invalid status')
+  if (v.canvasVerified !== undefined && typeof v.canvasVerified !== 'boolean')
+    throw Error('Invalid Canvas proof')
+  if (v.appearance !== undefined) {
+    const a = v.appearance
+    for (const key of [
+      'partnerName',
+      'prospectName',
+      'heading',
+      'message',
+      'instructions',
+      'backgroundColor',
+      'textColor',
+      'accentColor',
+    ] as const)
+      if (typeof a[key] !== 'string' || a[key].length > 4096) throw Error('Invalid appearance')
+    for (const key of ['partnerLogoUrl', 'prospectLogoUrl'] as const)
+      if (a[key] !== null && (typeof a[key] !== 'string' || a[key]!.length > 2048))
+        throw Error('Invalid logo')
+    for (const key of ['backgroundColor', 'textColor', 'accentColor'] as const)
+      if (!/^#[\da-f]{6}$/i.test(a[key])) throw Error('Invalid colour')
+  }
+  if (v.state === 'locked' && !v.appearance) throw Error('Missing appearance')
+  return v
+}
+async function boundedJSON(response: Response, limit = 16384): Promise<unknown> {
+  if (Number(response.headers.get('content-length') ?? 0) > limit || !response.body)
+    throw Error('Invalid body')
+  const reader = response.body.getReader(),
+    parts: Uint8Array[] = []
+  let length = 0
+  try {
+    for (;;) {
+      const { value, done } = await reader.read()
+      if (done) break
+      length += value.byteLength
+      if (length > limit) {
+        await reader.cancel()
+        throw Error('Body too large')
+      }
+      parts.push(value)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+  return JSON.parse(Buffer.concat(parts).toString('utf8'))
+}
+
+/** Opt-in server boundary. Importing ordinary site-kit exports does not install this gate. */
+export function createPreviewLock(options: PreviewLockOptions) {
+  const base = new URL(options.platformUrl.replace(/\/$/, '') + '/')
+  if (!['https:', 'http:'].includes(base.protocol) || !options.apiKey || !options.revalidateSecret)
+    throw Error('Preview lock configuration is incomplete')
+  const endpoint = new URL('api/u90/preview-lock', base),
+    fetcher = options.fetch ?? globalThis.fetch
+  const publicAssets = new Set(options.publicAssets ?? [])
+  for (const path of publicAssets)
+    if (
+      safeReturnTo(path) !== path ||
+      path.includes('?') ||
+      path.includes('#') ||
+      path.startsWith('/api/') ||
+      !/\.(?:svg|png|jpe?g|gif|webp|avif|ico|woff2?|ttf|otf)$/i.test(path)
+    )
+      throw Error('Public branding assets must be exact local asset paths')
+  const key = createHash('sha256')
+    .update('u90-site-preview-handoff:v1:' + options.revalidateSecret)
+    .digest()
+  const mac = (v: string) => createHmac('sha256', key).update(v).digest('base64url')
+  function visitor(request: Request) {
+    const [id, signature] = (cookie(request, 'u90-preview-visitor') ?? '').split('.')
+    const authenticated = !!id && !!signature && equal(signature, mac(id))
+    const value = authenticated ? id : randomUUID()
+    return {
+      id: value,
+      authenticated,
+      cookie: `u90-preview-visitor=${value}.${mac(value)}; Path=/; HttpOnly; SameSite=Lax; Max-Age=86400${new URL(request.url).protocol === 'https:' ? '; Secure' : ''}`,
+    }
+  }
+  async function remote(init: RequestInit): Promise<{ response: Response; body: unknown }> {
+    const controller = new AbortController()
+    let timer: ReturnType<typeof setTimeout> | undefined
+    try {
+      return await Promise.race([
+        (async () => {
+          const response = await fetcher(endpoint, {
+            ...init,
+            cache: 'no-store',
+            redirect: 'error',
+            signal: controller.signal,
+            headers: {
+              authorization: `Bearer ${options.apiKey}`,
+              ...Object.fromEntries(new Headers(init.headers)),
+            },
+          })
+          return { response, body: await boundedJSON(response) }
+        })(),
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(() => {
+            controller.abort()
+            reject(Error('Timeout'))
+          }, 3000)
+        }),
+      ])
+    } finally {
+      if (timer) clearTimeout(timer)
+    }
+  }
+  function handoff(request: Request): string | null {
+    const url = new URL(request.url),
+      encoded = url.searchParams.get(HANDOFF_QUERY)
+    if (!encoded || encoded.length > 8192) return null
+    try {
+      const [iv, data, tag, ...rest] = encoded.split('.')
+      if (rest.length) return null
+      const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(iv, 'base64url'))
+      decipher.setAuthTag(Buffer.from(tag, 'base64url'))
+      const payload = JSON.parse(
+        Buffer.concat([
+          decipher.update(Buffer.from(data, 'base64url')),
+          decipher.final(),
+        ]).toString(),
+      )
+      if (
+        !tokenLike(payload.token) ||
+        !Number.isFinite(payload.exp) ||
+        payload.exp <= Date.now() ||
+        payload.exp > Date.now() + 60000 ||
+        payload.path !== safeReturnTo(url.pathname + url.search)
+      )
+        return null
+      return payload.token
+    } catch {
+      return null
+    }
+  }
+  async function status(request: Request): Promise<PreviewLockStatus> {
+    const preview = handoff(request) ?? cookie(request, 'u90-preview-token'),
+      access = cookie(request, ACCESS_COOKIE)
+    const { response, body } = await remote({
+      method: 'GET',
+      headers: {
+        ...(preview ? { 'X-U90-Preview-Token': preview } : {}),
+        ...(access ? { 'X-U90-Preview-Access': access } : {}),
+      },
+    })
+    if (!response.ok) throw Error('Status unavailable')
+    return statusValue(body)
+  }
+  /** Opt-in draft adapter: verified Canvas access also works without Next's draft-mode cookie. */
+  async function draft(request: Request): Promise<{ enabled: boolean; token: string | null }> {
+    const token = handoff(request) ?? cookie(request, 'u90-preview-token')
+    if (!token?.startsWith('u90pt1.')) return { enabled: false, token: null }
+    const current = await status(request)
+    return current.canvasVerified === true
+      ? { enabled: true, token }
+      : { enabled: false, token: null }
+  }
+  async function gate(request: Request): Promise<PreviewLockGate> {
+    const url = new URL(request.url),
+      path = url.pathname
+    const requestHeaders = new Headers(request.headers)
+    for (const name of ['x-u90-preview-token', 'x-u90-preview-access']) requestHeaders.delete(name)
+    const next = (headers: Record<string, string> = {}): PreviewLockGate => {
+      url.searchParams.delete(HANDOFF_QUERY)
+      return { kind: 'next', headers: new Headers(headers), requestHeaders, url: url.href }
+    }
+    if (path === LOCK_ENDPOINT && request.method === 'GET')
+      return {
+        kind: 'response',
+        response: equal(
+          request.headers.get('authorization') ?? '',
+          `Bearer ${options.revalidateSecret}`,
+        )
+          ? json({ ready: true, version: 1 })
+          : json({ error: 'Unauthorised' }, 401),
+      }
+    if (path === LOCK_ENDPOINT && request.method === 'POST') return next(PRIVATE)
+    if (
+      [
+        '/api/u90/preview',
+        '/api/u90/revalidate',
+        '/api/u90/exit-preview',
+        '/api/u90/manifest',
+      ].includes(path)
+    )
+      return next(PRIVATE)
+    if (
+      (request.method === 'GET' || request.method === 'HEAD') &&
+      (path.startsWith('/_next/static/') ||
+        path === '/_next/webpack-hmr' ||
+        path === '/favicon.ico' ||
+        publicAssets.has(path))
+    )
+      return next()
+    let current: PreviewLockStatus
+    try {
+      current = await status(request)
+    } catch {
+      return { kind: 'response', response: unavailable() }
+    }
+    if (path === LOCK_PATH) {
+      const entry = next(current.protected ? PRIVATE : {})
+      const identity = visitor(request)
+      if (current.protected && !identity.authenticated && entry.kind === 'next')
+        entry.headers.append('set-cookie', identity.cookie)
+      return entry
+    }
+    if (current.state === 'open') {
+      // Preserve verified Canvas context for layout and draft reads when browser cookies are blocked.
+      // This is a request-only cookie override, never an outgoing cookie or browser bypass flag.
+      const preview = handoff(request)
+      if (preview && current.canvasVerified === true) {
+        const existing = (requestHeaders.get('cookie') ?? '')
+          .split(';')
+          .map((x) => x.trim())
+          .filter((x) => x && !x.startsWith('u90-preview-token='))
+        requestHeaders.set('cookie', [...existing, `u90-preview-token=${preview}`].join('; '))
+      }
+      return next(current.protected || current.canvasVerified === true ? PRIVATE : {})
+    }
+    if (path.startsWith('/api/') || !['GET', 'HEAD'].includes(request.method))
+      return { kind: 'response', response: json({ error: 'Preview access required' }, 423) }
+    const destination = new URL(LOCK_PATH, url.origin)
+    destination.searchParams.set('returnTo', safeReturnTo(path + url.search))
+    return {
+      kind: 'response',
+      response: new Response(null, {
+        status: 307,
+        headers: { ...PRIVATE, location: destination.href },
+      }),
+    }
+  }
+  async function unlock(request: Request): Promise<Response> {
+    if (request.method !== 'POST') return json({ error: 'Method not allowed' }, 405)
+    const origin = request.headers.get('origin')
+    if (
+      (origin && origin !== new URL(request.url).origin) ||
+      request.headers.get('sec-fetch-site') === 'cross-site'
+    )
+      return json({ error: 'Unauthorised origin' }, 403)
+    let input: { code: string; requestId: string; path: string }
+    try {
+      const raw = (await boundedJSON(
+        new Response(request.body, { headers: request.headers }),
+        4096,
+      )) as Partial<typeof input> | null
+      if (
+        !raw ||
+        typeof raw.code !== 'string' ||
+        !/^\d{6}$/.test(raw.code) ||
+        typeof raw.requestId !== 'string' ||
+        !/^[A-Za-z0-9_-][A-Za-z0-9_.:-]{7,127}$/.test(raw.requestId) ||
+        typeof raw.path !== 'string'
+      )
+        throw Error('Invalid body')
+      input = { code: raw.code, requestId: raw.requestId, path: safeReturnTo(raw.path) }
+    } catch {
+      return json({ ok: false, error: 'Enter a valid six-digit access code.' }, 400)
+    }
+    const identity = visitor(request),
+      visitorCookie = identity.cookie
+    if (!identity.authenticated) {
+      const response = json(
+        { ok: false, error: 'Allow cookies for this site, then try again.' },
+        428,
+      )
+      response.headers.append('set-cookie', visitorCookie)
+      return response
+    }
+    try {
+      const { response, body } = await remote({
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'X-U90-Visitor': identity.id,
+          ...(cookie(request, ACCESS_COOKIE)
+            ? { 'X-U90-Preview-Access': cookie(request, ACCESS_COOKIE)! }
+            : {}),
+        },
+        body: JSON.stringify(input),
+      })
+      if ([400, 401, 429].includes(response.status)) {
+        const reply = json(
+          {
+            ok: false,
+            error:
+              response.status === 429
+                ? 'Please wait before trying again.'
+                : 'That code was not accepted.',
+          },
+          response.status,
+        )
+        reply.headers.append('set-cookie', visitorCookie)
+        const retry = response.headers.get('retry-after')
+        if (retry && /^\d{1,4}$/.test(retry)) reply.headers.set('retry-after', retry)
+        return reply
+      }
+      const result = body as { ok?: unknown; token?: unknown; maxAge?: unknown }
+      if (
+        !response.ok ||
+        result?.ok !== true ||
+        !tokenLike(result.token) ||
+        typeof result.maxAge !== 'number' ||
+        !Number.isInteger(result.maxAge) ||
+        result.maxAge < 1 ||
+        result.maxAge > 3600
+      )
+        throw Error('Invalid unlock')
+      const reply = json({ ok: true, returnTo: input.path })
+      reply.headers.append(
+        'set-cookie',
+        `${ACCESS_COOKIE}=${result.token}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${result.maxAge}${new URL(request.url).protocol === 'https:' ? '; Secure' : ''}`,
+      )
+      reply.headers.append('set-cookie', visitorCookie)
+      return reply
+    } catch {
+      const reply = unavailable()
+      reply.headers.append('set-cookie', visitorCookie)
+      return reply
+    }
+  }
+  /** Called only inside the existing authenticated preview handler, before its redirect. */
+  async function previewHandoff(request: Request): Promise<string | null> {
+    const url = new URL(request.url),
+      token = url.searchParams.get('token')
+    if (
+      url.pathname !== '/api/u90/preview' ||
+      !equal(url.searchParams.get('secret') ?? '', options.revalidateSecret) ||
+      !tokenLike(token) ||
+      !token.startsWith('u90pt1.')
+    )
+      return null
+    const path = safeReturnTo(url.searchParams.get('path'))
+    const target = new URL(path, url.origin)
+    try {
+      const { response, body } = await remote({
+        method: 'GET',
+        headers: { 'X-U90-Preview-Token': token },
+      })
+      if (!response.ok || statusValue(body).canvasVerified !== true) return null
+      const iv = randomBytes(12),
+        cipher = createCipheriv('aes-256-gcm', key, iv)
+      const data = Buffer.concat([
+        cipher.update(
+          JSON.stringify({ token, path: target.pathname + target.search, exp: Date.now() + 60000 }),
+        ),
+        cipher.final(),
+      ])
+      target.searchParams.set(
+        HANDOFF_QUERY,
+        `${iv.toString('base64url')}.${data.toString('base64url')}.${cipher.getAuthTag().toString('base64url')}`,
+      )
+      return target.pathname + target.search + target.hash
+    } catch {
+      return null
+    }
+  }
+  return { gate, status, draft, unlock, previewHandoff, safeReturnTo }
+}
+export type { PreviewLockAppearance, PreviewLockStatus }

package/src/redirects/config.d.mts

@@ -0,0 +1,5 @@
+/** Adds `env.U90_REDIRECTS_SNAPSHOT` to a Next config: the platform's redirect rules as read at build time. */
+export function withRedirectsSnapshot<C extends { env?: Record<string, string | undefined> }>(
+  config: C,
+  options?: { env?: NodeJS.ProcessEnv; fetch?: typeof fetch },
+): Promise<C>

package/src/redirects/config.mjs

@@ -0,0 +1,22 @@
+/**
+ * Bakes the platform's redirect rules into a build, so a fresh deploy applies them from its first
+ * request: `export default async () => withRedirectsSnapshot(nextConfig)`, a form every config file type accepts. The rules are read from the v1
+ * read API with the site's key and handed to the proxy as `env.U90_REDIRECTS_SNAPSHOT`. With no
+ * `PLATFORM_URL` the snapshot is empty. A platform that will not answer, or takes more than 10 s, stops the build.
+ */
+export async function withRedirectsSnapshot(config, { env = process.env, fetch: fetchImpl = globalThis.fetch } = {}) {
+  const base = env.PLATFORM_URL ? env.PLATFORM_URL.replace(/\/+$/, '') : ''
+  let snapshot = { rules: [], generatedAt: new Date(0).toISOString() }
+  if (base) {
+    // The timeout covers the body as well as the headers: a platform that stalls mid-reply stops the build the same way.
+    try {
+      const res = await fetchImpl(`${base}/api/u90/v1/redirects`, { headers: { authorization: `Bearer ${env.PAYLOAD_API_KEY ?? ''}` }, cache: 'no-store', signal: AbortSignal.timeout(10000) })
+      if (!res.ok) throw new Error(`The platform answered ${res.status} for the site's redirect rules, so the build stops rather than deploy without them.`)
+      snapshot = await res.json()
+    } catch (err) {
+      if (err instanceof Error && err.name === 'TimeoutError') throw new Error('The platform timed out after 10 s on the site\'s redirect rules, so the build stops rather than deploy without them.')
+      throw err
+    }
+  }
+  return { ...config, env: { ...(config.env ?? {}), U90_REDIRECTS_SNAPSHOT: JSON.stringify(snapshot) } }
+}

package/src/redirects/index.ts

@@ -0,0 +1,3 @@
+export * from './match'
+export * from './wire'
+export { redirectsProxy } from './proxy'

package/src/redirects/location.ts

@@ -0,0 +1,31 @@
+/** Every run of `/` and `\` in a path as one `/`. */
+export const collapseSeparators = (path: string): string => path.replace(/[/\\]+/g, '/')
+
+/** A redirect's `Location`, or why none is sent: `unusable` when no URL can be made of the destination, `unsafe` when it would leave the site or land under `/_next/`. */
+export type SiteLocation = { location: URL } | { refused: 'unusable' | 'unsafe' }
+
+/**
+ * The `Location` a proxy sends for `destination`, made absolute against the request.
+ * Next's proxy adapter reads the response's `Location` with `new NextURL(location)`, which throws on a relative one (a 500),
+ * so the address is made absolute against the request. Next then rewrites a same-host `Location` back to a relative one:
+ * its path, query and hash. A same-origin path that starts with `//` or `/\` therefore reaches the browser as `//host`, another
+ * site. Dot segments resolve only here (`/.//evil.com` becomes `//evil.com`), so the resolved path is checked, not the built
+ * string. Next also strips a leading part of that path first: a basePath, the default locale (`/en//evil.com`), or
+ * `/_next/data/<buildId>` (`/_next/data///evil.com.json`), which turns an interior `//` into a leading one. So every run of
+ * `/` and `\` in a same-origin path becomes one `/`, and a same-origin path under `/_next/` is refused.
+ * A destination on another origin is returned as given.
+ */
+export function siteLocation(destination: string, requestUrl: URL): SiteLocation {
+  let location: URL
+  try {
+    location = new URL(destination, requestUrl)
+  } catch {
+    return { refused: 'unusable' }
+  }
+  if (location.origin === requestUrl.origin) {
+    const collapsed = collapseSeparators(location.pathname)
+    if (collapsed !== location.pathname) location.pathname = collapsed
+    if (location.origin !== requestUrl.origin || /[/\\]{2}/.test(location.pathname) || location.pathname.startsWith('/_next/')) return { refused: 'unsafe' }
+  }
+  return { location }
+}

package/src/redirects/match.ts

@@ -0,0 +1,199 @@
+import type { RedirectRule, RedirectStatus } from './wire'
+
+/** Drop every trailing `/`. A loop, not `/\/+$/`: that pattern backtracks, so it is quadratic on a long run of slashes in a visitor's path. */
+const dropTrailingSlashes = (path: string): string => {
+  let end = path.length
+  while (end > 0 && path.charCodeAt(end - 1) === 47) end -= 1
+  return path.slice(0, end)
+}
+
+/**
+ * Normalise a path so both sides of a comparison agree: percent-decode (a malformed escape keeps the input), NFC,
+ * strip the trailing slash except at the root, lowercase. The steps are ordered: a percent-encoded combining mark
+ * only becomes comparable to its precomposed form once it is decoded. Stored rule sources go through this too.
+ */
+export const normalisePath = (input: string): string => {
+  let path = input
+  try {
+    path = decodeURIComponent(path)
+  } catch {
+    // A bare `%` or `%zz` throws; the input is kept so one bad row does not fail the whole set.
+  }
+  path = path.normalize('NFC')
+  if (path.length > 1 && path.endsWith('/')) path = dropTrailingSlashes(path)
+  if (path === '') path = '/'
+  return path.toLowerCase()
+}
+
+/** Strip the trailing slash as `normalisePath` does and nothing else, so the raw path can be walked segment for segment with the normalised one. */
+const trimTrailingSlash = (path: string): string => {
+  if (path.length > 1 && path.endsWith('/')) {
+    const trimmed = dropTrailingSlashes(path)
+    return trimmed === '' ? '/' : trimmed
+  }
+  return path
+}
+
+/**
+ * Make a destination safe for a `Location` header, which is a ByteString: a character above U+00FF or a bare CR or LF throws.
+ * Each run outside printable ASCII is percent-encoded; printable ASCII, `%` included, is left alone so an already-encoded
+ * remainder is not encoded twice. A run that cannot be encoded (a lone surrogate) is dropped.
+ */
+export const encodeLocation = (destination: string): string =>
+  destination.replace(/[^!-~]+/gu, (run) => {
+    try {
+      return encodeURIComponent(run)
+    } catch {
+      return ''
+    }
+  })
+
+/** Split a request target at the first `?`. `query` keeps its `?`. */
+export const splitQuery = (target: string): { path: string; query: string } => {
+  const mark = target.indexOf('?')
+  if (mark === -1) return { path: target, query: '' }
+  return { path: target.slice(0, mark), query: target.slice(mark) }
+}
+
+/** The `:name` and `*` segments a pattern declares, in order. A `*` is listed as `'*'`. */
+export const patternParams = (pattern: string): string[] => {
+  const found: string[] = []
+  for (const segment of pattern.split('/')) {
+    if (segment.startsWith(':') && segment.length > 1) found.push(segment.slice(1))
+    else if (segment === '*') found.push('*')
+  }
+  return found
+}
+
+/**
+ * A same-site destination (one `/` then anything but another `/`) keeps exactly one leading separator. A remainder or a
+ * capture can start with `/` or `\`: a raw `//`, or a `%2F` or `%5C` that decoding turned into one. A browser reads a
+ * `Location` of `//host` or `/\host` as another site. Any other destination, an absolute one included, is left as stored.
+ * This tidies the built string only: a dot segment (`/.//host`) still resolves to `//host`. The guarantee is the proxy's
+ * check of the resolved `Location`.
+ */
+const keepOnSite = (stored: string, built: string): string => {
+  if (!stored.startsWith('/') || stored.startsWith('//')) return built
+  let start = 0
+  while (start < built.length && (built[start] === '/' || built[start] === '\\')) start += 1
+  return start > 1 ? `/${built.slice(start)}` : built
+}
+
+/** Substitute a pattern rule's captures into its destination. */
+export const applyCaptures = (destination: string, captures: Record<string, string>): string =>
+  destination
+    .split('/')
+    .map((segment) => {
+      if (segment === '*') return captures['*'] ?? ''
+      if (segment.startsWith(':') && segment.length > 1) return captures[segment.slice(1)] ?? segment
+      return segment
+    })
+    .join('/')
+
+export type RedirectMatch = {
+  destination: string
+  status: RedirectStatus
+  /** The rule that won. */
+  rule: RedirectRule
+}
+
+type Compiled = { exact: Map<string, RedirectRule>; prefix: RedirectRule[]; pattern: RedirectRule[] }
+
+const compiledFor = new WeakMap<readonly RedirectRule[], Compiled>()
+
+/** Sources are normalised again here: a rule stored before a change to `normalisePath` must still be reachable. */
+const compile = (rules: readonly RedirectRule[]): Compiled => {
+  const exact = new Map<string, RedirectRule>()
+  const prefix: RedirectRule[] = []
+  const pattern: RedirectRule[] = []
+  for (const rule of rules) {
+    const normalised: RedirectRule = { ...rule, source: normalisePath(rule.source) }
+    if (normalised.matchType === 'exact') exact.set(normalised.source, normalised)
+    else if (normalised.matchType === 'prefix') prefix.push(normalised)
+    else pattern.push(normalised)
+  }
+  // Longest source first, then string order, so the result does not depend on row order.
+  prefix.sort((a, b) => b.source.length - a.source.length || a.source.localeCompare(b.source))
+  pattern.sort((a, b) => patternParams(a.source).length - patternParams(b.source).length || b.source.length - a.source.length || a.source.localeCompare(b.source))
+  return { exact, prefix, pattern }
+}
+
+/**
+ * Match one pattern against the normalised path, segment by segment, with no regular expression built from the pattern.
+ * Captures are taken from `emit`, the raw segments, since normalising decodes and lowercases and a capture is emitted.
+ */
+const matchPattern = (pattern: string, path: string, emit: string[]): Record<string, string> | null => {
+  const patternSegments = pattern.split('/')
+  const pathSegments = path.split('/')
+  const captures: Record<string, string> = {}
+  for (let index = 0; index < patternSegments.length; index += 1) {
+    const expected = patternSegments[index] ?? ''
+    if (expected === '*' && index === patternSegments.length - 1) {
+      captures['*'] = emit.slice(index).join('/')
+      return captures
+    }
+    const actual = pathSegments[index]
+    if (actual === undefined) return null
+    if (expected.startsWith(':') && expected.length > 1) {
+      if (actual === '') return null
+      captures[expected.slice(1)] = emit[index] ?? actual
+      continue
+    }
+    if (expected === '*') {
+      if (actual === '') return null
+      captures['*'] = emit[index] ?? actual
+      continue
+    }
+    if (expected !== actual) return null
+  }
+  return pathSegments.length === patternSegments.length ? captures : null
+}
+
+/**
+ * Resolve a request target (a path with an optional query) against a rule set. Exact rules win, then prefix rules
+ * (longest first), then patterns (fewest parameters, then longest source). The rule set is compiled once per array.
+ *
+ * Matching reads the normalised path; the destination is built from the raw one, so captures and a prefix remainder
+ * keep their encoding and case. When decoding introduces a separator (`%2F`) the segment counts differ and the
+ * normalised segments are used.
+ */
+export const matchRedirect = (rules: readonly RedirectRule[], target: string): RedirectMatch | null => {
+  let compiled = compiledFor.get(rules)
+  if (!compiled) {
+    compiled = compile(rules)
+    compiledFor.set(rules, compiled)
+  }
+  const { path, query } = splitQuery(target)
+  const normalised = normalisePath(path)
+  const rawSegments = trimTrailingSlash(path).split('/')
+  const normalisedSegments = normalised.split('/')
+  const outputSegments = rawSegments.length === normalisedSegments.length ? rawSegments : normalisedSegments
+
+  const carry = (rule: RedirectRule, destination: string): RedirectMatch => {
+    if (rule.status === 410) return { destination: '', status: 410, rule }
+    const onSite = keepOnSite(rule.destination, destination)
+    // A destination with its own query keeps it and drops the request's: merging two query strings gives duplicate keys.
+    const withQuery = rule.preserveQuery && query && !onSite.includes('?') ? onSite + query : onSite
+    return { destination: encodeLocation(withQuery), status: rule.status, rule }
+  }
+
+  const exact = compiled.exact.get(normalised)
+  if (exact) return carry(exact, exact.destination)
+
+  for (const rule of compiled.prefix) {
+    // A prefix ends at a segment boundary: `/blog` does not match `/blogroll`.
+    if (normalised === rule.source || normalised.startsWith(`${rule.source}/`)) {
+      const consumed = rule.source.split('/').length
+      const rest = outputSegments.length > consumed ? `/${outputSegments.slice(consumed).join('/')}` : ''
+      const destination = rule.destination.endsWith('/') && rest.startsWith('/') ? rule.destination.slice(0, -1) + rest : rule.destination + rest
+      return carry(rule, destination)
+    }
+  }
+
+  for (const rule of compiled.pattern) {
+    const captures = matchPattern(rule.source, normalised, outputSegments)
+    if (captures) return carry(rule, applyCaptures(rule.destination, captures))
+  }
+
+  return null
+}