@stvor/sdk 2.0.0

package/docs/index.mdx

@@ -0,0 +1,649 @@
+---
+title: STVOR SDK Documentation
+description: Client-side E2E encryption SDK for modern applications
+---
+
+# STVOR SDK
+
+Client-side end-to-end encryption SDK. Secure by default, zero crypto knowledge required.
+
+```typescript
+import { Stvor } from '@stvor/sdk';
+
+const app = await Stvor.init({ appToken: 'sk_live_...' });
+const alice = await app.connect('alice@example.com');
+await alice.send('bob@example.com', 'Hello!');
+```
+
+---
+
+## Quick Links
+
+- [Quickstart](#-quickstart) — Get started in 5 minutes
+- [API Reference](#api-reference) — Full API documentation
+- [Errors](#errors) — Error codes and recovery
+- [Security](#security-model) — What STVOR protects
+
+---
+
+## Installation
+
+<CodeGroup>
+```bash npm
+npm install @stvor/sdk
+```
+
+```bash pnpm
+pnpm add @stvor/sdk
+```
+
+```bash yarn
+yarn add @stvor/sdk
+```
+</CodeGroup>
+
+Requires a modern browser with [Web Crypto API](https://caniuse.com/cryptography) support.
+
+---
+
+## Quickstart
+
+```typescript
+import { Stvor } from '@stvor/sdk';
+
+// 1. Initialize SDK
+const app = await Stvor.init({
+  appToken: 'sk_live_abc123...'
+});
+
+// 2. Connect as user
+const alice = await app.connect('alice@example.com');
+
+// 3. Send encrypted message
+await alice.send('bob@example.com', 'Hello Bob!');
+
+// 4. Receive messages
+const message = await alice.receive();
+console.log(`${message.senderId}: ${message.content}`);
+```
+
+<Tip>
+**That's it.** No crypto configuration, no key management, no protocol choices.
+</Tip>
+
+---
+
+## AppToken
+
+Get your AppToken from the [developer dashboard](https://dashboard.stvor.io).
+
+```typescript
+const app = await Stvor.init({
+  appToken: 'sk_live_abc123...', // From dashboard
+  relayUrl: 'https://relay.stvor.io' // Optional
+});
+```
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `appToken` | Yes | — | Token from developer dashboard |
+| `relayUrl` | No | `https://relay.stvor.io` | Relay server URL |
+
+<Warning>
+Never commit AppToken to version control. Use environment variables:
+```typescript
+const app = await Stvor.init({
+  appToken: process.env.STVOR_APP_TOKEN
+});
+```
+</Warning>
+
+---
+
+# SDK Basics
+
+## Initialization
+
+```typescript
+const app = await Stvor.init({ appToken: 'sk_live_...' });
+```
+
+Creates SDK instance. Call once at app startup.
+
+| Returns | Description |
+|---------|-------------|
+| `StvorApp` | Main SDK instance for creating users |
+
+```typescript
+// Check if ready
+app.isReady(); // boolean
+
+// Cleanup when done
+await app.disconnect();
+```
+
+---
+
+## Users & Identity
+
+```typescript
+const user = await app.connect('alice@example.com');
+```
+
+Connects a user and establishes their encryption identity.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `userId` | `string` | User identifier (email, username, UUID) |
+
+| Returns | Description |
+|---------|-------------|
+| `StvorClient` | Client instance for this user |
+
+```typescript
+// Get current user ID
+user.getUserId(); // 'alice@example.com'
+
+// Multiple users
+const bob = await app.connect('bob@example.com');
+await alice.send('bob@example.com', 'Hey Bob!');
+```
+
+<Tip>
+Each device = separate user. Same user on different devices has different identity.
+</Tip>
+
+---
+
+## Sending Messages
+
+```typescript
+await alice.send('bob@example.com', 'Hello Bob!');
+await alice.send('bob@example.com', new Uint8Array([1, 2, 3]));
+```
+
+Sends an encrypted message to a recipient.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `recipientId` | `string` | Recipient's user ID |
+| `content` | `string \| Uint8Array` | Message text or binary data |
+
+| Returns | Description |
+|---------|-------------|
+| `Promise<void>` | Resolves when message is sent |
+
+```typescript
+// Send text
+await alice.send('bob@example.com', 'Hello!');
+
+// Send binary (files, images)
+const fileData = await fetchFile();
+await alice.send('bob@example.com', fileData);
+```
+
+<Warning>
+Message is delivered asynchronously. Use `await` to ensure message is sent.
+</Warning>
+
+---
+
+## Receiving Messages
+
+```typescript
+const message = await alice.receive();
+console.log(message.content);
+```
+
+Blocks until a message is available, then returns decrypted content.
+
+| Returns | Description |
+|---------|-------------|
+| `Promise<DecryptedMessage>` | Decrypted message object |
+
+```typescript
+interface DecryptedMessage {
+  id: string;        // Message identifier
+  senderId: string;  // Sender's user ID
+  content: string | Uint8Array;
+  timestamp: Date;   // When message was sent
+}
+```
+
+```typescript
+// Blocking receive
+const msg = await alice.receive();
+console.log(`${msg.senderId}: ${msg.content}`);
+
+// Non-blocking with subscription
+const unsubscribe = alice.onMessage((msg) => {
+  console.log(`[Push] ${msg.senderId}: ${msg.content}`);
+});
+// Later...
+unsubscribe();
+```
+
+<Tip>
+`receive()` blocks indefinitely. For production, use `onMessage()` subscription pattern.
+</Tip>
+
+---
+
+## Sealing Data
+
+For encrypting files, API payloads, or any binary data:
+
+```typescript
+const sealed = await alice.seal(fileData, 'bob@example.com');
+// Send sealed.ciphertext via your server...
+```
+
+Encrypts data for a specific recipient without establishing a session.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `data` | `string \| Uint8Array` | Data to encrypt |
+| `recipientId` | `string` | Recipient's user ID |
+
+| Returns | Description |
+|---------|-------------|
+| `Promise<SealedPayload>` | Encrypted package |
+
+```typescript
+interface SealedPayload {
+  ciphertext: Uint8Array;  // Encrypted data
+  nonce: Uint8Array;       // Encryption nonce
+  recipientId: string;     // Who this was sealed for
+}
+```
+
+```typescript
+// Seal a file
+const fileContent = await readFile('document.pdf');
+const sealed = await alice.seal(fileContent, 'bob@example.com');
+
+// Send via your server
+await fetch('/api/files', {
+  method: 'POST',
+  body: JSON.stringify({
+    ciphertext: Array.from(sealed.ciphertext),
+    nonce: Array.from(sealed.nonce)
+  })
+});
+```
+
+---
+
+## Opening Sealed Data
+
+```typescript
+const decrypted = await bob.open(sealed);
+```
+
+Decrypts data that was sealed for the recipient.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `sealed` | `SealedPayload` | Sealed payload from sender |
+
+| Returns | Description |
+|---------|-------------|
+| `Promise<Uint8Array>` | Decrypted data |
+
+```typescript
+// Receive sealed payload from server
+const response = await fetch('/api/files/123');
+const sealed: SealedPayload = await response.json();
+
+// Open it
+const decrypted = await bob.open(sealed);
+// Use decrypted data...
+```
+
+---
+
+# API Reference
+
+## Stvor.init()
+
+```typescript
+function init(config: StvorAppConfig): Promise<StvorApp>
+```
+
+Initializes the SDK with your AppToken.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config.appToken` | `string` | Yes | Token from developer dashboard |
+| `config.relayUrl` | `string` | No | Relay server URL |
+| `config.timeout` | `number` | No | Connection timeout (ms) |
+
+### Returns
+
+`Promise<StvorApp>` — Main SDK instance
+
+### Example
+
+```typescript
+const app = await Stvor.init({
+  appToken: process.env.STVOR_APP_TOKEN,
+  relayUrl: 'https://relay.stvor.io',
+  timeout: 15000
+});
+```
+
+### Errors
+
+- `AUTH_FAILED` — Invalid or revoked AppToken
+- `RELAY_UNAVAILABLE` — Cannot connect to relay
+
+---
+
+## StvorApp.connect()
+
+```typescript
+function connect(userId: string): Promise<StvorClient>
+```
+
+Connects a user and returns a client for messaging operations.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `userId` | `string` | Yes | User identifier |
+
+### Returns
+
+`Promise<StvorClient>` — Client for messaging
+
+### Example
+
+```typescript
+const alice = await app.connect('alice@example.com');
+await alice.send('bob@example.com', 'Hello!');
+```
+
+---
+
+## StvorClient.send()
+
+```typescript
+function send(recipientId: string, content: string | Uint8Array): Promise<void>
+```
+
+Sends an encrypted message to a recipient.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `recipientId` | `string` | Yes | Recipient's user ID |
+| `content` | `string \| Uint8Array` | Yes | Message content |
+
+### Returns
+
+`Promise<void>` — Resolves when sent
+
+### Example
+
+```typescript
+await alice.send('bob@example.com', 'Hello Bob!');
+await alice.send('bob@example.com', binaryData);
+```
+
+### Errors
+
+- `RECIPIENT_UNAVAILABLE` — Recipient offline > 24h
+- `DELIVERY_FAILED` — Message could not be delivered
+
+---
+
+## StvorClient.receive()
+
+```typescript
+function receive(): Promise<DecryptedMessage>
+```
+
+Receives and decrypts the next message.
+
+### Parameters
+
+None
+
+### Returns
+
+`Promise<DecryptedMessage>` — Decrypted message
+
+```typescript
+interface DecryptedMessage {
+  id: string;
+  senderId: string;
+  content: string | Uint8Array;
+  timestamp: Date;
+}
+```
+
+### Example
+
+```typescript
+const msg = await alice.receive();
+console.log(msg.content);
+```
+
+### Errors
+
+- `MESSAGE_INTEGRITY_FAILED` — Message corrupted or tampered
+
+---
+
+## StvorClient.seal()
+
+```typescript
+function seal(data: string | Uint8Array, recipientId: string): Promise<SealedPayload>
+```
+
+Encrypts data for a specific recipient.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `data` | `string \| Uint8Array` | Yes | Data to encrypt |
+| `recipientId` | `string` | Yes | Recipient's user ID |
+
+### Returns
+
+`Promise<SealedPayload>` — Encrypted payload
+
+### Example
+
+```typescript
+const sealed = await alice.seal(fileData, 'bob@example.com');
+```
+
+---
+
+## StvorClient.open()
+
+```typescript
+function open(sealed: SealedPayload): Promise<Uint8Array>
+```
+
+Decrypts sealed data.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `sealed` | `SealedPayload` | Yes | Sealed payload |
+
+### Returns
+
+`Promise<Uint8Array>` — Decrypted data
+
+### Example
+
+```typescript
+const decrypted = await bob.open(sealed);
+```
+
+---
+
+## StvorClient.onMessage()
+
+```typescript
+function onMessage(handler: (msg: DecryptedMessage) => void): () => void
+```
+
+Subscribes to incoming messages.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `handler` | `function` | Yes | Message callback |
+
+### Returns
+
+`() => void` — Unsubscribe function
+
+### Example
+
+```typescript
+const unsubscribe = alice.onMessage((msg) => {
+  console.log(`${msg.senderId}: ${msg.content}`);
+});
+
+// Unsubscribe later
+unsubscribe();
+```
+
+---
+
+# Errors
+
+## Error Codes
+
+| Code | Message | Action |
+|------|---------|--------|
+| `AUTH_FAILED` | AppToken is invalid or revoked | Get new token from dashboard |
+| `RELAY_UNAVAILABLE` | Cannot connect to relay server | Check network connection |
+| `RECIPIENT_UNAVAILABLE` | Recipient offline > 24 hours | Wait for recipient to come online |
+| `MESSAGE_INTEGRITY_FAILED` | Message corrupted or tampered | Request message again |
+| `KEYSTORE_CORRUPTED` | Local keystore corrupted | User must re-register device |
+| `DEVICE_COMPROMISED` | Security violation detected | Log out user immediately |
+| `PROTOCOL_VERSION_MISMATCH` | App version outdated | Update SDK |
+| `DELIVERY_FAILED` | Message delivery failed | Check recipient exists |
+
+## Error Handling
+
+```typescript
+try {
+  await alice.send('bob@example.com', 'Hello!');
+} catch (error) {
+  if (error.code === 'AUTH_FAILED') {
+    // Handle auth error
+    console.error(error.message);
+    console.error('Action:', error.action);
+  }
+}
+```
+
+---
+
+# Security Model
+
+## What STVOR Protects
+
+✅ End-to-end encryption of message content  
+✅ Perfect Forward Secrecy (new keys for each message)  
+✅ Post-quantum resistance (hybrid encryption)  
+✅ Message authentication (tampering detection)  
+✅ Secure key storage (encrypted keystore)  
+
+## What STVOR Does NOT Protect
+
+❌ **Metadata** — Relay knows who communicates with whom  
+❌ **Timing** — When messages are sent  
+❌ **Device security** — Rooted/jailbroken devices  
+❌ **Social engineering** — User sending message to wrong person  
+❌ **Screen capture** — Recipient can screenshot decrypted messages  
+
+## Threat Model
+
+- **Attacker model**: Network eavesdropper, relay operator (untrusted)
+- **Attacker goals**: Read message content, forge messages
+- **Attacker capabilities**: Observe metadata, control relay
+- **Attacker cannot**: Read content, forge authenticated messages, decrypt past messages
+
+<Tip>
+For metadata hiding, use a separate anonymity layer (Tor, mixnet).
+</Tip>
+
+---
+
+# Limits & Guarantees
+
+## Limits
+
+| Limit | Value |
+|-------|-------|
+| Message size | 1 MB |
+| Offline storage | 24 hours |
+| Sealed payload size | 10 MB |
+| Connection timeout | 10 seconds |
+
+## Guarantees
+
+- Messages delivered at least once
+- Decryption fails on tampering (hard fail)
+- No plaintext leaves the device
+- Keys never sent to relay
+
+---
+
+# FAQ
+
+**Q: Do I need to manage keys?**
+
+No. All key management is automatic and secure-by-default.
+
+**Q: Can users have multiple devices?**
+
+Yes, but each device is a separate identity. Sync is out of scope.
+
+**Q: Can users recover messages on a new device?**
+
+No. This would require storing keys on the server, which weakens security.
+
+**Q: Is this really end-to-end encrypted?**
+
+Yes. Plaintext never leaves the device. Relay only sees ciphertext.
+
+**Q: What happens if a user loses their device?**
+
+Messages on that device are lost. Messages to that user still work (they'll appear when they register a new device).
+
+**Q: Does STVOR work offline?**
+
+You can seal data offline. Sending/receiving requires connection to relay.
+
+**Q: How is post-quantum security achieved?**
+
+Hybrid encryption (X25519 + ML-KEM-768). No action required from developers.
+
+---
+
+## Next Steps
+
+1. [Get AppToken](https://dashboard.stvor.io)
+2. [Run Quickstart](#quickstart)
+3. [Explore API Reference](#api-reference)
+4. [Review Security Model](#security-model)
+
+---
+
+*STVOR SDK v2.0 — Secure by default.*

package/example.ts

@@ -0,0 +1,64 @@
+/**
+ * STVOR DX Facade - Quick Start Example
+ * 
+ * Copy-paste ready example for getting started.
+ * 
+ * IMPORTANT: This is a DX facade. The actual security guarantees
+ * depend on the STVOR core implementation.
+ */
+
+import { Stvor, StvorError, DecryptedMessage } from './index';
+
+/**
+ * Basic messaging example with proper error handling
+ */
+async function main() {
+  try {
+    // 1. Initialize SDK with AppToken from environment
+    const app = await Stvor.init({
+      appToken: process.env.STVOR_APP_TOKEN || 'stvor_demo_abc123...'
+    });
+    console.log('SDK initialized');
+
+    // 2. Connect as a user
+    const alice = await app.connect('alice@example.com');
+    console.log(`Connected as ${alice.getUserId()}`);
+
+    // 3. Subscribe to incoming messages (recommended for production)
+    const unsubscribe = alice.onMessage((msg: DecryptedMessage) => {
+      console.log(`[Push] ${msg.senderId}: ${msg.content}`);
+    });
+
+    // 4. Send encrypted message
+    await alice.send('bob@example.com', 'Hello Bob!');
+
+    // 5. Cleanup
+    await app.disconnect();
+    unsubscribe();
+    
+  } catch (error: unknown) {
+    if (error instanceof StvorError) {
+      console.error(`[${error.code}] ${error.message}`);
+      console.error(`Action: ${error.action}`);
+      console.error(`Retryable: ${error.retryable}`);
+    } else {
+      console.error('Unknown error:', error);
+    }
+  }
+}
+
+/**
+ * Note on security guarantees:
+ * 
+ * The facade provides a convenient API, but actual security
+ * (E2EE, PFS, post-quantum resistance) depends on the STVOR core.
+ * 
+ * For production use, verify:
+ * 1. Core implements Double Ratchet for PFS
+ * 2. Core implements ML-KEM for post-quantum resistance  
+ * 3. Keys are stored securely (not in plain memory)
+ * 4. Relay is trusted or verified
+ */
+
+// Run example
+main();