@stvor/sdk 2.0.0

package/facade/app.ts

@@ -0,0 +1,331 @@
+/**
+ * STVOR DX Facade - Main Application Classes
+ */
+
+import { StvorAppConfig, UserId, MessageContent } from './types';
+import { DecryptedMessage, SealedPayload } from './types';
+import { Errors, StvorError } from './errors';
+import { RelayClient } from './relay-client';
+
+export class StvorApp {
+  private relay: RelayClient;
+  private config: Required<StvorAppConfig>;
+  private connectedClients: Map<UserId, StvorFacadeClient> = new Map();
+
+  constructor(config: Required<StvorAppConfig>) {
+    this.config = config;
+    this.relay = new RelayClient(config.relayUrl, config.appToken, config.timeout);
+  }
+
+  isReady(): boolean {
+    return this.relay.isConnected();
+  }
+
+  async connect(userId: UserId): Promise<StvorFacadeClient> {
+    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?: UserId): Promise<void> {
+    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();
+    }
+  }
+
+  private async initClient(client: StvorFacadeClient): Promise<void> {
+    await client.internalInitialize();
+  }
+}
+
+export class StvorFacadeClient {
+  private userId: UserId;
+  private relay: RelayClient;
+  private initialized: boolean = false;
+  private sessionKeyPair: CryptoKeyPair | null = null;
+  private messageQueue: DecryptedMessage[] = [];
+  private messageHandlers: Map<string, (msg: DecryptedMessage) => void> = new Map();
+  private isReceiving: boolean = false;
+
+  constructor(userId: UserId, relay: RelayClient) {
+    this.userId = userId;
+    this.relay = relay;
+  }
+
+  async internalInitialize(): Promise<void> {
+    await this.initialize();
+  }
+
+  private async initialize(): Promise<void> {
+    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: UserId, content: MessageContent): Promise<void> {
+    if (!this.initialized) {
+      throw Errors.clientNotReady();
+    }
+
+    const contentBytes: Uint8Array = 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 } as AesGcmParams,
+      sharedKey,
+      contentBytes.buffer as ArrayBuffer
+    );
+
+    await this.relay.send({
+      to: recipientId,
+      from: this.userId,
+      ciphertext: new Uint8Array(encrypted),
+      nonce: iv,
+    });
+  }
+
+  async receive(): Promise<DecryptedMessage> {
+    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: MessageContent, recipientId: UserId): Promise<SealedPayload> {
+    if (!this.initialized) {
+      throw Errors.clientNotReady();
+    }
+
+    const contentBytes: Uint8Array = 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 } as AesGcmParams,
+      sharedKey,
+      contentBytes.buffer as ArrayBuffer
+    );
+
+    return {
+      ciphertext: new Uint8Array(encrypted),
+      nonce: iv,
+      recipientId,
+    };
+  }
+
+  async open(sealed: SealedPayload): Promise<Uint8Array> {
+    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 } as AesGcmParams,
+      sharedKey,
+      sealed.ciphertext.buffer as ArrayBuffer
+    );
+
+    return new Uint8Array(decrypted);
+  }
+
+  onMessage(handler: (msg: DecryptedMessage) => void): () => void {
+    const id = crypto.randomUUID();
+    this.messageHandlers.set(id, handler);
+    return () => {
+      this.messageHandlers.delete(id);
+    };
+  }
+
+  getUserId(): UserId {
+    return this.userId;
+  }
+
+  async disconnect(): Promise<void> {
+    this.messageHandlers.clear();
+    this.initialized = false;
+    this.sessionKeyPair = null;
+    this.messageQueue = [];
+    this.isReceiving = false;
+  }
+
+  private async deriveSharedKey(peerPublicKey: CryptoKey): Promise<CryptoKey> {
+    return await crypto.subtle.deriveKey(
+      { name: 'ECDH', public: peerPublicKey },
+      this.sessionKeyPair!.privateKey,
+      { name: 'AES-GCM', length: 256 },
+      false,
+      ['encrypt', 'decrypt']
+    );
+  }
+
+  private async fetchAndDecryptMessageWithTimeout(timeoutMs: number): Promise<DecryptedMessage> {
+    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();
+  }
+
+  private async decryptMessage(msg: { from: string; ciphertext: number[]; nonce: number[]; timestamp: string; id?: string }): Promise<DecryptedMessage> {
+    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) } as AesGcmParams,
+        sharedKey,
+        new Uint8Array(msg.ciphertext).buffer as ArrayBuffer
+      );
+
+      return {
+        id: msg.id || crypto.randomUUID(),
+        senderId: msg.from,
+        content: new TextDecoder().decode(decrypted),
+        timestamp: new Date(msg.timestamp),
+      };
+    } catch {
+      throw Errors.messageIntegrityFailed();
+    }
+  }
+
+  private startMessagePolling(): void {
+    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: StvorAppConfig): Promise<StvorApp> {
+  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: Required<StvorAppConfig> = {
+    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/facade/errors.ts

@@ -0,0 +1,149 @@
+/**
+ * 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',
+} as const;
+
+export type ErrorCode = typeof ErrorCode[keyof typeof ErrorCode];
+
+export class StvorError extends Error {
+  readonly code: ErrorCode;
+  readonly action: string;
+  readonly retryable: boolean;
+
+  constructor(
+    code: ErrorCode, 
+    message: string, 
+    action: string,
+    retryable: boolean = false
+  ) {
+    super(message);
+    this.name = 'StvorError';
+    this.code = code;
+    this.action = action;
+    this.retryable = retryable;
+  }
+}
+
+export const Errors = {
+  authFailed(): StvorError {
+    return new StvorError(
+      ErrorCode.AUTH_FAILED,
+      'The AppToken is invalid or has been revoked.',
+      'Check your dashboard and regenerate a new AppToken.',
+      false
+    );
+  },
+
+  invalidAppToken(): StvorError {
+    return new StvorError(
+      ErrorCode.INVALID_APP_TOKEN,
+      'Invalid AppToken format. AppToken must start with "stvor_".',
+      'Get your AppToken from the developer dashboard.',
+      false
+    );
+  },
+
+  relayUnavailable(): StvorError {
+    return new StvorError(
+      ErrorCode.RELAY_UNAVAILABLE,
+      'Cannot connect to STVOR relay server.',
+      'Check your internet connection.',
+      true
+    );
+  },
+
+  recipientNotFound(userId: string): StvorError {
+    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(): StvorError {
+    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(): StvorError {
+    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(): StvorError {
+    return new StvorError(
+      ErrorCode.DEVICE_COMPROMISED,
+      'Security violation detected. This device has been flagged.',
+      'Immediately log out the user and investigate.',
+      false
+    );
+  },
+
+  protocolMismatch(): StvorError {
+    return new StvorError(
+      ErrorCode.PROTOCOL_VERSION_MISMATCH,
+      'This app version uses an older protocol version.',
+      'Update the SDK to the latest version.',
+      false
+    );
+  },
+
+  clientNotReady(): StvorError {
+    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: string): StvorError {
+    return new StvorError(
+      ErrorCode.DELIVERY_FAILED,
+      `Failed to deliver message to ${recipientId}.`,
+      'Check that the recipient exists and try again.',
+      true
+    );
+  },
+
+  receiveTimeout(): StvorError {
+    return new StvorError(
+      ErrorCode.RECEIVE_TIMEOUT,
+      'No messages received within 30 second timeout.',
+      'Use onMessage() subscription for real-time updates.',
+      true
+    );
+  },
+
+  receiveInProgress(): StvorError {
+    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

@@ -0,0 +1,21 @@
+/**
+ * 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 { StvorApp, StvorFacadeClient } from './app';
+
+export { Stvor, init } from './app';
+export { ErrorCode as STVOR_ERRORS } from './errors';

package/facade/relay-client.ts

@@ -0,0 +1,173 @@
+/**
+ * STVOR DX Facade - Relay Client
+ */
+
+import { Errors } from './errors';
+
+interface OutgoingMessage {
+  to: string;
+  from: string;
+  ciphertext: Uint8Array;
+  nonce: Uint8Array;
+}
+
+interface IncomingMessage {
+  id?: string;
+  from: string;
+  ciphertext: number[];
+  nonce: number[];
+  timestamp: string;
+}
+
+export class RelayClient {
+  private relayUrl: string;
+  private timeout: number;
+  private appToken: string;
+  private connected: boolean = false;
+
+  constructor(relayUrl: string, appToken: string, timeout: number = 10000) {
+    this.relayUrl = relayUrl;
+    this.appToken = appToken;
+    this.timeout = timeout;
+  }
+
+  private getAuthHeaders(): Record<string, string> {
+    return {
+      'Authorization': `Bearer ${this.appToken}`,
+      'Content-Type': 'application/json',
+    };
+  }
+
+  async healthCheck(): Promise<void> {
+    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(): boolean {
+    return this.connected;
+  }
+
+  async register(userId: string, publicKey: JsonWebKey): Promise<void> {
+    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: string): Promise<CryptoKey | null> {
+    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: OutgoingMessage): Promise<void> {
+    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: string): Promise<IncomingMessage[]> {
+    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(): void {
+    this.connected = false;
+  }
+}