@novasamatech/handoff-service 0.6.18

package/README.md

@@ -0,0 +1,156 @@
+# @novasamatech/handoff-service
+
+HOP (Handoff Pool) file transfer service for peer-to-peer chat. Uploads files to a Bulletin chain HOP pool as AES-256-GCM encrypted chunks and returns a compact identifier + claim ticket that the recipient uses to download and decrypt the file.
+
+Non-custodial, ephemeral, end-to-end encrypted. The pool node only ever sees encrypted bytes. Wire format matches the iOS `HandoffService` and Android `HopFileUploader` implementations.
+
+## Installation
+
+```shell
+npm install @novasamatech/handoff-service --save -E
+```
+
+## Overview
+
+A transfer happens in two roles:
+
+- **Sender** generates a random 32-byte `ticket`. From the ticket the service derives an sr25519 keypair (signer) and an AES-256-GCM key (encryption) via keyed blake2b (`khash(ticket, "signer" | "encryption")`). The file is split into 2 MB chunks, each chunk is AES-GCM encrypted and submitted to the pool addressed to the ticket's public key. A SCALE-encoded metadata blob listing all chunk hashes is then encrypted and submitted the same way — its hash is the file `identifier`. The sender ships `{ identifier, claimTicket }` through a side channel (the chat message).
+- **Recipient** re-derives the encryption key and signing keypair from `claimTicket`, signs the identifier to prove ownership, and calls `hop_claim` to fetch the encrypted metadata. The metadata's chunk hashes are claimed and decrypted one by one, then concatenated to reconstruct the original bytes.
+
+```
+┌────────┐   hop_submit(enc(chunk_i), [pubkey])    ┌─────────┐
+│ Sender │ ──────────────────────────────────────► │  HOP    │
+│        │   hop_submit(enc(metadata), [pubkey])   │  Pool   │
+└────────┘ ──────────────────────────────────────► └─────────┘
+  ticket                                                ▲
+     │                                                  │ hop_claim(hash, sig)
+     │ identifier + claimTicket (via chat)              │
+     ▼                                            ┌──────────┐
+                                                  │ Recipient│
+                                                  └──────────┘
+```
+
+## Usage
+
+### Upload a file
+
+```typescript
+import { createHopClient, uploadFile } from '@novasamatech/handoff-service';
+
+// Your JSON-RPC transport — any function that calls methods on a HOP node.
+const requestFn = <T>(method: string, params: unknown[]): Promise<T> =>
+  wsClient.request(method, params);
+
+const hopClient = createHopClient(requestFn);
+
+const result = await uploadFile({
+  data: fileBytes, // Uint8Array
+  hopClient,
+  onProgress: (sent, total) => console.info(`${sent}/${total} chunks`),
+});
+
+if (result.isErr()) {
+  console.error('Upload failed:', result.error);
+} else {
+  const { identifier, claimTicket } = result.value;
+  // Send identifier + claimTicket to the recipient (e.g. inside an encrypted chat message).
+}
+```
+
+### Download a file
+
+```typescript
+import { createHopClient, downloadFile } from '@novasamatech/handoff-service';
+
+const hopClient = createHopClient(requestFn);
+
+const result = await downloadFile({
+  identifier, // Uint8Array from the sender
+  claimTicket, // Uint8Array from the sender
+  hopClient,
+  onProgress: (received, total) => console.info(`${received}/${total} chunks`),
+});
+
+if (result.isErr()) {
+  console.error('Download failed:', result.error);
+} else {
+  const fileBytes = result.value; // Uint8Array — original file contents
+}
+```
+
+### Inspect pool capacity
+
+```typescript
+const status = await hopClient.poolStatus();
+// { entryCount, totalBytes, maxBytes }
+```
+
+## API
+
+### `createHopClient(requestFn): HopClient`
+
+Wraps a JSON-RPC request function into a typed HOP client. `requestFn` is called with the raw method names `hop_submit`, `hop_claim`, and `hop_poolStatus` — bring your own WebSocket / HTTP transport.
+
+```typescript
+type HopClient = {
+  submit(data: Uint8Array, recipients: Uint8Array[]): ResultAsync<PoolStatus, Error>;
+  claim(hash: Uint8Array, signature: Uint8Array): ResultAsync<Uint8Array, Error>;
+  poolStatus(): ResultAsync<PoolStatus, Error>;
+};
+```
+
+### `uploadFile(params): ResultAsync<UploadResult, Error>`
+
+```typescript
+type UploadParams = {
+  data: Uint8Array;
+  hopClient: HopClient;
+  chunkSize?: number; // default 2_000_000
+  onProgress?: (sent: number, total: number) => void;
+};
+
+type UploadResult = {
+  identifier: Uint8Array; // blake2b-256 hash of the encrypted metadata
+  claimTicket: Uint8Array; // 32-byte secret — share with recipient
+};
+```
+
+### `downloadFile(params): ResultAsync<Uint8Array, Error>`
+
+```typescript
+type DownloadParams = {
+  identifier: Uint8Array;
+  claimTicket: Uint8Array;
+  hopClient: HopClient;
+  onProgress?: (received: number, total: number) => void;
+};
+```
+
+Reassembled bytes are validated against the `totalSize` encoded in the metadata; a size mismatch produces an `Err`.
+
+### Crypto primitives
+
+Exposed for advanced use cases (e.g. signing custom pool entries):
+
+```typescript
+import {
+  generateTicket,
+  derivePublicKey,
+  deriveEncryptionKey,
+  deriveSigningKeypair,
+  signWithTicket,
+  createFileEncryption,
+} from '@novasamatech/handoff-service';
+
+const ticket = generateTicket(); // 32 random bytes
+const pubkey = derivePublicKey(ticket); // sr25519 public key
+const signature = signWithTicket(ticket, messageBytes);
+
+const enc = createFileEncryption(deriveEncryptionKey(ticket));
+const ciphertext = enc.encrypt(plainBytes); // nonce(12) || ciphertext || tag(16)
+const plain = enc.decrypt(ciphertext);
+```
+
+## Error handling
+
+All async operations return `neverthrow` `ResultAsync`, so errors are values rather than thrown exceptions. Chain with `.andThen` / `.map` or unwrap via `.isErr()` / `.value` / `.error`.

