(feat): add package.json for easy wasm installs

(feat): add code quality control (fix): ci rewritten for forgejo (qol): move docs to dedicated docs/ folder
2026-06-27 02:32:43 +02:00 · 2026-06-27 02:32:43 +02:00 · 22245e673d
commit 22245e673d
parent 43f028a1f6
20 changed files with 354 additions and 112 deletions
--- a/docs/NATIVE-HOST.md
+++ b/docs/NATIVE-HOST.md
@ -0,0 +1,342 @@
+# MTP Native Host
+
+The native host is a Rust library (`mtp-host`) that runs a QUIC server, accepts
+MTP client connections, negotiates protocol versions, and optionally performs a
+mutual-authentication handshake (login/register) using Ed25519 and ML-DSA-65
+signatures.
+
+## Cargo Dependency
+
+```toml
+[dependencies]
+mtp = { path = "/path/to/mtp", features = ["host"] }
+
+# Add crypto for authenticated connections:
+mtp = { path = "/path/to/mtp", features = ["host", "crypto"] }
+```
+
+## HostConfig
+
+```rust
+use mtp::host::HostConfig;
+use std::net::{IpAddr, Ipv4Addr};
+
+let config = HostConfig {
+    ip: IpAddr::V4(Ipv4Addr::UNSPECIFIED),
+    port: 4433,
+    tls_fullchain: std::fs::read("cert.pem")?,
+    tls_key: std::fs::read("key.pem")?,
+
+    // Crypto fields (required when feature = "crypto"):
+    require_authentication: true,
+    host_id: 1,
+    host_keyring: /* Keyring */,
+    get_existing_user: Box::new(|client_id: u64| -> Option<PublicKeyBundle> {
+        CLIENT_DB.lock().unwrap().get(&client_id).cloned()
+    }),
+    complete_register: Box::new(|bundle: PublicKeyBundle| -> u64 {
+        let id = next_id();
+        CLIENT_DB.lock().unwrap().insert(id, bundle);
+        id
+    }),
+};
+```
+
+| Field                  | Type                                    | Description                                    |
+|------------------------|-----------------------------------------|------------------------------------------------|
+| `ip`                   | `IpAddr`                                | Bind address                                   |
+| `port`                 | `u16`                                   | Listen port                                    |
+| `tls_fullchain`        | `Vec<u8>`                               | PEM-encoded TLS certificate chain              |
+| `tls_key`              | `Vec<u8>`                               | PEM-encoded TLS private key                    |
+| `require_authentication` | `bool` (crypto)                      | Enable login/register handshake                |
+| `host_id`              | `u64` (crypto)                          | Host identifier                                |
+| `host_keyring`         | `Keyring` (crypto)                      | Host's signing and KEM keys                    |
+| `get_existing_user`    | `Box<dyn Fn(u64) -> Option<PublicKeyBundle> + Send>` (crypto) | Lookup callback for login |
+| `complete_register`    | `Box<dyn Fn(PublicKeyBundle) -> u64 + Send>` (crypto) | Registration callback, returns new client ID |
+
+### TLS
+
+The host requires a TLS certificate. For development, generate a self-signed
+certificate using `rcgen`. For production, use a CA-signed certificate.
+
+## Accepting Connections
+
+```rust
+use mtp::host::MTPHost;
+
+let mut host = MTPHost::new(config).await?;
+println!("Listening on {}", host.local_addr());
+
+while let Some(conn) = host.accept().await {
+    // conn is an MTPConnection ready for I/O
+}
+```
+
+### MTPConnection
+
+Returned by `accept()` after version negotiation (and authentication if
+enabled):
+
+```rust
+pub struct MTPConnection {
+    pub version: Version,
+    pub codec: VersionedCodec,
+    pub sender: Sender,
+    pub receiver: Receiver,
+    #[cfg(feature = "crypto")]
+    pub auth_state: AuthState,
+    #[cfg(feature = "crypto")]
+    pub client_id: u64,
+    #[cfg(feature = "crypto")]
+    pub client_public_key: Option<PublicKeyBundle>,
+}
+```
+
+- `version` -- the negotiated protocol version
+- `codec` -- a `VersionedCodec` scoped to the negotiated version (use for
+  version-aware encode/decode)
+- `sender` / `receiver` -- for message I/O
+- `client_id` -- the authenticated client's ID
+- `client_public_key` -- the client's public key bundle (for signature
+  verification of subsequent messages)
+
+## Version Negotiation
+
+When a client connects, `accept()` performs the following sequence:
+
+1. Accept the QUIC connection
+2. Read the client's first `CommunicationValue` (always encoded with reserved
+   type IDs)
+3. Extract the protocol version from `DataType::Version` (wire ID 3) as a
+   `DataValue::Str("major.minor")`
+4. Call `registry.negotiate(&[client_version])` to find the highest mutually
+   supported version
+5. Return `None` (closing the connection) if no compatible version exists
+6. Return an `MTPConnection` with the negotiated version
+
+The `Registry` is built automatically from all type maps defined in your
+`type-maps.yaml` via `Registry::builtin()`.
+
+### Registry
+
+```rust
+use mtp::codec::registry::Registry;
+
+let registry = host.registry();
+assert!(registry.supports(&Version(2, 0)));
+
+let negotiated = registry.negotiate(&[Version(1, 0), Version(2, 0)]);
+// -> Some(Version(2, 0)) if both versions are registered
+```
+
+## Authentication Flow
+
+When `require_authentication` is `true`, `accept()` runs a mutually-authenticated
+**challenge-response** handshake before returning the connection. The host issues
+a fresh, random `server_challenge` that the client must sign, which is what makes
+the client's proof unreplayable: a captured proof is bound to a one-time challenge
+the host generates per connection and will never reissue. The challenge lives only
+on the accepting task's stack; there is no replay database or shared state.
+
+All signed payloads begin with a one-byte domain-separation tag (see
+`mtp::crypto::auth`) so a signature for one step can never be reused as another.
+
+### Login
+
+```
+Client                                    Host
+  |                                         |
+  |  QUIC connect                           |
+  |---------------------------------------->|
+  |                                         |
+  |  Identification { Version, Id }         |  (unsigned hello)
+  |---------------------------------------->|
+  |                                         |  lookup get_existing_user(id)
+  |                                         |  generate random server_challenge
+  |  Challenge {                            |
+  |    ServerNonce(server_challenge),       |
+  |    Signature, [PqSignature]             |  host signs the challenge
+  |  }                                      |
+  |<----------------------------------------|
+  |  ChallengeResponse {                    |
+  |    ClientNonce, Signature, [PqSignature]|  client signs the challenge
+  |  }                                      |
+  |---------------------------------------->|
+  |                                         |  verify proof over server_challenge
+  |  IdentificationResponse {              |
+  |    Connected=true, Id,                  |
+  |    ClientNonce(echoed),                 |
+  |    Signature, [PqSignature]             |
+  |  }                                      |
+  |<----------------------------------------|
+```
+
+Payloads (`||` is concatenation, integers big-endian; `DS_*` are domain tags):
+
+- Host challenge: `DS_CHALLENGE || id (8) || server_challenge (16)`
+- Client proof:   `DS_LOGIN_PROOF || version_string || id (8) || server_challenge (16) || client_nonce (16)`
+- Host final:     `DS_HOST_FINAL || assigned_id (8) || client_nonce (16) || server_challenge (16)`
+
+### Register
+
+```
+Client                                    Host
+  |                                         |
+  |  QUIC connect                           |
+  |---------------------------------------->|
+  |                                         |
+  |  Register {                             |
+  |    Version,                             |  (unsigned hello)
+  |    PublicKeys (serialized PublicKeyBundle)
+  |  }                                      |
+  |---------------------------------------->|
+  |                                         |  generate random server_challenge
+  |  Challenge {                            |
+  |    ServerNonce(server_challenge),       |
+  |    Signature, [PqSignature]             |  (challenge binds id = 0)
+  |  }                                      |
+  |<----------------------------------------|
+  |  ChallengeResponse {                    |
+  |    ClientNonce, Signature, [PqSignature]|
+  |  }                                      |
+  |---------------------------------------->|
+  |                                         |  verify proof over server_challenge
+  |                                         |  call complete_register(bundle) -> new_id
+  |  RegisterResponse {                    |
+  |    Connected=true, Id(new_id),          |
+  |    ClientNonce(echoed),                 |
+  |    Signature, [PqSignature]             |
+  |  }                                      |
+  |<----------------------------------------|
+```
+
+The register client proof is:
+`DS_REGISTER_PROOF || version_string || server_challenge (16) || client_nonce (16) || public_key_bytes`
+
+After a successful handshake, `accept()` returns an `MTPConnection` with
+`auth_state = Authenticated`, `client_id` set, and `client_public_key`
+available for verifying subsequent signed messages from the client.
+
+### Rejection
+
+If verification fails or the client is not found (login), the host sends a
+rejection response with `Connected=false` and closes the send stream, returning
+`None` from `accept()`.
+
+## Handling Messages
+
+Use `conn.sender` and `conn.receiver` for bidirectional message exchange:
+
+```rust
+while let Some(conn) = host.accept().await {
+    tokio::spawn(async move {
+        loop {
+            match conn.receiver.receive().await {
+                Ok(msg) => {
+                    let response = process_message(&msg, &conn);
+                    conn.sender.send(&response).await.ok();
+                }
+                Err(_) => break,
+            }
+        }
+    });
+}
+```
+
+### Versioned Codec
+
+The `conn.codec` is a `VersionedCodec` pre-configured with the negotiated
+version. Use it to encode/decode with version-specific type maps:
+
+```rust
+let tm = conn.codec.registry().get(&conn.version).unwrap();
+
+// Look up type IDs for the negotiated version
+let desc_id = DataTypeId(tm.data_id_enum(DataType::Description).unwrap());
+let value = msg.get_data(desc_id);
+```
+
+## Host Callbacks
+
+### get_existing_user
+
+Called during login to retrieve a client's public key bundle for signature
+verification. Must return `Some(PublicKeyBundle)` if the client ID is known,
+or `None` to reject.
+
+```rust
+let get_existing_user = Box::new(|id: u64| -> Option<PublicKeyBundle> {
+    db.lock().unwrap().get(&id).cloned()
+});
+```
+
+### complete_register
+
+Called during registration to persist a new client's public key bundle and
+assign a client ID. The returned `u64` becomes the client's permanent
+identifier.
+
+```rust
+let complete_register = Box::new(|bundle: PublicKeyBundle| -> u64 {
+    let mut db = db.lock().unwrap();
+    let id = next_id;
+    next_id += 1;
+    db.insert(id, bundle);
+    id
+});
+```
+
+Both callbacks are called from within `accept()` and must be `Send`. They are
+invoked synchronously, so avoid long-running operations (or use `spawn_blocking`
+if needed, though the callbacks are `Fn`, not `AsyncFn`).
+
+## Host Key Generation
+
+Generate a host keyring once and persist it:
+
+```rust
+use mtp::crypto::{Ed25519Signer, Keyring, MlDsaSigner};
+use mtp::crypto::kem::HybridKem;
+
+let (_ed_signer, sig_sk, sig_pk) = Ed25519Signer::generate();
+let (_pq_signer, sig_pq_sk, sig_pq_pk) = MlDsaSigner::generate();
+let (kem_sk, kem_pk) = HybridKem::generate_keypair();
+
+let host_keyring = Keyring::new(kem_pk, kem_sk, sig_pq_pk, sig_pq_sk, sig_pk, sig_sk);
+
+// Save to disk
+let bytes = host_keyring.to_bytes();
+std::fs::write("host_keys.bin", bytes)?;
+```
+
+Export the public key bundle so clients can verify the host identity:
+
+```rust
+let bundle = host_keyring.public_key_bundle();
+std::fs::write("host_enc_kem_pk.bin", bundle.kem_public_key.as_bytes())?;
+std::fs::write("host_sig_pk.bin", bundle.sig_cl_public_key.as_bytes())?;
+std::fs::write("host_sig_pq_pk.bin", bundle.sig_pq_public_key.as_bytes())?;
+```
+
+## Policy
+
+The transport `Policy` is set to defaults internally. To customise (timeouts,
+send mode, etc.), use `mtp_transport::host()` directly instead of `MTPHost`:
+
+```rust
+use mtp_transport::{host, Policy};
+
+let transport = host(ip, port, cert, key, custom_policy).await?;
+// Then build version negotiation on top:
+// - accept transport.next()
+// - read first frame
+// - registry.negotiate()
+// - return MTPConnection
+```
+
+## Graceful Shutdown
+
+Drop the `MTPHost` to stop accepting new connections. Active connections
+continue until their `Sender`/`Receiver` are dropped or the peer disconnects.
+
+