hivemind-rendezvous 0.1.1a1__tar.gz

hivemind_rendezvous-0.1.1a1/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: hivemind-rendezvous
+Version: 0.1.1a1
+Summary: Async store-and-forward dead-drop rendezvous service for HiveMind nodes
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: hivemind-bus-client
+Requires-Dist: json-database>=0.10.2a1
+Requires-Dist: poorman-handshake
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+
+# hivemind-rendezvous
+
+An async **store-and-forward dead-drop** for [HiveMind](https://github.com/JarbasHiveMind/HiveMind-core)
+nodes that are never online at the same time. A sender deposits an encrypted
+message addressed to a recipient's public key; the recipient later proves
+ownership of that key and collects the message. No simultaneous connection, no
+shared IP, no persistent HiveMind session.
+
+## Where it sits
+
+Normal HiveMind links are live encrypted WebSocket connections between a satellite
+and a [hivemind-core](https://github.com/JarbasHiveMind/HiveMind-core) hub. That
+requires both ends to be reachable at once. hivemind-rendezvous fills the gap for
+nodes that are only intermittently online: it is a small neutral HTTP relay that
+holds [`INTERCOM`](https://github.com/JarbasHiveMind/hivemind-websocket-client)
+messages until the recipient comes back to fetch them.
+
+The relay never sees plaintext — messages are end-to-end encrypted to the
+recipient's public key before deposit. The relay only stores opaque blobs keyed by
+recipient pubkey and enforces ownership on retrieval.
+
+## How it works
+
+```
+Node A (sender)    Rendezvous node     Node B (recipient)
+     │                   │                    │
+     │-- POST /deposit -->│                    │
+     │   INTERCOM msg     │                    │
+     │   target=B.pubkey  │  (stored, TTL ≤7d) │
+     │                   │                    │
+     │           (time passes)                │
+     │                   │<-- POST /retrieve --│
+     │                   │    sign(B.privkey)  │
+     │                   │-- messages -------->│
+     │                   │   (deleted)         │
+```
+
+Authentication is **proof of RSA pubkey ownership**: to retrieve, a node signs a
+fresh timestamp with its private key. The relay verifies the signature against the
+claimed pubkey and the timestamp freshness (replay window), then returns and
+deletes the pending messages.
+
+## Prerequisites
+
+- Python 3.10+
+- An RSA identity for each node (handled by HiveMind / `poorman-handshake`).
+- A reachable host to run the relay (a small VPS, a Pi, or any always-on box the
+  intermittent nodes can reach over HTTP).
+
+## Install
+
+```bash
+pip install hivemind-rendezvous
+```
+
+From source:
+
+```bash
+git clone https://github.com/JarbasHiveMind/hivemind-rendezvous
+cd hivemind-rendezvous
+pip install -e .
+```
+
+## Quickstart
+
+Run the relay on an always-on host:
+
+```bash
+hivemind-rendezvous
+# Rendezvous server listening on 0.0.0.0:6789
+```
+
+That is the whole relay. Senders `POST /deposit` an INTERCOM message addressed to
+a recipient pubkey; recipients `POST /retrieve` with an ownership proof to collect
+them. See [HTTP API](docs/http-api.md) for the request bodies and
+[examples](docs/examples.md) for deposit/retrieve snippets.
+
+## Configuration
+
+`run_server()` arguments (and their defaults):
+
+| Argument | Default | Description |
+| --- | --- | --- |
+| `host` | `0.0.0.0` | Bind address. |
+| `port` | `6789` | Listen port. |
+| `node_pubkey` | `""` | This relay's own RSA pubkey (PEM), served at `/pubkey`. |
+| `deposit_rate_limit` | `60` | Max deposits per client IP per window. |
+| `deposit_rate_window` | `60` | Rate-limit window in seconds. |
+| `require_depositor_proof` | `False` | Require a valid depositor ownership proof on every deposit. |
+
+Message TTL is set per deposit (`ttl` field, default and hard cap **7 days**).
+
+## Documentation
+
+See [`docs/`](docs/index.md):
+
+- [How it works](docs/how-it-works.md) — deposit/retrieve flow and authentication.
+- [HTTP API](docs/http-api.md) — endpoints, request/response bodies, error codes.
+- [Deploy](docs/deploy.md) — running and configuring the relay.
+- [Examples](docs/examples.md) — deposit and retrieve from a client.
+
+## License
+
+Apache-2.0

hivemind_rendezvous-0.1.1a1/README.md

@@ -0,0 +1,104 @@
+# hivemind-rendezvous
+
+An async **store-and-forward dead-drop** for [HiveMind](https://github.com/JarbasHiveMind/HiveMind-core)
+nodes that are never online at the same time. A sender deposits an encrypted
+message addressed to a recipient's public key; the recipient later proves
+ownership of that key and collects the message. No simultaneous connection, no
+shared IP, no persistent HiveMind session.
+
+## Where it sits
+
+Normal HiveMind links are live encrypted WebSocket connections between a satellite
+and a [hivemind-core](https://github.com/JarbasHiveMind/HiveMind-core) hub. That
+requires both ends to be reachable at once. hivemind-rendezvous fills the gap for
+nodes that are only intermittently online: it is a small neutral HTTP relay that
+holds [`INTERCOM`](https://github.com/JarbasHiveMind/hivemind-websocket-client)
+messages until the recipient comes back to fetch them.
+
+The relay never sees plaintext — messages are end-to-end encrypted to the
+recipient's public key before deposit. The relay only stores opaque blobs keyed by
+recipient pubkey and enforces ownership on retrieval.
+
+## How it works
+
+```
+Node A (sender)    Rendezvous node     Node B (recipient)
+     │                   │                    │
+     │-- POST /deposit -->│                    │
+     │   INTERCOM msg     │                    │
+     │   target=B.pubkey  │  (stored, TTL ≤7d) │
+     │                   │                    │
+     │           (time passes)                │
+     │                   │<-- POST /retrieve --│
+     │                   │    sign(B.privkey)  │
+     │                   │-- messages -------->│
+     │                   │   (deleted)         │
+```
+
+Authentication is **proof of RSA pubkey ownership**: to retrieve, a node signs a
+fresh timestamp with its private key. The relay verifies the signature against the
+claimed pubkey and the timestamp freshness (replay window), then returns and
+deletes the pending messages.
+
+## Prerequisites
+
+- Python 3.10+
+- An RSA identity for each node (handled by HiveMind / `poorman-handshake`).
+- A reachable host to run the relay (a small VPS, a Pi, or any always-on box the
+  intermittent nodes can reach over HTTP).
+
+## Install
+
+```bash
+pip install hivemind-rendezvous
+```
+
+From source:
+
+```bash
+git clone https://github.com/JarbasHiveMind/hivemind-rendezvous
+cd hivemind-rendezvous
+pip install -e .
+```
+
+## Quickstart
+
+Run the relay on an always-on host:
+
+```bash
+hivemind-rendezvous
+# Rendezvous server listening on 0.0.0.0:6789
+```
+
+That is the whole relay. Senders `POST /deposit` an INTERCOM message addressed to
+a recipient pubkey; recipients `POST /retrieve` with an ownership proof to collect
+them. See [HTTP API](docs/http-api.md) for the request bodies and
+[examples](docs/examples.md) for deposit/retrieve snippets.
+
+## Configuration
+
+`run_server()` arguments (and their defaults):
+
+| Argument | Default | Description |
+| --- | --- | --- |
+| `host` | `0.0.0.0` | Bind address. |
+| `port` | `6789` | Listen port. |
+| `node_pubkey` | `""` | This relay's own RSA pubkey (PEM), served at `/pubkey`. |
+| `deposit_rate_limit` | `60` | Max deposits per client IP per window. |
+| `deposit_rate_window` | `60` | Rate-limit window in seconds. |
+| `require_depositor_proof` | `False` | Require a valid depositor ownership proof on every deposit. |
+
+Message TTL is set per deposit (`ttl` field, default and hard cap **7 days**).
+
+## Documentation
+
+See [`docs/`](docs/index.md):
+
+- [How it works](docs/how-it-works.md) — deposit/retrieve flow and authentication.
+- [HTTP API](docs/http-api.md) — endpoints, request/response bodies, error codes.
+- [Deploy](docs/deploy.md) — running and configuring the relay.
+- [Examples](docs/examples.md) — deposit and retrieve from a client.
+
+## License
+
+Apache-2.0

hivemind_rendezvous-0.1.1a1/hivemind_rendezvous/__init__.py

@@ -0,0 +1,18 @@
+"""hivemind-rendezvous — async store-and-forward dead drop for HiveMind nodes.
+
+Nodes from different, non-simultaneously-connected hives can exchange INTERCOM
+messages via a shared rendezvous point.  The sender deposits a message keyed by
+the recipient's RSA public key; the recipient retrieves it later by proving
+pubkey ownership (signed timestamp, no server-side challenge state).
+
+Submodules:
+    auth     — :func:`~hivemind_rendezvous.auth.sign_ownership` /
+               :func:`~hivemind_rendezvous.auth.verify_ownership`
+    storage  — :class:`~hivemind_rendezvous.storage.RendezvousStore`
+    server   — :func:`~hivemind_rendezvous.server.run_server`
+"""
+
+from hivemind_rendezvous.version import VERSION
+
+__version__ = VERSION
+__all__ = ["VERSION"]

hivemind_rendezvous-0.1.1a1/hivemind_rendezvous/auth.py

@@ -0,0 +1,102 @@
+"""Proof-of-pubkey-ownership authentication for the rendezvous service.
+
+Stateless, single-round-trip: the client signs a domain-separated message:
+
+    ``b"hivemind-rendezvous-v1\\x00" + pubkey_bytes + b"\\x00"
+      + server_pubkey_bytes + b"\\x00" + timestamp_bytes``
+
+The server verifies the signature and rejects timestamps outside a ±60 second
+window to prevent replay attacks.  Binding the server's own pubkey into the
+signed message prevents cross-server replay: a valid proof issued to one
+rendezvous node cannot be replayed at another.
+"""
+
+import base64
+import time
+from typing import Union
+
+from poorman_handshake.asymmetric.utils import sign_RSA, verify_RSA
+
+
+_TIMESTAMP_TOLERANCE_SECONDS: int = 60
+_DOMAIN: bytes = b"hivemind-rendezvous-v1\x00"
+
+
+def _ownership_message(pubkey: str, timestamp: int, server_pubkey: str = "") -> bytes:
+    """Return the canonical byte string that is signed/verified for ownership proof.
+
+    The message is domain-separated and binds the server's public key to prevent
+    cross-server replay attacks.
+
+    Format (bytes, null-delimited fields):
+    ``DOMAIN || claimer_pubkey || 0x00 || server_pubkey || 0x00 || timestamp_decimal``
+
+    Args:
+        pubkey: PEM-encoded RSA public key of the claiming node.
+        timestamp: Unix timestamp (integer seconds).
+        server_pubkey: PEM-encoded RSA public key of the rendezvous server.
+            Empty string when server identity binding is not used (legacy / testing).
+
+    Returns:
+        The message bytes to sign or verify.
+    """
+    return (
+        _DOMAIN
+        + pubkey.encode("utf-8") + b"\x00"
+        + server_pubkey.encode("utf-8") + b"\x00"
+        + str(timestamp).encode("utf-8")
+    )
+
+
+def sign_ownership(private_key: Union[str, bytes], pubkey: str, timestamp: int,
+                   server_pubkey: str = "") -> str:
+    """Produce a base64-encoded ownership proof signature.
+
+    Args:
+        private_key: RSA private key (PEM string, bytes, or RsaKey) of the claimer.
+        pubkey: PEM-encoded RSA public key of the claimer.
+        timestamp: Unix timestamp (integer seconds) to embed in the proof.
+        server_pubkey: PEM-encoded RSA public key of the rendezvous server.
+            Binds the proof to a specific server — must match the value used
+            by the server in :func:`verify_ownership`.
+
+    Returns:
+        Base64-encoded signature string suitable for JSON transport.
+    """
+    message = _ownership_message(pubkey, timestamp, server_pubkey)
+    signature_bytes = sign_RSA(private_key, message)
+    return base64.b64encode(signature_bytes).decode("utf-8")
+
+
+def verify_ownership(pubkey: str, timestamp: int, signature: str,
+                     server_pubkey: str = "") -> bool:
+    """Verify a proof-of-pubkey-ownership claim.
+
+    Checks both signature validity and timestamp freshness.  A valid proof
+    requires:
+
+    1. The signature over the domain-separated message verifies against
+       ``pubkey``.
+    2. ``abs(now - timestamp) <= 60`` seconds (replay protection).
+    3. ``server_pubkey`` in the signed message matches the value passed here
+       (cross-server replay protection).
+
+    Args:
+        pubkey: PEM-encoded RSA public key of the claiming node.
+        timestamp: Unix timestamp (integer seconds) embedded in the proof.
+        signature: Base64-encoded signature produced by :func:`sign_ownership`.
+        server_pubkey: PEM-encoded RSA public key of the rendezvous server
+            that was used when signing.  Must be supplied by the server itself.
+
+    Returns:
+        ``True`` if the proof is valid and fresh; ``False`` otherwise.
+    """
+    now = int(time.time())
+    if abs(now - timestamp) > _TIMESTAMP_TOLERANCE_SECONDS:
+        return False
+    try:
+        signature_bytes = base64.b64decode(signature)
+    except Exception:
+        return False
+    message = _ownership_message(pubkey, timestamp, server_pubkey)
+    return verify_RSA(pubkey, message, signature_bytes)