OnionShare

OnionShare is a cross‑platform, self‑hosted file transfer and web hosting utility built around the Tor anonymity network. From a developer’s standpoint, it exposes a minimal yet powerful API that abstracts away the complexities of Tor circuit management, onion service creation, and secure data transmission. The core workflow consists of generating a hidden‑service address (*.onion), binding the desired file or web content to that service, and optionally publishing a one‑time invitation URL. The application guarantees end‑to‑end encryption by leveraging Tor’s layered encryption and the underlying HTTP(S) layer, while preventing metadata leakage through careful socket handling.

• Language & Runtime: Python 3.11+ with the asyncio event loop, ensuring non‑blocking I/O for high‑throughput uploads.
• Frameworks: Uses aiohttp for HTTP server/client interactions, and the stem library to interface with Tor’s control port. The GUI is built with Qt 5 via PySide2, providing a consistent look across Windows, macOS, and Linux.
• Tor Integration: OnionShare relies on an external Tor process; it communicates over the control port to create temporary hidden services. No custom Tor code is bundled, which keeps the binary lean and eases maintenance.
• Data Storage: Uploaded files are stored in a temporary directory (/tmp/onionshare on Linux, %TEMP%\onionshare on Windows). The app can optionally serve static files from a user‑supplied directory, making it suitable for lightweight web hosting.
• Security Model: The application never writes to persistent storage beyond the temporary upload directory. All sockets are wrapped with TLS when possible, and the code enforces strict permission checks on file paths.

• Onion Service API: Exposes a simple context manager (with onionshare.create_service(...) as service:) that yields the .onion address, public key, and invitation URL. Developers can embed this in scripts to automate file sharing or host temporary sites.
• Event Hooks: Callbacks for on_upload_start, on_upload_complete, and on_connection allow custom logging or analytics without modifying the core.
• Rate Limiting & Bandwidth Control: Built‑in throttling options (--max-speed) let developers prevent a single transfer from saturating the network, useful in multi‑tenant environments.
• Multi‑protocol Support: Beyond HTTP/HTTPS, OnionShare can expose services over SSH (via onionshare‑ssh) or WebSocket for real‑time applications.

• Self‑Hosting: The application is designed to run as a single binary with no server daemon. For production use, it can be wrapped in a systemd service or Docker container (onionshare:onion). The container image is lightweight (~200 MB) and pulls a pre‑built Tor binary.
• Scalability: Each instance creates its own hidden service; scaling horizontally involves spinning up additional containers or VMs. Because Tor circuits are per‑process, there is no shared state that would require clustering.
• Resource Footprint: Minimal RAM usage (~100 MB) and CPU overhead, making it suitable for edge devices or embedded systems that need secure file sharing.

• Plugin System: Developers can extend OnionShare by writing Python plugins that hook into the event system. The plugin API is documented in docs/plugins.md, and a registry allows dynamic loading at runtime.
• Webhooks: After a successful upload, OnionShare can POST a JSON payload to a user‑defined URL. This is ideal for CI/CD pipelines that need to trigger downstream actions (e.g., decrypting the file, moving it to storage).
• Custom UI: The Qt GUI can be replaced or augmented with a headless mode (--no-gui) for automated scripts. The underlying logic is fully exposed via the onionshare Python package, enabling integration into larger applications.

• Configuration: All settings are exposed via a YAML file (~/.config/onionshare/config.yaml) and command‑line flags. The configuration schema is validated at startup, preventing misconfiguration.
• Documentation: The project hosts comprehensive docs on ReadTheDocs (docs.onionshare.org), covering architecture, API usage, and contribution guidelines. The source code is heavily annotated with type hints, aiding IDE autocomplete.
• Community & Support: An active GitHub community maintains issue triage, and the project follows semantic versioning. Contributors benefit from a clear contribution workflow and automated CI tests that run on every pull request.

1. Secure Data Exchange – Developers can embed OnionShare in a data‑collection pipeline where clients upload encrypted logs to a temporary onion service, ensuring anonymity and preventing ISP tracking.
2. Temporary Web Hosting – A DevOps engineer can spin up a quick preview server for code reviews, exposing the site over Tor without configuring DNS.
3. Chat & Collaboration – By combining OnionShare’s hidden‑service chat feature with a custom plugin, teams can build private, end‑to‑end encrypted communication channels.
4. Disaster Recovery – Organizations can deploy OnionShare on backup servers to receive critical files from field agents who must remain covert.

• Performance: Built on asyncio and lightweight libraries, OnionShare delivers low latency for small‑to‑medium uploads while remaining efficient under load.