feature(mesh-genesis): add mesh genesis rules

[ndizazzo]

Summary

This PR lets operators create requirement-aware meshes: meshes whose admission rules are fixed at creation time and enforced before peers become routable members.

Operators can require trusted embedded release-build attestations, enforce node version floors or ceilings, require compatible protocol generations, and issue signed bootstrap tokens for restricted meshes. Legacy unrestricted meshes keep the existing unsigned invite-token flow.

Release attestation is now embedded in the packaged mesh-llm executable itself. There is no sibling .attestation.json file and no runtime sidecar path. Nodes inspect the binary they are actually running, advertise the verified release-attestation result, and remain non-blocking by default unless mesh policy requires certified builds.

Certified-build admission proves release provenance. It is not remote runtime attestation and does not prove the remote OS, hardware, or running process is untampered.

What operators can now do

1. Require trusted release-attested binaries before a node can join

mesh-llm serve --model Qwen3-8B-Q4_K_M --publish \
  --require-release-attestation \
  --release-signer-key ed25519:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \
  --owner-key ~/.mesh-llm/owner-keystore.json \
  --owner-required

A joining node presents the embedded attestation from its packaged executable:

mesh-llm serve --join <signed-bootstrap-token>

Operators can inspect the same packaged binary directly:

cargo run -p xtask -- release-attestation inspect \
  --binary /tmp/test-bundle/mesh-llm \
  --public-key-file /secure/mesh-release-key.pub \
  --json

Inspection reports valid, missing, or invalid. Unstamped local/dev builds report missing; trusted stamped packages report valid; bytes changed after packaging report invalid.

Admission failures use stable reasons such as:

certified_binary_required
build_proof_missing
build_proof_invalid
release_signer_untrusted
attestation_policy_mismatch

2. Stamp the final packaged release artifact

Release attestation is stamped after the package binary's final mutation, so the signed bytes match the artifact operators install and distribute.

MESH_RELEASE_ATTESTATION_SIGNING_KEY_FILE=/secure/mesh-release-key.json \
MESH_RELEASE_ATTESTATION_PUBLIC_KEY_FILE=/secure/mesh-release-key.pub \
  just release-bundle v0.65.0

Smoke and nightly evidence now inspect packaged artifacts rather than raw target/release/mesh-llm outputs.

3. Require a minimum mesh-llm version for all joining nodes

mesh-llm serve --model Qwen3-8B-Q4_K_M --publish \
  --min-node-version 0.65.0

Peers advertising older versions are rejected before routing:

node_version_below_minimum

4. Cap or pin accepted node versions

mesh-llm serve --model Qwen3-8B-Q4_K_M --publish \
  --min-node-version 0.65.0 \
  --max-node-version 0.65.9

This lets operators stage upgrade windows without silently admitting incompatible future or older binaries.

5. Guarantee protocol-generation compatibility

mesh-llm serve --model Qwen3-8B-Q4_K_M --publish \
  --min-protocol-version 1 \
  --max-protocol-version 1

Peers outside the accepted range are rejected with stable reason codes:

protocol_generation_below_minimum
protocol_generation_above_maximum
protocol_generation_unknown

6. Combine binary, version, and protocol requirements into one immutable mesh policy

mesh-llm serve --model Qwen3-8B-Q4_K_M --publish \
  --min-node-version 0.65.0 \
  --max-node-version 0.65.9 \
  --min-protocol-version 1 \
  --max-protocol-version 1 \
  --require-release-attestation \
  --release-signer-key ed25519:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \
  --owner-key ~/.mesh-llm/owner-keystore.json \
  --owner-required

Changing those requirements creates a different requirement-aware mesh instead of mutating the existing mesh in place.

7. Configure the same requirements from config.toml

[mesh_requirements]
min_node_version = "0.65.0"
max_node_version = "0.65.9"
min_protocol_version = 1
max_protocol_version = 1
require_release_attestation = true
release_signer_keys = [
  "ed25519:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
]

Then start with an owner identity so the genesis policy and bootstrap token can be signed:

mesh-llm serve --model Qwen3-8B-Q4_K_M --publish \
  --owner-key ~/.mesh-llm/owner-keystore.json \
  --owner-required

8. Keep public discovery separate from admission

Discovery can advertise that a mesh exists, while admission still rejects nodes that do not satisfy its requirements.

mesh-llm serve --model Qwen3-8B-Q4_K_M --publish \
  --mesh-name certified-lab \
  --require-release-attestation \
  --release-signer-key ed25519:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \
  --owner-key ~/.mesh-llm/owner-keystore.json \
  --owner-required

Runtime, API, and UI status surfaces now expose release-attestation state, mesh requirements, and recent mesh-rejection evidence.

Compatibility

