ipfs/kubo v0.43.0

on GitHub

• Overview
• 🔦 Highlights
  • 🔗 Native ipfs:// and ipns:// URIs work as input
  • 🛜 One-time notice when behind CGNAT
  • 🩺 AutoTLS checks broker health before registration
  • 🕒 Revamped TTL and expiration handling for IPNS and DNSLink
  • 🛑 Clearer errors for invalid config at startup
  • 🗂️ ipfs files no longer hangs when garbage collection runs
  • 🔑 ipfs config replace keeps PeerID and private key in sync
  • 🔐 secp256k1 key generation, export, and import
  • 🔄 Sturdier DHT reprovides on large nodes
  • 📡 Future-proofing browser retrieval: webrtc-direct v2
  • 🌐 Future-proofing browser retrieval: WebTransport draft-15
  • 🧭 Delegated routers now hand browsers an address they can dial
  • 🗺️ Fewer stale addresses in the peerstore
  • 🕳️ Behind NAT: faster relay recovery, dependable shutdown
  • 🚮 ipfs init no longer creates an IPNS record
  • 📛 Unified IPNS record storage
  • 🧪 Tests use new go-test and rand v2
  • 🖥️ WebUI Improvements
  • 🧵 A truncated CAR response now says so
  • 🔒 Security fixes: update recommended
  • 📦️ Dependency updates
• 📝 Changelog
• 👨‍👩‍👧‍👦 Contributors

Overview

🔦 Highlights

🔗 Native ipfs:// and ipns:// URIs work as input

Commands that take a path or CID now also accept native IPFS URIs: ipfs://<cid>, ipns://<name>, and the shorter ipfs:<cid> and ipns:<name> forms. ipfs cat ipfs://<cid> now behaves the same as ipfs cat /ipfs/<cid> or ipfs cat <cid>.

ipfs:// and ipns:// are how web browsers, browser extensions, and many non-IPFS apps link to and share IPFS content. Before, you had to rewrite such an address into an /ipfs/ path before Kubo would take it. Now you can copy a URI from a browser address bar and paste it straight into the CLI or the RPC API.

This works wherever a path or CID is accepted, including cat, get, ls, refs, dag, block, pin, files, and name resolve. The scheme is case-insensitive, and the CID or name after it is left untouched.

🛜 One-time notice when behind CGNAT

Kubo now logs a one-time notice to stderr at startup when it detects it is behind carrier-grade NAT (CGNAT) or double NAT. CGNAT is common on IPv4-scarce ISPs that share one public address across many subscribers: other peers cannot reach the node directly, and a busy node can fill the shared NAT session table and disrupt internet access for every device on the local network. The notice gives that otherwise hard-to-diagnose "my whole home network drops" symptom a clear cause.

Detection is best-effort and conservative: it fires only when a private or shared-range (100.64.0.0/10, RFC 6598) address appears as a NAT-mapped WAN address (via UPnP/NAT-PMP/PCP) that is not one of the node's own interfaces. Kubo ignores addresses on a local interface, so VPN and overlay tools that use 100.64.0.0/10 (such as Tailscale) do not trigger it; when the upstream address is hidden, the node looks like any ordinary NAT and Kubo stays quiet. ipfs swarm addrs autonat reports the current classification in its nat field (--enc=json).

Silence the notice with Internal.CGNATCheck=false. The dead-listener diagnostic added in v0.42 can now be toggled too, with Internal.DeadListenerCheck.

🩺 AutoTLS checks broker health before registration

AutoTLS certificate issuance depends on the ACME DNS-01 broker at AutoTLS.RegistrationEndpoint (registration.libp2p.direct by default). Before, a publicly reachable node without a certificate would attempt ACME issuance even when that broker was unreachable (offline network, firewall, service outage) and keep retrying in the background for days, filling logs with errors that could not resolve themselves.

Now the broker's health endpoint is checked right before the first registration attempt, after the registration delay (1h by default, none when AutoTLS.Enabled=true is set explicitly) and once the node is publicly reachable. While the broker keeps failing the check, certificate setup is postponed with a single ERROR in the log and one cheap re-check per hour, and issuance starts automatically once the broker recovers. Nodes that already have a certificate are unaffected, and short-lived nodes (such as CI runners) produce no broker traffic at all.

🕒 Revamped TTL and expiration handling for IPNS and DNSLink

A record's own lifetime and TTL now govern both how Kubo creates it and how long clients may cache it, and a cache never outlives the record's validity. This applies when ipfs name publish creates an IPNS record, and when the gateway serves IPNS and DNSLink responses.

