node hand-over: the terminal hands a directory used as found to the mesh, asked of the node's engine (hq issue 356)

A module's condition told the operator to run the node-engine's hand-over at the machine, as root (issue 339), and the mesh had no channel for it. Now node hand-over <node> <path> is the controller's terminal's — a node subcommand that is not a read, so every verb and mesh-cli outside the terminal refuse it — and asks that node's engine on mesh.node.<node>.ask.hand-over, a request only the controller may publish and only that node's engine may hear and answer (its grant gains the subject and the right to answer what it was asked). The line's node and path are judged before anything is asked; the engine's answer is printed, a refusal as a refusal. Every text addressed to the operator names the nox line (ADR 0272); the condition's words stay plain.

internal/broker/nats.go

@@ -289,6 +289,11 @@ func (p Principal) Username() string {
 // (novox/hq to-be 45 §6): its answer is an ordinary report, on its own report subject.
 func AskReportSubject(node string) string { return "mesh.node." + node + ".ask.report" }
 
+// AskHandOverSubject is where the controller's terminal asks one machine's node-engine to hand a directory it
+// uses as found to the mesh (novox/hq issue 356, issue 339): a request on core NATS, answered once on the reply
+// it carries. Only the controller publishes under `mesh.node.`, so the engine hears nobody else.
+func AskHandOverSubject(node string) string { return "mesh.node." + node + ".ask.hand-over" }
+
 // inbox is a principal's own reply space. No user is ever granted a bare `_INBOX.>` (design 25
 // §4): with one account, inbox privacy is the permission list or it is nothing, so each user's
 // inbox is derived from its own identity and its permissions name that prefix and no other.
@@ -562,7 +567,10 @@ func PermissionsFor(p Principal) (Permissions, error) {
 			// And the mesh asking it to say again what it last applied (novox/hq to-be 45 §6, the
 			// `report` verb healer H1 asks): its own machine's, on core NATS and off any stream. It
 			// answers through its report, the one thing it already says — no reply to anybody's inbox.
-			AskReportSubject(p.Node)}
+			AskReportSubject(p.Node),
+			// And the controller's terminal asking it to hand a directory used as found to the mesh (novox/hq
+			// issue 356), which it answers on the request's reply: the one request a node is asked.
+			AskHandOverSubject(p.Node)}
 		// The node-engine witnesses the core builds it places (novox/hq to-be 45 §8, ADR 0236; the
 		// contract is lease/witness.go): it asks its own machine's node tools PING, and, where the
 		// machine runs the controller, reads the lease's one key — read, never written.
@@ -863,9 +871,10 @@ func PermissionsFor(p Principal) (Permissions, error) {
 		PublishDeny: deny,
 		Subscribe:   sub,
 		// A module answers what it was asked — a tool call reaches it on its own namespace, so the
-		// authority is bounded by having been asked — and so does the controller. A node and a
-		// person are never asked anything, and are granted nothing here.
-		AllowResponses: p.Kind == KindModule || p.Kind == KindController || p.Kind == KindNodeTools,
+		// authority is bounded by having been asked — and so does the controller. A node is asked one
+		// thing, a hand-over on its own subject (novox/hq issue 356), and answers that. A person is never
+		// asked anything, and is granted nothing here.
+		AllowResponses: p.Kind == KindModule || p.Kind == KindController || p.Kind == KindNodeTools || p.Kind == KindNode,
 	}, nil
 }
 

internal/broker/nats_test.go

@@ -103,7 +103,8 @@ func TestAnInboxIsScopedToItsOwner(t *testing.T) {
 
 // A responder answers on the caller's inbox, which it has no permission for. allow_responses is
 // what makes a scoped inbox workable at all — the authority is bounded by having been asked. A
-// module is asked on its own namespace and may answer; a node and a person are never asked.
+// module is asked on its own namespace and may answer; a node is asked one thing, a hand-over on its own
+// subject (novox/hq issue 356), and may answer that; a person is never asked.
 func TestOnlyWhatCanBeAskedMayAnswer(t *testing.T) {
 	module, _ := PermissionsFor(Principal{Kind: KindModule, Node: "one", Module: "audit",
 		Consumes: []string{"shop.order.placed"}, PasswordHash: "x"})
@@ -111,8 +112,12 @@ func TestOnlyWhatCanBeAskedMayAnswer(t *testing.T) {
 		t.Fatal("a module cannot answer a tool call on its own namespace")
 	}
 	node, _ := PermissionsFor(Principal{Kind: KindNode, Node: "one", PasswordHash: "x"})
-	if node.AllowResponses {
-		t.Fatal("a node was granted the right to answer, and nothing asks a node anything")
+	if !node.AllowResponses || !slices.Contains(node.Subscribe, AskHandOverSubject("one")) {
+		t.Fatalf("a node cannot answer the hand-over it is asked: %v %v", node.AllowResponses, node.Subscribe)
+	}
+	person, _ := PermissionsFor(Principal{Kind: KindPerson, Node: "one", Module: "jo", PasswordHash: "x"})
+	if person.AllowResponses {
+		t.Fatal("a person was granted the right to answer, and nothing asks a person anything")
 	}
 }
 

internal/broker/testdata/composed.conf

@@ -34,7 +34,8 @@ accounts {
       } }
       { user: "node.one", password: "$2a$11$nnnnnnnnnnnnnnnnnnnnnn", permissions: {
         publish: { allow: ["$JS.ACK.NODES.one.>", "$JS.API.CONSUMER.INFO.NODES.one", "$SRV.PING.node-tools.one", "mesh.control.one.>"] }
-        subscribe: { allow: ["_DELIVER.one", "_DELIVER.one.>", "_INBOX.node.one.>", "mesh.node.one.ask.report", "mesh.node.one.declare"] }
+        subscribe: { allow: ["_DELIVER.one", "_DELIVER.one.>", "_INBOX.node.one.>", "mesh.node.one.ask.hand-over", "mesh.node.one.ask.report", "mesh.node.one.declare"] }
+        allow_responses: { max: 1, ttl: "1m" }
       } }
       { user: "one.nats", password: "$2a$11$bbbbbbbbbbbbbbbbbbbbbb", permissions: {
         publish: { allow: ["$JS.API.STREAM.INFO.*", "$JS.API.STREAM.NAMES", "$JS.API.STREAM.SNAPSHOT.*", "$JS.SNAPSHOT.ACK.>"] }