Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 jochen
|
a069d61fbd |
@@ -1,42 +0,0 @@
|
||||
# avahi
|
||||
|
||||
The local network's name and service discovery (mDNS/DNS-SD) as a module (novox/hq to-be 42 Phase 1,
|
||||
research 027).
|
||||
|
||||
## What it owns
|
||||
|
||||
- The `avahi` package.
|
||||
- `avahi-daemon.service`, running and enabled.
|
||||
|
||||
## What it improves
|
||||
|
||||
It was on all four machines and owned by none. It is now declared, and its tools show why discovery
|
||||
does not work today:
|
||||
|
||||
- **The packet filter drops mDNS.** The mesh's filter has no rule for inbound UDP 5353 on any of the
|
||||
four machines, so avahi announces this machine but hears no other machine's answers. A browse
|
||||
finds nothing, and resolving even the machine's own `.local` name times out. A module's `listens`
|
||||
can reach the private network, this machine or anywhere, but not the local link. Opening the port
|
||||
to anywhere would answer the internet on a public machine, so the module opens nothing. This needs
|
||||
a decision in novox/hq: a local-link source scope for `listens`. Until then, `avahi_status` reports
|
||||
`inbound_mdns_accepted: false`, and browse and resolve say so whenever they hear nothing.
|
||||
|
||||
## What it leaves found
|
||||
|
||||
- **`nss-mdns` and `/etc/nsswitch.conf`.** An ordinary lookup reaches avahi only through the
|
||||
`hosts:` line. That line is one ordered list shared by every name source: containers, files, DNS,
|
||||
mDNS and the resolver daemon. The host can write a marked block into a file, but it cannot add a
|
||||
member to a line. Owning the whole file would make this module the owner of every machine's name
|
||||
resolution. On 2026-10-04 all four machines had the same file, with `mdns4_minimal` wired by hand
|
||||
and nss-mdns installed. Both are left as found, and `avahi_status` reports the wiring.
|
||||
- `/etc/avahi/avahi-daemon.conf`, including each workstation's hand-set `allow-interfaces`, which
|
||||
names that machine's own network interface.
|
||||
|
||||
## Tools
|
||||
|
||||
| tool | | answers |
|
||||
|---|---|---|
|
||||
| `avahi_status` | r | the daemon, its version and configuration, the `hosts:` line and whether mdns is on it, nss-mdns, whether the filter accepts inbound 5353, systemd-resolved beside it, and notes |
|
||||
| `avahi_browse` | r | every service announced in a few seconds (`avahi-browse -prt`), resolved where possible, narrowed to a type |
|
||||
| `avahi_resolve` | r | a `.local` name through avahi and through the name service side by side, or an address to its name |
|
||||
| `avahi_services` | r | what this machine publishes from `/etc/avahi/services` |
|
||||
@@ -1,353 +0,0 @@
|
||||
package main
|
||||
|
||||
// Avahi, the local network's name and service discovery (mDNS/DNS-SD), as a module (novox/hq to-be 42
|
||||
// Phase 1, research 027: "on all four, owned by none"). The module declares the package and the
|
||||
// daemon. Two things it does not declare, and these tools report instead:
|
||||
//
|
||||
// - **The name service switch.** nss-mdns is what lets an ordinary lookup answer `<host>.local`, and
|
||||
// it works only through the `hosts:` line of /etc/nsswitch.conf. That line is one ordered list
|
||||
// shared by every name source on the machine (containers, files, DNS, mDNS, the resolver daemon),
|
||||
// the host can write a marked block into a file but not a member into a line, and owning the whole
|
||||
// file would make this module the owner of every machine's name resolution. So both stay as found
|
||||
// (wired by hand, identically, on all four machines on 2026-10-04) and `avahi_status` says whether
|
||||
// the wiring is there.
|
||||
// - **The packet filter.** mDNS is multicast to UDP 5353 on the local link. The mesh's filter has no
|
||||
// source scope for "the local link" — a module's `listens` reach the private network, this machine
|
||||
// or anywhere — so it drops what other machines announce, and a browse hears nothing. Opening it to
|
||||
// anywhere would answer the internet on a public machine. `avahi_status` reports whether inbound
|
||||
// 5353 is accepted; browse and resolve say so when they hear nothing.
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"net"
|
||||
"regexp"
|
||||
"sort"
|
||||
"strconv"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// The files avahi and the name service read.
|
||||
const (
|
||||
DaemonConf = "/etc/avahi/avahi-daemon.conf"
|
||||
ServicesDir = "/etc/avahi/services"
|
||||
NSSwitch = "/etc/nsswitch.conf"
|
||||
Daemon = "avahi-daemon.service"
|
||||
)
|
||||
|
||||
// Status is the daemon, its configuration, the name service's wiring and the filter.
|
||||
type Status struct {
|
||||
Daemon map[string]string `json:"daemon"`
|
||||
Version string `json:"version,omitempty"`
|
||||
Config map[string]map[string]string `json:"config"`
|
||||
HostsLine string `json:"nsswitch_hosts"`
|
||||
MDNSWired bool `json:"nss_mdns_wired"`
|
||||
NSSMDNS string `json:"nss_mdns_package,omitempty"`
|
||||
InboundMDNS *bool `json:"inbound_mdns_accepted"`
|
||||
FilterError string `json:"filter_error,omitempty"`
|
||||
ResolvedOn bool `json:"systemd_resolved_active"`
|
||||
Notes []string `json:"notes"`
|
||||
}
|
||||
|
||||
// ParseINI reads avahi-daemon.conf's sections and their set keys; commented keys are defaults.
|
||||
func ParseINI(text string) map[string]map[string]string {
|
||||
out := map[string]map[string]string{}
|
||||
section := ""
|
||||
for _, l := range lines(text) {
|
||||
l = strings.TrimSpace(l)
|
||||
switch {
|
||||
case strings.HasPrefix(l, "#") || strings.HasPrefix(l, ";"):
|
||||
case strings.HasPrefix(l, "[") && strings.HasSuffix(l, "]"):
|
||||
section = strings.Trim(l, "[]")
|
||||
out[section] = map[string]string{}
|
||||
default:
|
||||
if k, v, ok := strings.Cut(l, "="); ok && section != "" {
|
||||
out[section][strings.TrimSpace(k)] = strings.TrimSpace(v)
|
||||
}
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// HostsLine is the `hosts:` line of nsswitch.conf, and whether an mdns source is on it.
|
||||
func HostsLine(text string) (string, bool) {
|
||||
for _, l := range lines(text) {
|
||||
l = strings.TrimSpace(l)
|
||||
if !strings.HasPrefix(l, "hosts:") {
|
||||
continue
|
||||
}
|
||||
for _, f := range strings.Fields(strings.TrimPrefix(l, "hosts:")) {
|
||||
if strings.HasPrefix(f, "mdns") {
|
||||
return l, true
|
||||
}
|
||||
}
|
||||
return l, false
|
||||
}
|
||||
return "", false
|
||||
}
|
||||
|
||||
var mdnsAccept = regexp.MustCompile(`(?m)\budp dport (?:\{[^}\n]*\b(?:5353|mdns)\b[^}\n]*\}|(?:5353|mdns)\b)[^\n]*\baccept\b`)
|
||||
|
||||
// InboundMDNS is whether a ruleset accepts UDP 5353 coming in.
|
||||
func InboundMDNS(ruleset string) bool { return mdnsAccept.MatchString(ruleset) }
|
||||
|
||||
// GetStatus reads the daemon, its configuration, the name service and the packet filter.
|
||||
func (m *Machine) GetStatus() (Status, error) {
|
||||
s := Status{Config: map[string]map[string]string{}, Notes: []string{}}
|
||||
d, err := m.unitProps(Daemon, "LoadState", "ActiveState", "SubState", "UnitFileState", "MainPID")
|
||||
if err != nil {
|
||||
return s, err
|
||||
}
|
||||
s.Daemon = d
|
||||
if v, err := m.Out("avahi-daemon", "--version"); err == nil {
|
||||
s.Version = strings.TrimSpace(v)
|
||||
}
|
||||
if text, err := m.ReadFile(DaemonConf); err == nil {
|
||||
s.Config = ParseINI(string(text))
|
||||
}
|
||||
if text, err := m.ReadFile(NSSwitch); err == nil {
|
||||
s.HostsLine, s.MDNSWired = HostsLine(string(text))
|
||||
}
|
||||
if r := m.Run(bg(), "pacman", "-Q", "nss-mdns"); r.Status == 0 && r.Err == "" {
|
||||
s.NSSMDNS = strings.TrimSpace(r.Stdout)
|
||||
}
|
||||
if rs, err := m.Root("nft", "list", "ruleset"); err == nil {
|
||||
open := InboundMDNS(rs)
|
||||
s.InboundMDNS = &open
|
||||
if !open {
|
||||
s.Notes = append(s.Notes, "the packet filter drops inbound UDP 5353: this machine announces itself but hears no other machine's mDNS")
|
||||
}
|
||||
} else {
|
||||
s.FilterError = err.Error()
|
||||
}
|
||||
if p, err := m.unitProps("systemd-resolved.service", "ActiveState"); err == nil {
|
||||
s.ResolvedOn = p["ActiveState"] == "active"
|
||||
}
|
||||
if s.MDNSWired && s.NSSMDNS == "" {
|
||||
s.Notes = append(s.Notes, "nsswitch names mdns and nss-mdns is not installed: those lookups fail")
|
||||
}
|
||||
if !s.MDNSWired {
|
||||
s.Notes = append(s.Notes, "nsswitch does not name mdns: ordinary lookups never ask avahi")
|
||||
}
|
||||
return s, nil
|
||||
}
|
||||
|
||||
// Service is one service a browse found.
|
||||
type Service struct {
|
||||
Interface string `json:"interface"`
|
||||
Protocol string `json:"protocol"`
|
||||
Name string `json:"name"`
|
||||
Type string `json:"type"`
|
||||
Domain string `json:"domain"`
|
||||
Host string `json:"host,omitempty"`
|
||||
Address string `json:"address,omitempty"`
|
||||
Port int `json:"port,omitempty"`
|
||||
TXT []string `json:"txt,omitempty"`
|
||||
Resolved bool `json:"resolved"`
|
||||
}
|
||||
|
||||
// unescape undoes avahi-browse -p's escaping: a special byte as a backslash and three decimals, any
|
||||
// other character after a backslash as itself. Decoded as bytes, so a name in UTF-8 stays whole.
|
||||
func unescape(s string) string {
|
||||
out := make([]byte, 0, len(s))
|
||||
for i := 0; i < len(s); i++ {
|
||||
if s[i] == '\\' {
|
||||
if d := s[i+1 : min(i+4, len(s))]; len(d) == 3 && isDigits(d) {
|
||||
n, _ := strconv.Atoi(d)
|
||||
out = append(out, byte(n))
|
||||
i += 3
|
||||
continue
|
||||
}
|
||||
if i+1 < len(s) {
|
||||
out = append(out, s[i+1])
|
||||
i++
|
||||
continue
|
||||
}
|
||||
}
|
||||
out = append(out, s[i])
|
||||
}
|
||||
return string(out)
|
||||
}
|
||||
|
||||
func isDigits(s string) bool {
|
||||
for _, c := range s {
|
||||
if c < '0' || c > '9' {
|
||||
return false
|
||||
}
|
||||
}
|
||||
return true
|
||||
}
|
||||
|
||||
var txtItem = regexp.MustCompile(`"((?:[^"\\]|\\.)*)"`)
|
||||
|
||||
// ParseBrowse reads `avahi-browse -p -r`: `+` lines found, `=` lines resolved; a found service
|
||||
// that resolved is answered once, resolved.
|
||||
func ParseBrowse(out string) []Service {
|
||||
byKey := map[string]int{}
|
||||
services := []Service{}
|
||||
for _, l := range lines(out) {
|
||||
f := strings.Split(l, ";")
|
||||
if len(f) < 6 || (f[0] != "+" && f[0] != "=") {
|
||||
continue
|
||||
}
|
||||
s := Service{Interface: f[1], Protocol: f[2], Name: unescape(f[3]), Type: f[4], Domain: f[5]}
|
||||
if f[0] == "=" && len(f) >= 9 {
|
||||
s.Resolved, s.Host, s.Address = true, f[6], f[7]
|
||||
s.Port, _ = strconv.Atoi(f[8])
|
||||
if len(f) >= 10 {
|
||||
for _, t := range txtItem.FindAllStringSubmatch(strings.Join(f[9:], ";"), -1) {
|
||||
s.TXT = append(s.TXT, t[1])
|
||||
}
|
||||
}
|
||||
}
|
||||
key := strings.Join([]string{s.Interface, s.Protocol, s.Name, s.Type, s.Domain}, "\x00")
|
||||
if i, seen := byKey[key]; seen {
|
||||
if s.Resolved {
|
||||
services[i] = s
|
||||
}
|
||||
continue
|
||||
}
|
||||
byKey[key] = len(services)
|
||||
services = append(services, s)
|
||||
}
|
||||
sort.SliceStable(services, func(i, j int) bool {
|
||||
if services[i].Type != services[j].Type {
|
||||
return services[i].Type < services[j].Type
|
||||
}
|
||||
return services[i].Name < services[j].Name
|
||||
})
|
||||
return services
|
||||
}
|
||||
|
||||
var serviceType = regexp.MustCompile(`^_[A-Za-z0-9-]+\._(tcp|udp)$`)
|
||||
|
||||
// Browse listens for a few seconds and answers every service announced, resolved where it could be.
|
||||
func (m *Machine) Browse(seconds int, kind string) (map[string]any, error) {
|
||||
args := []string{strconv.Itoa(seconds), "avahi-browse", "-p", "-r", "-t"}
|
||||
if kind == "" {
|
||||
args = append(args, "-a")
|
||||
} else {
|
||||
if !serviceType.MatchString(kind) {
|
||||
return nil, fmt.Errorf("%q is not a service type such as _ssh._tcp", kind)
|
||||
}
|
||||
args = append(args, kind)
|
||||
}
|
||||
r := m.Run(bg(), "timeout", args...)
|
||||
// timeout's 124 is the listening time ending, which is how a browse that keeps hearing ends.
|
||||
if r.Err != "" || (r.Status != 0 && r.Status != 124) {
|
||||
return nil, failure("avahi-browse", "avahi-browse", r)
|
||||
}
|
||||
services := ParseBrowse(r.Stdout)
|
||||
out := map[string]any{"seconds": seconds, "count": len(services), "services": services}
|
||||
if len(services) == 0 {
|
||||
out["note"] = m.silenceNote()
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// silenceNote says why nothing may have been heard, from the packet filter when it can be read.
|
||||
func (m *Machine) silenceNote() string {
|
||||
if rs, err := m.Root("nft", "list", "ruleset"); err == nil && !InboundMDNS(rs) {
|
||||
return "nothing was heard, and this machine's packet filter drops inbound UDP 5353 (mDNS): other machines' answers do not reach avahi"
|
||||
}
|
||||
return "nothing was heard on the local network"
|
||||
}
|
||||
|
||||
// Resolve asks avahi for a name's address (or an address's name), and the name service the same,
|
||||
// so an answer avahi has and an ordinary lookup does not shows the switch unwired.
|
||||
func (m *Machine) Resolve(name, address string) (map[string]any, error) {
|
||||
if (name == "") == (address == "") {
|
||||
return nil, fmt.Errorf("give a name or an address")
|
||||
}
|
||||
out := map[string]any{}
|
||||
var r Ran
|
||||
if name != "" {
|
||||
if !strings.HasSuffix(name, ".local") {
|
||||
name += ".local"
|
||||
}
|
||||
out["name"] = name
|
||||
r = m.Run(bg(), "avahi-resolve", "-n", name)
|
||||
} else {
|
||||
if net.ParseIP(address) == nil {
|
||||
return nil, fmt.Errorf("%q is not an address", address)
|
||||
}
|
||||
out["address"] = address
|
||||
r = m.Run(bg(), "avahi-resolve", "-a", address)
|
||||
}
|
||||
if r.Err != "" {
|
||||
return nil, failure("avahi-resolve", "avahi-resolve", r)
|
||||
}
|
||||
// avahi-resolve says a failure on stderr and exits 0.
|
||||
avahi := map[string]any{"answers": []string{}}
|
||||
for _, l := range lines(r.Stdout) {
|
||||
if f := strings.Fields(l); len(f) >= 2 {
|
||||
avahi["answers"] = append(avahi["answers"].([]string), f[1])
|
||||
}
|
||||
}
|
||||
if said := firstLine(r.Stderr); said != "" {
|
||||
avahi["error"] = said
|
||||
}
|
||||
avahi["resolved"] = len(avahi["answers"].([]string)) > 0
|
||||
out["avahi"] = avahi
|
||||
if name != "" {
|
||||
nss := map[string]any{"answers": []string{}}
|
||||
g := m.Run(bg(), "getent", "hosts", name)
|
||||
for _, l := range lines(g.Stdout) {
|
||||
if f := strings.Fields(l); len(f) >= 1 {
|
||||
nss["answers"] = append(nss["answers"].([]string), f[0])
|
||||
}
|
||||
}
|
||||
nss["resolved"] = len(nss["answers"].([]string)) > 0
|
||||
out["name_service"] = nss
|
||||
}
|
||||
if avahi["resolved"] == false {
|
||||
out["note"] = m.silenceNote()
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// Published is one service this machine announces from a file of /etc/avahi/services.
|
||||
type Published struct {
|
||||
File string `json:"file"`
|
||||
Name string `json:"name,omitempty"`
|
||||
Types []string `json:"types"`
|
||||
Ports []int `json:"ports"`
|
||||
}
|
||||
|
||||
var (
|
||||
xmlName = regexp.MustCompile(`<name[^>]*>([^<]*)</name>`)
|
||||
xmlType = regexp.MustCompile(`<type>([^<]*)</type>`)
|
||||
xmlPort = regexp.MustCompile(`<port>(\d+)</port>`)
|
||||
)
|
||||
|
||||
// Services is what this machine publishes from its service files.
|
||||
func (m *Machine) Services() (map[string]any, error) {
|
||||
r := m.Run(bg(), "find", ServicesDir, "-mindepth", "1", "-maxdepth", "1", "-name", "*.service", "-printf", "%f\n")
|
||||
if r.Err != "" || r.Status != 0 {
|
||||
if strings.Contains(r.Stderr, "No such file") {
|
||||
return map[string]any{"directory": ServicesDir, "published": []Published{}}, nil
|
||||
}
|
||||
return nil, failure("find", "find", r)
|
||||
}
|
||||
pub := []Published{}
|
||||
names := lines(r.Stdout)
|
||||
sort.Strings(names)
|
||||
for _, n := range names {
|
||||
text, err := m.ReadFile(ServicesDir + "/" + n)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
p := Published{File: n, Types: []string{}, Ports: []int{}}
|
||||
if x := xmlName.FindStringSubmatch(string(text)); x != nil {
|
||||
p.Name = x[1]
|
||||
}
|
||||
for _, t := range xmlType.FindAllStringSubmatch(string(text), -1) {
|
||||
p.Types = append(p.Types, t[1])
|
||||
}
|
||||
for _, x := range xmlPort.FindAllStringSubmatch(string(text), -1) {
|
||||
port, _ := strconv.Atoi(x[1])
|
||||
p.Ports = append(p.Ports, port)
|
||||
}
|
||||
pub = append(pub, p)
|
||||
}
|
||||
return map[string]any{"directory": ServicesDir, "published": pub}, nil
|
||||
}
|
||||
@@ -1,165 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
const browse = `+;enp6s0;IPv4;home\032server;_ssh._tcp;local
|
||||
+;enp6s0;IPv4;Printer\046Co;_ipp._tcp;local
|
||||
=;enp6s0;IPv4;home\032server;_ssh._tcp;local;home-server.local;192.168.1.10;22;
|
||||
=;enp6s0;IPv4;Printer\046Co;_ipp._tcp;local;printer.local;192.168.1.20;631;"txtvers=1" "rp=ipp/print"
|
||||
+;enp6s0;IPv6;Kitchen;_spotify-connect._tcp;local
|
||||
`
|
||||
|
||||
func TestABrowseIsReadResolvedOnceAndUnescaped(t *testing.T) {
|
||||
s := ParseBrowse(browse)
|
||||
if len(s) != 3 {
|
||||
t.Fatalf("%+v", s)
|
||||
}
|
||||
by := map[string]Service{}
|
||||
for _, x := range s {
|
||||
by[x.Name] = x
|
||||
}
|
||||
ssh := by["home server"]
|
||||
if !ssh.Resolved || ssh.Address != "192.168.1.10" || ssh.Port != 22 || ssh.Host != "home-server.local" {
|
||||
t.Fatalf("%+v", ssh)
|
||||
}
|
||||
ipp := by["Printer.Co"]
|
||||
if strings.Join(ipp.TXT, ",") != "txtvers=1,rp=ipp/print" {
|
||||
t.Fatalf("%+v", ipp)
|
||||
}
|
||||
if k := by["Kitchen"]; k.Resolved || k.Type != "_spotify-connect._tcp" {
|
||||
t.Fatalf("%+v", k)
|
||||
}
|
||||
if unescape(`caf\195\169`) != "café" || unescape(`a\.b`) != "a.b" {
|
||||
t.Fatal("unescape")
|
||||
}
|
||||
}
|
||||
|
||||
func TestABrowseThatHearsNothingSaysTheFilterDropsMDNS(t *testing.T) {
|
||||
var calls []call
|
||||
m := machine(fake(func(c call) Ran {
|
||||
switch c.String() {
|
||||
case "timeout 5 avahi-browse -p -r -t -a":
|
||||
return Ran{Status: 124}
|
||||
case "sudo -n nft list ruleset":
|
||||
return Ran{Stdout: "table inet mesh {\n chain input {\n type filter hook input priority filter; policy drop;\n tcp dport 22 accept\n }\n}\n"}
|
||||
}
|
||||
return Ran{Status: 99}
|
||||
}, &calls), 1000)
|
||||
r, err := m.Browse(5, "")
|
||||
if err != nil || r["count"] != 0 || !strings.Contains(r["note"].(string), "drops inbound UDP 5353") {
|
||||
t.Fatalf("%v %v", r, err)
|
||||
}
|
||||
if _, err := m.Browse(5, "ssh; rm"); err == nil {
|
||||
t.Fatal("not a service type")
|
||||
}
|
||||
}
|
||||
|
||||
func TestTheFilterIsReadForAnAcceptedInboundMDNS(t *testing.T) {
|
||||
for rs, want := range map[string]bool{
|
||||
"\t\tudp dport 5353 accept\n": true,
|
||||
"\t\tiifname \"enp6s0\" udp dport { 53, 5353 } accept\n": true,
|
||||
"\t\tudp dport mdns accept\n": true,
|
||||
"\t\tudp dport 53 accept\n": false,
|
||||
"\t\tudp dport 5353 drop\n": false,
|
||||
"\t\tip saddr 10.0.0.0/8 udp dport 15353 accept\n": false,
|
||||
} {
|
||||
if InboundMDNS(rs) != want {
|
||||
t.Errorf("%q: %v", rs, !want)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestStatusNamesTheSwitchTheFilterAndTheDaemon(t *testing.T) {
|
||||
m := machine(fake(func(c call) Ran {
|
||||
switch {
|
||||
case c.name == "systemctl" && c.args[1] == Daemon:
|
||||
return Ran{Stdout: "LoadState=loaded\nActiveState=active\nUnitFileState=enabled\n"}
|
||||
case c.name == "systemctl":
|
||||
return Ran{Stdout: "ActiveState=inactive\n"}
|
||||
case c.String() == "avahi-daemon --version":
|
||||
return Ran{Stdout: "avahi-daemon 0.9-rc5\n"}
|
||||
case c.String() == "pacman -Q nss-mdns":
|
||||
return Ran{Stdout: "nss-mdns 0.15.1-2\n"}
|
||||
case c.String() == "sudo -n nft list ruleset":
|
||||
return Ran{Stdout: "udp dport 53 accept\n"}
|
||||
}
|
||||
return Ran{Status: 99}
|
||||
}, nil), 1000)
|
||||
files := map[string]string{
|
||||
DaemonConf: "[server]\nuse-ipv4=yes\n#host-name=foo\nallow-interfaces=enp6s0\n[publish]\npublish-hinfo=no\n",
|
||||
NSSwitch: "passwd: files\nhosts: mymachines files dns mdns4_minimal [NOTFOUND=return] resolve [!UNAVAIL=return]\n",
|
||||
}
|
||||
m.ReadFile = func(p string) ([]byte, error) {
|
||||
if s, ok := files[p]; ok {
|
||||
return []byte(s), nil
|
||||
}
|
||||
return nil, errNoFile
|
||||
}
|
||||
s, err := m.GetStatus()
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !s.MDNSWired || s.NSSMDNS != "nss-mdns 0.15.1-2" || s.InboundMDNS == nil || *s.InboundMDNS || s.Version != "avahi-daemon 0.9-rc5" {
|
||||
t.Fatalf("%+v", s)
|
||||
}
|
||||
if s.Config["server"]["allow-interfaces"] != "enp6s0" || s.Config["server"]["host-name"] != "" || s.Daemon["ActiveState"] != "active" {
|
||||
t.Fatalf("%+v", s.Config)
|
||||
}
|
||||
if len(s.Notes) != 1 || !strings.Contains(s.Notes[0], "drops inbound UDP 5353") {
|
||||
t.Fatalf("%v", s.Notes)
|
||||
}
|
||||
if _, wired := HostsLine("hosts: files dns\n"); wired {
|
||||
t.Fatal("no mdns on the line")
|
||||
}
|
||||
}
|
||||
|
||||
func TestResolveAsksAvahiAndTheNameServiceAndReadsAFailureFromStderr(t *testing.T) {
|
||||
m := machine(byLine(map[string]Ran{
|
||||
"avahi-resolve -n printer.local": {Stdout: "printer.local\t192.168.1.20\n"},
|
||||
"getent hosts printer.local": {Status: 2},
|
||||
"avahi-resolve -n nowhere.local": {Stderr: "Failed to resolve host name 'nowhere.local': Timeout reached\n"},
|
||||
"getent hosts nowhere.local": {Status: 2},
|
||||
"sudo -n nft list ruleset": {Stdout: "udp dport 5353 accept\n"},
|
||||
"avahi-resolve -a 192.168.1.20": {Stdout: "192.168.1.20\tprinter.local\n"},
|
||||
}, nil), 1000)
|
||||
r, err := m.Resolve("printer", "")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if r["avahi"].(map[string]any)["resolved"] != true || r["name_service"].(map[string]any)["resolved"] != false {
|
||||
t.Fatalf("%v", r)
|
||||
}
|
||||
r, _ = m.Resolve("nowhere.local", "")
|
||||
if a := r["avahi"].(map[string]any); a["resolved"] != false || !strings.Contains(a["error"].(string), "Timeout reached") || r["note"] != "nothing was heard on the local network" {
|
||||
t.Fatalf("%v", r)
|
||||
}
|
||||
r, _ = m.Resolve("", "192.168.1.20")
|
||||
if r["avahi"].(map[string]any)["answers"].([]string)[0] != "printer.local" {
|
||||
t.Fatalf("%v", r)
|
||||
}
|
||||
for _, bad := range [][2]string{{"", ""}, {"a", "1.2.3.4"}, {"", "not-an-ip"}} {
|
||||
if _, err := m.Resolve(bad[0], bad[1]); err == nil {
|
||||
t.Errorf("%v accepted", bad)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestPublishedServicesAreReadFromTheirFiles(t *testing.T) {
|
||||
m := machine(byLine(map[string]Ran{
|
||||
"find /etc/avahi/services -mindepth 1 -maxdepth 1 -name *.service -printf %f\n": {Stdout: "ssh.service\n"},
|
||||
}, nil), 1000)
|
||||
m.ReadFile = func(string) ([]byte, error) {
|
||||
return []byte(`<service-group><name replace-wildcards="yes">%h</name><service><type>_ssh._tcp</type><port>22</port></service></service-group>`), nil
|
||||
}
|
||||
r, err := m.Services()
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
p := r["published"].([]Published)
|
||||
if len(p) != 1 || p[0].Name != "%h" || p[0].Types[0] != "_ssh._tcp" || p[0].Ports[0] != 22 {
|
||||
t.Fatalf("%+v", p)
|
||||
}
|
||||
}
|
||||
@@ -1,289 +0,0 @@
|
||||
package main
|
||||
|
||||
// The commands this bundle runs on its machine, and who runs them.
|
||||
//
|
||||
// Who asks. The node's tool runtime runs as the operator account, not root (novox/hq ADR 0175 §4),
|
||||
// and launches this binary as a process of its own (ADR 0188, ADR 0193) with the runtime's words —
|
||||
// HOME, a PATH, MESH_OPERATOR_ACCOUNT — and no session words. Reading needs nothing more; what only
|
||||
// root may do goes through `sudo -n`, as the packet filter's, the service manager's and the
|
||||
// intrusion prevention's tools do (to-be 38 WP4), and the `sudo` module is what declares that the
|
||||
// account may (to-be 42, research 027). A refusal is named by how it failed, never read as an
|
||||
// empty answer.
|
||||
//
|
||||
// The runner is injected, so every tool is tested over a fake one without the machine.
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"errors"
|
||||
"fmt"
|
||||
"io/fs"
|
||||
"os"
|
||||
"os/exec"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// Ran is what one command did: its output, its exit status, and why it never ran to an answer.
|
||||
type Ran struct {
|
||||
Stdout string
|
||||
Stderr string
|
||||
Status int
|
||||
// Err is "ENOENT" when the program is not there, or that it was ended for taking too long.
|
||||
Err string
|
||||
}
|
||||
|
||||
// Runner runs one command, so the tools can be tested without the machine.
|
||||
type Runner func(ctx context.Context, name string, args ...string) Ran
|
||||
|
||||
// CallTimeout is how long one command may take: below the runtime's thirty-second call limit, so a
|
||||
// command that hangs is answered as such rather than as a call the runtime gave up on.
|
||||
const CallTimeout = 20 * time.Second
|
||||
|
||||
// outputLimit bounds what one command may hand back, so a runaway listing cannot exhaust the
|
||||
// process; well above anything a tool answers.
|
||||
const outputLimit = 16 << 20
|
||||
|
||||
type bounded struct {
|
||||
bytes.Buffer
|
||||
cut bool
|
||||
}
|
||||
|
||||
func (b *bounded) Write(p []byte) (int, error) {
|
||||
if room := outputLimit - b.Len(); room < len(p) {
|
||||
if room > 0 {
|
||||
b.Buffer.Write(p[:room])
|
||||
}
|
||||
b.cut = true
|
||||
return len(p), nil
|
||||
}
|
||||
return b.Buffer.Write(p)
|
||||
}
|
||||
|
||||
// ExecRunner runs a command on this machine, in the C locale so what is parsed is one language.
|
||||
func ExecRunner(ctx context.Context, name string, args ...string) Ran {
|
||||
ctx, cancel := context.WithTimeout(ctx, CallTimeout)
|
||||
defer cancel()
|
||||
cmd := exec.CommandContext(ctx, name, args...)
|
||||
cmd.Env = append(os.Environ(), "LC_ALL=C")
|
||||
var out, errb bounded
|
||||
cmd.Stdout, cmd.Stderr = &out, &errb
|
||||
err := cmd.Run()
|
||||
r := Ran{Stdout: out.String(), Stderr: errb.String()}
|
||||
if ctx.Err() == context.DeadlineExceeded {
|
||||
r.Status, r.Err = 124, fmt.Sprintf("no answer within %d s", int(CallTimeout.Seconds()))
|
||||
return r
|
||||
}
|
||||
var exit *exec.ExitError
|
||||
switch {
|
||||
case err == nil:
|
||||
case errors.As(err, &exit):
|
||||
r.Status = exit.ExitCode()
|
||||
case errors.Is(err, exec.ErrNotFound) || errors.Is(err, fs.ErrNotExist):
|
||||
r.Status, r.Err = 127, "ENOENT"
|
||||
default:
|
||||
r.Status, r.Err = 126, err.Error()
|
||||
}
|
||||
return r
|
||||
}
|
||||
|
||||
// Escalated is the command as it is run: as given when this process is root, else through sudo
|
||||
// without a prompt.
|
||||
func Escalated(uid int, name string, args ...string) (string, []string) {
|
||||
if uid == 0 {
|
||||
return name, args
|
||||
}
|
||||
return "sudo", append([]string{"-n", name}, args...)
|
||||
}
|
||||
|
||||
// Machine is this machine as the tools see it: a runner, who this process is, and its files.
|
||||
type Machine struct {
|
||||
Run Runner
|
||||
UID int
|
||||
User string
|
||||
Account string
|
||||
ReadFile func(path string) ([]byte, error)
|
||||
Now func() time.Time
|
||||
Sleep func(time.Duration)
|
||||
}
|
||||
|
||||
// ThisMachine is the machine the runtime launched this bundle on.
|
||||
func ThisMachine() *Machine {
|
||||
user := os.Getenv("USER")
|
||||
if user == "" {
|
||||
user = os.Getenv("LOGNAME")
|
||||
}
|
||||
account := strings.TrimSpace(os.Getenv("MESH_OPERATOR_ACCOUNT"))
|
||||
if account == "" {
|
||||
account = user
|
||||
}
|
||||
return &Machine{Run: ExecRunner, UID: os.Getuid(), User: user, Account: account, ReadFile: os.ReadFile, Now: time.Now, Sleep: time.Sleep}
|
||||
}
|
||||
|
||||
// Out runs a command that only reads, and fails with what went wrong named.
|
||||
func (m *Machine) Out(name string, args ...string) (string, error) {
|
||||
r := m.Run(context.Background(), name, args...)
|
||||
if r.Status == 0 && r.Err == "" {
|
||||
return r.Stdout, nil
|
||||
}
|
||||
return r.Stdout, failure(name, name, r)
|
||||
}
|
||||
|
||||
// Root runs a command that needs root, escalated when this process is not.
|
||||
func (m *Machine) Root(name string, args ...string) (string, error) {
|
||||
program, argv := Escalated(m.UID, name, args...)
|
||||
r := m.Run(context.Background(), program, argv...)
|
||||
if r.Status == 0 && r.Err == "" {
|
||||
return r.Stdout, nil
|
||||
}
|
||||
return r.Stdout, failure(name, program, r)
|
||||
}
|
||||
|
||||
// RootRan is Root's raw answer, for a command whose non-zero status is itself an answer.
|
||||
func (m *Machine) RootRan(name string, args ...string) (Ran, error) {
|
||||
program, argv := Escalated(m.UID, name, args...)
|
||||
r := m.Run(context.Background(), program, argv...)
|
||||
if r.Err != "" || (program == "sudo" && sudoRefused(r)) {
|
||||
return r, failure(name, program, r)
|
||||
}
|
||||
return r, nil
|
||||
}
|
||||
|
||||
func sudoRefused(r Ran) bool {
|
||||
return strings.HasPrefix(strings.TrimSpace(r.Stderr), "sudo:")
|
||||
}
|
||||
|
||||
// failure names what failed by how it failed: the program missing is a spawn error, sudo missing
|
||||
// or refusing speaks for itself, and the rest is the command's own first line.
|
||||
func failure(cmd, program string, r Ran) error {
|
||||
said := strings.TrimSpace(r.Stderr + "\n" + r.Stdout)
|
||||
if r.Err == "ENOENT" {
|
||||
if program == "sudo" {
|
||||
return fmt.Errorf("%s needs root for this, and sudo is not installed here for the runtime's account to escalate with", cmd)
|
||||
}
|
||||
return fmt.Errorf("%s is not installed on this machine", cmd)
|
||||
}
|
||||
if r.Err != "" {
|
||||
return fmt.Errorf("%s did not answer: %s", cmd, r.Err)
|
||||
}
|
||||
if program == "sudo" && sudoRefused(r) {
|
||||
if strings.Contains(said, "command not found") {
|
||||
return fmt.Errorf("%s is not installed on this machine", cmd)
|
||||
}
|
||||
return fmt.Errorf("%s needs root for this and the runtime's account may not run it without a prompt: %s", cmd, firstLine(said))
|
||||
}
|
||||
if line := firstLine(said); line != "" {
|
||||
return fmt.Errorf("%s failed (%d): %s", cmd, r.Status, line)
|
||||
}
|
||||
return fmt.Errorf("%s failed with status %d", cmd, r.Status)
|
||||
}
|
||||
|
||||
func firstLine(text string) string {
|
||||
for _, l := range strings.Split(text, "\n") {
|
||||
if l = strings.TrimSpace(l); l != "" {
|
||||
return l
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
func lines(text string) []string {
|
||||
var out []string
|
||||
for _, l := range strings.Split(text, "\n") {
|
||||
if l = strings.TrimRight(l, "\r"); strings.TrimSpace(l) != "" {
|
||||
out = append(out, l)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// text is a string argument; required says whether it may be absent. It is never something a
|
||||
// command would read as an option, which under sudo would be root's option.
|
||||
func text(args map[string]any, key string, required bool) (string, error) {
|
||||
raw, present := args[key]
|
||||
if !present || raw == nil {
|
||||
if required {
|
||||
return "", fmt.Errorf("%s is required", key)
|
||||
}
|
||||
return "", nil
|
||||
}
|
||||
s, ok := raw.(string)
|
||||
if !ok {
|
||||
return "", fmt.Errorf("%s must be a string", key)
|
||||
}
|
||||
s = strings.TrimSpace(s)
|
||||
if required && s == "" {
|
||||
return "", fmt.Errorf("%s is required", key)
|
||||
}
|
||||
if strings.HasPrefix(s, "-") || strings.ContainsRune(s, 0) || strings.ContainsAny(s, "\n\r") {
|
||||
return "", fmt.Errorf("%s %q is not a value this tool passes on", key, s)
|
||||
}
|
||||
return s, nil
|
||||
}
|
||||
|
||||
// whole is a whole-number argument with a default, kept within bounds.
|
||||
func whole(args map[string]any, key string, def, least, most int) (int, error) {
|
||||
raw, present := args[key]
|
||||
if !present || raw == nil {
|
||||
return def, nil
|
||||
}
|
||||
f, ok := raw.(float64)
|
||||
if !ok || f != float64(int(f)) {
|
||||
return 0, fmt.Errorf("%s must be a whole number", key)
|
||||
}
|
||||
n := int(f)
|
||||
if n < least {
|
||||
return 0, fmt.Errorf("%s must be at least %d", key, least)
|
||||
}
|
||||
if n > most {
|
||||
n = most
|
||||
}
|
||||
return n, nil
|
||||
}
|
||||
|
||||
// flag is a boolean argument, false when absent.
|
||||
func flag(args map[string]any, key string) (bool, error) {
|
||||
raw, present := args[key]
|
||||
if !present || raw == nil {
|
||||
return false, nil
|
||||
}
|
||||
b, ok := raw.(bool)
|
||||
if !ok {
|
||||
return false, fmt.Errorf("%s must be true or false", key)
|
||||
}
|
||||
return b, nil
|
||||
}
|
||||
|
||||
// schema is a tool's input: its properties and the ones it requires.
|
||||
func schema(properties map[string]any, required ...string) map[string]any {
|
||||
s := map[string]any{"type": "object", "properties": properties}
|
||||
if len(required) > 0 {
|
||||
s["required"] = required
|
||||
}
|
||||
return s
|
||||
}
|
||||
|
||||
// unitProps reads a unit's properties as systemctl shows them.
|
||||
func (m *Machine) unitProps(unit string, props ...string) (map[string]string, error) {
|
||||
args := []string{"show", unit, "--no-pager"}
|
||||
for _, p := range props {
|
||||
args = append(args, "--property="+p)
|
||||
}
|
||||
out, err := m.Out("systemctl", args...)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return keyValues(out, "="), nil
|
||||
}
|
||||
|
||||
// keyValues reads `key<sep>value` lines; a line without the separator is skipped.
|
||||
func keyValues(out, sep string) map[string]string {
|
||||
kv := map[string]string{}
|
||||
for _, l := range strings.Split(out, "\n") {
|
||||
k, v, ok := strings.Cut(l, sep)
|
||||
if ok {
|
||||
kv[strings.TrimSpace(k)] = strings.TrimSpace(v)
|
||||
}
|
||||
}
|
||||
return kv
|
||||
}
|
||||
@@ -1,107 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
// call is one command a fake runner was asked to run.
|
||||
type call struct {
|
||||
name string
|
||||
args []string
|
||||
}
|
||||
|
||||
func (c call) String() string {
|
||||
if len(c.args) == 0 {
|
||||
return c.name
|
||||
}
|
||||
return c.name + " " + strings.Join(c.args, " ")
|
||||
}
|
||||
|
||||
// fake is a runner answering by the command line it is given, recording every call.
|
||||
func fake(answer func(c call) Ran, calls *[]call) Runner {
|
||||
return func(_ context.Context, name string, args ...string) Ran {
|
||||
c := call{name, append([]string(nil), args...)}
|
||||
if calls != nil {
|
||||
*calls = append(*calls, c)
|
||||
}
|
||||
return answer(c)
|
||||
}
|
||||
}
|
||||
|
||||
// byLine answers from a table keyed by the whole command line, and refuses anything else as a
|
||||
// command the test did not expect.
|
||||
func byLine(table map[string]Ran, calls *[]call) Runner {
|
||||
return fake(func(c call) Ran {
|
||||
if r, ok := table[c.String()]; ok {
|
||||
return r
|
||||
}
|
||||
return Ran{Status: 99, Stderr: "unexpected command: " + c.String()}
|
||||
}, calls)
|
||||
}
|
||||
|
||||
func machine(run Runner, uid int) *Machine {
|
||||
return &Machine{Run: run, UID: uid, User: "operator", Account: "operator",
|
||||
ReadFile: func(string) ([]byte, error) { return nil, errNoFile },
|
||||
Now: func() time.Time { return time.Date(2026, 10, 4, 12, 0, 0, 0, time.UTC) },
|
||||
Sleep: func(time.Duration) {}}
|
||||
}
|
||||
|
||||
type noFile struct{}
|
||||
|
||||
func (noFile) Error() string { return "no such file" }
|
||||
|
||||
var errNoFile = noFile{}
|
||||
|
||||
func TestAnActNeedingRootGoesThroughSudoWithoutAPromptUnlessThisIsRoot(t *testing.T) {
|
||||
if p, a := Escalated(1000, "visudo", "-c"); p != "sudo" || strings.Join(a, " ") != "-n visudo -c" {
|
||||
t.Fatalf("not root: %s %v", p, a)
|
||||
}
|
||||
if p, a := Escalated(0, "visudo", "-c"); p != "visudo" || strings.Join(a, " ") != "-c" {
|
||||
t.Fatalf("root: %s %v", p, a)
|
||||
}
|
||||
}
|
||||
|
||||
func TestFailuresAreNamedNeverReadAsEmpty(t *testing.T) {
|
||||
cases := []struct {
|
||||
r Ran
|
||||
want string
|
||||
}{
|
||||
{Ran{Status: 127, Err: "ENOENT"}, "sudo is not installed here"},
|
||||
{Ran{Status: 1, Stderr: "sudo: a password is required\n"}, "may not run it without a prompt: sudo: a password is required"},
|
||||
{Ran{Status: 124, Err: "no answer within 20 s"}, "did not answer: no answer within 20 s"},
|
||||
{Ran{Status: 2, Stderr: "boom\nmore"}, "failed (2): boom"},
|
||||
}
|
||||
for _, c := range cases {
|
||||
m := machine(fake(func(call) Ran { return c.r }, nil), 1000)
|
||||
if _, err := m.Root("thing"); err == nil || !strings.Contains(err.Error(), c.want) {
|
||||
t.Errorf("%+v: %v, want %q", c.r, err, c.want)
|
||||
}
|
||||
}
|
||||
m := machine(fake(func(call) Ran { return Ran{Status: 127, Err: "ENOENT"} }, nil), 1000)
|
||||
if _, err := m.Out("thing"); err == nil || !strings.Contains(err.Error(), "thing is not installed") {
|
||||
t.Errorf("a missing program: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAnArgumentIsNeverAnOption(t *testing.T) {
|
||||
for _, bad := range []any{"-rf", "a\nb", 3.0} {
|
||||
if _, err := text(map[string]any{"x": bad}, "x", true); err == nil {
|
||||
t.Errorf("%v was accepted", bad)
|
||||
}
|
||||
}
|
||||
if s, err := text(map[string]any{"x": " ok "}, "x", true); err != nil || s != "ok" {
|
||||
t.Errorf("a plain value: %q %v", s, err)
|
||||
}
|
||||
if _, err := text(map[string]any{}, "x", true); err == nil {
|
||||
t.Error("a missing required value was accepted")
|
||||
}
|
||||
if n, _ := whole(map[string]any{"n": 10000.0}, "n", 5, 1, 100); n != 100 {
|
||||
t.Errorf("not bounded: %d", n)
|
||||
}
|
||||
if _, err := whole(map[string]any{"n": 0.0}, "n", 5, 1, 100); err == nil {
|
||||
t.Error("below the least was accepted")
|
||||
}
|
||||
}
|
||||
@@ -1,85 +0,0 @@
|
||||
// avahi's tools bundle (novox/hq to-be 42 Phase 1, research 026/05): a process the node's runtime
|
||||
// launches and speaks MCP over stdio to, through the Go SDK (ADR 0188, ADR 0193). It reads the
|
||||
// daemon, the name service's wiring and the packet filter's view of mDNS, browses the local network
|
||||
// for services, resolves a name, and lists what the machine publishes. It changes nothing.
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"os"
|
||||
|
||||
stdio "git.novox.be/novox/mesh-sdk/go"
|
||||
)
|
||||
|
||||
// binaryName is what the build names this bundle's executable: the manifest's `binary`.
|
||||
const binaryName = "avahi-tools"
|
||||
|
||||
func bg() context.Context { return context.Background() }
|
||||
|
||||
func main() {
|
||||
// An empty name serves as the module the runtime names (MESH_SERVED_MODULE): avahi.
|
||||
if err := stdio.Serve("", tools(ThisMachine())); err != nil {
|
||||
fmt.Fprintln(os.Stderr, err)
|
||||
os.Exit(1)
|
||||
}
|
||||
}
|
||||
|
||||
func tools(m *Machine) []stdio.Tool {
|
||||
return []stdio.Tool{
|
||||
{
|
||||
Name: "avahi_status",
|
||||
Description: "The daemon's state and version, its configuration as set, the name service switch's hosts line and whether mdns is on it, " +
|
||||
"whether nss-mdns is installed, whether the packet filter accepts inbound mDNS (UDP 5353), whether systemd-resolved runs beside it, " +
|
||||
"and notes naming what keeps discovery from working.",
|
||||
Input: schema(map[string]any{}),
|
||||
Run: func(map[string]any) (any, error) { return m.GetStatus() },
|
||||
},
|
||||
{
|
||||
Name: "avahi_browse",
|
||||
Description: "Listen on the local network for a few seconds (avahi-browse -prt) and answer every service announced, with interface, " +
|
||||
"protocol, name, type, host, address, port and TXT where it resolved; narrowed to one service type when given. Hearing nothing says why it may be.",
|
||||
Input: schema(map[string]any{
|
||||
"seconds": map[string]any{"type": "integer", "description": "how long to listen (default 5, at most 15)"},
|
||||
"type": map[string]any{"type": "string", "description": "one service type, e.g. _ssh._tcp (optional)"},
|
||||
}),
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
n, err := whole(args, "seconds", 5, 1, 15)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
kind, err := text(args, "type", false)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.Browse(n, kind)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "avahi_resolve",
|
||||
Description: "Resolve a .local name to its addresses through avahi, and through the name service (getent) beside it, or an address to its name. " +
|
||||
"An answer from avahi that the name service lacks shows nsswitch unwired; no answer says why it may be.",
|
||||
Input: schema(map[string]any{
|
||||
"name": map[string]any{"type": "string", "description": "a host name; .local is added when missing"},
|
||||
"address": map[string]any{"type": "string", "description": "an address to name instead"},
|
||||
}),
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
name, err := text(args, "name", false)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
address, err := text(args, "address", false)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.Resolve(name, address)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "avahi_services",
|
||||
Description: "What this machine publishes from /etc/avahi/services: each file with the service's name, types and ports.",
|
||||
Input: schema(map[string]any{}),
|
||||
Run: func(map[string]any) (any, error) { return m.Services() },
|
||||
},
|
||||
}
|
||||
}
|
||||
@@ -1,26 +0,0 @@
|
||||
package main
|
||||
|
||||
// The module's shape (novox/hq to-be 42 Phase 1, research 027): the package and the daemon, and
|
||||
// nothing written into the name service switch or opened in the packet filter — avahi.go says why
|
||||
// neither can be declared safely today, and the tools report both instead.
|
||||
|
||||
import "testing"
|
||||
|
||||
func TestItDeclaresThePackageAndTheDaemonOnly(t *testing.T) {
|
||||
m := manifest(t)
|
||||
if p := m.resource(t, "package"); p["package"] != "avahi" {
|
||||
t.Fatalf("%v", p)
|
||||
}
|
||||
d := m.resource(t, "daemon")
|
||||
if d["unit"] != Daemon || d["state"] != "running" || d["boot"] != "enabled" {
|
||||
t.Fatalf("%v", d)
|
||||
}
|
||||
for _, r := range m.Resources {
|
||||
if r["path"] == NSSwitch || r["package"] == "nss-mdns" {
|
||||
t.Fatalf("%v: the name service switch is left as found", r["id"])
|
||||
}
|
||||
}
|
||||
if len(m.Resources) != 2 {
|
||||
t.Fatalf("%v", m.Resources)
|
||||
}
|
||||
}
|
||||
@@ -1,80 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"os"
|
||||
"testing"
|
||||
)
|
||||
|
||||
type resource map[string]any
|
||||
|
||||
type manifestShape struct {
|
||||
Module string `json:"module"`
|
||||
Version string `json:"version"`
|
||||
Capabilities []string `json:"capabilities"`
|
||||
Claims []map[string]any `json:"claims"`
|
||||
Tools []string `json:"tools"`
|
||||
Resources []resource `json:"resources"`
|
||||
Build struct {
|
||||
Artifacts []map[string]any `json:"artifacts"`
|
||||
} `json:"build"`
|
||||
}
|
||||
|
||||
func manifest(t *testing.T) manifestShape {
|
||||
t.Helper()
|
||||
raw, err := os.ReadFile("../../module.json")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var m manifestShape
|
||||
if err := json.Unmarshal(raw, &m); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return m
|
||||
}
|
||||
|
||||
func (m manifestShape) resource(t *testing.T, id string) resource {
|
||||
t.Helper()
|
||||
for _, r := range m.Resources {
|
||||
if r["id"] == id {
|
||||
return r
|
||||
}
|
||||
}
|
||||
t.Fatalf("no resource %s", id)
|
||||
return nil
|
||||
}
|
||||
|
||||
// TestToolsAreTheManifests holds the served tools and the manifest's list to one another, and the
|
||||
// bundle to the shape the builder compiles and the runtime loads.
|
||||
func TestToolsAreTheManifests(t *testing.T) {
|
||||
m := manifest(t)
|
||||
names := map[string]bool{}
|
||||
for _, tool := range tools(machine(nil, 1000)) {
|
||||
if names[tool.Name] {
|
||||
t.Errorf("%s is served twice", tool.Name)
|
||||
}
|
||||
names[tool.Name] = true
|
||||
}
|
||||
for _, want := range m.Tools {
|
||||
if !names[want] {
|
||||
t.Errorf("the manifest lists %s and the bundle does not serve it", want)
|
||||
}
|
||||
delete(names, want)
|
||||
}
|
||||
if len(names) != 0 {
|
||||
t.Errorf("served and not listed: %v", names)
|
||||
}
|
||||
var tools map[string]any
|
||||
for _, a := range m.Build.Artifacts {
|
||||
if a["name"] == "tools" {
|
||||
tools = a
|
||||
}
|
||||
}
|
||||
if tools == nil || tools["kind"] != "bundle" || tools["language"] != "go" || tools["system"] != "arch" ||
|
||||
tools["from"] != "cmd/"+binaryName || tools["binary"] != binaryName {
|
||||
t.Fatalf("the tools artifact: %v", tools)
|
||||
}
|
||||
if loads, _ := tools["loads"].([]any); len(loads) != 1 || loads[0] != binaryName {
|
||||
t.Fatalf("loads: %v", tools["loads"])
|
||||
}
|
||||
}
|
||||
@@ -1,5 +0,0 @@
|
||||
module avahi
|
||||
|
||||
go 1.22
|
||||
|
||||
require git.novox.be/novox/mesh-sdk/go v0.1.6
|
||||
@@ -1,2 +0,0 @@
|
||||
git.novox.be/novox/mesh-sdk/go v0.1.6 h1:9qzdYONYbJdWcu6sxQcq9v1LI0JxcfkiKYkMUzJSkVQ=
|
||||
git.novox.be/novox/mesh-sdk/go v0.1.6/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=
|
||||
@@ -1,43 +0,0 @@
|
||||
{
|
||||
"module": "avahi",
|
||||
"version": "1",
|
||||
"capabilities": [
|
||||
"package-manager",
|
||||
"service-manager"
|
||||
],
|
||||
"tools": [
|
||||
"avahi_status",
|
||||
"avahi_browse",
|
||||
"avahi_resolve",
|
||||
"avahi_services"
|
||||
],
|
||||
"resources": [
|
||||
{
|
||||
"id": "package",
|
||||
"type": "package",
|
||||
"package": "avahi"
|
||||
},
|
||||
{
|
||||
"id": "daemon",
|
||||
"type": "service",
|
||||
"unit": "avahi-daemon.service",
|
||||
"state": "running",
|
||||
"boot": "enabled"
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "tools",
|
||||
"kind": "bundle",
|
||||
"language": "go",
|
||||
"system": "arch",
|
||||
"from": "cmd/avahi-tools",
|
||||
"binary": "avahi-tools",
|
||||
"loads": [
|
||||
"avahi-tools"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -37,15 +37,14 @@ must see, a node that joins later included — kept, so it carries no secret eit
|
||||
|
||||
| what | how |
|
||||
|---|---|
|
||||
| what this node holds | the module's `holdings` state, one key for this node — the account, the kind, fingerprints and expiries, never a token — written at start and whenever the credentials file changes (hq ADR 0206) |
|
||||
| a person ran `/login` here | the credentials file gains a refresh token this module never writes; its next report shows it, and the licence manager asks `claude_code_grant` for it, giving its key — the one time a refresh token leaves the node, for the manager to adopt by refreshing it |
|
||||
| what this node should hold | the licence manager's `bindings` state, this node's key; on a newer generation this module asks `anthropic-licence-manager.current` for its token, sealed to the key it sends, and writes it access-token-only — so the agent here never refreshes. A node that was off reads its key when it is back |
|
||||
| the licence manager rotated a licence, or switched this node | its `licence.rotated` / `licence.switched` event; this module then asks `anthropic-licence-manager.current` for its token, sealed to the key it sends |
|
||||
| this node starts | it asks `current` once, so a node that was off catches up |
|
||||
| a person ran `/login` here | the credentials file gains a refresh token this module never writes; it asks `anthropic-licence-manager.adopt` at once with the grant sealed to the manager's key — the one time a refresh token travels, because the login made the manager's stale |
|
||||
| an MCP server registered through this module | a key in the module's `servers` state — `all.<server>` for every node, `<node>.<server>` for one; every node watches it and renders what applies to it, a node's own entry over the one for every node. A node that joins later, or was off, reads the whole current set at start; unregistering is a delete. An entry with a secret in its `env` or `headers` is refused by the runtime |
|
||||
|
||||
## Tools
|
||||
|
||||
`claude_code_status`, `claude_code_render`, `claude_code_pull`, `claude_code_grant` (for the licence
|
||||
manager), `claude_code_mcp_list`,
|
||||
`claude_code_status`, `claude_code_render`, `claude_code_pull`, `claude_code_mcp_list`,
|
||||
`claude_code_mcp_register` (this node by default; `nodes: "all"` or a list for more — called for this
|
||||
node alone, its answer names the other nodes running claude-code), `claude_code_mcp_unregister`.
|
||||
|
||||
@@ -73,9 +72,3 @@ Remove these by hand, once; the mesh removes nothing it did not make (ADR 0182):
|
||||
Writing `/etc/claude-code` needs root. The runtime runs as the operator account, and the module uses
|
||||
that account's passwordless `sudo`; on a machine without it, `claude_code_render` says so and nothing
|
||||
is written.
|
||||
|
||||
## Code
|
||||
|
||||
Go, one binary (`cmd/claude-code`) the node's runtime launches. Tested with `go test ./...`; the managed
|
||||
instruction file is held to the TypeScript renderer it replaced (`testdata/rendered-by-typescript.json`),
|
||||
and the sealed box is the licence manager's own format.
|
||||
|
||||
@@ -1,364 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"reflect"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
var now = time.Now().UnixMilli()
|
||||
|
||||
func node(t *testing.T, name string) (Paths, map[string]string) {
|
||||
t.Helper()
|
||||
root := t.TempDir()
|
||||
p := Paths{State: filepath.Join(root, "state"), Facts: filepath.Join(root, "state", "facts.json"),
|
||||
Settings: filepath.Join(root, "state", "settings.json"), Home: filepath.Join(root, "home"), Node: name}
|
||||
_ = os.MkdirAll(p.State, 0o700)
|
||||
_ = os.MkdirAll(filepath.Join(p.Home, ".claude"), 0o700)
|
||||
_ = os.WriteFile(p.Facts, []byte(`{"node":"`+name+`","console":"http://127.0.0.1:4270/mcp"}`), 0o600)
|
||||
_ = os.WriteFile(p.Settings, []byte(`{"role":"","mcp_servers":{}}`), 0o600)
|
||||
return p, map[string]string{}
|
||||
}
|
||||
|
||||
func writer(w map[string]string) WriteManaged {
|
||||
return func(name, content string) (string, error) { w[name] = content; return name + ": written", nil }
|
||||
}
|
||||
|
||||
func writeFile(t *testing.T, path, content string) {
|
||||
t.Helper()
|
||||
if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
||||
func creds(t *testing.T, p Paths) map[string]any {
|
||||
t.Helper()
|
||||
var c map[string]any
|
||||
raw, _ := os.ReadFile(p.credentials())
|
||||
if err := json.Unmarshal(raw, &c); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return c["claudeAiOauth"].(map[string]any)
|
||||
}
|
||||
|
||||
// ---- the renderer, held to the TypeScript it replaced -------------------------------------------------
|
||||
|
||||
func TestTheRendererWritesWhatTheTypeScriptOneWrote(t *testing.T) {
|
||||
raw, err := os.ReadFile("testdata/rendered-by-typescript.json")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var f struct {
|
||||
Facts Facts `json:"facts"`
|
||||
Settings Settings `json:"settings"`
|
||||
Registered Servers `json:"registered"`
|
||||
WithKey map[string]string `json:"withKey"`
|
||||
Plain map[string]string `json:"plain"`
|
||||
}
|
||||
if err := json.Unmarshal(raw, &f); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
same := func(label string, got, want map[string]string) {
|
||||
if got["CLAUDE.md"] != want["CLAUDE.md"] {
|
||||
t.Errorf("%s: CLAUDE.md differs from the TypeScript's:\n--- go\n%s\n--- typescript\n%s", label, got["CLAUDE.md"], want["CLAUDE.md"])
|
||||
}
|
||||
for _, file := range []string{"managed-mcp.json", "managed-settings.json"} {
|
||||
var a, b any
|
||||
_ = json.Unmarshal([]byte(got[file]), &a)
|
||||
_ = json.Unmarshal([]byte(want[file]), &b)
|
||||
if !reflect.DeepEqual(a, b) {
|
||||
t.Errorf("%s: %s means something else:\n--- go\n%s\n--- typescript\n%s", label, file, got[file], want[file])
|
||||
}
|
||||
}
|
||||
}
|
||||
same("with an API key", Render(f.Facts, f.Settings, &Binding{Licence: "api", Kind: "api-key"}, "/state/api-key-helper", f.Registered), f.WithKey)
|
||||
same("plain", Render(f.Facts, Settings{}, nil, "/h", Servers{}), f.Plain)
|
||||
}
|
||||
|
||||
func TestASettingCannotReplaceTheMeshsOwnEntryAndABadNameIsLeftOut(t *testing.T) {
|
||||
out := Render(Facts{Node: "w", Console: "http://127.0.0.1:4270/mcp"},
|
||||
Settings{MCPServers: map[string]map[string]any{"mesh": {"type": "http", "url": "http://evil"}, "bad name": {}}}, nil, "/h", nil)
|
||||
var mcp struct {
|
||||
MCPServers map[string]map[string]any `json:"mcpServers"`
|
||||
}
|
||||
_ = json.Unmarshal([]byte(out["managed-mcp.json"]), &mcp)
|
||||
if mcp.MCPServers["mesh"]["url"] != "http://127.0.0.1:4270/mcp" || mcp.MCPServers["bad name"] != nil {
|
||||
t.Fatalf("%v", mcp.MCPServers)
|
||||
}
|
||||
if !reflect.DeepEqual(Render(Facts{Console: "x"}, Settings{}, nil, "/h", nil), Render(Facts{Console: "x"}, Settings{}, nil, "/h", nil)) {
|
||||
t.Fatal("rendering is not deterministic")
|
||||
}
|
||||
}
|
||||
|
||||
// ---- the credentials file -----------------------------------------------------------------------------
|
||||
|
||||
func i64(v int64) *int64 { return &v }
|
||||
|
||||
func TestTheLineageRules(t *testing.T) {
|
||||
const hour = 3_600_000
|
||||
g := func(at string, exp int64, rtExp int64) Grant {
|
||||
return Grant{AccessToken: at, ExpiresAt: exp, RefreshTokenExpiresAt: i64(rtExp)}
|
||||
}
|
||||
month := now + 30*24*hour
|
||||
if d := DecideApply(&Grant{AccessToken: "A", ExpiresAt: now + hour, RefreshTokenExpiresAt: i64(month)}, g("B", now+2*hour, month), false); !d.Apply {
|
||||
t.Fatal("a newer rotation was refused")
|
||||
}
|
||||
if d := DecideApply(&Grant{AccessToken: "new", ExpiresAt: now + 2*hour, RefreshTokenExpiresAt: i64(month)}, g("old", now+hour, month), false); d.Apply || d.Reason != "not-newer" {
|
||||
t.Fatalf("a late older rotation: %+v", d)
|
||||
}
|
||||
if d := DecideApply(&Grant{AccessToken: "A", ExpiresAt: now + 8*hour, RefreshTokenExpiresAt: i64(month)}, g("re", now+hour, now+5*24*hour), false); !d.Apply || !d.Reissued {
|
||||
t.Fatalf("a re-issued grant: %+v", d)
|
||||
}
|
||||
if d := DecideApply(&Grant{AccessToken: "A", ExpiresAt: now + 8*hour}, g("other", now+hour, month), true); !d.Apply {
|
||||
t.Fatal("a switch was refused")
|
||||
}
|
||||
if d := DecideApply(&Grant{AccessToken: "A"}, Grant{AccessToken: "A"}, true); d.Apply || d.Reason != "already-current" {
|
||||
t.Fatalf("the same token: %+v", d)
|
||||
}
|
||||
}
|
||||
|
||||
func TestALoginIsSeenAndStrippedWhenTheNodesOwnGrantIsWritten(t *testing.T) {
|
||||
p, _ := node(t, "laptop")
|
||||
writeFile(t, p.credentials(), `{"claudeAiOauth":{"accessToken":"at-login","refreshToken":"rt-login","expiresAt":1700000000000},"other":1}`)
|
||||
login := ReadCredentials(p.credentials())
|
||||
if !HoldsLogin(login) {
|
||||
t.Fatal("a login was not seen")
|
||||
}
|
||||
if err := WriteCredentials(p.credentials(), WithGrant(login, Grant{AccessToken: "at-mesh", ExpiresAt: 1, Scopes: []string{"user:inference"}})); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
back := ReadCredentials(p.credentials())
|
||||
raw, _ := os.ReadFile(p.credentials())
|
||||
info, _ := os.Stat(p.credentials())
|
||||
if HoldsLogin(back) || GrantOf(back).AccessToken != "at-mesh" || back["other"] == nil || strings.Contains(string(raw), "rt-login") || info.Mode().Perm() != 0o600 {
|
||||
t.Fatalf("written %s (mode %v)", raw, info.Mode())
|
||||
}
|
||||
}
|
||||
|
||||
func TestTheAccountIsReadFromTheAgentsStateFileAndNeverGuessed(t *testing.T) {
|
||||
p, _ := node(t, "laptop")
|
||||
writeFile(t, p.account(), `{"oauthAccount":{"accountUuid":"u-1","emailAddress":"a@example.org"},"other":2}`)
|
||||
if id := ReadIdentity(p.account()); id == nil || id.AccountUUID != "u-1" || id.EmailAddress != "a@example.org" {
|
||||
t.Fatalf("%+v", id)
|
||||
}
|
||||
if ReadIdentity("/nonexistent/.claude.json") != nil {
|
||||
t.Fatal("an identity from nothing")
|
||||
}
|
||||
writeFile(t, p.account(), `{}`)
|
||||
if ReadIdentity(p.account()) != nil {
|
||||
t.Fatal("an identity from an empty file")
|
||||
}
|
||||
}
|
||||
|
||||
// ---- the licence, ADR 0206 ----------------------------------------------------------------------------
|
||||
|
||||
func TestWhatANodeHoldsIsReportedWithFingerprintsAndItsAccountNeverAToken(t *testing.T) {
|
||||
p, _ := node(t, "laptop")
|
||||
writeFile(t, p.credentials(), `{"claudeAiOauth":{"accessToken":"at-secret","refreshToken":"rt-secret","expiresAt":2000,"refreshTokenExpiresAt":9000}}`)
|
||||
writeFile(t, p.account(), `{"oauthAccount":{"accountUuid":"u-1","emailAddress":"a@example.org"}}`)
|
||||
h := HoldingsOf(p)
|
||||
if h.Node != "laptop" || h.Identity.AccountUUID != "u-1" || *h.Kind != "subscription" || !h.Refresh.Present ||
|
||||
!strings.HasPrefix(*h.Refresh.Fingerprint, "sha256:") || h.Access.ExpiresAt != 2000 || h.ChangedAt == nil {
|
||||
t.Fatalf("%+v", h)
|
||||
}
|
||||
raw, _ := json.Marshal(h)
|
||||
if strings.Contains(string(raw), "at-secret") || strings.Contains(string(raw), "rt-secret") {
|
||||
t.Fatalf("a token is in the report: %s", raw)
|
||||
}
|
||||
var keys map[string]any
|
||||
_ = json.Unmarshal(raw, &keys)
|
||||
for k := range keys {
|
||||
if strings.Contains(strings.ToLower(k), "token") || strings.Contains(strings.ToLower(k), "secret") {
|
||||
t.Fatalf("a field the runtime would refuse: %s", k)
|
||||
}
|
||||
}
|
||||
// The manager reads exactly this shape.
|
||||
if _, err := time.Parse(time.RFC3339Nano, *h.ChangedAt); err != nil {
|
||||
t.Fatalf("the manager cannot read the report's time: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestTheGrantAnswersOnlyAWaitingLoginSealedToTheManagersKey(t *testing.T) {
|
||||
p, _ := node(t, "laptop")
|
||||
manager, _ := GenerateKeyPair()
|
||||
if a, _ := GrantFor(p, manager.PublicKey); a.Sealed != nil || a.Waiting == nil || *a.Waiting {
|
||||
t.Fatalf("%+v", a)
|
||||
}
|
||||
writeFile(t, p.credentials(), `{"claudeAiOauth":{"accessToken":"at","refreshToken":"rt-login","expiresAt":1}}`)
|
||||
writeFile(t, p.account(), `{"oauthAccount":{"accountUuid":"u-9"}}`)
|
||||
a, err := GrantFor(p, manager.PublicKey)
|
||||
if err != nil || a.Identity.AccountUUID != "u-9" {
|
||||
t.Fatalf("%+v %v", a, err)
|
||||
}
|
||||
plain, _ := Open(*a.Sealed, manager.PrivateKey)
|
||||
if !strings.Contains(plain, `"refreshToken":"rt-login"`) {
|
||||
t.Fatalf("opened %s", plain)
|
||||
}
|
||||
raw, _ := json.Marshal(a)
|
||||
if strings.Contains(string(raw), "rt-login") {
|
||||
t.Fatal("the refresh token crossed in the clear")
|
||||
}
|
||||
}
|
||||
|
||||
// seat answers `current` as the manager does: the grant sealed to the key the node sent.
|
||||
func seat(t *testing.T, licence, token string, gen int64, asked *[]string) Ask {
|
||||
return func(address string, args any) (json.RawMessage, error) {
|
||||
*asked = append(*asked, address)
|
||||
key := args.(map[string]any)["public_key"].(string)
|
||||
g, _ := json.Marshal(Grant{AccessToken: token, ExpiresAt: now + 3_600_000})
|
||||
box, err := Seal(string(g), key)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return json.Marshal(Current{Licence: licence, Kind: "subscription", Generation: gen, Sealed: &box})
|
||||
}
|
||||
}
|
||||
|
||||
func TestANewerGenerationFetchesTheTokenOnceByTheSeatsVerb(t *testing.T) {
|
||||
p, w := node(t, "laptop")
|
||||
var asked []string
|
||||
ask := seat(t, "personal", "at-1", 3, &asked)
|
||||
if _, err := OnBinding(p, &BindingState{Licence: "personal", Kind: "subscription", Generation: 3}, ask, writer(w)); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if len(asked) != 1 || asked[0] != "seat:anthropic-licence-manager.current" || creds(t, p)["accessToken"] != "at-1" {
|
||||
t.Fatalf("asked %v, credentials %v", asked, creds(t, p))
|
||||
}
|
||||
if done, _ := OnBinding(p, &BindingState{Licence: "personal", Kind: "subscription", Generation: 3}, ask, writer(w)); done != "" || len(asked) != 1 {
|
||||
t.Fatal("an equal generation asked again")
|
||||
}
|
||||
if HoldingsOf(p).Generation != 3 || w["managed-mcp.json"] == "" {
|
||||
t.Fatal("the generation or the managed files were not written")
|
||||
}
|
||||
}
|
||||
|
||||
func TestTheTokenANodeIsHandedReplacesALoginsGrantAndLeavesNoRefreshToken(t *testing.T) {
|
||||
p, w := node(t, "laptop")
|
||||
writeFile(t, p.credentials(), `{"claudeAiOauth":{"accessToken":"at-old","refreshToken":"rt-spent","expiresAt":`+
|
||||
strings.TrimSpace(string(mustJSON(now+7_200_000)))+`}}`)
|
||||
var asked []string
|
||||
out, err := Pull(p, seat(t, "personal", "at-new", 1, &asked), writer(w))
|
||||
if err != nil || out["applied"] != true {
|
||||
t.Fatalf("%v %v", out, err)
|
||||
}
|
||||
c := creds(t, p)
|
||||
if c["accessToken"] != "at-new" || c["refreshToken"] != nil || HoldingsOf(p).Refresh.Present {
|
||||
t.Fatalf("%v", c)
|
||||
}
|
||||
}
|
||||
|
||||
func mustJSON(v any) []byte { b, _ := json.Marshal(v); return b }
|
||||
|
||||
// ---- MCP servers in state, ADR 0201 -------------------------------------------------------------------
|
||||
|
||||
// bus is the `servers` state as every node in a test shares it, with each node's watch.
|
||||
type bus struct {
|
||||
kept map[string]map[string]any
|
||||
watchers []func(ServerChange)
|
||||
}
|
||||
|
||||
func (b *bus) Put(key string, value any) error {
|
||||
v := value.(map[string]any)
|
||||
b.kept[key] = v
|
||||
for _, w := range b.watchers {
|
||||
w(ServerChange{Key: key, Op: "put", Value: v})
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func (b *bus) Delete(key string) error {
|
||||
delete(b.kept, key)
|
||||
for _, w := range b.watchers {
|
||||
w(ServerChange{Key: key, Op: "delete"})
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func (b *bus) Keys() ([]string, error) {
|
||||
var out []string
|
||||
for k := range b.kept {
|
||||
out = append(out, k)
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// join is a node joining: its view takes the current state, then every change.
|
||||
func (b *bus) join(p Paths, w map[string]string) *ServerView {
|
||||
v := NewServerView(p)
|
||||
for k, val := range b.kept {
|
||||
_, _ = OnServerChange(v, ServerChange{Key: k, Op: "put", Value: val}, p, writer(w))
|
||||
}
|
||||
b.watchers = append(b.watchers, func(c ServerChange) { _, _ = OnServerChange(v, c, p, writer(w)) })
|
||||
return v
|
||||
}
|
||||
|
||||
func noOthers() ([]string, error) { return nil, nil }
|
||||
|
||||
func TestRegisteringHerePutsItUnderThisNodesKeyAndAsksAboutTheOthers(t *testing.T) {
|
||||
p, w := node(t, "laptop")
|
||||
b := &bus{kept: map[string]map[string]any{}}
|
||||
v := b.join(p, w)
|
||||
r, err := RegisterServer(p, Registration{Name: "search", Entry: map[string]any{"type": "http", "url": "https://s.example/mcp"}}, b, v, writer(w),
|
||||
func() ([]string, error) { return []string{"laptop", "server", "desktop"}, nil })
|
||||
if err != nil || r["here"] != "changed" || !strings.Contains(r["also"].(string), "server, desktop") || b.kept["laptop.search"] == nil {
|
||||
t.Fatalf("%v %v %v", r, err, b.kept)
|
||||
}
|
||||
if !strings.Contains(w["managed-mcp.json"], `"search"`) {
|
||||
t.Fatal("not rendered")
|
||||
}
|
||||
}
|
||||
|
||||
func TestEveryNodeRegistrationReachesTheOthersAndALateNodeReadsIt(t *testing.T) {
|
||||
a, wa := node(t, "laptop")
|
||||
s, ws := node(t, "server")
|
||||
b := &bus{kept: map[string]map[string]any{}}
|
||||
va := b.join(a, wa)
|
||||
b.join(s, ws)
|
||||
_, _ = RegisterServer(a, Registration{Name: "docs", Entry: map[string]any{"type": "stdio", "command": "docs-mcp"}, Nodes: []string{"all"}}, b, va, writer(wa), noOthers)
|
||||
if Registered(s)["docs"] == nil || !strings.Contains(ws["managed-mcp.json"], "docs-mcp") {
|
||||
t.Fatalf("the other node did not take it: %v", Registered(s))
|
||||
}
|
||||
late, wl := node(t, "desktop")
|
||||
b.join(late, wl)
|
||||
if Registered(late)["docs"] == nil {
|
||||
t.Fatal("a node joining later did not read the current set")
|
||||
}
|
||||
_, _ = RegisterServer(a, Registration{Name: "docs", Nodes: []string{"all"}}, b, va, writer(wa), noOthers)
|
||||
if Registered(s)["docs"] != nil || Registered(late)["docs"] != nil {
|
||||
t.Fatal("an unregistration did not reach every node")
|
||||
}
|
||||
}
|
||||
|
||||
func TestANodesOwnRegistrationOverridesTheOneForEveryNode(t *testing.T) {
|
||||
a, wa := node(t, "laptop")
|
||||
s, ws := node(t, "server")
|
||||
b := &bus{kept: map[string]map[string]any{}}
|
||||
va := b.join(a, wa)
|
||||
b.join(s, ws)
|
||||
_, _ = RegisterServer(a, Registration{Name: "x", Entry: map[string]any{"type": "http", "url": "https://all"}, Nodes: []string{"all"}}, b, va, writer(wa), noOthers)
|
||||
_, _ = RegisterServer(a, Registration{Name: "x", Entry: map[string]any{"type": "http", "url": "https://laptop"}}, b, va, writer(wa), noOthers)
|
||||
if Registered(a)["x"]["url"] != "https://laptop" || Registered(s)["x"]["url"] != "https://all" {
|
||||
t.Fatalf("%v %v", Registered(a), Registered(s))
|
||||
}
|
||||
r, _ := RegisterServer(a, Registration{Name: "x"}, b, va, writer(wa), noOthers)
|
||||
if !strings.Contains(r["still"].(string), "still applies here") || Registered(a)["x"]["url"] != "https://all" {
|
||||
t.Fatalf("%v", r)
|
||||
}
|
||||
}
|
||||
|
||||
func TestABadEntryIsRefusedBeforeAnythingIsPut(t *testing.T) {
|
||||
p, w := node(t, "laptop")
|
||||
b := &bus{kept: map[string]map[string]any{}}
|
||||
v := b.join(p, w)
|
||||
r, _ := RegisterServer(p, Registration{Name: "mesh", Entry: map[string]any{"type": "http", "url": "https://x"}}, b, v, writer(w), noOthers)
|
||||
if r["registered"] != false || len(b.kept) != 0 {
|
||||
t.Fatalf("%v %v", r, b.kept)
|
||||
}
|
||||
if done, _ := OnServerChange(v, ServerChange{Key: "server.b", Op: "put", Value: map[string]any{"type": "http", "url": "https://b"}}, p, writer(w)); done != "" {
|
||||
t.Fatal("another node's key changed this one")
|
||||
}
|
||||
}
|
||||
@@ -1,198 +0,0 @@
|
||||
package main
|
||||
|
||||
// The agent's credentials file, and whether an offered grant may replace what it holds (novox/hq ADR 0183,
|
||||
// ADR 0206, design 36 §5). Pure where it decides, so the rules are tested without a file.
|
||||
//
|
||||
// The file is the vendor's: `{ claudeAiOauth: { accessToken, expiresAt, refreshTokenExpiresAt?, scopes?,
|
||||
// subscriptionType?, rateLimitTier? }, ... }`. A node bound to a licence never holds a refresh token, so
|
||||
// the one this module writes never carries one; a refresh token found there is a person's login.
|
||||
//
|
||||
// The lineage rule is the predecessor's, with the incidents that earned it: a rotation of the same licence
|
||||
// is applied only if newer; a grant re-issued by a login is adopted whatever its expiry; a switch to another
|
||||
// licence is applied regardless, because across licences the expiries are unrelated numbers.
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"math"
|
||||
"os"
|
||||
"path/filepath"
|
||||
)
|
||||
|
||||
// Grant is what the manager hands a node: an access token and its expiries, never a refresh token.
|
||||
type Grant struct {
|
||||
AccessToken string `json:"accessToken"`
|
||||
ExpiresAt int64 `json:"expiresAt"`
|
||||
RefreshTokenExpiresAt *int64 `json:"refreshTokenExpiresAt,omitempty"`
|
||||
Scopes []string `json:"scopes,omitempty"`
|
||||
SubscriptionType string `json:"subscriptionType,omitempty"`
|
||||
RateLimitTier string `json:"rateLimitTier,omitempty"`
|
||||
}
|
||||
|
||||
// Decision is whether a handed grant is applied, and why not.
|
||||
type Decision struct {
|
||||
Apply bool
|
||||
Reissued bool
|
||||
Reason string // already-current | not-newer
|
||||
}
|
||||
|
||||
// generationTolerance: two refresh-token expiries within a day are one lineage; a login starts a fresh
|
||||
// window weeks away.
|
||||
const generationTolerance = 24 * 60 * 60 * 1000
|
||||
|
||||
func sameGeneration(a, b *int64) bool {
|
||||
if a == nil || b == nil {
|
||||
return true
|
||||
}
|
||||
return math.Abs(float64(*a-*b)) <= generationTolerance
|
||||
}
|
||||
|
||||
// DecideApply says whether an offered grant replaces the one held; switch is a move to another licence.
|
||||
func DecideApply(local *Grant, offered Grant, switching bool) Decision {
|
||||
if local == nil || local.AccessToken == "" {
|
||||
return Decision{Apply: true}
|
||||
}
|
||||
if local.AccessToken == offered.AccessToken {
|
||||
return Decision{Reason: "already-current"}
|
||||
}
|
||||
reissued := !sameGeneration(local.RefreshTokenExpiresAt, offered.RefreshTokenExpiresAt)
|
||||
if !switching && !reissued && local.ExpiresAt >= offered.ExpiresAt {
|
||||
return Decision{Reason: "not-newer"}
|
||||
}
|
||||
return Decision{Apply: true, Reissued: reissued}
|
||||
}
|
||||
|
||||
// Credentials is the file as found, every key kept — the vendor's other keys are not this module's.
|
||||
type Credentials map[string]any
|
||||
|
||||
func (c Credentials) oauth() map[string]any {
|
||||
o, _ := c["claudeAiOauth"].(map[string]any)
|
||||
return o
|
||||
}
|
||||
|
||||
// ReadCredentials reads the file, keeping numbers as written; nil when there is none.
|
||||
func ReadCredentials(path string) Credentials {
|
||||
raw, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return nil
|
||||
}
|
||||
dec := json.NewDecoder(bytes.NewReader(raw))
|
||||
dec.UseNumber()
|
||||
var c Credentials
|
||||
if dec.Decode(&c) != nil {
|
||||
return nil
|
||||
}
|
||||
return c
|
||||
}
|
||||
|
||||
func number(v any) (int64, bool) {
|
||||
switch n := v.(type) {
|
||||
case json.Number:
|
||||
i, err := n.Int64()
|
||||
if err != nil {
|
||||
f, err := n.Float64()
|
||||
return int64(f), err == nil
|
||||
}
|
||||
return i, true
|
||||
case float64:
|
||||
return int64(n), true
|
||||
case int64:
|
||||
return n, true
|
||||
}
|
||||
return 0, false
|
||||
}
|
||||
|
||||
// GrantOf is the grant the file holds, or nil.
|
||||
func GrantOf(c Credentials) *Grant {
|
||||
o := c.oauth()
|
||||
at, _ := o["accessToken"].(string)
|
||||
if at == "" {
|
||||
return nil
|
||||
}
|
||||
g := &Grant{AccessToken: at}
|
||||
g.ExpiresAt, _ = number(o["expiresAt"])
|
||||
if v, ok := number(o["refreshTokenExpiresAt"]); ok {
|
||||
g.RefreshTokenExpiresAt = &v
|
||||
}
|
||||
return g
|
||||
}
|
||||
|
||||
// HoldsLogin says the file holds a refresh token — which this module never writes, so a person's login.
|
||||
func HoldsLogin(c Credentials) bool {
|
||||
rt, _ := c.oauth()["refreshToken"].(string)
|
||||
return rt != ""
|
||||
}
|
||||
|
||||
// RefreshTokenOf is the refresh token a login left, or "".
|
||||
func RefreshTokenOf(c Credentials) string {
|
||||
rt, _ := c.oauth()["refreshToken"].(string)
|
||||
return rt
|
||||
}
|
||||
|
||||
// WithGrant lays the handed grant over what is there, and deletes any refresh token.
|
||||
func WithGrant(local Credentials, g Grant) Credentials {
|
||||
next := Credentials{}
|
||||
for k, v := range local {
|
||||
next[k] = v
|
||||
}
|
||||
oauth := map[string]any{}
|
||||
for k, v := range local.oauth() {
|
||||
oauth[k] = v
|
||||
}
|
||||
oauth["accessToken"] = g.AccessToken
|
||||
oauth["expiresAt"] = g.ExpiresAt
|
||||
if g.RefreshTokenExpiresAt != nil {
|
||||
oauth["refreshTokenExpiresAt"] = *g.RefreshTokenExpiresAt
|
||||
}
|
||||
if len(g.Scopes) > 0 {
|
||||
oauth["scopes"] = g.Scopes
|
||||
}
|
||||
if g.SubscriptionType != "" {
|
||||
oauth["subscriptionType"] = g.SubscriptionType
|
||||
}
|
||||
if g.RateLimitTier != "" {
|
||||
oauth["rateLimitTier"] = g.RateLimitTier
|
||||
}
|
||||
delete(oauth, "refreshToken")
|
||||
next["claudeAiOauth"] = oauth
|
||||
return next
|
||||
}
|
||||
|
||||
// ReplacedBy is the handed grant in place of the old licence's, whole — scopes and subscription included;
|
||||
// only keys outside the grant stay. No refresh token survives.
|
||||
func ReplacedBy(local Credentials, g Grant) Credentials {
|
||||
next := Credentials{}
|
||||
for k, v := range local {
|
||||
if k != "claudeAiOauth" {
|
||||
next[k] = v
|
||||
}
|
||||
}
|
||||
return WithGrant(next, g)
|
||||
}
|
||||
|
||||
// WriteCredentials writes atomically at 0600: a partial credentials file must never be read as a whole one.
|
||||
func WriteCredentials(path string, c Credentials) error {
|
||||
if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
|
||||
return err
|
||||
}
|
||||
raw, err := indented(c)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
tmp := path + ".mesh-tmp"
|
||||
if err := os.WriteFile(tmp, raw, 0o600); err != nil {
|
||||
return err
|
||||
}
|
||||
return os.Rename(tmp, path)
|
||||
}
|
||||
|
||||
// indented is JSON as the agent's own files are written: two-space indent, a trailing newline, nothing
|
||||
// escaped that need not be.
|
||||
func indented(v any) ([]byte, error) {
|
||||
var b bytes.Buffer
|
||||
enc := json.NewEncoder(&b)
|
||||
enc.SetEscapeHTML(false)
|
||||
enc.SetIndent("", " ")
|
||||
err := enc.Encode(v)
|
||||
return b.Bytes(), err
|
||||
}
|
||||
@@ -1,84 +0,0 @@
|
||||
package main
|
||||
|
||||
// Which account the agent is logged in as (novox/hq ADR 0183): not in the token, but in the agent's own
|
||||
// state file beside the home, `~/.claude.json` → `oauthAccount`. Read to report and attribute a login;
|
||||
// written, three keys and nothing else, when a licence is switched, so the account Claude Code shows is
|
||||
// the one whose token it now holds.
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"os"
|
||||
)
|
||||
|
||||
// Identity is an account as the agent's state file names it.
|
||||
type Identity struct {
|
||||
AccountUUID string `json:"accountUuid"`
|
||||
EmailAddress string `json:"emailAddress,omitempty"`
|
||||
OrganizationUUID string `json:"organizationUuid,omitempty"`
|
||||
}
|
||||
|
||||
func readState(path string) (map[string]any, bool) {
|
||||
raw, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return nil, false
|
||||
}
|
||||
dec := json.NewDecoder(bytes.NewReader(raw))
|
||||
dec.UseNumber()
|
||||
var m map[string]any
|
||||
if dec.Decode(&m) != nil || m == nil {
|
||||
return nil, false
|
||||
}
|
||||
return m, true
|
||||
}
|
||||
|
||||
// ReadIdentity is the account the state file names, or nil — never a guess.
|
||||
func ReadIdentity(path string) *Identity {
|
||||
m, ok := readState(path)
|
||||
if !ok {
|
||||
return nil
|
||||
}
|
||||
a, _ := m["oauthAccount"].(map[string]any)
|
||||
uuid, _ := a["accountUuid"].(string)
|
||||
if uuid == "" {
|
||||
return nil
|
||||
}
|
||||
id := &Identity{AccountUUID: uuid}
|
||||
id.EmailAddress, _ = a["emailAddress"].(string)
|
||||
id.OrganizationUUID, _ = a["organizationUuid"].(string)
|
||||
return id
|
||||
}
|
||||
|
||||
// WriteIdentity points the state file's account at id, keeping every other key as found; answers whether
|
||||
// the file changed. A file that is there and cannot be read as an object is left alone.
|
||||
func WriteIdentity(path string, id Identity) (bool, error) {
|
||||
m, ok := readState(path)
|
||||
if !ok {
|
||||
if _, err := os.Stat(path); err == nil {
|
||||
return false, nil
|
||||
}
|
||||
m = map[string]any{}
|
||||
}
|
||||
current, _ := m["oauthAccount"].(map[string]any)
|
||||
if current == nil {
|
||||
current = map[string]any{}
|
||||
}
|
||||
e, _ := current["emailAddress"].(string)
|
||||
o, _ := current["organizationUuid"].(string)
|
||||
if current["accountUuid"] == id.AccountUUID && e == id.EmailAddress && o == id.OrganizationUUID {
|
||||
return false, nil
|
||||
}
|
||||
current["accountUuid"] = id.AccountUUID
|
||||
current["emailAddress"] = id.EmailAddress
|
||||
current["organizationUuid"] = id.OrganizationUUID
|
||||
m["oauthAccount"] = current
|
||||
raw, err := indented(m)
|
||||
if err != nil {
|
||||
return false, err
|
||||
}
|
||||
tmp := path + ".mesh-tmp"
|
||||
if err := os.WriteFile(tmp, raw, 0o600); err != nil {
|
||||
return false, err
|
||||
}
|
||||
return true, os.Rename(tmp, path)
|
||||
}
|
||||
@@ -1,12 +0,0 @@
|
||||
package main
|
||||
|
||||
// instructionsText is the managed instruction file, generated from the TypeScript renderer it replaced so
|
||||
// the file under the agent's managed directory did not change by a byte when the module moved to Go;
|
||||
// a test holds it to that renderer's own output (testdata/rendered-by-typescript.json).
|
||||
func instructionsText(node, role string) string {
|
||||
return "# This machine is a node of a Novox mesh\n\nWritten by the mesh's `claude-code` module. Edit the module's settings or the catalogue, never this file:\nit is rewritten whenever the module renders.\n\n## Who this node is\n\n- **Node:** `" +
|
||||
node +
|
||||
"`\n- **Role:** " +
|
||||
role +
|
||||
"\n- The other nodes, their roles and what runs where: ask the controller (`mesh-controller.nodes`,\n `mesh-controller.node`). Nothing here lists them, because a copy drifts.\n\n## How a session on this mesh works\n\nThe console is the only way to the mesh: the MCP server named `mesh`. It offers five tools, and\neverything else is an address you find and call through them:\n\n- `mesh_search` — words in, matching addresses out. `mesh_describe` — one address's arguments.\n- `mesh_call` — call an address. A seat the mesh holds once is `<seat>.<verb>` (the mesh's own verbs\n are `mesh-controller.<verb>`: `status`, `plan`, `node`, `assign`, `push`, `settings`);\n a module on a machine is `<node>/<module>.<tool>`.\n- `mesh_overview` and `mesh_machine` — the mesh's seats and machines, and what one machine runs.\n\n- **Symptom first.** For an error, a failing service or anything unexpected, search the record with the\n literal text before forming a hypothesis: the records module's `records_search`, then\n `records_read`.\n- **Ask the mesh before changing it**, and change it through the controller's verbs or the catalogue.\n- **A licence** through the `anthropic-licence-manager` seat's verbs. Never edit the agent's credentials\n file by hand, never print or ask for a token.\n\n## Hard rules\n\n- A file the mesh manages is changed through the verb or the catalogue that owns it, never on disk. If\n unsure, `mesh-controller.plan` for the node says what the mesh writes there.\n- Never write to a store's database by hand; schema changes are numbered migrations.\n- Never push to a main branch: a branch, a pull request, and a human approval for every merge.\n- The mesh creates no symlinks, and nobody else does either.\n- A package is declared in a module, never installed by hand.\n\n## Conventions\n\n- Commit messages are concise, in the imperative, about why.\n- Test before pushing: nodes update unattended.\n- The playbooks in the record say how research, decisions, designs, issues and hand-offs are done.\n"
|
||||
}
|
||||
@@ -1,365 +0,0 @@
|
||||
// claude-code's bundle (novox/hq design 36, ADR 0183, ADR 0206): a binary the node's runtime launches over
|
||||
// stdio as the operator account (ADR 0193) and is the bus for (ADR 0198). It is given its state directory
|
||||
// and two files the mesh renders into it (ADR 0192), beside the runtime's own words.
|
||||
//
|
||||
// At start it renders the agent's managed directory, reports what this node holds as the module's
|
||||
// `holdings` state and again whenever the credentials file changes, watches the licence manager's
|
||||
// `bindings` state for this node and fetches the token when it says so, and watches the module's
|
||||
// `servers` state — every node's MCP server registrations (ADR 0201). node.go holds the logic.
|
||||
//
|
||||
// stdout is the MCP channel; everything this module says, it says on stderr.
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"os"
|
||||
"os/exec"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
stdio "git.novox.be/novox/mesh-sdk/go"
|
||||
)
|
||||
|
||||
func say(format string, args ...any) {
|
||||
fmt.Fprintf(os.Stderr, "[claude-code] "+format+"\n", args...)
|
||||
}
|
||||
|
||||
// writeManaged writes one managed file as root, only when its content changed. From a staged file, never
|
||||
// /dev/stdin: a child's input may be a socket, which /dev/stdin cannot open (found on the first assignment).
|
||||
func writeManaged(name, content string) (string, error) {
|
||||
path := filepath.Join(ManagedDir, name)
|
||||
if was, err := os.ReadFile(path); err == nil && string(was) == content {
|
||||
return name + ": unchanged", nil
|
||||
}
|
||||
staged, err := os.MkdirTemp("", "claude-code-")
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
defer os.RemoveAll(staged)
|
||||
source := filepath.Join(staged, name)
|
||||
if err := os.WriteFile(source, []byte(content), 0o644); err != nil {
|
||||
return "", err
|
||||
}
|
||||
args := []string{"install", "-D", "-m", "0644", source, path}
|
||||
if os.Geteuid() != 0 {
|
||||
args = append([]string{"sudo", "-n"}, args...)
|
||||
}
|
||||
if out, err := exec.Command(args[0], args[1:]...).CombinedOutput(); err != nil {
|
||||
return "", fmt.Errorf("%s: could not be written to %s (%s); the module writes there through the operator account's passwordless sudo",
|
||||
name, ManagedDir, strings.TrimSpace(string(out)))
|
||||
}
|
||||
return name + ": written", nil
|
||||
}
|
||||
|
||||
// ask is a tool on the bus, through the runtime: its answer is the tool's value.
|
||||
func ask(address string, args any) (json.RawMessage, error) { return stdio.Ask(address, args) }
|
||||
|
||||
// stateOf adapts the SDK's state to what node.go asks of one.
|
||||
type stateOf struct{ s stdio.KeptState }
|
||||
|
||||
func (s stateOf) Put(key string, value any) error { _, err := s.s.Put(key, value); return err }
|
||||
func (s stateOf) Delete(key string) error { return s.s.Delete(key) }
|
||||
func (s stateOf) Keys() ([]string, error) { return s.s.Keys() }
|
||||
|
||||
// nodesRunningMe is the nodes claude-code runs on, from the controller's list of modules — for the register
|
||||
// tool's question.
|
||||
func nodesRunningMe() ([]string, error) {
|
||||
raw, err := ask("seat:mesh-controller.modules", map[string]any{})
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
var answer struct {
|
||||
Output string `json:"output"`
|
||||
}
|
||||
text := string(raw)
|
||||
if json.Unmarshal(raw, &answer) == nil && answer.Output != "" {
|
||||
text = answer.Output
|
||||
}
|
||||
for _, line := range strings.Split(text, "\n") {
|
||||
if !strings.HasPrefix(line, "claude-code ") {
|
||||
continue
|
||||
}
|
||||
_, on, ok := strings.Cut(line, " on ")
|
||||
if !ok || strings.TrimSpace(on) == "nothing" {
|
||||
return nil, nil
|
||||
}
|
||||
var out []string
|
||||
for _, n := range strings.Split(on, ",") {
|
||||
if n = strings.TrimSpace(n); n != "" {
|
||||
out = append(out, n)
|
||||
}
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
return nil, nil
|
||||
}
|
||||
|
||||
func fingerprintOfFile(path string) any {
|
||||
raw, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return nil
|
||||
}
|
||||
return Fingerprint(string(raw))
|
||||
}
|
||||
|
||||
func status(p Paths) map[string]any {
|
||||
creds := ReadCredentials(p.credentials())
|
||||
var token any
|
||||
if g := GrantOf(creds); g != nil {
|
||||
token = map[string]any{"fingerprint": Fingerprint(g.AccessToken), "expiresAt": stamp(g.ExpiresAt), "loginWaiting": HoldsLogin(creds)}
|
||||
}
|
||||
var managed []map[string]any
|
||||
for _, f := range []string{"managed-mcp.json", "managed-settings.json", "CLAUDE.md"} {
|
||||
path := filepath.Join(ManagedDir, f)
|
||||
managed = append(managed, map[string]any{"file": path, "fingerprint": fingerprintOfFile(path)})
|
||||
}
|
||||
var licence any
|
||||
var b Binding
|
||||
if readJSON(p.binding(), &b) {
|
||||
licence = b
|
||||
}
|
||||
names := []string{}
|
||||
for n := range Registered(p) {
|
||||
names = append(names, n)
|
||||
}
|
||||
return map[string]any{"node": p.Node, "licence": licence, "token": token, "holdings": HoldingsOf(p),
|
||||
"managed": managed, "registered": names}
|
||||
}
|
||||
|
||||
func str(description string) map[string]any {
|
||||
return map[string]any{"type": "string", "description": description}
|
||||
}
|
||||
|
||||
// nodesOf reads the tools' `nodes` argument: absent is this node, "all" every node, else a list.
|
||||
func nodesOf(v any) []string {
|
||||
s, _ := v.(string)
|
||||
s = strings.TrimSpace(s)
|
||||
switch s {
|
||||
case "":
|
||||
return nil
|
||||
case "all":
|
||||
return []string{"all"}
|
||||
}
|
||||
var out []string
|
||||
for _, n := range strings.Split(s, ",") {
|
||||
if n = strings.TrimSpace(n); n != "" {
|
||||
out = append(out, n)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func tools(p Paths, servers ServerState, view *ServerView) []stdio.Tool {
|
||||
nodesArg := str(`more nodes: "all" for every node running claude-code, or a comma-separated list; absent is this node only`)
|
||||
return []stdio.Tool{
|
||||
{Name: "claude_code_status",
|
||||
Description: "Claude Code on this machine as the mesh configured it: the licence it holds and when its token expires, what it reports holding, the managed files, the MCP servers registered here. Fingerprints only, never a token.",
|
||||
Run: func(map[string]any) (any, error) { return status(p), nil }},
|
||||
{Name: "claude_code_render",
|
||||
Description: "Write Claude Code's managed directory now, from the mesh's facts, this module's settings and the servers registered here.",
|
||||
Run: func(map[string]any) (any, error) {
|
||||
out, err := RenderNow(p, writeManaged)
|
||||
return map[string]any{"rendered": out}, err
|
||||
}},
|
||||
{Name: "claude_code_pull",
|
||||
Description: "Ask the licence manager for this node's current token now and apply it, rather than waiting for its binding to change.",
|
||||
Run: func(map[string]any) (any, error) { return Pull(p, ask, writeManaged) }},
|
||||
{Name: "claude_code_grant",
|
||||
Description: "For the licence manager (ADR 0206): the full grant in this node's credentials file — a login made here — sealed to the public key given, with the account it belongs to. Nothing when no login is waiting. Never answers a token in the clear.",
|
||||
Input: map[string]any{"public_key": str("the manager's public key, PEM; the grant opens only with its private half")},
|
||||
Run: func(a map[string]any) (any, error) {
|
||||
key, _ := a["public_key"].(string)
|
||||
if !strings.Contains(key, "PUBLIC KEY") {
|
||||
return nil, errors.New("claude_code_grant seals to a public key, and none was given")
|
||||
}
|
||||
return GrantFor(p, key)
|
||||
}},
|
||||
{Name: "claude_code_mcp_list",
|
||||
Description: "The MCP servers registered through this module: those that apply on this node (beside the console, `mesh`, and those set in the module's settings), and every registration on the mesh, by key — `all.<server>` for every node, `<node>.<server>` for one.",
|
||||
Run: func(map[string]any) (any, error) {
|
||||
keys, err := servers.Keys()
|
||||
return map[string]any{"here": Registered(p), "everywhere": keys}, err
|
||||
}},
|
||||
{Name: "claude_code_mcp_register",
|
||||
Description: "Register an MCP server with Claude Code on this node, every node, or a list — an http/sse server by url, or a stdio server by command. Kept on the bus, so a node that joins later takes it too. Never put a secret in env or headers: the mesh refuses one.",
|
||||
Input: map[string]any{
|
||||
"name": str("the server's name: letters, digits, - and _"),
|
||||
"type": str("http, sse or stdio (default stdio when a command is given, http when a url is)"),
|
||||
"url": str("an http or sse server's url"),
|
||||
"command": str("a stdio server's program"),
|
||||
"args": map[string]any{"type": "array", "description": "a stdio server's arguments"},
|
||||
"env": map[string]any{"type": "object", "description": "a stdio server's environment"},
|
||||
"headers": map[string]any{"type": "object", "description": "an http server's headers"},
|
||||
"nodes": nodesArg,
|
||||
},
|
||||
Run: func(a map[string]any) (any, error) {
|
||||
entry := map[string]any{}
|
||||
if t, _ := a["type"].(string); t != "" {
|
||||
entry["type"] = t
|
||||
} else if _, hasURL := a["url"]; hasURL {
|
||||
entry["type"] = "http"
|
||||
} else {
|
||||
entry["type"] = "stdio"
|
||||
}
|
||||
for _, k := range []string{"url", "command", "args", "env", "headers"} {
|
||||
if v, ok := a[k]; ok {
|
||||
entry[k] = v
|
||||
}
|
||||
}
|
||||
name, _ := a["name"].(string)
|
||||
return RegisterServer(p, Registration{Name: name, Entry: entry, Nodes: nodesOf(a["nodes"])}, servers, view, writeManaged, nodesRunningMe)
|
||||
}},
|
||||
{Name: "claude_code_mcp_unregister",
|
||||
Description: "Remove an MCP server registered through this module, on this node or more.",
|
||||
Input: map[string]any{"name": str("the server's name"), "nodes": nodesArg},
|
||||
Run: func(a map[string]any) (any, error) {
|
||||
name, _ := a["name"].(string)
|
||||
return RegisterServer(p, Registration{Name: name, Nodes: nodesOf(a["nodes"])}, servers, view, writeManaged, nodesRunningMe)
|
||||
}},
|
||||
}
|
||||
}
|
||||
|
||||
// persist asks the state again until it answers: its bucket or the bus's grant may arrive after the module.
|
||||
func persist(what string, attempt func() error, done func(refusals int)) {
|
||||
waits := []time.Duration{2 * time.Second, 5 * time.Second, 10 * time.Second, 30 * time.Second}
|
||||
for n := 0; ; n++ {
|
||||
err := attempt()
|
||||
if err == nil {
|
||||
done(n)
|
||||
return
|
||||
}
|
||||
pause := time.Minute
|
||||
if n < len(waits) {
|
||||
pause = waits[n]
|
||||
}
|
||||
say("%s not yet (%v); asking again in %s", what, err, pause)
|
||||
time.Sleep(pause)
|
||||
}
|
||||
}
|
||||
|
||||
func main() {
|
||||
p, launched := PathsFrom(os.Getenv)
|
||||
if !launched {
|
||||
// Outside a launch — a build, a check — it serves nothing and says why.
|
||||
say("not launched by the runtime with this module's words; serving no tools")
|
||||
if err := stdio.Serve("", nil); err != nil {
|
||||
os.Exit(1)
|
||||
}
|
||||
return
|
||||
}
|
||||
if _, err := Keypair(p); err != nil {
|
||||
say("this module's key: %v", err)
|
||||
}
|
||||
if out, err := RenderNow(p, writeManaged); err != nil {
|
||||
say("%v", err)
|
||||
} else {
|
||||
for _, line := range out {
|
||||
if !strings.HasSuffix(line, "unchanged") {
|
||||
say("%s", line)
|
||||
}
|
||||
}
|
||||
}
|
||||
servers := stateOf{stdio.State("servers")}
|
||||
view := NewServerView(p)
|
||||
go run(p, view)
|
||||
if err := stdio.Serve("", tools(p, servers, view)); err != nil {
|
||||
say("%v", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
}
|
||||
|
||||
// run is the module's long-running half, beside the tools (ADR 0198).
|
||||
func run(p Paths, view *ServerView) {
|
||||
// Every node's MCP servers: the whole current set first, then each change (ADR 0201).
|
||||
go persist("watching the MCP servers", func() error {
|
||||
return stdio.State("servers").Watch("", func(c stdio.StateChange) error {
|
||||
var value map[string]any
|
||||
_ = json.Unmarshal(c.Value, &value)
|
||||
if done, err := OnServerChange(view, ServerChange{Key: c.Key, Op: c.Op, Value: value}, p, writeManaged); err != nil {
|
||||
say("taking %s %s: %v", c.Op, c.Key, err) // the view took it; the next render writes it
|
||||
} else if done != "" {
|
||||
say("%s", done)
|
||||
}
|
||||
return nil
|
||||
})
|
||||
}, func(n int) { say("watching the MCP servers%s", refusals(n)) })
|
||||
|
||||
// What this node holds (ADR 0206): at start — a node already logged in is reported at once — and on
|
||||
// every change of the credentials file, polled, because the file is replaced by rename and a watch on
|
||||
// the old inode would go quiet. Fingerprints and expiries only.
|
||||
holdings := stdio.State("holdings")
|
||||
reported := ""
|
||||
report := func() {
|
||||
now := HoldingsOf(p)
|
||||
raw, _ := json.Marshal(now)
|
||||
if string(raw) == reported {
|
||||
return
|
||||
}
|
||||
persist("reporting what this node holds", func() error { _, err := holdings.Put(p.Node, now); return err }, func(int) {
|
||||
reported = string(raw)
|
||||
account := "no account"
|
||||
if now.Identity != nil && now.Identity.EmailAddress != "" {
|
||||
account = now.Identity.EmailAddress
|
||||
}
|
||||
line := "reported: " + account
|
||||
if now.Kind != nil {
|
||||
line += ", " + *now.Kind
|
||||
}
|
||||
if now.Refresh.Present {
|
||||
line += ", a login waiting"
|
||||
}
|
||||
if now.Licence != nil {
|
||||
line += fmt.Sprintf(", licence %s g%d", *now.Licence, now.Generation)
|
||||
}
|
||||
say("%s", line)
|
||||
})
|
||||
}
|
||||
|
||||
// What this node should hold (ADR 0206): the manager's `bindings` key for this node; a newer
|
||||
// generation is fetched with the seat's `current`, sealed to this module's key.
|
||||
go persist("watching this node's licence binding", func() error {
|
||||
return stdio.State(Manager+".bindings").Watch(p.Node, func(c stdio.StateChange) error {
|
||||
if c.Key != p.Node {
|
||||
return nil
|
||||
}
|
||||
var b *BindingState
|
||||
if c.Op == "put" {
|
||||
b = &BindingState{}
|
||||
if err := json.Unmarshal(c.Value, b); err != nil {
|
||||
return nil
|
||||
}
|
||||
}
|
||||
if done, err := OnBinding(p, b, ask, writeManaged); err != nil {
|
||||
say("fetching this node's token failed: %v", err)
|
||||
} else if done != "" {
|
||||
say("%s", done)
|
||||
}
|
||||
go report()
|
||||
return nil
|
||||
})
|
||||
}, func(n int) { say("watching this node's licence binding%s", refusals(n)) })
|
||||
|
||||
report()
|
||||
var last string
|
||||
for range time.Tick(5 * time.Second) {
|
||||
info, err := os.Stat(p.credentials())
|
||||
now := "absent"
|
||||
if err == nil {
|
||||
now = fmt.Sprintf("%d/%d", info.ModTime().UnixNano(), info.Size())
|
||||
}
|
||||
if now != last {
|
||||
last = now
|
||||
report()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func refusals(n int) string {
|
||||
if n == 0 {
|
||||
return ""
|
||||
}
|
||||
return fmt.Sprintf(" (after %d refusal(s))", n)
|
||||
}
|
||||
@@ -1,529 +0,0 @@
|
||||
package main
|
||||
|
||||
// What claude-code does on a node, written against what it is handed — a way to ask a tool on the bus, its
|
||||
// own state, a way to write a managed file — so every path is tested without a bus (novox/hq design 36,
|
||||
// ADR 0183, ADR 0201, ADR 0206).
|
||||
//
|
||||
// Over NATS, and nothing an event: what is current is state, and a secret only ever travels on a request,
|
||||
// sealed to its one recipient.
|
||||
// - What this node holds is the module's `holdings` state, one key per node: the account, the kind,
|
||||
// fingerprints and expiries — never a token. Written at start and on every change of the credentials
|
||||
// file, so the licence manager learns a login, or a node already logged in, from the state alone.
|
||||
// - The grant itself leaves only when the manager asks `claude_code_grant`, sealed to the key it gives.
|
||||
// - What this node should hold is the manager's `bindings` state; a newer generation for this node is
|
||||
// fetched with the seat's `current` verb, sealed to this module's key, and written access-token-only.
|
||||
// - An MCP server registered through this module is a key in its `servers` state — `all.<server>` for
|
||||
// every node, `<node>.<server>` for one — which every node watches.
|
||||
|
||||
import (
|
||||
"crypto/sha256"
|
||||
"encoding/hex"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"sort"
|
||||
"strings"
|
||||
"sync"
|
||||
"time"
|
||||
)
|
||||
|
||||
// Seat is the licence manager's role, and Manager the module whose `bindings` state this one reads.
|
||||
const (
|
||||
Seat = "anthropic-licence-manager"
|
||||
Manager = "claude-licence-manager"
|
||||
)
|
||||
|
||||
// SeatVerb is a seat's verb as the runtime addresses it: a role, not a module.
|
||||
func SeatVerb(verb string) string { return "seat:" + Seat + "." + verb }
|
||||
|
||||
// Fingerprint names a token without being one: the first 16 hex of its SHA-256, as the manager computes it.
|
||||
func Fingerprint(s string) string {
|
||||
sum := sha256.Sum256([]byte(s))
|
||||
return "sha256:" + hex.EncodeToString(sum[:])[:16]
|
||||
}
|
||||
|
||||
// Paths are where this node's files are, from the module's words (ADR 0192).
|
||||
type Paths struct {
|
||||
State, Facts, Settings, Home, Node string
|
||||
}
|
||||
|
||||
// PathsFrom reads them, or answers false outside a launch.
|
||||
func PathsFrom(env func(string) string) (Paths, bool) {
|
||||
p := Paths{State: env("MESH_CLAUDE_CODE_STATE"), Facts: env("MESH_CLAUDE_CODE_FACTS"),
|
||||
Settings: env("MESH_CLAUDE_CODE_SETTINGS"), Home: env("MESH_OPERATOR_HOME"), Node: env("MESH_NODE")}
|
||||
return p, p.State != "" && p.Facts != "" && p.Settings != "" && p.Home != "" && p.Node != ""
|
||||
}
|
||||
|
||||
func (p Paths) credentials() string { return filepath.Join(p.Home, ".claude", ".credentials.json") }
|
||||
func (p Paths) account() string { return filepath.Join(p.Home, ".claude.json") }
|
||||
func (p Paths) binding() string { return filepath.Join(p.State, "licence.json") }
|
||||
func (p Paths) apiKey() string { return filepath.Join(p.State, "api-key") }
|
||||
func (p Paths) helper() string { return filepath.Join(p.State, "api-key-helper") }
|
||||
func (p Paths) registry() string { return filepath.Join(p.State, "mcp-servers.json") }
|
||||
|
||||
// Ask is a tool on the bus: its address and arguments in, its JSON answer out.
|
||||
type Ask func(address string, args any) (json.RawMessage, error)
|
||||
|
||||
// WriteManaged writes one managed file and answers what happened.
|
||||
type WriteManaged func(name, content string) (string, error)
|
||||
|
||||
func readJSON(path string, into any) bool {
|
||||
raw, err := os.ReadFile(path)
|
||||
return err == nil && json.Unmarshal(raw, into) == nil
|
||||
}
|
||||
|
||||
// Keypair is this module's own, made once in its state; the TypeScript module's files are kept, so a node
|
||||
// moving to this binary keeps the key it had.
|
||||
func Keypair(p Paths) (KeyPair, error) {
|
||||
priv, pub := filepath.Join(p.State, "key.pem"), filepath.Join(p.State, "key.pub.pem")
|
||||
if _, err := os.Stat(priv); errors.Is(err, os.ErrNotExist) {
|
||||
k, err := GenerateKeyPair()
|
||||
if err != nil {
|
||||
return KeyPair{}, err
|
||||
}
|
||||
if err := os.WriteFile(priv, []byte(k.PrivateKey), 0o600); err != nil {
|
||||
return KeyPair{}, err
|
||||
}
|
||||
if err := os.WriteFile(pub, []byte(k.PublicKey), 0o644); err != nil {
|
||||
return KeyPair{}, err
|
||||
}
|
||||
}
|
||||
a, err1 := os.ReadFile(priv)
|
||||
b, err2 := os.ReadFile(pub)
|
||||
return KeyPair{PrivateKey: string(a), PublicKey: string(b)}, errors.Join(err1, err2)
|
||||
}
|
||||
|
||||
// Registered is what applies here of the servers registered through this module.
|
||||
func Registered(p Paths) Servers {
|
||||
s := Servers{}
|
||||
readJSON(p.registry(), &s)
|
||||
return s
|
||||
}
|
||||
|
||||
// RenderNow writes the managed directory from the facts, the settings, the licence held and the servers
|
||||
// registered here.
|
||||
func RenderNow(p Paths, write WriteManaged) ([]string, error) {
|
||||
var facts Facts
|
||||
if !readJSON(p.Facts, &facts) || facts.Console == "" {
|
||||
return nil, fmt.Errorf("the mesh has not rendered %s yet; nothing to write", p.Facts)
|
||||
}
|
||||
var settings Settings
|
||||
readJSON(p.Settings, &settings)
|
||||
var binding *Binding
|
||||
var b Binding
|
||||
if readJSON(p.binding(), &b) {
|
||||
binding = &b
|
||||
}
|
||||
files := Render(facts, settings, binding, p.helper(), Registered(p))
|
||||
names := make([]string, 0, len(files))
|
||||
for n := range files {
|
||||
names = append(names, n)
|
||||
}
|
||||
sort.Strings(names)
|
||||
var out []string
|
||||
for _, n := range names {
|
||||
line, err := write(n, files[n])
|
||||
if err != nil {
|
||||
return out, err
|
||||
}
|
||||
out = append(out, line)
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// ---- the licence ----------------------------------------------------------------------------------
|
||||
|
||||
// BindingState is what the manager's `bindings` state says one consumer should hold (ADR 0206).
|
||||
type BindingState struct {
|
||||
Licence string `json:"licence"`
|
||||
Kind string `json:"kind"`
|
||||
Generation int64 `json:"generation"`
|
||||
}
|
||||
|
||||
// Current is what the seat answers to `current`: the licence this node is bound to and its token, sealed.
|
||||
type Current struct {
|
||||
Licence string `json:"licence"`
|
||||
Kind string `json:"kind"`
|
||||
Generation int64 `json:"generation"`
|
||||
Sealed *SealedBox `json:"sealed"`
|
||||
Identity *Identity `json:"identity"`
|
||||
}
|
||||
|
||||
// Holdings is what this node holds, as the `holdings` state carries it (ADR 0206): enough for the manager
|
||||
// to tell a login it has not adopted from one it has, and never a token — fingerprints and expiries only.
|
||||
type Holdings struct {
|
||||
Node string `json:"node"`
|
||||
Identity *Identity `json:"identity"`
|
||||
Kind *string `json:"kind"`
|
||||
Refresh struct {
|
||||
Present bool `json:"present"`
|
||||
Fingerprint *string `json:"fingerprint"`
|
||||
ExpiresAt *int64 `json:"expiresAt"`
|
||||
} `json:"refresh"`
|
||||
Access *struct {
|
||||
Fingerprint string `json:"fingerprint"`
|
||||
ExpiresAt int64 `json:"expiresAt"`
|
||||
} `json:"access"`
|
||||
Licence *string `json:"licence"`
|
||||
Generation int64 `json:"generation"`
|
||||
ChangedAt *string `json:"changedAt"`
|
||||
}
|
||||
|
||||
// HoldingsOf is what this node holds now.
|
||||
func HoldingsOf(p Paths) Holdings {
|
||||
h := Holdings{Node: p.Node, Identity: ReadIdentity(p.account())}
|
||||
creds := ReadCredentials(p.credentials())
|
||||
if info, err := os.Stat(p.credentials()); err == nil {
|
||||
at := info.ModTime().UTC().Format("2006-01-02T15:04:05.000Z")
|
||||
h.ChangedAt = &at
|
||||
}
|
||||
if rt := RefreshTokenOf(creds); rt != "" {
|
||||
fp := Fingerprint(rt)
|
||||
h.Refresh.Present, h.Refresh.Fingerprint = true, &fp
|
||||
}
|
||||
if v, ok := number(creds.oauth()["refreshTokenExpiresAt"]); ok {
|
||||
h.Refresh.ExpiresAt = &v
|
||||
}
|
||||
if g := GrantOf(creds); g != nil {
|
||||
h.Access = &struct {
|
||||
Fingerprint string `json:"fingerprint"`
|
||||
ExpiresAt int64 `json:"expiresAt"`
|
||||
}{Fingerprint(g.AccessToken), g.ExpiresAt}
|
||||
}
|
||||
kind := ""
|
||||
if _, err := os.Stat(p.apiKey()); err == nil {
|
||||
kind = "api-key"
|
||||
} else if h.Access != nil {
|
||||
kind = "subscription"
|
||||
}
|
||||
if kind != "" {
|
||||
h.Kind = &kind
|
||||
}
|
||||
var applied Binding
|
||||
if readJSON(p.binding(), &applied) && applied.Licence != "" {
|
||||
h.Licence, h.Generation = &applied.Licence, applied.Generation
|
||||
}
|
||||
return h
|
||||
}
|
||||
|
||||
// GrantAnswer is what `claude_code_grant` answers: a login sealed to the key given, or nothing waiting.
|
||||
type GrantAnswer struct {
|
||||
Sealed *SealedBox `json:"sealed,omitempty"`
|
||||
Identity *Identity `json:"identity,omitempty"`
|
||||
Fingerprint string `json:"fingerprint,omitempty"`
|
||||
Waiting *bool `json:"waiting,omitempty"`
|
||||
}
|
||||
|
||||
// GrantFor is the full grant in the credentials file sealed to the manager's key — the one time a refresh
|
||||
// token leaves this node, for the manager to adopt by refreshing it (ADR 0206). Nothing waiting when the
|
||||
// file holds no refresh token.
|
||||
func GrantFor(p Paths, managerPublicKey string) (GrantAnswer, error) {
|
||||
creds := ReadCredentials(p.credentials())
|
||||
rt := RefreshTokenOf(creds)
|
||||
if rt == "" {
|
||||
no := false
|
||||
return GrantAnswer{Waiting: &no}, nil
|
||||
}
|
||||
raw, err := json.Marshal(creds.oauth())
|
||||
if err != nil {
|
||||
return GrantAnswer{}, err
|
||||
}
|
||||
box, err := Seal(string(raw), managerPublicKey)
|
||||
if err != nil {
|
||||
return GrantAnswer{}, err
|
||||
}
|
||||
return GrantAnswer{Sealed: &box, Identity: ReadIdentity(p.account()), Fingerprint: Fingerprint(rt)}, nil
|
||||
}
|
||||
|
||||
// Pull asks the seat for this node's current token and applies it.
|
||||
func Pull(p Paths, ask Ask, write WriteManaged) (map[string]any, error) {
|
||||
keys, err := Keypair(p)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
raw, err := ask(SeatVerb("current"), map[string]any{"consumer": p.Node, "public_key": keys.PublicKey})
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
var c Current
|
||||
if err := json.Unmarshal(raw, &c); err != nil || c.Sealed == nil {
|
||||
return map[string]any{"applied": false, "reason": "the seat holds no licence for this node"}, nil
|
||||
}
|
||||
return Apply(p, c, write)
|
||||
}
|
||||
|
||||
// OnBinding takes a change to this node's key in the manager's `bindings` state (ADR 0206): the token is
|
||||
// fetched when the generation is newer than the one applied. A released binding keeps the last token,
|
||||
// which lives hours, and says so.
|
||||
func OnBinding(p Paths, b *BindingState, ask Ask, write WriteManaged) (string, error) {
|
||||
if b == nil {
|
||||
return "this node's binding was released; it keeps its last token until it expires", nil
|
||||
}
|
||||
var applied Binding
|
||||
if readJSON(p.binding(), &applied) && applied.Generation >= b.Generation {
|
||||
return "", nil
|
||||
}
|
||||
out, err := Pull(p, ask, write)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
raw, _ := json.Marshal(out)
|
||||
return string(raw), nil
|
||||
}
|
||||
|
||||
// Apply applies what the seat handed over. A switch replaces the grant whole and cleans up after the old
|
||||
// licence; whatever it is, the file is written without a refresh token, so the agent here never refreshes.
|
||||
func Apply(p Paths, c Current, write WriteManaged) (map[string]any, error) {
|
||||
keys, err := Keypair(p)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
plain, err := Open(*c.Sealed, keys.PrivateKey)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
var previous Binding
|
||||
had := readJSON(p.binding(), &previous)
|
||||
switched := !had || previous.Licence != c.Licence
|
||||
out := map[string]any{"applied": true, "licence": c.Licence, "kind": c.Kind, "switched": switched}
|
||||
if c.Kind == "api-key" {
|
||||
if err := os.WriteFile(p.apiKey(), []byte(strings.TrimSpace(plain)+"\n"), 0o600); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if err := os.WriteFile(p.helper(), []byte("#!/bin/sh\nexec cat '"+p.apiKey()+"'\n"), 0o700); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
_ = os.Chmod(p.helper(), 0o700)
|
||||
} else {
|
||||
var g Grant
|
||||
if err := json.Unmarshal([]byte(plain), &g); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
local := ReadCredentials(p.credentials())
|
||||
// A login waiting here was handed to the manager first (ADR 0206): what comes back is its successor,
|
||||
// and the refresh token in the file is the one the manager just spent.
|
||||
d := DecideApply(GrantOf(local), g, switched || HoldsLogin(local))
|
||||
if d.Apply {
|
||||
next := WithGrant(local, g)
|
||||
if switched {
|
||||
next = ReplacedBy(local, g)
|
||||
}
|
||||
if err := WriteCredentials(p.credentials(), next); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
} else {
|
||||
out = map[string]any{"applied": false, "licence": c.Licence, "reason": d.Reason}
|
||||
}
|
||||
// Away from the API key: it goes, with its helper.
|
||||
_ = os.Remove(p.apiKey())
|
||||
_ = os.Remove(p.helper())
|
||||
}
|
||||
if switched && c.Identity != nil && c.Identity.AccountUUID != "" {
|
||||
changed, err := WriteIdentity(p.account(), *c.Identity)
|
||||
if err == nil {
|
||||
out["account"] = map[bool]string{true: "updated", false: "unchanged"}[changed]
|
||||
}
|
||||
}
|
||||
gen := c.Generation
|
||||
if gen == 0 {
|
||||
gen = previous.Generation
|
||||
}
|
||||
raw, _ := json.Marshal(Binding{Licence: c.Licence, Kind: c.Kind, Generation: gen})
|
||||
if err := os.WriteFile(p.binding(), append(raw, '\n'), 0o600); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
// The key-helper comes or goes with the licence's kind.
|
||||
if rendered, err := RenderNow(p, write); err != nil {
|
||||
out["rendered"] = map[string]any{"failed": err.Error()}
|
||||
} else {
|
||||
out["rendered"] = rendered
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// ---- MCP servers ----------------------------------------------------------------------------------
|
||||
|
||||
// Registration is a server registered (or, with no entry, unregistered) through this module.
|
||||
type Registration struct {
|
||||
Name string
|
||||
Entry map[string]any
|
||||
// Nodes: nil for this node, ["all"] for every node running the module, or a list.
|
||||
Nodes []string
|
||||
}
|
||||
|
||||
// ServerState is the `servers` state as this module reaches it through the runtime.
|
||||
type ServerState interface {
|
||||
Put(key string, value any) error
|
||||
Delete(key string) error
|
||||
Keys() ([]string, error)
|
||||
}
|
||||
|
||||
// ServerChange is one change to the `servers` state, as a watch hands it over.
|
||||
type ServerChange struct {
|
||||
Key string
|
||||
Op string // put | delete
|
||||
Value map[string]any
|
||||
}
|
||||
|
||||
// KeyOf is the key a registration lives at: `all.<server>` for every node, `<node>.<server>` for one.
|
||||
func KeyOf(scope, name string) string { return scope + "." + name }
|
||||
|
||||
// ServerView is what this node takes from the `servers` state: the entries for every node and for this
|
||||
// one, kept in memory from the watch and written through to the module's own file whenever what applies
|
||||
// here changes, so the managed directory renders without the bus.
|
||||
type ServerView struct {
|
||||
p Paths
|
||||
mu sync.Mutex
|
||||
entries map[string]map[string]any
|
||||
}
|
||||
|
||||
// NewServerView is an empty view for this node.
|
||||
func NewServerView(p Paths) *ServerView {
|
||||
return &ServerView{p: p, entries: map[string]map[string]any{}}
|
||||
}
|
||||
|
||||
// Take takes one change, and answers whether what applies to this node changed.
|
||||
func (v *ServerView) Take(c ServerChange) bool {
|
||||
scope, name, ok := strings.Cut(c.Key, ".")
|
||||
if !ok || scope == "" || (scope != "all" && scope != v.p.Node) {
|
||||
return false
|
||||
}
|
||||
v.mu.Lock()
|
||||
if c.Op == "put" && c.Value != nil && EntryProblem(name, c.Value) == "" {
|
||||
v.entries[c.Key] = c.Value
|
||||
} else {
|
||||
delete(v.entries, c.Key)
|
||||
}
|
||||
v.mu.Unlock()
|
||||
return v.writeThrough()
|
||||
}
|
||||
|
||||
// Effective is what applies here: every node's entries, with this node's own laid over them by name.
|
||||
func (v *ServerView) Effective() Servers {
|
||||
v.mu.Lock()
|
||||
defer v.mu.Unlock()
|
||||
out := Servers{}
|
||||
for _, scope := range []string{"all", v.p.Node} {
|
||||
for key, entry := range v.entries {
|
||||
if name, ok := strings.CutPrefix(key, scope+"."); ok {
|
||||
out[name] = entry
|
||||
}
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func (v *ServerView) writeThrough() bool {
|
||||
now, _ := indented(v.Effective())
|
||||
before, _ := os.ReadFile(v.p.registry())
|
||||
if string(before) == string(now) {
|
||||
return false
|
||||
}
|
||||
_ = os.WriteFile(v.p.registry(), now, 0o600)
|
||||
return true
|
||||
}
|
||||
|
||||
// OnServerChange takes a change from the watch, and renders when what applies here changed.
|
||||
func OnServerChange(v *ServerView, c ServerChange, p Paths, write WriteManaged) (string, error) {
|
||||
if !v.Take(c) {
|
||||
return "", nil
|
||||
}
|
||||
if _, err := RenderNow(p, write); err != nil {
|
||||
return "", err
|
||||
}
|
||||
what := "registered"
|
||||
if c.Op != "put" {
|
||||
what = "unregistered"
|
||||
}
|
||||
return what + " " + c.Key, nil
|
||||
}
|
||||
|
||||
// RegisterServer registers (or, with no entry, unregisters) a server: a put (or delete) per scope in the
|
||||
// `servers` state, taken into this node's view at once so the answer says what it did here; every other
|
||||
// node takes it from its watch, and a node that joins later from the current state.
|
||||
func RegisterServer(p Paths, r Registration, servers ServerState, v *ServerView, write WriteManaged,
|
||||
others func() ([]string, error)) (map[string]any, error) {
|
||||
if r.Entry != nil {
|
||||
if problem := EntryProblem(r.Name, r.Entry); problem != "" {
|
||||
return map[string]any{"registered": false, "reason": problem}, nil
|
||||
}
|
||||
}
|
||||
scopes := r.Nodes
|
||||
if len(scopes) == 0 {
|
||||
scopes = []string{p.Node}
|
||||
}
|
||||
// Compared before and after rather than read from Take: this node's own watch may hand the view the
|
||||
// same change first, and then Take here finds nothing new although this call made it.
|
||||
before, _ := json.Marshal(v.Effective())
|
||||
for _, scope := range scopes {
|
||||
key := KeyOf(scope, r.Name)
|
||||
var err error
|
||||
if r.Entry != nil {
|
||||
err = servers.Put(key, r.Entry)
|
||||
} else {
|
||||
err = servers.Delete(key)
|
||||
}
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
op := "put"
|
||||
if r.Entry == nil {
|
||||
op = "delete"
|
||||
}
|
||||
v.Take(ServerChange{Key: key, Op: op, Value: r.Entry})
|
||||
}
|
||||
after, _ := json.Marshal(v.Effective())
|
||||
changed := string(before) != string(after)
|
||||
here := false
|
||||
for _, s := range scopes {
|
||||
here = here || s == "all" || s == p.Node
|
||||
}
|
||||
verb := "registered"
|
||||
if r.Entry == nil {
|
||||
verb = "unregistered"
|
||||
}
|
||||
answer := map[string]any{verb: r.Name, "on": scopes}
|
||||
switch {
|
||||
case !here:
|
||||
answer["here"] = "not this node"
|
||||
case changed:
|
||||
answer["here"] = "changed"
|
||||
default:
|
||||
answer["here"] = "already so"
|
||||
}
|
||||
if changed {
|
||||
rendered, err := RenderNow(p, write)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
answer["rendered"] = rendered
|
||||
}
|
||||
if r.Entry == nil {
|
||||
if _, still := v.Effective()[r.Name]; still {
|
||||
answer["still"] = r.Name + " still applies here from another registration (for every node, or for this one); unregister that too"
|
||||
}
|
||||
}
|
||||
if len(r.Nodes) == 0 {
|
||||
// The question the operator wanted asked: here only, or more?
|
||||
var elsewhere []string
|
||||
if nodes, err := others(); err == nil {
|
||||
for _, n := range nodes {
|
||||
if n != p.Node {
|
||||
elsewhere = append(elsewhere, n)
|
||||
}
|
||||
}
|
||||
}
|
||||
if len(elsewhere) > 0 {
|
||||
answer["also"] = fmt.Sprintf("claude-code also runs on %s. To %s it there too, call again with nodes: \"all\" or a list of those nodes.",
|
||||
strings.Join(elsewhere, ", "), map[bool]string{true: "register", false: "unregister"}[r.Entry != nil])
|
||||
} else {
|
||||
answer["also"] = "To do the same on every node running claude-code, call again with nodes: \"all\"."
|
||||
}
|
||||
}
|
||||
return answer, nil
|
||||
}
|
||||
|
||||
// stamp is a time as the status answers it.
|
||||
func stamp(ms int64) string { return time.UnixMilli(ms).UTC().Format(time.RFC3339) }
|
||||
@@ -1,121 +0,0 @@
|
||||
package main
|
||||
|
||||
// What the module writes into the agent's machine-wide managed directory (novox/hq design 36 §1–§4).
|
||||
// Pure: composed from the facts the mesh rendered, the settings the operator set and the licence the node
|
||||
// holds, so what lands under /etc is tested without a machine.
|
||||
//
|
||||
// Three files, owned whole by this module:
|
||||
//
|
||||
// managed-mcp.json the tool servers every session loads: the mesh's console as `mesh`, and the
|
||||
// servers the operator declared or registered through this module. Exclusive by
|
||||
// the vendor's rule — a server not listed here does not load (operator's choice,
|
||||
// 2026-10-03).
|
||||
// managed-settings.json the mesh's keys only: the repositories' attribution convention, the claude.ai
|
||||
// connectors kept beside the managed servers, and — for an API-key licence only —
|
||||
// the key-helper. A person's preferences are theirs.
|
||||
// CLAUDE.md how a session on this mesh works, who this node is, the conventions.
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"regexp"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// ManagedDir is the agent's machine-wide managed directory.
|
||||
const ManagedDir = "/etc/claude-code"
|
||||
|
||||
const meshEntry = "mesh"
|
||||
|
||||
// Facts are what the mesh rendered for this node.
|
||||
type Facts struct {
|
||||
Node string `json:"node"`
|
||||
Console string `json:"console"`
|
||||
}
|
||||
|
||||
// Settings are the operator's, for the mesh or this node.
|
||||
type Settings struct {
|
||||
Role string `json:"role"`
|
||||
MCPServers map[string]map[string]any `json:"mcp_servers"`
|
||||
}
|
||||
|
||||
// Binding is the licence this node holds, as it was last applied.
|
||||
type Binding struct {
|
||||
Licence string `json:"licence"`
|
||||
Kind string `json:"kind"` // subscription | api-key
|
||||
Generation int64 `json:"generation,omitempty"`
|
||||
}
|
||||
|
||||
// Servers are tool server entries by name, in the vendor's `.mcp.json` shape.
|
||||
type Servers map[string]map[string]any
|
||||
|
||||
var serverName = regexp.MustCompile(`^[A-Za-z0-9_-]+$`)
|
||||
|
||||
// EntryProblem says why the vendor's managed file would not take an entry, or "" when it would: a name of
|
||||
// letters, digits, `-` and `_`, and an http/sse server with a url or a stdio server with a command.
|
||||
func EntryProblem(name string, entry map[string]any) string {
|
||||
if !serverName.MatchString(name) {
|
||||
return fmt.Sprintf("%q is not a name the agent takes: letters, digits, - and _", name)
|
||||
}
|
||||
if name == meshEntry {
|
||||
return fmt.Sprintf("%q is the mesh's own entry", meshEntry)
|
||||
}
|
||||
kind, _ := entry["type"].(string)
|
||||
if kind == "" {
|
||||
kind = "stdio"
|
||||
}
|
||||
switch kind {
|
||||
case "http", "sse", "streamable-http":
|
||||
if u, _ := entry["url"].(string); u != "" {
|
||||
return ""
|
||||
}
|
||||
return fmt.Sprintf("an %s server needs a url", kind)
|
||||
case "stdio":
|
||||
if c, _ := entry["command"].(string); c != "" {
|
||||
return ""
|
||||
}
|
||||
return "a stdio server needs a command"
|
||||
}
|
||||
return fmt.Sprintf("%q is not a server type the agent knows (http, sse, stdio)", kind)
|
||||
}
|
||||
|
||||
// jsonFile is a value as the managed files are written: two-space indent, a trailing newline, nothing
|
||||
// escaped that need not be.
|
||||
func jsonFile(v any) string {
|
||||
var b bytes.Buffer
|
||||
enc := json.NewEncoder(&b)
|
||||
enc.SetEscapeHTML(false)
|
||||
enc.SetIndent("", " ")
|
||||
_ = enc.Encode(v)
|
||||
return b.String()
|
||||
}
|
||||
|
||||
// Render composes the three files. registered — what was registered through this module and applies
|
||||
// here — is laid over the servers the operator set in its settings.
|
||||
func Render(facts Facts, settings Settings, binding *Binding, helperPath string, registered Servers) map[string]string {
|
||||
servers := map[string]any{}
|
||||
for _, layer := range []map[string]map[string]any{settings.MCPServers, registered} {
|
||||
for name, entry := range layer {
|
||||
if EntryProblem(name, entry) != "" {
|
||||
continue // the mesh's own entry, or one the agent would refuse
|
||||
}
|
||||
servers[name] = entry
|
||||
}
|
||||
}
|
||||
servers[meshEntry] = map[string]any{"type": "http", "url": facts.Console}
|
||||
|
||||
managed := map[string]any{"attribution": map[string]any{"commit": "", "pr": ""}, "allowAllClaudeAiMcps": true}
|
||||
if binding != nil && binding.Kind == "api-key" {
|
||||
managed["apiKeyHelper"] = helperPath
|
||||
}
|
||||
role := strings.TrimSpace(settings.Role)
|
||||
if role == "" {
|
||||
role = "not stated — set it in this module's settings for the node"
|
||||
}
|
||||
return map[string]string{
|
||||
"managed-mcp.json": jsonFile(map[string]any{"mcpServers": servers}),
|
||||
"managed-settings.json": jsonFile(managed),
|
||||
"CLAUDE.md": instructionsText(facts.Node, role),
|
||||
}
|
||||
}
|
||||
@@ -1,189 +0,0 @@
|
||||
package main
|
||||
|
||||
// Sealing to one recipient (novox/hq ADR 0183, ADR 0206): the manager seals what it hands a consumer to
|
||||
// the key that consumer sent, and a node seals a waiting login to the key the manager gives. The same box
|
||||
// the agent module's TypeScript makes and opens, byte for byte — X25519 for the agreement, HKDF-SHA256 for
|
||||
// the key, AES-256-GCM for the box — so `testdata/sealed-by-typescript.json` is opened here, and a test
|
||||
// reopens what this seals with the same derivation.
|
||||
//
|
||||
// A box is `{ v: 1, eph, iv, tag, ct }`, every field base64; `eph` is the one-time public key as SPKI DER,
|
||||
// and the key is bound to it and to the recipient's raw public key, so a box cannot be re-addressed.
|
||||
|
||||
import (
|
||||
"crypto/aes"
|
||||
"crypto/cipher"
|
||||
"crypto/ecdh"
|
||||
"crypto/hkdf"
|
||||
"crypto/rand"
|
||||
"crypto/sha256"
|
||||
"crypto/x509"
|
||||
"encoding/base64"
|
||||
"encoding/pem"
|
||||
"errors"
|
||||
"fmt"
|
||||
)
|
||||
|
||||
// SealedBox is a value sealed to one recipient.
|
||||
type SealedBox struct {
|
||||
V int `json:"v"`
|
||||
Eph string `json:"eph"`
|
||||
IV string `json:"iv"`
|
||||
Tag string `json:"tag"`
|
||||
Ct string `json:"ct"`
|
||||
}
|
||||
|
||||
// KeyPair is a recipient's keypair as the two PEM strings it is kept and sent as.
|
||||
type KeyPair struct {
|
||||
PublicKey string `json:"publicKey"`
|
||||
PrivateKey string `json:"privateKey"`
|
||||
}
|
||||
|
||||
const sealInfo = "novox-mesh sealed box v1"
|
||||
|
||||
// GenerateKeyPair makes an X25519 keypair, PEM-encoded as the agent module's are.
|
||||
func GenerateKeyPair() (KeyPair, error) {
|
||||
priv, err := ecdh.X25519().GenerateKey(rand.Reader)
|
||||
if err != nil {
|
||||
return KeyPair{}, err
|
||||
}
|
||||
pubDER, err := x509.MarshalPKIXPublicKey(priv.PublicKey())
|
||||
if err != nil {
|
||||
return KeyPair{}, err
|
||||
}
|
||||
privDER, err := x509.MarshalPKCS8PrivateKey(priv)
|
||||
if err != nil {
|
||||
return KeyPair{}, err
|
||||
}
|
||||
return KeyPair{
|
||||
PublicKey: string(pem.EncodeToMemory(&pem.Block{Type: "PUBLIC KEY", Bytes: pubDER})),
|
||||
PrivateKey: string(pem.EncodeToMemory(&pem.Block{Type: "PRIVATE KEY", Bytes: privDER})),
|
||||
}, nil
|
||||
}
|
||||
|
||||
func publicFromPEM(p string) (*ecdh.PublicKey, error) {
|
||||
block, _ := pem.Decode([]byte(p))
|
||||
if block == nil {
|
||||
return nil, errors.New("not a PEM public key")
|
||||
}
|
||||
k, err := x509.ParsePKIXPublicKey(block.Bytes)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
pub, ok := k.(*ecdh.PublicKey)
|
||||
if !ok || pub.Curve() != ecdh.X25519() {
|
||||
return nil, errors.New("not an X25519 public key")
|
||||
}
|
||||
return pub, nil
|
||||
}
|
||||
|
||||
func privateFromPEM(p string) (*ecdh.PrivateKey, error) {
|
||||
block, _ := pem.Decode([]byte(p))
|
||||
if block == nil {
|
||||
return nil, errors.New("not a PEM private key")
|
||||
}
|
||||
k, err := x509.ParsePKCS8PrivateKey(block.Bytes)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
priv, ok := k.(*ecdh.PrivateKey)
|
||||
if !ok || priv.Curve() != ecdh.X25519() {
|
||||
return nil, errors.New("not an X25519 private key")
|
||||
}
|
||||
return priv, nil
|
||||
}
|
||||
|
||||
func boxKey(secret, ephDER, recipientRaw []byte) ([]byte, error) {
|
||||
salt := append(append([]byte{}, ephDER...), recipientRaw...)
|
||||
return hkdf.Key(sha256.New, secret, salt, sealInfo, 32)
|
||||
}
|
||||
|
||||
// Seal seals plaintext to the recipient's public key.
|
||||
func Seal(plaintext, recipientPEM string) (SealedBox, error) {
|
||||
recipient, err := publicFromPEM(recipientPEM)
|
||||
if err != nil {
|
||||
return SealedBox{}, err
|
||||
}
|
||||
eph, err := ecdh.X25519().GenerateKey(rand.Reader)
|
||||
if err != nil {
|
||||
return SealedBox{}, err
|
||||
}
|
||||
secret, err := eph.ECDH(recipient)
|
||||
if err != nil {
|
||||
return SealedBox{}, err
|
||||
}
|
||||
ephDER, err := x509.MarshalPKIXPublicKey(eph.PublicKey())
|
||||
if err != nil {
|
||||
return SealedBox{}, err
|
||||
}
|
||||
key, err := boxKey(secret, ephDER, recipient.Bytes())
|
||||
if err != nil {
|
||||
return SealedBox{}, err
|
||||
}
|
||||
gcm, err := newGCM(key)
|
||||
if err != nil {
|
||||
return SealedBox{}, err
|
||||
}
|
||||
iv := make([]byte, 12)
|
||||
if _, err := rand.Read(iv); err != nil {
|
||||
return SealedBox{}, err
|
||||
}
|
||||
out := gcm.Seal(nil, iv, []byte(plaintext), nil)
|
||||
ct, tag := out[:len(out)-gcm.Overhead()], out[len(out)-gcm.Overhead():]
|
||||
b64 := base64.StdEncoding.EncodeToString
|
||||
return SealedBox{V: 1, Eph: b64(ephDER), IV: b64(iv), Tag: b64(tag), Ct: b64(ct)}, nil
|
||||
}
|
||||
|
||||
// Open opens a box with the recipient's private key; it fails for a box to another key or one tampered with.
|
||||
func Open(box SealedBox, privatePEM string) (string, error) {
|
||||
if box.V != 1 {
|
||||
return "", errors.New("not a sealed box this module can open")
|
||||
}
|
||||
priv, err := privateFromPEM(privatePEM)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
d := base64.StdEncoding.DecodeString
|
||||
ephDER, err := d(box.Eph)
|
||||
if err != nil {
|
||||
return "", fmt.Errorf("the box's eph: %w", err)
|
||||
}
|
||||
ephKey, err := x509.ParsePKIXPublicKey(ephDER)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
eph, ok := ephKey.(*ecdh.PublicKey)
|
||||
if !ok {
|
||||
return "", errors.New("the box's eph is not an X25519 key")
|
||||
}
|
||||
secret, err := priv.ECDH(eph)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
key, err := boxKey(secret, ephDER, priv.PublicKey().Bytes())
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
iv, err1 := d(box.IV)
|
||||
tag, err2 := d(box.Tag)
|
||||
ct, err3 := d(box.Ct)
|
||||
if err := errors.Join(err1, err2, err3); err != nil {
|
||||
return "", err
|
||||
}
|
||||
gcm, err := newGCM(key)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
plain, err := gcm.Open(nil, iv, append(ct, tag...), nil)
|
||||
if err != nil {
|
||||
return "", errors.New("the box does not open with this key")
|
||||
}
|
||||
return string(plain), nil
|
||||
}
|
||||
|
||||
func newGCM(key []byte) (cipher.AEAD, error) {
|
||||
block, err := aes.NewCipher(key)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return cipher.NewGCM(block)
|
||||
}
|
||||
@@ -1,42 +0,0 @@
|
||||
{
|
||||
"facts": {
|
||||
"node": "workstation",
|
||||
"console": "http://127.0.0.1:4270/mcp"
|
||||
},
|
||||
"settings": {
|
||||
"role": "the laptop",
|
||||
"mcp_servers": {
|
||||
"search": {
|
||||
"type": "http",
|
||||
"url": "https://s.example/mcp"
|
||||
},
|
||||
"docs": {
|
||||
"type": "stdio",
|
||||
"command": "docs-mcp",
|
||||
"args": [
|
||||
"--x"
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"registered": {
|
||||
"anton": {
|
||||
"type": "stdio",
|
||||
"command": "node",
|
||||
"args": [
|
||||
"/a/b.js"
|
||||
],
|
||||
"env": {}
|
||||
}
|
||||
},
|
||||
"withKey": {
|
||||
"managed-mcp.json": "{\n \"mcpServers\": {\n \"anton\": {\n \"type\": \"stdio\",\n \"command\": \"node\",\n \"args\": [\n \"/a/b.js\"\n ],\n \"env\": {}\n },\n \"docs\": {\n \"type\": \"stdio\",\n \"command\": \"docs-mcp\",\n \"args\": [\n \"--x\"\n ]\n },\n \"mesh\": {\n \"type\": \"http\",\n \"url\": \"http://127.0.0.1:4270/mcp\"\n },\n \"search\": {\n \"type\": \"http\",\n \"url\": \"https://s.example/mcp\"\n }\n }\n}\n",
|
||||
"managed-settings.json": "{\n \"attribution\": {\n \"commit\": \"\",\n \"pr\": \"\"\n },\n \"allowAllClaudeAiMcps\": true,\n \"apiKeyHelper\": \"/state/api-key-helper\"\n}\n",
|
||||
"CLAUDE.md": "# This machine is a node of a Novox mesh\n\nWritten by the mesh's `claude-code` module. Edit the module's settings or the catalogue, never this file:\nit is rewritten whenever the module renders.\n\n## Who this node is\n\n- **Node:** `workstation`\n- **Role:** the laptop\n- The other nodes, their roles and what runs where: ask the controller (`mesh-controller.nodes`,\n `mesh-controller.node`). Nothing here lists them, because a copy drifts.\n\n## How a session on this mesh works\n\nThe console is the only way to the mesh: the MCP server named `mesh`. It offers five tools, and\neverything else is an address you find and call through them:\n\n- `mesh_search` — words in, matching addresses out. `mesh_describe` — one address's arguments.\n- `mesh_call` — call an address. A seat the mesh holds once is `<seat>.<verb>` (the mesh's own verbs\n are `mesh-controller.<verb>`: `status`, `plan`, `node`, `assign`, `push`, `settings`);\n a module on a machine is `<node>/<module>.<tool>`.\n- `mesh_overview` and `mesh_machine` — the mesh's seats and machines, and what one machine runs.\n\n- **Symptom first.** For an error, a failing service or anything unexpected, search the record with the\n literal text before forming a hypothesis: the records module's `records_search`, then\n `records_read`.\n- **Ask the mesh before changing it**, and change it through the controller's verbs or the catalogue.\n- **A licence** through the `anthropic-licence-manager` seat's verbs. Never edit the agent's credentials\n file by hand, never print or ask for a token.\n\n## Hard rules\n\n- A file the mesh manages is changed through the verb or the catalogue that owns it, never on disk. If\n unsure, `mesh-controller.plan` for the node says what the mesh writes there.\n- Never write to a store's database by hand; schema changes are numbered migrations.\n- Never push to a main branch: a branch, a pull request, and a human approval for every merge.\n- The mesh creates no symlinks, and nobody else does either.\n- A package is declared in a module, never installed by hand.\n\n## Conventions\n\n- Commit messages are concise, in the imperative, about why.\n- Test before pushing: nodes update unattended.\n- The playbooks in the record say how research, decisions, designs, issues and hand-offs are done.\n"
|
||||
},
|
||||
"plain": {
|
||||
"managed-mcp.json": "{\n \"mcpServers\": {\n \"mesh\": {\n \"type\": \"http\",\n \"url\": \"http://127.0.0.1:4270/mcp\"\n }\n }\n}\n",
|
||||
"managed-settings.json": "{\n \"attribution\": {\n \"commit\": \"\",\n \"pr\": \"\"\n },\n \"allowAllClaudeAiMcps\": true\n}\n",
|
||||
"CLAUDE.md": "# This machine is a node of a Novox mesh\n\nWritten by the mesh's `claude-code` module. Edit the module's settings or the catalogue, never this file:\nit is rewritten whenever the module renders.\n\n## Who this node is\n\n- **Node:** `workstation`\n- **Role:** not stated — set it in this module's settings for the node\n- The other nodes, their roles and what runs where: ask the controller (`mesh-controller.nodes`,\n `mesh-controller.node`). Nothing here lists them, because a copy drifts.\n\n## How a session on this mesh works\n\nThe console is the only way to the mesh: the MCP server named `mesh`. It offers five tools, and\neverything else is an address you find and call through them:\n\n- `mesh_search` — words in, matching addresses out. `mesh_describe` — one address's arguments.\n- `mesh_call` — call an address. A seat the mesh holds once is `<seat>.<verb>` (the mesh's own verbs\n are `mesh-controller.<verb>`: `status`, `plan`, `node`, `assign`, `push`, `settings`);\n a module on a machine is `<node>/<module>.<tool>`.\n- `mesh_overview` and `mesh_machine` — the mesh's seats and machines, and what one machine runs.\n\n- **Symptom first.** For an error, a failing service or anything unexpected, search the record with the\n literal text before forming a hypothesis: the records module's `records_search`, then\n `records_read`.\n- **Ask the mesh before changing it**, and change it through the controller's verbs or the catalogue.\n- **A licence** through the `anthropic-licence-manager` seat's verbs. Never edit the agent's credentials\n file by hand, never print or ask for a token.\n\n## Hard rules\n\n- A file the mesh manages is changed through the verb or the catalogue that owns it, never on disk. If\n unsure, `mesh-controller.plan` for the node says what the mesh writes there.\n- Never write to a store's database by hand; schema changes are numbered migrations.\n- Never push to a main branch: a branch, a pull request, and a human approval for every merge.\n- The mesh creates no symlinks, and nobody else does either.\n- A package is declared in a module, never installed by hand.\n\n## Conventions\n\n- Commit messages are concise, in the imperative, about why.\n- Test before pushing: nodes update unattended.\n- The playbooks in the record say how research, decisions, designs, issues and hand-offs are done.\n"
|
||||
}
|
||||
}
|
||||
@@ -1,5 +0,0 @@
|
||||
module claude-code
|
||||
|
||||
go 1.25.0
|
||||
|
||||
require git.novox.be/novox/mesh-sdk/go v0.1.7
|
||||
@@ -1,2 +0,0 @@
|
||||
git.novox.be/novox/mesh-sdk/go v0.1.7 h1:C0sTQmtTiyYH7bnqZb7PusXnqA37gKuT7Nqjn9gG47w=
|
||||
git.novox.be/novox/mesh-sdk/go v0.1.7/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=
|
||||
@@ -0,0 +1,112 @@
|
||||
// The agent's credentials file, and whether an offered grant may replace what it holds (novox/hq
|
||||
// ADR 0183, design 36 §5). Pure where it decides, so the rules are tested without a file.
|
||||
//
|
||||
// The file is the vendor's: `{ claudeAiOauth: { accessToken, expiresAt, refreshTokenExpiresAt?,
|
||||
// scopes?, subscriptionType?, rateLimitTier? }, ... }`. A node never holds a refresh token, so the
|
||||
// one this module writes never carries one, and a full grant a login left behind is stripped the
|
||||
// moment the manager hands the node its own.
|
||||
//
|
||||
// The lineage rule is the predecessor's, with the incidents that earned it: a rotation of the same
|
||||
// licence is applied only if newer; a grant re-issued by a login is adopted whatever its expiry; a
|
||||
// switch to another licence is applied regardless, because across licences the expiries are
|
||||
// unrelated numbers.
|
||||
|
||||
import { readFileSync, renameSync, writeFileSync, mkdirSync } from "node:fs";
|
||||
import { dirname } from "node:path";
|
||||
|
||||
export interface Grant {
|
||||
readonly accessToken: string;
|
||||
readonly expiresAt: number;
|
||||
readonly refreshTokenExpiresAt?: number | null;
|
||||
readonly scopes?: readonly string[] | null;
|
||||
readonly subscriptionType?: string | null;
|
||||
readonly rateLimitTier?: string | null;
|
||||
}
|
||||
|
||||
export type ApplySource = "rotation" | "switch";
|
||||
|
||||
export type ApplyDecision =
|
||||
| { apply: true; reissued?: boolean }
|
||||
| { apply: false; reason: "already-current" }
|
||||
| { apply: false; reason: "not-newer"; localExpiresAt: number };
|
||||
|
||||
/** Two refresh-token expiries within a day are one lineage; a login starts a fresh window weeks away. */
|
||||
export const GENERATION_TOLERANCE_MS = 24 * 60 * 60 * 1000;
|
||||
|
||||
export function sameGeneration(a?: number | null, b?: number | null): boolean {
|
||||
if (a == null || b == null) return true;
|
||||
return Math.abs(Number(a) - Number(b)) <= GENERATION_TOLERANCE_MS;
|
||||
}
|
||||
|
||||
export function decideApply(local: Grant | null | undefined, offered: Grant, source: ApplySource): ApplyDecision {
|
||||
if (!local?.accessToken) return { apply: true };
|
||||
if (local.accessToken === offered.accessToken) return { apply: false, reason: "already-current" };
|
||||
const reissued = !sameGeneration(local.refreshTokenExpiresAt, offered.refreshTokenExpiresAt);
|
||||
if (source === "rotation" && !reissued && Number(local.expiresAt) >= Number(offered.expiresAt)) {
|
||||
return { apply: false, reason: "not-newer", localExpiresAt: Number(local.expiresAt) };
|
||||
}
|
||||
return reissued ? { apply: true, reissued: true } : { apply: true };
|
||||
}
|
||||
|
||||
type Oauth = Record<string, unknown> & { accessToken?: string; refreshToken?: string; expiresAt?: number };
|
||||
type Credentials = Record<string, unknown> & { claudeAiOauth?: Oauth };
|
||||
|
||||
export function readCredentials(path: string): Credentials | null {
|
||||
try {
|
||||
const parsed = JSON.parse(readFileSync(path, "utf8")) as Credentials;
|
||||
return parsed && typeof parsed === "object" ? parsed : null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/** The grant the file holds, or null. */
|
||||
export function grantOf(creds: Credentials | null): Grant | null {
|
||||
const o = creds?.claudeAiOauth;
|
||||
if (!o?.accessToken) return null;
|
||||
return {
|
||||
accessToken: o.accessToken,
|
||||
expiresAt: Number(o.expiresAt ?? 0),
|
||||
refreshTokenExpiresAt: o.refreshTokenExpiresAt == null ? null : Number(o.refreshTokenExpiresAt),
|
||||
};
|
||||
}
|
||||
|
||||
/** Does the file hold a full grant — a refresh token this module never writes, so a person's login? */
|
||||
export function holdsLogin(creds: Credentials | null): boolean {
|
||||
return typeof creds?.claudeAiOauth?.refreshToken === "string" && creds.claudeAiOauth.refreshToken.length > 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* The handed grant laid over what is there — a rotation of the licence the node already holds — or,
|
||||
* for a switch, in place of it: the old licence's grant goes whole, scopes and subscription included,
|
||||
* and only keys outside the grant (another kind of credential the vendor keeps in the file) stay.
|
||||
* Either way, no refresh token survives.
|
||||
*/
|
||||
export function replacedBy(local: Credentials | null, grant: Grant): Credentials {
|
||||
const next: Credentials = { ...(local ?? {}) };
|
||||
delete next.claudeAiOauth;
|
||||
return withGrant(next, grant);
|
||||
}
|
||||
|
||||
/** Overlay the handed grant on what is there, and delete any refresh token. */
|
||||
export function withGrant(local: Credentials | null, grant: Grant): Credentials {
|
||||
const next: Credentials = { ...(local ?? {}) };
|
||||
const oauth: Oauth = { ...(local?.claudeAiOauth ?? {}) };
|
||||
oauth.accessToken = grant.accessToken;
|
||||
oauth.expiresAt = grant.expiresAt;
|
||||
for (const k of ["refreshTokenExpiresAt", "scopes", "subscriptionType", "rateLimitTier"] as const) {
|
||||
const v = grant[k];
|
||||
if (v != null) oauth[k] = v as unknown;
|
||||
}
|
||||
delete oauth.refreshToken;
|
||||
next.claudeAiOauth = oauth;
|
||||
return next;
|
||||
}
|
||||
|
||||
/** Write atomically at 0600: a partial credentials file must never be read as a whole one. */
|
||||
export function writeCredentials(path: string, creds: Credentials): void {
|
||||
mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
|
||||
const tmp = `${path}.mesh-tmp`;
|
||||
writeFileSync(tmp, JSON.stringify(creds, null, 2) + "\n", { mode: 0o600 });
|
||||
renameSync(tmp, path);
|
||||
}
|
||||
@@ -0,0 +1,50 @@
|
||||
// Which account the agent is logged in as (novox/hq ADR 0183): not in the token, but in the agent's
|
||||
// own state file beside the home, `~/.claude.json` → `oauthAccount`. Read to attribute a login; written,
|
||||
// three keys and nothing else, when a licence is switched, so the file Claude Code shows the account from
|
||||
// names the account whose token it now holds (as the predecessor learned: two files that disagree make
|
||||
// a later login look like the wrong account).
|
||||
|
||||
import { readFileSync, renameSync, writeFileSync } from "node:fs";
|
||||
|
||||
export interface Identity {
|
||||
readonly accountUuid: string;
|
||||
readonly emailAddress?: string;
|
||||
readonly organizationUuid?: string;
|
||||
}
|
||||
|
||||
export function readIdentity(stateFile: string): Identity | null {
|
||||
try {
|
||||
const raw = JSON.parse(readFileSync(stateFile, "utf8")) as { oauthAccount?: Record<string, unknown> };
|
||||
const a = raw.oauthAccount;
|
||||
if (!a || typeof a.accountUuid !== "string") return null;
|
||||
return {
|
||||
accountUuid: a.accountUuid,
|
||||
emailAddress: typeof a.emailAddress === "string" ? a.emailAddress : undefined,
|
||||
organizationUuid: typeof a.organizationUuid === "string" ? a.organizationUuid : undefined,
|
||||
};
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Point the state file's account at `id`, keeping every other key as found. Returns whether the file
|
||||
* changed; a file that cannot be read as an object is left alone rather than replaced.
|
||||
*/
|
||||
export function writeIdentity(stateFile: string, id: Identity): boolean {
|
||||
let raw: Record<string, unknown>;
|
||||
try {
|
||||
raw = JSON.parse(readFileSync(stateFile, "utf8")) as Record<string, unknown>;
|
||||
if (!raw || typeof raw !== "object") return false;
|
||||
} catch {
|
||||
raw = {};
|
||||
}
|
||||
const current = (raw.oauthAccount ?? {}) as Record<string, unknown>;
|
||||
if (current.accountUuid === id.accountUuid && current.emailAddress === id.emailAddress
|
||||
&& current.organizationUuid === id.organizationUuid) return false;
|
||||
raw.oauthAccount = { ...current, accountUuid: id.accountUuid, emailAddress: id.emailAddress, organizationUuid: id.organizationUuid };
|
||||
const tmp = `${stateFile}.mesh-tmp`;
|
||||
writeFileSync(tmp, JSON.stringify(raw, null, 2), { mode: 0o600 });
|
||||
renameSync(tmp, stateFile);
|
||||
return true;
|
||||
}
|
||||
@@ -11,18 +11,17 @@
|
||||
"binds": {
|
||||
"mcp-endpoint": "${dir:state}/mcp-endpoint.json"
|
||||
},
|
||||
"state": [
|
||||
"servers",
|
||||
"holdings"
|
||||
"consumes": [
|
||||
"claude-licence-manager.licence.rotated",
|
||||
"claude-licence-manager.licence.switched"
|
||||
],
|
||||
"reads": [
|
||||
"claude-licence-manager.bindings"
|
||||
"state": [
|
||||
"servers"
|
||||
],
|
||||
"tools": [
|
||||
"claude_code_status",
|
||||
"claude_code_render",
|
||||
"claude_code_pull",
|
||||
"claude_code_grant",
|
||||
"claude_code_mcp_list",
|
||||
"claude_code_mcp_register",
|
||||
"claude_code_mcp_unregister"
|
||||
@@ -76,12 +75,9 @@
|
||||
{
|
||||
"name": "tools",
|
||||
"kind": "bundle",
|
||||
"language": "go",
|
||||
"system": "arch",
|
||||
"from": "cmd/claude-code",
|
||||
"binary": "claude-code",
|
||||
"loads": [
|
||||
"claude-code"
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"tools/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_CLAUDE_CODE_STATE": "${dir:state}",
|
||||
|
||||
@@ -0,0 +1,271 @@
|
||||
// What claude-code does on a node, written against two things it is handed — a way to ask a tool on the
|
||||
// bus and a way to emit an event — so every path is tested without a bus (novox/hq design 36 §4–§5,
|
||||
// ADR 0183, ADR 0198).
|
||||
//
|
||||
// **Over NATS, in two kinds** (design 32 §10): an event says that something happened and carries no
|
||||
// secret, because a stream keeps it; a token travels on a request, which nothing keeps. So:
|
||||
// - the licence manager's `licence.rotated` and `licence.switched` events tell this module to ask the
|
||||
// seat for its current token, sealed to the key it sends with the request;
|
||||
// - a login a person made here — a refresh token this module never writes — is offered to the seat at
|
||||
// once, sealed to the seat's key: the one moment a refresh token travels, because the login made the
|
||||
// manager's stale;
|
||||
// - an MCP server registered through this module is **state, not an event** (novox/hq ADR 0201): one
|
||||
// key per server in the module's `servers` bucket — `all.<server>` for every node, `<node>.<server>`
|
||||
// for one — which every node watches. A node that joins later, or was off, reads the whole current set
|
||||
// at start; unregistering is a delete. A secret never goes in an entry: the runtime refuses one.
|
||||
|
||||
import { chmodSync, existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
|
||||
import { render, entryProblem, MANAGED_DIR, type Binding, type Facts, type Settings, type Servers } from "./render.js";
|
||||
import { generateKeyPair, open, seal, type SealedBox } from "./seal.js";
|
||||
import { decideApply, grantOf, holdsLogin, readCredentials, replacedBy, withGrant, writeCredentials, type Grant } from "./grant.js";
|
||||
import { readIdentity, writeIdentity, type Identity } from "./identity.js";
|
||||
|
||||
export const SEAT = "anthropic-licence-manager";
|
||||
|
||||
export interface Paths {
|
||||
state: string;
|
||||
facts: string;
|
||||
settings: string;
|
||||
home: string;
|
||||
node: string;
|
||||
}
|
||||
|
||||
/** A tool on the bus: its address and arguments in, its JSON answer out. */
|
||||
export type Ask = (address: string, args: Record<string, unknown>) => Promise<unknown>;
|
||||
/** An event of this module's, by its local name. */
|
||||
export type Emit = (type: string, body: unknown) => Promise<void>;
|
||||
/** Write one managed file; answers what happened. */
|
||||
export type WriteManaged = (name: string, content: string) => string;
|
||||
|
||||
export const readJson = <T>(p: string, fallback: T): T => {
|
||||
try {
|
||||
return JSON.parse(readFileSync(p, "utf8")) as T;
|
||||
} catch {
|
||||
return fallback;
|
||||
}
|
||||
};
|
||||
|
||||
const credentialsPath = (p: Paths) => join(p.home, ".claude", ".credentials.json");
|
||||
const accountPath = (p: Paths) => join(p.home, ".claude.json");
|
||||
const bindingPath = (p: Paths) => join(p.state, "licence.json");
|
||||
const apiKeyPath = (p: Paths) => join(p.state, "api-key");
|
||||
export const helperPath = (p: Paths) => join(p.state, "api-key-helper");
|
||||
const keyPath = (p: Paths) => join(p.state, "key.pem");
|
||||
const pubPath = (p: Paths) => join(p.state, "key.pub.pem");
|
||||
const registryPath = (p: Paths) => join(p.state, "mcp-servers.json");
|
||||
|
||||
export function keypair(p: Paths): { publicKey: string; privateKey: string } {
|
||||
if (!existsSync(keyPath(p))) {
|
||||
const k = generateKeyPair();
|
||||
writeFileSync(keyPath(p), k.privateKey, { mode: 0o600 });
|
||||
writeFileSync(pubPath(p), k.publicKey, { mode: 0o644 });
|
||||
}
|
||||
return { privateKey: readFileSync(keyPath(p), "utf8"), publicKey: readFileSync(pubPath(p), "utf8") };
|
||||
}
|
||||
|
||||
export function registered(p: Paths): Servers {
|
||||
return readJson<Servers>(registryPath(p), {});
|
||||
}
|
||||
|
||||
export function renderNow(p: Paths, write: WriteManaged): string[] {
|
||||
const facts = readJson<Facts | null>(p.facts, null);
|
||||
if (!facts?.console) throw new Error(`the mesh has not rendered ${p.facts} yet; nothing to write`);
|
||||
const files = render(facts, readJson<Settings>(p.settings, {}), readJson<Binding | null>(bindingPath(p), null),
|
||||
helperPath(p), registered(p));
|
||||
return Object.entries(files).map(([name, content]) => write(name, content));
|
||||
}
|
||||
|
||||
// ---- the licence ----------------------------------------------------------------------------------
|
||||
|
||||
/** What the seat answers to `current`: the licence this node is bound to and its token, sealed. */
|
||||
export interface Current {
|
||||
licence: string;
|
||||
kind: "subscription" | "api-key";
|
||||
sealed: SealedBox;
|
||||
identity?: Identity | null;
|
||||
}
|
||||
|
||||
/** Ask the seat for this node's current token and apply it. */
|
||||
export async function pull(p: Paths, ask: Ask, write: WriteManaged): Promise<Record<string, unknown>> {
|
||||
const answer = (await ask(`${SEAT}.current`, { node: p.node, public_key: keypair(p).publicKey })) as Current | null;
|
||||
if (!answer?.sealed) return { applied: false, reason: "the seat holds no licence for this node" };
|
||||
return apply(p, answer, write);
|
||||
}
|
||||
|
||||
/** Apply what the seat handed over. A switch replaces the grant whole and cleans up after the old licence. */
|
||||
export function apply(p: Paths, handed: Current, write: WriteManaged): Record<string, unknown> {
|
||||
const plain = open(handed.sealed, keypair(p).privateKey);
|
||||
const previous = readJson<Binding | null>(bindingPath(p), null);
|
||||
const switched = previous?.licence !== handed.licence;
|
||||
let outcome: Record<string, unknown> = { applied: true, licence: handed.licence, kind: handed.kind, switched };
|
||||
if (handed.kind === "api-key") {
|
||||
writeFileSync(apiKeyPath(p), plain.trim() + "\n", { mode: 0o600 });
|
||||
writeFileSync(helperPath(p), `#!/bin/sh\nexec cat '${apiKeyPath(p)}'\n`, { mode: 0o700 });
|
||||
chmodSync(helperPath(p), 0o700);
|
||||
} else {
|
||||
const grant = JSON.parse(plain) as Grant;
|
||||
const local = readCredentials(credentialsPath(p));
|
||||
const d = decideApply(grantOf(local), grant, switched ? "switch" : "rotation");
|
||||
if (d.apply) writeCredentials(credentialsPath(p), switched ? replacedBy(local, grant) : withGrant(local, grant));
|
||||
else outcome = { applied: false, licence: handed.licence, reason: "reason" in d ? d.reason : undefined }; // narrowed by hand: the build compiles without strict
|
||||
// Away from the API key: it goes, with its helper.
|
||||
rmSync(apiKeyPath(p), { force: true });
|
||||
rmSync(helperPath(p), { force: true });
|
||||
}
|
||||
if (switched && handed.identity?.accountUuid) {
|
||||
outcome.account = writeIdentity(accountPath(p), handed.identity) ? "updated" : "unchanged";
|
||||
}
|
||||
writeFileSync(bindingPath(p), JSON.stringify({ licence: handed.licence, kind: handed.kind }) + "\n", { mode: 0o600 });
|
||||
try {
|
||||
outcome.rendered = renderNow(p, write); // the key-helper comes or goes with the licence's kind
|
||||
} catch (err) {
|
||||
outcome.rendered = { failed: err instanceof Error ? err.message : String(err) };
|
||||
}
|
||||
return outcome;
|
||||
}
|
||||
|
||||
/** A licence event from the manager: is it for this node? */
|
||||
export function concerns(p: Paths, type: string, body: { licence?: string; node?: string }): boolean {
|
||||
if (type.endsWith("licence.switched")) return body.node === p.node;
|
||||
if (type.endsWith("licence.rotated")) return body.licence === readJson<Binding | null>(bindingPath(p), null)?.licence;
|
||||
return false;
|
||||
}
|
||||
|
||||
/** A refresh token in the credentials file is a login: this module never writes one. Offer it to the seat. */
|
||||
export async function offerLogin(p: Paths, ask: Ask): Promise<Record<string, unknown> | null> {
|
||||
const creds = readCredentials(credentialsPath(p));
|
||||
if (!holdsLogin(creds)) return null;
|
||||
const key = (await ask(`${SEAT}.public_key`, {})) as { public_key?: string } | null;
|
||||
if (!key?.public_key) throw new Error("the licence manager did not say what key to seal a login to");
|
||||
return (await ask(`${SEAT}.adopt`, {
|
||||
node: p.node,
|
||||
identity: readIdentity(accountPath(p)),
|
||||
sealed: seal(JSON.stringify(creds!.claudeAiOauth), key.public_key),
|
||||
})) as Record<string, unknown>;
|
||||
}
|
||||
|
||||
// ---- MCP servers ----------------------------------------------------------------------------------
|
||||
|
||||
export interface Registration {
|
||||
name: string;
|
||||
entry?: Record<string, unknown>;
|
||||
/** Which nodes: this one (absent), every node running the module ("all"), or a list. */
|
||||
nodes?: "all" | string[];
|
||||
}
|
||||
|
||||
/** The `servers` state, as this module reaches it through the runtime (`state("servers")` in the SDK). */
|
||||
export interface ServerState {
|
||||
put(key: string, value: Record<string, unknown>): Promise<number>;
|
||||
delete(key: string): Promise<void>;
|
||||
keys(): Promise<string[]>;
|
||||
}
|
||||
|
||||
/** One change to the `servers` state, as a watch hands it over. */
|
||||
export interface ServerChange {
|
||||
key: string;
|
||||
op: "put" | "delete";
|
||||
value?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/** The key a registration lives at: `all.<server>` for every node, `<node>.<server>` for one. */
|
||||
export const keyOf = (scope: string, name: string) => `${scope}.${name}`;
|
||||
|
||||
/**
|
||||
* What this node takes from the `servers` state: the entries for every node and for this one, by key —
|
||||
* kept in memory from the watch, and written through to the module's own file whenever what applies here
|
||||
* changes, so the managed directory can be rendered without the bus.
|
||||
*/
|
||||
export class ServerView {
|
||||
private readonly entries = new Map<string, Record<string, unknown>>();
|
||||
constructor(private readonly p: Paths) {}
|
||||
|
||||
/** Take one change; answers whether what applies to this node changed. */
|
||||
take(c: ServerChange): boolean {
|
||||
const dot = c.key.indexOf(".");
|
||||
const scope = c.key.slice(0, dot), name = c.key.slice(dot + 1);
|
||||
if (dot <= 0 || (scope !== "all" && scope !== this.p.node)) return false;
|
||||
if (c.op === "put" && c.value && entryProblem(name, c.value) === null) this.entries.set(c.key, c.value);
|
||||
else this.entries.delete(c.key);
|
||||
return this.writeThrough();
|
||||
}
|
||||
|
||||
/** What applies here: every node's entries, with this node's own laid over them by server name. */
|
||||
effective(): Servers {
|
||||
const out: Record<string, Record<string, unknown>> = {};
|
||||
for (const scope of ["all", this.p.node]) {
|
||||
for (const [key, entry] of [...this.entries].sort(([a], [b]) => a.localeCompare(b))) {
|
||||
if (key.startsWith(scope + ".")) out[key.slice(scope.length + 1)] = entry;
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
private writeThrough(): boolean {
|
||||
const now = JSON.stringify(this.effective(), null, 2) + "\n";
|
||||
let before = "";
|
||||
try {
|
||||
before = readFileSync(registryPath(this.p), "utf8");
|
||||
} catch {
|
||||
/* none yet */
|
||||
}
|
||||
if (now === before) return false;
|
||||
writeFileSync(registryPath(this.p), now, { mode: 0o600 });
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
/** A change from the watch: take it, and render when what applies here changed. */
|
||||
export function onServerChange(view: ServerView, c: ServerChange, p: Paths, write: WriteManaged): string | null {
|
||||
if (!view.take(c)) return null;
|
||||
renderNow(p, write);
|
||||
return `${c.op === "put" ? "registered" : "unregistered"} ${c.key}`;
|
||||
}
|
||||
|
||||
const scopesOf = (p: Paths, nodes: Registration["nodes"]): string[] =>
|
||||
nodes === undefined ? [p.node] : nodes === "all" ? ["all"] : nodes;
|
||||
|
||||
/**
|
||||
* Register (or with no entry, unregister) a server: a put (or delete) per scope in the `servers` state.
|
||||
* Taken into this node's view at once, so the answer says what it did here; every other node takes it
|
||||
* from its watch, and a node that joins later from the current state.
|
||||
*/
|
||||
export async function registerServer(p: Paths, r: Registration, servers: ServerState, view: ServerView,
|
||||
write: WriteManaged, others: () => Promise<string[]>): Promise<Record<string, unknown>> {
|
||||
if (r.entry) {
|
||||
const problem = entryProblem(r.name, r.entry);
|
||||
if (problem) return { registered: false, reason: problem };
|
||||
}
|
||||
const scopes = scopesOf(p, r.nodes);
|
||||
// Compared before and after rather than read from take(): this node's own watch may hand the view the
|
||||
// same change first, and then take() here finds nothing new although this call made it.
|
||||
const before = JSON.stringify(view.effective());
|
||||
for (const scope of scopes) {
|
||||
const key = keyOf(scope, r.name);
|
||||
if (r.entry) await servers.put(key, r.entry);
|
||||
else await servers.delete(key);
|
||||
view.take({ key, op: r.entry ? "put" : "delete", value: r.entry });
|
||||
}
|
||||
const changedHere = JSON.stringify(view.effective()) !== before;
|
||||
const here = scopes.includes("all") || scopes.includes(p.node);
|
||||
const answer: Record<string, unknown> = {
|
||||
[r.entry ? "registered" : "unregistered"]: r.name,
|
||||
on: r.nodes === undefined ? [p.node] : r.nodes,
|
||||
here: here ? (changedHere ? "changed" : "already so") : "not this node",
|
||||
rendered: changedHere ? renderNow(p, write) : [],
|
||||
};
|
||||
if (!r.entry && view.effective()[r.name]) {
|
||||
answer.still = `${r.name} still applies here from another registration (for every node, or for this one); unregister that too`;
|
||||
}
|
||||
if (r.nodes === undefined) {
|
||||
// The question the operator wanted asked: here only, or more?
|
||||
const elsewhere = (await others().catch(() => [] as string[])).filter((n) => n !== p.node);
|
||||
answer.also = elsewhere.length
|
||||
? `claude-code also runs on ${elsewhere.join(", ")}. To ${r.entry ? "register" : "unregister"} it there too, call again with nodes: "all" or a list of those nodes.`
|
||||
: `To do the same on every node running claude-code, call again with nodes: "all".`;
|
||||
}
|
||||
return answer;
|
||||
}
|
||||
|
||||
export { MANAGED_DIR };
|
||||
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"name": "@novox/module-claude-code",
|
||||
"version": "0.1.0",
|
||||
"description": "claude-code — the operator's agent on a machine: its managed configuration, and the consumer side of the Anthropic licence manager (novox/hq design 36).",
|
||||
"type": "module",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"build": "tsc seal.ts grant.ts identity.ts render.ts node.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --rootDir . --outDir dist",
|
||||
"test": "npm run build && node --test --experimental-strip-types 'test/*.test.ts'"
|
||||
},
|
||||
"dependencies": {
|
||||
"@novox/mesh-sdk": "^0.1.7"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^22.0.0",
|
||||
"typescript": "^5.6.0"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,135 @@
|
||||
// What the module writes into the agent's machine-wide managed directory (novox/hq design 36 §1–§4).
|
||||
// Pure: composed from the facts the mesh rendered, the settings the operator set and the licence the
|
||||
// node holds, so what lands under /etc is tested without a machine.
|
||||
//
|
||||
// Three files, owned whole by this module:
|
||||
// managed-mcp.json the tool servers every session loads: the mesh's console as `mesh`, and the
|
||||
// servers the operator declared for the mesh or this node. Exclusive by the
|
||||
// vendor's rule — a server not listed here does not load — which is why the
|
||||
// list is the module's settings and nothing else (operator's choice, 2026-10-03).
|
||||
// managed-settings.json the mesh's keys only: the repositories' attribution convention, the
|
||||
// claude.ai connectors kept beside the managed servers, and — for an API-key
|
||||
// licence only — the key-helper. A person's preferences are theirs.
|
||||
// CLAUDE.md how a session on this mesh works, who this node is, the conventions.
|
||||
|
||||
export const MANAGED_DIR = "/etc/claude-code";
|
||||
|
||||
export interface Facts {
|
||||
readonly node: string;
|
||||
readonly console: string;
|
||||
}
|
||||
|
||||
export interface Settings {
|
||||
readonly role?: string;
|
||||
/** Extra tool servers, in the vendor's `.mcp.json` entry shape, keyed by name. */
|
||||
readonly mcp_servers?: Readonly<Record<string, Record<string, unknown>>>;
|
||||
}
|
||||
|
||||
export interface Binding {
|
||||
readonly licence: string;
|
||||
readonly kind: "subscription" | "api-key";
|
||||
}
|
||||
|
||||
export interface Rendered {
|
||||
readonly [file: string]: string;
|
||||
}
|
||||
|
||||
const MESH_ENTRY = "mesh";
|
||||
|
||||
export type Servers = Readonly<Record<string, Record<string, unknown>>>;
|
||||
|
||||
/** Whether an entry is one the vendor's managed file takes: a name of letters, digits, `-` and `_`, and
|
||||
* an http/sse server with a url or a stdio server with a command. Returns why not, or null. */
|
||||
export function entryProblem(name: string, entry: Record<string, unknown>): string | null {
|
||||
if (!/^[A-Za-z0-9_-]+$/.test(name)) return `"${name}" is not a name the agent takes: letters, digits, - and _`;
|
||||
if (name === MESH_ENTRY) return `"${MESH_ENTRY}" is the mesh's own entry`;
|
||||
const type = entry?.type ?? "stdio";
|
||||
if (type === "http" || type === "sse" || type === "streamable-http") {
|
||||
return typeof entry.url === "string" && entry.url ? null : `an ${type} server needs a url`;
|
||||
}
|
||||
if (type === "stdio") return typeof entry.command === "string" && entry.command ? null : "a stdio server needs a command";
|
||||
return `"${String(type)}" is not a server type the agent knows (http, sse, stdio)`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Compose the three files. `registered` is the module's own list on this node — what was registered
|
||||
* through its tools — laid over the servers the operator set in its settings.
|
||||
*/
|
||||
export function render(facts: Facts, settings: Settings, binding: Binding | null, helperPath: string,
|
||||
registered: Servers = {}): Rendered {
|
||||
const servers: Record<string, unknown> = {};
|
||||
for (const [name, entry] of Object.entries({ ...(settings.mcp_servers ?? {}), ...registered })) {
|
||||
if (entryProblem(name, entry) !== null) continue; // the mesh's own entry, or one the agent would refuse
|
||||
servers[name] = entry;
|
||||
}
|
||||
servers[MESH_ENTRY] = { type: "http", url: facts.console };
|
||||
|
||||
const managed: Record<string, unknown> = {
|
||||
attribution: { commit: "", pr: "" },
|
||||
allowAllClaudeAiMcps: true,
|
||||
};
|
||||
if (binding?.kind === "api-key") managed.apiKeyHelper = helperPath;
|
||||
|
||||
return {
|
||||
"managed-mcp.json": json({ mcpServers: sortKeys(servers) }),
|
||||
"managed-settings.json": json(managed),
|
||||
"CLAUDE.md": instructions(facts, settings),
|
||||
};
|
||||
}
|
||||
|
||||
function json(v: unknown): string {
|
||||
return JSON.stringify(v, null, 2) + "\n";
|
||||
}
|
||||
|
||||
function sortKeys(o: Record<string, unknown>): Record<string, unknown> {
|
||||
return Object.fromEntries(Object.keys(o).sort().map((k) => [k, o[k]]));
|
||||
}
|
||||
|
||||
export function instructions(facts: Facts, settings: Settings): string {
|
||||
const role = settings.role?.trim() ? settings.role.trim() : "not stated — set it in this module's settings for the node";
|
||||
return `# This machine is a node of a Novox mesh
|
||||
|
||||
Written by the mesh's \`claude-code\` module. Edit the module's settings or the catalogue, never this file:
|
||||
it is rewritten whenever the module renders.
|
||||
|
||||
## Who this node is
|
||||
|
||||
- **Node:** \`${facts.node}\`
|
||||
- **Role:** ${role}
|
||||
- The other nodes, their roles and what runs where: ask the controller (\`mesh-controller.nodes\`,
|
||||
\`mesh-controller.node\`). Nothing here lists them, because a copy drifts.
|
||||
|
||||
## How a session on this mesh works
|
||||
|
||||
The console is the only way to the mesh: the MCP server named \`mesh\`. It offers five tools, and
|
||||
everything else is an address you find and call through them:
|
||||
|
||||
- \`mesh_search\` — words in, matching addresses out. \`mesh_describe\` — one address's arguments.
|
||||
- \`mesh_call\` — call an address. A seat the mesh holds once is \`<seat>.<verb>\` (the mesh's own verbs
|
||||
are \`mesh-controller.<verb>\`: \`status\`, \`plan\`, \`node\`, \`assign\`, \`push\`, \`settings\`);
|
||||
a module on a machine is \`<node>/<module>.<tool>\`.
|
||||
- \`mesh_overview\` and \`mesh_machine\` — the mesh's seats and machines, and what one machine runs.
|
||||
|
||||
- **Symptom first.** For an error, a failing service or anything unexpected, search the record with the
|
||||
literal text before forming a hypothesis: the records module's \`records_search\`, then
|
||||
\`records_read\`.
|
||||
- **Ask the mesh before changing it**, and change it through the controller's verbs or the catalogue.
|
||||
- **A licence** through the \`anthropic-licence-manager\` seat's verbs. Never edit the agent's credentials
|
||||
file by hand, never print or ask for a token.
|
||||
|
||||
## Hard rules
|
||||
|
||||
- A file the mesh manages is changed through the verb or the catalogue that owns it, never on disk. If
|
||||
unsure, \`mesh-controller.plan\` for the node says what the mesh writes there.
|
||||
- Never write to a store's database by hand; schema changes are numbered migrations.
|
||||
- Never push to a main branch: a branch, a pull request, and a human approval for every merge.
|
||||
- The mesh creates no symlinks, and nobody else does either.
|
||||
- A package is declared in a module, never installed by hand.
|
||||
|
||||
## Conventions
|
||||
|
||||
- Commit messages are concise, in the imperative, about why.
|
||||
- Test before pushing: nodes update unattended.
|
||||
- The playbooks in the record say how research, decisions, designs, issues and hand-offs are done.
|
||||
`;
|
||||
}
|
||||
@@ -0,0 +1,77 @@
|
||||
// Sealing a token to one recipient (novox/hq ADR 0183): the manager seals what it hands a node to that
|
||||
// node's agent module key, and a node seals a waiting login to the key the manager names. X25519 for
|
||||
// the agreement, HKDF-SHA256 for the key, AES-256-GCM for the box — all from Node's own library, so a
|
||||
// bundle carries no dependency and no secret ever crosses the bus in the clear.
|
||||
//
|
||||
// A sealed box is `{ v: 1, eph, iv, tag, ct }`, every field base64. `eph` is a one-time public key, so
|
||||
// two boxes of one value to one recipient share nothing, and only the recipient's private key opens it.
|
||||
|
||||
import {
|
||||
createCipheriv, createDecipheriv, createPrivateKey, createPublicKey, diffieHellman,
|
||||
generateKeyPairSync, hkdfSync, randomBytes, type KeyObject,
|
||||
} from "node:crypto";
|
||||
|
||||
export interface SealedBox {
|
||||
readonly v: 1;
|
||||
readonly eph: string;
|
||||
readonly iv: string;
|
||||
readonly tag: string;
|
||||
readonly ct: string;
|
||||
}
|
||||
|
||||
/** A recipient's keypair, as the two PEM strings it is kept and published as. */
|
||||
export interface KeyPairPem {
|
||||
readonly publicKey: string;
|
||||
readonly privateKey: string;
|
||||
}
|
||||
|
||||
const INFO = Buffer.from("novox-mesh sealed box v1");
|
||||
|
||||
export function generateKeyPair(): KeyPairPem {
|
||||
const { publicKey, privateKey } = generateKeyPairSync("x25519");
|
||||
return {
|
||||
publicKey: publicKey.export({ type: "spki", format: "pem" }).toString(),
|
||||
privateKey: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
|
||||
};
|
||||
}
|
||||
|
||||
function keyFor(secret: Buffer, eph: Buffer, recipient: Buffer): Buffer {
|
||||
// The ephemeral and the recipient's public halves are bound into the key, so a box cannot be
|
||||
// re-addressed to another recipient by swapping its `eph`.
|
||||
return Buffer.from(hkdfSync("sha256", secret, Buffer.concat([eph, recipient]), INFO, 32));
|
||||
}
|
||||
|
||||
function rawPublic(key: KeyObject): Buffer {
|
||||
return key.export({ type: "spki", format: "der" }).subarray(-32);
|
||||
}
|
||||
|
||||
export function seal(plaintext: string, recipientPublicPem: string): SealedBox {
|
||||
const recipient = createPublicKey(recipientPublicPem);
|
||||
const eph = generateKeyPairSync("x25519");
|
||||
const secret = diffieHellman({ privateKey: eph.privateKey, publicKey: recipient });
|
||||
const ephRaw = eph.publicKey.export({ type: "spki", format: "der" });
|
||||
const key = keyFor(secret, ephRaw, rawPublic(recipient));
|
||||
const iv = randomBytes(12);
|
||||
const cipher = createCipheriv("aes-256-gcm", key, iv);
|
||||
const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
|
||||
return {
|
||||
v: 1,
|
||||
eph: ephRaw.toString("base64"),
|
||||
iv: iv.toString("base64"),
|
||||
tag: cipher.getAuthTag().toString("base64"),
|
||||
ct: ct.toString("base64"),
|
||||
};
|
||||
}
|
||||
|
||||
/** Open a box with the recipient's private key. Throws on a box for another key or one tampered with. */
|
||||
export function open(box: SealedBox, privateKeyPem: string): string {
|
||||
if (!box || box.v !== 1) throw new Error("not a sealed box this module can open");
|
||||
const priv = createPrivateKey(privateKeyPem);
|
||||
const ephRaw = Buffer.from(box.eph, "base64");
|
||||
const eph = createPublicKey({ key: ephRaw, format: "der", type: "spki" });
|
||||
const secret = diffieHellman({ privateKey: priv, publicKey: eph });
|
||||
const key = keyFor(secret, ephRaw, rawPublic(createPublicKey(priv)));
|
||||
const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(box.iv, "base64"));
|
||||
decipher.setAuthTag(Buffer.from(box.tag, "base64"));
|
||||
return Buffer.concat([decipher.update(Buffer.from(box.ct, "base64")), decipher.final()]).toString("utf8");
|
||||
}
|
||||
@@ -0,0 +1,54 @@
|
||||
import { test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { mkdtempSync, readFileSync, statSync, writeFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import {
|
||||
decideApply, grantOf, holdsLogin, readCredentials, withGrant, writeCredentials, type Grant,
|
||||
} from "../dist/grant.js";
|
||||
|
||||
const NOW = 1_700_000_000_000;
|
||||
const HOUR = 3_600_000;
|
||||
const g = (over: Partial<Grant> = {}): Grant => ({
|
||||
accessToken: "tok-A", expiresAt: NOW + HOUR, refreshTokenExpiresAt: NOW + 30 * 24 * HOUR, ...over,
|
||||
});
|
||||
|
||||
test("a rotation applies a newer grant of the same licence", () => {
|
||||
assert.deepEqual(decideApply(g(), g({ accessToken: "tok-B", expiresAt: NOW + 2 * HOUR }), "rotation"), { apply: true });
|
||||
});
|
||||
|
||||
test("a rotation refuses a grant that arrived late and is older", () => {
|
||||
const d = decideApply(g({ accessToken: "new", expiresAt: NOW + 2 * HOUR }), g({ accessToken: "old" }), "rotation");
|
||||
assert.equal(d.apply === false && d.reason, "not-newer");
|
||||
});
|
||||
|
||||
test("a grant re-issued by a login is adopted even though it expires sooner (2026-09-05)", () => {
|
||||
const local = g({ expiresAt: NOW + 8 * HOUR, refreshTokenExpiresAt: NOW + 30 * 24 * HOUR });
|
||||
const offered = g({ accessToken: "reissued", expiresAt: NOW + HOUR, refreshTokenExpiresAt: NOW + 5 * 24 * HOUR });
|
||||
assert.deepEqual(decideApply(local, offered, "rotation"), { apply: true, reissued: true });
|
||||
});
|
||||
|
||||
test("a switch to another licence applies whatever the expiries say", () => {
|
||||
const local = g({ expiresAt: NOW + 8 * HOUR });
|
||||
assert.equal(decideApply(local, g({ accessToken: "other", expiresAt: NOW + HOUR }), "switch").apply, true);
|
||||
});
|
||||
|
||||
test("the same token is not rewritten", () => {
|
||||
assert.deepEqual(decideApply(g(), g(), "switch"), { apply: false, reason: "already-current" });
|
||||
});
|
||||
|
||||
test("a full grant left by a login is seen as a login, and stripped when the node's own is written", () => {
|
||||
const dir = mkdtempSync(join(tmpdir(), "claude-code-"));
|
||||
const path = join(dir, ".claude", ".credentials.json");
|
||||
writeFileSync(join(dir, "x"), "");
|
||||
const login = { claudeAiOauth: { accessToken: "at-login", refreshToken: "rt-login", expiresAt: NOW }, other: 1 };
|
||||
assert.equal(holdsLogin(login), true);
|
||||
writeCredentials(path, withGrant(login, g({ accessToken: "at-mesh", scopes: ["user:inference"] })));
|
||||
const back = readCredentials(path)!;
|
||||
assert.equal(holdsLogin(back), false);
|
||||
assert.equal(grantOf(back)!.accessToken, "at-mesh");
|
||||
assert.deepEqual(back.claudeAiOauth!.scopes, ["user:inference"]);
|
||||
assert.equal(back.other, 1, "a key the module does not know was lost");
|
||||
assert.ok(!readFileSync(path, "utf8").includes("rt-login"));
|
||||
assert.equal(statSync(path).mode & 0o777, 0o600);
|
||||
});
|
||||
@@ -0,0 +1,19 @@
|
||||
import { test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { mkdtempSync, writeFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { readIdentity } from "../dist/identity.js";
|
||||
|
||||
test("the account is read from the agent's state file", () => {
|
||||
const p = join(mkdtempSync(join(tmpdir(), "cc-id-")), ".claude.json");
|
||||
writeFileSync(p, JSON.stringify({ oauthAccount: { accountUuid: "u-1", emailAddress: "a@example.org" }, other: 2 }));
|
||||
assert.deepEqual(readIdentity(p), { accountUuid: "u-1", emailAddress: "a@example.org", organizationUuid: undefined });
|
||||
});
|
||||
|
||||
test("no state file, or no account in it, is no identity rather than a guess", () => {
|
||||
assert.equal(readIdentity("/nonexistent/.claude.json"), null);
|
||||
const p = join(mkdtempSync(join(tmpdir(), "cc-id-")), ".claude.json");
|
||||
writeFileSync(p, "{}");
|
||||
assert.equal(readIdentity(p), null);
|
||||
});
|
||||
@@ -0,0 +1,173 @@
|
||||
import { test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import {
|
||||
apply, concerns, keypair, offerLogin, onServerChange, pull, registerServer, registered, ServerView, type Paths,
|
||||
type ServerChange, type ServerState,
|
||||
} from "../dist/node.js";
|
||||
import { generateKeyPair, open, seal } from "../dist/seal.js";
|
||||
|
||||
const NOW = Date.now();
|
||||
function node(name = "laptop"): { p: Paths; written: Record<string, string> } {
|
||||
const root = mkdtempSync(join(tmpdir(), "cc-node-"));
|
||||
const p = { state: join(root, "state"), facts: join(root, "state", "facts.json"), settings: join(root, "state", "settings.json"), home: join(root, "home"), node: name };
|
||||
mkdirSync(p.state, { recursive: true });
|
||||
mkdirSync(join(p.home, ".claude"), { recursive: true });
|
||||
writeFileSync(p.facts, JSON.stringify({ node: name, console: "http://127.0.0.1:4270/mcp" }));
|
||||
writeFileSync(p.settings, JSON.stringify({ role: "", mcp_servers: {} }));
|
||||
return { p, written: {} };
|
||||
}
|
||||
const writer = (w: Record<string, string>) => (name: string, content: string) => { w[name] = content; return `${name}: written`; };
|
||||
const creds = (p: Paths) => JSON.parse(readFileSync(join(p.home, ".claude", ".credentials.json"), "utf8"));
|
||||
const grantFor = (p: Paths, licence: string, token: string, kind: "subscription" | "api-key" = "subscription", identity?: object) => ({
|
||||
licence, kind, identity,
|
||||
sealed: seal(kind === "api-key" ? token : JSON.stringify({ accessToken: token, expiresAt: NOW + 3_600_000, refreshTokenExpiresAt: NOW + 86_400_000, subscriptionType: licence }), keypair(p).publicKey),
|
||||
});
|
||||
|
||||
test("a pull asks the seat with this node's key and applies what it answers", async () => {
|
||||
const { p, written } = node();
|
||||
let asked: [string, Record<string, unknown>] | null = null;
|
||||
const r = await pull(p, async (address, args) => { asked = [address, args]; return grantFor(p, "personal", "at-1"); }, writer(written));
|
||||
assert.equal(asked![0], "anthropic-licence-manager.current");
|
||||
assert.equal(asked![1].node, "laptop");
|
||||
assert.match(String(asked![1].public_key), /BEGIN PUBLIC KEY/);
|
||||
assert.equal(r.applied, true);
|
||||
assert.equal(creds(p).claudeAiOauth.accessToken, "at-1");
|
||||
assert.ok(written["managed-mcp.json"]);
|
||||
});
|
||||
|
||||
test("a switch replaces the old licence's grant whole and points the account at the new one", () => {
|
||||
const { p, written } = node();
|
||||
writeFileSync(join(p.home, ".claude.json"), JSON.stringify({ oauthAccount: { accountUuid: "old" }, projects: { keep: 1 } }));
|
||||
apply(p, grantFor(p, "personal", "at-1"), writer(written));
|
||||
const r = apply(p, grantFor(p, "work", "at-2", "subscription", { accountUuid: "new", emailAddress: "w@example.org" }), writer(written));
|
||||
assert.equal(r.switched, true);
|
||||
assert.equal(creds(p).claudeAiOauth.accessToken, "at-2");
|
||||
assert.equal(creds(p).claudeAiOauth.subscriptionType, "work", "the old licence's subscription type survived the switch");
|
||||
const account = JSON.parse(readFileSync(join(p.home, ".claude.json"), "utf8"));
|
||||
assert.equal(account.oauthAccount.accountUuid, "new");
|
||||
assert.deepEqual(account.projects, { keep: 1 });
|
||||
});
|
||||
|
||||
test("switching to the API key adds the key-helper; switching away removes the key and the helper", () => {
|
||||
const { p, written } = node();
|
||||
apply(p, grantFor(p, "api", "sk-key", "api-key"), writer(written));
|
||||
assert.ok(JSON.parse(written["managed-settings.json"]).apiKeyHelper);
|
||||
assert.ok(existsSync(join(p.state, "api-key")));
|
||||
apply(p, grantFor(p, "personal", "at-1"), writer(written));
|
||||
assert.ok(!("apiKeyHelper" in JSON.parse(written["managed-settings.json"])));
|
||||
assert.ok(!existsSync(join(p.state, "api-key")) && !existsSync(join(p.state, "api-key-helper")));
|
||||
});
|
||||
|
||||
test("a rotation event concerns the node bound to that licence; a switch event the node it names", () => {
|
||||
const { p, written } = node();
|
||||
apply(p, grantFor(p, "personal", "at-1"), writer(written));
|
||||
assert.equal(concerns(p, "claude-licence-manager.licence.rotated", { licence: "personal" }), true);
|
||||
assert.equal(concerns(p, "claude-licence-manager.licence.rotated", { licence: "work" }), false);
|
||||
assert.equal(concerns(p, "claude-licence-manager.licence.switched", { node: "laptop", licence: "work" }), true);
|
||||
assert.equal(concerns(p, "claude-licence-manager.licence.switched", { node: "server" }), false);
|
||||
});
|
||||
|
||||
test("a login is offered to the seat sealed to the seat's key, with the account it belongs to", async () => {
|
||||
const { p } = node();
|
||||
const manager = generateKeyPair();
|
||||
writeFileSync(join(p.home, ".claude", ".credentials.json"), JSON.stringify({ claudeAiOauth: { accessToken: "at-login", refreshToken: "rt-login", expiresAt: NOW } }));
|
||||
writeFileSync(join(p.home, ".claude.json"), JSON.stringify({ oauthAccount: { accountUuid: "u-9" } }));
|
||||
const calls: [string, Record<string, unknown>][] = [];
|
||||
await offerLogin(p, async (address, args) => { calls.push([address, args]); return address.endsWith("public_key") ? { public_key: manager.publicKey } : { adopted: true }; });
|
||||
assert.deepEqual(calls.map((c) => c[0]), ["anthropic-licence-manager.public_key", "anthropic-licence-manager.adopt"]);
|
||||
const adopt = calls[1][1] as { identity: { accountUuid: string }; sealed: never };
|
||||
assert.equal(adopt.identity.accountUuid, "u-9");
|
||||
assert.equal(JSON.parse(open(adopt.sealed, manager.privateKey)).refreshToken, "rt-login");
|
||||
assert.ok(!JSON.stringify(adopt).includes("rt-login"), "the refresh token crossed in the clear");
|
||||
});
|
||||
|
||||
test("no refresh token in the file is no login, and nothing is asked", async () => {
|
||||
const { p } = node();
|
||||
writeFileSync(join(p.home, ".claude", ".credentials.json"), JSON.stringify({ claudeAiOauth: { accessToken: "at", expiresAt: NOW } }));
|
||||
assert.equal(await offerLogin(p, async () => { throw new Error("asked"); }), null);
|
||||
});
|
||||
|
||||
/** The `servers` state as the bus holds it, shared by every node in a test, with each node's watch. */
|
||||
function bus() {
|
||||
const kept = new Map<string, Record<string, unknown>>();
|
||||
const watchers: ((c: ServerChange) => void)[] = [];
|
||||
const state: ServerState = {
|
||||
put: async (key, value) => { kept.set(key, value); watchers.forEach((w) => w({ key, op: "put", value })); return kept.size; },
|
||||
delete: async (key) => { kept.delete(key); watchers.forEach((w) => w({ key, op: "delete" })); },
|
||||
keys: async () => [...kept.keys()].sort(),
|
||||
};
|
||||
/** A node joining: its view takes the current state, then every change. */
|
||||
const join = (n: { p: Paths; written: Record<string, string> }) => {
|
||||
const view = new ServerView(n.p);
|
||||
for (const [key, value] of kept) onServerChange(view, { key, op: "put", value }, n.p, writer(n.written));
|
||||
watchers.push((c) => onServerChange(view, c, n.p, writer(n.written)));
|
||||
return view;
|
||||
};
|
||||
return { state, join, kept };
|
||||
}
|
||||
|
||||
test("registering a server here puts it under this node's key, renders it, and asks about the other nodes", async () => {
|
||||
const n = node();
|
||||
const b = bus();
|
||||
const view = b.join(n);
|
||||
const r = await registerServer(n.p, { name: "search", entry: { type: "http", url: "https://s.example/mcp" } },
|
||||
b.state, view, writer(n.written), async () => ["laptop", "server", "desktop"]);
|
||||
assert.equal(r.here, "changed");
|
||||
assert.match(String(r.also), /server, desktop/);
|
||||
assert.deepEqual([...b.kept.keys()], ["laptop.search"]);
|
||||
assert.ok(JSON.parse(n.written["managed-mcp.json"]).mcpServers.search);
|
||||
});
|
||||
|
||||
test("registering for every node reaches the others through their watch, and a node joining later reads it", async () => {
|
||||
const a = node("laptop"), s = node("server");
|
||||
const b = bus();
|
||||
const va = b.join(a);
|
||||
b.join(s);
|
||||
await registerServer(a.p, { name: "docs", entry: { type: "stdio", command: "docs-mcp" }, nodes: "all" },
|
||||
b.state, va, writer(a.written), async () => []);
|
||||
assert.deepEqual([...b.kept.keys()], ["all.docs"]);
|
||||
assert.deepEqual(registered(s.p).docs, { type: "stdio", command: "docs-mcp" });
|
||||
assert.ok(JSON.parse(s.written["managed-mcp.json"]).mcpServers.docs);
|
||||
// The gap events left: a node assigned after the registration takes the whole current set at start.
|
||||
const late = node("desktop");
|
||||
b.join(late);
|
||||
assert.deepEqual(registered(late.p).docs, { type: "stdio", command: "docs-mcp" });
|
||||
// Unregistering is a delete, and every node's view drops it.
|
||||
await registerServer(a.p, { name: "docs", nodes: "all" }, b.state, va, writer(a.written), async () => []);
|
||||
assert.equal(registered(s.p).docs, undefined);
|
||||
assert.equal(registered(late.p).docs, undefined);
|
||||
});
|
||||
|
||||
test("a node's own registration overrides the one for every node; other nodes' keys leave this one alone", async () => {
|
||||
const a = node("laptop"), s = node("server");
|
||||
const b = bus();
|
||||
const va = b.join(a);
|
||||
const vs = b.join(s);
|
||||
await registerServer(a.p, { name: "x", entry: { type: "http", url: "https://all" }, nodes: "all" }, b.state, va, writer(a.written), async () => []);
|
||||
await registerServer(a.p, { name: "x", entry: { type: "http", url: "https://laptop" } }, b.state, va, writer(a.written), async () => []);
|
||||
assert.equal(registered(a.p).x.url, "https://laptop");
|
||||
assert.equal(registered(s.p).x.url, "https://all");
|
||||
await registerServer(a.p, { name: "only", entry: { type: "http", url: "https://o" }, nodes: ["server"] }, b.state, va, writer(a.written), async () => []);
|
||||
assert.equal(registered(a.p).only, undefined);
|
||||
assert.equal(registered(s.p).only.url, "https://o");
|
||||
// Unregistering here leaves the every-node one applying, and says so.
|
||||
const r = await registerServer(a.p, { name: "x" }, b.state, va, writer(a.written), async () => []);
|
||||
assert.match(String(r.still), /still applies here/);
|
||||
assert.equal(registered(a.p).x.url, "https://all");
|
||||
assert.equal(vs.effective().x.url, "https://all");
|
||||
});
|
||||
|
||||
test("a bad entry is refused before anything is put; a repeated change changes nothing", async () => {
|
||||
const n = node();
|
||||
const b = bus();
|
||||
const view = b.join(n);
|
||||
const r = await registerServer(n.p, { name: "mesh", entry: { type: "http", url: "https://x" } }, b.state, view, writer(n.written), async () => []);
|
||||
assert.equal(r.registered, false);
|
||||
assert.equal(b.kept.size, 0);
|
||||
assert.equal(onServerChange(view, { key: "all.a", op: "put", value: { type: "http", url: "https://a" } }, n.p, writer(n.written)), "registered all.a");
|
||||
assert.equal(onServerChange(view, { key: "all.a", op: "put", value: { type: "http", url: "https://a" } }, n.p, writer(n.written)), null);
|
||||
assert.equal(onServerChange(view, { key: "server.b", op: "put", value: { type: "http", url: "https://b" } }, n.p, writer(n.written)), null);
|
||||
});
|
||||
@@ -0,0 +1,40 @@
|
||||
import { test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { render } from "../dist/render.js";
|
||||
|
||||
const facts = { node: "workstation", console: "http://127.0.0.1:4270/mcp" };
|
||||
|
||||
test("the console is the `mesh` server, and an operator's servers are listed beside it", () => {
|
||||
const out = render(facts, { mcp_servers: { search: { type: "http", url: "https://s.example/mcp" } } }, null, "/h");
|
||||
const mcp = JSON.parse(out["managed-mcp.json"]);
|
||||
assert.deepEqual(Object.keys(mcp.mcpServers), ["mesh", "search"]);
|
||||
assert.deepEqual(mcp.mcpServers.mesh, { type: "http", url: facts.console });
|
||||
});
|
||||
|
||||
test("a setting cannot replace the mesh's own entry, and a name the vendor refuses is left out", () => {
|
||||
const out = render(facts, { mcp_servers: { mesh: { type: "http", url: "http://evil" }, "bad name": {} } }, null, "/h");
|
||||
const mcp = JSON.parse(out["managed-mcp.json"]);
|
||||
assert.equal(mcp.mcpServers.mesh.url, facts.console);
|
||||
assert.ok(!("bad name" in mcp.mcpServers));
|
||||
});
|
||||
|
||||
test("managed settings carry the mesh's keys only, and the key-helper only for an API-key licence", () => {
|
||||
const sub = JSON.parse(render(facts, {}, { licence: "personal", kind: "subscription" }, "/h")["managed-settings.json"]);
|
||||
assert.deepEqual(sub, { attribution: { commit: "", pr: "" }, allowAllClaudeAiMcps: true });
|
||||
const key = JSON.parse(render(facts, {}, { licence: "api", kind: "api-key" }, "/state/api-key-helper")["managed-settings.json"]);
|
||||
assert.equal(key.apiKeyHelper, "/state/api-key-helper");
|
||||
assert.ok(!("model" in key), "a preference is the person's");
|
||||
});
|
||||
|
||||
test("the instruction file names the node and its role, and no other node", () => {
|
||||
const md = render(facts, { role: "the laptop" }, null, "/h")["CLAUDE.md"];
|
||||
assert.match(md, /\*\*Node:\*\* `workstation`/);
|
||||
assert.match(md, /\*\*Role:\*\* the laptop/);
|
||||
assert.match(md, /mesh_call/);
|
||||
assert.match(md, /records_search/);
|
||||
});
|
||||
|
||||
test("rendering is deterministic, so an unchanged input writes nothing", () => {
|
||||
const s = { mcp_servers: { b: { type: "http", url: "https://b" }, a: { type: "http", url: "https://a" } } };
|
||||
assert.deepEqual(render(facts, s, null, "/h"), render(facts, s, null, "/h"));
|
||||
});
|
||||
@@ -0,0 +1,31 @@
|
||||
import { test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { generateKeyPair, open, seal } from "../dist/seal.js";
|
||||
|
||||
test("a box opens with its recipient's key and yields the value", () => {
|
||||
const k = generateKeyPair();
|
||||
assert.equal(open(seal("at-secret", k.publicKey), k.privateKey), "at-secret");
|
||||
});
|
||||
|
||||
test("a box sealed for one node does not open with another node's key", () => {
|
||||
const a = generateKeyPair();
|
||||
const b = generateKeyPair();
|
||||
assert.throws(() => open(seal("at-secret", a.publicKey), b.privateKey));
|
||||
});
|
||||
|
||||
test("a tampered box is refused, not opened to garbage", () => {
|
||||
const k = generateKeyPair();
|
||||
const box = seal("at-secret", k.publicKey);
|
||||
const ct = Buffer.from(box.ct, "base64");
|
||||
ct[0] ^= 0xff;
|
||||
assert.throws(() => open({ ...box, ct: ct.toString("base64") }, k.privateKey));
|
||||
});
|
||||
|
||||
test("two boxes of one value share nothing a reader could compare", () => {
|
||||
const k = generateKeyPair();
|
||||
const x = seal("at-secret", k.publicKey);
|
||||
const y = seal("at-secret", k.publicKey);
|
||||
assert.notEqual(x.ct, y.ct);
|
||||
assert.notEqual(x.eph, y.eph);
|
||||
assert.ok(!JSON.stringify(x).includes("at-secret"));
|
||||
});
|
||||
@@ -0,0 +1,208 @@
|
||||
// claude-code's bundle (novox/hq design 36, ADR 0183). The node's runtime launches it over stdio, as the
|
||||
// operator account (ADR 0193), and is its bus (ADR 0198): it asks tools, emits and consumes through the
|
||||
// runtime. It is given its state directory and two files the mesh renders into it (ADR 0192), beside the
|
||||
// runtime's own words. **stdout is the MCP channel**: everything this module says, it says on stderr.
|
||||
//
|
||||
// At start it renders the agent's managed directory, asks the licence manager for this node's token,
|
||||
// begins watching the credentials file for a login, takes the manager's licence events, and watches the
|
||||
// module's `servers` state — every node's MCP server registrations (novox/hq ADR 0201). node.ts holds the
|
||||
// logic.
|
||||
|
||||
import { readFileSync, watchFile } from "node:fs";
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { join } from "node:path";
|
||||
import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
|
||||
import { broker } from "@novox/mesh-sdk/messaging";
|
||||
import { on } from "@novox/mesh-sdk/events";
|
||||
import { state } from "@novox/mesh-sdk/state";
|
||||
|
||||
import {
|
||||
MANAGED_DIR, SEAT, ServerView, concerns, keypair, offerLogin, onServerChange, pull, readJson, registerServer,
|
||||
registered, renderNow, type Ask, type Paths, type Registration, type ServerChange, type ServerState, type WriteManaged,
|
||||
} from "../node.js";
|
||||
import { grantOf, holdsLogin, readCredentials } from "../grant.js";
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
const say = (line: string) => console.error(`[claude-code] ${line}`);
|
||||
const fingerprint = (s: string) => "sha256:" + createHash("sha256").update(s).digest("hex").slice(0, 16);
|
||||
|
||||
function pathsFrom(env: NodeJS.ProcessEnv): Paths | null {
|
||||
const state = env.MESH_CLAUDE_CODE_STATE, facts = env.MESH_CLAUDE_CODE_FACTS;
|
||||
const settings = env.MESH_CLAUDE_CODE_SETTINGS, home = env.MESH_OPERATOR_HOME, node = env.MESH_NODE;
|
||||
if (!state || !facts || !settings || !home || !node) return null;
|
||||
return { state, facts, settings, home, node };
|
||||
}
|
||||
|
||||
/** Write one managed file as root, only when its content changed. */
|
||||
const writeManaged: WriteManaged = (name, content) => {
|
||||
const path = join(MANAGED_DIR, name);
|
||||
try {
|
||||
if (readFileSync(path, "utf8") === content) return `${name}: unchanged`;
|
||||
} catch {
|
||||
/* absent */
|
||||
}
|
||||
const asRoot = process.getuid?.() === 0;
|
||||
const cmd = asRoot ? ["install", "-D", "-m", "0644", "/dev/stdin", path] : ["sudo", "-n", "install", "-D", "-m", "0644", "/dev/stdin", path];
|
||||
const r = spawnSync(cmd[0], cmd.slice(1), { input: content, encoding: "utf8" });
|
||||
if (r.status !== 0) {
|
||||
throw new Error(`${name}: could not be written to ${MANAGED_DIR} (${(r.stderr || r.error?.message || "").trim()}); ` +
|
||||
`the module writes there through the operator account's passwordless sudo`);
|
||||
}
|
||||
return `${name}: written`;
|
||||
};
|
||||
|
||||
/** A tool on the bus, through the runtime; its MCP answer read back as JSON where it is JSON. */
|
||||
const ask: Ask = async (address, args) => {
|
||||
const answer = (await broker().request<Record<string, unknown>, { content?: { text?: string }[]; isError?: boolean }>(address, args)) ?? {};
|
||||
const text = answer.content?.map((c) => c.text ?? "").join("") ?? "";
|
||||
if (answer.isError) throw new Error(`${address}: ${text}`);
|
||||
try {
|
||||
return JSON.parse(text);
|
||||
} catch {
|
||||
return text;
|
||||
}
|
||||
};
|
||||
|
||||
/** The nodes claude-code runs on, from the controller's list of modules — for the register tool's question. */
|
||||
async function nodesRunningMe(): Promise<string[]> {
|
||||
const out = await ask("mesh-controller.modules", {});
|
||||
const text = typeof out === "string" ? out : String((out as { output?: string })?.output ?? "");
|
||||
const line = text.split("\n").find((l) => /^claude-code\s/.test(l)) ?? "";
|
||||
const on = line.split(" on ")[1] ?? "";
|
||||
return on.trim() === "nothing" ? [] : on.split(",").map((s) => s.trim()).filter(Boolean);
|
||||
}
|
||||
|
||||
function status(p: Paths): Record<string, unknown> {
|
||||
const creds = readCredentials(join(p.home, ".claude", ".credentials.json"));
|
||||
const grant = grantOf(creds);
|
||||
const managed = ["managed-mcp.json", "managed-settings.json", "CLAUDE.md"].map((f) => {
|
||||
try {
|
||||
return { file: join(MANAGED_DIR, f), fingerprint: fingerprint(readFileSync(join(MANAGED_DIR, f), "utf8")) };
|
||||
} catch {
|
||||
return { file: join(MANAGED_DIR, f), fingerprint: null };
|
||||
}
|
||||
});
|
||||
return {
|
||||
node: p.node,
|
||||
licence: readJson(join(p.state, "licence.json"), null),
|
||||
token: grant ? { fingerprint: fingerprint(grant.accessToken), expiresAt: new Date(grant.expiresAt).toISOString(),
|
||||
loginWaiting: holdsLogin(creds) } : null,
|
||||
managed,
|
||||
registered: Object.keys(registered(p)),
|
||||
};
|
||||
}
|
||||
|
||||
/** The module's MCP servers on the bus (ADR 0201): its own state, which every node of it watches. */
|
||||
const servers = () => state<Record<string, unknown>>("servers") as unknown as ServerState;
|
||||
|
||||
/** What this node takes from that state, kept from the watch. One per process. */
|
||||
let view: ServerView | null = null;
|
||||
const viewOf = (p: Paths) => (view ??= new ServerView(p));
|
||||
|
||||
function tools(p: Paths): ToolDefinition[] {
|
||||
const nodesArg = { type: "string", description: 'more nodes: "all" for every node running claude-code, or a comma-separated list; absent is this node only' };
|
||||
const nodesOf = (v: unknown): Registration["nodes"] =>
|
||||
v === undefined || v === "" ? undefined : v === "all" ? "all" : String(v).split(",").map((s) => s.trim()).filter(Boolean);
|
||||
return [
|
||||
{
|
||||
name: "claude_code_status",
|
||||
description: "Claude Code on this machine as the mesh configured it: the licence it holds and when its token expires, the managed files, the MCP servers registered here. Fingerprints only, never a token.",
|
||||
input: {},
|
||||
run: async () => status(p),
|
||||
},
|
||||
{
|
||||
name: "claude_code_render",
|
||||
description: "Write Claude Code's managed directory now, from the mesh's facts, this module's settings and the servers registered here.",
|
||||
input: {},
|
||||
run: async () => ({ rendered: renderNow(p, writeManaged) }),
|
||||
},
|
||||
{
|
||||
name: "claude_code_pull",
|
||||
description: "Ask the licence manager for this node's current token now and apply it, rather than waiting for its next event.",
|
||||
input: {},
|
||||
run: async () => pull(p, ask, writeManaged),
|
||||
},
|
||||
{
|
||||
name: "claude_code_mcp_list",
|
||||
description: "The MCP servers registered through this module: those that apply on this node (beside the console, `mesh`, and those set in the module's settings), and every registration on the mesh, by key — `all.<server>` for every node, `<node>.<server>` for one.",
|
||||
input: {},
|
||||
run: async () => ({ here: registered(p), everywhere: await servers().keys() }),
|
||||
},
|
||||
{
|
||||
name: "claude_code_mcp_register",
|
||||
description: "Register an MCP server with Claude Code on this node, every node, or a list — an http/sse server by url, or a stdio server by command. Kept on the bus, so a node that joins later takes it too. Never put a secret in env or headers: the mesh refuses one.",
|
||||
input: {
|
||||
name: { type: "string", description: "the server's name: letters, digits, - and _" },
|
||||
type: { type: "string", description: "http, sse or stdio (default stdio when a command is given, http when a url is)" },
|
||||
url: { type: "string", description: "an http or sse server's url" },
|
||||
command: { type: "string", description: "a stdio server's program" },
|
||||
args: { type: "array", description: "a stdio server's arguments" },
|
||||
env: { type: "object", description: "a stdio server's environment" },
|
||||
headers: { type: "object", description: "an http server's headers" },
|
||||
nodes: nodesArg,
|
||||
},
|
||||
run: async (a) => {
|
||||
const entry: Record<string, unknown> = { type: a.type ?? (a.url ? "http" : "stdio") };
|
||||
for (const k of ["url", "command", "args", "env", "headers"]) if (a[k] !== undefined) entry[k] = a[k];
|
||||
return registerServer(p, { name: String(a.name ?? ""), entry, nodes: nodesOf(a.nodes) }, servers(), viewOf(p), writeManaged, nodesRunningMe);
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "claude_code_mcp_unregister",
|
||||
description: "Remove an MCP server registered through this module, on this node or more.",
|
||||
input: { name: { type: "string", description: "the server's name" }, nodes: nodesArg },
|
||||
run: async (a) => registerServer(p, { name: String(a.name ?? ""), nodes: nodesOf(a.nodes) }, servers(), viewOf(p), writeManaged, nodesRunningMe),
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
registerModuleTools("claude-code", (env) => {
|
||||
const p = pathsFrom(env);
|
||||
if (!p) return [];
|
||||
try {
|
||||
keypair(p);
|
||||
for (const line of renderNow(p, writeManaged)) if (!line.endsWith("unchanged")) say(line);
|
||||
} catch (err) {
|
||||
say(err instanceof Error ? err.message : String(err));
|
||||
}
|
||||
return tools(p);
|
||||
});
|
||||
|
||||
// Launched by the runtime: the bus is there from the first line (ADR 0198). Outside it — a test, a
|
||||
// build — nothing below runs.
|
||||
const p = process.env.MESH_SERVED_MODULE ? pathsFrom(process.env) : null;
|
||||
if (p) {
|
||||
const loud = (what: string) => (err: unknown) => say(`${what}: ${err instanceof Error ? err.message : String(err)}`);
|
||||
|
||||
void on<{ licence?: string; node?: string }>("claude-licence-manager.licence.*", async (event) => {
|
||||
if (!concerns(p, event.type, event.body ?? {})) return;
|
||||
say(`${event.type} — asking ${SEAT} for this node's token`);
|
||||
say(JSON.stringify(await pull(p, ask, writeManaged).catch((e) => ({ failed: String(e) }))));
|
||||
}).catch(loud("the licence events"));
|
||||
|
||||
// Every node's MCP servers: the whole current set first, then each change (ADR 0201). Awaited, so the
|
||||
// managed directory holds every server that applies here before the bundle says what it serves.
|
||||
try {
|
||||
await state<Record<string, unknown>>("servers").watch((c) => {
|
||||
try {
|
||||
const done = onServerChange(viewOf(p), c as ServerChange, p, writeManaged);
|
||||
if (done) say(done);
|
||||
} catch (err) {
|
||||
loud(`taking ${c.op} ${c.key}`)(err); // the view took it; the next render writes it
|
||||
}
|
||||
});
|
||||
} catch (err) {
|
||||
loud("watching the MCP servers")(err);
|
||||
}
|
||||
|
||||
// Catch up once at start: a node that was off takes its current token now.
|
||||
void pull(p, ask, writeManaged).then((r) => say(`at start: ${JSON.stringify(r)}`), loud("asking for this node's token at start"));
|
||||
|
||||
// A login: a refresh token appears in the credentials file. Polled, because the file is replaced by
|
||||
// rename and a watch on the old inode would go quiet.
|
||||
const credentials = join(p.home, ".claude", ".credentials.json");
|
||||
watchFile(credentials, { interval: 5000 }, () => {
|
||||
void offerLogin(p, ask).then((r) => { if (r) say(`a login here was offered to ${SEAT}: ${JSON.stringify(r)}`); },
|
||||
loud("offering a login to the licence manager"));
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2022",
|
||||
"module": "NodeNext",
|
||||
"moduleResolution": "NodeNext",
|
||||
"strict": true,
|
||||
"esModuleInterop": true,
|
||||
"skipLibCheck": true,
|
||||
"noEmit": true
|
||||
},
|
||||
"include": ["seal.ts", "grant.ts", "identity.ts", "render.ts", "node.ts", "tools/index.ts"]
|
||||
}
|
||||
@@ -1,55 +0,0 @@
|
||||
# claude-licence-manager
|
||||
|
||||
Holds the `anthropic-licence-manager` seat: every Anthropic licence the mesh has, kept alive by one
|
||||
rotation source, and handed to each consumer sealed (novox/hq ADR 0183, ADR 0206, design 39).
|
||||
|
||||
## How a licence comes to exist
|
||||
|
||||
Nothing is configured. Every node running `claude-code` reports what it holds as that module's
|
||||
`holdings` state — the account, fingerprints and expiries, never a token. This module reads every report
|
||||
when it starts and watches them:
|
||||
|
||||
1. A report with a refresh token it does not hold is a **candidate**.
|
||||
2. It asks that node's `claude_code_grant`, giving its public key, and receives the grant sealed to it.
|
||||
3. **It refreshes it.** If the vendor exchanges the token, the grant is this module's — encrypted at rest
|
||||
with the key the vault made for it — and from then on it is the only refresher. If not, the candidate
|
||||
is recorded dead and nothing is adopted.
|
||||
4. Several nodes logged in to one account: newest login first; the rest are never exchanged.
|
||||
5. A node reporting that account and bound to nothing is bound to it.
|
||||
|
||||
Each node is then handed an access token only, so the agent there never refreshes, and a refresh token
|
||||
appearing on a node later can only be a person's login — which wins if it refreshes.
|
||||
|
||||
An API key enters through `adopt`, from a file on this module's node.
|
||||
|
||||
## What each consumer holds
|
||||
|
||||
This module's `bindings` state: one key per consumer (a node's name) with the licence, its kind and a
|
||||
generation that grows with every rotation and switch. `claude-code` watches its own key and, on a newer
|
||||
generation, asks `current` with its public key.
|
||||
|
||||
## The seat's verbs
|
||||
|
||||
`licences`, `bindings`, `bind`, `switch`, `release`, `refresh`, `usage`, `adopt`, `current` — through
|
||||
the console as `anthropic-licence-manager.<verb>`. No answer carries a token.
|
||||
|
||||
## Settings
|
||||
|
||||
`settings.json` in the state directory: `cadence_minutes` (240), `floor_minutes` (60),
|
||||
`failures_to_notify` (3), `cooldown_hours` (24), `refresh_warn_days` (3).
|
||||
|
||||
## Events
|
||||
|
||||
`licence.adopted`, `licence.refused`, `licence.failing`, `usage.read` — none carries a secret.
|
||||
|
||||
## Code and tests
|
||||
|
||||
Go, one binary (`cmd/claude-licence-manager`): the seat's verbs and the daemon in one launched bundle,
|
||||
`prepare` as the run-once preparation step. The sealed box is `claude-code`'s own format, byte for byte —
|
||||
the two modules carry the same `seal.go` — and a test opens one sealed by the TypeScript agent module the
|
||||
Go one replaced, so the format is the one already on the machines.
|
||||
|
||||
go test ./...
|
||||
# the store against a real postgres:
|
||||
docker run -d --rm --name licmgr-pg -e POSTGRES_PASSWORD=t -p 15498:5432 postgres:16-alpine
|
||||
MESH_TEST_POSTGRES=postgres://postgres:t@127.0.0.1:15498/postgres go test ./...
|
||||
@@ -1,64 +0,0 @@
|
||||
package main
|
||||
|
||||
// The grants at rest (novox/hq ADR 0183): encrypted with a key the vault made for this module, so the
|
||||
// store holds ciphertext and only this module, reading its own secret, can open a row. AES-256-GCM, the
|
||||
// key derived from the vault's secret by SHA-256 so a secret of any length serves.
|
||||
|
||||
import (
|
||||
"crypto/rand"
|
||||
"crypto/sha256"
|
||||
"encoding/base64"
|
||||
"errors"
|
||||
"os"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// Crypt seals and opens what the store keeps.
|
||||
type Crypt struct{ key []byte }
|
||||
|
||||
// NewCrypt is the store's cipher from the vault's secret.
|
||||
func NewCrypt(secret string) (*Crypt, error) {
|
||||
secret = strings.TrimSpace(secret)
|
||||
if secret == "" {
|
||||
return nil, errors.New("the key the grants are encrypted with is empty: the vault has not delivered it yet")
|
||||
}
|
||||
sum := sha256.Sum256([]byte(secret))
|
||||
return &Crypt{key: sum[:]}, nil
|
||||
}
|
||||
|
||||
// CryptFromFile reads the vault's secret from the file the mesh delivered it to.
|
||||
func CryptFromFile(path string) (*Crypt, error) {
|
||||
raw, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return NewCrypt(string(raw))
|
||||
}
|
||||
|
||||
// Seal encrypts a plaintext as `v1.<iv>.<ciphertext and tag>`.
|
||||
func (c *Crypt) Seal(plaintext string) string {
|
||||
gcm, _ := newGCM(c.key)
|
||||
iv := make([]byte, 12)
|
||||
_, _ = rand.Read(iv)
|
||||
b64 := base64.StdEncoding.EncodeToString
|
||||
return "v1." + b64(iv) + "." + b64(gcm.Seal(nil, iv, []byte(plaintext), nil))
|
||||
}
|
||||
|
||||
// Open decrypts what Seal made with the same key.
|
||||
func (c *Crypt) Open(sealed string) (string, error) {
|
||||
parts := strings.Split(sealed, ".")
|
||||
if len(parts) != 3 || parts[0] != "v1" {
|
||||
return "", errors.New("not a grant this module sealed")
|
||||
}
|
||||
iv, err1 := base64.StdEncoding.DecodeString(parts[1])
|
||||
ct, err2 := base64.StdEncoding.DecodeString(parts[2])
|
||||
if err := errors.Join(err1, err2); err != nil {
|
||||
return "", err
|
||||
}
|
||||
gcm, _ := newGCM(c.key)
|
||||
plain, err := gcm.Open(nil, iv, ct, nil)
|
||||
if err != nil {
|
||||
return "", errors.New("the grant does not open with this module's key")
|
||||
}
|
||||
return string(plain), nil
|
||||
}
|
||||
@@ -1,348 +0,0 @@
|
||||
// claude-licence-manager (novox/hq ADR 0183, ADR 0206, design 39): one binary, launched by the control
|
||||
// node's runtime and speaking MCP to it over stdio through the Go SDK (ADR 0193, ADR 0198). It serves the
|
||||
// `anthropic-licence-manager` seat's verbs and, beside them, runs long: it watches what every node reports
|
||||
// holding and adopts a login it does not hold, keeps every grant alive under a lease, and reads usage.
|
||||
//
|
||||
// `claude-licence-manager prepare` is the preparation step (ADR 0135): the host runs it once before the
|
||||
// version that needs it, with the module's words and no bus, and it brings the store's schema to shape.
|
||||
//
|
||||
// stdout is the MCP channel; everything this module says, it says on stderr.
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"sort"
|
||||
"strings"
|
||||
"sync"
|
||||
"time"
|
||||
|
||||
stdio "git.novox.be/novox/mesh-sdk/go"
|
||||
)
|
||||
|
||||
// Seat is the role this module holds.
|
||||
const Seat = "anthropic-licence-manager"
|
||||
|
||||
func say(format string, args ...any) {
|
||||
fmt.Fprintf(os.Stderr, "[claude-licence-manager] "+format+"\n", args...)
|
||||
}
|
||||
|
||||
func main() {
|
||||
if len(os.Args) > 1 && os.Args[1] == "prepare" {
|
||||
if err := prepare(); err != nil {
|
||||
say("preparing the store failed: %v", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
say("the store's schema is what this version needs")
|
||||
return
|
||||
}
|
||||
go daemon()
|
||||
if err := stdio.Serve("", tools()); err != nil {
|
||||
say("%v", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
}
|
||||
|
||||
func prepare() error {
|
||||
ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
|
||||
defer cancel()
|
||||
store, err := PgStoreFromEnv(ctx)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
defer store.Close()
|
||||
return store.Migrate(ctx)
|
||||
}
|
||||
|
||||
// ---- what the binary is handed -----------------------------------------------------------------------
|
||||
|
||||
var (
|
||||
built *Manager
|
||||
buildMu sync.Mutex
|
||||
)
|
||||
|
||||
// manager builds the rules' dependencies once, from the module's words (ADR 0192): file paths, never
|
||||
// values. A failure is said and tried again on the next call, so a database that arrives late is not fatal.
|
||||
func manager() (*Manager, error) {
|
||||
buildMu.Lock()
|
||||
defer buildMu.Unlock()
|
||||
if built != nil {
|
||||
return built, nil
|
||||
}
|
||||
dir, keyFile := os.Getenv("MESH_LICENCE_STATE"), os.Getenv("MESH_LICENCE_KEY_FILE")
|
||||
if dir == "" || keyFile == "" {
|
||||
return nil, errors.New("MESH_LICENCE_STATE and MESH_LICENCE_KEY_FILE are not set: the mesh renders them for this module")
|
||||
}
|
||||
crypt, err := CryptFromFile(keyFile)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
keys, err := keypair(dir)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
store, err := PgStoreFromEnv(context.Background())
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
node, _ := os.Hostname()
|
||||
if n := os.Getenv("MESH_NODE"); n != "" {
|
||||
node = n
|
||||
}
|
||||
bindings := stdio.State("bindings")
|
||||
built = &Manager{
|
||||
Store: store,
|
||||
Vendor: LiveVendor(),
|
||||
Crypt: crypt,
|
||||
Keys: keys,
|
||||
AskGrant: func(_ context.Context, node, publicKey string) (GrantAnswer, error) {
|
||||
var a GrantAnswer
|
||||
raw, err := stdio.Ask("claude-code.claude_code_grant@"+node, map[string]any{"public_key": publicKey})
|
||||
if err != nil {
|
||||
return a, err
|
||||
}
|
||||
return a, json.Unmarshal(raw, &a)
|
||||
},
|
||||
PutBinding: func(_ context.Context, consumer string, b BindingState) error {
|
||||
_, err := bindings.Put(consumer, b)
|
||||
return err
|
||||
},
|
||||
DeleteBinding: func(_ context.Context, consumer string) error { return bindings.Delete(consumer) },
|
||||
Emit: func(event string, body map[string]any) error { return stdio.Emit(event, body) },
|
||||
Now: time.Now,
|
||||
Log: say,
|
||||
Holder: fmt.Sprintf("%s:%d", node, os.Getpid()),
|
||||
Settings: SettingsFrom(os.Getenv("MESH_LICENCE_SETTINGS")),
|
||||
}
|
||||
return built, nil
|
||||
}
|
||||
|
||||
// keypair is this module's own, made once in its state directory; the private half never leaves it.
|
||||
// Written whole, then linked into place, so a second process reads the first's key and never half of it.
|
||||
func keypair(dir string) (KeyPair, error) {
|
||||
file := filepath.Join(dir, "manager-key.json")
|
||||
if _, err := os.Stat(file); errors.Is(err, os.ErrNotExist) {
|
||||
k, err := GenerateKeyPair()
|
||||
if err != nil {
|
||||
return KeyPair{}, err
|
||||
}
|
||||
raw, _ := json.Marshal(k)
|
||||
tmp := filepath.Join(dir, fmt.Sprintf(".manager-key.%d.json", os.Getpid()))
|
||||
if err := os.WriteFile(tmp, raw, 0o600); err != nil {
|
||||
return KeyPair{}, err
|
||||
}
|
||||
_ = os.Link(tmp, file) // fails when another made it first, which is right
|
||||
_ = os.Remove(tmp)
|
||||
}
|
||||
raw, err := os.ReadFile(file)
|
||||
if err != nil {
|
||||
return KeyPair{}, err
|
||||
}
|
||||
var k KeyPair
|
||||
return k, json.Unmarshal(raw, &k)
|
||||
}
|
||||
|
||||
// ---- the long-running half ---------------------------------------------------------------------------
|
||||
|
||||
func daemon() {
|
||||
var mu sync.Mutex
|
||||
reports := map[string]Holdings{}
|
||||
var passing sync.Mutex
|
||||
pass := func() {
|
||||
passing.Lock() // one pass at a time: each account is leased, and a pass is cheap
|
||||
defer passing.Unlock()
|
||||
m, err := manager()
|
||||
if err != nil {
|
||||
say("not ready: %v", err)
|
||||
return
|
||||
}
|
||||
mu.Lock()
|
||||
all := make([]Holdings, 0, len(reports))
|
||||
for _, r := range reports {
|
||||
all = append(all, r)
|
||||
}
|
||||
mu.Unlock()
|
||||
sort.Slice(all, func(i, j int) bool { return all[i].Node < all[j].Node })
|
||||
adopted, err := m.Consider(context.Background(), all)
|
||||
if err != nil {
|
||||
say("considering the reports failed: %v", err)
|
||||
}
|
||||
if len(adopted) > 0 {
|
||||
say("adopted %s", strings.Join(adopted, ", "))
|
||||
}
|
||||
}
|
||||
|
||||
// What every node holds (ADR 0206): the whole current set, then each change. Asked again until it
|
||||
// answers — the channel to the runtime opens as the bundle starts, and the agent module's state may
|
||||
// arrive after this one.
|
||||
go func() {
|
||||
waits := []time.Duration{2 * time.Second, 5 * time.Second, 10 * time.Second, 30 * time.Second}
|
||||
for attempt := 0; ; attempt++ {
|
||||
err := stdio.State("claude-code.holdings").Watch("", func(c stdio.StateChange) error {
|
||||
mu.Lock()
|
||||
if c.Op == "put" {
|
||||
var h Holdings
|
||||
if json.Unmarshal(c.Value, &h) == nil {
|
||||
reports[c.Key] = h
|
||||
}
|
||||
} else {
|
||||
delete(reports, c.Key)
|
||||
}
|
||||
mu.Unlock()
|
||||
// During the current values the pass waits for the whole set: newest login first needs all.
|
||||
if !c.Current {
|
||||
go pass()
|
||||
}
|
||||
return nil
|
||||
})
|
||||
if err == nil {
|
||||
mu.Lock()
|
||||
n := len(reports)
|
||||
mu.Unlock()
|
||||
say("watching what %d node(s) hold", n)
|
||||
pass()
|
||||
return
|
||||
}
|
||||
pause := time.Minute
|
||||
if attempt < len(waits) {
|
||||
pause = waits[attempt]
|
||||
}
|
||||
say("what the nodes hold cannot be watched yet (%v); asking again in %s", err, pause)
|
||||
time.Sleep(pause)
|
||||
}
|
||||
}()
|
||||
|
||||
refresh := time.NewTicker(time.Minute)
|
||||
usage := time.NewTicker(5 * time.Minute)
|
||||
for {
|
||||
select {
|
||||
case <-refresh.C:
|
||||
if m, err := manager(); err == nil {
|
||||
out, err := m.RotateDue(context.Background())
|
||||
for _, r := range out {
|
||||
b, _ := json.Marshal(r)
|
||||
say("%s", b)
|
||||
}
|
||||
if err != nil {
|
||||
say("refreshing failed: %v", err)
|
||||
}
|
||||
}
|
||||
pass() // a login whose node did not answer last time is asked again
|
||||
case <-usage.C:
|
||||
if m, err := manager(); err == nil {
|
||||
if err := m.ReadUsage(context.Background()); err != nil {
|
||||
say("reading usage failed: %v", err)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ---- the seat's verbs --------------------------------------------------------------------------------
|
||||
|
||||
func text(a map[string]any, k string) (string, error) {
|
||||
v, _ := a[k].(string)
|
||||
if strings.TrimSpace(v) == "" {
|
||||
return "", fmt.Errorf("%s is required", k)
|
||||
}
|
||||
return strings.TrimSpace(v), nil
|
||||
}
|
||||
|
||||
// verb is one of the seat's verbs: listed as `<seat>.<verb>`, so the runtime serves it on the seat's subject.
|
||||
func verb(name, description string, input map[string]any, run func(ctx context.Context, m *Manager, a map[string]any) (any, error)) stdio.Tool {
|
||||
return stdio.Tool{Name: Seat + "." + name, Description: description, Input: input,
|
||||
Run: func(a map[string]any) (any, error) {
|
||||
m, err := manager()
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return run(context.Background(), m, a)
|
||||
}}
|
||||
}
|
||||
|
||||
func str(description string) map[string]any {
|
||||
return map[string]any{"type": "string", "description": description}
|
||||
}
|
||||
|
||||
func two(a map[string]any, k1, k2 string) (string, string, error) {
|
||||
v1, err1 := text(a, k1)
|
||||
v2, err2 := text(a, k2)
|
||||
return v1, v2, errors.Join(err1, err2)
|
||||
}
|
||||
|
||||
func tools() []stdio.Tool {
|
||||
consumer := str("the node's name")
|
||||
return []stdio.Tool{
|
||||
verb("licences", "Every licence the manager holds — account, kind, when its token and its refresh token expire, failures in a row, which consumers are bound to it. Never a token.",
|
||||
nil, func(ctx context.Context, m *Manager, _ map[string]any) (any, error) { return m.Licences(ctx) }),
|
||||
verb("bindings", "Which licence each consumer (a node's agent, by the node's name) is bound to, and the generation it was last given.",
|
||||
nil, func(ctx context.Context, m *Manager, _ map[string]any) (any, error) { return m.Store.Bindings(ctx) }),
|
||||
verb("bind", "Bind a consumer — a node's agent, by the node's name — to a licence. Its node fetches the licence's token at once.",
|
||||
map[string]any{"consumer": consumer, "licence": str("a licence, as `licences` names it")},
|
||||
func(ctx context.Context, m *Manager, a map[string]any) (any, error) {
|
||||
c, l, err := two(a, "consumer", "licence")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.Bind(ctx, c, l, "bind")
|
||||
}),
|
||||
verb("switch", "Move a consumer to another licence. Its node fetches the new licence's token at once and points the agent's account at it.",
|
||||
map[string]any{"consumer": consumer, "licence": str("the licence to move to")},
|
||||
func(ctx context.Context, m *Manager, a map[string]any) (any, error) {
|
||||
c, l, err := two(a, "consumer", "licence")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.Bind(ctx, c, l, "switch")
|
||||
}),
|
||||
verb("release", "Unbind a consumer. Its node keeps its last token, which expires within hours.",
|
||||
map[string]any{"consumer": consumer},
|
||||
func(ctx context.Context, m *Manager, a map[string]any) (any, error) {
|
||||
c, err := text(a, "consumer")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.Release(ctx, c, "release")
|
||||
}),
|
||||
verb("refresh", "Refresh a licence now, or every due licence when none is named; under each licence's lease, so it never races the daemon. Answers the outcome, never a token.",
|
||||
map[string]any{"licence": str("a licence; absent for every due one")},
|
||||
func(ctx context.Context, m *Manager, a map[string]any) (any, error) {
|
||||
if l, _ := a["licence"].(string); l != "" {
|
||||
return m.Rotate(ctx, l, true)
|
||||
}
|
||||
return m.RotateDue(ctx)
|
||||
}),
|
||||
verb("usage", "Usage readings, the latest first, for every licence or one.",
|
||||
map[string]any{"licence": str("a licence; absent for all"), "limit": map[string]any{"type": "number", "description": "how many readings (default 20)"}},
|
||||
func(ctx context.Context, m *Manager, a map[string]any) (any, error) {
|
||||
l, _ := a["licence"].(string)
|
||||
limit := 20
|
||||
if v, ok := a["limit"].(float64); ok && v > 0 {
|
||||
limit = int(v)
|
||||
}
|
||||
return m.Store.Usage(ctx, l, limit)
|
||||
}),
|
||||
verb("adopt", "Adopt an API key from a file on the manager's node, never as an argument. Subscriptions are adopted from the nodes' logins by themselves.",
|
||||
map[string]any{"name": str("the licence's name"), "file": str("a file on the manager's node holding the key")},
|
||||
func(ctx context.Context, m *Manager, a map[string]any) (any, error) {
|
||||
n, f, err := two(a, "name", "file")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.AdoptKey(ctx, n, f)
|
||||
}),
|
||||
verb("current", "For a consumer's agent module (ADR 0206): its token, sealed to the public key it sends, with the licence, kind and generation. Null when it is bound to nothing.",
|
||||
map[string]any{"consumer": consumer, "public_key": str("the consumer's public key, PEM")},
|
||||
func(ctx context.Context, m *Manager, a map[string]any) (any, error) {
|
||||
c, k, err := two(a, "consumer", "public_key")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.Current(ctx, c, k)
|
||||
}),
|
||||
}
|
||||
}
|
||||
@@ -1,678 +0,0 @@
|
||||
package main
|
||||
|
||||
// The Anthropic licence manager's rules (novox/hq ADR 0183, ADR 0206, design 39), written against what it
|
||||
// is handed — a store, the vendor, a way to ask a node, its own state, a way to emit — so every rule is
|
||||
// tested without a bus, a database or the vendor.
|
||||
//
|
||||
// - A licence is an account, learned from what the nodes report (`holdings`, the agent module's state).
|
||||
// A report with a refresh token the manager does not hold is a candidate.
|
||||
// - The secret is asked for, sealed to this module's key, never published.
|
||||
// - Adopting is refreshing: newest login first, once per account; a failure adopts nothing.
|
||||
// - What each consumer should hold is this module's `bindings` state, with a generation that grows with
|
||||
// every rotation and switch; the consumer fetches its token by asking `current`.
|
||||
// - One rotation source: every exchange with the vendor runs under a lease.
|
||||
|
||||
import (
|
||||
"context"
|
||||
"crypto/sha256"
|
||||
"encoding/hex"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"os"
|
||||
"regexp"
|
||||
"sort"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// Fingerprint names a token without being one: the agent module's own fingerprint, so the two compare.
|
||||
func Fingerprint(s string) string {
|
||||
sum := sha256.Sum256([]byte(s))
|
||||
return "sha256:" + hex.EncodeToString(sum[:])[:16]
|
||||
}
|
||||
|
||||
// Identity is the account a grant belongs to, as the agent's own state file names it.
|
||||
type Identity struct {
|
||||
AccountUUID string `json:"accountUuid"`
|
||||
EmailAddress string `json:"emailAddress,omitempty"`
|
||||
OrganizationUUID string `json:"organizationUuid,omitempty"`
|
||||
}
|
||||
|
||||
// Holdings is one node's report, as the agent module writes it to its `holdings` state (ADR 0206).
|
||||
type Holdings struct {
|
||||
Node string `json:"node"`
|
||||
Identity *Identity `json:"identity"`
|
||||
Kind string `json:"kind"`
|
||||
Refresh struct {
|
||||
Present bool `json:"present"`
|
||||
Fingerprint string `json:"fingerprint"`
|
||||
} `json:"refresh"`
|
||||
ChangedAt string `json:"changedAt"`
|
||||
}
|
||||
|
||||
// BindingState is what `bindings` holds for one consumer: no secret, only what it should hold and which
|
||||
// generation.
|
||||
type BindingState struct {
|
||||
Licence string `json:"licence"`
|
||||
Kind string `json:"kind"`
|
||||
Generation int64 `json:"generation"`
|
||||
}
|
||||
|
||||
// Settings are the manager's own, declared with defaults (design 39 §8).
|
||||
type Settings struct {
|
||||
Cadence time.Duration // rotate a grant once older than this
|
||||
Floor time.Duration // refresh in any case with less than this left
|
||||
FailuresToNotify int
|
||||
Cooldown time.Duration // at most one notification per licence in this window
|
||||
RefreshWarn time.Duration // warn this long before a refresh token itself expires
|
||||
}
|
||||
|
||||
// Defaults are the settings a fresh mesh runs with.
|
||||
var Defaults = Settings{Cadence: 4 * time.Hour, Floor: time.Hour, FailuresToNotify: 3, Cooldown: 24 * time.Hour, RefreshWarn: 72 * time.Hour}
|
||||
|
||||
// SettingsFrom reads the settings file, keeping a default for anything absent or not positive.
|
||||
func SettingsFrom(path string) Settings {
|
||||
s := Defaults
|
||||
raw, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return s
|
||||
}
|
||||
var f map[string]float64
|
||||
if json.Unmarshal(raw, &f) != nil {
|
||||
return s
|
||||
}
|
||||
set := func(k string, unit time.Duration, into *time.Duration) {
|
||||
if v := f[k]; v > 0 {
|
||||
*into = time.Duration(v * float64(unit))
|
||||
}
|
||||
}
|
||||
set("cadence_minutes", time.Minute, &s.Cadence)
|
||||
set("floor_minutes", time.Minute, &s.Floor)
|
||||
set("cooldown_hours", time.Hour, &s.Cooldown)
|
||||
if v := f["refresh_warn_days"]; v > 0 {
|
||||
s.RefreshWarn = time.Duration(v * float64(24*time.Hour))
|
||||
}
|
||||
if v := f["failures_to_notify"]; v > 0 {
|
||||
s.FailuresToNotify = int(v)
|
||||
}
|
||||
return s
|
||||
}
|
||||
|
||||
// GrantAnswer is what a node's `claude_code_grant` answers: a login sealed to the key given, or nothing.
|
||||
type GrantAnswer struct {
|
||||
Sealed *SealedBox `json:"sealed"`
|
||||
Identity *Identity `json:"identity"`
|
||||
Fingerprint string `json:"fingerprint"`
|
||||
}
|
||||
|
||||
// Manager is the rules and what they are handed.
|
||||
type Manager struct {
|
||||
Store Store
|
||||
Vendor Vendor
|
||||
Crypt *Crypt
|
||||
Keys KeyPair
|
||||
// AskGrant asks a node's agent module for the grant a login left there, sealed to publicKey. An error
|
||||
// is the node not answering; a nil Sealed is no login waiting.
|
||||
AskGrant func(ctx context.Context, node, publicKey string) (GrantAnswer, error)
|
||||
// PutBinding and DeleteBinding are this module's `bindings` state.
|
||||
PutBinding func(ctx context.Context, consumer string, b BindingState) error
|
||||
DeleteBinding func(ctx context.Context, consumer string) error
|
||||
Emit func(event string, body map[string]any) error
|
||||
Now func() time.Time
|
||||
Log func(format string, args ...any)
|
||||
// Holder names this process in a lease, so a second run is told apart.
|
||||
Holder string
|
||||
Settings Settings
|
||||
}
|
||||
|
||||
const leaseFor = 2 * time.Minute
|
||||
|
||||
// NameFor is a licence's name: the account's address where it has one, else its id.
|
||||
func NameFor(id Identity) string {
|
||||
if e := strings.TrimSpace(id.EmailAddress); e != "" {
|
||||
return e
|
||||
}
|
||||
return id.AccountUUID
|
||||
}
|
||||
|
||||
// ---- learning licences from what the nodes hold ------------------------------------------------------
|
||||
|
||||
// Candidate is a report the manager should try.
|
||||
type Candidate struct {
|
||||
Node string
|
||||
Identity Identity
|
||||
Fingerprint string
|
||||
ChangedAt int64
|
||||
}
|
||||
|
||||
// CandidatesIn is the candidates in a set of reports by account, newest login first (ADR 0206 §2, §4). A
|
||||
// report without an identity is not one: a grant is filed under its account or not at all.
|
||||
func (m *Manager) CandidatesIn(ctx context.Context, reports []Holdings) (map[string][]Candidate, error) {
|
||||
out := map[string][]Candidate{}
|
||||
for _, r := range reports {
|
||||
if !r.Refresh.Present || r.Refresh.Fingerprint == "" || r.Identity == nil || r.Identity.AccountUUID == "" {
|
||||
continue
|
||||
}
|
||||
settled, err := m.Store.Outcome(ctx, r.Refresh.Fingerprint)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if settled != "" {
|
||||
continue // adopted, dead, skipped, refused or gone: settled once
|
||||
}
|
||||
held, err := m.Store.LicenceForAccount(ctx, r.Identity.AccountUUID)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if held != nil && held.RefreshFingerprint == r.Refresh.Fingerprint {
|
||||
continue
|
||||
}
|
||||
var changed int64
|
||||
if t, err := time.Parse(time.RFC3339Nano, r.ChangedAt); err == nil {
|
||||
changed = t.UnixMilli()
|
||||
}
|
||||
// The latest login wins: one no newer than the grant held is not a newer login.
|
||||
if held != nil && changed <= held.AdoptedAt {
|
||||
continue
|
||||
}
|
||||
out[r.Identity.AccountUUID] = append(out[r.Identity.AccountUUID],
|
||||
Candidate{Node: r.Node, Identity: *r.Identity, Fingerprint: r.Refresh.Fingerprint, ChangedAt: changed})
|
||||
}
|
||||
for _, list := range out {
|
||||
sort.SliceStable(list, func(i, j int) bool { return list[i].ChangedAt > list[j].ChangedAt })
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// Consider every report (ADR 0206): for each account with candidates, under that account's lease, try them
|
||||
// newest first; the first that refreshes is adopted and the rest are settled as skipped without being
|
||||
// exchanged. Answers what was adopted.
|
||||
func (m *Manager) Consider(ctx context.Context, reports []Holdings) ([]string, error) {
|
||||
byAccount, err := m.CandidatesIn(ctx, reports)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
accounts := make([]string, 0, len(byAccount))
|
||||
for a := range byAccount {
|
||||
accounts = append(accounts, a)
|
||||
}
|
||||
sort.Strings(accounts)
|
||||
// A node reporting an account the manager already holds, and bound to nothing, is bound to it
|
||||
// (ADR 0206 §7) — whenever its report arrives, not only when the licence is adopted: a node whose own
|
||||
// login is older than the one adopted is never a candidate, and would otherwise never be bound.
|
||||
if err := m.bindReporters(ctx, reports); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
var adopted []string
|
||||
for _, account := range accounts {
|
||||
list := byAccount[account]
|
||||
key := "account:" + account
|
||||
ok, err := m.Store.Lease(ctx, key, m.Holder, leaseFor)
|
||||
if err != nil || !ok {
|
||||
continue
|
||||
}
|
||||
for i, c := range list {
|
||||
name, err := m.adoptOne(ctx, c, reports)
|
||||
if err != nil {
|
||||
m.Log("adopting %s's login failed: %v", c.Node, err)
|
||||
continue
|
||||
}
|
||||
if name != "" {
|
||||
adopted = append(adopted, name)
|
||||
for _, rest := range list[i+1:] {
|
||||
_ = m.Store.RecordOutcome(ctx, rest.Fingerprint, rest.Node, account, Skipped, c.Node+"'s newer login was adopted first")
|
||||
}
|
||||
break
|
||||
}
|
||||
}
|
||||
_ = m.Store.Unlease(ctx, key, m.Holder)
|
||||
}
|
||||
return adopted, nil
|
||||
}
|
||||
|
||||
// bindReporters binds each reporting node that is bound to nothing to the licence its account already has.
|
||||
func (m *Manager) bindReporters(ctx context.Context, reports []Holdings) error {
|
||||
for _, rep := range reports {
|
||||
if rep.Identity == nil || rep.Identity.AccountUUID == "" {
|
||||
continue
|
||||
}
|
||||
if b, err := m.Store.Binding(ctx, rep.Node); err != nil || b != nil {
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
continue
|
||||
}
|
||||
l, err := m.Store.LicenceForAccount(ctx, rep.Identity.AccountUUID)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if l == nil {
|
||||
continue
|
||||
}
|
||||
b, err := m.Store.Bind(ctx, rep.Node, l.Name)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
_ = m.Store.Audit(ctx, "bound", map[string]any{"consumer": rep.Node, "licence": l.Name, "by": "its account's report"})
|
||||
if err := m.PutBinding(ctx, rep.Node, BindingState{Licence: l.Name, Kind: l.Kind, Generation: b.Generation}); err != nil {
|
||||
return err
|
||||
}
|
||||
m.Log("bound %s to %s, the licence its account already has", rep.Node, l.Name)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func (m *Manager) adoptOne(ctx context.Context, c Candidate, reports []Holdings) (string, error) {
|
||||
answer, err := m.AskGrant(ctx, c.Node, m.Keys.PublicKey)
|
||||
if err != nil {
|
||||
// Not answering is not an answer: asked again on the next pass.
|
||||
m.Log("%s did not hand over its login: %v", c.Node, err)
|
||||
return "", nil
|
||||
}
|
||||
if answer.Sealed == nil {
|
||||
return "", m.Store.RecordOutcome(ctx, c.Fingerprint, c.Node, c.Identity.AccountUUID, Gone, "no login was waiting when asked")
|
||||
}
|
||||
plain, err := Open(*answer.Sealed, m.Keys.PrivateKey)
|
||||
if err != nil {
|
||||
return "", m.Store.RecordOutcome(ctx, c.Fingerprint, c.Node, c.Identity.AccountUUID, Refused, "the grant did not open with this module's key")
|
||||
}
|
||||
var offered FullGrant
|
||||
if err := json.Unmarshal([]byte(plain), &offered); err != nil || offered.RefreshToken == "" {
|
||||
return "", m.Store.RecordOutcome(ctx, c.Fingerprint, c.Node, c.Identity.AccountUUID, Refused, "the grant holds no refresh token")
|
||||
}
|
||||
if Fingerprint(offered.RefreshToken) != c.Fingerprint {
|
||||
m.Log("%s's login changed while it was asked for; waiting for its next report", c.Node)
|
||||
return "", nil
|
||||
}
|
||||
|
||||
// Adopting is refreshing (ADR 0206 §4): the exchange is the check, and from here this module is the
|
||||
// only holder of a live refresh token for the account.
|
||||
r := m.Vendor.Refresh(ctx, offered)
|
||||
if !r.OK {
|
||||
_ = m.Store.RecordOutcome(ctx, c.Fingerprint, c.Node, c.Identity.AccountUUID, Dead, fmt.Sprintf("%d %s", r.Status, r.Reason))
|
||||
_ = m.Store.Audit(ctx, "refused", map[string]any{"node": c.Node, "account": c.Identity.AccountUUID, "status": r.Status, "reason": r.Reason})
|
||||
_ = m.Emit("licence.refused", map[string]any{"node": c.Node, "account": NameFor(c.Identity),
|
||||
"reason": fmt.Sprintf("the login's refresh token did not refresh (%d)", r.Status)})
|
||||
m.Log("%s's login for %s did not refresh: %d %s", c.Node, NameFor(c.Identity), r.Status, r.Reason)
|
||||
return "", nil
|
||||
}
|
||||
// The identity guard, on two sources (ADR 0206 §8).
|
||||
if r.Account != "" && r.Account != c.Identity.AccountUUID {
|
||||
_ = m.Store.RecordOutcome(ctx, c.Fingerprint, c.Node, c.Identity.AccountUUID, Refused,
|
||||
"the node says "+c.Identity.AccountUUID+", the vendor says "+r.Account)
|
||||
_ = m.Store.Audit(ctx, "refused", map[string]any{"node": c.Node, "reported": c.Identity.AccountUUID, "vendor": r.Account})
|
||||
_ = m.Emit("licence.refused", map[string]any{"node": c.Node, "account": NameFor(c.Identity),
|
||||
"reason": "the account the node reported is not the one the vendor answered for"})
|
||||
return "", nil
|
||||
}
|
||||
|
||||
held, err := m.Store.LicenceForAccount(ctx, c.Identity.AccountUUID)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
now := m.Now().UnixMilli()
|
||||
l := Licence{Name: NameFor(c.Identity), Kind: "subscription", AccountUUID: c.Identity.AccountUUID,
|
||||
Email: c.Identity.EmailAddress, OrganizationUUID: c.Identity.OrganizationUUID}
|
||||
if held != nil {
|
||||
l.Name, l.NotifiedAt = held.Name, held.NotifiedAt
|
||||
if l.Email == "" {
|
||||
l.Email = held.Email
|
||||
}
|
||||
if l.OrganizationUUID == "" {
|
||||
l.OrganizationUUID = held.OrganizationUUID
|
||||
}
|
||||
}
|
||||
m.keep(&l, r.Grant)
|
||||
l.AdoptedAt = max(now, c.ChangedAt)
|
||||
if err := m.Store.SaveLicence(ctx, l); err != nil {
|
||||
return "", err
|
||||
}
|
||||
why := "a new licence"
|
||||
if held != nil {
|
||||
why = "a newer login"
|
||||
}
|
||||
_ = m.Store.RecordOutcome(ctx, c.Fingerprint, c.Node, c.Identity.AccountUUID, Adopted, why)
|
||||
_ = m.Store.Audit(ctx, "adopted", map[string]any{"licence": l.Name, "node": c.Node, "account": c.Identity.AccountUUID,
|
||||
"vendorNamedAccount": r.Account != ""})
|
||||
|
||||
// A first binding follows the login (ADR 0206 §7): every node reporting this account and bound to nothing.
|
||||
for _, rep := range reports {
|
||||
if rep.Identity == nil || rep.Identity.AccountUUID != c.Identity.AccountUUID {
|
||||
continue
|
||||
}
|
||||
if b, err := m.Store.Binding(ctx, rep.Node); err != nil || b != nil {
|
||||
continue
|
||||
}
|
||||
if _, err := m.Store.Bind(ctx, rep.Node, l.Name); err == nil {
|
||||
_ = m.Store.Audit(ctx, "bound", map[string]any{"consumer": rep.Node, "licence": l.Name, "by": "its login"})
|
||||
}
|
||||
}
|
||||
if err := m.publishAdvance(ctx, l); err != nil {
|
||||
return "", err
|
||||
}
|
||||
_ = m.Emit("licence.adopted", map[string]any{"licence": l.Name, "from": c.Node, "replaced": held != nil})
|
||||
m.Log("adopted %s from %s (%s)", l.Name, c.Node, why)
|
||||
return l.Name, nil
|
||||
}
|
||||
|
||||
// keep stores a grant on its licence: encrypted, fingerprinted, its expiries, fresh.
|
||||
func (m *Manager) keep(l *Licence, g FullGrant) {
|
||||
raw, _ := json.Marshal(g)
|
||||
l.Sealed = m.Crypt.Seal(string(raw))
|
||||
l.RefreshFingerprint = Fingerprint(g.RefreshToken)
|
||||
l.AccessExpiresAt = g.ExpiresAt
|
||||
if g.RefreshTokenExpiresAt != nil {
|
||||
l.RefreshExpiresAt = *g.RefreshTokenExpiresAt
|
||||
}
|
||||
l.Failures = 0
|
||||
l.RotatedAt = m.Now().UnixMilli()
|
||||
}
|
||||
|
||||
// publishAdvance gives every consumer of a licence a new generation, and tells each in the state.
|
||||
func (m *Manager) publishAdvance(ctx context.Context, l Licence) error {
|
||||
bindings, err := m.Store.Advance(ctx, l.Name)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
for _, b := range bindings {
|
||||
if err := m.PutBinding(ctx, b.Consumer, BindingState{Licence: b.Licence, Kind: l.Kind, Generation: b.Generation}); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// ---- keeping grants alive ----------------------------------------------------------------------------
|
||||
|
||||
// Due says whether a licence needs a refresh now: near expiry, or older than the cadence.
|
||||
func Due(l Licence, now time.Time, s Settings) bool {
|
||||
if l.Kind != "subscription" || l.Sealed == "" {
|
||||
return false
|
||||
}
|
||||
ms := now.UnixMilli()
|
||||
if l.AccessExpiresAt != 0 && l.AccessExpiresAt-ms < s.Floor.Milliseconds() {
|
||||
return true
|
||||
}
|
||||
return l.RotatedAt == 0 || ms-l.RotatedAt >= s.Cadence.Milliseconds()
|
||||
}
|
||||
|
||||
// Rotate refreshes one licence under its lease (design 39 §3). A second run started together finds the
|
||||
// lease live and does nothing; one started just after finds a fresh grant and is not due. force refreshes
|
||||
// whatever the age — the seat's `refresh` verb.
|
||||
func (m *Manager) Rotate(ctx context.Context, name string, force bool) (map[string]any, error) {
|
||||
key := "licence:" + name
|
||||
ok, err := m.Store.Lease(ctx, key, m.Holder, leaseFor)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if !ok {
|
||||
return map[string]any{"licence": name, "refreshed": false, "reason": "another run holds its lease"}, nil
|
||||
}
|
||||
defer func() { _ = m.Store.Unlease(ctx, key, m.Holder) }()
|
||||
l, err := m.Store.Licence(ctx, name)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if l == nil {
|
||||
return map[string]any{"licence": name, "refreshed": false, "reason": "no such licence"}, nil
|
||||
}
|
||||
if l.Kind != "subscription" || l.Sealed == "" {
|
||||
return map[string]any{"licence": name, "refreshed": false, "reason": "an API key does not refresh"}, nil
|
||||
}
|
||||
now := m.Now()
|
||||
if !force && !Due(*l, now, m.Settings) {
|
||||
return map[string]any{"licence": name, "refreshed": false, "reason": "not due"}, nil
|
||||
}
|
||||
plain, err := m.Crypt.Open(l.Sealed)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
var g FullGrant
|
||||
if err := json.Unmarshal([]byte(plain), &g); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
r := m.Vendor.Refresh(ctx, g)
|
||||
if !r.OK {
|
||||
l.Failures++
|
||||
m.Log("%s did not refresh (%d in a row): %d %s", name, l.Failures, r.Status, r.Reason)
|
||||
_ = m.Store.Audit(ctx, "failed", map[string]any{"licence": name, "status": r.Status, "reason": r.Reason, "failures": l.Failures})
|
||||
m.notify(l, fmt.Sprintf("refresh failed %d time(s) in a row: %d", l.Failures, r.Status), l.Failures >= m.Settings.FailuresToNotify)
|
||||
if err := m.Store.SaveLicence(ctx, *l); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return map[string]any{"licence": name, "refreshed": false, "reason": fmt.Sprintf("%d %s", r.Status, r.Reason), "failures": l.Failures}, nil
|
||||
}
|
||||
m.keep(l, r.Grant)
|
||||
if l.RefreshExpiresAt != 0 {
|
||||
left := time.Duration(l.RefreshExpiresAt-now.UnixMilli()) * time.Millisecond
|
||||
m.notify(l, fmt.Sprintf("its refresh token expires in %.1f day(s): a person must log in again", left.Hours()/24),
|
||||
left < m.Settings.RefreshWarn)
|
||||
}
|
||||
if err := m.Store.SaveLicence(ctx, *l); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
_ = m.Store.Audit(ctx, "rotated", map[string]any{"licence": name, "expiresAt": l.AccessExpiresAt})
|
||||
if err := m.publishAdvance(ctx, *l); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return map[string]any{"licence": name, "refreshed": true, "expiresAt": time.UnixMilli(l.AccessExpiresAt).UTC().Format(time.RFC3339)}, nil
|
||||
}
|
||||
|
||||
// notify emits `licence.failing` at most once per cooldown (design 39 §3); it carries no secret.
|
||||
func (m *Manager) notify(l *Licence, why string, when bool) {
|
||||
if !when {
|
||||
return
|
||||
}
|
||||
now := m.Now().UnixMilli()
|
||||
if l.NotifiedAt != 0 && now-l.NotifiedAt < m.Settings.Cooldown.Milliseconds() {
|
||||
return
|
||||
}
|
||||
l.NotifiedAt = now
|
||||
_ = m.Emit("licence.failing", map[string]any{"licence": l.Name, "why": why})
|
||||
}
|
||||
|
||||
// RotateDue refreshes every licence that is due.
|
||||
func (m *Manager) RotateDue(ctx context.Context) ([]map[string]any, error) {
|
||||
all, err := m.Store.Licences(ctx)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
var out []map[string]any
|
||||
for _, l := range all {
|
||||
if Due(l, m.Now(), m.Settings) {
|
||||
r, err := m.Rotate(ctx, l.Name, false)
|
||||
if err != nil {
|
||||
return out, err
|
||||
}
|
||||
out = append(out, r)
|
||||
}
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// ReadUsage reads and records each subscription's usage (ADR 0054); the event names the licence and numbers.
|
||||
func (m *Manager) ReadUsage(ctx context.Context) error {
|
||||
all, err := m.Store.Licences(ctx)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
for _, l := range all {
|
||||
if l.Kind != "subscription" || l.Sealed == "" {
|
||||
continue
|
||||
}
|
||||
plain, err := m.Crypt.Open(l.Sealed)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
var g FullGrant
|
||||
_ = json.Unmarshal([]byte(plain), &g)
|
||||
raw, err := m.Vendor.Usage(ctx, g.AccessToken)
|
||||
if err != nil || raw == nil {
|
||||
continue
|
||||
}
|
||||
reading := FlattenUsage(raw)
|
||||
if err := m.Store.RecordUsage(ctx, l.Name, m.Now().UnixMilli(), reading, raw); err != nil {
|
||||
return err
|
||||
}
|
||||
_ = m.Emit("usage.read", map[string]any{"licence": l.Name, "sessionPct": reading.SessionPct,
|
||||
"weeklyPct": reading.WeeklyPct, "sonnetPct": reading.SonnetPct})
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// ---- the seat's verbs --------------------------------------------------------------------------------
|
||||
|
||||
// Current is a consumer's token sealed to the key it sent (ADR 0206 §6): for a subscription the access
|
||||
// token and its expiries only — never the refresh token, which no node holds. Nil when it is bound to
|
||||
// nothing.
|
||||
func (m *Manager) Current(ctx context.Context, consumer, publicKey string) (map[string]any, error) {
|
||||
if !strings.Contains(publicKey, "PUBLIC KEY") {
|
||||
return nil, errors.New("current seals to the consumer's public key, and none was given")
|
||||
}
|
||||
b, err := m.Store.Binding(ctx, consumer)
|
||||
if err != nil || b == nil {
|
||||
return nil, err
|
||||
}
|
||||
l, err := m.Store.Licence(ctx, b.Licence)
|
||||
if err != nil || l == nil || l.Sealed == "" {
|
||||
return nil, err
|
||||
}
|
||||
plain, err := m.Crypt.Open(l.Sealed)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
handed := plain
|
||||
if l.Kind == "subscription" {
|
||||
var g FullGrant
|
||||
if err := json.Unmarshal([]byte(plain), &g); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
access, _ := json.Marshal(map[string]any{"accessToken": g.AccessToken, "expiresAt": g.ExpiresAt,
|
||||
"refreshTokenExpiresAt": g.RefreshTokenExpiresAt, "scopes": g.Scopes,
|
||||
"subscriptionType": g.SubscriptionType, "rateLimitTier": g.RateLimitTier})
|
||||
handed = string(access)
|
||||
}
|
||||
box, err := Seal(handed, publicKey)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
out := map[string]any{"licence": l.Name, "kind": l.Kind, "generation": b.Generation, "sealed": box}
|
||||
if l.AccountUUID != "" {
|
||||
out["identity"] = Identity{AccountUUID: l.AccountUUID, EmailAddress: l.Email, OrganizationUUID: l.OrganizationUUID}
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// Bind binds or switches a consumer: a person's act (ADR 0183), told to the consumer as a new generation.
|
||||
func (m *Manager) Bind(ctx context.Context, consumer, licence, by string) (map[string]any, error) {
|
||||
l, err := m.Store.Licence(ctx, licence)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if l == nil {
|
||||
return nil, fmt.Errorf("there is no licence %s; `licences` lists them", licence)
|
||||
}
|
||||
before, err := m.Store.Binding(ctx, consumer)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
b, err := m.Store.Bind(ctx, consumer, licence)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
from, what := "", "bound"
|
||||
if before != nil {
|
||||
from, what = before.Licence, "switched"
|
||||
}
|
||||
_ = m.Store.Audit(ctx, what, map[string]any{"consumer": consumer, "licence": licence, "from": from, "by": by})
|
||||
if err := m.PutBinding(ctx, consumer, BindingState{Licence: licence, Kind: l.Kind, Generation: b.Generation}); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return map[string]any{"consumer": consumer, "licence": licence, "generation": b.Generation, "from": from}, nil
|
||||
}
|
||||
|
||||
// Release unbinds a consumer; its node keeps its last token, which expires within hours.
|
||||
func (m *Manager) Release(ctx context.Context, consumer, by string) (map[string]any, error) {
|
||||
was, err := m.Store.Binding(ctx, consumer)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if ok, err := m.Store.Unbind(ctx, consumer); err != nil || !ok {
|
||||
return map[string]any{"consumer": consumer, "released": false, "reason": "it was bound to nothing"}, err
|
||||
}
|
||||
if err := m.DeleteBinding(ctx, consumer); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
_ = m.Store.Audit(ctx, "released", map[string]any{"consumer": consumer, "licence": was.Licence, "by": by})
|
||||
return map[string]any{"consumer": consumer, "released": true, "was": was.Licence}, nil
|
||||
}
|
||||
|
||||
var licenceName = regexp.MustCompile(`^[A-Za-z0-9@._-]+$`)
|
||||
|
||||
// AdoptKey adopts an API key from a file on this node — never an argument (design 39 §6).
|
||||
func (m *Manager) AdoptKey(ctx context.Context, name, file string) (map[string]any, error) {
|
||||
if !licenceName.MatchString(name) {
|
||||
return nil, fmt.Errorf("%q is not a licence name: letters, digits and @._-", name)
|
||||
}
|
||||
raw, err := os.ReadFile(file)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
key := strings.TrimSpace(string(raw))
|
||||
if key == "" {
|
||||
return nil, fmt.Errorf("%s is empty", file)
|
||||
}
|
||||
held, err := m.Store.Licence(ctx, name)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if held != nil && held.Kind != "api-key" {
|
||||
return nil, fmt.Errorf("%s is a subscription; an API key needs a name of its own", name)
|
||||
}
|
||||
l := Licence{Name: name, Kind: "api-key", Sealed: m.Crypt.Seal(key), AdoptedAt: m.Now().UnixMilli()}
|
||||
if err := m.Store.SaveLicence(ctx, l); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
_ = m.Store.Audit(ctx, "adopted", map[string]any{"licence": name, "kind": "api-key", "from": "a file"})
|
||||
if err := m.publishAdvance(ctx, l); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
_ = m.Emit("licence.adopted", map[string]any{"licence": name, "from": "a file", "replaced": held != nil})
|
||||
return map[string]any{"licence": name, "kind": "api-key", "adopted": true, "fingerprint": Fingerprint(key)}, nil
|
||||
}
|
||||
|
||||
// Licences is each licence as a person reads it: health and who is bound, never a token.
|
||||
func (m *Manager) Licences(ctx context.Context) ([]map[string]any, error) {
|
||||
all, err := m.Store.Licences(ctx)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
bindings, err := m.Store.Bindings(ctx)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
stamp := func(ms int64) any {
|
||||
if ms == 0 {
|
||||
return nil
|
||||
}
|
||||
return time.UnixMilli(ms).UTC().Format(time.RFC3339)
|
||||
}
|
||||
out := []map[string]any{}
|
||||
for _, l := range all {
|
||||
bound := []string{}
|
||||
for _, b := range bindings {
|
||||
if b.Licence == l.Name {
|
||||
bound = append(bound, b.Consumer)
|
||||
}
|
||||
}
|
||||
account := l.Email
|
||||
if account == "" {
|
||||
account = l.AccountUUID
|
||||
}
|
||||
out = append(out, map[string]any{"name": l.Name, "kind": l.Kind, "account": account,
|
||||
"accessExpiresAt": stamp(l.AccessExpiresAt), "refreshExpiresAt": stamp(l.RefreshExpiresAt),
|
||||
"rotatedAt": stamp(l.RotatedAt), "failures": l.Failures, "bound": bound})
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
@@ -1,359 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"sync"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
var t0 = time.Date(2026, 10, 4, 12, 0, 0, 0, time.UTC)
|
||||
|
||||
// stubVendor rotates like the real one is presumed to: each refresh token exchanges once.
|
||||
type stubVendor struct {
|
||||
mu sync.Mutex
|
||||
live map[string]bool
|
||||
exchanged []string
|
||||
issued int
|
||||
account string
|
||||
now func() time.Time
|
||||
}
|
||||
|
||||
func (v *stubVendor) Refresh(_ context.Context, g FullGrant) Refreshed {
|
||||
v.mu.Lock()
|
||||
defer v.mu.Unlock()
|
||||
v.exchanged = append(v.exchanged, g.RefreshToken)
|
||||
if !v.live[g.RefreshToken] {
|
||||
return Refreshed{Status: 400, Reason: `{"error":"invalid_grant"}`}
|
||||
}
|
||||
delete(v.live, g.RefreshToken)
|
||||
v.issued++
|
||||
next := fmt.Sprintf("rt-%d", v.issued)
|
||||
v.live[next] = true
|
||||
g.AccessToken = fmt.Sprintf("at-%d", v.issued)
|
||||
g.RefreshToken = next
|
||||
g.ExpiresAt = v.now().Add(8 * time.Hour).UnixMilli()
|
||||
exp := v.now().Add(30 * 24 * time.Hour).UnixMilli()
|
||||
g.RefreshTokenExpiresAt = &exp
|
||||
return Refreshed{OK: true, Grant: g, Account: v.account}
|
||||
}
|
||||
|
||||
func (v *stubVendor) Usage(context.Context, string) (map[string]any, error) {
|
||||
return map[string]any{"five_hour": map[string]any{"utilization": 12.0}}, nil
|
||||
}
|
||||
|
||||
type miniMesh struct {
|
||||
m *Manager
|
||||
store *MemoryStore
|
||||
vendor *stubVendor
|
||||
logins map[string]FullGrant // node → what its credentials file holds
|
||||
state map[string]BindingState
|
||||
events []string
|
||||
now time.Time
|
||||
keys KeyPair
|
||||
askDown bool
|
||||
}
|
||||
|
||||
func newMesh(t *testing.T) *miniMesh {
|
||||
t.Helper()
|
||||
mm := &miniMesh{logins: map[string]FullGrant{}, state: map[string]BindingState{}, now: t0}
|
||||
now := func() time.Time { return mm.now }
|
||||
mm.store = NewMemoryStore(now)
|
||||
mm.vendor = &stubVendor{live: map[string]bool{}, now: now}
|
||||
crypt, _ := NewCrypt("a key the vault made")
|
||||
mm.keys, _ = GenerateKeyPair()
|
||||
mm.m = &Manager{
|
||||
Store: mm.store, Vendor: mm.vendor, Crypt: crypt, Keys: mm.keys,
|
||||
AskGrant: func(_ context.Context, node, publicKey string) (GrantAnswer, error) {
|
||||
if mm.askDown {
|
||||
return GrantAnswer{}, fmt.Errorf("503 no responders")
|
||||
}
|
||||
g, ok := mm.logins[node]
|
||||
if !ok {
|
||||
return GrantAnswer{}, nil
|
||||
}
|
||||
raw, _ := json.Marshal(g)
|
||||
box, err := Seal(string(raw), publicKey)
|
||||
return GrantAnswer{Sealed: &box, Fingerprint: Fingerprint(g.RefreshToken)}, err
|
||||
},
|
||||
PutBinding: func(_ context.Context, c string, b BindingState) error { mm.state[c] = b; return nil },
|
||||
DeleteBinding: func(_ context.Context, c string) error { delete(mm.state, c); return nil },
|
||||
Emit: func(event string, body map[string]any) error {
|
||||
raw, _ := json.Marshal(body)
|
||||
mm.events = append(mm.events, event+" "+string(raw))
|
||||
return nil
|
||||
},
|
||||
Now: now, Log: func(string, ...any) {}, Holder: "test", Settings: Defaults,
|
||||
}
|
||||
return mm
|
||||
}
|
||||
|
||||
func (mm *miniMesh) report(node, rt string, at time.Time, account string) Holdings {
|
||||
h := Holdings{Node: node, Identity: &Identity{AccountUUID: account, EmailAddress: account + "@example.org"},
|
||||
Kind: "subscription", ChangedAt: at.Format(time.RFC3339Nano)}
|
||||
if rt != "" {
|
||||
h.Refresh.Present, h.Refresh.Fingerprint = true, Fingerprint(rt)
|
||||
}
|
||||
return h
|
||||
}
|
||||
|
||||
func (mm *miniMesh) login(node, rt string, valid bool, at time.Time) Holdings {
|
||||
mm.logins[node] = FullGrant{AccessToken: "local-" + node, RefreshToken: rt, ExpiresAt: mm.now.Add(time.Hour).UnixMilli()}
|
||||
if valid {
|
||||
mm.vendor.live[rt] = true
|
||||
}
|
||||
return mm.report(node, rt, at, "acct-1")
|
||||
}
|
||||
|
||||
const licence1 = "acct-1@example.org"
|
||||
|
||||
func TestAManagerWithNoLicenceAdoptsTheNewestLoginThatRefreshesAndNeverExchangesTheRest(t *testing.T) {
|
||||
mm := newMesh(t)
|
||||
ctx := context.Background()
|
||||
older := mm.login("server", "rt-server", true, t0.Add(-time.Hour))
|
||||
newest := mm.login("laptop", "rt-laptop", true, t0.Add(-time.Minute))
|
||||
adopted, err := mm.m.Consider(ctx, []Holdings{older, newest})
|
||||
if err != nil || len(adopted) != 1 || adopted[0] != licence1 {
|
||||
t.Fatalf("adopted %v, %v", adopted, err)
|
||||
}
|
||||
if strings.Join(mm.vendor.exchanged, ",") != "rt-laptop" {
|
||||
t.Fatalf("exchanged %v: an older login was exchanged although a newer one refreshed", mm.vendor.exchanged)
|
||||
}
|
||||
if o, _ := mm.store.Outcome(ctx, Fingerprint("rt-server")); o != Skipped {
|
||||
t.Fatalf("the older login is %q, not skipped", o)
|
||||
}
|
||||
// A first binding follows the login: both nodes reported this account and were bound to nothing.
|
||||
bs, _ := mm.store.Bindings(ctx)
|
||||
if len(bs) != 2 || mm.state["laptop"].Licence != licence1 || mm.state["server"].Licence != licence1 {
|
||||
t.Fatalf("bindings %v, state %v", bs, mm.state)
|
||||
}
|
||||
if !strings.HasPrefix(strings.Join(mm.events, "|"), "licence.adopted") {
|
||||
t.Fatalf("events %v", mm.events)
|
||||
}
|
||||
}
|
||||
|
||||
func TestALoginThatDoesNotRefreshAdoptsNothingAndIsNotTriedAgain(t *testing.T) {
|
||||
mm := newMesh(t)
|
||||
ctx := context.Background()
|
||||
dead := mm.login("laptop", "rt-dead", false, t0)
|
||||
if adopted, _ := mm.m.Consider(ctx, []Holdings{dead}); len(adopted) != 0 {
|
||||
t.Fatalf("adopted %v", adopted)
|
||||
}
|
||||
if o, _ := mm.store.Outcome(ctx, Fingerprint("rt-dead")); o != Dead {
|
||||
t.Fatalf("outcome %q", o)
|
||||
}
|
||||
if ls, _ := mm.store.Licences(ctx); len(ls) != 0 {
|
||||
t.Fatalf("licences %v", ls)
|
||||
}
|
||||
if !strings.Contains(strings.Join(mm.events, "|"), "licence.refused") {
|
||||
t.Fatalf("events %v", mm.events)
|
||||
}
|
||||
_, _ = mm.m.Consider(ctx, []Holdings{dead})
|
||||
if len(mm.vendor.exchanged) != 1 {
|
||||
t.Fatalf("a dead refresh token was exchanged %d times", len(mm.vendor.exchanged))
|
||||
}
|
||||
}
|
||||
|
||||
func TestANewerLoginReplacesTheGrantHeldAndAnOlderOneDoesNot(t *testing.T) {
|
||||
mm := newMesh(t)
|
||||
ctx := context.Background()
|
||||
_, _ = mm.m.Consider(ctx, []Holdings{mm.login("laptop", "rt-a", true, t0.Add(-time.Minute))})
|
||||
before, _ := mm.store.Licence(ctx, licence1)
|
||||
_, _ = mm.m.Consider(ctx, []Holdings{mm.login("server", "rt-old", true, t0.Add(-24*time.Hour))})
|
||||
if strings.Join(mm.vendor.exchanged, ",") != "rt-a" {
|
||||
t.Fatalf("an older login was exchanged: %v", mm.vendor.exchanged)
|
||||
}
|
||||
mm.now = t0.Add(10 * time.Minute)
|
||||
_, _ = mm.m.Consider(ctx, []Holdings{mm.login("desktop", "rt-new", true, t0.Add(10*time.Minute))})
|
||||
after, _ := mm.store.Licence(ctx, licence1)
|
||||
if after.RefreshFingerprint == before.RefreshFingerprint || mm.vendor.exchanged[len(mm.vendor.exchanged)-1] != "rt-new" {
|
||||
t.Fatalf("a newer login did not win: %v", mm.vendor.exchanged)
|
||||
}
|
||||
if ls, _ := mm.store.Licences(ctx); len(ls) != 1 {
|
||||
t.Fatalf("one account became %d licences", len(ls))
|
||||
}
|
||||
}
|
||||
|
||||
func TestAReportNamingAnotherAccountThanTheVendorAnsweredForIsRefused(t *testing.T) {
|
||||
mm := newMesh(t)
|
||||
ctx := context.Background()
|
||||
mm.vendor.account = "someone-else"
|
||||
if adopted, _ := mm.m.Consider(ctx, []Holdings{mm.login("laptop", "rt-a", true, t0)}); len(adopted) != 0 {
|
||||
t.Fatalf("adopted %v", adopted)
|
||||
}
|
||||
if o, _ := mm.store.Outcome(ctx, Fingerprint("rt-a")); o != Refused {
|
||||
t.Fatalf("outcome %q", o)
|
||||
}
|
||||
}
|
||||
|
||||
func TestTwoRefreshRunsStartedTogetherRotateAGrantOnce(t *testing.T) {
|
||||
mm := newMesh(t)
|
||||
ctx := context.Background()
|
||||
_, _ = mm.m.Consider(ctx, []Holdings{mm.login("laptop", "rt-a", true, t0)})
|
||||
mm.now = t0.Add(5 * time.Hour)
|
||||
second := *mm.m
|
||||
second.Holder = "another run"
|
||||
var wg sync.WaitGroup
|
||||
results := make([]map[string]any, 2)
|
||||
for i, m := range []*Manager{mm.m, &second} {
|
||||
wg.Add(1)
|
||||
go func() { defer wg.Done(); results[i], _ = m.Rotate(ctx, licence1, false) }()
|
||||
}
|
||||
wg.Wait()
|
||||
n := 0
|
||||
for _, r := range results {
|
||||
if r["refreshed"] == true {
|
||||
n++
|
||||
}
|
||||
}
|
||||
if n != 1 {
|
||||
t.Fatalf("rotated %d times: %v", n, results)
|
||||
}
|
||||
if r, _ := second.Rotate(ctx, licence1, false); r["reason"] != "not due" {
|
||||
t.Fatalf("a run just after was %v", r)
|
||||
}
|
||||
}
|
||||
|
||||
func TestARotationAndASwitchEachGiveANewerGeneration(t *testing.T) {
|
||||
mm := newMesh(t)
|
||||
ctx := context.Background()
|
||||
_, _ = mm.m.Consider(ctx, []Holdings{mm.login("laptop", "rt-a", true, t0)})
|
||||
g0 := mm.state["laptop"].Generation
|
||||
_, _ = mm.m.Rotate(ctx, licence1, true)
|
||||
g1 := mm.state["laptop"].Generation
|
||||
if g1 <= g0 {
|
||||
t.Fatalf("a rotation went from %d to %d", g0, g1)
|
||||
}
|
||||
file := filepath.Join(t.TempDir(), "key")
|
||||
_ = os.WriteFile(file, []byte("sk-ant-api-key\n"), 0o600)
|
||||
if _, err := mm.m.AdoptKey(ctx, "api", file); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if _, err := mm.m.Bind(ctx, "laptop", "api", "test"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if mm.state["laptop"].Licence != "api" || mm.state["laptop"].Generation <= g1 {
|
||||
t.Fatalf("a switch to a licence rotated less often went backwards: %v", mm.state["laptop"])
|
||||
}
|
||||
if _, err := mm.m.Release(ctx, "laptop", "test"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if _, ok := mm.state["laptop"]; ok {
|
||||
t.Fatal("a released consumer still has a binding in the state")
|
||||
}
|
||||
}
|
||||
|
||||
func TestCurrentHandsAnAccessTokenOnlySealedToTheConsumersKey(t *testing.T) {
|
||||
mm := newMesh(t)
|
||||
ctx := context.Background()
|
||||
_, _ = mm.m.Consider(ctx, []Holdings{mm.login("laptop", "rt-a", true, t0)})
|
||||
node, _ := GenerateKeyPair()
|
||||
answer, err := mm.m.Current(ctx, "laptop", node.PublicKey)
|
||||
if err != nil || answer["kind"] != "subscription" {
|
||||
t.Fatalf("%v %v", answer, err)
|
||||
}
|
||||
box := answer["sealed"].(SealedBox)
|
||||
plain, err := Open(box, node.PrivateKey)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var handed map[string]any
|
||||
_ = json.Unmarshal([]byte(plain), &handed)
|
||||
if !strings.HasPrefix(handed["accessToken"].(string), "at-") || handed["refreshToken"] != nil {
|
||||
t.Fatalf("handed %v", handed)
|
||||
}
|
||||
other, _ := GenerateKeyPair()
|
||||
if _, err := Open(box, other.PrivateKey); err == nil {
|
||||
t.Fatal("the hand-over opened with another key")
|
||||
}
|
||||
if a, _ := mm.m.Current(ctx, "nobody", node.PublicKey); a != nil {
|
||||
t.Fatalf("a consumer bound to nothing was answered %v", a)
|
||||
}
|
||||
}
|
||||
|
||||
func TestNothingTheManagerPublishesKeepsOrListsCarriesAToken(t *testing.T) {
|
||||
mm := newMesh(t)
|
||||
ctx := context.Background()
|
||||
_, _ = mm.m.Consider(ctx, []Holdings{mm.login("laptop", "rt-secret-1", true, t0)})
|
||||
_, _ = mm.m.Rotate(ctx, licence1, true)
|
||||
_, _ = mm.m.Consider(ctx, []Holdings{mm.login("server", "rt-secret-dead", false, t0.Add(time.Hour))})
|
||||
_ = mm.m.ReadUsage(ctx)
|
||||
ls, _ := mm.m.Licences(ctx)
|
||||
bs, _ := mm.store.Bindings(ctx)
|
||||
everything, _ := json.Marshal([]any{mm.events, mm.state, ls, bs})
|
||||
for _, token := range []string{"rt-secret", "rt-1", "rt-2", "at-1", "at-2", "local-"} {
|
||||
if strings.Contains(string(everything), token) {
|
||||
t.Fatalf("%s was published: %s", token, everything)
|
||||
}
|
||||
}
|
||||
row, _ := mm.store.Licence(ctx, licence1)
|
||||
if strings.Contains(row.Sealed, "rt-") {
|
||||
t.Fatal("the grant is stored in the clear")
|
||||
}
|
||||
}
|
||||
|
||||
func TestANodeThatDoesNotAnswerIsAskedAgainAndOneWithNoLoginIsSettled(t *testing.T) {
|
||||
mm := newMesh(t)
|
||||
ctx := context.Background()
|
||||
r := mm.login("laptop", "rt-a", true, t0)
|
||||
mm.askDown = true
|
||||
if adopted, _ := mm.m.Consider(ctx, []Holdings{r}); len(adopted) != 0 {
|
||||
t.Fatalf("adopted %v from a node that did not answer", adopted)
|
||||
}
|
||||
if o, _ := mm.store.Outcome(ctx, Fingerprint("rt-a")); o != "" {
|
||||
t.Fatalf("a node that was down was settled %q", o)
|
||||
}
|
||||
mm.askDown = false
|
||||
if adopted, _ := mm.m.Consider(ctx, []Holdings{r}); len(adopted) != 1 {
|
||||
t.Fatalf("adopted %v on the next pass", adopted)
|
||||
}
|
||||
gone := mm.report("server", "rt-gone", t0.Add(time.Second), "acct-2")
|
||||
_, _ = mm.m.Consider(ctx, []Holdings{gone})
|
||||
if o, _ := mm.store.Outcome(ctx, Fingerprint("rt-gone")); o != Gone {
|
||||
t.Fatalf("outcome %q", o)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAReportIsReadAsTheAgentModuleWritesIt(t *testing.T) {
|
||||
// The agent module's own report shape (claude-code's holdingsOf), parsed here.
|
||||
raw := `{"node":"laptop","identity":{"accountUuid":"u-1","emailAddress":"a@example.org"},"kind":"subscription",
|
||||
"refresh":{"present":true,"fingerprint":"sha256:0123456789abcdef","expiresAt":null},
|
||||
"access":{"fingerprint":"sha256:fedcba9876543210","expiresAt":1},"licence":null,"generation":0,
|
||||
"changedAt":"2026-10-04T11:00:00.000Z"}`
|
||||
var h Holdings
|
||||
if err := json.Unmarshal([]byte(raw), &h); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if h.Node != "laptop" || h.Identity.AccountUUID != "u-1" || !h.Refresh.Present || h.Refresh.Fingerprint != "sha256:0123456789abcdef" {
|
||||
t.Fatalf("%+v", h)
|
||||
}
|
||||
if _, err := time.Parse(time.RFC3339Nano, h.ChangedAt); err != nil {
|
||||
t.Fatalf("the report's time does not parse: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// A node whose report arrives after its account was adopted — with an older login, so never a candidate —
|
||||
// is still bound to that account's licence, once.
|
||||
func TestANodeReportingAnAdoptedAccountLaterIsBoundToIt(t *testing.T) {
|
||||
mm := newMesh(t)
|
||||
ctx := context.Background()
|
||||
_, _ = mm.m.Consider(ctx, []Holdings{mm.login("novox", "rt-new", true, t0)})
|
||||
late := mm.login("laptop", "rt-older", true, t0.Add(-24*time.Hour))
|
||||
_, _ = mm.m.Consider(ctx, []Holdings{late})
|
||||
if mm.state["laptop"].Licence != licence1 {
|
||||
t.Fatalf("a node reporting the adopted account later was not bound: %v", mm.state)
|
||||
}
|
||||
if strings.Contains(strings.Join(mm.vendor.exchanged, ","), "rt-older") {
|
||||
t.Fatal("the older login was exchanged")
|
||||
}
|
||||
g := mm.state["laptop"].Generation
|
||||
_, _ = mm.m.Consider(ctx, []Holdings{late})
|
||||
if mm.state["laptop"].Generation != g {
|
||||
t.Fatal("a node already bound was bound again")
|
||||
}
|
||||
}
|
||||
@@ -1,281 +0,0 @@
|
||||
package main
|
||||
|
||||
// The store on the mesh's postgres (novox/hq design 39 §1), the database the mesh provisioned for this
|
||||
// module. The schema is brought to this version's shape by the preparation step (ADR 0135), each
|
||||
// statement idempotent.
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"os"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/jackc/pgx/v5"
|
||||
"github.com/jackc/pgx/v5/pgxpool"
|
||||
)
|
||||
|
||||
// Schema is what this version needs.
|
||||
var Schema = []string{
|
||||
`create table if not exists licence (
|
||||
name text primary key,
|
||||
kind text not null check (kind in ('subscription', 'api-key')),
|
||||
account_uuid text unique,
|
||||
email text,
|
||||
organization_uuid text,
|
||||
sealed text,
|
||||
refresh_fingerprint text,
|
||||
access_expires_at bigint,
|
||||
refresh_expires_at bigint,
|
||||
failures integer not null default 0,
|
||||
notified_at bigint,
|
||||
adopted_at bigint not null,
|
||||
rotated_at bigint)`,
|
||||
`create sequence if not exists binding_generation`,
|
||||
`create table if not exists binding (
|
||||
consumer text primary key,
|
||||
licence text not null references licence(name),
|
||||
generation bigint not null)`,
|
||||
`create table if not exists lease (
|
||||
key text primary key,
|
||||
holder text not null,
|
||||
until timestamptz not null)`,
|
||||
`create table if not exists offered (
|
||||
fingerprint text primary key,
|
||||
node text not null,
|
||||
account_uuid text,
|
||||
outcome text not null,
|
||||
why text not null,
|
||||
at timestamptz not null default now())`,
|
||||
`create table if not exists usage (
|
||||
licence text not null,
|
||||
at bigint not null,
|
||||
reading jsonb not null,
|
||||
raw jsonb not null)`,
|
||||
`create index if not exists usage_by_licence on usage (licence, at desc)`,
|
||||
`create table if not exists audit (
|
||||
at timestamptz not null default now(),
|
||||
what text not null,
|
||||
detail jsonb not null)`,
|
||||
}
|
||||
|
||||
// PgStore is the store on postgres.
|
||||
type PgStore struct{ pool *pgxpool.Pool }
|
||||
|
||||
// PgStoreFromEnv opens the store the mesh provisioned, its URL in the file DATABASE_URL_FILE names.
|
||||
func PgStoreFromEnv(ctx context.Context) (*PgStore, error) {
|
||||
file := os.Getenv("DATABASE_URL_FILE")
|
||||
if file == "" {
|
||||
return nil, errors.New("DATABASE_URL_FILE is not set: the manager's database is a requirement the mesh resolves")
|
||||
}
|
||||
raw, err := os.ReadFile(file)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return OpenPgStore(ctx, strings.TrimSpace(string(raw)))
|
||||
}
|
||||
|
||||
// OpenPgStore opens a store at a URL.
|
||||
func OpenPgStore(ctx context.Context, url string) (*PgStore, error) {
|
||||
pool, err := pgxpool.New(ctx, url)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &PgStore{pool: pool}, nil
|
||||
}
|
||||
|
||||
// Migrate brings the schema to this version's shape.
|
||||
func (s *PgStore) Migrate(ctx context.Context) error {
|
||||
for _, q := range Schema {
|
||||
if _, err := s.pool.Exec(ctx, q); err != nil {
|
||||
return fmt.Errorf("%s: %w", strings.Fields(q)[0:6], err)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
const licenceColumns = `name, kind, coalesce(account_uuid,''), coalesce(email,''), coalesce(organization_uuid,''),
|
||||
coalesce(sealed,''), coalesce(refresh_fingerprint,''), coalesce(access_expires_at,0), coalesce(refresh_expires_at,0),
|
||||
failures, coalesce(notified_at,0), adopted_at, coalesce(rotated_at,0)`
|
||||
|
||||
func scanLicence(row pgx.Row) (*Licence, error) {
|
||||
var l Licence
|
||||
err := row.Scan(&l.Name, &l.Kind, &l.AccountUUID, &l.Email, &l.OrganizationUUID, &l.Sealed, &l.RefreshFingerprint,
|
||||
&l.AccessExpiresAt, &l.RefreshExpiresAt, &l.Failures, &l.NotifiedAt, &l.AdoptedAt, &l.RotatedAt)
|
||||
if errors.Is(err, pgx.ErrNoRows) {
|
||||
return nil, nil
|
||||
}
|
||||
return &l, err
|
||||
}
|
||||
|
||||
func (s *PgStore) Licences(ctx context.Context) ([]Licence, error) {
|
||||
rows, err := s.pool.Query(ctx, `select `+licenceColumns+` from licence order by name`)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
defer rows.Close()
|
||||
var out []Licence
|
||||
for rows.Next() {
|
||||
l, err := scanLicence(rows)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
out = append(out, *l)
|
||||
}
|
||||
return out, rows.Err()
|
||||
}
|
||||
|
||||
func (s *PgStore) Licence(ctx context.Context, name string) (*Licence, error) {
|
||||
return scanLicence(s.pool.QueryRow(ctx, `select `+licenceColumns+` from licence where name = $1`, name))
|
||||
}
|
||||
|
||||
func (s *PgStore) LicenceForAccount(ctx context.Context, account string) (*Licence, error) {
|
||||
return scanLicence(s.pool.QueryRow(ctx, `select `+licenceColumns+` from licence where account_uuid = $1`, account))
|
||||
}
|
||||
|
||||
func nullable(s string) any {
|
||||
if s == "" {
|
||||
return nil
|
||||
}
|
||||
return s
|
||||
}
|
||||
|
||||
func nullableInt(v int64) any {
|
||||
if v == 0 {
|
||||
return nil
|
||||
}
|
||||
return v
|
||||
}
|
||||
|
||||
func (s *PgStore) SaveLicence(ctx context.Context, l Licence) error {
|
||||
_, err := s.pool.Exec(ctx, `insert into licence (name, kind, account_uuid, email, organization_uuid, sealed, refresh_fingerprint,
|
||||
access_expires_at, refresh_expires_at, failures, notified_at, adopted_at, rotated_at)
|
||||
values ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13)
|
||||
on conflict (name) do update set kind = excluded.kind, account_uuid = excluded.account_uuid, email = excluded.email,
|
||||
organization_uuid = excluded.organization_uuid, sealed = excluded.sealed, refresh_fingerprint = excluded.refresh_fingerprint,
|
||||
access_expires_at = excluded.access_expires_at, refresh_expires_at = excluded.refresh_expires_at,
|
||||
failures = excluded.failures, notified_at = excluded.notified_at, adopted_at = excluded.adopted_at,
|
||||
rotated_at = excluded.rotated_at`,
|
||||
l.Name, l.Kind, nullable(l.AccountUUID), nullable(l.Email), nullable(l.OrganizationUUID), nullable(l.Sealed),
|
||||
nullable(l.RefreshFingerprint), nullableInt(l.AccessExpiresAt), nullableInt(l.RefreshExpiresAt), l.Failures,
|
||||
nullableInt(l.NotifiedAt), l.AdoptedAt, nullableInt(l.RotatedAt))
|
||||
return err
|
||||
}
|
||||
|
||||
// Lease is taken in the store before a row is read (design 39 §3): a second run started together finds
|
||||
// it live and does nothing.
|
||||
func (s *PgStore) Lease(ctx context.Context, key, holder string, d time.Duration) (bool, error) {
|
||||
tag, err := s.pool.Exec(ctx, `insert into lease (key, holder, until) values ($1, $2, now() + make_interval(secs => $3))
|
||||
on conflict (key) do update set holder = excluded.holder, until = excluded.until
|
||||
where lease.until < now() or lease.holder = excluded.holder`, key, holder, d.Seconds())
|
||||
if err != nil {
|
||||
return false, err
|
||||
}
|
||||
return tag.RowsAffected() == 1, nil
|
||||
}
|
||||
|
||||
func (s *PgStore) Unlease(ctx context.Context, key, holder string) error {
|
||||
_, err := s.pool.Exec(ctx, `delete from lease where key = $1 and holder = $2`, key, holder)
|
||||
return err
|
||||
}
|
||||
|
||||
func (s *PgStore) bindingsWhere(ctx context.Context, q string, args ...any) ([]Binding, error) {
|
||||
rows, err := s.pool.Query(ctx, q, args...)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
defer rows.Close()
|
||||
var out []Binding
|
||||
for rows.Next() {
|
||||
var b Binding
|
||||
if err := rows.Scan(&b.Consumer, &b.Licence, &b.Generation); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
out = append(out, b)
|
||||
}
|
||||
return out, rows.Err()
|
||||
}
|
||||
|
||||
func (s *PgStore) Bindings(ctx context.Context) ([]Binding, error) {
|
||||
return s.bindingsWhere(ctx, `select consumer, licence, generation from binding order by consumer`)
|
||||
}
|
||||
|
||||
func (s *PgStore) Binding(ctx context.Context, consumer string) (*Binding, error) {
|
||||
out, err := s.bindingsWhere(ctx, `select consumer, licence, generation from binding where consumer = $1`, consumer)
|
||||
if err != nil || len(out) == 0 {
|
||||
return nil, err
|
||||
}
|
||||
return &out[0], nil
|
||||
}
|
||||
|
||||
func (s *PgStore) Bind(ctx context.Context, consumer, licence string) (Binding, error) {
|
||||
out, err := s.bindingsWhere(ctx, `insert into binding (consumer, licence, generation) values ($1, $2, nextval('binding_generation'))
|
||||
on conflict (consumer) do update set licence = excluded.licence, generation = excluded.generation
|
||||
returning consumer, licence, generation`, consumer, licence)
|
||||
if err != nil {
|
||||
return Binding{}, err
|
||||
}
|
||||
return out[0], nil
|
||||
}
|
||||
|
||||
func (s *PgStore) Unbind(ctx context.Context, consumer string) (bool, error) {
|
||||
tag, err := s.pool.Exec(ctx, `delete from binding where consumer = $1`, consumer)
|
||||
return err == nil && tag.RowsAffected() == 1, err
|
||||
}
|
||||
|
||||
func (s *PgStore) Advance(ctx context.Context, licence string) ([]Binding, error) {
|
||||
return s.bindingsWhere(ctx, `update binding set generation = nextval('binding_generation') where licence = $1
|
||||
returning consumer, licence, generation`, licence)
|
||||
}
|
||||
|
||||
func (s *PgStore) Outcome(ctx context.Context, fp string) (Outcome, error) {
|
||||
var o string
|
||||
err := s.pool.QueryRow(ctx, `select outcome from offered where fingerprint = $1`, fp).Scan(&o)
|
||||
if errors.Is(err, pgx.ErrNoRows) {
|
||||
return "", nil
|
||||
}
|
||||
return Outcome(o), err
|
||||
}
|
||||
|
||||
func (s *PgStore) RecordOutcome(ctx context.Context, fp, node, account string, o Outcome, why string) error {
|
||||
_, err := s.pool.Exec(ctx, `insert into offered (fingerprint, node, account_uuid, outcome, why) values ($1,$2,$3,$4,$5)
|
||||
on conflict (fingerprint) do update set outcome = excluded.outcome, why = excluded.why, at = now()`,
|
||||
fp, node, nullable(account), string(o), why)
|
||||
return err
|
||||
}
|
||||
|
||||
func (s *PgStore) RecordUsage(ctx context.Context, licence string, at int64, r UsageReading, raw map[string]any) error {
|
||||
reading, _ := json.Marshal(r)
|
||||
rawJSON, _ := json.Marshal(raw)
|
||||
_, err := s.pool.Exec(ctx, `insert into usage (licence, at, reading, raw) values ($1,$2,$3,$4)`, licence, at, reading, rawJSON)
|
||||
return err
|
||||
}
|
||||
|
||||
func (s *PgStore) Usage(ctx context.Context, licence string, limit int) ([]UsageRow, error) {
|
||||
rows, err := s.pool.Query(ctx, `select licence, at, reading from usage where ($1 = '' or licence = $1) order by at desc limit $2`, licence, limit)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
defer rows.Close()
|
||||
var out []UsageRow
|
||||
for rows.Next() {
|
||||
var u UsageRow
|
||||
var reading []byte
|
||||
if err := rows.Scan(&u.Licence, &u.At, &reading); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
_ = json.Unmarshal(reading, &u.Reading)
|
||||
out = append(out, u)
|
||||
}
|
||||
return out, rows.Err()
|
||||
}
|
||||
|
||||
func (s *PgStore) Audit(ctx context.Context, what string, detail map[string]any) error {
|
||||
raw, _ := json.Marshal(detail)
|
||||
_, err := s.pool.Exec(ctx, `insert into audit (what, detail) values ($1, $2)`, what, raw)
|
||||
return err
|
||||
}
|
||||
|
||||
func (s *PgStore) Close() { s.pool.Close() }
|
||||
@@ -1,189 +0,0 @@
|
||||
package main
|
||||
|
||||
// Sealing to one recipient (novox/hq ADR 0183, ADR 0206): the manager seals what it hands a consumer to
|
||||
// the key that consumer sent, and a node seals a waiting login to the key the manager gives. The same box
|
||||
// the agent module's TypeScript makes and opens, byte for byte — X25519 for the agreement, HKDF-SHA256 for
|
||||
// the key, AES-256-GCM for the box — so `testdata/sealed-by-typescript.json` is opened here, and a test
|
||||
// reopens what this seals with the same derivation.
|
||||
//
|
||||
// A box is `{ v: 1, eph, iv, tag, ct }`, every field base64; `eph` is the one-time public key as SPKI DER,
|
||||
// and the key is bound to it and to the recipient's raw public key, so a box cannot be re-addressed.
|
||||
|
||||
import (
|
||||
"crypto/aes"
|
||||
"crypto/cipher"
|
||||
"crypto/ecdh"
|
||||
"crypto/hkdf"
|
||||
"crypto/rand"
|
||||
"crypto/sha256"
|
||||
"crypto/x509"
|
||||
"encoding/base64"
|
||||
"encoding/pem"
|
||||
"errors"
|
||||
"fmt"
|
||||
)
|
||||
|
||||
// SealedBox is a value sealed to one recipient.
|
||||
type SealedBox struct {
|
||||
V int `json:"v"`
|
||||
Eph string `json:"eph"`
|
||||
IV string `json:"iv"`
|
||||
Tag string `json:"tag"`
|
||||
Ct string `json:"ct"`
|
||||
}
|
||||
|
||||
// KeyPair is a recipient's keypair as the two PEM strings it is kept and sent as.
|
||||
type KeyPair struct {
|
||||
PublicKey string `json:"publicKey"`
|
||||
PrivateKey string `json:"privateKey"`
|
||||
}
|
||||
|
||||
const sealInfo = "novox-mesh sealed box v1"
|
||||
|
||||
// GenerateKeyPair makes an X25519 keypair, PEM-encoded as the agent module's are.
|
||||
func GenerateKeyPair() (KeyPair, error) {
|
||||
priv, err := ecdh.X25519().GenerateKey(rand.Reader)
|
||||
if err != nil {
|
||||
return KeyPair{}, err
|
||||
}
|
||||
pubDER, err := x509.MarshalPKIXPublicKey(priv.PublicKey())
|
||||
if err != nil {
|
||||
return KeyPair{}, err
|
||||
}
|
||||
privDER, err := x509.MarshalPKCS8PrivateKey(priv)
|
||||
if err != nil {
|
||||
return KeyPair{}, err
|
||||
}
|
||||
return KeyPair{
|
||||
PublicKey: string(pem.EncodeToMemory(&pem.Block{Type: "PUBLIC KEY", Bytes: pubDER})),
|
||||
PrivateKey: string(pem.EncodeToMemory(&pem.Block{Type: "PRIVATE KEY", Bytes: privDER})),
|
||||
}, nil
|
||||
}
|
||||
|
||||
func publicFromPEM(p string) (*ecdh.PublicKey, error) {
|
||||
block, _ := pem.Decode([]byte(p))
|
||||
if block == nil {
|
||||
return nil, errors.New("not a PEM public key")
|
||||
}
|
||||
k, err := x509.ParsePKIXPublicKey(block.Bytes)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
pub, ok := k.(*ecdh.PublicKey)
|
||||
if !ok || pub.Curve() != ecdh.X25519() {
|
||||
return nil, errors.New("not an X25519 public key")
|
||||
}
|
||||
return pub, nil
|
||||
}
|
||||
|
||||
func privateFromPEM(p string) (*ecdh.PrivateKey, error) {
|
||||
block, _ := pem.Decode([]byte(p))
|
||||
if block == nil {
|
||||
return nil, errors.New("not a PEM private key")
|
||||
}
|
||||
k, err := x509.ParsePKCS8PrivateKey(block.Bytes)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
priv, ok := k.(*ecdh.PrivateKey)
|
||||
if !ok || priv.Curve() != ecdh.X25519() {
|
||||
return nil, errors.New("not an X25519 private key")
|
||||
}
|
||||
return priv, nil
|
||||
}
|
||||
|
||||
func boxKey(secret, ephDER, recipientRaw []byte) ([]byte, error) {
|
||||
salt := append(append([]byte{}, ephDER...), recipientRaw...)
|
||||
return hkdf.Key(sha256.New, secret, salt, sealInfo, 32)
|
||||
}
|
||||
|
||||
// Seal seals plaintext to the recipient's public key.
|
||||
func Seal(plaintext, recipientPEM string) (SealedBox, error) {
|
||||
recipient, err := publicFromPEM(recipientPEM)
|
||||
if err != nil {
|
||||
return SealedBox{}, err
|
||||
}
|
||||
eph, err := ecdh.X25519().GenerateKey(rand.Reader)
|
||||
if err != nil {
|
||||
return SealedBox{}, err
|
||||
}
|
||||
secret, err := eph.ECDH(recipient)
|
||||
if err != nil {
|
||||
return SealedBox{}, err
|
||||
}
|
||||
ephDER, err := x509.MarshalPKIXPublicKey(eph.PublicKey())
|
||||
if err != nil {
|
||||
return SealedBox{}, err
|
||||
}
|
||||
key, err := boxKey(secret, ephDER, recipient.Bytes())
|
||||
if err != nil {
|
||||
return SealedBox{}, err
|
||||
}
|
||||
gcm, err := newGCM(key)
|
||||
if err != nil {
|
||||
return SealedBox{}, err
|
||||
}
|
||||
iv := make([]byte, 12)
|
||||
if _, err := rand.Read(iv); err != nil {
|
||||
return SealedBox{}, err
|
||||
}
|
||||
out := gcm.Seal(nil, iv, []byte(plaintext), nil)
|
||||
ct, tag := out[:len(out)-gcm.Overhead()], out[len(out)-gcm.Overhead():]
|
||||
b64 := base64.StdEncoding.EncodeToString
|
||||
return SealedBox{V: 1, Eph: b64(ephDER), IV: b64(iv), Tag: b64(tag), Ct: b64(ct)}, nil
|
||||
}
|
||||
|
||||
// Open opens a box with the recipient's private key; it fails for a box to another key or one tampered with.
|
||||
func Open(box SealedBox, privatePEM string) (string, error) {
|
||||
if box.V != 1 {
|
||||
return "", errors.New("not a sealed box this module can open")
|
||||
}
|
||||
priv, err := privateFromPEM(privatePEM)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
d := base64.StdEncoding.DecodeString
|
||||
ephDER, err := d(box.Eph)
|
||||
if err != nil {
|
||||
return "", fmt.Errorf("the box's eph: %w", err)
|
||||
}
|
||||
ephKey, err := x509.ParsePKIXPublicKey(ephDER)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
eph, ok := ephKey.(*ecdh.PublicKey)
|
||||
if !ok {
|
||||
return "", errors.New("the box's eph is not an X25519 key")
|
||||
}
|
||||
secret, err := priv.ECDH(eph)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
key, err := boxKey(secret, ephDER, priv.PublicKey().Bytes())
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
iv, err1 := d(box.IV)
|
||||
tag, err2 := d(box.Tag)
|
||||
ct, err3 := d(box.Ct)
|
||||
if err := errors.Join(err1, err2, err3); err != nil {
|
||||
return "", err
|
||||
}
|
||||
gcm, err := newGCM(key)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
plain, err := gcm.Open(nil, iv, append(ct, tag...), nil)
|
||||
if err != nil {
|
||||
return "", errors.New("the box does not open with this key")
|
||||
}
|
||||
return string(plain), nil
|
||||
}
|
||||
|
||||
func newGCM(key []byte) (cipher.AEAD, error) {
|
||||
block, err := aes.NewCipher(key)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return cipher.NewGCM(block)
|
||||
}
|
||||
@@ -1,43 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"os"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// A box the agent module's TypeScript sealed opens here: the two implementations are one format.
|
||||
func TestABoxSealedInTypeScriptOpensInGo(t *testing.T) {
|
||||
raw, err := os.ReadFile("testdata/sealed-by-typescript.json")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var f struct {
|
||||
PrivateKey string `json:"privateKey"`
|
||||
Box SealedBox `json:"box"`
|
||||
Plaintext string `json:"plaintext"`
|
||||
}
|
||||
if err := json.Unmarshal(raw, &f); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
got, err := Open(f.Box, f.PrivateKey)
|
||||
if err != nil || got != f.Plaintext {
|
||||
t.Fatalf("opened %q, %v", got, err)
|
||||
}
|
||||
}
|
||||
|
||||
// What Go seals opens with its own key and no other.
|
||||
func TestABoxOpensOnlyForItsRecipient(t *testing.T) {
|
||||
a, _ := GenerateKeyPair()
|
||||
b, _ := GenerateKeyPair()
|
||||
box, err := Seal("a token", a.PublicKey)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if got, err := Open(box, a.PrivateKey); err != nil || got != "a token" {
|
||||
t.Fatalf("opened %q, %v", got, err)
|
||||
}
|
||||
if _, err := Open(box, b.PrivateKey); err == nil {
|
||||
t.Fatal("a box opened for another key")
|
||||
}
|
||||
}
|
||||
@@ -1,263 +0,0 @@
|
||||
package main
|
||||
|
||||
// The manager's store (novox/hq ADR 0183, design 39 §1): licences with their grants encrypted, bindings
|
||||
// with a generation, what became of each login it was offered, usage readings, and the audit. One
|
||||
// interface, two implementations — postgres for the mesh (pgstore.go), memory for the tests — so every
|
||||
// rule is tested without a database, and the database is asked only to keep rows.
|
||||
|
||||
import (
|
||||
"context"
|
||||
"sort"
|
||||
"sync"
|
||||
"time"
|
||||
)
|
||||
|
||||
// Licence is one licence: an account, or an API key.
|
||||
type Licence struct {
|
||||
Name string `json:"name"`
|
||||
Kind string `json:"kind"` // subscription | api-key
|
||||
AccountUUID string `json:"accountUuid,omitempty"`
|
||||
Email string `json:"email,omitempty"`
|
||||
OrganizationUUID string `json:"organizationUuid,omitempty"`
|
||||
Sealed string `json:"-"` // the grant or the key, encrypted at rest
|
||||
RefreshFingerprint string `json:"-"`
|
||||
AccessExpiresAt int64 `json:"accessExpiresAt,omitempty"`
|
||||
RefreshExpiresAt int64 `json:"refreshExpiresAt,omitempty"`
|
||||
Failures int `json:"failures"`
|
||||
NotifiedAt int64 `json:"-"`
|
||||
AdoptedAt int64 `json:"adoptedAt"`
|
||||
RotatedAt int64 `json:"rotatedAt,omitempty"`
|
||||
}
|
||||
|
||||
// Binding is one consumer's binding and the generation it was last given (ADR 0206).
|
||||
type Binding struct {
|
||||
Consumer string `json:"consumer"`
|
||||
Licence string `json:"licence"`
|
||||
Generation int64 `json:"generation"`
|
||||
}
|
||||
|
||||
// Outcome is what became of a login the manager was offered, by its refresh token's fingerprint.
|
||||
type Outcome string
|
||||
|
||||
const (
|
||||
Adopted Outcome = "adopted"
|
||||
Dead Outcome = "dead"
|
||||
Skipped Outcome = "skipped"
|
||||
Refused Outcome = "refused"
|
||||
Gone Outcome = "gone"
|
||||
)
|
||||
|
||||
// UsageRow is one usage reading.
|
||||
type UsageRow struct {
|
||||
Licence string `json:"licence"`
|
||||
At int64 `json:"at"`
|
||||
Reading UsageReading `json:"reading"`
|
||||
}
|
||||
|
||||
// Store is what the manager keeps.
|
||||
type Store interface {
|
||||
Licences(ctx context.Context) ([]Licence, error)
|
||||
Licence(ctx context.Context, name string) (*Licence, error)
|
||||
LicenceForAccount(ctx context.Context, account string) (*Licence, error)
|
||||
SaveLicence(ctx context.Context, l Licence) error
|
||||
// Lease takes a lease for d, or answers false while another holder's is live.
|
||||
Lease(ctx context.Context, key, holder string, d time.Duration) (bool, error)
|
||||
Unlease(ctx context.Context, key, holder string) error
|
||||
Bindings(ctx context.Context) ([]Binding, error)
|
||||
Binding(ctx context.Context, consumer string) (*Binding, error)
|
||||
// Bind binds (or switches) a consumer at the next generation.
|
||||
Bind(ctx context.Context, consumer, licence string) (Binding, error)
|
||||
Unbind(ctx context.Context, consumer string) (bool, error)
|
||||
// Advance gives every consumer of a licence a new generation: what a rotation is to them.
|
||||
Advance(ctx context.Context, licence string) ([]Binding, error)
|
||||
Outcome(ctx context.Context, fingerprint string) (Outcome, error)
|
||||
RecordOutcome(ctx context.Context, fingerprint, node, account string, o Outcome, why string) error
|
||||
RecordUsage(ctx context.Context, licence string, at int64, r UsageReading, raw map[string]any) error
|
||||
Usage(ctx context.Context, licence string, limit int) ([]UsageRow, error)
|
||||
Audit(ctx context.Context, what string, detail map[string]any) error
|
||||
Close()
|
||||
}
|
||||
|
||||
// MemoryStore is the tests' store.
|
||||
type MemoryStore struct {
|
||||
mu sync.Mutex
|
||||
now func() time.Time
|
||||
rows map[string]Licence
|
||||
binds map[string]Binding
|
||||
leases map[string]struct {
|
||||
holder string
|
||||
until time.Time
|
||||
}
|
||||
outcomes map[string]Outcome
|
||||
usage []UsageRow
|
||||
Audits []map[string]any
|
||||
generation int64
|
||||
}
|
||||
|
||||
// NewMemoryStore is an empty store whose leases age by now.
|
||||
func NewMemoryStore(now func() time.Time) *MemoryStore {
|
||||
return &MemoryStore{now: now, rows: map[string]Licence{}, binds: map[string]Binding{},
|
||||
leases: map[string]struct {
|
||||
holder string
|
||||
until time.Time
|
||||
}{}, outcomes: map[string]Outcome{}}
|
||||
}
|
||||
|
||||
func (m *MemoryStore) Licences(context.Context) ([]Licence, error) {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
out := make([]Licence, 0, len(m.rows))
|
||||
for _, l := range m.rows {
|
||||
out = append(out, l)
|
||||
}
|
||||
sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
|
||||
return out, nil
|
||||
}
|
||||
|
||||
func (m *MemoryStore) Licence(_ context.Context, name string) (*Licence, error) {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
if l, ok := m.rows[name]; ok {
|
||||
return &l, nil
|
||||
}
|
||||
return nil, nil
|
||||
}
|
||||
|
||||
func (m *MemoryStore) LicenceForAccount(_ context.Context, account string) (*Licence, error) {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
for _, l := range m.rows {
|
||||
if l.AccountUUID == account {
|
||||
return &l, nil
|
||||
}
|
||||
}
|
||||
return nil, nil
|
||||
}
|
||||
|
||||
func (m *MemoryStore) SaveLicence(_ context.Context, l Licence) error {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
m.rows[l.Name] = l
|
||||
return nil
|
||||
}
|
||||
|
||||
func (m *MemoryStore) Lease(_ context.Context, key, holder string, d time.Duration) (bool, error) {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
if held, ok := m.leases[key]; ok && held.until.After(m.now()) && held.holder != holder {
|
||||
return false, nil
|
||||
}
|
||||
m.leases[key] = struct {
|
||||
holder string
|
||||
until time.Time
|
||||
}{holder, m.now().Add(d)}
|
||||
return true, nil
|
||||
}
|
||||
|
||||
func (m *MemoryStore) Unlease(_ context.Context, key, holder string) error {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
if m.leases[key].holder == holder {
|
||||
delete(m.leases, key)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func (m *MemoryStore) Bindings(context.Context) ([]Binding, error) {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
out := make([]Binding, 0, len(m.binds))
|
||||
for _, b := range m.binds {
|
||||
out = append(out, b)
|
||||
}
|
||||
sort.Slice(out, func(i, j int) bool { return out[i].Consumer < out[j].Consumer })
|
||||
return out, nil
|
||||
}
|
||||
|
||||
func (m *MemoryStore) Binding(_ context.Context, consumer string) (*Binding, error) {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
if b, ok := m.binds[consumer]; ok {
|
||||
return &b, nil
|
||||
}
|
||||
return nil, nil
|
||||
}
|
||||
|
||||
func (m *MemoryStore) Bind(_ context.Context, consumer, licence string) (Binding, error) {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
m.generation++
|
||||
b := Binding{Consumer: consumer, Licence: licence, Generation: m.generation}
|
||||
m.binds[consumer] = b
|
||||
return b, nil
|
||||
}
|
||||
|
||||
func (m *MemoryStore) Unbind(_ context.Context, consumer string) (bool, error) {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
_, ok := m.binds[consumer]
|
||||
delete(m.binds, consumer)
|
||||
return ok, nil
|
||||
}
|
||||
|
||||
func (m *MemoryStore) Advance(_ context.Context, licence string) ([]Binding, error) {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
var out []Binding
|
||||
for c, b := range m.binds {
|
||||
if b.Licence != licence {
|
||||
continue
|
||||
}
|
||||
m.generation++
|
||||
b.Generation = m.generation
|
||||
m.binds[c] = b
|
||||
out = append(out, b)
|
||||
}
|
||||
sort.Slice(out, func(i, j int) bool { return out[i].Consumer < out[j].Consumer })
|
||||
return out, nil
|
||||
}
|
||||
|
||||
func (m *MemoryStore) Outcome(_ context.Context, fp string) (Outcome, error) {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
return m.outcomes[fp], nil
|
||||
}
|
||||
|
||||
func (m *MemoryStore) RecordOutcome(_ context.Context, fp, _, _ string, o Outcome, _ string) error {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
m.outcomes[fp] = o
|
||||
return nil
|
||||
}
|
||||
|
||||
func (m *MemoryStore) RecordUsage(_ context.Context, licence string, at int64, r UsageReading, _ map[string]any) error {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
m.usage = append(m.usage, UsageRow{Licence: licence, At: at, Reading: r})
|
||||
return nil
|
||||
}
|
||||
|
||||
func (m *MemoryStore) Usage(_ context.Context, licence string, limit int) ([]UsageRow, error) {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
var out []UsageRow
|
||||
for i := len(m.usage) - 1; i >= 0 && len(out) < limit; i-- {
|
||||
if licence == "" || m.usage[i].Licence == licence {
|
||||
out = append(out, m.usage[i])
|
||||
}
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
func (m *MemoryStore) Audit(_ context.Context, what string, detail map[string]any) error {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
d := map[string]any{"what": what}
|
||||
for k, v := range detail {
|
||||
d[k] = v
|
||||
}
|
||||
m.Audits = append(m.Audits, d)
|
||||
return nil
|
||||
}
|
||||
|
||||
func (m *MemoryStore) Close() {}
|
||||
@@ -1,125 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"os"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
// Against a real postgres, because the questions are the database's: does the schema apply twice, does a
|
||||
// lease refuse a second holder, does a generation only grow. Skipped unless one is named:
|
||||
//
|
||||
// docker run -d --rm --name licmgr-pg -e POSTGRES_PASSWORD=t -p 15498:5432 postgres:16-alpine
|
||||
// MESH_TEST_POSTGRES=postgres://postgres:t@127.0.0.1:15498/postgres go test ./...
|
||||
func TestTheStoreOnPostgres(t *testing.T) {
|
||||
url := os.Getenv("MESH_TEST_POSTGRES")
|
||||
if url == "" {
|
||||
t.Skip("MESH_TEST_POSTGRES unset")
|
||||
}
|
||||
ctx := context.Background()
|
||||
s, err := OpenPgStore(ctx, url)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
defer s.Close()
|
||||
for _, table := range []string{"binding", "licence", "lease", "offered", "usage", "audit"} {
|
||||
_, _ = s.pool.Exec(ctx, "drop table if exists "+table+" cascade")
|
||||
}
|
||||
_, _ = s.pool.Exec(ctx, "drop sequence if exists binding_generation")
|
||||
for i := 0; i < 2; i++ {
|
||||
if err := s.Migrate(ctx); err != nil {
|
||||
t.Fatalf("migration %d: %v", i+1, err)
|
||||
}
|
||||
}
|
||||
l := Licence{Name: "a@example.org", Kind: "subscription", AccountUUID: "u-1", Email: "a@example.org", Sealed: "v1.x.y",
|
||||
RefreshFingerprint: "sha256:1", AccessExpiresAt: 1, RefreshExpiresAt: 2, AdoptedAt: 3}
|
||||
if err := s.SaveLicence(ctx, l); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
l.Failures = 2
|
||||
_ = s.SaveLicence(ctx, l)
|
||||
if got, _ := s.LicenceForAccount(ctx, "u-1"); got == nil || got.Failures != 2 || got.OrganizationUUID != "" {
|
||||
t.Fatalf("%+v", got)
|
||||
}
|
||||
if none, err := s.Licence(ctx, "nobody"); none != nil || err != nil {
|
||||
t.Fatalf("%v %v", none, err)
|
||||
}
|
||||
lease := func(holder string) bool {
|
||||
ok, err := s.Lease(ctx, "licence:a", holder, time.Minute)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return ok
|
||||
}
|
||||
if !lease("one") || lease("two") || !lease("one") {
|
||||
t.Fatal("a lease did not refuse a second holder, or its own holder could not renew it")
|
||||
}
|
||||
_ = s.Unlease(ctx, "licence:a", "one")
|
||||
if !lease("two") {
|
||||
t.Fatal("a released lease was not taken")
|
||||
}
|
||||
b1, _ := s.Bind(ctx, "laptop", l.Name)
|
||||
adv, _ := s.Advance(ctx, l.Name)
|
||||
b3, _ := s.Bind(ctx, "laptop", l.Name)
|
||||
if len(adv) != 1 || !(b1.Generation < adv[0].Generation && adv[0].Generation < b3.Generation) {
|
||||
t.Fatalf("generations %d %v %d", b1.Generation, adv, b3.Generation)
|
||||
}
|
||||
_ = s.RecordOutcome(ctx, "sha256:x", "laptop", "u-1", Dead, "400")
|
||||
if o, _ := s.Outcome(ctx, "sha256:x"); o != Dead {
|
||||
t.Fatalf("outcome %q", o)
|
||||
}
|
||||
if o, _ := s.Outcome(ctx, "sha256:none"); o != "" {
|
||||
t.Fatalf("an unknown login is %q", o)
|
||||
}
|
||||
pct := 1.0
|
||||
_ = s.RecordUsage(ctx, l.Name, 5, UsageReading{SessionPct: &pct}, map[string]any{})
|
||||
if u, _ := s.Usage(ctx, "", 5); len(u) != 1 || *u[0].Reading.SessionPct != 1 {
|
||||
t.Fatalf("usage %v", u)
|
||||
}
|
||||
if err := s.Audit(ctx, "bound", map[string]any{"consumer": "laptop"}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if ok, _ := s.Unbind(ctx, "laptop"); !ok {
|
||||
t.Fatal("unbind")
|
||||
}
|
||||
all, _ := s.Licences(ctx)
|
||||
if len(all) != 1 || !strings.HasPrefix(all[0].Sealed, "v1.") {
|
||||
t.Fatalf("%v", all)
|
||||
}
|
||||
}
|
||||
|
||||
func TestARefreshThatDoesNotRotateKeepsTheRefreshToken(t *testing.T) {
|
||||
prev := FullGrant{AccessToken: "a", RefreshToken: "r", ExpiresAt: 1}
|
||||
in := int64(60)
|
||||
kept := NextGrant(prev, tokenResponse{AccessToken: "a2", ExpiresIn: &in}, 1000)
|
||||
if !kept.OK || kept.Grant.RefreshToken != "r" || kept.Grant.ExpiresAt != 61_000 {
|
||||
t.Fatalf("%+v", kept)
|
||||
}
|
||||
rotated := NextGrant(prev, tokenResponse{AccessToken: "a3", RefreshToken: "r2"}, 0)
|
||||
if rotated.Grant.RefreshToken != "r2" {
|
||||
t.Fatalf("%+v", rotated)
|
||||
}
|
||||
if NextGrant(prev, tokenResponse{}, 0).OK {
|
||||
t.Fatal("an answer with no access token was a grant")
|
||||
}
|
||||
}
|
||||
|
||||
func TestAGrantAtRestOpensOnlyWithItsKey(t *testing.T) {
|
||||
a, _ := NewCrypt("one key")
|
||||
b, _ := NewCrypt("another key")
|
||||
sealed := a.Seal(`{"refreshToken":"rt"}`)
|
||||
if strings.Contains(sealed, "rt") {
|
||||
t.Fatal("stored in the clear")
|
||||
}
|
||||
if got, err := a.Open(sealed); err != nil || got != `{"refreshToken":"rt"}` {
|
||||
t.Fatalf("%q %v", got, err)
|
||||
}
|
||||
if _, err := b.Open(sealed); err == nil {
|
||||
t.Fatal("opened with another key")
|
||||
}
|
||||
if _, err := NewCrypt(" "); err == nil {
|
||||
t.Fatal("an empty key was accepted")
|
||||
}
|
||||
}
|
||||
Vendored
-12
@@ -1,12 +0,0 @@
|
||||
{
|
||||
"privateKey": "-----BEGIN PRIVATE KEY-----\nMC4CAQAwBQYDK2VuBCIEIAi2NK/bN+p7cqYUwv/kz72TgLdmJUfOHCDZTrMpQzpS\n-----END PRIVATE KEY-----\n",
|
||||
"publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VuAyEARYvD/w+9ah0KWS9T9pd6Ea6CBymUE48vEVk983QPKyY=\n-----END PUBLIC KEY-----\n",
|
||||
"box": {
|
||||
"v": 1,
|
||||
"eph": "MCowBQYDK2VuAyEAIYlSGrJvF8qSjR1aTFWbEQM/NFbZXrarglN0aRLZZ0E=",
|
||||
"iv": "ABqT/hMukn6+xpjh",
|
||||
"tag": "POzmsWTPHSn9xLMMJJ9Akg==",
|
||||
"ct": "m2u0kuQ0PwrsGelM99Z5aBw6FCd6lFISUbwiK5TzzDw4ZrGtsHEvxytoIeFC"
|
||||
},
|
||||
"plaintext": "a grant sealed by the TypeScript agent module"
|
||||
}
|
||||
@@ -1,187 +0,0 @@
|
||||
package main
|
||||
|
||||
// The only file that talks to Anthropic (novox/hq ADR 0183): the token endpoint, which this module alone
|
||||
// calls — one rotation source — and the usage endpoint. Ported from the predecessor's manager, whose
|
||||
// client id and error handling were each earned by an incident.
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"io"
|
||||
"net/http"
|
||||
"net/url"
|
||||
"os"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// The public Claude Code client's id: not a secret, and a hard-won constant — a metadata URL in its place
|
||||
// answers 400, which the predecessor once misdiagnosed as a dead grant.
|
||||
const clientID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e"
|
||||
|
||||
func tokenEndpoint() string {
|
||||
if v := os.Getenv("MESH_ANTHROPIC_TOKEN_ENDPOINT"); v != "" {
|
||||
return v
|
||||
}
|
||||
return "https://platform.claude.com/v1/oauth/token"
|
||||
}
|
||||
|
||||
func usageEndpoint() string {
|
||||
if v := os.Getenv("MESH_ANTHROPIC_USAGE_ENDPOINT"); v != "" {
|
||||
return v
|
||||
}
|
||||
return "https://api.anthropic.com/api/oauth/usage"
|
||||
}
|
||||
|
||||
// FullGrant is a subscription's grant as this module keeps it: what the agent's credentials file calls
|
||||
// `claudeAiOauth`.
|
||||
type FullGrant struct {
|
||||
AccessToken string `json:"accessToken"`
|
||||
RefreshToken string `json:"refreshToken"`
|
||||
ExpiresAt int64 `json:"expiresAt"`
|
||||
RefreshTokenExpiresAt *int64 `json:"refreshTokenExpiresAt,omitempty"`
|
||||
Scopes []string `json:"scopes,omitempty"`
|
||||
SubscriptionType string `json:"subscriptionType,omitempty"`
|
||||
RateLimitTier string `json:"rateLimitTier,omitempty"`
|
||||
}
|
||||
|
||||
// Refreshed is what a refresh came to: the next grant and the account the vendor answered for, or why not.
|
||||
type Refreshed struct {
|
||||
OK bool
|
||||
Grant FullGrant
|
||||
Account string // empty when the vendor named none
|
||||
Status int
|
||||
Reason string
|
||||
}
|
||||
|
||||
// Vendor is the vendor as the manager reaches it; a test stubs it.
|
||||
type Vendor interface {
|
||||
Refresh(ctx context.Context, g FullGrant) Refreshed
|
||||
Usage(ctx context.Context, accessToken string) (map[string]any, error)
|
||||
}
|
||||
|
||||
type tokenResponse struct {
|
||||
AccessToken string `json:"access_token"`
|
||||
RefreshToken string `json:"refresh_token"`
|
||||
ExpiresIn *int64 `json:"expires_in"`
|
||||
RefreshTokenExpiresIn *int64 `json:"refresh_token_expires_in"`
|
||||
Scope string `json:"scope"`
|
||||
Scopes []string `json:"scopes"`
|
||||
SubscriptionType string `json:"subscription_type"`
|
||||
Account *struct {
|
||||
UUID string `json:"uuid"`
|
||||
} `json:"account"`
|
||||
}
|
||||
|
||||
// NextGrant is the grant a refresh answered, laid over the one refreshed: a refresh token the vendor did
|
||||
// not rotate is kept, so a rotating vendor and one that does not are both handled.
|
||||
func NextGrant(prev FullGrant, r tokenResponse, nowMs int64) Refreshed {
|
||||
if r.AccessToken == "" {
|
||||
return Refreshed{Status: 200, Reason: "the vendor answered without an access token"}
|
||||
}
|
||||
g := prev
|
||||
g.AccessToken = r.AccessToken
|
||||
if r.RefreshToken != "" {
|
||||
g.RefreshToken = r.RefreshToken
|
||||
}
|
||||
if r.ExpiresIn != nil {
|
||||
g.ExpiresAt = nowMs + *r.ExpiresIn*1000
|
||||
}
|
||||
if r.RefreshTokenExpiresIn != nil {
|
||||
v := nowMs + *r.RefreshTokenExpiresIn*1000
|
||||
g.RefreshTokenExpiresAt = &v
|
||||
}
|
||||
if len(r.Scopes) > 0 {
|
||||
g.Scopes = r.Scopes
|
||||
} else if r.Scope != "" {
|
||||
g.Scopes = strings.Fields(r.Scope)
|
||||
}
|
||||
if r.SubscriptionType != "" {
|
||||
g.SubscriptionType = r.SubscriptionType
|
||||
}
|
||||
out := Refreshed{OK: true, Grant: g}
|
||||
if r.Account != nil {
|
||||
out.Account = r.Account.UUID
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
type liveVendor struct{ client *http.Client }
|
||||
|
||||
// LiveVendor is the vendor over the network.
|
||||
func LiveVendor() Vendor { return liveVendor{client: &http.Client{Timeout: 30 * time.Second}} }
|
||||
|
||||
func (v liveVendor) Refresh(ctx context.Context, g FullGrant) Refreshed {
|
||||
form := url.Values{"grant_type": {"refresh_token"}, "refresh_token": {g.RefreshToken}, "client_id": {clientID}}
|
||||
req, err := http.NewRequestWithContext(ctx, http.MethodPost, tokenEndpoint(), strings.NewReader(form.Encode()))
|
||||
if err != nil {
|
||||
return Refreshed{Reason: err.Error()}
|
||||
}
|
||||
req.Header.Set("content-type", "application/x-www-form-urlencoded")
|
||||
resp, err := v.client.Do(req)
|
||||
if err != nil {
|
||||
return Refreshed{Reason: "the token endpoint did not answer: " + err.Error()}
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
|
||||
if resp.StatusCode/100 != 2 {
|
||||
// The body, never only the status: a malformed request and a revoked grant both answer 400.
|
||||
reason := string(body)
|
||||
if len(reason) > 400 {
|
||||
reason = reason[:400]
|
||||
}
|
||||
return Refreshed{Status: resp.StatusCode, Reason: reason}
|
||||
}
|
||||
var r tokenResponse
|
||||
if err := json.Unmarshal(body, &r); err != nil {
|
||||
return Refreshed{Status: resp.StatusCode, Reason: "the vendor's answer is not JSON"}
|
||||
}
|
||||
return NextGrant(g, r, time.Now().UnixMilli())
|
||||
}
|
||||
|
||||
func (v liveVendor) Usage(ctx context.Context, accessToken string) (map[string]any, error) {
|
||||
req, err := http.NewRequestWithContext(ctx, http.MethodGet, usageEndpoint(), nil)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
req.Header.Set("authorization", "Bearer "+accessToken)
|
||||
resp, err := v.client.Do(req)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
if resp.StatusCode/100 != 2 {
|
||||
return nil, fmt.Errorf("the usage endpoint answered %d", resp.StatusCode)
|
||||
}
|
||||
var out map[string]any
|
||||
return out, json.NewDecoder(resp.Body).Decode(&out)
|
||||
}
|
||||
|
||||
// UsageReading is the licence-grain reading (ADR 0054), flattened from the vendor's windows.
|
||||
type UsageReading struct {
|
||||
SessionPct *float64 `json:"sessionPct"`
|
||||
SessionResetsAt string `json:"sessionResetsAt,omitempty"`
|
||||
WeeklyPct *float64 `json:"weeklyPct"`
|
||||
SonnetPct *float64 `json:"sonnetPct"`
|
||||
}
|
||||
|
||||
// FlattenUsage reads the windows the predecessor read.
|
||||
func FlattenUsage(u map[string]any) UsageReading {
|
||||
window := func(k string) (*float64, string) {
|
||||
w, ok := u[k].(map[string]any)
|
||||
if !ok {
|
||||
return nil, ""
|
||||
}
|
||||
pct, ok := w["utilization"].(float64)
|
||||
resets, _ := w["resets_at"].(string)
|
||||
if !ok {
|
||||
return nil, resets
|
||||
}
|
||||
return &pct, resets
|
||||
}
|
||||
s, resets := window("five_hour")
|
||||
w, _ := window("seven_day")
|
||||
so, _ := window("seven_day_sonnet")
|
||||
return UsageReading{SessionPct: s, SessionResetsAt: resets, WeeklyPct: w, SonnetPct: so}
|
||||
}
|
||||
@@ -1,16 +0,0 @@
|
||||
module claude-licence-manager
|
||||
|
||||
go 1.25.0
|
||||
|
||||
require (
|
||||
git.novox.be/novox/mesh-sdk/go v0.1.7
|
||||
github.com/jackc/pgx/v5 v5.11.0
|
||||
)
|
||||
|
||||
require (
|
||||
github.com/jackc/pgpassfile v1.0.0 // indirect
|
||||
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
|
||||
github.com/jackc/puddle/v2 v2.2.2 // indirect
|
||||
golang.org/x/sync v0.17.0 // indirect
|
||||
golang.org/x/text v0.29.0 // indirect
|
||||
)
|
||||
@@ -1,28 +0,0 @@
|
||||
git.novox.be/novox/mesh-sdk/go v0.1.7 h1:C0sTQmtTiyYH7bnqZb7PusXnqA37gKuT7Nqjn9gG47w=
|
||||
git.novox.be/novox/mesh-sdk/go v0.1.7/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=
|
||||
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
|
||||
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
|
||||
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
|
||||
github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
|
||||
github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
|
||||
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
|
||||
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
|
||||
github.com/jackc/pgx/v5 v5.11.0 h1:IzBBtyK9AHqf98cctWFifYSci2hgQR/cd56wB4p+ogg=
|
||||
github.com/jackc/pgx/v5 v5.11.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
|
||||
github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
|
||||
github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
|
||||
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
|
||||
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
|
||||
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
|
||||
github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
|
||||
github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
|
||||
github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
|
||||
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
|
||||
golang.org/x/sync v0.17.0 h1:l60nONMj9l5drqw6jlhIELNv9I0A4OFgRsG9k2oT9Ug=
|
||||
golang.org/x/sync v0.17.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
|
||||
golang.org/x/text v0.29.0 h1:1neNs90w9YzJ9BocxfsQNHKuAT4pkghyXc4nhZ6sJvk=
|
||||
golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4=
|
||||
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
|
||||
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
|
||||
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
|
||||
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
|
||||
@@ -1,130 +0,0 @@
|
||||
{
|
||||
"module": "claude-licence-manager",
|
||||
"version": "1",
|
||||
"slug": "licmgr",
|
||||
"requires": [
|
||||
"postgres-database",
|
||||
"secret"
|
||||
],
|
||||
"contributes": {
|
||||
"postgres-database": {
|
||||
"name": "claude_licences"
|
||||
}
|
||||
},
|
||||
"binds": {
|
||||
"postgres-database": "${dir:state}/database.json"
|
||||
},
|
||||
"secrets": {
|
||||
"postgres-database": "${dir:state}/database.secret",
|
||||
"secret": {
|
||||
"grant-key": "${dir:state}/grant.key"
|
||||
}
|
||||
},
|
||||
"seats": [
|
||||
{
|
||||
"name": "anthropic-licence-manager",
|
||||
"scope": "mesh",
|
||||
"serves": [
|
||||
"licences",
|
||||
"bindings",
|
||||
"bind",
|
||||
"switch",
|
||||
"release",
|
||||
"refresh",
|
||||
"usage",
|
||||
"adopt",
|
||||
"current"
|
||||
]
|
||||
}
|
||||
],
|
||||
"claims": [
|
||||
{
|
||||
"name": "anthropic-licence-manager",
|
||||
"scope": "mesh",
|
||||
"serves": [
|
||||
"licences",
|
||||
"bindings",
|
||||
"bind",
|
||||
"switch",
|
||||
"release",
|
||||
"refresh",
|
||||
"usage",
|
||||
"adopt",
|
||||
"current"
|
||||
]
|
||||
}
|
||||
],
|
||||
"emits": [
|
||||
"licence.adopted",
|
||||
"licence.refused",
|
||||
"licence.failing",
|
||||
"usage.read"
|
||||
],
|
||||
"state": [
|
||||
"bindings"
|
||||
],
|
||||
"reads": [
|
||||
"claude-code.holdings"
|
||||
],
|
||||
"resources": [
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "."
|
||||
},
|
||||
{
|
||||
"id": "database-url",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/database.url",
|
||||
"mode": "0600",
|
||||
"content": "postgresql://${bound:postgres-database:as}:${secret:postgres-database}@${bound:postgres-database:at}:${bound:postgres-database:port}/${bound:postgres-database:as}\n"
|
||||
},
|
||||
{
|
||||
"id": "settings",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/settings.json",
|
||||
"mode": "0600",
|
||||
"merge": "json",
|
||||
"content": "{\n \"cadence_minutes\": 240,\n \"floor_minutes\": 60,\n \"failures_to_notify\": 3,\n \"cooldown_hours\": 24,\n \"refresh_warn_days\": 3\n}\n"
|
||||
},
|
||||
{
|
||||
"id": "prepare",
|
||||
"type": "process",
|
||||
"name": "claude-licence-manager-prepare",
|
||||
"artifact": "code",
|
||||
"run": [
|
||||
"./claude-licence-manager",
|
||||
"prepare"
|
||||
],
|
||||
"run-once": true,
|
||||
"env": {
|
||||
"DATABASE_URL_FILE": "${dir:state}/database.url"
|
||||
},
|
||||
"restart-on": [
|
||||
"database-url"
|
||||
]
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "code",
|
||||
"kind": "bundle",
|
||||
"language": "go",
|
||||
"system": "arch",
|
||||
"from": "cmd/claude-licence-manager",
|
||||
"binary": "claude-licence-manager",
|
||||
"loads": [
|
||||
"claude-licence-manager"
|
||||
],
|
||||
"env": {
|
||||
"DATABASE_URL_FILE": "${dir:state}/database.url",
|
||||
"MESH_LICENCE_STATE": "${dir:state}",
|
||||
"MESH_LICENCE_KEY_FILE": "${dir:state}/grant.key",
|
||||
"MESH_LICENCE_SETTINGS": "${dir:state}/settings.json"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,166 +0,0 @@
|
||||
# docker
|
||||
|
||||
The container runtime as a module (novox/hq to-be 42 phase 1, item 8; research 027/01–02; ADR 0166,
|
||||
ADR 0207). It claims the node seat `node-container-runtime`. That seat carries no verbs yet: its verbs,
|
||||
and the host creating containers through its holder, wait on ADR 0166's acceptance. Until then the
|
||||
tools below are the module's own.
|
||||
|
||||
## What it declares
|
||||
|
||||
| resource | what | the host's rule |
|
||||
|---|---|---|
|
||||
| `package` | `docker` | installed if absent; never uninstalled when the module goes |
|
||||
| `buildx` | `docker-buildx` | the same. Only the build machine has it today; `docker build` needs it for BuildKit everywhere |
|
||||
| `socket` | `docker.socket` running, enabled at boot | given back as found when the module goes (ADR 0118) |
|
||||
| `prune-service`, `prune-timer` | `/etc/systemd/system/docker-prune.{service,timer}`, written whole | removed with the module |
|
||||
| `prune` | `docker-prune.timer` running, enabled at boot; restarted when either file changes | stopped and disabled with the module (the mesh made the unit) |
|
||||
|
||||
The weekly prune takes **dangling images and build cache unused for a week, and nothing else**. It
|
||||
takes no volume, no container and no image a container uses, so it never touches a container the mesh
|
||||
holds. It runs at idle priority, at a random point in the hour after the weekly mark. A run missed
|
||||
while the machine was off happens at the next boot.
|
||||
|
||||
**Capabilities:** `package-manager`, `service-manager`, `privileged`. It does not declare
|
||||
`container-runtime`: under ADR 0165, which is still proposed, that word means a running daemon, and
|
||||
the module that installs the daemon cannot require it.
|
||||
|
||||
## What it does not declare yet, and why
|
||||
|
||||
Three things this module should own are already declared by other modules on every machine. The
|
||||
controller refuses two modules on one node that declare the same `path`, `unit`, `name` or `package`
|
||||
(`checkResources`, mesh-controller `internal/catalogue/resolve.go`). Declaring any of them here would
|
||||
make the module unassignable everywhere. The refusals were checked against the controller's own
|
||||
check:
|
||||
|
||||
```
|
||||
zsh and docker both declare the name "${machine:account}"
|
||||
dnsmasq and docker both declare the path "/etc/docker/daemon.json"
|
||||
dnsmasq and docker both declare the unit "docker.service"
|
||||
```
|
||||
|
||||
### 1. `/etc/docker/daemon.json` and `docker.service` (issue 190)
|
||||
|
||||
Today the file has three writers. Each writes into it (`into: json`, ADR 0102) and reloads the
|
||||
service:
|
||||
|
||||
- **`dnsmasq`** writes `dns` and `live-restore`, through `dnsmasq.runtime-dns` and `dnsmasq.runtime`.
|
||||
- **The private network**, generated by the controller (`internal/overlay/generator.go`), writes
|
||||
`insecure-registries`. The collision check does not see generated resources.
|
||||
- **Nobody** writes log rotation. One machine has `log-driver` and `log-opts` by hand.
|
||||
|
||||
**The change proposed, in one merge:**
|
||||
|
||||
1. `dnsmasq` drops its `runtime-dns` and `runtime` resources.
|
||||
2. `docker` adds the two resources below:
|
||||
|
||||
```json
|
||||
{"id": "daemon", "type": "file", "path": "/etc/docker/daemon.json", "mode": "0644", "into": "json",
|
||||
"content": "{\"dns\": [\"${machine:address}\"], \"live-restore\": true, \"log-driver\": \"json-file\", \"log-opts\": {\"max-size\": \"100m\", \"max-file\": \"5\"}}\n"},
|
||||
{"id": "runtime", "type": "service", "unit": "docker.service", "state": "running", "boot": "enabled", "reload-on": ["daemon"]}
|
||||
```
|
||||
|
||||
The service is **reloaded, never restarted**: a restart stops every container. The daemon reads
|
||||
`live-restore` on a reload. It reads `dns`, `log-driver` and `log-opts` only at its next start, so
|
||||
they apply then (to containers created afterwards, for the log keys). With `live-restore` on, that
|
||||
start keeps every container running.
|
||||
|
||||
**Why one merge, and only after this module is on every machine:**
|
||||
|
||||
- In one apply, the host first gives back the resources that are no longer declared, then applies
|
||||
the new ones (mesh-host `apply.go`).
|
||||
- `dnsmasq` gives back `dns` and `live-restore` to what they held before it, and `docker` sets them
|
||||
again in the same apply. The daemon is reloaded once, after both steps.
|
||||
- A machine pushed the new `dnsmasq` *without* this module would keep its pre-mesh values for both
|
||||
keys. On one machine that is `live-restore: false`, and the next daemon restart there would stop
|
||||
every container.
|
||||
|
||||
**Later:** the controller hands the registry to this module as a value, and the overlay stops
|
||||
generating its two resources (issue 190, steps 2 and 5). Until then the overlay keeps writing its one
|
||||
key beside this module's. The host merges disjoint keys correctly; the mesh-host `into.go` record is
|
||||
per resource.
|
||||
|
||||
### 2. The operator account's membership of the `docker` group
|
||||
|
||||
The right shape is the host's `user` shape. Its `groups` are additive: the host runs
|
||||
`usermod --append` and never takes a group away.
|
||||
|
||||
```json
|
||||
{"id": "group", "type": "user", "name": "${machine:account}", "groups": ["docker"]}
|
||||
```
|
||||
|
||||
`zsh` already declares a `user` resource for the same account (its login shell). The controller
|
||||
compares `name` across modules, so the two collide.
|
||||
|
||||
**The change proposed (mesh-controller, `checkResources`):** judge a `user` resource by the fields it
|
||||
sets, not by its name:
|
||||
|
||||
- `shell` and `home` stay single-owner;
|
||||
- `groups` may be declared by any number of modules, because the host only adds them.
|
||||
|
||||
Then this module declares the resource above, and no module has to carry another's group.
|
||||
|
||||
Today the operator account is in the group on every machine, by hand. Nothing is lost while it waits.
|
||||
|
||||
## The bootstrap's runtime
|
||||
|
||||
On the machine the mesh was first installed on, the foundation bundle declared `package docker`
|
||||
(`container-runtime`) and `docker.service` running and enabled (`container-runtime-running`). ADR 0207
|
||||
§5 exempts them.
|
||||
|
||||
- The host records them under their bare ids, with origin *carried*. A mesh declaration's orphan pass
|
||||
never sees them (mesh-host `store.go`).
|
||||
- So `docker.package` here is a **second record of the same package**. The apply says "already
|
||||
installed", and neither record ever uninstalls it.
|
||||
- This module does not declare `docker.service` today, so nothing overlaps there. The proposed step
|
||||
1 would add a second record of that unit. Its found state is *running*, because genesis started
|
||||
it, so undeclaring this module would leave the daemon running.
|
||||
|
||||
## Tools
|
||||
|
||||
The tools run as the operator account. If the daemon's socket refuses that account, a call is asked
|
||||
again through `sudo -n` (a process keeps the groups it started with). Every call has a 20 s bound.
|
||||
A failure is an error naming how it failed, never an empty answer.
|
||||
|
||||
**Every container on the machine is in scope.** A container the mesh holds carries the host's label
|
||||
`mesh-host.id` (its value names the assignment), and every answer says `mesh_held`.
|
||||
|
||||
| tool | | what |
|
||||
|---|---|---|
|
||||
| `docker_list` | r | every container: image, state, health, restarts, ports, mounts, compose project, `mesh_held`; filter by owner, state or name |
|
||||
| `docker_inspect` | r | one container whole, **environment values left out** (names kept) |
|
||||
| `docker_logs` | r | the last lines of both streams, merged in order, with timestamps (default 200, at most 2000) |
|
||||
| `docker_stats` | r | CPU, memory, I/O and process count per running container, heaviest first |
|
||||
| `docker_start` / `docker_stop` / `docker_restart` | a | one container. On a mesh-held one, the answer says the host restores its declared state at its next apply |
|
||||
| `docker_top` | r | the processes inside one container |
|
||||
| `docker_images` | r | images, largest first, with the containers using each; `dangling`, `unused` or `used` |
|
||||
| `docker_prune` | a | dangling images and build cache, and stopped containers the mesh does not hold if `containers` is true. **A dry run unless `dry_run` is false. Never a volume** |
|
||||
| `docker_disk_usage` | r | `docker system df -v`: total, active and reclaimable per kind, with the largest of each |
|
||||
| `docker_networks` | r | networks, subnets, and the containers on each |
|
||||
| `docker_volumes` | r | volumes, who mounts each, whether the mesh holds one of them, anonymous or not, and sizes if asked |
|
||||
| `docker_events` | r | the runtime's events over a window ending now (default 60 min, at most 24 h), without exec noise |
|
||||
| `docker_daemon_config` | r | `daemon.json` as on disk, `docker info`'s essentials, and keys the daemon has not taken yet |
|
||||
| `docker_unlabelled` | r | the containers the mesh does not hold: the cleanup list |
|
||||
| `docker_problems` | r | unhealthy, restarting, dead, killed for memory, failed, or restarted five times or more |
|
||||
| `docker_ports` | r | every published port, and the containers on the host's network |
|
||||
|
||||
## Tests
|
||||
|
||||
```
|
||||
go test ./...
|
||||
```
|
||||
|
||||
The tests run against a fake runner and cover:
|
||||
|
||||
- escalation through `sudo -n` on a refused socket, and never as root;
|
||||
- each failure named by its cause;
|
||||
- a name or id never read as an option;
|
||||
- mesh-held marking;
|
||||
- the environment left out of `inspect`;
|
||||
- the restore note on a mesh-held act;
|
||||
- prune being a dry run by default and never reaching a volume, a mesh container or `--volumes`;
|
||||
- the log merge;
|
||||
- size parsing;
|
||||
- what the daemon has not yet taken;
|
||||
- event filtering;
|
||||
- volume ownership;
|
||||
- that the tools served are exactly the manifest's `tools`.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,360 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"io/fs"
|
||||
"os"
|
||||
"reflect"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
type call struct {
|
||||
name string
|
||||
args []string
|
||||
}
|
||||
|
||||
// fake answers each command by the first rule whose prefix matches "name arg arg…".
|
||||
type fake struct {
|
||||
rules []rule
|
||||
calls []call
|
||||
}
|
||||
|
||||
type rule struct {
|
||||
prefix string
|
||||
ran Ran
|
||||
}
|
||||
|
||||
func (f *fake) on(prefix string, r Ran) *fake { f.rules = append(f.rules, rule{prefix, r}); return f }
|
||||
|
||||
func (f *fake) run(_ context.Context, name string, args ...string) Ran {
|
||||
f.calls = append(f.calls, call{name, args})
|
||||
line := strings.Join(append([]string{name}, args...), " ")
|
||||
for _, r := range f.rules {
|
||||
if strings.HasPrefix(line, r.prefix) {
|
||||
return r.ran
|
||||
}
|
||||
}
|
||||
return Ran{Status: 1, Stderr: "unexpected: " + line}
|
||||
}
|
||||
|
||||
func (f *fake) ran(prefix string) bool {
|
||||
for _, c := range f.calls {
|
||||
if strings.HasPrefix(strings.Join(append([]string{c.name}, c.args...), " "), prefix) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
func client(f *fake, uid int) *Client {
|
||||
return &Client{Run: f.run, UID: uid, ReadFile: func(string) ([]byte, error) { return nil, fs.ErrNotExist },
|
||||
Now: func() time.Time { return time.Date(2026, 10, 4, 12, 0, 0, 0, time.UTC) }}
|
||||
}
|
||||
|
||||
const held = `{"Id":"aaaaaaaaaaaaaaaa","Name":"/mesh-web","Created":"2026-10-01T00:00:00Z","Image":"sha256:img1",
|
||||
"Config":{"Image":"web:1","Labels":{"mesh-host.id":"hello-web.server","mesh-host.spec":"x"},"Env":["PASSWORD=hunter2","PATH=/bin"]},
|
||||
"State":{"Status":"running","Running":true,"StartedAt":"2026-10-01T00:00:01Z","FinishedAt":"0001-01-01T00:00:00Z","Health":{"Status":"healthy"}},
|
||||
"HostConfig":{"RestartPolicy":{"Name":"unless-stopped"},"NetworkMode":"bridge"},
|
||||
"NetworkSettings":{"Ports":{"80/tcp":[{"HostIp":"0.0.0.0","HostPort":"8080"}]}},
|
||||
"Mounts":[{"Type":"volume","Name":"webdata","Destination":"/data","RW":true}]}`
|
||||
|
||||
const stray = `{"Id":"bbbbbbbbbbbbbbbb","Name":"/dev-db","Created":"2026-09-01T00:00:00Z","Image":"sha256:img2",
|
||||
"Config":{"Image":"postgres:16","Labels":{"com.docker.compose.project":"dev","com.docker.compose.project.working_dir":"/home/op/dev"}},
|
||||
"State":{"Status":"exited","ExitCode":1,"FinishedAt":"2026-09-02T00:00:00Z"},
|
||||
"HostConfig":{"RestartPolicy":{"Name":"no"}},"NetworkSettings":{"Ports":{}},
|
||||
"Mounts":[{"Type":"volume","Name":"dbdata","Destination":"/var/lib/postgresql/data","RW":true}]}`
|
||||
|
||||
func machine() *fake {
|
||||
return (&fake{}).
|
||||
on("docker ps --all --quiet --no-trunc", Ran{Stdout: "aaaaaaaaaaaaaaaa\nbbbbbbbbbbbbbbbb\n"}).
|
||||
on("docker container inspect aaaaaaaaaaaaaaaa bbbbbbbbbbbbbbbb", Ran{Stdout: "[" + held + "," + stray + "]"}).
|
||||
on("docker container inspect mesh-web", Ran{Stdout: "[" + held + "]"}).
|
||||
on("docker container inspect dev-db", Ran{Stdout: "[" + stray + "]"})
|
||||
}
|
||||
|
||||
func TestARefusedSocketIsAskedAgainThroughSudoWithoutAPromptUnlessThisIsRoot(t *testing.T) {
|
||||
denied := Ran{Status: 1, Stderr: "permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get ...: dial unix /var/run/docker.sock: connect: permission denied\n"}
|
||||
f := (&fake{}).on("docker ", denied).on("sudo -n docker info", Ran{Stdout: "{}"})
|
||||
if _, err := client(f, 1000).docker(context.Background(), "info", "--format", "{{json .}}"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !f.ran("sudo -n docker info --format") {
|
||||
t.Fatalf("not escalated: %+v", f.calls)
|
||||
}
|
||||
f = (&fake{}).on("docker ", denied)
|
||||
if _, err := client(f, 0).docker(context.Background(), "info"); err == nil || f.ran("sudo") {
|
||||
t.Fatalf("root escalated or answered: %v %+v", err, f.calls)
|
||||
}
|
||||
}
|
||||
|
||||
func TestFailuresAreNamedByHowTheyFailed(t *testing.T) {
|
||||
denied := Ran{Status: 1, Stderr: "permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock\n"}
|
||||
cases := map[string]*fake{
|
||||
"may not escalate without a prompt": (&fake{}).on("docker ", denied).on("sudo ", Ran{Status: 1, Stderr: "sudo: a password is required\n"}),
|
||||
"sudo is not installed": (&fake{}).on("docker ", denied).on("sudo ", Ran{Status: 127, Err: "ENOENT"}),
|
||||
"docker is not installed": (&fake{}).on("docker ", Ran{Status: 127, Err: "ENOENT"}),
|
||||
"daemon is not answering": (&fake{}).on("docker ", Ran{Status: 1, Stderr: "Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?\n"}),
|
||||
"did not answer: no answer within": (&fake{}).on("docker ", Ran{Status: 124, Err: "no answer within 20 s"}),
|
||||
"docker info failed (3): boom": (&fake{}).on("docker ", Ran{Status: 3, Stderr: "boom\n"}),
|
||||
}
|
||||
for want, f := range cases {
|
||||
_, err := client(f, 1000).docker(context.Background(), "info")
|
||||
if err == nil || !strings.Contains(err.Error(), want) {
|
||||
t.Errorf("want %q, got %v", want, err)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestANameIsNeverAnOption(t *testing.T) {
|
||||
for _, bad := range []string{"--help", "-v", "", "a b", "x;y"} {
|
||||
if _, err := Ref(bad); err == nil {
|
||||
t.Errorf("%q accepted", bad)
|
||||
}
|
||||
}
|
||||
for _, good := range []string{"mesh-web", "aaaaaaaaaaaa", "registry.mesh.internal:5100/x@sha256:abc", "dev_db.1"} {
|
||||
if _, err := Ref(good); err != nil {
|
||||
t.Errorf("%q refused: %v", good, err)
|
||||
}
|
||||
}
|
||||
f := machine()
|
||||
for _, verb := range []string{"start", "stop", "restart"} {
|
||||
if _, err := client(f, 1000).Act(context.Background(), verb, "--rm"); err == nil {
|
||||
t.Errorf("%s took an option", verb)
|
||||
}
|
||||
}
|
||||
if len(f.calls) != 0 {
|
||||
t.Fatalf("docker was called: %+v", f.calls)
|
||||
}
|
||||
}
|
||||
|
||||
func TestEveryContainerIsListedAndTheMeshsAreMarked(t *testing.T) {
|
||||
c := client(machine(), 1000)
|
||||
all, err := c.Containers(context.Background(), "", "", "")
|
||||
if err != nil || len(all) != 2 {
|
||||
t.Fatalf("%v %+v", err, all)
|
||||
}
|
||||
web, db := all[1], all[0]
|
||||
if !web.MeshHeld || web.HeldBy != "hello-web.server" || web.Module != "hello-web" || web.Health != "healthy" {
|
||||
t.Errorf("held: %+v", web)
|
||||
}
|
||||
if !reflect.DeepEqual(web.Ports, []string{"0.0.0.0:8080->80/tcp"}) || web.Mounts[0].Name != "webdata" {
|
||||
t.Errorf("ports/mounts: %+v", web)
|
||||
}
|
||||
if db.MeshHeld || db.Compose != "dev" || db.ComposeDir != "/home/op/dev" || db.FinishedAt == "" {
|
||||
t.Errorf("stray: %+v", db)
|
||||
}
|
||||
mesh, _ := c.Containers(context.Background(), "mesh", "", "")
|
||||
other, _ := c.Containers(context.Background(), "other", "", "")
|
||||
if len(mesh) != 1 || mesh[0].Name != "mesh-web" || len(other) != 1 || other[0].Name != "dev-db" {
|
||||
t.Errorf("held filter: %+v / %+v", mesh, other)
|
||||
}
|
||||
if _, err := c.Containers(context.Background(), "mine", "", ""); err == nil {
|
||||
t.Error("an unknown held filter was accepted")
|
||||
}
|
||||
}
|
||||
|
||||
func TestNoContainersIsAnEmptyListAndAFailureIsAnError(t *testing.T) {
|
||||
got, err := client((&fake{}).on("docker ps", Ran{}), 1000).Containers(context.Background(), "", "", "")
|
||||
if err != nil || got == nil || len(got) != 0 {
|
||||
t.Fatalf("%v %v", got, err)
|
||||
}
|
||||
if _, err := client((&fake{}).on("docker ps", Ran{Status: 1, Stderr: "Cannot connect to the Docker daemon\n"}), 1000).Containers(context.Background(), "", "", ""); err == nil {
|
||||
t.Fatal("a daemon that does not answer read as no containers")
|
||||
}
|
||||
}
|
||||
|
||||
func TestInspectLeavesTheEnvironmentsValuesOut(t *testing.T) {
|
||||
got, err := client(machine(), 1000).Inspect(context.Background(), "mesh-web")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
b, _ := json.Marshal(got)
|
||||
if strings.Contains(string(b), "hunter2") || !strings.Contains(string(b), `"PASSWORD"`) || got["mesh_held"] != true {
|
||||
t.Fatalf("%s", b)
|
||||
}
|
||||
}
|
||||
|
||||
func TestActingOnAMeshContainerSaysTheHostRestoresIt(t *testing.T) {
|
||||
f := machine().on("docker stop", Ran{}).on("docker start", Ran{})
|
||||
got, err := client(f, 1000).Act(context.Background(), "stop", "mesh-web")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !f.ran("docker stop --time 10 mesh-web") || got["mesh_held"] != true || !strings.Contains(got["note"].(string), "host restores") {
|
||||
t.Fatalf("%v %+v", got, f.calls)
|
||||
}
|
||||
got, _ = client(f, 1000).Act(context.Background(), "start", "dev-db")
|
||||
if _, noted := got["note"]; noted || got["mesh_held"] != false {
|
||||
t.Fatalf("a stray was noted: %v", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestPruneIsADryRunByDefaultAndNeverTouchesAVolumeOrAMeshContainer(t *testing.T) {
|
||||
f := machine().
|
||||
on("docker image ls --no-trunc --filter dangling=true", Ran{Stdout: `{"ID":"sha256:dead","Size":"1.5GB"}` + "\n"}).
|
||||
on("docker system df --format", Ran{Stdout: `{"Type":"Build Cache","TotalCount":"3","Size":"2GB","Reclaimable":"1GB"}` + "\n"}).
|
||||
on("docker image prune", Ran{Stdout: "Deleted Images:\nx\n\nTotal reclaimed space: 1.5GB\n"}).
|
||||
on("docker builder prune", Ran{Stdout: "Total:\t1GB\n"}).
|
||||
on("docker container rm", Ran{})
|
||||
c := client(f, 1000)
|
||||
got, err := c.Prune(context.Background(), PruneAsk{Images: true, BuildCache: true, Containers: true, DryRun: true})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if f.ran("docker image prune") || f.ran("docker builder prune") || f.ran("docker container rm") {
|
||||
t.Fatalf("a dry run removed something: %+v", f.calls)
|
||||
}
|
||||
if got["images"].(map[string]any)["dangling"] != 1 || !reflect.DeepEqual(got["containers"].(map[string]any)["stopped_not_held"], []string{"dev-db"}) {
|
||||
t.Fatalf("%v", got)
|
||||
}
|
||||
got, err = c.Prune(context.Background(), PruneAsk{Images: true, BuildCache: true, Containers: true, OlderThanH: 24})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !f.ran("docker image prune --force --filter until=24h") || !f.ran("docker builder prune --force --filter until=24h") || !f.ran("docker container rm dev-db") {
|
||||
t.Fatalf("not pruned: %+v", f.calls)
|
||||
}
|
||||
for _, c := range f.calls {
|
||||
line := strings.Join(c.args, " ")
|
||||
if strings.Contains(line, "volume") || strings.Contains(line, "mesh-web") && c.args[0] != "container" || strings.Contains(line, "--volumes") || strings.Contains(line, "--all") && c.args[0] != "ps" {
|
||||
t.Errorf("prune reached too far: %s", line)
|
||||
}
|
||||
}
|
||||
if got["images"].(map[string]any)["reclaimed"] != "1.5GB" || got["build_cache"].(map[string]any)["reclaimed"] != "1GB" {
|
||||
t.Errorf("reclaimed: %v", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestLogsMergeBothStreamsInOrderAndKeepTheTail(t *testing.T) {
|
||||
f := (&fake{}).on("docker logs", Ran{Stdout: "2026-10-04T10:00:01Z out one\n2026-10-04T10:00:03Z out two\n", Stderr: "2026-10-04T10:00:02Z err one\n"})
|
||||
got, err := client(f, 1000).Logs(context.Background(), "web", 2, "30m")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !reflect.DeepEqual(got["lines"], []string{"2026-10-04T10:00:02Z err one", "2026-10-04T10:00:03Z out two"}) {
|
||||
t.Fatalf("%v", got["lines"])
|
||||
}
|
||||
if !f.ran("docker logs --timestamps --tail 2 --since 30m web") {
|
||||
t.Fatalf("%+v", f.calls)
|
||||
}
|
||||
if _, err := client(f, 1000).Logs(context.Background(), "web", 2, "--follow"); err == nil {
|
||||
t.Fatal("since took an option")
|
||||
}
|
||||
f = (&fake{}).on("docker logs", Ran{Status: 1, Stderr: "Error response from daemon: No such container: nope\n"})
|
||||
if _, err := client(f, 1000).Logs(context.Background(), "nope", 2, ""); err == nil {
|
||||
t.Fatal("a missing container read as no lines")
|
||||
}
|
||||
}
|
||||
|
||||
func TestSizesAreReadAsDockerPrintsThem(t *testing.T) {
|
||||
for in, want := range map[string]int64{"0B": 0, "55.63GB": 55630000000, "33.2MiB": 34812723, "1.5kB": 1500, "12MB (34%)": 12000000, "N/A": -1} {
|
||||
if got := Bytes(in); got != want {
|
||||
t.Errorf("%s: %d, want %d", in, got, want)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestDaemonConfigSaysWhatTheDaemonHasNotTakenYet(t *testing.T) {
|
||||
f := (&fake{}).on("docker info", Ran{Stdout: `{"ServerVersion":"29.8.2","LiveRestoreEnabled":false,"LoggingDriver":"json-file","RegistryConfig":{"IndexConfigs":{"docker.io":{"Secure":true},"registry.mesh.internal:5100":{"Secure":false}}}}`})
|
||||
c := client(f, 1000)
|
||||
c.ReadFile = func(string) ([]byte, error) {
|
||||
return []byte(`{"live-restore": true, "dns": ["10.0.0.1"], "log-driver": "local"}`), nil
|
||||
}
|
||||
got, err := c.DaemonConfig(context.Background())
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
pending := strings.Join(got["pending"].([]string), "\n")
|
||||
if !strings.Contains(pending, "live-restore is true in the file and false") || !strings.Contains(pending, "log-driver is local") {
|
||||
t.Errorf("pending: %s", pending)
|
||||
}
|
||||
if !reflect.DeepEqual(got["daemon"].(map[string]any)["InsecureRegistries"], []string{"registry.mesh.internal:5100"}) {
|
||||
t.Errorf("registries: %v", got["daemon"])
|
||||
}
|
||||
if !reflect.DeepEqual(got["read_only_at_start"], []string{"dns", "log-driver"}) {
|
||||
t.Errorf("start-only: %v", got["read_only_at_start"])
|
||||
}
|
||||
c.ReadFile = func(string) ([]byte, error) { return nil, os.ErrNotExist }
|
||||
got, _ = c.DaemonConfig(context.Background())
|
||||
if !strings.HasPrefix(got["file_state"].(string), "absent") {
|
||||
t.Errorf("absent: %v", got["file_state"])
|
||||
}
|
||||
c.ReadFile = func(string) ([]byte, error) { return nil, errors.New("permission denied") }
|
||||
got, _ = c.DaemonConfig(context.Background())
|
||||
if !strings.HasPrefix(got["file_state"].(string), "unreadable") {
|
||||
t.Errorf("unreadable: %v", got["file_state"])
|
||||
}
|
||||
}
|
||||
|
||||
func TestEventsAreABoundedWindowWithoutExecNoise(t *testing.T) {
|
||||
out := `{"Type":"container","Action":"exec_start: pg_isready","Actor":{"ID":"aaaaaaaaaaaaaaaa","Attributes":{"name":"db"}},"timeNano":1}
|
||||
{"Type":"container","Action":"die","Actor":{"ID":"aaaaaaaaaaaaaaaa","Attributes":{"name":"web","mesh-host.id":"hello-web.server","exitCode":"137"}},"timeNano":2}
|
||||
`
|
||||
f := (&fake{}).on("docker events", Ran{Stdout: out})
|
||||
got, err := client(f, 1000).Events(context.Background(), 30, "container", 10, false)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
evs := got["events"].([]map[string]any)
|
||||
if len(evs) != 1 || evs[0]["action"] != "die" || evs[0]["mesh_held"] != true || evs[0]["exit_code"] != "137" {
|
||||
t.Fatalf("%v", evs)
|
||||
}
|
||||
if !f.ran("docker events --since 30m --until 0s --format {{json .}} --filter type=container") {
|
||||
t.Fatalf("%+v", f.calls)
|
||||
}
|
||||
if _, err := client(f, 1000).Events(context.Background(), 30, "secret", 10, false); err == nil {
|
||||
t.Fatal("an unknown type was accepted")
|
||||
}
|
||||
}
|
||||
|
||||
func TestVolumesSayWhoMountsThemAndWhetherTheMeshDoes(t *testing.T) {
|
||||
f := machine().
|
||||
on("docker volume ls --quiet", Ran{Stdout: "webdata\ndbdata\nloose\n"}).
|
||||
on("docker volume inspect", Ran{Stdout: `[{"Name":"webdata","Driver":"local"},{"Name":"dbdata","Driver":"local"},{"Name":"loose","Driver":"local","Labels":{"com.docker.volume.anonymous":""}}]`})
|
||||
got, err := client(f, 1000).Volumes(context.Background(), false, false)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
vols := got["volumes"].([]map[string]any)
|
||||
if vols[0]["mesh_held"] != true || vols[1]["mesh_held"] != false || len(vols[2]["mounted_by"].([]map[string]any)) != 0 || vols[2]["anonymous"] != true {
|
||||
t.Fatalf("%v", vols)
|
||||
}
|
||||
got, _ = client(f, 1000).Volumes(context.Background(), true, false)
|
||||
if got["count"] != 1 {
|
||||
t.Fatalf("unmounted: %v", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestImagesNameTheirUsers(t *testing.T) {
|
||||
f := machine().on("docker image ls", Ran{Stdout: `{"ID":"sha256:img1","Repository":"web","Tag":"1","Size":"100MB"}
|
||||
{"ID":"sha256:img3","Repository":"<none>","Tag":"<none>","Size":"2GB"}
|
||||
`})
|
||||
got, err := client(f, 1000).Images(context.Background(), "", "", 10)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
imgs := got["images"].([]Image)
|
||||
if imgs[0].ID != "sha256:img3" || !imgs[0].Dangling || imgs[1].UsedBy[0] != "mesh-web" || !imgs[1].MeshUsed {
|
||||
t.Fatalf("%+v", imgs)
|
||||
}
|
||||
got, _ = client(f, 1000).Images(context.Background(), "unused", "", 10)
|
||||
if got["count"] != 1 {
|
||||
t.Fatalf("unused: %v", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestProblemsNameWhyAndUnlabelledIsTheCleanupList(t *testing.T) {
|
||||
c := client(machine(), 1000)
|
||||
p, err := c.Problems(context.Background())
|
||||
if err != nil || len(p) != 1 || p[0]["name"] != "dev-db" || p[0]["why"].([]string)[0] != "exited 1" {
|
||||
t.Fatalf("%v %v", p, err)
|
||||
}
|
||||
u, err := c.Unlabelled(context.Background())
|
||||
if err != nil || u["count"] != 1 {
|
||||
t.Fatalf("%v %v", u, err)
|
||||
}
|
||||
}
|
||||
@@ -1,279 +0,0 @@
|
||||
// docker's Go tools bundle (novox/hq ADR 0188, ADR 0193): a process the node's tool runtime launches
|
||||
// and speaks MCP over stdio to, through the Go SDK. It answers for every container on this machine —
|
||||
// the mesh's and every other — and for the runtime's images, networks, volumes, events and
|
||||
// configuration. It runs as the operator account (ADR 0175 §4); docker.go says how it reaches the
|
||||
// daemon's socket. The host applies the module's resources; these tools answer about the runtime.
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"math"
|
||||
"os"
|
||||
"strings"
|
||||
|
||||
stdio "git.novox.be/novox/mesh-sdk/go"
|
||||
)
|
||||
|
||||
func main() {
|
||||
// An empty name serves as the module the runtime names (MESH_SERVED_MODULE): docker.
|
||||
if err := stdio.Serve("", tools(NewClient())); err != nil {
|
||||
fmt.Fprintln(os.Stderr, err)
|
||||
os.Exit(1)
|
||||
}
|
||||
}
|
||||
|
||||
var containerArg = map[string]any{"type": "string", "description": "the container's name or id"}
|
||||
|
||||
func tools(c *Client) []stdio.Tool {
|
||||
ctx := context.Background()
|
||||
act := func(verb, description string) stdio.Tool {
|
||||
return stdio.Tool{
|
||||
Name: "docker_" + verb, Description: description,
|
||||
Input: map[string]any{"container": containerArg},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
ref, err := text(args, "container")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return c.Act(ctx, verb, ref)
|
||||
},
|
||||
}
|
||||
}
|
||||
return []stdio.Tool{
|
||||
{
|
||||
Name: "docker_list",
|
||||
Description: "Every container on this machine — the mesh's and every other — with its image, state, health, restarts, " +
|
||||
"published ports, mounts, compose project, and mesh_held/held_by (the assignment that holds it).",
|
||||
Input: map[string]any{
|
||||
"held": map[string]any{"type": "string", "enum": []string{"all", "mesh", "other"}, "description": "whose: all (default), the mesh's, or the others"},
|
||||
"state": map[string]any{"type": "string", "description": "only containers in this state (running, exited, created, restarting, paused, dead)"},
|
||||
"match": map[string]any{"type": "string", "description": "only containers whose name or image contains this"},
|
||||
},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
list, err := c.Containers(ctx, optional(args, "held"), optional(args, "state"), optional(args, "match"))
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return map[string]any{"count": len(list), "containers": list}, nil
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docker_inspect",
|
||||
Description: "One container whole, as docker inspects it, with mesh_held; its environment's values are left out (names kept), because that is where a container's secrets are.",
|
||||
Input: map[string]any{"container": containerArg},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
ref, err := text(args, "container")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return c.Inspect(ctx, ref)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docker_logs",
|
||||
Description: "The last lines one container wrote, both streams merged in order, each with its timestamp (default 200, at most 2000 lines; a line is cut at 4 KiB).",
|
||||
Input: map[string]any{
|
||||
"container": containerArg,
|
||||
"lines": map[string]any{"type": "integer", "description": "how many lines from the end (default 200, at most 2000)"},
|
||||
"since": map[string]any{"type": "string", "description": "only lines since then: a duration such as 30m or 2h, or a time"},
|
||||
},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
ref, err := text(args, "container")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
n, err := bounded(args, "lines", 200, 2000)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return c.Logs(ctx, ref, n, optional(args, "since"))
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docker_stats",
|
||||
Description: "What the running containers use now — CPU, memory, network and disk I/O, processes — the heaviest by memory first; or one container's.",
|
||||
Input: map[string]any{"container": map[string]any{"type": "string", "description": "one container (optional)"}},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
stats, err := c.Stats(ctx, optional(args, "container"))
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return map[string]any{"count": len(stats), "containers": stats}, nil
|
||||
},
|
||||
},
|
||||
act("start", "Start one container. A container the mesh holds is started too, and the answer says the host restores what its declaration says at its next apply."),
|
||||
act("stop", "Stop one container (ten seconds, then killed). For a container the mesh holds, the answer says the host will start it again at its next apply if its declaration says running."),
|
||||
act("restart", "Restart one container (ten seconds to stop, then killed); the answer says whether the mesh holds it."),
|
||||
{
|
||||
Name: "docker_top",
|
||||
Description: "The processes running inside one container: pid, user, elapsed time, CPU, resident memory and command.",
|
||||
Input: map[string]any{"container": containerArg},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
ref, err := text(args, "container")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return c.Top(ctx, ref)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docker_images",
|
||||
Description: "The images on this machine, the largest first, each with its size and the containers using it (and whether one of them is the mesh's). " +
|
||||
"filter: all, dangling, unused or used.",
|
||||
Input: map[string]any{
|
||||
"filter": map[string]any{"type": "string", "enum": []string{"all", "dangling", "unused", "used"}, "description": "which images (default all)"},
|
||||
"match": map[string]any{"type": "string", "description": "only images whose repository:tag contains this"},
|
||||
"limit": map[string]any{"type": "integer", "description": "how many to show (default 100, at most 1000); count says how many matched"},
|
||||
},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
n, err := bounded(args, "limit", 100, 1000)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return c.Images(ctx, optional(args, "filter"), optional(args, "match"), n)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docker_prune",
|
||||
Description: "Reclaim space: dangling images and unused build cache, and — only when containers is true — stopped containers the mesh does not hold. " +
|
||||
"Never a volume, never a container the mesh holds, never an image a container uses. A dry run by default: it lists what would go; dry_run false removes it.",
|
||||
Input: map[string]any{
|
||||
"dry_run": map[string]any{"type": "boolean", "description": "list only (default true)"},
|
||||
"images": map[string]any{"type": "boolean", "description": "dangling images (default true)"},
|
||||
"build_cache": map[string]any{"type": "boolean", "description": "build cache nothing refers to (default true)"},
|
||||
"containers": map[string]any{"type": "boolean", "description": "stopped containers the mesh does not hold (default false); what they mounted is kept"},
|
||||
"older_than_hours": map[string]any{"type": "integer", "description": "only what is older than this many hours (default 0: any age)"},
|
||||
},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
older := 0
|
||||
if v, ok := args["older_than_hours"]; ok && v != nil && v != float64(0) {
|
||||
n, err := bounded(args, "older_than_hours", 0, 24*365)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
older = n
|
||||
}
|
||||
return c.Prune(ctx, PruneAsk{
|
||||
DryRun: flag(args, "dry_run", true), Images: flag(args, "images", true), BuildCache: flag(args, "build_cache", true),
|
||||
Containers: flag(args, "containers", false), OlderThanH: older,
|
||||
})
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docker_disk_usage",
|
||||
Description: "What the runtime takes on disk (docker system df -v): per kind — images, containers, volumes, build cache — the total, the active and the reclaimable, and the largest of each.",
|
||||
Input: map[string]any{"top": map[string]any{"type": "integer", "description": "how many of the largest per kind (default 10, at most 100)"}},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
n, err := bounded(args, "top", 10, 100)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return c.DiskUsage(ctx, n)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docker_networks",
|
||||
Description: "Every network the runtime has: driver, scope, subnets and gateway, and the running containers on it with their addresses and whether the mesh holds them.",
|
||||
Run: func(map[string]any) (any, error) { return c.Networks(ctx) },
|
||||
},
|
||||
{
|
||||
Name: "docker_volumes",
|
||||
Description: "Every volume with the containers mounting it, whether the mesh holds any of them, whether it is anonymous, its compose project, and — when sizes is true (slower) — its size.",
|
||||
Input: map[string]any{
|
||||
"unmounted": map[string]any{"type": "boolean", "description": "only volumes no container mounts (default false)"},
|
||||
"sizes": map[string]any{"type": "boolean", "description": "measure each volume (default false: it walks every volume)"},
|
||||
},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
return c.Volumes(ctx, flag(args, "unmounted", false), flag(args, "sizes", false))
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docker_events",
|
||||
Description: "What the runtime did in a window ending now (default the last 60 minutes, at most 24 hours): containers created, started, died, health changes, images pulled — with mesh_held. Exec events are left out unless asked.",
|
||||
Input: map[string]any{
|
||||
"minutes": map[string]any{"type": "integer", "description": "how far back (default 60, at most 1440)"},
|
||||
"type": map[string]any{"type": "string", "description": "only one kind: container, image, network, volume, daemon, plugin or builder"},
|
||||
"limit": map[string]any{"type": "integer", "description": "the latest this many (default 200, at most 2000)"},
|
||||
"execs": map[string]any{"type": "boolean", "description": "include exec_* events (default false: health checks make many)"},
|
||||
},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
minutes, err := bounded(args, "minutes", 60, 1440)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
limit, err := bounded(args, "limit", 200, 2000)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return c.Events(ctx, minutes, optional(args, "type"), limit, flag(args, "execs", false))
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docker_daemon_config",
|
||||
Description: "The runtime's configuration: /etc/docker/daemon.json as it is on disk, the daemon's essentials as it runs now (docker info: version, storage and logging drivers, " +
|
||||
"live restore, root directory, insecure registries, warnings), and where the two differ — keys a reload or only a restart would take.",
|
||||
Run: func(map[string]any) (any, error) { return c.DaemonConfig(ctx) },
|
||||
},
|
||||
{
|
||||
Name: "docker_unlabelled",
|
||||
Description: "The containers the mesh does not hold — the cleanup list — each with its image, state, compose project and directory, ports and mounts.",
|
||||
Run: func(map[string]any) (any, error) { return c.Unlabelled(ctx) },
|
||||
},
|
||||
{
|
||||
Name: "docker_problems",
|
||||
Description: "Every container that is not well: unhealthy, restarting, dead, killed for memory, exited with a failure, or restarted five times or more — with whether the mesh holds it.",
|
||||
Run: func(map[string]any) (any, error) {
|
||||
p, err := c.Problems(ctx)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return map[string]any{"count": len(p), "containers": p}, nil
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docker_ports",
|
||||
Description: "Every port the containers publish on this machine (address:port -> container port), and the containers on the host's network, which publish whatever they listen on.",
|
||||
Run: func(map[string]any) (any, error) {
|
||||
p, err := c.Ports(ctx)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return map[string]any{"count": len(p), "ports": p}, nil
|
||||
},
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
func text(args map[string]any, key string) (string, error) {
|
||||
s, _ := args[key].(string)
|
||||
if s = strings.TrimSpace(s); s == "" {
|
||||
return "", fmt.Errorf("%s is required", key)
|
||||
}
|
||||
return s, nil
|
||||
}
|
||||
|
||||
func optional(args map[string]any, key string) string {
|
||||
s, _ := args[key].(string)
|
||||
return strings.TrimSpace(s)
|
||||
}
|
||||
|
||||
func flag(args map[string]any, key string, def bool) bool {
|
||||
if b, ok := args[key].(bool); ok {
|
||||
return b
|
||||
}
|
||||
return def
|
||||
}
|
||||
|
||||
// bounded is a whole number argument, defaulted when absent and held to a ceiling.
|
||||
func bounded(args map[string]any, key string, def, most int) (int, error) {
|
||||
v, ok := args[key]
|
||||
if !ok || v == nil {
|
||||
return def, nil
|
||||
}
|
||||
f, ok := v.(float64)
|
||||
if !ok || f != math.Trunc(f) || f < 1 {
|
||||
return 0, fmt.Errorf("%s must be a whole number of at least 1", key)
|
||||
}
|
||||
return int(math.Min(f, float64(most))), nil
|
||||
}
|
||||
@@ -1,59 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"errors"
|
||||
"fmt"
|
||||
"os/exec"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// Ran is what a command did: its output, its exit status, and why it never ran to an answer.
|
||||
type Ran struct {
|
||||
Stdout string
|
||||
Stderr string
|
||||
Status int
|
||||
// Err is "ENOENT" when the program is not installed, or says it was ended for taking too long.
|
||||
Err string
|
||||
}
|
||||
|
||||
// Runner runs one command, so every tool can be tested without a daemon.
|
||||
type Runner func(ctx context.Context, name string, args ...string) Ran
|
||||
|
||||
// CallTimeout is how long one docker command may take: below the runtime's thirty-second call
|
||||
// limit, so a daemon that hangs is answered as such rather than as a call the runtime gave up on.
|
||||
const CallTimeout = 20 * time.Second
|
||||
|
||||
// ExecRunner runs a command on this machine, bounded by CallTimeout.
|
||||
func ExecRunner(ctx context.Context, name string, args ...string) Ran {
|
||||
ctx, cancel := context.WithTimeout(ctx, CallTimeout)
|
||||
defer cancel()
|
||||
cmd := exec.CommandContext(ctx, name, args...)
|
||||
var out, errb bytes.Buffer
|
||||
cmd.Stdout, cmd.Stderr = &out, &errb
|
||||
err := cmd.Run()
|
||||
r := Ran{Stdout: out.String(), Stderr: errb.String()}
|
||||
var exitErr *exec.ExitError
|
||||
switch {
|
||||
case errors.Is(ctx.Err(), context.DeadlineExceeded):
|
||||
r.Status, r.Err = 124, fmt.Sprintf("no answer within %d s", int(CallTimeout/time.Second))
|
||||
case errors.Is(err, exec.ErrNotFound):
|
||||
r.Status, r.Err = 127, "ENOENT"
|
||||
case errors.As(err, &exitErr):
|
||||
r.Status = exitErr.ExitCode()
|
||||
case err != nil:
|
||||
r.Status, r.Err = 1, err.Error()
|
||||
}
|
||||
return r
|
||||
}
|
||||
|
||||
func firstLine(s string) string {
|
||||
for _, l := range strings.Split(s, "\n") {
|
||||
if l = strings.TrimSpace(l); l != "" {
|
||||
return l
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
@@ -1,60 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"os"
|
||||
"reflect"
|
||||
"sort"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestTheToolsServedAreTheToolsTheManifestNames(t *testing.T) {
|
||||
raw, err := os.ReadFile("../../module.json")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var m struct {
|
||||
Tools []string `json:"tools"`
|
||||
}
|
||||
if err := json.Unmarshal(raw, &m); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
served := []string{}
|
||||
for _, tool := range tools(client(&fake{}, 1000)) {
|
||||
if !strings.HasPrefix(tool.Name, "docker_") || tool.Description == "" || tool.Run == nil {
|
||||
t.Errorf("tool %q", tool.Name)
|
||||
}
|
||||
served = append(served, tool.Name)
|
||||
}
|
||||
sort.Strings(served)
|
||||
listed := append([]string{}, m.Tools...)
|
||||
sort.Strings(listed)
|
||||
if !reflect.DeepEqual(served, listed) {
|
||||
t.Fatalf("served %v, manifest %v", served, listed)
|
||||
}
|
||||
}
|
||||
|
||||
func TestNumbersAreDefaultedAndBounded(t *testing.T) {
|
||||
if n, _ := bounded(map[string]any{}, "lines", 200, 2000); n != 200 {
|
||||
t.Error(n)
|
||||
}
|
||||
if n, _ := bounded(map[string]any{"lines": float64(99999)}, "lines", 200, 2000); n != 2000 {
|
||||
t.Error(n)
|
||||
}
|
||||
for _, bad := range []any{float64(0), float64(-1), float64(1.5), "10"} {
|
||||
if _, err := bounded(map[string]any{"lines": bad}, "lines", 200, 2000); err == nil {
|
||||
t.Errorf("%v accepted", bad)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestAStopFromTheToolNeedsAContainer(t *testing.T) {
|
||||
for _, tool := range tools(client(&fake{}, 1000)) {
|
||||
if tool.Name == "docker_stop" {
|
||||
if _, err := tool.Run(map[string]any{}); err == nil {
|
||||
t.Fatal("a stop without a container was accepted")
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,5 +0,0 @@
|
||||
module docker
|
||||
|
||||
go 1.22
|
||||
|
||||
require git.novox.be/novox/mesh-sdk/go v0.1.6
|
||||
@@ -1,2 +0,0 @@
|
||||
git.novox.be/novox/mesh-sdk/go v0.1.6 h1:9qzdYONYbJdWcu6sxQcq9v1LI0JxcfkiKYkMUzJSkVQ=
|
||||
git.novox.be/novox/mesh-sdk/go v0.1.6/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=
|
||||
@@ -1,94 +0,0 @@
|
||||
{
|
||||
"module": "docker",
|
||||
"version": "1",
|
||||
"capabilities": [
|
||||
"package-manager",
|
||||
"service-manager",
|
||||
"privileged"
|
||||
],
|
||||
"claims": [
|
||||
{
|
||||
"name": "node-container-runtime",
|
||||
"scope": "node"
|
||||
}
|
||||
],
|
||||
"tools": [
|
||||
"docker_list",
|
||||
"docker_inspect",
|
||||
"docker_logs",
|
||||
"docker_stats",
|
||||
"docker_start",
|
||||
"docker_stop",
|
||||
"docker_restart",
|
||||
"docker_top",
|
||||
"docker_images",
|
||||
"docker_prune",
|
||||
"docker_disk_usage",
|
||||
"docker_networks",
|
||||
"docker_volumes",
|
||||
"docker_events",
|
||||
"docker_daemon_config",
|
||||
"docker_unlabelled",
|
||||
"docker_problems",
|
||||
"docker_ports"
|
||||
],
|
||||
"resources": [
|
||||
{
|
||||
"id": "package",
|
||||
"type": "package",
|
||||
"package": "docker"
|
||||
},
|
||||
{
|
||||
"id": "buildx",
|
||||
"type": "package",
|
||||
"package": "docker-buildx"
|
||||
},
|
||||
{
|
||||
"id": "socket",
|
||||
"type": "service",
|
||||
"unit": "docker.socket",
|
||||
"state": "running",
|
||||
"boot": "enabled"
|
||||
},
|
||||
{
|
||||
"id": "prune-service",
|
||||
"type": "file",
|
||||
"path": "/etc/systemd/system/docker-prune.service",
|
||||
"mode": "0644",
|
||||
"content": "# Generated by the mesh. Do not edit — module docker writes this file and replaces it at every push.\n[Unit]\nDescription=Prune dangling images and unused build cache (the mesh's docker module)\n# Never volumes, never a container, never an image a container uses: dangling\n# images and build cache nothing refers to, unused for a week. What a person\n# prunes beyond that is docker_prune's, by hand.\nAfter=docker.service\nConditionPathExists=/run/docker.sock\n\n[Service]\nType=oneshot\nNice=19\nIOSchedulingClass=idle\nExecStart=/usr/bin/docker image prune --force --filter until=168h\nExecStart=/usr/bin/docker builder prune --force --filter until=168h\n"
|
||||
},
|
||||
{
|
||||
"id": "prune-timer",
|
||||
"type": "file",
|
||||
"path": "/etc/systemd/system/docker-prune.timer",
|
||||
"mode": "0644",
|
||||
"content": "# Generated by the mesh. Do not edit — module docker writes this file and replaces it at every push.\n[Unit]\nDescription=Weekly prune of dangling images and unused build cache (the mesh's docker module)\n\n[Timer]\nOnCalendar=weekly\nRandomizedDelaySec=1h\nPersistent=true\n\n[Install]\nWantedBy=timers.target\n"
|
||||
},
|
||||
{
|
||||
"id": "prune",
|
||||
"type": "service",
|
||||
"unit": "docker-prune.timer",
|
||||
"state": "running",
|
||||
"boot": "enabled",
|
||||
"restart-on": [
|
||||
"prune-service",
|
||||
"prune-timer"
|
||||
]
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "tools",
|
||||
"kind": "bundle",
|
||||
"language": "go",
|
||||
"system": "arch",
|
||||
"from": "cmd/docker-tools",
|
||||
"binary": "docker-tools",
|
||||
"loads": [
|
||||
"docker-tools"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -50,6 +50,11 @@
|
||||
"type": "package",
|
||||
"package": "iproute2"
|
||||
},
|
||||
{
|
||||
"id": "sudo",
|
||||
"type": "package",
|
||||
"package": "sudo"
|
||||
},
|
||||
{
|
||||
"id": "npm",
|
||||
"type": "package",
|
||||
|
||||
@@ -1,46 +0,0 @@
|
||||
# localization
|
||||
|
||||
Locale, time zone and console keymap as one module (novox/hq to-be 42 Phase 1, research 027: the
|
||||
operator's choice of one module for the three).
|
||||
|
||||
## What it owns
|
||||
|
||||
- `/etc/locale.conf`, written whole: `LANG=en_US.UTF-8`. It takes effect at the next login.
|
||||
- `/etc/vconsole.conf`, written whole: `KEYMAP=us`. It takes effect at the next boot.
|
||||
- The time zone, `Europe/Brussels`, through a **step**. The host runs the module's own binary once
|
||||
per version of the bundle, as root: `localization-tools set-time-zone Europe/Brussels`. The step
|
||||
asks the time daemon (`timedatectl set-timezone`) only when the zone differs, and reads it back.
|
||||
|
||||
## Why the time zone is a step
|
||||
|
||||
`/etc/localtime` is a symbolic link into the zone database, and the mesh writes no symbolic links
|
||||
(ADR 0012). A copy of the zone file written there works for the C library, but timedatectl and
|
||||
everything else that reads the zone's *name* from the link then answers `n/a`. A module may not
|
||||
declare an action (ADR 0005). The step makes no link itself: the distribution's own time daemon keeps
|
||||
its link, and the step's answer is read back.
|
||||
|
||||
The trade-off: the step runs again only when the bundle changes, not at every push. A zone changed
|
||||
by hand stays changed until then. `localization_get` shows it as not as declared.
|
||||
|
||||
## What it improves
|
||||
|
||||
One machine was on another time zone (the same offset, a different name) with a German console
|
||||
keymap, and nothing recorded why. Every machine is now the same.
|
||||
|
||||
## What it leaves found
|
||||
|
||||
- `/etc/locale.gen` and the generated locales. `en_US.UTF-8` was generated on all four machines on
|
||||
2026-10-04, so the module checks it (`lang_generated`) and does not generate it.
|
||||
- X11's keyboard settings, which belong to the display server's module (research 026).
|
||||
|
||||
On a machine whose `/etc/locale.conf` carried more than `LANG` (one workstation also had
|
||||
`LANGUAGE=en_US`), the extra line goes. `LANG` alone means the same.
|
||||
|
||||
## Tools
|
||||
|
||||
| tool | | answers |
|
||||
|---|---|---|
|
||||
| `localization_get` | r | LANG and every `LC_*`, whether LANG is generated, the zone, whether the RTC keeps local time, NTP on and synchronised, the console keymap, X11 keyboard, and `as_declared` for each of the three |
|
||||
| `localization_time_zone` | r/a | the zone; the zones matching a word; or `set` one (sudo -n timedatectl, read back) |
|
||||
| `localization_locales` | r | generated, enabled in `locale.gen`, LANG and whether it is generated, and the locales glibc can generate (listed when narrowed) |
|
||||
| `localization_keymaps` | r | the keymap in force and the keymaps available, narrowed to a word |
|
||||
@@ -1,340 +0,0 @@
|
||||
package main
|
||||
|
||||
// Locale, time zone and console keymap as one module (novox/hq to-be 42 Phase 1, research 027/02:
|
||||
// the operator's choice of one module for the three). Measured on 2026-10-04, three machines had
|
||||
// en_US.UTF-8, Europe/Brussels and no keymap, and one had another zone and a German keymap with no
|
||||
// record why; the module brings every machine to the first.
|
||||
//
|
||||
// The locale and the keymap are files the host writes whole. The time zone is not a file the mesh
|
||||
// may write: /etc/localtime is a symbolic link into the zone database, and the mesh creates no
|
||||
// symbolic links (ADR 0012). Writing a copy of the zone there instead would leave every tool that
|
||||
// reads the zone's name from the link (timedatectl among them) answering "n/a", and a module may not
|
||||
// declare an action (ADR 0005). So the module's own binary is run once by the host, as root, as a
|
||||
// step (`set-time-zone`, below): it asks the service manager's time daemon to set the zone, which
|
||||
// makes the distribution's own link — the mesh writes none — and reads it back.
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
"regexp"
|
||||
"sort"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// What the module declares: its manifest's files and its step's argument, held to these by a test.
|
||||
const (
|
||||
MeshLang = "en_US.UTF-8"
|
||||
MeshZone = "Europe/Brussels"
|
||||
MeshKeymap = "us"
|
||||
)
|
||||
|
||||
// Settings is the machine's locale, time zone and keymap as its own daemons report them.
|
||||
type Settings struct {
|
||||
Locale map[string]string `json:"locale"`
|
||||
Lang string `json:"lang"`
|
||||
LangGenerated bool `json:"lang_generated"`
|
||||
TimeZone string `json:"time_zone"`
|
||||
LocalRTC bool `json:"rtc_in_local_time"`
|
||||
NTP bool `json:"ntp_enabled"`
|
||||
NTPSynced bool `json:"ntp_synchronized"`
|
||||
Keymap string `json:"console_keymap"`
|
||||
X11 map[string]string `json:"x11,omitempty"`
|
||||
// AsDeclared says, for each of the three, whether the machine is what the module declares.
|
||||
AsDeclared map[string]bool `json:"as_declared"`
|
||||
}
|
||||
|
||||
// Get reads localectl and timedatectl, and whether the locale in force is generated.
|
||||
func (m *Machine) Get() (Settings, error) {
|
||||
s := Settings{Locale: map[string]string{}, X11: map[string]string{}}
|
||||
out, err := m.Out("localectl", "status")
|
||||
if err != nil {
|
||||
return s, err
|
||||
}
|
||||
lc := ParseLocalectl(out)
|
||||
s.Locale, s.Keymap, s.X11 = lc.Locale, lc.Keymap, lc.X11
|
||||
s.Lang = s.Locale["LANG"]
|
||||
td, err := m.Out("timedatectl", "show")
|
||||
if err != nil {
|
||||
return s, err
|
||||
}
|
||||
kv := keyValues(td, "=")
|
||||
s.TimeZone = kv["Timezone"]
|
||||
s.LocalRTC = kv["LocalRTC"] == "yes"
|
||||
s.NTP = kv["NTP"] == "yes"
|
||||
s.NTPSynced = kv["NTPSynchronized"] == "yes"
|
||||
gen, err := m.Out("locale", "-a")
|
||||
if err != nil {
|
||||
return s, err
|
||||
}
|
||||
s.LangGenerated = generated(lines(gen), s.Lang)
|
||||
s.AsDeclared = map[string]bool{
|
||||
"locale": s.Lang == MeshLang && s.LangGenerated,
|
||||
"time_zone": s.TimeZone == MeshZone,
|
||||
"keymap": s.Keymap == MeshKeymap,
|
||||
}
|
||||
return s, nil
|
||||
}
|
||||
|
||||
// Localectl is `localectl status` read: the system locale's variables, the console keymap and the
|
||||
// X11 keyboard settings.
|
||||
type Localectl struct {
|
||||
Locale map[string]string
|
||||
Keymap string
|
||||
X11 map[string]string
|
||||
}
|
||||
|
||||
// ParseLocalectl reads `localectl status`. The locale's variables continue on lines of their own
|
||||
// beneath its label; "(unset)" is said as empty.
|
||||
func ParseLocalectl(out string) Localectl {
|
||||
l := Localectl{Locale: map[string]string{}, X11: map[string]string{}}
|
||||
label := ""
|
||||
for _, raw := range strings.Split(out, "\n") {
|
||||
line := strings.TrimSpace(raw)
|
||||
if line == "" {
|
||||
continue
|
||||
}
|
||||
value := line
|
||||
if k, v, ok := strings.Cut(line, ": "); ok && !strings.Contains(k, "=") {
|
||||
label, value = strings.TrimSpace(k), strings.TrimSpace(v)
|
||||
}
|
||||
if value == "(unset)" || value == "n/a" {
|
||||
value = ""
|
||||
}
|
||||
switch {
|
||||
case label == "System Locale":
|
||||
if k, v, ok := strings.Cut(value, "="); ok {
|
||||
l.Locale[k] = v
|
||||
}
|
||||
case label == "VC Keymap":
|
||||
l.Keymap = value
|
||||
case strings.HasPrefix(label, "X11 "):
|
||||
if value != "" {
|
||||
l.X11[strings.ToLower(strings.TrimPrefix(label, "X11 "))] = value
|
||||
}
|
||||
}
|
||||
}
|
||||
return l
|
||||
}
|
||||
|
||||
// normal is a locale's name as glibc compares it: the codeset lowercased without dashes, so
|
||||
// en_US.UTF-8 in a file and en_US.utf8 in `locale -a` are the same locale.
|
||||
func normal(name string) string {
|
||||
lang, codeset, ok := strings.Cut(name, ".")
|
||||
if !ok {
|
||||
return name
|
||||
}
|
||||
mod := ""
|
||||
if c, at, found := strings.Cut(codeset, "@"); found {
|
||||
codeset, mod = c, "@"+at
|
||||
}
|
||||
return lang + "." + strings.ToLower(strings.ReplaceAll(codeset, "-", "")) + mod
|
||||
}
|
||||
|
||||
func generated(have []string, want string) bool {
|
||||
if want == "" {
|
||||
return false
|
||||
}
|
||||
for _, h := range have {
|
||||
if normal(strings.TrimSpace(h)) == normal(want) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// Zone is the time zone tool's answer.
|
||||
type Zone struct {
|
||||
TimeZone string `json:"time_zone"`
|
||||
Before string `json:"before,omitempty"`
|
||||
Changed bool `json:"changed"`
|
||||
Declared string `json:"declared"`
|
||||
Zones []string `json:"zones,omitempty"`
|
||||
Count int `json:"zones_matching,omitempty"`
|
||||
Note string `json:"note,omitempty"`
|
||||
}
|
||||
|
||||
func (m *Machine) zone() (string, error) {
|
||||
out, err := m.Out("timedatectl", "show", "--property=Timezone", "--value")
|
||||
return strings.TrimSpace(out), err
|
||||
}
|
||||
|
||||
func (m *Machine) zones() ([]string, error) {
|
||||
out, err := m.Out("timedatectl", "list-timezones")
|
||||
return lines(out), err
|
||||
}
|
||||
|
||||
// TimeZone reads the zone, lists the zones matching a word, or sets one. Setting goes through the
|
||||
// time daemon with sudo -n, which polkit would otherwise refuse to an account without a session.
|
||||
func (m *Machine) TimeZone(set, match string) (Zone, error) {
|
||||
z := Zone{Declared: MeshZone}
|
||||
current, err := m.zone()
|
||||
if err != nil {
|
||||
return z, err
|
||||
}
|
||||
z.TimeZone = current
|
||||
if match != "" {
|
||||
all, err := m.zones()
|
||||
if err != nil {
|
||||
return z, err
|
||||
}
|
||||
for _, name := range all {
|
||||
if strings.Contains(strings.ToLower(name), strings.ToLower(match)) {
|
||||
z.Zones = append(z.Zones, name)
|
||||
}
|
||||
}
|
||||
z.Count = len(z.Zones)
|
||||
if len(z.Zones) > 200 {
|
||||
z.Zones = z.Zones[:200]
|
||||
}
|
||||
}
|
||||
if set == "" {
|
||||
return z, nil
|
||||
}
|
||||
all, err := m.zones()
|
||||
if err != nil {
|
||||
return z, err
|
||||
}
|
||||
if !contains(all, set) {
|
||||
return z, fmt.Errorf("%q is not a time zone this machine knows (timedatectl list-timezones)", set)
|
||||
}
|
||||
z.Before = current
|
||||
if set != current {
|
||||
if _, err := m.Root("timedatectl", "set-timezone", set); err != nil {
|
||||
return z, err
|
||||
}
|
||||
after, err := m.zone()
|
||||
if err != nil {
|
||||
return z, err
|
||||
}
|
||||
if after != set {
|
||||
return z, fmt.Errorf("the time zone was set to %s and reads back as %s", set, after)
|
||||
}
|
||||
z.TimeZone, z.Changed = after, true
|
||||
}
|
||||
if set != MeshZone {
|
||||
z.Note = fmt.Sprintf("the module declares %s; its step sets that zone again whenever the module's bundle changes", MeshZone)
|
||||
}
|
||||
return z, nil
|
||||
}
|
||||
|
||||
func contains(list []string, want string) bool {
|
||||
for _, s := range list {
|
||||
if s == want {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// Locales is what this machine can, may and does use.
|
||||
type Locales struct {
|
||||
Lang string `json:"lang"`
|
||||
LangGenerated bool `json:"lang_generated"`
|
||||
Generated []string `json:"generated"`
|
||||
Enabled []string `json:"enabled_in_locale_gen"`
|
||||
Available []string `json:"available,omitempty"`
|
||||
AvailableCount int `json:"available_count"`
|
||||
}
|
||||
|
||||
// Locales reads `locale -a`, the uncommented lines of /etc/locale.gen, and the locales glibc can
|
||||
// generate (/usr/share/i18n/SUPPORTED) — listed when a word narrows them, counted otherwise.
|
||||
func (m *Machine) Locales(match string) (Locales, error) {
|
||||
l := Locales{Generated: []string{}, Enabled: []string{}}
|
||||
gen, err := m.Out("locale", "-a")
|
||||
if err != nil {
|
||||
return l, err
|
||||
}
|
||||
l.Generated = lines(gen)
|
||||
if conf, err := m.ReadFile("/etc/locale.conf"); err == nil {
|
||||
l.Lang = keyValues(string(conf), "=")["LANG"]
|
||||
} else if !os.IsNotExist(err) {
|
||||
return l, err
|
||||
}
|
||||
l.LangGenerated = generated(l.Generated, l.Lang)
|
||||
if gen, err := m.ReadFile("/etc/locale.gen"); err == nil {
|
||||
for _, line := range lines(string(gen)) {
|
||||
if line = strings.TrimSpace(line); !strings.HasPrefix(line, "#") {
|
||||
l.Enabled = append(l.Enabled, line)
|
||||
}
|
||||
}
|
||||
}
|
||||
supported, err := m.ReadFile("/usr/share/i18n/SUPPORTED")
|
||||
if err != nil && !os.IsNotExist(err) {
|
||||
return l, err
|
||||
}
|
||||
for _, line := range lines(string(supported)) {
|
||||
name := strings.Fields(line)[0]
|
||||
l.AvailableCount++
|
||||
if match != "" && strings.Contains(strings.ToLower(name), strings.ToLower(match)) {
|
||||
l.Available = append(l.Available, strings.TrimSpace(line))
|
||||
}
|
||||
}
|
||||
return l, nil
|
||||
}
|
||||
|
||||
// Keymaps is the console keymaps this machine has.
|
||||
type Keymaps struct {
|
||||
Current string `json:"current"`
|
||||
Keymaps []string `json:"keymaps"`
|
||||
Count int `json:"count"`
|
||||
}
|
||||
|
||||
var keymapName = regexp.MustCompile(`^[A-Za-z0-9_.+-]+$`)
|
||||
|
||||
// Keymaps lists `localectl list-keymaps`, narrowed to a word when one is given.
|
||||
func (m *Machine) Keymaps(match string) (Keymaps, error) {
|
||||
k := Keymaps{Keymaps: []string{}}
|
||||
status, err := m.Out("localectl", "status")
|
||||
if err != nil {
|
||||
return k, err
|
||||
}
|
||||
k.Current = ParseLocalectl(status).Keymap
|
||||
out, err := m.Out("localectl", "list-keymaps", "--no-pager")
|
||||
if err != nil {
|
||||
return k, err
|
||||
}
|
||||
for _, name := range lines(out) {
|
||||
name = strings.TrimSpace(name)
|
||||
if !keymapName.MatchString(name) {
|
||||
continue
|
||||
}
|
||||
if match == "" || strings.Contains(strings.ToLower(name), strings.ToLower(match)) {
|
||||
k.Keymaps = append(k.Keymaps, name)
|
||||
}
|
||||
}
|
||||
sort.Strings(k.Keymaps)
|
||||
k.Count = len(k.Keymaps)
|
||||
if len(k.Keymaps) > 500 {
|
||||
k.Keymaps = k.Keymaps[:500]
|
||||
}
|
||||
return k, nil
|
||||
}
|
||||
|
||||
// SetTimeZoneStep is the module's step, run once by the host as root: the zone set through the time
|
||||
// daemon when it differs, and read back. It changes nothing on a machine already in the zone.
|
||||
func (m *Machine) SetTimeZoneStep(zone string) (string, error) {
|
||||
if zone == "" || strings.HasPrefix(zone, "-") || strings.Contains(zone, "..") {
|
||||
return "", fmt.Errorf("%q is not a time zone", zone)
|
||||
}
|
||||
if _, err := m.ReadFile("/usr/share/zoneinfo/" + zone); err != nil {
|
||||
return "", fmt.Errorf("%s is not in this machine's zone database: %v", zone, err)
|
||||
}
|
||||
current, err := m.zone()
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
if current == zone {
|
||||
return fmt.Sprintf("the time zone is already %s", zone), nil
|
||||
}
|
||||
if _, err := m.Root("timedatectl", "set-timezone", zone); err != nil {
|
||||
return "", err
|
||||
}
|
||||
after, err := m.zone()
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
if after != zone {
|
||||
return "", fmt.Errorf("the time zone was set to %s and reads back as %s", zone, after)
|
||||
}
|
||||
return fmt.Sprintf("the time zone was %s and is now %s", current, zone), nil
|
||||
}
|
||||
@@ -1,177 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
const localectlLaptop = `System Locale: LANG=en_US.UTF-8
|
||||
LANGUAGE=en_US
|
||||
VC Keymap: (unset)
|
||||
X11 Layout: (unset)
|
||||
`
|
||||
|
||||
const localectlAnchor = `System Locale: LANG=en_US.UTF-8
|
||||
LC_TIME=nl_BE.UTF-8
|
||||
VC Keymap: de-latin1-nodeadkeys
|
||||
X11 Layout: de
|
||||
X11 Model: pc105
|
||||
`
|
||||
|
||||
func TestLocalectlIsReadWithItsContinuationLinesAndUnsetAsEmpty(t *testing.T) {
|
||||
l := ParseLocalectl(localectlLaptop)
|
||||
if l.Locale["LANG"] != "en_US.UTF-8" || l.Locale["LANGUAGE"] != "en_US" || l.Keymap != "" || len(l.X11) != 0 {
|
||||
t.Fatalf("%+v", l)
|
||||
}
|
||||
a := ParseLocalectl(localectlAnchor)
|
||||
if a.Locale["LC_TIME"] != "nl_BE.UTF-8" || a.Keymap != "de-latin1-nodeadkeys" || a.X11["layout"] != "de" || a.X11["model"] != "pc105" {
|
||||
t.Fatalf("%+v", a)
|
||||
}
|
||||
}
|
||||
|
||||
func TestALocaleIsGeneratedWhateverTheCodesetsSpelling(t *testing.T) {
|
||||
have := []string{"C", "C.utf8", "POSIX", "en_US.utf8", "nl_BE.utf8@euro"}
|
||||
if !generated(have, "en_US.UTF-8") || generated(have, "de_DE.UTF-8") || generated(have, "") || !generated(have, "nl_BE.UTF-8@euro") {
|
||||
t.Fatal("generated")
|
||||
}
|
||||
}
|
||||
|
||||
func getMachine(zone, keymapStatus string) *Machine {
|
||||
return machine(byLine(map[string]Ran{
|
||||
"localectl status": {Stdout: keymapStatus},
|
||||
"timedatectl show": {Stdout: "Timezone=" + zone + "\nLocalRTC=no\nCanNTP=yes\nNTP=yes\nNTPSynchronized=yes\n"},
|
||||
"locale -a": {Stdout: "C\nC.utf8\nPOSIX\nen_US.utf8\n"},
|
||||
}, nil), 1000)
|
||||
}
|
||||
|
||||
func TestGetSaysWhetherEachOfTheThreeIsAsDeclared(t *testing.T) {
|
||||
s, err := getMachine("Europe/Berlin", localectlAnchor).Get()
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if s.TimeZone != "Europe/Berlin" || !s.NTP || !s.NTPSynced || s.LocalRTC || s.Keymap != "de-latin1-nodeadkeys" || !s.LangGenerated {
|
||||
t.Fatalf("%+v", s)
|
||||
}
|
||||
if !s.AsDeclared["locale"] || s.AsDeclared["time_zone"] || s.AsDeclared["keymap"] {
|
||||
t.Fatalf("as declared: %v", s.AsDeclared)
|
||||
}
|
||||
s, _ = getMachine("Europe/Brussels", strings.Replace(localectlLaptop, "VC Keymap: (unset)", "VC Keymap: us", 1)).Get()
|
||||
if !s.AsDeclared["locale"] || !s.AsDeclared["time_zone"] || !s.AsDeclared["keymap"] {
|
||||
t.Fatalf("as declared: %v", s.AsDeclared)
|
||||
}
|
||||
}
|
||||
|
||||
func zoneMachine(zones *[]string, calls *[]call) *Machine {
|
||||
current := "Europe/Berlin"
|
||||
return machine(fake(func(c call) Ran {
|
||||
switch c.String() {
|
||||
case "timedatectl show --property=Timezone --value":
|
||||
return Ran{Stdout: current + "\n"}
|
||||
case "timedatectl list-timezones":
|
||||
return Ran{Stdout: strings.Join(*zones, "\n") + "\n"}
|
||||
case "sudo -n timedatectl set-timezone Europe/Brussels", "timedatectl set-timezone Europe/Brussels":
|
||||
current = "Europe/Brussels"
|
||||
return Ran{}
|
||||
case "sudo -n timedatectl set-timezone Europe/Paris":
|
||||
current = "Europe/Paris"
|
||||
return Ran{}
|
||||
}
|
||||
return Ran{Status: 99, Stderr: "unexpected: " + c.String()}
|
||||
}, calls), 1000)
|
||||
}
|
||||
|
||||
func TestSettingTheZoneEscalatesIsReadBackAndRefusesAnUnknownZone(t *testing.T) {
|
||||
zones := []string{"Europe/Berlin", "Europe/Brussels", "Europe/Paris"}
|
||||
var calls []call
|
||||
m := zoneMachine(&zones, &calls)
|
||||
z, err := m.TimeZone("Europe/Brussels", "")
|
||||
if err != nil || !z.Changed || z.Before != "Europe/Berlin" || z.TimeZone != "Europe/Brussels" || z.Note != "" {
|
||||
t.Fatalf("%+v %v", z, err)
|
||||
}
|
||||
if _, err := m.TimeZone("Mars/Olympus", ""); err == nil || !strings.Contains(err.Error(), "not a time zone this machine knows") {
|
||||
t.Fatalf("an unknown zone: %v", err)
|
||||
}
|
||||
z, err = m.TimeZone("Europe/Paris", "")
|
||||
if err != nil || !strings.Contains(z.Note, "declares Europe/Brussels") {
|
||||
t.Fatalf("another zone than the declared one is said: %+v %v", z, err)
|
||||
}
|
||||
z, _ = m.TimeZone("", "bru")
|
||||
if z.Count != 1 || z.Zones[0] != "Europe/Brussels" || z.Changed {
|
||||
t.Fatalf("match: %+v", z)
|
||||
}
|
||||
}
|
||||
|
||||
func TestTheStepSetsTheZoneOnlyWhenItDiffersAsRoot(t *testing.T) {
|
||||
zones := []string{"Europe/Brussels"}
|
||||
var calls []call
|
||||
m := zoneMachine(&zones, &calls)
|
||||
m.UID = 0
|
||||
m.ReadFile = func(p string) ([]byte, error) {
|
||||
if p == "/usr/share/zoneinfo/Europe/Brussels" {
|
||||
return []byte("TZif"), nil
|
||||
}
|
||||
return nil, errNoFile
|
||||
}
|
||||
said, err := m.SetTimeZoneStep("Europe/Brussels")
|
||||
if err != nil || said != "the time zone was Europe/Berlin and is now Europe/Brussels" {
|
||||
t.Fatalf("%q %v", said, err)
|
||||
}
|
||||
for _, c := range calls {
|
||||
if c.name == "sudo" {
|
||||
t.Fatal("the step runs as root and does not go through sudo")
|
||||
}
|
||||
}
|
||||
calls = nil
|
||||
said, err = m.SetTimeZoneStep("Europe/Brussels")
|
||||
if err != nil || !strings.Contains(said, "already") {
|
||||
t.Fatalf("%q %v", said, err)
|
||||
}
|
||||
for _, c := range calls {
|
||||
if strings.Contains(c.String(), "set-timezone") {
|
||||
t.Fatal("a machine already in the zone was set again")
|
||||
}
|
||||
}
|
||||
if _, err := m.SetTimeZoneStep("Nowhere/Here"); err == nil {
|
||||
t.Fatal("a zone not in the database was set")
|
||||
}
|
||||
if _, err := m.SetTimeZoneStep("../etc"); err == nil {
|
||||
t.Fatal("a path was taken for a zone")
|
||||
}
|
||||
}
|
||||
|
||||
func TestLocalesAreListedAndAvailableOnesOnlyWhenNarrowed(t *testing.T) {
|
||||
files := map[string]string{
|
||||
"/etc/locale.conf": "LANG=en_US.UTF-8\n",
|
||||
"/etc/locale.gen": "# en_US.UTF-8 UTF-8\nen_US.UTF-8 UTF-8 \n#nl_BE.UTF-8 UTF-8\n",
|
||||
"/usr/share/i18n/SUPPORTED": "en_US.UTF-8 UTF-8\nen_US ISO-8859-1\nnl_BE.UTF-8 UTF-8\n",
|
||||
}
|
||||
m := machine(byLine(map[string]Ran{"locale -a": {Stdout: "C\nen_US.utf8\n"}}, nil), 1000)
|
||||
m.ReadFile = func(p string) ([]byte, error) {
|
||||
if s, ok := files[p]; ok {
|
||||
return []byte(s), nil
|
||||
}
|
||||
return nil, errNoFile
|
||||
}
|
||||
l, err := m.Locales("")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if l.Lang != "en_US.UTF-8" || !l.LangGenerated || len(l.Enabled) != 1 || l.AvailableCount != 3 || l.Available != nil {
|
||||
t.Fatalf("%+v", l)
|
||||
}
|
||||
l, _ = m.Locales("nl_")
|
||||
if len(l.Available) != 1 || l.Available[0] != "nl_BE.UTF-8 UTF-8" {
|
||||
t.Fatalf("%+v", l.Available)
|
||||
}
|
||||
}
|
||||
|
||||
func TestKeymapsAreNarrowedAndTheCurrentOneSaid(t *testing.T) {
|
||||
m := machine(byLine(map[string]Ran{
|
||||
"localectl status": {Stdout: localectlAnchor},
|
||||
"localectl list-keymaps --no-pager": {Stdout: "be-latin1\nde-latin1\nde-latin1-nodeadkeys\nus\n"},
|
||||
}, nil), 1000)
|
||||
k, err := m.Keymaps("de")
|
||||
if err != nil || k.Current != "de-latin1-nodeadkeys" || k.Count != 2 {
|
||||
t.Fatalf("%+v %v", k, err)
|
||||
}
|
||||
}
|
||||
@@ -1,288 +0,0 @@
|
||||
package main
|
||||
|
||||
// The commands this bundle runs on its machine, and who runs them.
|
||||
//
|
||||
// Who asks. The node's tool runtime runs as the operator account, not root (novox/hq ADR 0175 §4),
|
||||
// and launches this binary as a process of its own (ADR 0188, ADR 0193) with the runtime's words —
|
||||
// HOME, a PATH, MESH_OPERATOR_ACCOUNT — and no session words. Reading needs nothing more; what only
|
||||
// root may do goes through `sudo -n`, as the packet filter's, the service manager's and the
|
||||
// intrusion prevention's tools do (to-be 38 WP4), and the `sudo` module is what declares that the
|
||||
// account may (to-be 42, research 027). A refusal is named by how it failed, never read as an
|
||||
// empty answer.
|
||||
//
|
||||
// The runner is injected, so every tool is tested over a fake one without the machine.
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"errors"
|
||||
"fmt"
|
||||
"io/fs"
|
||||
"os"
|
||||
"os/exec"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// Ran is what one command did: its output, its exit status, and why it never ran to an answer.
|
||||
type Ran struct {
|
||||
Stdout string
|
||||
Stderr string
|
||||
Status int
|
||||
// Err is "ENOENT" when the program is not there, or that it was ended for taking too long.
|
||||
Err string
|
||||
}
|
||||
|
||||
// Runner runs one command, so the tools can be tested without the machine.
|
||||
type Runner func(ctx context.Context, name string, args ...string) Ran
|
||||
|
||||
// CallTimeout is how long one command may take: below the runtime's thirty-second call limit, so a
|
||||
// command that hangs is answered as such rather than as a call the runtime gave up on.
|
||||
const CallTimeout = 20 * time.Second
|
||||
|
||||
// outputLimit bounds what one command may hand back, so a runaway listing cannot exhaust the
|
||||
// process; well above anything a tool answers.
|
||||
const outputLimit = 16 << 20
|
||||
|
||||
type bounded struct {
|
||||
bytes.Buffer
|
||||
cut bool
|
||||
}
|
||||
|
||||
func (b *bounded) Write(p []byte) (int, error) {
|
||||
if room := outputLimit - b.Len(); room < len(p) {
|
||||
if room > 0 {
|
||||
b.Buffer.Write(p[:room])
|
||||
}
|
||||
b.cut = true
|
||||
return len(p), nil
|
||||
}
|
||||
return b.Buffer.Write(p)
|
||||
}
|
||||
|
||||
// ExecRunner runs a command on this machine, in the C locale so what is parsed is one language.
|
||||
func ExecRunner(ctx context.Context, name string, args ...string) Ran {
|
||||
ctx, cancel := context.WithTimeout(ctx, CallTimeout)
|
||||
defer cancel()
|
||||
cmd := exec.CommandContext(ctx, name, args...)
|
||||
cmd.Env = append(os.Environ(), "LC_ALL=C")
|
||||
var out, errb bounded
|
||||
cmd.Stdout, cmd.Stderr = &out, &errb
|
||||
err := cmd.Run()
|
||||
r := Ran{Stdout: out.String(), Stderr: errb.String()}
|
||||
if ctx.Err() == context.DeadlineExceeded {
|
||||
r.Status, r.Err = 124, fmt.Sprintf("no answer within %d s", int(CallTimeout.Seconds()))
|
||||
return r
|
||||
}
|
||||
var exit *exec.ExitError
|
||||
switch {
|
||||
case err == nil:
|
||||
case errors.As(err, &exit):
|
||||
r.Status = exit.ExitCode()
|
||||
case errors.Is(err, exec.ErrNotFound) || errors.Is(err, fs.ErrNotExist):
|
||||
r.Status, r.Err = 127, "ENOENT"
|
||||
default:
|
||||
r.Status, r.Err = 126, err.Error()
|
||||
}
|
||||
return r
|
||||
}
|
||||
|
||||
// Escalated is the command as it is run: as given when this process is root, else through sudo
|
||||
// without a prompt.
|
||||
func Escalated(uid int, name string, args ...string) (string, []string) {
|
||||
if uid == 0 {
|
||||
return name, args
|
||||
}
|
||||
return "sudo", append([]string{"-n", name}, args...)
|
||||
}
|
||||
|
||||
// Machine is this machine as the tools see it: a runner, who this process is, and its files.
|
||||
type Machine struct {
|
||||
Run Runner
|
||||
UID int
|
||||
User string
|
||||
Account string
|
||||
ReadFile func(path string) ([]byte, error)
|
||||
Now func() time.Time
|
||||
}
|
||||
|
||||
// ThisMachine is the machine the runtime launched this bundle on.
|
||||
func ThisMachine() *Machine {
|
||||
user := os.Getenv("USER")
|
||||
if user == "" {
|
||||
user = os.Getenv("LOGNAME")
|
||||
}
|
||||
account := strings.TrimSpace(os.Getenv("MESH_OPERATOR_ACCOUNT"))
|
||||
if account == "" {
|
||||
account = user
|
||||
}
|
||||
return &Machine{Run: ExecRunner, UID: os.Getuid(), User: user, Account: account, ReadFile: os.ReadFile, Now: time.Now}
|
||||
}
|
||||
|
||||
// Out runs a command that only reads, and fails with what went wrong named.
|
||||
func (m *Machine) Out(name string, args ...string) (string, error) {
|
||||
r := m.Run(context.Background(), name, args...)
|
||||
if r.Status == 0 && r.Err == "" {
|
||||
return r.Stdout, nil
|
||||
}
|
||||
return r.Stdout, failure(name, name, r)
|
||||
}
|
||||
|
||||
// Root runs a command that needs root, escalated when this process is not.
|
||||
func (m *Machine) Root(name string, args ...string) (string, error) {
|
||||
program, argv := Escalated(m.UID, name, args...)
|
||||
r := m.Run(context.Background(), program, argv...)
|
||||
if r.Status == 0 && r.Err == "" {
|
||||
return r.Stdout, nil
|
||||
}
|
||||
return r.Stdout, failure(name, program, r)
|
||||
}
|
||||
|
||||
// RootRan is Root's raw answer, for a command whose non-zero status is itself an answer.
|
||||
func (m *Machine) RootRan(name string, args ...string) (Ran, error) {
|
||||
program, argv := Escalated(m.UID, name, args...)
|
||||
r := m.Run(context.Background(), program, argv...)
|
||||
if r.Err != "" || (program == "sudo" && sudoRefused(r)) {
|
||||
return r, failure(name, program, r)
|
||||
}
|
||||
return r, nil
|
||||
}
|
||||
|
||||
func sudoRefused(r Ran) bool {
|
||||
return strings.HasPrefix(strings.TrimSpace(r.Stderr), "sudo:")
|
||||
}
|
||||
|
||||
// failure names what failed by how it failed: the program missing is a spawn error, sudo missing
|
||||
// or refusing speaks for itself, and the rest is the command's own first line.
|
||||
func failure(cmd, program string, r Ran) error {
|
||||
said := strings.TrimSpace(r.Stderr + "\n" + r.Stdout)
|
||||
if r.Err == "ENOENT" {
|
||||
if program == "sudo" {
|
||||
return fmt.Errorf("%s needs root for this, and sudo is not installed here for the runtime's account to escalate with", cmd)
|
||||
}
|
||||
return fmt.Errorf("%s is not installed on this machine", cmd)
|
||||
}
|
||||
if r.Err != "" {
|
||||
return fmt.Errorf("%s did not answer: %s", cmd, r.Err)
|
||||
}
|
||||
if program == "sudo" && sudoRefused(r) {
|
||||
if strings.Contains(said, "command not found") {
|
||||
return fmt.Errorf("%s is not installed on this machine", cmd)
|
||||
}
|
||||
return fmt.Errorf("%s needs root for this and the runtime's account may not run it without a prompt: %s", cmd, firstLine(said))
|
||||
}
|
||||
if line := firstLine(said); line != "" {
|
||||
return fmt.Errorf("%s failed (%d): %s", cmd, r.Status, line)
|
||||
}
|
||||
return fmt.Errorf("%s failed with status %d", cmd, r.Status)
|
||||
}
|
||||
|
||||
func firstLine(text string) string {
|
||||
for _, l := range strings.Split(text, "\n") {
|
||||
if l = strings.TrimSpace(l); l != "" {
|
||||
return l
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
func lines(text string) []string {
|
||||
var out []string
|
||||
for _, l := range strings.Split(text, "\n") {
|
||||
if l = strings.TrimRight(l, "\r"); strings.TrimSpace(l) != "" {
|
||||
out = append(out, l)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// text is a string argument; required says whether it may be absent. It is never something a
|
||||
// command would read as an option, which under sudo would be root's option.
|
||||
func text(args map[string]any, key string, required bool) (string, error) {
|
||||
raw, present := args[key]
|
||||
if !present || raw == nil {
|
||||
if required {
|
||||
return "", fmt.Errorf("%s is required", key)
|
||||
}
|
||||
return "", nil
|
||||
}
|
||||
s, ok := raw.(string)
|
||||
if !ok {
|
||||
return "", fmt.Errorf("%s must be a string", key)
|
||||
}
|
||||
s = strings.TrimSpace(s)
|
||||
if required && s == "" {
|
||||
return "", fmt.Errorf("%s is required", key)
|
||||
}
|
||||
if strings.HasPrefix(s, "-") || strings.ContainsRune(s, 0) || strings.ContainsAny(s, "\n\r") {
|
||||
return "", fmt.Errorf("%s %q is not a value this tool passes on", key, s)
|
||||
}
|
||||
return s, nil
|
||||
}
|
||||
|
||||
// whole is a whole-number argument with a default, kept within bounds.
|
||||
func whole(args map[string]any, key string, def, least, most int) (int, error) {
|
||||
raw, present := args[key]
|
||||
if !present || raw == nil {
|
||||
return def, nil
|
||||
}
|
||||
f, ok := raw.(float64)
|
||||
if !ok || f != float64(int(f)) {
|
||||
return 0, fmt.Errorf("%s must be a whole number", key)
|
||||
}
|
||||
n := int(f)
|
||||
if n < least {
|
||||
return 0, fmt.Errorf("%s must be at least %d", key, least)
|
||||
}
|
||||
if n > most {
|
||||
n = most
|
||||
}
|
||||
return n, nil
|
||||
}
|
||||
|
||||
// flag is a boolean argument, false when absent.
|
||||
func flag(args map[string]any, key string) (bool, error) {
|
||||
raw, present := args[key]
|
||||
if !present || raw == nil {
|
||||
return false, nil
|
||||
}
|
||||
b, ok := raw.(bool)
|
||||
if !ok {
|
||||
return false, fmt.Errorf("%s must be true or false", key)
|
||||
}
|
||||
return b, nil
|
||||
}
|
||||
|
||||
// schema is a tool's input: its properties and the ones it requires.
|
||||
func schema(properties map[string]any, required ...string) map[string]any {
|
||||
s := map[string]any{"type": "object", "properties": properties}
|
||||
if len(required) > 0 {
|
||||
s["required"] = required
|
||||
}
|
||||
return s
|
||||
}
|
||||
|
||||
// unitProps reads a unit's properties as systemctl shows them.
|
||||
func (m *Machine) unitProps(unit string, props ...string) (map[string]string, error) {
|
||||
args := []string{"show", unit, "--no-pager"}
|
||||
for _, p := range props {
|
||||
args = append(args, "--property="+p)
|
||||
}
|
||||
out, err := m.Out("systemctl", args...)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return keyValues(out, "="), nil
|
||||
}
|
||||
|
||||
// keyValues reads `key<sep>value` lines; a line without the separator is skipped.
|
||||
func keyValues(out, sep string) map[string]string {
|
||||
kv := map[string]string{}
|
||||
for _, l := range strings.Split(out, "\n") {
|
||||
k, v, ok := strings.Cut(l, sep)
|
||||
if ok {
|
||||
kv[strings.TrimSpace(k)] = strings.TrimSpace(v)
|
||||
}
|
||||
}
|
||||
return kv
|
||||
}
|
||||
@@ -1,106 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
// call is one command a fake runner was asked to run.
|
||||
type call struct {
|
||||
name string
|
||||
args []string
|
||||
}
|
||||
|
||||
func (c call) String() string {
|
||||
if len(c.args) == 0 {
|
||||
return c.name
|
||||
}
|
||||
return c.name + " " + strings.Join(c.args, " ")
|
||||
}
|
||||
|
||||
// fake is a runner answering by the command line it is given, recording every call.
|
||||
func fake(answer func(c call) Ran, calls *[]call) Runner {
|
||||
return func(_ context.Context, name string, args ...string) Ran {
|
||||
c := call{name, append([]string(nil), args...)}
|
||||
if calls != nil {
|
||||
*calls = append(*calls, c)
|
||||
}
|
||||
return answer(c)
|
||||
}
|
||||
}
|
||||
|
||||
// byLine answers from a table keyed by the whole command line, and refuses anything else as a
|
||||
// command the test did not expect.
|
||||
func byLine(table map[string]Ran, calls *[]call) Runner {
|
||||
return fake(func(c call) Ran {
|
||||
if r, ok := table[c.String()]; ok {
|
||||
return r
|
||||
}
|
||||
return Ran{Status: 99, Stderr: "unexpected command: " + c.String()}
|
||||
}, calls)
|
||||
}
|
||||
|
||||
func machine(run Runner, uid int) *Machine {
|
||||
return &Machine{Run: run, UID: uid, User: "operator", Account: "operator",
|
||||
ReadFile: func(string) ([]byte, error) { return nil, errNoFile },
|
||||
Now: func() time.Time { return time.Date(2026, 10, 4, 12, 0, 0, 0, time.UTC) }}
|
||||
}
|
||||
|
||||
type noFile struct{}
|
||||
|
||||
func (noFile) Error() string { return "no such file" }
|
||||
|
||||
var errNoFile = noFile{}
|
||||
|
||||
func TestAnActNeedingRootGoesThroughSudoWithoutAPromptUnlessThisIsRoot(t *testing.T) {
|
||||
if p, a := Escalated(1000, "visudo", "-c"); p != "sudo" || strings.Join(a, " ") != "-n visudo -c" {
|
||||
t.Fatalf("not root: %s %v", p, a)
|
||||
}
|
||||
if p, a := Escalated(0, "visudo", "-c"); p != "visudo" || strings.Join(a, " ") != "-c" {
|
||||
t.Fatalf("root: %s %v", p, a)
|
||||
}
|
||||
}
|
||||
|
||||
func TestFailuresAreNamedNeverReadAsEmpty(t *testing.T) {
|
||||
cases := []struct {
|
||||
r Ran
|
||||
want string
|
||||
}{
|
||||
{Ran{Status: 127, Err: "ENOENT"}, "sudo is not installed here"},
|
||||
{Ran{Status: 1, Stderr: "sudo: a password is required\n"}, "may not run it without a prompt: sudo: a password is required"},
|
||||
{Ran{Status: 124, Err: "no answer within 20 s"}, "did not answer: no answer within 20 s"},
|
||||
{Ran{Status: 2, Stderr: "boom\nmore"}, "failed (2): boom"},
|
||||
}
|
||||
for _, c := range cases {
|
||||
m := machine(fake(func(call) Ran { return c.r }, nil), 1000)
|
||||
if _, err := m.Root("thing"); err == nil || !strings.Contains(err.Error(), c.want) {
|
||||
t.Errorf("%+v: %v, want %q", c.r, err, c.want)
|
||||
}
|
||||
}
|
||||
m := machine(fake(func(call) Ran { return Ran{Status: 127, Err: "ENOENT"} }, nil), 1000)
|
||||
if _, err := m.Out("thing"); err == nil || !strings.Contains(err.Error(), "thing is not installed") {
|
||||
t.Errorf("a missing program: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAnArgumentIsNeverAnOption(t *testing.T) {
|
||||
for _, bad := range []any{"-rf", "a\nb", 3.0} {
|
||||
if _, err := text(map[string]any{"x": bad}, "x", true); err == nil {
|
||||
t.Errorf("%v was accepted", bad)
|
||||
}
|
||||
}
|
||||
if s, err := text(map[string]any{"x": " ok "}, "x", true); err != nil || s != "ok" {
|
||||
t.Errorf("a plain value: %q %v", s, err)
|
||||
}
|
||||
if _, err := text(map[string]any{}, "x", true); err == nil {
|
||||
t.Error("a missing required value was accepted")
|
||||
}
|
||||
if n, _ := whole(map[string]any{"n": 10000.0}, "n", 5, 1, 100); n != 100 {
|
||||
t.Errorf("not bounded: %d", n)
|
||||
}
|
||||
if _, err := whole(map[string]any{"n": 0.0}, "n", 5, 1, 100); err == nil {
|
||||
t.Error("below the least was accepted")
|
||||
}
|
||||
}
|
||||
@@ -1,106 +0,0 @@
|
||||
// localization's tools bundle (novox/hq to-be 42 Phase 1, research 026/05), and its step.
|
||||
//
|
||||
// Served by the node's runtime over MCP on stdio through the Go SDK (ADR 0188, ADR 0193) when it is
|
||||
// started with no arguments. Started as `localization-tools set-time-zone <zone>` it is instead the
|
||||
// module's step, which the host runs once as root for every version of the bundle (localization.go
|
||||
// says why the time zone is a step and not a file).
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"os"
|
||||
|
||||
stdio "git.novox.be/novox/mesh-sdk/go"
|
||||
)
|
||||
|
||||
// binaryName is what the build names this bundle's executable: the manifest's `binary`.
|
||||
const binaryName = "localization-tools"
|
||||
|
||||
func bg() context.Context { return context.Background() }
|
||||
|
||||
func main() {
|
||||
m := ThisMachine()
|
||||
if len(os.Args) > 1 {
|
||||
if len(os.Args) != 3 || os.Args[1] != "set-time-zone" {
|
||||
fmt.Fprintf(os.Stderr, "usage: %s [set-time-zone <zone>]\n", binaryName)
|
||||
os.Exit(2)
|
||||
}
|
||||
said, err := m.SetTimeZoneStep(os.Args[2])
|
||||
if err != nil {
|
||||
fmt.Fprintln(os.Stderr, err)
|
||||
os.Exit(1)
|
||||
}
|
||||
fmt.Println(said)
|
||||
return
|
||||
}
|
||||
// An empty name serves as the module the runtime names (MESH_SERVED_MODULE): localization.
|
||||
if err := stdio.Serve("", tools(m)); err != nil {
|
||||
fmt.Fprintln(os.Stderr, err)
|
||||
os.Exit(1)
|
||||
}
|
||||
}
|
||||
|
||||
func tools(m *Machine) []stdio.Tool {
|
||||
return []stdio.Tool{
|
||||
{
|
||||
Name: "localization_get",
|
||||
Description: "The machine's locale (LANG and every LC_* localed reports), whether LANG is generated, its time zone, " +
|
||||
"whether the clock keeps local time, whether NTP is on and synchronised, the console keymap and the X11 keyboard " +
|
||||
"settings — and for each of locale, zone and keymap whether it is what the module declares " +
|
||||
"(en_US.UTF-8, Europe/Brussels, us).",
|
||||
Input: schema(map[string]any{}),
|
||||
Run: func(map[string]any) (any, error) { return m.Get() },
|
||||
},
|
||||
{
|
||||
Name: "localization_time_zone",
|
||||
Description: "The time zone: read it; list the zones matching a word (match); or set one (set), through the time " +
|
||||
"daemon with sudo -n, read back after. The module declares Europe/Brussels and its step sets it again " +
|
||||
"whenever the module's bundle changes, which the answer says when another zone is set.",
|
||||
Input: schema(map[string]any{
|
||||
"set": map[string]any{"type": "string", "description": "a zone to set, as timedatectl list-timezones names it (optional)"},
|
||||
"match": map[string]any{"type": "string", "description": "list the zones whose name holds this word (optional)"},
|
||||
}),
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
set, err := text(args, "set", false)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
match, err := text(args, "match", false)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.TimeZone(set, match)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "localization_locales",
|
||||
Description: "The locales: generated (locale -a), enabled in /etc/locale.gen, the LANG of /etc/locale.conf and " +
|
||||
"whether it is generated, and how many glibc can generate — listed when a word narrows them (match).",
|
||||
Input: schema(map[string]any{
|
||||
"match": map[string]any{"type": "string", "description": "list the generatable locales whose name holds this word (optional)"},
|
||||
}),
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
match, err := text(args, "match", false)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.Locales(match)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "localization_keymaps",
|
||||
Description: "The console keymap in force and the keymaps this machine has (localectl list-keymaps), narrowed to a word when given; at most 500 listed.",
|
||||
Input: schema(map[string]any{
|
||||
"match": map[string]any{"type": "string", "description": "list only keymaps whose name holds this word (optional)"},
|
||||
}),
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
match, err := text(args, "match", false)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.Keymaps(match)
|
||||
},
|
||||
},
|
||||
}
|
||||
}
|
||||
@@ -1,53 +0,0 @@
|
||||
package main
|
||||
|
||||
// The module's shape (novox/hq to-be 42 Phase 1, research 027): two files written whole and the
|
||||
// time zone as a step of its own binary — never a symbolic link written by the mesh (ADR 0012),
|
||||
// never an action (ADR 0005).
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestTheFilesSayWhatTheToolsCompareAgainst(t *testing.T) {
|
||||
m := manifest(t)
|
||||
if m.Module != "localization" || m.Version != "1" {
|
||||
t.Fatalf("%s %s", m.Module, m.Version)
|
||||
}
|
||||
locale := m.resource(t, "locale")
|
||||
if locale["path"] != "/etc/locale.conf" || locale["into"] != nil || !strings.Contains(locale["content"].(string), "\nLANG="+MeshLang+"\n") {
|
||||
t.Fatalf("locale: %v", locale)
|
||||
}
|
||||
keymap := m.resource(t, "keymap")
|
||||
if keymap["path"] != "/etc/vconsole.conf" || !strings.Contains(keymap["content"].(string), "\nKEYMAP="+MeshKeymap+"\n") {
|
||||
t.Fatalf("keymap: %v", keymap)
|
||||
}
|
||||
for _, r := range []resource{locale, keymap} {
|
||||
var settings []string
|
||||
for _, l := range strings.Split(r["content"].(string), "\n") {
|
||||
if l != "" && !strings.HasPrefix(l, "#") {
|
||||
settings = append(settings, l)
|
||||
}
|
||||
}
|
||||
if len(settings) != 1 {
|
||||
t.Fatalf("%v says one thing: %v", r["id"], settings)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestTheTimeZoneIsAStepOfTheModulesOwnBinaryRunAsRoot(t *testing.T) {
|
||||
m := manifest(t)
|
||||
step := m.resource(t, "time-zone")
|
||||
if step["type"] != "process" || step["run-once"] != true || step["artifact"] != "tools" || step["user"] != nil {
|
||||
t.Fatalf("step: %v", step)
|
||||
}
|
||||
run := step["run"].([]any)
|
||||
if len(run) != 3 || run[0] != "./"+binaryName || run[1] != "set-time-zone" || run[2] != MeshZone {
|
||||
t.Fatalf("run: %v", run)
|
||||
}
|
||||
for _, r := range m.Resources {
|
||||
if r["type"] == "action" || r["path"] == "/etc/localtime" {
|
||||
t.Fatalf("%v: the zone is never written by the mesh", r["id"])
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,80 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"os"
|
||||
"testing"
|
||||
)
|
||||
|
||||
type resource map[string]any
|
||||
|
||||
type manifestShape struct {
|
||||
Module string `json:"module"`
|
||||
Version string `json:"version"`
|
||||
Capabilities []string `json:"capabilities"`
|
||||
Claims []map[string]any `json:"claims"`
|
||||
Tools []string `json:"tools"`
|
||||
Resources []resource `json:"resources"`
|
||||
Build struct {
|
||||
Artifacts []map[string]any `json:"artifacts"`
|
||||
} `json:"build"`
|
||||
}
|
||||
|
||||
func manifest(t *testing.T) manifestShape {
|
||||
t.Helper()
|
||||
raw, err := os.ReadFile("../../module.json")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var m manifestShape
|
||||
if err := json.Unmarshal(raw, &m); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return m
|
||||
}
|
||||
|
||||
func (m manifestShape) resource(t *testing.T, id string) resource {
|
||||
t.Helper()
|
||||
for _, r := range m.Resources {
|
||||
if r["id"] == id {
|
||||
return r
|
||||
}
|
||||
}
|
||||
t.Fatalf("no resource %s", id)
|
||||
return nil
|
||||
}
|
||||
|
||||
// TestToolsAreTheManifests holds the served tools and the manifest's list to one another, and the
|
||||
// bundle to the shape the builder compiles and the runtime loads.
|
||||
func TestToolsAreTheManifests(t *testing.T) {
|
||||
m := manifest(t)
|
||||
names := map[string]bool{}
|
||||
for _, tool := range tools(machine(nil, 1000)) {
|
||||
if names[tool.Name] {
|
||||
t.Errorf("%s is served twice", tool.Name)
|
||||
}
|
||||
names[tool.Name] = true
|
||||
}
|
||||
for _, want := range m.Tools {
|
||||
if !names[want] {
|
||||
t.Errorf("the manifest lists %s and the bundle does not serve it", want)
|
||||
}
|
||||
delete(names, want)
|
||||
}
|
||||
if len(names) != 0 {
|
||||
t.Errorf("served and not listed: %v", names)
|
||||
}
|
||||
var tools map[string]any
|
||||
for _, a := range m.Build.Artifacts {
|
||||
if a["name"] == "tools" {
|
||||
tools = a
|
||||
}
|
||||
}
|
||||
if tools == nil || tools["kind"] != "bundle" || tools["language"] != "go" || tools["system"] != "arch" ||
|
||||
tools["from"] != "cmd/"+binaryName || tools["binary"] != binaryName {
|
||||
t.Fatalf("the tools artifact: %v", tools)
|
||||
}
|
||||
if loads, _ := tools["loads"].([]any); len(loads) != 1 || loads[0] != binaryName {
|
||||
t.Fatalf("loads: %v", tools["loads"])
|
||||
}
|
||||
}
|
||||
@@ -1,5 +0,0 @@
|
||||
module localization
|
||||
|
||||
go 1.22
|
||||
|
||||
require git.novox.be/novox/mesh-sdk/go v0.1.6
|
||||
@@ -1,2 +0,0 @@
|
||||
git.novox.be/novox/mesh-sdk/go v0.1.6 h1:9qzdYONYbJdWcu6sxQcq9v1LI0JxcfkiKYkMUzJSkVQ=
|
||||
git.novox.be/novox/mesh-sdk/go v0.1.6/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=
|
||||
@@ -1,56 +0,0 @@
|
||||
{
|
||||
"module": "localization",
|
||||
"version": "1",
|
||||
"capabilities": [
|
||||
"service-manager"
|
||||
],
|
||||
"tools": [
|
||||
"localization_get",
|
||||
"localization_time_zone",
|
||||
"localization_locales",
|
||||
"localization_keymaps"
|
||||
],
|
||||
"resources": [
|
||||
{
|
||||
"id": "locale",
|
||||
"type": "file",
|
||||
"path": "/etc/locale.conf",
|
||||
"mode": "0644",
|
||||
"content": "# The mesh's (module localization, novox/hq to-be 42): the system locale. Written whole at every\n# push; an edit here is overwritten. Read at the next login.\nLANG=en_US.UTF-8\n"
|
||||
},
|
||||
{
|
||||
"id": "keymap",
|
||||
"type": "file",
|
||||
"path": "/etc/vconsole.conf",
|
||||
"mode": "0644",
|
||||
"content": "# The mesh's (module localization, novox/hq to-be 42): the console keymap. Written whole at every\n# push; an edit here is overwritten. Read at the next boot.\nKEYMAP=us\n"
|
||||
},
|
||||
{
|
||||
"id": "time-zone",
|
||||
"type": "process",
|
||||
"name": "localization-time-zone",
|
||||
"artifact": "tools",
|
||||
"run": [
|
||||
"./localization-tools",
|
||||
"set-time-zone",
|
||||
"Europe/Brussels"
|
||||
],
|
||||
"run-once": true
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "tools",
|
||||
"kind": "bundle",
|
||||
"language": "go",
|
||||
"system": "arch",
|
||||
"from": "cmd/localization-tools",
|
||||
"binary": "localization-tools",
|
||||
"loads": [
|
||||
"localization-tools"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,46 +0,0 @@
|
||||
# logrotate
|
||||
|
||||
Log rotation on every machine (novox/hq to-be 42 Phase 1, research 027).
|
||||
|
||||
## What it owns
|
||||
|
||||
- The `logrotate` package.
|
||||
- `/etc/logrotate.conf`, written whole. It is the distribution's base (weekly, four kept, `create`,
|
||||
the `.pac*` taboo, `include /etc/logrotate.d`, the `wtmp`/`btmp` rules) plus `compress` and
|
||||
`delaycompress`. A rotated log is compressed one rotation late, so a program still writing to the
|
||||
file it had open loses nothing. The manifest test dry-runs it with `logrotate -d` where logrotate is
|
||||
installed. The host keeps the machine's previous file once.
|
||||
- `logrotate.timer`, running and enabled: daily, catching up after downtime.
|
||||
|
||||
## What it improves
|
||||
|
||||
- Rotation ran on one machine of four. The other three had rules in `/etc/logrotate.d`, put there by
|
||||
their packages (nginx, postgresql, samba, cups) and by the mesh's own `fail2ban` module, and nothing
|
||||
that read them. On the anchor, a web server's access log had reached 4.9 GB and the intrusion
|
||||
prevention log 239 MB.
|
||||
- Rotated logs are compressed everywhere.
|
||||
- The one machine that did rotate had `olddir /var/log/archive` set by hand. That flattens logs from
|
||||
different directories into one, where two logs with the same name collide. It is dropped.
|
||||
`/var/log/archive` and what is in it are left as found.
|
||||
|
||||
## What it leaves found
|
||||
|
||||
- Every file in `/etc/logrotate.d`. They belong to their packages and modules.
|
||||
- The journal's own bounds (`journald.conf`). journald runs on its defaults everywhere: 10 % of the
|
||||
filesystem, capped at 4 GB. The journal tools below read and vacuum it.
|
||||
|
||||
## Tools
|
||||
|
||||
| tool | | answers |
|
||||
|---|---|---|
|
||||
| `logrotate_status` | r | each log's last rotation (the status file, through sudo -n), the timer, and the last run; "never run" where it has not |
|
||||
| `logrotate_configs` | r | the base's global settings, and each rule file with the logs it rotates |
|
||||
| `logrotate_check` | r | `logrotate -d` on the whole configuration: errors and warnings, changing nothing |
|
||||
| `logrotate_big_logs` | r | the largest files under `/var/log`, with the total and the journal's share; journal files listed on request |
|
||||
| `logrotate_force` | a | `logrotate -f -v` on one rule file, with the base's globals in front so it rotates as the nightly run would, or on every log |
|
||||
| `logrotate_journal_usage` | r | `journalctl --disk-usage` and the journald settings that bound it |
|
||||
| `logrotate_journal_vacuum` | a | `journalctl --vacuum-size/--vacuum-time`, with what each directory freed |
|
||||
|
||||
Forcing one rule file alone would leave out what the base sets. A rule that names no count would then
|
||||
keep no old logs at all. So the tool writes the base's globals to a file that root owns, which is the
|
||||
only kind logrotate running as root will read, and passes it in front of the rule.
|
||||
@@ -1,97 +0,0 @@
|
||||
package main
|
||||
|
||||
// The journal: the other place a machine's logs fill its disk, kept by journald rather than
|
||||
// logrotate. The tools say how much it holds and what bounds it, and vacuum it on demand. Read as
|
||||
// root: an account outside the journal's groups sees only its own part, and is told so.
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"regexp"
|
||||
"strings"
|
||||
)
|
||||
|
||||
var (
|
||||
usage = regexp.MustCompile(`take up (\S+) in the file system`)
|
||||
freed = regexp.MustCompile(`Vacuuming done, freed (\S+) of archived journals from (\S+?)\.?$`)
|
||||
sizeSpec = regexp.MustCompile(`^[0-9]+(\.[0-9]+)?[KMGT]?$`)
|
||||
timeSpec = regexp.MustCompile(`^[0-9]+(us|ms|s|sec|min|h|hour|hours|d|day|days|w|week|weeks|M|month|months|y|year|years)$`)
|
||||
)
|
||||
|
||||
// JournalBounds are the journald settings that bound its size and age.
|
||||
var JournalBounds = []string{"Storage", "Compress", "SystemMaxUse", "SystemKeepFree", "SystemMaxFileSize", "RuntimeMaxUse", "MaxRetentionSec", "MaxFileSec"}
|
||||
|
||||
// JournalUsage is the journal's size on disk and the settings that bound it, unset meaning
|
||||
// journald's default (10% of the filesystem, at most 4G).
|
||||
func (m *Machine) JournalUsage() (map[string]any, error) {
|
||||
out, err := m.Root("journalctl", "--disk-usage")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
answer := map[string]any{"said": firstLine(out)}
|
||||
if u := usage.FindStringSubmatch(out); u != nil {
|
||||
answer["usage"] = u[1]
|
||||
}
|
||||
settings := map[string]string{}
|
||||
if cat, err := m.Out("systemd-analyze", "cat-config", "systemd/journald.conf"); err == nil {
|
||||
for _, l := range lines(cat) {
|
||||
l = strings.TrimSpace(l)
|
||||
if strings.HasPrefix(l, "#") || strings.HasPrefix(l, "[") {
|
||||
continue
|
||||
}
|
||||
if k, v, ok := strings.Cut(l, "="); ok && contains(JournalBounds, k) {
|
||||
settings[k] = v
|
||||
}
|
||||
}
|
||||
}
|
||||
answer["settings"] = settings
|
||||
if len(settings) == 0 {
|
||||
answer["note"] = "journald runs on its defaults: at most 10% of the filesystem, capped at 4G"
|
||||
}
|
||||
return answer, nil
|
||||
}
|
||||
|
||||
// Vacuum removes archived journal files beyond a size or older than a time, and says what it freed.
|
||||
func (m *Machine) Vacuum(size, age string) (map[string]any, error) {
|
||||
if size == "" && age == "" {
|
||||
return nil, fmt.Errorf("say a size to keep (e.g. 500M) or an age to keep (e.g. 4weeks), or both")
|
||||
}
|
||||
args := []string{}
|
||||
if size != "" {
|
||||
if !sizeSpec.MatchString(size) {
|
||||
return nil, fmt.Errorf("size %q is a number with K, M, G or T", size)
|
||||
}
|
||||
args = append(args, "--vacuum-size="+size)
|
||||
}
|
||||
if age != "" {
|
||||
if !timeSpec.MatchString(age) {
|
||||
return nil, fmt.Errorf("time %q is a number with a unit: s, min, h, d, weeks, months, years", age)
|
||||
}
|
||||
args = append(args, "--vacuum-time="+age)
|
||||
}
|
||||
r, err := m.RootRan("journalctl", args...)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if r.Status != 0 {
|
||||
return nil, failure("journalctl", "sudo", r)
|
||||
}
|
||||
type freedFrom struct {
|
||||
Directory string `json:"directory"`
|
||||
Freed string `json:"freed"`
|
||||
}
|
||||
from := []freedFrom{}
|
||||
deleted := 0
|
||||
for _, l := range lines(r.Stdout + "\n" + r.Stderr) {
|
||||
if f := freed.FindStringSubmatch(strings.TrimSpace(l)); f != nil {
|
||||
from = append(from, freedFrom{f[2], f[1]})
|
||||
}
|
||||
if strings.HasPrefix(strings.TrimSpace(l), "Deleted archived journal") {
|
||||
deleted++
|
||||
}
|
||||
}
|
||||
answer := map[string]any{"freed": from, "files_deleted": deleted}
|
||||
if after, err := m.JournalUsage(); err == nil {
|
||||
answer["usage_after"] = after["usage"]
|
||||
}
|
||||
return answer, nil
|
||||
}
|
||||
@@ -1,326 +0,0 @@
|
||||
package main
|
||||
|
||||
// Log rotation, on every machine (novox/hq to-be 42 Phase 1, research 027/01: "rotation running on
|
||||
// one machine of four"). Three machines carried rules in /etc/logrotate.d — put there by their
|
||||
// packages and by the mesh's own fail2ban module — and no logrotate to read them, so those logs
|
||||
// grew without bound. The module installs logrotate, owns its base configuration and enables its
|
||||
// timer; these tools read what it did, find what grows, force one rule set, and do the same for the
|
||||
// journal, which is the other place a machine's logs fill its disk.
|
||||
//
|
||||
// The status file and much of /var/log are root's, so reading them goes through sudo -n.
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"path"
|
||||
"regexp"
|
||||
"sort"
|
||||
"strconv"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// The files logrotate reads and keeps.
|
||||
const (
|
||||
BaseConf = "/etc/logrotate.conf"
|
||||
RulesDir = "/etc/logrotate.d"
|
||||
StateFile = "/var/lib/logrotate.status"
|
||||
LogRoot = "/var/log"
|
||||
forcedConf = "/run/mesh-logrotate-force.conf"
|
||||
)
|
||||
|
||||
// Rotation is one log and when logrotate last rotated it.
|
||||
type Rotation struct {
|
||||
Log string `json:"log"`
|
||||
LastRotated string `json:"last_rotated"`
|
||||
}
|
||||
|
||||
var stateLine = regexp.MustCompile(`^"(.*)" (\d+)-(\d+)-(\d+)(?:-(\d+):(\d+)(?::(\d+))?)?$`)
|
||||
|
||||
// ParseState reads logrotate's status file: `"<log>" Y-M-D-h:m:s` per line.
|
||||
func ParseState(text string) []Rotation {
|
||||
out := []Rotation{}
|
||||
for _, l := range lines(text) {
|
||||
s := stateLine.FindStringSubmatch(strings.TrimSpace(l))
|
||||
if s == nil {
|
||||
continue
|
||||
}
|
||||
n := make([]int, 6)
|
||||
for i := range n {
|
||||
n[i], _ = strconv.Atoi(s[i+2])
|
||||
}
|
||||
t := time.Date(n[0], time.Month(n[1]), n[2], n[3], n[4], n[5], 0, time.Local)
|
||||
out = append(out, Rotation{Log: s[1], LastRotated: t.Format(time.RFC3339)})
|
||||
}
|
||||
sort.Slice(out, func(i, j int) bool { return out[i].Log < out[j].Log })
|
||||
return out
|
||||
}
|
||||
|
||||
// Status is each log's last rotation and the timer that rotates them.
|
||||
func (m *Machine) Status(match string) (map[string]any, error) {
|
||||
out := map[string]any{"state_file": StateFile}
|
||||
r, err := m.RootRan("cat", StateFile)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
switch {
|
||||
case r.Status == 0:
|
||||
rot := []Rotation{}
|
||||
for _, x := range ParseState(r.Stdout) {
|
||||
if match == "" || strings.Contains(x.Log, match) {
|
||||
rot = append(rot, x)
|
||||
}
|
||||
}
|
||||
out["logs"], out["state_file_present"] = rot, true
|
||||
case strings.Contains(r.Stderr, "No such file"):
|
||||
out["logs"], out["state_file_present"] = []Rotation{}, false
|
||||
out["note"] = "logrotate has never run here"
|
||||
default:
|
||||
return nil, failure("cat", "sudo", r)
|
||||
}
|
||||
if t, err := m.unitProps("logrotate.timer", "LoadState", "ActiveState", "UnitFileState", "LastTriggerUSec", "NextElapseUSecRealtime"); err == nil {
|
||||
out["timer"] = t
|
||||
}
|
||||
if s, err := m.unitProps("logrotate.service", "LoadState", "Result", "ExecMainExitTimestamp", "ExecMainStatus"); err == nil && s["LoadState"] == "loaded" {
|
||||
out["last_run"] = s
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// Rule is one rule file and the logs it rotates.
|
||||
type Rule struct {
|
||||
File string `json:"file"`
|
||||
Logs []string `json:"logs"`
|
||||
Mesh bool `json:"mesh_owned,omitempty"`
|
||||
}
|
||||
|
||||
// RulesIn reads the log patterns a logrotate file names: the paths before each `{`.
|
||||
func RulesIn(text string) []string {
|
||||
logs := []string{}
|
||||
depth := 0
|
||||
var pending []string
|
||||
for _, l := range lines(text) {
|
||||
l = strings.TrimSpace(l)
|
||||
if strings.HasPrefix(l, "#") {
|
||||
continue
|
||||
}
|
||||
if depth == 0 {
|
||||
before, _, opens := strings.Cut(l, "{")
|
||||
fields := strings.Fields(before)
|
||||
if len(fields) > 0 && !strings.HasPrefix(fields[0], "/") && !strings.HasPrefix(fields[0], "\"") {
|
||||
// A directive (olddir, include …), not a log.
|
||||
fields = nil
|
||||
}
|
||||
for _, f := range fields {
|
||||
if strings.HasPrefix(f, "/") || strings.HasPrefix(f, "\"/") {
|
||||
pending = append(pending, strings.Trim(f, "\""))
|
||||
}
|
||||
}
|
||||
if opens {
|
||||
logs = append(logs, pending...)
|
||||
pending = nil
|
||||
depth++
|
||||
if strings.Contains(l[strings.Index(l, "{"):], "}") {
|
||||
depth--
|
||||
}
|
||||
}
|
||||
continue
|
||||
}
|
||||
if strings.HasPrefix(l, "}") || strings.HasSuffix(l, "}") && !strings.Contains(l, "{") {
|
||||
depth--
|
||||
}
|
||||
}
|
||||
return logs
|
||||
}
|
||||
|
||||
// Configs is the base configuration's own logs and every rule file with the logs it rotates.
|
||||
func (m *Machine) Configs() (map[string]any, error) {
|
||||
base, err := m.ReadFile(BaseConf)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("reading %s: %w (logrotate is not installed, or the module has not been applied)", BaseConf, err)
|
||||
}
|
||||
names, err := m.Out("find", RulesDir, "-mindepth", "1", "-maxdepth", "1", "-type", "f", "-printf", "%f\n")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
rules := []Rule{{File: BaseConf, Logs: RulesIn(string(base)), Mesh: strings.HasPrefix(string(base), "# The mesh's (module logrotate")}}
|
||||
sorted := lines(names)
|
||||
sort.Strings(sorted)
|
||||
for _, n := range sorted {
|
||||
p := path.Join(RulesDir, n)
|
||||
text, err := m.ReadFile(p)
|
||||
if err != nil {
|
||||
rules = append(rules, Rule{File: p, Logs: []string{"(unreadable: " + err.Error() + ")"}})
|
||||
continue
|
||||
}
|
||||
rules = append(rules, Rule{File: p, Logs: RulesIn(string(text))})
|
||||
}
|
||||
return map[string]any{"globals": Globals(string(base)), "rules": rules}, nil
|
||||
}
|
||||
|
||||
// Globals is the base configuration without its includes and its per-log blocks: what every rule
|
||||
// file inherits. Forcing one rule file is done with these before it, so it rotates as it would in
|
||||
// the whole run — without them, a rule that names no count would keep no old log at all.
|
||||
func Globals(text string) []string {
|
||||
out := []string{}
|
||||
depth := 0
|
||||
for _, l := range strings.Split(text, "\n") {
|
||||
t := strings.TrimSpace(l)
|
||||
switch {
|
||||
case depth > 0:
|
||||
if strings.Contains(t, "}") {
|
||||
depth--
|
||||
}
|
||||
case strings.Contains(t, "{"):
|
||||
if !strings.Contains(t, "}") {
|
||||
depth++
|
||||
}
|
||||
case t == "" || strings.HasPrefix(t, "#"), strings.HasPrefix(t, "include"):
|
||||
default:
|
||||
out = append(out, t)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// Check is a dry run of the whole configuration (logrotate -d, which changes nothing): its errors
|
||||
// and warnings, so a broken rule is found before the night it was meant to run.
|
||||
func (m *Machine) Check() (map[string]any, error) {
|
||||
r, err := m.RootRan("logrotate", "-d", BaseConf)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
errs, warns := []string{}, []string{}
|
||||
for _, l := range lines(r.Stdout + "\n" + r.Stderr) {
|
||||
l = strings.TrimSpace(l)
|
||||
switch {
|
||||
case strings.HasPrefix(l, "error:"):
|
||||
errs = append(errs, l)
|
||||
case strings.HasPrefix(l, "warning:") && !strings.Contains(l, "debug mode does nothing"):
|
||||
warns = append(warns, l)
|
||||
}
|
||||
}
|
||||
return map[string]any{"ok": len(errs) == 0 && r.Status == 0, "status": r.Status, "errors": errs, "warnings": warns}, nil
|
||||
}
|
||||
|
||||
// LogFile is one file under /var/log and its size.
|
||||
type LogFile struct {
|
||||
Path string `json:"path"`
|
||||
Bytes int64 `json:"bytes"`
|
||||
Size string `json:"size"`
|
||||
Modified string `json:"modified"`
|
||||
Journal bool `json:"journal"`
|
||||
}
|
||||
|
||||
// BigLogs is the largest files under /var/log, on its own filesystem, read as root. Journal files
|
||||
// are counted and, unless asked for, not listed: journald bounds them, and the journal tools speak
|
||||
// for them.
|
||||
func (m *Machine) BigLogs(limit int, journals bool) (map[string]any, error) {
|
||||
r, err := m.RootRan("find", LogRoot, "-xdev", "-type", "f", "-printf", "%s\t%TY-%Tm-%Td %TH:%TM\t%p\n")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if r.Status != 0 && strings.TrimSpace(r.Stdout) == "" {
|
||||
return nil, failure("find", "sudo", r)
|
||||
}
|
||||
files := []LogFile{}
|
||||
var total, journalBytes int64
|
||||
for _, l := range lines(r.Stdout) {
|
||||
f := strings.SplitN(l, "\t", 3)
|
||||
if len(f) != 3 {
|
||||
continue
|
||||
}
|
||||
n, _ := strconv.ParseInt(f[0], 10, 64)
|
||||
total += n
|
||||
journal := strings.HasSuffix(f[2], ".journal") || strings.HasSuffix(f[2], ".journal~")
|
||||
if journal {
|
||||
journalBytes += n
|
||||
if !journals {
|
||||
continue
|
||||
}
|
||||
}
|
||||
files = append(files, LogFile{Path: f[2], Bytes: n, Size: human(n), Modified: f[1], Journal: journal})
|
||||
}
|
||||
sort.Slice(files, func(i, j int) bool { return files[i].Bytes > files[j].Bytes })
|
||||
count := len(files)
|
||||
if len(files) > limit {
|
||||
files = files[:limit]
|
||||
}
|
||||
return map[string]any{"under": LogRoot, "files": count, "total_bytes": total, "total": human(total),
|
||||
"journal_bytes": journalBytes, "journal": human(journalBytes), "journals_listed": journals, "largest": files}, nil
|
||||
}
|
||||
|
||||
func human(n int64) string {
|
||||
units := []string{"B", "K", "M", "G", "T"}
|
||||
f := float64(n)
|
||||
i := 0
|
||||
for f >= 1024 && i < len(units)-1 {
|
||||
f /= 1024
|
||||
i++
|
||||
}
|
||||
if i == 0 {
|
||||
return fmt.Sprintf("%d%s", n, units[0])
|
||||
}
|
||||
return fmt.Sprintf("%.1f%s", f, units[i])
|
||||
}
|
||||
|
||||
var ruleName = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._@+-]*$`)
|
||||
|
||||
// Force rotates the logs of one rule file now (logrotate -f -v), with the base configuration's
|
||||
// globals before it; or every log, given the base configuration's own name.
|
||||
func (m *Machine) Force(config string, writeTemp func(string) (string, func(), error)) (map[string]any, error) {
|
||||
var args []string
|
||||
switch {
|
||||
case config == path.Base(BaseConf) || config == BaseConf:
|
||||
args = []string{"-f", "-v", BaseConf}
|
||||
case ruleName.MatchString(config):
|
||||
rule := path.Join(RulesDir, config)
|
||||
if _, err := m.ReadFile(rule); err != nil {
|
||||
return nil, fmt.Errorf("%s is not a rule file here: %w", rule, err)
|
||||
}
|
||||
base, err := m.ReadFile(BaseConf)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("reading %s: %w", BaseConf, err)
|
||||
}
|
||||
temp, done, err := writeTemp("# The globals of " + BaseConf + ", for forcing " + rule + " alone.\n" + strings.Join(Globals(string(base)), "\n") + "\n")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
defer done()
|
||||
// logrotate running as root reads only a configuration root owns.
|
||||
if _, err := m.Root("install", "-m", "0644", "-o", "root", "-g", "root", temp, forcedConf); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
defer m.Root("rm", "-f", forcedConf) //nolint:errcheck
|
||||
args = []string{"-f", "-v", forcedConf, rule}
|
||||
default:
|
||||
return nil, fmt.Errorf("%q is neither a file of %s nor %s", config, RulesDir, path.Base(BaseConf))
|
||||
}
|
||||
r, err := m.RootRan("logrotate", args...)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
said := lines(r.Stdout + "\n" + r.Stderr)
|
||||
rotated, errs := []string{}, []string{}
|
||||
for _, l := range said {
|
||||
l = strings.TrimSpace(l)
|
||||
switch {
|
||||
case strings.HasPrefix(l, "rotating log "):
|
||||
rotated = append(rotated, strings.TrimSuffix(strings.Fields(strings.TrimPrefix(l, "rotating log "))[0], ","))
|
||||
case strings.HasPrefix(l, "error:"):
|
||||
errs = append(errs, l)
|
||||
}
|
||||
}
|
||||
if len(said) > 200 {
|
||||
said = said[len(said)-200:]
|
||||
}
|
||||
return map[string]any{"config": config, "ok": r.Status == 0 && len(errs) == 0, "rotated": rotated, "errors": errs, "log": said}, nil
|
||||
}
|
||||
|
||||
func contains(list []string, want string) bool {
|
||||
for _, s := range list {
|
||||
if s == want {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
@@ -1,188 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
const state = `logrotate state -- version 2
|
||||
"/var/log/nginx/error.log" 2026-3-15-0:34:52
|
||||
"/var/log/wtmp" 2024-6-27-11:0:0
|
||||
"/var/log/old.log" 2026-1-2
|
||||
`
|
||||
|
||||
func TestTheStatusFileIsReadPerLog(t *testing.T) {
|
||||
r := ParseState(state)
|
||||
if len(r) != 3 || r[0].Log != "/var/log/nginx/error.log" || !strings.HasPrefix(r[0].LastRotated, "2026-03-15T00:34:52") || !strings.HasPrefix(r[1].LastRotated, "2026-01-02T00:00:00") {
|
||||
t.Fatalf("%+v", r)
|
||||
}
|
||||
m := machine(fake(func(c call) Ran {
|
||||
if c.String() == "sudo -n cat "+StateFile {
|
||||
return Ran{Stdout: state}
|
||||
}
|
||||
return Ran{Stdout: "ActiveState=active\n"}
|
||||
}, nil), 1000)
|
||||
s, err := m.Status("nginx")
|
||||
if err != nil || len(s["logs"].([]Rotation)) != 1 || s["state_file_present"] != true {
|
||||
t.Fatalf("%v %v", s, err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAMachineWhereLogrotateNeverRanSaysSo(t *testing.T) {
|
||||
m := machine(fake(func(c call) Ran {
|
||||
if c.name == "sudo" {
|
||||
return Ran{Status: 1, Stderr: "cat: /var/lib/logrotate.status: No such file or directory\n"}
|
||||
}
|
||||
return Ran{Stdout: "LoadState=not-found\n"}
|
||||
}, nil), 1000)
|
||||
s, err := m.Status("")
|
||||
if err != nil || s["state_file_present"] != false || !strings.Contains(s["note"].(string), "never run") {
|
||||
t.Fatalf("%v %v", s, err)
|
||||
}
|
||||
refused := machine(fake(func(call) Ran { return Ran{Status: 1, Stderr: "sudo: a password is required\n"} }, nil), 1000)
|
||||
if _, err := refused.Status(""); err == nil || !strings.Contains(err.Error(), "without a prompt") {
|
||||
t.Fatalf("a refusal is an error: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
const samba = `/var/log/samba/log.smbd /var/log/samba/log.nmbd /var/log/samba/*.log {
|
||||
notifempty
|
||||
missingok
|
||||
copytruncate
|
||||
}
|
||||
# a comment { with a brace
|
||||
/var/log/one.log
|
||||
/var/log/two.log {
|
||||
postrotate
|
||||
kill -HUP 1
|
||||
endscript
|
||||
}
|
||||
`
|
||||
|
||||
func TestARuleFilesLogsAreThePathsBeforeEachBrace(t *testing.T) {
|
||||
got := RulesIn(samba)
|
||||
if strings.Join(got, " ") != "/var/log/samba/log.smbd /var/log/samba/log.nmbd /var/log/samba/*.log /var/log/one.log /var/log/two.log" {
|
||||
t.Fatalf("%v", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestADirectiveIsNotALog(t *testing.T) {
|
||||
got := RulesIn("weekly\nolddir /var/log/archive\ninclude /etc/logrotate.d\n/var/log/wtmp {\n monthly\n}\n")
|
||||
if strings.Join(got, " ") != "/var/log/wtmp" {
|
||||
t.Fatalf("%v", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestGlobalsAreTheBaseWithoutIncludesOrBlocks(t *testing.T) {
|
||||
g := manifest(t).resource(t, "config")["content"].(string)
|
||||
got := Globals(g)
|
||||
if strings.Join(got, "|") != "weekly|rotate 4|create|compress|delaycompress|tabooext + .pacorig .pacnew .pacsave" {
|
||||
t.Fatalf("%v", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestForcingOneRuleCarriesTheGlobalsInAFileRootOwns(t *testing.T) {
|
||||
var calls []call
|
||||
m := machine(fake(func(c call) Ran {
|
||||
if c.args[1] == "logrotate" {
|
||||
return Ran{Stderr: "reading config file /run/mesh-logrotate-force.conf\nrotating log /var/log/samba/log.smbd, log->rotateCount is 4\nerror: error renaming x: Permission denied\n"}
|
||||
}
|
||||
return Ran{}
|
||||
}, &calls), 1000)
|
||||
files := map[string]string{BaseConf: "weekly\nrotate 4\ninclude /etc/logrotate.d\n/var/log/wtmp {\n monthly\n}\n", RulesDir + "/samba": samba}
|
||||
m.ReadFile = func(p string) ([]byte, error) {
|
||||
if s, ok := files[p]; ok {
|
||||
return []byte(s), nil
|
||||
}
|
||||
return nil, errNoFile
|
||||
}
|
||||
var written string
|
||||
removed := false
|
||||
r, err := m.Force("samba", func(s string) (string, func(), error) {
|
||||
written = s
|
||||
return "/tmp/x.conf", func() { removed = true }, nil
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !strings.Contains(written, "weekly\nrotate 4\n") || strings.Contains(written, "include") || strings.Contains(written, "wtmp") || !removed {
|
||||
t.Fatalf("written %q removed %v", written, removed)
|
||||
}
|
||||
var seen []string
|
||||
for _, c := range calls {
|
||||
seen = append(seen, c.String())
|
||||
}
|
||||
want := []string{
|
||||
"sudo -n install -m 0644 -o root -g root /tmp/x.conf " + forcedConf,
|
||||
"sudo -n logrotate -f -v " + forcedConf + " " + RulesDir + "/samba",
|
||||
"sudo -n rm -f " + forcedConf,
|
||||
}
|
||||
if strings.Join(seen, "\n") != strings.Join(want, "\n") {
|
||||
t.Fatalf("ran:\n%s", strings.Join(seen, "\n"))
|
||||
}
|
||||
if r["ok"] != false || strings.Join(r["rotated"].([]string), ",") != "/var/log/samba/log.smbd" || len(r["errors"].([]string)) != 1 {
|
||||
t.Fatalf("%v", r)
|
||||
}
|
||||
if _, err := m.Force("../../etc/shadow", nil); err == nil {
|
||||
t.Fatal("a path was taken for a rule file")
|
||||
}
|
||||
if _, err := m.Force("absent", nil); err == nil {
|
||||
t.Fatal("a rule file that is not there was forced")
|
||||
}
|
||||
}
|
||||
|
||||
func TestBigLogsAreSortedAndBounded(t *testing.T) {
|
||||
m := machine(byLine(map[string]Ran{
|
||||
"sudo -n find /var/log -xdev -type f -printf %s\t%TY-%Tm-%Td %TH:%TM\t%p\n": {Status: 1, Stdout: "10\t2026-10-04 10:00\t/var/log/a.log\n4294967296\t2026-10-04 11:00\t/var/log/journal/x/system.journal\n2048\t2026-10-01 09:00\t/var/log/b.log\n", Stderr: "find: something vanished\n"},
|
||||
}, nil), 1000)
|
||||
r, err := m.BigLogs(2, true)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
l := r["largest"].([]LogFile)
|
||||
if r["files"] != 3 || len(l) != 2 || !l[0].Journal || l[0].Size != "4.0G" || l[1].Path != "/var/log/b.log" || l[1].Size != "2.0K" {
|
||||
t.Fatalf("%v", r)
|
||||
}
|
||||
r, _ = m.BigLogs(5, false)
|
||||
if l := r["largest"].([]LogFile); len(l) != 2 || l[0].Path != "/var/log/b.log" || r["journal"] != "4.0G" {
|
||||
t.Fatalf("journals counted, not listed: %v", r)
|
||||
}
|
||||
}
|
||||
|
||||
func TestTheDryRunReportsErrorsAndNotItsOwnWarning(t *testing.T) {
|
||||
m := machine(byLine(map[string]Ran{
|
||||
"sudo -n logrotate -d /etc/logrotate.conf": {Stderr: "warning: logrotate in debug mode does nothing except printing debug messages!\nerror: /etc/logrotate.d/x:3 unknown option 'bogus'\nwarning: something real\n"},
|
||||
}, nil), 1000)
|
||||
r, err := m.Check()
|
||||
if err != nil || r["ok"] != false || len(r["errors"].([]string)) != 1 || len(r["warnings"].([]string)) != 1 {
|
||||
t.Fatalf("%v %v", r, err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestTheJournalIsMeasuredAndVacuumedAsRoot(t *testing.T) {
|
||||
var calls []call
|
||||
m := machine(fake(func(c call) Ran {
|
||||
switch c.String() {
|
||||
case "sudo -n journalctl --disk-usage":
|
||||
return Ran{Stdout: "Archived and active journals take up 4G in the file system.\n"}
|
||||
case "systemd-analyze cat-config systemd/journald.conf":
|
||||
return Ran{Stdout: "# /etc/systemd/journald.conf\n[Journal]\n#SystemMaxUse=\nSystemMaxUse=1G\n"}
|
||||
case "sudo -n journalctl --vacuum-size=500M --vacuum-time=4weeks":
|
||||
return Ran{Stderr: "Deleted archived journal /var/log/journal/x/system@a.journal (128M).\nVacuuming done, freed 128M of archived journals from /var/log/journal/x.\n"}
|
||||
}
|
||||
return Ran{Status: 99}
|
||||
}, &calls), 1000)
|
||||
u, err := m.JournalUsage()
|
||||
if err != nil || u["usage"] != "4G" || u["settings"].(map[string]string)["SystemMaxUse"] != "1G" {
|
||||
t.Fatalf("%v %v", u, err)
|
||||
}
|
||||
v, err := m.Vacuum("500M", "4weeks")
|
||||
if err != nil || v["files_deleted"] != 1 || v["usage_after"] != "4G" {
|
||||
t.Fatalf("%v %v", v, err)
|
||||
}
|
||||
for _, bad := range [][2]string{{"", ""}, {"lots", ""}, {"", "forever"}, {"1G; rm", ""}} {
|
||||
if _, err := m.Vacuum(bad[0], bad[1]); err == nil {
|
||||
t.Errorf("%v accepted", bad)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,289 +0,0 @@
|
||||
package main
|
||||
|
||||
// The commands this bundle runs on its machine, and who runs them.
|
||||
//
|
||||
// Who asks. The node's tool runtime runs as the operator account, not root (novox/hq ADR 0175 §4),
|
||||
// and launches this binary as a process of its own (ADR 0188, ADR 0193) with the runtime's words —
|
||||
// HOME, a PATH, MESH_OPERATOR_ACCOUNT — and no session words. Reading needs nothing more; what only
|
||||
// root may do goes through `sudo -n`, as the packet filter's, the service manager's and the
|
||||
// intrusion prevention's tools do (to-be 38 WP4), and the `sudo` module is what declares that the
|
||||
// account may (to-be 42, research 027). A refusal is named by how it failed, never read as an
|
||||
// empty answer.
|
||||
//
|
||||
// The runner is injected, so every tool is tested over a fake one without the machine.
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"errors"
|
||||
"fmt"
|
||||
"io/fs"
|
||||
"os"
|
||||
"os/exec"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// Ran is what one command did: its output, its exit status, and why it never ran to an answer.
|
||||
type Ran struct {
|
||||
Stdout string
|
||||
Stderr string
|
||||
Status int
|
||||
// Err is "ENOENT" when the program is not there, or that it was ended for taking too long.
|
||||
Err string
|
||||
}
|
||||
|
||||
// Runner runs one command, so the tools can be tested without the machine.
|
||||
type Runner func(ctx context.Context, name string, args ...string) Ran
|
||||
|
||||
// CallTimeout is how long one command may take: below the runtime's thirty-second call limit, so a
|
||||
// command that hangs is answered as such rather than as a call the runtime gave up on.
|
||||
const CallTimeout = 20 * time.Second
|
||||
|
||||
// outputLimit bounds what one command may hand back, so a runaway listing cannot exhaust the
|
||||
// process; well above anything a tool answers.
|
||||
const outputLimit = 16 << 20
|
||||
|
||||
type bounded struct {
|
||||
bytes.Buffer
|
||||
cut bool
|
||||
}
|
||||
|
||||
func (b *bounded) Write(p []byte) (int, error) {
|
||||
if room := outputLimit - b.Len(); room < len(p) {
|
||||
if room > 0 {
|
||||
b.Buffer.Write(p[:room])
|
||||
}
|
||||
b.cut = true
|
||||
return len(p), nil
|
||||
}
|
||||
return b.Buffer.Write(p)
|
||||
}
|
||||
|
||||
// ExecRunner runs a command on this machine, in the C locale so what is parsed is one language.
|
||||
func ExecRunner(ctx context.Context, name string, args ...string) Ran {
|
||||
ctx, cancel := context.WithTimeout(ctx, CallTimeout)
|
||||
defer cancel()
|
||||
cmd := exec.CommandContext(ctx, name, args...)
|
||||
cmd.Env = append(os.Environ(), "LC_ALL=C")
|
||||
var out, errb bounded
|
||||
cmd.Stdout, cmd.Stderr = &out, &errb
|
||||
err := cmd.Run()
|
||||
r := Ran{Stdout: out.String(), Stderr: errb.String()}
|
||||
if ctx.Err() == context.DeadlineExceeded {
|
||||
r.Status, r.Err = 124, fmt.Sprintf("no answer within %d s", int(CallTimeout.Seconds()))
|
||||
return r
|
||||
}
|
||||
var exit *exec.ExitError
|
||||
switch {
|
||||
case err == nil:
|
||||
case errors.As(err, &exit):
|
||||
r.Status = exit.ExitCode()
|
||||
case errors.Is(err, exec.ErrNotFound) || errors.Is(err, fs.ErrNotExist):
|
||||
r.Status, r.Err = 127, "ENOENT"
|
||||
default:
|
||||
r.Status, r.Err = 126, err.Error()
|
||||
}
|
||||
return r
|
||||
}
|
||||
|
||||
// Escalated is the command as it is run: as given when this process is root, else through sudo
|
||||
// without a prompt.
|
||||
func Escalated(uid int, name string, args ...string) (string, []string) {
|
||||
if uid == 0 {
|
||||
return name, args
|
||||
}
|
||||
return "sudo", append([]string{"-n", name}, args...)
|
||||
}
|
||||
|
||||
// Machine is this machine as the tools see it: a runner, who this process is, and its files.
|
||||
type Machine struct {
|
||||
Run Runner
|
||||
UID int
|
||||
User string
|
||||
Account string
|
||||
ReadFile func(path string) ([]byte, error)
|
||||
Now func() time.Time
|
||||
Sleep func(time.Duration)
|
||||
}
|
||||
|
||||
// ThisMachine is the machine the runtime launched this bundle on.
|
||||
func ThisMachine() *Machine {
|
||||
user := os.Getenv("USER")
|
||||
if user == "" {
|
||||
user = os.Getenv("LOGNAME")
|
||||
}
|
||||
account := strings.TrimSpace(os.Getenv("MESH_OPERATOR_ACCOUNT"))
|
||||
if account == "" {
|
||||
account = user
|
||||
}
|
||||
return &Machine{Run: ExecRunner, UID: os.Getuid(), User: user, Account: account, ReadFile: os.ReadFile, Now: time.Now, Sleep: time.Sleep}
|
||||
}
|
||||
|
||||
// Out runs a command that only reads, and fails with what went wrong named.
|
||||
func (m *Machine) Out(name string, args ...string) (string, error) {
|
||||
r := m.Run(context.Background(), name, args...)
|
||||
if r.Status == 0 && r.Err == "" {
|
||||
return r.Stdout, nil
|
||||
}
|
||||
return r.Stdout, failure(name, name, r)
|
||||
}
|
||||
|
||||
// Root runs a command that needs root, escalated when this process is not.
|
||||
func (m *Machine) Root(name string, args ...string) (string, error) {
|
||||
program, argv := Escalated(m.UID, name, args...)
|
||||
r := m.Run(context.Background(), program, argv...)
|
||||
if r.Status == 0 && r.Err == "" {
|
||||
return r.Stdout, nil
|
||||
}
|
||||
return r.Stdout, failure(name, program, r)
|
||||
}
|
||||
|
||||
// RootRan is Root's raw answer, for a command whose non-zero status is itself an answer.
|
||||
func (m *Machine) RootRan(name string, args ...string) (Ran, error) {
|
||||
program, argv := Escalated(m.UID, name, args...)
|
||||
r := m.Run(context.Background(), program, argv...)
|
||||
if r.Err != "" || (program == "sudo" && sudoRefused(r)) {
|
||||
return r, failure(name, program, r)
|
||||
}
|
||||
return r, nil
|
||||
}
|
||||
|
||||
func sudoRefused(r Ran) bool {
|
||||
return strings.HasPrefix(strings.TrimSpace(r.Stderr), "sudo:")
|
||||
}
|
||||
|
||||
// failure names what failed by how it failed: the program missing is a spawn error, sudo missing
|
||||
// or refusing speaks for itself, and the rest is the command's own first line.
|
||||
func failure(cmd, program string, r Ran) error {
|
||||
said := strings.TrimSpace(r.Stderr + "\n" + r.Stdout)
|
||||
if r.Err == "ENOENT" {
|
||||
if program == "sudo" {
|
||||
return fmt.Errorf("%s needs root for this, and sudo is not installed here for the runtime's account to escalate with", cmd)
|
||||
}
|
||||
return fmt.Errorf("%s is not installed on this machine", cmd)
|
||||
}
|
||||
if r.Err != "" {
|
||||
return fmt.Errorf("%s did not answer: %s", cmd, r.Err)
|
||||
}
|
||||
if program == "sudo" && sudoRefused(r) {
|
||||
if strings.Contains(said, "command not found") {
|
||||
return fmt.Errorf("%s is not installed on this machine", cmd)
|
||||
}
|
||||
return fmt.Errorf("%s needs root for this and the runtime's account may not run it without a prompt: %s", cmd, firstLine(said))
|
||||
}
|
||||
if line := firstLine(said); line != "" {
|
||||
return fmt.Errorf("%s failed (%d): %s", cmd, r.Status, line)
|
||||
}
|
||||
return fmt.Errorf("%s failed with status %d", cmd, r.Status)
|
||||
}
|
||||
|
||||
func firstLine(text string) string {
|
||||
for _, l := range strings.Split(text, "\n") {
|
||||
if l = strings.TrimSpace(l); l != "" {
|
||||
return l
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
func lines(text string) []string {
|
||||
var out []string
|
||||
for _, l := range strings.Split(text, "\n") {
|
||||
if l = strings.TrimRight(l, "\r"); strings.TrimSpace(l) != "" {
|
||||
out = append(out, l)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// text is a string argument; required says whether it may be absent. It is never something a
|
||||
// command would read as an option, which under sudo would be root's option.
|
||||
func text(args map[string]any, key string, required bool) (string, error) {
|
||||
raw, present := args[key]
|
||||
if !present || raw == nil {
|
||||
if required {
|
||||
return "", fmt.Errorf("%s is required", key)
|
||||
}
|
||||
return "", nil
|
||||
}
|
||||
s, ok := raw.(string)
|
||||
if !ok {
|
||||
return "", fmt.Errorf("%s must be a string", key)
|
||||
}
|
||||
s = strings.TrimSpace(s)
|
||||
if required && s == "" {
|
||||
return "", fmt.Errorf("%s is required", key)
|
||||
}
|
||||
if strings.HasPrefix(s, "-") || strings.ContainsRune(s, 0) || strings.ContainsAny(s, "\n\r") {
|
||||
return "", fmt.Errorf("%s %q is not a value this tool passes on", key, s)
|
||||
}
|
||||
return s, nil
|
||||
}
|
||||
|
||||
// whole is a whole-number argument with a default, kept within bounds.
|
||||
func whole(args map[string]any, key string, def, least, most int) (int, error) {
|
||||
raw, present := args[key]
|
||||
if !present || raw == nil {
|
||||
return def, nil
|
||||
}
|
||||
f, ok := raw.(float64)
|
||||
if !ok || f != float64(int(f)) {
|
||||
return 0, fmt.Errorf("%s must be a whole number", key)
|
||||
}
|
||||
n := int(f)
|
||||
if n < least {
|
||||
return 0, fmt.Errorf("%s must be at least %d", key, least)
|
||||
}
|
||||
if n > most {
|
||||
n = most
|
||||
}
|
||||
return n, nil
|
||||
}
|
||||
|
||||
// flag is a boolean argument, false when absent.
|
||||
func flag(args map[string]any, key string) (bool, error) {
|
||||
raw, present := args[key]
|
||||
if !present || raw == nil {
|
||||
return false, nil
|
||||
}
|
||||
b, ok := raw.(bool)
|
||||
if !ok {
|
||||
return false, fmt.Errorf("%s must be true or false", key)
|
||||
}
|
||||
return b, nil
|
||||
}
|
||||
|
||||
// schema is a tool's input: its properties and the ones it requires.
|
||||
func schema(properties map[string]any, required ...string) map[string]any {
|
||||
s := map[string]any{"type": "object", "properties": properties}
|
||||
if len(required) > 0 {
|
||||
s["required"] = required
|
||||
}
|
||||
return s
|
||||
}
|
||||
|
||||
// unitProps reads a unit's properties as systemctl shows them.
|
||||
func (m *Machine) unitProps(unit string, props ...string) (map[string]string, error) {
|
||||
args := []string{"show", unit, "--no-pager"}
|
||||
for _, p := range props {
|
||||
args = append(args, "--property="+p)
|
||||
}
|
||||
out, err := m.Out("systemctl", args...)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return keyValues(out, "="), nil
|
||||
}
|
||||
|
||||
// keyValues reads `key<sep>value` lines; a line without the separator is skipped.
|
||||
func keyValues(out, sep string) map[string]string {
|
||||
kv := map[string]string{}
|
||||
for _, l := range strings.Split(out, "\n") {
|
||||
k, v, ok := strings.Cut(l, sep)
|
||||
if ok {
|
||||
kv[strings.TrimSpace(k)] = strings.TrimSpace(v)
|
||||
}
|
||||
}
|
||||
return kv
|
||||
}
|
||||
@@ -1,107 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
// call is one command a fake runner was asked to run.
|
||||
type call struct {
|
||||
name string
|
||||
args []string
|
||||
}
|
||||
|
||||
func (c call) String() string {
|
||||
if len(c.args) == 0 {
|
||||
return c.name
|
||||
}
|
||||
return c.name + " " + strings.Join(c.args, " ")
|
||||
}
|
||||
|
||||
// fake is a runner answering by the command line it is given, recording every call.
|
||||
func fake(answer func(c call) Ran, calls *[]call) Runner {
|
||||
return func(_ context.Context, name string, args ...string) Ran {
|
||||
c := call{name, append([]string(nil), args...)}
|
||||
if calls != nil {
|
||||
*calls = append(*calls, c)
|
||||
}
|
||||
return answer(c)
|
||||
}
|
||||
}
|
||||
|
||||
// byLine answers from a table keyed by the whole command line, and refuses anything else as a
|
||||
// command the test did not expect.
|
||||
func byLine(table map[string]Ran, calls *[]call) Runner {
|
||||
return fake(func(c call) Ran {
|
||||
if r, ok := table[c.String()]; ok {
|
||||
return r
|
||||
}
|
||||
return Ran{Status: 99, Stderr: "unexpected command: " + c.String()}
|
||||
}, calls)
|
||||
}
|
||||
|
||||
func machine(run Runner, uid int) *Machine {
|
||||
return &Machine{Run: run, UID: uid, User: "operator", Account: "operator",
|
||||
ReadFile: func(string) ([]byte, error) { return nil, errNoFile },
|
||||
Now: func() time.Time { return time.Date(2026, 10, 4, 12, 0, 0, 0, time.UTC) },
|
||||
Sleep: func(time.Duration) {}}
|
||||
}
|
||||
|
||||
type noFile struct{}
|
||||
|
||||
func (noFile) Error() string { return "no such file" }
|
||||
|
||||
var errNoFile = noFile{}
|
||||
|
||||
func TestAnActNeedingRootGoesThroughSudoWithoutAPromptUnlessThisIsRoot(t *testing.T) {
|
||||
if p, a := Escalated(1000, "visudo", "-c"); p != "sudo" || strings.Join(a, " ") != "-n visudo -c" {
|
||||
t.Fatalf("not root: %s %v", p, a)
|
||||
}
|
||||
if p, a := Escalated(0, "visudo", "-c"); p != "visudo" || strings.Join(a, " ") != "-c" {
|
||||
t.Fatalf("root: %s %v", p, a)
|
||||
}
|
||||
}
|
||||
|
||||
func TestFailuresAreNamedNeverReadAsEmpty(t *testing.T) {
|
||||
cases := []struct {
|
||||
r Ran
|
||||
want string
|
||||
}{
|
||||
{Ran{Status: 127, Err: "ENOENT"}, "sudo is not installed here"},
|
||||
{Ran{Status: 1, Stderr: "sudo: a password is required\n"}, "may not run it without a prompt: sudo: a password is required"},
|
||||
{Ran{Status: 124, Err: "no answer within 20 s"}, "did not answer: no answer within 20 s"},
|
||||
{Ran{Status: 2, Stderr: "boom\nmore"}, "failed (2): boom"},
|
||||
}
|
||||
for _, c := range cases {
|
||||
m := machine(fake(func(call) Ran { return c.r }, nil), 1000)
|
||||
if _, err := m.Root("thing"); err == nil || !strings.Contains(err.Error(), c.want) {
|
||||
t.Errorf("%+v: %v, want %q", c.r, err, c.want)
|
||||
}
|
||||
}
|
||||
m := machine(fake(func(call) Ran { return Ran{Status: 127, Err: "ENOENT"} }, nil), 1000)
|
||||
if _, err := m.Out("thing"); err == nil || !strings.Contains(err.Error(), "thing is not installed") {
|
||||
t.Errorf("a missing program: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAnArgumentIsNeverAnOption(t *testing.T) {
|
||||
for _, bad := range []any{"-rf", "a\nb", 3.0} {
|
||||
if _, err := text(map[string]any{"x": bad}, "x", true); err == nil {
|
||||
t.Errorf("%v was accepted", bad)
|
||||
}
|
||||
}
|
||||
if s, err := text(map[string]any{"x": " ok "}, "x", true); err != nil || s != "ok" {
|
||||
t.Errorf("a plain value: %q %v", s, err)
|
||||
}
|
||||
if _, err := text(map[string]any{}, "x", true); err == nil {
|
||||
t.Error("a missing required value was accepted")
|
||||
}
|
||||
if n, _ := whole(map[string]any{"n": 10000.0}, "n", 5, 1, 100); n != 100 {
|
||||
t.Errorf("not bounded: %d", n)
|
||||
}
|
||||
if _, err := whole(map[string]any{"n": 0.0}, "n", 5, 1, 100); err == nil {
|
||||
t.Error("below the least was accepted")
|
||||
}
|
||||
}
|
||||
@@ -1,128 +0,0 @@
|
||||
// logrotate's tools bundle (novox/hq to-be 42 Phase 1, research 026/05): a process the node's
|
||||
// runtime launches and speaks MCP over stdio to, through the Go SDK (ADR 0188, ADR 0193). It reads
|
||||
// when each log was last rotated, the rule files and a dry run of them, and the largest logs; forces
|
||||
// one rule file; and reads and vacuums the journal. Acts go through sudo -n.
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"os"
|
||||
|
||||
stdio "git.novox.be/novox/mesh-sdk/go"
|
||||
)
|
||||
|
||||
// binaryName is what the build names this bundle's executable: the manifest's `binary`.
|
||||
const binaryName = "logrotate-tools"
|
||||
|
||||
func bg() context.Context { return context.Background() }
|
||||
|
||||
func main() {
|
||||
// An empty name serves as the module the runtime names (MESH_SERVED_MODULE): logrotate.
|
||||
if err := stdio.Serve("", tools(ThisMachine())); err != nil {
|
||||
fmt.Fprintln(os.Stderr, err)
|
||||
os.Exit(1)
|
||||
}
|
||||
}
|
||||
|
||||
// writeTemp writes a file only this account can write, and gives back how to remove it.
|
||||
func writeTemp(content string) (string, func(), error) {
|
||||
f, err := os.CreateTemp("", "mesh-logrotate-*.conf")
|
||||
if err != nil {
|
||||
return "", nil, err
|
||||
}
|
||||
_, werr := f.WriteString(content)
|
||||
cerr := f.Close()
|
||||
done := func() { os.Remove(f.Name()) }
|
||||
if werr != nil || cerr != nil {
|
||||
done()
|
||||
return "", nil, fmt.Errorf("writing %s: %v %v", f.Name(), werr, cerr)
|
||||
}
|
||||
return f.Name(), done, nil
|
||||
}
|
||||
|
||||
func tools(m *Machine) []stdio.Tool {
|
||||
return []stdio.Tool{
|
||||
{
|
||||
Name: "logrotate_status",
|
||||
Description: "When logrotate last rotated each log (its status file, read through sudo -n), narrowed to logs whose path holds a word; with the timer's last and next run and the last run's result. A machine where it never ran says so.",
|
||||
Input: schema(map[string]any{"match": map[string]any{"type": "string", "description": "only logs whose path holds this"}}),
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
match, err := text(args, "match", false)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.Status(match)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "logrotate_configs",
|
||||
Description: "The base configuration's global settings and every rule file of /etc/logrotate.d with the logs it rotates.",
|
||||
Input: schema(map[string]any{}),
|
||||
Run: func(map[string]any) (any, error) { return m.Configs() },
|
||||
},
|
||||
{
|
||||
Name: "logrotate_check",
|
||||
Description: "A dry run of the whole configuration (logrotate -d through sudo -n, which changes nothing): its errors and warnings, so a broken rule is found before the night it runs.",
|
||||
Input: schema(map[string]any{}),
|
||||
Run: func(map[string]any) (any, error) { return m.Check() },
|
||||
},
|
||||
{
|
||||
Name: "logrotate_big_logs",
|
||||
Description: "The largest files under /var/log on its own filesystem (read through sudo -n), with size and modification time; with the total and how much of it is the journal. Journal files are listed only when asked (journals: true).",
|
||||
Input: schema(map[string]any{
|
||||
"limit": map[string]any{"type": "integer", "description": "how many (default 20, at most 200)"},
|
||||
"journals": map[string]any{"type": "boolean", "description": "list the journal's files too"},
|
||||
}),
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
n, err := whole(args, "limit", 20, 1, 200)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
j, err := flag(args, "journals")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.BigLogs(n, j)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "logrotate_force",
|
||||
Description: "Rotate now (logrotate -f -v, through sudo -n) the logs of one rule file of /etc/logrotate.d, with the base configuration's " +
|
||||
"global settings before it so it rotates as the nightly run would; or every log, given logrotate.conf. Answers what was rotated, the errors and the log.",
|
||||
Input: schema(map[string]any{"config": map[string]any{"type": "string", "description": "a file name in /etc/logrotate.d, or logrotate.conf for every log"}}, "config"),
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
config, err := text(args, "config", true)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.Force(config, writeTemp)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "logrotate_journal_usage",
|
||||
Description: "How much the systemd journal holds on disk (journalctl --disk-usage, through sudo -n so every part is counted) and the journald settings that bound it.",
|
||||
Input: schema(map[string]any{}),
|
||||
Run: func(map[string]any) (any, error) { return m.JournalUsage() },
|
||||
},
|
||||
{
|
||||
Name: "logrotate_journal_vacuum",
|
||||
Description: "Remove archived journal files (through sudo -n) beyond a total size, older than an age, or both; answers what each directory freed and the usage after.",
|
||||
Input: schema(map[string]any{
|
||||
"size": map[string]any{"type": "string", "description": "keep at most this much, e.g. 500M or 2G"},
|
||||
"time": map[string]any{"type": "string", "description": "keep at most this old, e.g. 4weeks or 30d"},
|
||||
}),
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
size, err := text(args, "size", false)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
age, err := text(args, "time", false)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.Vacuum(size, age)
|
||||
},
|
||||
},
|
||||
}
|
||||
}
|
||||
@@ -1,54 +0,0 @@
|
||||
package main
|
||||
|
||||
// The module's shape (novox/hq to-be 42 Phase 1, research 027): the package, its base configuration
|
||||
// whole, and its timer — and the base configuration proven by logrotate's own dry run where logrotate
|
||||
// is installed, because a base configuration that does not parse stops every rotation on the machine.
|
||||
|
||||
import (
|
||||
"os"
|
||||
"os/exec"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestItDeclaresThePackageTheBaseAndTheTimer(t *testing.T) {
|
||||
m := manifest(t)
|
||||
if p := m.resource(t, "package"); p["package"] != "logrotate" {
|
||||
t.Fatalf("%v", p)
|
||||
}
|
||||
c := m.resource(t, "config")
|
||||
if c["path"] != BaseConf || c["into"] != nil || !strings.HasPrefix(c["content"].(string), "# The mesh's (module logrotate") {
|
||||
t.Fatalf("%v", c)
|
||||
}
|
||||
if !strings.Contains(c["content"].(string), "\ninclude "+RulesDir+"\n") {
|
||||
t.Fatal("the base must include the packages' rules, or nothing of theirs rotates")
|
||||
}
|
||||
if strings.Contains(c["content"].(string), "olddir") {
|
||||
t.Fatal("olddir flattens logs of different directories into one, where two of one name collide")
|
||||
}
|
||||
timer := m.resource(t, "timer")
|
||||
if timer["unit"] != "logrotate.timer" || timer["state"] != "running" || timer["boot"] != "enabled" {
|
||||
t.Fatalf("%v", timer)
|
||||
}
|
||||
}
|
||||
|
||||
func TestTheBaseParses(t *testing.T) {
|
||||
logrotate, err := exec.LookPath("logrotate")
|
||||
if err != nil {
|
||||
t.Skip("logrotate is not installed here; the base configuration is not dry-run")
|
||||
}
|
||||
dir := t.TempDir()
|
||||
content := strings.ReplaceAll(manifest(t).resource(t, "config")["content"].(string), "include "+RulesDir, "include "+filepath.Join(dir, "d"))
|
||||
if err := os.Mkdir(filepath.Join(dir, "d"), 0o755); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
conf := filepath.Join(dir, "logrotate.conf")
|
||||
if err := os.WriteFile(conf, []byte(content), 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
out, err := exec.Command(logrotate, "-d", "-s", filepath.Join(dir, "state"), conf).CombinedOutput()
|
||||
if err != nil || strings.Contains(string(out), "error:") {
|
||||
t.Fatalf("logrotate -d: %v\n%s", err, out)
|
||||
}
|
||||
}
|
||||
@@ -1,80 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"os"
|
||||
"testing"
|
||||
)
|
||||
|
||||
type resource map[string]any
|
||||
|
||||
type manifestShape struct {
|
||||
Module string `json:"module"`
|
||||
Version string `json:"version"`
|
||||
Capabilities []string `json:"capabilities"`
|
||||
Claims []map[string]any `json:"claims"`
|
||||
Tools []string `json:"tools"`
|
||||
Resources []resource `json:"resources"`
|
||||
Build struct {
|
||||
Artifacts []map[string]any `json:"artifacts"`
|
||||
} `json:"build"`
|
||||
}
|
||||
|
||||
func manifest(t *testing.T) manifestShape {
|
||||
t.Helper()
|
||||
raw, err := os.ReadFile("../../module.json")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var m manifestShape
|
||||
if err := json.Unmarshal(raw, &m); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return m
|
||||
}
|
||||
|
||||
func (m manifestShape) resource(t *testing.T, id string) resource {
|
||||
t.Helper()
|
||||
for _, r := range m.Resources {
|
||||
if r["id"] == id {
|
||||
return r
|
||||
}
|
||||
}
|
||||
t.Fatalf("no resource %s", id)
|
||||
return nil
|
||||
}
|
||||
|
||||
// TestToolsAreTheManifests holds the served tools and the manifest's list to one another, and the
|
||||
// bundle to the shape the builder compiles and the runtime loads.
|
||||
func TestToolsAreTheManifests(t *testing.T) {
|
||||
m := manifest(t)
|
||||
names := map[string]bool{}
|
||||
for _, tool := range tools(machine(nil, 1000)) {
|
||||
if names[tool.Name] {
|
||||
t.Errorf("%s is served twice", tool.Name)
|
||||
}
|
||||
names[tool.Name] = true
|
||||
}
|
||||
for _, want := range m.Tools {
|
||||
if !names[want] {
|
||||
t.Errorf("the manifest lists %s and the bundle does not serve it", want)
|
||||
}
|
||||
delete(names, want)
|
||||
}
|
||||
if len(names) != 0 {
|
||||
t.Errorf("served and not listed: %v", names)
|
||||
}
|
||||
var tools map[string]any
|
||||
for _, a := range m.Build.Artifacts {
|
||||
if a["name"] == "tools" {
|
||||
tools = a
|
||||
}
|
||||
}
|
||||
if tools == nil || tools["kind"] != "bundle" || tools["language"] != "go" || tools["system"] != "arch" ||
|
||||
tools["from"] != "cmd/"+binaryName || tools["binary"] != binaryName {
|
||||
t.Fatalf("the tools artifact: %v", tools)
|
||||
}
|
||||
if loads, _ := tools["loads"].([]any); len(loads) != 1 || loads[0] != binaryName {
|
||||
t.Fatalf("loads: %v", tools["loads"])
|
||||
}
|
||||
}
|
||||
@@ -1,5 +0,0 @@
|
||||
module logrotate
|
||||
|
||||
go 1.22
|
||||
|
||||
require git.novox.be/novox/mesh-sdk/go v0.1.6
|
||||
@@ -1,2 +0,0 @@
|
||||
git.novox.be/novox/mesh-sdk/go v0.1.6 h1:9qzdYONYbJdWcu6sxQcq9v1LI0JxcfkiKYkMUzJSkVQ=
|
||||
git.novox.be/novox/mesh-sdk/go v0.1.6/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=
|
||||
@@ -1,53 +0,0 @@
|
||||
{
|
||||
"module": "logrotate",
|
||||
"version": "1",
|
||||
"capabilities": [
|
||||
"package-manager",
|
||||
"service-manager"
|
||||
],
|
||||
"tools": [
|
||||
"logrotate_status",
|
||||
"logrotate_configs",
|
||||
"logrotate_check",
|
||||
"logrotate_big_logs",
|
||||
"logrotate_force",
|
||||
"logrotate_journal_usage",
|
||||
"logrotate_journal_vacuum"
|
||||
],
|
||||
"resources": [
|
||||
{
|
||||
"id": "package",
|
||||
"type": "package",
|
||||
"package": "logrotate"
|
||||
},
|
||||
{
|
||||
"id": "config",
|
||||
"type": "file",
|
||||
"path": "/etc/logrotate.conf",
|
||||
"mode": "0644",
|
||||
"content": "# The mesh's (module logrotate, novox/hq to-be 42): the base configuration every rotation inherits.\n# Written whole at every push; an edit here is overwritten. Each package's own rules are in\n# /etc/logrotate.d and stay the packages'.\n\n# Weekly, four weeks kept, a new empty log created after each rotation.\nweekly\nrotate 4\ncreate\n\n# Rotated logs are compressed, one rotation late, so a program still writing to the file it had open\n# loses nothing to the compression.\ncompress\ndelaycompress\n\n# A package's replaced configuration is never read as a rule.\ntabooext + .pacorig .pacnew .pacsave\n\ninclude /etc/logrotate.d\n\n/var/log/wtmp {\n monthly\n create 0664 root utmp\n minsize 1M\n rotate 1\n}\n\n/var/log/btmp {\n missingok\n monthly\n create 0600 root utmp\n rotate 1\n}\n"
|
||||
},
|
||||
{
|
||||
"id": "timer",
|
||||
"type": "service",
|
||||
"unit": "logrotate.timer",
|
||||
"state": "running",
|
||||
"boot": "enabled"
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "tools",
|
||||
"kind": "bundle",
|
||||
"language": "go",
|
||||
"system": "arch",
|
||||
"from": "cmd/logrotate-tools",
|
||||
"binary": "logrotate-tools",
|
||||
"loads": [
|
||||
"logrotate-tools"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,64 +0,0 @@
|
||||
# pacman
|
||||
|
||||
The package manager as a module (novox/hq to-be 42 Phase 1, ADR 0207, research 027). It holds the
|
||||
`node-package-manager` seat, which has no verbs yet. Every module that declares a package depends on
|
||||
that seat (ADR 0207).
|
||||
|
||||
## What it owns
|
||||
|
||||
- The `pacman` package. A component's own package belongs to the module that holds its seat
|
||||
(ADR 0207).
|
||||
- **`/etc/pacman.conf`, whole.** A block cannot be added to `[options]` by appending: anything added
|
||||
at the end of the file lands in the last repository's section. So the module owns the file:
|
||||
- The repositories are the union of what the four machines had enabled on 2026-10-04: `core`,
|
||||
`extra` and `multilib`. All four had all three.
|
||||
- The options are the distribution's defaults, plus `Color`, `ParallelDownloads = 5`,
|
||||
`VerbosePkgLists`, and `DownloadUser = alpm` (pacman 7; the `alpm` user exists on all four).
|
||||
- The manifest test runs `pacman-conf` on the rendered file and checks the repository list and the
|
||||
options as pacman reads them. It skips that check where `pacman-conf` is absent.
|
||||
- The host keeps the machine's previous file once, the first time it writes over it (ADR 0102).
|
||||
- **Mirrors.** The `reflector` package, `/etc/xdg/reflector/reflector.conf` written whole (https,
|
||||
Belgium, the Netherlands, Luxembourg, Germany, France, the 20 most recently synced, sorted by
|
||||
rate, saved to `/etc/pacman.d/mirrorlist`), and `reflector.timer` running and enabled. The mirror
|
||||
list stays reflector's to write, not the mesh's.
|
||||
- **Cache cleaning.** The `pacman-contrib` package and `paccache.timer` running and enabled. Each
|
||||
week it keeps the last three versions of each package.
|
||||
|
||||
## What it improves
|
||||
|
||||
- Mirrors were generated once and never again: in 2022, 2023 and 2024, and on one machine by its
|
||||
hosting provider's installer. The list is now refreshed weekly. The timer's first run is at the
|
||||
next weekly boundary; `pacman_mirrors` with `refresh: true` runs it at once.
|
||||
- Package caches were never cleaned. One workstation held 48 GB, of which paccache would free 33 GB.
|
||||
- Every machine has the same options. Only one had parallel downloads.
|
||||
|
||||
## What it leaves found
|
||||
|
||||
- `/etc/pacman.d/mirrorlist`, which reflector rewrites, and the stale `mirrorlist.pacnew`,
|
||||
`.bak`, `.original` and similar copies beside it.
|
||||
- `/etc/pacman.d/hooks`, the keyring, and the AUR helper. Packages from outside the repositories
|
||||
are research 027 question 1.
|
||||
|
||||
## Tools
|
||||
|
||||
| tool | | answers |
|
||||
|---|---|---|
|
||||
| `pacman_search` | r | `pacman -Ss`: repository, name, version, groups, installed and at which version, description |
|
||||
| `pacman_info` | r | `-Qi`, or `-Si` when not installed, with lists as lists |
|
||||
| `pacman_installed` | r | every package with version, explicit or dependency, foreign; filters and totals |
|
||||
| `pacman_owns` | r | which package owns a path, or `owned: false` |
|
||||
| `pacman_files` | r | what a package placed, bounded |
|
||||
| `pacman_updates` | r | `checkupdates`: what a full upgrade would change, never setting up a partial upgrade |
|
||||
| `pacman_upgrade` | a | starts `pacman -Syu --noconfirm` (sudo -n) as a transient unit that outlives the call; answers the unit and the news since the last upgrade; given the unit, how it went |
|
||||
| `pacman_orphans` | r | `pacman -Qdt` |
|
||||
| `pacman_remove_orphans` | a | `pacman -Rs` on named orphans, or all of them, as a unit of its own; a name that is not an orphan is refused |
|
||||
| `pacman_cache` | r/a | size, interrupted downloads, what paccache would free keeping N; `clean: true` removes them |
|
||||
| `pacman_history` | r | `/var/log/pacman.log`: installs, upgrades, downgrades, reinstalls and removals since a day, and the last full upgrade |
|
||||
| `pacman_mirrors` | r/a | the list, its generator and age, reflector's options, timer and last run; `refresh: true` starts reflector |
|
||||
| `pacman_foreign` | r | `pacman -Qm` |
|
||||
| `pacman_news` | r | the distribution's news since the last full upgrade (or a day), over https; no network is `reachable: false` |
|
||||
| `pacman_config` | r | `pacman-conf`: options, repositories, and whether `/etc/pacman.conf` is the module's |
|
||||
|
||||
A transaction never runs as the tool's own child. An upgrade takes longer than the 20 s a call may
|
||||
take, and a pacman killed mid-transaction leaves a half-upgraded machine and a lock. So a transaction
|
||||
runs as a transient unit (`systemd-run`, named `mesh-pacman-…`), and its log is read from the journal.
|
||||
@@ -1,236 +0,0 @@
|
||||
package main
|
||||
|
||||
// Acting on the package manager (novox/hq to-be 42 Phase 1, research 026/05): an upgrade, removing
|
||||
// orphans, cleaning the cache.
|
||||
//
|
||||
// **A transaction is never this process's child.** A tool call is ended after twenty seconds, and an
|
||||
// upgrade takes minutes; a pacman killed in the middle of a transaction leaves a half-upgraded machine
|
||||
// and a lock. So a transaction runs as a transient unit of the service manager (`systemd-run`), started
|
||||
// through sudo -n: it belongs to the machine, outlives the call, and logs to the journal, from which
|
||||
// the tool answers what it did.
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"regexp"
|
||||
"strconv"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// DBLock is the file pacman holds while a transaction runs.
|
||||
const DBLock = "/var/lib/pacman/db.lck"
|
||||
|
||||
// unitPrefix names every transient unit the module's tools start, so one is recognised as the mesh's.
|
||||
const unitPrefix = "mesh-pacman-"
|
||||
|
||||
func (m *Machine) locked() bool {
|
||||
_, err := m.ReadFile(DBLock)
|
||||
return err == nil
|
||||
}
|
||||
|
||||
// transaction starts pacman with these arguments as a transient unit, waiting for it when asked.
|
||||
func (m *Machine) transaction(what string, wait bool, args ...string) (string, Ran, error) {
|
||||
if m.locked() {
|
||||
return "", Ran{}, fmt.Errorf("another pacman holds %s: a transaction is running, or one was killed and left its lock", DBLock)
|
||||
}
|
||||
unit := fmt.Sprintf("%s%s-%d", unitPrefix, what, m.Now().Unix())
|
||||
run := []string{"--unit=" + unit, "--description=pacman " + strings.Join(args, " ") + ", started by the mesh's pacman tools", "--quiet"}
|
||||
if wait {
|
||||
run = append(run, "--wait")
|
||||
}
|
||||
run = append(run, append([]string{"pacman"}, args...)...)
|
||||
r, err := m.RootRan("systemd-run", run...)
|
||||
if err == nil && !wait && r.Status != 0 {
|
||||
err = failure("systemd-run", "sudo", r)
|
||||
}
|
||||
return unit, r, err
|
||||
}
|
||||
|
||||
// journal is the last lines a unit logged, read through sudo -n: the operator account need not be
|
||||
// in a group that reads the system journal.
|
||||
func (m *Machine) journal(unit string, n int) []string {
|
||||
out, err := m.Root("journalctl", "--no-pager", "-o", "cat", "-n", strconv.Itoa(n), "-u", unit)
|
||||
if err != nil {
|
||||
return []string{"(the journal could not be read: " + err.Error() + ")"}
|
||||
}
|
||||
return lines(out)
|
||||
}
|
||||
|
||||
// Upgrade starts a full system upgrade as a transient unit and answers at once, with the
|
||||
// distribution's news since the last upgrade; or, given a unit it started, answers how it went.
|
||||
func (m *Machine) Upgrade(unit string, n int) (map[string]any, error) {
|
||||
if unit != "" {
|
||||
return m.UpgradeStatus(unit, n)
|
||||
}
|
||||
news := m.News("")
|
||||
started, _, err := m.transaction("upgrade", false, "-Syu", "--noconfirm")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return map[string]any{
|
||||
"started": started,
|
||||
"follow": "call pacman_upgrade with this unit to read how it goes",
|
||||
"news": news,
|
||||
}, nil
|
||||
}
|
||||
|
||||
var unitName = regexp.MustCompile(`^` + unitPrefix + `[a-z-]+-[0-9]+$`)
|
||||
|
||||
// UpgradeStatus is a transaction unit's state and the tail of what it logged.
|
||||
func (m *Machine) UpgradeStatus(unit string, n int) (map[string]any, error) {
|
||||
if !unitName.MatchString(unit) {
|
||||
return nil, fmt.Errorf("%q is not a unit the pacman tools started", unit)
|
||||
}
|
||||
p, err := m.unitProps(unit, "LoadState", "ActiveState", "SubState", "Result", "ExecMainStatus")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
out := map[string]any{"unit": unit, "running": p["ActiveState"] == "active" || p["ActiveState"] == "activating", "log": m.journal(unit, n)}
|
||||
switch {
|
||||
case p["LoadState"] == "not-found":
|
||||
// A transient unit that finished well is let go by the service manager; one that failed stays.
|
||||
out["finished"], out["succeeded"] = true, true
|
||||
case p["ActiveState"] == "failed":
|
||||
out["finished"], out["succeeded"], out["exit_status"] = true, false, p["ExecMainStatus"]
|
||||
default:
|
||||
out["finished"] = !out["running"].(bool)
|
||||
out["succeeded"] = p["Result"] == "success" && p["ExecMainStatus"] == "0"
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// RemoveOrphans removes the named orphans, or every one when all is said; a name that is not an
|
||||
// orphan is refused, so this never removes a package something needs or someone chose. Their
|
||||
// configuration files changed on the machine are kept by the package manager as .pacsave.
|
||||
func (m *Machine) RemoveOrphans(names []string, all bool) (map[string]any, error) {
|
||||
listed, err := m.Orphans()
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
orphans := map[string]bool{}
|
||||
var every []string
|
||||
for _, p := range listed["orphans"].([]map[string]string) {
|
||||
orphans[p["name"]] = true
|
||||
every = append(every, p["name"])
|
||||
}
|
||||
switch {
|
||||
case all && len(names) > 0:
|
||||
return nil, fmt.Errorf("name the orphans to remove, or say all — not both")
|
||||
case all:
|
||||
names = every
|
||||
case len(names) == 0:
|
||||
return nil, fmt.Errorf("name the orphans to remove (pacman_orphans lists them), or say all: true")
|
||||
}
|
||||
for _, n := range names {
|
||||
if !orphans[n] {
|
||||
return nil, fmt.Errorf("%s is not an orphan here, and is not removed", n)
|
||||
}
|
||||
}
|
||||
if len(names) == 0 {
|
||||
return map[string]any{"removed": []string{}, "note": "there are no orphans"}, nil
|
||||
}
|
||||
unit, r, err := m.transaction("remove-orphans", true, append([]string{"-Rs", "--noconfirm", "--"}, names...)...)
|
||||
if err != nil {
|
||||
if r.Status == 124 {
|
||||
return map[string]any{"unit": unit, "running": true, "note": "still running after the call's limit; it continues as its unit"}, nil
|
||||
}
|
||||
return nil, err
|
||||
}
|
||||
answer := map[string]any{"unit": unit, "log": m.journal(unit, 100)}
|
||||
if r.Status != 0 {
|
||||
answer["removed"] = []string{}
|
||||
answer["error"] = fmt.Sprintf("pacman failed with status %d; nothing is removed by a transaction that failed", r.Status)
|
||||
return answer, nil
|
||||
}
|
||||
answer["removed"] = names
|
||||
return answer, nil
|
||||
}
|
||||
|
||||
// PkgCache is the package cache: its size, what cleaning would free, and its timer.
|
||||
type PkgCache struct {
|
||||
Directory string `json:"directory"`
|
||||
Files int `json:"package_files"`
|
||||
Bytes int64 `json:"bytes"`
|
||||
LeftDownloads int `json:"interrupted_download_dirs"`
|
||||
Keep int `json:"keep"`
|
||||
Candidates int `json:"candidates"`
|
||||
Frees string `json:"frees"`
|
||||
Uninstalled bool `json:"uninstalled_only"`
|
||||
Cleaned bool `json:"cleaned"`
|
||||
Timer map[string]string `json:"paccache_timer"`
|
||||
Said string `json:"said"`
|
||||
}
|
||||
|
||||
// CacheDir is where pacman keeps what it downloaded.
|
||||
const CacheDir = "/var/cache/pacman/pkg"
|
||||
|
||||
var (
|
||||
dryRun = regexp.MustCompile(`finished dry run: (\d+) candidates \(disk space saved: ([^)]+)\)`)
|
||||
removed = regexp.MustCompile(`finished: (\d+) packages removed \(disk space saved: ([^)]+)\)`)
|
||||
noPrune = regexp.MustCompile(`no candidate packages found for pruning`)
|
||||
)
|
||||
|
||||
// Cache reads the cache, says what paccache would remove keeping the last keep versions of each
|
||||
// package (or only those of packages no longer installed), and with clean removes them.
|
||||
func (m *Machine) Cache(keep int, uninstalled, clean bool) (PkgCache, error) {
|
||||
c := PkgCache{Directory: CacheDir, Keep: keep, Uninstalled: uninstalled}
|
||||
out, err := m.Out("find", CacheDir, "-mindepth", "1", "-maxdepth", "1", "-printf", "%y %s %f\n")
|
||||
if err != nil && strings.TrimSpace(out) == "" {
|
||||
return c, err
|
||||
}
|
||||
for _, l := range lines(out) {
|
||||
f := strings.SplitN(l, " ", 3)
|
||||
if len(f) != 3 {
|
||||
continue
|
||||
}
|
||||
switch {
|
||||
case f[0] == "d" && strings.HasPrefix(f[2], "download-"):
|
||||
c.LeftDownloads++
|
||||
case f[0] == "f":
|
||||
size, _ := strconv.ParseInt(f[1], 10, 64)
|
||||
c.Bytes += size
|
||||
if strings.Contains(f[2], ".pkg.tar") && !strings.HasSuffix(f[2], ".sig") {
|
||||
c.Files++
|
||||
}
|
||||
}
|
||||
}
|
||||
args := []string{"-k", strconv.Itoa(keep)}
|
||||
if uninstalled {
|
||||
args = append(args, "-u")
|
||||
}
|
||||
if clean {
|
||||
said, err := m.Root("paccache", append([]string{"-r"}, args...)...)
|
||||
if err != nil {
|
||||
return c, err
|
||||
}
|
||||
c.Cleaned, c.Said = true, firstLine(lastLines(said, 1))
|
||||
if x := removed.FindStringSubmatch(said); x != nil {
|
||||
c.Candidates, _ = strconv.Atoi(x[1])
|
||||
c.Frees = x[2]
|
||||
}
|
||||
} else {
|
||||
r := m.Run(bg(), "paccache", append([]string{"-d"}, args...)...)
|
||||
if r.Err != "" || r.Status != 0 && !noPrune.MatchString(r.Stdout+r.Stderr) {
|
||||
if r.Err == "ENOENT" {
|
||||
return c, fmt.Errorf("paccache is not installed: it comes with pacman-contrib, which this module declares")
|
||||
}
|
||||
return c, failure("paccache", "paccache", r)
|
||||
}
|
||||
c.Said = firstLine(lastLines(r.Stdout+r.Stderr, 1))
|
||||
if x := dryRun.FindStringSubmatch(r.Stdout + r.Stderr); x != nil {
|
||||
c.Candidates, _ = strconv.Atoi(x[1])
|
||||
c.Frees = x[2]
|
||||
}
|
||||
}
|
||||
if t, err := m.unitProps("paccache.timer", "ActiveState", "UnitFileState", "LastTriggerUSec", "NextElapseUSecRealtime"); err == nil {
|
||||
c.Timer = t
|
||||
}
|
||||
return c, nil
|
||||
}
|
||||
|
||||
func lastLines(text string, n int) string {
|
||||
ls := lines(text)
|
||||
if len(ls) > n {
|
||||
ls = ls[len(ls)-n:]
|
||||
}
|
||||
return strings.Join(ls, "\n")
|
||||
}
|
||||
@@ -1,125 +0,0 @@
|
||||
package main
|
||||
|
||||
// The package manager's own record, /var/log/pacman.log (novox/hq research 026/05: "installs and
|
||||
// upgrades from the log"): every install, upgrade, downgrade, reinstall and removal since a date,
|
||||
// and when the machine was last fully upgraded.
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"regexp"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// PacmanLog is where pacman writes what it did.
|
||||
const PacmanLog = "/var/log/pacman.log"
|
||||
|
||||
// Event is one package changed by a transaction.
|
||||
type Event struct {
|
||||
Time string `json:"time"`
|
||||
Action string `json:"action"`
|
||||
Package string `json:"package"`
|
||||
Version string `json:"version"`
|
||||
From string `json:"from,omitempty"`
|
||||
}
|
||||
|
||||
var (
|
||||
logLine = regexp.MustCompile(`^\[([^\]]+)\] \[ALPM\] (installed|upgraded|downgraded|reinstalled|removed) (\S+) \((.*)\)$`)
|
||||
fullUpdate = regexp.MustCompile(`^\[([^\]]+)\] \[PACMAN\] starting full system upgrade`)
|
||||
)
|
||||
|
||||
// Actions are what a history may be narrowed to.
|
||||
var Actions = []string{"installed", "upgraded", "downgraded", "reinstalled", "removed"}
|
||||
|
||||
func logTime(s string) (time.Time, bool) {
|
||||
for _, layout := range []string{"2006-01-02T15:04:05-0700", "2006-01-02 15:04"} {
|
||||
if t, err := time.Parse(layout, s); err == nil {
|
||||
return t, true
|
||||
}
|
||||
}
|
||||
return time.Time{}, false
|
||||
}
|
||||
|
||||
// ParseLog reads pacman.log's package events since a time, and the last full upgrade it records.
|
||||
func ParseLog(text string, since time.Time) (events []Event, lastUpgrade time.Time) {
|
||||
for _, l := range strings.Split(text, "\n") {
|
||||
if u := fullUpdate.FindStringSubmatch(l); u != nil {
|
||||
if t, ok := logTime(u[1]); ok {
|
||||
lastUpgrade = t
|
||||
}
|
||||
continue
|
||||
}
|
||||
e := logLine.FindStringSubmatch(l)
|
||||
if e == nil {
|
||||
continue
|
||||
}
|
||||
t, ok := logTime(e[1])
|
||||
if !ok || t.Before(since) {
|
||||
continue
|
||||
}
|
||||
ev := Event{Time: t.Format(time.RFC3339), Action: e[2], Package: e[3], Version: e[4]}
|
||||
if from, to, ok := strings.Cut(e[4], " -> "); ok {
|
||||
ev.From, ev.Version = from, to
|
||||
}
|
||||
events = append(events, ev)
|
||||
}
|
||||
return events, lastUpgrade
|
||||
}
|
||||
|
||||
// LastUpgrade is when the machine last started a full upgrade, from pacman's log.
|
||||
func (m *Machine) LastUpgrade() (time.Time, error) {
|
||||
text, err := m.ReadFile(PacmanLog)
|
||||
if err != nil {
|
||||
return time.Time{}, err
|
||||
}
|
||||
_, last := ParseLog(string(text), m.Now())
|
||||
return last, nil
|
||||
}
|
||||
|
||||
// History is the package events since a day (YYYY-MM-DD; thirty days ago by default), narrowed to
|
||||
// an action and a name, the newest last and at most limit of them.
|
||||
func (m *Machine) History(since, action, match string, limit int) (map[string]any, error) {
|
||||
from := m.Now().AddDate(0, 0, -30)
|
||||
if since != "" {
|
||||
t, err := time.ParseInLocation("2006-01-02", since, time.Local)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("since %q is not a day as YYYY-MM-DD", since)
|
||||
}
|
||||
from = t
|
||||
}
|
||||
if action != "" && !contains(Actions, action) {
|
||||
return nil, fmt.Errorf("action %q is one of %s", action, strings.Join(Actions, ", "))
|
||||
}
|
||||
text, err := m.ReadFile(PacmanLog)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("reading %s: %w", PacmanLog, err)
|
||||
}
|
||||
all, last := ParseLog(string(text), from)
|
||||
events := []Event{}
|
||||
counts := map[string]int{}
|
||||
for _, e := range all {
|
||||
if action != "" && e.Action != action || match != "" && !strings.Contains(e.Package, match) {
|
||||
continue
|
||||
}
|
||||
events = append(events, e)
|
||||
counts[e.Action]++
|
||||
}
|
||||
truncated := false
|
||||
if len(events) > limit {
|
||||
events, truncated = events[len(events)-limit:], true
|
||||
}
|
||||
out := map[string]any{"since": from.Format(time.RFC3339), "count": len(events), "by_action": counts, "events": events, "truncated": truncated}
|
||||
if !last.IsZero() {
|
||||
out["last_full_upgrade"] = last.Format(time.RFC3339)
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
func contains(list []string, want string) bool {
|
||||
for _, s := range list {
|
||||
if s == want {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
@@ -1,289 +0,0 @@
|
||||
package main
|
||||
|
||||
// The commands this bundle runs on its machine, and who runs them.
|
||||
//
|
||||
// Who asks. The node's tool runtime runs as the operator account, not root (novox/hq ADR 0175 §4),
|
||||
// and launches this binary as a process of its own (ADR 0188, ADR 0193) with the runtime's words —
|
||||
// HOME, a PATH, MESH_OPERATOR_ACCOUNT — and no session words. Reading needs nothing more; what only
|
||||
// root may do goes through `sudo -n`, as the packet filter's, the service manager's and the
|
||||
// intrusion prevention's tools do (to-be 38 WP4), and the `sudo` module is what declares that the
|
||||
// account may (to-be 42, research 027). A refusal is named by how it failed, never read as an
|
||||
// empty answer.
|
||||
//
|
||||
// The runner is injected, so every tool is tested over a fake one without the machine.
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"errors"
|
||||
"fmt"
|
||||
"io/fs"
|
||||
"os"
|
||||
"os/exec"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// Ran is what one command did: its output, its exit status, and why it never ran to an answer.
|
||||
type Ran struct {
|
||||
Stdout string
|
||||
Stderr string
|
||||
Status int
|
||||
// Err is "ENOENT" when the program is not there, or that it was ended for taking too long.
|
||||
Err string
|
||||
}
|
||||
|
||||
// Runner runs one command, so the tools can be tested without the machine.
|
||||
type Runner func(ctx context.Context, name string, args ...string) Ran
|
||||
|
||||
// CallTimeout is how long one command may take: below the runtime's thirty-second call limit, so a
|
||||
// command that hangs is answered as such rather than as a call the runtime gave up on.
|
||||
const CallTimeout = 20 * time.Second
|
||||
|
||||
// outputLimit bounds what one command may hand back, so a runaway listing cannot exhaust the
|
||||
// process; well above anything a tool answers.
|
||||
const outputLimit = 16 << 20
|
||||
|
||||
type bounded struct {
|
||||
bytes.Buffer
|
||||
cut bool
|
||||
}
|
||||
|
||||
func (b *bounded) Write(p []byte) (int, error) {
|
||||
if room := outputLimit - b.Len(); room < len(p) {
|
||||
if room > 0 {
|
||||
b.Buffer.Write(p[:room])
|
||||
}
|
||||
b.cut = true
|
||||
return len(p), nil
|
||||
}
|
||||
return b.Buffer.Write(p)
|
||||
}
|
||||
|
||||
// ExecRunner runs a command on this machine, in the C locale so what is parsed is one language.
|
||||
func ExecRunner(ctx context.Context, name string, args ...string) Ran {
|
||||
ctx, cancel := context.WithTimeout(ctx, CallTimeout)
|
||||
defer cancel()
|
||||
cmd := exec.CommandContext(ctx, name, args...)
|
||||
cmd.Env = append(os.Environ(), "LC_ALL=C")
|
||||
var out, errb bounded
|
||||
cmd.Stdout, cmd.Stderr = &out, &errb
|
||||
err := cmd.Run()
|
||||
r := Ran{Stdout: out.String(), Stderr: errb.String()}
|
||||
if ctx.Err() == context.DeadlineExceeded {
|
||||
r.Status, r.Err = 124, fmt.Sprintf("no answer within %d s", int(CallTimeout.Seconds()))
|
||||
return r
|
||||
}
|
||||
var exit *exec.ExitError
|
||||
switch {
|
||||
case err == nil:
|
||||
case errors.As(err, &exit):
|
||||
r.Status = exit.ExitCode()
|
||||
case errors.Is(err, exec.ErrNotFound) || errors.Is(err, fs.ErrNotExist):
|
||||
r.Status, r.Err = 127, "ENOENT"
|
||||
default:
|
||||
r.Status, r.Err = 126, err.Error()
|
||||
}
|
||||
return r
|
||||
}
|
||||
|
||||
// Escalated is the command as it is run: as given when this process is root, else through sudo
|
||||
// without a prompt.
|
||||
func Escalated(uid int, name string, args ...string) (string, []string) {
|
||||
if uid == 0 {
|
||||
return name, args
|
||||
}
|
||||
return "sudo", append([]string{"-n", name}, args...)
|
||||
}
|
||||
|
||||
// Machine is this machine as the tools see it: a runner, who this process is, and its files.
|
||||
type Machine struct {
|
||||
Run Runner
|
||||
UID int
|
||||
User string
|
||||
Account string
|
||||
ReadFile func(path string) ([]byte, error)
|
||||
Now func() time.Time
|
||||
Sleep func(time.Duration)
|
||||
}
|
||||
|
||||
// ThisMachine is the machine the runtime launched this bundle on.
|
||||
func ThisMachine() *Machine {
|
||||
user := os.Getenv("USER")
|
||||
if user == "" {
|
||||
user = os.Getenv("LOGNAME")
|
||||
}
|
||||
account := strings.TrimSpace(os.Getenv("MESH_OPERATOR_ACCOUNT"))
|
||||
if account == "" {
|
||||
account = user
|
||||
}
|
||||
return &Machine{Run: ExecRunner, UID: os.Getuid(), User: user, Account: account, ReadFile: os.ReadFile, Now: time.Now, Sleep: time.Sleep}
|
||||
}
|
||||
|
||||
// Out runs a command that only reads, and fails with what went wrong named.
|
||||
func (m *Machine) Out(name string, args ...string) (string, error) {
|
||||
r := m.Run(context.Background(), name, args...)
|
||||
if r.Status == 0 && r.Err == "" {
|
||||
return r.Stdout, nil
|
||||
}
|
||||
return r.Stdout, failure(name, name, r)
|
||||
}
|
||||
|
||||
// Root runs a command that needs root, escalated when this process is not.
|
||||
func (m *Machine) Root(name string, args ...string) (string, error) {
|
||||
program, argv := Escalated(m.UID, name, args...)
|
||||
r := m.Run(context.Background(), program, argv...)
|
||||
if r.Status == 0 && r.Err == "" {
|
||||
return r.Stdout, nil
|
||||
}
|
||||
return r.Stdout, failure(name, program, r)
|
||||
}
|
||||
|
||||
// RootRan is Root's raw answer, for a command whose non-zero status is itself an answer.
|
||||
func (m *Machine) RootRan(name string, args ...string) (Ran, error) {
|
||||
program, argv := Escalated(m.UID, name, args...)
|
||||
r := m.Run(context.Background(), program, argv...)
|
||||
if r.Err != "" || (program == "sudo" && sudoRefused(r)) {
|
||||
return r, failure(name, program, r)
|
||||
}
|
||||
return r, nil
|
||||
}
|
||||
|
||||
func sudoRefused(r Ran) bool {
|
||||
return strings.HasPrefix(strings.TrimSpace(r.Stderr), "sudo:")
|
||||
}
|
||||
|
||||
// failure names what failed by how it failed: the program missing is a spawn error, sudo missing
|
||||
// or refusing speaks for itself, and the rest is the command's own first line.
|
||||
func failure(cmd, program string, r Ran) error {
|
||||
said := strings.TrimSpace(r.Stderr + "\n" + r.Stdout)
|
||||
if r.Err == "ENOENT" {
|
||||
if program == "sudo" {
|
||||
return fmt.Errorf("%s needs root for this, and sudo is not installed here for the runtime's account to escalate with", cmd)
|
||||
}
|
||||
return fmt.Errorf("%s is not installed on this machine", cmd)
|
||||
}
|
||||
if r.Err != "" {
|
||||
return fmt.Errorf("%s did not answer: %s", cmd, r.Err)
|
||||
}
|
||||
if program == "sudo" && sudoRefused(r) {
|
||||
if strings.Contains(said, "command not found") {
|
||||
return fmt.Errorf("%s is not installed on this machine", cmd)
|
||||
}
|
||||
return fmt.Errorf("%s needs root for this and the runtime's account may not run it without a prompt: %s", cmd, firstLine(said))
|
||||
}
|
||||
if line := firstLine(said); line != "" {
|
||||
return fmt.Errorf("%s failed (%d): %s", cmd, r.Status, line)
|
||||
}
|
||||
return fmt.Errorf("%s failed with status %d", cmd, r.Status)
|
||||
}
|
||||
|
||||
func firstLine(text string) string {
|
||||
for _, l := range strings.Split(text, "\n") {
|
||||
if l = strings.TrimSpace(l); l != "" {
|
||||
return l
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
func lines(text string) []string {
|
||||
var out []string
|
||||
for _, l := range strings.Split(text, "\n") {
|
||||
if l = strings.TrimRight(l, "\r"); strings.TrimSpace(l) != "" {
|
||||
out = append(out, l)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// text is a string argument; required says whether it may be absent. It is never something a
|
||||
// command would read as an option, which under sudo would be root's option.
|
||||
func text(args map[string]any, key string, required bool) (string, error) {
|
||||
raw, present := args[key]
|
||||
if !present || raw == nil {
|
||||
if required {
|
||||
return "", fmt.Errorf("%s is required", key)
|
||||
}
|
||||
return "", nil
|
||||
}
|
||||
s, ok := raw.(string)
|
||||
if !ok {
|
||||
return "", fmt.Errorf("%s must be a string", key)
|
||||
}
|
||||
s = strings.TrimSpace(s)
|
||||
if required && s == "" {
|
||||
return "", fmt.Errorf("%s is required", key)
|
||||
}
|
||||
if strings.HasPrefix(s, "-") || strings.ContainsRune(s, 0) || strings.ContainsAny(s, "\n\r") {
|
||||
return "", fmt.Errorf("%s %q is not a value this tool passes on", key, s)
|
||||
}
|
||||
return s, nil
|
||||
}
|
||||
|
||||
// whole is a whole-number argument with a default, kept within bounds.
|
||||
func whole(args map[string]any, key string, def, least, most int) (int, error) {
|
||||
raw, present := args[key]
|
||||
if !present || raw == nil {
|
||||
return def, nil
|
||||
}
|
||||
f, ok := raw.(float64)
|
||||
if !ok || f != float64(int(f)) {
|
||||
return 0, fmt.Errorf("%s must be a whole number", key)
|
||||
}
|
||||
n := int(f)
|
||||
if n < least {
|
||||
return 0, fmt.Errorf("%s must be at least %d", key, least)
|
||||
}
|
||||
if n > most {
|
||||
n = most
|
||||
}
|
||||
return n, nil
|
||||
}
|
||||
|
||||
// flag is a boolean argument, false when absent.
|
||||
func flag(args map[string]any, key string) (bool, error) {
|
||||
raw, present := args[key]
|
||||
if !present || raw == nil {
|
||||
return false, nil
|
||||
}
|
||||
b, ok := raw.(bool)
|
||||
if !ok {
|
||||
return false, fmt.Errorf("%s must be true or false", key)
|
||||
}
|
||||
return b, nil
|
||||
}
|
||||
|
||||
// schema is a tool's input: its properties and the ones it requires.
|
||||
func schema(properties map[string]any, required ...string) map[string]any {
|
||||
s := map[string]any{"type": "object", "properties": properties}
|
||||
if len(required) > 0 {
|
||||
s["required"] = required
|
||||
}
|
||||
return s
|
||||
}
|
||||
|
||||
// unitProps reads a unit's properties as systemctl shows them.
|
||||
func (m *Machine) unitProps(unit string, props ...string) (map[string]string, error) {
|
||||
args := []string{"show", unit, "--no-pager"}
|
||||
for _, p := range props {
|
||||
args = append(args, "--property="+p)
|
||||
}
|
||||
out, err := m.Out("systemctl", args...)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return keyValues(out, "="), nil
|
||||
}
|
||||
|
||||
// keyValues reads `key<sep>value` lines; a line without the separator is skipped.
|
||||
func keyValues(out, sep string) map[string]string {
|
||||
kv := map[string]string{}
|
||||
for _, l := range strings.Split(out, "\n") {
|
||||
k, v, ok := strings.Cut(l, sep)
|
||||
if ok {
|
||||
kv[strings.TrimSpace(k)] = strings.TrimSpace(v)
|
||||
}
|
||||
}
|
||||
return kv
|
||||
}
|
||||
@@ -1,107 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
// call is one command a fake runner was asked to run.
|
||||
type call struct {
|
||||
name string
|
||||
args []string
|
||||
}
|
||||
|
||||
func (c call) String() string {
|
||||
if len(c.args) == 0 {
|
||||
return c.name
|
||||
}
|
||||
return c.name + " " + strings.Join(c.args, " ")
|
||||
}
|
||||
|
||||
// fake is a runner answering by the command line it is given, recording every call.
|
||||
func fake(answer func(c call) Ran, calls *[]call) Runner {
|
||||
return func(_ context.Context, name string, args ...string) Ran {
|
||||
c := call{name, append([]string(nil), args...)}
|
||||
if calls != nil {
|
||||
*calls = append(*calls, c)
|
||||
}
|
||||
return answer(c)
|
||||
}
|
||||
}
|
||||
|
||||
// byLine answers from a table keyed by the whole command line, and refuses anything else as a
|
||||
// command the test did not expect.
|
||||
func byLine(table map[string]Ran, calls *[]call) Runner {
|
||||
return fake(func(c call) Ran {
|
||||
if r, ok := table[c.String()]; ok {
|
||||
return r
|
||||
}
|
||||
return Ran{Status: 99, Stderr: "unexpected command: " + c.String()}
|
||||
}, calls)
|
||||
}
|
||||
|
||||
func machine(run Runner, uid int) *Machine {
|
||||
return &Machine{Run: run, UID: uid, User: "operator", Account: "operator",
|
||||
ReadFile: func(string) ([]byte, error) { return nil, errNoFile },
|
||||
Now: func() time.Time { return time.Date(2026, 10, 4, 12, 0, 0, 0, time.UTC) },
|
||||
Sleep: func(time.Duration) {}}
|
||||
}
|
||||
|
||||
type noFile struct{}
|
||||
|
||||
func (noFile) Error() string { return "no such file" }
|
||||
|
||||
var errNoFile = noFile{}
|
||||
|
||||
func TestAnActNeedingRootGoesThroughSudoWithoutAPromptUnlessThisIsRoot(t *testing.T) {
|
||||
if p, a := Escalated(1000, "visudo", "-c"); p != "sudo" || strings.Join(a, " ") != "-n visudo -c" {
|
||||
t.Fatalf("not root: %s %v", p, a)
|
||||
}
|
||||
if p, a := Escalated(0, "visudo", "-c"); p != "visudo" || strings.Join(a, " ") != "-c" {
|
||||
t.Fatalf("root: %s %v", p, a)
|
||||
}
|
||||
}
|
||||
|
||||
func TestFailuresAreNamedNeverReadAsEmpty(t *testing.T) {
|
||||
cases := []struct {
|
||||
r Ran
|
||||
want string
|
||||
}{
|
||||
{Ran{Status: 127, Err: "ENOENT"}, "sudo is not installed here"},
|
||||
{Ran{Status: 1, Stderr: "sudo: a password is required\n"}, "may not run it without a prompt: sudo: a password is required"},
|
||||
{Ran{Status: 124, Err: "no answer within 20 s"}, "did not answer: no answer within 20 s"},
|
||||
{Ran{Status: 2, Stderr: "boom\nmore"}, "failed (2): boom"},
|
||||
}
|
||||
for _, c := range cases {
|
||||
m := machine(fake(func(call) Ran { return c.r }, nil), 1000)
|
||||
if _, err := m.Root("thing"); err == nil || !strings.Contains(err.Error(), c.want) {
|
||||
t.Errorf("%+v: %v, want %q", c.r, err, c.want)
|
||||
}
|
||||
}
|
||||
m := machine(fake(func(call) Ran { return Ran{Status: 127, Err: "ENOENT"} }, nil), 1000)
|
||||
if _, err := m.Out("thing"); err == nil || !strings.Contains(err.Error(), "thing is not installed") {
|
||||
t.Errorf("a missing program: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAnArgumentIsNeverAnOption(t *testing.T) {
|
||||
for _, bad := range []any{"-rf", "a\nb", 3.0} {
|
||||
if _, err := text(map[string]any{"x": bad}, "x", true); err == nil {
|
||||
t.Errorf("%v was accepted", bad)
|
||||
}
|
||||
}
|
||||
if s, err := text(map[string]any{"x": " ok "}, "x", true); err != nil || s != "ok" {
|
||||
t.Errorf("a plain value: %q %v", s, err)
|
||||
}
|
||||
if _, err := text(map[string]any{}, "x", true); err == nil {
|
||||
t.Error("a missing required value was accepted")
|
||||
}
|
||||
if n, _ := whole(map[string]any{"n": 10000.0}, "n", 5, 1, 100); n != 100 {
|
||||
t.Errorf("not bounded: %d", n)
|
||||
}
|
||||
if _, err := whole(map[string]any{"n": 0.0}, "n", 5, 1, 100); err == nil {
|
||||
t.Error("below the least was accepted")
|
||||
}
|
||||
}
|
||||
@@ -1,278 +0,0 @@
|
||||
// pacman's tools bundle (novox/hq to-be 42 Phase 1, research 026/05): a process the node's runtime
|
||||
// launches and speaks MCP over stdio to, through the Go SDK (ADR 0188, ADR 0193). It reads the
|
||||
// package manager — search, info, what is installed and why, owners, files, updates, orphans,
|
||||
// foreign packages, history, mirrors, the configuration in force, the distribution's news — and acts
|
||||
// on it: a full upgrade, removing orphans, cleaning the cache, refreshing the mirrors. Acts go through
|
||||
// sudo -n, and a transaction runs as a unit of its own (acts.go says why).
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"os"
|
||||
|
||||
stdio "git.novox.be/novox/mesh-sdk/go"
|
||||
)
|
||||
|
||||
// binaryName is what the build names this bundle's executable: the manifest's `binary`.
|
||||
const binaryName = "pacman-tools"
|
||||
|
||||
func bg() context.Context { return context.Background() }
|
||||
|
||||
func main() {
|
||||
// An empty name serves as the module the runtime names (MESH_SERVED_MODULE): pacman.
|
||||
if err := stdio.Serve("", tools(ThisMachine())); err != nil {
|
||||
fmt.Fprintln(os.Stderr, err)
|
||||
os.Exit(1)
|
||||
}
|
||||
}
|
||||
|
||||
var (
|
||||
pkgArg = map[string]any{"type": "string", "description": "a package's name"}
|
||||
limitArg = func(def, most int) map[string]any {
|
||||
return map[string]any{"type": "integer", "description": fmt.Sprintf("at most this many (default %d, at most %d)", def, most)}
|
||||
}
|
||||
sinceArg = map[string]any{"type": "string", "description": "a day, YYYY-MM-DD"}
|
||||
)
|
||||
|
||||
func tools(m *Machine) []stdio.Tool {
|
||||
return []stdio.Tool{
|
||||
{
|
||||
Name: "pacman_search",
|
||||
Description: "Search the repositories (pacman -Ss): each package's repository, name, version, groups, whether it is installed and at which version, and its description.",
|
||||
Input: schema(map[string]any{"query": map[string]any{"type": "string", "description": "words, each a regular expression; all must match"}, "limit": limitArg(50, 500)}, "query"),
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
q, err := text(args, "query", true)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
n, err := whole(args, "limit", 50, 1, 500)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.Search(q, n)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "pacman_info",
|
||||
Description: "One package's details (pacman -Qi, or -Si when it is not installed): version, description, dependencies, what requires it, sizes, dates, install reason; lists as lists.",
|
||||
Input: schema(map[string]any{"package": pkgArg}, "package"),
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
p, err := text(args, "package", true)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.Info(p)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "pacman_installed",
|
||||
Description: "Installed packages with version, why each is installed (explicit or dependency) and whether it is foreign (in no repository); narrowed by name, reason or foreign; with totals.",
|
||||
Input: schema(map[string]any{
|
||||
"match": map[string]any{"type": "string", "description": "only names holding this"},
|
||||
"reason": map[string]any{"type": "string", "enum": []string{"explicit", "dependency"}},
|
||||
"foreign": map[string]any{"type": "boolean", "description": "only foreign packages"},
|
||||
"limit": limitArg(5000, 20000),
|
||||
}),
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
match, err := text(args, "match", false)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
reason, err := text(args, "reason", false)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if reason != "" && reason != "explicit" && reason != "dependency" {
|
||||
return nil, fmt.Errorf("reason is explicit or dependency")
|
||||
}
|
||||
foreign, err := flag(args, "foreign")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
n, err := whole(args, "limit", 5000, 1, 20000)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.Installed(match, reason, foreign, n)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "pacman_owns",
|
||||
Description: "Which installed package owns a path (pacman -Qo); owned false when none does.",
|
||||
Input: schema(map[string]any{"path": map[string]any{"type": "string", "description": "an absolute path"}}, "path"),
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
p, err := text(args, "path", true)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.Owns(p)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "pacman_files",
|
||||
Description: "The paths an installed package placed (pacman -Ql), bounded.",
|
||||
Input: schema(map[string]any{"package": pkgArg, "limit": limitArg(2000, 20000)}, "package"),
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
p, err := text(args, "package", true)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
n, err := whole(args, "limit", 2000, 1, 20000)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.Files(p, n)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "pacman_updates",
|
||||
Description: "What a full upgrade would change, each package from and to (checkupdates: the repositories are asked into a copy of their databases, so asking never sets up a partial upgrade). Needs the network.",
|
||||
Input: schema(map[string]any{}),
|
||||
Run: func(map[string]any) (any, error) { return m.Updates() },
|
||||
},
|
||||
{
|
||||
Name: "pacman_upgrade",
|
||||
Description: "Start a full system upgrade (pacman -Syu --noconfirm, through sudo -n) as a transient unit of its own that outlives the call, " +
|
||||
"answering at once with the unit and the distribution's news since the last upgrade — read the news first. Given that unit, " +
|
||||
"answer whether it is running, finished and succeeded, with the tail of its log.",
|
||||
Input: schema(map[string]any{
|
||||
"unit": map[string]any{"type": "string", "description": "a unit this tool started, to read how it goes (optional)"},
|
||||
"lines": limitArg(60, 400),
|
||||
}),
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
unit, err := text(args, "unit", false)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
n, err := whole(args, "lines", 60, 1, 400)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.Upgrade(unit, n)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "pacman_orphans",
|
||||
Description: "Packages installed as dependencies that nothing requires any more (pacman -Qdt), with versions.",
|
||||
Input: schema(map[string]any{}),
|
||||
Run: func(map[string]any) (any, error) { return m.Orphans() },
|
||||
},
|
||||
{
|
||||
Name: "pacman_remove_orphans",
|
||||
Description: "Remove orphans (pacman -Rs, through sudo -n, as a unit of its own): the names given, each of which must be an orphan, " +
|
||||
"or every orphan with all: true. Changed configuration files are kept as .pacsave. Answers what was removed and the log.",
|
||||
Input: schema(map[string]any{
|
||||
"names": map[string]any{"type": "array", "items": map[string]any{"type": "string"}, "description": "orphans to remove"},
|
||||
"all": map[string]any{"type": "boolean", "description": "remove every orphan"},
|
||||
}),
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
all, err := flag(args, "all")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
var names []string
|
||||
if raw, ok := args["names"].([]any); ok {
|
||||
for i := range raw {
|
||||
n, err := text(map[string]any{"name": raw[i]}, "name", true)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
names = append(names, n)
|
||||
}
|
||||
}
|
||||
return m.RemoveOrphans(names, all)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "pacman_cache",
|
||||
Description: "The package cache: files, bytes, interrupted downloads left behind, what paccache would remove keeping the last " +
|
||||
"keep versions of each package (or only packages no longer installed), and the paccache timer. With clean: true it removes them (sudo -n).",
|
||||
Input: schema(map[string]any{
|
||||
"keep": map[string]any{"type": "integer", "description": "versions of each package to keep (default 3)"},
|
||||
"uninstalled": map[string]any{"type": "boolean", "description": "only packages no longer installed"},
|
||||
"clean": map[string]any{"type": "boolean", "description": "remove them, rather than say what would go"},
|
||||
}),
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
keep, err := whole(args, "keep", 3, 0, 100)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
un, err := flag(args, "uninstalled")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
clean, err := flag(args, "clean")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.Cache(keep, un, clean)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "pacman_history",
|
||||
Description: "What the package manager did, from /var/log/pacman.log: each install, upgrade, downgrade, reinstall and removal since a day (default thirty days back), narrowed to an action or a name, with counts and the last full upgrade.",
|
||||
Input: schema(map[string]any{
|
||||
"since": sinceArg,
|
||||
"action": map[string]any{"type": "string", "enum": Actions},
|
||||
"match": map[string]any{"type": "string", "description": "only packages whose name holds this"},
|
||||
"limit": limitArg(500, 5000),
|
||||
}),
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
since, err := text(args, "since", false)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
action, err := text(args, "action", false)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
match, err := text(args, "match", false)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
n, err := whole(args, "limit", 500, 1, 5000)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.History(since, action, match, n)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "pacman_mirrors",
|
||||
Description: "The mirror list in force (servers, commented ones, who generated it and when), reflector's options, its timer and its last run. With refresh: true, start reflector now (sudo -n), without waiting.",
|
||||
Input: schema(map[string]any{"refresh": map[string]any{"type": "boolean", "description": "rank and rewrite the list now"}}),
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
refresh, err := flag(args, "refresh")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.MirrorList(refresh)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "pacman_foreign",
|
||||
Description: "Installed packages that no repository this machine syncs carries (pacman -Qm): built from the AUR or by hand, which the mesh cannot install.",
|
||||
Input: schema(map[string]any{}),
|
||||
Run: func(map[string]any) (any, error) { return m.Foreign() },
|
||||
},
|
||||
{
|
||||
Name: "pacman_news",
|
||||
Description: "The distribution's news posts since a day, or since the last full upgrade by default — what an upgrade may need a person to do. Fetched over https; no network is answered as reachable: false.",
|
||||
Input: schema(map[string]any{"since": sinceArg}),
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
since, err := text(args, "since", false)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m.News(since), nil
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "pacman_config",
|
||||
Description: "The configuration pacman runs with, as pacman-conf resolves it: every option, each repository with its signature level and how many servers, and whether /etc/pacman.conf is the module's.",
|
||||
Input: schema(map[string]any{}),
|
||||
Run: func(map[string]any) (any, error) { return m.Conf() },
|
||||
},
|
||||
}
|
||||
}
|
||||
@@ -1,103 +0,0 @@
|
||||
package main
|
||||
|
||||
// The module's shape (novox/hq to-be 42 Phase 1, ADR 0207, research 027): it holds the
|
||||
// node-package-manager seat and declares the package manager's own package; it owns pacman.conf
|
||||
// whole — proven by pacman-conf on the rendered file, because a pacman.conf pacman cannot read is a
|
||||
// machine that can neither install nor upgrade — and reflector's configuration, with the refresher
|
||||
// and the cache cleaner on their timers.
|
||||
|
||||
import (
|
||||
"os"
|
||||
"os/exec"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestItHoldsThePackageManagerSeatAndDeclaresItsPackage(t *testing.T) {
|
||||
m := manifest(t)
|
||||
if len(m.Claims) != 1 || m.Claims[0]["name"] != "node-package-manager" || m.Claims[0]["scope"] != "node" || m.Claims[0]["serves"] != nil {
|
||||
t.Fatalf("claims: %v", m.Claims)
|
||||
}
|
||||
for id, pkg := range map[string]string{"package": "pacman", "contrib": "pacman-contrib", "reflector": "reflector"} {
|
||||
if r := m.resource(t, id); r["package"] != pkg || r["absent"] != nil {
|
||||
t.Errorf("%s: %v", id, r)
|
||||
}
|
||||
}
|
||||
for id, unit := range map[string]string{"mirror-refresh": "reflector.timer", "cache-cleaning": "paccache.timer"} {
|
||||
r := m.resource(t, id)
|
||||
if r["unit"] != unit || r["state"] != "running" || r["boot"] != "enabled" {
|
||||
t.Errorf("%s: %v", id, r)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestPacmanConfIsWholeTheUnionOfRepositoriesAndTheImprovedOptions(t *testing.T) {
|
||||
f := manifest(t).resource(t, "config")
|
||||
content := f["content"].(string)
|
||||
if f["path"] != "/etc/pacman.conf" || f["into"] != nil || !strings.HasPrefix(content, MeshHeader) {
|
||||
t.Fatalf("%v", f)
|
||||
}
|
||||
var sections []string
|
||||
for _, l := range strings.Split(content, "\n") {
|
||||
if strings.HasPrefix(l, "[") {
|
||||
sections = append(sections, l)
|
||||
}
|
||||
}
|
||||
if strings.Join(sections, " ") != "[options] [core] [extra] [multilib]" {
|
||||
t.Fatalf("sections: %v", sections)
|
||||
}
|
||||
for _, want := range []string{"\nColor\n", "\nCheckSpace\n", "\nVerbosePkgLists\n", "\nParallelDownloads = 5\n", "\nDownloadUser = alpm\n", "\nSigLevel = Required DatabaseOptional\n"} {
|
||||
if !strings.Contains(content, want) {
|
||||
t.Errorf("missing %q", strings.TrimSpace(want))
|
||||
}
|
||||
}
|
||||
conf, err := exec.LookPath("pacman-conf")
|
||||
if err != nil {
|
||||
t.Skip("pacman-conf is not installed here; the rendered file is not proven")
|
||||
}
|
||||
file := filepath.Join(t.TempDir(), "pacman.conf")
|
||||
if err := os.WriteFile(file, []byte(content), 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
repos, err := exec.Command(conf, "--config", file, "--repo-list").CombinedOutput()
|
||||
if err != nil || strings.Join(strings.Fields(string(repos)), " ") != "core extra multilib" {
|
||||
t.Fatalf("pacman-conf --repo-list: %v\n%s", err, repos)
|
||||
}
|
||||
out, err := exec.Command(conf, "--config", file).CombinedOutput()
|
||||
if err != nil {
|
||||
t.Fatalf("pacman-conf refuses the file: %v\n%s", err, out)
|
||||
}
|
||||
c := ParseConf(string(out))
|
||||
if c.Options["ParallelDownloads"][0] != "5" || c.Options["DownloadUser"] == nil || c.Options["Color"] == nil || c.Options["VerbosePkgLists"] == nil {
|
||||
t.Fatalf("pacman-conf does not read the options as written: %v", c.Options)
|
||||
}
|
||||
}
|
||||
|
||||
func TestReflectorWritesTheListPacmanReads(t *testing.T) {
|
||||
content := manifest(t).resource(t, "mirrors")["content"].(string)
|
||||
opts := map[string]string{}
|
||||
for _, l := range strings.Split(content, "\n") {
|
||||
if l == "" || strings.HasPrefix(l, "#") {
|
||||
continue
|
||||
}
|
||||
k, v, _ := strings.Cut(l, " ")
|
||||
opts[k] = v
|
||||
}
|
||||
if opts["--save"] != Mirrorlist || opts["--protocol"] != "https" || opts["--latest"] != "20" || opts["--sort"] != "rate" || opts["--country"] == "" {
|
||||
t.Fatalf("%v", opts)
|
||||
}
|
||||
if manifest(t).resource(t, "mirrors")["path"] != ReflectorConf {
|
||||
t.Fatal("reflector reads its options from " + ReflectorConf)
|
||||
}
|
||||
}
|
||||
|
||||
func TestTheReflectorPackageIsDeclaredBeforeTheFileItShips(t *testing.T) {
|
||||
order := map[string]int{}
|
||||
for i, r := range manifest(t).Resources {
|
||||
order[r["id"].(string)] = i
|
||||
}
|
||||
if order["reflector"] > order["mirrors"] || order["contrib"] > order["cache-cleaning"] || order["reflector"] > order["mirror-refresh"] {
|
||||
t.Fatalf("a package's file and timer come after the package: %v", order)
|
||||
}
|
||||
}
|
||||
@@ -1,86 +0,0 @@
|
||||
package main
|
||||
|
||||
// The mirror list and its refresher (novox/hq to-be 42 Phase 1). On 2026-10-04 every machine's list
|
||||
// had been generated once — by a tool no longer installed, or by a hosting provider's installer — and
|
||||
// never again. The module installs reflector, owns its configuration and enables its weekly timer;
|
||||
// this reads the list and the refresher's last run, and starts a refresh on demand.
|
||||
|
||||
import (
|
||||
"strings"
|
||||
)
|
||||
|
||||
// Where the list is and how reflector is told to write it.
|
||||
const (
|
||||
Mirrorlist = "/etc/pacman.d/mirrorlist"
|
||||
ReflectorConf = "/etc/xdg/reflector/reflector.conf"
|
||||
)
|
||||
|
||||
// Mirrors is the mirror list and its refresher.
|
||||
type Mirrors struct {
|
||||
Servers []string `json:"servers"`
|
||||
Commented int `json:"commented_servers"`
|
||||
GeneratedBy string `json:"generated_by,omitempty"`
|
||||
When string `json:"generated_when,omitempty"`
|
||||
Reflector []string `json:"reflector_options"`
|
||||
Timer map[string]string `json:"reflector_timer,omitempty"`
|
||||
LastRun map[string]string `json:"reflector_last_run,omitempty"`
|
||||
Refreshing bool `json:"refresh_started"`
|
||||
Note string `json:"note,omitempty"`
|
||||
}
|
||||
|
||||
// ParseMirrorlist reads the servers in force, those commented out, and the generator's header.
|
||||
func ParseMirrorlist(text string) Mirrors {
|
||||
m := Mirrors{Servers: []string{}, Reflector: []string{}}
|
||||
for _, l := range lines(text) {
|
||||
l = strings.TrimSpace(l)
|
||||
switch {
|
||||
case strings.HasPrefix(l, "Server"):
|
||||
if _, v, ok := strings.Cut(l, "="); ok {
|
||||
m.Servers = append(m.Servers, strings.TrimSpace(v))
|
||||
}
|
||||
case strings.HasPrefix(strings.TrimLeft(l, "# "), "Server"):
|
||||
m.Commented++
|
||||
case strings.Contains(l, "generated by Reflector"):
|
||||
m.GeneratedBy = "reflector"
|
||||
case strings.HasPrefix(l, "# When:"):
|
||||
m.When = strings.TrimSpace(strings.TrimPrefix(l, "# When:"))
|
||||
case strings.HasPrefix(l, "## Generated on"):
|
||||
m.GeneratedBy, m.When = "the distribution's mirrorlist", strings.TrimSpace(strings.TrimPrefix(l, "## Generated on"))
|
||||
}
|
||||
}
|
||||
return m
|
||||
}
|
||||
|
||||
// MirrorList answers the list, reflector's options, its timer and its last run; refresh starts
|
||||
// reflector now, without waiting, since ranking mirrors by rate takes longer than a call may.
|
||||
func (m *Machine) MirrorList(refresh bool) (Mirrors, error) {
|
||||
text, err := m.ReadFile(Mirrorlist)
|
||||
if err != nil {
|
||||
return Mirrors{}, err
|
||||
}
|
||||
out := ParseMirrorlist(string(text))
|
||||
if conf, err := m.ReadFile(ReflectorConf); err == nil {
|
||||
for _, l := range lines(string(conf)) {
|
||||
if l = strings.TrimSpace(l); !strings.HasPrefix(l, "#") {
|
||||
out.Reflector = append(out.Reflector, l)
|
||||
}
|
||||
}
|
||||
}
|
||||
if t, err := m.unitProps("reflector.timer", "LoadState", "ActiveState", "UnitFileState", "LastTriggerUSec", "NextElapseUSecRealtime"); err == nil {
|
||||
out.Timer = t
|
||||
}
|
||||
if s, err := m.unitProps("reflector.service", "LoadState", "ActiveState", "Result", "ExecMainExitTimestamp", "ExecMainStatus"); err == nil {
|
||||
out.LastRun = s
|
||||
}
|
||||
if out.Timer["LoadState"] == "not-found" {
|
||||
out.Note = "reflector is not installed here; the module installs it"
|
||||
}
|
||||
if refresh {
|
||||
if _, err := m.Root("systemctl", "start", "--no-block", "reflector.service"); err != nil {
|
||||
return out, err
|
||||
}
|
||||
out.Refreshing = true
|
||||
out.Note = "reflector is ranking mirrors now; call again in a minute for the new list"
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
@@ -1,110 +0,0 @@
|
||||
package main
|
||||
|
||||
// The distribution's news since the last upgrade (novox/hq research 026/05: "an upgrade with the
|
||||
// news first"). Arch posts what an upgrade needs a person to do — a manual intervention, a replaced
|
||||
// package — in its news feed, and an upgrade that ignores it is how a machine breaks. Fetched over
|
||||
// https; no network is an answer, never a failure.
|
||||
|
||||
import (
|
||||
"encoding/xml"
|
||||
"fmt"
|
||||
"io"
|
||||
"net/http"
|
||||
"regexp"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// NewsFeed is the distribution's news, as RSS.
|
||||
const NewsFeed = "https://archlinux.org/feeds/news/"
|
||||
|
||||
// fetch is how the feed is read; a test replaces it.
|
||||
var fetch = func(url string) ([]byte, error) {
|
||||
client := http.Client{Timeout: 10 * time.Second}
|
||||
res, err := client.Get(url)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
defer res.Body.Close()
|
||||
if res.StatusCode != http.StatusOK {
|
||||
return nil, fmt.Errorf("%s answered %s", url, res.Status)
|
||||
}
|
||||
return io.ReadAll(io.LimitReader(res.Body, 4<<20))
|
||||
}
|
||||
|
||||
// NewsItem is one post.
|
||||
type NewsItem struct {
|
||||
Title string `json:"title"`
|
||||
Link string `json:"link"`
|
||||
Published string `json:"published"`
|
||||
Summary string `json:"summary"`
|
||||
}
|
||||
|
||||
type rss struct {
|
||||
Items []struct {
|
||||
Title string `xml:"title"`
|
||||
Link string `xml:"link"`
|
||||
PubDate string `xml:"pubDate"`
|
||||
Description string `xml:"description"`
|
||||
} `xml:"channel>item"`
|
||||
}
|
||||
|
||||
var tags = regexp.MustCompile(`<[^>]*>`)
|
||||
|
||||
// ParseNews reads the feed's posts published after a time, newest first as the feed has them.
|
||||
func ParseNews(body []byte, since time.Time) ([]NewsItem, error) {
|
||||
var feed rss
|
||||
if err := xml.Unmarshal(body, &feed); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
items := []NewsItem{}
|
||||
for _, it := range feed.Items {
|
||||
t, err := time.Parse(time.RFC1123Z, strings.TrimSpace(it.PubDate))
|
||||
if err != nil {
|
||||
t, err = time.Parse(time.RFC1123, strings.TrimSpace(it.PubDate))
|
||||
}
|
||||
if err != nil || !t.After(since) {
|
||||
continue
|
||||
}
|
||||
summary := strings.Join(strings.Fields(tags.ReplaceAllString(it.Description, " ")), " ")
|
||||
if len(summary) > 600 {
|
||||
summary = summary[:600] + "…"
|
||||
}
|
||||
items = append(items, NewsItem{Title: it.Title, Link: it.Link, Published: t.Format(time.RFC3339), Summary: summary})
|
||||
}
|
||||
return items, nil
|
||||
}
|
||||
|
||||
// News is the posts since a day (YYYY-MM-DD), or since the last full upgrade the log records.
|
||||
func (m *Machine) News(since string) map[string]any {
|
||||
out := map[string]any{"feed": NewsFeed, "items": []NewsItem{}}
|
||||
var from time.Time
|
||||
if since != "" {
|
||||
t, err := time.ParseInLocation("2006-01-02", since, time.Local)
|
||||
if err != nil {
|
||||
out["error"] = fmt.Sprintf("since %q is not a day as YYYY-MM-DD", since)
|
||||
return out
|
||||
}
|
||||
from = t
|
||||
} else if last, err := m.LastUpgrade(); err == nil && !last.IsZero() {
|
||||
from = last
|
||||
out["since_last_full_upgrade"] = true
|
||||
} else {
|
||||
from = m.Now().AddDate(0, 0, -90)
|
||||
}
|
||||
out["since"] = from.Format(time.RFC3339)
|
||||
body, err := fetch(NewsFeed)
|
||||
if err != nil {
|
||||
out["reachable"] = false
|
||||
out["error"] = err.Error()
|
||||
return out
|
||||
}
|
||||
out["reachable"] = true
|
||||
items, err := ParseNews(body, from)
|
||||
if err != nil {
|
||||
out["error"] = "the feed could not be read: " + err.Error()
|
||||
return out
|
||||
}
|
||||
out["items"] = items
|
||||
return out
|
||||
}
|
||||
@@ -1,376 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
const searchOut = `extra/zsh 5.9.2-1 [installed]
|
||||
A very advanced and programmable command interpreter (shell) for UNIX
|
||||
extra/ripgrep 15.2.0-1 [installed: 15.1.0-1]
|
||||
A search tool
|
||||
core/base-devel 1-2 (base-devel)
|
||||
Basic tools to build Arch Linux packages
|
||||
`
|
||||
|
||||
func TestSearchReadsHeaderAndDescriptionAndWhatIsInstalled(t *testing.T) {
|
||||
f := ParseSearch(searchOut)
|
||||
if len(f) != 3 {
|
||||
t.Fatalf("%+v", f)
|
||||
}
|
||||
if f[0].Repository != "extra" || f[0].Name != "zsh" || !f[0].Installed || f[0].InstalledAs != "5.9.2-1" || !strings.HasPrefix(f[0].Description, "A very advanced") {
|
||||
t.Fatalf("%+v", f[0])
|
||||
}
|
||||
if f[1].InstalledAs != "15.1.0-1" || f[1].Version != "15.2.0-1" {
|
||||
t.Fatalf("%+v", f[1])
|
||||
}
|
||||
if f[2].Installed || len(f[2].Groups) != 1 || f[2].Groups[0] != "base-devel" {
|
||||
t.Fatalf("%+v", f[2])
|
||||
}
|
||||
}
|
||||
|
||||
func TestASearchThatFindsNothingIsEmptyAndAFailureIsAnError(t *testing.T) {
|
||||
m := machine(fake(func(c call) Ran { return Ran{Status: 1} }, nil), 1000)
|
||||
r, err := m.Search("nothing", 50)
|
||||
if err != nil || r["count"] != 0 {
|
||||
t.Fatalf("%v %v", r, err)
|
||||
}
|
||||
m = machine(fake(func(c call) Ran { return Ran{Status: 1, Stderr: "error: failed to initialize alpm library\n"} }, nil), 1000)
|
||||
if _, err := m.Search("x", 50); err == nil || !strings.Contains(err.Error(), "failed to initialize") {
|
||||
t.Fatalf("%v", err)
|
||||
}
|
||||
}
|
||||
|
||||
const infoOut = `Name : zsh
|
||||
Version : 5.9.2-1
|
||||
Depends On : pcre2 libcap gdbm
|
||||
Optional Deps : grml-zsh-config: grml's zsh setup
|
||||
zsh-doc: documentation [installed]
|
||||
Required By : None
|
||||
Install Reason : Explicitly installed
|
||||
|
||||
`
|
||||
|
||||
func TestInfoReadsListsAsListsAndFallsBackToTheRepositories(t *testing.T) {
|
||||
p := ParseInfo(infoOut)
|
||||
if len(p) != 1 {
|
||||
t.Fatalf("%v", p)
|
||||
}
|
||||
if deps := p[0]["Depends On"].([]string); len(deps) != 3 || deps[2] != "gdbm" {
|
||||
t.Fatalf("%v", p[0]["Depends On"])
|
||||
}
|
||||
if opt := p[0]["Optional Deps"].([]string); len(opt) != 2 || !strings.HasPrefix(opt[1], "zsh-doc") {
|
||||
t.Fatalf("%v", p[0]["Optional Deps"])
|
||||
}
|
||||
if req := p[0]["Required By"].([]string); len(req) != 0 {
|
||||
t.Fatalf("None is empty: %v", req)
|
||||
}
|
||||
var calls []call
|
||||
m := machine(byLine(map[string]Ran{
|
||||
"pacman -Qi -- zsh": {Status: 1, Stderr: "error: package 'zsh' was not found\n"},
|
||||
"pacman -Si -- zsh": {Stdout: "Repository : extra\n" + infoOut},
|
||||
}, &calls), 1000)
|
||||
r, err := m.Info("zsh")
|
||||
if err != nil || r["installed"] != false || r["package"].(map[string]any)["Repository"] != "extra" {
|
||||
t.Fatalf("%v %v", r, err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestInstalledSaysWhyAndWhatIsForeign(t *testing.T) {
|
||||
m := machine(byLine(map[string]Ran{
|
||||
"pacman -Q": {Stdout: "glibc 2.42-1\nyay 12.0-1\nzsh 5.9-1\n"},
|
||||
"pacman -Qeq": {Stdout: "yay\nzsh\n"},
|
||||
"pacman -Qmq": {Stdout: "yay\n"},
|
||||
}, nil), 1000)
|
||||
r, err := m.Installed("", "", false, 10)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
pk := r["packages"].([]Package)
|
||||
if pk[0].Reason != "dependency" || pk[1].Reason != "explicit" || !pk[1].Foreign || pk[2].Foreign {
|
||||
t.Fatalf("%+v", pk)
|
||||
}
|
||||
if tot := r["totals"].(map[string]int); tot["explicit"] != 2 || tot["dependency"] != 1 || tot["foreign"] != 1 {
|
||||
t.Fatalf("%v", tot)
|
||||
}
|
||||
r, _ = m.Installed("", "", true, 10)
|
||||
if r["count"] != 1 {
|
||||
t.Fatalf("foreign only: %v", r)
|
||||
}
|
||||
r, _ = m.Installed("", "explicit", false, 1)
|
||||
if r["count"] != 2 || r["truncated"] != true {
|
||||
t.Fatalf("bounded: %v", r)
|
||||
}
|
||||
}
|
||||
|
||||
func TestOwnsAnswersNoOwnerAsAnAnswer(t *testing.T) {
|
||||
m := machine(byLine(map[string]Ran{
|
||||
"pacman -Qo -- /usr/bin/zsh": {Stdout: "/usr/bin/zsh is owned by zsh 5.9.2-1\n"},
|
||||
"pacman -Qo -- /etc/hostname": {Status: 1, Stderr: "error: No package owns /etc/hostname\n"},
|
||||
"pacman -Qo -- /nope": {Status: 1, Stderr: "error: failed to read file '/nope': No such file or directory\n"},
|
||||
}, nil), 1000)
|
||||
if r, err := m.Owns("/usr/bin/zsh"); err != nil || r["package"] != "zsh" || r["owned"] != true {
|
||||
t.Fatalf("%v %v", r, err)
|
||||
}
|
||||
if r, err := m.Owns("/etc/hostname"); err != nil || r["owned"] != false {
|
||||
t.Fatalf("%v %v", r, err)
|
||||
}
|
||||
if _, err := m.Owns("/nope"); err == nil {
|
||||
t.Fatal("a path that is not there is an error")
|
||||
}
|
||||
if _, err := m.Owns("relative"); err == nil {
|
||||
t.Fatal("a relative path was taken")
|
||||
}
|
||||
}
|
||||
|
||||
func TestUpdatesReadsCheckupdatesAndItsNothingToDo(t *testing.T) {
|
||||
m := machine(byLine(map[string]Ran{"checkupdates": {Stdout: "linux 6.1-1 -> 6.2-1\nzsh 5.9-1 -> 5.9-2\n"}}, nil), 1000)
|
||||
r, err := m.Updates()
|
||||
if err != nil || r["count"] != 2 || r["updates"].([]Update)[0] != (Update{"linux", "6.1-1", "6.2-1"}) {
|
||||
t.Fatalf("%v %v", r, err)
|
||||
}
|
||||
m = machine(byLine(map[string]Ran{"checkupdates": {Status: 2}}, nil), 1000)
|
||||
if r, err := m.Updates(); err != nil || r["count"] != 0 {
|
||||
t.Fatalf("%v %v", r, err)
|
||||
}
|
||||
m = machine(byLine(map[string]Ran{"checkupdates": {Status: 1, Stderr: "==> ERROR: Cannot fetch updates\n"}}, nil), 1000)
|
||||
if _, err := m.Updates(); err == nil || !strings.Contains(err.Error(), "Cannot fetch updates") {
|
||||
t.Fatalf("%v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func lockless(m *Machine) *Machine {
|
||||
m.ReadFile = func(p string) ([]byte, error) { return nil, errNoFile }
|
||||
return m
|
||||
}
|
||||
|
||||
func TestAnUpgradeRunsAsAUnitOfItsOwnThroughSudoAndBringsTheNews(t *testing.T) {
|
||||
fetch = func(string) ([]byte, error) { return nil, errors.New("no network") }
|
||||
var calls []call
|
||||
m := lockless(machine(fake(func(c call) Ran { return Ran{} }, &calls), 1000))
|
||||
r, err := m.Upgrade("", 60)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
unit := r["started"].(string)
|
||||
if unit != "mesh-pacman-upgrade-1791115200" {
|
||||
t.Fatalf("unit: %s", unit)
|
||||
}
|
||||
last := calls[len(calls)-1]
|
||||
want := "sudo -n systemd-run --unit=" + unit
|
||||
if !strings.HasPrefix(last.String(), want) || !strings.HasSuffix(last.String(), "--quiet pacman -Syu --noconfirm") || strings.Contains(last.String(), "--wait") {
|
||||
t.Fatalf("started as: %s", last)
|
||||
}
|
||||
news := r["news"].(map[string]any)
|
||||
if news["reachable"] != false || !strings.Contains(news["error"].(string), "no network") {
|
||||
t.Fatalf("no network is an answer: %v", news)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAnUpgradeIsRefusedWhileTheDatabaseIsLocked(t *testing.T) {
|
||||
fetch = func(string) ([]byte, error) { return nil, errors.New("offline") }
|
||||
var calls []call
|
||||
m := machine(fake(func(c call) Ran { return Ran{} }, &calls), 1000)
|
||||
m.ReadFile = func(p string) ([]byte, error) {
|
||||
if p == DBLock {
|
||||
return []byte{}, nil
|
||||
}
|
||||
return nil, errNoFile
|
||||
}
|
||||
if _, err := m.Upgrade("", 60); err == nil || !strings.Contains(err.Error(), "another pacman holds") {
|
||||
t.Fatalf("%v", err)
|
||||
}
|
||||
for _, c := range calls {
|
||||
if c.name == "sudo" {
|
||||
t.Fatal("started while locked")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestAnUpgradesUnitIsReadBack(t *testing.T) {
|
||||
unit := "mesh-pacman-upgrade-1791115200"
|
||||
m := machine(byLine(map[string]Ran{
|
||||
"systemctl show " + unit + " --no-pager --property=LoadState --property=ActiveState --property=SubState --property=Result --property=ExecMainStatus": {Stdout: "LoadState=loaded\nActiveState=failed\nSubState=failed\nResult=exit-code\nExecMainStatus=1\n"},
|
||||
"sudo -n journalctl --no-pager -o cat -n 60 -u " + unit: {Stdout: "error: failed to commit transaction (conflicting files)\n"},
|
||||
}, nil), 1000)
|
||||
r, err := m.Upgrade(unit, 60)
|
||||
if err != nil || r["finished"] != true || r["succeeded"] != false || r["exit_status"] != "1" || len(r["log"].([]string)) != 1 {
|
||||
t.Fatalf("%v %v", r, err)
|
||||
}
|
||||
if _, err := m.Upgrade("sshd.service", 60); err == nil {
|
||||
t.Fatal("a unit the tools did not start was read")
|
||||
}
|
||||
}
|
||||
|
||||
func orphanMachine(calls *[]call) *Machine {
|
||||
return lockless(machine(fake(func(c call) Ran {
|
||||
switch {
|
||||
case c.String() == "pacman -Qdt":
|
||||
return Ran{Stdout: "argon2 20190702-6\nclang21 21.1.8-1\n"}
|
||||
case c.name == "sudo" && c.args[1] == "systemd-run":
|
||||
return Ran{}
|
||||
case c.name == "sudo" && c.args[1] == "journalctl":
|
||||
return Ran{Stdout: "removing argon2...\n"}
|
||||
}
|
||||
return Ran{Status: 99}
|
||||
}, calls), 1000))
|
||||
}
|
||||
|
||||
func TestRemovingOrphansTakesOnlyOrphansNamedOrAll(t *testing.T) {
|
||||
var calls []call
|
||||
m := orphanMachine(&calls)
|
||||
if _, err := m.RemoveOrphans(nil, false); err == nil || !strings.Contains(err.Error(), "name the orphans") {
|
||||
t.Fatalf("nothing named: %v", err)
|
||||
}
|
||||
if _, err := m.RemoveOrphans([]string{"glibc"}, false); err == nil || !strings.Contains(err.Error(), "glibc is not an orphan") {
|
||||
t.Fatalf("not an orphan: %v", err)
|
||||
}
|
||||
r, err := m.RemoveOrphans([]string{"argon2"}, false)
|
||||
if err != nil || strings.Join(r["removed"].([]string), ",") != "argon2" {
|
||||
t.Fatalf("%v %v", r, err)
|
||||
}
|
||||
var run string
|
||||
for _, c := range calls {
|
||||
if c.name == "sudo" && c.args[1] == "systemd-run" {
|
||||
run = c.String()
|
||||
}
|
||||
}
|
||||
if !strings.Contains(run, "--wait pacman -Rs --noconfirm -- argon2") {
|
||||
t.Fatalf("ran: %s", run)
|
||||
}
|
||||
r, _ = m.RemoveOrphans(nil, true)
|
||||
if len(r["removed"].([]string)) != 2 {
|
||||
t.Fatalf("all: %v", r)
|
||||
}
|
||||
}
|
||||
|
||||
func TestCacheSaysWhatCleaningWouldFreeAndCleansThroughSudo(t *testing.T) {
|
||||
var calls []call
|
||||
m := machine(fake(func(c call) Ran {
|
||||
switch c.String() {
|
||||
case "find /var/cache/pacman/pkg -mindepth 1 -maxdepth 1 -printf %y %s %f\n":
|
||||
return Ran{Status: 1, Stdout: "f 1000 zsh-5.9-1-x86_64.pkg.tar.zst\nf 10 zsh-5.9-1-x86_64.pkg.tar.zst.sig\nd 4096 download-abc\n", Stderr: "find: permission denied\n"}
|
||||
case "paccache -d -k 3":
|
||||
return Ran{Stdout: "\n==> finished dry run: 12 candidates (disk space saved: 1.5 GiB)\n"}
|
||||
case "sudo -n paccache -r -k 3":
|
||||
return Ran{Stdout: "==> finished: 12 packages removed (disk space saved: 1.5 GiB)\n"}
|
||||
}
|
||||
if c.name == "systemctl" {
|
||||
return Ran{Stdout: "ActiveState=active\nUnitFileState=enabled\n"}
|
||||
}
|
||||
return Ran{Status: 99}
|
||||
}, &calls), 1000)
|
||||
c, err := m.Cache(3, false, false)
|
||||
if err != nil || c.Files != 1 || c.Bytes != 1010 || c.LeftDownloads != 1 || c.Candidates != 12 || c.Frees != "1.5 GiB" || c.Cleaned {
|
||||
t.Fatalf("%+v %v", c, err)
|
||||
}
|
||||
c, err = m.Cache(3, false, true)
|
||||
if err != nil || !c.Cleaned || c.Candidates != 12 || c.Timer["UnitFileState"] != "enabled" {
|
||||
t.Fatalf("%+v %v", c, err)
|
||||
}
|
||||
}
|
||||
|
||||
const pacmanLog = `[2026-09-24T17:47:36+0200] [PACMAN] starting full system upgrade
|
||||
[2026-09-24T17:48:00+0200] [ALPM] upgraded linux (6.1-1 -> 6.2-1)
|
||||
[2026-09-24T17:48:01+0200] [ALPM] installed zsh (5.9-1)
|
||||
[2026-10-02T09:00:00+0200] [ALPM] removed ntp (4.2.8-1)
|
||||
[2026-10-02T09:00:00+0200] [ALPM-SCRIPTLET] some words
|
||||
[2022-01-01 10:00] [ALPM] installed old (1-1)
|
||||
`
|
||||
|
||||
func TestHistoryReadsTheLogSinceADayAndTheLastFullUpgrade(t *testing.T) {
|
||||
m := machine(nil, 1000)
|
||||
m.ReadFile = func(p string) ([]byte, error) { return []byte(pacmanLog), nil }
|
||||
r, err := m.History("2026-09-01", "", "", 10)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
ev := r["events"].([]Event)
|
||||
if len(ev) != 3 || ev[0].From != "6.1-1" || ev[0].Version != "6.2-1" || ev[2].Action != "removed" {
|
||||
t.Fatalf("%+v", ev)
|
||||
}
|
||||
if r["last_full_upgrade"] != "2026-09-24T17:47:36+02:00" {
|
||||
t.Fatalf("%v", r["last_full_upgrade"])
|
||||
}
|
||||
r, _ = m.History("2026-09-01", "removed", "", 10)
|
||||
if r["count"] != 1 {
|
||||
t.Fatalf("%v", r)
|
||||
}
|
||||
r, _ = m.History("2026-09-01", "", "", 1)
|
||||
if r["truncated"] != true || r["events"].([]Event)[0].Package != "ntp" {
|
||||
t.Fatalf("the newest are kept: %v", r)
|
||||
}
|
||||
if _, err := m.History("yesterday", "", "", 1); err == nil {
|
||||
t.Fatal("not a day")
|
||||
}
|
||||
if _, err := m.History("", "exploded", "", 1); err == nil {
|
||||
t.Fatal("not an action")
|
||||
}
|
||||
}
|
||||
|
||||
const feed = `<?xml version="1.0" encoding="utf-8"?>
|
||||
<rss version="2.0"><channel><title>Arch Linux: Recent news updates</title>
|
||||
<item><title>Manual intervention needed</title><link>https://example.org/news/a/</link><description><p>Do this <b>first</b>.</p></description><pubDate>Tue, 22 Sep 2026 09:09:27 +0000</pubDate></item>
|
||||
<item><title>Old news</title><link>https://example.org/news/b/</link><description>old</description><pubDate>Mon, 01 Jun 2026 09:00:00 +0000</pubDate></item>
|
||||
</channel></rss>`
|
||||
|
||||
func TestNewsSinceTheLastUpgrade(t *testing.T) {
|
||||
items, err := ParseNews([]byte(feed), time.Date(2026, 9, 1, 0, 0, 0, 0, time.UTC))
|
||||
if err != nil || len(items) != 1 || items[0].Title != "Manual intervention needed" || items[0].Summary != "Do this first ." {
|
||||
t.Fatalf("%+v %v", items, err)
|
||||
}
|
||||
fetch = func(string) ([]byte, error) { return []byte(feed), nil }
|
||||
m := machine(nil, 1000)
|
||||
m.ReadFile = func(p string) ([]byte, error) { return []byte(pacmanLog), nil }
|
||||
n := m.News("")
|
||||
if n["reachable"] != true || n["since_last_full_upgrade"] != true || len(n["items"].([]NewsItem)) != 0 {
|
||||
t.Fatalf("after the last upgrade on the 24th, the post of the 22nd is old: %v", n)
|
||||
}
|
||||
}
|
||||
|
||||
const mirrorlistReflector = `################################################################################
|
||||
################# Arch Linux mirrorlist generated by Reflector #################
|
||||
################################################################################
|
||||
|
||||
# With: reflector @/etc/xdg/reflector/reflector.conf
|
||||
# When: 2024-06-12 21:26:34 UTC
|
||||
|
||||
Server = https://mirror.example.org/archlinux/$repo/os/$arch
|
||||
Server = https://mirror2.example.org/$repo/os/$arch
|
||||
#Server = https://old.example.org/$repo/os/$arch
|
||||
`
|
||||
|
||||
func TestMirrorsReadTheListAndRefreshWithoutWaiting(t *testing.T) {
|
||||
var calls []call
|
||||
m := machine(fake(func(c call) Ran {
|
||||
if c.name == "systemctl" && c.args[0] == "show" {
|
||||
return Ran{Stdout: "LoadState=loaded\nActiveState=active\nUnitFileState=enabled\n"}
|
||||
}
|
||||
return Ran{}
|
||||
}, &calls), 1000)
|
||||
m.ReadFile = func(p string) ([]byte, error) {
|
||||
switch p {
|
||||
case Mirrorlist:
|
||||
return []byte(mirrorlistReflector), nil
|
||||
case ReflectorConf:
|
||||
return []byte("# comment\n--save /etc/pacman.d/mirrorlist\n--sort rate\n"), nil
|
||||
}
|
||||
return nil, errNoFile
|
||||
}
|
||||
r, err := m.MirrorList(true)
|
||||
if err != nil || len(r.Servers) != 2 || r.Commented != 1 || r.GeneratedBy != "reflector" || r.When != "2024-06-12 21:26:34 UTC" || len(r.Reflector) != 2 || !r.Refreshing {
|
||||
t.Fatalf("%+v %v", r, err)
|
||||
}
|
||||
if calls[len(calls)-1].String() != "sudo -n systemctl start --no-block reflector.service" {
|
||||
t.Fatalf("%v", calls[len(calls)-1])
|
||||
}
|
||||
}
|
||||
|
||||
func TestConfigIsReadAsPacmanConfResolvesIt(t *testing.T) {
|
||||
c := ParseConf("[options]\nHoldPkg = pacman\nHoldPkg = glibc\nCheckSpace\nParallelDownloads = 5\n[core]\nUsage = All\nServer = https://a/core\nServer = https://b/core\n[extra]\nServer = https://a/extra\n")
|
||||
if len(c.Options["HoldPkg"]) != 2 || c.Options["ParallelDownloads"][0] != "5" || len(c.Repositories) != 2 || c.Repositories[0].Servers != 2 || c.Repositories[0].FirstServer != "https://a/core" {
|
||||
t.Fatalf("%+v", c)
|
||||
}
|
||||
}
|
||||
@@ -1,404 +0,0 @@
|
||||
package main
|
||||
|
||||
// Reading the package manager (novox/hq to-be 42 Phase 1, research 026/05): what is installed and
|
||||
// why, what a search finds, what owns a path, what a package holds, what is orphaned or foreign.
|
||||
// Every one of these reads the local or sync databases, which any account may; none escalates.
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"path"
|
||||
"regexp"
|
||||
"sort"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// Found is one package a search found.
|
||||
type Found struct {
|
||||
Repository string `json:"repository"`
|
||||
Name string `json:"name"`
|
||||
Version string `json:"version"`
|
||||
Groups []string `json:"groups,omitempty"`
|
||||
Installed bool `json:"installed"`
|
||||
InstalledAs string `json:"installed_version,omitempty"`
|
||||
Description string `json:"description"`
|
||||
}
|
||||
|
||||
var searchHeader = regexp.MustCompile(`^(\S+)/(\S+) (\S+)(?: \(([^)]*)\))?(?: \[installed(?:: ([^\]]+))?\])?$`)
|
||||
|
||||
// ParseSearch reads `pacman -Ss`: a header line per package and its description indented beneath.
|
||||
func ParseSearch(out string) []Found {
|
||||
found := []Found{}
|
||||
for _, l := range strings.Split(out, "\n") {
|
||||
if strings.TrimSpace(l) == "" {
|
||||
continue
|
||||
}
|
||||
if strings.HasPrefix(l, " ") {
|
||||
if n := len(found); n > 0 {
|
||||
found[n-1].Description = strings.TrimSpace(strings.TrimSpace(found[n-1].Description + " " + strings.TrimSpace(l)))
|
||||
}
|
||||
continue
|
||||
}
|
||||
m := searchHeader.FindStringSubmatch(l)
|
||||
if m == nil {
|
||||
continue
|
||||
}
|
||||
f := Found{Repository: m[1], Name: m[2], Version: m[3], Installed: strings.Contains(l, "[installed")}
|
||||
if m[4] != "" {
|
||||
f.Groups = strings.Fields(m[4])
|
||||
}
|
||||
if f.Installed {
|
||||
f.InstalledAs = f.Version
|
||||
if m[5] != "" {
|
||||
f.InstalledAs = m[5]
|
||||
}
|
||||
}
|
||||
found = append(found, f)
|
||||
}
|
||||
return found
|
||||
}
|
||||
|
||||
// none is pacman's way of saying a query found nothing: status 1 and nothing said.
|
||||
func none(r Ran) bool {
|
||||
return r.Status == 1 && r.Err == "" && strings.TrimSpace(r.Stdout+r.Stderr) == ""
|
||||
}
|
||||
|
||||
// query runs a pacman query whose empty answer is status 1, and fails only on a real failure.
|
||||
func (m *Machine) query(args ...string) (string, error) {
|
||||
r := m.Run(bg(), "pacman", args...)
|
||||
if r.Status == 0 && r.Err == "" {
|
||||
return r.Stdout, nil
|
||||
}
|
||||
if none(r) {
|
||||
return "", nil
|
||||
}
|
||||
return "", failure("pacman", "pacman", r)
|
||||
}
|
||||
|
||||
// Search is `pacman -Ss` over the sync databases, bounded.
|
||||
func (m *Machine) Search(words string, limit int) (map[string]any, error) {
|
||||
out, err := m.query(append([]string{"-Ss", "--"}, strings.Fields(words)...)...)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
found := ParseSearch(out)
|
||||
return bound("packages", found, limit), nil
|
||||
}
|
||||
|
||||
// bound is a list answered with its count, cut to a limit and saying so.
|
||||
func bound[T any](key string, list []T, limit int) map[string]any {
|
||||
out := map[string]any{"count": len(list), "truncated": false}
|
||||
if limit > 0 && len(list) > limit {
|
||||
list = list[:limit]
|
||||
out["truncated"] = true
|
||||
}
|
||||
out[key] = list
|
||||
return out
|
||||
}
|
||||
|
||||
// ParseInfo reads `pacman -Qi`/`-Si`: `Key : value` lines, continuation lines indented beneath.
|
||||
// A field that is a list (two spaces between members) is answered as one, and "None" as empty.
|
||||
func ParseInfo(out string) []map[string]any {
|
||||
var pkgs []map[string]any
|
||||
var cur map[string]any
|
||||
last := ""
|
||||
for _, l := range strings.Split(out, "\n") {
|
||||
if strings.TrimSpace(l) == "" {
|
||||
if cur != nil {
|
||||
pkgs = append(pkgs, cur)
|
||||
cur = nil
|
||||
}
|
||||
continue
|
||||
}
|
||||
if cur == nil {
|
||||
cur = map[string]any{}
|
||||
}
|
||||
if k, v, ok := strings.Cut(l, " : "); ok && !strings.HasPrefix(l, " ") {
|
||||
last = strings.TrimSpace(k)
|
||||
cur[last] = infoValue(last, strings.TrimSpace(v))
|
||||
continue
|
||||
}
|
||||
// A continuation: the optional dependencies, one per line.
|
||||
if last != "" {
|
||||
v := strings.TrimSpace(l)
|
||||
switch prev := cur[last].(type) {
|
||||
case []string:
|
||||
cur[last] = append(prev, v)
|
||||
case string:
|
||||
cur[last] = []string{prev, v}
|
||||
}
|
||||
}
|
||||
}
|
||||
if cur != nil {
|
||||
pkgs = append(pkgs, cur)
|
||||
}
|
||||
return pkgs
|
||||
}
|
||||
|
||||
var listFields = map[string]bool{
|
||||
"Licenses": true, "Groups": true, "Provides": true, "Depends On": true, "Optional Deps": true,
|
||||
"Required By": true, "Optional For": true, "Conflicts With": true, "Replaces": true,
|
||||
}
|
||||
|
||||
func infoValue(key, v string) any {
|
||||
if !listFields[key] {
|
||||
return v
|
||||
}
|
||||
if v == "None" {
|
||||
return []string{}
|
||||
}
|
||||
if key == "Optional Deps" {
|
||||
return []string{v}
|
||||
}
|
||||
return strings.Fields(v)
|
||||
}
|
||||
|
||||
// Info is one package as the local database knows it, or the sync databases when it is not installed.
|
||||
func (m *Machine) Info(name string) (map[string]any, error) {
|
||||
r := m.Run(bg(), "pacman", "-Qi", "--", name)
|
||||
installed := true
|
||||
if r.Status != 0 {
|
||||
if r.Err != "" || !strings.Contains(r.Stderr, "was not found") {
|
||||
return nil, failure("pacman", "pacman", r)
|
||||
}
|
||||
installed = false
|
||||
if r = m.Run(bg(), "pacman", "-Si", "--", name); r.Status != 0 || r.Err != "" {
|
||||
if strings.Contains(r.Stderr, "was not found") {
|
||||
return nil, fmt.Errorf("no package %s, installed or in a repository", name)
|
||||
}
|
||||
return nil, failure("pacman", "pacman", r)
|
||||
}
|
||||
}
|
||||
pkgs := ParseInfo(r.Stdout)
|
||||
if len(pkgs) == 0 {
|
||||
return nil, fmt.Errorf("pacman said nothing about %s", name)
|
||||
}
|
||||
return map[string]any{"installed": installed, "package": pkgs[0]}, nil
|
||||
}
|
||||
|
||||
// Package is an installed package and why it is installed.
|
||||
type Package struct {
|
||||
Name string `json:"name"`
|
||||
Version string `json:"version"`
|
||||
Reason string `json:"reason"`
|
||||
Foreign bool `json:"foreign"`
|
||||
}
|
||||
|
||||
func nameVersions(out string) [][2]string {
|
||||
var nv [][2]string
|
||||
for _, l := range lines(out) {
|
||||
if f := strings.Fields(l); len(f) >= 2 {
|
||||
nv = append(nv, [2]string{f[0], f[1]})
|
||||
}
|
||||
}
|
||||
return nv
|
||||
}
|
||||
|
||||
func nameSet(out string) map[string]bool {
|
||||
s := map[string]bool{}
|
||||
for _, l := range lines(out) {
|
||||
s[strings.TrimSpace(l)] = true
|
||||
}
|
||||
return s
|
||||
}
|
||||
|
||||
// Installed is every installed package with its version, whether it was installed explicitly or as
|
||||
// a dependency, and whether it is foreign (in no repository this machine syncs).
|
||||
func (m *Machine) Installed(match, reason string, foreignOnly bool, limit int) (map[string]any, error) {
|
||||
all, err := m.query("-Q")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
explicit, err := m.query("-Qeq")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
foreign, err := m.query("-Qmq")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
ex, fo := nameSet(explicit), nameSet(foreign)
|
||||
pkgs := []Package{}
|
||||
counts := map[string]int{"explicit": 0, "dependency": 0, "foreign": 0}
|
||||
for _, nv := range nameVersions(all) {
|
||||
p := Package{Name: nv[0], Version: nv[1], Reason: "dependency", Foreign: fo[nv[0]]}
|
||||
if ex[p.Name] {
|
||||
p.Reason = "explicit"
|
||||
}
|
||||
counts[p.Reason]++
|
||||
if p.Foreign {
|
||||
counts["foreign"]++
|
||||
}
|
||||
if match != "" && !strings.Contains(p.Name, match) || reason != "" && p.Reason != reason || foreignOnly && !p.Foreign {
|
||||
continue
|
||||
}
|
||||
pkgs = append(pkgs, p)
|
||||
}
|
||||
out := bound("packages", pkgs, limit)
|
||||
out["totals"] = counts
|
||||
return out, nil
|
||||
}
|
||||
|
||||
var ownedBy = regexp.MustCompile(`^(.*) is owned by (\S+) (\S+)$`)
|
||||
|
||||
// Owns is which package owns a path.
|
||||
func (m *Machine) Owns(p string) (map[string]any, error) {
|
||||
if !path.IsAbs(p) {
|
||||
return nil, fmt.Errorf("%q is not an absolute path", p)
|
||||
}
|
||||
r := m.Run(bg(), "pacman", "-Qo", "--", p)
|
||||
if r.Status == 0 && r.Err == "" {
|
||||
for _, l := range lines(r.Stdout) {
|
||||
if o := ownedBy.FindStringSubmatch(l); o != nil {
|
||||
return map[string]any{"path": o[1], "owned": true, "package": o[2], "version": o[3]}, nil
|
||||
}
|
||||
}
|
||||
}
|
||||
if r.Err == "" && strings.Contains(r.Stderr, "No package owns") {
|
||||
return map[string]any{"path": p, "owned": false}, nil
|
||||
}
|
||||
return nil, failure("pacman", "pacman", r)
|
||||
}
|
||||
|
||||
// Files is what an installed package placed, bounded.
|
||||
func (m *Machine) Files(name string, limit int) (map[string]any, error) {
|
||||
r := m.Run(bg(), "pacman", "-Ql", "--", name)
|
||||
if r.Status != 0 || r.Err != "" {
|
||||
if strings.Contains(r.Stderr, "was not found") {
|
||||
return nil, fmt.Errorf("%s is not installed", name)
|
||||
}
|
||||
return nil, failure("pacman", "pacman", r)
|
||||
}
|
||||
paths := []string{}
|
||||
for _, l := range lines(r.Stdout) {
|
||||
if _, p, ok := strings.Cut(l, " "); ok {
|
||||
paths = append(paths, p)
|
||||
}
|
||||
}
|
||||
out := bound("paths", paths, limit)
|
||||
out["package"] = name
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// Orphans are packages installed as dependencies that nothing requires any more.
|
||||
func (m *Machine) Orphans() (map[string]any, error) {
|
||||
out, err := m.query("-Qdt")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
pkgs := []map[string]string{}
|
||||
for _, nv := range nameVersions(out) {
|
||||
pkgs = append(pkgs, map[string]string{"name": nv[0], "version": nv[1]})
|
||||
}
|
||||
return map[string]any{"count": len(pkgs), "orphans": pkgs}, nil
|
||||
}
|
||||
|
||||
// Foreign is every installed package no repository this machine syncs carries: built from the AUR
|
||||
// or by hand, which the host's `package` shape cannot install (research 027, question 1).
|
||||
func (m *Machine) Foreign() (map[string]any, error) {
|
||||
out, err := m.query("-Qm")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
pkgs := []map[string]string{}
|
||||
for _, nv := range nameVersions(out) {
|
||||
pkgs = append(pkgs, map[string]string{"name": nv[0], "version": nv[1]})
|
||||
}
|
||||
sort.Slice(pkgs, func(i, j int) bool { return pkgs[i]["name"] < pkgs[j]["name"] })
|
||||
return map[string]any{"count": len(pkgs), "packages": pkgs}, nil
|
||||
}
|
||||
|
||||
// Update is one package an upgrade would change.
|
||||
type Update struct {
|
||||
Name string `json:"name"`
|
||||
From string `json:"from"`
|
||||
To string `json:"to"`
|
||||
}
|
||||
|
||||
var updateLine = regexp.MustCompile(`^(\S+) (\S+) -> (\S+)`)
|
||||
|
||||
// Updates is what a full upgrade would change, from checkupdates: a copy of the sync databases
|
||||
// refreshed apart from the machine's own, so asking never makes a partial upgrade possible.
|
||||
func (m *Machine) Updates() (map[string]any, error) {
|
||||
r := m.Run(bg(), "checkupdates")
|
||||
switch {
|
||||
case r.Err == "ENOENT":
|
||||
return nil, fmt.Errorf("checkupdates is not installed: it comes with pacman-contrib, which this module declares")
|
||||
case r.Err == "" && r.Status == 2:
|
||||
return map[string]any{"count": 0, "updates": []Update{}}, nil
|
||||
case r.Err != "" || r.Status != 0:
|
||||
return nil, failure("checkupdates", "checkupdates", r)
|
||||
}
|
||||
ups := []Update{}
|
||||
for _, l := range lines(r.Stdout) {
|
||||
if u := updateLine.FindStringSubmatch(strings.TrimSpace(l)); u != nil {
|
||||
ups = append(ups, Update{u[1], u[2], u[3]})
|
||||
}
|
||||
}
|
||||
return map[string]any{"count": len(ups), "updates": ups}, nil
|
||||
}
|
||||
|
||||
// Config is the configuration pacman runs with, as pacman-conf resolves it.
|
||||
type Config struct {
|
||||
Options map[string][]string `json:"options"`
|
||||
Repositories []Repository `json:"repositories"`
|
||||
MeshOwned bool `json:"mesh_owned"`
|
||||
}
|
||||
|
||||
// Repository is one repository and where it is fetched from.
|
||||
type Repository struct {
|
||||
Name string `json:"name"`
|
||||
Servers int `json:"servers"`
|
||||
FirstServer string `json:"first_server,omitempty"`
|
||||
SigLevel string `json:"sig_level,omitempty"`
|
||||
}
|
||||
|
||||
// MeshHeader is how the module's pacman.conf begins, which is how it is recognised.
|
||||
const MeshHeader = "# The mesh's (module pacman"
|
||||
|
||||
// ParseConf reads `pacman-conf`: [options] and each repository, with their values.
|
||||
func ParseConf(out string) Config {
|
||||
c := Config{Options: map[string][]string{}, Repositories: []Repository{}}
|
||||
section := ""
|
||||
for _, l := range lines(out) {
|
||||
l = strings.TrimSpace(l)
|
||||
if strings.HasPrefix(l, "[") && strings.HasSuffix(l, "]") {
|
||||
section = strings.Trim(l, "[]")
|
||||
if section != "options" {
|
||||
c.Repositories = append(c.Repositories, Repository{Name: section})
|
||||
}
|
||||
continue
|
||||
}
|
||||
k, v, _ := strings.Cut(l, " = ")
|
||||
k, v = strings.TrimSpace(k), strings.TrimSpace(v)
|
||||
if section == "options" {
|
||||
c.Options[k] = append(c.Options[k], v)
|
||||
continue
|
||||
}
|
||||
if n := len(c.Repositories); n > 0 {
|
||||
r := &c.Repositories[n-1]
|
||||
switch k {
|
||||
case "Server":
|
||||
if r.Servers == 0 {
|
||||
r.FirstServer = v
|
||||
}
|
||||
r.Servers++
|
||||
case "SigLevel":
|
||||
r.SigLevel = strings.TrimSpace(r.SigLevel + " " + v)
|
||||
}
|
||||
}
|
||||
}
|
||||
return c
|
||||
}
|
||||
|
||||
// Conf is pacman's configuration in force, and whether /etc/pacman.conf is the module's.
|
||||
func (m *Machine) Conf() (Config, error) {
|
||||
out, err := m.Out("pacman-conf")
|
||||
if err != nil {
|
||||
return Config{}, err
|
||||
}
|
||||
c := ParseConf(out)
|
||||
if text, err := m.ReadFile("/etc/pacman.conf"); err == nil {
|
||||
c.MeshOwned = strings.HasPrefix(string(text), MeshHeader)
|
||||
}
|
||||
return c, nil
|
||||
}
|
||||
@@ -1,80 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"os"
|
||||
"testing"
|
||||
)
|
||||
|
||||
type resource map[string]any
|
||||
|
||||
type manifestShape struct {
|
||||
Module string `json:"module"`
|
||||
Version string `json:"version"`
|
||||
Capabilities []string `json:"capabilities"`
|
||||
Claims []map[string]any `json:"claims"`
|
||||
Tools []string `json:"tools"`
|
||||
Resources []resource `json:"resources"`
|
||||
Build struct {
|
||||
Artifacts []map[string]any `json:"artifacts"`
|
||||
} `json:"build"`
|
||||
}
|
||||
|
||||
func manifest(t *testing.T) manifestShape {
|
||||
t.Helper()
|
||||
raw, err := os.ReadFile("../../module.json")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var m manifestShape
|
||||
if err := json.Unmarshal(raw, &m); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return m
|
||||
}
|
||||
|
||||
func (m manifestShape) resource(t *testing.T, id string) resource {
|
||||
t.Helper()
|
||||
for _, r := range m.Resources {
|
||||
if r["id"] == id {
|
||||
return r
|
||||
}
|
||||
}
|
||||
t.Fatalf("no resource %s", id)
|
||||
return nil
|
||||
}
|
||||
|
||||
// TestToolsAreTheManifests holds the served tools and the manifest's list to one another, and the
|
||||
// bundle to the shape the builder compiles and the runtime loads.
|
||||
func TestToolsAreTheManifests(t *testing.T) {
|
||||
m := manifest(t)
|
||||
names := map[string]bool{}
|
||||
for _, tool := range tools(machine(nil, 1000)) {
|
||||
if names[tool.Name] {
|
||||
t.Errorf("%s is served twice", tool.Name)
|
||||
}
|
||||
names[tool.Name] = true
|
||||
}
|
||||
for _, want := range m.Tools {
|
||||
if !names[want] {
|
||||
t.Errorf("the manifest lists %s and the bundle does not serve it", want)
|
||||
}
|
||||
delete(names, want)
|
||||
}
|
||||
if len(names) != 0 {
|
||||
t.Errorf("served and not listed: %v", names)
|
||||
}
|
||||
var tools map[string]any
|
||||
for _, a := range m.Build.Artifacts {
|
||||
if a["name"] == "tools" {
|
||||
tools = a
|
||||
}
|
||||
}
|
||||
if tools == nil || tools["kind"] != "bundle" || tools["language"] != "go" || tools["system"] != "arch" ||
|
||||
tools["from"] != "cmd/"+binaryName || tools["binary"] != binaryName {
|
||||
t.Fatalf("the tools artifact: %v", tools)
|
||||
}
|
||||
if loads, _ := tools["loads"].([]any); len(loads) != 1 || loads[0] != binaryName {
|
||||
t.Fatalf("loads: %v", tools["loads"])
|
||||
}
|
||||
}
|
||||
@@ -1,5 +0,0 @@
|
||||
module pacman
|
||||
|
||||
go 1.22
|
||||
|
||||
require git.novox.be/novox/mesh-sdk/go v0.1.6
|
||||
@@ -1,2 +0,0 @@
|
||||
git.novox.be/novox/mesh-sdk/go v0.1.6 h1:9qzdYONYbJdWcu6sxQcq9v1LI0JxcfkiKYkMUzJSkVQ=
|
||||
git.novox.be/novox/mesh-sdk/go v0.1.6/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=
|
||||
@@ -1,91 +0,0 @@
|
||||
{
|
||||
"module": "pacman",
|
||||
"version": "1",
|
||||
"capabilities": [
|
||||
"package-manager",
|
||||
"service-manager"
|
||||
],
|
||||
"claims": [
|
||||
{
|
||||
"name": "node-package-manager",
|
||||
"scope": "node"
|
||||
}
|
||||
],
|
||||
"tools": [
|
||||
"pacman_search",
|
||||
"pacman_info",
|
||||
"pacman_installed",
|
||||
"pacman_owns",
|
||||
"pacman_files",
|
||||
"pacman_updates",
|
||||
"pacman_upgrade",
|
||||
"pacman_orphans",
|
||||
"pacman_remove_orphans",
|
||||
"pacman_cache",
|
||||
"pacman_history",
|
||||
"pacman_mirrors",
|
||||
"pacman_foreign",
|
||||
"pacman_news",
|
||||
"pacman_config"
|
||||
],
|
||||
"resources": [
|
||||
{
|
||||
"id": "package",
|
||||
"type": "package",
|
||||
"package": "pacman"
|
||||
},
|
||||
{
|
||||
"id": "config",
|
||||
"type": "file",
|
||||
"path": "/etc/pacman.conf",
|
||||
"mode": "0644",
|
||||
"content": "# The mesh's (module pacman, novox/hq to-be 42): the package manager's configuration. Written\n# whole at every push: an edit here is overwritten, and the file a machine had before is kept once by\n# the host. Owned whole because [options] cannot take a block by appending: anything added at the end\n# of the file lands in the last repository's section.\n#\n# The repositories are the union of what the machines had enabled when the module was written\n# (core, extra, multilib). The options are the distribution's defaults with four more: colour on a\n# terminal, parallel downloads, package lists in columns, and downloads run as the unprivileged\n# alpm user, which pacman 7 creates.\n\n[options]\nHoldPkg = pacman glibc\nArchitecture = auto\nCheckSpace\nColor\nVerbosePkgLists\nParallelDownloads = 5\nDownloadUser = alpm\nSigLevel = Required DatabaseOptional\nLocalFileSigLevel = Optional\n\n[core]\nInclude = /etc/pacman.d/mirrorlist\n\n[extra]\nInclude = /etc/pacman.d/mirrorlist\n\n[multilib]\nInclude = /etc/pacman.d/mirrorlist\n"
|
||||
},
|
||||
{
|
||||
"id": "contrib",
|
||||
"type": "package",
|
||||
"package": "pacman-contrib"
|
||||
},
|
||||
{
|
||||
"id": "reflector",
|
||||
"type": "package",
|
||||
"package": "reflector"
|
||||
},
|
||||
{
|
||||
"id": "mirrors",
|
||||
"type": "file",
|
||||
"path": "/etc/xdg/reflector/reflector.conf",
|
||||
"mode": "0644",
|
||||
"content": "# The mesh's (module pacman, novox/hq to-be 42): how reflector refreshes the mirror list, weekly,\n# through reflector.timer. Written whole at every push. Before the module, every machine's list was\n# generated once and never again.\n--save /etc/pacman.d/mirrorlist\n--protocol https\n--country Belgium,Netherlands,Luxembourg,Germany,France\n--latest 20\n--sort rate\n"
|
||||
},
|
||||
{
|
||||
"id": "mirror-refresh",
|
||||
"type": "service",
|
||||
"unit": "reflector.timer",
|
||||
"state": "running",
|
||||
"boot": "enabled"
|
||||
},
|
||||
{
|
||||
"id": "cache-cleaning",
|
||||
"type": "service",
|
||||
"unit": "paccache.timer",
|
||||
"state": "running",
|
||||
"boot": "enabled"
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "tools",
|
||||
"kind": "bundle",
|
||||
"language": "go",
|
||||
"system": "arch",
|
||||
"from": "cmd/pacman-tools",
|
||||
"binary": "pacman-tools",
|
||||
"loads": [
|
||||
"pacman-tools"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user