@shhhum/xftp-web 0.2.0 → 0.4.0

package/README.md

@@ -12,39 +12,88 @@ npm install xftp-web
 
 ```typescript
 import {
-  newXFTPAgent, closeXFTPAgent,
+  XFTPAgent,
   parseXFTPServer,
-  encryptFileForUpload, uploadFile, downloadFile, deleteFile,
-  decodeDescriptionURI, encodeDescriptionURI,
+  sendFile, receiveFile, deleteFile,
   XFTPRetriableError, XFTPPermanentError, isRetriable,
 } from "xftp-web"
 
 // Create agent (manages connections)
-const agent = newXFTPAgent()
+const agent = new XFTPAgent()
+
+const servers = [
+  parseXFTPServer("xftp://server1..."),
+  parseXFTPServer("xftp://server2..."),
+  parseXFTPServer("xftp://server3..."),
+]
+
+// Upload (from Uint8Array)
+const {rcvDescriptions, sndDescription, uri} = await sendFile(
+  agent, servers, fileBytes, "photo.jpg",
+  {onProgress: (uploaded, total) => console.log(`${uploaded}/${total}`)}
+)
+
+// Upload (streaming — constant memory, no full-file buffer)
+const file = inputEl.files[0]
+const result = await sendFile(
+  agent, servers, file.stream(), file.size, file.name,
+  {onProgress: (uploaded, total) => console.log(`${uploaded}/${total}`)}
+)
+
+// Download
+const {header, content} = await receiveFile(agent, uri, {
+  onProgress: (downloaded, total) => console.log(`${downloaded}/${total}`)
+})
+
+// Delete (requires sender description from upload)
+await deleteFile(agent, sndDescription)
+
+// Cleanup
+agent.close()
+```
+
+### Advanced usage
+
+For streaming encryption (avoids buffering the full encrypted file) or worker-based uploads:
 
