The view: one read-only bus user for a page in a browser, composed like every other (hq research 036)

Research 036 names the gap (G1): no way for a browser to reach the bus. The bus module now listens
over WebSocket (mesh-catalog, nats); this is who connects there. The view is a fixed principal
(broker.KindView, user `view`) composed into the user list like every user once its credential is
minted, and left out once it is forgotten: it subscribes the issue tracker's events (opened, moved,
noted, linked), the controller's plan-moved and condition-raised/changed/cleared, and the delivery
owner's transition and group; it publishes only the JetStream API requests a read-only watcher of
the tracker's bucket (mesh-issues_issues) makes — STREAM.INFO, DIRECT.GET, CONSUMER.CREATE/INFO/
DELETE, flow control — answered in its own inbox; no reply, no tool, no event, no `$KV` write.

`bus view-credential` mints and prints it once (hash kept, like a person's); `bus view-revoke`
forgets it, real at the next composition. Tests: the composed grants are exactly these and a write
grant of any shape fails; the view is composed only once minted; and against a real server read from
the composed file over WebSocket, the view binds the bucket, reads a key, watches a put land, and is
refused a put, a delete and an event, the bucket unchanged.

cmd/mesh-controller/bus_step.go

@@ -151,6 +151,13 @@ func busCommand(ctx context.Context, args []string) error {
 	if len(args) > 0 && !strings.HasPrefix(args[0], "-") {
 		sub, args = args[0], args[1:]
 	}
+	// The view's credential, a terminal line like a person's (bus_view.go).
+	switch sub {
+	case "view-credential":
+		return busViewCredential(ctx, args)
+	case "view-revoke":
+		return busViewRevoke(ctx, args)
+	}
 	set := flag.NewFlagSet("bus", flag.ContinueOnError)
 	snapshot := set.String("snapshot-taken", "", "where the streams' snapshot a person took is, while the mesh takes none itself")
 	reversible := set.Bool("reversible", false, "the new version can be undone by putting the old one back")
@@ -160,14 +167,14 @@ func busCommand(ctx context.Context, args []string) error {
 	if rest, err := parseAround(set, args); err != nil {
 		return err
 	} else if len(rest) > 0 {
-		return errors.New("bus [upgrade --why … --reversible|--irreversible [--snapshot-taken <where>]]")
+		return errors.New(busUsage)
 	}
 	switch sub {
 	case "":
 		return busStatus(ctx)
 	case "upgrade":
 	default:
-		return fmt.Errorf("bus says what a bus upgrade would do, or `bus upgrade` — not %q", sub)
+		return fmt.Errorf("bus says what a bus upgrade would do, or `bus upgrade`, `bus view-credential`, `bus view-revoke` — not %q", sub)
 	}
 	// Everything refused before anything is done.
 	if err := why.require("bus upgrade"); err != nil {

cmd/mesh-controller/bus_view.go

@@ -0,0 +1,111 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net"
+	"strconv"
+	"strings"
+
+	"github.com/novox/mesh-controller/internal/broker"
+	"github.com/novox/mesh-controller/internal/inventory"
+)
+
+// The view's credential: the one read-only user a page in a browser connects to the bus as, over the
+// bus module's WebSocket listener (novox/hq research 036, gap G1; broker.KindView).
+//
+// **A terminal line, like a person's credential** (operator.go): printed once, never stored — the mesh
+// keeps a hash — and revoked by forgetting the row, which the next composition of the user list makes
+// real. There is one view; issuing it again rotates its password.
+const busUsage = "bus [upgrade --why … --reversible|--irreversible [--snapshot-taken <where>] | view-credential | view-revoke]"
+
+// busWebSocketPort is the port the bus module's WebSocket listener is published on, mirrored from the
+// nats module's manifest (its `bus-websocket` opening), because the credential names where to connect
+// and the controller does not read the module's configuration. Reached across the overlay only: the
+// opening is from the mesh, and the mesh's filter admits nothing else.
+const busWebSocketPort = 4223
+
+func busViewCredential(ctx context.Context, args []string) error {
+	if len(args) != 0 {
+		return errors.New("bus view-credential takes nothing: there is one view, and this prints its credential once")
+	}
+	open, err := openStores(ctx)
+	if err != nil {
+		return err
+	}
+	defer open.Close()
+	inv := open.inventory
+
+	// Refused here rather than at the next composition, where it would stop the whole file.
+	if _, err := broker.PermissionsFor(broker.Principal{Kind: broker.KindView, PasswordHash: "x"}); err != nil {
+		return err
+	}
+	password, err := inv.MintBusPassword(ctx, inventory.BusUser{Username: broker.ViewUser, Kind: inventory.BusView})
+	if err != nil {
+		return err
+	}
+
+	where, err := broker.FromEnvironment()
+	if err != nil && !errors.Is(err, broker.ErrNotConfigured) {
+		return err
+	}
+	host := where.Address
+	if h, _, err := net.SplitHostPort(where.Address); err == nil {
+		host = h
+	}
+	websocket := ""
+	if host != "" {
+		websocket = "ws://" + net.JoinHostPort(host, strconv.Itoa(busWebSocketPort))
+	}
+	held, err := json.Marshal(struct {
+		WebSocket   string   `json:"websocket,omitempty"`
+		URL         string   `json:"url,omitempty"`
+		Fingerprint string   `json:"fingerprint,omitempty"`
+		User        string   `json:"user"`
+		Password    string   `json:"password"`
+		InboxPrefix string   `json:"inbox_prefix"`
+		Hears       []string `json:"hears"`
+		Reads       string   `json:"reads"`
+	}{
+		WebSocket: websocket, URL: "nats://" + where.Address, Fingerprint: where.Fingerprint,
+		User: broker.ViewUser, Password: password,
+		// The client must make its inboxes under the view's own prefix: its subscribe grant is
+		// `_INBOX.view.>` and no wider (design 25 §4), and a client's default inbox is not under it.
+		InboxPrefix: "_INBOX." + broker.ViewUser,
+		Hears:       broker.ViewHears, Reads: broker.ViewBucket,
+	})
+	if err != nil {
+		return err
+	}
+
+	fmt.Printf("issued the view, which hears %s and reads the bucket %s, and nothing else\n",
+		strings.Join(broker.ViewHears, ", "), broker.ViewBucket)
+	fmt.Println("  this is the only time the credential is printed; the mesh keeps a hash")
+	fmt.Println("  it works once the bus has been told, which is the next push to the machine holding mesh-broker;")
+	fmt.Println("  the WebSocket listener it connects through is the bus module's, live there after the bus step a person starts (`bus upgrade`)")
+	fmt.Println()
+	fmt.Println(string(held))
+	return nil
+}
+
+func busViewRevoke(ctx context.Context, args []string) error {
+	if len(args) != 0 {
+		return errors.New("bus view-revoke takes nothing: there is one view")
+	}
+	open, err := openStores(ctx)
+	if err != nil {
+		return err
+	}
+	defer open.Close()
+
+	if err := open.inventory.ForgetBusUser(ctx, broker.ViewUser); err != nil {
+		return err
+	}
+	// **Revoked at the next composition, not now** — as a person is (operator revoke): the bus's users
+	// are a file, and the credential stops working when the file no longer names it.
+	fmt.Println("the view is forgotten, and its credential stops working at the next composition — " +
+		"push the machine holding mesh-broker to make it so")
+	return nil
+}