@absolutejs/auth 0.21.1 → 0.22.0

package/.claude/settings.local.json

@@ -0,0 +1,5 @@
+{
+	"permissions": {
+		"allow": ["Bash(bun run typecheck:*)", "Bash(bun lint:*)"]
+	}
+}

package/CLAUDE.md

@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Absolute Auth is a TypeScript OAuth2 authentication library for the Elysia web framework. It provides session management, multi-provider OAuth2 support, and route protection utilities. Built for Bun runtime.
+
+## Commands
+
+```bash
+bun run build        # Bundle with Bun, generate TypeScript declarations
+bun run typecheck    # TypeScript type checking
+bun run format       # Prettier formatting
+bun run dev          # Watch and run example server
+bun run release      # Full pipeline: lint, format, build, publish
+
+# Database (example app)
+bun db:push          # Drizzle migration push
+bun db:migrate       # Custom migration runner
+bun db:studio        # Drizzle Studio interface
+```
+
+## Architecture
+
+### Core Module Pattern
+
+Each auth feature (`authorize`, `callback`, `refresh`, `revoke`, `signout`, `userStatus`, `profile`) is a standalone module that returns an Elysia instance. The main `absoluteAuth<UserType>(config)` function composes all modules using Elysia's `.use()` pattern.
+
+### OAuth2 Flow
+
+1. **authorize.ts** - Sets state/code_verifier/origin cookies, redirects to provider
+2. **callback.ts** - Validates authorization code, exchanges for tokens, creates/retrieves user, stores session
+3. **userStatus.ts** - Returns current session status
+4. **refresh.ts** - Refreshes tokens for providers that support it
+5. **revoke.ts** - Revokes tokens for providers that support it
+6. **signout.ts** - Cleans up session and cookies
+
+### Session Management
+
+- Sessions stored in Elysia state (`sessionStore.ts`)
+- Session ID in httpOnly secure cookie (UUID v4)
+- Two session types: `SessionRecord<UserType>` (authenticated) and `UnregisteredSessionRecord` (during OAuth flow)
+- Always check `expiresAt` timestamp before using session
+
+### Generic UserType Pattern
+
+All modules are generic over `<UserType>`. The config requires a `getUser(decoded)` function that returns your user type from decoded token data. This keeps the library agnostic to your user model.
+
+### Event Handler Pattern
+
+Lifecycle hooks follow `On<Event><Success|Error>` naming:
+- `OnCallbackSuccess`, `OnCallbackError`
+- `OnAuthorizeError`, `OnRefreshSuccess`, etc.
+
+Handlers receive context objects and can return `Response`, status object, or `undefined`.
+
+## Code Conventions
+
+### ESLint Rules (from @absolutejs plugin)
+
+- No default exports (except eslint config)
+- Minimum variable name length: 3 characters
+- Enforce sorted exports and object keys
+- Maximum nesting depth enforced
+
+### Formatting
+
+- Tabs (width 4), not spaces
+- Single quotes, semicolons
+- Trailing commas: none
+- Print width: 80
+
+### Type Safety
+
+- Strict mode enabled
+- Use provided type guards from `typeGuards.ts` for runtime validation
+- Always return typed status responses or Response objects for errors
+
+## Key Files
+
+- `src/index.ts` - Main export, composes all auth routes
+- `src/types.ts` - Core type definitions
+- `src/utils.ts` - Session validation, instantiation helpers
+- `src/constants.ts` - Cookie/session duration constants
+- `example/server.ts` - Reference implementation
+
+## Dependencies
+
+- **elysia** - Web framework (peer dependency)
+- **citra** - OAuth2 client management (provides provider configs, PKCE utilities)

package/dist/index.js

@@ -2087,7 +2087,7 @@ var createOAuth2Client = async (providerName, config) => {
 };
 
 // src/index.ts
-import { Elysia as Elysia10 } from "elysia";
+import { Elysia as Elysia11 } from "elysia";
 
 // src/authorize.ts
 import { Elysia, t as t2 } from "elysia";
