@karbonjs/auth 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KarbonJS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# @karbonjs/auth
+
+Authentication helpers for Karbon — token management, user cache, and role hierarchy. Pure TypeScript, framework-agnostic.
+
+## Install
+
+```bash
+npm install @karbonjs/auth @karbonjs/types
+```
+
+## User Cache (SSR)
+
+Prevents hammering your `/profile` endpoint on every SSR request.
+
+```typescript
+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).
+
+```typescript
+import { createTokenManager } from '@karbonjs/auth'
+
+const tokenManager = createTokenManager({
+  apiUrl: 'http://localhost:3005/api/v1',
+  refreshEndpoint: '/auth/refresh',
+  onRefresh: (tokens) => {
+    // Set new cookies
+    cookies.set('token', tokens.token)
+    cookies.set('refresh_token', tokens.refreshToken)
+  },
+  onExpired: () => {
+    // Clear session
+    cookies.delete('token')
+  },
+})
+
+const newTokens = await tokenManager.refresh(refreshToken, sessionId)
+```
+
+## Role Hierarchy
+
+Check roles with inheritance support.
+
+```typescript
+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

package/dist/cache/user-cache.d.ts

@@ -0,0 +1,19 @@
+import type { AuthUser } from '@karbonjs/types';
+export interface UserCacheOptions {
+    /** Max entries in cache (default: 500) */
+    maxSize?: number;
+    /** TTL in milliseconds (default: 2 minutes) */
+    ttl?: number;
+}
+/**
+ * In-memory user cache for SSR hooks.
+ * Prevents hammering the /profile endpoint on every request.
+ */
+export declare function createUserCache(opts?: UserCacheOptions): {
+    get(token: string): AuthUser | null;
+    set(token: string, user: AuthUser): void;
+    invalidate(token: string): void;
+    clear(): void;
+    readonly size: number;
+};
+//# sourceMappingURL=user-cache.d.ts.map

package/dist/cache/user-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-cache.d.ts","sourceRoot":"","sources":["../../src/cache/user-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAE/C,MAAM,WAAW,gBAAgB;IAC/B,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAOD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,gBAAqB;eAa5C,MAAM,GAAG,QAAQ,GAAG,IAAI;eAUxB,MAAM,QAAQ,QAAQ,GAAG,IAAI;sBAWtB,MAAM,GAAG,IAAI;aAItB,IAAI;mBAID,MAAM;EAIrB"}

package/dist/cache/user-cache.js

@@ -0,0 +1,49 @@
+/**
+ * In-memory user cache for SSR hooks.
+ * Prevents hammering the /profile endpoint on every request.
+ */
+export function createUserCache(opts = {}) {
+    const maxSize = opts.maxSize ?? 500;
+    const ttl = opts.ttl ?? 120_000;
+    const store = new Map();
+    function purgeExpired() {
+        const now = Date.now();
+        for (const [key, entry] of store) {
+            if (now - entry.timestamp > ttl)
+                store.delete(key);
+        }
+    }
+    return {
+        get(token) {
+            const entry = store.get(token);
+            if (!entry)
+                return null;
+            if (Date.now() - entry.timestamp > ttl) {
+                store.delete(token);
+                return null;
+            }
+            return entry.user;
+        },
+        set(token, user) {
+            if (store.size >= maxSize) {
+                purgeExpired();
+            }
+            if (store.size >= maxSize) {
+                const oldest = store.keys().next().value;
+                if (oldest)
+                    store.delete(oldest);
+            }
+            store.set(token, { user, timestamp: Date.now() });
+        },
+        invalidate(token) {
+            store.delete(token);
+        },
+        clear() {
+            store.clear();
+        },
+        get size() {
+            return store.size;
+        },
+    };
+}
+//# sourceMappingURL=user-cache.js.map

