@syncvault/sdk 1.2.0 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncvault/sdk",
-  "version": "1.2.0",
+  "version": "1.4.1",
   "description": "SyncVault SDK - Zero-knowledge encrypted sync for Node.js and browsers",
   "type": "module",
   "main": "src/index.js",
@@ -18,7 +18,8 @@
     "src"
   ],
   "scripts": {
-    "test": "node test/test.js"
+    "test": "node test/test.js",
+    "build": "esbuild src/index.js --bundle --outfile=dist/index.js --format=esm --minify --sourcemap"
   },
   "keywords": [
     "syncvault",
@@ -45,5 +46,8 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "sideEffects": false
+  "sideEffects": false,
+  "devDependencies": {
+    "esbuild": "^0.27.2"
+  }
 }

package/src/crypto.js

@@ -137,3 +137,72 @@ function base64ToBuffer(base64) {
   }
   return bytes;
 }
+
+/**
+ * Decrypt data that was encrypted by an app server using hybrid encryption.
+ * The server encrypts an AES key with RSA-OAEP, then encrypts the data with AES-GCM.
+ * 
+ * Format: encryptedAESKey (256 bytes) + iv (12 bytes) + authTag (16 bytes) + ciphertext
+ * 
+ * @param {string} encryptedBase64 - Base64 encoded encrypted package
+ * @param {string} privateKeyBase64 - User's RSA private key in base64 (PKCS8 format)
+ */
+export async function decryptFromServer(encryptedBase64, privateKeyBase64) {
+  try {
+    const combined = base64ToBuffer(encryptedBase64);
+    
+    const RSA_KEY_SIZE = 256;
+    const AES_IV_LENGTH = 12;
+    const AUTH_TAG_LENGTH = 16;
+    
+    const minLength = RSA_KEY_SIZE + AES_IV_LENGTH + AUTH_TAG_LENGTH;
+    if (combined.length < minLength) {
+      throw new Error(`Invalid encrypted data: too short (${combined.length} bytes, need ${minLength})`);
+    }
+    
+    const encryptedAESKey = combined.slice(0, RSA_KEY_SIZE);
+    const iv = combined.slice(RSA_KEY_SIZE, RSA_KEY_SIZE + AES_IV_LENGTH);
+    const authTag = combined.slice(RSA_KEY_SIZE + AES_IV_LENGTH, RSA_KEY_SIZE + AES_IV_LENGTH + AUTH_TAG_LENGTH);
+    const ciphertext = combined.slice(RSA_KEY_SIZE + AES_IV_LENGTH + AUTH_TAG_LENGTH);
+    
+    const privateKeyBuffer = base64ToBuffer(privateKeyBase64);
+    
+    const privateKey = await crypto.subtle.importKey(
+      'pkcs8',
+      privateKeyBuffer,
+      { name: 'RSA-OAEP', hash: 'SHA-256' },
+      false,
+      ['decrypt']
+    );
+    
+    const rawAESKey = await crypto.subtle.decrypt(
+      { name: 'RSA-OAEP' },
+      privateKey,
+      encryptedAESKey
+    );
+    
+    const aesKey = await crypto.subtle.importKey(
+      'raw',
+      rawAESKey,
+      { name: 'AES-GCM' },
+      false,
+      ['decrypt']
+    );
+    
+    const ciphertextWithTag = new Uint8Array(ciphertext.length + AUTH_TAG_LENGTH);
+    ciphertextWithTag.set(ciphertext, 0);
+    ciphertextWithTag.set(authTag, ciphertext.length);
+    
+    const decrypted = await crypto.subtle.decrypt(
+      { name: 'AES-GCM', iv },
+      aesKey,
+      ciphertextWithTag
+    );
+    
+    const decoder = new TextDecoder();
+    return JSON.parse(decoder.decode(decrypted));
+  } catch (err) {
+    console.error('[SDK decryptFromServer] Error:', err.message);
+    throw err;
+  }
+}