package/dist/codec.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Internal metadata stored in the HOP pool that references all chunks of an uploaded file.
+ * This is not part of the chat message — it's only used by the file loader.
+ */
+export declare const UploadedFile: import("scale-ts").Codec<{
+    totalSize: bigint;
+    chunks: Uint8Array<ArrayBufferLike>[];
+}>;

package/dist/codec.js

@@ -0,0 +1,9 @@
+import { Bytes, Struct, Vector, u64 } from 'scale-ts';
+/**
+ * Internal metadata stored in the HOP pool that references all chunks of an uploaded file.
+ * This is not part of the chat message — it's only used by the file loader.
+ */
+export const UploadedFile = Struct({
+    totalSize: u64,
+    chunks: Vector(Bytes()),
+});

package/dist/codec.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/codec.spec.js

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import { UploadedFile } from './codec.js';
+describe('UploadedFile codec', () => {
+    it('encodes and decodes round-trip', () => {
+        const hash1 = new Uint8Array(32).fill(0xaa);
+        const hash2 = new Uint8Array(32).fill(0xbb);
+        const original = {
+            totalSize: 4000000n,
+            chunks: [hash1, hash2],
+        };
+        const encoded = UploadedFile.enc(original);
+        const decoded = UploadedFile.dec(encoded);
+        expect(decoded.totalSize).toBe(4000000n);
+        expect(decoded.chunks).toHaveLength(2);
+        expect(decoded.chunks[0]).toEqual(hash1);
+        expect(decoded.chunks[1]).toEqual(hash2);
+    });
+    it('handles single chunk', () => {
+        const hash = new Uint8Array(32).fill(0xcc);
+        const original = { totalSize: 100n, chunks: [hash] };
+        const encoded = UploadedFile.enc(original);
+        const decoded = UploadedFile.dec(encoded);
+        expect(decoded.totalSize).toBe(100n);
+        expect(decoded.chunks).toHaveLength(1);
+    });
+    it('handles many chunks', () => {
+        const chunks = Array.from({ length: 50 }, (_, i) => new Uint8Array(32).fill(i));
+        const original = { totalSize: 100000000n, chunks };
+        const encoded = UploadedFile.enc(original);
+        const decoded = UploadedFile.dec(encoded);
+        expect(decoded.totalSize).toBe(100000000n);
+        expect(decoded.chunks).toHaveLength(50);
+    });
+});

package/dist/crypto/encryption.d.ts