package/dist/cache/user-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-cache.js","sourceRoot":"","sources":["../../src/cache/user-cache.ts"],"names":[],"mappings":"AAcA;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,OAAyB,EAAE;IACzD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,GAAG,CAAA;IACnC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAA;IAC/B,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAA;IAE3C,SAAS,YAAY;QACnB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QACtB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC;YACjC,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS,GAAG,GAAG;gBAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACpD,CAAC;IACH,CAAC;IAED,OAAO;QACL,GAAG,CAAC,KAAa;YACf,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;YAC9B,IAAI,CAAC,KAAK;gBAAE,OAAO,IAAI,CAAA;YACvB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC;gBACvC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;gBACnB,OAAO,IAAI,CAAA;YACb,CAAC;YACD,OAAO,KAAK,CAAC,IAAI,CAAA;QACnB,CAAC;QAED,GAAG,CAAC,KAAa,EAAE,IAAc;YAC/B,IAAI,KAAK,CAAC,IAAI,IAAI,OAAO,EAAE,CAAC;gBAC1B,YAAY,EAAE,CAAA;YAChB,CAAC;YACD,IAAI,KAAK,CAAC,IAAI,IAAI,OAAO,EAAE,CAAC;gBAC1B,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAA;gBACxC,IAAI,MAAM;oBAAE,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;YAClC,CAAC;YACD,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;QACnD,CAAC;QAED,UAAU,CAAC,KAAa;YACtB,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACrB,CAAC;QAED,KAAK;YACH,KAAK,CAAC,KAAK,EAAE,CAAA;QACf,CAAC;QAED,IAAI,IAAI;YACN,OAAO,KAAK,CAAC,IAAI,CAAA;QACnB,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/cache/user-cache.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=user-cache.test.d.ts.map

package/dist/cache/user-cache.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-cache.test.d.ts","sourceRoot":"","sources":["../../src/cache/user-cache.test.ts"],"names":[],"mappings":""}

package/dist/cache/user-cache.test.js

@@ -0,0 +1,46 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createUserCache } from './user-cache';
+const mockUser = { id: 1, username: 'david', email: 'david@test.com', roles: ['ROLE_USER'] };
+describe('createUserCache', () => {
+    it('stores and retrieves users', () => {
+        const cache = createUserCache();
+        cache.set('token123', mockUser);
+        expect(cache.get('token123')).toEqual(mockUser);
+    });
+    it('returns null for missing token', () => {
+        const cache = createUserCache();
+        expect(cache.get('nonexistent')).toBeNull();
+    });
+    it('invalidates entries', () => {
+        const cache = createUserCache();
+        cache.set('token123', mockUser);
+        cache.invalidate('token123');
+        expect(cache.get('token123')).toBeNull();
+    });
+    it('clears all entries', () => {
+        const cache = createUserCache();
+        cache.set('a', mockUser);
+        cache.set('b', mockUser);
+        cache.clear();
+        expect(cache.size).toBe(0);
+    });
+    it('respects TTL', () => {
+        vi.useFakeTimers();
+        const cache = createUserCache({ ttl: 1000 });
+        cache.set('token123', mockUser);
+        expect(cache.get('token123')).toEqual(mockUser);
+        vi.advanceTimersByTime(1001);
+        expect(cache.get('token123')).toBeNull();
+        vi.useRealTimers();
+    });
+    it('evicts oldest when maxSize reached', () => {
+        const cache = createUserCache({ maxSize: 2 });
+        cache.set('a', mockUser);
+        cache.set('b', mockUser);
+        cache.set('c', mockUser);
+        expect(cache.size).toBe(2);
+        expect(cache.get('a')).toBeNull();
+        expect(cache.get('b')).toEqual(mockUser);
+    });
+});
+//# sourceMappingURL=user-cache.test.js.map

package/dist/cache/user-cache.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-cache.test.js","sourceRoot":"","sources":["../../src/cache/user-cache.test.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { createUserCache } from './cache/user-cache';
+export type { UserCacheOptions } from './cache/user-cache';
+export { createTokenManager } from './token/token-manager';
+export type { TokenManagerConfig, TokenPair } from './token/token-manager';
+export { hasRole, isAdmin, highestRole } from './roles/roles';
+export type { RoleHierarchy } from './roles/roles';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACpD,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAE1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC1D,YAAY,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAE1E,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC7D,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createUserCache } from './cache/user-cache';
+export { createTokenManager } from './token/token-manager';
+export { hasRole, isAdmin, highestRole } from './roles/roles';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAGpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAG1D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}

