A machine joins the mesh it raised

The last step of the first-node path, and the bundle now carries all of it: a
container runtime, the store, a database per context, their schemas, the broker
with a certificate it generated itself, and the control plane running.

Then the machine enrols against the mesh on its own disk. It dials the broker
over TLS, refuses anything but the pinned certificate, presents the one-time
secret with a public key it generated, and is told the name the mesh has for
it. Its specialness lasted two commands, which is what ADR 0004 asked for.

The identity is saved only after the mesh says it knows this node. A node
holding an identity the mesh never recorded would believe it had joined and be
believed by nobody, which is worse than not joining because nothing looks wrong.

An already-enrolled machine refuses a valid token rather than quietly acquiring
a second identity, and a spent token is refused by the mesh. Both checked.

Containers gained a network field. The control plane must reach the store and
the broker on the machine it was raised on, before there is any mesh to arrange
that; the alternative was publishing ports and guessing an address that works
from inside a container, which fails in a worse way.

The control plane talks to the broker over loopback in plaintext, deliberately.
The TLS on 5671 exists so a node crossing a network can pin a certificate, not
for a hop that never leaves the machine.

Verified on a sealed lab machine: eleven resources applied from bare, the
control plane consuming, a token issued from inside it, and the machine
enrolled -- with the recorded public key matching what the host printed, the
token marked spent, and the profile stored.

cmd/mesh-host/main.go

