feat: swarm addrs autonat command (#11184)

* feat: add swarm addrs autonat command

fixes #11171 by adding a self service way to debug public reachability
with autonat

* test: add test for ipfs swarm addr autonat command

* docs: add ipfs swarm addrs autonat to changelog

* test: update failing test

* fix: swarm addrs autonat bugfixes and cleanup

- fix help text to show capitalized reachability values (Public, Private,
  Unknown) matching actual output from network.Reachability.String()
- default Reachability to "Unknown" instead of empty string when the
  host interface assertion fails
- extract multiaddrsToStrings and writeAddrSection helpers to
  deduplicate repeated conversion loops and text formatting blocks

---------

Co-authored-by: Marcin Rataj <lidel@lidel.org>

core/commands/commands_test.go

@@ -198,6 +198,7 @@ func TestCommands(t *testing.T) {
 		"/stats/repo",
 		"/swarm",
 		"/swarm/addrs",
+		"/swarm/addrs/autonat",
 		"/swarm/addrs/listen",
 		"/swarm/addrs/local",
 		"/swarm/connect",

core/commands/swarm.go

@@ -513,8 +513,9 @@ var swarmAddrsCmd = &cmds.Command{
 `,
 	},
 	Subcommands: map[string]*cmds.Command{
-		"local":  swarmAddrsLocalCmd,
-		"listen": swarmAddrsListenCmd,
+		"autonat": swarmAddrsAutoNATCmd,
+		"local":   swarmAddrsLocalCmd,
+		"listen":  swarmAddrsListenCmd,
 	},
 	Run: func(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment) error {
 		api, err := cmdenv.GetApi(env, req)

core/commands/swarm_addrs_autonat.go

@@ -0,0 +1,139 @@
+package commands
+
+import (
+	"fmt"
+	"io"
+
+	cmds "github.com/ipfs/go-ipfs-cmds"
+	cmdenv "github.com/ipfs/kubo/core/commands/cmdenv"
+	"github.com/libp2p/go-libp2p/core/network"
+	ma "github.com/multiformats/go-multiaddr"
+)
+
+// reachabilityHost provides access to the AutoNAT reachability status.
+type reachabilityHost interface {
+	Reachability() network.Reachability
+}
+
+// confirmedAddrsHost provides access to per-address reachability from AutoNAT V2.
+type confirmedAddrsHost interface {
+	ConfirmedAddrs() (reachable, unreachable, unknown []ma.Multiaddr)
+}
+
+// autoNATResult represents the AutoNAT reachability information.
+type autoNATResult struct {
+	Reachability string   `json:"reachability"`
+	Reachable    []string `json:"reachable,omitempty"`
+	Unreachable  []string `json:"unreachable,omitempty"`
+	Unknown      []string `json:"unknown,omitempty"`
+}
+
+func multiaddrsToStrings(addrs []ma.Multiaddr) []string {
+	out := make([]string, len(addrs))
+	for i, a := range addrs {
+		out[i] = a.String()
+	}
+	return out
+}
+
+func writeAddrSection(w io.Writer, label string, addrs []string) {
+	if len(addrs) > 0 {
+		fmt.Fprintf(w, "  %s:\n", label)
+		for _, addr := range addrs {
+			fmt.Fprintf(w, "    %s\n", addr)
+		}
+	}
+}
+
+var swarmAddrsAutoNATCmd = &cmds.Command{
+	Helptext: cmds.HelpText{
+		Tagline: "Show address reachability as determined by AutoNAT V2.",
+		ShortDescription: `
+'ipfs swarm addrs autonat' shows the reachability status of your node's
+addresses as determined by AutoNAT V2.
+`,
+		LongDescription: `
+'ipfs swarm addrs autonat' shows the reachability status of your node's
+addresses as verified by AutoNAT V2.
+
+AutoNAT V2 probes your node's addresses to determine if they are reachable
+from the public internet. This helps understand whether other peers can
+dial your node directly.
+
+The output shows:
+- Reachability: Overall status (Public, Private, or Unknown)
+- Reachable: Addresses confirmed to be publicly reachable
+- Unreachable: Addresses that failed reachability checks
+- Unknown: Addresses that haven't been tested yet
+
+For more information on AutoNAT V2, see:
+https://github.com/libp2p/specs/blob/master/autonat/autonat-v2.md
+
+Example:
+
+    > ipfs swarm addrs autonat
+    AutoNAT V2 Status:
+      Reachability: Public
+
+    Per-Address Reachability:
+      Reachable:
+        /ip4/203.0.113.42/tcp/4001
+        /ip4/203.0.113.42/udp/4001/quic-v1
+      Unreachable:
+        /ip6/2001:db8::1/tcp/4001
+      Unknown:
+        /ip4/203.0.113.42/udp/4001/webrtc-direct
+`,
+	},
+	Run: func(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment) error {
+		nd, err := cmdenv.GetNode(env)
+		if err != nil {
+			return err
+		}
+
+		if !nd.IsOnline {
+			return ErrNotOnline
+		}
+
+		result := autoNATResult{
+			Reachability: network.ReachabilityUnknown.String(),
+		}
+
+		// Get per-address reachability from AutoNAT V2.
+		// The host embeds *BasicHost (closableBasicHost, closableRoutedHost)
+		// which implements ConfirmedAddrs.
+		if h, ok := nd.PeerHost.(confirmedAddrsHost); ok {
+			reachable, unreachable, unknown := h.ConfirmedAddrs()
+			result.Reachable = multiaddrsToStrings(reachable)
+			result.Unreachable = multiaddrsToStrings(unreachable)
+			result.Unknown = multiaddrsToStrings(unknown)
+		}
+
+		// Get overall reachability status.
+		if h, ok := nd.PeerHost.(reachabilityHost); ok {
+			result.Reachability = h.Reachability().String()
+		}
+
+		return cmds.EmitOnce(res, result)
+	},
+	Type: autoNATResult{},
+	Encoders: cmds.EncoderMap{
+		cmds.Text: cmds.MakeTypedEncoder(func(req *cmds.Request, w io.Writer, result autoNATResult) error {
+			fmt.Fprintln(w, "AutoNAT V2 Status:")
+			fmt.Fprintf(w, "  Reachability: %s\n", result.Reachability)
+
+			fmt.Fprintln(w)
+			fmt.Fprintln(w, "Per-Address Reachability:")
+
+			writeAddrSection(w, "Reachable", result.Reachable)
+			writeAddrSection(w, "Unreachable", result.Unreachable)
+			writeAddrSection(w, "Unknown", result.Unknown)
+
+			if len(result.Reachable) == 0 && len(result.Unreachable) == 0 && len(result.Unknown) == 0 {
+				fmt.Fprintln(w, "  (no address reachability data available)")
+			}
+
+			return nil
+		}),
+	},
+}

docs/changelogs/v0.40.md

@@ -18,6 +18,7 @@ This release was brought to you by the [Shipyard](https://ipshipyard.com/) team.
   - [IPIP-524: Gateway codec conversion disabled by default](#ipip-524-gateway-codec-conversion-disabled-by-default)
   - [Improved IPNS over PubSub validation](#improved-ipns-over-pubsub-validation)
   - [New `ipfs diag datastore` commands](#new-ipfs-diag-datastore-commands)
+  - [🔍 New `ipfs swarm addrs autonat` command](#-new-ipfs-swarm-addrs-autonat-command)
   - [🚇 Improved `ipfs p2p` tunnels with foreground mode](#-improved-ipfs-p2p-tunnels-with-foreground-mode)
   - [Improved `ipfs dag stat` output](#improved-ipfs-dag-stat-output)
   - [🔑 `ipfs key` improvements](#-ipfs-key-improvements)
@@ -129,6 +130,38 @@ New experimental commands for low-level datastore inspection:
 
 The daemon must not be running when using these commands. Run `ipfs diag datastore --help` for usage examples.
 
+#### 🔍 New `ipfs swarm addrs autonat` command
+
+The new `ipfs swarm addrs autonat` command shows the network reachability status of your node's addresses as verified by AutoNAT V2. AutoNAT V2 leverages other nodes in the IPFS network to test your node's external public reachability, providing a self-service way to debug connectivity.
+
+Public reachability is important for:
+
+- **Direct data fetching**: Other nodes can fetch data directly from your node without NAT hole punching.
+- **Browser access**: Web browsers can connect to your node directly for content retrieval.
+- **DHT participation**: Your node can act as a DHT server, helping to maintain the distributed hash table and making content routing more robust.
+
+The command displays:
+
+- Overall reachability status (public, private, or unknown)
+- Per-address reachability showing which specific addresses are reachable, unreachable, or unknown
+
+Example output:
+```
+AutoNAT V2 Status:
+  Reachability: public
+
+Per-Address Reachability:
+  Reachable:
+    /ip4/203.0.113.42/tcp/4001
+    /ip4/203.0.113.42/udp/4001/quic-v1
+  Unreachable:
+    /ip6/2001:db8::1/tcp/4001
+  Unknown:
+    /ip4/203.0.113.42/udp/4001/webrtc-direct
+```
+
+This helps diagnose connectivity issues and understand if your node is publicly reachable. See the [AutoNAT V2 spec](https://github.com/libp2p/specs/blob/master/autonat/autonat-v2.md) for more details.
+
 #### 🚇 Improved `ipfs p2p` tunnels with foreground mode
 
 P2P tunnels can now run like SSH port forwarding: start a tunnel, use it, and it cleans up automatically when you're done.

test/cli/swarm_test.go

@@ -92,4 +92,35 @@ func TestSwarm(t *testing.T) {
 		assert.ElementsMatch(t, outputIdentify.Addresses, otherNodeIDOutput.Addresses)
 		assert.ElementsMatch(t, outputIdentify.Protocols, otherNodeIDOutput.Protocols)
 	})
+
+	t.Run("ipfs swarm addrs autonat returns valid reachability status", func(t *testing.T) {
+		t.Parallel()
+		node := harness.NewT(t).NewNode().Init().StartDaemon()
+		defer node.StopDaemon()
+
+		res := node.RunIPFS("swarm", "addrs", "autonat", "--enc=json")
+		assert.NoError(t, res.Err)
+
+		var output struct {
+			Reachability string   `json:"reachability"`
+			Reachable    []string `json:"reachable"`
+			Unreachable  []string `json:"unreachable"`
+			Unknown      []string `json:"unknown"`
+		}
+		err := json.Unmarshal(res.Stdout.Bytes(), &output)
+		assert.NoError(t, err)
+
+		// Reachability must be one of the valid states
+		// Note: network.Reachability constants use capital first letter
+		validStates := []string{"Public", "Private", "Unknown"}
+		assert.Contains(t, validStates, output.Reachability,
+			"Reachability should be one of: Public, Private, Unknown")
+
+		// For a newly started node, reachability is typically Unknown initially
+		// as AutoNAT hasn't completed probing yet. This is expected behavior.
+		// The important thing is that the command runs and returns valid data.
+		totalAddrs := len(output.Reachable) + len(output.Unreachable) + len(output.Unknown)
+		t.Logf("Reachability: %s, Total addresses: %d (reachable: %d, unreachable: %d, unknown: %d)",
+			output.Reachability, totalAddrs, len(output.Reachable), len(output.Unreachable), len(output.Unknown))
+	})
 }