mirror of
https://github.com/ruvnet/RuView
synced 2026-06-09 10:13:17 +00:00
Compare commits
6 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 ruv
|
d4f0e12073 | ||
|
ruv
|
07b792715f | ||
|
ruv
|
34eced880f | ||
|
ruv
|
bb154d4e78 | ||
|
ruv
|
1f5b7b48c9 | ||
|
ruv
|
a3478ea3b5 |
@@ -87,6 +87,7 @@ Ranked by build cost × user impact:
|
||||
| 3 | **Local SONA fine-tuning loop** (HA feedback → LoRA gradient steps) | ~2-3 weeks | Reduces false positives, closes #1 user complaint | P5 (this cog) |
|
||||
| 4 | **HACS gold-tier integration** (config flow + repairs + diagnostics) | ~4-6 weeks | Removes MQTT prerequisite for mainstream users | P9 (separate repo `hass-wifi-densepose`) |
|
||||
| 5 | **Matter Bridge with OccupancySensor + dynamic endpoints** | ~6-8 weeks | Apple Home / Google Home / Alexa native | **v0.8** dedicated sprint (after HACS adoption data) |
|
||||
| 6 | **Embedded MQTT broker (rumqttd) inside the cog** | ~1 week | "Works without external broker" but every HA install already has mosquitto / built-in | **v0.7** deferred — adds ~2 MB binary + ACL config surface for marginal user benefit. Dossier ranking did not include this in the prioritised v1 scope. |
|
||||
|
||||
## 4. Implementation phases
|
||||
|
||||
@@ -95,7 +96,7 @@ Ranked by build cost × user impact:
|
||||
| **P1** | Research dossier ([`docs/research/ADR-116-ha-matter-cog-research.md`](../research/ADR-116-ha-matter-cog-research.md)) | ✅ **done** — 8 sections, 30+ citations, v1 scope ranked |
|
||||
| **P2** | Cog crate scaffold (`v2/crates/cog-ha-matter/`) — Cargo.toml + `src/{lib,main,manifest}.rs`, workspace member, CLI args, `--print-manifest` flag, 2 manifest unit tests | ✅ **done** — `cargo check` + `cargo test` green |
|
||||
| **P3** | Wrap existing ADR-115 MQTT publisher as cog entry point | ✅ **wiring done** — `main.rs` boots ADR-115's `publisher::spawn` via `runtime::spawn_publisher` thin wrapper, holds a long-lived `broadcast::Sender<VitalsSnapshot>`, awaits Ctrl-C. Live-handle test green without a broker. Next (P3.5): subscribe to sensing-server `/v1/snapshot` WS and republish into the channel. |
|
||||
| **P4** | Seed-native enhancements (embedded broker, mDNS, witness) | in progress — (a) mDNS service-record builder shipped (`mdns::build_mdns_service`, 6-key locked TXT surface, PII-leak guard). (b) Witness hash-chain primitive shipped (`witness::WitnessChain` — append-only SHA-256 chain with `verify()` catching tampered payload / broken prev_hash / seq gap). (c) Responder (mdns-sd) + embedded rumqttd + Ed25519 signing layer still pending. |
|
||||
| **P4** | Seed-native enhancements (mDNS, witness; embedded broker deferred) | ✅ **shipped** — mDNS half: record-builder + ServiceInfo conversion + live responder wired into `main.rs` (HA auto-discovery on `_ruview-ha._tcp` works out of the box, `--no-mdns` flag for restrictive networks). Witness half: hash-chain + JSONL + file persistence + chain-level verify + Ed25519 signing. **Embedded rumqttd broker deferred to v0.7** per dossier §8 ranking — not in the prioritised v1 scope; v1 ships with external-broker only (mosquitto or HA's built-in broker). See §4 v1 scope table. |
|
||||
| **P5** | RuVector-backed threshold learning (SONA adaptation) | pending |
|
||||
| **P6** | Multi-Seed federation (cross-Seed dedup + witness) | pending |
|
||||
| **P7** | Matter Bridge mode (depends on matter-rs / esp-matter readiness) | pending |
|
||||
|
||||
Generated
+95
@@ -934,6 +934,8 @@ name = "cog-ha-matter"
|
||||
version = "0.3.0"
|
||||
dependencies = [
|
||||
"clap",
|
||||
"ed25519-dalek",
|
||||
"mdns-sd",
|
||||
"serde",
|
||||
"serde_json",
|
||||
"sha2",
|
||||
@@ -1074,6 +1076,12 @@ dependencies = [
|
||||
"wasm-bindgen",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "const-oid"
|
||||
version = "0.9.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "c2459377285ad874054d797f3ccebf984978aa39129f6eafde5cdc8315b612f8"
|
||||
|
||||
[[package]]
|
||||
name = "constant_time_eq"
|
||||
version = "0.1.5"
|
||||
@@ -1367,6 +1375,33 @@ dependencies = [
|
||||
"libloading 0.9.0",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "curve25519-dalek"
|
||||
version = "4.1.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "97fb8b7c4503de7d6ae7b42ab72a5a59857b4c937ec27a3d4539dba95b5ab2be"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"cpufeatures",
|
||||
"curve25519-dalek-derive",
|
||||
"digest",
|
||||
"fiat-crypto",
|
||||
"rustc_version",
|
||||
"subtle",
|
||||
"zeroize",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "curve25519-dalek-derive"
|
||||
version = "0.1.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f46882e17999c6cc590af592290432be3bce0428cb0d5f8b6715e4dc7b383eb3"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn 2.0.117",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "darling"
|
||||
version = "0.21.3"
|
||||
@@ -1428,6 +1463,7 @@ version = "0.7.10"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "e7c1832837b905bbfb5101e07cc24c8deddf52f93225eee6ead5f4d63d53ddcb"
|
||||
dependencies = [
|
||||
"const-oid",
|
||||
"pem-rfc7468",
|
||||
"zeroize",
|
||||
]
|
||||
@@ -1643,6 +1679,30 @@ dependencies = [
|
||||
"num-traits",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "ed25519"
|
||||
version = "2.2.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "115531babc129696a58c64a4fef0a8bf9e9698629fb97e9e40767d235cfbcd53"
|
||||
dependencies = [
|
||||
"pkcs8",
|
||||
"signature",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "ed25519-dalek"
|
||||
version = "2.2.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "70e796c081cee67dc755e1a36a0a172b897fab85fc3f6bc48307991f64e4eca9"
|
||||
dependencies = [
|
||||
"curve25519-dalek",
|
||||
"ed25519",
|
||||
"serde",
|
||||
"sha2",
|
||||
"subtle",
|
||||
"zeroize",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "either"
|
||||
version = "1.15.0"
|
||||
@@ -1773,6 +1833,12 @@ dependencies = [
|
||||
"simd-adler32",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "fiat-crypto"
|
||||
version = "0.2.9"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "28dea519a9695b9977216879a3ebfddf92f1c08c05d984f8996aecd6ecdc811d"
|
||||
|
||||
[[package]]
|
||||
name = "field-offset"
|
||||
version = "0.3.6"
|
||||
@@ -5097,6 +5163,16 @@ version = "0.1.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8b870d8c151b6f2fb93e84a13146138f05d02ed11c7e7c54f8826aaaf7c9f184"
|
||||
|
||||
[[package]]
|
||||
name = "pkcs8"
|
||||
version = "0.10.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f950b2377845cebe5cf8b5165cb3cc1a5e0fa5cfa3e1f7f55707d8fd82e0a7b7"
|
||||
dependencies = [
|
||||
"der",
|
||||
"spki",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "pkg-config"
|
||||
version = "0.3.32"
|
||||
@@ -6996,6 +7072,15 @@ dependencies = [
|
||||
"libc",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "signature"
|
||||
version = "2.2.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "77549399552de45a898a580c1b41d445bf730df867cc44e6c0233bbc4b8329de"
|
||||
dependencies = [
|
||||
"rand_core 0.6.4",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "simba"
|
||||
version = "0.9.1"
|
||||
@@ -7154,6 +7239,16 @@ dependencies = [
|
||||
"lock_api",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "spki"
|
||||
version = "0.7.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d91ed6c858b01f942cd56b37a94b3e0a1798290327d1236e4d9cf4eaca44d29d"
|
||||
dependencies = [
|
||||
"base64ct",
|
||||
"der",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "stable_deref_trait"
|
||||
version = "1.2.1"
|
||||
|
||||
@@ -35,9 +35,16 @@ wifi-densepose-sensing-server = { version = "0.3.0", path = "../wifi-densepose-s
|
||||
# Hardware crate for SyncPacket + NodeState bridging (ADR-110 substrate).
|
||||
wifi-densepose-hardware = { version = "0.3.0", path = "../wifi-densepose-hardware" }
|
||||
|
||||
# Witness chain (ADR-116 P4): SHA-256 only for now; Ed25519 signing
|
||||
# layers on top once we ship the key-management story.
|
||||
# Witness chain (ADR-116 P4): SHA-256 hash chain + Ed25519 signature
|
||||
# layer for tamper-evident audit logs (ADR-116 §2.2). Same version
|
||||
# already vetted by ruv-neural — keep them aligned.
|
||||
sha2 = { workspace = true }
|
||||
ed25519-dalek = "2.1"
|
||||
|
||||
# mDNS responder (ADR-116 P4 §2.2): pure-Rust zero-conf daemon.
|
||||
# Same version pinned in wifi-densepose-desktop to keep the
|
||||
# workspace lockfile narrow.
|
||||
mdns-sd = "0.11"
|
||||
|
||||
[dev-dependencies]
|
||||
tempfile = "3.10"
|
||||
|
||||
@@ -30,6 +30,7 @@ pub mod manifest;
|
||||
pub mod mdns;
|
||||
pub mod runtime;
|
||||
pub mod witness;
|
||||
pub mod witness_signing;
|
||||
|
||||
/// Cog identifier used in Seed's app-registry.json + the manifest.
|
||||
pub const COG_ID: &str = "ha-matter";
|
||||
|
||||
@@ -48,6 +48,24 @@ struct Args {
|
||||
/// control plane and exit. Useful for the build-time signer.
|
||||
#[arg(long)]
|
||||
print_manifest: bool,
|
||||
|
||||
/// mDNS hostname for the Seed advertisement. Must end with
|
||||
/// `.local.` per RFC 6762. Default lets HA's discovery find a
|
||||
/// dev cog on localhost without LAN config.
|
||||
#[arg(long, default_value = "cog-ha-matter.local.")]
|
||||
mdns_hostname: String,
|
||||
|
||||
/// LAN-routable IPv4 the cog binds the control plane on. The
|
||||
/// mDNS responder advertises this; HA reaches back to it for
|
||||
/// MQTT + Matter Bridge.
|
||||
#[arg(long, default_value = "127.0.0.1")]
|
||||
mdns_ipv4: String,
|
||||
|
||||
/// Skip the mDNS responder. Useful in containerised CI where
|
||||
/// multicast bind is filtered, or when running multiple cog
|
||||
/// instances on the same loopback.
|
||||
#[arg(long)]
|
||||
no_mdns: bool,
|
||||
}
|
||||
|
||||
#[tokio::main]
|
||||
@@ -115,6 +133,35 @@ async fn main() -> ExitCode {
|
||||
// HA install with no nodes online looks like.
|
||||
let _ = &state_tx;
|
||||
|
||||
// P4: mDNS responder. HA's auto-discovery picks the cog up on
|
||||
// `_ruview-ha._tcp` so users don't need to type broker host/port.
|
||||
let _mdns_handle = if args.no_mdns {
|
||||
None
|
||||
} else {
|
||||
let identity = runtime::CogIdentity::default_for_build();
|
||||
let service = cog_ha_matter::mdns::build_mdns_service(
|
||||
&identity,
|
||||
cog_ha_matter::DEFAULT_CONTROL_PORT,
|
||||
args.mqtt_port,
|
||||
args.privacy_mode,
|
||||
);
|
||||
match runtime::start_mdns_responder(&service, &args.mdns_hostname, &args.mdns_ipv4) {
|
||||
Ok(h) => {
|
||||
info!(
|
||||
fullname = h.fullname(),
|
||||
hostname = %args.mdns_hostname,
|
||||
ipv4 = %args.mdns_ipv4,
|
||||
"mDNS responder registered — HA auto-discovery should find the cog now"
|
||||
);
|
||||
Some(h)
|
||||
}
|
||||
Err(e) => {
|
||||
warn!(error = ?e, "mDNS responder failed to start — discovery disabled, falling back to manual HA config");
|
||||
None
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
// Wait on Ctrl-C so the cog runs as a long-lived daemon under
|
||||
// the Seed's process supervisor.
|
||||
tokio::select! {
|
||||
@@ -125,5 +172,8 @@ async fn main() -> ExitCode {
|
||||
warn!(?joined, "publisher task exited unexpectedly");
|
||||
}
|
||||
}
|
||||
|
||||
// _mdns_handle drops here, sending the mDNS goodbye packet so
|
||||
// HA's discovery integration sees the service leave cleanly.
|
||||
ExitCode::SUCCESS
|
||||
}
|
||||
|
||||
@@ -38,6 +38,10 @@
|
||||
//! are broadcast in cleartext and harvested by passive scanners, so
|
||||
//! treating them as PII-clean is part of the privacy posture.
|
||||
|
||||
use std::collections::HashMap;
|
||||
|
||||
use mdns_sd::ServiceInfo;
|
||||
|
||||
use crate::COG_ID;
|
||||
|
||||
/// Default mDNS instance name template. `{node_id}` is substituted
|
||||
@@ -74,6 +78,33 @@ impl MdnsService {
|
||||
.find(|(k, _)| k == key)
|
||||
.map(|(_, v)| v.as_str())
|
||||
}
|
||||
|
||||
/// Convert into the `mdns_sd::ServiceInfo` the responder daemon
|
||||
/// consumes. Pure transform — no socket binding, no daemon
|
||||
/// registration. The caller wires the resulting `ServiceInfo`
|
||||
/// into `ServiceDaemon::register` (next iter).
|
||||
///
|
||||
/// `hostname` should end in `.local.` per RFC 6762 — e.g.
|
||||
/// `"cognitum-seed-1.local."`. `ipv4` is the LAN-routable
|
||||
/// address HA's discovery will reach back on.
|
||||
pub fn to_service_info(
|
||||
&self,
|
||||
hostname: &str,
|
||||
ipv4: &str,
|
||||
) -> Result<ServiceInfo, mdns_sd::Error> {
|
||||
let mut props: HashMap<String, String> = HashMap::with_capacity(self.txt_records.len());
|
||||
for (k, v) in &self.txt_records {
|
||||
props.insert(k.clone(), v.clone());
|
||||
}
|
||||
ServiceInfo::new(
|
||||
&self.service_type,
|
||||
&self.instance_name,
|
||||
hostname,
|
||||
ipv4,
|
||||
self.control_port,
|
||||
Some(props),
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
/// Build the cog's mDNS advertisement record from the cog's typed
|
||||
@@ -203,6 +234,51 @@ mod tests {
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn to_service_info_carries_service_type_and_port() {
|
||||
let svc = build_mdns_service(&id(), 9180, 1883, false);
|
||||
let info = svc
|
||||
.to_service_info("cognitum-seed-1.local.", "192.168.1.50")
|
||||
.expect("valid service info");
|
||||
// mdns-sd may rewrite the type with a trailing dot; allow
|
||||
// both forms.
|
||||
let ty = info.get_type();
|
||||
assert!(
|
||||
ty == "_ruview-ha._tcp" || ty == "_ruview-ha._tcp.",
|
||||
"unexpected service type: {ty}"
|
||||
);
|
||||
assert_eq!(info.get_port(), 9180);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn to_service_info_propagates_txt_records() {
|
||||
let svc = build_mdns_service(&id(), 9180, 1883, true);
|
||||
let info = svc
|
||||
.to_service_info("cognitum-seed-1.local.", "192.168.1.50")
|
||||
.expect("valid service info");
|
||||
// Every locked TXT key must reach the wire-format payload.
|
||||
assert_eq!(info.get_property_val_str("cog_id"), Some(crate::COG_ID));
|
||||
assert_eq!(info.get_property_val_str("mqtt_port"), Some("1883"));
|
||||
assert_eq!(info.get_property_val_str("privacy"), Some("1"));
|
||||
assert_eq!(info.get_property_val_str("proto"), Some("ruview-ha/1"));
|
||||
assert!(info.get_property_val_str("node_id").is_some());
|
||||
assert!(info.get_property_val_str("cog_version").is_some());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn to_service_info_does_not_silently_drop_caller_hostname() {
|
||||
// mdns-sd 0.11 accepts bare hostnames (no `.local.`); the
|
||||
// responsibility for the trailing dot lives in our wrapper.
|
||||
// Lock that the caller's hostname survives the conversion
|
||||
// verbatim — a future bump that starts mutating the value
|
||||
// surfaces a named test instead of a silent change.
|
||||
let svc = build_mdns_service(&id(), 9180, 1883, false);
|
||||
let info = svc
|
||||
.to_service_info("cognitum-seed-1.local.", "192.168.1.50")
|
||||
.unwrap();
|
||||
assert!(info.get_hostname().contains("cognitum-seed-1"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn txt_keys_match_locked_surface() {
|
||||
// The HA-side YAML auto-discovery binds on these exact keys.
|
||||
|
||||
@@ -21,6 +21,7 @@
|
||||
|
||||
use std::sync::Arc;
|
||||
|
||||
use mdns_sd::ServiceDaemon;
|
||||
use tokio::{sync::broadcast, task::JoinHandle};
|
||||
use wifi_densepose_sensing_server::mqtt::{
|
||||
config::{MqttConfig, PublishRates, TlsConfig},
|
||||
@@ -29,6 +30,8 @@ use wifi_densepose_sensing_server::mqtt::{
|
||||
DEFAULT_DISCOVERY_PREFIX, MANUFACTURER,
|
||||
};
|
||||
|
||||
use crate::mdns::MdnsService;
|
||||
|
||||
/// Caller-supplied identity for the cog instance. Filled in by the
|
||||
/// cog runtime from the mDNS hostname / Seed control plane in
|
||||
/// production; threaded as a parameter so tests can build inputs
|
||||
@@ -129,6 +132,66 @@ pub fn spawn_publisher(
|
||||
publisher::spawn(Arc::new(config), discovery, state_rx)
|
||||
}
|
||||
|
||||
/// Owned handle to a live mDNS responder. Holding it keeps the
|
||||
/// service advertised; `shutdown` unregisters cleanly so HA's
|
||||
/// discovery integration sees a goodbye packet instead of a
|
||||
/// dropped advertisement.
|
||||
///
|
||||
/// `Drop` is best-effort: tries unregister + daemon shutdown but
|
||||
/// swallows errors, since panicking in Drop would mask the real
|
||||
/// failure that prompted the shutdown.
|
||||
pub struct MdnsResponderHandle {
|
||||
daemon: ServiceDaemon,
|
||||
fullname: String,
|
||||
}
|
||||
|
||||
impl MdnsResponderHandle {
|
||||
/// Fully-qualified DNS-SD name (`<instance>.<type>.<domain>`).
|
||||
/// Exposed for tests + logging; the responder uses it to
|
||||
/// unregister.
|
||||
pub fn fullname(&self) -> &str {
|
||||
&self.fullname
|
||||
}
|
||||
|
||||
/// Unregister the service and shut down the daemon. Returns
|
||||
/// any error so the caller's shutdown sequence can surface it.
|
||||
pub fn shutdown(self) -> Result<(), mdns_sd::Error> {
|
||||
let _ = self.daemon.unregister(&self.fullname);
|
||||
let _ = self.daemon.shutdown()?;
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for MdnsResponderHandle {
|
||||
fn drop(&mut self) {
|
||||
let _ = self.daemon.unregister(&self.fullname);
|
||||
let _ = self.daemon.shutdown();
|
||||
}
|
||||
}
|
||||
|
||||
/// Start the mDNS responder for a cog and register its service.
|
||||
///
|
||||
/// Binds a multicast socket (`mdns_sd::ServiceDaemon::new`) and
|
||||
/// publishes `service` under `hostname` (must end in `.local.`)
|
||||
/// and `ipv4` (the LAN-routable address HA's discovery reaches
|
||||
/// back on).
|
||||
///
|
||||
/// Live-I/O: binding multicast may fail in containerised CI or
|
||||
/// on networks where 5353/udp is filtered — callers should treat
|
||||
/// the error as recoverable (log + retry, or fall back to manual
|
||||
/// HA configuration) rather than fatal to the cog.
|
||||
pub fn start_mdns_responder(
|
||||
service: &MdnsService,
|
||||
hostname: &str,
|
||||
ipv4: &str,
|
||||
) -> Result<MdnsResponderHandle, mdns_sd::Error> {
|
||||
let daemon = ServiceDaemon::new()?;
|
||||
let info = service.to_service_info(hostname, ipv4)?;
|
||||
let fullname = info.get_fullname().to_string();
|
||||
daemon.register(info)?;
|
||||
Ok(MdnsResponderHandle { daemon, fullname })
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
@@ -230,6 +293,36 @@ mod tests {
|
||||
assert!(DEFAULT_STATE_CHANNEL_CAPACITY >= 64);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn mdns_responder_fullname_concatenates_instance_and_service_type() {
|
||||
// Live-I/O test: binds multicast on the loopback adapter.
|
||||
// Skips with a warning if the host's network stack refuses
|
||||
// the bind (containerised CI without --network host, etc.)
|
||||
// rather than failing the whole test suite.
|
||||
use crate::mdns::build_mdns_service;
|
||||
let svc = build_mdns_service(&id(), 9180, 1883, false);
|
||||
let handle = match start_mdns_responder(&svc, "cog-ha-matter-test.local.", "127.0.0.1") {
|
||||
Ok(h) => h,
|
||||
Err(e) => {
|
||||
eprintln!("mdns multicast bind not available in this sandbox: {e} — skipping");
|
||||
return;
|
||||
}
|
||||
};
|
||||
// Fullname format is "<instance>.<service_type>." per RFC 6763.
|
||||
// mdns-sd may URL-escape special chars (— in instance name) so
|
||||
// we only assert on the service-type segment which is stable.
|
||||
let fullname = handle.fullname().to_string();
|
||||
assert!(
|
||||
!fullname.is_empty(),
|
||||
"fullname empty after register"
|
||||
);
|
||||
assert!(
|
||||
fullname.contains("_ruview-ha._tcp"),
|
||||
"fullname `{fullname}` missing service type"
|
||||
);
|
||||
handle.shutdown().expect("clean shutdown");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn default_identity_carries_pkg_version_and_pid() {
|
||||
let identity = CogIdentity::default_for_build();
|
||||
|
||||
@@ -30,6 +30,8 @@
|
||||
//! when the chain spans days and the auditor wants O(log n)
|
||||
//! inclusion proofs.
|
||||
|
||||
use std::io::{self, BufRead, Write};
|
||||
|
||||
use sha2::{Digest, Sha256};
|
||||
|
||||
/// 32-byte hash output. Lifted into a newtype so a future migration
|
||||
@@ -53,6 +55,22 @@ impl WitnessHash {
|
||||
}
|
||||
s
|
||||
}
|
||||
|
||||
/// Parse a 64-char lowercase-hex string back into a `WitnessHash`.
|
||||
/// Rejects wrong-length input and non-hex characters — used by
|
||||
/// the JSONL parser when reading audit bundles.
|
||||
pub fn from_hex(s: &str) -> Result<WitnessHash, WitnessParseError> {
|
||||
if s.len() != 64 {
|
||||
return Err(WitnessParseError::HashLength { found: s.len() });
|
||||
}
|
||||
let mut out = [0u8; 32];
|
||||
for (i, byte) in out.iter_mut().enumerate() {
|
||||
let lo = i * 2;
|
||||
*byte = u8::from_str_radix(&s[lo..lo + 2], 16)
|
||||
.map_err(|_| WitnessParseError::HashHex { at: lo })?;
|
||||
}
|
||||
Ok(WitnessHash(out))
|
||||
}
|
||||
}
|
||||
|
||||
/// A single witnessed event. Append-only — once committed to a
|
||||
@@ -182,6 +200,49 @@ impl WitnessChain {
|
||||
&self.events
|
||||
}
|
||||
|
||||
/// Stream every event to a JSONL sink. Each event becomes one
|
||||
/// line terminated by `\n`. Empty chains write zero bytes.
|
||||
///
|
||||
/// The caller owns the writer — `File`, `BufWriter`, an
|
||||
/// in-memory `Vec<u8>` for tests — so this method never
|
||||
/// allocates beyond per-event line buffers.
|
||||
pub fn write_jsonl<W: Write>(&self, w: &mut W) -> io::Result<()> {
|
||||
for ev in &self.events {
|
||||
w.write_all(ev.to_jsonl_line().as_bytes())?;
|
||||
w.write_all(b"\n")?;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Read a JSONL audit bundle into a fresh `WitnessChain`. Each
|
||||
/// non-empty line is parsed via `WitnessEvent::from_jsonl_line`
|
||||
/// (which re-verifies the stored hash), then the loaded chain
|
||||
/// is end-to-end verified via [`WitnessChain::verify`] to catch
|
||||
/// out-of-order events or replayed prefixes.
|
||||
///
|
||||
/// Bundle errors surface with their `line_no` (1-indexed) so an
|
||||
/// auditor can point at the bad record.
|
||||
pub fn read_jsonl<R: BufRead>(r: R) -> Result<WitnessChain, WitnessReadError> {
|
||||
let mut chain = WitnessChain::new();
|
||||
for (i, line_res) in r.lines().enumerate() {
|
||||
let line_no = i + 1;
|
||||
let line = line_res.map_err(|e| WitnessReadError::Io {
|
||||
line_no,
|
||||
msg: e.to_string(),
|
||||
})?;
|
||||
if line.trim().is_empty() {
|
||||
continue; // tolerate blank lines / trailing \n
|
||||
}
|
||||
let ev = WitnessEvent::from_jsonl_line(&line)
|
||||
.map_err(|source| WitnessReadError::Parse { line_no, source })?;
|
||||
chain.events.push(ev);
|
||||
}
|
||||
chain
|
||||
.verify()
|
||||
.map_err(|source| WitnessReadError::Verify { source })?;
|
||||
Ok(chain)
|
||||
}
|
||||
|
||||
/// Verify every event's `this_hash` matches the canonical bytes,
|
||||
/// every `prev_hash` matches the predecessor's `this_hash`, and
|
||||
/// `seq` is gap-free starting at 0.
|
||||
@@ -223,6 +284,161 @@ pub enum WitnessVerifyError {
|
||||
HashMismatch { at: usize },
|
||||
}
|
||||
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
pub enum WitnessReadError {
|
||||
#[error("io error at line {line_no}: {msg}")]
|
||||
Io { line_no: usize, msg: String },
|
||||
#[error("parse error at line {line_no}: {source}")]
|
||||
Parse {
|
||||
line_no: usize,
|
||||
#[source]
|
||||
source: WitnessParseError,
|
||||
},
|
||||
#[error("chain-level verify failed: {source}")]
|
||||
Verify {
|
||||
#[source]
|
||||
source: WitnessVerifyError,
|
||||
},
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
|
||||
pub enum WitnessParseError {
|
||||
#[error("invalid JSON: {0}")]
|
||||
Json(String),
|
||||
#[error("missing required field `{0}`")]
|
||||
MissingField(&'static str),
|
||||
#[error("field `{field}` has wrong type")]
|
||||
WrongType { field: &'static str },
|
||||
#[error("hash hex must be 64 chars, got {found}")]
|
||||
HashLength { found: usize },
|
||||
#[error("hash hex parse error at byte offset {at}")]
|
||||
HashHex { at: usize },
|
||||
#[error("payload hex parse error at byte offset {at}")]
|
||||
PayloadHex { at: usize },
|
||||
#[error("payload hex must be even length, got {found}")]
|
||||
PayloadLength { found: usize },
|
||||
#[error("recomputed hash does not match this_hash — bundle is forged or corrupted")]
|
||||
HashMismatch,
|
||||
}
|
||||
|
||||
fn hex_encode(bytes: &[u8]) -> String {
|
||||
let mut s = String::with_capacity(bytes.len() * 2);
|
||||
for b in bytes {
|
||||
s.push_str(&format!("{b:02x}"));
|
||||
}
|
||||
s
|
||||
}
|
||||
|
||||
fn hex_decode(s: &str) -> Result<Vec<u8>, WitnessParseError> {
|
||||
if s.len() % 2 != 0 {
|
||||
return Err(WitnessParseError::PayloadLength { found: s.len() });
|
||||
}
|
||||
let mut out = Vec::with_capacity(s.len() / 2);
|
||||
for i in (0..s.len()).step_by(2) {
|
||||
let byte = u8::from_str_radix(&s[i..i + 2], 16)
|
||||
.map_err(|_| WitnessParseError::PayloadHex { at: i })?;
|
||||
out.push(byte);
|
||||
}
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
impl WitnessEvent {
|
||||
/// Serialize one event to a single JSONL line (no trailing
|
||||
/// newline). The format is the audit-bundle wire shape; tools
|
||||
/// downstream parse it line-by-line with [`Self::from_jsonl_line`].
|
||||
///
|
||||
/// Field ordering is locked alphabetically for byte-stable
|
||||
/// output across rebuilds — auditors hash whole bundles, so a
|
||||
/// rebuild that reordered fields would silently invalidate
|
||||
/// archival hashes.
|
||||
///
|
||||
/// Wire shape:
|
||||
///
|
||||
/// ```json
|
||||
/// {"kind":"...","payload_hex":"...","prev_hash":"...","seq":N,"this_hash":"...","timestamp_unix_s":N}
|
||||
/// ```
|
||||
pub fn to_jsonl_line(&self) -> String {
|
||||
// Hand-rolled instead of serde_derive so the wire-format
|
||||
// ordering is under direct test control.
|
||||
format!(
|
||||
"{{\"kind\":{kind},\"payload_hex\":\"{payload}\",\"prev_hash\":\"{prev}\",\"seq\":{seq},\"this_hash\":\"{this}\",\"timestamp_unix_s\":{ts}}}",
|
||||
kind = serde_json::to_string(&self.kind).expect("string is always serializable"),
|
||||
payload = hex_encode(&self.payload),
|
||||
prev = self.prev_hash.to_hex(),
|
||||
seq = self.seq,
|
||||
this = self.this_hash.to_hex(),
|
||||
ts = self.timestamp_unix_s,
|
||||
)
|
||||
}
|
||||
|
||||
/// Parse one JSONL line back into a `WitnessEvent`. Re-verifies
|
||||
/// the stored `this_hash` against the canonical bytes — a
|
||||
/// tampered bundle fires [`WitnessParseError::HashMismatch`]
|
||||
/// instead of silently loading forged events.
|
||||
pub fn from_jsonl_line(line: &str) -> Result<WitnessEvent, WitnessParseError> {
|
||||
let v: serde_json::Value =
|
||||
serde_json::from_str(line).map_err(|e| WitnessParseError::Json(e.to_string()))?;
|
||||
let obj = v
|
||||
.as_object()
|
||||
.ok_or(WitnessParseError::WrongType { field: "<root>" })?;
|
||||
|
||||
let seq = obj
|
||||
.get("seq")
|
||||
.ok_or(WitnessParseError::MissingField("seq"))?
|
||||
.as_u64()
|
||||
.ok_or(WitnessParseError::WrongType { field: "seq" })?;
|
||||
let timestamp_unix_s = obj
|
||||
.get("timestamp_unix_s")
|
||||
.ok_or(WitnessParseError::MissingField("timestamp_unix_s"))?
|
||||
.as_u64()
|
||||
.ok_or(WitnessParseError::WrongType {
|
||||
field: "timestamp_unix_s",
|
||||
})?;
|
||||
let kind = obj
|
||||
.get("kind")
|
||||
.ok_or(WitnessParseError::MissingField("kind"))?
|
||||
.as_str()
|
||||
.ok_or(WitnessParseError::WrongType { field: "kind" })?
|
||||
.to_string();
|
||||
let prev_hash = WitnessHash::from_hex(
|
||||
obj.get("prev_hash")
|
||||
.ok_or(WitnessParseError::MissingField("prev_hash"))?
|
||||
.as_str()
|
||||
.ok_or(WitnessParseError::WrongType { field: "prev_hash" })?,
|
||||
)?;
|
||||
let this_hash = WitnessHash::from_hex(
|
||||
obj.get("this_hash")
|
||||
.ok_or(WitnessParseError::MissingField("this_hash"))?
|
||||
.as_str()
|
||||
.ok_or(WitnessParseError::WrongType { field: "this_hash" })?,
|
||||
)?;
|
||||
let payload = hex_decode(
|
||||
obj.get("payload_hex")
|
||||
.ok_or(WitnessParseError::MissingField("payload_hex"))?
|
||||
.as_str()
|
||||
.ok_or(WitnessParseError::WrongType {
|
||||
field: "payload_hex",
|
||||
})?,
|
||||
)?;
|
||||
|
||||
// Re-verify the stored hash. The on-disk hash is purely
|
||||
// declarative; this is what makes the JSONL a witness.
|
||||
let recomputed = hash_event(prev_hash, seq, timestamp_unix_s, &kind, &payload);
|
||||
if recomputed != this_hash {
|
||||
return Err(WitnessParseError::HashMismatch);
|
||||
}
|
||||
|
||||
Ok(WitnessEvent {
|
||||
seq,
|
||||
prev_hash,
|
||||
timestamp_unix_s,
|
||||
kind,
|
||||
payload,
|
||||
this_hash,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
@@ -342,4 +558,238 @@ mod tests {
|
||||
let h2 = hash_event(WitnessHash::GENESIS, 0, 100, "k", b"b");
|
||||
assert_ne!(h1, h2);
|
||||
}
|
||||
|
||||
// ---- JSONL persistence ----
|
||||
|
||||
fn fresh_event() -> WitnessEvent {
|
||||
let mut c = WitnessChain::new();
|
||||
c.append("fall_risk_elevated", br#"{"node":"kitchen"}"#, 1779512400);
|
||||
c.events()[0].clone()
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn jsonl_round_trip_preserves_all_fields() {
|
||||
let original = fresh_event();
|
||||
let line = original.to_jsonl_line();
|
||||
let parsed = WitnessEvent::from_jsonl_line(&line).expect("clean line round-trips");
|
||||
assert_eq!(parsed, original);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn jsonl_line_has_no_embedded_newline() {
|
||||
// JSONL is one record per line; an embedded \n in the
|
||||
// serialized form would corrupt the file format.
|
||||
let line = fresh_event().to_jsonl_line();
|
||||
assert!(!line.contains('\n'));
|
||||
assert!(!line.contains('\r'));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn jsonl_field_order_is_alphabetical_for_byte_stability() {
|
||||
// Auditors archive whole bundles and hash them — reordered
|
||||
// fields would silently invalidate archival hashes. Lock
|
||||
// the order with a substring check on a known event.
|
||||
let line = fresh_event().to_jsonl_line();
|
||||
let order = ["kind", "payload_hex", "prev_hash", "seq", "this_hash", "timestamp_unix_s"];
|
||||
let mut last = 0usize;
|
||||
for field in order {
|
||||
let pos = line.find(field).unwrap_or_else(|| panic!("missing field `{field}`"));
|
||||
assert!(pos > last, "field `{field}` out of alphabetical order");
|
||||
last = pos;
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn jsonl_parser_rejects_tampered_payload() {
|
||||
let original = fresh_event();
|
||||
let line = original.to_jsonl_line();
|
||||
// Flip one nibble in the payload hex — the stored hash
|
||||
// won't match the recomputed hash.
|
||||
let tampered = line.replacen("payload_hex\":\"7b", "payload_hex\":\"6b", 1);
|
||||
assert_ne!(line, tampered, "test fixture didn't flip a byte");
|
||||
let err = WitnessEvent::from_jsonl_line(&tampered).unwrap_err();
|
||||
assert!(
|
||||
matches!(err, WitnessParseError::HashMismatch),
|
||||
"expected HashMismatch, got {err:?}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn jsonl_parser_rejects_non_hex_hash() {
|
||||
// Replace the hex hash with non-hex chars — must fire a
|
||||
// structured error, not a panic.
|
||||
let original = fresh_event();
|
||||
let line = original.to_jsonl_line();
|
||||
let broken = line.replacen(
|
||||
&original.this_hash.to_hex()[..4],
|
||||
"ZZZZ",
|
||||
1,
|
||||
);
|
||||
let err = WitnessEvent::from_jsonl_line(&broken).unwrap_err();
|
||||
assert!(matches!(err, WitnessParseError::HashHex { .. }));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn jsonl_parser_rejects_missing_field() {
|
||||
let bad = r#"{"seq":0,"kind":"k","prev_hash":"00","this_hash":"00","timestamp_unix_s":1}"#;
|
||||
let err = WitnessEvent::from_jsonl_line(bad).unwrap_err();
|
||||
// Missing payload_hex; should fire MissingField before any
|
||||
// hex decode happens.
|
||||
assert!(matches!(err, WitnessParseError::MissingField("payload_hex")
|
||||
| WitnessParseError::HashLength { .. }));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn hex_encode_decode_round_trip() {
|
||||
let cases: &[&[u8]] = &[
|
||||
b"",
|
||||
b"\x00",
|
||||
b"\xff",
|
||||
b"hello world",
|
||||
&[0x00, 0x01, 0xab, 0xcd, 0xef],
|
||||
];
|
||||
for c in cases {
|
||||
let encoded = hex_encode(c);
|
||||
let decoded = hex_decode(&encoded).unwrap();
|
||||
assert_eq!(&decoded[..], *c, "round-trip failed for {c:?}");
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn hex_decode_rejects_odd_length() {
|
||||
let err = hex_decode("abc").unwrap_err();
|
||||
assert!(matches!(err, WitnessParseError::PayloadLength { found: 3 }));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn witness_hash_from_hex_round_trip() {
|
||||
let h = WitnessHash([0x12; 32]);
|
||||
let hex = h.to_hex();
|
||||
let parsed = WitnessHash::from_hex(&hex).unwrap();
|
||||
assert_eq!(parsed, h);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn witness_hash_from_hex_rejects_wrong_length() {
|
||||
let err = WitnessHash::from_hex("ab").unwrap_err();
|
||||
assert!(matches!(err, WitnessParseError::HashLength { found: 2 }));
|
||||
}
|
||||
|
||||
// ---- file persistence (write_jsonl / read_jsonl) ----
|
||||
|
||||
#[test]
|
||||
fn write_jsonl_empty_chain_writes_zero_bytes() {
|
||||
let c = WitnessChain::new();
|
||||
let mut buf = Vec::new();
|
||||
c.write_jsonl(&mut buf).unwrap();
|
||||
assert_eq!(buf, b"");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn write_then_read_round_trips_multi_event_chain() {
|
||||
let mut written = WitnessChain::new();
|
||||
written.append("a", b"first", 100);
|
||||
written.append("b", b"second", 101);
|
||||
written.append("c", br#"{"x":1}"#, 102);
|
||||
|
||||
let mut buf = Vec::new();
|
||||
written.write_jsonl(&mut buf).unwrap();
|
||||
|
||||
let read_back = WitnessChain::read_jsonl(buf.as_slice()).unwrap();
|
||||
assert_eq!(read_back.len(), 3);
|
||||
assert_eq!(read_back.events(), written.events());
|
||||
assert_eq!(read_back.tip(), written.tip());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn write_jsonl_separates_events_with_newline() {
|
||||
let mut c = WitnessChain::new();
|
||||
c.append("a", b"1", 100);
|
||||
c.append("b", b"2", 101);
|
||||
let mut buf = Vec::new();
|
||||
c.write_jsonl(&mut buf).unwrap();
|
||||
let s = std::str::from_utf8(&buf).unwrap();
|
||||
// Exactly N newlines for N events.
|
||||
assert_eq!(s.matches('\n').count(), 2);
|
||||
assert!(s.ends_with('\n'));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn read_jsonl_tolerates_blank_lines() {
|
||||
let mut c = WitnessChain::new();
|
||||
c.append("a", b"1", 100);
|
||||
c.append("b", b"2", 101);
|
||||
let mut buf = Vec::new();
|
||||
c.write_jsonl(&mut buf).unwrap();
|
||||
// Inject blanks — sometimes happens when files are edited.
|
||||
let with_blanks = format!(
|
||||
"\n{}\n\n",
|
||||
std::str::from_utf8(&buf).unwrap().trim_end()
|
||||
);
|
||||
let read = WitnessChain::read_jsonl(with_blanks.as_bytes()).unwrap();
|
||||
assert_eq!(read.len(), 2);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn read_jsonl_surfaces_line_no_on_parse_error() {
|
||||
// Two good events, then one with a flipped payload byte.
|
||||
let mut c = WitnessChain::new();
|
||||
c.append("a", b"1", 100);
|
||||
c.append("b", b"2", 101);
|
||||
let mut buf = Vec::new();
|
||||
c.write_jsonl(&mut buf).unwrap();
|
||||
let mut text = String::from_utf8(buf).unwrap();
|
||||
let forged = c.events()[0].to_jsonl_line().replacen(
|
||||
"payload_hex\":\"31",
|
||||
"payload_hex\":\"32",
|
||||
1,
|
||||
);
|
||||
text.push_str(&forged);
|
||||
text.push('\n');
|
||||
|
||||
let err = WitnessChain::read_jsonl(text.as_bytes()).unwrap_err();
|
||||
match err {
|
||||
WitnessReadError::Parse { line_no, .. } => assert_eq!(line_no, 3),
|
||||
other => panic!("expected Parse error at line 3, got {other:?}"),
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn read_jsonl_chain_verify_catches_reordered_events() {
|
||||
// Build a chain, then write it out with the events swapped.
|
||||
// Each individual event still verifies its own hash (because
|
||||
// its prev_hash is internally consistent with what *it*
|
||||
// claimed), but the cross-event chain check fires.
|
||||
let mut original = WitnessChain::new();
|
||||
original.append("a", b"1", 100);
|
||||
original.append("b", b"2", 101);
|
||||
let mut buf = Vec::new();
|
||||
original.write_jsonl(&mut buf).unwrap();
|
||||
let lines: Vec<&[u8]> = buf.split(|&b| b == b'\n').filter(|s| !s.is_empty()).collect();
|
||||
// Reverse order, send through reader.
|
||||
let mut reversed: Vec<u8> = Vec::new();
|
||||
reversed.extend_from_slice(lines[1]);
|
||||
reversed.push(b'\n');
|
||||
reversed.extend_from_slice(lines[0]);
|
||||
reversed.push(b'\n');
|
||||
let err = WitnessChain::read_jsonl(reversed.as_slice()).unwrap_err();
|
||||
assert!(matches!(err, WitnessReadError::Verify { .. }));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn read_jsonl_no_trailing_newline_still_works() {
|
||||
// BufRead's lines() handles the no-final-newline case; lock
|
||||
// the behavior so a future swap to a different reader can't
|
||||
// silently truncate the last event.
|
||||
let mut c = WitnessChain::new();
|
||||
c.append("only", b"x", 100);
|
||||
let mut buf = Vec::new();
|
||||
c.write_jsonl(&mut buf).unwrap();
|
||||
// Strip the trailing \n.
|
||||
if buf.last() == Some(&b'\n') {
|
||||
buf.pop();
|
||||
}
|
||||
let read = WitnessChain::read_jsonl(buf.as_slice()).unwrap();
|
||||
assert_eq!(read.len(), 1);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,231 @@
|
||||
//! `witness_signing` — Ed25519 signature layer over the witness chain.
|
||||
//!
|
||||
//! ADR-116 §2.2: every state transition must be signed by the
|
||||
//! Seed so a downstream auditor can prove the chain wasn't
|
||||
//! retroactively assembled. The chain primitive
|
||||
//! (`witness::WitnessChain`) handles hash linkage; this module
|
||||
//! adds the cryptographic attestation.
|
||||
//!
|
||||
//! Kept in a separate module from the chain itself so:
|
||||
//!
|
||||
//! * the hash chain stays usable without `ed25519-dalek` linked
|
||||
//! in (good for the `wasm32-unknown-unknown` cog variant we'll
|
||||
//! ship for browser-side audit verification),
|
||||
//! * key rotation invalidates *signatures* but not the chain —
|
||||
//! the auditor only needs the new public key to re-verify,
|
||||
//! * the signing surface stays small enough to audit in one
|
||||
//! read.
|
||||
//!
|
||||
//! ## What gets signed
|
||||
//!
|
||||
//! `sign_event(event, key)` signs the same canonical byte form
|
||||
//! that `witness::hash_event` hashes. That means:
|
||||
//!
|
||||
//! 1. A signature commits to the entire event (kind, payload,
|
||||
//! timestamp, seq, prev_hash) — no field can be retroactively
|
||||
//! changed without invalidating both the hash AND the
|
||||
//! signature.
|
||||
//! 2. The signature implicitly commits to the *chain position*
|
||||
//! via `prev_hash` — splicing a signed event into a different
|
||||
//! chain breaks verification.
|
||||
//!
|
||||
//! ## Key management
|
||||
//!
|
||||
//! Out of scope for this module. The cog runtime reads the Seed's
|
||||
//! Ed25519 signing key from the Cognitum control plane's secure
|
||||
//! key store (separate concern). Tests use a fixed-bytes seed for
|
||||
//! determinism — never check in real Seed keys here.
|
||||
|
||||
use ed25519_dalek::{Signature, Signer, SigningKey, Verifier, VerifyingKey};
|
||||
|
||||
use crate::witness::{canonical_bytes, WitnessEvent};
|
||||
|
||||
/// Sign a witness event with the Seed's Ed25519 key. Returns the
|
||||
/// 64-byte Ed25519 signature over the event's canonical bytes —
|
||||
/// the same bytes `witness::hash_event` hashes, so a verifier that
|
||||
/// already trusts the hash chain only needs one extra check.
|
||||
pub fn sign_event(event: &WitnessEvent, key: &SigningKey) -> Signature {
|
||||
let bytes = canonical_bytes(
|
||||
event.prev_hash,
|
||||
event.seq,
|
||||
event.timestamp_unix_s,
|
||||
&event.kind,
|
||||
&event.payload,
|
||||
);
|
||||
key.sign(&bytes)
|
||||
}
|
||||
|
||||
/// Verify an Ed25519 signature against a witness event using the
|
||||
/// Seed's public key. `Ok(())` iff the signature is valid for the
|
||||
/// event's canonical bytes under this key.
|
||||
pub fn verify_signature(
|
||||
event: &WitnessEvent,
|
||||
signature: &Signature,
|
||||
public_key: &VerifyingKey,
|
||||
) -> Result<(), SignatureVerifyError> {
|
||||
let bytes = canonical_bytes(
|
||||
event.prev_hash,
|
||||
event.seq,
|
||||
event.timestamp_unix_s,
|
||||
&event.kind,
|
||||
&event.payload,
|
||||
);
|
||||
public_key
|
||||
.verify(&bytes, signature)
|
||||
.map_err(|_| SignatureVerifyError::Invalid)
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
|
||||
pub enum SignatureVerifyError {
|
||||
#[error("Ed25519 signature does not match event under this public key")]
|
||||
Invalid,
|
||||
}
|
||||
|
||||
/// Encode a signature as 128 hex chars (no `0x` prefix). Matches the
|
||||
/// hex convention the rest of the witness wire format uses.
|
||||
pub fn signature_to_hex(sig: &Signature) -> String {
|
||||
let bytes = sig.to_bytes();
|
||||
let mut s = String::with_capacity(128);
|
||||
for b in bytes {
|
||||
s.push_str(&format!("{b:02x}"));
|
||||
}
|
||||
s
|
||||
}
|
||||
|
||||
/// Parse a 128-char lowercase-hex string back into a `Signature`.
|
||||
pub fn signature_from_hex(s: &str) -> Result<Signature, SignatureParseError> {
|
||||
if s.len() != 128 {
|
||||
return Err(SignatureParseError::Length { found: s.len() });
|
||||
}
|
||||
let mut bytes = [0u8; 64];
|
||||
for (i, byte) in bytes.iter_mut().enumerate() {
|
||||
let lo = i * 2;
|
||||
*byte = u8::from_str_radix(&s[lo..lo + 2], 16)
|
||||
.map_err(|_| SignatureParseError::Hex { at: lo })?;
|
||||
}
|
||||
Ok(Signature::from_bytes(&bytes))
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
|
||||
pub enum SignatureParseError {
|
||||
#[error("signature hex must be 128 chars, got {found}")]
|
||||
Length { found: usize },
|
||||
#[error("signature hex parse error at byte offset {at}")]
|
||||
Hex { at: usize },
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::witness::{WitnessChain, WitnessHash};
|
||||
|
||||
fn fixed_key() -> SigningKey {
|
||||
// Deterministic test key — DO NOT use in production. The
|
||||
// seed is `b"cog-ha-matter-unit-tests--------"` (32 bytes).
|
||||
SigningKey::from_bytes(b"cog-ha-matter-unit-tests--------")
|
||||
}
|
||||
|
||||
fn fresh_event() -> WitnessEvent {
|
||||
let mut c = WitnessChain::new();
|
||||
c.append("fall_risk_elevated", br#"{"node":"kitchen"}"#, 1779512400);
|
||||
c.events()[0].clone()
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn sign_and_verify_round_trip() {
|
||||
let key = fixed_key();
|
||||
let public = key.verifying_key();
|
||||
let event = fresh_event();
|
||||
let sig = sign_event(&event, &key);
|
||||
verify_signature(&event, &sig, &public).expect("clean signature verifies");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn verify_rejects_signature_under_wrong_key() {
|
||||
let key = fixed_key();
|
||||
let other = SigningKey::from_bytes(b"different-key-different-key-----");
|
||||
let event = fresh_event();
|
||||
let sig = sign_event(&event, &key);
|
||||
// Same event, signature from `key`, but verify under `other`'s
|
||||
// public key — must fail.
|
||||
let err = verify_signature(&event, &sig, &other.verifying_key()).unwrap_err();
|
||||
assert_eq!(err, SignatureVerifyError::Invalid);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn verify_rejects_tampered_event() {
|
||||
// Sign one event, then mutate the payload and verify the
|
||||
// *mutated* event under the same signature. Must fail.
|
||||
let key = fixed_key();
|
||||
let public = key.verifying_key();
|
||||
let mut event = fresh_event();
|
||||
let sig = sign_event(&event, &key);
|
||||
event.payload = b"forged-after-sign".to_vec();
|
||||
let err = verify_signature(&event, &sig, &public).unwrap_err();
|
||||
assert_eq!(err, SignatureVerifyError::Invalid);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn verify_rejects_event_with_wrong_prev_hash() {
|
||||
// Same payload + kind, but the event claims a different
|
||||
// chain position. Cryptographically bound to prev_hash via
|
||||
// canonical bytes.
|
||||
let key = fixed_key();
|
||||
let public = key.verifying_key();
|
||||
let mut event = fresh_event();
|
||||
let sig = sign_event(&event, &key);
|
||||
event.prev_hash = WitnessHash([0x77; 32]);
|
||||
let err = verify_signature(&event, &sig, &public).unwrap_err();
|
||||
assert_eq!(err, SignatureVerifyError::Invalid);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn signature_hex_round_trip() {
|
||||
let key = fixed_key();
|
||||
let event = fresh_event();
|
||||
let sig = sign_event(&event, &key);
|
||||
let hex = signature_to_hex(&sig);
|
||||
assert_eq!(hex.len(), 128);
|
||||
assert!(hex.chars().all(|c| c.is_ascii_hexdigit() && !c.is_ascii_uppercase()));
|
||||
let parsed = signature_from_hex(&hex).unwrap();
|
||||
assert_eq!(parsed.to_bytes(), sig.to_bytes());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn signature_from_hex_rejects_wrong_length() {
|
||||
let err = signature_from_hex("abcd").unwrap_err();
|
||||
assert_eq!(err, SignatureParseError::Length { found: 4 });
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn signature_from_hex_rejects_non_hex() {
|
||||
// 128 chars but non-hex.
|
||||
let bad = "Z".repeat(128);
|
||||
let err = signature_from_hex(&bad).unwrap_err();
|
||||
assert!(matches!(err, SignatureParseError::Hex { at: 0 }));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn signature_is_deterministic_for_same_event_and_key() {
|
||||
// Ed25519 is deterministic; locking this means a future
|
||||
// accidental switch to a randomized scheme (RustCrypto's
|
||||
// optional rand-based API) fires a named test.
|
||||
let key = fixed_key();
|
||||
let event = fresh_event();
|
||||
let sig1 = sign_event(&event, &key);
|
||||
let sig2 = sign_event(&event, &key);
|
||||
assert_eq!(sig1.to_bytes(), sig2.to_bytes());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn different_events_produce_different_signatures() {
|
||||
let key = fixed_key();
|
||||
let mut a = fresh_event();
|
||||
let mut b = fresh_event();
|
||||
a.payload = b"a".to_vec();
|
||||
b.payload = b"b".to_vec();
|
||||
let sig_a = sign_event(&a, &key);
|
||||
let sig_b = sign_event(&b, &key);
|
||||
assert_ne!(sig_a.to_bytes(), sig_b.to_bytes());
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user