feat(chrome-extension): Handle manifest permissions in a more-deterministic fashion

[tmilewski]

Description

Breaking Change: Service Workers / Session Handling

The extension now requires the storage permission in order to maintain sessions and provide authenticated access to other extension features, such as service workers.

How to Update:

• Please add storage to the permissions key in your extension manifest.

Breaking Change: Host Session Syncing

The extension no longer infers the sync host as the original implementation led to increased configuration confusion and false positives.

As such, we've replaced syncSessionWithTab with syncHost. You can set syncHost to the host URL you intend to retrieve the authentication state from.

How to Update:

• Please replace syncSessionWithTab with syncHost="<YOUR_CLERK_FRONTEND_API_DOMAIN>"
• Please ensure that the sync host, along with your app host, is listed in host_permissions and appended with /*. e.g.: https://<YOUR_DOMAIN>/* and https://clerk.<YOUR_DOMAIN>/*

Fixes ECO-212

Feature: Service Workers createClerkClient

We've introduced a new method createClerkClient to handle background tasks in your extension!

import { createClerkClient } from '@clerk/chrome-extension/background';

// Create a new Clerk instance and get a fresh token for the user
async function getToken() {
  const clerk = await createClerkClient({
    publishableKey: process.env.PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY,
  });
  return await clerk.session?.getToken();
}

// Create a listener to listen for messages from content scripts
// NOTE: A runtime listener cannot be async.
//       It must return true, in order to keep the connection open and send a response later.
chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  // You can use the token in the listener to perform actions on behalf of the user
  // OR send the token back to the content script
  getToken().then(token => sendResponse({ token }));
  return true;
});

Fixes ECO-213

Checklist

• [x] npm test runs as expected.
• [x] npm run build runs as expected.
• [ ] (If applicable) JSDoc comments have been added or updated for any package exports
• [ ] (If applicable) Documentation has been updated

Type of change

• [x] 🐛 Bug fix
• [x] 🌟 New feature
• [x] 🔨 Breaking change
• [x] 📖 Refactoring / dependency upgrade / documentation
• [ ] other: