This release is a pre-release and may not be stable for production use.
hivemind-usenet
An experimental HiveMind
transport over Usenet: anonymous, store-and-forward, censorship-resistant mesh
links carried by alt.anonymous.messages. Nodes post PGP-encrypted, hSub-addressed
articles to a newsgroup and poll for replies. There is no direct connection, no
shared IP, and no registered account on the public anon-post servers.
Usenet is high-latency and poll-based. Treat this as a covert or control-plane link, or as a fallback for nodes that are never reachable directly, not as a low-latency audio channel.
Where it sits
Standard HiveMind links are live encrypted WebSocket connections to a hivemind-core hub. hivemind-usenet swaps the carrier for Usenet and keeps the HiveMind handshake and AES session on top, unchanged. It ships three surfaces in one package:
UsenetCarrier: the shared framing layer. It chunks arbitrary payloads into roughly 8 KB base64 frames, PGP-encrypts each to the peer's key, posts under an hSub subject, and reassembles on poll. You can test it fully without a live NNTP connection.UsenetWormhole(aNetworkProtocol): the full HiveMessage transport. A point-to-point link whose poll loop reassembleskind="hive"frames and routes them throughhm_protocol.handle_message. It is registered under thehivemind.network.protocolentry point.UsenetBridge(athreading.Thread): a natural-language gateway. It polls a code-word hSub for text posts, injects them into the hive as utterances, and posts the spoken answers back. Per-peer session ids and per-session FIFO queues keep concurrent conversations separate.
A satellite-side client (UsenetClient) mirrors the HTTP/WS client API, so the
same connect/emit/run/close usage works over the Usenet carrier.
How it works
local node ◀──── UsenetCarrier (PGP + hSub frames) ────▶ peer node
post to alt.anonymous.messages
poll + match hSub + decrypt + reassemble
- Addressing is hSub (hashed subject): a shared passphrase per peer. The
sender stamps the subject with
create_hsub(peer_secret). The receiver filters articles withmatch_hsub(subject, my_secret). - Confidentiality is PGP. Each frame is encrypted to the peer's public key.
- Reassembly dedupes on
(message-id, chunk)and rebuilds the payload once all chunks arrive.
Prerequisites
- Python 3.10-3.12. The carrier's PGP crypto (
remailersto PGPy) imports the standard-libraryimghdrmodule, which was removed in Python 3.13 (PEP 594). The package is capped>=3.10,<3.13. See the security docs. - A PGP identity per node.
remailers.Credentialsgenerates one automatically at the configuredkey_pathif it is missing. - For each peer link, an out-of-band exchange of an hSub passphrase and the peer's PGP public key (see first contact).
- Network access to a Usenet server that accepts anonymous posts. This defaults
to
paganini.bofh.team.news.tcpreset.netalso accepts anonymous posts.
Install
pip install hivemind-usenet
From source:
git clone https://github.com/JarbasHiveMind/hivemind-usenet
cd hivemind-usenet
pip install -e .
This pulls in the usenet and remailers carrier libraries plus the HiveMind
packages.
Quickstart
Two nodes that have exchanged passphrases and public keys out of band:
# Wormhole node (full HiveMessage transport)
hivemind-usenet-wormhole \
--my-secret "my-passphrase" \
--peer-secret "their-passphrase" \
--peer-pubkey /path/to/peer.asc \
--server-url paganini.bofh.team
# NL bridge (text in/out of a local hive)
hivemind-usenet-bridge \
--my-secret "bridge-codeword" \
--hive-host 127.0.0.1 \
--hive-key "my-hivemind-api-key" \
--hive-password "my-hivemind-password"
--hive-key is the access key and --hive-password is the Noise PSK
password -- both are required to authenticate against a v3-Noise-only
HiveMind hub. The legacy crypto_key is not used for authentication.
--my-secret is the hSub passphrase you read with. --peer-secret is the
one you post with, and the peer reads it. They are the mirror image on the
other node.
First contact / hSub addressing
hSub addressing is shared-secret symmetric: both peers must agree on a passphrase and exchange PGP public keys out of band before any post. There is no in-band key exchange in v1. A discovery "lobby" hSub is a planned stretch goal.
Configuration
CLI flags map to config keys read by each component. See configuration for the full table and the JSON config-file form.
Documentation
See docs/:
- How it works: carrier framing, hSub, PGP, reassembly.
- Components: carrier, wormhole, bridge, client.
- Configuration: every CLI flag and config key.
- Security model: the two crypto layers, the threat model, and the Python 3.12 ceiling.
- Examples: the live-network demos under
examples/. - Testing & development: running the offline suite and how the end-to-end carrier is faked.
Related projects
- HiveMind-core: the hub this transport connects to.
- hivescope: the in-process HiveMind test harness used by this package's end-to-end tests.
Tests
All tests run offline. There is no live news server and no network. The
carrier's NNTP transport is the only thing faked. The end-to-end suite drives a
real hivemind-core master and satellite through a real handshake and bus
round-trip over the real UsenetCarrier. The package is capped at Python 3.12,
as noted above:
uv venv --python 3.12
uv pip install --prerelease=allow -e .[test]
uv run pytest tests/
See docs/testing.md for the full layout and how the carrier is faked.
License
Apache-2.0
Metadata
Release files for hivemind-usenet 0.1.5a1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hivemind_usenet-0.1.5a1.tar.gz | 29.1 kB | Without provenance | Details for hivemind_usenet-0.1.5a1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hivemind_usenet-0.1.5a1-py3-none-any.whl | Python 3 | none | any | Details for hivemind_usenet-0.1.5a1-py3-none-any.whl |
Total release size: 52.5 kB
Release files / hivemind_usenet-0.1.5a1.tar.gz
| Download URL | hivemind_usenet-0.1.5a1.tar.gz |
|---|---|
| Size | 29.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fe91ded2b9c3c1b27005060a58ee382bd97869849a97635ea8d15668e47d1640
|
|
BLAKE2b-256 checksum How to use checksums |
7c36cbeebbeb4757dfa5997ad01927eed7560dd00bd55d0fb8e3de1219fa8d47
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / hivemind_usenet-0.1.5a1-py3-none-any.whl
| Download URL | hivemind_usenet-0.1.5a1-py3-none-any.whl |
|---|---|
| Size | 23.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
87ce1edc6a736509e29bb3d15abc9163142e74376e4750b83012615f06a1da52
|
|
BLAKE2b-256 checksum How to use checksums |
6ac2f2e759dbe3fa44e7794bd2f8cc1e787ed38492d7af635bcee4d7b0c8317b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for hivemind-usenet 0.1.5a1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.