package/dist/roles/roles.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Role hierarchy definition.
+ * Higher roles inherit permissions from lower roles.
+ *
+ * ```ts
+ * const hierarchy: RoleHierarchy = {
+ *   'ROLE_SUPER_ADMIN': ['ROLE_ADMIN'],
+ *   'ROLE_ADMIN': ['ROLE_EDITOR'],
+ *   'ROLE_EDITOR': ['ROLE_USER'],
+ *   'ROLE_USER': [],
+ * }
+ * ```
+ */
+export type RoleHierarchy = Record<string, string[]>;
+/**
+ * Check if a user's roles satisfy a required role, considering hierarchy.
+ *
+ * ```ts
+ * hasRole(['ROLE_ADMIN'], 'ROLE_USER', hierarchy) // true (admin inherits user)
+ * hasRole(['ROLE_USER'], 'ROLE_ADMIN', hierarchy)  // false
+ * ```
+ */
+export declare function hasRole(userRoles: string[], requiredRole: string, hierarchy?: RoleHierarchy): boolean;
+/**
+ * Get the highest priority role from a list.
+ * Priority is determined by hierarchy depth (deeper = higher).
+ */
+export declare function highestRole(userRoles: string[], hierarchy: RoleHierarchy): string | null;
+/**
+ * Shorthand: check if user has admin-level access.
+ */
+export declare function isAdmin(userRoles: string[], hierarchy?: RoleHierarchy): boolean;
+//# sourceMappingURL=roles.d.ts.map

package/dist/roles/roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../../src/roles/roles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AAEpD;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAE,aAAkB,GAAG,OAAO,CAQzG;AAiBD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAexF;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,SAAS,GAAE,aAAkB,GAAG,OAAO,CAEnF"}

package/dist/roles/roles.js

@@ -0,0 +1,57 @@
+/**
+ * Check if a user's roles satisfy a required role, considering hierarchy.
+ *
+ * ```ts
+ * hasRole(['ROLE_ADMIN'], 'ROLE_USER', hierarchy) // true (admin inherits user)
+ * hasRole(['ROLE_USER'], 'ROLE_ADMIN', hierarchy)  // false
+ * ```
+ */
+export function hasRole(userRoles, requiredRole, hierarchy = {}) {
+    if (userRoles.includes(requiredRole))
+        return true;
+    // Check hierarchy: does any user role inherit the required role?
+    for (const role of userRoles) {
+        if (resolveRoles(role, hierarchy).includes(requiredRole))
+            return true;
+    }
+    return false;
+}
+/**
+ * Resolve all inherited roles for a given role.
+ */
+function resolveRoles(role, hierarchy, visited = new Set()) {
+    if (visited.has(role))
+        return [];
+    visited.add(role);
+    const children = hierarchy[role] ?? [];
+    const all = [role];
+    for (const child of children) {
+        all.push(...resolveRoles(child, hierarchy, visited));
+    }
+    return all;
+}
+/**
+ * Get the highest priority role from a list.
+ * Priority is determined by hierarchy depth (deeper = higher).
+ */
+export function highestRole(userRoles, hierarchy) {
+    if (userRoles.length === 0)
+        return null;
+    let best = userRoles[0];
+    let bestDepth = 0;
+    for (const role of userRoles) {
+        const depth = resolveRoles(role, hierarchy).length;
+        if (depth > bestDepth) {
+            bestDepth = depth;
+            best = role;
+        }
+    }
+    return best;
+}
+/**
+ * Shorthand: check if user has admin-level access.
+ */
+export function isAdmin(userRoles, hierarchy = {}) {
+    return hasRole(userRoles, 'ROLE_ADMIN', hierarchy);
+}
+//# sourceMappingURL=roles.js.map

package/dist/roles/roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.js","sourceRoot":"","sources":["../../src/roles/roles.ts"],"names":[],"mappings":"AAeA;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CAAC,SAAmB,EAAE,YAAoB,EAAE,YAA2B,EAAE;IAC9F,IAAI,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC;QAAE,OAAO,IAAI,CAAA;IAEjD,iEAAiE;IACjE,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,IAAI,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC;YAAE,OAAO,IAAI,CAAA;IACvE,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;GAEG;AACH,SAAS,YAAY,CAAC,IAAY,EAAE,SAAwB,EAAE,UAAU,IAAI,GAAG,EAAU;IACvF,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAA;IAChC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAEjB,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;IACtC,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,CAAA;IAClB,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC7B,GAAG,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAA;IACtD,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,SAAmB,EAAE,SAAwB;IACvE,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAEvC,IAAI,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,CAAA;IACvB,IAAI,SAAS,GAAG,CAAC,CAAA;IAEjB,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,MAAM,CAAA;QAClD,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;YACtB,SAAS,GAAG,KAAK,CAAA;YACjB,IAAI,GAAG,IAAI,CAAA;QACb,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,OAAO,CAAC,SAAmB,EAAE,YAA2B,EAAE;IACxE,OAAO,OAAO,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,CAAC,CAAA;AACpD,CAAC"}

