feat(chrome-extension,shared): Expand WebSSO capabilities. [SDK-836]

Author: tmilewski

.changeset/perfect-monkeys-beg.md

@@ -0,0 +1,40 @@
+---
+'@clerk/chrome-extension': major
+'@clerk/shared': patch
+---
+
+Expand the ability for `@clerk/chrome-extension` WebSSO to sync with host applications which use URL-based session syncing.
+
+### How to Update
+
+**WebSSO Local Host Permissions:**
+
+Add `*://localhost:*/*` to the `host_permissions` array in your `manifest.json` file:
+```json
+{
+  "host_permissions": ["*://localhost:*/*"]
+}
+```
+
+If you're using a local domain other than `localhost`, you'll want replace that entry with your domain: `*://<DOMAIN>/*`
+
+```json
+{
+  "host_permissions": ["*://<DOMAIN>/*"]
+}
+```
+
+**WebSSO Provider settings:**
+
+```tsx
+<ClerkProvider
+  publishableKey={publishableKey}
+  routerPush={to => navigate(to)}
+  routerReplace={to => navigate(to, { replace: true })}
+  syncSessionWithTab
+
+  // [Development Only]: If the host application isn't on 
+  // `http://localhost`, you can provide it here:
+  syncSessionHost="http://<DOMAIN>"
+>
+```

package-lock.json

@@ -134,19 +134,34 @@ The 2 supported cases (links to different branches of the same repository):
 
 ## WebSSO required settings
 
-### Permissions (in manifest.json)
+### Extension Manifest (`manifest.json`)
 
-- "cookies" for more info see (here)[https://developer.chrome.com/docs/extensions/reference/cookies/]
-- "storage" for more info see (here)[https://developer.chrome.com/docs/extensions/reference/storage/]
+#### Permissions
 
-### Host permissions (in manifest.json)
-
-You will need your Frontend API URL, which can be found in your `Dashboard > API Keys > Advanced > Clerk API URLs`.
+You must enable the following permissions in your `manifest.json` file:
 
 ```
-"host_permissions": ["*://YOUR_CLERK_FRONTEND_API_GOES_HERE/"],
+"permissions": ["cookies", "storage"]
 ```
 
+- For more info on the "cookies" permission: (Google Developer Cookies Reference)[https://developer.chrome.com/docs/extensions/reference/cookies/]
+- For more info on the "storage" permission: (Google Developer Storage Reference)[https://developer.chrome.com/docs/extensions/reference/storage/]
+
+#### Host Permissions
+
+You must enable the following host permissions in your `manifest.json` file:
+
+- **Development:** `"host_permissions": ["*://localhost:*/*"]`
+  - If you're using a domain other than `localhost`, you'll want replace that entry with your domain: `*://<DOMAIN>/*`
+- **Production:** `"host_permissions": ["*://<YOUR_CLERK_FRONTEND_API_GOES_HERE>/"]`
+  - Your Frontend API URL can be found in `Clerk Dashboard > API Keys > Advanced > Clerk API URLs`.
+
+For more info on host permissions: (Google Developer `host_permissions` Reference)[https://developer.chrome.com/docs/extensions/mv3/declare_permissions/#host-permissions]
+
+#### ClerkProvider
+
+If your plan to sync sessions with a host application not on `localhost`, you'll need to use the `syncSessionHost` prop on `ClerkProvider` to specify the domain you're using, inclusive of the protocol. (eg: `https://<domain>`)
+
 <a name="clerk-settings"></a>
 
 ### Clerk settings
@@ -160,10 +175,6 @@ curl  -X PATCH https://api.clerk.com/v1/instance \
       -d '{"allowed_origins": ["chrome-extension://extension_id_goes_here"]}'
 ```
 
-## Development
-
-The `Enable URL-based session syncing` should be `DISABLED` from the `Clerk Dashboard > Setting` for a development instance to support @clerk/chrome-extension functionality.
-
 ## Deploy to Production
 
 Setting the `allowed_origins` (check [Clerk Settings](#clerk-settings)) is **REQUIRED** for both **Development** and **Production** instances when using the WebSSO use case.

packages/chrome-extension/README.md

@@ -6,7 +6,7 @@ module.exports = {
 
   roots: ['<rootDir>/src'],
   testEnvironment: 'jsdom',
-  setupFilesAfterEnv: ['<rootDir>../../jest.setup-after-env.ts'],
+  setupFilesAfterEnv: ['<rootDir>../../jest.setup-after-env.ts', '<rootDir>/jest.setup.ts'],
 
   moduleDirectories: ['node_modules', '<rootDir>/src'],
   transform: {

packages/chrome-extension/jest.config.js

@@ -0,0 +1,21 @@
+globalThis.chrome = {
+  cookies: {
+    // @ts-expect-error - Mock implementation
+    get: jest.fn(({ url, name }) => `cookies.get:${url}:${name}`),
+  },
+  runtime: {
+    // @ts-expect-error - Mock implementation
+    getManifest: jest.fn(() => ({
+      permissions: ['cookies', 'storage'],
+      host_permissions: ['https://*/*'],
+    })),
+  },
+  storage: {
+    // @ts-expect-error - Mock implementation
+    local: {
+      // @ts-expect-error - Mock implementation
+      get: jest.fn(async k => Promise.resolve({ [k]: `storage.get:${k}` })),
+      set: jest.fn(async () => Promise.resolve()),
+    },
+  },
+};

packages/chrome-extension/jest.setup.ts

@@ -45,11 +45,12 @@
     "test:coverage": "jest --collectCoverage && open coverage/lcov-report/index.html"
   },
   "dependencies": {
-    "@clerk/clerk-js": "5.0.0-alpha-v5.6",
-    "@clerk/clerk-react": "5.0.0-alpha-v5.6"
+    "@clerk/clerk-js": "*",
+    "@clerk/clerk-react": "*",
+    "@clerk/shared": "*"
   },
   "devDependencies": {
-    "@types/chrome": "*",
+    "@types/chrome": "latest",
     "@types/node": "^18.17.0",
     "@types/react": "*",
     "@types/react-dom": "*",