-// Upload
-const server = parseXFTPServer("xftp://...")
-const encrypted = encryptFileForUpload(fileBytes, "photo.jpg")
-const {rcvDescription, sndDescription, uri} = await uploadFile(agent, server, encrypted, {
-  onProgress: (uploaded, total) => console.log(`${uploaded}/${total}`),
+```typescript
+import {
+  encryptFileForUpload, uploadFile, downloadFile,
+  decodeDescriptionURI,
+} from "xftp-web"
+
+// Streaming encryption — encrypted slices emitted via callback
+const metadata = await encryptFileForUpload(fileBytes, "photo.jpg", {
+  onSlice: (data) => { /* write to OPFS, IndexedDB, etc. */ },
+  onProgress: (done, total) => {},
 })
+// metadata has {digest, key, nonce, chunkSizes} but no encData
 
-// Download (from URI or FileDescription)
+// Upload with custom chunk reader (e.g. reading from OPFS)
+const result = await uploadFile(agent, servers, metadata, {
+  readChunk: (offset, size) => readFromStorage(offset, size),
+})
+
+// Download with FileDescription object
 const fd = decodeDescriptionURI(uri)
 const {header, content} = await downloadFile(agent, fd)
+```
 
-// Delete (using sender description)
-await deleteFile(agent, sndDescription)
+### Upload options
 
-// Cleanup
-closeXFTPAgent(agent)
+```typescript
+await sendFile(agent, servers, fileBytes, "photo.jpg", {
+  onProgress: (uploaded, total) => {},  // progress callback
+  auth: basicAuthBytes,                 // BasicAuth for auth-required servers
+  numRecipients: 3,                     // multiple independent download credentials (default: 1)
+})
 ```
 
 ### Error handling
 
 ```typescript
 try {
-  await uploadFile(agent, server, encrypted)
+  await sendFile(agent, servers, fileBytes, "photo.jpg")
 } catch (e) {
   if (e instanceof XFTPRetriableError) {
     // Network/timeout/session errors — safe to retry

package/dist/agent.d.ts

@@ -1,6 +1,7 @@
+export { prepareEncryption, type EncryptionParams } from "./crypto/file.js";
 import { type FileDescription } from "./protocol/description.js";
-import { type XFTPClientAgent } from "./client.js";
-export { newXFTPAgent, closeXFTPAgent, type XFTPClientAgent, type TransportConfig, XFTPRetriableError, XFTPPermanentError, isRetriable, categorizeError, humanReadableMessage } from "./client.js";
+import { XFTPAgent } from "./client.js";
+export { XFTPAgent, type TransportConfig, XFTPRetriableError, XFTPPermanentError, isRetriable, categorizeError, humanReadableMessage } from "./client.js";
 import type { XFTPServer } from "./protocol/address.js";
 import type { FileHeader } from "./crypto/file.js";
 export interface EncryptedFileMetadata {
@@ -13,7 +14,7 @@ export interface EncryptedFileInfo extends EncryptedFileMetadata {
     encData: Uint8Array;
 }
 export interface UploadResult {
-    rcvDescription: FileDescription;
+    rcvDescriptions: FileDescription[];
     sndDescription: FileDescription;
     uri: string;
 }
@@ -23,13 +24,29 @@ export interface DownloadResult {
 }
 export declare function encodeDescriptionURI(fd: FileDescription): string;
 export declare function decodeDescriptionURI(fragment: string): FileDescription;
-export declare function encryptFileForUpload(source: Uint8Array, fileName: string): EncryptedFileInfo;
+export interface EncryptForUploadOptions {
+    onProgress?: (done: number, total: number) => void;
+    onSlice?: (data: Uint8Array) => void | Promise<void>;
+}
+export declare function encryptFileForUpload(source: Uint8Array, fileName: string, options: EncryptForUploadOptions & {
+    onSlice: NonNullable<EncryptForUploadOptions['onSlice']>;
+}): Promise<EncryptedFileMetadata>;
+export declare function encryptFileForUpload(source: Uint8Array, fileName: string, options?: EncryptForUploadOptions): Promise<EncryptedFileInfo>;
 export interface UploadOptions {
     onProgress?: (uploaded: number, total: number) => void;
     redirectThreshold?: number;
     readChunk?: (offset: number, size: number) => Promise<Uint8Array>;
+    auth?: Uint8Array;
+    numRecipients?: number;
+}
+export declare function uploadFile(agent: XFTPAgent, servers: XFTPServer[], encrypted: EncryptedFileMetadata, options?: UploadOptions): Promise<UploadResult>;
+export interface SendFileOptions {
+    onProgress?: (uploaded: number, total: number) => void;
+    auth?: Uint8Array;
+    numRecipients?: number;
 }
-export declare function uploadFile(agent: XFTPClientAgent, server: XFTPServer, encrypted: EncryptedFileMetadata, options?: UploadOptions): Promise<UploadResult>;
+export declare function sendFile(agent: XFTPAgent, servers: XFTPServer[], source: Uint8Array, fileName: string, options?: SendFileOptions): Promise<UploadResult>;
+export declare function sendFile(agent: XFTPAgent, servers: XFTPServer[], source: AsyncIterable<Uint8Array>, sourceSize: number, fileName: string, options?: SendFileOptions): Promise<UploadResult>;
 export interface RawDownloadedChunk {
     chunkNo: number;
     dhSecret: Uint8Array;
@@ -39,9 +56,11 @@ export interface RawDownloadedChunk {
 }
 export interface DownloadRawOptions {
     onProgress?: (downloaded: number, total: number) => void;
-    concurrency?: number;
 }
-export declare function downloadFileRaw(agent: XFTPClientAgent, fd: FileDescription, onRawChunk: (chunk: RawDownloadedChunk) => Promise<void>, options?: DownloadRawOptions): Promise<FileDescription>;
-export declare function downloadFile(agent: XFTPClientAgent, fd: FileDescription, onProgress?: (downloaded: number, total: number) => void): Promise<DownloadResult>;
-export declare function deleteFile(agent: XFTPClientAgent, sndDescription: FileDescription): Promise<void>;
+export declare function downloadFileRaw(agent: XFTPAgent, fd: FileDescription, onRawChunk: (chunk: RawDownloadedChunk) => Promise<void>, options?: DownloadRawOptions): Promise<FileDescription>;
+export declare function downloadFile(agent: XFTPAgent, fd: FileDescription, onProgress?: (downloaded: number, total: number) => void): Promise<DownloadResult>;
+export declare function receiveFile(agent: XFTPAgent, uri: string, options?: {
+    onProgress?: (downloaded: number, total: number) => void;
+}): Promise<DownloadResult>;
+export declare function deleteFile(agent: XFTPAgent, sndDescription: FileDescription): Promise<void>;
 //# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAUA,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,2BAA2B,CAAA;AAElC,OAAO,EAEY,KAAK,eAAe,EACtC,MAAM,aAAa,CAAA;AACpB,OAAO,EAAC,YAAY,EAAE,cAAc,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAC9E,kBAAkB,EAAE,kBAAkB,EAAE,WAAW,EAAE,eAAe,EAAE,oBAAoB,EAAC,MAAM,aAAa,CAAA;AAEhH,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,uBAAuB,CAAA;AAErD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAA;AAehD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,UAAU,CAAA;IAClB,GAAG,EAAE,UAAU,CAAA;IACf,KAAK,EAAE,UAAU,CAAA;IACjB,UAAU,EAAE,MAAM,EAAE,CAAA;CACrB;AAED,MAAM,WAAW,iBAAkB,SAAQ,qBAAqB;IAC9D,OAAO,EAAE,UAAU,CAAA;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,eAAe,CAAA;IAC/B,cAAc,EAAE,eAAe,CAAA;IAC/B,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,UAAU,CAAA;IAClB,OAAO,EAAE,UAAU,CAAA;CACpB;AAID,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,eAAe,GAAG,MAAM,CAIhE;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAOtE;AAID,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAc5F;AAID,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACtD,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;CAClE;AAED,wBAAsB,UAAU,CAC9B,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,qBAAqB,EAChC,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC,CA+CvB;AAqFD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,UAAU,CAAA;IACpB,KAAK,EAAE,UAAU,CAAA;IACjB,IAAI,EAAE,UAAU,CAAA;IAChB,MAAM,EAAE,UAAU,CAAA;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACxD,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,eAAe,EACtB,EAAE,EAAE,eAAe,EACnB,UAAU,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,EACxD,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,eAAe,CAAC,CAwC1B;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,eAAe,EACtB,EAAE,EAAE,eAAe,EACnB,UAAU,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GACvD,OAAO,CAAC,cAAc,CAAC,CAYzB;AAgCD,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CASvG"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/agent.js

@@ -3,13 +3,16 @@
 // Combines all building blocks: encryption, chunking, XFTP client commands,
 // file descriptions, and DEFLATE-compressed URI encoding.
 import pako from "pako";
-import { encryptFile, encodeFileHeader } from "./crypto/file.js";
+import { encryptFileAsync, prepareEncryption } from "./crypto/file.js";
+import { sbInit, sbEncryptChunk, sbAuth } from "./crypto/secretbox.js";
+import { concatBytes, encodeInt64 } from "./protocol/encoding.js";
+export { prepareEncryption } from "./crypto/file.js";
 import { generateEd25519KeyPair, encodePubKeyEd25519, encodePrivKeyEd25519, decodePrivKeyEd25519, ed25519KeyPairFromSeed } from "./crypto/keys.js";
-import { sha512Streaming } from "./crypto/digest.js";
-import { prepareChunkSizes, prepareChunkSpecs, getChunkDigest, fileSizeLen, authTagSize } from "./protocol/chunks.js";
+import { sha512Streaming, sha512Init, sha512Update, sha512Final } from "./crypto/digest.js";
+import { prepareChunkSpecs, getChunkDigest } from "./protocol/chunks.js";
 import { encodeFileDescription, decodeFileDescription, validateFileDescription, base64urlEncode, base64urlDecode } from "./protocol/description.js";
-import { createXFTPChunk, uploadXFTPChunk, downloadXFTPChunk, downloadXFTPChunkRaw, deleteXFTPChunk } from "./client.js";
-export { newXFTPAgent, closeXFTPAgent, XFTPRetriableError, XFTPPermanentError, isRetriable, categorizeError, humanReadableMessage } from "./client.js";
+import { createXFTPChunk, addXFTPRecipients, uploadXFTPChunk, downloadXFTPChunk, downloadXFTPChunkRaw, deleteXFTPChunk, ackXFTPChunk } from "./client.js";
+export { XFTPAgent, XFTPRetriableError, XFTPPermanentError, isRetriable, categorizeError, humanReadableMessage } from "./client.js";
 import { processDownloadedFile, decryptReceivedChunk } from "./download.js";
 import { formatXFTPServer, parseXFTPServer } from "./protocol/address.js";
 // -- URI encoding/decoding (RFC section 4.1: DEFLATE + base64url)
@@ -27,25 +30,61 @@ export function decodeDescriptionURI(fragment) {
         throw new Error("decodeDescriptionURI: " + err);
     return fd;
 }
-// -- Upload
-export function encryptFileForUpload(source, fileName) {
-    const key = new Uint8Array(32);
-    const nonce = new Uint8Array(24);
-    crypto.getRandomValues(key);
-    crypto.getRandomValues(nonce);
-    const fileHdr = encodeFileHeader({ fileName, fileExtra: null });
-    const fileSize = BigInt(fileHdr.length + source.length);
-    const payloadSize = Number(fileSize) + fileSizeLen + authTagSize;
-    const chunkSizes = prepareChunkSizes(payloadSize);
-    const encSize = BigInt(chunkSizes.reduce((a, b) => a + b, 0));
-    const encData = encryptFile(source, fileHdr, key, nonce, fileSize, encSize);
-    const digest = sha512Streaming([encData]);
-    console.log(`[AGENT-DBG] encrypt: encData.len=${encData.length} digest=${_dbgHex(digest, 64)} chunkSizes=[${chunkSizes.join(',')}]`);
-    return { encData, digest, key, nonce, chunkSizes };
+export async function encryptFileForUpload(source, fileName, options) {
+    const { onProgress, onSlice } = options ?? {};
+    const { fileHdr, key, nonce, fileSize, encSize, chunkSizes } = prepareEncryption(source.length, fileName);
+    if (onSlice) {
+        const hashState = sha512Init();
+        await encryptFileAsync(source, fileHdr, key, nonce, fileSize, encSize, onProgress, (data) => {
+            sha512Update(hashState, data);
+            return onSlice(data);
+        });
+        const digest = sha512Final(hashState);
+        return { digest, key, nonce, chunkSizes };
+    }
+    else {
+        const encData = await encryptFileAsync(source, fileHdr, key, nonce, fileSize, encSize, onProgress);
+        const digest = sha512Streaming([encData]);
+        console.log(`[AGENT-DBG] encrypt: encData.len=${encData.length} digest=${_dbgHex(digest, 64)} chunkSizes=[${chunkSizes.join(',')}]`);
+        return { encData, digest, key, nonce, chunkSizes };
+    }
 }
 const DEFAULT_REDIRECT_THRESHOLD = 400;
-export async function uploadFile(agent, server, encrypted, options) {
-    const { onProgress, redirectThreshold, readChunk: readChunkOpt } = options ?? {};
+const MAX_RECIPIENTS_PER_REQUEST = 200; // each key is ~46 bytes; 200 keys fit within 16KB XFTP block
+async function uploadSingleChunk(agent, server, chunkNo, chunkData, chunkSize, numRecipients, auth) {
+    const sndKp = generateEd25519KeyPair();
+    const rcvKps = Array.from({ length: numRecipients }, () => generateEd25519KeyPair());
+    const chunkDigest = getChunkDigest(chunkData);
+    const fileInfo = {
+        sndKey: encodePubKeyEd25519(sndKp.publicKey),
+        size: chunkSize,
+        digest: chunkDigest
+    };
+    const firstBatch = Math.min(numRecipients, MAX_RECIPIENTS_PER_REQUEST);
+    const firstBatchKeys = rcvKps.slice(0, firstBatch).map(kp => encodePubKeyEd25519(kp.publicKey));
+    const { senderId, recipientIds: firstIds } = await createXFTPChunk(agent, server, sndKp.privateKey, fileInfo, firstBatchKeys, auth);
+    const allRecipientIds = [...firstIds];
+    let added = firstBatch;
+    while (added < numRecipients) {
+        const batchSize = Math.min(numRecipients - added, MAX_RECIPIENTS_PER_REQUEST);
+        const batchKeys = rcvKps.slice(added, added + batchSize).map(kp => encodePubKeyEd25519(kp.publicKey));
+        const moreIds = await addXFTPRecipients(agent, server, sndKp.privateKey, senderId, batchKeys);
+        allRecipientIds.push(...moreIds);
+        added += batchSize;
+    }
+    await uploadXFTPChunk(agent, server, sndKp.privateKey, senderId, chunkData);
+    return {
+        chunkNo, senderId, senderKey: sndKp.privateKey,
+        recipients: allRecipientIds.map((rid, ri) => ({
+            recipientId: rid, recipientKey: rcvKps[ri].privateKey
+        })),
+        chunkSize, digest: chunkDigest, server
+    };
+}
+export async function uploadFile(agent, servers, encrypted, options) {
+    if (servers.length === 0)
+        throw new Error("uploadFile: servers list is empty");
+    const { onProgress, redirectThreshold, readChunk: readChunkOpt, auth, numRecipients = 1 } = options ?? {};
     const readChunk = readChunkOpt
         ? readChunkOpt
         : ('encData' in encrypted
@@ -53,44 +92,123 @@ export async function uploadFile(agent, server, encrypted, options) {
             : () => { throw new Error("uploadFile: readChunk required when encData is absent"); });
     const total = encrypted.chunkSizes.reduce((a, b) => a + b, 0);
     const specs = prepareChunkSpecs(encrypted.chunkSizes);
-    const sentChunks = [];
-    let uploaded = 0;
-    for (let i = 0; i < specs.length; i++) {
-        const spec = specs[i];
-        const chunkNo = i + 1;
-        const sndKp = generateEd25519KeyPair();
-        const rcvKp = generateEd25519KeyPair();
-        const chunkData = await readChunk(spec.chunkOffset, spec.chunkSize);
-        const chunkDigest = getChunkDigest(chunkData);
-        console.log(`[AGENT-DBG] upload chunk=${chunkNo} offset=${spec.chunkOffset} size=${spec.chunkSize} digest=${_dbgHex(chunkDigest, 32)} data[0..8]=${_dbgHex(chunkData)} data[-8..]=${_dbgHex(chunkData.slice(-8))}`);
-        const fileInfo = {
-            sndKey: encodePubKeyEd25519(sndKp.publicKey),
-            size: spec.chunkSize,
-            digest: chunkDigest
-        };
-        const rcvKeysForChunk = [encodePubKeyEd25519(rcvKp.publicKey)];
-        const { senderId, recipientIds } = await createXFTPChunk(agent, server, sndKp.privateKey, fileInfo, rcvKeysForChunk);
-        await uploadXFTPChunk(agent, server, sndKp.privateKey, senderId, chunkData);
-        sentChunks.push({
-            chunkNo, senderId, senderKey: sndKp.privateKey,
-            recipientId: recipientIds[0], recipientKey: rcvKp.privateKey,
-            chunkSize: spec.chunkSize, digest: chunkDigest, server
-        });
-        uploaded += spec.chunkSize;
-        onProgress?.(uploaded, total);
+    // Pre-assign servers and group by server (matching Haskell groupAllOn)
+    const chunkJobs = specs.map((spec, i) => ({
+        index: i,
+        spec,
+        server: servers[Math.floor(Math.random() * servers.length)]
+    }));
+    const byServer = new Map();
+    for (const job of chunkJobs) {
+        const key = formatXFTPServer(job.server);
+        if (!byServer.has(key))
+            byServer.set(key, []);
+        byServer.get(key).push(job);
     }
-    const rcvDescription = buildDescription("recipient", encrypted, sentChunks);
-    const sndDescription = buildDescription("sender", encrypted, sentChunks);
-    let uri = encodeDescriptionURI(rcvDescription);
-    let finalRcvDescription = rcvDescription;
+    // Upload groups in parallel, sequential within each group
+    const sentChunks = new Array(specs.length);
+    let uploaded = 0;
+    await Promise.all([...byServer.values()].map(async (jobs) => {
+        for (const { index, spec, server } of jobs) {
+            const chunkNo = index + 1;
+            const chunkData = await readChunk(spec.chunkOffset, spec.chunkSize);
+            sentChunks[index] = await uploadSingleChunk(agent, server, chunkNo, chunkData, spec.chunkSize, numRecipients, auth ?? null);
+            uploaded += spec.chunkSize;
+            onProgress?.(uploaded, total);
+        }
+    }));
+    const rcvDescriptions = Array.from({ length: numRecipients }, (_, ri) => buildDescription("recipient", ri, encrypted, sentChunks));
+    const sndDescription = buildDescription("sender", 0, encrypted, sentChunks);
+    let uri = encodeDescriptionURI(rcvDescriptions[0]);
+    let finalRcvDescriptions = rcvDescriptions;
     const threshold = redirectThreshold ?? DEFAULT_REDIRECT_THRESHOLD;
     if (uri.length > threshold && sentChunks.length > 1) {
-        finalRcvDescription = await uploadRedirectDescription(agent, server, rcvDescription);
-        uri = encodeDescriptionURI(finalRcvDescription);
+        const redirected = await uploadRedirectDescription(agent, servers, rcvDescriptions[0], auth);
+        finalRcvDescriptions = [redirected, ...rcvDescriptions.slice(1)];
+        uri = encodeDescriptionURI(redirected);
+    }
+    return { rcvDescriptions: finalRcvDescriptions, sndDescription, uri };
+}
+export async function sendFile(agent, servers, source, fileNameOrSize, fileNameOrOptions, maybeOptions) {
+    let sourceSize, fileName, options;
+    if (source instanceof Uint8Array) {
+        sourceSize = source.length;
+        fileName = fileNameOrSize;
+        options = fileNameOrOptions;
+    }
+    else {
+        sourceSize = fileNameOrSize;
+        fileName = fileNameOrOptions;
+        options = maybeOptions;
+    }
+    if (servers.length === 0)
+        throw new Error("sendFile: servers list is empty");
+    const { onProgress, auth, numRecipients = 1 } = options ?? {};
+    const params = prepareEncryption(sourceSize, fileName);
+    const specs = prepareChunkSpecs(params.chunkSizes);
+    const total = params.chunkSizes.reduce((a, b) => a + b, 0);
+    const encState = sbInit(params.key, params.nonce);
+    const hashState = sha512Init();
+    const sentChunks = new Array(specs.length);
+    let specIdx = 0, chunkOff = 0, uploaded = 0;
+    let chunkBuf = new Uint8Array(specs[0].chunkSize);
+    async function flushChunk() {
+        const server = servers[Math.floor(Math.random() * servers.length)];
+        sentChunks[specIdx] = await uploadSingleChunk(agent, server, specIdx + 1, chunkBuf, specs[specIdx].chunkSize, numRecipients, auth ?? null);
+        uploaded += specs[specIdx].chunkSize;
+        onProgress?.(uploaded, total);
+        specIdx++;
+        if (specIdx < specs.length) {
+            chunkBuf = new Uint8Array(specs[specIdx].chunkSize);
+            chunkOff = 0;
+        }
+    }
+    async function feedEncrypted(data) {
+        sha512Update(hashState, data);
+        let off = 0;
+        while (off < data.length) {
+            const space = specs[specIdx].chunkSize - chunkOff;
+            const n = Math.min(space, data.length - off);
+            chunkBuf.set(data.subarray(off, off + n), chunkOff);
+            chunkOff += n;
+            off += n;
+            if (chunkOff === specs[specIdx].chunkSize)
+                await flushChunk();
+        }
+    }
+    await feedEncrypted(sbEncryptChunk(encState, concatBytes(encodeInt64(params.fileSize), params.fileHdr)));
+    const SLICE = 65536;
+    if (source instanceof Uint8Array) {
+        for (let off = 0; off < source.length; off += SLICE) {
+            await feedEncrypted(sbEncryptChunk(encState, source.subarray(off, Math.min(off + SLICE, source.length))));
+        }
+    }
+    else {
+        for await (const chunk of source) {
+            for (let off = 0; off < chunk.length; off += SLICE) {
+                await feedEncrypted(sbEncryptChunk(encState, chunk.subarray(off, Math.min(off + SLICE, chunk.length))));
+            }
+        }
+    }
+    const padLen = Number(params.encSize - 16n - params.fileSize - 8n);
+    const padding = new Uint8Array(padLen);
+    padding.fill(0x23);
+    await feedEncrypted(sbEncryptChunk(encState, padding));
+    await feedEncrypted(sbAuth(encState));
+    const digest = sha512Final(hashState);
+    const encrypted = { digest, key: params.key, nonce: params.nonce, chunkSizes: params.chunkSizes };
+    const rcvDescriptions = Array.from({ length: numRecipients }, (_, ri) => buildDescription("recipient", ri, encrypted, sentChunks));
+    const sndDescription = buildDescription("sender", 0, encrypted, sentChunks);
+    let uri = encodeDescriptionURI(rcvDescriptions[0]);
+    let finalRcvDescriptions = rcvDescriptions;
+    if (uri.length > DEFAULT_REDIRECT_THRESHOLD && sentChunks.length > 1) {
+        const redirected = await uploadRedirectDescription(agent, servers, rcvDescriptions[0], auth);
+        finalRcvDescriptions = [redirected, ...rcvDescriptions.slice(1)];
+        uri = encodeDescriptionURI(redirected);
     }
-    return { rcvDescription: finalRcvDescription, sndDescription, uri };
+    return { rcvDescriptions: finalRcvDescriptions, sndDescription, uri };
 }
-function buildDescription(party, enc, chunks) {
+function buildDescription(party, recipientIndex, enc, chunks) {
     const defChunkSize = enc.chunkSizes[0];
     return {
         party,
@@ -105,40 +223,38 @@ function buildDescription(party, enc, chunks) {
             digest: c.digest,
             replicas: [{
                     server: formatXFTPServer(c.server),
-                    replicaId: party === "recipient" ? c.recipientId : c.senderId,
-                    replicaKey: encodePrivKeyEd25519(party === "recipient" ? c.recipientKey : c.senderKey)
+                    replicaId: party === "recipient" ? c.recipients[recipientIndex].recipientId : c.senderId,
+                    replicaKey: encodePrivKeyEd25519(party === "recipient" ? c.recipients[recipientIndex].recipientKey : c.senderKey)
                 }]
         })),
         redirect: null
     };
 }
-async function uploadRedirectDescription(agent, server, innerFd) {
+async function uploadRedirectDescription(agent, servers, innerFd, auth) {
     const yaml = encodeFileDescription(innerFd);
     const yamlBytes = new TextEncoder().encode(yaml);
-    const enc = encryptFileForUpload(yamlBytes, "");
+    const enc = await encryptFileForUpload(yamlBytes, "");
     const specs = prepareChunkSpecs(enc.chunkSizes);
-    const sentChunks = [];
-    for (let i = 0; i < specs.length; i++) {
-        const spec = specs[i];
-        const chunkNo = i + 1;
-        const sndKp = generateEd25519KeyPair();
-        const rcvKp = generateEd25519KeyPair();
-        const chunkData = enc.encData.subarray(spec.chunkOffset, spec.chunkOffset + spec.chunkSize);
-        const chunkDigest = getChunkDigest(chunkData);
-        const fileInfo = {
-            sndKey: encodePubKeyEd25519(sndKp.publicKey),
-            size: spec.chunkSize,
-            digest: chunkDigest
-        };
-        const rcvKeysForChunk = [encodePubKeyEd25519(rcvKp.publicKey)];
-        const { senderId, recipientIds } = await createXFTPChunk(agent, server, sndKp.privateKey, fileInfo, rcvKeysForChunk);
-        await uploadXFTPChunk(agent, server, sndKp.privateKey, senderId, chunkData);
-        sentChunks.push({
-            chunkNo, senderId, senderKey: sndKp.privateKey,
-            recipientId: recipientIds[0], recipientKey: rcvKp.privateKey,
-            chunkSize: spec.chunkSize, digest: chunkDigest, server
-        });
+    const chunkJobs = specs.map((spec, i) => ({
+        index: i,
+        spec,
+        server: servers[Math.floor(Math.random() * servers.length)]
+    }));
+    const byServer = new Map();
+    for (const job of chunkJobs) {
+        const key = formatXFTPServer(job.server);
+        if (!byServer.has(key))
+            byServer.set(key, []);
+        byServer.get(key).push(job);
     }
+    const sentChunks = new Array(specs.length);
+    await Promise.all([...byServer.values()].map(async (jobs) => {
+        for (const { index, spec, server } of jobs) {
+            const chunkNo = index + 1;
+            const chunkData = enc.encData.subarray(spec.chunkOffset, spec.chunkOffset + spec.chunkSize);
+            sentChunks[index] = await uploadSingleChunk(agent, server, chunkNo, chunkData, spec.chunkSize, 1, auth ?? null);
+        }
+    }));
     return {
         party: "recipient",
         size: enc.chunkSizes.reduce((a, b) => a + b, 0),
@@ -152,8 +268,8 @@ async function uploadRedirectDescription(agent, server, innerFd) {
             digest: c.digest,
             replicas: [{
                     server: formatXFTPServer(c.server),
-                    replicaId: c.recipientId,
-                    replicaKey: encodePrivKeyEd25519(c.recipientKey)
+                    replicaId: c.recipients[0].recipientId,
+                    replicaKey: encodePrivKeyEd25519(c.recipients[0].recipientKey)
                 }]
         })),
         redirect: { size: innerFd.size, digest: innerFd.digest }
@@ -163,7 +279,7 @@ export async function downloadFileRaw(agent, fd, onRawChunk, options) {
     const err = validateFileDescription(fd);
     if (err)
         throw new Error("downloadFileRaw: " + err);
-    const { onProgress, concurrency = 1 } = options ?? {};
+    const { onProgress } = options ?? {};
     // Resolve redirect on main thread (redirect data is small)
     if (fd.redirect !== null) {
         console.log(`[AGENT-DBG] resolving redirect: outer size=${fd.size} chunks=${fd.chunks.length}`);
@@ -197,6 +313,7 @@ export async function downloadFileRaw(agent, fd, onRawChunk, options) {
                 body: raw.body,
                 digest: chunk.digest
             });
+            await ackXFTPChunk(agent, server, kp.privateKey, replica.replicaId);
             downloaded += chunk.chunkSize;
             onProgress?.(downloaded, resolvedFd.size);
         }
@@ -216,18 +333,32 @@ export async function downloadFile(agent, fd, onProgress) {
         throw new Error("downloadFile: file digest mismatch");
     return processDownloadedFile(resolvedFd, chunks);
 }
+export async function receiveFile(agent, uri, options) {
+    const fd = decodeDescriptionURI(uri);
+    return downloadFile(agent, fd, options?.onProgress);
+}
 async function resolveRedirect(agent, fd) {
     const plaintextChunks = new Array(fd.chunks.length);
+    const byServer = new Map();
     for (const chunk of fd.chunks) {
-        const replica = chunk.replicas[0];
-        if (!replica)
-            throw new Error("resolveRedirect: chunk has no replicas");
-        const server = parseXFTPServer(replica.server);
-        const seed = decodePrivKeyEd25519(replica.replicaKey);
-        const kp = ed25519KeyPairFromSeed(seed);
-        const data = await downloadXFTPChunk(agent, server, kp.privateKey, replica.replicaId, chunk.digest);
-        plaintextChunks[chunk.chunkNo - 1] = data;
+        const srv = chunk.replicas[0]?.server ?? "";
+        if (!byServer.has(srv))
+            byServer.set(srv, []);
+        byServer.get(srv).push(chunk);
     }
+    await Promise.all([...byServer.entries()].map(async ([srv, chunks]) => {
+        const server = parseXFTPServer(srv);
+        for (const chunk of chunks) {
+            const replica = chunk.replicas[0];
+            if (!replica)
+                throw new Error("resolveRedirect: chunk has no replicas");
+            const seed = decodePrivKeyEd25519(replica.replicaKey);
+            const kp = ed25519KeyPairFromSeed(seed);
+            const data = await downloadXFTPChunk(agent, server, kp.privateKey, replica.replicaId, chunk.digest);
+            plaintextChunks[chunk.chunkNo - 1] = data;
+            await ackXFTPChunk(agent, server, kp.privateKey, replica.replicaId);
+        }
+    }));
     const totalSize = plaintextChunks.reduce((s, c) => s + c.length, 0);
     if (totalSize !== fd.size)
         throw new Error("resolveRedirect: redirect file size mismatch");
@@ -248,15 +379,24 @@ async function resolveRedirect(agent, fd) {
 }
 // -- Delete
 export async function deleteFile(agent, sndDescription) {
+    const byServer = new Map();
     for (const chunk of sndDescription.chunks) {
-        const replica = chunk.replicas[0];
-        if (!replica)
-            throw new Error("deleteFile: chunk has no replicas");
-        const server = parseXFTPServer(replica.server);
-        const seed = decodePrivKeyEd25519(replica.replicaKey);
-        const kp = ed25519KeyPairFromSeed(seed);
-        await deleteXFTPChunk(agent, server, kp.privateKey, replica.replicaId);
+        const srv = chunk.replicas[0]?.server ?? "";
+        if (!byServer.has(srv))
+            byServer.set(srv, []);
+        byServer.get(srv).push(chunk);
     }
+    await Promise.all([...byServer.entries()].map(async ([srv, chunks]) => {
+        const server = parseXFTPServer(srv);
+        for (const chunk of chunks) {
+            const replica = chunk.replicas[0];
+            if (!replica)
+                throw new Error("deleteFile: chunk has no replicas");
+            const seed = decodePrivKeyEd25519(replica.replicaKey);
+            const kp = ed25519KeyPairFromSeed(seed);
+            await deleteXFTPChunk(agent, server, kp.privateKey, replica.replicaId);
+        }
+    }));
 }
 // -- Internal
 function _dbgHex(b, n = 8) {