@stvor/sdk 2.0.0 → 2.0.2

package/dist/example.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+export {};

package/dist/example.js

@@ -0,0 +1,57 @@
+/**
+ * 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 } 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) => {
+            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) {
+        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();

package/dist/facade/app.d.ts

@@ -0,0 +1,46 @@
+/**
+ * STVOR DX Facade - Main Application Classes
+ */
+import { StvorAppConfig, UserId, MessageContent } from './types';
+import { DecryptedMessage, SealedPayload } from './types';
+import { Errors, StvorError, ErrorCode } from './errors';
+export type { DecryptedMessage, SealedPayload, ErrorCode };
+export { StvorError, Errors };
+import { RelayClient } from './relay-client';
+export declare class StvorApp {
+    private relay;
+    private config;
+    private connectedClients;
+    constructor(config: Required<StvorAppConfig>);
+    isReady(): boolean;
+    connect(userId: UserId): Promise<StvorFacadeClient>;
+    disconnect(userId?: UserId): Promise<void>;
+    private initClient;
+}
+export declare class StvorFacadeClient {
+    private userId;
+    private relay;
+    private initialized;
+    private sessionKeyPair;
+    private messageQueue;
+    private messageHandlers;
+    private isReceiving;
+    constructor(userId: UserId, relay: RelayClient);
+    internalInitialize(): Promise<void>;
+    private initialize;
+    send(recipientId: UserId, content: MessageContent): Promise<void>;
+    receive(): Promise<DecryptedMessage>;
+    seal(data: MessageContent, recipientId: UserId): Promise<SealedPayload>;
+    open(sealed: SealedPayload): Promise<Uint8Array>;
+    onMessage(handler: (msg: DecryptedMessage) => void): () => void;
+    getUserId(): UserId;
+    disconnect(): Promise<void>;
+    private deriveSharedKey;
+    private fetchAndDecryptMessageWithTimeout;
+    private decryptMessage;
+    private startMessagePolling;
+}
+export declare function init(config: StvorAppConfig): Promise<StvorApp>;
+export declare const Stvor: {
+    init: typeof init;
+};

package/dist/facade/app.js

