@nifrajs/web 2.0.0 → 2.2.0

package/src/draft.ts

@@ -14,7 +14,14 @@
  *   createWebApp({ ..., draftSecret: env.DRAFT_SECRET })   // → loaders get ctx.draft
  *   withISR(app, { ..., draftSecret: env.DRAFT_SECRET })   // → editors bypass the cache
  */
-import { type CookieOptions, parseCookies, signValue, unsignValue } from "@nifrajs/core/server"
+import {
+  type CookieOptions,
+  parseCookies,
+  serializeCookie,
+  signValue,
+  unsignValue,
+} from "@nifrajs/core/server"
+import { timingSafeEqual } from "./internal/timing-safe-equal.ts"
 
 /** The cookie name nifra uses for draft/preview mode. */
 export const DRAFT_COOKIE = "__nifra_draft"
@@ -51,15 +58,28 @@ export async function enableDraft(
   options: EnableDraftOptions = {},
 ): Promise<void> {
   const signed = await signValue(DRAFT_MARKER, secret)
+  c.set.cookie(DRAFT_COOKIE, signed, draftCookieOptions(options))
+}
+
+/**
+ * The attributes draft mode always sets. Shared by {@link enableDraft} (which writes through
+ * `c.set.cookie`) and {@link previewEndpoint} (which serializes its own `Set-Cookie`), so the two
+ * can't drift on the properties that make the cookie unforgeable and unreadable from JS.
+ *
+ * `secure` is resolved here rather than left to the caller: `serializeCookie` is pure and applies
+ * **no** security defaults, so the `previewEndpoint` path would silently emit a cookie without
+ * `Secure` — over plain HTTP that hands the draft cookie to any network observer. Passing it
+ * explicitly makes both paths identical instead of one inheriting a default the other never sees.
+ */
+function draftCookieOptions(options: EnableDraftOptions): CookieOptions {
   // Explicit security attributes (don't lean on the context default): signed + HttpOnly + SameSite=Lax.
-  const cookieOptions: CookieOptions = {
+  return {
     httpOnly: true,
     sameSite: "lax",
     path: options.path ?? "/",
     maxAge: options.maxAgeSeconds ?? 3600,
-    ...(options.secure === undefined ? {} : { secure: options.secure }),
+    secure: options.secure ?? true,
   }
-  c.set.cookie(DRAFT_COOKIE, signed, cookieOptions)
 }
 
 /** Turn draft mode **off**: clear the `__nifra_draft` cookie. Match the `path` used in `enableDraft`. */
@@ -80,3 +100,95 @@ export async function isDraftEnabled(request: Request, secret: string): Promise<
   if (cookie === undefined) return false
   return (await unsignValue(cookie, secret)) !== null
 }
