Dynamic routing for v2: customization preview and visitor auth (#2922)

SamyPesse · web-flow · commit 31e381035eb0 · 2025-03-05T11:25:44.000+01:00
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -224,7 +224,7 @@ jobs:
         runs-on: ubuntu-latest
         name: Visual Testing
         needs: deploy
-        timeout-minutes: 6
+        timeout-minutes: 8
         steps:
             - name: Checkout
               uses: actions/checkout@v4
@@ -243,7 +243,7 @@ jobs:
         runs-on: ubuntu-latest
         name: Visual Testing v2
         needs: deploy-v2-vercel
-        timeout-minutes: 6
+        timeout-minutes: 8
         steps:
             - name: Checkout
               uses: actions/checkout@v4
diff --git a/packages/gitbook-v2/src/lib/middleware.ts b/packages/gitbook-v2/src/lib/middleware.ts
@@ -32,11 +32,6 @@ export enum MiddlewareHeaders {
      */
     Customization = 'x-gitbook-customization',
 
-    /**
-     * Token to use for the API.
-     */
-    APIToken = 'x-gitbook-token',
-
     /**
      * The visitor token used to access this content
      */
diff --git a/packages/gitbook-v2/src/middleware.ts b/packages/gitbook-v2/src/middleware.ts
@@ -1,15 +1,18 @@
-import { GitBookAPIError } from '@gitbook/api';
+import { CustomizationThemeMode, GitBookAPIError } from '@gitbook/api';
 import type { NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
 
 import { getContentSecurityPolicy } from '@/lib/csp';
+import { validateSerializedCustomization } from '@/lib/customization';
 import { removeLeadingSlash, removeTrailingSlash } from '@/lib/paths';
+import { getResponseCookiesForVisitorAuth, getVisitorToken } from '@/lib/visitor-token';
 import { serveResizedImage } from '@/routes/image';
 import { getPublishedContentByURL } from '@v2/lib/data';
+import { GITBOOK_URL } from '@v2/lib/env';
 import { MiddlewareHeaders } from '@v2/lib/middleware';
 
 export const config = {
-    matcher: ['/((?!_next/|_static/|_vercel|[\\w-]+\\.\\w+).*)'],
+    matcher: ['/((?!_next/static|_next/image).*)'],
 };
 
 type URLWithMode = { url: URL; mode: 'url' | 'url-host' };
@@ -48,12 +51,18 @@ export async function middleware(request: NextRequest) {
  */
 async function serveSiteByURL(request: NextRequest, urlWithMode: URLWithMode) {
     const { url, mode } = urlWithMode;
-    const dynamicHeaders = getDynamicHeaders(url, request);
+
+    // Visitor authentication
+    // @ts-ignore - request typing
+    const visitorToken = getVisitorToken(request, url);
 
     const result = await getPublishedContentByURL({
         url: url.toString(),
-        visitorAuthToken: null,
-        redirectOnError: false,
+        visitorAuthToken: visitorToken?.token ?? null,
+        // When the visitor auth token is pulled from the cookie, set redirectOnError when calling getPublishedContentByUrl to allow
+        // redirecting when the token is invalid as we could be dealing with stale token stored in the cookie.
+        // For example when the VA backend signature has changed but the token stored in the cookie is not yet expired.
+        redirectOnError: visitorToken?.source === 'visitor-auth-cookie',
     });
 
     if (result.error) {
@@ -66,17 +75,31 @@ async function serveSiteByURL(request: NextRequest, urlWithMode: URLWithMode) {
         return NextResponse.redirect(data.redirect);
     }
 
-    const routeType = dynamicHeaders ? 'dynamic' : 'static';
+    // When visitor has authentication (adaptive content or VA), we serve dynamic routes.
+    let routeType = visitorToken ? 'dynamic' : 'static';
 
     const requestHeaders = new Headers(request.headers);
     requestHeaders.set(MiddlewareHeaders.RouteType, routeType);
     requestHeaders.set(MiddlewareHeaders.URLMode, mode);
     requestHeaders.set(MiddlewareHeaders.SiteURL, `${url.origin}${data.basePath}`);
     requestHeaders.set(MiddlewareHeaders.SiteURLData, JSON.stringify(data));
-    if (dynamicHeaders) {
-        for (const [key, value] of Object.entries(dynamicHeaders)) {
-            requestHeaders.set(key, value);
-        }
+
+    // Preview of customization/theme
+    const customization = url.searchParams.get('customization');
+    if (customization && validateSerializedCustomization(customization)) {
+        routeType = 'dynamic';
+        requestHeaders.set(MiddlewareHeaders.Customization, customization);
+    }
+    const theme = url.searchParams.get('theme');
+    if (theme === CustomizationThemeMode.Dark || theme === CustomizationThemeMode.Light) {
+        routeType = 'dynamic';
+        requestHeaders.set(MiddlewareHeaders.Theme, theme);
+    }
+
+    // We support forcing dynamic routes by setting a `gitbook-dynamic-route` cookie
+    // This is useful for testing dynamic routes.
+    if (request.cookies.has('gitbook-dynamic-route')) {
+        routeType = 'dynamic';
     }
 
     // Pass a x-forwarded-host and origin that are equal to ensure Next doesn't block server actions when proxied
@@ -102,6 +125,17 @@ async function serveSiteByURL(request: NextRequest, urlWithMode: URLWithMode) {
 
     // Add Content Security Policy header
     response.headers.set('content-security-policy', getContentSecurityPolicy());
+    // Basic security headers
+    response.headers.set('strict-transport-security', 'max-age=31536000');
+    response.headers.set('referrer-policy', 'no-referrer-when-downgrade');
+    response.headers.set('x-content-type-options', 'nosniff');
+
+    if (visitorToken) {
+        const cookies = getResponseCookiesForVisitorAuth(data.basePath, visitorToken);
+        for (const [key, value] of Object.entries(cookies)) {
+            response.cookies.set(key, value.value, value.options);
+        }
+    }
 
     return response;
 }
@@ -121,9 +155,13 @@ function serveErrorResponse(error: Error) {
 }
 
 /**
- * The URL of the GitBook content can be passed in 3 different ways:
- * - The request URL is in the `X-GitBook-URL` header.
- * - The request URL is matching `/url/:url`
+ * The URL of the GitBook content can be passed in 3 different ways (in order of priority):
+ * - The request has a `X-GitBook-URL` header:
+ *      URL is taken from the header.
+ * - The request has a `X-Forwarded-Host` header:
+ *      Host is taken from the header, pathname is taken from the request URL.
+ * - The request URL is matching `/url/:url`:
+ *      URL is taken from the pathname.
  */
 function extractURL(request: NextRequest): URLWithMode | null {
     const xGitbookUrl = request.headers.get('x-gitbook-url');
@@ -134,6 +172,19 @@ function extractURL(request: NextRequest): URLWithMode | null {
         };
     }
 
+    const xForwardedHost = request.headers.get('x-forwarded-host');
+    // The x-forwarded-host is set by Vercel for all requests
+    // so we ignore it if the hostname is the same as the instance one.
+    if (xForwardedHost && GITBOOK_URL && new URL(GITBOOK_URL).host !== xForwardedHost) {
+        return {
+            url: appendQueryParams(
+                new URL(`https://${xForwardedHost}${request.nextUrl.pathname}`),
+                request.nextUrl.searchParams
+            ),
+            mode: 'url-host',
+        };
+    }
+
     const prefix = '/url/';
     if (request.nextUrl.pathname.startsWith(prefix)) {
         return {
@@ -148,17 +199,6 @@ function extractURL(request: NextRequest): URLWithMode | null {
     return null;
 }
 
-/**
- * Evaluate if a request is dynamic or static.
- */
-function getDynamicHeaders(_url: URL, _request: NextRequest): null | Record<string, string> {
-    // TODO:
-    // - check token in query string
-    // - check token in cookies
-    // - check special headers or query string
-    return null;
-}
-
 /**
  * Encode path in a site content.
  * Special paths are not encoded and passed to be handled by the route handlers.
diff --git a/packages/gitbook/src/lib/visitor-token.ts b/packages/gitbook/src/lib/visitor-token.ts
@@ -5,6 +5,18 @@ const VISITOR_AUTH_PARAM = 'jwt_token';
 const VISITOR_AUTH_COOKIE_ROOT = 'gitbook-visitor-token~';
 export const VISITOR_TOKEN_COOKIE = 'gitbook-visitor-token';
 
+export type ResponseCookie = {
+    value: string;
+    options?: Partial<{
+        httpOnly: boolean;
+        sameSite: boolean | 'lax' | 'strict' | 'none' | undefined;
+        secure: boolean;
+        maxAge: number;
+    }>;
+};
+
+export type ResponseCookies = Record<string, ResponseCookie>;
+
 /**
  * The contents of the visitor authentication cookie.
  */
@@ -62,6 +74,39 @@ export function getVisitorToken(
     }
 }
 
+/**
+ * Return the lookup result for content served with visitor auth. It basically disables caching
+ * and sets a cookie with the visitor auth token.
+ */
+export function getResponseCookiesForVisitorAuth(
+    basePath: string,
+    visitorTokenLookup: VisitorTokenLookup
+): ResponseCookies {
+    return {
+        /**
+         * If the visitor token has been retrieve from the URL, or if its a VA cookie and the basePath is the same, set it
+         * as a cookie on the response.
+         *
+         * Note that we do not re-store the gitbook-visitor-cookie in another cookie, to maintain a single source of truth.
+         */
+        ...(visitorTokenLookup?.source === 'url' ||
+        (visitorTokenLookup?.source === 'visitor-auth-cookie' &&
+            visitorTokenLookup.basePath === basePath)
+            ? {
+                  [getVisitorAuthCookieName(basePath)]: {
+                      value: getVisitorAuthCookieValue(basePath, visitorTokenLookup.token),
+                      options: {
+                          httpOnly: true,
+                          sameSite: process.env.NODE_ENV === 'production' ? 'none' : undefined,
+                          secure: process.env.NODE_ENV === 'production',
+                          maxAge: 7 * 24 * 60 * 60,
+                      },
+                  },
+              }
+            : {}),
+    };
+}
+
 /**
  * Get the name of the visitor authentication cookie for a given base path.
  *
diff --git a/packages/gitbook/src/middleware.ts b/packages/gitbook/src/middleware.ts
@@ -23,9 +23,9 @@ import { getContentSecurityPolicy } from '@/lib/csp';
 import { validateSerializedCustomization } from '@/lib/customization';
 import { setMiddlewareHeader } from '@/lib/middleware';
 import {
+    type ResponseCookies,
     type VisitorTokenLookup,
-    getVisitorAuthCookieName,
-    getVisitorAuthCookieValue,
+    getResponseCookiesForVisitorAuth,
     getVisitorToken,
     normalizeVisitorAuthURL,
 } from '@/lib/visitor-token';
@@ -69,19 +69,11 @@ type URLLookupMode =
      */
     | 'multi-id';
 
-export type LookupCookies = Record<
-    string,
-    {
-        value: string;
-        options?: Partial<ResponseCookie>;
-    }
->;
-
 export type LookupResult = PublishedContentWithCache & {
     /** API endpoint to use for the content post lookup */
     apiEndpoint?: string;
     /** Cookies to store on the response */
-    cookies?: LookupCookies;
+    cookies?: ResponseCookies;
     /** Visitor authentication token */
     visitorToken?: string;
     /** URL of the site */
@@ -229,12 +221,12 @@ export async function middleware(request: NextRequest) {
 
     const customization = url.searchParams.get('customization');
     if (customization && validateSerializedCustomization(customization)) {
-        headers.set('x-gitbook-customization', customization);
+        headers.set(MiddlewareHeaders.Customization, customization);
     }
 
     const theme = url.searchParams.get('theme');
     if (theme === CustomizationThemeMode.Dark || theme === CustomizationThemeMode.Light) {
-        headers.set('x-gitbook-theme', theme);
+        headers.set(MiddlewareHeaders.Theme, theme);
     }
 
     if (apiEndpoint) {
@@ -551,7 +543,7 @@ async function lookupSiteOrSpaceInMultiIdMode(
         );
     }
 
-    const cookies: LookupCookies = {
+    const cookies: ResponseCookies = {
         [cookieName]: {
             value: encodeGitBookTokenCookie(source.id, apiToken, apiEndpoint),
             options: {
@@ -798,29 +790,7 @@ function getLookupResultForVisitorAuth(
         // No caching for content served with visitor auth
         cacheMaxAge: undefined,
         cacheTags: [],
-        cookies: {
-            /**
-             * If the visitor token has been retrieve from the URL, or if its a VA cookie and the basePath is the same, set it
-             * as a cookie on the response.
-             *
-             * Note that we do not re-store the gitbook-visitor-cookie in another cookie, to maintain a single source of truth.
-             */
-            ...(visitorTokenLookup?.source === 'url' ||
-            (visitorTokenLookup?.source === 'visitor-auth-cookie' &&
-                visitorTokenLookup.basePath === basePath)
-                ? {
-                      [getVisitorAuthCookieName(basePath)]: {
-                          value: getVisitorAuthCookieValue(basePath, visitorTokenLookup.token),
-                          options: {
-                              httpOnly: true,
-                              sameSite: process.env.NODE_ENV === 'production' ? 'none' : undefined,
-                              secure: process.env.NODE_ENV === 'production',
-                              maxAge: 7 * 24 * 60 * 60,
-                          },
-                      },
-                  }
-                : {}),
-        },
+        cookies: getResponseCookiesForVisitorAuth(basePath, visitorTokenLookup),
     };
 }
 
