File Transfer

Cloud Share can transfer individual files up to 100 MB — encrypted in transit with AES-256-GCM and verified on arrival with SHA-512.

Uploading a file

In the sender UI

  1. Open the sender web UI (http://localhost:5000)
  2. Click the File tab

📸 Screenshot needed: file-transfer-sender-tab.png Description: Sender web UI with the File tab selected, showing the drag-and-drop zone

  1. Either:
    • Drag and drop a file onto the drop zone
    • Click Browse (or the drop zone) to open a file picker

📸 Screenshot needed: file-transfer-sender-dragdrop.png Description: File tab with a file being dragged onto the drop zone, showing the hover state

  1. The file name and size appear in the UI
  2. Click Upload

The file is:

  • Read into memory on the sender
  • Hashed with SHA-512
  • Encrypted with AES-256-GCM (using a randomly generated 12-byte nonce)
  • Added to the in-memory queue
  • Broadcast to all connected receivers via SSE

📸 Screenshot needed: file-transfer-sender-queued.png Description: Sender queue showing the uploaded file with filename, size, and Queued badge

Via the API (advanced) 

  curl -X POST "https://<tunnel-url>/upload/file?secret=<your-secret>" \
  -F "file=@/path/to/your/document.pdf"

Response:

  { "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }

Receiving a file

In the receiver UI

When a file is queued on the sender, it appears in the receiver queue immediately.

📸 Screenshot needed: file-transfer-receiver-queue.png Description: Receiver queue showing a file item with filename, size, and Receive button

  1. Click Receive next to the file item
  2. The receiver downloads the encrypted file through the Dev Tunnel
  3. Decrypts it with AES-256-GCM using the derived key
  4. Computes the SHA-512 hash of the decrypted content
  5. A hash verification modal appears

📸 Screenshot needed: file-transfer-receiver-verifying.png Description: Receiver showing a progress indicator while downloading and verifying the file

  1. If verification passes (✅), a Download button appears
  2. Click Download to save the file to your local machine

📸 Screenshot needed: file-transfer-receiver-download.png Description: Hash verification modal showing success and the Download button

The downloaded file is identical to the original — the filename is preserved.

File size limit

LimitValue
Maximum file size100 MB

⚠️ Warning: Files larger than 100 MB will be rejected at upload time. For large files, consider splitting them into parts or using a different transfer mechanism.

Files are held in the sender’s in-memory queue. Ensure the sending machine has enough available RAM for the encrypted file content.

Filename handling

The original filename is preserved through the transfer and used when the receiver downloads the file. Filenames are sanitized on the sender side to prevent path traversal issues.

What happens on hash mismatch

If the SHA-512 hash of the decrypted file does not match the hash computed by the sender:

  1. An error is displayed in the receiver UI
  2. The item is permanently deleted from the sender queue — it cannot be received again
  3. The corrupted/tampered file is discarded — it is not written to disk

ℹ️ Info: Hash mismatches are rare in normal use. If you see one, it may indicate a network corruption issue. The sender will need to re-queue the file for another attempt.

Use cases

  • Sending compiled binaries between build machines
  • Transferring configuration files to a remote system
  • Sharing documents with a colleague on a different network
  • Moving files between a personal and work machine without cloud storage