mesh-peer-registry

A small, shared, language-agnostic peer registry for the mesh network used by hermes-mesh and openclaw-mesh.

Peers register with an Ed25519 public key and a webhook URL, then discover each other over a simple HTTP API. The server never holds private keys.

About

mesh-peer-registry provides a centralized but state-light way for mesh agents to announce themselves to one another:

• Peers register an Ed25519 public key and a webhook URL under a unique name.
• Registration, deregistration, and refresh requests are signed by the peer's private key, so the registry can trust the public key it stores.
• Other peers query the registry to find a recipient's webhook URL and public key.
• Mesh messages are signed by the sender and verified by the receiver against the sender's public key from the registry.

The signing protocol uses compact, deterministic, sorted-key JSON, making it straightforward to implement in other runtimes (e.g. the Node.js implementation in openclaw-mesh).

Features

• HTTP API for register, list, get, refresh, and deregister operations.
• Ed25519 signatures on all mutating requests.
• SQLite-backed store by default, with the path configurable via --store.
• TTL + reaper — peers can register with a TTL in seconds; a background reaper removes expired peers and refreshes keep them alive.
• CLI server launcher.
• Python client (RegistryClient) with built-in signing.
• No private keys kept by the registry.

Quick start

Install and run the server over plain HTTP for local development:

pip install mesh-peer-registry
MESH_REGISTRY_ALLOW_INSECURE=1 mesh-peer-registry --port 8646 --store ~/.mesh/registry.sqlite

The server will listen on http://127.0.0.1:8646 and store peers in ~/.mesh/registry.sqlite.

For production, serve over HTTPS with --ssl-cert / --ssl-key and set MESH_REGISTRY_HSTS=1 to emit Strict-Transport-Security headers.

CLI options

Environment variables mirror the flags and middleware settings:

• MESH_REGISTRY_ALLOW_INSECURE — set to 1 to allow plain HTTP requests.
• MESH_REGISTRY_BEHIND_PROXY — set to 1 to enable proxy header handling.
• MESH_REGISTRY_RATE_LIMIT — per-IP registration limit per minute (0 disables).
• MESH_REGISTRY_HSTS — set to 1 to emit HSTS headers.
• MESH_REGISTRY_PIN — when set, the client verifies the server certificate SPKI matches this SHA-256 hex digest.

API

All registration, refresh, and deregistration requests must include a valid Ed25519 signature in the X-Mesh-Signature header over the sorted JSON body (or the action payload for refresh/deregister).

Python client

from mesh_peer_registry.crypto import generate_keypair
from mesh_peer_registry.client import RegistryClient

private, public = generate_keypair()

# For plain HTTP development, allow_insecure=True is required unless the
# server is configured with MESH_REGISTRY_ALLOW_INSECURE=1.
client = RegistryClient(
    "http://127.0.0.1:8646",
    private,
    public,
    allow_insecure=True,
    pin=None,
)

# For HTTPS production with certificate pinning:
# client = RegistryClient(
#     "https://registry.example.com",
#     private,
#     public,
#     pin="sha256-hex-of-server-certificate-spki",
# )

client.register(
    "agent0",
    "http://127.0.0.1:8645/mesh/receive",
    role="operator",
    description="Hermes operator node",
    ttl=3600,
)

print(client.list_peers())

# Keep the registration alive before the TTL expires.
client.refresh("agent0")

# Later, deregister.
client.deregister("agent0")

Verifying a message

Receivers fetch the sender's public key from the registry and verify the X-Mesh-Signature header:

from mesh_peer_registry.crypto import verify_message
from mesh_peer_registry.client import RegistryClient

# Read-only lookup can use an empty keypair and allow_insecure for local HTTP.
client = RegistryClient(
    "http://127.0.0.1:8646",
    "",
    "",
    allow_insecure=True,
)
peer = client.get_peer("agent0")

# body is the raw request body; signature is from the X-Mesh-Signature header.
ok = verify_message(peer.public_key, body, signature)

When X-Mesh-Timestamp is included in the signed payload (optional, controlled by MESH_SIGN_TIMESTAMP on the sender), the receiver should prepend f"{timestamp}\n" to the body before verification. Backward-compatible receivers try both forms.

Development

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

License

MIT