@@ -0,0 +1,247 @@
+/**
+ * STVOR DX Facade - Main Application Classes
+ */
+import { Errors, StvorError } from './errors';
+export { StvorError, Errors };
+import { RelayClient } from './relay-client';
+export class StvorApp {
+    constructor(config) {
+        this.connectedClients = new Map();
+        this.config = config;
+        this.relay = new RelayClient(config.relayUrl, config.appToken, config.timeout);
+    }
+    isReady() {
+        return this.relay.isConnected();
+    }
+    async connect(userId) {
+        const existingClient = this.connectedClients.get(userId);
+        if (existingClient) {
+            console.warn(`[STVOR] Warning: User "${userId}" is already connected. Returning cached client.`);
+            return existingClient;
+        }
+        const client = new StvorFacadeClient(userId, this.relay);
+        await this.initClient(client);
+        this.connectedClients.set(userId, client);
+        return client;
+    }
+    async disconnect(userId) {
+        if (userId) {
+            const client = this.connectedClients.get(userId);
+            if (client) {
+                await client.disconnect();
+                this.connectedClients.delete(userId);
+            }
+        }
+        else {
+            for (const client of this.connectedClients.values()) {
+                await client.disconnect();
+            }
+            this.connectedClients.clear();
+            this.relay.disconnect();
+        }
+    }
+    async initClient(client) {
+        await client.internalInitialize();
+    }
+}
+export class StvorFacadeClient {
+    constructor(userId, relay) {
+        this.initialized = false;
+        this.sessionKeyPair = null;
+        this.messageQueue = [];
+        this.messageHandlers = new Map();
+        this.isReceiving = false;
+        this.userId = userId;
+        this.relay = relay;
+    }
+    async internalInitialize() {
+        await this.initialize();
+    }
+    async initialize() {
+        if (this.initialized)
+            return;
+        this.sessionKeyPair = await crypto.subtle.generateKey({ name: 'ECDH', namedCurve: 'X25519' }, true, ['deriveKey', 'deriveBits']);
+        const publicKeyJwk = await crypto.subtle.exportKey('jwk', this.sessionKeyPair.publicKey);
+        await this.relay.register(this.userId, publicKeyJwk);
+        this.initialized = true;
+        this.startMessagePolling();
+    }
+    async send(recipientId, content) {
+        if (!this.initialized) {
+            throw Errors.clientNotReady();
+        }
+        const contentBytes = typeof content === 'string'
+            ? new TextEncoder().encode(content)
+            : content;
+        const recipientKey = await this.relay.getPublicKey(recipientId);
+        if (!recipientKey) {
+            throw Errors.recipientNotFound(recipientId);
+        }
+        const sharedKey = await this.deriveSharedKey(recipientKey);
+        const iv = crypto.getRandomValues(new Uint8Array(12));
+        const encrypted = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, sharedKey, contentBytes.buffer);
+        await this.relay.send({
+            to: recipientId,
+            from: this.userId,
+            ciphertext: new Uint8Array(encrypted),
+            nonce: iv,
+        });
+    }
+    async receive() {
+        if (!this.initialized) {
+            throw Errors.clientNotReady();
+        }
+        if (this.isReceiving) {
+            throw Errors.receiveInProgress();
+        }
+        if (this.messageQueue.length > 0) {
+            return this.messageQueue.shift();
+        }
+        this.isReceiving = true;
+        try {
+            return await this.fetchAndDecryptMessageWithTimeout(30000);
+        }
+        finally {
+            this.isReceiving = false;
+        }
+    }
+    async seal(data, recipientId) {
+        if (!this.initialized) {
+            throw Errors.clientNotReady();
+        }
+        const contentBytes = typeof data === 'string'
+            ? new TextEncoder().encode(data)
+            : data;
+        const recipientKey = await this.relay.getPublicKey(recipientId);
+        if (!recipientKey) {
+            throw Errors.recipientNotFound(recipientId);
+        }
+        const sharedKey = await this.deriveSharedKey(recipientKey);
+        const iv = crypto.getRandomValues(new Uint8Array(12));
+        const encrypted = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, sharedKey, contentBytes.buffer);
+        return {
+            ciphertext: new Uint8Array(encrypted),
+            nonce: iv,
+            recipientId,
+        };
+    }
+    async open(sealed) {
+        if (!this.initialized) {
+            throw Errors.clientNotReady();
+        }
+        const senderKey = await this.relay.getPublicKey(sealed.recipientId);
+        if (!senderKey) {
+            throw Errors.recipientNotFound(sealed.recipientId);
+        }
+        const sharedKey = await this.deriveSharedKey(senderKey);
+        const decrypted = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: sealed.nonce }, sharedKey, sealed.ciphertext.buffer);
+        return new Uint8Array(decrypted);
+    }
+    onMessage(handler) {
+        const id = crypto.randomUUID();
+        this.messageHandlers.set(id, handler);
+        return () => {
+            this.messageHandlers.delete(id);
+        };
+    }
+    getUserId() {
+        return this.userId;
+    }
+    async disconnect() {
+        this.messageHandlers.clear();
+        this.initialized = false;
+        this.sessionKeyPair = null;
+        this.messageQueue = [];
+        this.isReceiving = false;
+    }
+    async deriveSharedKey(peerPublicKey) {
+        return await crypto.subtle.deriveKey({ name: 'ECDH', public: peerPublicKey }, this.sessionKeyPair.privateKey, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+    }
+    async fetchAndDecryptMessageWithTimeout(timeoutMs) {
+        const pollInterval = 1000;
+        let waited = 0;
+        while (waited < timeoutMs) {
+            try {
+                const messages = await this.relay.fetchMessages(this.userId);
+                if (messages.length > 0) {
+                    return await this.decryptMessage(messages[0]);
+                }
+            }
+            catch {
+                // Silent error on poll
+            }
+            waited += pollInterval;
+            await new Promise(resolve => setTimeout(resolve, pollInterval));
+        }
+        throw Errors.receiveTimeout();
+    }
+    async decryptMessage(msg) {
+        const senderKey = await this.relay.getPublicKey(msg.from);
+        if (!senderKey) {
+            throw Errors.recipientNotFound(msg.from);
+        }
+        const sharedKey = await this.deriveSharedKey(senderKey);
+        try {
+            const decrypted = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: new Uint8Array(msg.nonce) }, sharedKey, new Uint8Array(msg.ciphertext).buffer);
+            return {
+                id: msg.id || crypto.randomUUID(),
+                senderId: msg.from,
+                content: new TextDecoder().decode(decrypted),
+                timestamp: new Date(msg.timestamp),
+            };
+        }
+        catch {
+            throw Errors.messageIntegrityFailed();
+        }
+    }
+    startMessagePolling() {
+        const poll = async () => {
+            try {
+                const messages = await this.relay.fetchMessages(this.userId);
+                if (messages.length > 0) {
+                    const msg = await this.decryptMessage(messages[0]);
+                    this.messageQueue.push(msg);
+                    for (const handler of this.messageHandlers.values()) {
+                        try {
+                            handler(msg);
+                        }
+                        catch {
+                            // Handler error does not break other handlers
+                        }
+                    }
+                }
+            }
+            catch {
+                // Silent error on poll
+            }
+            if (this.initialized) {
+                setTimeout(poll, 1000);
+            }
+        };
+        poll();
+    }
+}
+export async function init(config) {
+    const relayUrl = config.relayUrl || 'https://relay.stvor.io';
+    const timeout = config.timeout || 10000;
+    if (!config.appToken || !config.appToken.startsWith('stvor_')) {
+        throw Errors.invalidAppToken();
+    }
+    const appConfig = {
+        appToken: config.appToken,
+        relayUrl,
+        timeout,
+    };
+    const app = new StvorApp(appConfig);
+    try {
+        const relay = new RelayClient(relayUrl, config.appToken, timeout);
+        await relay.healthCheck();
+    }
+    catch {
+        throw Errors.relayUnavailable();
+    }
+    return app;
+}
+export const Stvor = {
+    init,
+};

