feat(clerk): add support for JWKS endpoint verification

Author: Jeroen Peeters

plugins/clerk/README.md

@@ -11,6 +11,7 @@ Add the ClerkPlugin plugin to your Starbase configuration:
 ```typescript
 import { ClerkPlugin } from './plugins/clerk'
 const clerkPlugin = new ClerkPlugin({
+    dataSource,
     clerkInstanceId: 'ins_**********',
     clerkSigningSecret: 'whsec_**********',
     clerkSessionPublicKey: '-----BEGIN PUBLIC KEY***'
@@ -25,32 +26,45 @@ If you want to use the Clerk plugin to verify sessions, change the function `aut
 
 ```diff
 ... existing code ...
+-                       if (!payload.sub) {
++                       if (!payload.sub || !await clerkPlugin.sessionExistsInDb(payload)) {
+                                throw new Error(
+                                'Invalid JWT payload, subject not found.'
+                            )
+                        }
+
+                        context = payload
 } else {
-+    try {
-+        const authenticated = await clerkPlugin.authenticate(request, dataSource)
-+        if (!authenticated) {
-+            throw new Error('Unauthorized request')
-+        }
-+    } catch (error) {
-        // If no JWT secret or JWKS endpoint is provided, then the request has no authorization.
-        throw new Error('Unauthorized request')
-    }
++   const authenticated = await clerkPlugin.authenticate({
++       cookie: request.headers.get("Cookie"),
++       token,
++   })
+    // If no JWT secret or JWKS endpoint is provided, then the request has no authorization.
+-   throw new Error('Unauthorized request')
++   if (!authenticated) throw new Error('Unauthorized request')
++   context = authenticated
 }
 ... existing code ...
 ```
 
 ## Configuration Options
 
