@syncvault/sdk 1.0.0

package/README.md

@@ -0,0 +1,161 @@
+# @syncvault/sdk
+
+Zero-knowledge sync SDK for Node.js and browsers.
+
+## Installation
+
+```bash
+npm install @syncvault/sdk
+```
+
+## Quick Start (OAuth Flow - Recommended)
+
+```javascript
+import { SyncVault } from '@syncvault/sdk';
+
+const vault = new SyncVault({
+  appToken: 'your_app_token',
+  redirectUri: 'http://localhost:3000/callback',
+  serverUrl: 'https://api.syncvault.io' // optional
+});
+
+// Step 1: Redirect user to authorize
+const authUrl = vault.getAuthUrl();
+window.location.href = authUrl;
+
+// Step 2: After redirect, exchange code for token
+// The user will be redirected to: http://localhost:3000/callback?code=xxx
+const urlParams = new URLSearchParams(window.location.search);
+const code = urlParams.get('code');
+
+// User must provide their encryption password
+const password = prompt('Enter your encryption password:');
+const user = await vault.exchangeCode(code, password);
+
+// Step 3: Use the SDK
+await vault.put('data.json', { hello: 'world' });
+const data = await vault.get('data.json');
+```
+
+## Quick Start (Direct Auth)
+
+```javascript
+import { SyncVault } from '@syncvault/sdk';
+
+const vault = new SyncVault({
+  appToken: 'your_app_token',
+  serverUrl: 'https://api.syncvault.io' // optional
+});
+
+// Authenticate user directly
+await vault.auth('username', 'password');
+
+// Store data (automatically encrypted)
+await vault.put('notes/my-note.json', { 
+  title: 'Hello', 
+  content: 'World' 
+});
+
+// Retrieve data (automatically decrypted)
+const note = await vault.get('notes/my-note.json');
+```
+
+## API Reference
+
+### Constructor
+
+```javascript
+new SyncVault({
+  appToken: string,      // Required: Your app token from developer dashboard
+  serverUrl?: string,    // Optional: API URL (default: https://api.syncvault.dev)
+  redirectUri?: string   // Required for OAuth flow
+})
+```
+
+### OAuth Methods
+
+#### `vault.getAuthUrl(state?)`
+Generate OAuth authorization URL. Redirect users here to start the flow.
+
+#### `vault.exchangeCode(code, password)`
+Exchange authorization code for access token. Call this after user returns with the code.
+
+#### `vault.setAuth(token, password)`
+Manually set authentication state (e.g., from stored session).
+
+### Direct Auth Methods
+
+#### `vault.auth(username, password)`
+Authenticate user directly. Requires valid app token.
+
+#### `vault.register(username, password)`
+Register new user. Requires valid app token.
+
+### Data Methods
+
+#### `vault.put(path, data)`
+Store encrypted data at the given path.
+
+#### `vault.get(path)`
+Retrieve and decrypt data from the given path.
+
+#### `vault.list()`
+List all files for this app.
+
+#### `vault.delete(path)`
+Delete a file.
+
+### Metadata Methods
+
+App metadata is unencrypted data stored server-side. Use it for app-specific logic like subscription status, feature flags, or user preferences that don't need encryption.
+
+#### `vault.getMetadata()`
+Get app metadata for the current user.
+
+#### `vault.setMetadata(metadata)`
+Set app metadata (replaces all existing metadata).
+
+#### `vault.updateMetadata(metadata)`
+Update app metadata (merges with existing metadata).
+
+```javascript
+// Example: Store subscription status
+await vault.setMetadata({
+  subscriptionActive: true,
+  subscriptionExpiresAt: '2026-12-31',
+  plan: 'premium'
+});
+
+// Read metadata
+const meta = await vault.getMetadata();
+console.log(meta.subscriptionActive); // true
+
+// Update specific fields
+await vault.updateMetadata({ lastLogin: new Date().toISOString() });
+```
+
+### State Methods
+
+#### `vault.isAuthenticated()`
+Check if user is authenticated.
+
+#### `vault.logout()`
+Clear authentication state.
+
+#### `vault.getUser()`
+Get current user info.
+
+## App Permissions
+
+Apps can request specific permissions when created:
+- `read` - Read user data
+- `write` - Create and update user data
+- `delete` - Delete user data
+
+Users see these permissions during OAuth authorization.
+
+## Encryption
+
+All data is encrypted client-side using AES-256-GCM with a key derived from the user's password using PBKDF2 (100,000 iterations). The server never sees unencrypted data.
+
+Note: Metadata is NOT encrypted - use it only for non-sensitive app logic.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@syncvault/sdk",
+  "version": "1.0.0",
+  "description": "SyncVault SDK - Zero-knowledge encrypted sync for Node.js and browsers",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./src/index.d.ts"
+    },
+    "./crypto": {
+      "import": "./src/crypto.js"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node test/test.js"
+  },
+  "keywords": [
+    "syncvault",
+    "sync",
+    "encryption",
+    "e2e",
+    "end-to-end-encryption",
+    "zero-knowledge",
+    "aes-256",
+    "pbkdf2",
+    "cloud-sync",
+    "secure-storage"
+  ],
+  "author": "SyncVault <support@syncvault.dev>",
+  "license": "MIT",
+  "homepage": "https://syncvault.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/syncvault-dev/sdk-js"
+  },
+  "bugs": {
+    "url": "https://github.com/syncvault-dev/sdk-js/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "sideEffects": false
+}

