fix(scanner): make distributed usage convergence authoritative (#5151)

* fix(scanner): make distributed usage cycles authoritative * fix(scanner): close distributed refresh races * fix(config): align scanner reload integration * fix(admin): scope config test helpers * fix(scanner): harden distributed usage convergence * fix(scanner): preserve rolling activity compatibility * fix(admin): expose non-secret optional config values * fix(scanner): acknowledge distributed dirty usage * fix(ecstore): make bucket mutations cancellation safe * fix(scanner): preserve pending dirty acknowledgements * test(obs): account for superseded scanner metric * fix(api): reject excess detached bucket mutations * test: close scanner convergence coverage gaps * fix(scanner): make path tracking cleanup one-shot --------- Co-authored-by: Henry Guo <marshawcoco@users.noreply.github.com> Co-authored-by: houseme <housemecn@gmail.com>
2026-08-19 19:16:17 +00:00 · 2026-07-25 18:45:16 +08:00
parent 0364523dad
commit a63b79004c
69 changed files with 18073 additions and 1585 deletions
@@ -27,6 +27,7 @@
 //! Advisory: <https://github.com/rustfs/rustfs/security/advisories/GHSA-r5qv-rc46-hv8q>

 use crate::cluster::rpc::context_propagation::{inject_request_id_into_http_headers, inject_trace_context_into_http_headers};
+use crate::storage_api_contracts::internode::NS_SCANNER_PROTOCOL_VERSION;
 use base64::Engine as _;
 use base64::engine::general_purpose;
 use hmac::{Hmac, KeyInit, Mac};
@@ -61,6 +62,7 @@ const UNSIGNED_PAYLOAD_NONCE: &str = "unsigned";
 const SIGNATURE_VALID_DURATION: i64 = 300; // 5 minutes
 const REPLAY_CACHE_RETENTION: Duration = Duration::from_secs(601);
 const MAX_REPLAY_PROTECTED_NONCES: usize = 65_536;
+const NS_SCANNER_CAPABILITY_AUTH_DOMAIN: &[u8] = b"rustfs-ns-scanner-capability-v3";
 pub const TONIC_RPC_PREFIX: &str = "/node_service.NodeService";
 static INTERNODE_RPC_SIGNATURE_STRICT: LazyLock<bool> = LazyLock::new(|| {
    get_env_bool(
@@ -209,6 +211,42 @@ fn verify_signature(secret: &str, url: &str, method: &Method, timestamp: i64, si
    mac.verify_slice(&signature).is_ok()
 }

+fn update_ns_scanner_capability_mac(mac: &mut HmacSha256, challenge: Uuid, server_epoch: Uuid) {
+    mac.update(NS_SCANNER_CAPABILITY_AUTH_DOMAIN);
+    mac.update(&NS_SCANNER_PROTOCOL_VERSION.to_be_bytes());
+    mac.update(challenge.as_bytes());
+    mac.update(server_epoch.as_bytes());
+}
+
+fn generate_ns_scanner_capability_proof(secret: &str, challenge: Uuid, server_epoch: Uuid) -> std::io::Result<Vec<u8>> {
+    if challenge.is_nil() || server_epoch.is_nil() {
+        return Err(std::io::Error::other("Invalid namespace scanner capability scope"));
+    }
+    let mut mac =
+        <HmacSha256 as KeyInit>::new_from_slice(secret.as_bytes()).map_err(|_| std::io::Error::other("Invalid RPC HMAC key"))?;
+    update_ns_scanner_capability_mac(&mut mac, challenge, server_epoch);
+    Ok(mac.finalize().into_bytes().to_vec())
+}
+
+fn verify_ns_scanner_capability_proof(secret: &str, challenge: Uuid, server_epoch: Uuid, proof: &[u8]) -> std::io::Result<()> {
+    if challenge.is_nil() || server_epoch.is_nil() {
+        return Err(std::io::Error::other("Invalid namespace scanner capability scope"));
+    }
+    let mut mac =
+        <HmacSha256 as KeyInit>::new_from_slice(secret.as_bytes()).map_err(|_| std::io::Error::other("Invalid RPC HMAC key"))?;
+    update_ns_scanner_capability_mac(&mut mac, challenge, server_epoch);
+    mac.verify_slice(proof)
+        .map_err(|_| std::io::Error::new(std::io::ErrorKind::PermissionDenied, "Invalid namespace scanner capability proof"))
+}
+
+pub fn sign_ns_scanner_capability(challenge: Uuid, server_epoch: Uuid) -> std::io::Result<Vec<u8>> {
+    generate_ns_scanner_capability_proof(&get_shared_secret()?, challenge, server_epoch)
+}
+
+pub fn verify_ns_scanner_capability(challenge: Uuid, server_epoch: Uuid, proof: &[u8]) -> std::io::Result<()> {
+    verify_ns_scanner_capability_proof(&get_shared_secret()?, challenge, server_epoch, proof)
+}
+
 #[derive(Clone, Copy)]
 struct SignatureV2Scope<'a> {
    audience: &'a str,
@@ -629,6 +667,20 @@ mod tests {
        runtime_sources::ensure_test_rpc_secret();
    }

+    #[test]
+    fn namespace_scanner_capability_proof_binds_challenge_and_server_epoch() {
+        let secret = "test-scanner-capability-secret";
+        let challenge = Uuid::new_v4();
+        let server_epoch = Uuid::new_v4();
+        let proof =
+            generate_ns_scanner_capability_proof(secret, challenge, server_epoch).expect("capability proof should be generated");
+
+        assert!(verify_ns_scanner_capability_proof(secret, challenge, server_epoch, &proof).is_ok());
+        assert!(verify_ns_scanner_capability_proof(secret, Uuid::new_v4(), server_epoch, &proof).is_err());
+        assert!(verify_ns_scanner_capability_proof(secret, challenge, Uuid::new_v4(), &proof).is_err());
+        assert!(verify_ns_scanner_capability_proof("different-secret", challenge, server_epoch, &proof).is_err());
+    }
+
    /// Security regression for GHSA-r5qv-rc46-hv8q (internode RPC fail-closed,
    /// fixed in rustfs/rustfs#4402): secret resolution must never silently fall
    /// back to a default/empty shared secret. Missing and default secrets both
@@ -12,11 +12,14 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.

-use crate::cluster::rpc::build_auth_headers;
+use crate::cluster::rpc::{build_auth_headers, verify_ns_scanner_capability};
 use crate::disk::error::{Error, Result};
 use crate::disk::{FileReader, FileWriter};
 use crate::storage_api_contracts::internode::{
-    WALK_DIR_BODY_SHA256_QUERY, WALK_DIR_STREAM_COMPLETION_QUERY, WALK_DIR_STREAM_COMPLETION_V1,
+    NS_SCANNER_BODY_SHA256_QUERY, NS_SCANNER_CAPABILITY_CHALLENGE_QUERY, NS_SCANNER_CYCLE_QUERY, NS_SCANNER_LEADER_EPOCH_QUERY,
+    NS_SCANNER_PROTOCOL_VERSION, NS_SCANNER_PROTOCOL_VERSION_QUERY, NS_SCANNER_REQUEST_ID_QUERY, NS_SCANNER_SERVER_EPOCH_QUERY,
+    NS_SCANNER_SESSION_ID_QUERY, NS_SCANNER_SESSION_SEQUENCE_QUERY, NsScannerCapabilityResponse, WALK_DIR_BODY_SHA256_QUERY,
+    WALK_DIR_STREAM_COMPLETION_QUERY, WALK_DIR_STREAM_COMPLETION_V1,
 };
 use async_trait::async_trait;
 use http::{HeaderMap, HeaderValue, Method, header::CONTENT_TYPE};
@@ -28,13 +31,18 @@ use rustfs_rio::{HttpReader, HttpWriter};
 use sha2::{Digest, Sha256};
 use std::sync::{Arc, OnceLock};
 use std::time::Duration;
+use tokio::io::AsyncReadExt;
+use uuid::Uuid;

 static INTERNODE_DATA_TRANSPORT: OnceLock<std::result::Result<Arc<dyn InternodeDataTransport>, String>> = OnceLock::new();

 const READ_FILE_STREAM_PATH: &str = "/rustfs/rpc/read_file_stream";
 const PUT_FILE_STREAM_PATH: &str = "/rustfs/rpc/put_file_stream";
 const WALK_DIR_PATH: &str = "/rustfs/rpc/walk_dir";
+const NS_SCANNER_PATH: &str = "/rustfs/rpc/ns_scanner";
+const NS_SCANNER_MAX_CAPABILITY_RESPONSE_SIZE: usize = 1024;
 const CONTENT_TYPE_JSON: &str = "application/json";
+const CONTENT_TYPE_MSGPACK: &str = "application/msgpack";

 fn unsupported_transport_message(transport: &str) -> String {
    format!(
@@ -101,6 +109,25 @@ pub struct WalkDirStreamRequest {
    pub stall_timeout: Option<Duration>,
 }

+#[derive(Debug, Clone)]
+pub struct NsScannerStreamRequest {
+    pub endpoint: String,
+    pub disk: String,
+    pub request_id: Uuid,
+    pub server_epoch: Uuid,
+    pub session_id: Uuid,
+    pub session_sequence: u64,
+    pub next_cycle: u64,
+    pub leader_epoch: u64,
+    pub body: Vec<u8>,
+    pub stall_timeout: Option<Duration>,
+}
+
+#[derive(Debug, Clone)]
+pub struct NsScannerCapabilityRequest {
+    pub endpoint: String,
+}
+
 /// Data-plane stream opener used by `RemoteDisk`.
 ///
 /// This boundary is limited to remote disk streams that can move large payloads.
@@ -114,6 +141,12 @@ pub trait InternodeDataTransport: Send + Sync + std::fmt::Debug {
    async fn open_read(&self, request: ReadStreamRequest) -> Result<FileReader>;
    async fn open_write(&self, request: WriteStreamRequest) -> Result<FileWriter>;
    async fn open_walk_dir(&self, request: WalkDirStreamRequest) -> Result<FileReader>;
+    async fn open_ns_scanner(&self, _request: NsScannerStreamRequest) -> Result<FileReader> {
+        Err(Error::MethodNotAllowed)
+    }
+    async fn probe_ns_scanner(&self, _request: NsScannerCapabilityRequest) -> Result<Uuid> {
+        Err(Error::MethodNotAllowed)
+    }
    fn name(&self) -> &'static str;
    fn capabilities(&self) -> InternodeDataTransportCapabilities;
 }
@@ -148,6 +181,39 @@ impl InternodeDataTransport for TcpHttpInternodeDataTransport {
        ))
    }

+    async fn open_ns_scanner(&self, request: NsScannerStreamRequest) -> Result<FileReader> {
+        let url = build_ns_scanner_url(&request);
+        let mut headers = msgpack_headers();
+        build_auth_headers(&url, &Method::POST, &mut headers)?;
+        Ok(Box::new(
+            HttpReader::new_with_stall_timeout(url, Method::POST, headers, Some(request.body), request.stall_timeout).await?,
+        ))
+    }
+
+    async fn probe_ns_scanner(&self, request: NsScannerCapabilityRequest) -> Result<Uuid> {
+        let challenge = Uuid::new_v4();
+        let url = build_ns_scanner_capability_url(&request, challenge);
+        let mut headers = msgpack_headers();
+        build_auth_headers(&url, &Method::GET, &mut headers)?;
+        let reader = HttpReader::new(url, Method::GET, headers, None).await?;
+        let mut body = Vec::new();
+        reader
+            .take(u64::try_from(NS_SCANNER_MAX_CAPABILITY_RESPONSE_SIZE + 1).unwrap_or(u64::MAX))
+            .read_to_end(&mut body)
+            .await?;
+        if body.is_empty() || body.len() > NS_SCANNER_MAX_CAPABILITY_RESPONSE_SIZE {
+            return Err(Error::other("invalid remote namespace scanner capability response size"));
+        }
+        let response: NsScannerCapabilityResponse =
+            rmp_serde::from_slice(&body).map_err(|_| Error::other("invalid remote namespace scanner capability response"))?;
+        if response.version != NS_SCANNER_PROTOCOL_VERSION || response.server_epoch.is_nil() {
+            return Err(Error::other("incompatible remote namespace scanner capability response"));
+        }
+        verify_ns_scanner_capability(challenge, response.server_epoch, &response.proof)
+            .map_err(|err| Error::other(format!("remote namespace scanner capability authentication failed: {err}")))?;
+        Ok(response.server_epoch)
+    }
+
    fn name(&self) -> &'static str {
        DEFAULT_INTERNODE_DATA_TRANSPORT
    }
@@ -197,12 +263,54 @@ fn build_walk_dir_url(request: &WalkDirStreamRequest) -> String {
    )
 }

+fn build_ns_scanner_url(request: &NsScannerStreamRequest) -> String {
+    let body_sha256 = hex_simd::encode_to_string(Sha256::digest(&request.body), hex_simd::AsciiCase::Lower);
+    format!(
+        "{}{}?disk={}&{}={}&{}={}&{}={}&{}={}&{}={}&{}={}&{}={}",
+        request.endpoint,
+        NS_SCANNER_PATH,
+        urlencoding::encode(&request.disk),
+        NS_SCANNER_REQUEST_ID_QUERY,
+        request.request_id,
+        NS_SCANNER_SERVER_EPOCH_QUERY,
+        request.server_epoch,
+        NS_SCANNER_SESSION_ID_QUERY,
+        request.session_id,
+        NS_SCANNER_SESSION_SEQUENCE_QUERY,
+        request.session_sequence,
+        NS_SCANNER_CYCLE_QUERY,
+        request.next_cycle,
+        NS_SCANNER_LEADER_EPOCH_QUERY,
+        request.leader_epoch,
+        NS_SCANNER_BODY_SHA256_QUERY,
+        body_sha256
+    )
+}
+
+fn build_ns_scanner_capability_url(request: &NsScannerCapabilityRequest, challenge: Uuid) -> String {
+    format!(
+        "{}{}?{}={}&{}={}",
+        request.endpoint,
+        NS_SCANNER_PATH,
+        NS_SCANNER_PROTOCOL_VERSION_QUERY,
+        NS_SCANNER_PROTOCOL_VERSION,
+        NS_SCANNER_CAPABILITY_CHALLENGE_QUERY,
+        challenge
+    )
+}
+
 fn json_headers() -> HeaderMap {
    let mut headers = HeaderMap::new();
    headers.insert(CONTENT_TYPE, HeaderValue::from_static(CONTENT_TYPE_JSON));
    headers
 }

+fn msgpack_headers() -> HeaderMap {
+    let mut headers = HeaderMap::new();
+    headers.insert(CONTENT_TYPE, HeaderValue::from_static(CONTENT_TYPE_MSGPACK));
+    headers
+}
+
 fn build_internode_data_transport_result(
    configured_transport: Option<&str>,
 ) -> std::result::Result<Arc<dyn InternodeDataTransport>, String> {
@@ -241,6 +349,65 @@ pub fn build_internode_data_transport_from_env() -> Result<Arc<dyn InternodeData
 mod tests {
    use super::*;

+    #[derive(Debug)]
+    struct LegacyTestTransport;
+
+    #[async_trait::async_trait]
+    impl InternodeDataTransport for LegacyTestTransport {
+        async fn open_read(&self, _request: ReadStreamRequest) -> Result<FileReader> {
+            Ok(Box::new(tokio::io::empty()))
+        }
+
+        async fn open_write(&self, _request: WriteStreamRequest) -> Result<FileWriter> {
+            Ok(Box::new(tokio::io::sink()))
+        }
+
+        async fn open_walk_dir(&self, _request: WalkDirStreamRequest) -> Result<FileReader> {
+            Ok(Box::new(tokio::io::empty()))
+        }
+
+        fn name(&self) -> &'static str {
+            "legacy-test"
+        }
+
+        fn capabilities(&self) -> InternodeDataTransportCapabilities {
+            InternodeDataTransportCapabilities::tcp_http()
+        }
+    }
+
+    #[tokio::test]
+    async fn legacy_transport_defaults_namespace_scanner_to_unsupported() {
+        let transport = LegacyTestTransport;
+
+        let probe_err = transport
+            .probe_ns_scanner(NsScannerCapabilityRequest {
+                endpoint: "http://node1:9000".to_string(),
+            })
+            .await
+            .expect_err("legacy transport should report namespace scanner as unsupported");
+        assert!(matches!(probe_err, Error::MethodNotAllowed));
+
+        let open_result = transport
+            .open_ns_scanner(NsScannerStreamRequest {
+                endpoint: "http://node1:9000".to_string(),
+                disk: "http://node1:9000/data/rustfs0".to_string(),
+                request_id: Uuid::new_v4(),
+                server_epoch: Uuid::new_v4(),
+                session_id: Uuid::new_v4(),
+                session_sequence: 0,
+                next_cycle: 7,
+                leader_epoch: 9,
+                body: Vec::new(),
+                stall_timeout: None,
+            })
+            .await;
+        let open_err = match open_result {
+            Ok(_) => panic!("legacy transport should not open namespace scanner streams"),
+            Err(err) => err,
+        };
+        assert!(matches!(open_err, Error::MethodNotAllowed));
+    }
+
    #[test]
    fn tcp_http_capabilities_are_behavior_preserving() {
        let transport = TcpHttpInternodeDataTransport;
@@ -322,6 +489,57 @@ mod tests {
        );
    }

+    #[test]
+    fn ns_scanner_url_binds_body_and_encodes_disk_ref() {
+        let request_id = Uuid::parse_str("11111111-2222-4333-8444-555555555555").expect("request ID");
+        let server_epoch = Uuid::parse_str("aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee").expect("server epoch");
+        let session_id = Uuid::parse_str("99999999-8888-4777-8666-555555555555").expect("session ID");
+        let url = build_ns_scanner_url(&NsScannerStreamRequest {
+            endpoint: "http://node1:9000".to_string(),
+            disk: "http://node1:9000/data/rustfs0".to_string(),
+            request_id,
+            server_epoch,
+            session_id,
+            session_sequence: 3,
+            next_cycle: 7,
+            leader_epoch: 9,
+            body: b"scanner-request".to_vec(),
+            stall_timeout: None,
+        });
+
+        assert_eq!(
+            url,
+            concat!(
+                "http://node1:9000/rustfs/rpc/ns_scanner?disk=http%3A%2F%2Fnode1%3A9000%2Fdata%2Frustfs0",
+                "&ns_scanner_request_id=11111111-2222-4333-8444-555555555555",
+                "&ns_scanner_server_epoch=aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
+                "&ns_scanner_session_id=99999999-8888-4777-8666-555555555555",
+                "&ns_scanner_session_sequence=3",
+                "&ns_scanner_cycle=7",
+                "&ns_scanner_leader_epoch=9",
+                "&ns_scanner_body_sha256=c958f15ca28422275c1245399f4c44eaba628ca453fcd77d6b3d4484573e4387"
+            )
+        );
+    }
+
+    #[test]
+    fn ns_scanner_capability_url_binds_version_and_challenge() {
+        let challenge = Uuid::parse_str("12345678-1234-4234-8234-123456789abc").expect("challenge");
+        let url = build_ns_scanner_capability_url(
+            &NsScannerCapabilityRequest {
+                endpoint: "http://node1:9000".to_string(),
+            },
+            challenge,
+        );
+
+        assert_eq!(
+            url,
+            format!(
+                "http://node1:9000/rustfs/rpc/ns_scanner?ns_scanner_protocol={NS_SCANNER_PROTOCOL_VERSION}&ns_scanner_challenge={challenge}"
+            )
+        );
+    }
+
    #[test]
    fn transport_config_defaults_to_tcp_http() {
        let transport = build_internode_data_transport(None).unwrap();
@@ -30,8 +30,8 @@ pub use client::{
 };
 pub use http_auth::{
    TONIC_RPC_PREFIX, build_auth_headers, gen_signature_headers, gen_tonic_signature_headers, normalize_tonic_rpc_audience,
-    set_tonic_canonical_body_digest, sign_tonic_rpc_response_proof, verify_rpc_signature, verify_tonic_canonical_body_digest,
-    verify_tonic_rpc_response_proof, verify_tonic_rpc_signature,
+    set_tonic_canonical_body_digest, sign_ns_scanner_capability, sign_tonic_rpc_response_proof, verify_ns_scanner_capability,
+    verify_rpc_signature, verify_tonic_canonical_body_digest, verify_tonic_rpc_response_proof, verify_tonic_rpc_signature,
 };
 #[cfg(test)]
 pub(crate) use internode_data_transport::TcpHttpInternodeDataTransport;
@@ -41,6 +41,6 @@ pub use peer_rest_client::{
    SERVICE_SIGNAL_RELOAD_DYNAMIC, ScannerPeerActivity,
 };
 pub(crate) use peer_s3_client::heal_bucket_local_on_disks;
-pub use peer_s3_client::{LocalPeerS3Client, PeerS3Client, S3PeerSys};
+pub use peer_s3_client::{LocalPeerS3Client, PeerS3Client, S3PeerSys, ScannerBucketListing, ScannerSetBucketListing};
 pub use remote_disk::RemoteDisk;
 pub use remote_locker::RemoteClient;
@@ -18,6 +18,9 @@ use crate::cluster::rpc::client::{
 };
 use crate::cluster::rpc::{set_tonic_canonical_body_digest, verify_tonic_rpc_response_proof};
 use crate::error::{Error, Result};
+use crate::storage_api_contracts::internode::{
+    SCANNER_ACTIVITY_LEGACY_PROTOCOL_VERSION, SCANNER_ACTIVITY_PREVIOUS_PROTOCOL_VERSION, SCANNER_ACTIVITY_PROTOCOL_VERSION,
+};
 use crate::{
    bucket::replication::BucketStats,
    disk::disk_store::{get_drive_active_check_interval, get_drive_active_check_timeout},
@@ -27,6 +30,7 @@ use crate::{
 };
 use bytes::Bytes;
 use rmp_serde::{Deserializer, Serializer};
+use rustfs_config::{HEAL_SUB_SYS, SCANNER_SUB_SYS};
 use rustfs_madmin::{
    ServerProperties,
    health::{Cpus, MemInfo, OsInfo, Partitions, ProcInfo, SysConfig, SysErrors, SysServices},
@@ -97,15 +101,34 @@ fn decode_bucket_stats_response(response: GetBucketStatsDataResponse) -> Result<
    Ok(stats)
 }

+fn validate_signal_service_protocol(sig: u64, sub_sys: &str, protocol_version: u32) -> Result<()> {
+    if sig == SERVICE_SIGNAL_RELOAD_DYNAMIC
+        && matches!(sub_sys, SCANNER_SUB_SYS | HEAL_SUB_SYS)
+        && protocol_version < rustfs_protos::DYNAMIC_CONFIG_PROTOCOL_VERSION
+    {
+        return Err(Error::other(format!("peer does not support dynamic {sub_sys} config convergence")));
+    }
+    Ok(())
+}
+
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct ScannerPeerActivity {
    pub instance_id: String,
    pub namespace_generation: u64,
    pub maintenance_generation: u64,
+    pub protocol_version: u32,
+    pub topology_digest: Option<[u8; 32]>,
+    pub data_movement_active: Option<bool>,
+    pub dirty_usage_generation: Option<u64>,
+    pub dirty_usage_pending: Option<bool>,
 }

-fn decode_scanner_activity(response: ScannerActivityResponse) -> Result<ScannerPeerActivity> {
-    let instance_id = response.instance_id;
+fn decode_scanner_activity_with_verifier(
+    response: ScannerActivityResponse,
+    challenge: &[u8; 16],
+    verify_proof: impl FnOnce(&[u8], &[u8]) -> Result<()>,
+) -> Result<ScannerPeerActivity> {
+    let instance_id = &response.instance_id;
    if instance_id.len() != 32
        || !instance_id
            .as_bytes()
@@ -114,10 +137,80 @@ fn decode_scanner_activity(response: ScannerActivityResponse) -> Result<ScannerP
    {
        return Err(Error::other("peer returned an invalid scanner activity instance ID"));
    }
+    let (topology_digest, data_movement_active, dirty_usage_generation, dirty_usage_pending) = match response.protocol_version {
+        // RUSTFS_COMPAT_TODO(ns-scanner-rpc-v3): legacy response fields are unauthenticated. Remove after protocol v0 peers are unsupported.
+        SCANNER_ACTIVITY_LEGACY_PROTOCOL_VERSION
+            if response.topology_digest.is_empty()
+                && response.response_proof.is_empty()
+                && !response.data_movement_active
+                && response.dirty_usage_generation == 0
+                && !response.dirty_usage_pending =>
+        {
+            (None, None, None, None)
+        }
+        SCANNER_ACTIVITY_LEGACY_PROTOCOL_VERSION => {
+            return Err(Error::other("legacy scanner activity peer returned unexpected extended fields"));
+        }
+        SCANNER_ACTIVITY_PREVIOUS_PROTOCOL_VERSION => {
+            if response.dirty_usage_generation != 0 || response.dirty_usage_pending {
+                return Err(Error::other("scanner activity protocol v4 peer returned unauthenticated v5 fields"));
+            }
+            let canonical = rustfs_protos::canonical_scanner_activity_v4_response_body(challenge, &response)
+                .map_err(|_| Error::other("peer scanner activity response is too large to authenticate"))?;
+            verify_proof(&canonical, &response.response_proof)?;
+            (
+                Some(
+                    response
+                        .topology_digest
+                        .as_ref()
+                        .try_into()
+                        .map_err(|_| Error::other("peer returned an invalid scanner topology digest"))?,
+                ),
+                Some(response.data_movement_active),
+                None,
+                None,
+            )
+        }
+        SCANNER_ACTIVITY_PROTOCOL_VERSION => {
+            if response.dirty_usage_pending && response.dirty_usage_generation == 0 {
+                return Err(Error::other("scanner activity peer returned pending dirty usage without a generation"));
+            }
+            let canonical = rustfs_protos::canonical_scanner_activity_response_body(challenge, &response)
+                .map_err(|_| Error::other("peer scanner activity response is too large to authenticate"))?;
+            verify_proof(&canonical, &response.response_proof)?;
+            (
+                Some(
+                    response
+                        .topology_digest
+                        .as_ref()
+                        .try_into()
+                        .map_err(|_| Error::other("peer returned an invalid scanner topology digest"))?,
+                ),
+                Some(response.data_movement_active),
+                Some(response.dirty_usage_generation),
+                Some(response.dirty_usage_pending),
+            )
+        }
+        version => {
+            return Err(Error::other(format!("peer returned unsupported scanner activity protocol {version}")));
+        }
+    };
    Ok(ScannerPeerActivity {
-        instance_id,
+        instance_id: response.instance_id,
        namespace_generation: response.namespace_generation,
        maintenance_generation: response.maintenance_generation,
+        protocol_version: response.protocol_version,
+        topology_digest,
+        data_movement_active,
+        dirty_usage_generation,
+        dirty_usage_pending,
+    })
+}
+
+fn decode_scanner_activity(response: ScannerActivityResponse, challenge: &[u8; 16]) -> Result<ScannerPeerActivity> {
+    decode_scanner_activity_with_verifier(response, challenge, |canonical, proof| {
+        verify_tonic_rpc_response_proof(canonical, proof)
+            .map_err(|_| Error::other("peer returned an invalid scanner activity response proof"))
    })
 }

@@ -1331,6 +1424,7 @@ impl PeerRestClient {
                    }
                    return Err(Error::other(""));
                }
+                validate_signal_service_protocol(sig, sub_sys, response.protocol_version)?;
                Ok(())
            }
            .await,
@@ -1338,25 +1432,44 @@ impl PeerRestClient {
        .await
    }

-    pub async fn scanner_activity(&self) -> Result<ScannerPeerActivity> {
+    async fn scanner_activity_request(
+        &self,
+        acknowledge_instance_id: String,
+        acknowledge_dirty_usage_generation: u64,
+    ) -> Result<ScannerPeerActivity> {
        self.finalize_result(
            async {
+                let challenge = Uuid::new_v4();
                let mut client = self
                    .get_client()
                    .await?
                    .max_decoding_message_size(SCANNER_ACTIVITY_MAX_MESSAGE_SIZE)
                    .max_encoding_message_size(SCANNER_ACTIVITY_MAX_MESSAGE_SIZE);
-                let response = client
-                    .scanner_activity(Request::new(ScannerActivityRequest {}))
-                    .await?
-                    .into_inner();
-                decode_scanner_activity(response)
+                let mut request = Request::new(ScannerActivityRequest {
+                    challenge: challenge.as_bytes().to_vec().into(),
+                    protocol_version: SCANNER_ACTIVITY_PROTOCOL_VERSION,
+                    acknowledge_instance_id,
+                    acknowledge_dirty_usage_generation,
+                });
+                let canonical = rustfs_protos::canonical_scanner_activity_request_body(request.get_ref())
+                    .map_err(|_| Error::other("scanner activity request is too large to authenticate"))?;
+                set_tonic_canonical_body_digest(&mut request, &canonical)?;
+                let response = client.scanner_activity(request).await?.into_inner();
+                decode_scanner_activity(response, challenge.as_bytes())
            }
            .await,
        )
        .await
    }

+    pub async fn scanner_activity(&self) -> Result<ScannerPeerActivity> {
+        self.scanner_activity_request(String::new(), 0).await
+    }
+
+    pub async fn acknowledge_scanner_dirty_usage(&self, instance_id: String, generation: u64) -> Result<ScannerPeerActivity> {
+        self.scanner_activity_request(instance_id, generation).await
+    }
+
    pub async fn get_metacache_listing(&self) -> Result<()> {
        warn!("get_metacache_listing is not implemented in PeerRestClient");
        Err(Error::NotImplemented)
@@ -1542,6 +1655,7 @@ impl PeerRestClient {
 #[cfg(test)]
 mod tests {
    use super::*;
+    use crate::config::com::STORAGE_CLASS_SUB_SYS;
    use serde_json::Value;
    use std::io::{self, Write};
    use std::sync::{Arc, Mutex};
@@ -1650,6 +1764,14 @@ mod tests {
        )
    }

+    fn decode_test_scanner_activity(response: ScannerActivityResponse) -> Result<ScannerPeerActivity> {
+        decode_scanner_activity_with_verifier(response, &[9; 16], |_canonical, proof| {
+            (proof == b"proof")
+                .then_some(())
+                .ok_or_else(|| Error::other("peer returned an invalid scanner activity response proof"))
+        })
+    }
+
    #[test]
    fn build_clients_from_slots_preserves_missing_remote_topology_slots() {
        let slots = vec![
@@ -1682,13 +1804,89 @@ mod tests {

    #[test]
    fn scanner_activity_requires_restart_safe_peer_identity() {
+        let legacy = decode_test_scanner_activity(ScannerActivityResponse {
+            instance_id: "0123456789abcdef0123456789abcdef".to_string(),
+            namespace_generation: 7,
+            maintenance_generation: 3,
+            protocol_version: SCANNER_ACTIVITY_LEGACY_PROTOCOL_VERSION,
+            topology_digest: Vec::new().into(),
+            data_movement_active: false,
+            response_proof: Vec::new().into(),
+            dirty_usage_generation: 0,
+            dirty_usage_pending: false,
+        })
+        .expect("legacy peers should retain their activity generations during a rolling upgrade");
+        assert_eq!(
+            legacy,
+            ScannerPeerActivity {
+                instance_id: "0123456789abcdef0123456789abcdef".to_string(),
+                namespace_generation: 7,
+                maintenance_generation: 3,
+                protocol_version: SCANNER_ACTIVITY_LEGACY_PROTOCOL_VERSION,
+                topology_digest: None,
+                data_movement_active: None,
+                dirty_usage_generation: None,
+                dirty_usage_pending: None,
+            }
+        );
+
+        let previous = decode_test_scanner_activity(ScannerActivityResponse {
+            instance_id: "0123456789abcdef0123456789abcdef".to_string(),
+            namespace_generation: 7,
+            maintenance_generation: 3,
+            protocol_version: SCANNER_ACTIVITY_PREVIOUS_PROTOCOL_VERSION,
+            topology_digest: vec![7; 32].into(),
+            data_movement_active: true,
+            response_proof: b"proof".to_vec().into(),
+            dirty_usage_generation: 0,
+            dirty_usage_pending: false,
+        })
+        .expect("protocol v4 peers should remain observable during a rolling upgrade");
+        assert_eq!(
+            previous,
+            ScannerPeerActivity {
+                instance_id: "0123456789abcdef0123456789abcdef".to_string(),
+                namespace_generation: 7,
+                maintenance_generation: 3,
+                protocol_version: SCANNER_ACTIVITY_PREVIOUS_PROTOCOL_VERSION,
+                topology_digest: Some([7; 32]),
+                data_movement_active: Some(true),
+                dirty_usage_generation: None,
+                dirty_usage_pending: None,
+            }
+        );
+
+        let malformed_topology = ScannerActivityResponse {
+            instance_id: "0123456789abcdef0123456789abcdef".to_string(),
+            namespace_generation: 7,
+            maintenance_generation: 3,
+            protocol_version: SCANNER_ACTIVITY_PROTOCOL_VERSION,
+            topology_digest: vec![7; 31].into(),
+            data_movement_active: false,
+            response_proof: b"proof".to_vec().into(),
+            dirty_usage_generation: 11,
+            dirty_usage_pending: true,
+        };
+        assert!(
+            decode_test_scanner_activity(malformed_topology)
+                .expect_err("activity topology digests must have the protocol-defined length")
+                .to_string()
+                .contains("topology digest")
+        );
+
        let missing_instance = ScannerActivityResponse {
            instance_id: String::new(),
            namespace_generation: 7,
            maintenance_generation: 3,
+            protocol_version: SCANNER_ACTIVITY_PROTOCOL_VERSION,
+            topology_digest: vec![7; 32].into(),
+            data_movement_active: false,
+            response_proof: b"proof".to_vec().into(),
+            dirty_usage_generation: 11,
+            dirty_usage_pending: true,
        };
        assert!(
-            decode_scanner_activity(missing_instance)
+            decode_test_scanner_activity(missing_instance)
                .expect_err("an empty instance ID is not restart safe")
                .to_string()
                .contains("instance ID")
@@ -1698,18 +1896,30 @@ mod tests {
            instance_id: "ABCDEF0123456789ABCDEF0123456789".to_string(),
            namespace_generation: 7,
            maintenance_generation: 3,
+            protocol_version: SCANNER_ACTIVITY_PROTOCOL_VERSION,
+            topology_digest: vec![7; 32].into(),
+            data_movement_active: false,
+            response_proof: b"proof".to_vec().into(),
+            dirty_usage_generation: 11,
+            dirty_usage_pending: true,
        };
        assert!(
-            decode_scanner_activity(malformed_instance)
+            decode_test_scanner_activity(malformed_instance)
                .expect_err("activity instance IDs must use the canonical lowercase hex form")
                .to_string()
                .contains("instance ID")
        );

-        let activity = decode_scanner_activity(ScannerActivityResponse {
+        let activity = decode_test_scanner_activity(ScannerActivityResponse {
            instance_id: "0123456789abcdef0123456789abcdef".to_string(),
            namespace_generation: 7,
            maintenance_generation: 3,
+            protocol_version: SCANNER_ACTIVITY_PROTOCOL_VERSION,
+            topology_digest: vec![7; 32].into(),
+            data_movement_active: true,
+            response_proof: b"proof".to_vec().into(),
+            dirty_usage_generation: 11,
+            dirty_usage_pending: true,
        })
        .expect("complete activity responses should be accepted");
        assert_eq!(
@@ -1718,8 +1928,123 @@ mod tests {
                instance_id: "0123456789abcdef0123456789abcdef".to_string(),
                namespace_generation: 7,
                maintenance_generation: 3,
+                protocol_version: SCANNER_ACTIVITY_PROTOCOL_VERSION,
+                topology_digest: Some([7; 32]),
+                data_movement_active: Some(true),
+                dirty_usage_generation: Some(11),
+                dirty_usage_pending: Some(true),
            }
        );
+
+        let pending_without_generation = ScannerActivityResponse {
+            instance_id: "0123456789abcdef0123456789abcdef".to_string(),
+            namespace_generation: 7,
+            maintenance_generation: 3,
+            protocol_version: SCANNER_ACTIVITY_PROTOCOL_VERSION,
+            topology_digest: vec![7; 32].into(),
+            data_movement_active: false,
+            response_proof: b"proof".to_vec().into(),
+            dirty_usage_generation: 0,
+            dirty_usage_pending: true,
+        };
+        assert!(
+            decode_test_scanner_activity(pending_without_generation)
+                .expect_err("pending dirty usage must carry a nonzero generation")
+                .to_string()
+                .contains("without a generation")
+        );
+
+        let previous_with_dirty_usage = ScannerActivityResponse {
+            instance_id: "0123456789abcdef0123456789abcdef".to_string(),
+            namespace_generation: 7,
+            maintenance_generation: 3,
+            protocol_version: SCANNER_ACTIVITY_PREVIOUS_PROTOCOL_VERSION,
+            topology_digest: vec![7; 32].into(),
+            data_movement_active: false,
+            response_proof: b"proof".to_vec().into(),
+            dirty_usage_generation: 11,
+            dirty_usage_pending: true,
+        };
+        assert!(
+            decode_test_scanner_activity(previous_with_dirty_usage)
+                .expect_err("protocol v4 responses must not claim unauthenticated dirty usage fields")
+                .to_string()
+                .contains("unauthenticated v5 fields")
+        );
+
+        let legacy_with_topology = ScannerActivityResponse {
+            instance_id: "0123456789abcdef0123456789abcdef".to_string(),
+            namespace_generation: 7,
+            maintenance_generation: 3,
+            protocol_version: SCANNER_ACTIVITY_LEGACY_PROTOCOL_VERSION,
+            topology_digest: vec![7; 32].into(),
+            data_movement_active: false,
+            response_proof: b"proof".to_vec().into(),
+            dirty_usage_generation: 0,
+            dirty_usage_pending: false,
+        };
+        assert!(
+            decode_test_scanner_activity(legacy_with_topology)
+                .expect_err("legacy protocol responses must not claim extended fields")
+                .to_string()
+                .contains("unexpected extended fields")
+        );
+
+        let unsupported_protocol = ScannerActivityResponse {
+            instance_id: "0123456789abcdef0123456789abcdef".to_string(),
+            namespace_generation: 7,
+            maintenance_generation: 3,
+            protocol_version: SCANNER_ACTIVITY_PROTOCOL_VERSION + 1,
+            topology_digest: vec![7; 32].into(),
+            data_movement_active: false,
+            response_proof: b"proof".to_vec().into(),
+            dirty_usage_generation: 11,
+            dirty_usage_pending: true,
+        };
+        assert!(
+            decode_test_scanner_activity(unsupported_protocol)
+                .expect_err("unknown activity protocols must fail closed")
+                .to_string()
+                .contains("unsupported scanner activity protocol")
+        );
+
+        let missing_proof = ScannerActivityResponse {
+            instance_id: "0123456789abcdef0123456789abcdef".to_string(),
+            namespace_generation: 7,
+            maintenance_generation: 3,
+            protocol_version: SCANNER_ACTIVITY_PROTOCOL_VERSION,
+            topology_digest: vec![7; 32].into(),
+            data_movement_active: false,
+            response_proof: Vec::new().into(),
+            dirty_usage_generation: 11,
+            dirty_usage_pending: true,
+        };
+        assert!(
+            decode_test_scanner_activity(missing_proof)
+                .expect_err("unsigned scanner activity responses must fail closed")
+                .to_string()
+                .contains("response proof")
+        );
+    }
+
+    #[test]
+    fn dynamic_scanner_config_requires_versioned_peer_acknowledgement() {
+        for sub_system in [SCANNER_SUB_SYS, HEAL_SUB_SYS] {
+            let err = validate_signal_service_protocol(SERVICE_SIGNAL_RELOAD_DYNAMIC, sub_system, 0)
+                .expect_err("an unversioned peer must not claim scanner config convergence");
+            assert!(err.to_string().contains("does not support dynamic"));
+            validate_signal_service_protocol(
+                SERVICE_SIGNAL_RELOAD_DYNAMIC,
+                sub_system,
+                rustfs_protos::DYNAMIC_CONFIG_PROTOCOL_VERSION,
+            )
+            .expect("a current peer should support dynamic scanner config");
+        }
+
+        validate_signal_service_protocol(SERVICE_SIGNAL_RELOAD_DYNAMIC, STORAGE_CLASS_SUB_SYS, 0)
+            .expect("unrelated dynamic config keeps its existing compatibility contract");
+        validate_signal_service_protocol(SERVICE_SIGNAL_REFRESH_CONFIG, SCANNER_SUB_SYS, 0)
+            .expect("full refresh compatibility is guarded by its scanner preflight");
    }

    #[test]
@@ -49,6 +49,20 @@ use tracing::{debug, info, warn};

 type Client = Arc<Box<dyn PeerS3Client>>;

+#[derive(Clone, Debug)]
+pub struct ScannerBucketListing {
+    pub buckets: Vec<BucketInfo>,
+    pub set_buckets: Vec<ScannerSetBucketListing>,
+    pub topology_complete: bool,
+}
+
+#[derive(Clone, Debug)]
+pub struct ScannerSetBucketListing {
+    pub pool_index: usize,
+    pub set_index: usize,
+    pub buckets: Vec<BucketInfo>,
+}
+
 fn pool_participant_errors(clients: &[Client], errors: &[Option<Error>], pool_idx: usize) -> Vec<Option<Error>> {
    clients
        .iter()
@@ -216,6 +230,10 @@ impl S3PeerSys {
        Ok(())
    }
    pub async fn list_bucket(&self, opts: &BucketOptions) -> Result<Vec<BucketInfo>> {
+        Ok(self.list_bucket_for_scanner(opts).await?.buckets)
+    }
+
+    pub async fn list_bucket_for_scanner(&self, opts: &BucketOptions) -> Result<ScannerBucketListing> {
        let mut futures = Vec::with_capacity(self.clients.len());
        for cli in self.clients.iter() {
            futures.push(cli.list_bucket(opts));
@@ -239,9 +257,12 @@ impl S3PeerSys {
        }

        let mut result_map: HashMap<&String, BucketInfo> = HashMap::new();
+        let mut topology_complete = true;
        for i in 0..self.pools_count {
            let per_pool_errs = pool_participant_errors(&self.clients, &errors, i);
            let quorum = pool_write_quorum(per_pool_errs.len());
+            topology_complete &=
+                !per_pool_errs.is_empty() && per_pool_errs.iter().all(|participant_error| participant_error.is_none());

            if let Some(pool_err) = reduce_pool_write_quorum_errs(&per_pool_errs) {
                tracing::error!("list_bucket per_pool_errs: {per_pool_errs:?}");
@@ -261,20 +282,17 @@ impl S3PeerSys {
                    }

                    for bucket in buckets.iter() {
-                        if result_map.contains_key(&bucket.name) {
-                            continue;
-                        }
-
                        // incr bucket_map count create if not exists
                        let count = bucket_map.entry(&bucket.name).or_insert(0usize);
                        *count += 1;

                        if *count >= quorum {
-                            result_map.insert(&bucket.name, bucket.clone());
+                            result_map.entry(&bucket.name).or_insert_with(|| bucket.clone());
                        }
                    }
                }
            }
+            topology_complete &= bucket_map.values().all(|count| *count >= quorum);
            // TODO: MRF
        }

@@ -282,7 +300,11 @@ impl S3PeerSys {

        buckets.sort_by_key(|b| b.name.clone());

-        Ok(buckets)
+        Ok(ScannerBucketListing {
+            buckets,
+            set_buckets: Vec::new(),
+            topology_complete,
+        })
    }
    pub async fn delete_bucket(&self, bucket: &str, opts: &DeleteBucketOptions) -> Result<()> {
        let mut futures = Vec::with_capacity(self.clients.len());
@@ -1645,6 +1667,86 @@ mod tests {
        assert_eq!(buckets[0].name, bucket.name);
    }

+    #[tokio::test]
+    async fn scanner_bucket_listing_marks_quorum_result_incomplete_when_a_peer_is_missing() {
+        let bucket = BucketInfo {
+            name: "bucket-hidden-by-quorum".to_string(),
+            ..Default::default()
+        };
+        let peer_sys = S3PeerSys {
+            clients: vec![
+                test_peer_with_list_bucket(&[0], Ok(vec![bucket])),
+                test_peer_with_list_bucket(&[0], Ok(Vec::new())),
+                test_peer_with_list_bucket(&[0], Ok(Vec::new())),
+                test_peer_with_list_bucket(&[0], Err(Error::DiskAccessDenied)),
+            ],
+            pools_count: 1,
+        };
+
+        let listing = peer_sys
+            .list_bucket_for_scanner(&BucketOptions::default())
+            .await
+            .expect("peer quorum should still produce a scanner candidate listing");
+
+        assert!(listing.buckets.is_empty());
+        assert!(!listing.topology_complete);
+    }
+
+    #[tokio::test]
+    async fn scanner_bucket_listing_marks_divergent_successful_peers_incomplete() {
+        let bucket = BucketInfo {
+            name: "bucket-below-quorum".to_string(),
+            ..Default::default()
+        };
+        let peer_sys = S3PeerSys {
+            clients: vec![
+                test_peer_with_list_bucket(&[0], Ok(vec![bucket.clone()])),
+                test_peer_with_list_bucket(&[0], Ok(vec![bucket])),
+                test_peer_with_list_bucket(&[0], Ok(Vec::new())),
+                test_peer_with_list_bucket(&[0], Ok(Vec::new())),
+            ],
+            pools_count: 1,
+        };
+
+        let listing = peer_sys
+            .list_bucket_for_scanner(&BucketOptions::default())
+            .await
+            .expect("successful peer responses should still produce a scanner candidate listing");
+
+        assert!(listing.buckets.is_empty());
+        assert!(!listing.topology_complete);
+    }
+
+    #[tokio::test]
+    async fn scanner_bucket_listing_checks_same_bucket_in_every_pool() {
+        let bucket = BucketInfo {
+            name: "shared-bucket".to_string(),
+            ..Default::default()
+        };
+        let peer_sys = S3PeerSys {
+            clients: vec![
+                test_peer_with_list_bucket(&[0], Ok(vec![bucket.clone()])),
+                test_peer_with_list_bucket(&[0], Ok(vec![bucket.clone()])),
+                test_peer_with_list_bucket(&[0], Ok(vec![bucket.clone()])),
+                test_peer_with_list_bucket(&[0], Ok(vec![bucket.clone()])),
+                test_peer_with_list_bucket(&[1], Ok(vec![bucket.clone()])),
+                test_peer_with_list_bucket(&[1], Ok(vec![bucket.clone()])),
+                test_peer_with_list_bucket(&[1], Ok(Vec::new())),
+                test_peer_with_list_bucket(&[1], Ok(Vec::new())),
+            ],
+            pools_count: 2,
+        };
+
+        let listing = peer_sys
+            .list_bucket_for_scanner(&BucketOptions::default())
+            .await
+            .expect("a bucket visible in one pool should remain a scan candidate");
+
+        assert_eq!(listing.buckets.len(), 1);
+        assert_eq!(listing.buckets[0].name, bucket.name);
+        assert!(!listing.topology_complete);
+    }
+
    #[tokio::test]
    async fn test_delete_bucket_fails_when_any_pool_misses_write_quorum() {
        let peer_sys = S3PeerSys {
@@ -17,7 +17,8 @@ use crate::cluster::rpc::client::{
    node_service_time_out_client_for_class, node_service_time_out_client_no_auth,
 };
 use crate::cluster::rpc::internode_data_transport::{
-    InternodeDataTransport, ReadStreamRequest, WalkDirStreamRequest, WriteStreamRequest,
+    InternodeDataTransport, NsScannerCapabilityRequest, NsScannerStreamRequest, ReadStreamRequest, WalkDirStreamRequest,
+    WriteStreamRequest,
 };
 use crate::disk::error::{Error, Result};
 use crate::disk::{
@@ -81,6 +82,7 @@ const REMOTE_DISK_OPEN_WRITE_MAX_ATTEMPTS: usize = 2;
 const REMOTE_DISK_OPEN_WRITE_RETRY_BACKOFF: Duration = Duration::from_millis(20);
 const REMOTE_DISK_OPEN_READ_MAX_ATTEMPTS: usize = 2;
 const REMOTE_DISK_OPEN_READ_RETRY_BACKOFF: Duration = Duration::from_millis(20);
+const NS_SCANNER_CAPABILITY_PROBE_TIMEOUT: Duration = Duration::from_secs(5);
 /// Base backoff for idempotent read-only RPC retries (grpc-optimization P3-3); doubles per attempt.
 const REMOTE_DISK_READ_RETRY_BASE_BACKOFF: Duration = Duration::from_millis(50);
 const ENV_RUSTFS_METADATA_BATCH_READ: &str = "RUSTFS_METADATA_BATCH_READ";
@@ -97,6 +99,17 @@ const LOG_SUBSYSTEM_REMOTE_DISK: &str = "remote_disk";
 const EVENT_REMOTE_DISK_HEALTH: &str = "remote_disk_health";
 const EVENT_REMOTE_DISK_RPC: &str = "remote_disk_rpc";

+fn decode_volume_infos(volume_infos: Vec<String>) -> Result<Vec<VolumeInfo>> {
+    volume_infos
+        .into_iter()
+        .enumerate()
+        .map(|(index, json)| {
+            serde_json::from_str::<VolumeInfo>(&json)
+                .map_err(|err| Error::other(format!("decode list volumes entry {index} failed: {err}")))
+        })
+        .collect()
+}
+
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 enum BatchMetadataRpcMode {
    Off,
@@ -264,6 +277,71 @@ fn spawn_control_channel_prewarm(addr: String) {
 }

 impl RemoteDisk {
+    pub(crate) async fn ns_scanner_server_epoch(&self) -> Result<Option<Uuid>> {
+        if self.health.is_faulty() {
+            return Err(DiskError::FaultyDisk);
+        }
+        let probe = self.data_transport.probe_ns_scanner(NsScannerCapabilityRequest {
+            endpoint: self.endpoint.grid_host(),
+        });
+        let result = timeout(NS_SCANNER_CAPABILITY_PROBE_TIMEOUT, probe)
+            .await
+            .map_err(|_| DiskError::other("remote namespace scanner capability probe timed out"))?;
+        match result {
+            Ok(server_epoch) => Ok(Some(server_epoch)),
+            // RUSTFS_COMPAT_TODO(ns-scanner-rpc-v3): old peers and legacy transports lack the authenticated startup-epoch handshake. Remove after every supported peer implements namespace scanner protocol v3.
+            Err(DiskError::MethodNotAllowed) => Ok(None),
+            Err(err)
+                if matches!(
+                    err.internode_http_error_kind(),
+                    Some(rustfs_rio::InternodeHttpErrorKind::HttpStatus(status))
+                        if matches!(status.as_u16(), 404 | 405)
+                ) =>
+            {
+                Ok(None)
+            }
+            Err(err)
+                if matches!(
+                    err.internode_http_error_kind(),
+                    Some(rustfs_rio::InternodeHttpErrorKind::HttpStatus(status)) if status.as_u16() == 426
+                ) =>
+            {
+                Ok(None)
+            }
+            Err(err) => Err(err),
+        }
+    }
+
+    pub(crate) async fn open_ns_scanner_stream(&self, request: crate::disk::NsScannerOpenRequest) -> Result<FileReader> {
+        if self.health.is_faulty() {
+            return Err(DiskError::FaultyDisk);
+        }
+        let crate::disk::NsScannerOpenRequest {
+            request_id,
+            server_epoch,
+            session_id,
+            session_sequence,
+            next_cycle,
+            leader_epoch,
+            body,
+            stall_timeout,
+        } = request;
+        self.data_transport
+            .open_ns_scanner(NsScannerStreamRequest {
+                endpoint: self.endpoint.grid_host(),
+                disk: self.disk_ref().await,
+                request_id,
+                server_epoch,
+                session_id,
+                session_sequence,
+                next_cycle,
+                leader_epoch,
+                body,
+                stall_timeout,
+            })
+            .await
+    }
+
    fn recovery_monitor_span(addr: &str, endpoint: &Endpoint) -> tracing::Span {
        tracing::info_span!(
            "recovery-monitor",
@@ -1335,11 +1413,7 @@ impl DiskAPI for RemoteDisk {
                    return Err(response.error.unwrap_or_default().into());
                }

-                let infos = response
-                    .volume_infos
-                    .into_iter()
-                    .filter_map(|json_str| serde_json::from_str::<VolumeInfo>(&json_str).ok())
-                    .collect();
+                let infos = decode_volume_infos(response.volume_infos)?;

                Ok(infos)
            },
@@ -2722,6 +2796,19 @@ mod tests {

    static INIT: Once = Once::new();

+    #[test]
+    fn list_volumes_decode_rejects_a_malformed_entry() {
+        let valid = serde_json::to_string(&VolumeInfo {
+            name: "bucket".to_string(),
+            created: None,
+        })
+        .expect("volume info should serialize");
+        let err = decode_volume_infos(vec![valid, "{".to_string()])
+            .expect_err("a malformed volume entry must fail the complete response");
+
+        assert!(err.to_string().contains("entry 1"));
+    }
+
    #[test]
    fn decoded_remote_metadata_rejects_default_like_delete_marker() {
        let forged = FileInfo {
@@ -2794,14 +2881,31 @@ mod tests {
        Read(ReadStreamRequest),
        Write(WriteStreamRequest),
        WalkDir(WalkDirStreamRequest),
+        NsScanner(NsScannerStreamRequest),
+        NsScannerProbe(NsScannerCapabilityRequest),
    }

    #[derive(Debug, Clone, Default)]
    struct RecordingInternodeDataTransport {
        calls: Arc<StdMutex<Vec<RecordedTransportCall>>>,
+        ns_scanner_probe_status: Arc<StdMutex<Option<u16>>>,
    }

    impl RecordingInternodeDataTransport {
+        fn with_ns_scanner_probe_status(status: u16) -> Self {
+            Self {
+                calls: Arc::default(),
+                ns_scanner_probe_status: Arc::new(StdMutex::new(Some(status))),
+            }
+        }
+
+        fn set_ns_scanner_probe_status(&self, status: Option<u16>) {
+            *self
+                .ns_scanner_probe_status
+                .lock()
+                .expect("namespace scanner probe status lock poisoned") = status;
+        }
+
        fn calls(&self) -> Vec<RecordedTransportCall> {
            self.calls.lock().expect("recorded transport calls lock poisoned").clone()
        }
@@ -3369,6 +3473,26 @@ mod tests {
            Ok(Box::new(EmptyTestReader))
        }

+        async fn open_ns_scanner(&self, request: NsScannerStreamRequest) -> Result<FileReader> {
+            self.record(RecordedTransportCall::NsScanner(request));
+            Ok(Box::new(EmptyTestReader))
+        }
+
+        async fn probe_ns_scanner(&self, request: NsScannerCapabilityRequest) -> Result<Uuid> {
+            self.record(RecordedTransportCall::NsScannerProbe(request));
+            if let Some(status) = *self
+                .ns_scanner_probe_status
+                .lock()
+                .expect("namespace scanner probe status lock poisoned")
+            {
+                let status = reqwest::StatusCode::from_u16(status).expect("test status code should be valid");
+                return Err(
+                    rustfs_rio::new_test_internode_http_io_error(rustfs_rio::InternodeHttpErrorKind::HttpStatus(status)).into(),
+                );
+            }
+            Ok(Uuid::from_u128(1))
+        }
+
        fn name(&self) -> &'static str {
            "recording"
        }
@@ -3401,6 +3525,14 @@ mod tests {
            }
        }

+        async fn open_ns_scanner(&self, _request: NsScannerStreamRequest) -> Result<FileReader> {
+            panic!("open_ns_scanner should not be used in walk_dir retry test");
+        }
+
+        async fn probe_ns_scanner(&self, _request: NsScannerCapabilityRequest) -> Result<Uuid> {
+            Ok(Uuid::from_u128(1))
+        }
+
        fn name(&self) -> &'static str {
            "retrying-walk-dir"
        }
@@ -3429,6 +3561,14 @@ mod tests {
            panic!("open_walk_dir should not be used in open_write retry test");
        }

+        async fn open_ns_scanner(&self, _request: NsScannerStreamRequest) -> Result<FileReader> {
+            panic!("open_ns_scanner should not be used in open_write retry test");
+        }
+
+        async fn probe_ns_scanner(&self, _request: NsScannerCapabilityRequest) -> Result<Uuid> {
+            Ok(Uuid::from_u128(1))
+        }
+
        fn name(&self) -> &'static str {
            "retrying-open-write"
        }
@@ -4092,6 +4232,139 @@ mod tests {
        }
    }

+    #[tokio::test]
+    async fn test_remote_disk_namespace_scanner_uses_configured_data_transport() {
+        let transport = RecordingInternodeDataTransport::default();
+        let remote_disk = new_remote_disk_with_transport(Arc::new(transport.clone())).await;
+        let expected_disk = remote_disk.disk_ref().await;
+        let expected_body = b"namespace-scanner-request".to_vec();
+        let expected_request_id = Uuid::new_v4();
+        let expected_server_epoch = Uuid::new_v4();
+        let expected_session_id = Uuid::new_v4();
+
+        let _reader = remote_disk
+            .open_ns_scanner_stream(crate::disk::NsScannerOpenRequest {
+                request_id: expected_request_id,
+                server_epoch: expected_server_epoch,
+                session_id: expected_session_id,
+                session_sequence: 3,
+                next_cycle: 7,
+                leader_epoch: 9,
+                body: expected_body.clone(),
+                stall_timeout: Some(Duration::from_secs(15)),
+            })
+            .await
+            .expect("namespace scanner stream should open");
+
+        let calls = transport.calls();
+        assert_eq!(calls.len(), 1);
+        match &calls[0] {
+            RecordedTransportCall::NsScanner(request) => {
+                assert_eq!(request.endpoint, "http://remote-node:9000");
+                assert_eq!(request.disk, expected_disk);
+                assert_eq!(request.request_id, expected_request_id);
+                assert_eq!(request.server_epoch, expected_server_epoch);
+                assert_eq!(request.session_id, expected_session_id);
+                assert_eq!(request.session_sequence, 3);
+                assert_eq!(request.next_cycle, 7);
+                assert_eq!(request.leader_epoch, 9);
+                assert_eq!(request.body, expected_body);
+                assert_eq!(request.stall_timeout, Some(Duration::from_secs(15)));
+            }
+            other => panic!("expected namespace scanner transport call, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_remote_disk_namespace_scanner_capability_uses_configured_data_transport() {
+        let transport = RecordingInternodeDataTransport::default();
+        let remote_disk = new_remote_disk_with_transport(Arc::new(transport.clone())).await;
+
+        assert_eq!(
+            remote_disk
+                .ns_scanner_server_epoch()
+                .await
+                .expect("namespace scanner capability probe should succeed"),
+            Some(Uuid::from_u128(1))
+        );
+
+        let calls = transport.calls();
+        assert_eq!(calls.len(), 1);
+        match &calls[0] {
+            RecordedTransportCall::NsScannerProbe(request) => {
+                assert_eq!(request.endpoint, "http://remote-node:9000");
+            }
+            other => panic!("expected namespace scanner capability probe, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_remote_disk_namespace_scanner_capability_rejects_old_and_incompatible_peers() {
+        for status in [404, 405, 426] {
+            let transport = RecordingInternodeDataTransport::with_ns_scanner_probe_status(status);
+            let remote_disk = new_remote_disk_with_transport(Arc::new(transport)).await;
+
+            assert_eq!(
+                remote_disk
+                    .ns_scanner_server_epoch()
+                    .await
+                    .expect("unsupported namespace scanner response should be classified"),
+                None
+            );
+        }
+    }
+
+    #[tokio::test]
+    async fn test_remote_disk_namespace_scanner_capability_rejects_legacy_transport() {
+        let remote_disk = new_remote_disk_with_transport(Arc::new(RetryingOpenReadInternodeDataTransport::default())).await;
+
+        assert_eq!(
+            remote_disk
+                .ns_scanner_server_epoch()
+                .await
+                .expect("legacy transport should be classified as unsupported"),
+            None
+        );
+    }
+
+    #[tokio::test]
+    async fn test_remote_disk_namespace_scanner_capability_reprobes_after_peer_upgrade() {
+        let transport = RecordingInternodeDataTransport::with_ns_scanner_probe_status(404);
+        let remote_disk = new_remote_disk_with_transport(Arc::new(transport.clone())).await;
+
+        assert_eq!(
+            remote_disk
+                .ns_scanner_server_epoch()
+                .await
+                .expect("old peer should be classified as unsupported"),
+            None
+        );
+        transport.set_ns_scanner_probe_status(None);
+        assert_eq!(
+            remote_disk
+                .ns_scanner_server_epoch()
+                .await
+                .expect("upgraded peer should be re-probed"),
+            Some(Uuid::from_u128(1))
+        );
+        assert_eq!(transport.calls().len(), 2);
+    }
+
+    #[tokio::test]
+    async fn test_remote_disk_namespace_scanner_capability_propagates_transient_failure() {
+        let transport = RecordingInternodeDataTransport::with_ns_scanner_probe_status(503);
+        let remote_disk = new_remote_disk_with_transport(Arc::new(transport)).await;
+
+        let err = remote_disk
+            .ns_scanner_server_epoch()
+            .await
+            .expect_err("transient capability failure must not be reported as unsupported");
+        assert!(matches!(
+            err.internode_http_error_kind(),
+            Some(rustfs_rio::InternodeHttpErrorKind::HttpStatus(status)) if status.as_u16() == 503
+        ));
+    }
+
    #[tokio::test]
    async fn test_remote_disk_walk_dir_preserves_skip_total_timeout_option() {
        let transport = RecordingInternodeDataTransport::default();