npm package: @oesp/browser
Description: OESP SDK for browsers (Web-compatible modules only)
Author: OESP Team
Latest version: 7.0.1

# @oesp/browser

Browser-compatible OESP SDK package. This package includes all OESP modules that work in web browsers, excluding Node.js-specific modules like `@oesp/keystore-node`.

## 📦 What's Included

- ✅ `@oesp/core` - Core protocol implementation
- ✅ `@oesp/crypto-sodium` - Cryptographic operations (libsodium)
- ✅ `@oesp/storage-memory` - In-memory replay store
- ✅ `@oesp/sync-http` - HTTP synchronization client
- ✅ `@oesp/transport-ble-gatt` - Bluetooth Low Energy transport (Web Bluetooth API)
- ✅ `BrowserKeyStore` - localStorage-based identity storage

## 🚫 What's Excluded

- ❌ `@oesp/keystore-node` - Requires Node.js `fs` module

## 📦 Installation

```bash
npm install @oesp/browser libsodium-wrappers-sumo
```

**Note:** `libsodium-wrappers-sumo` is a required peer dependency for cryptographic operations.

## 🚀 Usage

### Basic Setup

```typescript
import { 
  OESPClient,
  createSodiumCryptoProvider,
  MemoryReplayStore,
  BrowserKeyStore 
} from '@oesp/browser';

// Initialize components
const crypto = await createSodiumCryptoProvider();
const keystore = new BrowserKeyStore(); // Uses localStorage
const replay = new MemoryReplayStore();

// Create OESP client
const client = new OESPClient({ crypto, keystore, replay });

// Get your DID
const myDid = await client.getDid();
console.log('My DID:', myDid);
```

### BrowserKeyStore API

The `BrowserKeyStore` class provides localStorage-based identity management:

```typescript
const keystore = new BrowserKeyStore('my-custom-key'); // Default: 'oesp-identity'

// Check if identity exists
const exists = await keystore.exists();

// Load identity
const identity = await keystore.load();

// Save identity
await keystore.save({ /* identity data */ });

// Clear identity
await keystore.clear();
```

### With Web Bluetooth

```typescript
import { OESPBleGattTransport } from '@oesp/browser';

const transport = new OESPBleGattTransport();

// Scan and connect to BLE devices
// Requires HTTPS or localhost
// See Web Bluetooth API documentation
```

### With HTTP Sync

```typescript
import { OESPSyncClient } from '@oesp/browser';

const syncClient = new OESPSyncClient({
  baseUrl: 'https://sync.example.com'
});

// Sync tokens to server
await syncClient.syncTokens({
  tokens: ['OESP1.token1...', 'OESP1.token2...'],
  deviceDid: myDid
});
```

## 🔐 Security Considerations

### localStorage Security

`BrowserKeyStore` uses `localStorage` which:
- ✅ Persists across browser sessions
- ✅ Is isolated per origin (domain + protocol + port)
- ⚠️ Is accessible to all scripts on the same origin
- ⚠️ Is not encrypted by default

**Best Practices:**
1. Only use in trusted environments
2. Consider encrypting sensitive data before storage
3. Clear keystores when the user logs out
4. Use HTTPS to prevent man-in-the-middle attacks

### Web Bluetooth Requirements

- Must be served over **HTTPS** (or localhost for development)
- Requires user gesture to trigger `requestDevice()`
- Limited to supported browsers (Chrome, Edge, Opera)

## 📱 Platform Compatibility

| Feature | Chrome | Firefox | Safari | Edge | Mobile |
|---------|--------|---------|--------|------|--------|
| Core SDK | ✅ | ✅ | ✅ | ✅ | ✅ |
| localStorage | ✅ | ✅ | ✅ | ✅ | ✅ |
| Web Bluetooth | ✅ | ❌ | ❌ | ✅ | ✅* |

\* Mobile: Android Chrome, iOS WebBLE (limited)

## 🆚 vs @oesp/all

| Feature | @oesp/browser | @oesp/all |
|---------|--------------|-----------|
| **Platform** | Browser only | Node.js + Browser |
| **KeyStore** | localStorage | File system (fs) |
| **Size** | Smaller | Larger |
| **Use Case** | Web apps | Server apps |

For **Node.js applications**, use `@oesp/all` instead.  
For **web applications**, use `@oesp/browser`.

## 📚 Examples

See the [oesp-ts-test-app](../../oesp-ts-test-app) for a complete React example using this package.

## 🐛 Troubleshooting

### Error: Can't resolve 'libsodium-wrappers-sumo'

Install the peer dependency:
```bash
npm install libsodium-wrappers-sumo
```

### Web Bluetooth not working

1. Check you're on **HTTPS** (or localhost)
2. Use a supported browser (Chrome/Edge)
3. Ensure user gesture triggered the connection

### localStorage quota exceeded

Browser localStorage is typically limited to 5-10MB. If you hit the quota:
1. Clear old data with `keystore.clear()`
2. Consider using IndexedDB for larger data
3. Compress data before storing

## 📖 API Reference

See individual package documentation:
- [@oesp/core](../core/README.md)
- [@oesp/crypto-sodium](../crypto-sodium/README.md)
- [@oesp/storage-memory](../storage-memory/README.md)
- [@oesp/sync-http](../sync-http/README.md)
- [@oesp/transport-ble-gatt](../transport-ble-gatt/README.md)

## 📄 License

MIT