package/dist/facade/errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * STVOR DX Facade - Error Handling
+ */
+export declare const ErrorCode: {
+    readonly AUTH_FAILED: "AUTH_FAILED";
+    readonly INVALID_APP_TOKEN: "INVALID_APP_TOKEN";
+    readonly RELAY_UNAVAILABLE: "RELAY_UNAVAILABLE";
+    readonly RECIPIENT_NOT_FOUND: "RECIPIENT_NOT_FOUND";
+    readonly MESSAGE_INTEGRITY_FAILED: "MESSAGE_INTEGRITY_FAILED";
+    readonly KEYSTORE_CORRUPTED: "KEYSTORE_CORRUPTED";
+    readonly DEVICE_COMPROMISED: "DEVICE_COMPROMISED";
+    readonly PROTOCOL_VERSION_MISMATCH: "PROTOCOL_VERSION_MISMATCH";
+    readonly CLIENT_NOT_READY: "CLIENT_NOT_READY";
+    readonly DELIVERY_FAILED: "DELIVERY_FAILED";
+    readonly RECEIVE_TIMEOUT: "RECEIVE_TIMEOUT";
+    readonly RECEIVE_IN_PROGRESS: "RECEIVE_IN_PROGRESS";
+};
+export type ErrorCode = typeof ErrorCode[keyof typeof ErrorCode];
+export declare class StvorError extends Error {
+    code: string;
+    action?: string;
+    retryable?: boolean;
+    constructor(code: string, message: string, action?: string, retryable?: boolean);
+}
+export declare const Errors: {
+    authFailed(): StvorError;
+    invalidAppToken(): StvorError;
+    relayUnavailable(): StvorError;
+    recipientNotFound(userId: string): StvorError;
+    messageIntegrityFailed(): StvorError;
+    keystoreCorrupted(): StvorError;
+    deviceCompromised(): StvorError;
+    protocolMismatch(): StvorError;
+    clientNotReady(): StvorError;
+    deliveryFailed(recipientId: string): StvorError;
+    receiveTimeout(): StvorError;
+    receiveInProgress(): StvorError;
+};

package/dist/facade/errors.js