• Existing unrestricted private and public meshes keep the current unsigned invite-token behavior.
• Requirement-aware meshes use signed genesis policy, signed bootstrap tokens, and policy-matching direct admission proofs.
• Protocol additions are additive and preserve mixed-version compatibility for unrestricted meshes.
• Release attestation is optional by policy: missing or invalid binaries can still start unless the mesh requires certified builds.
• The embedded attestation applies only to the packaged mesh-llm executable, not SDK, XCFramework, or other native artifacts.
• Owner trust remains separate from release trust and is not part of the immutable mesh requirements hash.

Validation

• Verified embedded release-attestation inspection for valid, missing, and invalid states.
• Confirmed packaged release flows stamp the final bundled executable after its last mutation.
• Confirmed smoke and nightly evidence inspect packaged artifacts rather than raw release outputs.
• Confirmed runtime, API, and UI surfaces expose release-attestation status.
• Confirmed requirement-aware admission preserves the legacy unrestricted mesh compatibility path.

[Copilot]

Pull request overview

This PR introduces requirement-aware meshes whose immutable admission requirements (node version bounds, protocol generation bounds, and optional certified release-build attestation) are fixed at mesh creation time and included in mesh identity derivation, while keeping legacy unrestricted meshes compatible with the existing unsigned invite-token join flow.

Changes:

• Add signed genesis policy + signed bootstrap token support for requirement-aware mesh creation/join, plus direct peer admission proof validation before routing/admission.
• Load and advertise release-build attestations from a sibling mesh-llm.attestation.json file (or MESH_LLM_RELEASE_ATTESTATION_PATH), and enforce signer allowlists when required.
• Expose mesh requirement summaries and recent rejection events via status/runtime surfaces and UI types; extend protocol protobufs and compatibility tests accordingly.

Reviewed changes

Copilot reviewed 40 out of 41 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tools/xtask/src/main.rs	Adds release-attestation stamp/inspect helpers for generating and inspecting attestation sidecars.
tools/xtask/Cargo.toml	Adds crypto + hashing deps and links xtask to host-runtime attestation types.
scripts/task-8-real-binary.sh	Adds an end-to-end validation script for real-binary attestation/admission scenarios.
docs/README.md	Links new owner-identity design doc.
docs/MESHES.md	Documents immutable mesh requirements, certified-build limitations, and signed bootstrap joins.
docs/design/TESTING.md	Adds requirement-aware mesh smoke test steps and expected failure codes.
docs/design/NODE_OWNER_IDENTITY.md	Clarifies separation of owner identity vs release attestation and immutable mesh requirements.
docs/design/DESIGN.md	Updates mesh identity definition for requirement-aware meshes and config field placement.
docs/CLI.md	Documents new CLI flags for release-attestation-based requirements.
crates/mesh-llm/tests/protocol_convert_matrix.rs	Adds roundtrip/hash/validation tests for new mesh requirement + signing types.
crates/mesh-llm/tests/protocol_compat_v0_client.rs	Ensures unrestricted meshes remain compatible with v0 negotiation + legacy flows.
crates/mesh-llm-ui/src/features/app-shell/lib/status-types.ts	Adds UI status types for mesh requirements summary and rejection events.
crates/mesh-llm-protocol/src/protocol/mod.rs	Updates protocol tests to include mesh_requirements config snapshot field.
crates/mesh-llm-protocol/src/proto/node.rs	Adds protobuf-generated structs for requirements/policy/attestation/bootstrap/direct-proof fields.
crates/mesh-llm-protocol/proto/node.proto	Extends wire protocol schema with requirement/policy/attestation/bootstrap/direct-proof messages/fields.
crates/mesh-llm-host-runtime/src/runtime/release_attestation.rs	Implements loading of local release attestation sidecar (env override or sibling file).
crates/mesh-llm-host-runtime/src/runtime/mod.rs	Wires creation-time requirements into startup, loads local attestation, updates join UX message, and adds merge/validation helpers/tests.
crates/mesh-llm-host-runtime/src/runtime/config_state.rs	Updates config-state tests for new mesh_requirements config section defaults.
crates/mesh-llm-host-runtime/src/runtime_data/mod.rs	Extends runtime data snapshots/tests to carry requirements + rejection event surfaces.
crates/mesh-llm-host-runtime/src/runtime_data/api_views.rs	Initializes new status payload fields (later populated in API layer).
crates/mesh-llm-host-runtime/src/protocol/mod.rs	Makes protocol test module accessible for exact-test wrappers; updates fixtures for new fields.
crates/mesh-llm-host-runtime/src/protocol/convert.rs	Converts new gossip fields (policy hash, genesis policy, release attestation, direct proof) and round-trips mesh_requirements in config snapshots.
crates/mesh-llm-host-runtime/src/plugin/mod.rs	Re-exports mesh-requirements config helpers and validation error formatting.
crates/mesh-llm-host-runtime/src/plugin/config.rs	Adds [mesh_requirements] config parsing/validation and error messaging helpers + tests.
crates/mesh-llm-host-runtime/src/network/nostr.rs	Updates listing semantics from “invite token” to “join token” with requirement-aware context.
crates/mesh-llm-host-runtime/src/network/discovery.rs	Ensures LAN discovery only publishes a fingerprint, not trust-bearing join material.
crates/mesh-llm-host-runtime/src/mesh/tests.rs	Updates mesh tests and adds extensive requirement-aware admission/behavior coverage.
crates/mesh-llm-host-runtime/src/mesh/mod.rs	Implements requirement-aware mesh state, signed bootstrap parsing, direct admission proof verification, rejection tracking, and routing gating.
crates/mesh-llm-host-runtime/src/mesh/gossip.rs	Adds policy/attestation/proof to gossip, validates direct peers before promotion, and prevents transitive-only admission.
crates/mesh-llm-host-runtime/src/lib.rs	Re-exports mesh requirements/signing/attestation types from the runtime crate API.
crates/mesh-llm-host-runtime/src/exact_test_wrappers.rs	Hooks new tests into exact-test wrapper suite.
crates/mesh-llm-host-runtime/src/cli/output/mod.rs	Adjusts dashboard startup state transition message for “awaiting mesh admission”.
crates/mesh-llm-host-runtime/src/cli/mod.rs	Adds CLI flags for mesh requirements and updates docs-example parsing test.
crates/mesh-llm-host-runtime/src/cli/commands/runtime.rs	Updates runtime command tests to include mesh requirements defaults.
crates/mesh-llm-host-runtime/src/api/tests.rs	Adds API tests for requirements surfaces and ensures rejection events don’t leak tokens.
crates/mesh-llm-host-runtime/src/api/status.rs	Extends status payload with mesh requirements summary and recent rejection events.
crates/mesh-llm-host-runtime/src/api/mod.rs	Populates new status fields from node state and exports API test module for wrappers.
crates/mesh-client/tests/protocol_wire.rs	Adds wire-level protobuf roundtrip tests for new requirement/policy/attestation/proof fields.
crates/mesh-client/tests/control_plane_client.rs	Updates control-plane tests to include new optional config snapshot field.
Cargo.lock	Records new dependencies pulled in by xtask and requirement-aware additions.

