Implement zeroShadow Hermod support

[jmg-duarte]

Description

Adds support for Hermod, zeroShadow's self-hosted sanctioned-address agent, as an additional banned-user backend alongside the existing Chainalysis on-chain oracle.

Hermod is queried over HTTP with an HMAC-SHA256 obfuscated form of the user address (per-customer key), so we never send a raw address off-host. A hit returns 200, a miss returns 404. Both backends can run together — an address is banned if either reports it as sanctioned.

Changes

• New HermodConfig in crates/configs/src/banned_users.rs (url, hmac_key, optional api_key), wired into both autopilot and orderbook startup.
• HMAC key and API key support the %ENV_VAR indirection.
  • Added deserialize_optional_string_from_env helper for the optional API key.
  • Debug impl redacts both secrets.
• New crates/order-validation/src/banned/hermod.rs implementing the agent client: signs {address:#x} with HMAC-SHA256, hits GET <base>/addresses/<hex-sig>, optional Bearer auth, base-URL trailing-slash normalisation.
• Refactored crates/order-validation/src/banned.rs to introduce a Backend trait shared by the Chainalysis Onchain checker and the new Hermod checker.
  • Same 1-hour LRU cache and 60s background refresh behaviour for both. Users::banned now fans out to whichever subset of backends is configured.
• Unit tests for config deserialisation, secret redaction, env-var indirection, HMAC determinism, and base-URL normalisation.

How to test

1. cargo nextest run -p configs -p order-validation — covers the new config parsing, redaction, env-var indirection, HMAC signing, and URL normalisation tests.

[gemini-code-assist]

Code Review

This pull request introduces the Hermod (zeroShadow) sanctioned-address checker and refactors the banned-user detection logic into a trait-based system. The implementation includes HMAC-SHA256 address obfuscation, HTTP-based lookups, and a background cache maintenance task. Critical feedback was provided regarding the use of unbounded join_all for network requests; it is recommended to use concurrency-limited streams like buffer_unordered in both the lookup and maintenance flows to ensure system stability and avoid triggering rate limits.

[gemini-code-assist]

Using join_all without a concurrency limit can lead to a burst of HTTP requests if need_lookup contains many addresses. This can cause stability issues or trigger rate limits on the backend. Consider using a concurrency-limited stream instead. Additionally, ensure that individual fetch errors (like timeouts) are handled explicitly and not cached, as per repository guidelines on batch operations and caching.

    async fn check(&self, addresses: &HashSet<Address>, banned: &mut HashSet<Address>) {
        use futures::StreamExt;

        let mut need_lookup = Vec::new();
        for address in addresses {
            if banned.contains(address) {
                continue;
            }
            match self.cache().get(address) {
                Some(metadata) => {
                    metadata.is_banned.then(|| banned.insert(*address));
                }
                None => need_lookup.push(*address),
            }
        }

        let to_cache = futures::stream::iter(need_lookup)
            .map(|address| async move { (address, self.fetch(address).await) })
            .buffer_unordered(10)
            .collect::<Vec<_>>()
            .await;
    }

References

1. When fetching a batch of items where individual fetches can fail, do not silently ignore errors.
2. Do not cache timeouts if the timeout is moved deeper into the code, as this might lead to incorrect caching of failures.

[gemini-code-assist]

The background maintenance task uses join_all on all expired entries. If a large portion of the cache expires simultaneously, this will attempt to fire thousands of concurrent HTTP requests. Use buffer_unordered to limit concurrency. Additionally, ensure errors are not silently ignored (e.g., by using .flatten() on Results); in background tasks, unrecoverable errors should trigger a fail-fast response like panicking, as per repository guidelines.

                let results = futures::stream::iter(expired_data)
                    .map(|(address, metadata)| detector.determine_status(*address, metadata))
                    .buffer_unordered(10)
                    .collect::<Vec<_>>()
                    .await
                    .into_iter()
                    .flatten();

References

1. In critical background tasks, panicking on unrecoverable errors is an acceptable strategy to ensure a fail-fast behavior.
2. When fetching a batch of items where individual fetches can fail, do not silently ignore errors.