feat!: migrate to WorkOS as hosted auth, polish auth middlewares, fix logout

Author: NamesMT

README.md

@@ -23,13 +23,15 @@
     * [Utilities](#utilities)
     * [Build](#build)
     * [Develop](#develop)
-      * [Wrangler / Cloudflare Workers](#wrangler--cloudflare-workers)
+      * [Wrangler / Cloudflare Workers (Local dev via workerd)](#wrangler--cloudflare-workers-local-dev-via-workerd)
     * [Deploy](#deploy)
     * [Notes](#notes)
       * [`import` ordering](#import-ordering)
       * [Dev with SSL](#dev-with-ssl)
-    * [Remote Caching](#remote-caching)
+    * [Turborepo Remote Caching](#turborepo-remote-caching)
   * [Useful Links](#useful-links)
+    * [Turborepo](#turborepo)
+    * [grammY](#grammy)
 
 ## Overview
 
@@ -56,10 +58,10 @@ It is recommended to use an AI Agent ([`Roo Code`](https://github.com/RooVetGit/
   simply remove `sst` dependency and `sst.config.ts` if you want to use another solution.
 - *currently only `backend` app is configured, which will deploy a Lambda with Function URL enabled*
 
-🔐 Comes with starter-kit for [**Kinde**](https://kinde.com/) [typescript-sdk](https://github.com/kinde-oss/kinde-typescript-sdk), see: `/apps/backend/api/auth`
-- *Add your env variables, activate the auth routes, profit$*
+🔐 Comes with authentication boilerplate via [**WorkOS AuthKit**](https://workos.com/), see: `/apps/backend/api/auth`
+- *Add your env variables, DONE!*
 - Please note that by default `backend` comes with a cookies-based session manager, which have great DX, security and does not require an external database (which also means great performance), but as the `backend` is decoupled with the Nuxt's SSR server, it will not work well with SSR (the session/auth state is not shared).  
-So if you use SSR, you could use the official [Nuxt Kinde](https://nuxt.com/modules/kinde) module or implement your own way to manage the session at `apps/backend/src/middlewares/session.ts`.
+So, if you use SSR, you should implement another auth solution.
   - If you have a good session manager implementation, a PR is greatly appreciated!
 
 💯 JS is always [**TypeScript**](https://www.typescriptlang.org/) where possible.

apps/backend-convex/.env

@@ -1,4 +1,5 @@
 # Use `npx convex env` command to set the following environment variables:
 
-# CUSTOM_JWT_ISSUER=
-# CUSTOM_JWT_JWKS_URL=
+# CUSTOM_JWT_ISSUER=https://api.workos.com
+# CUSTOM_JWT_JWKS_URL=https://api.workos.com/sso/jwks/client_01JW6JMTP3CCKVBR5V7K8BT6R4
+# CUSTOM_JWT_CLIENT_ID=client_01JW6JMTP3CCKVBR5V7K8BT6R4

apps/backend-convex/README.md

@@ -8,9 +8,12 @@ Convex helps you kick-start amazing apps super fast and simple.
 
 Auth is optional, you can remove it or just put the following sample config into Convex (for testing and development, do not deploy a production app with this config):
 ```
-CUSTOM_JWT_ISSUER=https://topnames-dev.eu.kinde.com
-CUSTOM_JWT_JWKS_URL=https://topnames-dev.eu.kinde.com/.well-known/jwks
+CUSTOM_JWT_ISSUER=https://api.workos.com
+CUSTOM_JWT_JWKS_URL=https://api.workos.com/sso/jwks/client_01JW6JMTP3CCKVBR5V7K8BT6R4
+CUSTOM_JWT_CLIENT_ID=client_01JW6JMTP3CCKVBR5V7K8BT6R4
 ```
+**NOTE**: for auth to work with **WorkOS**, you currently need to manually add `aud` field to WorkOS's JWT payload yourself via `JWT Template` feature of WorkOS.  
+Ref: https://docs.convex.dev/auth/authkit/#debugging-authentication
 
 `convex dev` might create a few new files when you run it for the first time, you should discard it: `tsconfig.json`, `.gitignore`, `README.md`
 

apps/backend-convex/convex/auth.config.ts

@@ -4,6 +4,7 @@ export default {
       type: 'customJwt',
       issuer: process.env.CUSTOM_JWT_ISSUER!,
       jwks: process.env.CUSTOM_JWT_JWKS_URL!,
+      applicationID: process.env.CUSTOM_JWT_CLIENT_ID!,
       algorithm: 'RS256',
     },
   ],

apps/backend/.env

@@ -4,11 +4,9 @@
 # FRONTEND_URL=https://YOUR_FRONTEND_URL
 # CONVEX_URL=https://YOUR_CONVEX_URL
 
-# KINDE_DOMAIN=https://<YOUR_SUBDOMAIN>.kinde.com
-# KINDE_CLIENT_ID=
-# KINDE_CLIENT_SECRET=
-# KINDE_REDIRECT_URI=https://127.0.0.1:3300/api/auth/callback
-# KINDE_LOGOUT_REDIRECT_URI=https://127.0.0.1:3300/signed-out
+# WORKOS_CLIENT_ID=
+# WORKOS_API_KEY=
+# WORKOS_REDIRECT_URI=https://127.0.0.1:3300/api/auth/callback
 
 # GRAMMY_MAIN_TOKEN=
 # GRAMMY_MAIN_WEBHOOK_SECRET_TOKEN=

apps/backend/.env.dev

@@ -5,11 +5,9 @@ APP_DEV_port=3301
 FRONTEND_URL=https://127.0.0.1:3300
 CONVEX_URL=
 
-# KINDE_DOMAIN=https://<YOUR_SUBDOMAIN>.kinde.com
-# KINDE_CLIENT_ID=
-# KINDE_CLIENT_SECRET=
-KINDE_REDIRECT_URI=https://127.0.0.1:3300/api/auth/callback
-KINDE_LOGOUT_REDIRECT_URI=https://127.0.0.1:3300/signed-out
+# WORKOS_CLIENT_ID=
+# WORKOS_API_KEY=
+WORKOS_REDIRECT_URI=https://127.0.0.1:3300/api/auth/callback
 
 # GRAMMY_MAIN_TOKEN=
 # GRAMMY_MAIN_WEBHOOK_SECRET_TOKEN=

apps/backend/README.md

@@ -10,7 +10,7 @@
 - [Session management](./src/middlewares/session.ts).
 - Multi-platform support, one codebase that works for Node, Cloudflare Workers, AWS Lambda, and more.
 - Efficient providers management pattern, auto-optimize depends on platforms, with on-demand initialization support, sample providers includes:
-  - Kinde auth
+  - WorkOS AuthKit
   - Convex
   - grammY telegram bot
 - And more minor goodies!
@@ -19,7 +19,7 @@
 
 ## Structuring cookbook:
 #### Root level:
-Things like 3rd party APIs, DBs, Storages connectors, etc, should be placed in `#src/providers` folder, grouped by their purpose if possible, e.g: `#src/providers/auth/kinde-main.ts`, `#src/providers/db/neon-main.ts`.
+Things like 3rd party APIs, DBs, Storages connectors, etc, should be placed in `#src/providers` folder, grouped by their purpose if possible, e.g: `#src/providers/auth/workos-main.ts`, `#src/providers/db/neon-main.ts`.
 
 Things that interact with `#src/providers` should be placed in `#src/services` folder. (like an `user` service)
 

apps/backend/package.json

@@ -21,13 +21,13 @@
   },
   "devDependencies": {
     "@hono/standard-validator": "^0.1.5",
-    "@kinde-oss/kinde-typescript-sdk": "^2.13.0",
     "@local/common": "workspace:*",
     "@local/locales": "workspace:*",
     "@local/tsconfig": "workspace:*",
     "@namesmt/utils": "^0.5.18",
     "@scalar/hono-api-reference": "^0.9.22",
     "@vitest/coverage-v8": "^3.2.4",
+    "@workos-inc/node": "^7.71.0",
     "arktype": "^2.1.23",
     "backend-convex": "workspace:*",
     "convex": "^1.28.0",
@@ -36,7 +36,6 @@
     "hono-adapter-aws-lambda": "^1.3.3",
     "hono-cookie-state": "^0.1.3",
     "hono-openapi": "^1.1.0",
-    "hono-sessions": "^0.8.0",
     "petite-vue-i18n": "^11.1.12",
     "std-env": "^3.10.0",
     "tsdown": "^0.15.7",

apps/backend/src/api/$.ts

@@ -10,7 +10,7 @@ export const apiApp = appFactory.createApp()
   // Simple health check route
   .route('', apiRoute)
 
-  // Auth app - you'll need to setup Kinde environment variables.
+  // Auth app - you'll need to setup WorkOS environment variables.
   .route('/auth', authApp)
 
   // Some example routes

apps/backend/src/api/auth/$.middleware.ts

@@ -1,28 +1,31 @@
 import { appFactory } from '#src/helpers/factory.js'
-import { getSessionManager } from '#src/helpers/kinde.js'
-import { getKindeClient } from '#src/providers/auth/kinde-main.js'
+import { getWorkOS, getWorkOSJwks } from '#src/providers/auth/workos-main.js'
 import { DetailedError } from '@namesmt/utils'
-import { decode } from 'hono/jwt'
+import { decode, verifyWithJwks } from 'hono/jwt'
 
 export function keepAuthFresh() {
   return appFactory.createMiddleware(async (c, next) => {
-    const kindeClient = await getKindeClient()
-    const session = c.get('session')
-    const sessionManager = getSessionManager(c)
+    const workos = await getWorkOS()
+    const auth = c.get('backend-auth')
+    const userAuth = auth.data.userAuth
 
-    const userAuth = session.data.userAuth
     if (!userAuth)
       return await next()
 
-    const accessToken = await kindeClient.getToken(getSessionManager(c))
-
     // If token will expire in less than 20 minutes, refresh it
-    if ((decode(accessToken)?.payload?.exp || 0) * 1000 < Date.now() + 1000 * 60 * 20) {
-      const tokenRefresh = await kindeClient.refreshTokens(sessionManager, true)
+    if ((decode(userAuth.private.accessToken)?.payload?.exp || 0) * 1000 < Date.now() + 1000 * 60 * 20) {
+      const { accessToken, refreshToken } = await workos.userManagement.authenticateWithRefreshToken({
+        clientId: workos.clientId!,
+        refreshToken: userAuth.private.refreshToken,
+      })
 
-      session.data.userAuth = {
+      auth.data.userAuth = {
         ...userAuth,
-        tokens: { accessToken: tokenRefresh.access_token },
+        private: {
+          accessToken,
+          refreshToken,
+          sessionId: decode(accessToken).payload.sid as string,
+        },
       }
     }
 
@@ -32,23 +35,40 @@ export function keepAuthFresh() {
 
 export type checkAuthParams = {
   /**
-   * If false, will only throw if user is authenticated but token verification fails.
+   * Throws when the user is simply not authenticated yet (expired/revoked is still valid).
    *
    * @default true
    */
   throwOnUnauthenticated?: boolean
+
+  /**
+   * Throws when user is authenticated but the token fails to verify (including expired/revoked, etc).
+   *
+   * @default true
+   */
+  throwOnBadToken?: boolean
 }
-export function checkAuth({ throwOnUnauthenticated = true }: checkAuthParams = {}) {
+export function checkAuth({ throwOnUnauthenticated = true, throwOnBadToken = true }: checkAuthParams = {}) {
   return appFactory.createMiddleware(async (c, next) => {
-    const session = c.get('session')
-    const userAuth = session.data.userAuth
+    const auth = c.get('backend-auth')
+    const userAuth = auth.data.userAuth
+
     if (!userAuth) {
       if (throwOnUnauthenticated)
         throw new DetailedError('user is not authenticated', { statusCode: 401 })
 
       return await next()
     }
 
+    const _wosPayload = userAuth && await verifyWithJwks(userAuth.private.accessToken, await getWorkOSJwks())
+      .catch((e) => {
+        // Clears `userAuth` if token is bad
+        auth.data.userAuth = undefined
+
+        if (throwOnBadToken)
+          throw e
+      })
+
     // TODO: permission tokens system here
 
     await next()