@@ -0,0 +1,64 @@
+/**
+ * STVOR DX Facade - Error Handling
+ */
+export const ErrorCode = {
+    AUTH_FAILED: 'AUTH_FAILED',
+    INVALID_APP_TOKEN: 'INVALID_APP_TOKEN',
+    RELAY_UNAVAILABLE: 'RELAY_UNAVAILABLE',
+    RECIPIENT_NOT_FOUND: 'RECIPIENT_NOT_FOUND',
+    MESSAGE_INTEGRITY_FAILED: 'MESSAGE_INTEGRITY_FAILED',
+    KEYSTORE_CORRUPTED: 'KEYSTORE_CORRUPTED',
+    DEVICE_COMPROMISED: 'DEVICE_COMPROMISED',
+    PROTOCOL_VERSION_MISMATCH: 'PROTOCOL_VERSION_MISMATCH',
+    CLIENT_NOT_READY: 'CLIENT_NOT_READY',
+    DELIVERY_FAILED: 'DELIVERY_FAILED',
+    RECEIVE_TIMEOUT: 'RECEIVE_TIMEOUT',
+    RECEIVE_IN_PROGRESS: 'RECEIVE_IN_PROGRESS',
+};
+export class StvorError extends Error {
+    constructor(code, message, action, retryable) {
+        super(message);
+        this.name = 'StvorError';
+        this.code = code;
+        this.action = action;
+        this.retryable = retryable;
+    }
+}
+export const Errors = {
+    authFailed() {
+        return new StvorError(ErrorCode.AUTH_FAILED, 'The AppToken is invalid or has been revoked.', 'Check your dashboard and regenerate a new AppToken.', false);
+    },
+    invalidAppToken() {
+        return new StvorError(ErrorCode.INVALID_APP_TOKEN, 'Invalid AppToken format. AppToken must start with "stvor_".', 'Get your AppToken from the developer dashboard.', false);
+    },
+    relayUnavailable() {
+        return new StvorError(ErrorCode.RELAY_UNAVAILABLE, 'Cannot connect to STVOR relay server.', 'Check your internet connection.', true);
+    },
+    recipientNotFound(userId) {
+        return new StvorError(ErrorCode.RECIPIENT_NOT_FOUND, `User "${userId}" not found. They may not have registered with STVOR.`, 'Ask the recipient to initialize STVOR first, or verify the userId is correct.', false);
+    },
+    messageIntegrityFailed() {
+        return new StvorError(ErrorCode.MESSAGE_INTEGRITY_FAILED, 'Message integrity check failed. The message may be corrupted or tampered with.', 'Request the message again from the sender.', false);
+    },
+    keystoreCorrupted() {
+        return new StvorError(ErrorCode.KEYSTORE_CORRUPTED, 'Local keystore is corrupted. All local keys have been wiped.', 'The user will need to re-register this device.', false);
+    },
+    deviceCompromised() {
+        return new StvorError(ErrorCode.DEVICE_COMPROMISED, 'Security violation detected. This device has been flagged.', 'Immediately log out the user and investigate.', false);
+    },
+    protocolMismatch() {
+        return new StvorError(ErrorCode.PROTOCOL_VERSION_MISMATCH, 'This app version uses an older protocol version.', 'Update the SDK to the latest version.', false);
+    },
+    clientNotReady() {
+        return new StvorError(ErrorCode.CLIENT_NOT_READY, 'Client is not ready. Call connect() first and await it.', 'Make sure to await app.connect() before sending messages.', false);
+    },
+    deliveryFailed(recipientId) {
+        return new StvorError(ErrorCode.DELIVERY_FAILED, `Failed to deliver message to ${recipientId}.`, 'Check that the recipient exists and try again.', true);
+    },
+    receiveTimeout() {
+        return new StvorError(ErrorCode.RECEIVE_TIMEOUT, 'No messages received within 30 second timeout.', 'Use onMessage() subscription for real-time updates.', true);
+    },
+    receiveInProgress() {
+        return new StvorError(ErrorCode.RECEIVE_IN_PROGRESS, 'A receive() call is already in progress.', 'Wait for the current receive() to complete before calling again.', true);
+    },
+};

package/{facade/index.ts → dist/facade/index.d.ts}

@@ -1,21 +1,17 @@
 /**
  * STVOR DX Facade SDK
  * High-level developer experience layer for STVOR E2E encryption
- * 
+ *
  * Design goals:
  * - Minimal API surface
  * - Zero crypto knowledge required
  * - Secure by default
  * - Opinionated (no configuration)
  */
-
-// Re-export types
 export type { DecryptedMessage, SealedPayload } from './app';
 export type { StvorAppConfig, AppToken, UserId, MessageContent } from './types';
-export type { ErrorCode, StvorError } from './errors';
-
-// Re-export classes and functions
+export type { ErrorCode } from './errors';
+export { StvorError } from './errors';
 export { StvorApp, StvorFacadeClient } from './app';