package/dist/roles/roles.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=roles.test.d.ts.map

package/dist/roles/roles.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.test.d.ts","sourceRoot":"","sources":["../../src/roles/roles.test.ts"],"names":[],"mappings":""}

package/dist/roles/roles.test.js

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import { hasRole, highestRole, isAdmin } from './roles';
+const hierarchy = {
+    'ROLE_SUPER_ADMIN': ['ROLE_ADMIN'],
+    'ROLE_ADMIN': ['ROLE_EDITOR'],
+    'ROLE_EDITOR': ['ROLE_USER'],
+    'ROLE_USER': [],
+};
+describe('hasRole', () => {
+    it('returns true for direct role', () => {
+        expect(hasRole(['ROLE_USER'], 'ROLE_USER', hierarchy)).toBe(true);
+    });
+    it('returns true for inherited role', () => {
+        expect(hasRole(['ROLE_ADMIN'], 'ROLE_USER', hierarchy)).toBe(true);
+        expect(hasRole(['ROLE_ADMIN'], 'ROLE_EDITOR', hierarchy)).toBe(true);
+    });
+    it('returns false for higher role', () => {
+        expect(hasRole(['ROLE_USER'], 'ROLE_ADMIN', hierarchy)).toBe(false);
+    });
+    it('works without hierarchy (exact match only)', () => {
+        expect(hasRole(['ROLE_USER'], 'ROLE_USER')).toBe(true);
+        expect(hasRole(['ROLE_ADMIN'], 'ROLE_USER')).toBe(false);
+    });
+    it('handles deep hierarchy', () => {
+        expect(hasRole(['ROLE_SUPER_ADMIN'], 'ROLE_USER', hierarchy)).toBe(true);
+    });
+});
+describe('highestRole', () => {
+    it('returns highest role by depth', () => {
+        expect(highestRole(['ROLE_USER', 'ROLE_ADMIN'], hierarchy)).toBe('ROLE_ADMIN');
+    });
+    it('returns null for empty array', () => {
+        expect(highestRole([], hierarchy)).toBe(null);
+    });
+    it('returns super admin as highest', () => {
+        expect(highestRole(['ROLE_USER', 'ROLE_SUPER_ADMIN'], hierarchy)).toBe('ROLE_SUPER_ADMIN');
+    });
+});
+describe('isAdmin', () => {
+    it('returns true for admin', () => {
+        expect(isAdmin(['ROLE_ADMIN'], hierarchy)).toBe(true);
+    });
+    it('returns true for super admin', () => {
+        expect(isAdmin(['ROLE_SUPER_ADMIN'], hierarchy)).toBe(true);
+    });
+    it('returns false for user', () => {
+        expect(isAdmin(['ROLE_USER'], hierarchy)).toBe(false);
+    });
+});
+//# sourceMappingURL=roles.test.js.map

package/dist/roles/roles.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.test.js","sourceRoot":"","sources":["../../src/roles/roles.test.ts"],"names":[],"mappings":"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"}

package/dist/roles.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Role hierarchy definition.
+ * Higher roles inherit permissions from lower roles.
+ *
+ * ```ts
+ * const hierarchy: RoleHierarchy = {
+ *   'ROLE_SUPER_ADMIN': ['ROLE_ADMIN'],
+ *   'ROLE_ADMIN': ['ROLE_EDITOR'],
+ *   'ROLE_EDITOR': ['ROLE_USER'],
+ *   'ROLE_USER': [],
+ * }
+ * ```
+ */
+export type RoleHierarchy = Record<string, string[]>;
+/**
+ * Check if a user's roles satisfy a required role, considering hierarchy.
+ *
+ * ```ts
+ * hasRole(['ROLE_ADMIN'], 'ROLE_USER', hierarchy) // true (admin inherits user)
+ * hasRole(['ROLE_USER'], 'ROLE_ADMIN', hierarchy)  // false
+ * ```
+ */
+export declare function hasRole(userRoles: string[], requiredRole: string, hierarchy?: RoleHierarchy): boolean;
+/**
+ * Get the highest priority role from a list.
+ * Priority is determined by hierarchy depth (deeper = higher).
+ */
+export declare function highestRole(userRoles: string[], hierarchy: RoleHierarchy): string | null;
+/**
+ * Shorthand: check if user has admin-level access.
+ */
+export declare function isAdmin(userRoles: string[], hierarchy?: RoleHierarchy): boolean;
+//# sourceMappingURL=roles.d.ts.map

