Garrard.CloudShare.Receiver 0.1.8

cloud-share

A beautiful, secure way to share files and text between computers using Microsoft Dev Tunnels. Install as .NET global tools and enjoy a gorgeous CLI experience powered by Spectre.Console!

📖 Full Documentation →

✨ Features

• 🎨 Beautiful CLI with Spectre.Console - colors, tables, progress indicators
• 🌐 Web UI — both tools open a local browser UI (Bootstrap 5 + Alpine.js dark theme)
• 🔒 Authenticated web UI — sender UI gated by a one-time UI token + HttpOnly cookie; receiver UI protected by a local session token
• 🔐 End-to-end encryption — AES-256-GCM encrypts all content before it leaves the sender
• 🔑 HKDF key derivation — AES key derived via HKDF-SHA256 (RFC 5869 / NIST SP 800-56C), not a raw hash
• 🧮 Integrity verification — SHA-512 hash shown on both sides; receiver must confirm match before accessing content
• 🛡️ Brute-force protection — 10 failed auth attempts triggers a 60-second lockout with HTTP 429
• 🚀 Security hardened — Bearer auth, Anti-CSRF (Origin/Referer), security headers (CSP, CORS, X-Frame-Options), Kestrel size limits, constant-time comparisons, SRI hashes on all CDN dependencies (see full security features →)
• 🛡️ Rate limiting — receiver endpoints protected by a fixed-window rate limiter (30 req/10s) to prevent local abuse
• 🔑 CLOUDSHARE_SECRET env var — pre-load the shared secret via environment variable on both sender and receiver to avoid process list exposure
• 📁 File transfers — upload from sender UI, download via explicit button after hash verification
• 📦 Zip bundles — bundle multiple files into a zip, with optional AES-256 zip password, and queue it as a single item
• 📝 Text sharing — paste text in sender UI, copy to clipboard from receiver UI
• 🌐 Microsoft Dev Tunnels integration (free tier)
• ⚡ Fast and lightweight .NET 10 global tools
• 🔗 No port forwarding or firewall configuration needed
• 🤖 Auto-installs dependencies (devtunnels CLI) with user confirmation
• 🔑 Auto-login — prompts for Microsoft or GitHub account, remembers your choice; automatically re-authenticates if the token expires
• 💾 Session memory — receiver remembers the last URL and secret across runs
• 🌍 Cross-platform: Windows, macOS (including Apple Silicon), Linux (Ubuntu)

🚀 Installation

Option 1: Install as .NET Global Tools (Recommended)

# Install the sender
dotnet tool install --global Garrard.CloudShare.Sender

# Install the receiver
dotnet tool install --global Garrard.CloudShare.Receiver

After installation, you can run the tools from anywhere:

cloud-share-sender [file-path]
cloud-share-receiver

Option 2: Build from Source

git clone https://github.com/garrardkitchen/cloud-share.git
cd cloud-share
dotnet build --configuration Release

📋 Prerequisites

.NET 10 SDK

Download and install from https://dotnet.microsoft.com/download/dotnet/10.0

Verify installation:

dotnet --version  # Should be 10.0 or higher

DevTunnels CLI (Auto-installed)

The tools will automatically detect if DevTunnels CLI is missing and offer to install it for you! If you prefer manual installation:

Windows (via winget):

winget install Microsoft.devtunnel

macOS (via Homebrew):

brew install --cask devtunnel

Linux:

curl -sL https://aka.ms/DevTunnelCliInstall | bash

Authentication

On first run the sender will prompt you to choose a login method and launch a browser-based OAuth flow automatically:

? Choose your login method:
> Microsoft account
  GitHub account (free tier)

Your choice is saved to ~/<AppData>/CloudShare/preferences.json and reused on every subsequent run — no need to log in again.

If the login token expires, the sender detects this automatically, re-authenticates using your saved preference (no prompt), and retries the tunnel — no intervention needed.

To switch accounts or re-authenticate manually, pass --reset:

cloud-share-sender --reset

🎯 Usage

Sender

Start the sender (text-only mode):

cloud-share-sender

Start with a pre-loaded secret via environment variable (avoids process list exposure):

export CLOUDSHARE_SECRET="your-secret-here"
cloud-share-sender

Start the sender with a file pre-loaded:

cloud-share-sender /path/to/document.pdf

Re-authenticate or switch accounts:

cloud-share-sender --reset
cloud-share-sender /path/to/file.pdf --reset

Check version:

cloud-share-sender --version