+
+/**
+ * Accept only a same-site destination, or `null`.
+ *
+ * A redirect target that arrives in the query string is attacker-controlled: anyone can mint a link
+ * to your own preview route and choose where the editor lands. "Starts with `/`" is the check people
+ * write and it is not enough — `//evil.com` is a protocol-relative URL and `/\evil.com` is normalized
+ * to one by browsers, so both start with a slash and navigate off-site. Control characters are refused
+ * as well, since a newline in a `Location` header splits the response.
+ */
+function safeRedirectPath(value: string): string | null {
+  if (!value.startsWith("/")) return null
+  if (value.startsWith("//") || value.startsWith("/\\")) return null
+  // Escaped rather than written literally: raw control bytes in source make the file read as binary
+  // to ordinary tooling (grep, diffs) and are one reformat away from being silently mangled.
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: matching them is the point - this IS the check that refuses them.
+  if (/[\u0000-\u001f\u007f]/u.test(value)) return null
+  return value
+}
+
+/** Config for {@link previewEndpoint}. */
+export interface PreviewEndpointOptions {
+  /** Shared secret the preview link must carry. Compared in **constant time**. */
+  readonly secret: string
+  /** Secret that **signs** the draft cookie — the same one passed to `createWebApp({ draftSecret })`
+   * and `withISR({ draftSecret })`. Keep it distinct from {@link secret}: that one travels in URLs
+   * (logs, `Referer`, browser history), this one never leaves the server. */
+  readonly draftSecret: string
+  /** Query parameter carrying the token. Default `"token"`. */
+  readonly tokenParam?: string
+  /** Query parameter carrying the destination. Default `"to"`. */
+  readonly redirectParam?: string
+  /** Where to send the editor when the destination parameter is absent. Default `"/"`. Must be
+   * site-relative; a non-relative value throws at construction rather than at request time. */
+  readonly fallbackPath?: string
+  /** Cookie lifetime/path/secure overrides, exactly as {@link enableDraft} takes them. */
+  readonly cookie?: EnableDraftOptions
+}
+
+/**
+ * A **preview / draft-mode entry point** — a `fetch` handler that checks a preview token, turns draft
+ * mode on, and redirects the editor to the page they wanted. `GET` with `?token=<secret>&to=/some/path`;
+ * mount it on a nifra route, e.g. `app.get("/api/preview", (c) => handler(c.req))`.
+ *
+ * This is the link-borne sibling of `revalidateEndpoint`. It exists because the alternative — telling
+ * you to gate the route yourself — means hand-rolling two checks that are easy to get subtly wrong and
+ * that fail silently when you do: the token compare must not exit early on the first wrong character,
+ * and the `?to=` destination must not be allowed to point off-site. Both are handled here.
+ *
+ * A CMS "Preview" button is a plain link, so the token has to ride the query string. That has a cost
+ * no endpoint can remove — the secret lands in server logs, the `Referer` header, and browser history.
+ * Use a preview token minted for that purpose, rotate it, and never reuse a token that grants anything
+ * beyond draft mode.
+ *
+ * Wrong or missing token → `401`; an off-site `to` → `400`; success → `302` with the signed cookie and
+ * `Cache-Control: no-store`, so no shared cache can ever replay one editor's draft session to a visitor.
+ */
+export function previewEndpoint(
+  options: PreviewEndpointOptions,
+): (request: Request) => Promise<Response> {
+  const tokenParam = options.tokenParam ?? "token"
+  const redirectParam = options.redirectParam ?? "to"
+  const fallbackPath = options.fallbackPath ?? "/"
+  // Fail at construction, not on the request that happens to omit `?to=`: a misconfigured fallback is
+  // a deploy-time mistake and should surface at boot rather than as a rare 400 in production.
+  if (safeRedirectPath(fallbackPath) === null) {
+    throw new Error(
+      `[nifra] previewEndpoint fallbackPath must be a site-relative path, got ${JSON.stringify(fallbackPath)}`,
+    )
+  }
+  const cookieOptions = draftCookieOptions(options.cookie ?? {})
+  return async (request) => {
+    const url = new URL(request.url)
+    if (!timingSafeEqual(url.searchParams.get(tokenParam) ?? "", options.secret)) {
+      return Response.json({ ok: false, error: "unauthorized" }, { status: 401 })
+    }
+    const requested = url.searchParams.get(redirectParam)
+    const destination = requested === null ? fallbackPath : safeRedirectPath(requested)
+    if (destination === null) {
+      return Response.json({ ok: false, error: "invalid_redirect" }, { status: 400 })
+    }
+    const signed = await signValue(DRAFT_MARKER, options.draftSecret)
+    return new Response(null, {
+      status: 302,
+      headers: {
+        location: destination,
+        "set-cookie": serializeCookie(DRAFT_COOKIE, signed, cookieOptions),
+        "cache-control": "no-store",
+      },
+    })
+  }
+}

package/src/fs.ts

@@ -9,8 +9,21 @@ import { buildManifest, type Manifest, type RouteModule } from "./manifest.ts"
 /** Options for {@link discoverRoutes}. */
 export interface DiscoverRoutesOptions {
   /** Appended (as `?<importQuery>`) to each route's dynamic import — the dev server sets a
-   * changing value to bust Bun's module cache so SSR picks up edited route files. */
+   * changing value to bust Bun's module cache so SSR picks up edited route files. Ignored when
+   * {@link load} is supplied, which does its own cache handling. */
   readonly importQuery?: string
+  /**
+   * Load a route module by its absolute path, instead of a bare dynamic `import()`.
+   *
+   * This is what lets a pipeline own SSR resolution. A bare `import()` always resolves through the
+   * RUNTIME - Bun - so the Vite dev server ended up serving the client while Bun resolved the server,
+   * two resolvers disagreeing about one specifier in a single process. That is the dual-React bug and
+   * the reason `resolve.dedupe` never reached SSR: the alias governs Vite, and SSR never asked Vite.
+   *
+   * Pass `vite.ssrLoadModule` here and the Vite pipeline resolves both halves. Omit it and Bun does,
+   * which is correct for the Bun pipeline. Either way one toolchain owns the phase.
+   */
+  readonly load?: (absolutePath: string) => Promise<unknown>
 }
 
 /** Scan a `routes/` directory (recursively) and build the route manifest. */
@@ -19,8 +32,13 @@ export function discoverRoutes(dir: string, options: DiscoverRoutesOptions = {})
     .map((file) => file.replaceAll("\\", "/")) // normalize Windows separators
     .filter((file) => /\.(tsx|jsx|svelte|vue|mdx)$/.test(file))
   const query = options.importQuery ? `?${options.importQuery}` : ""
-  return buildManifest(
-    files,
-    (file) => () => import(`${dir}/${file}${query}`) as Promise<RouteModule>,
+  const load = options.load
+  return buildManifest(files, (file) =>
+    load === undefined
+      ? () => import(`${dir}/${file}${query}`) as Promise<RouteModule>
+      : // No `importQuery` here: an injected loader owns its own invalidation (Vite's module graph
+        // re-evaluates on change), and appending a cache-buster would defeat it by minting a new
+        // module id per request.
+        () => load(`${dir}/${file}`) as Promise<RouteModule>,
   )
 }