Skip to main content
Pre-release

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 (a NetworkProtocol): the full HiveMessage transport. A point-to-point link whose poll loop reassembles kind="hive" frames and routes them through hm_protocol.handle_message. It is registered under the hivemind.network.protocol entry point.
  • UsenetBridge (a threading.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 with match_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 (remailers to PGPy) imports the standard-library imghdr module, 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.Credentials generates one automatically at the configured key_path if 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.net also 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/:

  • 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)

Source distribution for hivemind-usenet 0.1.5a1
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)

Table of built distributions (wheels) for hivemind-usenet 0.1.5a1
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page