@@ -0,0 +1,9 @@
+export type FileEncryption = {
+    encrypt(data: Uint8Array): Uint8Array;
+    decrypt(data: Uint8Array): Uint8Array;
+};
+/**
+ * AES-256-GCM encryption for file chunks and metadata.
+ * Format: nonce (12 bytes) || ciphertext || tag (16 bytes)
+ */
+export declare function createFileEncryption(key: Uint8Array): FileEncryption;

package/dist/crypto/encryption.js

@@ -0,0 +1,22 @@
+import { gcm } from '@noble/ciphers/aes.js';
+import { randomBytes } from '@noble/hashes/utils.js';
+import { mergeUint8 } from '@polkadot-api/utils';
+/**
+ * AES-256-GCM encryption for file chunks and metadata.
+ * Format: nonce (12 bytes) || ciphertext || tag (16 bytes)
+ */
+export function createFileEncryption(key) {
+    return {
+        encrypt(data) {
+            const nonce = randomBytes(12);
+            const aes = gcm(key, nonce);
+            return mergeUint8([nonce, aes.encrypt(data)]);
+        },
+        decrypt(encryptedData) {
+            const nonce = encryptedData.slice(0, 12);
+            const ciphertext = encryptedData.slice(12);
+            const aes = gcm(key, nonce);
+            return aes.decrypt(ciphertext);
+        },
+    };
+}

package/dist/crypto/encryption.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/crypto/encryption.spec.js

@@ -0,0 +1,54 @@
+import { randomBytes } from '@noble/hashes/utils.js';
+import { describe, expect, it } from 'vitest';
+import { createFileEncryption } from './encryption.js';
+describe('file encryption', () => {
+    it('encrypts and decrypts data', () => {
+        const key = randomBytes(32);
+        const encryption = createFileEncryption(key);
+        const plaintext = new TextEncoder().encode('hello world');
+        const encrypted = encryption.encrypt(plaintext);
+        const decrypted = encryption.decrypt(encrypted);
+        expect(decrypted).toEqual(plaintext);
+    });
+    it('encrypted data is longer than plaintext (nonce + tag)', () => {
+        const key = randomBytes(32);
+        const encryption = createFileEncryption(key);
+        const plaintext = new Uint8Array(100);
+        const encrypted = encryption.encrypt(plaintext);
+        // 12 bytes nonce + 100 bytes ciphertext + 16 bytes tag = 128
+        expect(encrypted.length).toBe(100 + 12 + 16);
+    });
+    it('produces different ciphertext for same plaintext (random nonce)', () => {
+        const key = randomBytes(32);
+        const encryption = createFileEncryption(key);
+        const plaintext = new Uint8Array([1, 2, 3]);
+        const a = encryption.encrypt(plaintext);
+        const b = encryption.encrypt(plaintext);
+        expect(a).not.toEqual(b);
+    });
+    it('fails to decrypt with wrong key', () => {
+        const key1 = randomBytes(32);
+        const key2 = randomBytes(32);
+        const enc1 = createFileEncryption(key1);
+        const enc2 = createFileEncryption(key2);
+        const plaintext = new TextEncoder().encode('secret');
+        const encrypted = enc1.encrypt(plaintext);
+        expect(() => enc2.decrypt(encrypted)).toThrow();
+    });
+    it('handles empty data', () => {
+        const key = randomBytes(32);
+        const encryption = createFileEncryption(key);
+        const plaintext = new Uint8Array(0);
+        const encrypted = encryption.encrypt(plaintext);
+        const decrypted = encryption.decrypt(encrypted);
+        expect(decrypted).toEqual(plaintext);
+    });
+    it('handles large data', () => {
+        const key = randomBytes(32);
+        const encryption = createFileEncryption(key);
+        const plaintext = new Uint8Array(50_000).fill(0x42);
+        const encrypted = encryption.encrypt(plaintext);
+        const decrypted = encryption.decrypt(encrypted);
+        expect(decrypted).toEqual(plaintext);
+    });
+});

package/dist/crypto/index.d.ts

@@ -0,0 +1,4 @@
+export type { FileEncryption } from './encryption.js';
+export { createFileEncryption } from './encryption.js';
+export type { FileTicket } from './ticket.js';
+export { deriveEncryptionKey, derivePublicKey, deriveSigningKeypair, deriveSigningSeed, generateTicket, signWithTicket, } from './ticket.js';

package/dist/crypto/index.js

