feat!: auth improvements, refactors (desc)

Middleware to help check authentication state and refresh session
Custom interface for `authState` for provider-agnostic
Moved Kinde token to another cookie session key
Migrate to `hono-cookie-state`
Update deps
Apply lint fixes

Resolves #52

Author: NamesMT

apps/backend-convex/package.json

@@ -17,27 +17,27 @@
     "_deploy": "convex deploy -y"
   },
   "dependencies": {
-    "@ai-sdk/anthropic": "^2.0.17",
-    "@ai-sdk/google": "^2.0.15",
-    "@ai-sdk/groq": "^2.0.20",
-    "@ai-sdk/openai": "^2.0.32",
+    "@ai-sdk/anthropic": "^2.0.23",
+    "@ai-sdk/google": "^2.0.17",
+    "@ai-sdk/groq": "^2.0.22",
+    "@ai-sdk/openai": "^2.0.44",
     "@ai-sdk/provider": "^2.0.0",
-    "@convex-dev/rate-limiter": "^0.2.12",
+    "@convex-dev/rate-limiter": "^0.2.13",
     "@convex-dev/sharded-counter": "^0.1.8",
     "@hono/zod-validator": "^0.7.3",
     "@openrouter/ai-sdk-provider": "^1.2.0",
-    "ai": "^5.0.49",
+    "ai": "^5.0.60",
     "convex-helpers": "^0.1.104",
     "destr": "^2.0.5",
-    "hono": "^4.9.8",
-    "zod": "^4.1.11"
+    "hono": "^4.9.10",
+    "zod": "^4.1.12"
   },
   "devDependencies": {
     "@local/common": "workspace:*",
     "@local/locales": "workspace:*",
     "@local/tsconfig": "workspace:*",
-    "@namesmt/utils": "^0.5.17",
-    "convex": "^1.27.3",
+    "@namesmt/utils": "^0.5.18",
+    "convex": "^1.27.4",
     "kontroll": "^1.1.1",
     "vitest": "^3.2.4"
   }

apps/backend/package.json

@@ -17,28 +17,29 @@
     "deploy": "dotenvx run -f .env.prod.local -f .env.prod -f .env -- sh scripts/deploy.sh"
   },
   "dependencies": {
-    "srvx": "^0.8.7"
+    "srvx": "^0.8.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.17",
-    "@scalar/hono-api-reference": "^0.9.19",
+    "@namesmt/utils": "^0.5.18",
+    "@scalar/hono-api-reference": "^0.9.20",
     "@vitest/coverage-v8": "^3.2.4",
     "arktype": "^2.1.22",
     "backend-convex": "workspace:*",
-    "convex": "^1.27.3",
-    "grammy": "^1.38.2",
-    "hono": "^4.9.8",
+    "convex": "^1.27.4",
+    "grammy": "^1.38.3",
+    "hono": "^4.9.10",
     "hono-adapter-aws-lambda": "^1.3.3",
-    "hono-openapi": "^1.0.8",
+    "hono-cookie-state": "^0.1.2",
+    "hono-openapi": "^1.1.0",
     "hono-sessions": "^0.8.0",
     "petite-vue-i18n": "^11.1.12",
     "std-env": "^3.9.0",
-    "tsdown": "^0.15.4",
+    "tsdown": "^0.15.6",
     "vitest": "^3.2.4"
   }
 }

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

@@ -0,0 +1,56 @@
+import { appFactory } from '#src/helpers/factory.js'
+import { getSessionManager } from '#src/helpers/kinde.js'
+import { getKindeClient } from '#src/providers/auth/kinde-main.js'
+import { DetailedError } from '@namesmt/utils'
+import { decode } 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 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)
+
+      session.data.userAuth = {
+        ...userAuth,
+        tokens: { accessToken: tokenRefresh.access_token },
+      }
+    }
+
+    await next()
+  })
+}
+
+export type checkAuthParams = {
+  /**
+   * If false, will only throw if user is authenticated but token verification fails.
+   *
+   * @default true
+   */
+  throwOnUnauthenticated?: boolean
+}
+export function checkAuth({ throwOnUnauthenticated = true }: checkAuthParams = {}) {
+  return appFactory.createMiddleware(async (c, next) => {
+    const session = c.get('session')
+    const userAuth = session.data.userAuth
+    if (!userAuth) {
+      if (throwOnUnauthenticated)
+        throw new DetailedError('user is not authenticated', { statusCode: 401 })
+
+      return await next()
+    }
+
+    // TODO: permission tokens system here
+
+    await next()
+  })
+}

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

@@ -2,37 +2,36 @@
  * This file contains routes and sample routes for possible APIs usecases with Kinde.
  */
 
-import type { UserProfileType } from '@local/common/src/types/user'
 // import type { ClaimTokenType, FlagType } from '@kinde-oss/kinde-typescript-sdk'
 import { appFactory } from '#src/helpers/factory.js'
 import { getSessionManager } from '#src/helpers/kinde.js'
 import { getKindeClient } from '#src/providers/auth/kinde-main.js'