package/src/crypto.js

@@ -0,0 +1,139 @@
+/**
+ * Cryptographic utilities for SyncVault SDK
+ * Uses Web Crypto API (works in Node.js 18+ and browsers)
+ */
+
+const SALT_LENGTH = 16;
+const IV_LENGTH = 12;
+const KEY_LENGTH = 256;
+const ITERATIONS = 100000;
+
+/**
+ * Prepare password for authentication (hashing)
+ * This ensures the server never sees the raw password used for encryption
+ */
+export async function prepareAuthPassword(password) {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(password);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Derive encryption key from password using PBKDF2
+ */
+export async function deriveKey(password, salt) {
+  const encoder = new TextEncoder();
+  const passwordBuffer = encoder.encode(password);
+
+  const keyMaterial = await crypto.subtle.importKey(
+    'raw',
+    passwordBuffer,
+    'PBKDF2',
+    false,
+    ['deriveKey']
+  );
+
+  return crypto.subtle.deriveKey(
+    {
+      name: 'PBKDF2',
+      salt,
+      iterations: ITERATIONS,
+      hash: 'SHA-256'
+    },
+    keyMaterial,
+    { name: 'AES-GCM', length: KEY_LENGTH },
+    false,
+    ['encrypt', 'decrypt']
+  );
+}
+
+/**
+ * Generate a random salt
+ */
+export function generateSalt() {
+  return crypto.getRandomValues(new Uint8Array(SALT_LENGTH));
+}
+
+/**
+ * Encrypt data using AES-256-GCM
+ * Returns: salt (16 bytes) + iv (12 bytes) + ciphertext
+ */
+export async function encrypt(data, password) {
+  const encoder = new TextEncoder();
+  const dataBuffer = encoder.encode(JSON.stringify(data));
+
+  const salt = generateSalt();
+  const key = await deriveKey(password, salt);
+  const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+
+  const ciphertext = await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    dataBuffer
+  );
+
+  // Combine salt + iv + ciphertext
+  const combined = new Uint8Array(
+    SALT_LENGTH + IV_LENGTH + ciphertext.byteLength
+  );
+  combined.set(salt, 0);
+  combined.set(iv, SALT_LENGTH);
+  combined.set(new Uint8Array(ciphertext), SALT_LENGTH + IV_LENGTH);
+
+  return bufferToBase64(combined);
+}
+
+/**
+ * Decrypt data using AES-256-GCM
+ */
+export async function decrypt(encryptedBase64, password) {
+  const combined = base64ToBuffer(encryptedBase64);
+
+  const salt = combined.slice(0, SALT_LENGTH);
+  const iv = combined.slice(SALT_LENGTH, SALT_LENGTH + IV_LENGTH);
+  const ciphertext = combined.slice(SALT_LENGTH + IV_LENGTH);
+
+  const key = await deriveKey(password, salt);
+
+  const decrypted = await crypto.subtle.decrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    ciphertext
+  );
+
+  const decoder = new TextDecoder();
+  return JSON.parse(decoder.decode(decrypted));
+}
+
+/**
+ * Convert Uint8Array to base64 string
+ */
+function bufferToBase64(buffer) {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(buffer).toString('base64');
+  }
+  // Browser fallback
+  let binary = '';
+  for (let i = 0; i < buffer.byteLength; i++) {
+    binary += String.fromCharCode(buffer[i]);
+  }
+  return btoa(binary);
+}
+
+/**
+ * Convert base64 string to Uint8Array
+ */
+function base64ToBuffer(base64) {
+  if (typeof Buffer !== 'undefined') {
+    return new Uint8Array(Buffer.from(base64, 'base64'));
+  }
+  // Browser fallback
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}

