npm package: @optare/token-storage
Description: Secure token storage adapters for Optare SDKs
Author: Optare Team
Latest version: 0.1.2

# @optare/token-storage

Secure token storage adapters for [Optare ID](https://id.optare.one) SDKs. Provides pluggable storage backends for authentication tokens with security best practices.

## Installation

```bash
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

### CookieAdapter (Recommended)

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.)

### MemoryAdapter

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

### LocalStorageAdapter (Not Recommended)

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<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

```typescript
interface TokenStorage {
  get(key: string): Promise<string | null>;
  set(key: string, value: string): Promise<void>;
  remove(key: string): Promise<void>;
  clear(): Promise<void>;
}
```

### CookieAdapterConfig

```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
4. **Short token lifetimes** - Use refresh tokens for long sessions
5. **Never use LocalStorageAdapter in production** - Only for development

## Related Packages

- [@optare/optareid-js](https://www.npmjs.com/package/@optare/optareid-js) - Core SDK
- [@optare/optareid-react](https://www.npmjs.com/package/@optare/optareid-react) - React SDK

## License

MIT