The sender starts a local web UI at http://localhost:5000 and opens it in your browser automatically. The UI lets you:

• Text tab — paste any text and click Share Text to encrypt and queue it
• File tab — drag-and-drop or browse for a single file and click Upload File
• Zip Bundle tab — add multiple files to a bundle, set an optional AES-256 zip password, then click Create & Queue Zip to zip, encrypt, and queue the bundle as a single item
• Queue table — see all queued items with their SHA-512 hash prefix and timestamp; password-protected zips show a 🔒 icon; items are marked ✓ once received

The CLI also prints the tunnel URL and secret token to share with the receiver:

─────────────────────────────────────────
 Cloud Share Sender v1.0.0
─────────────────────────────────────────

✓ DevTunnels CLI is installed
✓ Authenticated with DevTunnels

╭──────────────┬──────────────────────────╮
│ Setting      │ Value                    │
├──────────────┼──────────────────────────┤
│ Secret Token │ aBc123XyZ456            │
│ File to Share│ none - text only mode    │
│ Local Port   │ 5000                     │
╰──────────────┴──────────────────────────╯

Tunnel URL: https://abc123.uks1.devtunnels.ms:5000
Web UI: http://localhost:5000 (opening in browser...)

Press Ctrl+C to stop sharing.

Receiver

cloud-share-receiver

With a pre-loaded secret (skips the interactive secret prompt entirely):

export CLOUDSHARE_SECRET="your-secret-here"
cloud-share-receiver

Check version:

cloud-share-receiver --version

The receiver prompts for the tunnel URL and secret, then starts a local web UI at http://localhost:5001 and opens it in your browser automatically.

Session memory: The URL and secret are saved to ~/<AppData>/CloudShare/receiver-session.json as you type them. On the next run the receiver offers to reuse the previous connection:

╭─ Previous session ──────────────────────────╮
│ URL:    https://c84xl717.uks1.devtunnels.ms │
│ Secret: ************                         │
╰──────────────────────────────────────────────╯
? Use previous connection? [Y/n]

Answering Y skips the prompts entirely. Answering N overwrites the saved session with new values.

Receiving items:

1. When the sender queues an item, it appears in the receiver's queue list in real time (via SSE).
2. Click Receive on any queued item.
3. The Hash Verification dialog opens showing both the sender's SHA-512 hash and the hash computed by the receiver. Confirm they match before proceeding.
   • Mismatch — the item is permanently deleted from the sender and the content is discarded.
   • Text match — the decrypted text is displayed with a Copy text button to copy it to your clipboard.
   • File/Zip match — a Download File button appears (bottom-left of the dialog); click it to save the file to your browser's download folder. Password-protected zips show a 🔒 warning — you will need the password (shared out-of-band) to extract the zip.

🏗️ Architecture

┌──────────────────────────┐                     ┌────────────────────────────┐
│  cloud-share-sender      │                     │  cloud-share-receiver      │
│                          │                     │                            │
│  CLI (Spectre.Console)   │                     │  CLI (Spectre.Console)     │
│  Web UI  localhost:5000  │                     │  Web UI  localhost:5001    │
│                          │                     │                            │
│  ┌────────────────────┐  │                     │  ┌──────────────────────┐  │
│  │ AES-256-GCM encrypt│  │  Microsoft Dev      │  │ Proxy → sender tunnel│  │
│  │ SHA-512 hash       │  │◄────Tunnels─────────│  │ AES-256-GCM decrypt  │  │
│  │ Queue (in-memory)  │  │                     │  │ SHA-512 verify       │  │
│  │ SSE broadcaster    │  │                     │  │ SSE proxy            │  │
│  └────────────────────┘  │                     │  └──────────────────────┘  │
└──────────────────────────┘                     └────────────────────────────┘
          │                                                    ▲
          └──────────── Share tunnel URL + secret ────────────┘
                         (out-of-band, e.g. chat)

🔒 Security

Cloud Share has been subject to a full parallel security audit using OWASP Top 10, NIST SP 800-53, NIST CSF 2.0, STRIDE, and CWE/SANS Top 25. The controls below reflect the implemented findings.

📋 Full Security Features Reference →
🔍 Complete Audit Report →

Transit & Cryptography

Authentication & Access Control

HTTP Hardening

Resource & DoS Protection

Secret & Credential Hygiene

Input Validation

Supply Chain & CI/CD

Security Event Logging

