Core Concepts
Core Concepts
Before diving into advanced features, it helps to understand the building blocks that make cloud-share work. This page explains each concept at a level that will inform how you use the tool day-to-day.
Dev Tunnels
A Microsoft Dev Tunnel is an outbound HTTPS connection from the sender machine to Microsoft’s relay infrastructure. It creates a publicly accessible URL (e.g. https://abc123.devtunnels.ms) that proxies all requests back to the sender’s local port 5000.
Why this matters:
- No port forwarding or firewall rules needed on the sender
- The receiver only needs outbound HTTPS (port 443) — works from corporate networks, coffee shops, mobile hotspots
- The tunnel is ephemeral — it exists only while the sender is running
- Microsoft’s relay sees only encrypted HTTPS traffic; it cannot read the content
The devtunnel CLI manages tunnel creation and authentication. Cloud Share calls it automatically.
Secret tokens
Every time you start cloud-share-sender, it generates a fresh 12-character alphanumeric secret token (e.g. aB3kP9mQ2rTs). This secret serves two roles:
- Authentication — every API call to the sender includes
?secret=<token>. Requests without a valid secret are rejected with401 Unauthorized. - Encryption key material — the AES-256 encryption key is derived from this secret using SHA-256.
The secret is:
- Generated randomly on each sender start
- Never saved to disk
- Never transmitted over the network in plaintext (it travels in HTTPS query parameters, encrypted by TLS)
- Scoped to a single session — starting the sender again creates a new secret and invalidates the old one
⚠️ Warning: Share the secret through a separate secure channel (e.g. Signal, phone call). Anyone who has both the tunnel URL and the secret can receive your queued items.
AES-256-GCM encryption
Every item — text, file, or zip bundle — is encrypted before it leaves the sender’s memory using AES-256-GCM:
| Component | Detail |
|---|---|
| Algorithm | AES-256 in Galois/Counter Mode (GCM) |
| Key | 32 bytes derived from the secret via SHA-256 |
| Nonce | 12 bytes, randomly generated per item |
| Authentication tag | 16 bytes, appended to ciphertext |
| Encoding | Nonce + ciphertext + tag, all base64-encoded for transport |
GCM mode provides both confidentiality (no one can read the content) and authenticity (no one can tamper with the ciphertext without the tag becoming invalid).
See Encryption Architecture for the full technical breakdown.
The queue model
The sender maintains an in-memory queue of items waiting to be received. Items are added when you click Share/Upload in the sender UI. Each item has:
- A unique ID (UUID)
- A type (
text,file,zip) - Encrypted content
- A SHA-512 hash of the plaintext
- A status (
Queued,Received)
Items remain in the queue until they are received (downloaded by the receiver) or explicitly deleted. The queue is not persisted to disk — restarting the sender clears all queued items.
The receiver fetches item metadata from GET /queue?secret=X and downloads individual items from GET /item/{id}?secret=X.
SHA-512 hash verification
Before encrypting an item, the sender computes a SHA-512 hash of the plaintext content and stores it alongside the encrypted item. When the receiver downloads and decrypts an item, it:
- Decrypts the content using AES-256-GCM
- Computes SHA-512 of the decrypted plaintext
- Compares it to the hash provided by the sender using a constant-time comparison
If the hashes match → ✅ content is intact and untampered.
If the hashes do not match → ❌ the item is permanently deleted from the sender queue and an error is shown in the receiver UI. This prevents a corrupted or tampered item from being kept or retried silently.
Real-time updates (SSE)
The receiver maintains a persistent connection to the sender’s GET /events?secret=X endpoint, which streams Server-Sent Events (SSE). This means:
- New items appear in the receiver queue instantly — no polling, no page refresh
- When an item is received, its status updates everywhere in real time
- When an item is deleted, it disappears from all connected receivers
If the SSE connection drops (network hiccup, tunnel reconnect), the receiver automatically reconnects after a 3-second backoff. A connection status badge in the UI shows whether the event stream is live.
Session memory
The receiver saves its last-used tunnel URL and secret to receiver-session.json in ~/AppData/CloudShare/. On the next run, it pre-fills these values so you do not have to type them again.
The sender saves your DevTunnels login (OAuth tokens) to preferences.json so you do not have to re-authenticate on every run.
Use cloud-share-sender --reset to clear the saved DevTunnels login and re-authenticate. Use cloud-share-receiver --no-prompt to skip the startup prompt entirely (useful in scripts when URL and secret are provided via flags).