Token Session Manager

A flexible token session manager for handling access/refresh token pairs with automatic refresh and cross-domain support. Inspired by Auth0's battle-tested approach to token management.

Features

- 🔄 Automatic Token Refresh: Proactively refreshes tokens before expiration
- 🏪 Flexible Storage: Support for localStorage, sessionStorage, cookies, and custom storage
- 🌐 Cross-Domain Support: Cookie storage with subdomain support for multi-app authentication
- 🔒 JWT Decoding: Extracts expiration times from JWT tokens without verification
- 🔗 Cross-Tab Synchronization: Prevents concurrent refresh attempts across browser tabs
- 👁️ Tab Focus Detection: Automatically checks auth state when tab gains focus
- 🎣 Lifecycle Hooks: Callbacks for session events (started, refreshed, expired, errors)
- 🧪 Well Tested: Comprehensive test suite with 100% coverage
- 📦 TypeScript: Full TypeScript support with detailed type definitions
- 🪶 Lightweight: Minimal dependencies, tree-shakeable

Installation

``bash
npm install manage-token-sessions


or

yarn add manage-token-sessions

or

pnpm add manage-token-sessions
`

Quick Start

`typescript
import { TokenSessionManager, LocalStorageAdapter } from 'manage-token-sessions';

// Define your refresh function
const refreshTokens = async (refreshToken: string) => {
const response = await fetch('/api/auth/refresh', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ refreshToken })
});

const data = await response.json();
return {
accessToken: data.accessToken,
refreshToken: data.refreshToken
};
};

// Create the session manager
const sessionManager = new TokenSessionManager({
refreshTokenFn: refreshTokens,
storage: new LocalStorageAdapter(),
onSessionRefreshed: (session) => {
console.log('Session refreshed!', session);
},
onSessionExpired: () => {
console.log('Session expired, redirecting to login...');
window.location.href = '/login';
}
});

// Start a session after login
await sessionManager.startSession({
accessToken: 'your-jwt-access-token',
refreshToken: 'your-refresh-token'
});

// Get current access token (automatically refreshes if needed)
const accessToken = await sessionManager.getCurrentAccessToken();

// Use the token in API calls
fetch('/api/protected', {
headers: {
'Authorization': Bearer ${accessToken}
}
});
`

Storage Options

$3


`typescript
import { LocalStorageAdapter } from 'manage-token-sessions';

const sessionManager = new TokenSessionManager({
refreshTokenFn: refreshTokens,
storage: new LocalStorageAdapter()
});
`

$3


`typescript
import { SessionStorageAdapter } from 'manage-token-sessions';

const sessionManager = new TokenSessionManager({
refreshTokenFn: refreshTokens,
storage: new SessionStorageAdapter()
});
`

$3


`typescript
import { CookieStorageAdapter } from 'manage-token-sessions';

// Basic cookie storage
const sessionManager = new TokenSessionManager({
refreshTokenFn: refreshTokens,
storage: new CookieStorageAdapter()
});

// Cross-subdomain cookie storage
const crossDomainSessionManager = new TokenSessionManager({
refreshTokenFn: refreshTokens,
storage: new CookieStorageAdapter({
domain: '.example.com', // Works across app1.example.com, app2.example.com, etc.
secure: true,
sameSite: 'lax'
})
});
`

$3


`typescript
import { MemoryStorageAdapter } from 'manage-token-sessions';

const sessionManager = new TokenSessionManager({
refreshTokenFn: refreshTokens,
storage: new MemoryStorageAdapter()
});
`

$3


`typescript
import { TokenStorage } from 'manage-token-sessions';

class CustomStorageAdapter implements TokenStorage {
async get(key: string): Promise {
// Your custom get implementation
return null;
}

async set(key: string, value: string): Promise {
// Your custom set implementation
}

async remove(key: string): Promise {
// Your custom remove implementation
}
}

const sessionManager = new TokenSessionManager({
refreshTokenFn: refreshTokens,
storage: new CustomStorageAdapter()
});
`

Configuration Options

`typescript
const sessionManager = new TokenSessionManager({
// Required: Function to refresh tokens
refreshTokenFn: async (refreshToken) => ({ accessToken, refreshToken }),

// Optional: Storage adapter (default: LocalStorageAdapter)
storage: new LocalStorageAdapter(),

// Optional: Storage key (default: '@token-sessions@')
storageKey: 'my-app-session',

// Optional: Refresh buffer in seconds (default: 60)
// Tokens are refreshed this many seconds before expiry
expiryBufferSeconds: 120,

// Optional: Refresh check interval in milliseconds (default: 30000)
refreshIntervalMs: 15000,

// Optional: Cross-tab lock configuration
lockOptions: {
timeout: 5000, // Lock timeout in milliseconds
retries: 10, // Number of retry attempts
retryDelay: 100 // Delay between retries
},

// Optional: Tab focus authentication check (default: true)
checkOnFocus: true, // Check auth state when tab gains focus
focusDebounce: 100, // Debounce focus events in milliseconds

// Optional: Lifecycle hooks
onSessionStarted: (session) => console.log('Session started', session),
onSessionRefreshed: (session) => console.log('Session refreshed', session),
onSessionExpired: () => console.log('Session expired'),
onSessionError: (error) => console.error('Session error', error),
onRefreshError: (error) => console.error('Refresh error', error),
onFocusCheck: (session) => console.log('Focus check completed', session)
});
`

API Reference

$3

#### Methods

- startSession(tokens, metadata?): Start a new session
- getCurrentAccessToken(): Get current access token (auto-refreshes if needed)
- getCurrentSession(): Get current session data
- refreshSession(): Manually refresh the session
- checkAuthState(): Manually trigger a focus check and return current session
- endSession(): End the current session
- hasActiveSession(): Check if there's an active session
- destroy(): Clean up resources

#### Events

- onSessionStarted(session): Called when a session is started
- onSessionRefreshed(session): Called when tokens are refreshed
- onSessionExpired(): Called when session expires
- onSessionError(error): Called on session errors
- onRefreshError(error): Called on refresh errors

Cross-Tab Synchronization

The package automatically prevents concurrent token refresh attempts across multiple browser tabs using a lock mechanism (similar to Auth0's approach). This ensures that:

- Only one tab refreshes tokens at a time
- Other tabs wait for the refresh to complete
- No duplicate refresh requests are made
- Token consistency is maintained across all tabs

`typescript
// Multiple tabs with the same session manager configuration
// will automatically coordinate refresh attempts

