Secure token storage adapters for Optare SDKs
npm install @optare/token-storagebash
npm install @optare/token-storage
or
pnpm add @optare/token-storage
`
Quick Start
`typescript
import { CookieAdapter, MemoryAdapter, LocalStorageAdapter } from '@optare/token-storage';
// Recommended: HttpOnly cookies (most secure)
const storage = new CookieAdapter({
baseUrl: 'https://your-api.com',
cookieEndpoint: '/api/auth/cookie'
});
// Development/Testing: In-memory storage
const memoryStorage = new MemoryAdapter();
// Legacy: localStorage (NOT recommended for production)
const localStorageAdapter = new LocalStorageAdapter();
`
Adapters
$3
Uses HttpOnly cookies for maximum security. Tokens are stored server-side and automatically attached to requests by the browser.
`typescript
import { CookieAdapter } from '@optare/token-storage';
const storage = new CookieAdapter({
baseUrl: 'https://api.example.com', // Your API base URL
cookieEndpoint: '/api/auth/cookie' // Endpoint to set/clear cookies
});
// Store token (sends to backend to set HttpOnly cookie)
await storage.set('access_token', 'eyJhbG...');
// Get token (returns null - HttpOnly cookies aren't readable by JS)
const token = await storage.get('access_token'); // null
// Remove token
await storage.remove('access_token');
// Clear all tokens
await storage.clear();
`
Security Benefits:
- ✅ Protected from XSS attacks
- ✅ Automatically sent with requests
- ✅ Server controls cookie attributes (Secure, SameSite, etc.)
$3
In-memory storage for testing and server-side rendering.
`typescript
import { MemoryAdapter } from '@optare/token-storage';
const storage = new MemoryAdapter();
await storage.set('access_token', 'eyJhbG...');
const token = await storage.get('access_token'); // 'eyJhbG...'
await storage.remove('access_token');
await storage.clear();
`
Use Cases:
- Unit testing
- Server-side rendering
- Edge functions
$3
Uses browser localStorage. ⚠️ WARNING: Vulnerable to XSS attacks.
`typescript
import { LocalStorageAdapter } from '@optare/token-storage';
const storage = new LocalStorageAdapter();
// Will log security warning in browser console
await storage.set('access_token', 'eyJhbG...');
const token = await storage.get('access_token'); // 'eyJhbG...'
`
Security Warning:
- ❌ Vulnerable to XSS attacks
- ❌ Tokens readable by any JavaScript on the page
- Use only for development or when HttpOnly cookies aren't possible
Custom Adapters
Implement the TokenStorage interface:
`typescript
import { TokenStorage } from '@optare/token-storage';
class MyCustomAdapter implements TokenStorage {
async get(key: string): Promise {
// Your implementation
}
async set(key: string, value: string): Promise {
// Your implementation
}
async remove(key: string): Promise {
// Your implementation
}
async clear(): Promise {
// Your implementation
}
}
`
API Reference
$3
`typescript
interface TokenStorage {
get(key: string): Promise;
set(key: string, value: string): Promise;
remove(key: string): Promise;
clear(): Promise;
}
`
$3
`typescript
interface CookieAdapterConfig {
baseUrl?: string; // API base URL (default: '')
cookieEndpoint?: string; // Cookie endpoint (default: '/api/auth/cookie')
}
`
Security Best Practices
1. Use CookieAdapter in production - HttpOnly cookies are the most secure option
2. Enable Secure flag - Ensure your backend sets Secure cookie flag for HTTPS
3. Set SameSite - Use SameSite=Strict or Lax` to prevent CSRF