fix(node): address review on icaptcha gate (validate config, bound key fetch)

Addresses CodeRabbit and @jatmn review feedback on #108:

- parse_mode now returns Option and rejects unrecognized ICAPTCHA_MODE values;
  init() warns and falls back to off instead of silently disabling the gate on
  a typo like "enforced". [P2]
- ICAPTCHA_REQUIRED_LEVEL: warn on a non-empty unparseable value instead of
  silently lowering the threshold to the default. [P2]
- fetch_key uses a reqwest client with a 5s timeout so a hung /v1/pubkey can
  never block node startup; still fails inert on timeout/error. [P2]
- .env.example: reorder ICAPTCHA_* keys (MODE, PUBKEY, REQUIRED_LEVEL, URL) to
  satisfy dotenv-linter. [P3]
- add parse_mode unit test (rejects junk, accepts documented values).

cargo test -p gitlawb-node icaptcha: 12 passed. clippy + fmt clean.

Author: Kevin Codex <kevin@gitlawb.com>

Author: kevincodex1

.env.example

@@ -96,10 +96,10 @@ GITLAWB_AUTO_SYNC=false
 #   shadow  - verify + log would-be rejections, but always allow
 #   enforce - reject requests without a valid, strong-enough proof
 ICAPTCHA_MODE=off
-# Base URL of the iCaptcha service.
-ICAPTCHA_URL=https://icaptcha.gitlawb.com
 # Optional base64url Ed25519 public key override; if unset it is fetched from
 # ICAPTCHA_URL/v1/pubkey at startup.
 ICAPTCHA_PUBKEY=
 # Minimum proof difficulty level required to pass.
 ICAPTCHA_REQUIRED_LEVEL=3
+# Base URL of the iCaptcha service.
+ICAPTCHA_URL=https://icaptcha.gitlawb.com

crates/gitlawb-node/src/icaptcha.rs

@@ -19,7 +19,7 @@
 //!   ICAPTCHA_REQUIRED_LEVEL  minimum proof level             (default 3)
 
 use std::sync::OnceLock;
-use std::time::{SystemTime, UNIX_EPOCH};
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
 use axum::http::HeaderMap;
 use base64::engine::general_purpose::URL_SAFE_NO_PAD;
@@ -48,11 +48,31 @@ impl Mode {
     }
 }
 
-fn parse_mode(s: &str) -> Mode {
+/// Parse `ICAPTCHA_MODE`. Returns `None` for unrecognized values so the caller
+/// can surface the typo instead of silently disabling the gate.
+fn parse_mode(s: &str) -> Option<Mode> {
     match s.trim().to_ascii_lowercase().as_str() {
-        "enforce" => Mode::Enforce,
-        "shadow" => Mode::Shadow,
-        _ => Mode::Off,
+        "" | "off" => Some(Mode::Off),
+        "shadow" => Some(Mode::Shadow),
+        "enforce" => Some(Mode::Enforce),
+        _ => None,
+    }
+}
+
+/// Parse `ICAPTCHA_REQUIRED_LEVEL`. Defaults to 3; warns (rather than silently
+/// lowering the threshold) when a non-empty value fails to parse.
+fn parse_required_level() -> u32 {
+    const DEFAULT: u32 = 3;
+    match std::env::var("ICAPTCHA_REQUIRED_LEVEL") {
+        Ok(v) if !v.trim().is_empty() => v.trim().parse().unwrap_or_else(|_| {
+            tracing::warn!(
+                value = %v,
+                default = DEFAULT,
+                "invalid ICAPTCHA_REQUIRED_LEVEL; using default"
+            );
+            DEFAULT
+        }),
+        _ => DEFAULT,
     }
 }
 
@@ -97,20 +117,27 @@ fn decode_key(b64url: &str) -> Option<VerifyingKey> {
 
 async fn fetch_key(url: &str) -> Option<VerifyingKey> {
     let endpoint = format!("{}/v1/pubkey", url.trim_end_matches('/'));
-    let jwks: Jwks = reqwest::get(&endpoint).await.ok()?.json().await.ok()?;
+    // Bounded request: a hung /v1/pubkey must never block node startup. On
+    // timeout/error we return None and the gate stays inert (fail safe).
+    let client = reqwest::Client::builder()
+        .timeout(Duration::from_secs(5))
+        .build()
+        .ok()?;
+    let jwks: Jwks = client.get(&endpoint).send().await.ok()?.json().await.ok()?;
     decode_key(&jwks.keys.first()?.x)
 }
 
 /// Initialize the gate from the environment. Call once at startup. Never panics;
 /// if the gate is active but no key can be loaded, it stays inert and warns.
 pub async fn init() {
-    let mode = parse_mode(&std::env::var("ICAPTCHA_MODE").unwrap_or_default());
+    let raw_mode = std::env::var("ICAPTCHA_MODE").unwrap_or_default();
+    let mode = parse_mode(&raw_mode).unwrap_or_else(|| {
+        tracing::warn!(value = %raw_mode, "invalid ICAPTCHA_MODE; disabling iCaptcha gate");
+        Mode::Off
+    });
     let url = std::env::var("ICAPTCHA_URL")
         .unwrap_or_else(|_| "https://icaptcha.gitlawb.com".to_string());
-    let required_level = std::env::var("ICAPTCHA_REQUIRED_LEVEL")
-        .ok()
-        .and_then(|v| v.parse().ok())
-        .unwrap_or(3);
+    let required_level = parse_required_level();
 
     let key = if mode == Mode::Off {
         None
@@ -287,6 +314,17 @@ mod tests {
         assert!(err.contains("missing"), "{err}");
     }
 
+    #[test]
+    fn parse_mode_accepts_documented_values_and_rejects_junk() {
+        assert_eq!(parse_mode(""), Some(Mode::Off));
+        assert_eq!(parse_mode("off"), Some(Mode::Off));
+        assert_eq!(parse_mode("  Shadow "), Some(Mode::Shadow));
+        assert_eq!(parse_mode("ENFORCE"), Some(Mode::Enforce));
+        // Typos must NOT silently disable the gate.
+        assert_eq!(parse_mode("enforced"), None);
+        assert_eq!(parse_mode("on"), None);
+    }
+
     #[test]
     fn off_mode_allows_everything() {
         let mut v = verifier(3);