package/src/index.d.ts

@@ -0,0 +1,60 @@
+export interface SyncVaultOptions {
+  appToken: string;
+  serverUrl?: string;
+  redirectUri?: string;
+}
+
+export interface User {
+  id: string;
+  username: string;
+  createdAt?: string;
+}
+
+export interface FileInfo {
+  path: string;
+  updatedAt: string;
+}
+
+export interface PutResponse {
+  path: string;
+  updatedAt: string;
+}
+
+export interface DeleteResponse {
+  deleted: boolean;
+  path: string;
+}
+
+export type Metadata = Record<string, unknown>;
+
+export declare class SyncVault {
+  constructor(options: SyncVaultOptions);
+  
+  // OAuth flow
+  getAuthUrl(state?: string): string;
+  exchangeCode(code: string, password: string): Promise<User>;
+  setAuth(token: string, password: string): void;
+  
+  // Direct auth (requires valid app token)
+  auth(username: string, password: string): Promise<User>;
+  register(username: string, password: string): Promise<User>;
+  
+  // Data operations
+  put<T = unknown>(path: string, data: T): Promise<PutResponse>;
+  get<T = unknown>(path: string): Promise<T>;
+  list(): Promise<FileInfo[]>;
+  delete(path: string): Promise<DeleteResponse>;
+  
+  // Metadata operations (unencrypted server-side data)
+  getMetadata<T extends Metadata = Metadata>(): Promise<T>;
+  setMetadata<T extends Metadata = Metadata>(metadata: T): Promise<T>;
+  updateMetadata<T extends Metadata = Metadata>(metadata: Partial<T>): Promise<T>;
+  
+  // State
+  isAuthenticated(): boolean;
+  logout(): void;
+  getUser(): Promise<User>;
+}
+
+export declare function encrypt(data: unknown, password: string): Promise<string>;
+export declare function decrypt<T = unknown>(encryptedBase64: string, password: string): Promise<T>;

package/src/index.js

