genesis-mesh 0.5.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- genesis_mesh-0.5.0/LICENSE +21 -0
- genesis_mesh-0.5.0/PKG-INFO +338 -0
- genesis_mesh-0.5.0/README.md +284 -0
- genesis_mesh-0.5.0/genesis_mesh/__init__.py +3 -0
- genesis_mesh-0.5.0/genesis_mesh/audit/__init__.py +5 -0
- genesis_mesh-0.5.0/genesis_mesh/audit/logger.py +395 -0
- genesis_mesh-0.5.0/genesis_mesh/cli/__init__.py +5 -0
- genesis_mesh-0.5.0/genesis_mesh/cli/__main__.py +6 -0
- genesis_mesh-0.5.0/genesis_mesh/cli/config.py +98 -0
- genesis_mesh-0.5.0/genesis_mesh/cli/main.py +254 -0
- genesis_mesh-0.5.0/genesis_mesh/cli/node_cmd.py +166 -0
- genesis_mesh-0.5.0/genesis_mesh/cli/ops.py +601 -0
- genesis_mesh-0.5.0/genesis_mesh/crypto/__init__.py +17 -0
- genesis_mesh-0.5.0/genesis_mesh/crypto/keys.py +135 -0
- genesis_mesh-0.5.0/genesis_mesh/crypto/signing.py +101 -0
- genesis_mesh-0.5.0/genesis_mesh/gossip/__init__.py +5 -0
- genesis_mesh-0.5.0/genesis_mesh/gossip/crl_gossip.py +379 -0
- genesis_mesh-0.5.0/genesis_mesh/models/__init__.py +22 -0
- genesis_mesh-0.5.0/genesis_mesh/models/certificates.py +75 -0
- genesis_mesh-0.5.0/genesis_mesh/models/control_plane.py +162 -0
- genesis_mesh-0.5.0/genesis_mesh/models/enrollment.py +21 -0
- genesis_mesh-0.5.0/genesis_mesh/models/genesis.py +69 -0
- genesis_mesh-0.5.0/genesis_mesh/models/policy.py +50 -0
- genesis_mesh-0.5.0/genesis_mesh/models/revocation.py +101 -0
- genesis_mesh-0.5.0/genesis_mesh/monitoring/__init__.py +11 -0
- genesis_mesh-0.5.0/genesis_mesh/monitoring/health.py +421 -0
- genesis_mesh-0.5.0/genesis_mesh/monitoring/metrics.py +342 -0
- genesis_mesh-0.5.0/genesis_mesh/na_service/__init__.py +5 -0
- genesis_mesh-0.5.0/genesis_mesh/na_service/__main__.py +6 -0
- genesis_mesh-0.5.0/genesis_mesh/na_service/auth.py +218 -0
- genesis_mesh-0.5.0/genesis_mesh/na_service/db.py +406 -0
- genesis_mesh-0.5.0/genesis_mesh/na_service/rate_limit.py +23 -0
- genesis_mesh-0.5.0/genesis_mesh/na_service/routes/__init__.py +15 -0
- genesis_mesh-0.5.0/genesis_mesh/na_service/routes/admin.py +211 -0
- genesis_mesh-0.5.0/genesis_mesh/na_service/routes/crl.py +24 -0
- genesis_mesh-0.5.0/genesis_mesh/na_service/routes/enrollment.py +342 -0
- genesis_mesh-0.5.0/genesis_mesh/na_service/routes/health.py +110 -0
- genesis_mesh-0.5.0/genesis_mesh/na_service/routes/public.py +363 -0
- genesis_mesh-0.5.0/genesis_mesh/na_service/server.py +250 -0
- genesis_mesh-0.5.0/genesis_mesh/na_service/wsgi.py +34 -0
- genesis_mesh-0.5.0/genesis_mesh/node/__init__.py +5 -0
- genesis_mesh-0.5.0/genesis_mesh/node/__main__.py +7 -0
- genesis_mesh-0.5.0/genesis_mesh/node/cert_manager.py +230 -0
- genesis_mesh-0.5.0/genesis_mesh/node/control_commands.py +210 -0
- genesis_mesh-0.5.0/genesis_mesh/node/control_handler.py +262 -0
- genesis_mesh-0.5.0/genesis_mesh/node/discovery.py +346 -0
- genesis_mesh-0.5.0/genesis_mesh/node/dispatcher.py +75 -0
- genesis_mesh-0.5.0/genesis_mesh/node/node.py +402 -0
- genesis_mesh-0.5.0/genesis_mesh/node/peer_identity.py +163 -0
- genesis_mesh-0.5.0/genesis_mesh/node/peer_manager.py +304 -0
- genesis_mesh-0.5.0/genesis_mesh/node/persistent_runner.py +73 -0
- genesis_mesh-0.5.0/genesis_mesh/node/rbac.py +220 -0
- genesis_mesh-0.5.0/genesis_mesh/node/runtime.py +531 -0
- genesis_mesh-0.5.0/genesis_mesh/routing/__init__.py +12 -0
- genesis_mesh-0.5.0/genesis_mesh/routing/protocol.py +231 -0
- genesis_mesh-0.5.0/genesis_mesh/routing/router.py +225 -0
- genesis_mesh-0.5.0/genesis_mesh/routing/table.py +321 -0
- genesis_mesh-0.5.0/genesis_mesh/transport/__init__.py +22 -0
- genesis_mesh-0.5.0/genesis_mesh/transport/connection.py +379 -0
- genesis_mesh-0.5.0/genesis_mesh/transport/heartbeat.py +75 -0
- genesis_mesh-0.5.0/genesis_mesh/transport/noise_handshake.py +185 -0
- genesis_mesh-0.5.0/genesis_mesh/transport/protocol.py +237 -0
- genesis_mesh-0.5.0/genesis_mesh/transport/websocket_transport.py +170 -0
- genesis_mesh-0.5.0/genesis_mesh.egg-info/PKG-INFO +338 -0
- genesis_mesh-0.5.0/genesis_mesh.egg-info/SOURCES.txt +70 -0
- genesis_mesh-0.5.0/genesis_mesh.egg-info/dependency_links.txt +1 -0
- genesis_mesh-0.5.0/genesis_mesh.egg-info/entry_points.txt +4 -0
- genesis_mesh-0.5.0/genesis_mesh.egg-info/requires.txt +23 -0
- genesis_mesh-0.5.0/genesis_mesh.egg-info/top_level.txt +1 -0
- genesis_mesh-0.5.0/pyproject.toml +90 -0
- genesis_mesh-0.5.0/setup.cfg +4 -0
- genesis_mesh-0.5.0/setup.py +5 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,338 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: genesis-mesh
|
|
3
|
+
Version: 0.5.0
|
|
4
|
+
Summary: Sovereign trust, identity, and communication fabric for AI agents, edge systems, and distributed infrastructure.
|
|
5
|
+
Author-email: Thaer Saidi <thaer.saidi@outlook.com>
|
|
6
|
+
Maintainer-email: Thaer Saidi <thaer.saidi@outlook.com>
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
Project-URL: Homepage, https://genesismesh.connectorzzz.com
|
|
9
|
+
Project-URL: Documentation, https://genesismesh.connectorzzz.com
|
|
10
|
+
Project-URL: Repository, https://github.com/thaersaidi/genesismesh
|
|
11
|
+
Project-URL: Issues, https://github.com/thaersaidi/genesismesh/issues
|
|
12
|
+
Project-URL: Releases, https://github.com/thaersaidi/genesismesh/releases
|
|
13
|
+
Project-URL: Live Deployment, https://na.genesismesh.connectorzzz.com
|
|
14
|
+
Keywords: mesh,p2p,noise-protocol,ed25519,decentralized,trust,identity,revocation,sovereign,agents
|
|
15
|
+
Classifier: Development Status :: 4 - Beta
|
|
16
|
+
Classifier: Environment :: Console
|
|
17
|
+
Classifier: Intended Audience :: Developers
|
|
18
|
+
Classifier: Intended Audience :: System Administrators
|
|
19
|
+
Classifier: Topic :: System :: Networking
|
|
20
|
+
Classifier: Topic :: Security :: Cryptography
|
|
21
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
22
|
+
Classifier: Operating System :: MacOS
|
|
23
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
24
|
+
Classifier: Programming Language :: Python :: 3
|
|
25
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
26
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
27
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
28
|
+
Classifier: Framework :: Flask
|
|
29
|
+
Requires-Python: >=3.12
|
|
30
|
+
Description-Content-Type: text/markdown
|
|
31
|
+
License-File: LICENSE
|
|
32
|
+
Requires-Dist: cryptography==48.0.0
|
|
33
|
+
Requires-Dist: PyNaCl==1.6.2
|
|
34
|
+
Requires-Dist: requests==2.34.2
|
|
35
|
+
Requires-Dist: Flask==3.1.3
|
|
36
|
+
Requires-Dist: pydantic==2.13.4
|
|
37
|
+
Requires-Dist: python-dateutil==2.9.0.post0
|
|
38
|
+
Requires-Dist: click==8.4.1
|
|
39
|
+
Requires-Dist: dissononce==0.34.3
|
|
40
|
+
Requires-Dist: websockets==16.0
|
|
41
|
+
Requires-Dist: gunicorn==22.0.0
|
|
42
|
+
Provides-Extra: dev
|
|
43
|
+
Requires-Dist: pytest==9.0.3; extra == "dev"
|
|
44
|
+
Requires-Dist: pytest-asyncio==1.4.0; extra == "dev"
|
|
45
|
+
Requires-Dist: mypy==2.1.0; extra == "dev"
|
|
46
|
+
Requires-Dist: pip-audit==2.10.0; extra == "dev"
|
|
47
|
+
Requires-Dist: pre-commit==4.4.0; extra == "dev"
|
|
48
|
+
Provides-Extra: docs
|
|
49
|
+
Requires-Dist: sphinx==9.1.0; extra == "docs"
|
|
50
|
+
Requires-Dist: furo==2025.12.19; extra == "docs"
|
|
51
|
+
Requires-Dist: myst-parser==5.1.0; extra == "docs"
|
|
52
|
+
Requires-Dist: sphinxcontrib-mermaid==2.0.2; extra == "docs"
|
|
53
|
+
Dynamic: license-file
|
|
54
|
+
|
|
55
|
+
# Genesis Mesh
|
|
56
|
+
|
|
57
|
+
[](https://genesismesh.connectorzzz.com)
|
|
58
|
+
[](LICENSE)
|
|
59
|
+
[](https://github.com/thaersaidi/genesismesh/releases)
|
|
60
|
+
|
|
61
|
+
## Live Deployment
|
|
62
|
+
|
|
63
|
+
| | |
|
|
64
|
+
|---|---|
|
|
65
|
+
| Network Authority | Online |
|
|
66
|
+
| Public Endpoint | https://na.genesismesh.connectorzzz.com |
|
|
67
|
+
| Deployment | Azure VM, Sweden Central |
|
|
68
|
+
| TLS | Enabled |
|
|
69
|
+
| Active Nodes | 2 |
|
|
70
|
+
| Tracked Nodes | 2 |
|
|
71
|
+
| Remote Nodes | 1 |
|
|
72
|
+
| Online since | 2026-05-30 |
|
|
73
|
+
|
|
74
|
+
Current deployment demonstrates:
|
|
75
|
+
|
|
76
|
+
- Identity and certificate-based enrollment
|
|
77
|
+
- Remote nodes across separate networks
|
|
78
|
+
- Noise XX encrypted peer sessions
|
|
79
|
+
- Direct message delivery
|
|
80
|
+
- Multi-hop routing and packet forwarding
|
|
81
|
+
- Route failure recovery
|
|
82
|
+
- Certificate revocation and CRL enforcement
|
|
83
|
+
|
|
84
|
+

|
|
85
|
+
|
|
86
|
+

|
|
87
|
+
|
|
88
|
+
## Live Message Delivery
|
|
89
|
+
|
|
90
|
+
A remote local node sends a DATA message to an Azure-hosted node over a Noise XX encrypted peer session.
|
|
91
|
+
|
|
92
|
+

|
|
93
|
+
|
|
94
|
+
- Noise XX handshake completed
|
|
95
|
+
- Connection established
|
|
96
|
+
- Neighbor added
|
|
97
|
+
- DATA message delivered
|
|
98
|
+
|
|
99
|
+
## Multi-Hop Routing
|
|
100
|
+
|
|
101
|
+
Genesis Mesh supports decentralized route propagation and packet forwarding.
|
|
102
|
+
|
|
103
|
+
Node A and Node C do not connect directly. Instead:
|
|
104
|
+
|
|
105
|
+
**Node A → Node B → Node C**
|
|
106
|
+
|
|
107
|
+
Node B learns routes, forwards packets, and decrements TTL values during transit.
|
|
108
|
+
|
|
109
|
+

|
|
110
|
+
|
|
111
|
+
- Route learned via intermediate node
|
|
112
|
+
- DATA forwarded by router
|
|
113
|
+
- DATA delivered to destination
|
|
114
|
+
|
|
115
|
+
## Route Failure Recovery
|
|
116
|
+
|
|
117
|
+
When a router goes offline, neighboring nodes withdraw its routes and traffic re-routes through a surviving path — no operator intervention.
|
|
118
|
+
|
|
119
|
+
**Topology:** A reaches C through two routers — B (primary) and D (backup). B is killed mid-demo.
|
|
120
|
+
|
|
121
|
+

|
|
122
|
+
|
|
123
|
+
- Primary path A → B → C delivers
|
|
124
|
+
- B goes offline
|
|
125
|
+
- A detects the disconnect and invalidates B's routes
|
|
126
|
+
- A → D → C delivers without retry or operator action
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+

|
|
130
|
+
|
|
131
|
+
**Trust can be revoked.**
|
|
132
|
+
|
|
133
|
+
A revoked node is removed from the active set, added to a signed CRL, and
|
|
134
|
+
immediately rejected by heartbeat, renewal, handshake, and routing checks.
|
|
135
|
+
|
|
136
|
+
Genesis Mesh treats revocation as a first-class control-plane action. When an
|
|
137
|
+
operator revokes a certificate, the Network Authority publishes a new signed
|
|
138
|
+
CRL, removes the node from the active set, and rejects further heartbeat,
|
|
139
|
+
renewal, peer handshake, and routing activity from that identity.
|
|
140
|
+
|
|
141
|
+
---
|
|
142
|
+
|
|
143
|
+
Genesis Mesh is a sovereign trust, identity, and communication fabric for AI
|
|
144
|
+
agents, edge systems, and distributed infrastructure.
|
|
145
|
+
|
|
146
|
+
It answers the operational questions that basic mesh networking leaves open:
|
|
147
|
+
who is allowed to be a node, how peers prove identity, what each node is
|
|
148
|
+
allowed to do, how messages reach the right peer, and how a compromised or
|
|
149
|
+
retired identity is removed.
|
|
150
|
+
|
|
151
|
+
Genesis Mesh combines five capabilities in one trust fabric:
|
|
152
|
+
|
|
153
|
+
- **Identity**: every node has an Ed25519 identity and a signed join certificate.
|
|
154
|
+
- **Trust**: a signed genesis block, Network Authority, operator keys, and CRLs
|
|
155
|
+
define who the network trusts.
|
|
156
|
+
- **Routing**: authenticated peers discover routes and forward messages without
|
|
157
|
+
depending on the Network Authority for every data exchange.
|
|
158
|
+
- **Authorization**: enrollment roles, policy manifests, RBAC, and signed admin
|
|
159
|
+
actions define what identities may do.
|
|
160
|
+
- **Sovereignty**: the operator owns the trust chain, membership process,
|
|
161
|
+
revocation process, and policy distribution path.
|
|
162
|
+
|
|
163
|
+
Every enrolled node holds a signed join certificate issued by the Network
|
|
164
|
+
Authority. Peer sessions are encrypted with the Noise XX protocol, deriving
|
|
165
|
+
X25519 keys directly from each node's Ed25519 identity. No separate TLS
|
|
166
|
+
certificate lifecycle is required for peer transport.
|
|
167
|
+
|
|
168
|
+
## Why It Exists
|
|
169
|
+
|
|
170
|
+
Most overlay networks focus on connectivity: can this machine reach that
|
|
171
|
+
machine? Genesis Mesh focuses on controlled participation: should this machine
|
|
172
|
+
be here, what identity is it using, what is it authorized to do, and can the
|
|
173
|
+
network remove it quickly?
|
|
174
|
+
|
|
175
|
+
Use Genesis Mesh when your system needs:
|
|
176
|
+
|
|
177
|
+
- a private trust domain for agents, devices, or edge services
|
|
178
|
+
- operator-controlled enrollment instead of open peer discovery
|
|
179
|
+
- certificate-backed peer authentication
|
|
180
|
+
- signed policy distribution
|
|
181
|
+
- revocation that affects heartbeats, renewal, peer handshakes, and routing
|
|
182
|
+
- audit trails for security-relevant control-plane actions
|
|
183
|
+
|
|
184
|
+
Do not use it when you only need public peer discovery, anonymous networking, a
|
|
185
|
+
general service mesh for Kubernetes ingress, or a permissionless blockchain.
|
|
186
|
+
|
|
187
|
+
## Architecture
|
|
188
|
+
|
|
189
|
+
```mermaid
|
|
190
|
+
flowchart TD
|
|
191
|
+
RS["Root Sovereign<br/>offline trust anchor"]
|
|
192
|
+
NA["Network Authority<br/>invite enrollment, certs, CRLs, policy"]
|
|
193
|
+
A["Node A"]
|
|
194
|
+
B["Node B"]
|
|
195
|
+
C["Node C"]
|
|
196
|
+
|
|
197
|
+
RS -->|"signs genesis"| NA
|
|
198
|
+
NA -->|"invite token + join certificate"| A
|
|
199
|
+
NA -->|"invite token + join certificate"| B
|
|
200
|
+
NA -->|"invite token + join certificate"| C
|
|
201
|
+
|
|
202
|
+
A <-->|"Noise XX encrypted peer session"| B
|
|
203
|
+
B <-->|"Noise XX encrypted peer session"| C
|
|
204
|
+
A <-->|"Noise XX encrypted peer session"| C
|
|
205
|
+
|
|
206
|
+
NA -.->|"signed CRL bootstrap"| A
|
|
207
|
+
A -.->|"CRL gossip"| B
|
|
208
|
+
B -.->|"CRL gossip"| C
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
At a high level, the Network Authority admits identities and publishes trust
|
|
212
|
+
state. Nodes use that state to communicate directly, route messages, and reject
|
|
213
|
+
revoked peers.
|
|
214
|
+
|
|
215
|
+
## Documentation
|
|
216
|
+
|
|
217
|
+
[Documentation Website](https://genesismesh.connectorzzz.com)
|
|
218
|
+
|
|
219
|
+
## Requirements
|
|
220
|
+
|
|
221
|
+
- Python 3.12 or later
|
|
222
|
+
- See `requirements.txt` for pinned runtime dependencies
|
|
223
|
+
|
|
224
|
+
## Installation
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
python -m venv .venv
|
|
228
|
+
source .venv/bin/activate # PowerShell: .\.venv\Scripts\Activate.ps1
|
|
229
|
+
pip install -r requirements.txt
|
|
230
|
+
pip install -e .
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
## Quick Start
|
|
234
|
+
|
|
235
|
+
The local workflow runs the NA in one terminal and joins a node in a second.
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
# Create keys, genesis block, and CLI config (one time).
|
|
239
|
+
genesis-mesh init
|
|
240
|
+
|
|
241
|
+
# Start the Network Authority (keep this terminal open).
|
|
242
|
+
genesis-mesh na start
|
|
243
|
+
|
|
244
|
+
# In a second terminal: create a single-use invite and join.
|
|
245
|
+
INVITE_TOKEN=$(genesis-mesh admin invite --role anchor)
|
|
246
|
+
genesis-mesh join --na http://127.0.0.1:8443 --token "$INVITE_TOKEN"
|
|
247
|
+
|
|
248
|
+
# Inspect NA health and node certificate state.
|
|
249
|
+
genesis-mesh status
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
PowerShell:
|
|
253
|
+
|
|
254
|
+
```powershell
|
|
255
|
+
$INVITE_TOKEN = genesis-mesh admin invite --role anchor
|
|
256
|
+
genesis-mesh join --na http://127.0.0.1:8443 --token $INVITE_TOKEN
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
Full local smoke test:
|
|
260
|
+
|
|
261
|
+
```bash
|
|
262
|
+
genesis-mesh dev up
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
## Production Deployment
|
|
266
|
+
|
|
267
|
+
Container startup uses `start.sh` and Gunicorn. Set `SERVICE_ROLE=na` for the
|
|
268
|
+
Network Authority or `SERVICE_ROLE=node` for a peer node. The NA role requires
|
|
269
|
+
two mounted secrets and fails closed if either is absent:
|
|
270
|
+
|
|
271
|
+
| Environment variable | Description |
|
|
272
|
+
|---------------------------|--------------------------------------------------|
|
|
273
|
+
| `SERVICE_ROLE` | `na` or `node` |
|
|
274
|
+
| `GENESIS_FILE` | Path to the signed genesis block |
|
|
275
|
+
| `NA_PRIVATE_KEY_FILE` | Path to the NA Ed25519 signing key (NA role) |
|
|
276
|
+
| `OPERATOR_PUBLIC_KEYS_JSON` | JSON map of operator key IDs to public keys |
|
|
277
|
+
| `DB_PATH` | SQLite database path (default: `genesis_mesh_na.db`) |
|
|
278
|
+
| `PORT` | Bind port (default: `8443`) |
|
|
279
|
+
| `WEB_CONCURRENCY` | Gunicorn worker count (default: `4`) |
|
|
280
|
+
|
|
281
|
+
The NA private key never leaves the NA process.
|
|
282
|
+
|
|
283
|
+
Health and readiness probes are available at `/healthz` and `/readyz`.
|
|
284
|
+
|
|
285
|
+
## Deployment Examples
|
|
286
|
+
|
|
287
|
+
Genesis Mesh includes deployment examples for:
|
|
288
|
+
|
|
289
|
+
- **Local process** — `genesis-mesh init && genesis-mesh na start`
|
|
290
|
+
- **Docker** — `docker run` and Docker Compose (`docs/examples/compose/`)
|
|
291
|
+
- **Kubernetes** — manifests under `examples/kubernetes/`
|
|
292
|
+
- **Terraform on Azure** — `infrastructure/azure/`, the same module used by the live deployment
|
|
293
|
+
|
|
294
|
+
See the [deployment guide](https://genesismesh.connectorzzz.com/operations/deployment.html) for the full walkthrough.
|
|
295
|
+
|
|
296
|
+
## Repository Layout
|
|
297
|
+
|
|
298
|
+
```
|
|
299
|
+
.
|
|
300
|
+
Dockerfile Container image definition
|
|
301
|
+
start.sh Container entry point (NA and node roles)
|
|
302
|
+
requirements.txt Pinned runtime dependencies
|
|
303
|
+
setup.py Package metadata and entry points
|
|
304
|
+
docs/ Sphinx documentation source
|
|
305
|
+
examples/ Demo workflows, sample genesis blocks, Kubernetes manifests
|
|
306
|
+
genesis_mesh/ Python package
|
|
307
|
+
infrastructure/ Terraform, Azure scripts, and operational tools
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
```
|
|
311
|
+
genesis_mesh/
|
|
312
|
+
audit/ Tamper-evident security audit logging
|
|
313
|
+
cli/ High-level and low-level CLI commands
|
|
314
|
+
crypto/ Ed25519 signing and key management
|
|
315
|
+
gossip/ CRL gossip protocol
|
|
316
|
+
models/ Genesis, certificate, policy, CRL, and enrollment models
|
|
317
|
+
monitoring/ Prometheus metrics and health checks
|
|
318
|
+
na_service/ Network Authority REST API and WSGI entry point
|
|
319
|
+
node/ Node client, runtime, discovery, RBAC, and control plane
|
|
320
|
+
routing/ Routing table, protocol, and message forwarding
|
|
321
|
+
tests/ Unit and integration tests
|
|
322
|
+
transport/ WebSocket transport, Noise XX, protocol framing, and connections
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
## Testing
|
|
326
|
+
|
|
327
|
+
```bash
|
|
328
|
+
python -m pytest genesis_mesh/tests -v
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
## Security
|
|
332
|
+
|
|
333
|
+
To report a vulnerability, open a GitHub Security Advisory on this repository.
|
|
334
|
+
Do not file a public issue for security-sensitive findings.
|
|
335
|
+
|
|
336
|
+
## License
|
|
337
|
+
|
|
338
|
+
[MIT](LICENSE)
|
|
@@ -0,0 +1,284 @@
|
|
|
1
|
+
# Genesis Mesh
|
|
2
|
+
|
|
3
|
+
[](https://genesismesh.connectorzzz.com)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
[](https://github.com/thaersaidi/genesismesh/releases)
|
|
6
|
+
|
|
7
|
+
## Live Deployment
|
|
8
|
+
|
|
9
|
+
| | |
|
|
10
|
+
|---|---|
|
|
11
|
+
| Network Authority | Online |
|
|
12
|
+
| Public Endpoint | https://na.genesismesh.connectorzzz.com |
|
|
13
|
+
| Deployment | Azure VM, Sweden Central |
|
|
14
|
+
| TLS | Enabled |
|
|
15
|
+
| Active Nodes | 2 |
|
|
16
|
+
| Tracked Nodes | 2 |
|
|
17
|
+
| Remote Nodes | 1 |
|
|
18
|
+
| Online since | 2026-05-30 |
|
|
19
|
+
|
|
20
|
+
Current deployment demonstrates:
|
|
21
|
+
|
|
22
|
+
- Identity and certificate-based enrollment
|
|
23
|
+
- Remote nodes across separate networks
|
|
24
|
+
- Noise XX encrypted peer sessions
|
|
25
|
+
- Direct message delivery
|
|
26
|
+
- Multi-hop routing and packet forwarding
|
|
27
|
+
- Route failure recovery
|
|
28
|
+
- Certificate revocation and CRL enforcement
|
|
29
|
+
|
|
30
|
+

|
|
31
|
+
|
|
32
|
+

|
|
33
|
+
|
|
34
|
+
## Live Message Delivery
|
|
35
|
+
|
|
36
|
+
A remote local node sends a DATA message to an Azure-hosted node over a Noise XX encrypted peer session.
|
|
37
|
+
|
|
38
|
+

|
|
39
|
+
|
|
40
|
+
- Noise XX handshake completed
|
|
41
|
+
- Connection established
|
|
42
|
+
- Neighbor added
|
|
43
|
+
- DATA message delivered
|
|
44
|
+
|
|
45
|
+
## Multi-Hop Routing
|
|
46
|
+
|
|
47
|
+
Genesis Mesh supports decentralized route propagation and packet forwarding.
|
|
48
|
+
|
|
49
|
+
Node A and Node C do not connect directly. Instead:
|
|
50
|
+
|
|
51
|
+
**Node A → Node B → Node C**
|
|
52
|
+
|
|
53
|
+
Node B learns routes, forwards packets, and decrements TTL values during transit.
|
|
54
|
+
|
|
55
|
+

|
|
56
|
+
|
|
57
|
+
- Route learned via intermediate node
|
|
58
|
+
- DATA forwarded by router
|
|
59
|
+
- DATA delivered to destination
|
|
60
|
+
|
|
61
|
+
## Route Failure Recovery
|
|
62
|
+
|
|
63
|
+
When a router goes offline, neighboring nodes withdraw its routes and traffic re-routes through a surviving path — no operator intervention.
|
|
64
|
+
|
|
65
|
+
**Topology:** A reaches C through two routers — B (primary) and D (backup). B is killed mid-demo.
|
|
66
|
+
|
|
67
|
+

|
|
68
|
+
|
|
69
|
+
- Primary path A → B → C delivers
|
|
70
|
+
- B goes offline
|
|
71
|
+
- A detects the disconnect and invalidates B's routes
|
|
72
|
+
- A → D → C delivers without retry or operator action
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+

|
|
76
|
+
|
|
77
|
+
**Trust can be revoked.**
|
|
78
|
+
|
|
79
|
+
A revoked node is removed from the active set, added to a signed CRL, and
|
|
80
|
+
immediately rejected by heartbeat, renewal, handshake, and routing checks.
|
|
81
|
+
|
|
82
|
+
Genesis Mesh treats revocation as a first-class control-plane action. When an
|
|
83
|
+
operator revokes a certificate, the Network Authority publishes a new signed
|
|
84
|
+
CRL, removes the node from the active set, and rejects further heartbeat,
|
|
85
|
+
renewal, peer handshake, and routing activity from that identity.
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
Genesis Mesh is a sovereign trust, identity, and communication fabric for AI
|
|
90
|
+
agents, edge systems, and distributed infrastructure.
|
|
91
|
+
|
|
92
|
+
It answers the operational questions that basic mesh networking leaves open:
|
|
93
|
+
who is allowed to be a node, how peers prove identity, what each node is
|
|
94
|
+
allowed to do, how messages reach the right peer, and how a compromised or
|
|
95
|
+
retired identity is removed.
|
|
96
|
+
|
|
97
|
+
Genesis Mesh combines five capabilities in one trust fabric:
|
|
98
|
+
|
|
99
|
+
- **Identity**: every node has an Ed25519 identity and a signed join certificate.
|
|
100
|
+
- **Trust**: a signed genesis block, Network Authority, operator keys, and CRLs
|
|
101
|
+
define who the network trusts.
|
|
102
|
+
- **Routing**: authenticated peers discover routes and forward messages without
|
|
103
|
+
depending on the Network Authority for every data exchange.
|
|
104
|
+
- **Authorization**: enrollment roles, policy manifests, RBAC, and signed admin
|
|
105
|
+
actions define what identities may do.
|
|
106
|
+
- **Sovereignty**: the operator owns the trust chain, membership process,
|
|
107
|
+
revocation process, and policy distribution path.
|
|
108
|
+
|
|
109
|
+
Every enrolled node holds a signed join certificate issued by the Network
|
|
110
|
+
Authority. Peer sessions are encrypted with the Noise XX protocol, deriving
|
|
111
|
+
X25519 keys directly from each node's Ed25519 identity. No separate TLS
|
|
112
|
+
certificate lifecycle is required for peer transport.
|
|
113
|
+
|
|
114
|
+
## Why It Exists
|
|
115
|
+
|
|
116
|
+
Most overlay networks focus on connectivity: can this machine reach that
|
|
117
|
+
machine? Genesis Mesh focuses on controlled participation: should this machine
|
|
118
|
+
be here, what identity is it using, what is it authorized to do, and can the
|
|
119
|
+
network remove it quickly?
|
|
120
|
+
|
|
121
|
+
Use Genesis Mesh when your system needs:
|
|
122
|
+
|
|
123
|
+
- a private trust domain for agents, devices, or edge services
|
|
124
|
+
- operator-controlled enrollment instead of open peer discovery
|
|
125
|
+
- certificate-backed peer authentication
|
|
126
|
+
- signed policy distribution
|
|
127
|
+
- revocation that affects heartbeats, renewal, peer handshakes, and routing
|
|
128
|
+
- audit trails for security-relevant control-plane actions
|
|
129
|
+
|
|
130
|
+
Do not use it when you only need public peer discovery, anonymous networking, a
|
|
131
|
+
general service mesh for Kubernetes ingress, or a permissionless blockchain.
|
|
132
|
+
|
|
133
|
+
## Architecture
|
|
134
|
+
|
|
135
|
+
```mermaid
|
|
136
|
+
flowchart TD
|
|
137
|
+
RS["Root Sovereign<br/>offline trust anchor"]
|
|
138
|
+
NA["Network Authority<br/>invite enrollment, certs, CRLs, policy"]
|
|
139
|
+
A["Node A"]
|
|
140
|
+
B["Node B"]
|
|
141
|
+
C["Node C"]
|
|
142
|
+
|
|
143
|
+
RS -->|"signs genesis"| NA
|
|
144
|
+
NA -->|"invite token + join certificate"| A
|
|
145
|
+
NA -->|"invite token + join certificate"| B
|
|
146
|
+
NA -->|"invite token + join certificate"| C
|
|
147
|
+
|
|
148
|
+
A <-->|"Noise XX encrypted peer session"| B
|
|
149
|
+
B <-->|"Noise XX encrypted peer session"| C
|
|
150
|
+
A <-->|"Noise XX encrypted peer session"| C
|
|
151
|
+
|
|
152
|
+
NA -.->|"signed CRL bootstrap"| A
|
|
153
|
+
A -.->|"CRL gossip"| B
|
|
154
|
+
B -.->|"CRL gossip"| C
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
At a high level, the Network Authority admits identities and publishes trust
|
|
158
|
+
state. Nodes use that state to communicate directly, route messages, and reject
|
|
159
|
+
revoked peers.
|
|
160
|
+
|
|
161
|
+
## Documentation
|
|
162
|
+
|
|
163
|
+
[Documentation Website](https://genesismesh.connectorzzz.com)
|
|
164
|
+
|
|
165
|
+
## Requirements
|
|
166
|
+
|
|
167
|
+
- Python 3.12 or later
|
|
168
|
+
- See `requirements.txt` for pinned runtime dependencies
|
|
169
|
+
|
|
170
|
+
## Installation
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
python -m venv .venv
|
|
174
|
+
source .venv/bin/activate # PowerShell: .\.venv\Scripts\Activate.ps1
|
|
175
|
+
pip install -r requirements.txt
|
|
176
|
+
pip install -e .
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
## Quick Start
|
|
180
|
+
|
|
181
|
+
The local workflow runs the NA in one terminal and joins a node in a second.
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
# Create keys, genesis block, and CLI config (one time).
|
|
185
|
+
genesis-mesh init
|
|
186
|
+
|
|
187
|
+
# Start the Network Authority (keep this terminal open).
|
|
188
|
+
genesis-mesh na start
|
|
189
|
+
|
|
190
|
+
# In a second terminal: create a single-use invite and join.
|
|
191
|
+
INVITE_TOKEN=$(genesis-mesh admin invite --role anchor)
|
|
192
|
+
genesis-mesh join --na http://127.0.0.1:8443 --token "$INVITE_TOKEN"
|
|
193
|
+
|
|
194
|
+
# Inspect NA health and node certificate state.
|
|
195
|
+
genesis-mesh status
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
PowerShell:
|
|
199
|
+
|
|
200
|
+
```powershell
|
|
201
|
+
$INVITE_TOKEN = genesis-mesh admin invite --role anchor
|
|
202
|
+
genesis-mesh join --na http://127.0.0.1:8443 --token $INVITE_TOKEN
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
Full local smoke test:
|
|
206
|
+
|
|
207
|
+
```bash
|
|
208
|
+
genesis-mesh dev up
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
## Production Deployment
|
|
212
|
+
|
|
213
|
+
Container startup uses `start.sh` and Gunicorn. Set `SERVICE_ROLE=na` for the
|
|
214
|
+
Network Authority or `SERVICE_ROLE=node` for a peer node. The NA role requires
|
|
215
|
+
two mounted secrets and fails closed if either is absent:
|
|
216
|
+
|
|
217
|
+
| Environment variable | Description |
|
|
218
|
+
|---------------------------|--------------------------------------------------|
|
|
219
|
+
| `SERVICE_ROLE` | `na` or `node` |
|
|
220
|
+
| `GENESIS_FILE` | Path to the signed genesis block |
|
|
221
|
+
| `NA_PRIVATE_KEY_FILE` | Path to the NA Ed25519 signing key (NA role) |
|
|
222
|
+
| `OPERATOR_PUBLIC_KEYS_JSON` | JSON map of operator key IDs to public keys |
|
|
223
|
+
| `DB_PATH` | SQLite database path (default: `genesis_mesh_na.db`) |
|
|
224
|
+
| `PORT` | Bind port (default: `8443`) |
|
|
225
|
+
| `WEB_CONCURRENCY` | Gunicorn worker count (default: `4`) |
|
|
226
|
+
|
|
227
|
+
The NA private key never leaves the NA process.
|
|
228
|
+
|
|
229
|
+
Health and readiness probes are available at `/healthz` and `/readyz`.
|
|
230
|
+
|
|
231
|
+
## Deployment Examples
|
|
232
|
+
|
|
233
|
+
Genesis Mesh includes deployment examples for:
|
|
234
|
+
|
|
235
|
+
- **Local process** — `genesis-mesh init && genesis-mesh na start`
|
|
236
|
+
- **Docker** — `docker run` and Docker Compose (`docs/examples/compose/`)
|
|
237
|
+
- **Kubernetes** — manifests under `examples/kubernetes/`
|
|
238
|
+
- **Terraform on Azure** — `infrastructure/azure/`, the same module used by the live deployment
|
|
239
|
+
|
|
240
|
+
See the [deployment guide](https://genesismesh.connectorzzz.com/operations/deployment.html) for the full walkthrough.
|
|
241
|
+
|
|
242
|
+
## Repository Layout
|
|
243
|
+
|
|
244
|
+
```
|
|
245
|
+
.
|
|
246
|
+
Dockerfile Container image definition
|
|
247
|
+
start.sh Container entry point (NA and node roles)
|
|
248
|
+
requirements.txt Pinned runtime dependencies
|
|
249
|
+
setup.py Package metadata and entry points
|
|
250
|
+
docs/ Sphinx documentation source
|
|
251
|
+
examples/ Demo workflows, sample genesis blocks, Kubernetes manifests
|
|
252
|
+
genesis_mesh/ Python package
|
|
253
|
+
infrastructure/ Terraform, Azure scripts, and operational tools
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
```
|
|
257
|
+
genesis_mesh/
|
|
258
|
+
audit/ Tamper-evident security audit logging
|
|
259
|
+
cli/ High-level and low-level CLI commands
|
|
260
|
+
crypto/ Ed25519 signing and key management
|
|
261
|
+
gossip/ CRL gossip protocol
|
|
262
|
+
models/ Genesis, certificate, policy, CRL, and enrollment models
|
|
263
|
+
monitoring/ Prometheus metrics and health checks
|
|
264
|
+
na_service/ Network Authority REST API and WSGI entry point
|
|
265
|
+
node/ Node client, runtime, discovery, RBAC, and control plane
|
|
266
|
+
routing/ Routing table, protocol, and message forwarding
|
|
267
|
+
tests/ Unit and integration tests
|
|
268
|
+
transport/ WebSocket transport, Noise XX, protocol framing, and connections
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
## Testing
|
|
272
|
+
|
|
273
|
+
```bash
|
|
274
|
+
python -m pytest genesis_mesh/tests -v
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
## Security
|
|
278
|
+
|
|
279
|
+
To report a vulnerability, open a GitHub Security Advisory on this repository.
|
|
280
|
+
Do not file a public issue for security-sensitive findings.
|
|
281
|
+
|
|
282
|
+
## License
|
|
283
|
+
|
|
284
|
+
[MIT](LICENSE)
|