@@ -0,0 +1,2 @@
+export { createFileEncryption } from './encryption.js';
+export { deriveEncryptionKey, derivePublicKey, deriveSigningKeypair, deriveSigningSeed, generateTicket, signWithTicket, } from './ticket.js';

package/dist/crypto/ticket.d.ts

@@ -0,0 +1,7 @@
+export type FileTicket = Uint8Array;
+export declare function generateTicket(): FileTicket;
+export declare function deriveSigningSeed(ticket: FileTicket): Uint8Array;
+export declare function deriveSigningKeypair(ticket: FileTicket): Uint8Array;
+export declare function derivePublicKey(ticket: FileTicket): Uint8Array;
+export declare function signWithTicket(ticket: FileTicket, message: Uint8Array): Uint8Array;
+export declare function deriveEncryptionKey(ticket: FileTicket): Uint8Array;

package/dist/crypto/ticket.js

@@ -0,0 +1,28 @@
+import { blake2b } from '@noble/hashes/blake2.js';
+import { randomBytes } from '@noble/hashes/utils.js';
+import { getPublicKey as sr25519GetPublicKey, secretFromSeed as sr25519SecretFromSeed, sign as sr25519Sign, } from '@scure/sr25519';
+const textEncoder = new TextEncoder();
+function khash(secret, message) {
+    return blake2b(message, { dkLen: 32, key: secret });
+}
+export function generateTicket() {
+    return randomBytes(32);
+}
+export function deriveSigningSeed(ticket) {
+    return khash(ticket, textEncoder.encode('signer'));
+}
+export function deriveSigningKeypair(ticket) {
+    const seed = deriveSigningSeed(ticket);
+    return sr25519SecretFromSeed(seed);
+}
+export function derivePublicKey(ticket) {
+    const keypair = deriveSigningKeypair(ticket);
+    return sr25519GetPublicKey(keypair);
+}
+export function signWithTicket(ticket, message) {
+    const keypair = deriveSigningKeypair(ticket);
+    return sr25519Sign(keypair, message);
+}
+export function deriveEncryptionKey(ticket) {
+    return khash(ticket, textEncoder.encode('encryption'));
+}

package/dist/crypto/ticket.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/crypto/ticket.spec.js

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import { deriveEncryptionKey, derivePublicKey, deriveSigningKeypair, deriveSigningSeed, generateTicket, signWithTicket, } from './ticket.js';
+describe('ticket key derivation', () => {
+    it('generates a 32-byte ticket', () => {
+        const ticket = generateTicket();
+        expect(ticket).toBeInstanceOf(Uint8Array);
+        expect(ticket.length).toBe(32);
+    });
+    it('generates unique tickets', () => {
+        const a = generateTicket();
+        const b = generateTicket();
+        expect(a).not.toEqual(b);
+    });
+    it('derives deterministic signing seed from ticket', () => {
+        const ticket = generateTicket();
+        const seed1 = deriveSigningSeed(ticket);
+        const seed2 = deriveSigningSeed(ticket);
+        expect(seed1).toEqual(seed2);
+        expect(seed1.length).toBe(32);
+    });
+    it('derives deterministic signing keypair from ticket', () => {
+        const ticket = generateTicket();
+        const kp1 = deriveSigningKeypair(ticket);
+        const kp2 = deriveSigningKeypair(ticket);
+        expect(kp1).toEqual(kp2);
+        expect(kp1.length).toBe(64); // sr25519 secret is 64 bytes
+    });
+    it('derives deterministic public key from ticket', () => {
+        const ticket = generateTicket();
+        const pk1 = derivePublicKey(ticket);
+        const pk2 = derivePublicKey(ticket);
+        expect(pk1).toEqual(pk2);
+        expect(pk1.length).toBe(32);
+    });
+    it('derives deterministic encryption key from ticket', () => {
+        const ticket = generateTicket();
+        const key1 = deriveEncryptionKey(ticket);
+        const key2 = deriveEncryptionKey(ticket);
+        expect(key1).toEqual(key2);
+        expect(key1.length).toBe(32);
+    });
+    it('signing key and encryption key are different', () => {
+        const ticket = generateTicket();
+        const sigSeed = deriveSigningSeed(ticket);
+        const encKey = deriveEncryptionKey(ticket);
+        expect(sigSeed).not.toEqual(encKey);
+    });
+    it('produces valid sr25519 signature', () => {
+        const ticket = generateTicket();
+        const message = new Uint8Array([1, 2, 3, 4]);
+        const signature = signWithTicket(ticket, message);
+        expect(signature).toBeInstanceOf(Uint8Array);
+        expect(signature.length).toBe(64);
+    });
+});