@@ -0,0 +1,249 @@
+import { encrypt, decrypt, prepareAuthPassword } from './crypto.js';
+
+const DEFAULT_SERVER = 'https://api.syncvault.dev';
+
+export class SyncVault {
+  constructor(options = {}) {
+    if (!options.appToken) {
+      throw new Error('appToken is required');
+    }
+
+    this.appToken = options.appToken;
+    this.serverUrl = options.serverUrl || DEFAULT_SERVER;
+    this.redirectUri = options.redirectUri || null;
+    this.token = null;
+    this.password = null;
+  }
+
+  /**
+   * Generate OAuth authorization URL
+   * Redirect users to this URL to start the OAuth flow
+   */
+  getAuthUrl(state = null) {
+    if (!this.redirectUri) {
+      throw new Error('redirectUri is required for OAuth flow');
+    }
+
+    const params = new URLSearchParams({
+      app_token: this.appToken,
+      redirect_uri: this.redirectUri
+    });
+
+    if (state) {
+      params.set('state', state);
+    }
+
+    return `${this.serverUrl}/api/oauth/authorize?${params}`;
+  }
+
+  /**
+   * Exchange authorization code for access token (OAuth flow)
+   * Call this after user is redirected back with the code
+   */
+  async exchangeCode(code, password) {
+    const response = await this._request('/api/oauth/token', {
+      method: 'POST',
+      body: JSON.stringify({
+        code,
+        app_token: this.appToken,
+        redirect_uri: this.redirectUri
+      })
+    });
+
+    this.token = response.access_token;
+    this.password = password;
+
+    return response.user;
+  }
+
+  /**
+   * Authenticate user with SyncVault (direct auth - requires valid app token)
+   */
+  async auth(username, password) {
+    const authPassword = await prepareAuthPassword(password);
+    const response = await this._request('/api/user/auth/login', {
+      method: 'POST',
+      body: JSON.stringify({ username, password: authPassword })
+    });
+
+    this.token = response.token;
+    this.password = password;
+
+    return response.user;
+  }
+
+  /**
+   * Register a new user (direct auth - requires valid app token)
+   */
+  async register(username, password) {
+    const authPassword = await prepareAuthPassword(password);
+    const response = await this._request('/api/user/auth/register', {
+      method: 'POST',
+      body: JSON.stringify({ username, password: authPassword })
+    });
+
+    this.token = response.token;
+    this.password = password;
+
+    return response.user;
+  }
+
+  /**
+   * Set authentication state manually (e.g., from stored session)
+   */
+  setAuth(token, password) {
+    this.token = token;
+    this.password = password;
+  }
+
+  /**
+   * Store encrypted data
+   */
+  async put(path, data) {
+    this._checkAuth();
+
+    const encrypted = await encrypt(data, this.password);
+
+    const response = await this._request('/api/sync/put', {
+      method: 'POST',
+      body: JSON.stringify({ path, data: encrypted })
+    });
+
+    return response;
+  }
+
+  /**
+   * Retrieve and decrypt data
+   */
+  async get(path) {
+    this._checkAuth();
+
+    const response = await this._request(`/api/sync/get?path=${encodeURIComponent(path)}`);
+
+    return decrypt(response.data, this.password);
+  }
+
+  /**
+   * List all files
+   */
+  async list() {
+    this._checkAuth();
+
+    const response = await this._request('/api/sync/list');
+
+    return response.files;
+  }
+
+  /**
+   * Delete a file
+   */
+  async delete(path) {
+    this._checkAuth();
+
+    const response = await this._request('/api/sync/delete', {
+      method: 'POST',
+      body: JSON.stringify({ path })
+    });
+
+    return response;
+  }
+
+  /**
+   * Get app metadata for current user (unencrypted, server-side data)
+   */
+  async getMetadata() {
+    this._checkAuth();
+
+    const response = await this._request('/api/sync/metadata');
+    return response.metadata;
+  }
+
+  /**
+   * Set app metadata for current user (replaces all metadata)
+   */
+  async setMetadata(metadata) {
+    this._checkAuth();
+
+    const response = await this._request('/api/sync/metadata', {
+      method: 'POST',
+      body: JSON.stringify({ metadata })
+    });
+
+    return response.metadata;
+  }
+
+  /**
+   * Update app metadata for current user (merges with existing)
+   */
+  async updateMetadata(metadata) {
+    this._checkAuth();
+
+    const response = await this._request('/api/sync/metadata', {
+      method: 'PATCH',
+      body: JSON.stringify({ metadata })
+    });
+
+    return response.metadata;
+  }
+
+  /**
+   * Check if user is authenticated
+   */
+  isAuthenticated() {
+    return this.token !== null && this.password !== null;
+  }
+
+  /**
+   * Clear authentication state
+   */
+  logout() {
+    this.token = null;
+    this.password = null;
+  }
+
+  /**
+   * Get current user info
+   */
+  async getUser() {
+    this._checkAuth();
+
+    return this._request('/api/user/auth/me');
+  }
+
+  _checkAuth() {
+    if (!this.token || !this.password) {
+      throw new Error('Not authenticated. Call auth() or register() first.');
+    }
+  }
+
+  async _request(path, options = {}) {
+    const url = `${this.serverUrl}${path}`;
+
+    const headers = {
+      'Content-Type': 'application/json',
+      'X-App-Token': this.appToken
+    };
+
+    if (this.token) {
+      headers['Authorization'] = `Bearer ${this.token}`;
+    }
+
+    const response = await fetch(url, {
+      ...options,
+      headers: {
+        ...headers,
+        ...options.headers
+      }
+    });
+
+    const data = await response.json();
+
+    if (!response.ok) {
+      throw new Error(data.error || 'Request failed');
+    }
+
+    return data;
+  }
+}
+
+export { encrypt, decrypt } from './crypto.js';