+import { objectOmit } from '@local/common/src/utils/general'
 import { env } from 'std-env'
 
 export const authRoutesApp = appFactory.createApp()
   .get('/health', async (c) => {
     return c.text('Good', 200)
   })
 
+  // This endpoint returns the current auth state
   .get('/authState', async (c) => {
-    const kindeClient = await getKindeClient()
-    const sessionManager = getSessionManager(c)
+    const session = c.get('session')
 
-    const [profile, token] = await Promise.all([
-      kindeClient.getUserProfile(sessionManager).catch(() => null) as Promise<UserProfileType>,
-      kindeClient.getToken(sessionManager).catch(() => null),
-    ])
+    const userAuth = session.data.userAuth
+    const tokens = userAuth?.tokens ?? null
 
-    return c.json({ profile, token })
+    return c.json({ userAuth: userAuth ? objectOmit(userAuth, ['tokens']) : null, tokens })
   })
 
   .get('/login', async (c) => {
     const kindeClient = await getKindeClient()
     const org_code = c.req.query('org_code')
+    const session = c.get('session')
 
     const loginUrl = await kindeClient.login(getSessionManager(c), { org_code })
 
-    c.get('session').set('backToPath', c.req.query('path'))
+    session.data.backToPath = c.req.query('path')
 
     return c.redirect(loginUrl.toString())
   })
@@ -48,13 +47,30 @@ export const authRoutesApp = appFactory.createApp()
 
   .get('/callback', async (c) => {
     const kindeClient = await getKindeClient()
+    const session = c.get('session')
+    const sessionManager = getSessionManager(c)
 
-    await kindeClient.handleRedirectToApp(getSessionManager(c), new URL(c.req.url))
+    await kindeClient.handleRedirectToApp(sessionManager, new URL(c.req.url))
 
-    let backToPath = c.get('session').get('backToPath') as string || '/'
+    let backToPath = session.data.backToPath as string || '/'
     if (!backToPath.startsWith('/'))
       backToPath = `/${backToPath}`
 
+    const kindeProfile = await kindeClient.getUserProfile(sessionManager)
+
+    session.data.userAuth = {
+      id: kindeProfile.id,
+      avatar: kindeProfile.picture || undefined,
+      email: kindeProfile.email,
+      firstName: kindeProfile.given_name,
+      // @ts-expect-error Kinde SDK is dumb
+      fullName: kindeProfile.name,
+
+      tokens: {
+        accessToken: await kindeClient.getToken(sessionManager),
+      },
+    }
+
     return c.redirect(`${env.FRONTEND_URL!}${backToPath}`)
   })
 
@@ -66,13 +82,14 @@ export const authRoutesApp = appFactory.createApp()
     return c.redirect(logoutUrl.toString())
   })
 
-// .get('/isAuth', async (c) => {
-//   const kindeClient = await getKindeClient()
+  // This endpoint checks if kinde session is authenticated
+  .get('/isAuth', async (c) => {
+    const kindeClient = await getKindeClient()
 
-//   const isAuthenticated = await kindeClient.isAuthenticated(getSessionManager(c)) // Boolean: true or false
+    const isAuthenticated = await kindeClient.isAuthenticated(getSessionManager(c))
 
-//   return c.json(isAuthenticated)
-// })
+    return c.json(isAuthenticated)
+  })
 
 // .get('/profile', async (c) => {
 //   const kindeClient = await getKindeClient()

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

@@ -1,5 +1,7 @@
 import { appFactory } from '#src/helpers/factory.js'
 import { authRoutesApp } from './$.routes'
+import { authCheckRoute } from './authCheck'
 
 export const authApp = appFactory.createApp()
   .route('', authRoutesApp)
+  .route('/check', authCheckRoute)

apps/backend/src/api/auth/authCheck.ts

@@ -0,0 +1,12 @@
+import { appFactory } from '#src/helpers/factory.js'
+import { checkAuth } from './$.middleware'
+
+// This route should be accessible only when user is authenticated
+export const authCheckRoute = appFactory.createApp()
+  .get(
+    '',
+    checkAuth(),
+    async (c) => {
+      return c.text('OK')
+    },
+  )

apps/backend/src/app.ts

@@ -1,6 +1,6 @@
 import { errorHandler } from '#src/helpers/error.js'
 import { appFactory, triggerFactory } from '#src/helpers/factory.js'
-import { cookieSession } from '#src/middlewares/session.js'
+import { createCookieState } from 'hono-cookie-state'
 import { cors } from 'hono/cors'
 import { logger as loggerMiddleware } from 'hono/logger'
 import { env, isWorkerd } from 'std-env'
@@ -38,8 +38,30 @@ export const app = appFactory.createApp()
     credentials: true,
   }))
 
