wolfronix-sdk 2.4.3 → 2.4.4

package/dist/index.js

@@ -307,6 +307,641 @@ var ValidationError = class extends WolfronixError {
     this.name = "ValidationError";
   }
 };
+var RECOVERY_WORDS = [
+  "able",
+  "about",
+  "absorb",
+  "access",
+  "acid",
+  "across",
+  "action",
+  "adapt",
+  "admit",
+  "adult",
+  "agent",
+  "agree",
+  "ahead",
+  "air",
+  "alert",
+  "alpha",
+  "anchor",
+  "angle",
+  "apple",
+  "arch",
+  "arena",
+  "argue",
+  "armed",
+  "arrow",
+  "asset",
+  "atlas",
+  "attack",
+  "audio",
+  "august",
+  "auto",
+  "avoid",
+  "awake",
+  "aware",
+  "badge",
+  "balance",
+  "banana",
+  "basic",
+  "beach",
+  "beauty",
+  "before",
+  "begin",
+  "below",
+  "benefit",
+  "best",
+  "beyond",
+  "bicycle",
+  "bird",
+  "black",
+  "bless",
+  "board",
+  "bold",
+  "bonus",
+  "border",
+  "borrow",
+  "bottle",
+  "bottom",
+  "brain",
+  "brand",
+  "brave",
+  "breeze",
+  "brick",
+  "brief",
+  "bring",
+  "brother",
+  "budget",
+  "build",
+  "camera",
+  "camp",
+  "canal",
+  "carbon",
+  "carry",
+  "casual",
+  "center",
+  "chain",
+  "change",
+  "charge",
+  "chase",
+  "cheap",
+  "check",
+  "chief",
+  "choice",
+  "circle",
+  "city",
+  "claim",
+  "class",
+  "clean",
+  "clear",
+  "client",
+  "clock",
+  "cloud",
+  "coach",
+  "coast",
+  "color",
+  "column",
+  "combo",
+  "common",
+  "concept",
+  "confirm",
+  "connect",
+  "copy",
+  "core",
+  "corner",
+  "correct",
+  "cost",
+  "cover",
+  "craft",
+  "create",
+  "credit",
+  "cross",
+  "crowd",
+  "crystal",
+  "current",
+  "custom",
+  "cycle",
+  "daily",
+  "danger",
+  "data",
+  "dealer",
+  "debate",
+  "decide",
+  "deep",
+  "define",
+  "degree",
+  "delay",
+  "demand",
+  "denial",
+  "design",
+  "detail",
+  "device",
+  "dialog",
+  "digital",
+  "direct",
+  "doctor",
+  "domain",
+  "double",
+  "draft",
+  "dragon",
+  "drama",
+  "dream",
+  "drive",
+  "early",
+  "earth",
+  "easy",
+  "echo",
+  "edge",
+  "edit",
+  "effect",
+  "either",
+  "elder",
+  "element",
+  "elite",
+  "email",
+  "energy",
+  "engine",
+  "enough",
+  "enter",
+  "equal",
+  "error",
+  "escape",
+  "estate",
+  "event",
+  "exact",
+  "example",
+  "exchange",
+  "exist",
+  "expand",
+  "expect",
+  "expert",
+  "extra",
+  "fabric",
+  "factor",
+  "family",
+  "famous",
+  "feature",
+  "fence",
+  "field",
+  "figure",
+  "filter",
+  "final",
+  "finger",
+  "finish",
+  "first",
+  "focus",
+  "follow",
+  "force",
+  "forest",
+  "format",
+  "forward",
+  "frame",
+  "fresh",
+  "front",
+  "future",
+  "gallery",
+  "general",
+  "giant",
+  "global",
+  "gold",
+  "good",
+  "grace",
+  "grant",
+  "green",
+  "group",
+  "guard",
+  "habit",
+  "half",
+  "hammer",
+  "handle",
+  "happy",
+  "harbor",
+  "health",
+  "height",
+  "hidden",
+  "history",
+  "honest",
+  "host",
+  "hotel",
+  "human",
+  "hybrid",
+  "idea",
+  "image",
+  "impact",
+  "income",
+  "index",
+  "input",
+  "inside",
+  "insight",
+  "island",
+  "item",
+  "jacket",
+  "jazz",
+  "join",
+  "jungle",
+  "keep",
+  "keyboard",
+  "kind",
+  "king",
+  "kitchen",
+  "label",
+  "ladder",
+  "language",
+  "large",
+  "laser",
+  "later",
+  "launch",
+  "layer",
+  "leader",
+  "learn",
+  "level",
+  "light",
+  "limit",
+  "linear",
+  "link",
+  "listen",
+  "local",
+  "logic",
+  "lucky",
+  "machine",
+  "magic",
+  "major",
+  "manage",
+  "manual",
+  "market",
+  "master",
+  "matrix",
+  "matter",
+  "member",
+  "memory",
+  "message",
+  "method",
+  "middle",
+  "million",
+  "mind",
+  "mirror",
+  "mobile",
+  "model",
+  "module",
+  "moment",
+  "monitor",
+  "moral",
+  "motion",
+  "mountain",
+  "music",
+  "native",
+  "nature",
+  "network",
+  "never",
+  "normal",
+  "notice",
+  "number",
+  "object",
+  "ocean",
+  "offer",
+  "office",
+  "online",
+  "option",
+  "orange",
+  "order",
+  "origin",
+  "output",
+  "owner",
+  "packet",
+  "panel",
+  "paper",
+  "parent",
+  "partner",
+  "pattern",
+  "pause",
+  "payment",
+  "people",
+  "perfect",
+  "phone",
+  "phrase",
+  "pilot",
+  "pixel",
+  "planet",
+  "platform",
+  "please",
+  "plus",
+  "policy",
+  "portal",
+  "position",
+  "power",
+  "predict",
+  "premium",
+  "prepare",
+  "present",
+  "pretty",
+  "price",
+  "prime",
+  "private",
+  "process",
+  "profile",
+  "project",
+  "protect",
+  "public",
+  "quality",
+  "quick",
+  "quiet",
+  "radio",
+  "random",
+  "rapid",
+  "rate",
+  "ready",
+  "reason",
+  "record",
+  "recover",
+  "region",
+  "release",
+  "remote",
+  "repair",
+  "repeat",
+  "report",
+  "request",
+  "result",
+  "return",
+  "review",
+  "right",
+  "rival",
+  "river",
+  "robot",
+  "route",
+  "royal",
+  "safe",
+  "sample",
+  "scale",
+  "scene",
+  "school",
+  "science",
+  "screen",
+  "search",
+  "secure",
+  "select",
+  "seller",
+  "senior",
+  "series",
+  "server",
+  "session",
+  "shadow",
+  "shape",
+  "share",
+  "shield",
+  "shift",
+  "ship",
+  "short",
+  "signal",
+  "silver",
+  "simple",
+  "single",
+  "skill",
+  "smart",
+  "smooth",
+  "social",
+  "solid",
+  "source",
+  "space",
+  "special",
+  "speed",
+  "spirit",
+  "split",
+  "square",
+  "stable",
+  "stack",
+  "stage",
+  "start",
+  "state",
+  "status",
+  "steel",
+  "step",
+  "stock",
+  "store",
+  "storm",
+  "story",
+  "stream",
+  "strike",
+  "strong",
+  "studio",
+  "style",
+  "subject",
+  "submit",
+  "success",
+  "sudden",
+  "sugar",
+  "supply",
+  "support",
+  "surface",
+  "switch",
+  "system",
+  "table",
+  "target",
+  "task",
+  "team",
+  "temple",
+  "tempo",
+  "tenant",
+  "term",
+  "test",
+  "theme",
+  "theory",
+  "thing",
+  "thread",
+  "time",
+  "title",
+  "token",
+  "tool",
+  "topic",
+  "total",
+  "tower",
+  "track",
+  "trade",
+  "traffic",
+  "train",
+  "travel",
+  "trust",
+  "tunnel",
+  "type",
+  "unable",
+  "update",
+  "upload",
+  "usage",
+  "useful",
+  "user",
+  "valid",
+  "value",
+  "vector",
+  "verify",
+  "version",
+  "video",
+  "view",
+  "virtual",
+  "vision",
+  "voice",
+  "volume",
+  "wait",
+  "wallet",
+  "watch",
+  "water",
+  "wealth",
+  "web",
+  "welcome",
+  "window",
+  "winner",
+  "wire",
+  "wise",
+  "wonder",
+  "work",
+  "world",
+  "write",
+  "xenon",
+  "year",
+  "yield",
+  "zone"
+];
+function randomInt(maxExclusive) {
+  const values = new Uint32Array(1);
+  globalThis.crypto.getRandomValues(values);
+  return values[0] % maxExclusive;
+}
+function generateRecoveryWords(count = 24) {
+  const words = [];
+  for (let i = 0; i < count; i++) {
+    words.push(RECOVERY_WORDS[randomInt(RECOVERY_WORDS.length)]);
+  }
+  return words;
+}
+var PFS_PROTOCOL = "wfx-dr-v1";
+var ZERO_32 = new Uint8Array(32);
+function toBase64(buf) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(buf).toString("base64");
+  }
+  const bytes = new Uint8Array(buf);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary);
+}
+function fromBase64(b64) {
+  if (typeof Buffer !== "undefined") {
+    const buf = Buffer.from(b64, "base64");
+    return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+  }
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes.buffer;
+}
+function normalizeJwk(jwk) {
+  return JSON.stringify({
+    kty: jwk.kty || "",
+    crv: jwk.crv || "",
+    x: jwk.x || "",
+    y: jwk.y || ""
+  });
+}
+function ratchetKeyId(jwk, n) {
+  const j = normalizeJwk(jwk);
+  if (typeof Buffer !== "undefined") {
+    return `${Buffer.from(j).toString("base64")}:${n}`;
+  }
+  return `${btoa(j)}:${n}`;
+}
+async function generatePfsRatchetKeyPair() {
+  return globalThis.crypto.subtle.generateKey(
+    { name: "ECDH", namedCurve: "P-256" },
+    true,
+    ["deriveBits"]
+  );
+}
+async function exportPublicJwk(key) {
+  return globalThis.crypto.subtle.exportKey("jwk", key);
+}
+async function exportPrivateJwk(key) {
+  return globalThis.crypto.subtle.exportKey("jwk", key);
+}
+async function importPfsPublicJwk(jwk) {
+  return globalThis.crypto.subtle.importKey(
+    "jwk",
+    jwk,
+    { name: "ECDH", namedCurve: "P-256" },
+    false,
+    []
+  );
+}
+async function importPfsPrivateJwk(jwk) {
+  return globalThis.crypto.subtle.importKey(
+    "jwk",
+    jwk,
+    { name: "ECDH", namedCurve: "P-256" },
+    false,
+    ["deriveBits"]
+  );
+}
+async function deriveEcdhSecret(privateJwk, publicJwk) {
+  const priv = await importPfsPrivateJwk(privateJwk);
+  const pub = await importPfsPublicJwk(publicJwk);
+  return globalThis.crypto.subtle.deriveBits({ name: "ECDH", public: pub }, priv, 256);
+}
+async function hkdfExpand(ikm, salt, info, outBits) {
+  const ikmKey = await globalThis.crypto.subtle.importKey("raw", ikm, "HKDF", false, ["deriveBits"]);
+  return globalThis.crypto.subtle.deriveBits(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt,
+      info: new TextEncoder().encode(info)
+    },
+    ikmKey,
+    outBits
+  );
+}
+async function hmacSha256(keyRaw, input) {
+  const key = await globalThis.crypto.subtle.importKey(
+    "raw",
+    keyRaw,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  return globalThis.crypto.subtle.sign("HMAC", key, new TextEncoder().encode(input));
+}
+async function deriveRootAndChains(rootKeyB64, dhSecret) {
+  const rootKeyRaw = rootKeyB64 ? fromBase64(rootKeyB64) : ZERO_32.buffer;
+  const mixed = await hkdfExpand(dhSecret, rootKeyRaw, `${PFS_PROTOCOL}:root`, 96 * 8);
+  const bytes = new Uint8Array(mixed);
+  return {
+    rootKey: toBase64(bytes.slice(0, 32).buffer),
+    chainA: toBase64(bytes.slice(32, 64).buffer),
+    chainB: toBase64(bytes.slice(64, 96).buffer)
+  };
+}
+async function deriveMessageKey(chainKeyB64, n) {
+  return hmacSha256(fromBase64(chainKeyB64), `msg:${n}`);
+}
+async function deriveNextChainKey(chainKeyB64) {
+  const next = await hmacSha256(fromBase64(chainKeyB64), "chain");
+  return toBase64(next);
+}
+async function encryptWithRawKey(rawKey, plaintext) {
+  const key = await globalThis.crypto.subtle.importKey("raw", rawKey, { name: "AES-GCM" }, false, ["encrypt"]);
+  const iv = globalThis.crypto.getRandomValues(new Uint8Array(12));
+  const out = await globalThis.crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, new TextEncoder().encode(plaintext));
+  return {
+    ciphertext: toBase64(out),
+    iv: toBase64(iv.buffer)
+  };
+}
+async function decryptWithRawKey(rawKey, ciphertextB64, ivB64) {
+  const key = await globalThis.crypto.subtle.importKey("raw", rawKey, { name: "AES-GCM" }, false, ["decrypt"]);
+  const out = await globalThis.crypto.subtle.decrypt(
+    { name: "AES-GCM", iv: new Uint8Array(fromBase64(ivB64)) },
+    key,
+    fromBase64(ciphertextB64)
+  );
+  return new TextDecoder().decode(out);
+}
 var Wolfronix = class {
   /**
    * Create a new Wolfronix client
@@ -327,6 +962,9 @@ var Wolfronix = class {
     this.publicKey = null;
     this.privateKey = null;
     this.publicKeyPEM = null;
+    this.pfsIdentityPrivateJwk = null;
+    this.pfsIdentityPublicJwk = null;
+    this.pfsSessions = /* @__PURE__ */ new Map();
     if (typeof config === "string") {
       this.config = {
         baseUrl: config,
@@ -446,6 +1084,59 @@ var Wolfronix = class {
       throw new AuthenticationError("Not authenticated. Call login() or register() first.");
     }
   }
+  toBlob(file) {
+    if (file instanceof File || file instanceof Blob) {
+      return file;
+    }
+    if (file instanceof ArrayBuffer) {
+      return new Blob([new Uint8Array(file)]);
+    }
+    if (file instanceof Uint8Array) {
+      const arrayBuffer = file.buffer.slice(file.byteOffset, file.byteOffset + file.byteLength);
+      return new Blob([arrayBuffer]);
+    }
+    throw new ValidationError("Invalid file type. Expected File, Blob, Buffer, or ArrayBuffer");
+  }
+  async ensurePfsIdentity() {
+    if (this.pfsIdentityPrivateJwk && this.pfsIdentityPublicJwk) {
+      return;
+    }
+    const kp = await generatePfsRatchetKeyPair();
+    this.pfsIdentityPrivateJwk = await exportPrivateJwk(kp.privateKey);
+    this.pfsIdentityPublicJwk = await exportPublicJwk(kp.publicKey);
+  }
+  getPfsSession(sessionId) {
+    const session = this.pfsSessions.get(sessionId);
+    if (!session) {
+      throw new ValidationError(`PFS session not found: ${sessionId}`);
+    }
+    return session;
+  }
+  async ratchetForSend(session) {
+    const nextRatchet = await generatePfsRatchetKeyPair();
+    const nextPriv = await exportPrivateJwk(nextRatchet.privateKey);
+    const nextPub = await exportPublicJwk(nextRatchet.publicKey);
+    const dh = await deriveEcdhSecret(nextPriv, session.their_ratchet_public_jwk);
+    const mixed = await deriveRootAndChains(session.root_key, dh);
+    session.root_key = mixed.rootKey;
+    session.send_chain_key = mixed.chainA;
+    session.recv_chain_key = mixed.chainB;
+    session.prev_send_count = session.send_count;
+    session.send_count = 0;
+    session.my_ratchet_private_jwk = nextPriv;
+    session.my_ratchet_public_jwk = nextPub;
+    session.updated_at = Date.now();
+  }
+  async ratchetForReceive(session, theirRatchetPub) {
+    const dh = await deriveEcdhSecret(session.my_ratchet_private_jwk, theirRatchetPub);
+    const mixed = await deriveRootAndChains(session.root_key, dh);
+    session.root_key = mixed.rootKey;
+    session.recv_chain_key = mixed.chainA;
+    session.send_chain_key = mixed.chainB;
+    session.recv_count = 0;
+    session.their_ratchet_public_jwk = theirRatchetPub;
+    session.updated_at = Date.now();
+  }
   // ==========================================================================
   // Authentication Methods
   // ==========================================================================
@@ -457,13 +1148,23 @@ var Wolfronix = class {
    * const { user_id, token } = await wfx.register('user@example.com', 'password123');
    * ```
    */
-  async register(email, password) {
+  async register(email, password, options = {}) {
     if (!email || !password) {
       throw new ValidationError("Email and password are required");
     }
     const keyPair = await generateKeyPair();
     const publicKeyPEM = await exportKeyToPEM(keyPair.publicKey, "public");
     const { encryptedKey, salt } = await wrapPrivateKey(keyPair.privateKey, password);
+    const enableRecovery = options.enableRecovery !== false;
+    const recoveryWords = enableRecovery ? options.recoveryPhrase ? options.recoveryPhrase.trim().split(/\s+/).filter(Boolean) : generateRecoveryWords(24) : [];
+    const recoveryPhrase = recoveryWords.join(" ");
+    let recoveryEncryptedPrivateKey = "";
+    let recoverySalt = "";
+    if (enableRecovery && recoveryPhrase) {
+      const recoveryWrap = await wrapPrivateKey(keyPair.privateKey, recoveryPhrase);
+      recoveryEncryptedPrivateKey = recoveryWrap.encryptedKey;
+      recoverySalt = recoveryWrap.salt;
+    }
     const response = await this.request("POST", "/api/v1/keys/register", {
       body: {
         client_id: this.config.clientId,
@@ -471,18 +1172,30 @@ var Wolfronix = class {
         // Using email as user_id for simplicity
         public_key_pem: publicKeyPEM,
         encrypted_private_key: encryptedKey,
-        salt
+        salt,
+        recovery_encrypted_private_key: recoveryEncryptedPrivateKey,
+        recovery_salt: recoverySalt
       },
       includeAuth: false
     });
-    if (response.success) {
+    if (response.status === "success" || response.success) {
       this.userId = email;
       this.publicKey = keyPair.publicKey;
       this.privateKey = keyPair.privateKey;
       this.publicKeyPEM = publicKeyPEM;
       this.token = "zk-session";
     }
-    return response;
+    const out = {
+      success: response.status === "success" || response.success === true,
+      user_id: response.user_id || email,
+      token: this.token || "zk-session",
+      message: response.message || "Keys registered successfully"
+    };
+    if (enableRecovery && recoveryPhrase) {
+      out.recoveryPhrase = recoveryPhrase;
+      out.recoveryWords = recoveryWords;
+    }
+    return out;
   }
   /**
    * Login with existing credentials
@@ -526,6 +1239,69 @@ var Wolfronix = class {
       throw new AuthenticationError("Invalid password (decryption failed)");
     }
   }
+  /**
+   * Recover account keys using a 24-word recovery phrase and set a new password.
+   * Returns a fresh local auth session if recovery succeeds.
+   */
+  async recoverAccount(email, recoveryPhrase, newPassword) {
+    if (!email || !recoveryPhrase || !newPassword) {
+      throw new ValidationError("email, recoveryPhrase, and newPassword are required");
+    }
+    const response = await this.request("POST", "/api/v1/keys/recover", {
+      body: {
+        client_id: this.config.clientId,
+        user_id: email
+      },
+      includeAuth: false
+    });
+    if (!response.recovery_encrypted_private_key || !response.recovery_salt || !response.public_key_pem) {
+      throw new AuthenticationError("Recovery material not found for this account");
+    }
+    const recoveredPrivateKey = await unwrapPrivateKey(
+      response.recovery_encrypted_private_key,
+      recoveryPhrase,
+      response.recovery_salt
+    );
+    const newPasswordWrap = await wrapPrivateKey(recoveredPrivateKey, newPassword);
+    await this.request("POST", "/api/v1/keys/update-password", {
+      body: {
+        client_id: this.config.clientId,
+        user_id: email,
+        encrypted_private_key: newPasswordWrap.encryptedKey,
+        salt: newPasswordWrap.salt
+      },
+      includeAuth: false
+    });
+    this.privateKey = recoveredPrivateKey;
+    this.publicKeyPEM = response.public_key_pem;
+    this.publicKey = await importKeyFromPEM(response.public_key_pem, "public");
+    this.userId = email;
+    this.token = "zk-session";
+    return {
+      success: true,
+      user_id: email,
+      token: this.token,
+      message: "Account recovered successfully"
+    };
+  }
+  /**
+   * Rotates long-term RSA identity keys and re-wraps with password (+ optional recovery phrase).
+   * Use this periodically to reduce long-term key exposure.
+   */
+  async rotateIdentityKeys(password, recoveryPhrase) {
+    this.ensureAuthenticated();
+    if (!password) {
+      throw new ValidationError("password is required");
+    }
+    if (recoveryPhrase !== void 0 && !recoveryPhrase.trim()) {
+      throw new ValidationError("recoveryPhrase must be non-empty when provided");
+    }
+    throw new WolfronixError(
+      "rotateIdentityKeys is not supported by the current server API. Use recoverAccount() to re-wrap the existing private key with a new password.",
+      "NOT_SUPPORTED",
+      501
+    );
+  }
   /**
    * Set authentication token directly (useful for server-side apps)
    * 
@@ -582,20 +1358,8 @@ var Wolfronix = class {
   async encrypt(file, filename) {
     this.ensureAuthenticated();
     const formData = new FormData();
-    if (file instanceof File) {
-      formData.append("file", file);
-    } else if (file instanceof Blob) {
-      formData.append("file", file, filename || "file");
-    } else if (file instanceof ArrayBuffer) {
-      const blob = new Blob([new Uint8Array(file)]);
-      formData.append("file", blob, filename || "file");
-    } else if (file instanceof Uint8Array) {
-      const arrayBuffer = file.buffer.slice(file.byteOffset, file.byteOffset + file.byteLength);
-      const blob = new Blob([arrayBuffer]);
-      formData.append("file", blob, filename || "file");
-    } else {
-      throw new ValidationError("Invalid file type. Expected File, Blob, Buffer, or ArrayBuffer");
-    }
+    const blob = this.toBlob(file);
+    formData.append("file", blob, filename || (file instanceof File ? file.name : "file"));
     formData.append("user_id", this.userId || "");
     if (!this.publicKeyPEM) {
       throw new Error("Public key not available. Is user logged in?");
@@ -609,6 +1373,65 @@ var Wolfronix = class {
       file_id: String(response.file_id)
     };
   }
+  /**
+   * Resumable large-file encryption upload.
+   * Splits a file into chunks (default 10MB) and uploads each chunk independently.
+   * If upload fails mid-way, pass the returned state as `existingState` to resume.
+   */
+  async encryptResumable(file, options = {}) {
+    this.ensureAuthenticated();
+    const chunkSize = options.chunkSizeBytes || 10 * 1024 * 1024;
+    if (chunkSize < 1024 * 1024) {
+      throw new ValidationError("chunkSizeBytes must be at least 1MB");
+    }
+    const blob = this.toBlob(file);
+    const filename = options.filename || (file instanceof File ? file.name : "file.bin");
+    const totalChunks = Math.ceil(blob.size / chunkSize);
+    const baseUploadId = `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+    const state = options.existingState || {
+      upload_id: baseUploadId,
+      filename,
+      file_size: blob.size,
+      chunk_size_bytes: chunkSize,
+      total_chunks: totalChunks,
+      uploaded_chunks: [],
+      chunk_file_ids: new Array(totalChunks).fill(""),
+      created_at: Date.now(),
+      updated_at: Date.now()
+    };
+    if (state.file_size !== blob.size || state.total_chunks !== totalChunks) {
+      throw new ValidationError("existingState does not match current file/chunking settings");
+    }
+    const uploadedSet = new Set(state.uploaded_chunks);
+    let uploaded = uploadedSet.size;
+    for (let i = 0; i < totalChunks; i++) {
+      if (uploadedSet.has(i)) {
+        continue;
+      }
+      const start = i * chunkSize;
+      const end = Math.min(start + chunkSize, blob.size);
+      const chunkBlob = blob.slice(start, end);
+      const chunkName = `${filename}.part-${String(i + 1).padStart(6, "0")}-of-${String(totalChunks).padStart(6, "0")}`;
+      const enc = await this.encrypt(chunkBlob, chunkName);
+      state.chunk_file_ids[i] = enc.file_id;
+      state.uploaded_chunks.push(i);
+      state.updated_at = Date.now();
+      uploaded++;
+      if (options.onProgress) {
+        options.onProgress(uploaded, totalChunks);
+      }
+    }
+    const result = {
+      upload_id: state.upload_id,
+      filename: state.filename,
+      total_chunks: state.total_chunks,
+      chunk_size_bytes: state.chunk_size_bytes,
+      uploaded_chunks: state.uploaded_chunks.length,
+      chunk_file_ids: state.chunk_file_ids,
+      complete: state.uploaded_chunks.length === state.total_chunks
+    };
+    return { result, state };
+  }
   /**
    * Decrypt and retrieve a file using zero-knowledge flow.
    * 
@@ -669,6 +1492,41 @@ var Wolfronix = class {
       }
     });
   }
+  /**
+   * Decrypts and reassembles a chunked upload produced by `encryptResumable`.
+   */
+  async decryptChunkedToBuffer(manifest, role = "owner") {
+    this.ensureAuthenticated();
+    if (!manifest?.chunk_file_ids?.length) {
+      throw new ValidationError("manifest.chunk_file_ids is required");
+    }
+    const chunks = [];
+    let totalLength = 0;
+    for (const fileId of manifest.chunk_file_ids) {
+      if (!fileId) {
+        throw new ValidationError("manifest contains empty chunk file ID");
+      }
+      const part = await this.decryptToBuffer(fileId, role);
+      const bytes = new Uint8Array(part);
+      chunks.push(bytes);
+      totalLength += bytes.byteLength;
+    }
+    const merged = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const part of chunks) {
+      merged.set(part, offset);
+      offset += part.byteLength;
+    }
+    return merged.buffer;
+  }
+  /**
+   * Decrypts and reassembles a chunked upload into a Blob.
+   * This is a browser-friendly alias over `decryptChunkedToBuffer`.
+   */
+  async decryptChunkedManifest(manifest, role = "owner") {
+    const merged = await this.decryptChunkedToBuffer(manifest, role);
+    return new Blob([merged], { type: "application/octet-stream" });
+  }
   /**
    * Fetch the encrypted key_part_a for a file (for client-side decryption)
    * 
@@ -790,6 +1648,197 @@ var Wolfronix = class {
       throw new Error("Decryption failed. You may not be the intended recipient.");
     }
   }
+  /**
+   * Create/share a pre-key bundle for Double Ratchet PFS session setup.
+   * Exchange this bundle out-of-band with the peer.
+   */
+  async createPfsPreKeyBundle() {
+    this.ensureAuthenticated();
+    await this.ensurePfsIdentity();
+    return {
+      protocol: "wfx-dr-v1",
+      user_id: this.userId || void 0,
+      ratchet_pub_jwk: this.pfsIdentityPublicJwk,
+      created_at: Date.now()
+    };
+  }
+  /**
+   * Initialize a local PFS ratchet session from peer bundle.
+   * Both sides must call this with opposite `asInitiator` values.
+   */
+  async initPfsSession(sessionId, peerBundle, asInitiator) {
+    this.ensureAuthenticated();
+    if (!sessionId) {
+      throw new ValidationError("sessionId is required");
+    }
+    if (!peerBundle || peerBundle.protocol !== PFS_PROTOCOL || !peerBundle.ratchet_pub_jwk) {
+      throw new ValidationError("Invalid peerBundle");
+    }
+    await this.ensurePfsIdentity();
+    const myPriv = this.pfsIdentityPrivateJwk;
+    const myPub = this.pfsIdentityPublicJwk;
+    const theirPub = peerBundle.ratchet_pub_jwk;
+    const dh = await deriveEcdhSecret(myPriv, theirPub);
+    const mixed = await deriveRootAndChains(toBase64(ZERO_32.buffer), dh);
+    const session = {
+      protocol: "wfx-dr-v1",
+      session_id: sessionId,
+      role: asInitiator ? "initiator" : "responder",
+      root_key: mixed.rootKey,
+      send_chain_key: asInitiator ? mixed.chainA : mixed.chainB,
+      recv_chain_key: asInitiator ? mixed.chainB : mixed.chainA,
+      send_count: 0,
+      recv_count: 0,
+      prev_send_count: 0,
+      my_ratchet_private_jwk: myPriv,
+      my_ratchet_public_jwk: myPub,
+      their_ratchet_public_jwk: theirPub,
+      skipped_keys: {},
+      created_at: Date.now(),
+      updated_at: Date.now()
+    };
+    this.pfsSessions.set(sessionId, session);
+    return session;
+  }
+  /**
+   * Export session state for persistence (e.g., localStorage/DB).
+   */
+  exportPfsSession(sessionId) {
+    const session = this.getPfsSession(sessionId);
+    return JSON.parse(JSON.stringify(session));
+  }
+  /**
+   * Import session state from storage.
+   */
+  importPfsSession(session) {
+    if (!session || session.protocol !== PFS_PROTOCOL || !session.session_id) {
+      throw new ValidationError("Invalid PFS session payload");
+    }
+    this.pfsSessions.set(session.session_id, JSON.parse(JSON.stringify(session)));
+  }
+  /**
+   * Encrypt a message using Double Ratchet session state.
+   */
+  async pfsEncryptMessage(sessionId, plaintext) {
+    this.ensureAuthenticated();
+    if (!plaintext) {
+      throw new ValidationError("plaintext is required");
+    }
+    const session = this.getPfsSession(sessionId);
+    await this.ratchetForSend(session);
+    const n = session.send_count;
+    const msgKey = await deriveMessageKey(session.send_chain_key, n);
+    const enc = await encryptWithRawKey(msgKey, plaintext);
+    session.send_chain_key = await deriveNextChainKey(session.send_chain_key);
+    session.send_count += 1;
+    session.updated_at = Date.now();
+    return {
+      v: 1,
+      type: "pfs_ratchet",
+      session_id: sessionId,
+      n,
+      pn: session.prev_send_count,
+      ratchet_pub_jwk: session.my_ratchet_public_jwk,
+      iv: enc.iv,
+      ciphertext: enc.ciphertext,
+      timestamp: Date.now()
+    };
+  }
+  /**
+   * Decrypt a Double Ratchet packet for a session.
+   * Handles basic out-of-order delivery through skipped message keys.
+   */
+  async pfsDecryptMessage(sessionId, packet) {
+    this.ensureAuthenticated();
+    const session = this.getPfsSession(sessionId);
+    const msg = typeof packet === "string" ? JSON.parse(packet) : packet;
+    if (!msg || msg.type !== "pfs_ratchet" || msg.session_id !== sessionId) {
+      throw new ValidationError("Invalid PFS message packet");
+    }
+    if (normalizeJwk(msg.ratchet_pub_jwk) !== normalizeJwk(session.their_ratchet_public_jwk)) {
+      await this.ratchetForReceive(session, msg.ratchet_pub_jwk);
+    }
+    while (session.recv_count < msg.n) {
+      const skippedKey = await deriveMessageKey(session.recv_chain_key, session.recv_count);
+      session.skipped_keys[ratchetKeyId(session.their_ratchet_public_jwk, session.recv_count)] = toBase64(skippedKey);
+      session.recv_chain_key = await deriveNextChainKey(session.recv_chain_key);
+      session.recv_count += 1;
+    }
+    const skipId = ratchetKeyId(session.their_ratchet_public_jwk, msg.n);
+    let msgKey;
+    if (session.skipped_keys[skipId]) {
+      msgKey = fromBase64(session.skipped_keys[skipId]);
+      delete session.skipped_keys[skipId];
+    } else {
+      msgKey = await deriveMessageKey(session.recv_chain_key, msg.n);
+      session.recv_chain_key = await deriveNextChainKey(session.recv_chain_key);
+      session.recv_count = msg.n + 1;
+    }
+    session.updated_at = Date.now();
+    return decryptWithRawKey(msgKey, msg.ciphertext, msg.iv);
+  }
+  /**
+   * Group message encryption using sender-key fanout:
+   * message encrypted once with AES key, AES key wrapped for each group member with their RSA public key.
+   */
+  async encryptGroupMessage(text, groupId, recipientIds) {
+    this.ensureAuthenticated();
+    if (!text || !groupId) {
+      throw new ValidationError("text and groupId are required");
+    }
+    if (!recipientIds?.length) {
+      throw new ValidationError("recipientIds cannot be empty");
+    }
+    const uniqueRecipients = Array.from(new Set(recipientIds.filter(Boolean)));
+    if (this.userId && !uniqueRecipients.includes(this.userId)) {
+      uniqueRecipients.push(this.userId);
+    }
+    const sessionKey = await generateSessionKey();
+    const { encrypted: ciphertext, iv } = await encryptData(text, sessionKey);
+    const rawSessionKey = await exportSessionKey(sessionKey);
+    const recipientKeys = {};
+    for (const rid of uniqueRecipients) {
+      const pem = await this.getPublicKey(rid);
+      const pub = await importKeyFromPEM(pem, "public");
+      recipientKeys[rid] = await rsaEncrypt(rawSessionKey, pub);
+    }
+    const packet = {
+      v: 1,
+      type: "group_sender_key",
+      sender_id: this.userId || "",
+      group_id: groupId,
+      timestamp: Date.now(),
+      ciphertext,
+      iv,
+      recipient_keys: recipientKeys
+    };
+    return JSON.stringify(packet);
+  }
+  /**
+   * Decrypt a packet produced by `encryptGroupMessage`.
+   */
+  async decryptGroupMessage(packetJson) {
+    this.ensureAuthenticated();
+    if (!this.privateKey || !this.userId) {
+      throw new Error("Private key not available. Is user logged in?");
+    }
+    let packet;
+    try {
+      packet = JSON.parse(packetJson);
+    } catch {
+      throw new ValidationError("Invalid group packet format");
+    }
+    if (packet.type !== "group_sender_key" || !packet.recipient_keys || !packet.ciphertext || !packet.iv) {
+      throw new ValidationError("Invalid group packet structure");
+    }
+    const wrappedKey = packet.recipient_keys[this.userId];
+    if (!wrappedKey) {
+      throw new PermissionDeniedError("You are not a recipient of this group message");
+    }
+    const rawSessionKey = await rsaDecrypt(wrappedKey, this.privateKey);
+    const sessionKey = await importSessionKey(rawSessionKey);
+    return decryptData(packet.ciphertext, packet.iv, sessionKey);
+  }
   // ==========================================================================
   // Server-Side Message Encryption (Dual-Key Split)
   // ==========================================================================