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.
Files changed (72) hide show
  1. genesis_mesh-0.5.0/LICENSE +21 -0
  2. genesis_mesh-0.5.0/PKG-INFO +338 -0
  3. genesis_mesh-0.5.0/README.md +284 -0
  4. genesis_mesh-0.5.0/genesis_mesh/__init__.py +3 -0
  5. genesis_mesh-0.5.0/genesis_mesh/audit/__init__.py +5 -0
  6. genesis_mesh-0.5.0/genesis_mesh/audit/logger.py +395 -0
  7. genesis_mesh-0.5.0/genesis_mesh/cli/__init__.py +5 -0
  8. genesis_mesh-0.5.0/genesis_mesh/cli/__main__.py +6 -0
  9. genesis_mesh-0.5.0/genesis_mesh/cli/config.py +98 -0
  10. genesis_mesh-0.5.0/genesis_mesh/cli/main.py +254 -0
  11. genesis_mesh-0.5.0/genesis_mesh/cli/node_cmd.py +166 -0
  12. genesis_mesh-0.5.0/genesis_mesh/cli/ops.py +601 -0
  13. genesis_mesh-0.5.0/genesis_mesh/crypto/__init__.py +17 -0
  14. genesis_mesh-0.5.0/genesis_mesh/crypto/keys.py +135 -0
  15. genesis_mesh-0.5.0/genesis_mesh/crypto/signing.py +101 -0
  16. genesis_mesh-0.5.0/genesis_mesh/gossip/__init__.py +5 -0
  17. genesis_mesh-0.5.0/genesis_mesh/gossip/crl_gossip.py +379 -0
  18. genesis_mesh-0.5.0/genesis_mesh/models/__init__.py +22 -0
  19. genesis_mesh-0.5.0/genesis_mesh/models/certificates.py +75 -0
  20. genesis_mesh-0.5.0/genesis_mesh/models/control_plane.py +162 -0
  21. genesis_mesh-0.5.0/genesis_mesh/models/enrollment.py +21 -0
  22. genesis_mesh-0.5.0/genesis_mesh/models/genesis.py +69 -0
  23. genesis_mesh-0.5.0/genesis_mesh/models/policy.py +50 -0
  24. genesis_mesh-0.5.0/genesis_mesh/models/revocation.py +101 -0
  25. genesis_mesh-0.5.0/genesis_mesh/monitoring/__init__.py +11 -0
  26. genesis_mesh-0.5.0/genesis_mesh/monitoring/health.py +421 -0
  27. genesis_mesh-0.5.0/genesis_mesh/monitoring/metrics.py +342 -0
  28. genesis_mesh-0.5.0/genesis_mesh/na_service/__init__.py +5 -0
  29. genesis_mesh-0.5.0/genesis_mesh/na_service/__main__.py +6 -0
  30. genesis_mesh-0.5.0/genesis_mesh/na_service/auth.py +218 -0
  31. genesis_mesh-0.5.0/genesis_mesh/na_service/db.py +406 -0
  32. genesis_mesh-0.5.0/genesis_mesh/na_service/rate_limit.py +23 -0
  33. genesis_mesh-0.5.0/genesis_mesh/na_service/routes/__init__.py +15 -0
  34. genesis_mesh-0.5.0/genesis_mesh/na_service/routes/admin.py +211 -0
  35. genesis_mesh-0.5.0/genesis_mesh/na_service/routes/crl.py +24 -0
  36. genesis_mesh-0.5.0/genesis_mesh/na_service/routes/enrollment.py +342 -0
  37. genesis_mesh-0.5.0/genesis_mesh/na_service/routes/health.py +110 -0
  38. genesis_mesh-0.5.0/genesis_mesh/na_service/routes/public.py +363 -0
  39. genesis_mesh-0.5.0/genesis_mesh/na_service/server.py +250 -0
  40. genesis_mesh-0.5.0/genesis_mesh/na_service/wsgi.py +34 -0
  41. genesis_mesh-0.5.0/genesis_mesh/node/__init__.py +5 -0
  42. genesis_mesh-0.5.0/genesis_mesh/node/__main__.py +7 -0
  43. genesis_mesh-0.5.0/genesis_mesh/node/cert_manager.py +230 -0
  44. genesis_mesh-0.5.0/genesis_mesh/node/control_commands.py +210 -0
  45. genesis_mesh-0.5.0/genesis_mesh/node/control_handler.py +262 -0
  46. genesis_mesh-0.5.0/genesis_mesh/node/discovery.py +346 -0
  47. genesis_mesh-0.5.0/genesis_mesh/node/dispatcher.py +75 -0
  48. genesis_mesh-0.5.0/genesis_mesh/node/node.py +402 -0
  49. genesis_mesh-0.5.0/genesis_mesh/node/peer_identity.py +163 -0
  50. genesis_mesh-0.5.0/genesis_mesh/node/peer_manager.py +304 -0
  51. genesis_mesh-0.5.0/genesis_mesh/node/persistent_runner.py +73 -0
  52. genesis_mesh-0.5.0/genesis_mesh/node/rbac.py +220 -0
  53. genesis_mesh-0.5.0/genesis_mesh/node/runtime.py +531 -0
  54. genesis_mesh-0.5.0/genesis_mesh/routing/__init__.py +12 -0
  55. genesis_mesh-0.5.0/genesis_mesh/routing/protocol.py +231 -0
  56. genesis_mesh-0.5.0/genesis_mesh/routing/router.py +225 -0
  57. genesis_mesh-0.5.0/genesis_mesh/routing/table.py +321 -0
  58. genesis_mesh-0.5.0/genesis_mesh/transport/__init__.py +22 -0
  59. genesis_mesh-0.5.0/genesis_mesh/transport/connection.py +379 -0
  60. genesis_mesh-0.5.0/genesis_mesh/transport/heartbeat.py +75 -0
  61. genesis_mesh-0.5.0/genesis_mesh/transport/noise_handshake.py +185 -0
  62. genesis_mesh-0.5.0/genesis_mesh/transport/protocol.py +237 -0
  63. genesis_mesh-0.5.0/genesis_mesh/transport/websocket_transport.py +170 -0
  64. genesis_mesh-0.5.0/genesis_mesh.egg-info/PKG-INFO +338 -0
  65. genesis_mesh-0.5.0/genesis_mesh.egg-info/SOURCES.txt +70 -0
  66. genesis_mesh-0.5.0/genesis_mesh.egg-info/dependency_links.txt +1 -0
  67. genesis_mesh-0.5.0/genesis_mesh.egg-info/entry_points.txt +4 -0
  68. genesis_mesh-0.5.0/genesis_mesh.egg-info/requires.txt +23 -0
  69. genesis_mesh-0.5.0/genesis_mesh.egg-info/top_level.txt +1 -0
  70. genesis_mesh-0.5.0/pyproject.toml +90 -0
  71. genesis_mesh-0.5.0/setup.cfg +4 -0
  72. 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