-  // Session management middleware, configure and see all available managers in `src/middlewares/session.ts`
-  .use(await cookieSession())
+  // Main cookie session for the app
+  .use(createCookieState({
+    key: 'session',
+    secret: 'password_at_least_32_characters!',
+    cookieOptions: {
+      maxAge: 90 * 60, // 90 mins
+      sameSite: 'None',
+      secure: true,
+      path: '/',
+      httpOnly: true,
+    },
+  }))
+  // auth vendor's session data
+  .use(createCookieState({
+    key: 'authVendorSession',
+    secret: 'password_at_least_32_characters!',
+    cookieOptions: {
+      maxAge: 90 * 60, // 90 mins
+      sameSite: 'None',
+      secure: true,
+      path: '/',
+      httpOnly: true,
+    },
+  }))
 
   // Register API routes
   .route('/api', apiApp)

apps/backend/src/helpers/error.ts

@@ -1,8 +1,8 @@
 /* eslint-disable no-console */
 import type { HonoEnv } from '#src/types.js'
+import type { DetailedError } from '@namesmt/utils'
 import type { ErrorHandler } from 'hono'
 import type { ContentfulStatusCode } from 'hono/utils/http-status'
-import { DetailedError } from '@namesmt/utils'
 import { HTTPException } from 'hono/http-exception'
 
 export const errorHandler: ErrorHandler<HonoEnv> = (err, c) => {
@@ -26,10 +26,13 @@ export const errorHandler: ErrorHandler<HonoEnv> = (err, c) => {
     })
   }
 
-  if (err instanceof DetailedError) {
+  // Handling of custom DetailedError (DetailedError can comes from multiple sources (hono's parseResponse, @namesmt/utils))
+  // So we're using a `.name` check here.
+  if (err.name === 'DetailedError') {
+    const _e = err as DetailedError
     return _makeErrorRes({
-      body: { message: err.message, code: err.code ?? err.name, detail: err.detail },
-      status: err.statusCode ?? 500,
+      body: { message: _e.message, code: _e.code ?? _e.name, detail: _e.detail },
+      status: _e.statusCode ?? 500,
     })
   }
 

apps/backend/src/helpers/kinde.ts

@@ -1,34 +1,32 @@
+import type { HonoEnv } from '#src/types.js'
 import type { SessionManager } from '@kinde-oss/kinde-typescript-sdk'
 import type { Context } from 'hono'
-import type { Session } from 'hono-sessions'
+import type { CookieState } from 'hono-cookie-state'
 import { HTTPException } from 'hono/http-exception'
 
 /**
- * This is a wrapper on top of hono-sessions for Kinde compatibility
+ * This is a wrapper on top of `hono-cookie-state` for Kinde compatibility
  */
-export function toKindeSessionManager(session: Session): SessionManager {
-  if (!session)
-    throw new HTTPException(400, { message: 'SessionManager requires a session' })
+export function toKindeSessionManager(cs: CookieState<any>): SessionManager {
+  if (!cs)
+    throw new HTTPException(400, { message: 'SessionManager requires a CookieState' })
 
   return {
     async getSessionItem(key: string) {
-      return session.get(key)
+      return cs.data[key]
     },
     async setSessionItem(key: string, value: unknown) {
-      session.set(key, value)
+      cs.data[key] = value
     },
     async removeSessionItem(key: string) {
-      delete session.getCache()._data[key]
+      delete cs.data[key]
     },
     async destroySession() {
-      session.deleteSession()
+      cs.data = {}
     },
   }
 }
 
-/**
- * A simple shortcut for `toKindeSessionManager(c.get('session'))`
- */
-export function getSessionManager(c: Context) {
-  return toKindeSessionManager(c.get('session'))
+export function getSessionManager(c: Context<HonoEnv>) {
+  return toKindeSessionManager(c.get('authVendorSession'))
 }

apps/backend/src/middlewares/session.ts …ackend/src/middlewares/header-session.tsapps/backend/src/middlewares/session.ts renamed to apps/backend/src/middlewares/header-session.ts apps/backend/src/middlewares/session.ts renamed to apps/backend/src/middlewares/header-session.ts

@@ -1,26 +1,5 @@
 import type { Context } from 'hono'
-import { CookieStore, MemoryStore, Session, sessionMiddleware } from 'hono-sessions'
-
-/**
- * `Cookies`-based manager by `hono-sessions`.
- *
- * Default configuration uses `CookieStore` and just works out of the box.
- */
-export async function cookieSession() {
-  return sessionMiddleware({
-    store: new CookieStore(),
-    encryptionKey: 'password_at_least_32_characters!', // Required for CookieStore, recommended for others
-    expireAfterSeconds: 3600, // Expire session after 1 hour of inactivity
-    cookieOptions: {
-      // @ts-expect-error number assign to Date
-      expires: 3600 + 1800, // Expire cookie after 1 hour 30 minutes of inactivity
-      sameSite: 'None', // Setting to None to support usecase of different domains for backend and frontend
-      secure: true, // Enforce HTTPS for cookie, required for sameSite: 'None'
-      path: '/', // Required for this library to work properly
-      httpOnly: true, // Recommended to avoid XSS attacks
-    },
-  })
-}
+import { MemoryStore, Session } from 'hono-sessions'
 
 // TODO: Maybe turn this middleware into a package and fully document it.
 /**