At publish time, ipfs name publish sanitizes its duration flags before creating an IPNS record, instead of emitting one that fails verification later:

• --lifetime must be greater than zero; a non-positive value would expire the record immediately.
• --ttl must be non-negative. An explicit --ttl greater than --lifetime is rejected; an omitted --ttl is capped to --lifetime, since a record is not cached past its validity.

On the serving side, the gateway derives a client's cache lifetime from the record itself:

• DNSLink websites (/ipns/<dnslink-host>) set Cache-Control: max-age from the DNS TXT record's own TTL, so a browser or CDN caches the site for as long as its DNS record allows and re-fetches once that expires, instead of following a fixed default that cached short-lived records too long and long-lived ones too briefly. This needs a resolver that reports TTLs: Go's built-in OS resolver does not, so point DNS.Resolvers at a DNS-over-HTTPS endpoint (a . entry covers every domain) to turn it on. Without one, DNSLink caching is unchanged. When a name resolves through several hops (a DNSLink pointing at an IPNS name, or a chain of them), the shortest TTL along the way wins.
• IPNS records cap their Cache-Control: max-age to the time left before the record expires (its EOL), so a cache cannot serve a record past the point it stops being valid. An already-expired record, or one whose expiration is unknown, returns no-store, and a malformed record's negative TTL is floored at zero instead of surfacing as a negative max-age. This covers both gateway IPNS responses and /routing/v1/ipns when the delegated routing server is enabled (boxo#1166).
• Revalidation with If-None-Match or If-Modified-Since now returns Etag and Cache-Control on the 304 Not Modified response, matching what the 200 would send. A bare 304 used to leave the client's stored copy expired, forcing a fresh revalidation on every later request even when the content had not changed (boxo#1188).

For resolved names, a cache hit reports the time remaining on the cache entry rather than the record's original TTL, so a late hit near expiry no longer restarts the full caching window on the client. Ipns.MaxCacheTTL still caps the reported value.

🛑 Clearer errors for invalid config at startup

When startup config is invalid, Kubo now stops with an error that names the problem instead of exiting abruptly. One case is an unsupported hole-punching setup: Swarm.EnableHolePunching set to true while Swarm.RelayClient.Enabled is false. Hole punching needs the relay client to coordinate the upgrade from a relayed to a direct connection, so the error now names both settings.

The same path also covers deprecated Provider and Reprovider settings, removed providing options, delegated routing with providing enabled, private-network auto routing, and the removed IPFS_REUSEPORT environment variable.

🗂️ ipfs files no longer hangs when garbage collection runs

Running ipfs repo gc at the same time as MFS writes could get the whole MFS (Mutable File System) stuck: every later ipfs files command would hang, the damage could persist across restarts, and the daemon had to be force-killed to recover. It mostly hit busy nodes that write to MFS from several processes at once and run GC often.

The cause was garbage collection deleting blocks that an in-progress write had just added but had not yet linked into the saved MFS root, leaving the tree pointing at data that no longer existed. Kubo now takes the same lock ipfs add uses around every MFS change (from ipfs files, ipfs add --to-files, and the FUSE /mfs and /ipns mounts) and reads the MFS root while that lock is held, so GC can no longer collect data a live write still needs. As with ipfs add, a garbage collection run and in-flight MFS writes now briefly hold each other off; under GC-heavy load a single write can pause for the length of a GC and, with a short client timeout, look like it timed out and then succeed on retry.

MFS also stops hanging when a block it needs is missing or unreachable, whether from a repo damaged by an older Kubo, a manual ipfs block rm, a crash, or lazily-referenced content whose providers have gone away. Before, the first operation to reach that block would wait forever, freezing the whole MFS and blocking a clean shutdown. Now such an operation ends with an error instead: a lookup that stalls gives up on its own after a timeout, and ipfs files read and ipfs files write respect --timeout, so a stuck read or write returns and the daemon stays responsive. Content lazily referenced with ipfs files cp /ipfs/<cid> still loads from the network as before.

Thanks to Rinse12 from the bitsocial.net community for stress-testing MFS and surfacing the mechanics with clear reproduction steps.

🔑 ipfs config replace keeps PeerID and private key in sync

ipfs config replace now re-derives Identity.PeerID from the node's existing private key, which cannot be set over the Kubo RPC API. You can now roll one shared config out across a fleet: replace it onto every node, and each keeps its own identity even when the file carries another node's PeerID. To change a node's identity deliberately, stop the daemon and run ipfs key rotate.

🔐 secp256k1 key generation, export, and import