@@ -2102,6 +2102,7 @@ var MILLISECONDS_IN_A_DAY = MILLISECONDS_IN_A_SECOND * SECONDS_IN_A_MINUTE * MIN
 var MILLISECONDS_IN_AN_HOUR = MILLISECONDS_IN_A_MINUTE * MINUTES_IN_AN_HOUR;
 var COOKIE_MINUTES = 30;
 var COOKIE_DURATION = SECONDS_IN_A_MINUTE * COOKIE_MINUTES;
+var DEFAULT_MAX_SESSIONS = 1e4;
 
 // src/typebox.ts
 import { t } from "elysia";
@@ -2109,6 +2110,19 @@ var userSessionIdTypebox = t.Optional(t.TemplateLiteral("${string}-${string}-${s
 var authProviderOption = t.Enum(Object.fromEntries(Object.keys(providers).filter(isValidProviderOption).map((key) => [key, key])));
 
 // src/authorize.ts
+var parseReferer = (headerReferer) => {
+  if (!headerReferer)
+    return "/";
+  try {
+    const url = new URL(headerReferer);
+    return url.pathname + url.search;
+  } catch {
+    if (headerReferer.startsWith("/") && !headerReferer.startsWith("//")) {
+      return headerReferer;
+    }
+    return "/";
+  }
+};
 var authorize = ({
   clientProviders,
   authorizeRoute = "/oauth2/:provider/authorization",
@@ -2129,7 +2143,7 @@ var authorize = ({
   if (!providerConfig)
     return status("Unauthorized", "Client provider not found");
   const { providerInstance, scope, searchParams } = providerConfig;
-  const referer = headers["referer"] ?? "/";
+  const referer = parseReferer(headers["referer"]);
   origin_url.set({
     httpOnly: true,
     maxAge: COOKIE_DURATION,
@@ -2175,14 +2189,16 @@ var authorize = ({
     });
     return redirect(authorizationURL.toString());
   } catch (err) {
+    console.error("[authorize] Failed to create authorization URL:", {
+      error: err instanceof Error ? err.message : err,
+      provider,
+      stack: err instanceof Error ? err.stack : undefined
+    });
     await onAuthorizeError?.({
       authProvider: provider,
       error: err
     });
-    if (err instanceof Error) {
-      return status("Internal Server Error", `${err.message} - ${err.stack ?? ""}`);
-    }
-    return status("Internal Server Error", `Unknown status: ${err}`);
+    return status("Internal Server Error", "Failed to create authorization URL");
   }
 }, {
   cookie: t2.Cookie({
@@ -2209,6 +2225,8 @@ var sessionStore = () => {
 
 // src/typeGuards.ts
 var isValidUser = (user) => true;
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var isUserSessionId = (key) => UUID_PATTERN.test(key);
 var isNonEmptyString = (str) => str !== null && str !== undefined && str.trim() !== "";
 var isStatusResponse = (value) => typeof value === "object" && value !== null && ("status" in value) && typeof Reflect.get(value, "status") === "number";
 
@@ -2221,7 +2239,9 @@ var instantiateUserSession = async ({
   tokenResponse,
   providerInstance,
   getUser,
-  onNewUser
+  onNewUser,
+  sessionDurationMs = MILLISECONDS_IN_A_DAY,
+  unregisteredSessionDurationMs = MILLISECONDS_IN_AN_HOUR
 }) => {
   let userIdentity;
   let accessToken = tokenResponse.access_token;
@@ -2236,7 +2256,11 @@ var instantiateUserSession = async ({
     userIdentity = await providerInstance.fetchUserProfile(tokenResponse.access_token);
   }
   const userSession = validateSession({ session, user_session_id });
-  const userSessionId = getUserSessionId(user_session_id);
+  const userSessionId = getUserSessionId({
+    session,
+    unregisteredSession,
+    user_session_id
+  });
   let user = userSession?.user ?? await getUser(userIdentity);
   const response = user ?? await onNewUser(userIdentity);
   const isRedirectOrStatus = response instanceof Response || isStatusResponse(response);
@@ -2244,7 +2268,7 @@ var instantiateUserSession = async ({
     user = response;
     session[userSessionId] = {
       accessToken,
-      expiresAt: Date.now() + MILLISECONDS_IN_A_DAY,
+      expiresAt: Date.now() + sessionDurationMs,
       refreshToken,
       user
     };
@@ -2253,14 +2277,14 @@ var instantiateUserSession = async ({
   const existingUnregistered = unregisteredSession[userSessionId];
   if (existingUnregistered) {
     existingUnregistered.accessToken = accessToken;
-    existingUnregistered.expiresAt = Date.now() + MILLISECONDS_IN_AN_HOUR;
+    existingUnregistered.expiresAt = Date.now() + unregisteredSessionDurationMs;
     existingUnregistered.refreshToken = refreshToken;
     existingUnregistered.userIdentity = userIdentity;
     return response;
   }
   unregisteredSession[userSessionId] = {
     accessToken,
-    expiresAt: Date.now() + MILLISECONDS_IN_AN_HOUR,
+    expiresAt: Date.now() + unregisteredSessionDurationMs,
     refreshToken,
     userIdentity
   };
@@ -2305,17 +2329,28 @@ var validateSession = ({
   }
   return userSession;
 };
-var getUserSessionId = (user_session_id) => {
+var clearExistingSession = (existingId, session, unregisteredSession) => {
+  if (session)
+    delete session[existingId];
+  if (unregisteredSession)
+    delete unregisteredSession[existingId];
+};
+var getUserSessionId = ({
+  user_session_id,
+  session,
+  unregisteredSession
+}) => {
   const existingId = user_session_id?.value;
-  const userSessionId = isNonEmptyString(existingId) ? existingId : crypto.randomUUID();
-  if (existingId === undefined) {
-    user_session_id.set({
-      httpOnly: true,
-      sameSite: "lax",
-      secure: true,
-      value: userSessionId
-    });
+  if (isNonEmptyString(existingId)) {
+    clearExistingSession(existingId, session, unregisteredSession);
   }
+  const userSessionId = crypto.randomUUID();
+  user_session_id.set({
+    httpOnly: true,
+    sameSite: "lax",
+    secure: true,
+    value: userSessionId
+  });
   return userSessionId;
 };
 
@@ -2365,14 +2400,23 @@ var callback = ({
   try {
     tokenResponse = await providerInstance.validateAuthorizationCode(requiresPKCE ? { code, codeVerifier: verifier } : { code });
   } catch (err) {
+    console.error("[callback] Failed to validate authorization code:", {
+      authProvider,
+      error: err instanceof Error ? err.message : err,
+      stack: err instanceof Error ? err.stack : undefined
+    });
     await onCallbackError?.({
       authProvider,
       error: err,
       originUrl
     });
-    return err instanceof Error ? status("Internal Server Error", `${err.message} - ${err.stack ?? ""}`) : status("Internal Server Error", `Failed to validate authorization code: Unknown status: ${err}`);
+    return status("Internal Server Error", "Failed to validate authorization code");
   }
-  const userSessionId = getUserSessionId(user_session_id);
+  const userSessionId = getUserSessionId({
+    session,
+    unregisteredSession,
+    user_session_id
+  });
   const response = await onCallbackSuccess?.({
     authProvider,
     cookie,
@@ -2447,7 +2491,7 @@ var profile = ({
 
 // src/protectRoute.ts
 import { Elysia as Elysia5, t as t5 } from "elysia";
-var protectRoute = () => new Elysia5().use(sessionStore()).guard({ cookie: t5.Cookie({ user_session_id: userSessionIdTypebox }) }).derive(({ store: { session }, cookie: { user_session_id }, status }) => ({
+var protectRoutePlugin = () => new Elysia5().use(sessionStore()).guard({ cookie: t5.Cookie({ user_session_id: userSessionIdTypebox }) }).derive(({ store: { session }, cookie: { user_session_id }, status }) => ({
   protectRoute: async (handleAuth, handleAuthFail) => {
     const { user, error } = await getStatus(session, user_session_id);
     if (error) {
@@ -2469,7 +2513,8 @@ var refresh = ({
   clientProviders,
   refreshRoute = "/oauth2/tokens",
   onRefreshSuccess,
-  onRefreshError
+  onRefreshError,
+  sessionDurationMs = MILLISECONDS_IN_A_DAY
 }) => new Elysia6().use(sessionStore()).post(refreshRoute, async ({
   status,
   store: { session },
@@ -2504,6 +2549,9 @@ var refresh = ({
   }
   try {
     const tokenResponse = await providerInstance.refreshAccessToken(refreshToken);
+    userSession.accessToken = tokenResponse.access_token;
+    userSession.expiresAt = Date.now() + sessionDurationMs;
+    userSession.refreshToken = tokenResponse.refresh_token ?? userSession.refreshToken;
     await onRefreshSuccess?.({
       authProvider: auth_provider.value,
       tokenResponse
@@ -2512,14 +2560,16 @@ var refresh = ({
       status: 204
     });
   } catch (err) {
+    console.error("[refresh] Failed to refresh token:", {
+      authProvider: auth_provider.value,
+      error: err instanceof Error ? err.message : err,
+      stack: err instanceof Error ? err.stack : undefined
+    });
     await onRefreshError?.({
       authProvider: auth_provider.value,
       error: err
     });
-    if (err instanceof Error) {
-      return status("Internal Server Error", `Failed to refresh token: ${err.message}`);
-    }
-    return status("Internal Server Error", `Failed to refresh token: Unknown status: ${err}`);
+    return status("Internal Server Error", "Failed to refresh token");
   }
 }, { cookie: t6.Cookie({ user_session_id: userSessionIdTypebox }) });
 
@@ -2569,23 +2619,128 @@ var revoke = ({
       status: 204
     });
   } catch (err) {
+    console.error("[revoke] Failed to revoke token:", {
+      authProvider: auth_provider.value,
+      error: err instanceof Error ? err.message : err,
+      stack: err instanceof Error ? err.stack : undefined
+    });
     await onRevocationError?.({
       authProvider: auth_provider.value,
       error: err
     });
-    if (err instanceof Error) {
-      return status("Internal Server Error", `Failed to revoke token: ${err.message}`);
-    }
-    return status("Internal Server Error", `Failed to revoke token: Unknown status: ${err}`);
+    return status("Internal Server Error", "Failed to revoke token");
   }
 }, { cookie: t7.Cookie({ user_session_id: userSessionIdTypebox }) });
 
+// src/sessionCleanup.ts
+import { Elysia as Elysia8 } from "elysia";
+var sessionCleanup = ({
+  cleanupIntervalMs = MILLISECONDS_IN_AN_HOUR,
+  maxSessions = DEFAULT_MAX_SESSIONS,
+  onSessionCleanup
+}) => {
+  let intervalId = null;
+  return new Elysia8({ name: "sessionCleanup" }).use(sessionStore()).onStart(({ store: { session, unregisteredSession } }) => {
+    intervalId = setInterval(async () => {
+      await performCleanup(session, unregisteredSession, maxSessions, onSessionCleanup);
+    }, cleanupIntervalMs);
+  }).onStop(() => {
+    if (intervalId) {
+      clearInterval(intervalId);
+      intervalId = null;
+    }
+  }).derive(({ store: { session, unregisteredSession } }) => ({
+    cleanupSessions: async () => {
+      await performCleanup(session, unregisteredSession, maxSessions, onSessionCleanup);
+    }
+  })).as("global");
+};
+var collectValidSessionEntries = (session) => {
+  const entries = [];
+  for (const [key, value] of Object.entries(session)) {
+    if (!isUserSessionId(key))
+      continue;
+    entries.push([key, value]);
+  }
+  return entries;
+};
+var collectValidUnregisteredEntries = (unregisteredSession) => {
+  const entries = [];
+  for (const [key, value] of Object.entries(unregisteredSession)) {
+    if (!isUserSessionId(key))
+      continue;
+    entries.push([key, value]);
+  }
+  return entries;
+};
+var removeExpiredSessions = (validEntries, session, now) => {
+  const removed = new Map;
+  for (const [sessionId, userSession] of validEntries) {
+    if (userSession.expiresAt >= now)
+      continue;
+    removed.set(sessionId, userSession);
+    delete session[sessionId];
+  }
+  return removed;
+};
+var removeExpiredUnregisteredSessions = (validEntries, unregisteredSession, now) => {
+  const removed = new Map;
+  for (const [sessionId, unregSession] of validEntries) {
+    if (unregSession.expiresAt >= now)
+      continue;
+    removed.set(sessionId, unregSession);
+    delete unregisteredSession[sessionId];
+  }
+  return removed;
+};
+var evictExcessSessions = (remainingEntries, session, maxSessions, removedSessions) => {
+  const excessCount = remainingEntries.length - maxSessions;
+  if (excessCount <= 0)
+    return;
+  const sortedByExpiry = remainingEntries.sort(([, entryA], [, entryB]) => entryA.expiresAt - entryB.expiresAt);
+  const toEvict = sortedByExpiry.slice(0, excessCount);
+  for (const [key, value] of toEvict) {
+    removedSessions.set(key, value);
+    delete session[key];
+  }
+};
+var evictExcessUnregisteredSessions = (remainingEntries, unregisteredSession, maxSessions, removedUnregisteredSessions) => {
+  const excessCount = remainingEntries.length - maxSessions;
+  if (excessCount <= 0)
+    return;
+  const sortedByExpiry = remainingEntries.sort(([, entryA], [, entryB]) => entryA.expiresAt - entryB.expiresAt);
+  const toEvict = sortedByExpiry.slice(0, excessCount);
+  for (const [key, value] of toEvict) {
+    removedUnregisteredSessions.set(key, value);
+    delete unregisteredSession[key];
+  }
+};
+var performCleanup = async (session, unregisteredSession, maxSessions, onSessionCleanup) => {
+  const now = Date.now();
+  const validSessionEntries = collectValidSessionEntries(session);
+  const removedSessions = removeExpiredSessions(validSessionEntries, session, now);
+  const validUnregisteredEntries = collectValidUnregisteredEntries(unregisteredSession);
+  const removedUnregisteredSessions = removeExpiredUnregisteredSessions(validUnregisteredEntries, unregisteredSession, now);
+  const remainingEntries = validSessionEntries.filter(([key]) => !removedSessions.has(key));
+  evictExcessSessions(remainingEntries, session, maxSessions, removedSessions);
+  const remainingUnregistered = validUnregisteredEntries.filter(([key]) => !removedUnregisteredSessions.has(key));
+  evictExcessUnregisteredSessions(remainingUnregistered, unregisteredSession, maxSessions, removedUnregisteredSessions);
+  try {
+    await onSessionCleanup?.({
+      removedSessions,
+      removedUnregisteredSessions
+    });
+  } catch (err) {
+    console.error("[sessionCleanup] onSessionCleanup handler failed:", err);
+  }
+};
+
 // src/signout.ts
-import { Elysia as Elysia8, t as t8 } from "elysia";
+import { Elysia as Elysia9, t as t8 } from "elysia";
 var signout = ({
   signoutRoute = "/oauth2/signout",
   onSignOut
-}) => new Elysia8().use(sessionStore()).delete(signoutRoute, async ({
+}) => new Elysia9().use(sessionStore()).delete(signoutRoute, async ({
   status,
   store: { session },
   cookie: { user_session_id, auth_provider }
@@ -2606,10 +2761,12 @@ var signout = ({
       userSessionId: user_session_id.value
     });
   } catch (err) {
-    if (err instanceof Error) {
-      return status("Internal Server Error", `Error: ${err.message} - ${err.stack ?? ""}`);
-    }
-    return status("Internal Server Error", `Unknown Error: ${err}`);
+    console.error("[signout] Sign out operation failed:", {
+      authProvider: auth_provider.value,
+      error: err instanceof Error ? err.message : err,
+      stack: err instanceof Error ? err.stack : undefined
+    });
+    return status("Internal Server Error", "Sign out operation failed");
   }
   delete session[user_session_id.value];
   user_session_id.remove();
@@ -2622,11 +2779,11 @@ var signout = ({
 });
 
 // src/userStatus.ts
-import { Elysia as Elysia9, t as t9 } from "elysia";
+import { Elysia as Elysia10, t as t9 } from "elysia";
 var userStatus = ({
   statusRoute = "/oauth2/status",
   onStatus
-}) => new Elysia9().use(sessionStore()).get(statusRoute, async ({ status, cookie: { user_session_id }, store: { session } }) => {
+}) => new Elysia10().use(sessionStore()).get(statusRoute, async ({ status, cookie: { user_session_id }, store: { session } }) => {
   const { user, error } = await getStatus(session, user_session_id);
   if (error) {
     return status(error.code, error.message);
@@ -2649,6 +2806,9 @@ var absoluteAuth = async ({
   statusRoute,
   refreshRoute,
   revokeRoute,
+  cleanupIntervalMs,
+  maxSessions,
+  sessionDurationMs,
   onAuthorizeSuccess,
   onAuthorizeError,
   onProfileSuccess,
@@ -2660,7 +2820,8 @@ var absoluteAuth = async ({
   onRefreshError,
   onSignOut,
   onRevocationSuccess,
-  onRevocationError
+  onRevocationError,
+  onSessionCleanup
 }) => {
   const entryPromises = [];
   for (const [providerName, providerConfig] of Object.entries(providersConfiguration)) {
@@ -2676,7 +2837,11 @@ var absoluteAuth = async ({
     ]));
   }
   const clientProviders = Object.fromEntries(await Promise.all(entryPromises));
-  return new Elysia10().use(signout({ onSignOut, signoutRoute })).use(revoke({
+  return new Elysia11().use(sessionCleanup({
+    cleanupIntervalMs,
+    maxSessions,
+    onSessionCleanup
+  })).use(signout({ onSignOut, signoutRoute })).use(revoke({
     clientProviders,
     onRevocationError,
     onRevocationSuccess,
@@ -2685,7 +2850,8 @@ var absoluteAuth = async ({
     clientProviders,
     onRefreshError,
     onRefreshSuccess,
-    refreshRoute
+    refreshRoute,
+    sessionDurationMs
   })).use(authorize({
     authorizeRoute,
     clientProviders,
@@ -2701,22 +2867,24 @@ var absoluteAuth = async ({
     onProfileError,
     onProfileSuccess,
     profileRoute
-  })).use(protectRoute());
+  })).use(protectRoutePlugin());
 };
 export {
   validateSession,
   userSessionIdTypebox,
   sessionStore,
+  sessionCleanup,
   scopeRequiredProviderOptions,
   revocableProviderOptions,
   refreshableProviderOptions,
   providers,
   providerOptions,
-  protectRoute,
+  protectRoutePlugin,
   pkceProviderOptions,
   oidcProviderOptions,
   isValidUser,
   isValidProviderOption,
+  isUserSessionId,
   isRevocableProviderOption,
   isRevocableOAuth2Client,
   isRefreshableProviderOption,
@@ -2734,5 +2902,5 @@ export {
   absoluteAuth
 };
 
-//# debugId=34EE5A8C28DCAFD964756E2164756E21
+//# debugId=305D4B9D1F128FE664756E2164756E21
 //# sourceMappingURL=index.js.map