@karbonjs/auth

Authentication helpers for Karbon — token management, user cache, and role hierarchy. Pure TypeScript, framework-agnostic.

Install

npm install @karbonjs/auth @karbonjs/types

User Cache (SSR)

Prevents hammering your /profile endpoint on every SSR request.

import { createUserCache } from '@karbonjs/auth'

const userCache = createUserCache({
  ttl: 120_000,   // 2 minutes
  maxSize: 500,    // max cached users
})

// In your SSR hook
let user = userCache.get(token)
if (!user) {
  user = await fetchProfile(token)
  if (user) userCache.set(token, user)
}

Token Manager

Server-side token refresh with deduplication (prevents multiple concurrent refresh requests).

import { createTokenManager } from '@karbonjs/auth'

const tokenManager = createTokenManager({
  apiUrl: 'http://localhost:3005/api/v1',
  refreshEndpoint: '/auth/refresh',
  onRefresh: (tokens) => {
    cookies.set('token', tokens.token)
    cookies.set('refresh_token', tokens.refreshToken)
  },
  onExpired: () => {
    cookies.delete('token')
  },
})

const newTokens = await tokenManager.refresh(refreshToken, sessionId)

Features: AbortController timeout, concurrent dedup, JWT structure validation.

User Cache

Collision-resistant 64-bit token hashing, LRU eviction, TTL expiration, destroy() for cleanup.

Role Hierarchy

Check roles with inheritance support.

import { hasRole, isAdmin, highestRole } from '@karbonjs/auth'

const hierarchy = {
  'ROLE_SUPER_ADMIN': ['ROLE_ADMIN'],
  'ROLE_ADMIN': ['ROLE_EDITOR'],
  'ROLE_EDITOR': ['ROLE_USER'],
  'ROLE_USER': [],
}

hasRole(['ROLE_ADMIN'], 'ROLE_USER', hierarchy)   // true (inherits)
hasRole(['ROLE_USER'], 'ROLE_ADMIN', hierarchy)    // false
isAdmin(['ROLE_SUPER_ADMIN'], hierarchy)           // true
highestRole(['ROLE_USER', 'ROLE_ADMIN'], hierarchy) // "ROLE_ADMIN"

License

MIT