package/dist/fileLoader/fileLoader.d.ts

@@ -0,0 +1,20 @@
+import type { ResultAsync } from 'neverthrow';
+import type { HopClient } from '../rpc/index.js';
+export type UploadParams = {
+    data: Uint8Array;
+    hopClient: HopClient;
+    chunkSize?: number;
+    onProgress?: (sent: number, total: number) => void;
+};
+export type UploadResult = {
+    identifier: Uint8Array;
+    claimTicket: Uint8Array;
+};
+export declare function uploadFile(params: UploadParams): ResultAsync<UploadResult, Error>;
+export type DownloadParams = {
+    identifier: Uint8Array;
+    claimTicket: Uint8Array;
+    hopClient: HopClient;
+    onProgress?: (received: number, total: number) => void;
+};
+export declare function downloadFile(params: DownloadParams): ResultAsync<Uint8Array, Error>;

package/dist/fileLoader/fileLoader.js

@@ -0,0 +1,96 @@
+import { blake2b } from '@noble/hashes/blake2.js';
+import { mergeUint8 } from '@polkadot-api/utils';
+import { errAsync, okAsync } from 'neverthrow';
+import { UploadedFile } from '../codec.js';
+import { createFileEncryption, deriveEncryptionKey, derivePublicKey, generateTicket, signWithTicket, } from '../crypto/index.js';
+const DEFAULT_CHUNK_SIZE = 2_000_000;
+function hash256(data) {
+    return blake2b(data, { dkLen: 32 });
+}
+function splitIntoChunks(data, chunkSize) {
+    const chunks = [];
+    for (let offset = 0; offset < data.length; offset += chunkSize) {
+        chunks.push(data.subarray(offset, offset + chunkSize));
+    }
+    return chunks;
+}
+export function uploadFile(params) {
+    const { data, hopClient, chunkSize = DEFAULT_CHUNK_SIZE, onProgress } = params;
+    const ticket = generateTicket();
+    const recipientPublicKey = derivePublicKey(ticket);
+    const encryptionKey = deriveEncryptionKey(ticket);
+    const encryption = createFileEncryption(encryptionKey);
+    const recipients = [recipientPublicKey];
+    const chunks = splitIntoChunks(data, chunkSize);
+    const totalChunks = chunks.length;
+    let result = okAsync([]);
+    for (let i = 0; i < totalChunks; i++) {
+        const chunk = chunks[i];
+        result = result.andThen(hashes => {
+            const encrypted = encryption.encrypt(chunk);
+            return hopClient.submit(encrypted, recipients).map(_poolStatus => {
+                const chunkHash = hash256(encrypted);
+                onProgress?.(i + 1, totalChunks + 1); // +1 for metadata
+                return [...hashes, chunkHash];
+            });
+        });
+    }
+    return result.andThen(chunkHashes => {
+        const metadata = UploadedFile.enc({
+            totalSize: BigInt(data.length),
+            chunks: chunkHashes,
+        });
+        const encryptedMetadata = encryption.encrypt(metadata);
+        return hopClient.submit(encryptedMetadata, recipients).map(_poolStatus => {
+            const metadataHash = hash256(encryptedMetadata);
+            onProgress?.(totalChunks + 1, totalChunks + 1);
+            return { identifier: metadataHash, claimTicket: ticket };
+        });
+    });
+}
+export function downloadFile(params) {
+    const { identifier, claimTicket, hopClient, onProgress } = params;
+    const encryptionKey = deriveEncryptionKey(claimTicket);
+    const encryption = createFileEncryption(encryptionKey);
+    const metadataSignature = signWithTicket(claimTicket, identifier);
+    return hopClient
+        .claim(identifier, metadataSignature)
+        .andThen(encryptedMetadata => {
+        try {
+            const metadataBytes = encryption.decrypt(encryptedMetadata);
+            const uploadedFile = UploadedFile.dec(metadataBytes);
+            return okAsync(uploadedFile);
+        }
+        catch (e) {
+            return errAsync(new Error(`Failed to decrypt/decode metadata: ${e}`));
+        }
+    })
+        .andThen(uploadedFile => {
+        const { totalSize, chunks: chunkHashes } = uploadedFile;
+        const totalChunks = chunkHashes.length;
+        let result = okAsync([]);
+        for (let i = 0; i < totalChunks; i++) {
+            const chunkHash = chunkHashes[i];
+            result = result.andThen(decryptedChunks => {
+                const chunkSignature = signWithTicket(claimTicket, chunkHash);
+                return hopClient.claim(chunkHash, chunkSignature).andThen(encryptedChunk => {
+                    try {
+                        const chunk = encryption.decrypt(encryptedChunk);
+                        onProgress?.(i + 1, totalChunks);
+                        return okAsync([...decryptedChunks, chunk]);
+                    }
+                    catch (e) {
+                        return errAsync(new Error(`Failed to decrypt chunk ${i}: ${e}`));
+                    }
+                });
+            });
+        }
+        return result.andThen(decryptedChunks => {
+            const reassembled = mergeUint8(decryptedChunks);
+            if (BigInt(reassembled.length) !== totalSize) {
+                return errAsync(new Error(`File size mismatch: expected ${totalSize}, got ${reassembled.length}`));
+            }
+            return okAsync(reassembled);
+        });
+    });
+}

