Persist visitor params values in public visitor session cookie (#3231)

Author: spastorelli

packages/gitbook-v2/src/middleware.ts

@@ -10,7 +10,7 @@ import {
  type ResponseCookies,
  getPathScopedCookieName,
  getResponseCookiesForVisitorAuth,
- getVisitorPayload,
+ getVisitorData,
  normalizeVisitorAuthURL,
 } from '@/lib/visitors';
 import { serveResizedImage } from '@/routes/image';
@@ -95,7 +95,7 @@ async function serveSiteRoutes(requestURL: URL, request: NextRequest) {
  //
  // Detect and extract the visitor authentication token from the request
  //
- const { visitorToken, unsignedClaims } = getVisitorPayload({
+ const { visitorToken, unsignedClaims, visitorParamsCookie } = getVisitorData({
  cookies: request.cookies.getAll(),
  url: siteRequestURL,
  });
@@ -121,7 +121,13 @@ async function serveSiteRoutes(requestURL: URL, request: NextRequest) {
  apiToken,
  })
  );
- const cookies: ResponseCookies = [];
+
+ const cookies: ResponseCookies = visitorParamsCookie
+ ? [
+ // If visitor.* params were passed to the site URL, include a session cookie to persist these params across navigation.
+ visitorParamsCookie,
+ ]
+ : [];
 
  //
  // Handle redirects

packages/gitbook/src/lib/visitors.test.ts

@@ -178,7 +178,7 @@ describe('getVisitorUnsignedClaims', () => {
  const url = new URL('https://example.com/');
  const claims = getVisitorUnsignedClaims({ cookies, url });
 
- expect(claims).toStrictEqual({
+ expect(claims.all).toStrictEqual({
  bucket: { flags: { SITE_AI: true, SITE_PREVIEW: true } },
  launchdarkly: { flags: { ALPHA: true, API: true } },
  });
@@ -191,7 +191,12 @@ describe('getVisitorUnsignedClaims', () => {
 
  const claims = getVisitorUnsignedClaims({ cookies: [], url });
 
- expect(claims).toStrictEqual({
+ expect(claims.all).toStrictEqual({
+ isEnterprise: true,
+ language: 'fr',
+ country: 'fr',
+ });
+ expect(claims.fromVisitorParams).toStrictEqual({
  isEnterprise: true,
  language: 'fr',
  country: 'fr',
@@ -203,10 +208,13 @@ describe('getVisitorUnsignedClaims', () => {
 
  const claims = getVisitorUnsignedClaims({ cookies: [], url });
 
- expect(claims).toStrictEqual({
+ expect(claims.all).toStrictEqual({
  isEnterprise: true,
  // otherParam is not present
  });
+ expect(claims.fromVisitorParams).toStrictEqual({
+ isEnterprise: true,
+ });
  });
 
  it('should support nested query param keys via dot notation', () => {
@@ -216,7 +224,14 @@ describe('getVisitorUnsignedClaims', () => {
 
  const claims = getVisitorUnsignedClaims({ cookies: [], url });
 
- expect(claims).toStrictEqual({
+ expect(claims.all).toStrictEqual({
+ isEnterprise: true,
+ flags: {
+ ALPHA: true,
+ API: false,
+ },
+ });
+ expect(claims.fromVisitorParams).toStrictEqual({
  isEnterprise: true,
  flags: {
  ALPHA: true,
@@ -235,7 +250,7 @@ describe('getVisitorUnsignedClaims', () => {
  const url = new URL('https://example.com/');
  const claims = getVisitorUnsignedClaims({ cookies, url });
 
- expect(claims).toStrictEqual({});
+ expect(claims.all).toStrictEqual({});
  });
 
  it('should merge claims from cookies and visitor.* query params', () => {
@@ -250,16 +265,27 @@ describe('getVisitorUnsignedClaims', () => {
  },
  ];
  const url = new URL(
- 'https://example.com/?visitor.isEnterprise=true&visitor.flags.ALPHA=true&visitor.flags.API=false'
+ 'https://example.com/?visitor.isEnterprise=true&visitor.flags.ALPHA=true&visitor.flags.API=false&visitor.bucket.flags.HELLO=false'
  );
 
  const claims = getVisitorUnsignedClaims({ cookies, url });
 
- expect(claims).toStrictEqual({
+ expect(claims.all).toStrictEqual({
  role: 'admin',
  language: 'fr',
  bucket: {
- flags: { SITE_AI: true, SITE_PREVIEW: true },
+ flags: { HELLO: false, SITE_AI: true, SITE_PREVIEW: true },
+ },
+ isEnterprise: true,
+ flags: {
+ ALPHA: true,
+ API: false,
+ },
+ });
+
+ expect(claims.fromVisitorParams).toStrictEqual({
+ bucket: {
+ flags: { HELLO: false },
  },
  isEnterprise: true,
  flags: {

packages/gitbook/src/lib/visitors.ts

@@ -41,13 +41,15 @@ type ClaimPrimitive =
  | ClaimPrimitive[];
 
 /**
- * The result of a visitor info lookup that can include:
+ * The result of a visitor data lookup that can include:
  * - a visitor token (JWT)
  * - a record of visitor public/unsigned claims (JSON object)
+ * - a session cookie response to persist any visitor query params across navigations.
  */
-export type VisitorPayloadLookup = {
+export type VisitorDataLookup = {
  visitorToken: VisitorTokenLookup;
  unsignedClaims: Record<string, ClaimPrimitive>;
+ visitorParamsCookie: ResponseCookie | undefined;
 };
 
 /**
@@ -74,21 +76,26 @@ export type VisitorTokenLookup =
  | undefined;
 
 /**
- * Get the visitor info for the request including its token and/or unsigned claims when present.
+ * Get the visitor data for the request potentially including:
+ * - a JWT token that may contain signed claims or can be used for VA authentication.
+ * - a record of the unsigned claims passed via a cookie or visitor.* params.
+ * - a session cookie response that is used to persist any visitor.* params that were passed via the site URL.
  */
-export function getVisitorPayload({
+export function getVisitorData({
  cookies,
  url,
 }: {
  cookies: RequestCookies;
  url: URL | NextRequest['nextUrl'];
-}): VisitorPayloadLookup {
+}): VisitorDataLookup {
  const visitorToken = getVisitorToken({ cookies, url });
  const unsignedClaims = getVisitorUnsignedClaims({ cookies, url });
+ const visitorParamsCookie = getResponseCookieForVisitorParams(unsignedClaims.fromVisitorParams);
 
  return {
  visitorToken,
- unsignedClaims,
+ unsignedClaims: unsignedClaims.all,
+ visitorParamsCookie,
  };
 }
 
@@ -128,9 +135,19 @@ export function getVisitorToken({
 export function getVisitorUnsignedClaims(args: {
  cookies: RequestCookies;
  url: URL | NextRequest['nextUrl'];
-}): Record<string, ClaimPrimitive> {
+}): {
+ /**
+ * The unsigned claims coming from both `gitbook-visitor-public` cookies and `visitor.*` query params.
+ */
+ all: Record<string, ClaimPrimitive>;
+ /**
+ * The unsigned claims from the `visitor.*` query params.
+ */
+ fromVisitorParams: Record<string, ClaimPrimitive>;
+} {
  const { cookies, url } = args;
  const claims: Record<string, ClaimPrimitive> = {};
+ const searchParamsClaims: Record<string, ClaimPrimitive> = {};
 
  for (const cookie of cookies) {
  if (cookie.name.startsWith(VISITOR_UNSIGNED_CLAIMS_PREFIX)) {
@@ -149,11 +166,13 @@ export function getVisitorUnsignedClaims(args: {
  if (key.startsWith('visitor.')) {
  const claimPath = key.substring('visitor.'.length);
  const claimValue = parseVisitorQueryParamValue(value);
+
  setVisitorClaimByPath(claims, claimPath, claimValue);
+ setVisitorClaimByPath(searchParamsClaims, claimPath, claimValue);
  }
  }
 
- return claims;
+ return { all: claims, fromVisitorParams: searchParamsClaims };
 }
 
 /**
@@ -221,6 +240,26 @@ function parseVisitorQueryParamValue(value: string): ClaimPrimitive {
  return value;
 }
 
+/**
+ * Returns to cookie response to use in order to persist visitor params that were passed to the URL.
+ */
+function getResponseCookieForVisitorParams(
+ visitorParamsClaims: Record<string, ClaimPrimitive>
+): ResponseCookie | undefined {
+ if (Object.keys(visitorParamsClaims).length === 0) {
+ return undefined;
+ }
+
+ return {
+ name: VISITOR_UNSIGNED_CLAIMS_PREFIX,
+ value: JSON.stringify(visitorParamsClaims),
+ options: {
+ sameSite: process.env.NODE_ENV === 'production' ? 'none' : undefined,
+ secure: process.env.NODE_ENV === 'production',
+ },
+ };
+}
+
 /**
  * Return the lookup result for content served with visitor auth.
  */

packages/gitbook/src/middleware.ts

@@ -24,7 +24,7 @@ import {
  type ResponseCookies,
  type VisitorTokenLookup,
  getResponseCookiesForVisitorAuth,
- getVisitorPayload,
+ getVisitorData,
  normalizeVisitorAuthURL,
 } from '@/lib/visitors';
 
@@ -392,7 +392,7 @@ async function lookupSiteInProxy(request: NextRequest, url: URL): Promise<Lookup
  * When serving multi spaces based on the current URL.
  */
 async function lookupSiteInMultiMode(request: NextRequest, url: URL): Promise<LookupResult> {
- const { visitorToken } = getVisitorPayload({
+ const { visitorToken } = getVisitorData({
  cookies: request.cookies.getAll(),
  url,
  });
@@ -609,7 +609,7 @@ async function lookupSiteInMultiPathMode(request: NextRequest, url: URL): Promis
  const target = new URL(targetStr);
  target.search = url.search;
 
- const { visitorToken } = getVisitorPayload({
+ const { visitorToken } = getVisitorData({
  cookies: request.cookies.getAll(),
  url: target,
  });