-
 export { Stvor, init } from './app';
 export { ErrorCode as STVOR_ERRORS } from './errors';

package/dist/facade/index.js

@@ -0,0 +1,15 @@
+/**
+ * STVOR DX Facade SDK
+ * High-level developer experience layer for STVOR E2E encryption
+ *
+ * Design goals:
+ * - Minimal API surface
+ * - Zero crypto knowledge required
+ * - Secure by default
+ * - Opinionated (no configuration)
+ */
+export { StvorError } from './errors';
+// Re-export classes and functions
+export { StvorApp, StvorFacadeClient } from './app';
+export { Stvor, init } from './app';
+export { ErrorCode as STVOR_ERRORS } from './errors';

package/dist/facade/relay-client.d.ts

@@ -0,0 +1,32 @@
+/**
+ * STVOR DX Facade - Relay Client
+ */
+interface OutgoingMessage {
+    to: string;
+    from: string;
+    ciphertext: Uint8Array;
+    nonce: Uint8Array;
+}
+interface IncomingMessage {
+    id?: string;
+    from: string;
+    ciphertext: number[];
+    nonce: number[];
+    timestamp: string;
+}
+export declare class RelayClient {
+    private relayUrl;
+    private timeout;
+    private appToken;
+    private connected;
+    constructor(relayUrl: string, appToken: string, timeout?: number);
+    private getAuthHeaders;
+    healthCheck(): Promise<void>;
+    isConnected(): boolean;
+    register(userId: string, publicKey: JsonWebKey): Promise<void>;
+    getPublicKey(userId: string): Promise<CryptoKey | null>;
+    send(message: OutgoingMessage): Promise<void>;
+    fetchMessages(userId: string): Promise<IncomingMessage[]>;
+    disconnect(): void;
+}
+export {};

package/dist/facade/relay-client.js

@@ -0,0 +1,128 @@
+/**
+ * STVOR DX Facade - Relay Client
+ */
+import { Errors } from './errors';
+export class RelayClient {
+    constructor(relayUrl, appToken, timeout = 10000) {
+        this.connected = false;
+        this.relayUrl = relayUrl;
+        this.appToken = appToken;
+        this.timeout = timeout;
+    }
+    getAuthHeaders() {
+        return {
+            'Authorization': `Bearer ${this.appToken}`,
+            'Content-Type': 'application/json',
+        };
+    }
+    async healthCheck() {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const res = await fetch(`${this.relayUrl}/health`, {
+                method: 'GET',
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                throw Errors.relayUnavailable();
+            }
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    isConnected() {
+        return this.connected;
+    }
+    async register(userId, publicKey) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const res = await fetch(`${this.relayUrl}/register`, {
+                method: 'POST',
+                headers: this.getAuthHeaders(),
+                body: JSON.stringify({ user_id: userId, publicKey }),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const error = await res.json().catch(() => ({}));
+                if (error.code === 'AUTH_FAILED') {
+                    throw Errors.authFailed();
+                }
+                throw Errors.relayUnavailable();
+            }
+            this.connected = true;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    async getPublicKey(userId) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const res = await fetch(`${this.relayUrl}/public-key/${userId}`, {
+                method: 'GET',
+                headers: this.getAuthHeaders(),
+                signal: controller.signal,
+            });
+            if (res.status === 404) {
+                return null;
+            }
+            if (!res.ok) {
+                throw Errors.relayUnavailable();
+            }
+            const data = await res.json();
+            const jwk = data.publicKey;
+            return await crypto.subtle.importKey('jwk', jwk, { name: 'ECDH', namedCurve: 'X25519' }, false, []);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    async send(message) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const res = await fetch(`${this.relayUrl}/message`, {
+                method: 'POST',
+                headers: this.getAuthHeaders(),
+                body: JSON.stringify({
+                    to: message.to,
+                    from: message.from,
+                    ciphertext: Array.from(message.ciphertext),
+                    nonce: Array.from(message.nonce),
+                }),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                throw Errors.deliveryFailed(message.to);
+            }
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    async fetchMessages(userId) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const res = await fetch(`${this.relayUrl}/messages/${userId}`, {
+                method: 'GET',
+                headers: this.getAuthHeaders(),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                throw Errors.relayUnavailable();
+            }
+            const data = await res.json();
+            return data.messages || [];
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    disconnect() {
+        this.connected = false;
+    }
+}