package/dist/fileLoader/fileLoader.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/fileLoader/fileLoader.spec.js

@@ -0,0 +1,127 @@
+import { blake2b } from '@noble/hashes/blake2.js';
+import { randomBytes } from '@noble/hashes/utils.js';
+import { okAsync } from 'neverthrow';
+import { describe, expect, it, vi } from 'vitest';
+import { downloadFile, uploadFile } from './fileLoader.js';
+function hash256(data) {
+    return blake2b(data, { dkLen: 32 });
+}
+function createMockHopClient() {
+    const submittedEntries = new Map();
+    function hashKey(hash) {
+        return Array.from(hash)
+            .map(b => b.toString(16).padStart(2, '0'))
+            .join('');
+    }
+    const submitMock = vi.fn();
+    const claimMock = vi.fn();
+    submitMock.mockImplementation((data, _recipients) => {
+        const h = hash256(data);
+        submittedEntries.set(hashKey(h), new Uint8Array(data));
+        return okAsync({ entryCount: submittedEntries.size, totalBytes: 0, maxBytes: 10_000_000 });
+    });
+    claimMock.mockImplementation((hash, _signature) => {
+        const key = hashKey(hash);
+        const entry = submittedEntries.get(key);
+        if (!entry) {
+            throw new Error(`No entry for hash ${key}`);
+        }
+        submittedEntries.delete(key);
+        return okAsync(entry);
+    });
+    const client = {
+        submit: submitMock,
+        claim: claimMock,
+        poolStatus: vi.fn(() => okAsync({ entryCount: 0, totalBytes: 0, maxBytes: 10_000_000 })),
+    };
+    return { client, submitMock, claimMock, submittedEntries };
+}
+describe('file loader', () => {
+    it('uploads and downloads a small file (single chunk)', async () => {
+        const { client, submitMock } = createMockHopClient();
+        const data = new TextEncoder().encode('hello world');
+        const uploadResult = await uploadFile({ data, hopClient: client });
+        expect(uploadResult.isOk()).toBe(true);
+        const { identifier, claimTicket } = uploadResult._unsafeUnwrap();
+        expect(identifier.length).toBe(32);
+        expect(claimTicket.length).toBe(32);
+        // 1 chunk + 1 metadata = 2 submissions
+        expect(submitMock).toHaveBeenCalledTimes(2);
+        const downloadResult = await downloadFile({
+            identifier,
+            claimTicket,
+            hopClient: client,
+        });
+        expect(downloadResult.isOk()).toBe(true);
+        expect(downloadResult._unsafeUnwrap()).toEqual(data);
+    });
+    it('uploads and downloads a multi-chunk file', async () => {
+        const { client, submitMock } = createMockHopClient();
+        const data = randomBytes(5_000); // 5KB with 2KB chunk size
+        const uploadResult = await uploadFile({
+            data,
+            hopClient: client,
+            chunkSize: 2_000,
+        });
+        expect(uploadResult.isOk()).toBe(true);
+        const { identifier, claimTicket } = uploadResult._unsafeUnwrap();
+        // 3 chunks (2000 + 2000 + 1000) + 1 metadata = 4 submissions
+        expect(submitMock).toHaveBeenCalledTimes(4);
+        const downloadResult = await downloadFile({
+            identifier,
+            claimTicket,
+            hopClient: client,
+        });
+        expect(downloadResult.isOk()).toBe(true);
+        expect(downloadResult._unsafeUnwrap()).toEqual(data);
+    });
+    it('reports upload progress', async () => {
+        const { client } = createMockHopClient();
+        const data = randomBytes(5_000);
+        const progress = [];
+        await uploadFile({
+            data,
+            hopClient: client,
+            chunkSize: 2_000,
+            onProgress: (sent, total) => progress.push([sent, total]),
+        });
+        // 3 chunks + 1 metadata = total 4 steps
+        expect(progress).toEqual([
+            [1, 4],
+            [2, 4],
+            [3, 4],
+            [4, 4],
+        ]);
+    });
+    it('reports download progress', async () => {
+        const { client } = createMockHopClient();
+        const data = randomBytes(5_000);
+        const { identifier, claimTicket } = (await uploadFile({ data, hopClient: client, chunkSize: 2_000 }))._unsafeUnwrap();
+        const progress = [];
+        await downloadFile({
+            identifier,
+            claimTicket,
+            hopClient: client,
+            onProgress: (received, total) => progress.push([received, total]),
+        });
+        expect(progress).toEqual([
+            [1, 3],
+            [2, 3],
+            [3, 3],
+        ]);
+    });
+    it('handles empty file', async () => {
+        const { client } = createMockHopClient();
+        const data = new Uint8Array(0);
+        const uploadResult = await uploadFile({ data, hopClient: client });
+        expect(uploadResult.isOk()).toBe(true);
+        const { identifier, claimTicket } = uploadResult._unsafeUnwrap();
+        const downloadResult = await downloadFile({
+            identifier,
+            claimTicket,
+            hopClient: client,
+        });
+        expect(downloadResult.isOk()).toBe(true);
+        expect(downloadResult._unsafeUnwrap()).toEqual(data);
+    });
+});

