@unitninety/site-kit 0.0.0-stage → 1.6.1

package/src/legacy/routes.ts

@@ -0,0 +1,414 @@
+import { canonicalLocale } from './languages/settings'
+import { localePath } from './languages/routing'
+import type { createLanguageRuntime } from './languages/runtime'
+import { createManifest, type BlockSpec } from './defineBlocks'
+import { PREVIEW_MAX_AGE_SECONDS, PREVIEW_TOKEN_COOKIE, PREVIEW_UNTIL_COOKIE } from './preview'
+import { manifestFrom, type Site } from './defineSite'
+import type { EditorBlock, ManifestCollection, PageDeclaration, SeedSection } from './contract'
+
+/**
+ * The four routes every UnitNinety site mounts.
+ *
+ * Each is a factory returning a Next route handler, so a site's route file is one line
+ * and the logic is versioned here. These used to be copy-pasted per site, which meant
+ * a fix to one of them existed in exactly one repo and the next client silently got the
+ * old version.
+ *
+ * Nothing here needs the platform's API key — these are the *inbound* half of the
+ * contract, authenticated with the tenant's `revalidateSecret`.
+ */
+
+/** Constant-time compare, so a wrong secret can't be found a byte at a time. */
+const secretMatches = (provided: string, expected: string): boolean => {
+  if (provided.length !== expected.length) return false
+  let mismatch = 0
+  for (let index = 0; index < provided.length; index += 1) {
+    mismatch |= provided.charCodeAt(index) ^ expected.charCodeAt(index)
+  }
+  return mismatch === 0
+}
+
+const bearer = (request: Request): string => {
+  const header = request.headers.get('authorization') ?? ''
+  return header.startsWith('Bearer ') ? header.slice(7) : ''
+}
+
+/**
+ * `GET /api/u90/manifest` — publish this site's content schema.
+ *
+ *   export const GET = createManifestRoute({ blocks, pages })
+ *
+ * Authenticated, because the schema describes the client's editing surface and there is
+ * no reason for it to be public. The platform is the only caller.
+ */
+export const createManifestRoute = ({
+  blocks,
+  languageRuntime,
+  collections,
+  newPage,
+  pages,
+  routesAllPages,
+  secret = process.env.REVALIDATE_SECRET,
+  seed,
+  site,
+}: {
+  languageRuntime?: ReturnType<typeof createLanguageRuntime>
+  blocks?: EditorBlock[]
+  /** Repeatable record types, from `defineCollections`. Their seeds ride along. */
+  collections?: ManifestCollection[]
+  /** The sections a client-added page starts with. See `SiteManifest.newPage`. */
+  newPage?: SeedSection[]
+  pages?: PageDeclaration[]
+  /** True when a catch-all serves every stored slug. See `SiteManifest.routesAllPages`. */
+  routesAllPages?: boolean
+  secret?: string
+  /**
+   * The spec passed to `defineBlocks`, so the manifest carries the site's committed
+   * copy as seed content. The platform stores it once, on a tenant's first pair —
+   * without it a fresh tenant's editor is a page of blanks while the site renders
+   * perfectly, because every component falls back to its committed copy.
+   */
+  seed?: BlockSpec
+  /** A `defineSite` result. Supersedes `blocks`, `collections` and `seed`; pass one or the other. */
+  site?: Site<unknown>
+}) => {
+  if (site) {
+    const legacyKey = blocks ? 'blocks' : collections ? 'collections' : seed ? 'seed' : undefined
+    if (legacyKey) {
+      throw new Error(
+        `createManifestRoute takes either \`site\` or \`${legacyKey}\`, not both. A site already carries its blocks, collections and seed.`,
+      )
+    }
+  } else if (!blocks) {
+    /*
+     * Neither form, which is the other half of the guard above and fails the same way:
+     * quietly. `blocks` is optional only so that `site` can replace it, so a route with
+     * neither serves `blocks: []` — a manifest the platform accepts and renders as an
+     * editor with nothing in it, which a client reads as their content having vanished.
+     * Both keys being absent is a mistake at the call site, so it is raised where the
+     * call is, at module load, rather than on the platform's first fetch.
+     *
+     * This also catches a legacy call that names `collections` or `seed` and forgets
+     * `blocks`, which used to serve an empty block list. That is the same empty editor, so
+     * the error is right — but a site that really does publish no blocks has to be able to
+     * say so, which is why the message names `blocks: []` rather than only the two keys.
+     */
+    throw new Error(
+      "createManifestRoute needs either `site` (from defineSite) or `blocks` (from defineBlocks). With neither it publishes an empty schema, and the client's editor opens with no fields at all. If this site genuinely has no blocks, say so with `blocks: []`.",
+    )
+  }
+
+  return async function GET(request: Request): Promise<Response> {
+    if (!secret) {
+      // Misconfiguration, not an auth failure — say so, because the platform surfaces
+      // this string to an operator during pairing.
+      return Response.json({ error: 'REVALIDATE_SECRET is not set on this site.' }, { status: 500 })
+    }
+
+    if (!secretMatches(bearer(request), secret)) {
+      return Response.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    return Response.json(
+      {
+        ...(site
+          ? manifestFrom({ newPage, pages, routesAllPages, site })
+          : createManifest({
+              blocks: blocks ?? [],
+              collections,
+              newPage,
+              pages,
+              routesAllPages,
+              seed,
+            })),
+        ...(languageRuntime?.languageVersion === 1 ? { languageVersion: 1 } : {}),
+      },
+      {
+        // The platform does its own tag-based caching; a cached response here would just
+        // make a deploy's new schema invisible for longer.
+        headers: { 'Cache-Control': 'no-store' },
+      },
+    )
+  }
+}
+
+/**
+ * `POST /api/revalidate` — the platform telling this site something published.
+ *
+ *   export const POST = createRevalidateRoute({ revalidateTag })
+ *
+ * `revalidateTag` is injected rather than imported, because it comes from
+ * `next/cache` in the consuming app and this package must not pin a Next version.
+ *
+ * Note the platform's POST is fire-and-forget with a short timeout: this route being
+ * down means a stale page, never a broken dashboard.
+ */
+export const createRevalidateRoute = ({
+  revalidateTag,
+  secret = process.env.REVALIDATE_SECRET,
+}: {
+  /**
+   * Next's own `revalidateTag`. Both versions satisfy this: Next 16 requires a
+   * cache profile and types it as `string | CacheLifeConfig`, Next 15 takes the
+   * tag alone.
+   *
+   * `...rest: never[]` rather than `profile?: unknown` because the check runs the
+   * other way round — a function whose parameter is narrower than `unknown` is
+   * *not* assignable to one declaring `unknown`, so Next 16's signature was
+   * rejected outright. `never` accepts any parameter type, which is what
+   * "whatever your Next version wants" actually means in the type system.
+   */
+  revalidateTag: (tag: string, ...rest: never[]) => unknown
+  secret?: string
+}) =>
+  async function POST(request: Request): Promise<Response> {
+    const body = (await request.json().catch(() => ({}))) as {
+      collection?: string
+      secret?: string
+      slug?: null | string
+    }
+
+    // Sent as a header *and* in the body, so it can be checked before parsing.
+    const provided = request.headers.get('x-revalidate-secret') ?? body.secret ?? ''
+
+    if (!secret || !secretMatches(provided, secret)) {
+      return Response.json({ error: 'Bad secret' }, { status: 401 })
+    }
+
+    const { collection, slug } = body
+    if (!collection) {
+      return Response.json({ error: 'No collection given' }, { status: 400 })
+    }
+
+    /*
+     * `{ expire: 0 }` so the purged entry is refetched on the next request rather than
+     * after a grace period — a publish the client just pressed should be visible now.
+     * Next 15 ignores the second argument; Next 16 requires it.
+     *
+     * One cast, because the profile's type is `CacheLifeConfig` in Next 16 and this
+     * package deliberately does not depend on Next to name it.
+     */
+    const purge = revalidateTag as (tag: string, profile?: unknown) => unknown
+
+    purge(collection, { expire: 0 })
+    if (slug) purge(`${collection}:${slug}`, { expire: 0 })
+
+    return Response.json({ revalidated: true })
+  }
+
+/**
+ * `GET /api/preview` — enter draft mode for one document.
+ *
+ *   export const GET = createPreviewRoute({ cookies, draftMode, redirect })
+ *
+ * Next's own primitives are injected for the same reason as `revalidateTag`.
+ *
+ * The forwarded Payload token is stashed as a cookie so the page can fetch drafts *as
+ * the signed-in client* rather than with the site's own key. That matters: it means a
+ * preview shows what that person staged, and it expires with their session.
+ */
+export const createPreviewRoute = ({
+  cookies,
+  draftMode,
+  onAuthorised,
+  previewMaxAgeSeconds = PREVIEW_MAX_AGE_SECONDS,
+  redirect,
+  sameSite = process.env.NODE_ENV === 'production' ? 'none' : 'lax',
+  secret = process.env.REVALIDATE_SECRET,
+}: {
+  cookies: () => Promise<{
+    set: (name: string, value: string, options?: Record<string, unknown>) => void
+  }>
+  draftMode: () => Promise<{ enable: () => void }>
+  /**
+   * Run after the secret is verified and before the redirect, with the cookie store.
+   *
+   * This exists for the private-preview gate every prospect site is behind. Without
+   * it, an editor opening Canvas is redirected to the site root, the gate rewrites
+   * that to the lock screen, and the dashboard reports the site as not responding to
+   * the editor — the schema still loads, so it looks like a bridge fault rather than
+   * a locked door. Knowing `REVALIDATE_SECRET` is a stronger proof than the gate's
+   * own code, so a site can mint its access cookie here.
+   *
+   * Called only on an authorised request. `secure` is passed through so the cookie
+   * matches the `sameSite` choice below — `none` requires `secure`.
+   */
+  onAuthorised?: (
+    store: {
+      set: (name: string, value: string, options?: Record<string, unknown>) => void
+    },
+    options: { sameSite: 'lax' | 'none'; secure: boolean },
+  ) => Promise<void> | void
+  /**
+   * How long this preview counts for. See `./preview` for why it must count for anything.
+   *
+   * Every entry restamps it, so an editor working through Canvas never meets the edge;
+   * the window is there for the browser that stops asking.
+   */
+  previewMaxAgeSeconds?: number
+  redirect: (url: string) => never
+  /**
+   * `none` in production because the dashboard frames this site cross-origin, and a
+   * `lax` cookie is not sent in a third-party frame — the preview would silently show
+   * published content instead of the draft.
+   */
+  sameSite?: 'lax' | 'none'
+  secret?: string
+}) =>
+  async function GET(request: Request): Promise<Response> {
+    const { searchParams } = new URL(request.url)
+
+    if (!secret || !secretMatches(searchParams.get('secret') ?? '', secret)) {
+      return new Response('Bad secret', { status: 401 })
+    }
+
+    if (searchParams.has('locale') && !canonicalLocale(searchParams.get('locale')))
+      return new Response('Invalid locale', { status: 400 })
+    if (
+      searchParams.has('languageRevision') &&
+      (!/^(0|[1-9]\d*)$/.test(searchParams.get('languageRevision') ?? '') ||
+        !Number.isSafeInteger(Number(searchParams.get('languageRevision'))))
+    )
+      return new Response('Invalid language revision', { status: 400 })
+    const draft = await draftMode()
+    draft.enable()
+
+    const store = await cookies()
+    const token = searchParams.get('token')
+
+    const shared = {
+      httpOnly: true,
+      maxAge: previewMaxAgeSeconds,
+      path: '/',
+      sameSite,
+      secure: sameSite === 'none',
+    }
+
+    if (token) {
+      /*
+       * `maxAge` rather than a session cookie. The doc above says the token "expires with
+       * their session", which is true of the JWT inside it and false of the cookie holding
+       * it: browsers restore sessions instead of ending them, so a session cookie is a
+       * permanent one with extra steps.
+       */
+      store.set(PREVIEW_TOKEN_COOKIE, token, shared)
+    }
+
+    /*
+     * The stamp `resolvePreview` reads. Set on every entry, so the window tracks the last
+     * time somebody actually asked to preview rather than the first.
+     */
+    store.set(PREVIEW_UNTIL_COOKIE, String(Date.now() + previewMaxAgeSeconds * 1000), shared)
+
+    await onAuthorised?.(store, { sameSite, secure: sameSite === 'none' })
+
+    /*
+     * An explicit route wins over the document's slug.
+     *
+     * The dashboard sends one for the screens that have no `pages` document behind them
+     * — a collection row's own page, `/projects/port-coogee`, is one route serving
+     * however many rows the client has. Without this there is no way to frame such a
+     * page in draft mode at all, so a client could never edit a project where it
+     * actually appears.
+     *
+     * Run through the same `safeReturnPath` as the exit route: it arrives in a query
+     * string, so it is not ours to trust even with the secret verified.
+     */
+    const path = searchParams.get('path')
+    const locale = canonicalLocale(searchParams.get('locale'))
+    const previewPath = (logical: string) => {
+      const target = new URL(
+        locale ? localePath(logical, locale) : logical,
+        'https://preview.invalid',
+      )
+      const revision = searchParams.get('languageRevision')
+      if (locale && revision && /^\d+$/.test(revision))
+        target.searchParams.set('languageRevision', revision)
+      return target.pathname + target.search + target.hash
+    }
+    if (path) return redirect(previewPath(safeReturnPath(path)))
+
+    const slug = searchParams.get('slug') ?? ''
+    /*
+     * `return` even though `redirect` never returns: it is a destructured parameter, so
+     * TypeScript won't narrow the call to unreachable and would report the handler as
+     * missing a return. `never` is assignable to the declared type, so this is honest
+     * rather than a cast.
+     */
+    return redirect(previewPath(slug && slug !== 'home' ? `/${slug}` : '/'))
+  }
+
+/**
+ * Only same-origin paths, so `?to=` cannot be turned into an open redirect.
+ *
+ * `//evil.com` and `/\evil.com` are both browser-protocol-relative, so a leading slash
+ * is not on its own enough.
+ */
+const safeReturnPath = (value: null | string): string => {
+  if (!value || !value.startsWith('/')) return '/'
+  if (value.startsWith('//') || value.startsWith('/\\')) return '/'
+  return value
+}
+
+/**
+ * `GET /api/exit-preview` — leave draft mode.
+ *
+ *   export const GET = createExitPreviewRoute({ cookies, draftMode, redirect })
+ *
+ * **Why this has to exist.** `createPreviewRoute` enables Next's draft mode and stashes
+ * the Payload token, and both are *session* cookies with no expiry. Nothing expires
+ * them and, until this route, nothing cleared them — so one click of Preview left that
+ * browser reading drafts on every page of the site until it was quit. The operator sees
+ * their unpublished edits on the live domain and reports, entirely reasonably, that the
+ * site changes before Publish is clicked. Visitors were never affected; the person
+ * checking was the only one who could see it.
+ *
+ * The pair with `createPreviewRoute` is the whole design, so the two live next to each
+ * other and the token is cleared with the same attributes it was set with.
+ *
+ * No secret, deliberately. Leaving draft mode is not a privileged act — the worst a
+ * stranger can do with this URL is take someone out of a mode they were not in.
+ *
+ * The site's own access cookie is left alone. A prospect site's private-preview gate is
+ * a different door, and slamming it on the way out would lock the operator off the site
+ * they were just editing.
+ */
+export const createExitPreviewRoute = ({
+  cookies,
+  draftMode,
+  redirect,
+  sameSite = process.env.NODE_ENV === 'production' ? 'none' : 'lax',
+}: {
+  cookies: () => Promise<{
+    set: (name: string, value: string, options?: Record<string, unknown>) => void
+  }>
+  draftMode: () => Promise<{ disable: () => void }>
+  redirect: (url: string) => never
+  /** Matched to `createPreviewRoute`'s, since this clears what that one set. */
+  sameSite?: 'lax' | 'none'
+}) =>
+  async function GET(request: Request): Promise<Response> {
+    const draft = await draftMode()
+    draft.disable()
+
+    /*
+     * Expired rather than deleted. A cookie is cleared only by a `Set-Cookie` whose
+     * path matches the one it was stored under, and this handler lives at
+     * `/api/exit-preview` — `delete(name)` would emit no path and the browser would
+     * scope it to `/api`, leaving the real `/` cookie in place and the fix looking
+     * like it silently did nothing.
+     */
+    const store = await cookies()
+    const cleared = {
+      httpOnly: true,
+      maxAge: 0,
+      path: '/',
+      sameSite,
+      secure: sameSite === 'none',
+    }
+    store.set(PREVIEW_TOKEN_COOKIE, '', cleared)
+    // Cleared with the token, so leaving by the front door and lapsing agree on the state.
+    store.set(PREVIEW_UNTIL_COOKIE, '', cleared)
+
+    return redirect(safeReturnPath(new URL(request.url).searchParams.get('to')))
+  }