[Copilot]

Pull request overview

Copilot reviewed 42 out of 43 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 42 out of 43 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 42 out of 43 changed files in this pull request and generated 2 comments.

[michaelneale]

taking a look - may need this soon @ndizazzo

[IvGolovach]

Thanks for pushing this through. I did a careful pass over the current shape and the earlier review threads.

This is a big change, but the scope feels coherent: requirement-aware meshes get immutable genesis/admission policy, signed bootstrap material, version/protocol bounds, optional release-build attestation, and visible status/API/UI state, while unrestricted meshes keep the legacy open path.

The prior review threads look resolved, and the important edge cases around unsigned fallback, token validity, pre-join validation, optional attestation loading, protobuf layout, and release/test tooling all appear accounted for.

Given the protocol/security surface area, I’d just want the branch refreshed on latest main and the final CI/smoke evidence on that head. With that, I’m comfortable with the direction and think this is a strong foundation for restricted meshes.

[michaelneale]

@ndizazzo could this be used to gate admission to a mesh to only blessed peers? (ie protection is bi directional?)

[ndizazzo]

could this be used to gate admission to a mesh to only blessed peers? (ie protection is bi directional?)

@michaelneale absolutely! This is actually the whole point of making this surface a bit more robust than simple if-checks.

Permitting "allowed" peers doesn't exist right now on this PR, but the framework and structure is in place to make it very easy to extend with this rule.

Right now, the PR has (all disabled by default):

• Minimum app version needed
• Maximum app version admitted
• Minimun protocol version needed
• Maximum protocol version admitted
• Embedded binary attestation -> Only nodes running a mesh-llm binary with a specifically embedded attestation is permitted
  • IE: We do a post-build process on CI to attach a HSM-signed attestation to our binary, then all mesh-llm nodes that require it must validate before being allowed on the mesh

It would be not much more work to:

• Have each node grant itself a specific identifier through the mesh-llm auth flow
• Add some services to maintain a list of auth keys that are permitted
• Only admit nodes that have signed proof they are the correct node

I'd like to get this in as-is before adding support for that, so this doesn't balloon too much. In the meantime, I'll draft up a spec for you to check out in the issues.

[michaelneale]

I think this is important and good for maturity.

Some thoughts (which could be follow ons):

• Bind min/max_node_version to the signed attestation’s node_version, not the peer’s self-advertised gossip version.
• Fail startup when --require-release-attestation is set but the local binary is missing/invalid attestation
• is there a way to somehow enforce/check/prove the binary is itself signed/attested (depending on the OS, using whatever TEE is available?)

[ndizazzo]

@michaelneale GitHub also has this: https://github.com/actions/attest-build-provenance