package/dist/fileLoader/index.d.ts

@@ -0,0 +1,2 @@
+export type { DownloadParams, UploadParams, UploadResult } from './fileLoader.js';
+export { downloadFile, uploadFile } from './fileLoader.js';

package/dist/fileLoader/index.js

@@ -0,0 +1 @@
+export { downloadFile, uploadFile } from './fileLoader.js';

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { HopClient } from './rpc/index.js';
+export { createHopClient } from './rpc/index.js';
+export type { HexString, PoolStatus, RequestFn } from './rpc/index.js';
+export type { FileEncryption, FileTicket } from './crypto/index.js';
+export { createFileEncryption, deriveEncryptionKey, derivePublicKey, deriveSigningKeypair, deriveSigningSeed, generateTicket, signWithTicket, } from './crypto/index.js';
+export type { DownloadParams, UploadParams, UploadResult } from './fileLoader/index.js';
+export { downloadFile, uploadFile } from './fileLoader/index.js';
+export { UploadedFile } from './codec.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createHopClient } from './rpc/index.js';
+export { createFileEncryption, deriveEncryptionKey, derivePublicKey, deriveSigningKeypair, deriveSigningSeed, generateTicket, signWithTicket, } from './crypto/index.js';
+export { downloadFile, uploadFile } from './fileLoader/index.js';
+// Codec (internal pool metadata)
+export { UploadedFile } from './codec.js';

package/dist/rpc/client.d.ts

@@ -0,0 +1,8 @@
+import type { ResultAsync } from 'neverthrow';
+import type { PoolStatus, RequestFn } from './types.js';
+export type HopClient = {
+    submit(data: Uint8Array, recipients: Uint8Array[]): ResultAsync<PoolStatus, Error>;
+    claim(hash: Uint8Array, signature: Uint8Array): ResultAsync<Uint8Array, Error>;
+    poolStatus(): ResultAsync<PoolStatus, Error>;
+};
+export declare function createHopClient(requestFn: RequestFn): HopClient;

package/dist/rpc/client.js

