@ursalock/client 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -554,4 +554,172 @@ declare function useCredential(client: VaultClient): ZKCredential | null;
  */
 declare function usePasskeySupport(client: VaultClient): boolean;
 
-export { type AuthProvider, type AuthResult, type AuthState, EmailAuth, type EmailAuthOptions, type EmailCredentials, type EmailSignInOptions, type EmailSignUpOptions, FetchHttpClient, type IAuthProvider, type IHttpClient, PasskeyAuth, type PasskeyAuthOptions, type PasskeySignUpOptions, type Token, TokenManager, type TokenManagerOptions, type User, VaultClient, type VaultClientOptions, type ZKAuthResult, useAuth, useCredential, usePasskeySupport, useSignIn, useSignOut, useSignUp, useUser };
+/**
+ * Document types for UrsaLock v2
+ * E2E encrypted document storage
+ */
+/** A decrypted document with typed content */
+interface Document<T> {
+    uid: string;
+    collection: string;
+    content: T;
+    version: number;
+    createdAt: number;
+    updatedAt: number;
+    deletedAt?: number;
+}
+/** Server response shape (encrypted) */
+interface DocumentResponse {
+    uid: string;
+    collection: string;
+    data: string;
+    hmac: string | null;
+    version: number;
+    createdAt: number;
+    updatedAt: number;
+    deletedAt: number | null;
+}
+/** Options for listing documents */
+interface ListOptions {
+    collection?: string;
+    since?: number;
+    includeDeleted?: boolean;
+    limit?: number;
+    offset?: number;
+}
+/** Sync result */
+interface SyncResult<T> {
+    documents: Document<T>[];
+    syncedAt: number;
+}
+
+/**
+ * Collection - Typed E2E encrypted document storage
+ *
+ * Encrypts documents client-side using AES-GCM and optionally HMAC-SHA256
+ * for integrity verification in transit/storage.
+ */
+
+/**
+ * Collection provides typed, encrypted document storage
+ *
+ * All documents are encrypted client-side before being sent to the server.
+ * The server never sees plaintext content, only encrypted blobs.
+ */
+declare class Collection<T> {
+    private serverUrl;
+    private vaultUid;
+    private collectionName;
+    private encryptionKey;
+    private hmacKey;
+    private getAuthHeader;
+    private httpClient?;
+    constructor(serverUrl: string, vaultUid: string, collectionName: string, encryptionKey: Uint8Array, hmacKey: Uint8Array | undefined, getAuthHeader: () => Record<string, string>, httpClient?: IHttpClient | undefined);
+    /**
+     * Create a new document
+     * @param content Document content (will be encrypted)
+     * @returns Created document with server-generated uid
+     */
+    create(content: T): Promise<Document<T>>;
+    /**
+     * Get a document by uid
+     * @param uid Document uid
+     * @returns Decrypted document
+     */
+    get(uid: string): Promise<Document<T>>;
+    /**
+     * List documents in this collection
+     * @param options Filter options
+     * @returns Array of decrypted documents
+     */
+    list(options?: Omit<ListOptions, 'collection'>): Promise<Document<T>[]>;
+    /**
+     * Update a document
+     * @param uid Document uid
+     * @param content Partial content to merge (or full replacement)
+     * @returns Updated document
+     */
+    update(uid: string, content: Partial<T>): Promise<Document<T>>;
+    /**
+     * Delete a document (soft delete)
+     * @param uid Document uid
+     */
+    delete(uid: string): Promise<void>;
+    /**
+     * Sync documents since a timestamp
+     * @param since Timestamp (ms) to sync from
+     * @returns Sync result with documents and sync timestamp
+     */
+    sync(since?: number): Promise<SyncResult<T>>;
+    /**
+     * Encrypt content to base64 string with optional HMAC
+     */
+    private encryptContent;
+    /**
+     * Decrypt a server response document
+     */
+    private decryptDocument;
+    /**
+     * Make authenticated HTTP request
+     */
+    private request;
+    /**
+     * Convert Uint8Array to base64 string
+     */
+    private bytesToBase64;
+    /**
+     * Convert base64 string to Uint8Array
+     */
+    private base64ToBytes;
+}
+
+/**
+ * DocumentClient - Factory for creating typed Collections
+ *
+ * Provides a simple interface to create Collection instances
+ * with shared configuration (server URL, vault UID, encryption keys).
+ */
+
+interface DocumentClientOptions {
+    /** Server URL */
+    serverUrl: string;
+    /** Vault UID */
+    vaultUid: string;
+    /** 256-bit encryption key */
+    encryptionKey: Uint8Array;
+    /** Optional HMAC key for integrity verification */
+    hmacKey?: Uint8Array;
+    /** Function to get current auth header */
+    getAuthHeader: () => Record<string, string>;
+    /** Optional HTTP client (defaults to fetch) */
+    httpClient?: IHttpClient;
+}
+/**
+ * DocumentClient creates typed Collections with shared configuration
+ *
+ * @example
+ * ```ts
+ * const client = new DocumentClient({
+ *   serverUrl: 'https://api.ursalock.com',
+ *   vaultUid: 'vault-123',
+ *   encryptionKey: key,
+ *   hmacKey: hmacKey,
+ *   getAuthHeader: () => ({ Authorization: `Bearer ${token}` }),
+ * });
+ *
+ * const notes = client.collection<Note>('notes');
+ * await notes.create({ title: 'Secret note', content: 'Hello' });
+ * ```
+ */
+declare class DocumentClient {
+    private options;
+    constructor(options: DocumentClientOptions);
+    /**
+     * Get a typed collection
+     * @param name Collection name
+     * @returns Collection instance
+     */
+    collection<T>(name: string): Collection<T>;
+}
+
+export { type AuthProvider, type AuthResult, type AuthState, Collection, type Document, DocumentClient, type DocumentClientOptions, type DocumentResponse, EmailAuth, type EmailAuthOptions, type EmailCredentials, type EmailSignInOptions, type EmailSignUpOptions, FetchHttpClient, type IAuthProvider, type IHttpClient, type ListOptions, PasskeyAuth, type PasskeyAuthOptions, type PasskeySignUpOptions, type SyncResult, type Token, TokenManager, type TokenManagerOptions, type User, VaultClient, type VaultClientOptions, type ZKAuthResult, useAuth, useCredential, usePasskeySupport, useSignIn, useSignOut, useSignUp, useUser };