package/dist/roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../src/roles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AAEpD;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAE,aAAkB,GAAG,OAAO,CAQzG;AAiBD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAexF;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,SAAS,GAAE,aAAkB,GAAG,OAAO,CAEnF"}

package/dist/roles.js

@@ -0,0 +1,57 @@
+/**
+ * Check if a user's roles satisfy a required role, considering hierarchy.
+ *
+ * ```ts
+ * hasRole(['ROLE_ADMIN'], 'ROLE_USER', hierarchy) // true (admin inherits user)
+ * hasRole(['ROLE_USER'], 'ROLE_ADMIN', hierarchy)  // false
+ * ```
+ */
+export function hasRole(userRoles, requiredRole, hierarchy = {}) {
+    if (userRoles.includes(requiredRole))
+        return true;
+    // Check hierarchy: does any user role inherit the required role?
+    for (const role of userRoles) {
+        if (resolveRoles(role, hierarchy).includes(requiredRole))
+            return true;
+    }
+    return false;
+}
+/**
+ * Resolve all inherited roles for a given role.
+ */
+function resolveRoles(role, hierarchy, visited = new Set()) {
+    if (visited.has(role))
+        return [];
+    visited.add(role);
+    const children = hierarchy[role] ?? [];
+    const all = [role];
+    for (const child of children) {
+        all.push(...resolveRoles(child, hierarchy, visited));
+    }
+    return all;
+}
+/**
+ * Get the highest priority role from a list.
+ * Priority is determined by hierarchy depth (deeper = higher).
+ */
+export function highestRole(userRoles, hierarchy) {
+    if (userRoles.length === 0)
+        return null;
+    let best = userRoles[0];
+    let bestDepth = 0;
+    for (const role of userRoles) {
+        const depth = resolveRoles(role, hierarchy).length;
+        if (depth > bestDepth) {
+            bestDepth = depth;
+            best = role;
+        }
+    }
+    return best;
+}
+/**
+ * Shorthand: check if user has admin-level access.
+ */
+export function isAdmin(userRoles, hierarchy = {}) {
+    return hasRole(userRoles, 'ROLE_ADMIN', hierarchy);
+}
+//# sourceMappingURL=roles.js.map

package/dist/roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.js","sourceRoot":"","sources":["../src/roles.ts"],"names":[],"mappings":"AAeA;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CAAC,SAAmB,EAAE,YAAoB,EAAE,YAA2B,EAAE;IAC9F,IAAI,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC;QAAE,OAAO,IAAI,CAAA;IAEjD,iEAAiE;IACjE,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,IAAI,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC;YAAE,OAAO,IAAI,CAAA;IACvE,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;GAEG;AACH,SAAS,YAAY,CAAC,IAAY,EAAE,SAAwB,EAAE,UAAU,IAAI,GAAG,EAAU;IACvF,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAA;IAChC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAEjB,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;IACtC,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,CAAA;IAClB,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC7B,GAAG,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAA;IACtD,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,SAAmB,EAAE,SAAwB;IACvE,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAEvC,IAAI,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,CAAA;IACvB,IAAI,SAAS,GAAG,CAAC,CAAA;IAEjB,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,MAAM,CAAA;QAClD,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;YACtB,SAAS,GAAG,KAAK,CAAA;YACjB,IAAI,GAAG,IAAI,CAAA;QACb,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,OAAO,CAAC,SAAmB,EAAE,YAA2B,EAAE;IACxE,OAAO,OAAO,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,CAAC,CAAA;AACpD,CAAC"}

package/dist/token/token-manager.d.ts

@@ -0,0 +1,26 @@
+export interface TokenPair {
+    token: string;
+    refreshToken: string;
+    sessionId?: number;
+}
+export interface TokenManagerConfig {
+    /** API endpoint for token refresh (e.g. "/auth/refresh") */
+    refreshEndpoint: string;
+    /** Base API URL */
+    apiUrl: string;
+    /** Timeout in ms for refresh request (default: 10000) */
+    timeout?: number;
+    /** Called with new tokens after successful refresh */
+    onRefresh?: (tokens: TokenPair) => void;
+    /** Called when refresh fails */
+    onExpired?: () => void;
+}
+/**
+ * Server-side token refresh manager.
+ * Handles refresh token exchange and deduplication.
+ */
+export declare function createTokenManager(config: TokenManagerConfig): {
+    /** Refresh tokens. Deduplicates concurrent calls. */
+    refresh(refreshToken: string, sessionId?: number): Promise<TokenPair | null>;
+};
+//# sourceMappingURL=token-manager.d.ts.map