Kubo can now generate secp256k1 keys and move them in and out as PEM files. Until now ipfs key gen --type=secp256k1 failed with unrecognized key type, and secp256k1 keys could not be exported to PEM: the PEM PKCS #8 support went through Go's crypto/x509, which does not know the secp256k1 curve.

ipfs key gen, ipfs key rotate, and ipfs init all accept --type=secp256k1 (-a secp256k1 for ipfs init). ipfs key export --format=pem-pkcs8-cleartext and ipfs key import handle secp256k1 like the other key types, so keys move between Kubo and tools such as OpenSSL in both directions:

$ openssl ecparam -name secp256k1 -genkey -noout | openssl pkcs8 -topk8 -nocrypt > secp.pem
$ ipfs key import mykey --format=pem-pkcs8-cleartext secp.pem

ed25519 and secp256k1 keys are always 256 bits, so --size (--bits for ipfs init) is accepted only when it is 256 and rejected otherwise.

🔄 Sturdier DHT reprovides on large nodes

go-libp2p-kad-dht v0.41.0 lowers peak memory during reprovides on nodes that announce many CIDs, so low-memory consumer devices are less likely to be out-of-memory killed. More in kad-dht#1259.

📡 Future-proofing browser retrieval: webrtc-direct v2

/webrtc-direct and /quic-v1/webtransport, both on by default, are the two transports that let a web browser fetch content straight from your node: no gateway in the middle, no signalling server, no CA-issued certificate. Browsers are moving underneath both. Chrome and Firefox have breaking changes in flight, and Safari requires a setting servers were not sending. The go-libp2p v0.49.0 in this release keeps your node ready for browsers on both sides of those changes, with nothing to configure.

For webrtc-direct, Chrome has already merged the removal of the SDP-rewriting behavior the original (v1) handshake relies on, gated for now behind the WebRTC-NoSdpMangleUfrag field trial. Once that reaches stable, Chrome can no longer dial a v1-only server. Kubo now also accepts the replacement (v2) handshake on the same port, so your node is ready before browsers switch, and old clients keep working. More in go-libp2p#3520, and libp2p/specs#672 tracks progress across the other libp2p implementations.

Two more webrtc-direct fixes ship in the same bump:

• Your node's /certhash address now survives restarts. It used to change on every start (the certificate behind it was minted at random each time), so every cached copy of your address in other peers' address books and in DHT records kept going stale. The certificate is now derived from your node's identity key: the certhash changes one final time when you upgrade, then stays put for as long as you keep the same key. More in go-libp2p#3512.
• On a node AutoNAT had confirmed publicly reachable, /webrtc-direct silently went missing from the confirmed-address list, a side effect of sharing UDP port 4001 with /quic-v1 in the default config. ipfs swarm addrs autonat did not report it. On nodes configured to publish provider records to a delegated HTTP router, the records went out without the /webrtc-direct address, so a browser that discovered your node that way could not dial it over this transport. Regular DHT announcements were unaffected. Fixed in go-libp2p#3526, and confirmed addresses also stop periodically flapping back to unknown (go-libp2p#3528).

🌐 Future-proofing browser retrieval: WebTransport draft-15

WebTransport is the other transport a browser can use to dial your node directly. It is still an IETF draft, and browsers implement different draft versions. The /quic-v1/webtransport listener now answers them all:

• draft-15 renamed the two values that identify a WebTransport session on the wire. Every shipping browser still sends the old names, but Firefox is already implementing the new ones, and a server that only knows the old pair would stop answering Firefox the day that ships. Your node now answers to both.
• Safari (26.4 and later) does not complete the WebTransport handshake unless the server sends the WT_MAX_SESSIONS session limit from an earlier draft. Your node now sends it, so Safari can open sessions it previously could not.

Nothing to do today. More in go-libp2p#3532. The same update closes a memory-exhaustion hole in the WebTransport server, covered in Security fixes below.

One regression, and it is go-to-go only: when dialing out over WebTransport, Kubo now speaks only draft-15, so it can no longer dial peers running older go-libp2p over this transport. Those peers can still dial your node, and go-to-go connections prefer plain /quic-v1 on the same UDP port anyway. WebTransport is there for browsers, and browsers are unaffected.

🧭 Delegated routers now hand browsers an address they can dial

This one is for nodes that send provider records to an HTTP router, which today means Routing.Type=custom with a provide entry in Routing.Methods. The default auto provides over the DHT alone and is unaffected.

Those records now carry every address the node announces, including the AutoTLS /tls/ws and webrtc-direct ones. The DHT already published those two; the HTTP path dropped them. Loopback and LAN addresses stay out of the record whenever the node has a public one.

