Kubo Windows Redirect DNS Reproducer

This repository contains a minimal Node.js project that reproduces a Windows-specific DNS failure triggered by Kubo's gateway redirect logic.

Background

When a client requests a path-based IPNS resource (for example http://localhost:18080/ipns/<peer-id>), Kubo redirects the request to the subdomain form (http://<peer-id>.ipns.localhost:18080/). On Linux, any *.localhost hostname resolves to the loopback interface, so the redirect completes successfully. Windows only recognises the literal localhost hostname, causing the redirected lookup to fail with getaddrinfo ENOTFOUND.

CI jobs that hit a local Kubo gateway with fetch() (or any HTTP client that follows redirects) therefore fail immediately on Windows because DNS resolution fails before Kubo can return a response.

Disabling subdomain redirects for loopback hosts via the Kubo configuration

Gateway.PublicGateways.{localhost,127.0.0.1,[::1]}.UseSubdomains = false

keeps the gateway in path mode and sidesteps the issue. This reproducer captures the failure that happens without that override.

Prerequisites

• Windows (the bug only manifests there; other platforms will display a warning)
• Node.js 18 or newer (for native fetch and fs.rm support)

The project downloads [email protected] from npm, which provides the platform specific Kubo binary during installation. It also installs kubo-rpc-client to drive the HTTP API when preparing the IPNS record.

Setup

npm install

On Windows, installation will download the corresponding ipfs binary automatically via the kubo package's post-install hook.

Reproducing the Failure

Run the scripted repro:

npm run repro:windows

The script performs the following steps:

1. Creates an isolated temporary IPFS repository (IPFS_PATH).
2. Verifies that the chosen swarm/API/gateway ports are free on 127.0.0.1.
3. Initialises the repository and binds the API to 127.0.0.1:55101, the gateway to 127.0.0.1:48180, and the swarm listener to 127.0.0.1:46105.
4. Starts the Kubo daemon in offline mode.
5. Uses kubo-rpc-client to add a small file, generate an Ed25519 key, and publish an IPNS record with allowOffline: true.
6. Requests http://localhost:48180/ipns/<generated-key> using Node's native fetch implementation.

On Windows the fetch call follows Kubo's redirect to http://<generated-key>.ipns.localhost:18080/ and immediately fails with TypeError: fetch failed whose underlying cause is getaddrinfo ENOTFOUND. The script recognises this as the expected failure mode and reports success.

To demonstrate the workaround, update the Kubo configuration before launching the daemon:

ipfs config --json Gateway.PublicGateways '{ "localhost": {"UseSubdomains": false}, "127.0.0.1": {"UseSubdomains": false}, "[::1]": {"UseSubdomains": false} }'

With subdomain redirects disabled for loopback hosts, rerunning the script will result in a standard HTTP response rather than a DNS error.

Curl-Based Variant

If you prefer exercising the same workflow via curl, run:

npm run repro:windows:curl

The bash script mirrors the Node.js reproducer but performs the gateway probes with curl --location, which surfaces Windows DNS failures as curl: (6) Could not resolve host: *.ip(f|n)s.localhost.

Note: When run from Git Bash, /ip4/... multiaddresses may be rewritten into Windows-style paths. The script automatically sets MSYS_NO_PATHCONV=1 and MSYS2_ARG_CONV_EXCL='*' to avoid that conversion.

Expected Output

A successful reproduction ends with log lines similar to:

✅ Successfully reproduced the redirect-induced DNS failure.
   fetch() followed the gateway redirect to http://k51...ipns.localhost:48180/ and Windows DNS
   could not resolve the subdomain form of localhost.

Any other outcome is treated as an unexpected failure and the script exits with a non-zero status code.