package/src/index.d.ts

@@ -35,6 +35,20 @@ export interface QuotaInfo {
   unlimited: boolean;
 }
 
+export interface SharedVault {
+  id: string;
+  name: string;
+  ownerId: string;
+  ownerUsername: string;
+  memberCount: number;
+  isOwner: boolean;
+  createdAt: string;
+}
+
+export interface PutOptions {
+  updatedAt?: number | Date;
+}
+
 export declare class SyncVault {
   constructor(options: SyncVaultOptions);
   
@@ -48,7 +62,7 @@ export declare class SyncVault {
   register(username: string, password: string): Promise<User>;
   
   // Data operations
-  put<T = unknown>(path: string, data: T): Promise<PutResponse>;
+  put<T = unknown>(path: string, data: T, options?: PutOptions): Promise<PutResponse>;
   get<T = unknown>(path: string): Promise<T>;
   list(): Promise<FileInfo[]>;
   delete(path: string): Promise<DeleteResponse>;
@@ -64,6 +78,13 @@ export declare class SyncVault {
   // Quota info
   getQuota(): Promise<QuotaInfo>;
   
+  // Shared vaults
+  getSharedVaults(): Promise<SharedVault[]>;
+  listShared(vaultId: string): Promise<FileInfo[]>;
+  putShared<T = unknown>(vaultId: string, path: string, data: T, sharedPassword?: string): Promise<PutResponse>;
+  getShared<T = unknown>(vaultId: string, path: string, sharedPassword?: string): Promise<T>;
+  deleteShared(vaultId: string, path: string): Promise<DeleteResponse>;
+  
   // State
   isAuthenticated(): boolean;
   logout(): void;
@@ -79,6 +100,7 @@ export interface PendingOperation {
   type: 'put' | 'delete';
   path: string;
   data?: string;
+  updatedAt?: number;
   createdAt: number;
   retries: number;
 }

package/src/index.js

@@ -1,4 +1,6 @@
-import { encrypt, decrypt, prepareAuthPassword } from './crypto.js';
+import { encrypt, decrypt, prepareAuthPassword, decryptFromServer } from './crypto.js';
+
+export { encrypt, decrypt, decryptFromServer };
 
 const DEFAULT_SERVER = 'https://api.syncvault.dev';
 
@@ -107,15 +109,24 @@ export class SyncVault {
 
   /**
    * Store encrypted data
+   * @param {string} path - File path
+   * @param {any} data - Data to encrypt and store
+   * @param {Object} options - Optional settings
+   * @param {number} options.updatedAt - Timestamp for LWW conflict resolution
    */
-  async put(path, data) {
+  async put(path, data, options = {}) {
     this._checkAuth();
 
     const encrypted = await encrypt(data, this.password);
+    const body = { path, data: encrypted };
+    
+    if (options.updatedAt) {
+      body.updatedAt = new Date(options.updatedAt).toISOString();
+    }
 
     const response = await this._request('/api/sync/put', {
       method: 'POST',
-      body: JSON.stringify({ path, data: encrypted })
+      body: JSON.stringify(body)
     });
 
     return response;
@@ -215,6 +226,63 @@ export class SyncVault {
     return this._request('/api/sync/quota');
   }
 
+  // --- Shared Vaults ---
+
+  /**
+   * Get all shared vaults the user has access to in this app
+   */
+  async getSharedVaults() {
+    this._checkAuth();
+
+    return this._request('/api/sync/shared/vaults');
+  }
+
+  /**
+   * List files in a shared vault
+   */
+  async listShared(vaultId) {
+    this._checkAuth();
+
+    const response = await this._request(`/api/sync/shared/${vaultId}/list`);
+    return response.files;
+  }
+
+  /**
+   * Store encrypted data in a shared vault
+   */
+  async putShared(vaultId, path, data, sharedPassword) {
+    this._checkAuth();
+
+    const encrypted = await encrypt(data, sharedPassword || this.password);
+
+    return this._request(`/api/sync/shared/${vaultId}/put`, {
+      method: 'POST',
+      body: JSON.stringify({ path, data: encrypted })
+    });
+  }
+
+  /**
+   * Retrieve and decrypt data from a shared vault
+   */
+  async getShared(vaultId, path, sharedPassword) {
+    this._checkAuth();
+
+    const response = await this._request(`/api/sync/shared/${vaultId}/get?path=${encodeURIComponent(path)}`);
+    return decrypt(response.data, sharedPassword || this.password);
+  }
+
+  /**
+   * Delete a file from a shared vault
+   */
+  async deleteShared(vaultId, path) {
+    this._checkAuth();
+
+    return this._request(`/api/sync/shared/${vaultId}/delete`, {
+      method: 'POST',
+      body: JSON.stringify({ path })
+    });
+  }
+
   /**
    * Check if user is authenticated
    */
@@ -279,5 +347,154 @@ export class SyncVault {
   }
 }
 
-export { encrypt, decrypt } from './crypto.js';
+/**
+ * Server-side client for app backends to write data on behalf of users.
+ * Requires server_write OAuth scope to be granted by users.
+ * 
+ * Data is encrypted with the user's public key (RSA-OAEP),
+ * so only the user can decrypt it with their private key.
+ */
+export class SyncVaultServer {
+  constructor(options = {}) {
+    if (!options.appToken) {
+      throw new Error('appToken is required');
+    }
+    if (!options.secretToken) {
+      throw new Error('secretToken is required for server-side operations');
+    }
+
+    this.appToken = options.appToken;
+    this.secretToken = options.secretToken;
+    this.serverUrl = options.serverUrl || DEFAULT_SERVER;
+  }
+
+  /**
+   * Get user's public key for encryption
+   */
+  async getUserPublicKey(userId) {
+    return this._request(`/api/server/user/${userId}/public-key`);
+  }
+
+  /**
+   * Encrypt data with user's public key (RSA-OAEP + AES-GCM hybrid)
+   */
+  async encryptForUser(data, publicKeyPem) {
+    // Parse PEM to get raw key bytes
+    const pemBody = publicKeyPem
+      .replace(/-----BEGIN PUBLIC KEY-----/, '')
+      .replace(/-----END PUBLIC KEY-----/, '')
+      .replace(/\s+/g, '');
+    const publicKeyBuffer = Uint8Array.from(atob(pemBody), c => c.charCodeAt(0));
+    
+    const publicKey = await crypto.subtle.importKey(
+      'spki',
+      publicKeyBuffer,
+      { name: 'RSA-OAEP', hash: 'SHA-256' },
+      false,
+      ['encrypt']
+    );
+
+    const encoder = new TextEncoder();
+    const dataBuffer = encoder.encode(JSON.stringify(data));
+    
+    // Generate random AES key
+    const aesKey = await crypto.subtle.generateKey(
+      { name: 'AES-GCM', length: 256 },
+      true,
+      ['encrypt']
+    );
+
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const encryptedData = await crypto.subtle.encrypt(
+      { name: 'AES-GCM', iv },
+      aesKey,
+      dataBuffer
+    );
+
+    // Web Crypto returns ciphertext with authTag appended
+    // We need to separate them for our format
+    const encryptedArray = new Uint8Array(encryptedData);
+    const authTag = encryptedArray.slice(-16);
+    const ciphertext = encryptedArray.slice(0, -16);
+
+    const rawAesKey = await crypto.subtle.exportKey('raw', aesKey);
+    const encryptedAesKey = await crypto.subtle.encrypt(
+      { name: 'RSA-OAEP' },
+      publicKey,
+      rawAesKey
+    );
+
+    // Pack: encryptedAesKey (256 bytes) + iv (12 bytes) + authTag (16 bytes) + ciphertext
+    const result = new Uint8Array(
+      encryptedAesKey.byteLength + iv.byteLength + authTag.byteLength + ciphertext.byteLength
+    );
+    let offset = 0;
+    result.set(new Uint8Array(encryptedAesKey), offset);
+    offset += encryptedAesKey.byteLength;
+    result.set(iv, offset);
+    offset += iv.byteLength;
+    result.set(authTag, offset);
+    offset += authTag.byteLength;
+    result.set(ciphertext, offset);
+
+    return btoa(String.fromCharCode(...result));
+  }
+
+  /**
+   * Write pre-encrypted data to user's storage
+   */
+  async putForUser(userId, path, encryptedData) {
+    return this._request(`/api/server/user/${userId}/put`, {
+      method: 'POST',
+      body: JSON.stringify({ path, data: encryptedData })
+    });
+  }
+
+  /**
+   * Encrypt and store data for user in one call
+   */
+  async writeForUser(userId, path, data) {
+    const { publicKey } = await this.getUserPublicKey(userId);
+    const encrypted = await this.encryptForUser(data, publicKey);
+    return this.putForUser(userId, path, encrypted);
+  }
+
+  /**
+   * List files in user's storage for this app
+   */
+  async listForUser(userId) {
+    return this._request(`/api/server/user/${userId}/list`);
+  }
+
+  async _request(path, options = {}) {
+    const url = `${this.serverUrl}${path}`;
+
+    const headers = {
+      'Content-Type': 'application/json',
+      'X-App-Token': this.appToken,
+      'X-Secret-Token': this.secretToken
+    };
+
+    const response = await fetch(url, {
+      ...options,
+      headers: {
+        ...headers,
+        ...options.headers
+      }
+    });
+
+    const responseData = await response.json();
+
+    if (!response.ok) {
+      throw new SyncVaultError(
+        responseData.error || 'Request failed',
+        response.status,
+        responseData
+      );
+    }
+
+    return responseData;
+  }
+}
+
 export { OfflineSyncVault, OfflineStore, createOfflineClient } from './offline.js';

package/src/offline.js

@@ -219,15 +219,16 @@ export class OfflineSyncVault {
   }
   
   /**
-   * Put with offline support
+   * Put with offline support (LWW enabled)
    */
   async put(path, data) {
     await this.init();
     
+    const timestamp = Date.now();
     const encrypted = await encrypt(data, this.client.password);
     
     try {
-      const result = await this.client.put(path, data);
+      const result = await this.client.put(path, data, { updatedAt: timestamp });
       await this.store.setCache(path, encrypted);
       return result;
     } catch (error) {
@@ -236,7 +237,8 @@ export class OfflineSyncVault {
         await this.store.queueOperation({
           type: 'put',
           path,
-          data: encrypted
+          data: encrypted,
+          updatedAt: timestamp
         });
         return { queued: true, path };
       }
@@ -391,10 +393,31 @@ export class OfflineSyncVault {
   }
   
   async _syncPut(op) {
-    await this.client._request('/api/sync/put', {
-      method: 'POST',
-      body: JSON.stringify({ path: op.path, data: op.data })
-    });
+    const body = { path: op.path, data: op.data };
+    if (op.updatedAt) {
+      body.updatedAt = new Date(op.updatedAt).toISOString();
+    }
+    
+    try {
+      await this.client._request('/api/sync/put', {
+        method: 'POST',
+        body: JSON.stringify(body)
+      });
+    } catch (error) {
+      // LWW conflict - server has newer data, discard local change
+      if (error.statusCode === 409 && error.data?.code === 'CONFLICT_STALE') {
+        // Fetch fresh data from server to update cache
+        try {
+          const result = await this.client.get(op.path);
+          const encrypted = await encrypt(result, this.client.password);
+          await this.store.setCache(op.path, encrypted);
+        } catch (cacheErr) {
+          console.warn('Failed to update cache after LWW conflict:', cacheErr.message);
+        }
+        return; // Consider this "synced" - we accepted server's version
+      }
+      throw error;
+    }
   }
   
   async _syncDelete(op) {