feat(chrome-extension): Add onChange cookie listeners (#4962)

Author: tmilewski

.changeset/green-bikes-end.md

@@ -0,0 +1,5 @@
+---
+'@clerk/chrome-extension': minor
+---
+
+Add experimental support for listening to cookie changes on a synced host via the `__experimental_syncHostListener`

packages/chrome-extension/src/internal/clerk.ts

@@ -6,6 +6,7 @@ import browser from 'webextension-polyfill';
 import { SCOPE, type Scope } from '../types';
 import { CLIENT_JWT_KEY, DEFAULT_LOCAL_HOST_PERMISSION } from './constants';
 import { assertPublishableKey } from './utils/errors';
+import type { JWTHandlerParams } from './utils/jwt-handler';
 import { JWTHandler } from './utils/jwt-handler';
 import { validateManifest } from './utils/manifest';
 import { requestHandler } from './utils/request-handler';
@@ -20,13 +21,15 @@ Clerk.sdkMetadata = {
 };
 
 export type CreateClerkClientOptions = {
+  __experimental_syncHostListener?: boolean;
   publishableKey: string;
   scope?: Scope;
   storageCache?: StorageCache;
   syncHost?: string;
 };
 
 export async function createClerkClient({
+  __experimental_syncHostListener = false,
   publishableKey,
   scope,
   storageCache = BrowserStorageCache,
@@ -60,17 +63,35 @@ export async function createClerkClient({
   // Set up JWT handler and attempt to get JWT from storage on initialization
   const url = syncHost ? syncHost : DEFAULT_LOCAL_HOST_PERMISSION;
 
-  const jwtOptions = {
+  // Create Clerk instance
+  clerk = new Clerk(publishableKey);
+
+  // @ts-expect-error - TODO: sync is evaluating to true vs boolean
+  const jwtOptions: JWTHandlerParams = {
     frontendApi: key.frontendApi,
     name: isProd ? CLIENT_JWT_KEY : DEV_BROWSER_JWT_KEY,
-    sync,
     url,
+    sync: sync,
   };
 
+  if (jwtOptions.sync && __experimental_syncHostListener) {
+    jwtOptions.onListenerCallback = () => {
+      if (clerk.user) {
+        clerk.user.reload();
+      } else {
+        window.location.reload();
+      }
+    };
+  }
+
   const jwt = JWTHandler(storageCache, jwtOptions);
 
-  // Create Clerk instance
-  clerk = new Clerk(publishableKey);
+  // Add listener to sync host cookies if enabled
+  if (jwtOptions.sync && __experimental_syncHostListener) {
+    const listener = jwt.listener();
+    listener?.add();
+  }
+
   clerk.__unstable__onAfterResponse(responseHandler(jwt, { isProd }));
   clerk.__unstable__onBeforeRequest(requestHandler(jwt, { isProd }));
 

packages/chrome-extension/src/internal/constants.ts

@@ -4,5 +4,6 @@ export const AUTH_HEADER = {
 };
 
 export const CLIENT_JWT_KEY = '__client';
+export const CLIENT_UAT_KEY = '__clerk_uat';
 export const DEFAULT_LOCAL_HOST_PERMISSION = 'http://localhost';
 export const STORAGE_KEY_CLIENT_JWT = '__clerk_client_jwt';

packages/chrome-extension/src/internal/utils/cookies.ts

@@ -1,9 +1,18 @@
 import browser from 'webextension-polyfill';
 
 export type FormattedUrl = `http${string}`;
+
 export type GetClientCookieParams = {
   name: string;
   url: string;
+  callback: (changeInfo: ChangeInfo) => Promise<void>;
+  onListenerCallback?: () => void;
+};
+
+export type ChangeInfo = {
+  cookie: browser.Cookies.Cookie;
+  cause: browser.Cookies.OnChangedCause;
+  removed: boolean;
 };
 
 function ensureFormattedUrl(url: string): FormattedUrl {
@@ -13,3 +22,20 @@ function ensureFormattedUrl(url: string): FormattedUrl {
 export async function getClientCookie({ url, name }: GetClientCookieParams) {
   return await browser.cookies.get({ name, url: ensureFormattedUrl(url) });
 }
+
+export function createClientCookieListener({ url, name, callback }: GetClientCookieParams) {
+  const domain = new URL(url).hostname;
+  const cookieDomain = domain.startsWith('www.') ? domain.slice(4) : domain;
+
+  const listener = (changeInfo: ChangeInfo) => {
+    if (changeInfo.cookie.domain === cookieDomain && changeInfo.cookie.name === name) {
+      void callback(changeInfo);
+    }
+  };
+
+  return {
+    add: () => browser.cookies.onChanged.addListener(listener),
+    has: () => browser.cookies.onChanged.hasListener(listener),
+    remove: () => browser.cookies.onChanged.removeListener(listener),
+  };
+}

packages/chrome-extension/src/internal/utils/jwt-handler.ts

@@ -1,12 +1,10 @@
-import { Poller } from '@clerk/shared/poller';
-
-import { STORAGE_KEY_CLIENT_JWT } from '../constants';
-import type { GetClientCookieParams } from './cookies';
-import { getClientCookie } from './cookies';
+import { CLIENT_UAT_KEY, STORAGE_KEY_CLIENT_JWT } from '../constants';
+import type { ChangeInfo, GetClientCookieParams } from './cookies';
+import { createClientCookieListener, getClientCookie } from './cookies';
 import { errorLogger } from './errors';
 import type { StorageCache } from './storage';
 
-type JWTHandlerParams = { frontendApi: string } & (
+export type JWTHandlerParams = { frontendApi: string } & (
   | {
       sync?: false;
     }
@@ -59,22 +57,33 @@ export function JWTHandler(store: StorageCache, params: JWTHandlerParams) {
     return await store.get<string>(CACHE_KEY);
   };
 
-  /**
-   * Polls for the synced session JWT via the get() function.
-   *
-   * @param delayInMs: Polling delay in milliseconds (default: 1500ms)
-   */
-  const poll = async (delayInMs = 1500) => {
-    const { run, stop } = Poller({ delayInMs });
+  const listener = () => {
+    if (!shouldSync(sync, cookieParams)) {
+      return;
+    }
 
-    void run(async () => {
-      const currentJWT = await get();
+    const { onListenerCallback, ...restCookieParams } = cookieParams;
 
-      if (currentJWT) {
-        stop();
-      }
+    return createClientCookieListener({
+      ...restCookieParams,
+      callback: async (changeInfo: ChangeInfo) => {
+        const existingJWT = await get();
+
+        if (existingJWT === changeInfo.cookie.value) {
+          const syncedUAT = await getClientCookie({ ...restCookieParams, name: CLIENT_UAT_KEY }).catch(errorLogger);
+
+          if (!syncedUAT || syncedUAT?.value === '0') {
+            onListenerCallback?.();
+          }
+
+          return;
+        }
+
+        await set(changeInfo.cookie.value);
+        onListenerCallback?.();
+      },
     });
   };
 
-  return { get, poll, set, remove };
+  return { get, listener, set, remove };
 }

packages/chrome-extension/src/react/ClerkProvider.tsx

@@ -7,21 +7,28 @@ import { createClerkClient } from '../internal/clerk';
 import type { StorageCache } from '../internal/utils/storage';
 
 type ChromeExtensionClerkProviderProps = ClerkReactProviderProps & {
+  /**
+   * @experimental
+   * @description Enables the listener to sync host cookies on changes.
+   */
+  __experimental_syncHostListener?: boolean;
   storageCache?: StorageCache;
   syncHost?: string;
 };
 
 export function ClerkProvider(props: ChromeExtensionClerkProviderProps): JSX.Element | null {
-  const { children, storageCache, syncHost, ...rest } = props;
+  const { children, storageCache, syncHost, __experimental_syncHostListener, ...rest } = props;
   const { publishableKey = '' } = props;
 
   const [clerkInstance, setClerkInstance] = React.useState<Clerk | null>(null);
 
   React.useEffect(() => {
     void (async () => {
-      setClerkInstance(await createClerkClient({ publishableKey, storageCache, syncHost }));
+      setClerkInstance(
+        await createClerkClient({ publishableKey, storageCache, syncHost, __experimental_syncHostListener }),
+      );
     })();
-  }, [publishableKey, storageCache, syncHost]);
+  }, [publishableKey, storageCache, syncHost, __experimental_syncHostListener]);
 
   if (!clerkInstance) {
     return null;

playground/browser-extension/README.md

@@ -26,6 +26,22 @@ After following the quickstart you'll have learned how to:
 - Load your Chrome Extension into your Chromium-based browser
 - Test your Chrome Extension
 
+
+## Connect with developement package
+
+Run the development server:
+```bash
+> cd playground/browser-extension
+> npm i
+> npm dev
+```
+
+In a separate terminal, build and publish the development package to your local registry:
+```bash
+> cd packages/chrome-extension
+> pnpm build && pnpm publish:local
+```
+
 ## Running the template
 
 ```bash

playground/browser-extension/package.json

@@ -1,5 +1,6 @@
 {
-  "name": "chrome-extension",
+  "name": "browser-extension",
+  "private": true,
   "displayName": "Clerk Chrome Extension Demo",
   "version": "0.0.1",
   "description": "A feature rich implementation of Clerk with a Plasmo-based Chrome Extension.",
@@ -11,10 +12,11 @@
     "debug:firefox": "plasmo dev --target=firefox-mv2 --verbose",
     "dev": "plasmo dev",
     "dev:firefox": "plasmo dev --target=firefox-mv2",
-    "start:firefox": "web-ext run --source-dir ./build/firefox-mv2-dev"
+    "start:firefox": "web-ext run --source-dir ./build/firefox-mv2-dev",
+    "yalc:add": "pnpm yalc add @clerk/chrome-extension"
   },
   "dependencies": {
-    "@clerk/chrome-extension": "file:../../packages/chrome-extension",
+    "@clerk/chrome-extension": "file:.yalc/@clerk/chrome-extension",
     "plasmo": "0.89.4",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
@@ -41,6 +43,7 @@
     ],
     "host_permissions": [
       "$CLERK_FRONTEND_API/*",
+      "$PLASMO_PUBLIC_CLERK_SYNC_HOST/*",
       "http://localhost/*"
     ],
     "key": "$CRX_PUBLIC_KEY"