feat: implement fast multipart download API for envd

[mishushakov]

Summary

Implements efficient multipart file downloads using direct ReadAt() for random access reads, mirroring the existing multipart upload pattern. Supports concurrent part downloads with configurable part sizes (default 5MB, max 100MB) and session-based management with 1-hour TTL and automatic cleanup.

Test plan

• ✅ Init session with correct metadata
• ✅ Download all parts and verify content
• ✅ Out-of-order part downloads (thread-safe)
• ✅ Invalid downloadId/part returns 400/404
• ✅ Max sessions limit returns 429
• ✅ Session cleanup on TTL expiry
• ✅ Auth allowlist updated for download paths

🤖 Generated with Claude Code

In general, to fix uncontrolled path usage, we should resolve the user-provided path against a well-defined base directory and then verify that the resulting absolute path is still inside that base. If it is not, we reject the request. This prevents directory traversal or arbitrary absolute path usage even when the attacker supplies .. components or absolute paths.

The best place to fix this without changing existing behavior too much is in permissions.ExpandAndResolve. That function is the centralized helper used to turn a user-supplied path plus user and defaultPath info into an absolute path. We can extend it so that it (1) computes a base directory (either from defaultPath or user.HomeDir), (2) expands ~ relative to that base, (3) resolves to an absolute path, and (4) ensures the resulting absolute path stays under the base directory. If the path escapes the base (for example, via .. or an absolute path like /etc/passwd), we return an error instead of the path.

Concretely, in permissions/path.go we will:

• Import "strings" to support prefix checks.
• Change ExpandAndResolve to:
  • Compute an absolute baseDir from defaultPath (if provided) or user.HomeDir.
  • Apply execcontext.ResolveDefaultWorkdir as before to handle empty/default values.
  • Use expand to deal with ~, but ensure it uses the base directory semantics.
  • Always join the resulting path to baseDir (ignoring whether the user supplied an absolute path).
  • Call filepath.Abs to normalize the joined path.
  • Check that abs is within baseDir using a prefix check after ensuring both are absolute, with a trailing separator logic to avoid partial prefix issues.
  • Return an error if the check fails.

We will not modify multipart_download.go because it is already centralizing resolution via permissions.ExpandAndResolve; after we harden that function, filePath will be safe to use with os.Stat and subsequent file operations.

---

General fix approach: After resolving the user-supplied path into an absolute path, ensure that it is contained within a safe base directory (such as the user’s home directory or a configured workdir). Reject paths that escape this base. This is done by: (1) computing the base directory as an absolute path, (2) resolving the requested path relative to that base (or expanding ~ into that base), and (3) verifying that the final absolute path still has the base as its prefix on a path-component boundary.

Best concrete fix here without changing external behavior more than necessary:

1. Strengthen permissions.ExpandAndResolve so it:

   • Always resolves the user-supplied path to an absolute path.
   • Determines a “base directory” from the given user and defaultPath (via execcontext.ResolveDefaultWorkdir), normalizes that base to an absolute path, and uses it as the root.
   • Expands ~ using user.HomeDir as before.
   • If the resulting path is not absolute, join it relative to the base directory, then normalize.
   • Finally, verify that the resulting absolute path is within the base directory using a safe prefix check (e.g., strings.HasPrefix(absPathWithSeparator, baseWithSeparator) after both are cleaned and made absolute). If it is outside, return an error instead of the path.

2. To avoid breaking existing behavior where a fully absolute path is passed, we still accept it only if it lies under the computed base directory; otherwise, we now reject it. This is the key security change.

3. The caller in PostFilesDownloadInit continues to call permissions.ExpandAndResolve and then uses filePath for os.Stat and os.Open. With the added containment check, filePath can no longer reference arbitrary filesystem locations outside the intended base, which addresses the CodeQL finding.

Implementation details / specific changes:

• In packages/envd/internal/permissions/path.go:

  • Add an import of strings.
  • Introduce computation of a baseDir at the start of ExpandAndResolve:
    • Use execcontext.ResolveDefaultWorkdir(path, defaultPath) as now, but we’ll separate the concerns: first resolve resolvedPath := execcontext.ResolveDefaultWorkdir(path, defaultPath), then derive baseDir from defaultPath (or user.HomeDir if no default path).
    • Compute baseDirAbs := filepath.Abs(baseDir) and handle errors.
  • Apply expand on the resolved path as now.
  • If the expanded path is not absolute, join it with baseDirAbs and normalize via filepath.Abs.
  • If the (possibly already absolute) expanded path is absolute but not under baseDirAbs, return an error indicating the path is outside the allowed base.
  • Implement a helper-style check inline in ExpandAndResolve using strings.TrimRight + HasPrefix to enforce directory containment.

• No changes are needed in packages/envd/internal/api/multipart_download.go, because we centralize the security in ExpandAndResolve. The call site already handles an error from ExpandAndResolve and returns a 400 Bad Request, which is appropriate when the requested path is invalid or disallowed.