refactor(#2302): type socket wire fields as ident, validated by serde on deserialize

hive-types/src/lib.rs

@@ -0,0 +1,153 @@
+//! Foundational shared newtypes for the hyperhive workspace.
+//!
+//! A zero-dependency (bar `serde`) leaf crate so every wire-type crate
+//! (`hive-sh4re`, `hive-host-sock`, `hive-agent-sock`) and both binaries
+//! (`hive-c0re`, `hivectl`) can type their agent-name fields as [`Ident`]
+//! and get serde-validated parsing at the socket boundary for free — with
+//! no cross-crate coupling and without growing `hive-sh4re`.
+
+/// A validated hive identifier: 1-63 chars of `[a-z0-9-]`.
+///
+/// The single ident type for agent names, forge labels, and matrix / github
+/// account names — every value that becomes a filesystem path segment or an
+/// nspawn machine-name component. Constructed only through the validating
+/// [`Ident::parse`], so "this string passed the naming whitelist" is a fact
+/// the type carries instead of a convention every call site re-checks against
+/// a raw `String`. The charset is deliberately conservative — lowercase
+/// ascii, digits, and hyphen only (no underscore, dot, slash, or non-ASCII) —
+/// and length-capped, tracking `nixos-container` basename rules and keeping
+/// `../` traversal, unicode homoglyphs, and unbounded path segments out of
+/// any path built from it. Deserialization runs the same parse, so a value
+/// arriving over the wire is validated on the way in.
+#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub struct Ident(String);
+
+impl Ident {
+    /// Maximum length in bytes. A cap stops an unbounded operator-supplied
+    /// name from becoming an over-long path segment (a filesystem / `DoS`
+    /// footgun).
+    pub const MAX_LEN: usize = 63;
+
+    /// Parse + validate an identifier.
+    ///
+    /// # Errors
+    /// Returns `Err(reason)` — a caller-ready message — when `s` is empty,
+    /// longer than [`Ident::MAX_LEN`], or contains any byte outside
+    /// `[a-z0-9-]`.
+    pub fn parse(s: &str) -> Result<Self, &'static str> {
+        if s.is_empty() {
+            return Err("identifier must not be empty");
+        }
+        if s.len() > Self::MAX_LEN {
+            return Err("identifier must be 63 characters or fewer");
+        }
+        if !s
+            .bytes()
+            .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
+        {
+            return Err("identifier must contain only [a-z0-9-]");
+        }
+        Ok(Self(s.to_owned()))
+    }
+
+    /// The validated identifier as a string slice.
+    #[must_use]
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+
+    /// Consume into the inner `String`.
+    #[must_use]
+    pub fn into_string(self) -> String {
+        self.0
+    }
+}
+
+impl std::fmt::Display for Ident {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+impl AsRef<str> for Ident {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
+/// Lets an `Ident` key a `HashMap`/`BTreeMap` be looked up with a `&str`.
+impl std::borrow::Borrow<str> for Ident {
+    fn borrow(&self) -> &str {
+        &self.0
+    }
+}
+
+impl serde::Serialize for Ident {
+    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        serializer.serialize_str(&self.0)
+    }
+}
+
+impl<'de> serde::Deserialize<'de> for Ident {
+    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        use serde::de::Error as _;
+        let s = String::deserialize(deserializer)?;
+        Ident::parse(&s).map_err(D::Error::custom)
+    }
+}
+
+#[cfg(test)]
+mod ident_tests {
+    use super::Ident;
+
+    #[test]
+    fn accepts_canonical_shapes() {
+        for ok in [
+            "damocles",
+            "hm1nd",
+            "agent-with-dashes",
+            "codeberg",
+            "acct-1",
+        ] {
+            assert!(Ident::parse(ok).is_ok(), "should accept {ok:?}");
+        }
+        assert!(
+            Ident::parse(&"a".repeat(Ident::MAX_LEN)).is_ok(),
+            "63 chars is the boundary"
+        );
+    }
+
+    #[test]
+    fn rejects_bad_input() {
+        let too_long = "a".repeat(Ident::MAX_LEN + 1);
+        for bad in [
+            "",
+            &too_long,
+            "Alice",          // uppercase
+            "snake_case",     // underscore (tightened out)
+            "alice.bob",      // dot
+            "alice/bob",      // slash
+            "../etc/passwd",  // traversal
+            "damóclès",       // non-ASCII
+            "alice\u{2013}b", // en-dash homoglyph
+        ] {
+            assert!(Ident::parse(bad).is_err(), "should reject {bad:?}");
+        }
+    }
+
+    #[test]
+    fn round_trips_and_serde_validates() {
+        let id = Ident::parse("damocles").unwrap();
+        assert_eq!(id.as_str(), "damocles");
+        // Serialize is transparent (just the inner string).
+        let json = serde_json::to_string(&id).unwrap();
+        assert_eq!(json, "\"damocles\"");
+        // Deserialize runs the same parse.
+        let back: Ident = serde_json::from_str(&json).unwrap();
+        assert_eq!(back, id);
+        assert!(
+            serde_json::from_str::<Ident>("\"BAD_NAME\"").is_err(),
+            "deserialize must reject an invalid ident"
+        );
+    }
+}