A person may be issued, listed and revoked

Design 25 §7's first item, which existed as a permission model and as nothing a person
could actually be given. There is a record now, and three commands.

Their authority is a list of tools and nothing else. Not a module: they hold no seat,
nothing is addressed to them, nothing is delivered to them, and they have no consumer to
acknowledge. What they have is permission to ask — which is why there is no scope and no
node in the record.

Stating what somebody may call replaces what was there rather than adding to it: a list
that could only grow is a permission nobody can take back. Forgetting somebody takes
their credential with them, because a person's row gone with their bus user left behind
is a credential that still works and that nothing derives — the worst of both, since it
keeps working and nobody can explain why.

The credential is printed once and the mesh keeps only a hash, the same contract a token
has. And it starts working at the next composition rather than immediately, because the
bus's users are a file — said out loud in both the issue and the revoke messages, since
"revoked" that still works for another minute is worth knowing about.

Four properties held by test, each a way of being wrong that would not announce itself:
a person may publish exactly the tool subjects they were given and nothing on control,
nodes or events; they cannot answer a request; changing the list removes what is no longer
named; and forgetting them revokes them.

cmd/mesh-controller/operator.go

@@ -2,12 +2,15 @@ package main
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"flag"
 	"fmt"
 	"os"
 	"strings"
 
+	"github.com/novox/mesh-controller/internal/broker"
+	"github.com/novox/mesh-controller/internal/inventory"
 	"github.com/novox/mesh-controller/internal/secrets"
 )
 
@@ -26,9 +29,25 @@ import (
 //	operator key make [--out <file>]    make a keypair: private half to the file, public half printed
 //	operator key set <public>           tell the mesh which key to seal to
 //	operator key show                   the public key, its fingerprint, and what it can recover
-const operatorUsage = "operator key make [--out <file>] | operator key set <public> [--replace] | operator key show"
+const operatorUsage = "operator key make [--out <file>] | operator key set <public> [--replace] | " +
+	"operator key show | operator issue <name> --invokes <tool,tool|*> | operator revoke <name> | " +
+	"operator list"
 
 func operatorCommand(ctx context.Context, args []string) error {
+	if len(args) == 0 {
+		return errors.New(operatorUsage)
+	}
+	// The people who may reach the mesh's tools (design 25 §7). Beside the operator's key because
+	// both answer "who, other than a machine, may do something here" — and a person reading this
+	// command's usage is asking exactly that.
+	switch args[0] {
+	case "issue":
+		return personIssue(ctx, args[1:])
+	case "revoke":
+		return personRevoke(ctx, args[1:])
+	case "list":
+		return personList(ctx)
+	}
 	if len(args) < 2 || args[0] != "key" {
 		return errors.New(operatorUsage)
 	}
@@ -160,3 +179,125 @@ func readPrivateKey(path string) (string, error) {
 	}
 	return strings.TrimSpace(string(raw)), nil
 }
+
+// personIssue gives somebody a credential for the mesh's tools, and prints it once.
+//
+// **Printed, not stored.** The mesh keeps a hash and nothing else, so this is the only moment the
+// credential exists anywhere but on the workstation that will use it — the same contract a token has,
+// and for the same reason: a credential recoverable from the mesh's store has the store's blast
+// radius.
+func personIssue(ctx context.Context, args []string) error {
+	set := flag.NewFlagSet("operator issue", flag.ContinueOnError)
+	invokes := set.String("invokes", "", "the tools this person may call, comma-separated, or * for every one")
+	if err := set.Parse(args); err != nil {
+		return err
+	}
+	if set.NArg() != 1 {
+		return errors.New("operator issue <name> --invokes <tool,tool|*>")
+	}
+	name := set.Arg(0)
+	if *invokes == "" {
+		return errors.New(
+			"say what this person may call: --invokes mesh-catalog.catalog_tools,gitea.repo_create, " +
+				"or --invokes '*' for an administrator")
+	}
+	var tools []string
+	for _, t := range strings.Split(*invokes, ",") {
+		if t = strings.TrimSpace(t); t != "" {
+			tools = append(tools, t)
+		}
+	}
+
+	open, err := openStores(ctx)
+	if err != nil {
+		return err
+	}
+	defer open.Close()
+	inv := open.inventory
+
+	if err := inv.RecordPerson(ctx, inventory.Person{Name: name, Invokes: tools}); err != nil {
+		return err
+	}
+	// Refused here rather than at the next composition, where it would stop the whole file being
+	// written for everybody. A name that cannot be part of a subject is one the server would read as
+	// a wider permission than anybody granted.
+	if _, err := broker.PermissionsFor(broker.Principal{
+		Kind: broker.KindPerson, Module: name, Invokes: tools, PasswordHash: "x",
+	}); err != nil {
+		return err
+	}
+
+	user := broker.Principal{Kind: broker.KindPerson, Module: name}.Username()
+	password, err := inv.MintBusPassword(ctx, inventory.BusUser{Username: user, Kind: inventory.BusPerson})
+	if err != nil {
+		return err
+	}
+
+	where, err := broker.FromEnvironment()
+	if err != nil && !errors.Is(err, broker.ErrNotConfigured) {
+		return err
+	}
+	held, err := json.Marshal(struct {
+		URL         string   `json:"url"`
+		Fingerprint string   `json:"fingerprint,omitempty"`
+		User        string   `json:"user"`
+		Password    string   `json:"password"`
+		Person      string   `json:"person"`
+		Invokes     []string `json:"invokes"`
+	}{
+		URL: "nats://" + where.Address, Fingerprint: where.Fingerprint,
+		User: user, Password: password, Person: name, Invokes: tools,
+	})
+	if err != nil {
+		return err
+	}
+
+	fmt.Printf("issued %s, who may call %s\n", name, strings.Join(tools, ", "))
+	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()
+	fmt.Println(string(held))
+	return nil
+}
+
+func personRevoke(ctx context.Context, args []string) error {
+	if len(args) != 1 {
+		return errors.New("operator revoke <name>")
+	}
+	open, err := openStores(ctx)
+	if err != nil {
+		return err
+	}
+	defer open.Close()
+
+	if err := open.inventory.ForgetPerson(ctx, args[0]); err != nil {
+		return err
+	}
+	// **Revoked at the next composition, not now.** The bus's users are a file, so a credential stops
+	// working when the file no longer names it. Said plainly, because "revoked" that still works for
+	// another minute is worth knowing about.
+	fmt.Printf("%s is forgotten, and their credential stops working at the next composition — "+
+		"push the machine holding mesh-broker to make it so\n", args[0])
+	return nil
+}
+
+func personList(ctx context.Context) error {
+	open, err := openStores(ctx)
+	if err != nil {
+		return err
+	}
+	defer open.Close()
+
+	people, err := open.inventory.People(ctx)
+	if err != nil {
+		return err
+	}
+	if len(people) == 0 {
+		fmt.Println("nobody but machines reaches this mesh")
+		return nil
+	}
+	for _, p := range people {
+		fmt.Printf("%-20s %s\n", p.Name, strings.Join(p.Invokes, ", "))
+	}
+	return nil
+}