@@ -222,7 +222,7 @@ func run(ctx context.Context, command string, opts options) error {
 		return w.Flush()
 
 	case "enrol", "enroll":
-		return enrol(opts)
+		return enrol(ctx, opts)
 
 	case "version":
 		fmt.Println(version)
@@ -386,7 +386,7 @@ func runApply(ctx context.Context, opts options, d *declaration.Declaration, sou
 // the one-time secret together with a public key it generated itself.
 //
 // The mesh issues no identity. This machine arrives holding one; what it receives is being known.
-func enrol(opts options) error {
+func enrol(ctx context.Context, opts options) error {
 	tokenText, name := &opts.token, &opts.nodeName
 	if strings.TrimSpace(*tokenText) == "" {
 		return errors.New("enrol --token <token>: the token is carried to this machine by a " +
@@ -429,13 +429,44 @@ func enrol(opts options) error {
 	defer conn.Close()
 	fmt.Println("\nthe broker presented the certificate this token pins")
 
+	conn.Close()
+
 	mine, err := identity.Generate(*name)
 	if err != nil {
 		return err
 	}
 	fmt.Printf("generated this node's identity: %s\n", mine.PublicBase64())
 
-	return errors.New("the link is not built: this machine has verified the broker and made its " +
+	// What this machine can be asked to do, gathered before joining rather than after. The
-		"identity, and there is nothing yet to present them to.\n" +
+	// control plane cannot decide what a node should run without it, so it travels with the
-		"Nothing has been saved, so this can be run again unchanged")
+	// request instead of being asked for in a second round trip.
+	detected := profile.Detect(ctx, profile.Default(nil), opts.timeout)
+	reported := map[string]any{}
+	if raw, err := json.Marshal(detected); err == nil {
+		_ = json.Unmarshal(raw, &reported)
+	}
+
+	reply, err := link.Enrol(ctx, token.Broker, token.Fingerprint, *name, token.Secret,
+		mine.Public, reported, opts.timeout)
+	if err != nil {
+		return err
+	}
+
+	// The mesh's name for this node wins over what the machine called itself: the token was
+	// issued for a node record, and that record is what the identity binds to.
+	mine.Node = reply.Node
+
+	// Saved only now, and only once the mesh has said it knows this node. A node holding an
+	// identity the mesh has never recorded would believe it had joined and be believed by
+	// nobody — worse than not having joined, because nothing would look wrong.
+	if err := identity.Save(identityPath, mine); err != nil {
+		return fmt.Errorf(
+			"the mesh accepted this node as %q and its identity could not be saved: %w\n"+
+				"That token is spent, so getting back needs a new one", reply.Node, err)
+	}
+
+	fmt.Printf("\nenrolled as %s\n", reply.Node)
+	fmt.Printf("  identity   %s\n", identityPath)
+	fmt.Printf("  queue      %s\n", reply.Queue)
+	return nil
 }

examples/substrate-first-node.lock

@@ -1,11 +1,14 @@
 // substrate-first-node.lock — what a machine must be before a mesh exists.
 //
-// Steps 0 to 4 of the bootstrap (novox/hq 03-DESIGN/01-to-be/07-the-substrate.md): a container
+// Steps 0 to 5 of the bootstrap (novox/hq 03-DESIGN/01-to-be/07-the-substrate.md): a container
 // runtime, a store, a database per context, that context's schema, and the broker.
 //
-// It stops before step 5 (a virtual host, a credential, a certificate) and step 6 (the control
+// It stops before step 6, where the control plane runs.
-// plane runs), because nothing consumes them yet. A bundle naming a control plane that serves
+//
-// nothing would be a bundle whose last step cannot be checked.
+// The broker generates its OWN certificate, in its own image, into a volume it then mounts read
+// only. Self-signed, because at this moment there is no mesh to issue one and no public name to
+// obtain one for -- and it does not matter, because what a joining node checks is the fingerprint
+// pinned in its token, not a chain or a name (novox/hq ADR 0004). The subject is decoration.
 //
 // PINNED BY DIGEST, and the digest is not decoration: a tag can be made to point at a different
 // image, and this file is applied on a machine with no mesh to ask about anything. These digests
@@ -41,6 +44,7 @@
         "POSTGRES_PASSWORD": "bootstrap",
         "PGDATA": "/var/lib/postgresql/data/pgdata"
       },
+      "ports": ["127.0.0.1:5432:5432"],
       "volumes": ["mesh-store-data:/var/lib/postgresql/data"]
     },
     {
@@ -58,21 +62,40 @@
       "verify": ["sh", "-c", "psql -U postgres -lqt | cut -d'|' -f1 | grep -qw inventory"]
     },
     {
-      "id": "inventory-schema",
+      "id": "identity-database",
+      "type": "action",
+      "in": "mesh-store",
+      "command": ["sh", "-c", "psql -U postgres -c 'CREATE DATABASE identity'"],
+      "verify": ["sh", "-c", "psql -U postgres -lqt | cut -d'|' -f1 | grep -qw identity"]
+    },
+    {
+      "id": "context-schemas",
       "type": "action",
       "command": ["docker", "run", "--rm", "--network", "container:mesh-store",
                   "-e", "MESH_STORE_INVENTORY=postgres://postgres:bootstrap@127.0.0.1:5432/inventory?sslmode=disable",
-                  "192.0.2.250:5000/mesh-control@sha256:1c27a43c4431c2b580404e8e1768cd858009e265e80b6f1591eb6de1123fc411",
+                  "-e", "MESH_STORE_IDENTITY=postgres://postgres:bootstrap@127.0.0.1:5432/identity?sslmode=disable",
+                  "192.0.2.250:5000/mesh-control@sha256:c6e96dc574ea52085bae4ed0a64e593ee512265ecb226643aa1fcbaf56d78396",
                   "migrate"],
-      "verify": ["sh", "-c", "docker exec mesh-store psql -U postgres -d inventory -tAc \"select to_regclass('public.node')\" | grep -qx node"]
+      "verify": ["sh", "-c", "docker exec mesh-store psql -U postgres -d inventory -tAc \"select to_regclass('public.node')\" | grep -qx node && docker exec mesh-store psql -U postgres -d identity -tAc \"select to_regclass('public.signing_key')\" | grep -qx signing_key"]
+    },
+    {
+      "id": "broker-certificate",
+      "type": "action",
+      "command": ["docker", "run", "--rm", "--entrypoint", "sh", "-v", "mesh-broker-tls:/tls",
+                  "192.0.2.250:5000/cloudamqp/lavinmq@sha256:b117c254e6e269a29db479e6b410ca4e46e035b4981e49d24b159673ef09d336",
+                  "-c", "test -f /tls/tls.crt || (openssl req -x509 -newkey rsa:2048 -nodes -keyout /tls/tls.key -out /tls/tls.crt -days 3650 -subj '/CN=mesh-broker' >/dev/null 2>&1 && chmod 644 /tls/tls.crt && chmod 600 /tls/tls.key)"],
+      "verify": ["docker", "run", "--rm", "--entrypoint", "sh", "-v", "mesh-broker-tls:/tls",
+                 "192.0.2.250:5000/cloudamqp/lavinmq@sha256:b117c254e6e269a29db479e6b410ca4e46e035b4981e49d24b159673ef09d336",
+                 "-c", "test -s /tls/tls.crt && openssl x509 -in /tls/tls.crt -noout"]
     },
     {
       "id": "broker",
       "type": "container",
       "name": "mesh-broker",
       "image": "192.0.2.250:5000/cloudamqp/lavinmq@sha256:b117c254e6e269a29db479e6b410ca4e46e035b4981e49d24b159673ef09d336",
-      "ports": ["5672:5672"],
+      "ports": ["5671:5671", "127.0.0.1:5672:5672", "127.0.0.1:15672:15672"],
-      "volumes": ["mesh-broker-data:/var/lib/lavinmq"]
+      "volumes": ["mesh-broker-data:/var/lib/lavinmq", "mesh-broker-tls:/tls:ro"],
+      "args": ["--amqps-port=5671", "--cert=/tls/tls.crt", "--key=/tls/tls.key"]
     },
     {
       "id": "broker-ready",
@@ -80,6 +103,24 @@
       "in": "mesh-broker",
       "command": ["sh", "-c", "for i in $(seq 1 60); do lavinmqctl status >/dev/null 2>&1 && exit 0; sleep 1; done; exit 1"],
       "verify": ["lavinmqctl", "status"]
+    },
+    {
+      "id": "control-plane",
+      "type": "container",
+      "name": "mesh-control",
+      "image": "192.0.2.250:5000/mesh-control@sha256:c6e96dc574ea52085bae4ed0a64e593ee512265ecb226643aa1fcbaf56d78396",
+      "network": "host",
+      "args": ["serve"],
+      "volumes": ["mesh-broker-tls:/broker-tls:ro"],
+      "env": {
+        "MESH_STORE_INVENTORY": "postgres://postgres:bootstrap@127.0.0.1:5432/inventory?sslmode=disable",
+        "MESH_STORE_IDENTITY": "postgres://postgres:bootstrap@127.0.0.1:5432/identity?sslmode=disable",
+        "MESH_BROKER_AMQP": "amqp://guest:guest@127.0.0.1:5672/",
+        "MESH_BROKER_MANAGEMENT": "http://guest:guest@127.0.0.1:15672",
+        "MESH_BROKER_ADDRESS": "192.0.2.10:5671",
+        "MESH_BROKER_CERTIFICATE": "/broker-tls/tls.crt"
       }
+    }
+
   ]
 }

go.mod

@@ -1,3 +1,5 @@
 module github.com/novox/mesh-host
 
 go 1.24
+
+require github.com/rabbitmq/amqp091-go v1.14.0 // indirect

go.sum

@@ -0,0 +1,2 @@
+github.com/rabbitmq/amqp091-go v1.14.0 h1:RSaT7aOKt/OrkVUyswPDW29lnRz9psuGmfZFBmLqLek=
+github.com/rabbitmq/amqp091-go v1.14.0/go.mod h1:Hy4jKW5kQART1u+JkDTF9YYOQUHXqMuhrgxOEeS7G4o=

internal/apply/apply.go

@@ -584,8 +584,12 @@ func applyContainer(ctx context.Context, r *declaration.Container, run Runner) (
 		}
 	}
 
-	args := []string{"run", "--detach", "--name", r.Name, "--restart", "unless-stopped",
+	args := []string{"run", "--detach", "--name", r.Name, "--restart", "unless-stopped"}
-		"--label", specLabel + "=" + want, "--label", idLabel + "=" + r.ID}
+	if r.Network != "" {
+		args = append(args, "--network", r.Network)
+	}
+	args = append(args,
+		"--label", specLabel+"="+want, "--label", idLabel+"="+r.ID)
 	for _, k := range sortedKeys(r.Env) {
 		args = append(args, "--env", k+"="+r.Env[k])
 	}

internal/declaration/declaration.go

@@ -168,6 +168,13 @@ type Container struct {
 	Ports   []string          `json:"ports,omitempty"`
 	Volumes []string          `json:"volumes,omitempty"`
 	Args    []string          `json:"args,omitempty"`
+	// Network is the container's network, passed to the runtime unchanged.
+	//
+	// Needed because the control plane must reach the store and the broker on the machine it was
+	// raised on, before there is any mesh to arrange that. The alternative was publishing ports
+	// and guessing an address that works from inside a container, which is the same thing with a
+	// worse failure mode.
+	Network string `json:"network,omitempty"`
 }
 
 func (c *Container) Identity() string { return c.ID }

internal/link/enrol.go

@@ -0,0 +1,149 @@
+package link
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/url"
+	"time"
+
+	amqp "github.com/rabbitmq/amqp091-go"
+)
+
+// The wire format shared with the control plane, which defines it separately because this binary
+// requires nothing present and does not import it. A test on each side asserts the field names.
+const (
+	Exchange = "mesh"
+	KeyEnrol = "enrol"
+)
+
+// QueueFor is the queue this node consumes from — the only one its account may read.
+func QueueFor(node string) string { return "node." + node }
+
+// EnrolRequest is what this node says when joining.
+type EnrolRequest struct {
+	Node      string         `json:"node"`
+	Secret    string         `json:"secret"`
+	PublicKey []byte         `json:"public_key"`
+	Profile   map[string]any `json:"profile,omitempty"`
+}
+
+// EnrolReply is what the mesh says back.
+type EnrolReply struct {
+	Accepted bool   `json:"accepted"`
+	Node     string `json:"node,omitempty"`
+	Queue    string `json:"queue,omitempty"`
+	Refusal  string `json:"refusal,omitempty"`
+}
+
+// ErrRefused is what a node gets when the mesh will not have it.
+var ErrRefused = errors.New("the mesh refused this enrolment")
+
+// Enrol presents this node's key and its one-time secret, and waits to be told it is known.
+//
+// The broker has already authenticated this connection: the account was created when the token
+// was issued and the secret is its password. So this is not how the node gets in — it is what it
+// says once it is in, and the secret travels again because the control plane must not have to ask
+// the broker who connected.
+func Enrol(ctx context.Context, address, pin, node, secret string, public []byte,
+	profile map[string]any, timeout time.Duration) (EnrolReply, error) {
+
+	config, err := PinnedConfig(pin)
+	if err != nil {
+		return EnrolReply{}, err
+	}
+
+	// The account name is the node's, and the password is the token's secret. Escaped because a
+	// name or secret containing a colon or an at-sign would otherwise change which host this
+	// connects to — a credential silently redirecting a connection is the worst shape this could
+	// take.
+	dsn := fmt.Sprintf("amqps://%s:%s@%s/",
+		url.QueryEscape(node), url.QueryEscape(secret), address)
+
+	conn, err := amqp.DialConfig(dsn, amqp.Config{
+		TLSClientConfig: config,
+		Dial:            amqp.DefaultDial(timeout),
+	})
+	if err != nil {
+		if errors.Is(err, ErrWrongCertificate) {
+			return EnrolReply{}, err
+		}
+		// Not quoted back: the DSN carries the one-time secret.
+		return EnrolReply{}, fmt.Errorf("cannot reach the broker at %s as %s: %w", address, node, err)
+	}
+	defer conn.Close()
+
+	channel, err := conn.Channel()
+	if err != nil {
+		return EnrolReply{}, err
+	}
+	defer channel.Close()
+
+	// This node's own queue, which its account is scoped to and nothing else may read.
+	queue, err := channel.QueueDeclare(QueueFor(node), true, false, false, false, nil)
+	if err != nil {
+		return EnrolReply{}, fmt.Errorf(
+			"cannot declare this node's queue %s: %w", QueueFor(node), err)
+	}
+
+	replies, err := channel.Consume(queue.Name, "", true, false, false, false, nil)
+	if err != nil {
+		return EnrolReply{}, err
+	}
+
+	request := EnrolRequest{Node: node, Secret: secret, PublicKey: public, Profile: profile}
+	body, err := json.Marshal(request)
+	if err != nil {
+		return EnrolReply{}, err
+	}
+
+	correlation := fmt.Sprintf("%s-%d", node, time.Now().UnixNano())
+	publish, cancel := context.WithTimeout(ctx, timeout)
+	defer cancel()
+	if err := channel.PublishWithContext(publish, Exchange, KeyEnrol, false, false,
+		amqp.Publishing{
+			ContentType:   "application/json",
+			CorrelationId: correlation,
+			ReplyTo:       queue.Name,
+			Body:          body,
+		}); err != nil {
+		return EnrolReply{}, fmt.Errorf("cannot publish to the %s exchange: %w", Exchange, err)
+	}
+
+	// Waited for rather than assumed. A published message that nothing answers means the control
+	// plane is not running, and a node that carried on regardless would believe it had joined a
+	// mesh that has never heard of it.
+	deadline := time.NewTimer(timeout)
+	defer deadline.Stop()
+	closed := conn.NotifyClose(make(chan *amqp.Error, 1))
+
+	for {
+		select {
+		case <-ctx.Done():
+			return EnrolReply{}, ctx.Err()
+		case reason := <-closed:
+			return EnrolReply{}, fmt.Errorf("the broker closed the connection: %v", reason)
+		case <-deadline.C:
+			return EnrolReply{}, fmt.Errorf(
+				"the broker accepted this node's connection and nothing answered within %s. The "+
+					"mesh's broker is running and its control plane is not", timeout)
+		case delivery, ok := <-replies:
+			if !ok {
+				return EnrolReply{}, errors.New("the broker stopped delivering")
+			}
+			// Anything else on this queue is not the answer to this question.
+			if delivery.CorrelationId != correlation {
+				continue
+			}
+			var reply EnrolReply
+			if err := json.Unmarshal(delivery.Body, &reply); err != nil {
+				return EnrolReply{}, fmt.Errorf("the mesh's answer could not be read: %w", err)
+			}
+			if !reply.Accepted {
+				return reply, fmt.Errorf("%w: %s", ErrRefused, reply.Refusal)
+			}
+			return reply, nil
+		}
+	}
+}