-| Option                  | Type     | Default | Description                                                                                      |
-| ----------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------ |
-| `clerkSigningSecret`    | string   | `null`  | Access your signing secret from (https://dashboard.clerk.com/last-active?path=webhooks)          |
-| `clerkInstanceId`       | string   | `null`  | (optional) Access your instance ID from  (https://dashboard.clerk.com/last-active?path=settings) |
-| `verifySessions`        | boolean  | `true`  | (optional) Verify sessions                                                                       |
-| `clerkSessionPublicKey` | string   | `null`  | (optional) Access your public key from (https://dashboard.clerk.com/last-active?path=api-keys)   |
-| `permittedOrigins`      | string[] | `[]`    | (optional) A list of allowed origins                                                             |
+| Option                  | Type       | Default | Description                                                                                                                             |
+| ----------------------- | ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `dataSource`            | DataSource | `null`  | dataSource is needed to create tables and execute queries.                                                                              |
+| `clerkSigningSecret`    | string     | `null`  | Access your signing secret from (https://dashboard.clerk.com/last-active?path=webhooks)                                                 |
+| `clerkInstanceId`       | string     | `null`  | (optional) Access your instance ID from  (https://dashboard.clerk.com/last-active?path=settings)                                        |
+| `clerkSessionPublicKey` | string     | `null`  | (optional) Access your public key from (https://dashboard.clerk.com/last-active?path=api-keys) if you want to verify using a public key |
+| `verifySessions`        | boolean    | `true`  | (optional) Verify sessions, this creates a user_session table to store session data                                                     |
+| `permittedOrigins`      | string[]   | `[]`    | (optional) A list of allowed origins                                                                                                    |
 
 ## How To Use
 
+### Available Methods
+
+- `authenticate` - Authenticates a request using the Clerk session public key, returns the payload if authenticated, false in any other case.
+- `sessionExistsInDb` - Checks if a user session exists in the database, returns true if it does, false in any other case.
+
 ### Webhook Setup
 
 For our Starbase instance to receive webhook events when user information changes, we need to add our plugin endpoint to Clerk.
@@ -66,3 +80,8 @@ For our Starbase instance to receive webhook events when user information change
     - Visit the API Keys page for your Clerk instance: https://dashboard.clerk.com/last-active?path=api-keys
     - Click the copy icon next to `JWKS Public Key`
 5. Copy the public key into the Clerk plugin
+6. Alternatively, you can use a JWKS endpoint instead of a public key.
+    - Visit the API Keys page for your Clerk instance: https://dashboard.clerk.com/last-active?path=api-keys
+    - Click the copy icon next to `JWKS URL`
+    - Paste the URL under `AUTH_JWKS_ENDPOINT` in your `wrangler.toml`
+    - Tweak the `authenticate` function in `src/index.ts` to check whether the session exists in the database, as shown in the [Usage](#usage) section.

plugins/clerk/index.ts

@@ -1,5 +1,5 @@
 import { parse } from 'cookie'
-import { jwtVerify, importSPKI } from 'jose'
+import { jwtVerify, importSPKI, JWTPayload } from 'jose'
 import { Webhook } from 'svix'
 import { StarbaseApp } from '../../src/handler'
 import { StarbasePlugin } from '../../src/plugin'
@@ -68,6 +68,7 @@ export class ClerkPlugin extends StarbasePlugin {
         clerkSessionPublicKey?: string
         verifySessions?: boolean
         permittedOrigins?: string[]
+        dataSource: DataSource
     }) {
         super('starbasedb:clerk', {
             // The `requiresAuth` is set to false to allow for the webhooks sent by Clerk to be accessible
@@ -83,12 +84,11 @@ export class ClerkPlugin extends StarbasePlugin {
         this.clerkSessionPublicKey = opts.clerkSessionPublicKey
         this.verifySessions = opts.verifySessions ?? true
         this.permittedOrigins = opts.permittedOrigins ?? []
+        this.dataSource = opts.dataSource
     }
 
     override async register(app: StarbaseApp) {
-        app.use(async (c, next) => {
-            this.dataSource = c?.get('dataSource')
-
+        app.use(async (_, next) => {
             // Create user table if it doesn't exist
             await this.dataSource?.rpc.executeQuery({
                 sql: SQL_QUERIES.CREATE_USER_TABLE,
@@ -145,6 +145,8 @@ export class ClerkPlugin extends StarbasePlugin {
                         sql: SQL_QUERIES.DELETE_USER,
                         params: [id],
                     })
+
+                    // todo if user is deleted, delete all sessions for that user
                 } else if (
                     event.type === 'user.updated' ||
                     event.type === 'user.created'
@@ -190,28 +192,24 @@ export class ClerkPlugin extends StarbasePlugin {
     /**
      * Authenticates a request using the Clerk session public key.
      * heavily references https://clerk.com/docs/backend-requests/handling/manual-jwt
-     * @param request The request to authenticate.
-     * @param dataSource The data source to use for the authentication. Must be passed as a param as this can be called before the plugin is registered.
-     * @returns {boolean} True if authenticated, false if not, undefined if the public key is not present.
+     * @param cookie The cookie to authenticate.
+     * @param token The token to authenticate.
+     * @returns {JWTPayload | false} The decoded payload if authenticated, false if not.
      */
-    public async authenticate(request: Request, dataSource: DataSource): Promise<boolean | undefined> {
+    public async authenticate({ cookie, token: tokenCrossOrigin }: { cookie?: string | null, token?: string }) {
         if (!this.verifySessions || !this.clerkSessionPublicKey) {
-            throw new Error('Public key or session verification is not enabled.')
+            console.error('Public key or session verification is not enabled.')
+            return false
         }
 
         const COOKIE_NAME = "__session"
-        const cookie = parse(request.headers.get("Cookie") || "")
-        const tokenSameOrigin = cookie[COOKIE_NAME]
-        const tokenCrossOrigin = request.headers.get("Authorization")?.replace('Bearer ', '') ?? null
-
-        if (!tokenSameOrigin && !tokenCrossOrigin) {
-            return false
-        }
+        const tokenSameOrigin = cookie ? parse(cookie)[COOKIE_NAME] : undefined
+        if (!tokenSameOrigin && !tokenCrossOrigin) return false
 
         try {
             const publicKey = await importSPKI(this.clerkSessionPublicKey, 'RS256')
             const token = tokenSameOrigin || tokenCrossOrigin
-            const decoded = await jwtVerify(token!, publicKey)
+            const decoded = await jwtVerify<{ sid: string; sub: string }>(token!, publicKey)
 
             const currentTime = Math.floor(Date.now() / 1000)
             if (
@@ -229,23 +227,37 @@ export class ClerkPlugin extends StarbasePlugin {
                 return false
             }
 
-            const sessionId = decoded.payload.sid
-            const userId = decoded.payload.sub
-
-            const result: any = await dataSource?.rpc.executeQuery({
-                sql: SQL_QUERIES.GET_SESSION,
-                params: [sessionId, userId],
-            })
-
-            if (!result?.length) {
+            const sessionExists = await this.sessionExistsInDb(decoded.payload)
+            if (!sessionExists) {
                 console.error("Session not found")
                 return false
             }
 
-            return true
+            return decoded.payload
         } catch (error) {
             console.error('Authentication error:', error)
-            throw error
+            return false
+        }
+    }
+
+    /**
+     * Checks if a user session exists in the database.
+     * @param sessionId The session ID to check.
+     * @param userId The user ID to check.
+     * @param dataSource The data source to use for the check.
+     * @returns {boolean} True if the session exists, false if not.
+     */
+    public async sessionExistsInDb(payload: { sub: string, sid: string }): Promise<boolean> {        
+        try {
+            const result: any = await this.dataSource?.rpc.executeQuery({
+                sql: SQL_QUERIES.GET_SESSION,
+                params: [payload.sid, payload.sub],
+            })
+            
+            return result?.length > 0
+        } catch (error) {
+            console.error('db error while fetching session:', error)
+            return false
         }
     }
 }