Add methods in visitor util to return visitor unsigned claims and token

spastorelli · spastorelli · commit 44c35c043d44 · 2025-04-30T19:09:26.000+02:00
diff --git a/packages/gitbook-v2/src/middleware.ts b/packages/gitbook-v2/src/middleware.ts
@@ -10,9 +10,9 @@ import {
     type ResponseCookies,
     getPathScopedCookieName,
     getResponseCookiesForVisitorAuth,
-    getVisitorToken,
+    getVisitorPayload,
     normalizeVisitorAuthURL,
-} from '@/lib/visitor-token';
+} from '@/lib/visitors';
 import { serveResizedImage } from '@/routes/image';
 import {
     DataFetcherError,
@@ -85,8 +85,7 @@ async function serveSiteRoutes(requestURL: URL, request: NextRequest) {
     //
     // Detect and extract the visitor authentication token from the request
     //
-    // @ts-ignore - request typing
-    const visitorToken = getVisitorToken({
+    const { visitorToken } = getVisitorPayload({
         cookies: request.cookies.getAll(),
         url: siteRequestURL,
     });
diff --git a/packages/gitbook/src/lib/visitors.test.ts b/packages/gitbook/src/lib/visitors.test.ts
@@ -6,7 +6,8 @@ import {
     getVisitorAuthCookieName,
     getVisitorAuthCookieValue,
     getVisitorToken,
-} from './visitor-token';
+    getVisitorUnsignedClaims,
+} from './visitors';
 
 describe('getVisitorAuthToken', () => {
     it('should return the token from the query parameters', () => {
@@ -158,3 +159,139 @@ function assertVisitorAuthCookieValue(
 
     throw new Error('Expected a VisitorAuthCookieValue');
 }
+
+describe('getVisitorPublicClaims', () => {
+    it('should merge claims from multiple public cookies', () => {
+        const cookies = [
+            {
+                name: 'gitbook-visitor-public-bucket',
+                value: JSON.stringify({ bucket: { flags: { SITE_AI: true, SITE_PREVIEW: true } } }),
+            },
+            {
+                name: 'gitbook-visitor-public-launchdarkly',
+                value: JSON.stringify({
+                    launchdarkly: { flags: { ALPHA: true, API: true } },
+                }),
+            },
+        ];
+
+        const url = new URL('https://example.com/');
+        const claims = getVisitorUnsignedClaims({ cookies, url });
+
+        expect(claims).toStrictEqual({
+            bucket: { flags: { SITE_AI: true, SITE_PREVIEW: true } },
+            launchdarkly: { flags: { ALPHA: true, API: true } },
+        });
+    });
+
+    it('should parse visitor.* query params with simple types', () => {
+        const url = new URL(
+            'https://example.com/?visitor.isEnterprise=true&visitor.language=fr&visitor.country=fr'
+        );
+
+        const claims = getVisitorUnsignedClaims({ cookies: [], url });
+
+        expect(claims).toStrictEqual({
+            isEnterprise: true,
+            language: 'fr',
+            country: 'fr',
+        });
+    });
+
+    it('should ignore params that do not match visitor.* convention', () => {
+        const url = new URL('https://example.com/?visitor.isEnterprise=true&otherParam=true');
+
+        const claims = getVisitorUnsignedClaims({ cookies: [], url });
+
+        expect(claims).toStrictEqual({
+            isEnterprise: true,
+            // otherParam is not present
+        });
+    });
+
+    it('should ignore public cookies not present in the allowed list', () => {
+        const url = new URL('https://example.com/');
+
+        const claims = getVisitorUnsignedClaims({
+            cookies: [
+                {
+                    name: 'gitbook-visitor-public',
+                    value: JSON.stringify({ role: 'admin', language: 'fr' }),
+                },
+                // The claims in this cookie should be ignored
+                {
+                    name: 'gitbook-visitor-public-disallowed',
+                    value: JSON.stringify({
+                        disallowed: { flags: { SITE_AI: true, SITE_PREVIEW: true } },
+                    }),
+                },
+            ],
+            url,
+        });
+
+        expect(claims).toStrictEqual({
+            role: 'admin',
+            language: 'fr',
+        });
+    });
+
+    it('should support nested query param keys via dot notation', () => {
+        const url = new URL(
+            'https://example.com/?visitor.isEnterprise=true&visitor.flags.ALPHA=true&visitor.flags.API=false'
+        );
+
+        const claims = getVisitorUnsignedClaims({ cookies: [], url });
+
+        expect(claims).toStrictEqual({
+            isEnterprise: true,
+            flags: {
+                ALPHA: true,
+                API: false,
+            },
+        });
+    });
+
+    it('should ignore invalid JSON in cookie values', () => {
+        const cookies = [
+            {
+                name: 'gitbook-visitor-public',
+                value: '{not: "json"}',
+            },
+        ];
+        const url = new URL('https://example.com/');
+        const claims = getVisitorUnsignedClaims({ cookies, url });
+
+        expect(claims).toStrictEqual({});
+    });
+
+    it('should merge claims from cookies and visitor.* query params', () => {
+        const cookies = [
+            {
+                name: 'gitbook-visitor-public',
+                value: JSON.stringify({ role: 'admin', language: 'fr' }),
+            },
+            {
+                name: 'gitbook-visitor-public-bucket',
+                value: JSON.stringify({ bucket: { flags: { SITE_AI: true, SITE_PREVIEW: true } } }),
+            },
+        ];
+        const url = new URL(
+            'https://example.com/?visitor.isEnterprise=true&visitor.flags.ALPHA=true&visitor.flags.API=false'
+        );
+
+        const claims = getVisitorUnsignedClaims({ cookies, url });
+
+        expect(claims).toStrictEqual({
+            role: 'admin',
+            language: 'fr',
+            bucket: {
+                flags: { SITE_AI: true, SITE_PREVIEW: true },
+            },
+            isEnterprise: true,
+            flags: {
+                ALPHA: true,
+                API: false,
+            },
+        });
+    });
+});
diff --git a/packages/gitbook/src/lib/visitors.ts b/packages/gitbook/src/lib/visitors.ts
@@ -4,6 +4,11 @@ import hash from 'object-hash';
 
 const VISITOR_AUTH_PARAM = 'jwt_token';
 export const VISITOR_TOKEN_COOKIE = 'gitbook-visitor-token';
+const VISITOR_UNSIGNED_CLAIM_COOKIES = [
+    'gitbook-visitor-public',
+    'gitbook-visitor-public-bucket',
+    'gitbook-visitor-public-launchdarkly',
+];
 
 /**
  * Typing for a cookie, matching the internal type of Next.js.
@@ -30,6 +35,25 @@ type VisitorAuthCookieValue = {
     token: string;
 };
 
+type ClaimPrimitive =
+    | string
+    | number
+    | boolean
+    | null
+    | undefined
+    | { [key: string]: ClaimPrimitive }
+    | ClaimPrimitive[];
+
+/**
+ * The result of a visitor info lookup that can include:
+ *   - a visitor token (JWT)
+ *   - a record of visitor public/unsigned claims (JSON object)
+ */
+export type VisitorPayload = {
+    visitorToken: VisitorTokenLookup;
+    unsignedClaims: Record<string, ClaimPrimitive>;
+};
+
 /**
  * The result of a visitor token lookup.
  */
@@ -53,6 +77,25 @@ export type VisitorTokenLookup =
     /** Not visitor token was found */
     | undefined;
 
+/**
+ * Get the visitor info for the request including its token and/or unsigned claims when present.
+ */
+export function getVisitorPayload({
+    cookies,
+    url,
+}: {
+    cookies: RequestCookies;
+    url: URL | NextRequest['nextUrl'];
+}): VisitorPayload {
+    const visitorToken = getVisitorToken({ cookies, url });
+    const unsignedClaims = getVisitorUnsignedClaims({ cookies, url });
+
+    return {
+        visitorToken,
+        unsignedClaims,
+    };
+}
+
 /**
  * Get the visitor token for the request. This token can either be in the
  * query parameters or stored as a cookie.
@@ -82,6 +125,106 @@ export function getVisitorToken({
     }
 }
 
+/**
+ * Get the visitor unsigned/public claims for the request. They can either be in `visitor.` query
+ * parameters or stored in special `gitbook-visitor-public-*` cookies.
+ */
+export function getVisitorUnsignedClaims(args: {
+    cookies: RequestCookies;
+    url: URL | NextRequest['nextUrl'];
+}): Record<string, ClaimPrimitive> {
+    const { cookies, url } = args;
+    const claims: Record<string, ClaimPrimitive> = {};
+
+    for (const cookie of cookies) {
+        if (VISITOR_UNSIGNED_CLAIM_COOKIES.includes(cookie.name)) {
+            try {
+                const parsed = JSON.parse(cookie.value);
+                if (typeof parsed === 'object' && parsed !== null) {
+                    Object.assign(claims, parsed);
+                }
+            } catch (_err) {
+                console.warn(`Invalid JSON in unsigned claim cookie "${cookie.name}"`);
+            }
+        }
+    }
+
+    for (const [key, value] of url.searchParams.entries()) {
+        if (key.startsWith('visitor.')) {
+            const claimPath = key.substring('visitor.'.length);
+            const claimValue = parseVisitorQueryParamValue(value);
+            setVisitorClaimByPath(claims, claimPath, claimValue);
+        }
+    }
+
+    return claims;
+}
+
+/**
+ * Set the value of claims in a claims object at a specific path.
+ */
+function setVisitorClaimByPath(
+    claims: Record<string, ClaimPrimitive>,
+    keyPath: string,
+    value: ClaimPrimitive
+): void {
+    const keys = keyPath.split('.');
+    let current = claims;
+
+    for (let index = 0; index < keys.length; index++) {
+        const key = keys[index];
+
+        if (index === keys.length - 1) {
+            current[key] = value;
+        } else {
+            if (!(key in current) || !isClaimPrimitiveObject(current[key])) {
+                current[key] = {};
+            }
+
+            current = current[key];
+        }
+    }
+}
+
+function isClaimPrimitiveObject(value: unknown): value is Record<string, ClaimPrimitive> {
+    return typeof value === 'object' && value !== null;
+}
+
+/**
+ * Parse the value expected in a `visitor.` URL query parameter.
+ */
+function parseVisitorQueryParamValue(value: string): ClaimPrimitive {
+    if (value === 'true') {
+        return true;
+    }
+
+    if (value === 'false') {
+        return false;
+    }
+
+    if (value === 'null') {
+        return null;
+    }
+
+    if (value === 'undefined') {
+        return undefined;
+    }
+
+    const num = Number(value);
+    if (!Number.isNaN(num) && value.trim() !== '') {
+        return num;
+    }
+
+    try {
+        const parsed = JSON.parse(value);
+        if (typeof parsed === 'object' && parsed !== null) {
+            return parsed;
+        }
+    } catch {}
+
+    return value;
+}
+
 /**
  * Return the lookup result for content served with visitor auth.
  */
diff --git a/packages/gitbook/src/middleware.ts b/packages/gitbook/src/middleware.ts
