@o/better-auth-utils 0.16.19

package/src/createAuthClient.ts

@@ -0,0 +1,373 @@
+/**
+ * Better-auth helpers for React / React Native applications
+ *
+ * Features:
+ *  - Session persistence in local storage
+ *  - State management with emitters
+ *  - Automatic retry on errors
+ *  - Optional JWT support (for Tauri, React Native)
+ */
+
+import {
+  createEmitter,
+  createStorageValue,
+  type Emitter,
+  isEqualDeepLite,
+  useEmitterValue,
+} from '@o/helpers'
+import { type BetterAuthClientOptions, createAuthClient } from 'better-auth/client'
+
+import type { Session, User } from 'better-auth'
+
+export interface StorageKeys {
+  token: string
+  session: string
+}
+
+export type AuthState<U extends User = User> = {
+  state: 'loading' | 'logged-in' | 'logged-out'
+  session: Session | null
+  user: U | null
+  /** JWT token - only populated when useJWT is enabled */
+  token: string | null
+}
+
+export interface BetterAuthClientProps<
+  TUser extends User = User,
+> extends BetterAuthClientOptions {
+  /**
+   * Callback to transform and type the user object
+   * @default (user) => user
+   */
+  createUser?: (user: User) => TUser
+
+  /**
+   * Optional callback when authentication state changes
+   */
+  onAuthStateChange?: (state: AuthState<TUser>) => void
+
+  /**
+   * Optional callback for handling auth errors
+   */
+  onAuthError?: (error: any) => void
+
+  /**
+   * Storage key prefix for local storage
+   * @default 'auth'
+   */
+  storagePrefix?: string
+
+  /**
+   * Retry delay in milliseconds after auth errors
+   * @default 4000
+   */
+  retryDelay?: number
+
+  /**
+   * Enable JWT token management for native apps (Tauri, React Native)
+   * When false (default), auth uses session cookies forwarded by the server
+   * When true, fetches and manages JWT tokens for Authorization header auth
+   * @default false
+   */
+  useJWT?: boolean
+
+  /**
+   * Cookie names to clear on auth invalidation
+   * @default ['better-auth.jwt', 'better-auth.session_token']
+   */
+  authCookieNames?: string[]
+}
+
+export interface BetterAuthClientReturn<U extends User = User, TClient = any> {
+  clearState: () => void
+  authState: ReturnType<typeof createEmitter<AuthState<U>>>
+  authClient: TClient
+  setAuthClientToken: (props: { token: string; session: string }) => Promise<void>
+  clearAuthClientToken: () => void
+  clearAllAuth: () => void
+  useAuth: () => AuthState<U>
+  getAuth: () => AuthState<U> & { loggedIn: boolean }
+  getValidToken: () => Promise<string | undefined>
+  updateAuthClient: (session: string) => void
+  authClientVersion: Emitter<number>
+}
+
+type InferUser<T> = T extends { createUser?: (user: User) => infer R }
+  ? R extends User
+    ? R
+    : User
+  : User
+
+export function createBetterAuthClient<const Opts extends BetterAuthClientProps<any>>(
+  options: Opts
+): BetterAuthClientReturn<InferUser<Opts>, ReturnType<typeof createAuthClient<Opts>>> {
+  type TUser = InferUser<Opts>
+  const {
+    onAuthStateChange,
+    onAuthError,
+    createUser,
+    storagePrefix = 'auth',
+    retryDelay = 4000,
+    useJWT = false,
+    authCookieNames = ['better-auth.jwt', 'better-auth.session_token'],
+    ...authClientOptions
+  } = options
+
+  const empty: AuthState<TUser> = {
+    state: 'logged-out',
+    session: null,
+    user: null,
+    token: null,
+  }
+
+  const keysStorage = createStorageValue<StorageKeys>(`${storagePrefix}-keys`)
+  const stateStorage = createStorageValue<AuthState<TUser>>(`${storagePrefix}-state`)
+
+  const createAuthClientWithSession = (session: string) => {
+    return createAuthClient({
+      ...authClientOptions,
+      fetchOptions: {
+        credentials: 'include',
+        headers: session ? { Authorization: `Bearer ${session}` } : undefined,
+      },
+    })
+  }
+
+  let authClient = (() => {
+    const existingSession = keysStorage.get()?.session
+    return existingSession
+      ? createAuthClientWithSession(existingSession)
+      : createAuthClient({
+          ...authClientOptions,
+          fetchOptions: { credentials: 'include' },
+        } as Opts)
+  })()
+
+  const authState = createEmitter<AuthState<TUser>>(
+    'authState',
+    stateStorage.get() || empty,
+    { comparator: isEqualDeepLite }
+  )
+
+  const authClientVersion = createEmitter<number>('authClientVersion', 0)
+
+  const setState = (update: Partial<AuthState<TUser>>) => {
+    const current = authState.value!
+    const next = { ...current, ...update }
+    stateStorage.set(next)
+    authState.emit(next)
+
+    // update storage keys
+    if (next.token && next.session) {
+      keysStorage.set({
+        token: next.token,
+        session: next.session.token,
+      })
+    } else if (next.session) {
+      keysStorage.set({
+        token: '',
+        session: next.session.token,
+      })
+    } else {
+      keysStorage.set({ token: '', session: '' })
+    }
+
+    onAuthStateChange?.(next)
+  }
+
+  const setAuthClientToken = async (props: { token: string; session: string }) => {
+    keysStorage.set(props)
+    updateAuthClient(props.session)
+  }
+
+  function updateAuthClient(session: string) {
+    authClient = createAuthClientWithSession(session)
+    authClientVersion.emit(Math.random())
+    subscribeToAuthEffect()
+  }
+
+  let dispose: Function | null = null
+  let retryTimer: ReturnType<typeof setTimeout> | null = null
+  // consecutive poll failures drive exponential backoff. a fixed retry clock
+  // is self-defeating against a rate limiter: one 429 puts the client on a
+  // cadence that keeps it over the limit forever (a real device wedged this
+  // way — every 4s retry re-tripped the server's window and the session never
+  // confirmed). backoff doubles per consecutive failure up to 60s and resets
+  // on any successful poll.
+  let consecutiveFailures = 0
+
+  function subscribeToAuthEffect() {
+    dispose?.()
+
+    dispose = authClient.useSession.subscribe(async (props) => {
+      const { data: dataGeneric, isPending, error } = props
+
+      if (error) {
+        onAuthError?.(error)
+        // if no persisted session, transition to logged-out instead of staying loading
+        const hasPersistedSession = !!keysStorage.get()?.session
+        if (!hasPersistedSession) {
+          setState({ state: 'logged-out', session: null, user: null })
+        }
+        consecutiveFailures++
+        scheduleAuthRetry(Math.min(retryDelay * 2 ** (consecutiveFailures - 1), 60_000))
+        return
+      }
+
+      consecutiveFailures = 0
+
+      const data = dataGeneric as
+        | undefined
+        | {
+            session?: AuthState<TUser>['session']
+            user?: AuthState<TUser>['user']
+          }
+
+      // if we have a persisted session but server hasn't confirmed yet, stay loading
+      const hasPersistedSession = !!keysStorage.get()?.session
+      const nextState = isPending
+        ? 'loading'
+        : data?.session
+          ? 'logged-in'
+          : hasPersistedSession && data === undefined
+            ? 'loading'
+            : 'logged-out'
+
+      // only update session/user when we have definitive data
+      const sessionUpdate =
+        nextState === 'loading'
+          ? {}
+          : {
+              session: data?.session ?? null,
+              user: data?.user ? (createUser ? createUser(data.user) : data.user) : null,
+            }
+
+      // detect new session
+      const previousSession = authState.value?.session
+      const isNewSession =
+        data?.session &&
+        (!previousSession ||
+          previousSession.id !== data.session.id ||
+          previousSession.userId !== data.session.userId)
+
+      setState({
+        state: nextState,
+        ...sessionUpdate,
+      })
+
+      // fetch JWT token when useJWT is enabled (for native/tauri apps)
+      if (useJWT && data?.session && (isNewSession || !authState.value.token)) {
+        if (isNewSession && authState.value.token) {
+          setState({ token: null })
+        }
+
+        getValidToken().then((token) => {
+          if (token) {
+            setState({ token })
+          }
+        })
+      }
+    })
+  }
+
+  function scheduleAuthRetry(delayMs: number) {
+    if (retryTimer) clearTimeout(retryTimer)
+    retryTimer = setTimeout(() => {
+      retryTimer = null
+      subscribeToAuthEffect()
+    }, delayMs)
+  }
+
+  async function getValidToken(): Promise<string | undefined> {
+    const res = await authClient.$fetch('/token')
+    if (res.error) {
+      console.error(`Error fetching token: ${res.error.statusText}`)
+      return undefined
+    }
+    return (res.data as any)?.token as string | undefined
+  }
+
+  const clearAuthClientToken = () => {
+    keysStorage.remove()
+  }
+
+  function clearAuthCookies() {
+    if (typeof document === 'undefined') return
+
+    for (const cookieName of authCookieNames) {
+      document.cookie = `${cookieName}=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/`
+      const domain = window.location.hostname
+      document.cookie = `${cookieName}=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/; domain=${domain}`
+      if (domain.startsWith('.')) {
+        document.cookie = `${cookieName}=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/; domain=${domain.slice(1)}`
+      }
+    }
+  }
+
+  function clearAllAuth() {
+    clearAuthCookies()
+    clearState()
+  }
+
+  const getAuth = () => {
+    const state = authState?.value || empty
+    return { ...state, loggedIn: !!state.session }
+  }
+
+  const useAuth = () => {
+    return useEmitterValue(authState) || empty
+  }
+
+  function clearState() {
+    keysStorage.remove()
+    stateStorage.remove()
+    setState(empty)
+  }
+
+  subscribeToAuthEffect()
+
+  if (typeof window !== 'undefined' && window.addEventListener) {
+    const cleanup = () => {
+      dispose?.()
+      if (retryTimer) clearTimeout(retryTimer)
+    }
+    window.addEventListener('beforeunload', cleanup)
+  }
+
+  const proxiedAuthClient = new Proxy(authClient, {
+    get(_target, key) {
+      if (key === 'signOut') {
+        return async () => {
+          // an explicit empty body makes better-fetch send JSON instead of a
+          // bodyless POST, which Better Auth rejects with 415.
+          const result = await authClient.$fetch('/sign-out', {
+            method: 'POST',
+            body: {},
+          })
+          if (result.error) throw result.error
+
+          clearState()
+          if (typeof window !== 'undefined') {
+            window.location?.reload?.()
+          }
+          return result
+        }
+      }
+      return Reflect.get(authClient, key)
+    },
+  }) as ReturnType<typeof createAuthClient<Opts>>
+
+  return {
+    authClientVersion,
+    clearState,
+    authState,
+    authClient: proxiedAuthClient,
+    setAuthClientToken,
+    clearAuthClientToken,
+    clearAllAuth,
+    useAuth,
+    getAuth,
+    getValidToken,
+    updateAuthClient,
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './createAuthClient'

package/src/server.ts

@@ -0,0 +1,150 @@
+/**
+ * Server-side auth utilities for better-auth
+ * - Session validation via cookies (web)
+ * - JWT validation via JWKS (native apps)
+ */
+
+import { createRemoteJWKSet, jwtVerify, type JWTPayload } from 'jose'
+
+export interface ValidateTokenOptions {
+  /** base URL for the auth server (e.g., https://myapp.com) */
+  baseUrl?: string
+  /** optional issuer override for CI/test environments */
+  forceIssuer?: string
+  /** JWKS endpoint path, defaults to /api/auth/jwks */
+  jwksPath?: string
+}
+
+export interface AuthData {
+  id: string
+  email?: string
+  role: 'admin' | undefined
+}
+
+export class NotAuthenticatedError extends Error {}
+export class InvalidTokenError extends Error {}
+
+export type AuthServer = {
+  api: {
+    getSession: (opts: { headers: Headers }) =>
+      | Promise<{
+          user: { id: string; email?: string | null; role?: string | null }
+        } | null>
+      | Promise<any>
+  }
+}
+
+/**
+ * Get auth data from request - tries session first, then a JWKS-verified JWT.
+ * Session: web cookies (forwarded by zero) and native bearer tokens resolved by
+ *   the better-auth bearer() plugin — both handled by getSession.
+ * JWT: only for servers using the jwt() plugin instead of bearer().
+ */
+export async function getAuthDataFromRequest(
+  authServer: AuthServer,
+  req: Request,
+  tokenOptions?: ValidateTokenOptions
+): Promise<AuthData | null> {
+  const authHeader = req.headers.get('authorization')
+
+  // try session-based auth first, passing the request headers THROUGH UNTOUCHED:
+  // - web sends the forwarded session cookie.
+  // - native (React Native / Tauri) sends `Authorization: Bearer <session-token>`,
+  //   which the better-auth bearer() plugin verifies and rewrites into the session
+  //   cookie internally (with the correct cookie name).
+  // do NOT rewrite the Cookie header from the bearer value: the bearer token is
+  // not a `name=value` cookie, so it never matched a real session cookie, and
+  // overwriting an existing forwarded cookie with it silently dropped authenticated
+  // web requests (cookie + bearer both present) to an `anon` identity.
+  try {
+    const session = await authServer.api.getSession({ headers: req.headers })
+    if (session?.user) {
+      return {
+        id: session.user.id,
+        email: session.user.email || undefined,
+        role: session.user.role === 'admin' ? 'admin' : undefined,
+      }
+    }
+  } catch (err) {
+    console.warn(`Error validating session`, err)
+    // session auth failed, try JWT
+  }
+
+  // fall back to JWKS-verified JWT for servers using the jwt() plugin (no
+  // bearer() plugin to resolve the token above).
+  const jwtToken = authHeader?.replace('Bearer ', '')
+
+  if (jwtToken) {
+    try {
+      const payload = await validateToken(jwtToken, tokenOptions)
+      const userId = (payload as any)?.id || payload?.sub
+      if (userId) {
+        return {
+          id: userId as string,
+          email: (payload as any).email as string | undefined,
+          role: (payload as any).role === 'admin' ? 'admin' : undefined,
+        }
+      }
+    } catch (err) {
+      if (!(err instanceof InvalidTokenError)) {
+        throw err
+      }
+    }
+  }
+
+  return null
+}
+
+// jwt validation for native apps
+
+export async function validateToken(
+  token: string,
+  options?: ValidateTokenOptions
+): Promise<JWTPayload> {
+  const {
+    baseUrl = process.env.ONE_SERVER_URL,
+    forceIssuer = process.env.FORCE_ISSUER || '',
+    jwksPath = '/api/auth/jwks',
+  } = options || {}
+
+  if (!baseUrl) {
+    throw new Error(`No baseURL!`)
+  }
+
+  const normalizedBaseUrl = removeTrailingSlash(baseUrl)
+  const url = `${forceIssuer || normalizedBaseUrl}${jwksPath}`
+
+  // create fresh JWKS fetcher each time to avoid stale key cache issues
+  const JWKS = createRemoteJWKSet(new URL(url))
+
+  try {
+    const verifyOptions = forceIssuer
+      ? {}
+      : {
+          issuer: normalizedBaseUrl,
+          audience: normalizedBaseUrl,
+        }
+
+    const { payload } = await jwtVerify(token, JWKS, verifyOptions)
+
+    return payload
+  } catch (error) {
+    throw new InvalidTokenError(`${error}`)
+  }
+}
+
+export async function isValidJWT(
+  token: string,
+  options: ValidateTokenOptions
+): Promise<boolean> {
+  try {
+    await validateToken(token, options)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function removeTrailingSlash(str: string) {
+  return str.replace(/\/$/, '')
+}