All security-relevant events are prefixed with SECURITY_EVENT: in the console output at warning level, making them straightforward to grep or pipe to a SIEM:

• Authentication failures and brute-force lockouts
• Hash mismatches (potential tampering)
• Decryption failures
• Oversized response rejections
• Unknown or malformed SSE event types
• Anti-CSRF Origin/Referer violations

Best Practices

• 🔐 Always share the secret token through a secure, out-of-band channel (e.g. encrypted messaging)
• 🔄 A new secret is generated on every sender start — secrets are single-session
• ⏱️ Stop the sender immediately after file transfer is complete
• 🎯 This tool is designed for one-time, temporary file sharing only

🌐 Network Requirements

The following outbound connections are required. Share this list with your network administrator for firewall rule creation.

Sender machine

Receiver machine

Tool installation only (one-time)

Exact CDN resources loaded by the web UI

Both the sender (localhost:5000) and receiver (localhost:5001) browsers load:

All <script> and <link> tags carry integrity= (SRI) and crossorigin="anonymous" attributes. Versions are pinned exactly — no floating @3.x.x wildcards.

Air-gapped environments: If outbound access to cdn.jsdelivr.net is blocked, the web UI will not render correctly. In that scenario the CDN <script> and <link> tags in sender-ui.html and receiver-ui.html can be replaced with locally hosted copies of the same assets.

🧪 Development

Building

dotnet build --configuration Release

Running Tests

dotnet test --configuration Release

With coverage:

dotnet test --collect:"XPlat Code Coverage" --results-directory ./coverage

Project Structure

cloud-share/
├── cloud-share.sln              # Solution file
├── README.md                    # This file
├── LICENSE                      # MIT license
├── global.json                  # .NET SDK version
├── .github/
│   └── workflows/
│       └── ci.yml               # CI/CD pipeline with tests & coverage
├── CloudShare.Core/
│   ├── CloudShare.Core.csproj  # Shared library
│   ├── CryptoHelper.cs         # AES-256-GCM encryption & SHA-512 hashing
│   ├── DependencyManager.cs    # Auto-install, login flow & preferences
│   ├── SpectreHelper.cs        # Markup escaping helpers
│   └── VersionInfo.cs          # Version information
├── TunnelSender/
│   ├── TunnelSender.csproj     # Sender global tool (uses SharpZipLib for zip bundles)
│   ├── Program.cs              # Sender application & web server
│   └── sender-ui.html          # Embedded sender web UI
├── TunnelReceiver/
│   ├── TunnelReceiver.csproj   # Receiver global tool
│   ├── Program.cs              # Receiver application & proxy web server
│   └── receiver-ui.html        # Embedded receiver web UI
└── CloudShare.Tests/
    ├── CloudShare.Tests.csproj # Test project
    ├── DependencyManagerTests.cs
    └── VersionInfoTests.cs

📦 NuGet Packages

• Garrard.CloudShare.Sender - The sender tool
• Garrard.CloudShare.Receiver - The receiver tool

Install globally:

dotnet tool install --global Garrard.CloudShare.Sender
dotnet tool install --global Garrard.CloudShare.Receiver

Update:

dotnet tool update --global Garrard.CloudShare.Sender
dotnet tool update --global Garrard.CloudShare.Receiver

Uninstall:

dotnet tool uninstall --global Garrard.CloudShare.Sender
dotnet tool uninstall --global Garrard.CloudShare.Receiver

🐛 Troubleshooting

"DevTunnels CLI not found"

The tool will offer to install it automatically. If auto-install fails, install manually (see Prerequisites).

"Authentication required" / "Login token expired"

The sender automatically detects expired tokens and re-authenticates using your saved login preference. If the browser flow fails, run devtunnel user login -g (GitHub) or devtunnel user login (Microsoft) manually, then retry. To switch accounts use cloud-share-sender --reset.

"Connection refused"

• Ensure the sender is still running
• Verify you copied the complete tunnel URL
• Check your internet connection

"File not found"

Make sure you specified the file path when starting the sender:

cloud-share-sender /path/to/your/file.pdf

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

Garrard Kitchen

• GitHub: @garrardkitchen
• NuGet: garrardkitchen

🙏 Acknowledgments

• Built with .NET 10
• CLI powered by Spectre.Console
• Uses Microsoft Dev Tunnels for secure connectivity
• Tested with xUnit and Moq

🔗 Resources

• Microsoft Dev Tunnels Documentation
• .NET Documentation
• Spectre.Console Documentation
• GitHub Repository