package/dist/token/token-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-manager.d.ts","sourceRoot":"","sources":["../../src/token/token-manager.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,eAAe,EAAE,MAAM,CAAA;IACvB,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sDAAsD;IACtD,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAA;IACvC,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,IAAI,CAAA;CACvB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB;IA8CzD,qDAAqD;0BACzB,MAAM,cAAc,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;EAOrF"}

package/dist/token/token-manager.js

@@ -0,0 +1,55 @@
+/**
+ * Server-side token refresh manager.
+ * Handles refresh token exchange and deduplication.
+ */
+export function createTokenManager(config) {
+    let pending = null;
+    async function doRefresh(refreshToken, sessionId) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), config.timeout ?? 10_000);
+        try {
+            const res = await fetch(`${config.apiUrl}${config.refreshEndpoint}`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    refresh_token: refreshToken,
+                    session_id: sessionId,
+                }),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                config.onExpired?.();
+                return null;
+            }
+            const data = await res.json();
+            if (!data.token || !data.refresh_token) {
+                config.onExpired?.();
+                return null;
+            }
+            const tokens = {
+                token: data.token,
+                refreshToken: data.refresh_token,
+                sessionId: data.session_id,
+            };
+            config.onRefresh?.(tokens);
+            return tokens;
+        }
+        catch {
+            config.onExpired?.();
+            return null;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return {
+        /** Refresh tokens. Deduplicates concurrent calls. */
+        async refresh(refreshToken, sessionId) {
+            if (!pending) {
+                pending = doRefresh(refreshToken, sessionId).finally(() => { pending = null; });
+            }
+            return pending;
+        },
+    };
+}
+//# sourceMappingURL=token-manager.js.map

package/dist/token/token-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-manager.js","sourceRoot":"","sources":["../../src/token/token-manager.ts"],"names":[],"mappings":"AAmBA;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAA0B;IAC3D,IAAI,OAAO,GAAqC,IAAI,CAAA;IAEpD,KAAK,UAAU,SAAS,CAAC,YAAoB,EAAE,SAAkB;QAC/D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;QACxC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,CAAA;QAE5E,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,eAAe,EAAE,EAAE;gBACnE,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,aAAa,EAAE,YAAY;oBAC3B,UAAU,EAAE,SAAS;iBACtB,CAAC;gBACF,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAA;YAEF,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,CAAC,SAAS,EAAE,EAAE,CAAA;gBACpB,OAAO,IAAI,CAAA;YACb,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAA;YAC7B,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;gBACvC,MAAM,CAAC,SAAS,EAAE,EAAE,CAAA;gBACpB,OAAO,IAAI,CAAA;YACb,CAAC;YAED,MAAM,MAAM,GAAc;gBACxB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,YAAY,EAAE,IAAI,CAAC,aAAa;gBAChC,SAAS,EAAE,IAAI,CAAC,UAAU;aAC3B,CAAA;YAED,MAAM,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAA;YAC1B,OAAO,MAAM,CAAA;QACf,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,CAAC,SAAS,EAAE,EAAE,CAAA;YACpB,OAAO,IAAI,CAAA;QACb,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAA;QACrB,CAAC;IACH,CAAC;IAED,OAAO;QACL,qDAAqD;QACrD,KAAK,CAAC,OAAO,CAAC,YAAoB,EAAE,SAAkB;YACpD,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,GAAG,SAAS,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,IAAI,CAAA,CAAC,CAAC,CAAC,CAAA;YAChF,CAAC;YACD,OAAO,OAAO,CAAA;QAChB,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/token-manager.d.ts

