Description

This PR addresses a potential Arbitrary File Write / Path Traversal vulnerability in TransferManager.downloadManyFiles() by enforcing strict path containment checks on all downloaded object names.

The entire path assembly pipeline has been refactored to prioritize security and path normalization:

1. Sequential Name Assembly: All path modifications (stripPrefix, prefix) are applied sequentially to the relative object name before security validation.

2. Absolute Path Rejection: The function now immediately rejects object names (even after modification) that are absolute paths (e.g., /etc/passwd).

3. Canonical Resolution and Containment: The final relative path is resolved into an absolute path (finalPath = path.resolve(baseDir, name)). The function then verifies that finalPath strictly begins with the absolute baseDir, preventing path traversal sequences like ../../.

4. Directory Marker Fix: A critical fix was added to explicitly check if the original GCS object name was a directory marker (ends in /). Since path.resolve strips the trailing slash, logic was added to re-add the separator to finalPath for directory markers, ensuring fsp.mkdir is called correctly.

The old, manual, and insecure logic for joining prefix and destination using path.join() was removed as it bypassed these new security checks.

Impact

The primary impact is a significant security uplift for all users utilizing downloadManyFiles().

• Security: Prevents malicious object names from writing files outside the intended download folder (e.g., preventing overwrites of configuration files or system files).

• Behavioral Change: If a malicious path traversal attempt is detected, the function will no longer silently fail or attempt an unsafe operation. It will now explicitly throw a SECURITY_PATH_TRAVERSAL_REJECTED error (or SECURITY_ABSOLUTE_PATH_REJECTED).

• Internal Consistency: The destination passed to the underlying file.download method is now always a canonical, absolute path, improving consistency across all download scenarios.

Testing

Yes, unit tests were heavily modified.

• All existing tests related to checking the destination path (prefix, stripPrefix, passthroughOptions.destination, and default download) were updated to assert against the new absolute, canonical path returned by the secure logic.

• New test assertions were added to explicitly verify that attempts to use absolute paths or traversal sequences result in the expected security exceptions.

• The complex test for nested directories was fully refactored and now passes, confirming that the new directory marker fix correctly triggers the recursive fsp.mkdir call.

Breaking Changes: None technically, as the previous behavior was insecure. However, consumers who rely on supplying relative paths for passthroughOptions.destination will now receive absolute paths in the underlying file.download callback options, which is a desirable side effect of the security fix.

Additional Information

The implementation detail to note is the use of path.resolve for path canonicalization. This forced the manual re-insertion of the trailing path separator (path.sep) for GCS folder markers, as path.resolve strips it, which otherwise would prevent the directory from being created recursively. This refactoring was essential to maintaining directory creation functionality while enforcing path safety.

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 #