Before, a publicly reachable node with AutoTLS or webrtc-direct enabled published records listing only tcp, quic-v1, and webtransport. No browser can dial any of those. ipfs id still showed the missing addresses and the node was still listening on them, so everything looked healthy while browsers that found the node through a delegated router had nothing to connect with.

That gap broke browser-first apps. Bitsocial runs libp2p in the browser, uses delegated routers only to find peers, and fetches posts straight from those peers. A record without /tls/ws or webrtc-direct is a record its readers cannot use, no matter how reachable the node behind it is. See #11369.

🗺️ Fewer stale addresses in the peerstore

Your node remembers addresses for peers it hears about, and dead ones pile up and waste dial attempts. Two fixes trim them:

• When a peer announces a newer signed address list, it now replaces the stored one instead of merging into it. Addresses in use by a live connection are kept. More in go-libp2p#3487.
• Kubo no longer puts empty addresses into the signed records it announces about itself, which other implementations error out on. More in go-libp2p#3494.

The new Internal.NonPublicAddrPublishing flag controls whether your node publishes addresses the wider internet cannot reach, such as private, CGNAT, and loopback ranges. Set it to false to keep them out of the signed peer record and the DHT, or true to publish them, which is what a LAN-only node wants. Leave it unset to follow go-libp2p's defaults, which are known to change.

🕳️ Behind NAT: faster relay recovery, dependable shutdown

A node behind NAT depends on circuit relays to stay reachable and to hole punch direct connections. When such a node lost its relay (a relay restart, a dropped connection), it put that same known-good relay on a penalty list for up to an hour before trying it again, and could sit without a relayed address, invisible to inbound peers, for that long. Only failed attempts to reserve a slot count against a relay now, so your node reconnects to a lost relay right away. More in go-libp2p#3482.

Two rare shutdown races in the same machinery are fixed as well: hole punching discovering the node's first public address at the moment of shutdown could leave ipfs daemon hanging on exit until force-killed (go-libp2p#3504), and stopping the daemon mid-reachability-check could crash it (go-libp2p#3528).

🚮 ipfs init no longer creates an IPNS record

Since the earliest days, ipfs init published an IPNS record for the node's own key pointing at an empty directory. The record was effectively invisible (the DHT discarded records stored without a receive timestamp), so resolving an unpublished name failed as expected. With this release's unified record storage the record would have become visible to the network, making every fresh node's name resolve to an empty directory instead of failing until the first real ipfs name publish. The publish is removed; ipfs init still pins the empty directory. Resolving a never-published name now consistently returns an error.

📛 Unified IPNS record storage

Offline resolution (offline nodes, --offline commands, and Gateway.NoFetch gateways) and the DHT now share one value store, under a dedicated /dht prefix in the repo datastore (/dht/pk/..., /dht/ipns/...). So a name resolves the same whether your node is reachable or not: publish online and it still resolves offline; publish offline and peers get it once you reconnect.

How long a record lives depends on whether a DHT is running. A running DHT drops value records not refreshed within 48h (amino.DefaultMaxRecordAge); your own survive because the republisher re-announces them every Ipns.RepublishPeriod (4h default). An offline node runs no DHT, so nothing sweeps the store and records last until their IPNS EOL, as offline resolution always has.

On first daemon start after upgrading, Kubo clears the old root-level records (pre-v0.42 layout) once in the background; they return in the new layout as they are republished. Provider records keep their /providers/... prefix, untouched.

The cleanup runs in the background and does not block startup, but it has to scan every key in the datastore once, because the stale records sit at the datastore root with no shared prefix to narrow the search. On a large repo the first start after upgrading can spend extra time on this. A marker is written once the scan finishes, so later starts skip it entirely.

🧪 Tests use new go-test and rand v2

The new go-test is upgraded to use math/rand/v2 in all of its packages. The /go-test/random package now allows reuse of the random number generator for more efficiently generating sets of random values.

Additionally, the /go-test/random package removes support for a global seed for the random number generator. This led to the possibility of multiple tests setting the global seed to generate deterministic values, and breaking other tests by causing the generator to generate unexpected values. This breakage could be intermittent and difficult to debug, depending on the how/which tests ran at the same time.

Since the underlying pseudo-random number generator was changed in the go-test module, the data generated for a given seed also changed. This required updating tests that relied on seeding the generator and getting expected values.

🖥️ WebUI Improvements

IPFS Web UI has been updated to v4.13.0.