const sessionManager = new TokenSessionManager({
refreshTokenFn: refreshTokens,
storage: new LocalStorageAdapter(),
// Lock configuration (optional)
lockOptions: {
timeout: 5000, // Wait up to 5 seconds for lock
retries: 10, // Retry 10 times if lock fails
retryDelay: 100 // Wait 100ms between retries
}
});

// Tab 1: Triggers refresh
await sessionManager.refreshSession();

// Tab 2: Waits for Tab 1 to complete, then uses the new token
const token = await sessionManager.getCurrentAccessToken();
`

Tab Focus Authentication Check

The package automatically checks authentication state when a browser tab gains focus. This provides instant feedback when users switch between tabs and ensures the UI reflects the current session state immediately.

$3

- Automatic Detection: When you switch to a tab, it immediately validates the current session
- Instant Sync: No waiting for the periodic refresh interval (default 30 seconds)
- Cross-Tab Login: If logged in from another tab, switching back shows the authenticated state instantly
- Cross-Tab Logout: If logged out in another tab, switching back shows the logged-out state instantly
- Session Validation: Checks if stored tokens are still valid and not expired
- Clock Synchronization: Aligns refresh timers with tokens refreshed by other tabs

$3

`typescript
const sessionManager = new TokenSessionManager({
refreshTokenFn: refreshTokens,

// Tab focus options (all optional)
checkOnFocus: true, // Enable focus checking (default: true)
focusDebounce: 100, // Debounce rapid focus events (default: 100ms)

// Focus check callback
onFocusCheck: (session) => {
console.log('Tab focused, session state:', session ? 'authenticated' : 'logged out');
}
});

// Manual focus check (useful for testing)
const currentSession = await sessionManager.checkAuthState();
`

$3

`typescript
// Scenario 1: Login in another tab
// Tab A: User is logged out
// Tab B: User logs in successfully
// Tab A: User switches back → onSessionStarted() fires → UI updates to authenticated

// Scenario 2: Logout in another tab
// Tab A: User is logged in
// Tab B: User logs out
// Tab A: User switches back → onSessionExpired() fires → UI updates to logged out

// Scenario 3: Token refresh in another tab
// Tab A: Token expires in 30 seconds
// Tab B: Token gets refreshed → now expires in 1 hour
// Tab A: User switches back → Timer synchronizes to 1 hour expiry
`

$3

✅ Instant UI Updates: No delay when switching between tabs
✅ Better UX: Immediate feedback on authentication state changes
✅ Bidirectional Sync: Detects both login and logout from other tabs
✅ Security: Quick detection of session changes from other tabs
✅ Clock Synchronization: Aligns with token refreshes from other tabs
✅ Efficiency: Only checks when user actually focuses the tab

Cross-Domain Authentication

For applications spanning multiple subdomains, use cookie storage with a shared domain:

`typescript
// On auth.example.com (login page)
const authSessionManager = new TokenSessionManager({
refreshTokenFn: refreshTokens,
storage: new CookieStorageAdapter({
domain: '.example.com',
secure: true,
sameSite: 'lax'
})
});

// After successful login
await authSessionManager.startSession(tokens);

// On app1.example.com and app2.example.com
const appSessionManager = new TokenSessionManager({
refreshTokenFn: refreshTokens,
storage: new CookieStorageAdapter({
domain: '.example.com',
secure: true,
sameSite: 'lax'
})
});

// Session is automatically available across subdomains
const accessToken = await appSessionManager.getCurrentAccessToken();
`

Error Handling

`typescript
const sessionManager = new TokenSessionManager({
refreshTokenFn: refreshTokens,
onRefreshError: async (error) => {
if (error.message.includes('invalid_grant')) {
// Refresh token is invalid, redirect to login
window.location.href = '/login';
} else {
// Network error, retry later
console.error('Refresh failed, will retry:', error);
}
},
onSessionError: (error) => {
console.error('Session error:', error);
}
});
``

License

MIT