refactor(trogon-github): replace bool signature check with SignatureError enum

Enables structured logging with specific failure reasons (missing prefix,
invalid hex, mismatch). Also adds NATS healthcheck to docker-compose.

Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>

Author: yordis

rsworkspace/crates/trogon-github/docker-compose.yml

@@ -3,13 +3,19 @@ name: trogon-github
 services:
   nats:
     image: nats:2-alpine
-    command: ["--jetstream", "--store_dir=/data"]
+    command: ["--jetstream", "--store_dir=/data", "--http_port=8222"]
     ports:
       - "4222:4222"
       - "8222:8222"
     volumes:
       - nats-data:/data
     restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:8222/healthz"]
+      interval: 5s
+      timeout: 3s
+      start_period: 5s
+      retries: 3
 
   trogon-github:
     build:
@@ -28,7 +34,8 @@ services:
       GITHUB_MAX_BODY_SIZE: "${GITHUB_MAX_BODY_SIZE:-26214400}"
       RUST_LOG: "${RUST_LOG:-info}"
     depends_on:
-      - nats
+      nats:
+        condition: service_healthy
     restart: unless-stopped
     healthcheck:
       test: ["CMD", "curl", "-sf", "http://localhost:${GITHUB_WEBHOOK_PORT:-8080}/health"]

rsworkspace/crates/trogon-github/src/lib.rs

@@ -37,5 +37,6 @@ pub mod signature;
 
 pub use config::GithubConfig;
 pub use server::{ServeError, provision};
+pub use signature::SignatureError;
 #[cfg(not(coverage))]
 pub use server::{router, serve};

rsworkspace/crates/trogon-github/src/server.rs

@@ -219,10 +219,11 @@ async fn handle_webhook<P: JetStreamPublisher>(
             .and_then(|v| v.to_str().ok());
 
         match sig {
-            Some(sig) if signature::verify(secret, &body, sig) => {}
-            Some(_) => {
-                warn!("Invalid GitHub webhook signature");
-                return StatusCode::UNAUTHORIZED;
+            Some(sig) => {
+                if let Err(e) = signature::verify(secret, &body, sig) {
+                    warn!(reason = %e, "GitHub webhook signature validation failed");
+                    return StatusCode::UNAUTHORIZED;
+                }
             }
             None => {
                 warn!("Missing X-Hub-Signature-256 header");

rsworkspace/crates/trogon-github/src/signature.rs

@@ -1,28 +1,44 @@
+use std::fmt;
+
 use hmac::{Hmac, Mac};
 use sha2::Sha256;
 
 type HmacSha256 = Hmac<Sha256>;
 
+#[derive(Debug)]
+pub enum SignatureError {
+    MissingPrefix,
+    InvalidHex,
+    Mismatch,
+}
+
+impl fmt::Display for SignatureError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            SignatureError::MissingPrefix => f.write_str("missing sha256= prefix"),
+            SignatureError::InvalidHex => f.write_str("invalid hex encoding"),
+            SignatureError::Mismatch => f.write_str("signature mismatch"),
+        }
+    }
+}
+
 /// Verifies a GitHub webhook signature using constant-time comparison.
 ///
 /// GitHub sends `X-Hub-Signature-256: sha256=<hex>`. This function validates
 /// the HMAC-SHA256 of the raw request body against that header value.
-pub fn verify(secret: &str, body: &[u8], signature_header: &str) -> bool {
-    let hex_sig = match signature_header.strip_prefix("sha256=") {
-        Some(s) => s,
-        None => return false,
-    };
+pub fn verify(secret: &str, body: &[u8], signature_header: &str) -> Result<(), SignatureError> {
+    let hex_sig = signature_header
+        .strip_prefix("sha256=")
+        .ok_or(SignatureError::MissingPrefix)?;
 
-    let Ok(expected) = hex::decode(hex_sig) else {
-        return false;
-    };
+    let expected = hex::decode(hex_sig).map_err(|_| SignatureError::InvalidHex)?;
 
-    let Ok(mut mac) = HmacSha256::new_from_slice(secret.as_bytes()) else {
-        return false;
-    };
+    let mut mac = HmacSha256::new_from_slice(secret.as_bytes())
+        .expect("HMAC-SHA256 accepts any key length");
 
     mac.update(body);
-    mac.verify_slice(&expected).is_ok()
+    mac.verify_slice(&expected)
+        .map_err(|_| SignatureError::Mismatch)
 }
 
 #[cfg(test)]
@@ -35,39 +51,58 @@ mod tests {
         format!("sha256={}", hex::encode(mac.finalize().into_bytes()))
     }
 
+    #[test]
+    fn error_display_messages() {
+        assert_eq!(SignatureError::MissingPrefix.to_string(), "missing sha256= prefix");
+        assert_eq!(SignatureError::InvalidHex.to_string(), "invalid hex encoding");
+        assert_eq!(SignatureError::Mismatch.to_string(), "signature mismatch");
+    }
+
     #[test]
     fn valid_signature_passes() {
         let sig = compute_sig("test-secret", b"hello world");
-        assert!(verify("test-secret", b"hello world", &sig));
+        assert!(verify("test-secret", b"hello world", &sig).is_ok());
     }
 
     #[test]
     fn wrong_secret_fails() {
         let sig = compute_sig("correct-secret", b"body");
-        assert!(!verify("wrong-secret", b"body", &sig));
+        assert!(matches!(
+            verify("wrong-secret", b"body", &sig),
+            Err(SignatureError::Mismatch)
+        ));
     }
 
     #[test]
     fn tampered_body_fails() {
         let sig = compute_sig("secret", b"original body");
-        assert!(!verify("secret", b"tampered body", &sig));
+        assert!(matches!(
+            verify("secret", b"tampered body", &sig),
+            Err(SignatureError::Mismatch)
+        ));
     }
 
     #[test]
     fn missing_sha256_prefix_fails() {
         let sig = compute_sig("secret", b"body");
         let raw_hex = sig.strip_prefix("sha256=").unwrap().to_string();
-        assert!(!verify("secret", b"body", &raw_hex));
+        assert!(matches!(
+            verify("secret", b"body", &raw_hex),
+            Err(SignatureError::MissingPrefix)
+        ));
     }
 
     #[test]
     fn invalid_hex_fails() {
-        assert!(!verify("secret", b"body", "sha256=not-valid-hex!"));
+        assert!(matches!(
+            verify("secret", b"body", "sha256=not-valid-hex!"),
+            Err(SignatureError::InvalidHex)
+        ));
     }
 
     #[test]
     fn empty_body_with_valid_sig_passes() {
         let sig = compute_sig("secret", b"");
-        assert!(verify("secret", b"", &sig));
+        assert!(verify("secret", b"", &sig).is_ok());
     }
 }