Share Link only ever produced a public gateway URL, so everything you shared depended on a server someone else runs. A new "Sharing IPFS Links" section in Settings lets you pick native ipfs:// and ipns:// addresses instead. This is opt-in: the default still points at dweb.link.

Through Docker or a reverse proxy, the Web UI handed out dead links built from Addresses.Gateway, usually /ip4/0.0.0.0/tcp/8080. The new "Local HTTP Gateway" field takes a URL your browser can reach.

Removing files through the selection toolbar left their pins behind. It now offers the "Also remove local pin (recommended)" checkbox.

🧵 A truncated CAR response now says so

A CAR response that stopped partway through used to look exactly like a complete one, so a client could accept a short DAG as the whole thing. Such a response now ends with [Gateway Error: CAR stream truncated, response is incomplete], which makes the trailing bytes invalid CAR: a reader stops with an error instead of trusting what it got. If you run a gateway behind a reverse proxy or a CDN, a short response now identifies itself instead of leaving you to guess which hop dropped it.

The gateway also caps how deep a CAR response descends into a DAG at 1024 levels, far beyond anything UnixFS produces: traversal cost grows with depth, and the cap stops an adversarially nested DAG from eating memory. A response cut at the limit ends with the same marker (boxo#1197).

🔒 Security fixes: update recommended

This release closes several memory-exhaustion and crash issues, some of them already public. Update when you can.

• Pubsub memory exhaustion (CVE-2026-46679): a remote peer could subscribe to an endless stream of unique topic names, disconnect, and leave your node holding every one of them, with memory growing each round until a restart. Kubo now frees a topic's state once the last peer leaves it and limits how much a peer can pack into a single control message. Only nodes that turn pubsub on are affected, through Pubsub.Enabled or Ipns.UsePubsub; if you set either, update as soon as you can. The Go and Python libp2p ports track the same pattern in go-libp2p-pubsub#705 and py-libp2p#1349.
• WebTransport memory exhaustion (CVE-2026-57497): a peer could send a WebTransport message of a type your node did not recognise, and your node would hold the whole body in memory while skipping past it. A big enough message, or enough of them, exhausts memory. Affects any node listening on /quic-v1/webtransport, which is the default.
• HTTP/3 trailer decompression memory exhaustion (CVE-2026-40898): quic-go limited the compressed size of incoming HTTP/3 trailers but not their decoded size, so a crafted message could expand to about fifty times its wire size in memory. Kubo runs quic-go's HTTP/3 server as part of the default WebTransport listener; the quic-go v0.60.0 in this release includes the fix.
• libp2p resource caps: a hostile peer could flood your peerstore with unconnected addresses (go-libp2p#3486), plant more than 1,800 protocol entries through chunked identify messages (go-libp2p#3501), or attach an unbounded number of addresses to one webrtc-direct connection (go-libp2p#3500). Each is now bounded.
• Daemon crash on routing queries (go-libp2p#3490): a data race could corrupt the results streamed by ipfs routing findprovs, ipfs routing findpeer, and ipfs dht query, taking the whole daemon down mid-response.
• Tracing exporter memory (CVE-2026-39882): a hostile or man-in-the-middle collector could exhaust memory through the OpenTelemetry OTLP HTTP exporter. Affects nodes that export traces over OTLP HTTP.

📦️ Dependency updates

• update ipfs-webui to v4.13.0
• update go-libp2p to v0.49.0
• update go-libp2p-pubsub to v0.17.0
• update go-libp2p-kad-dht to v0.42.1 (incl. v0.42.0, v0.41.0 and the local record validation fix); see Unified IPNS record storage above
• update boxo to v0.42.1 (incl. v0.42.0, v0.41.0); see Revamped TTL and expiration handling for IPNS and DNSLink and Unified IPNS record storage above, plus a bitswap fix so fetches from a just-reconnected peer no longer stall (boxo#1164), a fix so HTTP providers on IPv6 addresses are dialed correctly (boxo#1196), and shorter stale windows on cached /routing/v1 responses so clients stop getting long-dead peer addresses (boxo#1195); also pulls in go-doh-resolver v0.6.0 and go-multiaddr-dns v0.6.0
• update p2p-forge/client to v0.10.1 (incl. v0.10.0, v0.9.1, v0.9.0, v0.8.1); a node that comes back online after its AutoTLS certificate expired now discards it and requests a fresh one, instead of retrying a renewal the CA always rejects
• update go-ds-pebble to v0.5.12
• updates github.com/cockroachdb/pebble to v2.1.6

📝 Changelog

👨‍👩‍👧‍👦 Contributors