@@ -0,0 +1,35 @@
+export interface TokenPair {
+    token: string;
+    refreshToken: string;
+    sessionId?: number;
+}
+export interface TokenManagerConfig {
+    /** API endpoint for token refresh (e.g. "/auth/refresh") */
+    refreshEndpoint: string;
+    /** Base API URL */
+    apiUrl: string;
+    /** Called with new tokens after successful refresh */
+    onRefresh?: (tokens: TokenPair) => void;
+    /** Called when refresh fails */
+    onExpired?: () => void;
+}
+/**
+ * Server-side token refresh manager.
+ * Handles refresh token exchange and deduplication.
+ *
+ * ```ts
+ * const tokenManager = createTokenManager({
+ *   refreshEndpoint: '/auth/refresh',
+ *   apiUrl: 'http://localhost:3005/api/v1',
+ *   onRefresh: (tokens) => setCookies(tokens),
+ *   onExpired: () => clearSession(),
+ * })
+ *
+ * const newTokens = await tokenManager.refresh(refreshToken, sessionId)
+ * ```
+ */
+export declare function createTokenManager(config: TokenManagerConfig): {
+    /** Refresh tokens. Deduplicates concurrent calls. */
+    refresh(refreshToken: string, sessionId?: number): Promise<TokenPair | null>;
+};
+//# sourceMappingURL=token-manager.d.ts.map

package/dist/token-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-manager.d.ts","sourceRoot":"","sources":["../src/token-manager.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,eAAe,EAAE,MAAM,CAAA;IACvB,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,sDAAsD;IACtD,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAA;IACvC,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,IAAI,CAAA;CACvB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB;IAmCzD,qDAAqD;0BACzB,MAAM,cAAc,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;EAOrF"}

package/dist/token-manager.js

@@ -0,0 +1,56 @@
+/**
+ * Server-side token refresh manager.
+ * Handles refresh token exchange and deduplication.
+ *
+ * ```ts
+ * const tokenManager = createTokenManager({
+ *   refreshEndpoint: '/auth/refresh',
+ *   apiUrl: 'http://localhost:3005/api/v1',
+ *   onRefresh: (tokens) => setCookies(tokens),
+ *   onExpired: () => clearSession(),
+ * })
+ *
+ * const newTokens = await tokenManager.refresh(refreshToken, sessionId)
+ * ```
+ */
+export function createTokenManager(config) {
+    let pending = null;
+    async function doRefresh(refreshToken, sessionId) {
+        try {
+            const res = await fetch(`${config.apiUrl}${config.refreshEndpoint}`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    refresh_token: refreshToken,
+                    session_id: sessionId,
+                }),
+            });
+            if (!res.ok) {
+                config.onExpired?.();
+                return null;
+            }
+            const data = await res.json();
+            const tokens = {
+                token: data.token,
+                refreshToken: data.refresh_token,
+                sessionId: data.session_id,
+            };
+            config.onRefresh?.(tokens);
+            return tokens;
+        }
+        catch {
+            config.onExpired?.();
+            return null;
+        }
+    }
+    return {
+        /** Refresh tokens. Deduplicates concurrent calls. */
+        async refresh(refreshToken, sessionId) {
+            if (!pending) {
+                pending = doRefresh(refreshToken, sessionId).finally(() => { pending = null; });
+            }
+            return pending;
+        },
+    };
+}
+//# sourceMappingURL=token-manager.js.map

package/dist/token-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-manager.js","sourceRoot":"","sources":["../src/token-manager.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAA0B;IAC3D,IAAI,OAAO,GAAqC,IAAI,CAAA;IAEpD,KAAK,UAAU,SAAS,CAAC,YAAoB,EAAE,SAAkB;QAC/D,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,eAAe,EAAE,EAAE;gBACnE,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,aAAa,EAAE,YAAY;oBAC3B,UAAU,EAAE,SAAS;iBACtB,CAAC;aACH,CAAC,CAAA;YAEF,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,CAAC,SAAS,EAAE,EAAE,CAAA;gBACpB,OAAO,IAAI,CAAA;YACb,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAA;YAC7B,MAAM,MAAM,GAAc;gBACxB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,YAAY,EAAE,IAAI,CAAC,aAAa;gBAChC,SAAS,EAAE,IAAI,CAAC,UAAU;aAC3B,CAAA;YAED,MAAM,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAA;YAC1B,OAAO,MAAM,CAAA;QACf,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,CAAC,SAAS,EAAE,EAAE,CAAA;YACpB,OAAO,IAAI,CAAA;QACb,CAAC;IACH,CAAC;IAED,OAAO;QACL,qDAAqD;QACrD,KAAK,CAAC,OAAO,CAAC,YAAoB,EAAE,SAAkB;YACpD,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,GAAG,SAAS,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,IAAI,CAAA,CAAC,CAAC,CAAC,CAAA;YAChF,CAAC;YACD,OAAO,OAAO,CAAA;QAChB,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/user-cache.d.ts

