@optare/token-storage

Secure token storage adapters for Optare ID SDKs. Provides pluggable storage backends for authentication tokens with security best practices.

Installation

npm install @optare/token-storage
# or
pnpm add @optare/token-storage

Quick Start

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

CookieAdapter (Recommended)

Uses HttpOnly cookies for maximum security. Tokens are stored server-side and automatically attached to requests by the browser.

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.)

MemoryAdapter

In-memory storage for testing and server-side rendering.

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

LocalStorageAdapter (Not Recommended)

Uses browser localStorage. ⚠️ WARNING: Vulnerable to XSS attacks.

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:

import { TokenStorage } from '@optare/token-storage';

class MyCustomAdapter implements TokenStorage {
  async get(key: string): Promise<string | null> {
    // Your implementation
  }

  async set(key: string, value: string): Promise<void> {
    // Your implementation
  }

  async remove(key: string): Promise<void> {
    // Your implementation
  }

  async clear(): Promise<void> {
    // Your implementation
  }
}

API Reference

TokenStorage Interface

interface TokenStorage {
  get(key: string): Promise<string | null>;
  set(key: string, value: string): Promise<void>;
  remove(key: string): Promise<void>;
  clear(): Promise<void>;
}

CookieAdapterConfig

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
4. Short token lifetimes - Use refresh tokens for long sessions
5. Never use LocalStorageAdapter in production - Only for development

Related Packages

• @optare/optareid-js - Core SDK
• @optare/optareid-react - React SDK

License

MIT