+ [![Docs](https://img.shields.io/badge/docs-online-blue)](https://genesismesh.connectorzzz.com)
58
+ [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
59
+ [![Release](https://img.shields.io/github/v/release/thaersaidi/genesismesh)](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
+ ![NA dashboard showing 2 active nodes](docs/examples/assets/na-dashboard.png)
85
+
86
+ ![/nodes endpoint showing two enrolled nodes with different remote addresses](docs/examples/assets/na-nodes.png)
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
+ ![Genesis Mesh live message delivery](docs/examples/assets/genesis-mesh-message-delivery.gif)
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
+ ![Genesis Mesh multi-hop routing demo](docs/examples/assets/genesis-mesh-multi-hop.gif)
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
+ ![Genesis Mesh route failure recovery demo](docs/examples/assets/genesis-mesh-failover.gif)
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
+ ![Genesis Mesh revocation demo](docs/examples/assets/genesis-mesh-revocation.gif)
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
+ [![Docs](https://img.shields.io/badge/docs-online-blue)](https://genesismesh.connectorzzz.com)
4
+ [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
5
+ [![Release](https://img.shields.io/github/v/release/thaersaidi/genesismesh)](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
+ ![NA dashboard showing 2 active nodes](docs/examples/assets/na-dashboard.png)
31
+
32
+ ![/nodes endpoint showing two enrolled nodes with different remote addresses](docs/examples/assets/na-nodes.png)
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
+ ![Genesis Mesh live message delivery](docs/examples/assets/genesis-mesh-message-delivery.gif)
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
+ ![Genesis Mesh multi-hop routing demo](docs/examples/assets/genesis-mesh-multi-hop.gif)
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
+ ![Genesis Mesh route failure recovery demo](docs/examples/assets/genesis-mesh-failover.gif)
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
+ ![Genesis Mesh revocation demo](docs/examples/assets/genesis-mesh-revocation.gif)
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)
@@ -0,0 +1,3 @@
1
+ """Genesis Mesh - Secure decentralized mesh networking with cryptographic trust chains."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,5 @@
1
+ """Audit logging for security events."""
2
+
3
+ from .logger import AuditLogger, AuditEvent, EventType
4
+
5
+ __all__ = ["AuditLogger", "AuditEvent", "EventType"]