comfyui-mcp 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -4,6 +4,94 @@ All notable changes to this project are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/) and the format follows
 [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.8.1] - 2026-06-01
+
+Bug-fix release picking up upstream contributions from
+[@joaolvivas](https://github.com/joaolvivas)'s fork of comfyui-mcp.
+
+### Added
+
+- **`health_check`** — single-call pre-flight diagnostic that reports
+  ComfyUI/Python/PyTorch versions, GPU + VRAM, queue depth, per-category
+  `/models` populations (catches empty-dropdown surprises from a
+  misconfigured `extra_model_paths.yaml`), and recent errors from
+  `/internal/logs`. Read-only. Useful before a long batch or when triaging an
+  unexplained failure. Originally contributed by
+  [@joaolvivas](https://github.com/joaolvivas) in
+  [`joaolvivas/comfyui-mcp-byjlucas@de82ecda`](https://github.com/joaolvivas/comfyui-mcp-byjlucas/commit/de82ecda).
+
+### Fixed
+
+- **`search_custom_nodes`** — `api.comfy.org/nodes` accepts a `search` query
+  parameter but ignores it server-side, returning the same paginated default
+  list regardless of query. We now fetch a larger window (limit=100) and
+  rank-filter client-side by id / name / author / description with a
+  popularity boost, so query-relevant packs actually appear. Diagnosed and
+  patched by [@joaolvivas](https://github.com/joaolvivas) in
+  [`joaolvivas/comfyui-mcp-byjlucas@f066b597`](https://github.com/joaolvivas/comfyui-mcp-byjlucas/commit/f066b597);
+  port adds a guard so popularity no longer inflates non-matching packs.
+- **`upload_image` / `upload_video` / `upload_audio`** — HTTP-only.
+  Previously these tools fell back to a local filesystem copy if HTTP upload
+  failed and `COMFYUI_PATH` was set. When `COMFYUI_PATH` was auto-detected to
+  an unrelated install (common for users targeting a remote `--comfyui-url`),
+  the fallback wrote the file to the wrong tree and reported success, while
+  the remote ComfyUI never received it — the next `LoadImage` then failed
+  mysteriously. Now HTTP-only against the connected ComfyUI's
+  `/upload/image` endpoint, which works for both local and remote. Diagnosed
+  and patched by [@joaolvivas](https://github.com/joaolvivas) in
+  [`joaolvivas/comfyui-mcp-byjlucas@089180ad`](https://github.com/joaolvivas/comfyui-mcp-byjlucas/commit/089180ad).
+
+## [0.8.0] - 2026-05-26
+
+Completes the custom-node authoring lifecycle, adds cloud storage I/O and
+declarative setup, and adds node discovery — all built and reviewed in a
+codex implement→review→fix loop.
+
+### Added
+
+- **`apply_manifest`** — declarative environment setup from an inline object or
+  a JSON/YAML manifest: `pip` packages, `custom_nodes` (registry ids or git URLs
+  with `@ref`), and `models`. Idempotent, per-item structured report; `apt`
+  entries are accepted but skipped (manual/root). Local-only.
+- **`verify_custom_node`** — the "test" step of the author loop: restarts ComfyUI
+  (with a bounded readiness wait) and confirms a pack's `NODE_CLASS_MAPPINGS`
+  class_types registered in `/object_info` (a failed import simply never appears).
+- **`scaffold_custom_node`** now also emits `.comfyignore`/`.gitignore` and, with
+  `with_ci`, a `.github/workflows/publish_action.yml` (Comfy-Org/publish-node-action).
+- **`convert_image`** — re-encode a generated image (by `asset_id` or output-dir
+  path) to PNG/JPEG/WebP via `sharp`; returns inline base64 + optional file write
+  (output-dir confined), and reports bytes saved.
+- **Cloud storage** — model downloads may be `s3://` or Azure Blob URLs
+  (`download_model` gains `s3` auth); new **`upload_output`** pushes a generated
+  output to S3 / Azure / HTTP / Hugging Face and returns URL(s).
+- **`download_model` `auth`** — per-request `bearer`/`basic`/`header`/`query`
+  authentication for gated/private hosts (carried over and extended).
+- **`comfy-researcher` agent** — turns a problem statement into ranked custom-node
+  pack recommendations (searches the Registry, evaluates, delegates deep dives to
+  `comfy-explorer`).
+- **Cached `generate_node_skill`** — read-through cache keyed by source@version
+  (`COMFYUI_SKILL_CACHE_DIR`; `refresh` to bypass), so repeat analyses are instant.
+
+### Security
+
+- `apply_manifest` rejects pip argv-option injection; realpath/symlink-safe path
+  containment for manifest model paths, `convert_image`, and upload sources;
+  `convert_image` caps source size + sharp pixels.
+- Cloud storage: Azure SAS / AWS presigned secrets redacted from logs/errors;
+  Azure URL-vs-env account mismatch rejected; HF-CLI remote-path argv hardening;
+  manual redirect handling (no cross-origin auth replay or upload-redirect SSRF).
+
+### Fixed
+
+- `generate_node_skill` cache resolves the current pack version before lookup
+  (no stale docs served after a pack updates) and writes atomically (temp +
+  rename with a content-hash check).
+
+### Dependencies
+
+- Added `yaml` (manifest parsing), `sharp` (image conversion), `@aws-sdk/client-s3`
+  and `@azure/storage-blob` (cloud storage). `npm audit`: 0 high vulnerabilities.
+
 ## [0.7.0] - 2026-05-25
 
 Stability + authoring release: hardens model downloads and the ComfyUI process
@@ -120,6 +208,8 @@ subprocess fallback where the API can't do the job.
 
 Earlier releases predate this changelog.
 
+[0.8.1]: https://github.com/artokun/comfyui-mcp/releases/tag/v0.8.1
+[0.8.0]: https://github.com/artokun/comfyui-mcp/releases/tag/v0.8.0
 [0.7.0]: https://github.com/artokun/comfyui-mcp/releases/tag/v0.7.0
 [0.6.1]: https://github.com/artokun/comfyui-mcp/releases/tag/v0.6.1
 [0.6.0]: https://github.com/artokun/comfyui-mcp/releases/tag/v0.6.0

package/CONTRIBUTING.md

@@ -0,0 +1,137 @@
+# Contributing to comfyui-mcp
+
+Thanks for your interest in improving **comfyui-mcp** — an MCP server (and Claude Code plugin)
+that lets an AI agent drive [ComfyUI](https://github.com/comfyanonymous/ComfyUI). This guide covers
+the dev setup, project conventions, how to add a tool, and how releases work.
+
+By contributing you agree your contributions are licensed under the project's [MIT License](./LICENSE).
+
+## Getting started
+
+Requirements: **Node ≥ 22** and npm (the repo is committed with `package-lock.json`; npm is the
+supported dev path).
+
+```bash
+git clone https://github.com/artokun/comfyui-mcp
+cd comfyui-mcp
+npm install        # builds native deps (better-sqlite3, sharp)
+npm run build      # tsc → dist/
+npm test           # vitest
+```
+
+- **`npm run build`** — type-checks and compiles to `dist/` (`tsc`).
+- **`npm run lint`** — type-check only (`tsc --noEmit`).
+- **`npm test`** / **`npm run test:watch`** — the vitest suite.
+- **`npm run dev`** — run the server from source via `tsx`.
+- **`npm run docs:gen`** — regenerate the docs tool reference from the live schemas (see [Docs](#documentation)).
+
+> **pnpm users:** pnpm 10 blocks dependency build scripts unless allow-listed. The native deps are
+> already declared in `package.json` `pnpm.onlyBuiltDependencies` (`better-sqlite3`, `sharp`); if you
+> add a dependency that needs a build step at runtime, add it there too.
+
+Before opening a PR, make sure **`npm run build` and `npm test` both pass**.
+
+## Project layout
+
+```
+src/
+  tools/        # thin MCP tool wrappers — one registerXxxTools(server) per file
+    index.ts    #   registers every tool group (the one shared wiring file)
+  services/     # the actual logic (network, subprocess, filesystem)
+  comfyui/      # ComfyUI client + workflow types
+  utils/        # errors, logger, shared helpers
+  __tests__/    # vitest tests, mirroring the source path
+scripts/        # build/docs/util scripts (gen-tool-docs.ts, postinstall.mjs, …)
+docs/           # Mintlify docs site (tool reference is GENERATED — see below)
+plugin/         # the Claude Code plugin (skills, agents, slash commands, hooks)
+```
+
+**Separation of concerns:** business logic lives in `src/services/<name>.ts`; the matching
+`src/tools/<name>.ts` is a thin wrapper that defines the MCP tool and calls the service.
+
+## Conventions
+
+- **ESM** — this is an ESM package; **relative imports must use the `.js` extension**
+  (`import { foo } from "./foo.js"`), even from `.ts` files.
+- **Errors** — throw typed errors from `src/utils/errors.ts` (`ComfyUIError`, `ValidationError`,
+  `ProcessControlError`, …) and convert them at the tool boundary with `errorToToolResult(err)`.
+- **Local vs remote** — comfyui-mcp can target a remote ComfyUI (`--comfyui-url`). Tools that need a
+  local install must read `config.comfyuiPath` and throw a clear error when it's undefined.
+- **Security** (please respect these — they're enforced in review):
+  - Secrets (API tokens, registry keys, cloud credentials) travel in **headers or env**, never in
+    URLs, argv, or logs. Redact secrets from any logged URL.
+  - Validate filesystem paths against traversal/symlink escapes (resolve + contain to the intended root).
+  - Validate values that reach a subprocess argv (reject leading `-` / control chars; use
+    `--end-of-options` for git, etc.).
+
+## Adding a new MCP tool
+
+Use `src/tools/registry-search.ts` and `src/tools/process-control.ts` as canonical examples.
+
+1. **Service** — add `src/services/<name>.ts` with the logic and an exported function. Keep network
+   in `fetch`, subprocess in `node:child_process`. Make I/O seams injectable so they're testable.
+2. **Tool** — add `src/tools/<name>.ts` exporting `registerXxxTools(server: McpServer): void`. Inside,
+   call `server.tool(name, description, zodShape, handler)`. Handlers return
+   `{ content: [{ type: "text" as const, text }] }` and wrap failures with `errorToToolResult(err)`.
+3. **Wire it** — add one import and one `registerXxxTools(server);` call in `src/tools/index.ts`,
+   **before** `await registerAutoloadedWorkflows(server);`.
+4. **Categorize for docs** — add the new tool name to the right category in
+   `scripts/gen-tool-docs.ts` (`CATEGORIES`), then run `npm run docs:gen` (it warns about any
+   uncategorized tool).
+5. **Test** — add `src/__tests__/…` mirroring the source path. Mock `global.fetch`,
+   `node:child_process`, and `node:fs` — **no real network, disk, or process side effects**.
+
+### Tool descriptions matter
+
+Descriptions are the agent's only guide to a tool. Write them to answer three questions:
+**what it does to the world** (read-only? mutates disk? requires a running server? irreversible?),
+**when to use it vs. a sibling tool**, and **what each parameter means beyond its type**. Don't just
+restate the schema. (This is graded by Glama's TDQS — see the [blog post](https://comfyui-mcp.artokun.io/docs/blog/comfyui-mcp-tdqs-case-study).)
+
+## Documentation
+
+The hosted docs live in `docs/` (Mintlify). The **Tool Reference is generated** from the live tool
+schemas — **do not hand-edit `docs/tools/*.mdx`**. After changing any tool (name, description,
+params), run:
+
+```bash
+npm run docs:gen
+```
+
+and commit the regenerated MDX. Guide pages (`docs/*.mdx`) are hand-written; edit those directly.
+Run `cd docs && npx mint broken-links` to validate links.
+
+## Optional / experimental dependencies
+
+Cloud storage (`@aws-sdk/client-s3`, `@azure/storage-blob`) and the experimental agent-panel POC
+(`ai`, `@ai-sdk/*`, `cloudflared`) power optional/flag-gated features. Keep new heavy or
+feature-specific dependencies out of the core hot path, and prefer lazy/dynamic imports so a base
+install stays lean.
+
+## Commits & pull requests
+
+- **Branch** off `main` (`feat/…`, `fix/…`, `docs/…`).
+- Use **Conventional Commit** prefixes (`feat:`, `fix:`, `docs:`, `chore:`, `test:`, `refactor:`).
+- Keep PRs focused; include tests for behavior changes.
+- **PR checklist:** `npm run build` ✓ · `npm test` ✓ · docs regenerated if tools changed ✓ ·
+  a clear description of what and why.
+
+Open a GitHub issue first for large or potentially-breaking changes so we can align on the approach.
+
+## Releases (maintainers)
+
+Releases are automated — **never `npm publish` manually**. Bump + tag, and pushing the `v*` tag
+triggers the GitHub Actions workflow that publishes to npm with provenance (OIDC):
+
+```bash
+npm run release        # patch
+npm run release:minor  # minor
+npm run release:major  # major
+```
+
+Each script runs `npm version <bump>` (creating the commit + tag) and `git push --follow-tags`.
+Update `CHANGELOG.md` (Keep a Changelog) and regenerate docs before tagging.
+
+## Questions
+
+Open a [GitHub issue](https://github.com/artokun/comfyui-mcp/issues) or start a discussion. Thanks for contributing! 🎨

package/README.md

@@ -641,10 +641,11 @@ Use `/comfy:install <pack>` to install missing node packs from the registry. The
 
 ## Contributing
 
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feat/my-feature`)
-3. Make your changes and ensure `npm run lint` passes
-4. Submit a pull request
+Contributions are welcome! See **[CONTRIBUTING.md](./CONTRIBUTING.md)** for the dev setup, project
+conventions, how to add an MCP tool, and the release process.
+
+Quick version: fork → branch (`feat/my-feature`) → make changes (ensure `npm run build` and
+`npm test` pass; run `npm run docs:gen` if you touched tools) → open a PR.
 
 ---
 
@@ -658,6 +659,18 @@ MIT — see [LICENSE](./LICENSE) for details.
 
 The full, structured changelog lives in [CHANGELOG.md](./CHANGELOG.md). Recent highlights:
 
+### 0.8.0 — 2026-05-26
+
+**Lifecycle + I/O + discovery.**
+
+- **`apply_manifest`** — declarative env setup (pip / custom_nodes / models) from an inline or JSON/YAML manifest; idempotent.
+- **`verify_custom_node`** — restart + `/object_info` load-check that a scaffolded/installed pack's node types actually registered.
+- **`scaffold_custom_node`** — now also emits `.comfyignore`/`.gitignore` and (with `with_ci`) a GitHub publish workflow.
+- **`convert_image`** — re-encode outputs to PNG/JPEG/WebP via `sharp`.
+- **Cloud storage** — `s3://` / Azure-Blob model downloads + a new **`upload_output`** (S3/Azure/HTTP/HF).
+- **`comfy-researcher` agent** — problem → ranked custom-node recommendations; **`generate_node_skill`** is now cached (source@version).
+- **Security** — pip/argv-injection guards, realpath/symlink-safe path containment, cloud-credential + SAS/presigned redaction, redirect-SSRF hardening.
+
 ### 0.7.0 — 2026-05-25
 
 **Stability + authoring.**

package/ROADMAP.md

@@ -10,6 +10,21 @@ Comfy Registry.
 
 ---
 
+## Status — 2026-05-26
+
+- **Released:** `0.7.0` on npm — Theme E stability/hardening (E1–E4, E7, E2-auth), custom-node
+  authoring tools, experimental agent-panel backend, hosted docs.
+- **Complete (on main, unreleased → queued for `0.8.0`):** Theme E additive (E5 `apply_manifest`,
+  E6/E2b cloud storage, E8 `convert_image`), Theme C (C3 `verify_custom_node`, C5 scaffold CI),
+  Theme D (D1 `comfy-researcher` + skill cache). **Epics A, C, D, E are closed.**
+- **Pending release:** cut **`0.8.0`** for the unreleased surface above — `comfyui-mcp-yrp` (see beads).
+- **Blocked:** **Theme B** (embedded agent panel UI, B3–B6) is gated on the upstream
+  **`@comfyorg/extension-api`** package being published to npm (PRs #12142–#12145 still open). The
+  panel *backend* POC (B1/B2) already shipped. Tracked by a watch bead under Epic B; resume the
+  codex build loop on B once the package lands.
+
+---
+
 ## ✅ Shipped (0.6.x)
 - comfy-cli capability port (custom-node mgmt, snapshots, bisect, workflow deps, install/update,
   models, workspace/env, API nodes, manager config) — tools surface ~70+.

package/design/remote-and-cloud-modes.md

@@ -0,0 +1,113 @@
+# Design — Remote ComfyUI and Comfy Cloud modes
+
+**Status:** Draft, 2026-06-01
+**Beads:** `comfyui-mcp-m1p` (Comfy Cloud evaluation)
+**Sources surveyed:**
+- `picoSols/comfyui-cloud-mcp` — added Comfy Cloud (`cloud.comfy.org`) as a deployment target
+- `joaolvivas/comfyui-mcp-byjlucas` — HTTP-first refactor of file-bound tools for remote setups
+
+## Why this doc
+
+Today `comfyui-mcp` is **local-first**: many tools need `config.comfyuiPath` (process control, model removal, manifest, install, etc.) and the rest reach a "ComfyUI" identified by host:port. Two forks have independently pushed the project toward two related but distinct deployment shapes:
+
+1. **Remote ComfyUI** — user runs ComfyUI on a RunPod / server / VPS, reaches it via `--comfyui-url`. The HTTP API works; filesystem and process control do not. Today some of our "remote-friendly" tools still have local-filesystem fallbacks that hide failures.
+2. **Comfy Cloud** — `cloud.comfy.org` exposes a ComfyUI-shaped REST API (no WebSocket, no `/internal/logs`, no process control) authenticated with `X-API-Key`. Users in this mode don't have a "ComfyUI process" at all.
+
+We have a strategic decision to make: do we want to be the canonical MCP for **all three** (local, remote, cloud), or stay opinionated about local-first?
+
+## Survey: picoSols Comfy Cloud fork
+
+PR-equivalent: `picoSols/comfyui-cloud-mcp@7a812069` (feat: Comfy Cloud API support).
+
+### Architecture they shipped
+
+- Added `comfyuiApiKey` + `comfyuiCloudUrl` to `configSchema`. New env vars: `COMFYUI_API_KEY`, `COMFYUI_CLOUD_URL` (defaults to `https://cloud.comfy.org`).
+- `isCloudMode(): boolean` — returns `!!parsedConfig.comfyuiApiKey`. Acts as the dispatch switch.
+- In cloud mode, **skip local port auto-detection** entirely (no `detectComfyUIPort` call).
+- New file `src/comfyui/cloud-client.ts` (~346 LOC) — re-implements the surface area that `src/comfyui/client.ts` exposes (enqueue, history, system stats, queue, interrupt, view, object info, samplers/schedulers/checkpoints/loras/vaes/upscalers/logs) against `cloud.comfy.org` using `X-API-Key` headers and raw `fetch`.
+- `src/comfyui/client.ts` becomes a **dispatcher**:
+  - Functions that have a cloud equivalent get an `if (isCloudMode()) return cloudClient.fn(...)` prologue.
+  - Functions that fundamentally can't work in cloud mode (`getClient`, `connectClient`, `ensureConnected` — anything WebSocket-bound) call `requireLocalMode("op")` that throws `ComfyUIError("CLOUD_UNSUPPORTED")`.
+- `JobWatcher` gate: WebSocket attach is wrapped in `if (!isCloudMode())`. Cloud mode falls through to the existing HTTP-polling path that the local watcher already uses as a fallback.
+
+### What's missing / opinionated
+
+- No model-management tools touched. In cloud mode, models are pre-provisioned by Comfy-Org — `download_model`, `remove_model`, `list_local_models` should either be no-ops or surface a cloud-specific listing endpoint.
+- No `/internal/logs` equivalent in cloud — picoSols returns `[]`. Our `health_check` (just landed from João Lucas) would degrade gracefully there.
+- No process control coverage — the fork doesn't say what happens, but our `requireLocalMode` shim would correctly reject `start_comfyui`/`stop_comfyui`/`restart_comfyui`/`install_comfyui`/`apply_manifest`/etc.
+
+## Survey: João Lucas remote-HTTP refactor
+
+PR-equivalents:
+- `joaolvivas/comfyui-mcp-byjlucas@089180ad` — `upload_image` HTTP-only (removed deceptive filesystem fallback)
+- `joaolvivas/comfyui-mcp-byjlucas@e2ae39c8` — same pattern across `image-management.ts` + `model-resolver.ts`
+
+### The deceptive-fallback bug
+
+Current `src/tools/image-management.ts:104-119` (and `upload_video` / `upload_audio` mirrors at L:208–230):
+
+```ts
+try {
+  // HTTP first (works remote)
+  const result = await uploadImageAuto(...);
+  return success;
+} catch (httpErr) {
+  // Fallback: filesystem copy if COMFYUI_PATH is set
+  const result = await uploadImage(...);
+  return success;  // ← LIES when COMFYUI_PATH is auto-detected stale
+}
+```
+
+The auto-detection in `config.ts` happily resolves `~/ComfyUI` or `/opt/ComfyUI` even when the user is targeting a remote `--comfyui-url`. If HTTP fails (server down, wrong URL, network blip), the fallback writes the file into an **unrelated local install** and returns "success" — but the remote ComfyUI the agent will actually `enqueue` against never received the file. The next workflow run fails with "LoadImage: file not found" and the agent has no breadcrumb back to the upload step.
+
+João's fix: drop the fallback entirely. HTTP-only, fail loud. His tool description updates to "Works with both local and remote ComfyUI instances" (because the local HTTP endpoint of course also works).
+
+**Recommendation:** Pull this in, separately from cloud support, as a 0.8.1 fix. Affects three tools: `upload_image`, `upload_video`, `upload_audio`.
+
+### Other João changes in scope
+
+- `model-resolver.ts` (+37/-7) — likely makes model-existence checks remote-friendly (instead of `existsSync(localPath)`, ask ComfyUI via `/object_info` or `/models/{cat}`). Worth a closer read before deciding whether to port.
+- `client.ts` (+70/-1) — HTTP-first paths for things we currently do filesystem-first.
+- Partner-node auto-inject `api_key_comfy_org` (4b989e47) — comparison vs our existing `COMFY_API_KEY → extra_data` mechanism from 0.6.0. Likely duplicative.
+
+## Proposed direction
+
+### Three modes, three roles
+
+| Mode | How user opts in | Local FS? | Process control? | WebSocket? | Process tools should… |
+|---|---|---|---|---|---|
+| **Local** | `COMFYUI_PATH` set or auto-detected | yes | yes | yes | work |
+| **Remote** | `--comfyui-url` and no FS path (or FS path explicitly cleared) | no | no | yes | throw "remote-only target" |
+| **Cloud** | `COMFYUI_API_KEY` set | no | no | no | throw "cloud-only target" |
+
+Today we conflate "local" and "remote" because auto-detection silently fills in a local `COMFYUI_PATH` that may not match the `--comfyui-url` target. That's the root cause of João's deceptive-fallback bug.
+
+### Phased adoption
+
+**Phase 1 — Pull the bug fixes (no architecture change).** [0.8.1 patch]
+- João's `upload_image`/`upload_video`/`upload_audio` HTTP-only fix.
+- Read `model-resolver.ts` diff and decide on remote-aware model checks.
+- Credit @joaolvivas in CHANGELOG.
+
+**Phase 2 — Explicit remote mode.** [0.9.0]
+- Add a `--remote-only` / `COMFYUI_REMOTE_ONLY=true` flag that suppresses `COMFYUI_PATH` auto-detection.
+- All local-only tools (process control, install, manifest, model removal, model download cache materialization) check `config.comfyuiPath` and throw a clear `ProcessControlError("remote target — tool requires a local install path")` instead of silently degrading.
+- Document the three modes explicitly in `docs/configuration.mdx`.
+
+**Phase 3 — Comfy Cloud first-class.** [0.9.0 stretch or 0.10.0]
+- Adopt picoSols's `isCloudMode()` + `cloud-client.ts` shape.
+- Build the feature-parity matrix (which tools work in cloud? which throw?).
+- Decide cloud-model-listing API (does `cloud.comfy.org` expose pre-provisioned model lists? if yes, wire `list_local_models` to it).
+- Consider reaching out to Comfy-Org about a partnership listing.
+- Credit @picoSols in CHANGELOG; consider co-authorship in commits.
+
+### Open questions for the maintainer
+
+1. Do we want to commit to cloud support? Strategic: it makes `comfyui-mcp` the right MCP for anyone using Comfy Cloud, which broadens the audience but also makes us a partner-of-record. If yes, an outreach to Comfy-Org alongside the implementation feels right.
+2. For Phase 2's explicit remote mode — do we silently fix the auto-detection (don't fill in `COMFYUI_PATH` if `--comfyui-url` is a non-loopback host) or require users to opt in?
+3. For the `upload_*` fix: ship as 0.8.1 patch alongside the search/health fixes from `df8050e`, or wait for the bigger 0.9.0 mode rework?
+
+## Attribution
+
+- **Comfy Cloud architecture, dispatch pattern, cloud-client.ts shape:** [@picoSols](https://github.com/picoSols) — `picoSols/comfyui-cloud-mcp@7a812069` (2026-03-25).
+- **HTTP-first refactor + deceptive-fallback diagnosis:** [@joaolvivas](https://github.com/joaolvivas) — `joaolvivas/comfyui-mcp-byjlucas@089180ad` and `@e2ae39c8` (2026-05-12).

package/dist/services/download-auth.d.ts

@@ -13,6 +13,13 @@ export type DownloadAuth = {
     type: "query";
     query_param: string;
     query_value: string;
+} | {
+    type: "s3";
+    access_key_id: string;
+    secret_access_key: string;
+    session_token?: string;
+    region?: string;
+    endpoint?: string;
 };
 export interface DownloadRequestAuth {
     url: string;

package/dist/services/download-auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"download-auth.d.ts","sourceRoot":"","sources":["../../src/services/download-auth.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAyCD,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,oBAAoB,GAAE,MAAM,EAAO,GAClC,MAAM,CAaR;AAED,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,YAAY,GAClB,mBAAmB,CAgCrB"}
+{"version":3,"file":"download-auth.d.ts","sourceRoot":"","sources":["../../src/services/download-auth.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC3D;IACE,IAAI,EAAE,IAAI,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEN,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAyDD,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,oBAAoB,GAAE,MAAM,EAAO,GAClC,MAAM,CAcR;AAED,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,YAAY,GAClB,mBAAmB,CAuCrB"}

package/dist/services/download-auth.js

@@ -3,6 +3,8 @@ const TOKEN_QUERY_RE = /token|key|secret|signature|auth|password|credential/i;
 const REDACTED = "[REDACTED]";
 const HEADER_NAME_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 const ASCII_CONTROL_RE = /[\x00-\x1F\x7F]/;
+const AZURE_BLOB_HOST_SUFFIX = ".blob.core.windows.net";
+const AWS_PRESIGNED_QUERY_RE = /^x-amz-/i;
 function rejectControlChars(label, value) {
     if (ASCII_CONTROL_RE.test(value)) {
         throw new ValidationError(`${label} cannot contain ASCII control characters.`);
@@ -25,17 +27,34 @@ function validateDownloadAuth(auth) {
         rejectControlChars("Header auth header_value", auth.header_value);
         return;
     }
+    if (auth.type === "s3") {
+        rejectControlChars("S3 access_key_id", auth.access_key_id);
+        rejectControlChars("S3 secret_access_key", auth.secret_access_key);
+        if (auth.session_token)
+            rejectControlChars("S3 session_token", auth.session_token);
+        if (auth.region)
+            rejectControlChars("S3 region", auth.region);
+        if (auth.endpoint)
+            rejectControlChars("S3 endpoint", auth.endpoint);
+        return;
+    }
     if (auth.query_param.length === 0) {
         throw new ValidationError("Query auth query_param must be a non-empty string.");
     }
     rejectControlChars("Query auth query_param", auth.query_param);
 }
+function shouldRedactAllQueryValues(parsed) {
+    if (parsed.hostname.endsWith(AZURE_BLOB_HOST_SUFFIX))
+        return true;
+    return [...parsed.searchParams.keys()].some((key) => AWS_PRESIGNED_QUERY_RE.test(key));
+}
 export function redactUrlForLogs(url, extraSensitiveParams = []) {
     try {
         const parsed = new URL(url);
+        const redactAll = shouldRedactAllQueryValues(parsed);
         const sensitive = new Set(extraSensitiveParams.map((p) => p.toLowerCase()));
         for (const key of [...parsed.searchParams.keys()]) {
-            if (sensitive.has(key.toLowerCase()) || TOKEN_QUERY_RE.test(key)) {
+            if (redactAll || sensitive.has(key.toLowerCase()) || TOKEN_QUERY_RE.test(key)) {
                 parsed.searchParams.set(key, REDACTED);
             }
         }
@@ -68,6 +87,12 @@ export function applyDownloadAuth(url, auth) {
             headers: { [auth.header_name]: auth.header_value },
         };
     }
+    if (auth.type === "s3") {
+        return {
+            url,
+            headers: {},
+        };
+    }
     const parsed = new URL(url);
     parsed.searchParams.set(auth.query_param, auth.query_value);
     return {

package/dist/services/download-auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"download-auth.js","sourceRoot":"","sources":["../../src/services/download-auth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"download-auth.js","sourceRoot":"","sources":["../../src/services/download-auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAqBrD,MAAM,cAAc,GAAG,sDAAsD,CAAC;AAC9E,MAAM,QAAQ,GAAG,YAAY,CAAC;AAC9B,MAAM,cAAc,GAAG,gCAAgC,CAAC;AACxD,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;AAC3C,MAAM,sBAAsB,GAAG,wBAAwB,CAAC;AACxD,MAAM,sBAAsB,GAAG,UAAU,CAAC;AAE1C,SAAS,kBAAkB,CAAC,KAAa,EAAE,KAAa;IACtD,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,eAAe,CAAC,GAAG,KAAK,2CAA2C,CAAC,CAAC;IACjF,CAAC;AACH,CAAC;AAED,SAAS,oBAAoB,CAAC,IAAkB;IAC9C,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC3B,kBAAkB,CAAC,cAAc,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QAC/C,OAAO;IACT,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC1B,kBAAkB,CAAC,qBAAqB,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzD,kBAAkB,CAAC,qBAAqB,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzD,OAAO;IACT,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC3B,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,eAAe,CACvB,4DAA4D,CAC7D,CAAC;QACJ,CAAC;QACD,kBAAkB,CAAC,0BAA0B,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QAClE,OAAO;IACT,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QACvB,kBAAkB,CAAC,kBAAkB,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;QAC3D,kBAAkB,CAAC,sBAAsB,EAAE,IAAI,CAAC,iBAAiB,CAAC,CAAC;QACnE,IAAI,IAAI,CAAC,aAAa;YAAE,kBAAkB,CAAC,kBAAkB,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;QACnF,IAAI,IAAI,CAAC,MAAM;YAAE,kBAAkB,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAC9D,IAAI,IAAI,CAAC,QAAQ;YAAE,kBAAkB,CAAC,aAAa,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QACpE,OAAO;IACT,CAAC;IAED,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,eAAe,CAAC,oDAAoD,CAAC,CAAC;IAClF,CAAC;IACD,kBAAkB,CAAC,wBAAwB,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;AACjE,CAAC;AAED,SAAS,0BAA0B,CAAC,MAAW;IAC7C,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,sBAAsB,CAAC;QAAE,OAAO,IAAI,CAAC;IAClE,OAAO,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACzF,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,GAAW,EACX,uBAAiC,EAAE;IAEnC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,MAAM,SAAS,GAAG,0BAA0B,CAAC,MAAM,CAAC,CAAC;QACrD,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;QAC5E,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YAClD,IAAI,SAAS,IAAI,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC9E,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;YACzC,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAC;IACb,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,GAAW,EACX,IAAmB;IAEnB,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACvC,oBAAoB,CAAC,IAAI,CAAC,CAAC;IAE3B,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC3B,OAAO;YACL,GAAG;YACH,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,IAAI,CAAC,KAAK,EAAE,EAAE;SACnD,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACpF,OAAO;YACL,GAAG;YACH,OAAO,EAAE,EAAE,aAAa,EAAE,SAAS,OAAO,EAAE,EAAE;SAC/C,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC3B,OAAO;YACL,GAAG;YACH,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE;SACnD,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QACvB,OAAO;YACL,GAAG;YACH,OAAO,EAAE,EAAE;SACZ,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IAC5D,OAAO;QACL,GAAG,EAAE,MAAM,CAAC,QAAQ,EAAE;QACtB,OAAO,EAAE,EAAE;KACZ,CAAC;AACJ,CAAC"}

package/dist/services/download-cache.d.ts

@@ -1,4 +1,5 @@
 import { copyFile, link, mkdir, readdir, rename, rm, stat, utimes } from "node:fs/promises";
+import { type CloudStorageAuth } from "./storage/index.js";
 export declare const downloadCacheFs: {
     copyFile: typeof copyFile;
     link: typeof link;
@@ -14,6 +15,7 @@ export interface DownloadCacheOptions {
     headers: Record<string, string>;
     targetPath: string;
     logUrl?: string;
+    storageAuth?: CloudStorageAuth;
 }
 export interface DownloadCacheResult {
     targetPath: string;
@@ -21,6 +23,6 @@ export interface DownloadCacheResult {
     cachePath?: string;
     materializedBy?: "hardlink" | "copy";
 }
-export declare function downloadUrlToFile(url: string, targetPath: string, headers: Record<string, string>, logUrl?: string): Promise<void>;
+export declare function downloadUrlToFile(url: string, targetPath: string, headers: Record<string, string>, logUrl?: string, storageAuth?: CloudStorageAuth): Promise<void>;
 export declare function downloadWithCache(options: DownloadCacheOptions): Promise<DownloadCacheResult>;
 //# sourceMappingURL=download-cache.d.ts.map

package/dist/services/download-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"download-cache.d.ts","sourceRoot":"","sources":["../../src/services/download-cache.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,OAAO,EACP,MAAM,EACN,EAAE,EACF,IAAI,EACJ,MAAM,EACP,MAAM,kBAAkB,CAAC;AAa1B,eAAO,MAAM,eAAe;;;;;;;;;CAS3B,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;CACtC;AA+ID,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAqB9B"}
+{"version":3,"file":"download-cache.d.ts","sourceRoot":"","sources":["../../src/services/download-cache.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,OAAO,EACP,MAAM,EACN,EAAE,EACF,IAAI,EACJ,MAAM,EACP,MAAM,kBAAkB,CAAC;AAQ1B,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAC;AAO5B,eAAO,MAAM,eAAe;;;;;;;;;CAS3B,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,gBAAgB,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;CACtC;AAoLD,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,MAAM,CAAC,EAAE,MAAM,EACf,WAAW,GAAE,gBAAqB,GACjC,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAgC9B"}

package/dist/services/download-cache.js

@@ -8,8 +8,10 @@ import { pipeline } from "node:stream/promises";
 import { ModelError } from "../utils/errors.js";
 import { logger } from "../utils/logger.js";
 import { redactUrlForLogs } from "./download-auth.js";
+import { downloadCloudUrlToFile, supportsCloudDownload, } from "./storage/index.js";
 const DEFAULT_CACHE_DIR = join(homedir(), ".comfyui-mcp", "cache");
 const HASH_CHARS = 32;
+const MAX_HTTP_REDIRECTS = 5;
 const inflight = new Map();
 export const downloadCacheFs = {
     copyFile,
@@ -46,10 +48,44 @@ async function touch(path) {
     const now = new Date();
     await downloadCacheFs.utimes(path, now, now);
 }
-async function streamUrlToFile(url, targetPath, headers, logUrl = redactUrlForLogs(url)) {
-    const res = await fetch(url, { headers });
+async function streamUrlToFile(url, targetPath, headers, logUrl = redactUrlForLogs(url), storageAuth = {}) {
+    if (supportsCloudDownload(url)) {
+        await downloadCloudUrlToFile(url, targetPath, storageAuth);
+        return;
+    }
+    let currentUrl = url;
+    let currentHeaders = headers;
+    let res;
+    for (let redirectCount = 0;; redirectCount += 1) {
+        res = await fetch(currentUrl, { headers: currentHeaders, redirect: "manual" });
+        if (res.status < 300 || res.status >= 400)
+            break;
+        if (redirectCount >= MAX_HTTP_REDIRECTS) {
+            throw new ModelError("Download redirect limit exceeded", {
+                url: redactUrlForLogs(currentUrl),
+                status: res.status,
+            });
+        }
+        const location = res.headers.get("location");
+        if (!location)
+            break;
+        let nextUrl;
+        try {
+            nextUrl = new URL(location, currentUrl).toString();
+        }
+        catch {
+            throw new ModelError("Download redirect location is invalid", {
+                url: redactUrlForLogs(currentUrl),
+                status: res.status,
+            });
+        }
+        const sameOrigin = new URL(nextUrl).origin === new URL(currentUrl).origin;
+        currentUrl = nextUrl;
+        if (!sameOrigin)
+            currentHeaders = {};
+    }
     if (!res.ok) {
-        throw new ModelError(`Download failed: ${res.status} ${res.statusText}`, { url: logUrl, status: res.status });
+        throw new ModelError(`Download failed: ${res.status} ${res.statusText}`, { url: currentUrl === url ? logUrl : redactUrlForLogs(currentUrl), status: res.status });
     }
     if (!res.body) {
         throw new ModelError("Download response has no body", { url: logUrl });
@@ -58,7 +94,7 @@ async function streamUrlToFile(url, targetPath, headers, logUrl = redactUrlForLo
     const fileStream = createWriteStream(targetPath);
     await pipeline(nodeStream, fileStream);
 }
-async function downloadIntoCache(url, headers, logUrl) {
+async function downloadIntoCache(url, headers, logUrl, storageAuth = {}) {
     const target = cachePathForUrl(url);
     const key = target;
     const existing = inflight.get(key);
@@ -78,7 +114,7 @@ async function downloadIntoCache(url, headers, logUrl) {
         }
         const tmp = join(cacheDir(), `.${basename(target)}.${process.pid}.${randomUUID()}.tmp`);
         try {
-            await streamUrlToFile(url, tmp, headers, logUrl);
+            await streamUrlToFile(url, tmp, headers, logUrl, storageAuth);
             await downloadCacheFs.rename(tmp, target);
             await touch(target);
             return target;
@@ -137,13 +173,13 @@ async function evictLruIfNeeded() {
             break;
     }
 }
-export async function downloadUrlToFile(url, targetPath, headers, logUrl) {
-    await streamUrlToFile(url, targetPath, headers, logUrl);
+export async function downloadUrlToFile(url, targetPath, headers, logUrl, storageAuth = {}) {
+    await streamUrlToFile(url, targetPath, headers, logUrl, storageAuth);
 }
 export async function downloadWithCache(options) {
     const logUrl = options.logUrl ?? redactUrlForLogs(options.url);
     try {
-        const cachePath = await downloadIntoCache(options.url, options.headers, logUrl);
+        const cachePath = await downloadIntoCache(options.url, options.headers, logUrl, options.storageAuth);
         const materializedBy = await materializeCacheFile(cachePath, options.targetPath);
         await evictLruIfNeeded();
         return {
@@ -160,7 +196,7 @@ export async function downloadWithCache(options) {
             url: logUrl,
             error: err instanceof Error ? err.message : String(err),
         });
-        await downloadUrlToFile(options.url, options.targetPath, options.headers, logUrl);
+        await downloadUrlToFile(options.url, options.targetPath, options.headers, logUrl, options.storageAuth);
         return { targetPath: options.targetPath, usedCache: false };
     }
 }