@@ -0,0 +1,30 @@
+import type { AuthUser } from '@karbonjs/types';
+export interface UserCacheOptions {
+    /** Max entries in cache (default: 500) */
+    maxSize?: number;
+    /** TTL in milliseconds (default: 2 minutes) */
+    ttl?: number;
+}
+/**
+ * In-memory user cache for SSR hooks.
+ * Prevents hammering the /profile endpoint on every request.
+ *
+ * ```ts
+ * const cache = createUserCache({ ttl: 120_000, maxSize: 500 })
+ *
+ * // In your SSR hook:
+ * let user = cache.get(token)
+ * if (!user) {
+ *   user = await fetchProfile(token)
+ *   if (user) cache.set(token, user)
+ * }
+ * ```
+ */
+export declare function createUserCache(opts?: UserCacheOptions): {
+    get(token: string): AuthUser | null;
+    set(token: string, user: AuthUser): void;
+    invalidate(token: string): void;
+    clear(): void;
+    readonly size: number;
+};
+//# sourceMappingURL=user-cache.d.ts.map

package/dist/user-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-cache.d.ts","sourceRoot":"","sources":["../src/user-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAE/C,MAAM,WAAW,gBAAgB;IAC/B,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAOD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,gBAAqB;eAM5C,MAAM,GAAG,QAAQ,GAAG,IAAI;eAUxB,MAAM,QAAQ,QAAQ,GAAG,IAAI;sBAStB,MAAM,GAAG,IAAI;aAItB,IAAI;mBAID,MAAM;EAIrB"}

package/dist/user-cache.js

@@ -0,0 +1,51 @@
+/**
+ * In-memory user cache for SSR hooks.
+ * Prevents hammering the /profile endpoint on every request.
+ *
+ * ```ts
+ * const cache = createUserCache({ ttl: 120_000, maxSize: 500 })
+ *
+ * // In your SSR hook:
+ * let user = cache.get(token)
+ * if (!user) {
+ *   user = await fetchProfile(token)
+ *   if (user) cache.set(token, user)
+ * }
+ * ```
+ */
+export function createUserCache(opts = {}) {
+    const maxSize = opts.maxSize ?? 500;
+    const ttl = opts.ttl ?? 120_000;
+    const store = new Map();
+    return {
+        get(token) {
+            const entry = store.get(token);
+            if (!entry)
+                return null;
+            if (Date.now() - entry.timestamp > ttl) {
+                store.delete(token);
+                return null;
+            }
+            return entry.user;
+        },
+        set(token, user) {
+            // Evict oldest if full
+            if (store.size >= maxSize) {
+                const oldest = store.keys().next().value;
+                if (oldest)
+                    store.delete(oldest);
+            }
+            store.set(token, { user, timestamp: Date.now() });
+        },
+        invalidate(token) {
+            store.delete(token);
+        },
+        clear() {
+            store.clear();
+        },
+        get size() {
+            return store.size;
+        },
+    };
+}
+//# sourceMappingURL=user-cache.js.map

package/dist/user-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-cache.js","sourceRoot":"","sources":["../src/user-cache.ts"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAAC,OAAyB,EAAE;IACzD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,GAAG,CAAA;IACnC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAA;IAC/B,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAA;IAE3C,OAAO;QACL,GAAG,CAAC,KAAa;YACf,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;YAC9B,IAAI,CAAC,KAAK;gBAAE,OAAO,IAAI,CAAA;YACvB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC;gBACvC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;gBACnB,OAAO,IAAI,CAAA;YACb,CAAC;YACD,OAAO,KAAK,CAAC,IAAI,CAAA;QACnB,CAAC;QAED,GAAG,CAAC,KAAa,EAAE,IAAc;YAC/B,uBAAuB;YACvB,IAAI,KAAK,CAAC,IAAI,IAAI,OAAO,EAAE,CAAC;gBAC1B,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAA;gBACxC,IAAI,MAAM;oBAAE,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;YAClC,CAAC;YACD,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;QACnD,CAAC;QAED,UAAU,CAAC,KAAa;YACtB,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACrB,CAAC;QAED,KAAK;YACH,KAAK,CAAC,KAAK,EAAE,CAAA;QACf,CAAC;QAED,IAAI,IAAI;YACN,OAAO,KAAK,CAAC,IAAI,CAAA;QACnB,CAAC;KACF,CAAA;AACH,CAAC"}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@karbonjs/auth",
+  "version": "0.1.0",
+  "description": "Authentication helpers for Karbon — token management, user cache, hooks",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@karbonjs/types": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  }
+}