Chrome extension integration guide

[andresgutgon]

What?

Hi, Andres here 👋 I've being using this lib only a few weeks for a side project but I think it's awesome. Coming from Rails world where we have Devise this looks super similar in the sense that is a very well though working solution but for nextjs.

My use case in my current side project is to make a nextjs backend with an API that will be consumed from a Chrome extension in a content script. Chrome extensions have different ways of showing content to user and doing actions. tab, background or content_script. I used content script because it allows me to inject a UI in the web page so the user can interact with my API.

As you can imagine interacting with a nextjs auth protected api requires users being logged in. And I want my users being logged in from the site where the Chrome extension is used. I haven't seen a lot of documentation on internet about this topic so I think it would be great to have a guide about it in this project so people with a similar use case to mine have a nice reference.

There's already some issue open about this

So what are the problems with Chrome extensions?

Chrome extension V3 (2023) are more extrict when it comes to security. Before it was possible to inject thrird party JS like the Google client Auth and open a login screen. But now that's not an option. Also anyway I want to being able to make calls to my API from the Chrome extensions with the user authenticated with a cookie session.

I wrote a document for myself to remember what I did. I'll post here so you can review and tell me if you think is the best approach.

Why we need SSL in development?

So Chrome extensions content scripts require your server two security measures in
order to be able to make request to your server from other web pages from your
content script

1. Configure CORS and allow those website to make requests against your server.
2. Make NextJS Auth to write session cookie as sameSite=none
   About sameSite=None

means that the browser sends the cookie with both cross-site and same-site requests. The Secure attribute must also be set when setting this value, like so SameSite=None; Secure.

So secure means your server needs to use https. And here we're setting SSL on
our local development nextjs app to write the next-auth session cookie as
sameSite=None and be able to read that cookie from the Chrome extension.

CORS

I followed NextJS CORS docs and this video
My middleware.ts looks like this:

import { NextResponse } from "next/server"
import getTrustedDomain from "@/lib/api/trustedDomains"

export function middleware(request: Request) {
  const domain = getTrustedDomain(request)

  if (!domain) {
    return new NextResponse(null, {
      status: 422,
      statusText: "Bad Request",
      headers: {
        'Content-Type': 'text/plain'
      }
    })
  }

  return NextResponse.next({
    headers: {
      'Access-Control-Allow-Credentials': 'true',
      'Access-Control-Allow-Origin': domain
    }
  })
}

export const config = {
  matcher: '/api/:path*',
}

And @/lib/api/trustedDomains looks like this:

/**
 * NOTE: Referer comes with a `/` at the end sometimes
 */
function addSlash(domain: string): string[] {
  return [domain, `${domain}/`]
}

// Put here all domains that can access your API
const ALLOWED_DOMAINS = [
  'https://example1.com',
  'https://example2.com',
  // ...
]

const TRUSTED_DOMAINS = [
  ...ALLOWED_DOMAINS,
  ...addSlash(process.env.NEXTAUTH_URL),
  ...addSlash('https://accounts.google.com') // Google Auth Callback
]

/**
 * Check origin/referer to allow CORS on external
 */
export default function isDomainTrusted(request: Request) {
  const origin = request.headers.get('Origin')
  const referer = request.headers.get('referer') ?? ''
  if (!origin && !referer) return null

  const domain = origin || referer
  const isTrusted = TRUSTED_DOMAINS.includes(domain)
  if (!isTrusted) return null

  return domain
}

From chrome extension fetch

You have to send Origin header from Chrome extension to tell the server the user is calling it from authorized domain. A basic fetch api call:

const headers = new Headers()
headers.set('Origin', window.location.origin)
headers.append('Accept', 'application/json')
const response = await window.fetch(
  'https://localhost:3001/api/me'
  {
      method: 'GET',
      mode: 'cors',
      credentials: 'include',
      headers,
  }
)

sameSite=None

This is needed to be able to do cross-site request. I have this in my nextjs auth config:

export const authOptions: NextAuthOptions = {
  secret: env.NEXTAUTH_SECRET,
  cookies: {
    sessionToken: {
      name: `__Secure-next-auth.session-token`,
      options: {
        httpOnly: true,
        sameSite: 'none',
        path: '/',
        secure: true
      }
    },
  },
  // rest of config
}

How to setup SSL in development?

The answer is using mkcert + local-ssl-proxy

mkcert: This is tool for generating a local SSL certificate and tell your
machine to trust it. It makes things super easy. If something is not clear after
reading this README read the readme on their repo.
local-ssl-proxy: I could setup a traefik/nginx in a docker compose as reverse
proxy for the nextjs app but I want to be able to debug and I feel that would
complicate debugging node server. Specially from the editor.

