Feat: Implement robust path validation and structured skip reporting

[thiyaguk09]

Description

This PR implements a robust security layer for the downloadManyFiles method in the TransferManager. It addresses potential path traversal vulnerabilities and introduces a structured result reporting system.

Key Changes:

• Structured Reporting: Changed the return type from Promise<DownloadResponse[]> to Promise<DownloadManyFilesResult>. This new object includes both successful responses and a skippedFiles array containing detailed metadata (reason, message, local path).

• Strict Security Validation: Implemented a "Strict Blocking" model for file paths. It prevents:

  • Path Traversal: Blocking dot-segments (../) that resolve outside the intended target.
  • Absolute Escape: Blocking object names that start with /, \, or Windows drive letters to prevent root-level directory escapes.
  • Filename Poisoning: Filtering illegal characters such as Null bytes (\0), control characters, and Windows volume separators (:).

• Parity Guarantee: Updated the internal batch loop to ensure every input file is accounted for. If a file is not downloaded due to security or a network error, it is explicitly added to the skippedFiles list.

Impact

This is a BREAKING CHANGE.
Existing implementations that expect an array return from downloadManyFiles will need to be updated to destructure the new result object.

Testing

Unit Tests:

• Added a "Parity Check" test to ensure inputCount === responses.length + skippedFiles.length.
• Verified behavior across simulated Unix and Windows path structures.

Integration Tests:

• Updated existing storage samples to handle the new return type and log skipped files.
• Verified that successful downloads still function as expected with the new parallel limit logic.

Additional Information

Migration Guide for Users

Before:

const results = await transferManager.downloadManyFiles(files);
console.log(`${results.length} files downloaded.`);

After:

const { responses, skippedFiles } = await transferManager.downloadManyFiles(files);
console.log(`${responses.length} files downloaded.`);

if (skippedFiles.length > 0) {
 console.warn(`${skippedFiles.length} files were skipped for security or errors.`);
}

Checklist

• Make sure to open an issue as a bug/issue before writing your code! That way we can discuss the change, evaluate designs, and agree on the general idea
• Ensure the tests and linter pass
• Code coverage does not decrease
• Appropriate docs were updated
• Appropriate comments were added, particularly in complex areas or places that require background
• No new warnings or issues will be generated from this change

Fixes #2660