package/dist/index.js

@@ -802,4 +802,375 @@ function usePasskeySupport(client) {
   return client.supportsPasskey();
 }
 
-export { EmailAuth, FetchHttpClient, PasskeyAuth, TokenManager, VaultClient, useAuth, useCredential, usePasskeySupport, useSignIn, useSignOut, useSignUp, useUser };
+// ../crypto/dist/index.js
+function randomBytes(length) {
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  return bytes;
+}
+function concatBytes(...arrays) {
+  const totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const arr of arrays) {
+    result.set(arr, offset);
+    offset += arr.length;
+  }
+  return result;
+}
+var IV_LENGTH = 12;
+var WebCryptoProvider = class {
+  async encrypt(plaintext, key) {
+    if (key.length !== 32) {
+      throw new Error(`Invalid key length: expected 32 bytes, got ${key.length}`);
+    }
+    const actualIv = randomBytes(IV_LENGTH);
+    const cryptoKey = await crypto.subtle.importKey(
+      "raw",
+      key.buffer.slice(key.byteOffset, key.byteOffset + key.byteLength),
+      { name: "AES-GCM" },
+      false,
+      ["encrypt"]
+    );
+    const ciphertext = new Uint8Array(
+      await crypto.subtle.encrypt(
+        { name: "AES-GCM", iv: actualIv },
+        cryptoKey,
+        plaintext.buffer.slice(plaintext.byteOffset, plaintext.byteOffset + plaintext.byteLength)
+      )
+    );
+    const combined = concatBytes(actualIv, ciphertext);
+    return { iv: actualIv, ciphertext, combined };
+  }
+  async decrypt(encrypted, key) {
+    if (key.length !== 32) {
+      throw new Error(`Invalid key length: expected 32 bytes, got ${key.length}`);
+    }
+    let iv;
+    let ciphertext;
+    if (encrypted instanceof Uint8Array) {
+      if (encrypted.length < IV_LENGTH + 16) {
+        throw new Error("Invalid encrypted data: too short");
+      }
+      iv = encrypted.slice(0, IV_LENGTH);
+      ciphertext = encrypted.slice(IV_LENGTH);
+    } else {
+      iv = encrypted.iv;
+      ciphertext = encrypted.ciphertext;
+    }
+    const cryptoKey = await crypto.subtle.importKey(
+      "raw",
+      key.buffer.slice(key.byteOffset, key.byteOffset + key.byteLength),
+      { name: "AES-GCM" },
+      false,
+      ["decrypt"]
+    );
+    try {
+      const plaintext = await crypto.subtle.decrypt(
+        { name: "AES-GCM", iv },
+        cryptoKey,
+        ciphertext.buffer.slice(ciphertext.byteOffset, ciphertext.byteOffset + ciphertext.byteLength)
+      );
+      return new Uint8Array(plaintext);
+    } catch (error) {
+      throw new Error("Decryption failed: invalid key or corrupted data");
+    }
+  }
+};
+var defaultProvider = new WebCryptoProvider();
+async function encrypt(plaintext, key, provider = defaultProvider) {
+  return provider.encrypt(plaintext, key);
+}
+async function decrypt(encrypted, key, provider = defaultProvider) {
+  return provider.decrypt(encrypted, key);
+}
+async function computeHmac(data, key) {
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    key,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const signature = new Uint8Array(
+    await crypto.subtle.sign("HMAC", cryptoKey, data)
+  );
+  return bytesToHex(signature);
+}
+async function verifyHmac(data, key, expectedHmac) {
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    key,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"]
+  );
+  const expectedBytes = hexToBytes(expectedHmac);
+  return crypto.subtle.verify(
+    "HMAC",
+    cryptoKey,
+    expectedBytes,
+    data
+  );
+}
+function bytesToHex(bytes) {
+  let hex = "";
+  for (let i = 0; i < bytes.length; i++) {
+    hex += bytes[i].toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+function hexToBytes(hex) {
+  const len = hex.length >>> 1;
+  const bytes = new Uint8Array(len);
+  for (let i = 0; i < len; i++) {
+    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+// src/collection.ts
+var Collection = class {
+  constructor(serverUrl, vaultUid, collectionName, encryptionKey, hmacKey, getAuthHeader, httpClient) {
+    this.serverUrl = serverUrl;
+    this.vaultUid = vaultUid;
+    this.collectionName = collectionName;
+    this.encryptionKey = encryptionKey;
+    this.hmacKey = hmacKey;
+    this.getAuthHeader = getAuthHeader;
+    this.httpClient = httpClient;
+  }
+  /**
+   * Create a new document
+   * @param content Document content (will be encrypted)
+   * @returns Created document with server-generated uid
+   */
+  async create(content) {
+    const { data, hmac } = await this.encryptContent(content);
+    const body = {
+      collection: this.collectionName,
+      data
+    };
+    if (hmac) {
+      body.hmac = hmac;
+    }
+    const response = await this.request(`/vault/${this.vaultUid}/documents`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    return this.decryptDocument(response);
+  }
+  /**
+   * Get a document by uid
+   * @param uid Document uid
+   * @returns Decrypted document
+   */
+  async get(uid) {
+    const response = await this.request(`/vault/${this.vaultUid}/documents/${uid}`);
+    return this.decryptDocument(response);
+  }
+  /**
+   * List documents in this collection
+   * @param options Filter options
+   * @returns Array of decrypted documents
+   */
+  async list(options) {
+    const params = new URLSearchParams();
+    params.set("collection", this.collectionName);
+    if (options?.since !== void 0) {
+      params.set("since", String(options.since));
+    }
+    if (options?.includeDeleted !== void 0) {
+      params.set("includeDeleted", String(options.includeDeleted));
+    }
+    if (options?.limit !== void 0) {
+      params.set("limit", String(options.limit));
+    }
+    if (options?.offset !== void 0) {
+      params.set("offset", String(options.offset));
+    }
+    const response = await this.request(
+      `/vault/${this.vaultUid}/documents?${params}`
+    );
+    return Promise.all(response.documents.map((doc) => this.decryptDocument(doc)));
+  }
+  /**
+   * Update a document
+   * @param uid Document uid
+   * @param content Partial content to merge (or full replacement)
+   * @returns Updated document
+   */
+  async update(uid, content) {
+    const current = await this.get(uid);
+    const merged = { ...current.content, ...content };
+    const { data, hmac } = await this.encryptContent(merged);
+    const body = {
+      data,
+      version: current.version
+    };
+    if (hmac) {
+      body.hmac = hmac;
+    }
+    const response = await this.request(`/vault/${this.vaultUid}/documents/${uid}`, {
+      method: "PUT",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    return this.decryptDocument(response);
+  }
+  /**
+   * Delete a document (soft delete)
+   * @param uid Document uid
+   */
+  async delete(uid) {
+    await this.request(`/vault/${this.vaultUid}/documents/${uid}`, {
+      method: "DELETE"
+    });
+  }
+  /**
+   * Sync documents since a timestamp
+   * @param since Timestamp (ms) to sync from
+   * @returns Sync result with documents and sync timestamp
+   */
+  async sync(since) {
+    const params = new URLSearchParams();
+    if (since !== void 0) {
+      params.set("since", String(since));
+    }
+    const response = await this.request(
+      `/vault/${this.vaultUid}/documents/sync?${params}`
+    );
+    const documents = await Promise.all(
+      response.documents.map((doc) => this.decryptDocument(doc))
+    );
+    return {
+      documents,
+      syncedAt: response.syncedAt
+    };
+  }
+  // ==================
+  // Private Helpers
+  // ==================
+  /**
+   * Encrypt content to base64 string with optional HMAC
+   */
+  async encryptContent(content) {
+    const json = JSON.stringify(content);
+    const plaintext = new TextEncoder().encode(json);
+    const encrypted = await encrypt(plaintext, this.encryptionKey);
+    const data = this.bytesToBase64(encrypted.combined);
+    let hmac;
+    if (this.hmacKey) {
+      const dataBytes = new TextEncoder().encode(data);
+      hmac = await computeHmac(dataBytes, this.hmacKey);
+    }
+    return { data, hmac };
+  }
+  /**
+   * Decrypt a server response document
+   */
+  async decryptDocument(response) {
+    if (this.hmacKey && response.hmac) {
+      const dataBytes = new TextEncoder().encode(response.data);
+      const valid = await verifyHmac(dataBytes, this.hmacKey, response.hmac);
+      if (!valid) {
+        throw new Error("HMAC verification failed: invalid signature");
+      }
+    }
+    const encryptedBytes = this.base64ToBytes(response.data);
+    const plaintext = await decrypt(encryptedBytes, this.encryptionKey);
+    const json = new TextDecoder().decode(plaintext);
+    const content = JSON.parse(json);
+    return {
+      uid: response.uid,
+      collection: response.collection,
+      content,
+      version: response.version,
+      createdAt: response.createdAt,
+      updatedAt: response.updatedAt,
+      deletedAt: response.deletedAt ?? void 0
+    };
+  }
+  /**
+   * Make authenticated HTTP request
+   */
+  async request(path, options = {}) {
+    const url = path.startsWith("http") ? path : `${this.serverUrl}${path}`;
+    const headers = {
+      ...this.getAuthHeader(),
+      ...options.headers
+    };
+    const fetchFn = this.httpClient ? (url2, opts) => this.httpClient.fetch(url2, opts) : fetch;
+    const response = await fetchFn(url, { ...options, headers });
+    if (!response.ok) {
+      let errorMessage;
+      try {
+        const errorData = await response.json();
+        errorMessage = errorData.message || errorData.error || response.statusText;
+      } catch {
+        errorMessage = response.statusText;
+      }
+      if (response.status === 404) {
+        throw new Error(`Document not found: ${errorMessage}`);
+      } else if (response.status === 409) {
+        throw new Error(`Conflict: ${errorMessage}`);
+      } else if (response.status === 401) {
+        throw new Error(`Unauthorized: ${errorMessage}`);
+      } else {
+        throw new Error(`HTTP ${response.status}: ${errorMessage}`);
+      }
+    }
+    return response.json();
+  }
+  /**
+   * Convert Uint8Array to base64 string
+   */
+  bytesToBase64(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+  }
+  /**
+   * Convert base64 string to Uint8Array
+   */
+  base64ToBytes(base64) {
+    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;
+  }
+};
+
+// src/document-client.ts
+var DocumentClient = class {
+  constructor(options) {
+    this.options = options;
+  }
+  /**
+   * Get a typed collection
+   * @param name Collection name
+   * @returns Collection instance
+   */
+  collection(name) {
+    return new Collection(
+      this.options.serverUrl,
+      this.options.vaultUid,
+      name,
+      this.options.encryptionKey,
+      this.options.hmacKey,
+      this.options.getAuthHeader,
+      this.options.httpClient
+    );
+  }
+};
+
+export { Collection, DocumentClient, EmailAuth, FetchHttpClient, PasskeyAuth, TokenManager, VaultClient, useAuth, useCredential, usePasskeySupport, useSignIn, useSignOut, useSignUp, useUser };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ursalock/client",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Auth and API client for ursalock with E2EE passkey encryption",
   "type": "module",
   "main": "./dist/index.js",