SSL in Development with mkcert

This is here to explain how to enable SSL while developing in your machine.
For generating the SSL certificate locally use mkcert (It can be installed with Homebrew in Mac OSX).

Run this:

cd ~/code/apps/web/ssl/certificates
mkcert localhost

package.json

"scripts": {
  "dev": "next dev",
  "ssl": "local-ssl-proxy --config ./ssl/config.json",
}

You have to open 2 terminals. NextJS non secure http://localhost:3000 and SSL secure proxy https://localhost:3001

You have to tell NextJS auth now your domain is the secure. Change your .env file like this:

NEXTAUTH_URL='https://localhost:3001'

Now you have to start your NextJS dev server normally:

pnpm dev

And on other terminal the https proxy:

pnpm ssl

All my SSL stuff is under a certificates folder like this:

my-root-app
  |- ssl
      |- config.json
      |- certificates
            - localhost.pem 
            - localhost-key.pem 

So we're telling NextJS auth that our app domain is the domain of the SSL local
proxy. Not the real NextJS domain http://localhost:3000. You can see this
config in ./ssl/config.json

{
  "your_app_name": {
    "hostname": "localhost",
    "source": 3001,
    "target": 3000,
    "cert": "ssl/certificates/localhost.pem",
    "key": "ssl/certificates/localhost-key.pem"
  }
}

I think that's all 🎉. Now I see from the page where my Chrome extension is used the cookie for session
Now how the other cookies I didn't set to None are not accesible (are in yellow)

---

Note about security

NextAuth docs
recommends not to override the cookie configuration. But I don't see other way
of achiving what I want. I don't know how this config can be insecure if the
goal of my app is to allow cross-site sessions between domains. Specially having
cors correctly configured and only allowing some specific sites to read cookies
session.

Using a custom cookie policy may introduce security flaws into your application and is intended as an option for advanced users who understand the implications. Using this option is not recommended.

I would change this warning for a more informative note on how to securely
configure a site for use sameSite=None. Even I would add an option to pass
this setting and do not need to override all the cookie.

---

Articles

About cookies and host permissions

Chrome extensions documentation is not the best. This article make the topics of
host permissions and cookies a bit clear for me:
https://www.gmass.co/blog/send-cookie-cross-origin-xmlhttprequest-chrome-extension/

1. Host permissions we ask permissions to user for manipulating something on
   that host. Maybe don't needed for the API because we're going to do this via
   AJAX. No permission needed to update my own server lol.
2. Cookies permissions in manifest.json is not for passing cookies via AJAX.
   Is for interacting with the cookies of a site via Chrome's API
   chrome.cookies.

[andresgutgon]

Signout

As a follow up to the discussion I'll try to explain how to make POST requests from the Chrome extension to the Nextjs API. I think we need to have access to the CSRF token

In the Chrome Extension

I copied what next-auth does here

import api from '@base/lib/api'

async function getCsrfToken() {
  return api.get({ path: 'auth/csrf' })
}

async function fetchLogout() {
  const { csrfToken } = await getCsrfToken()
  const callbackUrl = window.location.href
  await api.post({
    path: 'auth/signout',
    headers: { contentType: 'urlencoded' },
    // @ts-expect-error
    data: new URLSearchParams({
      csrfToken,
      callbackUrl,
      json: true,
    })
  })

  window.location.reload()
}

My ApiClient

You can use Axios or pure window.fetch. This is not important but just in case I'll explain how I do it.

The import api from '@base/lib/api' is an abstraction I made over standard window.fetch. You can check it here

This is how initialize the api

// `core` is where is the gist I posted
import { ApiClient } from 'core'

const api = new ApiClient({
  clientHostOrigin: window.location.origin,
  apiHost: env.VITE_API_HOST // This is the domain of your NextJS API Ex.: https://localhost:3001
})

export default api

[shlroland]

Thanks @andresgutgon. This guide is very inspiring to me. It would be better if you could give a complete sample code.

[andresgutgon]

I played with this in this repo. Is, as all my weekend projects, abandoned 😂 but I managed to do a chrome extension that log ins with Google. Is a mono repo with a NextJS app and a Vite app for the chrome extension.

https://github.com/andresgutgon/aibooknotes

Enjoy. Don't ask me much I barely remember what I did 😅

[shlroland]

It is a private repo for you? I can open it. 😳

[andresgutgon]

Upps, sorry now you should see it

[shlroland]

Thanks again. 🙏