package grants import ( "crypto/sha256" "encoding/hex" "encoding/json" "fmt" "regexp" "slices" "sort" "strings" "git.novox.be/novox/mesh-sdk/go/buscompose" "git.novox.be/novox/mesh-sdk/go/catalogue" ) // User is one bus user and its grants, as the bus module's nats_users answers them: never a password hash. type User struct { User string `json:"user"` Publish []string `json:"publish"` Subscribe []string `json:"subscribe"` AllowResponses bool `json:"allow_responses"` // Hash is the bcrypt hash the vault holds for the user (WithHashes): in memory alone, never in a digest, a compare // or the part's state, and empty for a loaded user. Hash string `json:"-"` } // WithHashes gives each user of the shadow list the hash the vault holds for it, when it holds one. func WithHashes(users []User, hashes map[string]HeldHash) []User { for i := range users { users[i].Hash = hashes[users[i].User].Hash } return users } // Credential is one user's hash as the list would carry it: whether the vault holds one, and how the user stands in the // shadow list and the loaded list. Never the hash: a bcrypt hash of the same password differs by its salt, so two hashes // say nothing compared. type Credential struct { User string `json:"user"` InShadow bool `json:"in_shadow"` Loaded bool `json:"loaded"` HashHeld bool `json:"hash_held"` Adopted bool `json:"adopted,omitempty"` // Generation is the vault's generation of the account the hash is of; zero for an adopted one. Generation int `json:"generation,omitempty"` // Would is how the list with the vault's hashes would differ from the loaded one for this user: same (a hash held, // loaded), adds (a hash held, not loaded), left-out (in the shadow list, no hash: left out for want of a // credential), loses-login (loaded, no hash held: its login would be lost) or not-composed (a hash held, loaded, // and not in the shadow list). Would string `json:"would"` } // The ways a user's line would differ. const ( WouldSame = "same" WouldAdd = "adds" WouldLeaveOut = "left-out" WouldLoseLogin = "loses-login" WouldNotComposed = "not-composed" ) // Credentials is every user's Credential, and the users of each way that differs. type Credentials struct { Users []Credential `json:"users"` HashesHeld int `json:"hashes_held"` LeftOut []string `json:"left_out"` LosesLogin []string `json:"loses_login"` Adds []string `json:"adds"` } // CredentialsOf says, of every user of the shadow and the loaded list, whether the vault holds its hash and how its line // would differ. Pure. func CredentialsOf(shadow, loaded []User, hashes map[string]HeldHash) Credentials { c := Credentials{Users: []Credential{}, LeftOut: []string{}, LosesLogin: []string{}, Adds: []string{}} rows := map[string]*Credential{} row := func(user string) *Credential { if rows[user] == nil { h, held := hashes[user] rows[user] = &Credential{User: user, HashHeld: held, Adopted: h.Adopted, Generation: h.Generation} } return rows[user] } for _, u := range shadow { row(u.User).InShadow = true } for _, u := range loaded { row(u.User).Loaded = true } for _, user := range sortedKeys(rows) { r := rows[user] switch { case r.HashHeld && r.InShadow && r.Loaded: r.Would = WouldSame case r.HashHeld && r.InShadow: r.Would = WouldAdd c.Adds = append(c.Adds, user) case r.InShadow: r.Would = WouldLeaveOut c.LeftOut = append(c.LeftOut, user) case !r.HashHeld: r.Would = WouldLoseLogin c.LosesLogin = append(c.LosesLogin, user) default: r.Would = WouldNotComposed } if r.HashHeld { c.HashesHeld++ } c.Users = append(c.Users, *r) } return c } // ComposeUsers is the shadow list: every user the composer derives from the records, with its grants. Pure. func ComposeUsers(r buscompose.Records) ([]User, error) { principals, err := buscompose.Users(r) if err != nil { return nil, err } out := make([]User, 0, len(principals)) for _, p := range principals { perms, err := buscompose.PermissionsFor(p) if err != nil { return nil, fmt.Errorf("%s: %w", p.Username(), err) } out = append(out, User{User: p.Username(), Publish: set(perms.Publish), Subscribe: set(perms.Subscribe), AllowResponses: perms.AllowResponses}) } sort.Slice(out, func(i, j int) bool { return out[i].User < out[j].User }) return out, nil } func set(in []string) []string { out := slices.Clone(in) sort.Strings(out) out = slices.Compact(out) if out == nil { out = []string{} } return out } // Digest is a list's digest, `sha256:`, over its users and grants in order. func Digest(users []User) string { raw, _ := json.Marshal(users) sum := sha256.Sum256(raw) return "sha256:" + hex.EncodeToString(sum[:]) } // LoadedUsers is the list the bus loaded, as its module's nats_users reads it from the file: every user by name, then // each one's grants in full. func LoadedUsers(c Caller) ([]User, error) { raw, err := c.Call(CallUsers, map[string]any{}) if err != nil { return nil, fmt.Errorf("%s: %w", CallUsers, err) } var names struct { Users []struct { User string `json:"user"` } `json:"users"` } if err := json.Unmarshal(unwrap(raw), &names); err != nil { return nil, fmt.Errorf("%s answered no list of users: %w", CallUsers, err) } full := map[string]User{} ask := func(part string) error { raw, err := c.Call(CallUsers, map[string]any{"user": part}) if err != nil { return fmt.Errorf("%s %s: %w", CallUsers, part, err) } var got struct { Users []User `json:"users"` } if err := json.Unmarshal(unwrap(raw), &got); err != nil { return fmt.Errorf("%s %s answered no grants: %w", CallUsers, part, err) } for _, u := range got.Users { u.Publish, u.Subscribe = set(u.Publish), set(u.Subscribe) full[u.User] = u } return nil } // Every name with a dot in one call; each name without one (the controller) alone. if err := ask("."); err != nil { return nil, err } out := make([]User, 0, len(names.Users)) for _, n := range names.Users { if _, ok := full[n.User]; !ok { if err := ask(n.User); err != nil { return nil, err } } u, ok := full[n.User] if !ok { return nil, fmt.Errorf("%s names %s and gives no grants for it", CallUsers, n.User) } out = append(out, u) } sort.Slice(out, func(i, j int) bool { return out[i].User < out[j].User }) return out, nil } // unwrap takes a tool's answer out of an MCP content wrapper, when a runtime hands one. func unwrap(raw json.RawMessage) []byte { var wrapped struct { Content []struct { Text string `json:"text"` } `json:"content"` } if json.Unmarshal(raw, &wrapped) == nil && len(wrapped.Content) == 1 && wrapped.Content[0].Text != "" { return []byte(wrapped.Content[0].Text) } return raw } // UserDiff is how one user's grants differ: what the shadow list grants that the loaded list does not, and back. type UserDiff struct { User string `json:"user"` PublishAdded []string `json:"publish_added,omitempty"` PublishDropped []string `json:"publish_dropped,omitempty"` SubscribeAdded []string `json:"subscribe_added,omitempty"` SubscribeDropped []string `json:"subscribe_dropped,omitempty"` Responses string `json:"responses,omitempty"` } // Comparison is the shadow list against the loaded list. type Comparison struct { Shadow int `json:"shadow"` Loaded int `json:"loaded"` // Added are users in the shadow list the loaded list lacks (one left out for want of a credential among them); // Dropped are loaded users the shadow list lacks; Gone are those of Dropped whose machine or module placement no // longer names, which both lists agree are gone. Added []string `json:"added"` Dropped []string `json:"dropped"` Gone []string `json:"gone,omitempty"` Differ []UserDiff `json:"differ"` // Excused are the subjects the comparison does not count, each with why (Comparison.Excusing). Excused []Excuse `json:"excused,omitempty"` Same int `json:"same"` // Unread says the loaded list could not be read, and why: nothing is compared then. Unread string `json:"unread,omitempty"` } // Equal says the two lists agree in every user, but those both agree are gone. func (c Comparison) Equal() bool { return c.Unread == "" && len(c.Added) == 0 && len(c.Differ) == 0 && len(c.Dropped) == len(c.Gone) } // Differing names every user that keeps the lists apart: added, dropped and not gone, or granted otherwise. func (c Comparison) Differing() []string { var out []string out = append(out, c.Added...) for _, d := range c.Dropped { if !slices.Contains(c.Gone, d) { out = append(out, d) } } for _, d := range c.Differ { out = append(out, d.User) } sort.Strings(out) return out } // Compare compares the shadow list with the loaded one. placed says whether placement still names a loaded user's // machine and module; nil names every one. Pure. func Compare(shadow, loaded []User, placed func(user string) bool) Comparison { c := Comparison{Shadow: len(shadow), Loaded: len(loaded), Added: []string{}, Dropped: []string{}, Differ: []UserDiff{}} have := map[string]User{} for _, u := range loaded { have[u.User] = u } want := map[string]bool{} for _, s := range shadow { want[s.User] = true l, ok := have[s.User] if !ok { c.Added = append(c.Added, s.User) continue } d := UserDiff{User: s.User, PublishAdded: minus(s.Publish, l.Publish), PublishDropped: minus(l.Publish, s.Publish), SubscribeAdded: minus(s.Subscribe, l.Subscribe), SubscribeDropped: minus(l.Subscribe, s.Subscribe)} if s.AllowResponses != l.AllowResponses { d.Responses = fmt.Sprintf("shadow %v, loaded %v", s.AllowResponses, l.AllowResponses) } if len(d.PublishAdded)+len(d.PublishDropped)+len(d.SubscribeAdded)+len(d.SubscribeDropped) == 0 && d.Responses == "" { c.Same++ continue } c.Differ = append(c.Differ, d) } for _, l := range loaded { if !want[l.User] { c.Dropped = append(c.Dropped, l.User) if placed != nil && !placed(l.User) { c.Gone = append(c.Gone, l.User) } } } return c } func minus(a, b []string) []string { var out []string for _, x := range a { if !slices.Contains(b, x) { out = append(out, x) } } return out } // Placed says whether placement still names a user's machine and module: a machine's users (`node.`, // `provisioner.`) while the machine is seen, a module's or process's (`.[.]`) while the module is // assigned there. The controller, enrolment users and persons are never judged gone from here. func Placed(in Inputs) func(user string) bool { return func(user string) bool { parts := strings.Split(user, ".") switch { case len(parts) < 2: return true case parts[0] == "node" || parts[0] == "provisioner": return slices.Contains(in.Nodes, parts[1]) case parts[0] == "person" || parts[0] == "enrol": return true } return slices.Contains(in.Nodes, parts[0]) && slices.Contains(in.Assigned[parts[0]], parts[1]) } } // Excuse is one subject the comparison does not count as a difference between the lists, and why. type Excuse struct { User string `json:"user"` Subject string `json:"subject"` Why string `json:"why"` } // Excusing removes from the differences the subjects f excuses (added: the shadow grants it and the loaded list does not), // naming each in Excused; a user left with no difference counts as the same. Pure. func (c Comparison) Excusing(f func(user, subject string, added, subscribe bool) string) Comparison { var differ []UserDiff for _, d := range c.Differ { keep := func(list []string, added, subscribe bool) []string { var out []string for _, s := range list { if why := f(d.User, s, added, subscribe); why != "" { c.Excused = append(c.Excused, Excuse{User: d.User, Subject: s, Why: why}) continue } out = append(out, s) } return out } d.PublishAdded, d.PublishDropped = keep(d.PublishAdded, true, false), keep(d.PublishDropped, false, false) d.SubscribeAdded, d.SubscribeDropped = keep(d.SubscribeAdded, true, true), keep(d.SubscribeDropped, false, true) if len(d.PublishAdded)+len(d.PublishDropped)+len(d.SubscribeAdded)+len(d.SubscribeDropped) == 0 && d.Responses == "" { c.Same++ continue } differ = append(differ, d) } if differ == nil { differ = []UserDiff{} } c.Differ = differ return c } // seatSubject is a seat verb's subject, for any caller (`.*`) or one machine's (`.`, a seat of every node). var seatSubject = regexp.MustCompile(`^mesh\.seat\.([^.]+)\.(?:call|tool)\.([^.]+)(?:\.[^.]+)?$`) var seatService = regexp.MustCompile(`^\$SRV\.(?:INFO|PING|STATS)\.([^.]+)(?:\.>)?$`) // ExcusedBy is the excuse of a comparison until placement lives in the catalogue (the operator, 2026-10-26): a verb the // seat catalogue retired on purpose, which the shadow no longer grants, is no difference; and what the shadow grants more // for a mesh seat that is claimed on several machines (the standing gap seat holdings: it composes the seat as held on each) // is named and not counted, for a user on a machine that claims the seat and only as a subscription (what it serves), since // a subscription to a seat's verbs on a machine whose holder does not answer them harms nothing and is gone when holdings // follow the catalogue. Nothing else is excused: an added publish, a grant of a user on another machine, or the loss of any // other subject, keeps the lists apart. func ExcusedBy(multiHeld map[string][]string) func(user, subject string, added, subscribe bool) string { // holds says the user is on a machine where the seat is claimed: the machine's tool runner, or a module of it. holds := func(user, seat string) bool { node, _, _ := strings.Cut(user, ".") return slices.Contains(multiHeld[seat], node) } return func(user, subject string, added, subscribe bool) string { if m := seatSubject.FindStringSubmatch(subject); m != nil { if !added && subscribe && retiredVerb(m[1], m[2]) { return "a verb the seat catalogue retired" } if added && subscribe && holds(user, m[1]) { return "seat " + m[1] + " is claimed on several machines: composed as held on each until holdings follow the catalogue" } } if m := seatService.FindStringSubmatch(subject); m != nil && added && subscribe && holds(user, m[1]) { return "seat " + m[1] + " is claimed on several machines: composed as held on each until holdings follow the catalogue" } return "" } } // MultiHeld are the mesh seats (held once for the mesh) that more than one machine's module claims, each with the // machines that claim it. func MultiHeld(r buscompose.Records) map[string][]string { nodes := map[string][]string{} for node, declared := range r.Assigned { for _, d := range declared { for _, s := range d.Holds { if (s.Scope == "" || s.Scope == catalogue.ScopeMesh) && !slices.Contains(nodes[s.Name], node) { nodes[s.Name] = append(nodes[s.Name], node) } } } } for seat, ns := range nodes { if len(ns) < 2 { delete(nodes, seat) continue } sort.Strings(ns) } return nodes }