@@ -0,0 +1,29 @@
+import { fromHex, toHex } from '@polkadot-api/utils';
+import { fromPromise } from 'neverthrow';
+import { MultiSignature, MultiSigner } from './scale.js';
+function toHexString(bytes) {
+    return toHex(bytes);
+}
+function encodeSr25519Signer(publicKey) {
+    return toHexString(MultiSigner.enc({ tag: 'sr25519', value: publicKey }));
+}
+function encodeSr25519Signature(signature) {
+    return toHexString(MultiSignature.enc({ tag: 'sr25519', value: signature }));
+}
+function toError(e) {
+    return e instanceof Error ? e : new Error(String(e));
+}
+export function createHopClient(requestFn) {
+    return {
+        submit(data, recipients) {
+            const encodedRecipients = recipients.map(r => encodeSr25519Signer(r));
+            return fromPromise(requestFn('hop_submit', [toHexString(data), encodedRecipients, '0x']), toError);
+        },
+        claim(hash, signature) {
+            return fromPromise(requestFn('hop_claim', [toHexString(hash), encodeSr25519Signature(signature)]).then(hex => fromHex(hex)), toError);
+        },
+        poolStatus() {
+            return fromPromise(requestFn('hop_poolStatus', []), toError);
+        },
+    };
+}

package/dist/rpc/index.d.ts

@@ -0,0 +1,3 @@
+export type { HopClient } from './client.js';
+export { createHopClient } from './client.js';
+export type { HexString, PoolStatus, RequestFn } from './types.js';

package/dist/rpc/index.js

@@ -0,0 +1 @@
+export { createHopClient } from './client.js';

package/dist/rpc/scale.d.ts

@@ -0,0 +1,32 @@
+/**
+ * SCALE-encoded MultiSigner:
+ *   0 = Ed25519 (32 bytes)
+ *   1 = SR25519 (32 bytes)
+ *   2 = ECDSA   (33 bytes)
+ */
+export declare const MultiSigner: import("scale-ts").Codec<{
+    tag: "ed25519";
+    value: Uint8Array<ArrayBufferLike>;
+} | {
+    tag: "sr25519";
+    value: Uint8Array<ArrayBufferLike>;
+} | {
+    tag: "ecdsa";
+    value: Uint8Array<ArrayBufferLike>;
+}>;
+/**
+ * SCALE-encoded MultiSignature:
+ *   0 = Ed25519 (64 bytes)
+ *   1 = SR25519 (64 bytes)
+ *   2 = ECDSA   (65 bytes)
+ */
+export declare const MultiSignature: import("scale-ts").Codec<{
+    tag: "ed25519";
+    value: Uint8Array<ArrayBufferLike>;
+} | {
+    tag: "sr25519";
+    value: Uint8Array<ArrayBufferLike>;
+} | {
+    tag: "ecdsa";
+    value: Uint8Array<ArrayBufferLike>;
+}>;

package/dist/rpc/scale.js

@@ -0,0 +1,23 @@
+import { Bytes, Enum } from 'scale-ts';
+/**
+ * SCALE-encoded MultiSigner:
+ *   0 = Ed25519 (32 bytes)
+ *   1 = SR25519 (32 bytes)
+ *   2 = ECDSA   (33 bytes)
+ */
+export const MultiSigner = Enum({
+    ed25519: Bytes(32),
+    sr25519: Bytes(32),
+    ecdsa: Bytes(33),
+});
+/**
+ * SCALE-encoded MultiSignature:
+ *   0 = Ed25519 (64 bytes)
+ *   1 = SR25519 (64 bytes)
+ *   2 = ECDSA   (65 bytes)
+ */
+export const MultiSignature = Enum({
+    ed25519: Bytes(64),
+    sr25519: Bytes(64),
+    ecdsa: Bytes(65),
+});

package/dist/rpc/types.d.ts

@@ -0,0 +1,16 @@
+export type HexString = `0x${string}`;
+export type PoolStatus = {
+    entryCount: number;
+    totalBytes: number;
+    maxBytes: number;
+};
+export type SubmitParams = {
+    data: HexString;
+    recipients: HexString[];
+    proof: HexString;
+};
+export type ClaimParams = {
+    hash: HexString;
+    signature: HexString;
+};
+export type RequestFn = <Reply>(method: string, params: unknown[]) => Promise<Reply>;

package/dist/rpc/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@novasamatech/handoff-service",
+  "type": "module",
+  "version": "0.6.18",
+  "description": "HOP (Handoff Pool) file transfer service for P2P chat",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paritytech/triangle-js-sdks.git"
+  },
+  "keywords": [
+    "polkadot"
+  ],
+  "main": "dist/index.js",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "#/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@novasamatech/scale": "0.6.18",
+    "@noble/ciphers": "2.2.0",
+    "@noble/hashes": "2.2.0",
+    "@polkadot-api/utils": "0.2.0",
+    "@scure/sr25519": "1.0.0",
+    "neverthrow": "^8.2.0",
+    "scale-ts": "1.6.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}