package grants import ( "encoding/json" "fmt" "slices" "sort" "strings" occ "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/clients/operatorchannelclient" oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel" "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient" "git.novox.be/novox/mesh-delivery/modules/mesh-grants/grantsstate" "git.novox.be/novox/mesh-networking/modules/mesh-wireguard/go/overlay" "git.novox.be/novox/mesh-sdk/go/keys" "mesh-grants/internal/buscompose" ) // **The grants the part writes** (novox/hq ADR 0547 §4, §5, ADR 0561 §2, §6; issue 774). A module's grant is the record // that its bus credential exists for the fingerprint the catalogue's trunk names for it: `.` in // the part's state grants, naming the accounts (the module's own and each process's) the vault holds a hash for. It is the // grant the controller composed (cmd/mesh-controller grants.go grantsFrom), whose readers it took over; the assigner reads // the part's keys alone since the controller ended by its unassignment (ADR 0590, issue 1126). // // A module of which an account has no hash yet is granted the accounts that have one; a module none of whose accounts has // one has no grant, and one it was written for is deleted (an older grant naming a node whose account is gone would let the // assigner want it, and a grant naming no account names every node). Nothing else is ever deleted, and nothing is written // or deleted in a pass that could not read the vault's hashes, the indexer's modules or a manifest of the module. // GrantsWritten is what one pass did to the state grants. type GrantsWritten struct { Wanted int `json:"wanted"` Written []string `json:"written,omitempty"` Deleted []string `json:"deleted,omitempty"` // Kept says why a pass wrote and deleted nothing, or left a module out. Kept []string `json:"kept,omitempty"` // Missing is each module the assignments or an assignment puts on a machine that has no grant after the pass, // `: `: the assigner's sixth rule wants none of it (MissingGrants). Never passed over in silence: once // the part's grants are the ones read, it is the condition mesh-grants.grant-missing. Missing []string `json:"missing,omitempty"` // Waits is each grant composed and not written, `: `: a grant is new or changed only once the // list the bus loaded carries it (issue 774, GrantWaits). Read with grants_grants (last_pass). Waits []string `json:"waits,omitempty"` } // GrantWaits says why a grant composed now, new or changed, is not written yet, or "" when it may be (issue 774). The // assigner moves a module's want to the fingerprint once its grant is there, so the grant is the word that the list the bus // has loaded already carries the module's accounts as composed now (composed, from ListRecords: what runs and what the trunk // names): every publish and subscribe allowed, the allowance of responses, and no deny the composed account lacks. A grant // that adds no permission is written at once, whatever list is held or pending; one that adds any waits until a list that // carries it is loaded. loaded is the loaded list by user, nil when its contents are unknown (unknown says why): then only // a grant naming no account is written. Pure. func GrantWaits(accounts []string, composed, loaded map[string]User, unknown string) string { if len(accounts) == 0 { return "" } if loaded == nil { return "waits: the contents of the list the bus loaded are unknown (" + unknown + "), so no grant adding an account is written" } var adds []string for _, user := range accounts { c, ok := composed[user] if !ok { continue } l, ok := loaded[user] if !ok { adds = append(adds, user+" (not in the loaded list)") continue } // By what a permission allows, not by its text: a subject a loaded one covers is carried (`>` covers every one), and // answering requests is carried where the loaded user may publish every subject (2026-11-16: every grant waited on // "1 permissions" that the loaded `>` already gave). n := len(notAllowed(c.Publish, l.Publish)) + len(notAllowed(c.Subscribe, l.Subscribe)) if c.AllowResponses && !l.AllowResponses && len(notAllowed([]string{">"}, l.Publish)) > 0 { n++ } if l.PublishDeny != nil { n += len(minus(l.PublishDeny, c.PublishDeny)) } n += len(minus(l.SubscribeDeny, c.SubscribeDeny)) if n > 0 { adds = append(adds, fmt.Sprintf("%s (%d permissions)", user, n)) } } if len(adds) == 0 { return "" } return "waits for the bus to load a list carrying what it adds: " + strings.Join(adds, ", ") } // notAllowed is each subject of a that no subject of b covers. func notAllowed(a, b []string) []string { var out []string for _, x := range a { if !slices.ContainsFunc(b, func(y string) bool { return subjectCovers(y, x) }) { out = append(out, x) } } return out } // subjectCovers says whether the permission pattern p allows every subject the permission s allows, by the bus's wildcards: // `*` one token, `>` one or more tokens at the end. func subjectCovers(p, s string) bool { pt, st := strings.Split(p, "."), strings.Split(s, ".") for i, t := range pt { if t == ">" { return len(st) > i } if i >= len(st) { return false } switch { case t == "*": if st[i] == ">" { return false } case t != st[i]: return false } } return len(pt) == len(st) } // **The permissions of each list the part sealed, one key per user** (issue 774, sweep 2026-10-30 item 5): the last two // lists, by digest, each user's permissions as sealed, never a hash: what tells which grants the list the bus loaded // carries, without the bus module's tools. One value holding every user of two lists outgrew the bucket's largest value // (JetStream 10054, "message size exceeds maximum", 16:37 and 16:55 on 2026-10-30), so a list's permissions were never // kept and a grant judged against them waited. Each user's permissions are a key of their own, // `sealed-grants..`, which grows with that user alone; the key `sealed-lists` names the lists kept and // their users, and is written only once every user's key of its newest list is: it never names a list whose keys are not // all there. // KeySealedGrants is the key that held every user of the last two lists in one value, before this release: read when the // index names no list, and taken away once the index is written. const KeySealedGrants = "sealed-grants" // KeySealedLists is the key of the state user-list naming the sealed lists whose permissions are kept, newest first. const KeySealedLists = "sealed-lists" // sealedKept is how many sealed lists keep their permissions: the one in force and the one before. const sealedKept = 2 // SealedGrants is the value KeySealedGrants held. type SealedGrants struct { Lists []SealedList `json:"lists"` } // SealedList is one sealed list's users and their permissions. type SealedList struct { Digest string `json:"digest"` Users []User `json:"users"` } // SealedLists is the value of KeySealedLists: the lists kept, newest first, each by its digest and its users' names. type SealedLists struct { Lists []SealedNames `json:"lists"` } // SealedNames is one kept list: its digest and its users, sorted. type SealedNames struct { Digest string `json:"digest"` Users []string `json:"users"` } // SealedUserKey is the key of one user's permissions in the sealed list of digest. func SealedUserKey(digest, user string) string { return KeySealedGrants + "." + strings.TrimPrefix(digest, "sha256:") + "." + user } // keepSealedGrants records the permissions of the list sealed now, one key per user, beside the list before; the lists // older than those two lose their keys, purged with every value they kept (purge.go: a delete left them in the bucket). func (p *Part) keepSealedGrants(res *Result, digest string, list []byte, composed []User) { in := listUsers(list) var users []User for _, u := range composed { if slices.Contains(in, u.User) { u.Hash = "" users = append(users, u) } } failed := false names := make([]string, 0, len(users)) for _, u := range users { names = append(names, u.User) data, _ := json.Marshal(u) if _, err := p.Store.Put(StateUserList, SealedUserKey(digest, u.User), data); err != nil { failed = true res.Errors = append(res.Errors, fmt.Sprintf("its own %s %s cannot be written: %v", StateUserList, SealedUserKey(digest, u.User), err)) } } if failed { // The index keeps naming the lists whose keys are all there; this list's permissions are not kept. return } sort.Strings(names) was := p.sealedLists() next := SealedLists{Lists: []SealedNames{{Digest: digest, Users: names}}} var gone []SealedNames for _, l := range was.Lists { switch { case l.Digest == digest: case len(next.Lists) < sealedKept: next.Lists = append(next.Lists, l) default: gone = append(gone, l) } } data, _ := json.Marshal(next) if _, err := p.Store.Put(StateUserList, KeySealedLists, data); err != nil { res.Errors = append(res.Errors, fmt.Sprintf("its own %s %s cannot be written: %v", StateUserList, KeySealedLists, err)) return } for _, l := range gone { for _, user := range l.Users { if err := p.takeAway(StateUserList, SealedUserKey(l.Digest, user)); err != nil { res.Errors = append(res.Errors, fmt.Sprintf("its own %s %s cannot be taken away: %v", StateUserList, SealedUserKey(l.Digest, user), err)) } } } if _, _, found, err := p.Store.Get(StateUserList, KeySealedGrants); err == nil && found { if err := p.takeAway(StateUserList, KeySealedGrants); err != nil { res.Errors = append(res.Errors, fmt.Sprintf("its own %s %s cannot be taken away: %v", StateUserList, KeySealedGrants, err)) } } } // sealedLists is the index of kept lists; none when it cannot be read. func (p *Part) sealedLists() SealedLists { var out SealedLists if raw, _, found, err := p.Store.Get(StateUserList, KeySealedLists); err == nil && found { _ = json.Unmarshal(raw, &out) } return out } // sealedGrantsOf is the permissions of each user of the sealed list of digest, as the part kept them, and whether it kept // every one: from the index and each user's key, else from the one value written before this release. func (p *Part) sealedGrantsOf(digest string) (map[string]User, bool) { for _, l := range p.sealedLists().Lists { if l.Digest != digest { continue } out := map[string]User{} for _, user := range l.Users { raw, _, found, err := p.Store.Get(StateUserList, SealedUserKey(digest, user)) if err != nil || !found { return nil, false } var u User if json.Unmarshal(raw, &u) != nil { return nil, false } out[u.User] = u } return out, true } raw, _, found, err := p.Store.Get(StateUserList, KeySealedGrants) if err == nil && found { var sg SealedGrants if json.Unmarshal(raw, &sg) == nil { for _, sl := range sg.Lists { if sl.Digest == digest { out := map[string]User{} for _, u := range sl.Users { out[u.User] = u } return out, true } } } } return nil, false } // loadedContents is the list the bus loaded, by user: as the bus module's nats_users read it, else as the part sealed the // list of the digest the bus node says it loaded from the part's key; nil and why when neither says. func (p *Part) loadedContents(in Inputs, read []User, readErr error) (map[string]User, string) { byUser := func(us []User) map[string]User { out := map[string]User{} for _, u := range us { out[u.User] = u } return out } if readErr == nil { return byUser(read), "" } l := in.Loaded switch { case l == nil: return nil, "the bus node says no loaded list, and nats_users: " + readErr.Error() case l.Source != grantsstate.GrantsUserListSource || l.Follows != grantsstate.FollowGrants || l.Error != "": return nil, "the bus loaded no list of the grants part's (source " + l.Source + ", follows " + l.Follows + "), and nats_users: " + readErr.Error() } if kept, ok := p.sealedGrantsOf(l.Digest); ok { return kept, "" } return nil, "the part keeps no permissions of the loaded list " + short(l.Digest) + " (sealed before it kept them), and nats_users: " + readErr.Error() } // GrantMissingCondition is the key of the warning raised while a placed module has no grant (issue 1126). const GrantMissingCondition = "mesh-grants.grant-missing" // MissingGrants is each module assigned or placed on a machine that want leaves without a grant, `: `, // sorted, but a module the mesh provides itself, which is never wanted by fingerprint: its manifest refused (skip), no fingerprint of the new form at the indexer's trunk, or no account with a hash // in the vault (drop). **The fingerprint is the indexer's, never a commit's** (issue 1126: link2pay, snake, f1-circuits // and txt-game, whose source commit has not moved since a build of the old form, have a done key of the new form at it, // and that is the fingerprint granted). Pure. func MissingGrants(in Inputs, want map[string]grantsstate.Grant, drop []string, skip map[string]bool) []string { placed := map[string]bool{} for _, ms := range in.Assigned { for _, m := range ms { placed[m] = true } } var out []string for _, module := range sortedKeys(placed) { // A module the mesh provides itself (the private network) is built by no repository, so the indexer holds no // fingerprint of it and the assigner wants none: the controller composes it with the node's own. It needs no grant, // and naming it missing raised a warning nothing could clear (sweep 2026-10-30 item 6). if overlay.ProvidedByMesh(module) { continue } fp, has := in.Fingerprints[module] key, err := grantsstate.PartGrantKey(module, fp) if has && err == nil { if _, granted := want[key]; granted { continue } } why := "" switch { case skip[module]: why = "its manifest at the indexer's trunk is refused" case !has: why = "no fingerprint of the new form: " + orSaid(in.NoFingerprint[module], "the indexer holds no value of it") case err != nil: why = fmt.Sprintf("no grant key for %s: %v", fp, err) case slices.Contains(drop, key): why = "none of its accounts at " + fp + " has a hash in the vault" default: why = "no grant composed at " + fp } out = append(out, module+": "+why) } return out } func orSaid(s, none string) string { if s == "" { return none } return s } // sayMissing raises mesh-grants.grant-missing while a placed module has no grant (the part's grants are the ones the // assigner reads since the controller's end, issue 1126), and clears it when every one has one. Said once per set, again // when it changes, and always at the first pass after a start. func (p *Part) sayMissing(missing []string) { if p.Say == nil { return } why := "" if len(missing) > 0 { why = strings.Join(missing, "; ") } p.holdMu.Lock() defer p.holdMu.Unlock() if p.missingKnown && why == p.missingSaid { return } c := oc.Condition{Key: GrantMissingCondition, Subject: oc.ConditionSubject{Scope: "module", ID: "mesh-grants"}} if why == "" { c.State = occ.StateCleared } else { c.Severity, c.State = occ.SeverityWarning, occ.StateRaised c.Summary = fmt.Sprintf("%d placed module(s) have no grant, so no want can name them", len(missing)) c.Headline = "A placed module has no bus grant" needsYou(&c, "a look at why each has none", "The grants part wrote no grant for these modules, so the assigner's "+ "credential rule gives them no want: "+why) c.Resolved = "every placed module has a grant at the fingerprint the indexer names" } if p.Say(c) == nil { p.missingSaid, p.missingKnown = why, true } } // GrantsOf is the grant of every module at the fingerprint the indexer's trunk names for it, by key, and the keys that // have none (drop): see the comment above. A module in skip (its manifest was refused) is neither. Pure. func GrantsOf(in Inputs, recs buscompose.Records, skip map[string]bool) (map[string]grantsstate.Grant, []string, error) { principals, err := buscompose.Users(recs) if err != nil { return nil, nil, err } accounts, missing := map[string][]string{}, map[string]bool{} for _, p := range principals { if p.Module == "" || (p.Kind != buscompose.KindModule && p.Kind != buscompose.KindProcess) { continue } if in.Hashes[p.Username()].Hash == "" { missing[p.Module] = true continue } accounts[p.Module] = append(accounts[p.Module], p.Username()) } out := map[string]grantsstate.Grant{} var drop []string for module, fp := range in.Fingerprints { if skip[module] || !strings.HasPrefix(fp, meshcatalogclient.SourcePrefix2) { continue } key, err := grantsstate.PartGrantKey(module, fp) if err != nil { continue } names := accounts[module] if missing[module] && len(names) == 0 { drop = append(drop, key) continue } sort.Strings(names) out[key] = grantsstate.Grant{Accounts: names} } sort.Strings(drop) return out, drop, nil } // grantsReadFailed names a read of this pass without which no grant is written: the hashes and the indexer's modules and // manifests. A manifest refused for one module only leaves that module out (writeGrants). func grantsReadFailed(in Inputs) string { for _, g := range in.Gaps { if !g.Failed { continue } for _, input := range []string{ReadAccounts, ReadModules, ReadManifests} { if strings.HasPrefix(g.Input, input) { return g.Input + ": " + g.Why } } } return "" } // writeGrants writes each grant whose key is absent or differs and says grant-written for each, and deletes the key of a // module that has none now. func (p *Part) writeGrants(res *Result, in Inputs, recs buscompose.Records, composed []User, loaded map[string]User, unknown string) { if why := grantsReadFailed(in); why != "" { res.Grants = &GrantsWritten{Kept: []string{"no grant is written or deleted in a pass that could not read " + why}} return } skip := map[string]bool{} for _, g := range in.Refused { skip[strings.TrimPrefix(g.Input, "manifest of ")] = true } want, drop, err := GrantsOf(in, recs, skip) if err != nil { res.Errors = append(res.Errors, "the grants could not be composed: "+err.Error()) return } done := &GrantsWritten{Wanted: len(want), Missing: MissingGrants(in, want, drop, skip)} res.Grants = done p.sayMissing(done.Missing) p.settleWaits(res, in, done.Missing) byUser := map[string]User{} for _, u := range composed { byUser[u.User] = u } for _, key := range sortedKeys(want) { g := want[key] data, err := grantsstate.EncodeGrant(g) if err != nil { res.Errors = append(res.Errors, fmt.Sprintf("the grant %s cannot be encoded: %v", key, err)) continue } if raw, _, found, err := p.Store.Get(StateGrants, key); err != nil { res.Errors = append(res.Errors, fmt.Sprintf("its own %s %s cannot be read: %v", StateGrants, key, err)) continue } else if found { if was, err := grantsstate.DecodeGrant(raw); err == nil && grantsstate.SameGrant(was, withVersion(g)) { continue } } if waits := GrantWaits(g.Accounts, byUser, loaded, unknown); waits != "" { done.Waits = append(done.Waits, key+": "+waits) continue } if _, err := p.Store.Put(StateGrants, key, data); err != nil { res.Errors = append(res.Errors, fmt.Sprintf("its own %s %s cannot be written: %v", StateGrants, key, err)) continue } done.Written = append(done.Written, key) module, fp, _ := grantsstate.ParsePartGrantKey(key) p.say(res, EventGrantWritten, map[string]any{"module": module, "fingerprint": fp, "accounts": g.Accounts}) } for _, key := range drop { if _, _, found, err := p.Store.Get(StateGrants, key); err != nil || !found { continue } if err := p.Store.Delete(StateGrants, key); err != nil { res.Errors = append(res.Errors, fmt.Sprintf("its own %s %s cannot be deleted: %v", StateGrants, key, err)) continue } done.Deleted = append(done.Deleted, key) } } func withVersion(g grantsstate.Grant) grantsstate.Grant { g.V = keys.Version return g }