commission-ai-mesh

The mesh and phone link protocol used by CommissionAI, as a Rust crate with no dependency on CommissionAI itself. It holds the parts that are pure protocol and cryptography:

• Mesh. Signed node records, owner-signed admissions and removals, shortest-path routing, sealed links between two computers (X25519, ChaCha20-Poly1305, ed25519 proofs) and end-to-end sealed request streams across computers in the middle. See docs/mesh.md.
• Phone link. The pairing message, the commission-phone-v1 session handshake, sealed frames and the relay frame codec for pairing an iPhone with a computer. See docs/phone.md.
• Views. The serde and ts-rs types for node records and for the mesh state a host shows (model).

Sockets, discovery, relays, persistence and what a request is allowed to do stay in the host. The crate takes streams (anything AsyncRead + AsyncWrite) and callbacks, never an application state.

Contract

| Item | Value | | --- | --- | | npm package | @patrick-lai/commission-ai-mesh | | Crate | crate/ (commission-mesh, library commission_mesh, edition 2024, not published to crates.io) | | Modules | mesh, mesh_link, mesh_stream, model, phone | | Mesh protocol version | 1 (mesh::PROTOCOL_VERSION); a record or hello with another version is refused with mesh.bad_version | | Phone protocol label | commission-phone-v1 | | Test vectors | crate/fixtures/phone-handshake.json | | Dependencies | External crates only; no path, git or workspace dependencies in crate/Cargo.toml |

The crate's behaviour checks are public functions in #[doc(hidden)] pub mod checks inside each module, so a host can run the same checks against its own copy. The checks in tests/checks.rs call every one of them.

The fixture is generated by the crate and verified by a check, and a client in another language reads the same file. The iOS shell in CommissionAI derives the session keys from the fixture's secrets and compares its sealed frames byte for byte.

How CommissionAI uses it

CommissionAI keeps a byte-identical pinned copy of crate/ at service/crates/mesh, the lowest layer of its Rust crates, and re-exports its modules where they used to live, so the rest of the daemon does not change. CommissionAI's scripts/extracted.py sync mesh <checkout> refreshes the copy and records its hash, and CommissionAI's lint fails if the copy is edited by hand. Change the code here, commit, then sync.

Test

cargo test --locked --workspace
cargo clippy --locked --workspace --all-targets -- -D warnings
sh scripts/pack-npm.sh

The link and stream checks run complete nodes over in-memory duplex streams, so they need no network and no other process. To regenerate the phone fixture after a deliberate protocol change:

COMMISSION_MESH_UPDATE_FIXTURE=1 cargo test --locked -p commission-mesh-tests --test checks phone

Release

Update version in package.json and crate/Cargo.toml, commit and push a v<version> tag. The release workflow tests the crate, packs the npm tarball, checks it with npm publish --dry-run, creates the GitHub release and publishes @patrick-lai/commission-ai-mesh with provenance. Run the workflow by hand with dry_run on (the default) to do everything except create the release and publish.

License

MIT. See LICENSE.