A token can be issued for a machine's tunnel key, and it joins through the tunnel

token issue --overlay-key records the key the machine made, binds the
token to it, gives the machine its address and makes it a peer of the
hub, pushing the hub before the token is shown. The token carries the
hub's tunnel and the bus at its address on the private network, and
enrolment refuses any other key (novox/hq ADR 0169). Tokens without a
key enrol as before until the bus is closed. Also a token verb.

cmd/mesh-controller/network.go

@@ -232,9 +232,22 @@ func network(ctx context.Context, inv *inventory.Inventory, on map[string]bool,
 	if err != nil {
 		return nil, err
 	}
+	// **A machine joining is on the network before it is anything else** (novox/hq ADR 0169). Its
+	// token was issued for its tunnel key and gave it an address, so while that token can still be
+	// used the hub carries it as a peer: it brings its tunnel up from the token and enrols over it.
+	// When the token is spent the machine is on the network by what it runs, as every other is; when
+	// it expires unused, the peer goes with it at the hub's next composition.
+	joining, err := inv.NodesWithALiveToken(ctx)
+	if err != nil {
+		return nil, err
+	}
+	isJoining := map[string]bool{}
+	for _, name := range joining {
+		isJoining[name] = true
+	}
 	nodes := make([]overlay.Node, 0, len(places))
 	for _, p := range places {
-		if !on[p.Name] {
+		if !on[p.Name] && !(isJoining[p.Name] && p.Key != "" && p.Address != "") {
 			continue
 		}
 		n := overlay.Node{

cmd/mesh-controller/nodes.go

@@ -2,9 +2,11 @@ package main
 
 import (
 	"context"
+	"encoding/base64"
 	"errors"
 	"flag"
 	"fmt"
+	"net"
 	"strings"
 	"time"
 
@@ -230,6 +232,8 @@ func tokenCommand(ctx context.Context, args []string) error {
 	validFor := set.Duration("for", time.Hour, "how long the token may be used")
 	adopted := set.Bool("adopted", false,
 		"the machine joining is in use: it is adopted, and keeps what is found on it")
+	tunnelKey := set.String("overlay-key", "",
+		"the public half of the tunnel key the machine made (`nox-mesh-host key`): it joins through the tunnel")
 	if err := set.Parse(args[1:]); err != nil {
 		return err
 	}
@@ -283,6 +287,14 @@ func tokenCommand(ctx context.Context, args []string) error {
 	default:
 		return err
 	}
+	// **Through the tunnel** (novox/hq ADR 0169): the machine's key recorded, its address given, the
+	// hub sent it as a peer — all before the token is shown, so the tunnel answers the first time the
+	// machine knocks. The bus is then reached at its address on the private network.
+	if *tunnelKey != "" {
+		if made.Tunnel, made.Broker, err = throughTheTunnel(ctx, open, issued.Node, *tunnelKey, made.Broker); err != nil {
+			return err
+		}
+	}
 	encoded, err := made.Encode()
 	if err != nil {
 		return err
@@ -307,6 +319,66 @@ func tokenCommand(ctx context.Context, args []string) error {
 	return nil
 }
 
+// throughTheTunnel makes a machine a peer of the hub for its token, and says what the token carries
+// for it: its first tunnel, and the bus at its address on the private network (novox/hq ADR 0169).
+//
+// The hub is pushed here, before the token is shown. A token shown before the hub knew the key is a
+// tunnel that does not answer, and a machine that cannot tell that from a bus that is down.
+func throughTheTunnel(ctx context.Context, open *stores, node inventory.Node, key, busAt string) (
+	*token.Tunnel, string, error) {
+	inv := open.inventory
+	key = strings.TrimSpace(key)
+	if raw, err := base64.StdEncoding.DecodeString(key); err != nil || len(raw) != 32 {
+		return nil, "", fmt.Errorf("%q is not a tunnel public key: it is 32 bytes in base64, as "+
+			"`nox-mesh-host key` prints it", key)
+	}
+	// The bus on the private network is the hub's address at the bus's own port, so the port must be
+	// known before anything is recorded.
+	_, port, err := net.SplitHostPort(busAt)
+	if err != nil || port == "" {
+		return nil, "", fmt.Errorf("the bus's address %q has no port to reach it on", busAt)
+	}
+	places, err := inv.Overlays(ctx)
+	if err != nil {
+		return nil, "", err
+	}
+	var hub *inventory.Overlay
+	for i := range places {
+		if places[i].Hub {
+			hub = &places[i]
+		}
+	}
+	if hub == nil || hub.Key == "" || hub.Endpoint == "" || hub.Address == "" {
+		return nil, "", errors.New("this mesh has no hub with a key, an address and an endpoint to " +
+			"dial, so there is no tunnel to join through: place one (`overlay place <node> --hub " +
+			"--endpoint <host>:<port>`), or issue the token without --overlay-key")
+	}
+	if err := inv.RecordOverlayKey(ctx, node.ID, key); err != nil {
+		return nil, "", err
+	}
+	if err := inv.BindTokenToKey(ctx, node.ID, key); err != nil {
+		return nil, "", err
+	}
+	cidr, err := overlayRange(ctx, inv)
+	if err != nil {
+		return nil, "", err
+	}
+	address, err := inv.AssignAddress(ctx, node.ID, cidr)
+	if err != nil {
+		return nil, "", err
+	}
+	if err := sendTo(ctx, open, []string{hub.Name}); err != nil {
+		return nil, "", fmt.Errorf("%s was made a peer of the hub, and the hub could not be sent "+
+			"it, so the tunnel would not answer — the token is not shown; issue it again once %s "+
+			"can be pushed: %w", node.Name, hub.Name, err)
+	}
+	// An address, not a name — nothing resolves before the machine has joined (novox/hq ADR 0004).
+	return &token.Tunnel{
+		Key: key, Address: address + "/32", Range: cidr,
+		HubKey: hub.Key, HubEndpoint: hub.Endpoint,
+	}, net.JoinHostPort(hub.Address, port), nil
+}
+
 // issueFor is the inventory's half of issuing a token: the record, made when it is new, adopted
 // when the operator says so, and the one-time secret for it. The node in what it returns carries
 // its mode, which is what the token says.

cmd/mesh-controller/seatverbs.go

@@ -129,6 +129,26 @@ func argvFor(verb string, args map[string]any) ([]string, error) {
 		// Half of either shape: the command says its usage, which names both shapes, and that is
 		// the answer the caller needs.
 		return []string{"rotate"}, nil
+	case "token":
+		// `token issue` at a shell (novox/hq ADR 0169). Exactly one of node or new; the command
+		// refuses both or neither in its own words.
+		argv := []string{"token", "issue"}
+		if n := str("node"); n != "" {
+			argv = append(argv, "--node", n)
+		}
+		if n := str("new"); n != "" {
+			argv = append(argv, "--new", n)
+		}
+		if k := str("overlay_key"); k != "" {
+			argv = append(argv, "--overlay-key", k)
+		}
+		if d := str("for"); d != "" {
+			argv = append(argv, "--for", d)
+		}
+		if str("adopted") == "true" {
+			argv = append(argv, "--adopted")
+		}
+		return argv, nil
 	case "settings":
 		// `settings set|clear` at a shell (novox/hq issue 198). The values travel as an argument
 		// because a tool has no file to hand the command; the command reads either.

cmd/mesh-controller/seatverbs_test.go

@@ -73,6 +73,14 @@ func TestRotateTakesAProvisionOrAnOwnSecret(t *testing.T) {
 	}
 }
 
+// `token` is `token issue` at a shell, with the machine's tunnel key (novox/hq ADR 0169).
+func TestTokenIssuesForAMachineAndItsTunnelKey(t *testing.T) {
+	argv, err := argvFor("token", map[string]any{"new": "laptop", "overlay_key": "k", "for": "2h"})
+	if err != nil || strings.Join(argv, " ") != "token issue --new laptop --overlay-key k --for 2h" {
+		t.Fatalf("token: %v %v", argv, err)
+	}
+}
+
 // `settings` is `settings set|clear` at a shell, with the values passed inline (novox/hq issue 198).
 func TestSettingsSetsOrClearsALayer(t *testing.T) {
 	argv, err := argvFor("settings", map[string]any{"module": "dnsmasq", "values": `{"a":1}`, "node": "ace"})