@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

npm install @oesp/browser libsodium-wrappers-sumo

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

🚀 Usage

Basic Setup

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:

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

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

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 for a complete React example using this package.

🐛 Troubleshooting

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

Install the peer dependency:

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
• @oesp/crypto-sodium
• @oesp/storage-memory
• @oesp/sync-http
• @oesp/transport-ble-gatt

📄 License

MIT